doc-claims is red in every freshly scaffolded project, and the design says it should be #16

New Issue

Closed

opened 2026-08-17 23:34:42 -05:00 by null · 1 comment

null commented

2026-08-17 23:34:42 -05:00

Owner

Scaffolding into an empty directory and running doc-claims.sh there reports six findings, all bare script names:

docs/TOOLS.md: names scaffold.sh, which does not exist
docs/TOOLS.md: names release.sh, which does not exist
docs/architecture/README.md: names backup.sh, release.sh, check-env.sh
docs/security/SECURITY.md: names secrets.sh, which does not exist

None of them is a mistake. scaffold.sh deliberately does not copy the scripts — "an unconfigured release.sh landing in every new repository is a loaded gun, not a head start" — and TOOLS.md says so outright: "If this project has fewer scripts than that table lists, that is the intended state, not a broken copy... the table is a menu rather than an inventory here."

So the documents are right, the scaffold is right, and the guard is right, and the result is still that every project adopting this template has a red doc-claims on day one. That is the condition audit-gate.mjs argues about at length for npm advisories: a permanently red gate is one everybody has learned to ignore, and it takes the real findings down with it.

Three ways out, and this needs a decision rather than a quiet patch:

doc-claims.sh learns the difference. A bare filename with no slash is a weaker claim than a path — release.sh in prose is a reference to a script that may or may not have been adopted, while docs/qa/ClaudeReport.md is an assertion about this repository. Demote bare filenames to a warning, or drop them from the checked set entirely and keep the strictness for paths.
The documents stop naming scripts they cannot guarantee. Costly and worse to read: naming the script is the useful part.
Adopting projects are told to expect it, and the finding resolves as they copy each script. Cheapest, and it means the first thing a new project learns about its guards is that one of them is already red.

Recommendation is 1: the guard is the thing that can distinguish the two cases, and the distinction is real. Whichever is chosen, TOOLS.md's "menu rather than an inventory" paragraph should point at it, since that is where somebody will be standing when they hit this.

Verify: scaffold.sh into an empty directory, git init && git add -A, then doc-claims.sh docs/ exits 0 — or exits non-zero for a reason the template documents as expected, with TOOLS.md naming it.

Scaffolding into an empty directory and running `doc-claims.sh` there reports six findings, all bare script names: docs/TOOLS.md: names scaffold.sh, which does not exist docs/TOOLS.md: names release.sh, which does not exist docs/architecture/README.md: names backup.sh, release.sh, check-env.sh docs/security/SECURITY.md: names secrets.sh, which does not exist None of them is a mistake. `scaffold.sh` deliberately does not copy the scripts — *"an unconfigured release.sh landing in every new repository is a loaded gun, not a head start"* — and `TOOLS.md` says so outright: *"If this project has fewer scripts than that table lists, that is the intended state, not a broken copy... the table is a menu rather than an inventory here."* So the documents are right, the scaffold is right, and the guard is right, and the result is still that **every project adopting this template has a red `doc-claims` on day one**. That is the condition `audit-gate.mjs` argues about at length for npm advisories: a permanently red gate is one everybody has learned to ignore, and it takes the real findings down with it. Three ways out, and this needs a decision rather than a quiet patch: 1. **`doc-claims.sh` learns the difference.** A bare filename with no slash is a weaker claim than a path — `release.sh` in prose is a reference to a script that may or may not have been adopted, while `docs/qa/ClaudeReport.md` is an assertion about this repository. Demote bare filenames to a warning, or drop them from the checked set entirely and keep the strictness for paths. 2. **The documents stop naming scripts they cannot guarantee.** Costly and worse to read: naming the script is the useful part. 3. **Adopting projects are told to expect it**, and the finding resolves as they copy each script. Cheapest, and it means the first thing a new project learns about its guards is that one of them is already red. Recommendation is 1: the guard is the thing that can distinguish the two cases, and the distinction is real. Whichever is chosen, `TOOLS.md`'s "menu rather than an inventory" paragraph should point at it, since that is where somebody will be standing when they hit this. Verify: `scaffold.sh` into an empty directory, `git init && git add -A`, then `doc-claims.sh docs/` exits 0 — or exits non-zero for a reason the template documents as expected, with TOOLS.md naming it.

