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:
parent
eaf42c38ea
commit
f5fd67b152
|
|
@ -236,6 +236,7 @@ resolves() {
|
||||||
|
|
||||||
missing=0
|
missing=0
|
||||||
checked=0
|
checked=0
|
||||||
|
notes=0
|
||||||
|
|
||||||
for file in "${FILES[@]}"; do
|
for file in "${FILES[@]}"; do
|
||||||
[ -f "$file" ] || continue
|
[ -f "$file" ] || continue
|
||||||
|
|
@ -253,6 +254,28 @@ for file in "${FILES[@]}"; do
|
||||||
|
|
||||||
resolves "$token" "$file" && continue
|
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"
|
printf '%s: names %s, which does not exist\n' "$file" "$token"
|
||||||
missing=$((missing + 1))
|
missing=$((missing + 1))
|
||||||
done < <(grep -oE '`[^`]+`|\]\([^)]+\)' "$file" 2>/dev/null \
|
done < <(grep -oE '`[^`]+`|\]\([^)]+\)' "$file" 2>/dev/null \
|
||||||
|
|
@ -264,6 +287,12 @@ if [ "$checked" -eq 0 ]; then
|
||||||
exit 2
|
exit 2
|
||||||
fi
|
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
|
if [ "$missing" -gt 0 ]; then
|
||||||
say "$missing claimed path(s) do not exist, of $checked checked."
|
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"
|
say "A document naming a file that is not there is worse than one saying"
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue