docs: amend ADR-0021 and close the loose ends ADR-0024 left behind

A six-agent review of today's commits found three documentation defects
that the apm-only change left behind. All three are records that describe
deleted machinery in the present tense; no code or gate is affected.

ADR-0021 was the one ADR that ADR-0024 invalidates without carrying an
amendment note -- 0001, 0006, 0011, 0013, 0014, 0015, 0017, 0018 and 0019
all got one. Its Context section still compiles a plugin description into
four generated files and its Consequences section still names eight, but
718c79a deleted the per-plugin manifest pairs and 0dffff3 deleted the
.github/plugin/marketplace.json mirror. One target survives. The decision
itself is untouched: the note marks the counts historical rather than
rewriting them, since the staleness hazard that motivated the ADR is
exactly what shrinking the blast radius does not fix.

That note also lands the one ADR-0021 has promised since it was written:
its Context section said "see the note below" about the codex profile's
removal and no such note has ever existed in the file.

SIMPLIFICATION-AUDIT.md's section 8 still asked whether Copilot reads the
legacy mirror path. Finding 2c answered that at 11:35 and 0dffff3 acted on
it; two later passes over section 8 (d2480b8, 061bb3d) each checked off a
different question and stepped over this one. Closed with the answer that
already shipped: Copilot's discovery falls through to .claude-plugin/,
so what the deletion cost is discovery-order preference, not consumability.

ADR-0020 cited plugins/bin/skills/zoom-out/SKILL.md:4 as end-to-end
verification evidence. That path is mirror, deleted by ADR-0024. The .apm/
source and the deployed copy both still carry the flag and the pass-through
still holds, so the citation is narrowed to the two live paths rather than
the finding being withdrawn.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
This commit is contained in:
2026-09-14 18:38:49 +00:00
parent c96ca9ca0d
commit a6434e0cdb
3 changed files with 18 additions and 6 deletions

View File

@@ -212,10 +212,11 @@ hand-invoked skill sets `disable-model-invocation: true` and carries one plain h
with no trigger list.
Verified end-to-end rather than assumed: `plugins/bin/.apm/skills/zoom-out/SKILL.md:4` carries the
flag, apm passes it through verbatim to both `.claude/skills/zoom-out/SKILL.md:4` and the flat mirror
at `plugins/bin/skills/zoom-out/SKILL.md:4`, and `zoom-out` was — at the time of that check, when it
was the only carrier — the one installed skill absent from the model-visible skill listing in a live
session. It remains invocable as `/zoom-out`. `caveman` has since taken the flag as well, so the
flag, apm passes it through verbatim to `.claude/skills/zoom-out/SKILL.md:4`, and `zoom-out` was — at
the time of that check, when it was the only carrier — the one installed skill absent from the
model-visible skill listing in a live session. It remains invocable as `/zoom-out`. (That check also
covered the flat mirror at `plugins/bin/skills/zoom-out/SKILL.md:4`, which ADR-0024 deleted on
2026-09-14; only the `.apm/` source and the deployed copy remain, and the pass-through is unaffected.) `caveman` has since taken the flag as well, so the
corpus now has **two** carriers. Do not read a carrier list off this page; re-derive it:
```

View File

@@ -8,6 +8,16 @@ plugin is *for*, and the inventory lives where an inventory can be read off the
**Status: accepted (2026-08-17).**
**Amended by ADR-0024 (2026-09-14).** The decision stands unchanged — a published description states
a boundary and never enumerates skills — but three of the four compile targets named below no longer
exist. `718c79a` deleted every per-plugin `.claude-plugin/plugin.json` and `.github/plugin/plugin.json`;
`0dffff3` deleted the repo-wide `.github/plugin/marketplace.json` mirror; and `.agents/plugins/marketplace.json`
with the codex profile producing it was removed 2026-09-13. A description is still authored twice —
`plugins/<name>/apm.yml` and root `apm.yml`'s `marketplace.packages[]` — but now compiles into one
file, `.claude-plugin/marketplace.json`. Read the "four generated files" in Context and the "eight
generated files" in Consequences as historical counts, true when written. The blast radius shrank;
the staleness hazard that motivated this ADR did not.
## Context
A plugin's published description is one string authored twice — in `plugins/<name>/apm.yml` and in
@@ -16,7 +26,7 @@ files per plugin edit: the plugin's `.claude-plugin/plugin.json` and `.github/pl
plus the repo-wide `.claude-plugin/marketplace.json` and its `.github/plugin/marketplace.json`
mirror. (`.agents/plugins/marketplace.json`, apm's codex profile, carried no per-package
`description` or `version` at all and was unaffected — that file and the profile producing it were
removed 2026-09-13; see the note below.) It is the only text a consumer sees in a marketplace listing before
removed 2026-09-13; see the amendment above.) It is the only text a consumer sees in a marketplace listing before
installing. It is **not** a SKILL.md `description`: it is never preloaded into an agent's context and
routes nothing at runtime. ADR-0020 governs that other artifact; this one governs this one. The
overlap is a finding, not a scope: ADR-0020 established that capability enumeration in a description