docs(adr): correct the records the branch left describing deleted things

Seven ADRs described code that no longer exists or behaviour the gates do
not have. Where the wrong text came from main it carries a dated
correction; where this branch introduced it, it is fixed in place, because
main never published it and there is no record to preserve.

Fixed in place, branch-introduced:

- ADR-0021's 2026-09-14 correction asserted apm audit --ci "was never a
  drift gate at all". It is one: it replays the install and diffs. The
  claim contradicted this branch's own AGENTS.md and gates.md.
- ADR-0015 said unconditionally that no pre-push hook needs the network.
  The guarantee holds only once apm install has populated apm_modules/.
- ADR-0014's 2026-09-16 correction said restoring .pre-commit-hooks.yaml
  would ship a hook that fails for every consumer, because their checkout
  has no lib-boundary-resolver.sh. pre-commit clones the whole hook repo
  and skill-size-check.sh resolves the library from BASH_SOURCE, so the
  hook would work.
- ADR-0019's "twelve hooks pass under unshare -rn" matched neither HEAD
  (8) nor main (14), and stated the offline guarantee unconditionally.

Corrected, inherited from main:

- ADR-0022 and ADR-0013 named skill-frontmatter's pre-commit hook as the
  enforcer of mandatory metadata.version. That hook was deleted on this
  branch; the check lives in skill-size-check.sh.
- ADR-0022 enumerated the tip rule's carve-outs as a closed list and
  described a single merge-base. The gate also exempts a tree-identical
  skill and intersects every base from merge-base --all, and emits a third
  failure form. 8cfd54f said the documented behaviour did not change; it
  did. The gate is correct and is unchanged -- the record was not.
- ADR-0020's Decision still routed description overflow to README.md, its
  ADR-0025 amendment pointed the mirrored constants at validate.sh, which
  holds none, and its Enforcement table still named the two deleted
  validate.sh paths.
- ADR-0015's Status claimed every plugin's plugin.json is pack output;
  none exist.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NwD8Egs5r4ndqeFLmhusX2
This commit is contained in:
2026-09-20 18:38:00 +00:00
parent e849a823f7
commit 44bde9e9c9
7 changed files with 105 additions and 19 deletions

View File

@@ -54,6 +54,13 @@ per-plugin choice.
`name:` or `description:`; a missing `metadata.version` is now the same class of failure, not a
style nit an audit might or might not catch.
> **Correction (2026-09-20): that hook no longer exists.** `skill-frontmatter` was removed and its
> required-field checks folded into `skill-size-check`. The enforcer is now
> `scripts/skill-size-check.sh:324-335`, declared under the `skill-size-check` hook at
> `.pre-commit-config.yaml:237`. It checks presence and three-part-semver shape, on the same
> `SKILL.md` glob and at the same pre-commit stage, so the decision is unaffected — only the name
> of the hook that holds it. The same substitution applies to the Consequences section below.
## Considered options
**Leave it per-plugin, document the split.** This was the initial framing of #127 and is coherent —
@@ -152,6 +159,38 @@ on the same skill. That is the case the rule exists for, and rebasing onto or me
shows the version to beat. The rule reads `origin/main` as last fetched, so a tip that moved since
the last fetch is not seen until the next one.
## Amendment (2026-09-20): two exemptions and a third failure form the rules above never stated
The carve-outs enumerated above read as a closed list, and the baseline above reads as a single
merge-base. `scripts/check-skill-version-bump.sh` as shipped has two further exemptions and emits a
third failure form. **The gate is right and is not changing; this ADR was behind it.** Its own header
comments (`:9-93`) have described all three correctly since it shipped.
- **The baseline is `git merge-base --all`, not one merge-base.** A criss-cross history — `main`
merges a branch while that branch merges a commit of `main` — has two merge bases, and which one
`git merge-base` prints is an implementation detail. The script takes every base (`:154-157`) and
**intersects** the changed-skill sets across them (`:203-217`): a skill matching any one base is
already shipped by that base and is exempt, and a skill that does reach the comparison must exceed
the version at every base it exists at (`:367-376`). Picking one base made the verdict a coin
flip — an already-merged bump failed the push it should have passed.
- **A skill whose directory tree object equals the tip's skips the tip comparison.**
`same_subtree()` (`:288-297`, applied at `:334-337`) compares tree object ids rather than diffing:
the same tree is the same content, whatever route the history took to it. A branch cut before a
fix landed on `main` and then cherry-picking that fix has one merge-base, predating the fix, so the
skill counts as changed against it and reaches the tip comparison carrying exactly the tip's
version — same content, same version. The merge-base intersection catches that only when some base
carries the content, which the criss-cross shape gives and a linear one does not. Without the skip
the only escapes are a spurious bump, leaving `main` carrying two versions of identical content,
or a rebase the push does not otherwise need.
- **A third failure form.** The amendment above lists `(not above merge-base)` and
`(not above origin/main tip)`. When there is more than one base, the merge-base line is
sha-suffixed — `(not above merge-base <sha>)` (`:372`, against the unsuffixed `:374`) — because
"which merge-base" is the one question a reader cannot answer from the branch alone.
`8cfd54f` recorded that "ADR-0022 is not amended: the documented behaviour does not change". That
was wrong for the tree-identical case: the `same_subtree` skip makes a push **pass** that this ADR as
written requires to **fail**, which is documented behaviour changing, not an implementation detail.
## Consequences
27 SKILL.md files gain `metadata.version: "1.0.0"`, and a 28th — `bin/write-docs` — reaches the same