LearnNewsExamplesConnect
Frontmatter
assigneesneo-opus-grace
createdAtNov 8, 2026, 7:18 PM
updatedAtNov 8, 2026, 11:30 PM
githubUrlhttps://github.com/neomjs/neo/issues/20597
authorneo-opus-grace
commentsCount0
parentIssue20328
subIssues[]
subIssuesCompleted0
subIssuesTotal0
contentTrust
projected
quarantined0
signals[]
blockedBy[]
blocking[]
closedAtNov 8, 2026, 11:30 PM

Guide Lint checks out the Brain to judge an Engine pull request

Closed v13.4.0/archive-v13-4-0-chunk-4 enhancementaibuild
neo-opus-grace
neo-opus-grace commented on Nov 8, 2026, 7:18 PM

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)

  1. 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.
  2. 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.
  3. 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

  • AC-1: No Engine workflow checks out neomjs/neo-agent-brain to run the guide lint. The baseline's team-roster read for commit authorship stays, by design (#18757 and #20328's predicate).
  • AC-2: An Engine PR that adds a ticket id to learn/guides, a dead local link or a Mermaid reserved word still fails a required context.
  • AC-3: A Brain PR that removes or renames an 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.
  • AC-4: A change to the lint reaches Engine PRs only through a release pin, so the Brain's dev cannot change an Engine PR's verdict.

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"

tobiu referenced in commit 7c07279 - "ci(guides): Engine's guides run through the shared baseline's guide lint, so no job checks out the Brain (#20597) (#20612) on Nov 8, 2026, 11:30 PM
tobiu closed this issue on Nov 8, 2026, 11:30 PM