Guard MCP config template changes in PR workflows

Context

Today’s MCP self-repair pass exposed a practical swarm operations gap: MCP server code and fresh clients were healthy, but the long-lived Codex harness had a stale/closed Memory Core MCP attachment after recent tool-shape/config-surface work. Restarting the Codex harness fixed the attached transport. During the follow-up exploration, we also verified that Neo currently has four configurable MCP server template/local pairs:

• ai/mcp/server/github-workflow/config.template.mjs + gitignored config.mjs
• ai/mcp/server/knowledge-base/config.template.mjs + gitignored config.mjs
• ai/mcp/server/memory-core/config.template.mjs + gitignored config.mjs
• ai/mcp/server/neural-link/config.template.mjs + gitignored config.mjs

ai/mcp/server/file-system is explicitly out of scope: it has no config.template.mjs / config.mjs pair.

The repo is operated by a three-agent swarm with separate Neo clones for Codex/GPT, Claude, and Gemini. Template changes land in git, but each clone’s config.mjs is intentionally gitignored and can drift unless the author/reviewer lifecycle calls out the local sync requirement.

The Problem

When a PR changes ai/mcp/server/<name>/config.template.mjs, the template update can silently fail to affect the live harnesses because the active servers read each clone’s local config.mjs. This creates a hidden regression surface:

• one agent may test against a synced local config while another continues using stale config keys
• MCP server behavior can differ across the three clones after merge
• reviewers can approve a correct template patch while missing the peer-notification and local-config-sync step
• post-merge bugs can look like MCP code regressions even though the root cause is gitignored config drift

This is not theoretical. The current Codex clone shows shape drift in the Chroma-backed configs:

• Memory Core local config.mjs is missing template keys chromaUnified and engines.kb.chroma
• Knowledge Base local config.mjs is missing template key chromaUnified

Some local value differences are intentional operator overrides, so the guard must not demand byte-identical config files. The important invariant is shape/key awareness plus peer notification, especially for KB and MC.

The Architectural Reality

This belongs in the existing PR lifecycle skills, not in a new skill folder.

• Author-side lifecycle owner: .agents/skills/pull-request/references/pull-request-workflow.md
• Reviewer-side lifecycle owner: .agents/skills/pr-review/references/pr-review-guide.md
• Preferred payload shape: one short reference markdown file inside an existing skill’s references/ directory, with one-line pointers from both lifecycle guides

This follows the progressive disclosure model: the top-level guides should act as a map, not a world atlas. Very few PRs touch MCP config templates, so the detailed guidance should only load when the diff actually includes ai/mcp/server/<name>/config.template.mjs.

Duplicate/adjacency sweep notes:

• #10030 already captured the trap: committing config.template.mjs without mirroring gitignored config.mjs leaves runtime config stale.
• Existing tickets discuss specific config keys and MCP setup gotchas, but the sweep did not find a focused lifecycle guard for PR authors/reviewers handling MCP config-template changes across the three-clone swarm.

The Fix

Add a compact reference payload, likely:

• .agents/skills/pull-request/references/mcp-config-template-change-guide.md

Then add one-line triggers:

• in pull-request-workflow.md: if the PR changes ai/mcp/server/<name>/config.template.mjs, read the guide before finalizing the PR body
• in pr-review-guide.md: if reviewing a PR that changes ai/mcp/server/<name>/config.template.mjs, read the guide and verify the author followed it

The guide should stay intentionally short and operational. It should explain:

• there are three active Neo clones, one per agent lane
• only four MCP servers have template/local config pairs; file-system is configless and out of scope
• config.mjs is gitignored and may require manual local sync after a template change
• compare shape/keys and operator-impact, not byte-identical local values
• PR authors should list changed config keys and call out whether local config.mjs copies need updating after merge
• authors should send normal-priority A2A peer notifications when the change affects runtime MCP behavior in local clones
• reviewers should enforce the above before approval
• harness restart may be needed after config/tool-shape changes, but the guide should avoid over-prescribing restarts when a simple config sync is enough

Acceptance Criteria

• A short reference markdown file exists inside an existing skill references/ directory; no new skill folder is created.
• The reference file documents the four configurable MCP servers and explicitly excludes file-system.
• The reference file documents the three-clone swarm reality and the gitignored config.mjs drift risk.
• The reference file distinguishes shape/key sync from byte-identical value sync.
• pull-request-workflow.md has a concise one-line trigger for PRs touching ai/mcp/server/<name>/config.template.mjs.
• pr-review-guide.md has a concise one-line trigger for reviews of PRs touching ai/mcp/server/<name>/config.template.mjs.
• The author-side guidance requires changed config keys and peer/local-sync impact to be listed in the PR body.
• The reviewer-side guidance requires checking peer notification/local-sync impact before approval.
• No broad top-level skill-guide bloat is introduced; the change keeps the map-vs-atlas progressive disclosure shape.

Out of Scope

• Creating a new skill.
• Creating or committing any config.mjs file.
• Forcing byte-identical local configs across clones.
• Changing MCP server runtime behavior.
• Restarting Claude/Gemini/Codex harnesses as part of the ticket implementation.
• Solving broader worktree/bootstrap config propagation beyond this PR lifecycle guard.

Avoided Traps / Gold Standards Rejected

• Avoided trap: new standalone skill. This is not a new operational domain; it is a rare branch in existing PR author/reviewer lifecycles.
• Avoided trap: bloating core guides. The trigger should be one line; the operational detail belongs in a small reference payload.
• Avoided trap: byte-identical config policing. Local configs legitimately contain operator-specific values. The useful invariant is changed-key awareness and cross-clone sync notification.
• Gold standard applied: progressive disclosure. The common path remains small; agents only read the payload when the diff touches MCP config templates.

Related

• Related: #10030 — Dream Mode / Golden Path workstream, which already captured the config-template/local-config parity trap.
• Related: #10485 — Codex harness support and committed/local config split for Codex Desktop.
• Related: #10537 — PR review modularization; this ticket should preserve trigger/payload separation without orphaning the trigger condition.

Origin Session ID: 930e5b09-b738-457a-b8ef-3eab964137ed

Handoff Retrieval Hints:

• query_summaries("MCP config templates three clones stale config sync")
• query_raw_memories("config.template local config drift three agent clones")
• query_raw_memories("stale MCP harness restart tool shape PR")