From a6434e0cdb415ec69f878a288a34bdd8e14a85d8 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Mon, 14 Sep 2026 18:38:49 +0000 Subject: [PATCH] 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 Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD --- SIMPLIFICATION-AUDIT.md | 3 ++- ...20-skill-description-and-body-context-contract.md | 9 +++++---- ...21-plugin-descriptions-state-a-domain-boundary.md | 12 +++++++++++- 3 files changed, 18 insertions(+), 6 deletions(-) diff --git a/SIMPLIFICATION-AUDIT.md b/SIMPLIFICATION-AUDIT.md index 1893365..c266a53 100644 --- a/SIMPLIFICATION-AUDIT.md +++ b/SIMPLIFICATION-AUDIT.md @@ -222,7 +222,8 @@ Findings 9, 10, 11, and 12 are coupled through the provenance validator and the - [x] ~~**Native Claude Code marketplace install vs apm-only.** The flat mirror, `check-plugin-content-sync`, and ADR-0017 exist only for native `claude plugin install`. If apm install is the only supported path, the mirror and its 2,100 lines of tooling go away. Which install paths must work for consumers?~~ > **Answered (2026-09-14):** apm-only. See ADR-0024 (`docs/adr/0024-apm-is-the-only-supported-install-path.md`) and commit `718c79a` on `docs/simplification-audit`. Native `claude plugin install` support is dropped; the flat mirror, the twelve per-plugin manifests, `sync-plugin-content.sh`, its test suite, `lib/marketplace-plugins.sh`, and the `check-plugin-content-sync` and `validate-plugins` hooks are all deleted (245 files changed, −22,602 lines). ADR-0017 carries a superseded banner. Kept deliberately: the root `marketplace:` block and the root `.claude-plugin/marketplace.json`, which apm's own consumers read. (`marketplace.json` is the only tracked file under `.claude-plugin/`; the root `plugin.json` beside it is untracked local `apm pack` output, ignored at `.gitignore:59`.) This answer is what voided finding 7's recommendation and closed §3's `check-plugin-content-sync` target. -- **Copilot CLI legacy path.** Is `.github/plugin/marketplace.json` still read by any Copilot version you target? If not, finding 2c is a pure delete. +- [x] ~~**Copilot CLI legacy path.** Is `.github/plugin/marketplace.json` still read by any Copilot version you target? If not, finding 2c is a pure delete.~~ + > **Answered (2026-09-14):** yes, but only as a preferred path, not a required one — so the delete holds. Settled under finding 2c above and executed in commit `0dffff3`; this bullet was left open by oversight when that finding closed. Copilot CLI falls through `marketplace.json`, `.plugin/marketplace.json`, `.github/plugin/marketplace.json`, `.claude-plugin/marketplace.json` in order, and the `.claude-plugin/` file apm already emits satisfies the last step. What was lost is discovery-order preference, not Copilot consumability. - **Provenance chain.** Is "which upstream informed this file" a requirement you still want, or was it a governance experiment? Finding 11 hinges on this. - **ADR-0012 (three core skills) and the one-script-per-skill install constraint.** The merges in 14, 15, and 24 need the first revisited and are the only way around the second. Are you open to superseding ADR-0012? - **Granularity of git/gitea skills.** One `git` skill vs seven trades routing precision for size. Is one broad description acceptable? diff --git a/docs/adr/0020-skill-description-and-body-context-contract.md b/docs/adr/0020-skill-description-and-body-context-contract.md index 09b7da2..f103b2e 100644 --- a/docs/adr/0020-skill-description-and-body-context-contract.md +++ b/docs/adr/0020-skill-description-and-body-context-contract.md @@ -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: ``` diff --git a/docs/adr/0021-plugin-descriptions-state-a-domain-boundary.md b/docs/adr/0021-plugin-descriptions-state-a-domain-boundary.md index cf3f79c..b7e8786 100644 --- a/docs/adr/0021-plugin-descriptions-state-a-domain-boundary.md +++ b/docs/adr/0021-plugin-descriptions-state-a-domain-boundary.md @@ -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//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//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