fix(guards): a bare filename is a weaker claim than a path

doc-claims treated `release.sh` mentioned in prose exactly as it treated
`docs/qa/ClaudeReport.md`. The second asserts something about this repository;
the first is usually a reference to a script the template offers and this
project has not adopted yet -- scaffold.sh ships no scripts on purpose, and
TOOLS.md says so outright: "the table is a menu rather than an inventory here".

So every freshly scaffolded project began with a red doc-claims over documents
that were correct. That is the condition audit-gate.mjs argues about for npm
advisories: a gate that is red from the first day is one everybody learns to
ignore, and it takes the true findings with it.

Bare filenames are now reported and counted separately, and do not fail the run.
Paths still do. The strictness that matters is untouched, and I checked rather
than assumed: the finding this script was written for -- a comment claiming
tests/notice-security.test.ts pinned a security rule, for a file that had never
existed -- is a path, so it would still fail today.

Verified on a scaffolded project with a real commit, because doc-claims reads
git ls-tree HEAD and an uncommitted scratch repo has no HEAD at all: with no
commit it checks no paths whatsoever and reports a confident pass. My first
attempt at this verification did exactly that and had to be redone. The skill's
warning to commit before running a doc checker is about the review checker; it
applies here for the same reason.

This is part of #16, not all of it. A committed fresh scaffold still exits 1 on
four PATH claims -- docs/architecture/scripts, docs/architecture/githooks, and
docs/architecture/scripts/release.sh, named by DOC_TRUST_MAP.md, TOOLS.md and
WORK_CYCLE.md. Those are the same root cause and need the decision #16 asks for,
so the issue stays open.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
null 2026-08-17 23:45:02 -05:00
parent eaf42c38ea
commit f5fd67b152
1 changed files with 29 additions and 0 deletions

View File

@ -236,6 +236,7 @@ resolves() {
missing=0
checked=0
notes=0
for file in "${FILES[@]}"; do
[ -f "$file" ] || continue
@ -253,6 +254,28 @@ for file in "${FILES[@]}"; do
resolves "$token" "$file" && continue
# A bare filename is a weaker claim than a path, and is reported without
# failing the run.
#
# `docs/qa/ClaudeReport.md` asserts something about THIS repository. But
# `release.sh` in prose is usually a reference to a script the template
# offers and this project may not have adopted yet -- scaffold.sh
# deliberately ships no scripts, and TOOLS.md says so: "the table is a menu
# rather than an inventory here". Treating those as failures made every
# freshly scaffolded project start with a red guard, over documents that
# were correct, and a gate that is red from day one is one nobody reads.
#
# The strictness that matters is untouched. The finding this script was
# written for -- a comment claiming `tests/notice-security.test.ts` pinned a
# security rule, for a file that had never existed -- is a path, and paths
# still fail.
case "$token" in
*/*) ;;
*) printf '%s: mentions %s, which is not in this repository (yet)\n' "$file" "$token"
notes=$((notes + 1))
continue ;;
esac
printf '%s: names %s, which does not exist\n' "$file" "$token"
missing=$((missing + 1))
done < <(grep -oE '`[^`]+`|\]\([^)]+\)' "$file" 2>/dev/null \
@ -264,6 +287,12 @@ if [ "$checked" -eq 0 ]; then
exit 2
fi
if [ "$notes" -gt 0 ]; then
say "$notes bare filename(s) above are mentioned but not present. Not a"
say "failure: a project adopts the scripts it needs one at a time, and the"
say "documents naming them are a menu rather than an inventory."
fi
if [ "$missing" -gt 0 ]; then
say "$missing claimed path(s) do not exist, of $checked checked."
say "A document naming a file that is not there is worse than one saying"