Context
Epic #20328's terminal predicate includes "no Engine CI job checks out the Brain". One job still does. .github/workflows/lint-guides.yml, added by #20177 on 2026-10-30, checks out neomjs/neo-agent-brain at dev. It runs the Brain's ai/scripts/lint/lint-guides.mjs --root engine on every Engine PR or push that touches learn/** or package.json. The epic's own sweep missed it. Found while reconciling the epic's last gaps on 2026-11-08.
The Problem
An Engine pull request is judged by whatever the Brain's dev holds at that moment, for both the lint's code and its data:
- A Brain PR that renames an OpenAPI operation or drops an
ai:* script reds the next Engine PR that touches a guide, even if that PR changed neither.
- A Brain PR can change the Engine's guide gate without any Engine review.
This is the cross-repository coupling the epic removed from the e2e tiers.
Two of the lint's rules need Brain data. Measured over the Engine's fully linted scope, the 10 top-level learn/agentos and learn/benefits guides, at dev d7439e28bd:
ai:* script references: 4, all to ai:fleet-server, in learn/agentos/RunningTheFleetCockpit.md. The Engine's package.json defines no ai:* script, so each resolves only against the Brain's.
- Tool-table references against
ai/mcp/server/*/openapi.yaml: none. No guide in that scope has a Tools heading. The one Engine tool table sits in learn/agentos/tooling/, which the lint excludes.
The other rules read only the Engine tree: Mermaid reserved words and self-loops, dead local links, and ticket ids in learn/guides.
The Architectural Reality
lint-guides.mjs imports only Node built-ins and the Brain's ai/services/shared/isEntryModule.mjs (Brain dev, 2026-11-08). --root comes from neomjs/neo-agent-brain#1366.
- The epic states the ownership rule: "The bridge and the tool definitions are the Brain's to test."
neo-agent-skills already ships shared guards that two repositories run without checking each other out: neo-agent-skills-secrets and neo-agent-skills-ticket-archaeology, installed into runner.temp at the pinned release.
- #17171 moves this repository's guards into the baseline's
guards list: one required context, one runner.
The Fix (shape)
- The guide lint ships in
neo-agent-skills (neomjs/neo-agent-skills#320) as a bin plus a Guides step in the shared PR baseline job. The Engine enables that step by input at its pinned baseline tag, skipping dead-script-ref, so no Engine job checks out the Brain and lint-guides.yml retires. It is not a guards entry: that job runs the consumer's own install, and the Engine pins neo-agent-skills 0.1.90, which has no such bin.
- The Brain-data rules run where the data lives: in Brain CI, over the Engine's guides as the Brain's own
neo.mjs pin ships them (Ada's refinement). The pin is an Engine commit tarball whose learn/ includes these guides. A Brain change that breaks an Engine guide's tool table or ai:* reference then reds the Brain PR that made the change, and neither repository reads the other's dev. The Brain half is neomjs/neo-agent-brain#1518.
- The same PR moves the Engine's exact
neo-agent-skills pin from 0.1.90 to 1.2.0, so the caller tag and the installed skills move together. Engine seats otherwise load skills older than v0.1.94 (Vega's defect-note). .agents/skills is gitignored, so the change is package.json and the lockfile only. The pin stays exact: .github/dependabot.yml documents why, and Dependabot already lands each skills release as its own PR. A range would change that policy, so it belongs with the PR that edits that file (#20606), if it is wanted.
Acceptance Criteria
Out of Scope
- What the lint checks, including the five report-only warnings #20177 left out.
- The guards' required context itself (#17171).
Avoided Traps
- Vendoring the lint into the Engine: two copies of one rule set drift, which is why the shared guards live in
neo-agent-skills.
- Dropping the Brain-data rules: the tool tables would rot silently. Those rules move to the repository that owns the data, and are not deleted.
Related
Parent #20328 · origin #20177 · neomjs/neo-agent-brain#1366 (--root) · #17171 (the guards list).
Decision Record impact: none.
Live latest-open + closed sweep: latest open in neo, plus an org-wide search for lint-guides and "guide lint Brain checkout"; closed #20177 read (Out of Scope: the five warnings); A2A claims and Memory Core checked, 2026-11-08T18:17Z. No equivalent or prior exclusion found.
Owner: @neo-opus-grace (the epic's owner). This is post-cut work: it needs a skills release and Brain CI work, so it does not block the 13.4 cut.
Origin Session ID: 963e0574-17e9-435e-becf-3f3e26c395ce
Retrieval Hint: "lint-guides.yml checks out neo-agent-brain dev Engine guide lint OpenAPI tool tables ai scripts #20328"
Context
Epic #20328's terminal predicate includes "no Engine CI job checks out the Brain". One job still does.
.github/workflows/lint-guides.yml, added by #20177 on 2026-10-30, checks outneomjs/neo-agent-brainatdev. It runs the Brain'sai/scripts/lint/lint-guides.mjs --root engineon every Engine PR or push that toucheslearn/**orpackage.json. The epic's own sweep missed it. Found while reconciling the epic's last gaps on 2026-11-08.The Problem
An Engine pull request is judged by whatever the Brain's
devholds at that moment, for both the lint's code and its data:ai:*script reds the next Engine PR that touches a guide, even if that PR changed neither.This is the cross-repository coupling the epic removed from the e2e tiers.
Two of the lint's rules need Brain data. Measured over the Engine's fully linted scope, the 10 top-level
learn/agentosandlearn/benefitsguides, atdevd7439e28bd:ai:*script references: 4, all toai:fleet-server, inlearn/agentos/RunningTheFleetCockpit.md. The Engine'spackage.jsondefines noai:*script, so each resolves only against the Brain's.ai/mcp/server/*/openapi.yaml: none. No guide in that scope has a Tools heading. The one Engine tool table sits inlearn/agentos/tooling/, which the lint excludes.The other rules read only the Engine tree: Mermaid reserved words and self-loops, dead local links, and ticket ids in
learn/guides.The Architectural Reality
lint-guides.mjsimports only Node built-ins and the Brain'sai/services/shared/isEntryModule.mjs(Braindev, 2026-11-08).--rootcomes from neomjs/neo-agent-brain#1366.neo-agent-skillsalready ships shared guards that two repositories run without checking each other out:neo-agent-skills-secretsandneo-agent-skills-ticket-archaeology, installed intorunner.tempat the pinned release.guardslist: one required context, one runner.The Fix (shape)
neo-agent-skills(neomjs/neo-agent-skills#320) as a bin plus aGuidesstep in the sharedPR baselinejob. The Engine enables that step by input at its pinned baseline tag, skippingdead-script-ref, so no Engine job checks out the Brain andlint-guides.ymlretires. It is not aguardsentry: that job runs the consumer's own install, and the Engine pinsneo-agent-skills0.1.90, which has no such bin.neo.mjspin ships them (Ada's refinement). The pin is an Engine commit tarball whoselearn/includes these guides. A Brain change that breaks an Engine guide's tool table orai:*reference then reds the Brain PR that made the change, and neither repository reads the other'sdev. The Brain half is neomjs/neo-agent-brain#1518.neo-agent-skillspin from 0.1.90 to 1.2.0, so the caller tag and the installed skills move together. Engine seats otherwise load skills older than v0.1.94 (Vega's defect-note)..agents/skillsis gitignored, so the change ispackage.jsonand the lockfile only. The pin stays exact:.github/dependabot.ymldocuments why, and Dependabot already lands each skills release as its own PR. A range would change that policy, so it belongs with the PR that edits that file (#20606), if it is wanted.Acceptance Criteria
neomjs/neo-agent-brainto run the guide lint. The baseline's team-roster read for commit authorship stays, by design (#18757 and #20328's predicate).learn/guides, a dead local link or a Mermaid reserved word still fails a required context.ai:*script named by an Engine guide fails Brain CI. So does one that removes or renames an operation named by an Engine tool table.devcannot change an Engine PR's verdict.Out of Scope
Avoided Traps
neo-agent-skills.Related
Parent #20328 · origin #20177 · neomjs/neo-agent-brain#1366 (
--root) · #17171 (theguardslist).Decision Record impact: none.
Live latest-open + closed sweep: latest open in neo, plus an org-wide search for
lint-guidesand "guide lint Brain checkout"; closed #20177 read (Out of Scope: the five warnings); A2A claims and Memory Core checked, 2026-11-08T18:17Z. No equivalent or prior exclusion found.Owner: @neo-opus-grace (the epic's owner). This is post-cut work: it needs a skills release and Brain CI work, so it does not block the 13.4 cut.
Origin Session ID: 963e0574-17e9-435e-becf-3f3e26c395ce Retrieval Hint: "lint-guides.yml checks out neo-agent-brain dev Engine guide lint OpenAPI tool tables ai scripts #20328"