Context
check-guard-ci-parity.mjs (relocated here by PR #18753 for #17783) requires every lint-staged guard to be mirrored by a workflow gating dev PRs. It deliberately credits a workflow carrying a paths: allowlist, and says why in its own source at NEO_INLINE_CODE_4:
"A paths ALLOWLIST is deliberately not rejected here, where paths-ignore is. […] The allowlist is conditional, so eligibility for it is not free; it is an alignment question, and until that predicate exists an allowlist is credited rather than reported as eight false defects."
This ticket is that predicate. @neo-opus-ada released this half to me on 2026-09-15 (comment) with the identity that makes it one lane: "scan ⊆ paths and 'scanned ⊆ watched' are the same predicate under two names".
Live latest-open sweep 2026-09-16T12:40Z — latest 20 open issues plus a targeted paths scan surface workflow filter covering mirror search: only #18754 (the single-guard instance; PR #18790 open). A2A sweep over the latest 30 messages: no competing [lane-claim]. Raw-memory sweep on the same terms: no prior art.
The Problem
A mirror whose filter does not cover what its guard reads is a false green: the workflow exists, the parity guard credits it, and an edit in the uncovered region never re-runs it. git commit --no-verify then ships past both layers with nothing downstream — the exact hole check-guard-ci-parity exists to close, one level in.
The predicate does not exist because it has nothing to read. Measured on dev today — the partition is the parity guard's own, not a hand census ([lint-guard-ci-parity] OK (15 lint-staged guards, 5 accepted client-only)):
|
|
guards invoked by lint-staged |
15 |
…accepted clientOnly: no mirror, so no alignment question |
5 |
| mirrored — the population this ticket governs |
10 |
| …that expose a scan surface to an importer |
5, under 2 names (SCAN_SURFACE ×4, DEFAULT_SCAN_PATHS ×1) |
| …that know their scan surface but keep it module-private |
5 — check-jsdoc-types#DEFAULT_DIRS, check-relative-links#SCAN_ROOTS, check-theme-value-files#themeRoot, check-theme-coverage's three dirs, check-content-logical-identity#archiveRoot |
So the shape is better than "nine guards cannot answer": every mirrored guard already knows what it reads. Five state it where a spec can ask and five state it where only a reader can, and the two that state it publicly disagree about what to call it. The predicate is unwritable for a naming reason, not a knowledge one — which is why it can be closed in one PR rather than ten.
One live true positive, found by reading the six declarations by hand:
check-jsdoc-types.mjs:37 scans ['src', 'ai', 'examples', 'apps', 'docs/app'], and says so in its own success line — "1233 file(s) read, 0 unparseable type expressions (docs-build parse scope: src, ai, examples, apps, docs/app)". jsdoc-type-lint.yml's paths: carries four of those five. ai is absent — and must be: git ls-files ai → 0.
Same pre-split residue as #18754, one guard over, and it fails more quietly: collectDefaultFiles tolerates find's non-zero exit by design, so nothing errors. The guard simply reports a scope it does not have.
The Architectural Reality
The predicate is not scan ⊆ paths. An untracked member is unreachable by any paths: filter, so a raw subset test reports a defect no workflow edit can fix — and #18754 settles that direction: such a member does not belong in a scan surface at all. Two clauses, not one:
tracked(member) ≠ ∅ for every declared member — the #18754 invariant, generalized from one guard to the population.
scan ∩ tracked ⊆ paths — every tracked file a guard reads is reachable by its mirror's filter.
The first makes the second's ∩ tracked a check rather than a silent narrowing. Without it, dropping a root into a gitignored directory would satisfy alignment by shrinking the left side.
The denominator is the third clause and the one that keeps this honest. check-guard-ci-parity already supplies it: its clientOnly registry partitions the 15 into 5 accepted-unmirrored and 10 mirrored, so the population is derived rather than authored here, and a guard that gains a mirror joins this predicate's scope in the same edit. Within those ten, an undeclared surface is a defect — not an unknown, and not a new registry row, because all ten already know their surface.
The Fix
- One export name across the ten.
SCAN_SURFACE is already the plurality (4 of 5 public); check-ticket-archaeology#DEFAULT_SCAN_PATHS renames onto it and the five private declarations become exports. Members are globs, because paths: filters are globs and comparing a bare root against one is where a hand-rolled subset test produces a confident wrong answer.
- Drop
ai from check-jsdoc-types, with the rule at the export site — the #18754 remedy, applied to the instance this ticket found.
- The predicate as a spec beside the existing
buildScripts unit arms, asserting all three clauses over the population derived from lint-staged minus the registry's clientOnly rows — never a hardcoded list, for the reason discoverGuards() already gives.
Contract Ledger
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback |
Docs |
Evidence |
| Guard scan-surface declaration |
Each mirrored buildScripts/util/check-*.mjs — lint-staged population minus the registry's clientOnly rows |
Exports SCAN_SURFACE as globs |
none: within the ten there is no accepted-undeclared state, because all ten already know their surface |
export-site JSDoc naming the tracked-member rule |
the spec's denominator arm: every derived mirrored guard exports one |
| Mirror filter alignment |
check-guard-ci-parity's eligible-workflow set |
A credited paths: allowlist must cover the guard's tracked scan surface |
none — an uncovered tracked path is a defect claim, not an unknown |
the :259 comment is replaced by the predicate it defers to |
seeded-drift red control: narrowing one workflow's paths: reds the spec |
check-jsdoc-types scope |
DEFAULT_DIRS → SCAN_SURFACE |
ai dropped; the reported scope equals the scope read |
none |
export-site rule, as #18754 |
git ls-files ai → 0; the success line stops naming a root it cannot read |
Retirement: folds into neo-agent-skills#14's unified governance when its reusable workflow supersedes per-repo callers — the same retirement #17783 names.
Acceptance Criteria
Not claimed by this ticket: alignment for the five clientOnly guards. They have no mirror, so there is no filter to align; when one gains a mirror it enters this predicate's population automatically, which is why the population is derived rather than listed.
Out of Scope
- The required-status-context decision (#17171, operator-owned) — this is the coverage half, not the enforcement half.
- Changing what any guard checks, or its CLI surface.
- Workflows that gate
dev but run no lint-staged guard (class-hierarchy-freshness, file-size-guard, consumer-runtime-build, check-package-contents, check-examples-body-only, check-theme-surfaces): outside check-guard-ci-parity's stated population, and pulling them in is a second ticket with its own authority question.
neo-agent-brain's lintWorkflowScanRootParity.spec.mjs — the Brain-side twin, which governs ai/scripts/lint/** and names no buildScripts/util/ guard.
Avoided Traps
- ⛔ Do not write
scan ⊆ paths. It reports eight defects no workflow edit can fix, which is exactly the false-defect family check-guard-ci-parity:259 refused to create. The tracked intersection is the whole difficulty.
- ⛔ Do not let the predicate cover only the guards that already declare. A gate whose denominator is its own numerator is green by construction. AC-4 is not optional polish; it is what makes AC-2 mean anything.
- ⛔ Do not hardcode the guard list.
discoverGuards() already states why: a hardcoded list answers today's question and rots, and a renamed guard leaves the population silently.
- ⛔ Do not compare a root to a glob by string prefix.
src and src/**/*.mjs are the same surface; test/playwright and test/playwright/unit/** are not. This is where a hand-rolled subset test produces a confident wrong answer.
- ⛔ Do not start before PR #18790 merges. It changes
check-ticket-archaeology's declaration and its spec; rebasing a rename onto it is avoidable churn.
Related
#18754 (the single-guard instance — PR #18790) · #17171 (the enforcement half, operator-gated) · #17783 (closed; relocated the parity guard here via PR #18753) · neo-agent-skills#14 (cross-repo callers and required-context binding)
Origin Session ID: 5bf0b816-b919-40fc-9c18-fee751fd1635
Retrieval Hint: "guard scan surface SCAN_SURFACE alignment predicate workflow paths allowlist covering mirror tracked intersection check-guard-ci-parity"
Context
check-guard-ci-parity.mjs(relocated here by PR #18753 for #17783) requires everylint-stagedguard to be mirrored by a workflow gatingdevPRs. It deliberately credits a workflow carrying apaths:allowlist, and says why in its own source at NEO_INLINE_CODE_4:This ticket is that predicate. @neo-opus-ada released this half to me on 2026-09-15 (comment) with the identity that makes it one lane: "
scan ⊆ pathsand 'scanned ⊆ watched' are the same predicate under two names".Live latest-open sweep 2026-09-16T12:40Z — latest 20 open issues plus a targeted
paths scan surface workflow filter covering mirrorsearch: only #18754 (the single-guard instance; PR #18790 open). A2A sweep over the latest 30 messages: no competing[lane-claim]. Raw-memory sweep on the same terms: no prior art.The Problem
A mirror whose filter does not cover what its guard reads is a false green: the workflow exists, the parity guard credits it, and an edit in the uncovered region never re-runs it.
git commit --no-verifythen ships past both layers with nothing downstream — the exact holecheck-guard-ci-parityexists to close, one level in.The predicate does not exist because it has nothing to read. Measured on
devtoday — the partition is the parity guard's own, not a hand census ([lint-guard-ci-parity] OK (15 lint-staged guards, 5 accepted client-only)):lint-stagedclientOnly: no mirror, so no alignment questionSCAN_SURFACE×4,DEFAULT_SCAN_PATHS×1)check-jsdoc-types#DEFAULT_DIRS,check-relative-links#SCAN_ROOTS,check-theme-value-files#themeRoot,check-theme-coverage's three dirs,check-content-logical-identity#archiveRootSo the shape is better than "nine guards cannot answer": every mirrored guard already knows what it reads. Five state it where a spec can ask and five state it where only a reader can, and the two that state it publicly disagree about what to call it. The predicate is unwritable for a naming reason, not a knowledge one — which is why it can be closed in one PR rather than ten.
One live true positive, found by reading the six declarations by hand:
check-jsdoc-types.mjs:37scans['src', 'ai', 'examples', 'apps', 'docs/app'], and says so in its own success line — "1233 file(s) read, 0 unparseable type expressions (docs-build parse scope: src, ai, examples, apps, docs/app)".jsdoc-type-lint.yml'spaths:carries four of those five.aiis absent — and must be:git ls-files ai→ 0.Same pre-split residue as #18754, one guard over, and it fails more quietly:
collectDefaultFilestoleratesfind's non-zero exit by design, so nothing errors. The guard simply reports a scope it does not have.The Architectural Reality
The predicate is not
scan ⊆ paths. An untracked member is unreachable by anypaths:filter, so a raw subset test reports a defect no workflow edit can fix — and #18754 settles that direction: such a member does not belong in a scan surface at all. Two clauses, not one:tracked(member) ≠ ∅for every declared member — the #18754 invariant, generalized from one guard to the population.scan ∩ tracked ⊆ paths— every tracked file a guard reads is reachable by its mirror's filter.The first makes the second's
∩ trackeda check rather than a silent narrowing. Without it, dropping a root into a gitignored directory would satisfy alignment by shrinking the left side.The denominator is the third clause and the one that keeps this honest.
check-guard-ci-parityalready supplies it: itsclientOnlyregistry partitions the 15 into 5 accepted-unmirrored and 10 mirrored, so the population is derived rather than authored here, and a guard that gains a mirror joins this predicate's scope in the same edit. Within those ten, an undeclared surface is a defect — not an unknown, and not a new registry row, because all ten already know their surface.The Fix
SCAN_SURFACEis already the plurality (4 of 5 public);check-ticket-archaeology#DEFAULT_SCAN_PATHSrenames onto it and the five private declarations become exports. Members are globs, becausepaths:filters are globs and comparing a bare root against one is where a hand-rolled subset test produces a confident wrong answer.aifromcheck-jsdoc-types, with the rule at the export site — the #18754 remedy, applied to the instance this ticket found.buildScriptsunit arms, asserting all three clauses over the population derived fromlint-stagedminus the registry'sclientOnlyrows — never a hardcoded list, for the reasondiscoverGuards()already gives.Contract Ledger
buildScripts/util/check-*.mjs—lint-stagedpopulation minus the registry'sclientOnlyrowsSCAN_SURFACEas globscheck-guard-ci-parity's eligible-workflow setpaths:allowlist must cover the guard's tracked scan surface:259comment is replaced by the predicate it defers topaths:reds the speccheck-jsdoc-typesscopeDEFAULT_DIRS→SCAN_SURFACEaidropped; the reported scope equals the scope readgit ls-files ai→ 0; the success line stops naming a root it cannot readRetirement: folds into
neo-agent-skills#14's unified governance when its reusable workflow supersedes per-repo callers — the same retirement #17783 names.Acceptance Criteria
lint-staged, that every declared scan-surface member is tracked (git ls-files <member>non-empty).scan ∩ tracked ⊆ pathsfor every guard that declares a surface AND is credited bycheck-guard-ci-paritythrough apaths:allowlist.paths:below its guard's declared surface reds AC-2's arm; the narrowing is reverted in the same run.lint-stagedminusclientOnly) exportsSCAN_SURFACE. A guard that does not fails, and a guard leavingclientOnlyjoins the population without anyone editing a list.check-jsdoc-typesno longer claimsai, and its reported scope equals what it reads.check-guard-ci-parity.mjs:259's comment no longer defers to a predicate that does not exist.npx playwright test --config playwright.config.unit.mjs test/playwright/unit/buildScriptsgreen, and every touched guard's CLI behavior unchanged — each declaration is a rename or an export, never a change to what the guard reads. The single exception is AC-5, which is the point.Not claimed by this ticket: alignment for the five
clientOnlyguards. They have no mirror, so there is no filter to align; when one gains a mirror it enters this predicate's population automatically, which is why the population is derived rather than listed.Out of Scope
devbut run nolint-stagedguard (class-hierarchy-freshness,file-size-guard,consumer-runtime-build,check-package-contents,check-examples-body-only,check-theme-surfaces): outsidecheck-guard-ci-parity's stated population, and pulling them in is a second ticket with its own authority question.neo-agent-brain'slintWorkflowScanRootParity.spec.mjs— the Brain-side twin, which governsai/scripts/lint/**and names nobuildScripts/util/guard.Avoided Traps
scan ⊆ paths. It reports eight defects no workflow edit can fix, which is exactly the false-defect familycheck-guard-ci-parity:259refused to create. The tracked intersection is the whole difficulty.discoverGuards()already states why: a hardcoded list answers today's question and rots, and a renamed guard leaves the population silently.srcandsrc/**/*.mjsare the same surface;test/playwrightandtest/playwright/unit/**are not. This is where a hand-rolled subset test produces a confident wrong answer.check-ticket-archaeology's declaration and its spec; rebasing a rename onto it is avoidable churn.Related
#18754 (the single-guard instance — PR #18790) · #17171 (the enforcement half, operator-gated) · #17783 (closed; relocated the parity guard here via PR #18753) ·
neo-agent-skills#14(cross-repo callers and required-context binding)Origin Session ID: 5bf0b816-b919-40fc-9c18-fee751fd1635
Retrieval Hint: "guard scan surface SCAN_SURFACE alignment predicate workflow paths allowlist covering mirror tracked intersection check-guard-ci-parity"