From a35f5e889e3f73a8878d839dc9efb1f3f5ceaa4d Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Sun, 13 Sep 2026 10:13:57 +0000 Subject: [PATCH] docs(gates): trim two stale post-mortem passages from gates.md Cut the "Verified fixed" reproduction paragraph carrying explicitly stale pre-retrofit figures, and condensed the "Current retrofit status" section's issue-#99 process narrative to the current-state facts and the commands to check them. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD --- docs/spec/gates.md | 56 +++++++++------------------------------------- 1 file changed, 10 insertions(+), 46 deletions(-) diff --git a/docs/spec/gates.md b/docs/spec/gates.md index 74da6b8..439324e 100644 --- a/docs/spec/gates.md +++ b/docs/spec/gates.md @@ -245,12 +245,9 @@ run it. Four cross-plugin targets here (`gitea-branches` → `git-branches`, `gi through `.claude/skills/` alone, so **the same commit measured 2 dangling targets on a developer machine and 6 on a fresh clone**. A gate shipping hot with no baseline cannot give two answers. -Verified fixed: running the hook over a tree holding only `plugins/` and the root `apm.yml`, with no -`.claude/` or `.agents/` anywhere, produced findings identical to the working tree. The figures that -reproduction recorded — 26 description FAILs, 9 body FAILs, 2 dangling targets, 0 missing references -— are the pre-retrofit corpus as it stood when the experiment was run, kept here as the evidence for -the install-independence claim. They are not current: the retrofit under #99 took the first three to -zero. What the experiment establishes is that the two trees agree, not what either measured. +Verified: running the hook over a tree holding only `plugins/` and the root `apm.yml`, with no +`.claude/` or `.agents/` anywhere, produces findings identical to the working tree — confirming the +two trees agree on the current corpus, independent of what happens to be installed locally. ### Boundary-clause detection: three outcomes, not two @@ -433,52 +430,19 @@ knows the difference; doing so silently enforces a gate ADR-0020 declines to set ## Current retrofit status -**The ADR-0020 gates ship hot, with no baseline file.** A shrinking baseline recording each -non-compliant skill's current numbers was considered and rejected in favour of hot gates. +The ADR-0020 gates ship hot, with no baseline file — a shrinking baseline was considered and +rejected. The corpus is currently clean on both: 0 of 39 descriptions/bodies exceed their FAIL tier, +0 dangling targets, 0 `Kyberforge.CompositionNote` (Vale) errors. History: issue #99. -**The corpus is now clean on both gates.** Issue **#99** retrofitted all 39 skills plugin by plugin; -`kyberforge` was the last wave, after which the corpus was swept as a whole rather than per plugin. -Each sweep is followed by an **independent review round**: a fresh agent with no memory of the -retrofit re-measures the corpus and files what it finds, and the round repeats until one lands no -findings. The rounds are recorded as comments on **#99** — read the current state off that thread, -which is why no round count is pinned here. - -| Gate | Current findings | -|---|---| -| `skill-size-check` | **0 of 39** descriptions and **0 of 39** bodies exceed their FAIL tier; 0 dangling targets; SUGGESTIONs outstanding (count not pinned — see below) | -| `Kyberforge.CompositionNote` (Vale) | **0 errors** — the four `gitea-*` carriers were all retrofitted | - -**The SUGGESTION count is deliberately not recorded here.** It moves with every skill edit *and* -with every change to the gate's own tiering, so any figure written down is stale by the next commit. -Measure it instead: +Nothing is grandfathered — a new skill, or an edit that crosses a FAIL tier, is blocked on first +commit. SUGGESTION counts are not pinned here; they move with every edit. Measure and check both +gates before starting work on a skill: ``` bash scripts/skill-size-check.sh plugins/*/.apm/skills/*/SKILL.md | grep -c '^SUGGESTION' -pre-commit run skill-size-check --all-files # same findings, via the hook +pre-commit run --all-files # size AND Vale — skill-size-check alone can pass while Vale still blocks ``` -A non-zero count is the expected steady state, not a regression. SUGGESTIONs exit 0 and block -nothing; only the two FAIL tiers, the dangling-target ERROR and the missing-`references/` ERROR do. -Read the count as a work queue, and the FAIL columns above as the gate. - -`Kyberforge.CompositionNote` is the ADR-0020 Vale rule banning composition and architecture prose -from a description. Every Vale rule here is `level: error` with no ignorable tier, so a description -that reintroduces one blocks the commit even though no skill carries one today. - -Because nothing is grandfathered, the gates now bite on **first commit**: a new skill, or an edit -that pushes a description past 400 characters or a body past 900 words, is blocked until it -complies. That is the steady state the retrofit was for — it is no longer true that an unrelated -one-line fix to a skill requires retrofitting that skill first. - -Check where a skill stands before starting, and check **both** gates: - -``` -pre-commit run skill-size-check --all-files # size/context only -pre-commit run --all-files # size AND Vale -``` - -Scoping a retrofit off `skill-size-check` output alone leaves you blocked at the second gate. - ## The `rtk` prefix gate (ADR-0023) `check-rtk-prefix` is a `repo: local` pre-commit hook running `scripts/check-rtk-prefix.sh` over