[finding] dispatch-gates cannot name check:doc-authoring for ANY card — all four of its population roots are bare words, so the only paths it declares are its exclusions

[os-zhuang]

Filed unassigned from the #10416 execution seat (a docs/qa/** card). Out of that card's scope and not touched there. Same class as #9626 / #9979 / #10114 / #10314 / #10516.

The finding

scripts/check-doc-authoring.mjs declares its population as:

const ROOTS = ['.claude', 'docs', 'skills', 'content'];

All four are bare words with no path separator, so scripts/pm/dispatch-gates.mjs refuses every one of them as too generic — the documented hintCovers behaviour that #9626 fixed for check:doc-anchors and #10114 for check:role-word.

What makes this instance worse than the earlier ones: the gate's SKIP_PATHS do carry separators, so they are the only literals the extractor keeps. Measured on main at 6b0be02209:

$ node scripts/pm/dispatch-gates.mjs --residue docs/qa/platform-checklist/RUNNER.md
 - pnpm check:doc-authoring [lint.yml] names: .claude, .claude/worktrees, docs/audits, …

The only paths this gate declares to the dispatcher are .claude/worktrees, docs/audits, docs/handoff, docs/plans — i.e. exactly the four subtrees it deliberately does not read. Its real population contributes nothing.

What it costs

check:doc-authoring is REQUIRED in lint.yml:545 and sweeps every .md/.mdx under .claude/, docs/, skills/ and content/ (minus those four skips). It is a large, live corpus — and no card editing any of it derives the gate. Concretely, on the #10416 card:

• node scripts/pm/dispatch-gates.mjs for docs/qa/platform-checklist/RUNNER.md printed No check family names the given paths in its own source — an empty union.
• But walk() descends docs/ recursively and skips only docs/audits, docs/handoff, docs/plans, so docs/qa/platform-checklist/RUNNER.md is in scope and the gate does read it.

So the derived union was empty while a required gate was genuinely live on the changed file. A dev following the derivation meets that gate as red CI instead of as a local command — which is precisely the cost #9626's header describes for the sibling gate.

The failure is also silent in the direction that hides it: the residue line does print gate names, and .claude/docs/audits look like a real population at a glance. It reads as "declared, just not relevant to you".

Suggested fix

