check:role-word and check:corpus-claim-drift skip every references/ directory, so 12 of 46 published-catalog markdown files - incl. both hand-authored reference companions - are invisible to both scans

[claude]

Measured while implementing #15056 (branch claude/issue-15056-frame-sync-scan-references, PR #15060) at origin/main 82291fba. Unassigned, bare, for triage. File surface: scripts/check-role-word.mjs and scripts/check-corpus-claim-drift.mjs.

What

#15056 is check:skill-frame-sync skipping every directory named references, which hid 44% of its scan population. The same entry sits in two other gates whose roots include the published catalog, and there it hides the same kind of file:

gate	ROOTS	SKIP_DIRS
scripts/check-role-word.mjs	['content/docs', 'skills']	node_modules, .git, dist, references
scripts/check-corpus-claim-drift.mjs	['content/docs', 'skills']	node_modules, .git, dist, references

The reason for the entry is stated in check-corpus-claim-drift.mjs itself and is true of only one of its two roots:

Generated references/ is skipped: the spec source is the fix site there, so a finding in a generated file names the wrong file.

content/docs/references/ is indeed generated from spec (AGENTS.md marks it AUTO-GEN). skills/*/references/ is not the same population, and this repo has already ruled on it twice:

• scripts/check-skill-identifier-liveness.mjs keeps references out of its skip set and pins the difference in its self-test: "under skills/** those files are hand-authored published content, unlike content/docs/references which is generated".
• scripts/check-doc-authoring.mjs gave its published-catalog rule a second walk rather than reuse its own skipping one, because reusing it "would have produced a gate that runs, passes, and cannot see a ninth of the population it exists to guard" — and it names skills/objectstack-data/references/data-hooks.md as a file that "alone carried 15 of these ids when the corpus was measured". It also refuses any exemption for the generated pages there: "A red here is fixed AT THE SPEC SOURCE, never by hand-editing the artifact".

Measured

Markdown under skills/ (.md + .mdx, the extension set both gates use):

population	files
all markdown under skills/	46
invisible to both gates (references/ only)	12 (26%)
of those 12: hand-authored companions	2
of those 12: generator-owned index pages	10

The 2 hand-authored companions are skills/objectstack-data/references/data-hooks.md and skills/objectstack-platform/references/plugin-hooks.md. Both ship verbatim to third-party projects via npx skills add, which is the distribution path both gates give as their reason to read skills/ at all. The 10 generator-owned pages are the nine references/_index.md files plus skills/objectstack-ui/references/react-blocks.md.

Not asserted

No claim that a role-word violation or a stale corpus claim is present in those 12 files today — this card was not the place to run either detector over a widened population, and #15056's flight was scoped to exactly one file. The defect asserted is the missing coverage.

Suggested shape (for triage, not a decision)

The narrow reading is that references belongs in the skip set for a content/docs root and not for a skills root, so a directory-name skip set is the wrong shape for a gate with both: skip by path prefix (content/docs/references) rather than by bare directory name, or give the published catalog its own walk the way check-doc-authoring.mjs did. Whether the generated pages under skills/** then earn an exemption is the same question check-doc-authoring.mjs already answered no to, and answering it differently here would need a reason.

Dedup

Complete enumeration of open items, 2026-09-03: REST GET /repos/objectstack-ai/objectstack/issues?state=open&per_page=100&page=1..6 returned 100+100+100+100+100+32 = 532, reconciled against the repository's own open_issues_count of 532 (508 issues, 24 PRs); local grep over titles and bodies for check-role-word, role-word, corpus-claim-drift, SKIP_DIRS, references/, reference companion, check-doc-authoring. One targeted search_issues covering closed items as well returned 18 results with the control (#15056) hitting, so the channel was live. Nearest neighbours, none of them this: #14659 (the role-word baseline is keyed by file path), #10107 (check-role-word's skills root is invisible to dispatch-gates derivation — a derivation-visibility defect, not a scan-population one), #13335 and #11705 (both about skills/**/references/_index.md being generator-owned, in the merge-driver and governed-fence senses). No carrier found.

---

Generated by Claude Code

[claude]

Triage — skills seat (session session_019RfFHiRCSs3JXLK4cwcfox, os-steve), 2026-09-03T19:46Z. Graded priority:p3, domain:skills (both gates guard the published catalog this lane owns), tooling, state pm:queue, type Task. Applied and read back after this comment.

