From f5fd67b152c9328789f9142966d7a4739a88e43c Mon Sep 17 00:00:00 2001 From: null Date: Mon, 17 Aug 2026 23:45:02 -0500 Subject: [PATCH] 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) --- docs/architecture/scripts/doc-claims.sh | 29 +++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/architecture/scripts/doc-claims.sh b/docs/architecture/scripts/doc-claims.sh index 3c8be57..9b60cc8 100755 --- a/docs/architecture/scripts/doc-claims.sh +++ b/docs/architecture/scripts/doc-claims.sh @@ -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"