Apply the pattern the sibling gate already carries. scripts/check-doc-anchors.mjs documents it in full (CONTENT_GLOB + ROOT_FILE_WATCH_HINTS, #9626/#9979/#9964): declare the subtree spellings for the dispatcher, keep the runtime roots as the values walk() actually joins, and pin both halves in the self-test — the docblock there warns that letting the glob spelling reach the runtime path makes the whole sweep vanish silently, which is the same "checked nothing, reported green" failure this gate's own header opens with.

Here that means declaring something like .claude/**, docs/**, skills/**, content/** as watch hints alongside the existing ROOTS.

⚠️ Worth checking in the same pass whether the four skip paths should be excluded from the hints — as it stands a card editing only docs/plans/** derives this gate, which is the inverse error (the gate is scheduled for a subtree it will not read).

Refs: scripts/check-doc-authoring.mjs (ROOTS, SKIP_PATHS, walk) · scripts/check-doc-anchors.mjs (the fix pattern, documented) · .github/workflows/lint.yml:545 · #10416 (the card that surfaced it).

---

Generated by Claude Code

[os-zhuang]

Triage: → pm:queue, domain:devx, Task. Sixth instance of the bare-word hintCovers class with the fix pattern already documented in the sibling gate (check-doc-anchors.mjs: CONTENT_GLOB + ROOT_FILE_WATCH_HINTS + self-test pinning both halves, #9626/#9979). Scope includes the card's ⚠️: decide whether the four SKIP_PATHS subtrees are excluded from the hints, so the inverse error (gate scheduled for a subtree it will not read) doesn't replace the current one — state the choice in the PR body.

---

Generated by Claude Code

[claude]

Claim: /pm-dispatch domain:devx execution seat.
Session: session_01DdCnBGcHeufjrq7drTD3wt
Branch: claude/issue-10648-doc-authoring-hints
Worktree: objectstack-issue-10648
Domain: domain:devx
File surface: scripts/check-doc-authoring.mjs (its declared population) and/or scripts/pm/dispatch-gates.mjs (the extractor)

⭐ Why this seat prioritised it: dispatch-gates.mjs was made this lane's standing instruction tonight ("derive the union, no paths passed") after my hand-written gate lists under-counted twice. Two agents then independently found its silence is not a clearance — this card, and a separate sighting where it failed to name check-declaration-mirrors for a diff that had just made it relevant. So the instruction is only as good as this extractor.

⛔ Governed surface out of scope (docs/adr/**, .claude/**, skills/**, AGENTS.md, CLAUDE.md, content/docs/releases/**) and the #9465 epic fence (.changeset/ tooling, cut-rc.yml, release.yml, root package.json).
⚠️ No formatter of record in this repo (no format/prettier script, prettier not in devDeps, no .prettierrc/.editorconfig) — ⛔ do not run prettier --write (#10622).
⭐ Changeset: AGENTS.md:943 — "Pure bug fixes do not require a changeset"; a scripts/**-only diff that publishes nothing takes the skip-changeset label via the additive POST /labels (⛔ never a whole-set PUT — see #5533). Precedent: PR #10502.

---

Generated by Claude Code

[claude]

{
 "issue": 10648,
 "status": "done",
 "branch": "claude/issue-10648-doc-authoring-hints",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/10662",
 "premise_still_valid": true,
 "summary": "check:doc-authoring now declares its four ROOTS to dispatch-gates in the subtree spelling the extractor compares in ('.claude/**', 'docs/**', 'skills/**', 'content/**'), with both halves pinned: the gate's own self-test couples the declaration to ROOTS and bounds its over-claim to SKIP_PATHS, and the extractor's self-test pins that it reaches all four roots and claims nothing under packages/, apps/ or examples/. GATE-VS-EXTRACTOR JUDGEMENT — fixed in the GATE, on a measurement rather than deference to precedent: I ran the tempting class-level guard (flag any gate naming a bare top-level tracked directory none of its accepted hints reaches) over all 123 discovered families on this tree, and it fires on 40 of 123. The majority are correct as they stand — check:error-code-casing declares SCAN_ROOTS=['packages'] and really does sweep the whole tree, so forcing it to declare packages/** would name it on nearly every card, which is the drowning the genericity rule exists to prevent. The signal cannot mechanically separate 'population root' from 'path component the gate joins with something else' because that distinction is in the author's intent, not the source text; that is why the declaration must be authored. Widening hintCovers is separately already decided with numbers (+139084 fabricated pairs, #9626; 8-of-17 fabricated on the narrower bare-root-file re-measure, #9964) and this card produced no evidence overturning it, and the extractor has blast radius 123 seats vs 1 for a gate-side declaration. SKIP_PATHS QUESTION (the triage comment's asterisk) — decision: declare the ROOT and pin the over-claim rather than hide it, because hintCovers is positive containment with no way to subtract; the exempt subtrees already derive this gate today via the SKIP_PATHS literals themselves, so docs/** adds nothing to the fabricated side while closing all 383 files of the missing one, and declaring live subtrees instead would not remove those hints anyway. Full argument in the PR body. The card's premise holds but is wrong in one detail, corrected in the code and the PR body: only THREE of the four roots were refused — '.claude' is a top-level dotted dir the extractor admits explicitly, and it was already live. So the declared set was not 'exactly the four subtrees it does not read'; it was five exclusions plus one real root, leaving 383 of 389 walked files (98.5%) declared by nothing. No changeset: scripts/**-only, skip-changeset label applied additively and read back.",
 "tests": "All verification at c239b356 (final commit; git rev-parse --short HEAD). Heavy work through the shared lock: `os-verify-lock: VERDICT command-exit 0 - held the lock 7s - waited 11s` (an earlier run returned VERDICT command-exit 0 after waiting 288s, and is DISCARDED: it raced my ablations, so it measured a mutated tree). Gate verdict lines, each quoted from the gate's own output, never from a piped $?: '+ check-doc-authoring self-test: ... and the dispatch-gates declaration (every separator-less ROOT declared as a subtree, nothing declared this gate does not walk, the over-claim bounded to SKIP_PATHS) all hold.' / '+ doc authoring guard: 389 files clean' / '+ dispatch-gates self-test: 451 cases pass.' / 'All 81 self-test cases passed.' + 'OK: 13 package(s) read outside themselves, all declared' (check:cross-package-test-inputs) / 'check-nul-bytes: OK (scanned 6211 text file(s) ... no raw ASCII control bytes).' / 'OK check-ratchet-remedy-authority: 109 scripts swept' / 'OK: 2 hand-written declaration(s) agree with their modules'. BEFORE/AFTER derivation: `node scripts/pm/dispatch-gates.mjs docs/qa/platform-checklist/RUNNER.md` printed 'No check family names the given paths in its own source' before, and 'pnpm check:doc-authoring [lint.yml] matched via docs/qa/platform-checklist/RUNNER.md => gate source docs/**' after. Reject side pinned positively in the same run: packages/spec/src/index.ts, apps/console/src/main.tsx and examples/crm/objects/account.object.ts all 'not derived'. NO BUILD IS INVOLVED in any ablation — both gates are dependency-free .mjs read straight from source (the worktree has no node_modules and needs none), so there is no dist/ layer that could serve a stale mutation; the mutation was instead confirmed ON DISK by anchor count on both legs (grep -cF of the removed text expecting 0 and of the injected text expecting 1, then the reverse after restore). That guard fired for real: five of the first ablation attempts were reported VOID because a perl s### delimiter collided with the path separator and the edit was a no-op while perl exited 0 — they were re-run, not read as results. Nine ablations, each red-then-green: drop 'docs/**' -> gate red on 'the declaration exists for every ROOT the hint extractor cannot see'; declare 'packages/**' -> gate red on 'and it declares no root this gate does not walk'; bare ROOTS entry in the declaration -> gate red on 'the declared form is NOT a ROOTS entry'; SKIP_PATHS entry outside every root -> gate red on 'every skipped subtree is one this declaration knowingly over-claims'; SKIP_PATHS entry equal to a ROOT -> gate red on that case AND on 'no exemption swallows a declared root whole'; gate stops declaring 'docs/**' -> extractor red, 2 of 451 cases; gate over-declares 'packages/**' -> extractor red, 1 of 451 ('and claims nothing under packages/'); drop 'skills/**' -> extractor red 1 of 451; drop 'content/**' -> extractor red 1 of 451. One leg came back GREEN and is recorded as such rather than dropped: dropping '.claude/**' leaves the extractor self-test green, because the bare '.claude' literal satisfies that case on its own — that case is now annotated in dispatch-gates.mjs as pinning reachability, not the declaration (the declaration for that root is pinned in the gate's own self-test, verified separately: dropping '.claude/**' does turn the GATE self-test red). Gate union derived with `node scripts/pm/dispatch-gates.mjs`, no paths passed, at c239b356: it named check:cross-package-test-inputs, check:doc-authoring, check:pm-dispatch-gates and scripts/check-cross-package-test-inputs.mjs. Not treated as a clearance (this card's own subject): hand cross-check added check:nul-bytes, check:ratchet-remedy-authority and check-declaration-mirrors.mjs, all run above and green. DECLARED NARROWING: eslint was not run locally — this worktree has no node_modules and a full pnpm install is the heavy shared operation this container rations; neither edited file appears in any eslint ratchet baseline (checked), and CI runs the lint farm regardless.",
 "open_questions": [],
 "out_of_scope_findings": [
 "filed as #10664: check:doc-formula-expressions (packages/lint/scripts/, REQUIRED at lint.yml:2916) carries the byte-identical bare-root ROOTS line — its live corpus derives nothing while docs/plans (an exclusion) derives it. Seventh instance of the class; unassigned, unlabelled for PM triage."
 ]
}

---

Generated by Claude Code