Context
Sub-issue of Epic #20328 ("Engine CI runs each tier only when a change can reach it"), coordinated with @neo-opus-grace and @neo-gpt-emmy in neomjs/neo#20328 (#issuecomment-6662846915 and MESSAGE:2c695615-05d4-45ef-b0d6-4fe64f5ac1b8).
- Live latest-open sweep: checked latest 20 open issues on
neomjs/neo (#20340 down to #20270) at 2026-11-05T16:17Z; no equivalent found.
- A2A in-flight claim sweep: checked
list_messages({ status: 'all', limit: 30 }) at 2026-11-05T16:17Z; @neo-opus-grace confirmed (MESSAGE:2c695615-05d4-45ef-b0d6-4fe64f5ac1b8) that repo-local lint/check consolidation + substrate-sync.yml PR deduplication is owned by @neo-gemini-julia (Skills #281 covers only the shared neo-agent-skills pr-baseline.yml jobs).
- Memory Core rationale & own-assignment sweep: queried Memory Core (
query_raw_memories for check-guard-ci-parity ScanSurfaceAlignment substrate-sync lint workflows) and inspected buildScripts/util/check-guard-ci-parity.mjs, test/playwright/unit/buildScripts/util/ScanSurfaceAlignment.spec.mjs, and test/playwright/unit/buildScripts/util/check-guard-ci-parity.spec.mjs.
- Design authority: Epic #20328,
buildScripts/util/check-guard-ci-parity.mjs, and test/playwright/unit/buildScripts/util/ScanSurfaceAlignment.spec.mjs.
The Problem
In neomjs/neo, every pull request currently triggers up to 13 separate repo-local lint/check workflows (in addition to pr-baseline.yml), each booting its own Ubuntu runner VM, running actions/checkout@v7 + actions/setup-node@v7 (+ npm ci --ignore-scripts in 6 of them, ~20–30s each), and then executing a <2s Node script (buildScripts/util/check-*.mjs):
.github/workflows/substrate-sync.yml (substrate): runs npm ci (26s) + npx --no-install neo-agent-skills-materialize --check on every pull_request — 100% duplicating pr-baseline.yml's baseline / Skills materialized check (which is already required in dev ruleset 19087298).
- 12 repo-local Node guard workflows (
guard-ci-parity-lint.yml, class-module-scope-lint.yml, content-root-derivation-lint.yml, engine-brain-boundary-lint.yml, fixed-sleep-lint.yml, jsdoc-type-lint.yml, check-relative-links.yml, theme-coverage-lint.yml, theme-value-file-lint.yml, check-examples-body-only.yml, check-theme-surfaces.yml, front-door-fingerprint.yml):
- The first 9 are the
mirroredGuards() population governed by buildScripts/util/check-guard-ci-parity.mjs; the remaining 3 are standalone fast buildScripts/util/check-*.mjs workflows.
- None of their job names (
substrate, lint, check, guard, check-fingerprint) are required status checks in dev ruleset 19087298.
The Architectural Reality
Three repo-local guard contracts inspect .github/workflows/:
buildScripts/util/check-guard-ci-parity.mjs (tested by test/playwright/unit/buildScripts/util/check-guard-ci-parity.spec.mjs):
- Scans
.github/workflows/*.yml and verifies that every lint-staged guard script (outside check-guard-ci-parity-registry.json) is executed by at least one workflow gating dev pull requests.
test/playwright/unit/buildScripts/util/check-guard-ci-parity.spec.mjs pins MIRROR_REL = '.github/workflows/guard-ci-parity-lint.yml' and asserts that guard-ci-parity-lint.yml watches VERDICT_INPUTS (package.json, .husky/pre-commit, .github/workflows/**, buildScripts/util/check-guard-ci-parity-registry.json, buildScripts/util/check-guard-ci-parity.mjs).
test/playwright/unit/buildScripts/util/ScanSurfaceAlignment.spec.mjs:
- Imports
mirroredGuards() from buildScripts/util/check-guard-ci-parity.mjs and asserts that each guard's SCAN_SURFACE is covered by the pull_request.paths filter of its mirror workflow(s).
node_modules/neo-agent-skills/scripts/check-workflow-concurrency.mjs:
- Requires every cancelling
concurrency block in .github/workflows/*.yml to be ref-keyed and rerun-safe (github.run_attempt == '1' && github.ref || github.run_id).
The Fix
- Deduplicate
.github/workflows/substrate-sync.yml on PRs:
- Remove
pull_request: from .github/workflows/substrate-sync.yml so it runs on push: branches: [dev, main] (where post-merge drift is verified), while pr-baseline.yml's required baseline / Skills materialized continues to gate every PR. Saves 1 full npm ci runner slot on every PR.
- Consolidate the 12 repo-local
buildScripts/util/check-*.mjs workflows into .github/workflows/guard-ci-parity-lint.yml:
- Run
actions/checkout@v7, actions/setup-node@v7, and npm ci --ignore-scripts once in .github/workflows/guard-ci-parity-lint.yml, then execute all 12 buildScripts/util/check-*.mjs guards sequentially as direct node ./buildScripts/util/check-*.mjs steps in the same VM (1 runner slot instead of up to 12, eliminating 5 redundant npm ci --ignore-scripts installs).
- Remove the 11 redundant workflow files (
class-module-scope-lint.yml, content-root-derivation-lint.yml, engine-brain-boundary-lint.yml, fixed-sleep-lint.yml, jsdoc-type-lint.yml, check-relative-links.yml, theme-coverage-lint.yml, theme-value-file-lint.yml, check-examples-body-only.yml, check-theme-surfaces.yml, front-door-fingerprint.yml).
- Update the stale-entry mirror-name assertion in
test/playwright/unit/buildScripts/util/check-guard-ci-parity.spec.mjs to match guard-ci-parity-lint.yml.
Contract Ledger Matrix
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback |
Docs |
Evidence |
.github/workflows/substrate-sync.yml |
Epic #20328 & pr-baseline.yml (baseline / Skills materialized) |
Runs on push: branches: [dev, main] only; PR check is already enforced by baseline / Skills materialized |
Fails post-merge on dev/main if skills materialization drifts |
Workflow header in .github/workflows/substrate-sync.yml |
node node_modules/neo-agent-skills/scripts/check-workflow-concurrency.mjs |
.github/workflows/guard-ci-parity-lint.yml & check-guard-ci-parity.spec.mjs |
buildScripts/util/check-guard-ci-parity.mjs & ScanSurfaceAlignment.spec.mjs |
Runs all 12 repo-local buildScripts/util/check-*.mjs guards in 1 runner job per PR/push instead of 12 separate workflows |
Fails the job if any guard script exits non-zero |
Workflow comments & check-guard-ci-parity.spec.mjs |
npm run test-unit (check-guard-ci-parity.spec.mjs + ScanSurfaceAlignment.spec.mjs) |
- Decision Record impact:
none
Acceptance Criteria
Out of Scope
- Changing the shared
neo-agent-skills pr-baseline.yml workflow (neomjs/neo-agent-skills#281, owned by @neo-opus-grace).
- Modifying
file-size-guard.yml, spec-retirement-lint.yml, class-hierarchy-freshness.yml, check-package-contents.yml, or lint-guides.yml (which have distinct trigger types, fetch-depth: 0 range semantics, full docs/pack builds, or cross-repo checkouts).
Avoided Traps
- Do not orphan any
lint-staged guard script from .github/workflows/*.yml: buildScripts/util/check-guard-ci-parity.mjs fails Guard CI Parity if any non-exempt guard script is not executed by an unmasked node ... step in a dev PR workflow.
- Do not weaken
ScanSurfaceAlignment.spec.mjs or check-guard-ci-parity.spec.mjs: Every directory in every guard's SCAN_SURFACE must remain covered by guard-ci-parity-lint.yml's on.pull_request.paths, and without('package.json') / without('.github/workflows/**') must still unwatch those exact inputs in check-guard-ci-parity.spec.mjs.
Related
Origin Session ID: c5b059c4-5d96-46f1-8c61-184af74d34b4
Retrieval Hint: "check-guard-ci-parity ScanSurfaceAlignment substrate-sync guard-ci-parity-lint #20328 #20345"
Context
Sub-issue of Epic #20328 ("Engine CI runs each tier only when a change can reach it"), coordinated with
@neo-opus-graceand@neo-gpt-emmyinneomjs/neo#20328(#issuecomment-6662846915andMESSAGE:2c695615-05d4-45ef-b0d6-4fe64f5ac1b8).neomjs/neo(#20340down to#20270) at2026-11-05T16:17Z; no equivalent found.list_messages({ status: 'all', limit: 30 })at2026-11-05T16:17Z;@neo-opus-graceconfirmed (MESSAGE:2c695615-05d4-45ef-b0d6-4fe64f5ac1b8) that repo-local lint/check consolidation +substrate-sync.ymlPR deduplication is owned by@neo-gemini-julia(Skills #281covers only the sharedneo-agent-skillspr-baseline.ymljobs).query_raw_memoriesforcheck-guard-ci-parity ScanSurfaceAlignment substrate-sync lint workflows) and inspectedbuildScripts/util/check-guard-ci-parity.mjs,test/playwright/unit/buildScripts/util/ScanSurfaceAlignment.spec.mjs, andtest/playwright/unit/buildScripts/util/check-guard-ci-parity.spec.mjs.buildScripts/util/check-guard-ci-parity.mjs, andtest/playwright/unit/buildScripts/util/ScanSurfaceAlignment.spec.mjs.The Problem
In
neomjs/neo, every pull request currently triggers up to 13 separate repo-local lint/check workflows (in addition topr-baseline.yml), each booting its own Ubuntu runner VM, runningactions/checkout@v7+actions/setup-node@v7(+npm ci --ignore-scriptsin 6 of them,~20–30seach), and then executing a<2sNode script (buildScripts/util/check-*.mjs):.github/workflows/substrate-sync.yml(substrate): runsnpm ci(26s) +npx --no-install neo-agent-skills-materialize --checkon everypull_request— 100% duplicatingpr-baseline.yml'sbaseline / Skills materializedcheck (which is already required indevruleset19087298).guard-ci-parity-lint.yml,class-module-scope-lint.yml,content-root-derivation-lint.yml,engine-brain-boundary-lint.yml,fixed-sleep-lint.yml,jsdoc-type-lint.yml,check-relative-links.yml,theme-coverage-lint.yml,theme-value-file-lint.yml,check-examples-body-only.yml,check-theme-surfaces.yml,front-door-fingerprint.yml):mirroredGuards()population governed bybuildScripts/util/check-guard-ci-parity.mjs; the remaining 3 are standalone fastbuildScripts/util/check-*.mjsworkflows.substrate,lint,check,guard,check-fingerprint) are required status checks indevruleset19087298.The Architectural Reality
Three repo-local guard contracts inspect
.github/workflows/:buildScripts/util/check-guard-ci-parity.mjs(tested bytest/playwright/unit/buildScripts/util/check-guard-ci-parity.spec.mjs):.github/workflows/*.ymland verifies that everylint-stagedguard script (outsidecheck-guard-ci-parity-registry.json) is executed by at least one workflow gatingdevpull requests.test/playwright/unit/buildScripts/util/check-guard-ci-parity.spec.mjspinsMIRROR_REL = '.github/workflows/guard-ci-parity-lint.yml'and asserts thatguard-ci-parity-lint.ymlwatchesVERDICT_INPUTS(package.json,.husky/pre-commit,.github/workflows/**,buildScripts/util/check-guard-ci-parity-registry.json,buildScripts/util/check-guard-ci-parity.mjs).test/playwright/unit/buildScripts/util/ScanSurfaceAlignment.spec.mjs:mirroredGuards()frombuildScripts/util/check-guard-ci-parity.mjsand asserts that each guard'sSCAN_SURFACEis covered by thepull_request.pathsfilter of its mirror workflow(s).node_modules/neo-agent-skills/scripts/check-workflow-concurrency.mjs:concurrencyblock in.github/workflows/*.ymlto be ref-keyed and rerun-safe (github.run_attempt == '1' && github.ref || github.run_id).The Fix
.github/workflows/substrate-sync.ymlon PRs:pull_request:from.github/workflows/substrate-sync.ymlso it runs onpush: branches: [dev, main](where post-merge drift is verified), whilepr-baseline.yml's requiredbaseline / Skills materializedcontinues to gate every PR. Saves 1 fullnpm cirunner slot on every PR.buildScripts/util/check-*.mjsworkflows into.github/workflows/guard-ci-parity-lint.yml:actions/checkout@v7,actions/setup-node@v7, andnpm ci --ignore-scriptsonce in.github/workflows/guard-ci-parity-lint.yml, then execute all 12buildScripts/util/check-*.mjsguards sequentially as directnode ./buildScripts/util/check-*.mjssteps in the same VM (1runner slot instead of up to12, eliminating 5 redundantnpm ci --ignore-scriptsinstalls).class-module-scope-lint.yml,content-root-derivation-lint.yml,engine-brain-boundary-lint.yml,fixed-sleep-lint.yml,jsdoc-type-lint.yml,check-relative-links.yml,theme-coverage-lint.yml,theme-value-file-lint.yml,check-examples-body-only.yml,check-theme-surfaces.yml,front-door-fingerprint.yml).test/playwright/unit/buildScripts/util/check-guard-ci-parity.spec.mjsto matchguard-ci-parity-lint.yml.Contract Ledger Matrix
.github/workflows/substrate-sync.ymlpr-baseline.yml(baseline / Skills materialized)push: branches: [dev, main]only; PR check is already enforced bybaseline / Skills materializeddev/mainif skills materialization drifts.github/workflows/substrate-sync.ymlnode node_modules/neo-agent-skills/scripts/check-workflow-concurrency.mjs.github/workflows/guard-ci-parity-lint.yml&check-guard-ci-parity.spec.mjsbuildScripts/util/check-guard-ci-parity.mjs&ScanSurfaceAlignment.spec.mjsbuildScripts/util/check-*.mjsguards in 1 runner job per PR/push instead of 12 separate workflowscheck-guard-ci-parity.spec.mjsnpm run test-unit(check-guard-ci-parity.spec.mjs+ScanSurfaceAlignment.spec.mjs)noneAcceptance Criteria
.github/workflows/substrate-sync.ymlno longer triggers a duplicatenpm cirunner job onpull_request(covered bybaseline / Skills materialized).buildScripts/util/check-*.mjsguard workflows are consolidated into.github/workflows/guard-ci-parity-lint.ymlso a PR boots at most 1 runner job for all 12 guards instead of up to 12.node buildScripts/util/check-guard-ci-parity.mjsandnode node_modules/neo-agent-skills/scripts/check-workflow-concurrency.mjsboth exit0.test/playwright/unit/buildScripts/util/check-guard-ci-parity.spec.mjsandtest/playwright/unit/buildScripts/util/ScanSurfaceAlignment.spec.mjspass undernpm run test-unit.Out of Scope
neo-agent-skillspr-baseline.ymlworkflow (neomjs/neo-agent-skills#281, owned by@neo-opus-grace).file-size-guard.yml,spec-retirement-lint.yml,class-hierarchy-freshness.yml,check-package-contents.yml, orlint-guides.yml(which have distinct trigger types,fetch-depth: 0range semantics, full docs/pack builds, or cross-repo checkouts).Avoided Traps
lint-stagedguard script from.github/workflows/*.yml:buildScripts/util/check-guard-ci-parity.mjsfailsGuard CI Parityif any non-exempt guard script is not executed by an unmaskednode ...step in adevPR workflow.ScanSurfaceAlignment.spec.mjsorcheck-guard-ci-parity.spec.mjs: Every directory in every guard'sSCAN_SURFACEmust remain covered byguard-ci-parity-lint.yml'son.pull_request.paths, andwithout('package.json')/without('.github/workflows/**')must still unwatch those exact inputs incheck-guard-ci-parity.spec.mjs.Related
neomjs/neo-agent-skills#281Origin Session ID: c5b059c4-5d96-46f1-8c61-184af74d34b4 Retrieval Hint: "check-guard-ci-parity ScanSurfaceAlignment substrate-sync guard-ci-parity-lint #20328 #20345"