LearnNewsExamplesServices
Frontmatter
id18791
titleA workflow''s paths: allowlist is credited as a mirror without checking it covers the guard''s scan surface
stateClosed
labels
bugaitestingbuild
assigneesneo-opus-vega
createdAtSep 16, 2026, 2:29 PM
updatedAtSep 16, 2026, 3:51 PM
githubUrlhttps://github.com/neomjs/neo/issues/18791
authorneo-opus-vega
commentsCount0
parentIssuenull
subIssues[]
subIssuesCompleted0
subIssuesTotal0
contentTrust
projected
quarantined0
signals[]
blockedBy[]
blocking[]
closedAtSep 16, 2026, 3:51 PM

A workflow's paths: allowlist is credited as a mirror without checking it covers the guard's scan surface

Closed v13.2.0/archive-v13-2-0-chunk-21 bugaitestingbuild
neo-opus-vega
neo-opus-vega commented on Sep 16, 2026, 2:29 PM

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

  1. 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.
  2. Drop ai from check-jsdoc-types, with the rule at the export site — the #18754 remedy, applied to the instance this ticket found.
  3. 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

  • AC-1: a spec asserts, over the population derived from lint-staged, that every declared scan-surface member is tracked (git ls-files <member> non-empty).
  • AC-2: a spec asserts scan ∩ tracked ⊆ paths for every guard that declares a surface AND is credited by check-guard-ci-parity through a paths: allowlist.
  • AC-3: red control — narrowing one mirror's paths: below its guard's declared surface reds AC-2's arm; the narrowing is reverted in the same run.
  • AC-4: the denominator is asserted — every mirrored guard (derived: lint-staged minus clientOnly) exports SCAN_SURFACE. A guard that does not fails, and a guard leaving clientOnly joins the population without anyone editing a list.
  • AC-5: check-jsdoc-types no longer claims ai, and its reported scope equals what it reads.
  • AC-6: check-guard-ci-parity.mjs:259's comment no longer defers to a predicate that does not exist.
  • AC-7: npx playwright test --config playwright.config.unit.mjs test/playwright/unit/buildScripts green, 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 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"

tobiu referenced in commit 643fc5a - "feat(buildScripts): a mirror's paths filter is held to what its guard reads (#18791) (#18793) on Sep 16, 2026, 3:51 PM
tobiu closed this issue on Sep 16, 2026, 3:51 PM