null added this to the Batch 02 — Findings from the first real runs milestone 2026-08-17 23:34:42 -05:00

null added the

label 2026-08-17 23:34:42 -05:00

null referenced this issue from a commit

2026-08-17 23:45:04 -05:00

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

null commented

2026-08-17 23:45:44 -05:00

Author

Owner

Partially addressed in f5fd67b, and measuring it properly changed the shape of the problem. The issue stays open.

The bare-filename half is done. Those six are now reported and counted separately and do not fail the run. I checked before loosening it that this does not undermine the guard: the finding it 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.

The remaining half is paths, and my original framing missed it. A freshly scaffolded project with a real commit exits 1 on four claims that are not bare names at all:

docs/DOC_TRUST_MAP.md: names docs/architecture/scripts
docs/DOC_TRUST_MAP.md: names docs/architecture/githooks
docs/TOOLS.md:         names docs/architecture/scripts
docs/WORK_CYCLE.md:    names docs/architecture/scripts/release.sh

Same root cause, different mechanism: three documents reference the tooling directories as paths, and scaffold.sh deliberately creates neither.

Why this was not visible until now. doc-claims builds its top-level set from git ls-tree --name-only HEAD. A scratch repo that has been git init-ed and git add-ed but never committed has no HEAD, so the set is empty, is_toplevel is false for everything, and no path is checked at all — while the run reports a confident pass. My first verification did exactly that and reported success; it had to be redone with a commit. Worth knowing independently of this issue: an uncommitted tree makes this guard report green over anything.

Options for the path half, updated:

scaffold.sh creates the directories empty, as DIRS already does for docs/data/img. Cheapest, precedented, and honest — an empty scripts/ says "this is where they go". Does not fix the release.sh reference, which names a file.
The documents stop naming tooling paths they cannot guarantee, which costs the most useful part of the sentence.
doc-claims learns that a path under a directory the scaffold declines to create is a menu entry too — the same demotion as bare names, keyed on the directory rather than the shape of the token.

Leaning 1 plus 3, not 2. Still a decision rather than a patch, which is why this is not closed.

Partially addressed in `f5fd67b`, and measuring it properly changed the shape of the problem. The issue stays open. **The bare-filename half is done.** Those six are now reported and counted separately and do not fail the run. I checked before loosening it that this does not undermine the guard: the finding it 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. **The remaining half is paths, and my original framing missed it.** A freshly scaffolded project **with a real commit** exits 1 on four claims that are not bare names at all: docs/DOC_TRUST_MAP.md: names docs/architecture/scripts docs/DOC_TRUST_MAP.md: names docs/architecture/githooks docs/TOOLS.md: names docs/architecture/scripts docs/WORK_CYCLE.md: names docs/architecture/scripts/release.sh Same root cause, different mechanism: three documents reference the tooling directories as paths, and `scaffold.sh` deliberately creates neither. **Why this was not visible until now.** `doc-claims` builds its top-level set from `git ls-tree --name-only HEAD`. A scratch repo that has been `git init`-ed and `git add`-ed but never committed has no `HEAD`, so the set is empty, `is_toplevel` is false for everything, and **no path is checked at all** — while the run reports a confident pass. My first verification did exactly that and reported success; it had to be redone with a commit. Worth knowing independently of this issue: an uncommitted tree makes this guard report green over anything. Options for the path half, updated: 1. **`scaffold.sh` creates the directories empty**, as `DIRS` already does for `docs/data/img`. Cheapest, precedented, and honest — an empty `scripts/` says "this is where they go". Does not fix the `release.sh` reference, which names a file. 2. **The documents stop naming tooling paths they cannot guarantee**, which costs the most useful part of the sentence. 3. **`doc-claims` learns that a path under a directory the scaffold declines to create is a menu entry too** — the same demotion as bare names, keyed on the directory rather than the shape of the token. Leaning 1 plus 3, not 2. Still a decision rather than a patch, which is why this is not closed.

null referenced this issue from a commit

2026-08-18 00:16:51 -05:00

fix(docs): three documents named the template's layout, not the project's

null closed this issue

2026-08-18 00:16:51 -05:00