Scope as queued (XS, two files, pure code): scripts/check-role-word.mjs and scripts/check-corpus-claim-drift.mjs stop skipping every directory named references and skip only the generated root they mean — content/docs/references — by path, not by name; measure each gate's population before and after (expect the 12 catalog files to appear, the generated content/docs/references/ tree still absent), pin the population from the walk in each self-test the way the frame-sync fix did. Stop condition (evidence, not verdict): if either widened scan reds on a hand-authored companion, do not edit that page — leave the gate red on it and name the site in the report; if it reds on a generator-owned index page, that is a generator finding, reported, not hand-edited.

---

Generated by Claude Code

[os-steve]

Claim: PM loop round 3
Session: session_019RfFHiRCSs3JXLK4cwcfox
Branch: claude/issue-15061-catalog-gates-scan-references
Worktree: objectstack-issue-15061
Domain: domain:skills
File surface: scripts/check-role-word.mjs + scripts/check-corpus-claim-drift.mjs (each gate's skip set and its self-test's population pin) (stop on breach; explain in the report). ⛔ No markdown file is edited by this flight.
Container & model: XS code (two skip sets narrowed from a name to the generated path, two population pins), mode:subagent, model: opus (tier: both paths are scripts/check-*.mjs — the frame-sync sibling read "no path-derived mandate … floor sonnet · default opus · ceiling fable" at 82291fba, 19:17Z; PM's call: opus default — the edit reasons about which root each skip was for)
Clause-②: no
Serial constraints cleared: neither file is on the seat post's hot-file queue; no in-flight claim names them; no open PR touches them; the sibling fix on check-skill-frame-sync.mjs is PR #15060 (a different file, at the flip checkpoint). Not governed (check-governed-merges --test on scripts/check-*.mjs reads 0 hits for the sibling; the flight re-runs it on both), no .md ⇒ pure-code landing: in-seat review → ready → auto-merge.

Decision re-read (19:47Z): no maintainer ruling; the seat's triage (comment 5531177809) fixes the scope — skip the generated root by path (content/docs/references), not by directory name; measure each population before and after; population pinned from the walk; a red on a hand-authored companion is reported, never patched in the page.

---

Generated by Claude Code

[claude]

os-dev-report

{
  "issue": 15061,
  "status": "needs_decision",
  "branch": "claude/issue-15061-catalog-gates-scan-references",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/15073",
  "premise_still_valid": true,
  "summary": "Implementation is COMPLETE and pushed; the status reflects one gated decision, not an incomplete flight. Both gates now hold only installed-or-generated NAMES in SKIP_DIRS (node_modules, .git, dist) and exclude the generated tree by PATH through a new SKIP_SUBTREES set holding exactly 'content/docs/references' — matched against the walker's joined path, which is that literal because the walker is seeded with the ROOTS entries verbatim (measured, not assumed). Population per each gate's own verdict line: 224 to 236 files, content/docs 190 to 190, skills 34 to 46 — the 12 catalog files appear, the 214 generated pages stay absent. Each self-test pins that FROM THE WALK in both directions (reaches skills references, reaches no content/docs/references, reaches more than those, every SKIP_DIRS entry declared installed-or-generated, every SKIP_SUBTREES entry under a ROOT and existing), never as a typed count; both gates use the #13489 battery roster, so the rosters go 11 to 12 and 16 to 17 with their floors. STOP CONDITION HIT, exactly as triage anticipated: the widened check:role-word reds on the hand-authored companion skills/objectstack-data/references/data-hooks.md with 12 occurrences. The page is NOT edited and the baseline is NOT touched — the remedy the evidence supports is the one the gate itself marks MAINTAINER-ONLY. check:corpus-claim-drift is GREEN and its baseline does not move. No markdown file was edited. Not a governed surface (0 of 2 paths hit the register, quoted in the PR body); skip-changeset applied additively and read back.",
  "tests": "Head 7c660c57 (git rev-parse --short HEAD from the verification run; tree clean, both ablations restored first). Families re-derived from the commit with `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack` (no paths) — 23 families, identical to the dispatch list, no additions; harvested with --commands. Every exit code captured by redirecting to a file BEFORE any pipe. 21 of 23 green; 1 red by design; 1 NOT MEASURED. RED: `pnpm check:role-word` exit 1 — self-test green, then the gate: 'skills/objectstack-data/references/data-hooks.md: NEW use of the reserved word \"role\" (12 occurrence(s)). ADR-0090 D3: use permission_set / position / business_unit.' plus its MAINTAINER-ONLY baseline clause. GREEN and relevant: `pnpm check:corpus-claim-drift` — 'OK, no new claim sites beside a pinned spelling. Scanned: 236 .md/.mdx file(s) read across 2 root(s) — content/docs 190, skills 46. Ledger: 2 baselined file(s)'; `check-self-test-wired` 'every one of the 166 script(s) CI runs that ship a --self-test has that self-test run by CI'; `check:ratchet-remedy-authority` '186 scripts swept; 12 mark the expanding remedy MAINTAINER-ONLY'; `check:watch-hint-literal` '48 declaration(s) across 4 rostered name(s)'; `bare-root-worklist --self-test` '57 live row(s), 49 recorded verdict(s) — none stale, none missing, none contradicted'; `check:pm-dispatch-gates` 'dispatch-gates self-test: 1291 cases pass'; `check:nul-bytes` 'scanned 8195 text file(s) ... no raw ASCII control bytes'. NOT MEASURED: `node scripts/check-test-completeness.mjs` exit 3, in its own words 'PREREQUISITE NOT MET — this gate grades a saved turbo run test log, and no log was named ... the local reading for this gate is NOT MEASURED. It is not a red'. Repo-wide ESLint run WHOLE, not narrowed, through the shared lock: `OS_VERIFY_LOCK_SLOT=issue-15061-lint bash scripts/pm/os-verify-lock.sh -c 'pnpm lint'` — 'VERDICT command-exit 0 · held the lock 61s · waited 0s'. BASELINE-CORPUS MEASUREMENT: none of check-corpus-claim-drift's four VOCABULARY spellings occurs in any of the 12 newly visible files (per-file count 0 for all twelve), so the baseline does not move and the gate's Ledger line is identical before and after. ABLATIONS, one per gate, each restoring the blanket `references` name-skip: NO REBUILD LEG APPLIES — both gates are plain .mjs run directly from source by path, resolved through no package exports, so there is no dist for a stale artifact to hide in. Mutation proved ON DISK, anchored at the target line: `grep -c -F` of the deleted text returned 0 and of the injected text returned 1 (never the editor's exit code), and the mutated blob hash differed from the HEAD blob. Result both times — the GATE exits 0, GREEN, printing 'Scanned: 224 ... skills 34', while its SELF-TEST exits 1 with 2 cases failing and naming themselves: 'x self-test: #15061 — the walk REACHES the published catalog's reference pages under skills/ ... Restoring the name-keyed skip empties this while the gate itself stays green, which is the dormancy this case exists for'. That is the dormancy the card asserts, reproduced per gate. RESTORE proved by STATE, not by an exit code: `git checkout HEAD -- ABSOLUTE_PATH` (never a bare checkout) inside a trap on EXIT INT TERM with an absolute REPO_ROOT, then `git diff HEAD` empty for the path AND the blob hash equal to the HEAD blob (0f3c2c64 for check-role-word.mjs, 1a81bdc8 for check-corpus-claim-drift.mjs; an empty hash was coded as FAILURE, not as nothing-to-compare), and `git status --porcelain` for each path empty. Gate-script clause: `git grep` over test files for either script name returns nothing — neither gate ships its own vitest suite, so that clause adds nothing beyond the 23 families.",
  "mcp_calls": "0 — zero MCP GitHub calls for the whole run. The card body and all comments came from the public-repo embedded JSON payload (zero quota); the sibling PR diff came from git; PR creation, the skip-changeset additive POST and both read-backs went through repo-scoped REST, probed live first (GET labels/skip-changeset returned 200). `gh` is absent from this container.",
  "open_questions": [
    {
      "question": "check:role-word is now RED on the hand-authored companion skills/objectstack-data/references/data-hooks.md (12 occurrences of the reserved word). Every occurrence is ADR-0090 D3's own named legitimate KIND — quoted pre-rename history documenting the retirement of session.roles ('No role list — session.roles was retired in 17.0.0: it was declared but never produced, so every read was undefined') and a hook comment warning 'Do NOT gate this on a role name', plus one example query on a user field in the better-auth sys_member.role territory D3 already carves out. Which remedy lands, and by whom?",
      "options": [
        "A — the maintainer runs `node scripts/check-role-word.mjs --update` and commits the baseline, admitting these 12 as the quoted-history KIND. Cost stated by the gate itself: --update rewrites the WHOLE baseline from the current tree, so it re-baselines every other file in one stroke, and it weakens a shrink-only ratchet. Marked MAINTAINER-ONLY by the gate; not this seat's act, and not any agent seat's.",
        "B — reword the page so the word disappears. Excluded by the card's own stop condition, and substantively wrong: the sentences ARE the retirement of the identifier they name, so renaming it makes them false — a page that teaches 'there is no role list' cannot say it without the word.",
        "C — mark the occurrences with the os:vendor-wire fence. Does not fit: most sites are prose and code comments rather than a third party's literal wire payload, and the fence exemption keys on a marked FENCE, which those sites are not.",
        "D — leave the gate red on main. Not an option: the two gates are required contexts in Lint and Repo Gates, so this PR cannot land and neither can anything behind it."
      ],
      "recommendation": "A, and it is the maintainer's act, not a seat's. By the four axes: (1) 实际业务需求 — the demand is real and measured, not speculative: these two companions ship verbatim to third-party projects via `npx skills add`, which is the distribution path that puts `skills` in ROOTS at all, so the coverage this PR restores is coverage of text an AI author actually reads in a codebase this repo cannot see; the 12 occurrences themselves are a real page teaching a real retirement. (2) 项目长远合理性 — A is the only option that keeps one strict contract: B falsifies documentation to satisfy a lint, and C would stretch a marking-bounded exemption over prose it was explicitly not extended to ('a backticked word in a sentence is prose with backticks around it'). Both are workarounds in Prime Directive 5's sense; A records the boundary in the ledger where it is greppable and reviewable. (3) 防 AI 写代码犯错 — A is the direction that makes the mistake harder to repeat: the page's whole subject is a declared-but-never-produced key that AI authors kept reading, and its remedy is to keep saying so loudly. Silencing it by rewording would remove the warning and leave the gate green — declared-not-enforced one layer up. Note the tightening this PR itself buys on the same axis: the dormant scan was a gate that ran, passed, and could not see a quarter of its population, which is the exact shape a tolerant consumer has. (4) 创业阶段不扩散需求 — A adds no surface at all: it is one ledger entry on an existing shrink-only baseline, no new exemption mechanism, no new vocabulary, no staged window. C by contrast would grow the exemption's blast radius, and B would spend author time rewriting correct pages. The one honest cost of A is the one the gate prints: --update re-baselines every file in one stroke, so the diff should be read as a whole rather than skimmed for the new row."
    }
  ],
  "out_of_scope_findings": []
}

Generated by Claude Code

---

Generated by Claude Code

[os-steve]

ACCEPT (delivery) — landing gated on a maintainer decision — skills seat (session session_019RfFHiRCSs3JXLK4cwcfox), reviewer of record, 2026-09-03T20:10Z, verified against GitHub and a compare worktree at the PR head, not against the report.

PR #15073 @ 7c660c57 — draft, base main, first line Fixes #15061, two files +266/-13, skip-changeset, no other closing keyword, no model name, one footer, no control bytes. check-governed-merges --test: 0 of 2 hit — not governed.

Content against the triage scope (comment 5531177809): both gates keep only installed-or-generated names in SKIP_DIRS and exclude the generated tree by path through a SKIP_SUBTREES set holding exactly content/docs/references; the seat re-ran both at the head — self-tests green (the walk reaches 236 markdown file(s) … 12 of them published reference pages under skills/, and 0 under the generated content/docs/references), check:corpus-claim-drift green with its ledger unchanged (Scanned: 236 … content/docs 190, skills 46), and check:role-word red by design on skills/objectstack-data/references/data-hooks.md (12 occurrences: the retirement history of session.roles at :350, the "do NOT gate this on a role name" comments at :575 / :837-841, one example query at :733). The stop condition fired exactly as triage wrote it: the page is not edited, the baseline is not touched, and the gate's own text marks the remedy (--update, whole-baseline rewrite on a shrink-only ratchet) MAINTAINER-ONLY. Ablations per gate reproduce the dormancy (gate green at 224 files while the population pin goes red) — good runs.

Decision: the four options and the recommendation (A — the maintainer admits the twelve as the quoted-history kind via --update, or authorises the seat to have the dev run it on this branch with the whole baseline diff read in review) go to the maintainer as decision batch 8. Until it is ruled, the PR stays draft (a required context is red, so it cannot enqueue), the card stays pm:dispatched with this open PR as its in-flight state, and no split is made: landing the corpus-claim-drift half alone would leave the role-word half a second PR and a Part of, for a wait the maintainer has been clearing within the hour today.

Deviations: none. Report mcp_calls: 0 — within contract. CI at 20:08Z on 7c660c57: 32 check runs, 16 success + 11 skipped, five in_progress; Lint & Repo Gates will report the role-word red — expected, not a rework signal.

---

Generated by Claude Code