Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

docs(gates): trim two stale post-mortem passages from gates.md

Browse Source 
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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
This commit is contained in:
Defame1297
2026-09-13 10:13:57 +00:00
parent cc2553d5f6
commit a35f5e889e
1 changed files with 10 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
docs/spec/gates.md
View File

@@ -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 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. 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 Verified: 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 `.claude/` or `.agents/` anywhere, produces findings identical to the working tree — confirming the
reproduction recorded — 26 description FAILs, 9 body FAILs, 2 dangling targets, 0 missing references two trees agree on the current corpus, independent of what happens to be installed locally.
— 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.
### Boundary-clause detection: three outcomes, not two ### 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 ## Current retrofit status
**The ADR-0020 gates ship hot, with no baseline file.** A shrinking baseline recording each The ADR-0020 gates ship hot, with no baseline file — a shrinking baseline was considered and
non-compliant skill's current numbers was considered and rejected in favour of hot gates. 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; Nothing is grandfathered — a new skill, or an edit that crosses a FAIL tier, is blocked on first
`kyberforge` was the last wave, after which the corpus was swept as a whole rather than per plugin. commit. SUGGESTION counts are not pinned here; they move with every edit. Measure and check both
Each sweep is followed by an **independent review round**: a fresh agent with no memory of the gates before starting work on a skill:
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:
``` ```
bash scripts/skill-size-check.sh plugins/*/.apm/skills/*/SKILL.md | grep -c '^SUGGESTION' 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) ## The `rtk` prefix gate (ADR-0023)
`check-rtk-prefix` is a `repo: local` pre-commit hook running `scripts/check-rtk-prefix.sh` over `check-rtk-prefix` is a `repo: local` pre-commit hook running `scripts/check-rtk-prefix.sh` over