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:
@@ -14,11 +14,12 @@
|
||||
# into a red run would just train people to ignore red.
|
||||
# * as a GATE (the run-tests pre-push hook): a skip is a SETUP ERROR, not a
|
||||
# legitimate state. README.md's Prerequisites table documents vale, apm and
|
||||
# jq as required pre-push dependencies, so a suite that cannot run on the
|
||||
# machine doing the pushing means the machine is misconfigured -- and
|
||||
# python3/PyYAML -- the dependencies these suites actually guard on -- as
|
||||
# required pre-push, so a suite that cannot run on the machine doing the
|
||||
# pushing means the machine is misconfigured -- and
|
||||
# pre-commit prints NOTHING for a passing hook, so the skip list below is
|
||||
# swallowed entirely. On a vale-less PATH that silently shipped a green
|
||||
# gate having verified 15 of 17 suites.
|
||||
# swallowed entirely. On a vale-less PATH that once silently shipped a
|
||||
# green gate having verified 15 of the 17 suites that existed then.
|
||||
# Exactly the vacuous-pass class the rest of this file exists to close.
|
||||
#
|
||||
# Deliberately its own switch, NOT folded into
|
||||
@@ -259,7 +260,7 @@ fi
|
||||
# here (not just referenced) because this block goes to stderr and is what a
|
||||
# pre-push reader actually gets handed.
|
||||
if [[ "$STRICT" == true && ${#SKIPPED[@]} -gt 0 ]]; then
|
||||
echo "Error: --strict and ${#SKIPPED[@]} suite(s) skipped. Run as a gate, a skip is a SETUP ERROR on this machine, not a legitimate state: README.md's Prerequisites table documents vale, apm and jq as required pre-push dependencies, so every suite is expected to be runnable here. Install what each suite names below and re-run; do not skip the hook." >&2
|
||||
echo "Error: --strict and ${#SKIPPED[@]} suite(s) skipped. Run as a gate, a skip is a SETUP ERROR on this machine, not a legitimate state: README.md's Prerequisites table documents vale, apm and python3/PyYAML — what these suites guard on — as required pre-push dependencies, so every suite is expected to be runnable here. Install what each suite names below and re-run; do not skip the hook." >&2
|
||||
sidx=0
|
||||
for s in ${SKIPPED[@]+"${SKIPPED[@]}"}; do
|
||||
echo " $s" >&2
|
||||
|
||||
Reference in New Issue
Block a user