fix(docs): correct claims the first fix round asserted without measuring
Why: two blind verifiers re-ran the five preceding commits and found four defects of the same class this branch exists to close -- a confidently stated measured claim that does not survive re-measurement -- this time inside the fixes themselves. - AGENTS.md:41 still carried both phrasingsc68e864reports having corrected. `grep -rn repo-defined` returned exactly one hit repo-wide: that line, in the file every session preloads.4d336bbedited the line directly above it. - ADR-0021 asserted twice, in the section justifying that no gate is added, that the ADR-0020 validators "never open an apm.yml". All three open and yaml.safe_load it (skill-size-check.sh:342, both validate.sh). The conclusion survives -- none reads the description: key, and their globs are SKILL.md and *.agent.md only -- but the stated mechanism is falsified by one grep. - architecture.md said the ADR directory holds 20 numbered ADRs;c7ba3d2made it 21, andc68e864audited that file for exactly this class of stale count. The number is dropped rather than corrected: `ls docs/adr/` is already the index, so a count in prose is a second thing to maintain. - gates.md's new three-verdict table said `-> name` promotes an unresolved target to ERROR. Reproduced with fixtures: NAME_HYPH (skill-size-check.sh:543) requires a hyphen, so `-> gitea-prs` is checked and `-> triage` is not extracted at all, and the unicode arrow is never recognised. The SUGGESTION text advises that spelling, so taking its advice can silence the finding. The gap is now documented as a defect; nothing covers it, since the one arrow case in test-adr0020-targets.sh happens to use a hyphenated target. Implementation notes: - AGENTS.md:48's coverage claim is shrunk rather than chased. Restoring six glossary entries did not make it true: 12 more sampled terms are undefined, three of them (trigger/capability/boundary clause) used inside CONTEXT.md itself. It now says CONTEXT.md is the glossary and is not exhaustive. - CONTEXT.md's output profile and near-miss entries are corrected against their sources. The first stated a false exclusion -- .github/plugin/plugin.json IS apm-generated; only the marketplace mirror has no profile. The second inverted its source's referent: description-quality.md defines a near-miss as a query, not a sibling skill. - The strict-mode message named jq, which no suite guards on (`command -v jq` appears nowhere in tests/), while omitting python3/PyYAML, which three do. - README's git and gitea bullets now name git-workflow and gitea-workflow. ADR-0021 leaves README the only inventory and architecture.md now points at it, so the two bullets that were short had to be completed. - ADR-0018's 2026-08-14 correction is marked superseded in place. It asserted machine state in the present tense that its own 2026-08-17 note retracts. - ADR-0021's remaining errors: six files -> four (measured fromde84d1b), the wiki description's length 114 -> 96 chars, the codex self-contradiction, the cost argument overstating bumps already owed for any skill addition, and two claims about files this branch went on to edit. - The "15 of 17 suites" figure is restored where I had removed it: it is a dated record of one incident, not a live count, and four sites now describe it the same way. Impact: 16/16 pre-push hooks pass, suite 24 passed 0 skipped 0 failed. No behaviour change; every edit is prose or a comment. Refs: #105 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w
This commit is contained in:
11
CONTEXT.md
11
CONTEXT.md
@@ -69,10 +69,10 @@ plugin's `.apm/` tree so hosts that convention-scan those paths discover the con
|
||||
_Avoid_: generated copy, duplicate tree
|
||||
|
||||
**Output profile**:
|
||||
An `apm pack` target format for a generated manifest; apm has `claude`
|
||||
An `apm pack` target format for a generated *marketplace* manifest; apm has `claude`
|
||||
(`.claude-plugin/marketplace.json`) and `codex` (the differently-shaped
|
||||
`.agents/plugins/marketplace.json`) and none for Copilot CLI's legacy path, which a sync script
|
||||
mirrors instead. Mechanics: `docs/spec/architecture.md`.
|
||||
`.agents/plugins/marketplace.json`), and none for `.github/plugin/marketplace.json` (Copilot CLI's
|
||||
legacy path), which a sync script mirrors instead. Mechanics: `docs/spec/architecture.md`.
|
||||
_Avoid_: build target, export format
|
||||
|
||||
**Plugin marketplace**:
|
||||
@@ -160,8 +160,9 @@ The directory a gate resolves against — the nearest ancestor of the file being
|
||||
_Avoid_: repo root, project root
|
||||
|
||||
**Near-miss**:
|
||||
A sibling skill or agent whose plausible queries share keywords with this one but need something
|
||||
different — the only thing a boundary clause should exclude.
|
||||
A query that shares keywords with this skill but needs a different one — and, by extension, the
|
||||
sibling that would wrongly answer it; boundary clauses exist to exclude genuine near-misses rather
|
||||
than to enumerate siblings. Detail: `skill-audit/references/description-quality.md`.
|
||||
_Avoid_: overlap, similar skill
|
||||
|
||||
**Vacuous green**:
|
||||
|
||||
Reference in New Issue
Block a user