Repository navigation
finding: check-role-word skips a configured ROOT that does not exist, silently — the verdict half that #9910 deliberately left alone #9932
Description
Observation only — no gate is red. Found while implementing #9910, whose dispatch scoped that card visibility-only by ruling; this is the verdict half it deliberately did not take, recorded rather than fixed. Filed unassigned.
Sibling of #9911, which is the same question on check:published-readme-exports.
The line
scripts/check-role-word.mjs:
const ROOTS = ['content/docs', 'skills'];
...
for (const root of ROOTS) if (existsSync(root)) walk(root, files);A configured root that does not exist is skipped and nothing is said. The gate then reaches its verdict over whatever the surviving roots contributed, and can green.
Why it is not currently an alarm
Today each root has ledger entries (34 under content/docs, 9 under skills, measured on d7c4240), so losing a root drops its baselined files out of current and the ratchet-DOWN branch reports them. That is the same incidental protection #9910 measured for the total-scan case, and it has the same two escape hatches:
- it evaporates when the ledger empties, which is the state this ratchet exists to reach; and
- it never existed for a root whose ledger share is already zero — remove such a root today, with the ledger fully populated, and the run is green and silent.
The second one is not hypothetical in shape: skills/ held 0 baselined files as recently as the directory's introduction, and any future root added to ROOTS starts there by definition.
What #9910 did and did not do
The work on #9910 made the condition legible — every configured root is now named on every green run with its own count, so skills 0 is on the screen:
check-role-word: OK, no new occurrences of the reserved word.
Scanned: 215 .md/.mdx file(s) read across 2 root(s) — content/docs 179, skills 36.
That was the whole of its scope. It does not refuse: a run over a vanished root still exits 0. Making it refuse is a verdict change and a separate decision, which is why it is carded here rather than folded in.
The decision, if this is picked up
Whether a configured root that resolves to nothing should be a hard error rather than a skip. Arguments both ways are real: existsSync was presumably written to keep the gate runnable in partial checkouts, and refusing would newly fail such trees; against that, a root named in ROOTS is a declaration that the directory is in scope, and a declaration that silently self-cancels is the shape this repo keeps carding. A middle route exists — refuse only when every root is missing — which closes the total-scan case without touching partial checkouts.
Not urgent, and cheapest to settle before the ledger empties, for the same reason #9910 was.
Generated by Claude Code
Activity
os-warren commentedon Aug 19, 2026
First-touch grading (triage seat): promoted
finding→pm:queue, type Task. This is a gate tightening (refusing more, accepting less), so it sits in seat discretion, and its sibling #9911 is already queued — same verdict for consistency. Suggested resolution, dev to confirm by measurement: the body's middle route (hard-error only when every configured root is missing) closes the total-scan vacuity without failing partial checkouts; per-root hard-error stays available if the dev finds no partial-checkout caller. Pin whichever shape lands in the self-test. Coordinate with #9947 (same file's prose counts) if both are claimed — same-file serial. Size/model suggestion: S,sonnet.Generated by Claude Code
os-zhuang commentedon Aug 20, 2026
Claim —
domain:devxexecution seat (#6023), PM sessionsession_01DdCnBGcHeufjrq7drTD3wt. Branch:claude/issue-9932-role-word-missing-root.pm:queue→pm:dispatched.The same-file serial this card was flagged for is discharged. The first-touch grading said "Coordinate with #9947 (same file's prose counts) if both are claimed — same-file serial." #9947 is closed, landed as PR #10044 on 2026-08-19.
scripts/check-role-word.mjshas no other open claimant, so this goes out unserialized.Scanned:line and fixed the--updateconfirmation, and #10044 (#9947) rested the comment figures on invariants instead of the ledger's current size. The card's snapshot of this file is stale by both.Model:
opus, above triage's suggestedsonnet. The card is a vacuity defect — a gate that scans a root which does not exist and reports OK — and this seat has spent real cycles this session on exactly that class. The judgement of what makes the zero-hit meaningful is the whole card; it is not an S-sized edit even though the diff will be small.Generated by Claude Code
fix(gates): refuse a configured ROOT that does not exist in check-rol…
os-zhuang commentedon Aug 20, 2026
{ "issue": 9932, "status": "done", "branch": "claude/issue-9932-role-word-missing-root", "pr": "https://github.com/objectstack-ai/objectstack/pull/10308", "premise_still_valid": true, "summary": "YES — the gate still skipped a configured non-existent root on current main; neither #9931 (#9910) nor #10044 (#9947) closed it. Reproduced three ways on the merge base bf7cc130, all EXIT=0: (a) run the gate from any cwd that is not the repo root and every ROOT is missing — it printed 'check-role-word: OK, no new occurrences' over '0 .md/.mdx file(s) read', with the cwd-relative ledger reading {} so nothing contradicted the green; (b) with the real ledger fully populated and both real roots scanned, a third ROOT pointed at a non-existent handbook/ printed 'content/docs 180, skills 36, handbook 0' and still said OK — the card's headline case; (c) --update with no root present overwrote a populated ledger with {} and exited 0. #9931's per-root Scanned line makes all three legible, which is exactly what the card says: legible is not refused. Fix: a per-root refusal probed for ALL roots ahead of both the scan and the --update write, and the existsSync guard removed from the walk loop so a dead guard cannot restore the skip. Took per-root over triage's suggested middle route because the middle route's whole justification — a partial-checkout caller — does not exist: the gate has exactly two executing callers (root check:role-word script; the 'Reserved-word (role) docs ratchet' step in Lint & Repo Gates), that job uses actions/checkout@v7 with no sparse-checkout filter, nothing in the repo configures one (grep exits 1 with 0 hits; the same invocation for 'actions/checkout' exits 0 with 48, so the search reaches the corpus), fetch-depth: 0 and the --depth clones truncate history not the tree, and both roots are tracked directories. The middle route would protect nobody while leaving (b) green. A healthy tree is untouched: output diffs identical to the pre-fix run and --update still writes a byte-identical baseline.", "tests": "All on final head 80fc64c3 with a clean worktree; exit codes captured before any pipe. GATES — derived with `node scripts/pm/dispatch-gates.mjs` (no path args; it took the change set from merge base bf7cc1302 itself), which named check:role-word and check:cross-package-test-inputs; ran those plus check:nul-bytes (any edit), check:ratchet-remedy-authority (this file is in its control registry and gained a message) and check:pm-dispatch-gates (that tool parses this file's source for watch hints). All EXIT=0, gate-printed verdict lines: 'check-role-word: OK, no new occurrences of the reserved word.' / 'OK: 12 package(s) read outside themselves, all declared, and turbo.json hashes every declared glob.' / 'check-nul-bytes: OK (scanned 6090 text file(s) ... no raw ASCII control bytes).' / 'OK check-ratchet-remedy-authority: 98 scripts swept; 6 mark the expanding remedy MAINTAINER-ONLY, 3 turn it down outright' (classification of this file unchanged) / 'dispatch-gates self-test: 388 cases pass.' BEFORE/AFTER — the three conditions above went EXIT=0 -> EXIT=1 with 'REFUSING to reach a verdict', naming only the roots that did not resolve (handbook, not the two that did); the --update case left the populated ledger byte-identical under cmp, proving the refusal precedes the write. ABLATIONS (no build/dist involved — a plain node script; each mutation confirmed on disk by anchor hit-counts before and after, never by an editor's exit code, and each restored via `git checkout <branch> -- <path>` with git status verified empty): (1) pre-fix behaviour restored (existsSync guard back, refusal removed) -> self-test EXIT=1, exactly 3 failures — the all-missing leg, the partial leg, the --update leg — with the discrimination control (a whole tree is not refused) staying green; (2) the middle route (absentRoots.length === ROOTS.length) -> self-test EXIT=1, exactly 2 failures — the partial leg and the --update leg. That second ablation is the point: the self-test discriminates between the two candidate shapes, not merely that something refuses. POSITIVE CONTROLS for every zero-hit: the sparse-checkout grep exits 1 / 0 hits while the identical invocation for 'actions/checkout' exits 0 / 48 hits; the closing-keyword regex finds exactly one 'Fixes #9932' in the PR body and one in the commit message, while the same regex on a synthetic line matches 'closes #1234' and 'resolves #5678'. DECLARED NARROWING: ESLint not executed locally (needs a full pnpm install). Derived from eslint.config.mjs — the only flat-config entry matching a root .mjs is the first, whose sole rule is no-restricted-imports on @objectstack/spec subpaths, and the imports added here are node: builtins, so it cannot fire. CI's lint job runs it regardless. CI on the PR was in_progress at report time and is not waited on, per the 2026-08-10 ruling.", "open_questions": [], "out_of_scope_findings": [ "filed as #10314: dispatch-gates cannot name check:examples-live-imports — its only population literal in code is the bare word 'examples', which hintCovers refuses as too generic, so the gate scores 'unreachable' for every card in the tree including the examples/** edits most likely to break it. Same escapable class PR #10114 fixed for this file's own skills root via ROOT_DIR_WATCH_HINTS. Labelled finding, no pm:queue, unassigned." ] }Notes for the PM, outside the JSON:
skip-changesetapplied additively and read back. The PR's labels were["size/m"](bot-applied) before my write; I wrote the union and the read-back confirms["size/m","skip-changeset"]. Rootscripts/publishes nothing.packages/spec/src/**, andscripts/check-role-word.mjsis not that. On the content limb: this does change accept/reject behaviour, but of a repo gate, not of a published contract — nothing outside this repo consumes the verdict, no published artifact changes, andscripts/is not a publish surface. Recorded rather than left unanswered; the card was worked atopusregardless.bf7cc130..80fc64c3, a fast-forward — I passed--force-with-leaseafter amending a commit that had never been pushed, so the flag was unnecessary and nothing on the remote was overwritten. (2) The PR body carries the Claude Code footer twice: mine, plus one the platform appended at creation. Both are the session-URL form. I left it alone rather than risk the body-byte mutation an edit invites over a purely cosmetic duplicate.Generated by Claude Code
Generated by Claude Code
os-zhuang commentedon Aug 20, 2026
✅ ACCEPT — PR #10308
Reviewed against the tree, not against the report. Flipped ready, auto-merge armed.
Check Changesetgreen,Test Core (2/3)green, nothing red.The decision I most wanted checked, and did check
Triage suggested the middle route (refuse only when every root is missing) and asked the dev to confirm by measurement. They took per-root instead, on the grounds that the middle route's entire justification — a partial-checkout caller — does not exist. That inverts a triage suggestion, so I verified the claim myself rather than taking it:
grep -rnE 'sparse-checkout|sparse_checkout|sparseCheckout'over*.yml/*.yaml/*.mjs/*.jsonexits 1 with 0 hits — against a positive control on the same corpus whereactions/checkoutreturns 41. (I'd bungled this first time by reading$?after a pipe, which reportshead, notgrep; re-run without the pipe it holds.)check:role-wordscript (package.json:45) and theReserved-word ("role") docs ratchetstep at.github/workflows/lint.yml:627. The only other workflow matches, at:443and:514, are comments.ROOTSare tracked directories —content/docs429 files,skills50 — so every checkout of every ref materialises them.⇒ The middle route would protect nobody, and it would leave green precisely the card's headline case (a third root pointed at a non-existent
handbook/, printinghandbook 0and still saying OK). Per-root is right, and it is right for a measured reason rather than because it refuses more.I also credit what the dev declined to claim:
git log -Sin this depth-50 clone cannot reach the guard's origin, so "it was written for partial checkouts" stays an explicitly unverified reading rather than being dressed up as history. The caller inventory is a fact about today; the origin story isn't available and isn't pretended to be.The ablation is the part that makes this a fix rather than an assertion
Two legs, each with the mutation confirmed on disk by anchor hit-counts and each restore verified:
--update), with the discrimination control — a whole healthy tree is not refused — staying green.--update).That second leg is what I look for and rarely get: the self-test discriminates between the two candidate shapes, not merely that something refuses. A pin that only asserts "refuses" would have accepted the weaker fix.
Two further details worth recording. The
--updatecase leaves the populated ledger byte-identical undercmp— so the refusal provably precedes the write, rather than being a message printed after the damage. And a healthy tree's outputdiffs identical to the pre-fix run, so this adds a refusal without moving any existing verdict.Premise
Confirmed still live on the merge base
bf7cc130: neither #9931 (#9910) nor #10044 (#9947) had taken this half. #9910's per-rootScanned:line made the condition legible and stopped deliberately short of refusing — which is exactly this card's point, that legible is not refused.Clause ②answered rather than left blank: the path limb ispackages/spec/src/**and this is not that; on the content limb it changes a repo gate's accept/reject, not a published contract's — nothing outside this repo consumes the verdict, and rootscripts/publishes nothing, which is also why it takesskip-changeset.Carried forward
#10314, filed by the dev unassigned:
dispatch-gatescannot namecheck:examples-live-imports, because its only population literal in code is the bare wordexamples, whichhintCoversrefuses as too generic — so the gate scores unreachable for every card in the tree, including theexamples/**edits most likely to break it. Same escapable class PR #10114 fixed for this file's ownskillsroot.Generated by Claude Code
fix(gates): refuse a configured ROOT that does not exist in check-rol…