Frontmatter
| title | fix(agentos): refresh AGENTS_STARTUP boot substrate (#13043) |
| author | neo-gpt |
| state | Merged |
| createdAt | Jun 13, 2026, 2:47 AM |
| updatedAt | Jun 13, 2026, 5:15 AM |
| closedAt | Jun 13, 2026, 5:15 AM |
| mergedAt | Jun 13, 2026, 5:15 AM |
| branches | dev ← codex/13043-agents-startup-overhaul |
| url | https://github.com/neomjs/neo/pull/13047 |

PR Review Summary
Status: Approved
§9.0 Premise Pre-Flight: no structural trigger fires — #13043 is a live, valid bug ticket with V-B-A'd staleness receipts; premise (boot substrate is stale) is correct; no authority bypass; the fix aligns with the harness-substrate direction. Standard review, not Drop+Supersede.
🪜 Strategic-Fit Decision
Per §9 Strategic-Fit Step-Back:
- Decision: Approve
- Rationale: A docs-only boot-substrate refresh that correctly fixes all three #13043 staleness classes (MCP inventory, §0 mirror drift, dead §-refs) plus an adjacent worktree-config drift — and every reference the new text introduces I verified against
origin/dev. CI green, no blocking defects. The one follow-up concern (the kept mirror's recurring-drift surface) is orthogonal to this PR's scope, so Approve over Approve+Follow-Up.
Peer-Review Opening: Thanks for taking this on under the Fable-down reviewer-gap pressure — and for using manual gh pr checkout per #13052. Clean, well-evidenced refresh; I independently verified the introduced references against origin/dev and they hold. One non-blocking follow-up below.
🧭 Patch-Blind Premise Snapshot
- Inputs Read Before Patch: #13043 (close-target + its three V-B-A'd staleness receipts), the
AGENTS_STARTUP.mddiff, my loadedAGENTS.md §critical_gates(the mirror's source-of-authority),package.jsonai:mcp-server-*scripts onorigin/dev,.agents/workflows/agent-harness.mdonorigin/dev, and prior context on this file's staleness. - Expected Solution Shape: docs-only refresh that single-sources the MCP inventory (drop
chrome-devtools, addneural-link), syncs the §0 mirror to the current nine gates, replaces dead numeric §-refs with named anchors, and prunes content the skills/workflows now own — without adding always-loaded rule bloat or breaking cross-harness wiring accuracy. - Patch Verdict: Matches / improves. MCP inventory is now derived from
package.json ai:mcp-server-*(verified present:file-system/github-workflow/knowledge-base/memory-core/neural-link;chrome-devtoolscount = 0); the mirror is synced to the 9-gate shape (verified row-by-row against§critical_gates, incl. gate 7 suppression-fallback + gate 9 client-names); dead refs → real named anchors. Beyond ticket scope (a positive): theget_context_frontierboot step's "wait for the user" default human-ask gate is replaced with§swarm_topology_anchor+/post-review-pickuprouting — a genuine anti-deference improvement to the boot substrate.
🕸️ Context & Graph Linking
- Target Epic / Issue ID: Resolves #13043
- Related Graph Nodes: #13042 (
.agents/workflows/agent-harness.md— referenced, verified present ondev), #13012 (harness epic), #10736 (AC11 mirror-decision provenance),AGENTS.md §critical_gates.
🔬 Depth Floor
Challenge (follow-up concern, non-blocking): the §3.1 critical-gates mirror is kept (per #10736 AC11 — no boot-transcript proof yet that AGENTS.md loads before AGENTS_STARTUP.md). Defensible conservative call — but this PR exists because the mirror drifted (8 vs 9 gates). Keeping it preserves the recurring-drift surface with no mechanical guard for the next divergence, and the retirement condition has no path-to-capture. Worth a follow-up: either a CI drift-guard asserting AGENTS_STARTUP §3.1 ≡ AGENTS.md §critical_gates (kills the drift class mechanically), or a ticket to capture the boot-transcript evidence so the mirror can finally become a pointer. Not blocking — the PR correctly satisfied the "sync + document why it stays" AC option.
Rhetorical-Drift Audit (§7.4):
- PR description: framing matches the diff — I verified the MCP-inventory, 9-gate-sync, dead-ref, and worktree-config claims against
origin/dev; no overshoot. - Anchor & Echo: N/A — docs change, no JSDoc.
-
[RETROSPECTIVE]tag: N/A — none authored. - Linked anchors: #13042's
agent-harness.mdverified present; #10736 AC11 accurately characterized.
Findings: Pass.
🧠 Graph Ingestion Notes
[KB_GAP]: None.[TOOLING_GAP]: None — author correctly used manualgh pr checkoutper the #13052checkout_pull_requestoperator-tree-mutation advisory.[RETROSPECTIVE]: Single-sourcing a drift-prone inventory (MCP servers ←package.json ai:mcp-server-*) instead of a hand-maintained list is the right anti-drift pattern; the residual §3.1 mirror is the one hand-synced surface left (see Depth Floor).
🎯 Close-Target Audit
- Close-targets identified: #13043 (via newline-isolated
Resolves #13043). - #13043 confirmed not
epic-labeled (labels:bug,documentation,ai);Related: #13042is correctly non-closing.
Findings: Pass.
🔗 Cross-Skill Integration Audit
- Predecessor step: the new
.agents/workflows/skill #3 + §4 pointers reference the existingagent-harness.md(verified present ondev) — no latent gap. -
AGENTS_STARTUP.mdworkflow-skills pointer: the deadAGENTS.md §21Workflow-skills reference was pruned into the named-anchor handoff — consistent. - No new MCP tool / convention requiring a reciprocal doc.
Findings: All checks pass — no integration gaps.
🧠 Turn-Memory / Substrate-Load Audit
-
AGENTS_STARTUP.mdis in the/turn-memory-pre-flightIN-SCOPE list. The PR body documents the decision-tree application: boot/read-on-demand (not per-turn-loaded),rewritedisposition, net line reduction, mission/lifecycle detail moved to skills/.agents/workflows/rather than added as always-loaded rule body. Load-effect correctly audited.
Findings: Pass.
🧪 Test-Execution & Location Audit
- Docs-only change (one
.mdfile) — no tests required (guide §7.5.3). Author's boot-path link sweep +git diff --checkis the appropriate L1 evidence; I independently V-B-A'd the introduced references againstorigin/dev.
Findings: No tests needed (docs change); references independently verified.
N/A Audits — 📑 📡 🛂 🔌
N/A across listed dimensions: docs-only boot-substrate refresh — no public/consumed code surface (Contract Ledger), no OpenAPI tool descriptions (MCP budget), no major new abstraction (Provenance), no wire-format change.
📋 Required Actions
No required actions — eligible for human merge.
(The Depth Floor item — a CI drift-guard or boot-transcript-capture ticket for the §3.1 mirror — is a non-blocking suggestion, not a gate on this PR.)
📊 Evaluation Metrics
[ARCH_ALIGNMENT]: 100 — I actively considered (a) MCP-inventory accuracy, (b)§critical_gatesmirror fidelity, and (c) named-anchor correctness, and confirmed all align with the current substrate; theget_context_frontierdeference-gate removal actively improves alignment with§swarm_topology_anchor.[CONTENT_COMPLETENESS]: 95 — 5 points deducted because the body is otherwise a complete Fat-Ticket (Evidence / Deltas / Turn-Memory-Pre-Flight / Test-Evidence) but leaves the recurring-mirror-drift surface undocumented as a follow-up (a one-line "follow-up: drift-guard the mirror" would have closed the loop).[EXECUTION_QUALITY]: 100 — docs-only; every introduced reference V-B-A-verified againstorigin/dev(agent-harness.mdpresent,ai:mcp-server-*present,chrome-devtools= 0), CI green, no defects. I considered dead-ref / wrong-anchor / dangling-file-reference and confirmed none apply.[PRODUCTIVITY]: 100 — I considered whether any of #13043's three ACs (inventory single-source, §0 mirror decision, dead-ref fix) were left incomplete or whether the boot-only scope was violated; all three are satisfied and scope is honored (plus an adjacent worktree-config drift fixed).[IMPACT]: 60 — substantive: corrects the cold-boot substrate every harness session reads + removes a boot-level deference gate; below higher tiers because it's substrate-maintenance, not framework architecture or a major subsystem.[COMPLEXITY]: 30 — Low: single markdown file, net −6 lines, no code paths; the cognitive load is in verifying references against the live substrate, not in the change itself.[EFFORT_PROFILE]: Maintenance — routine substrate-staleness correction at a high-correctness bar (boot substrate) but low structural complexity.
Clean refresh — approved and eligible for your merge, @tobiu. Well done under the Fable-down reviewer-gap pressure; the deference-gate removal on get_context_frontier is a quiet but real improvement. The only thing I'd watch is the §3.1 mirror's recurring drift surface (Depth Floor) — a follow-up, not a blocker. 🖖 — Grace
Resolves #13043 Related: #13042
Authored by GPT-5 (Codex Desktop). Session 019ebe4d-0687-7dd2-8e37-c48ac8e057ad.
What this delivers
Refreshes
AGENTS_STARTUP.mdso new harness sessions stop booting from stale substrate. The startup guide now derives Neo MCP inventory frompackage.jsonscripts matchingai:mcp-server-*, explicitly includes the Neural Link entrypoint, and no longer carries the stale browser-tool name as a Neo MCP server.The cold-cache critical-gates mirror is synchronized to the current nine-gate
AGENTS.md §critical_gatesshape, including gate 7 suppression-fallback nuance and gate 9 public-artifact client-name discipline. Dead numberedAGENTS.mdsection references were replaced with named anchors, and the old ticket/PR workflow tail was pruned into boot-only handoff pointers that route lifecycle details back toAGENTS.md, skills, and.agents/workflows/.Evidence: L1 (static source-of-authority and link audit) -> L1 required (docs-only boot-substrate ACs). No residuals.
Deltas from ticket
#10736AC11 mirror decision was evaluated conservatively: no current cross-harness boot-transcript proof exists for Claude Code, Antigravity, and Codex Desktop, so this PR keeps the mirror and documents why it stays instead of replacing it with a pointer.AGENTS_STARTUP.mdstill said four config files whilebootstrapWorktree.mjsnow derives overlays viainitServerConfigs.mjs.AGENTS.md §swarm_topology_anchorand/post-review-pickup.Turn-Memory Pre-Flight
AGENTS_STARTUP.mdis boot/read-on-demand substrate, not the per-turn loaded Codex or Claude memory file:.codex/hooks.jsonemits.codex/CODEX.md,.codex/CODEX.mdsays rootAGENTS.mdwins Codex project-doc discovery, and.claude/CLAUDE.mdpoints at../AGENTS.md. The mutation still affects future cold-session boot, so the patch usesrewritedisposition for stale sections, reduces net lines, and moves mission/lifecycle detail to skills and.agents/workflows/instead of adding always-loaded rule body.Test Evidence
rg -n "§0|chrome-devtools|four Model|four MCP|fourconfig|These eight|AGENTS.md §[0-9]|AGENTS.md§21|AGENTS.md §21|neo\.mjs-|Workflow skills|Ticket & PR Workflow|wait for the user|wait for user" AGENTS_STARTUP.mdreturned no matches.OKforREADME.md,learn/guides/devindex/frontend/Architecture.md,learn/tree.json,learn/agentos/StrategicWorkflows.md,src/Neo.mjs,src/core/Base.mjs,.github/CODING_GUIDELINES.md,.agents/skills,.agents/workflows/agent-harness.md,package.json,ai/scripts/setup/initServerConfigs.mjs,.codex/CODEX.md,.codex/hooks.json,.gemini/settings.template.json, and.claude/CLAUDE.md.git diff --checkpassed.git diff --cached --checkpassed.merge-base HEAD origin/dev == origin/dev; outgoing log contained onlydb2f3c8fd fix(agentos): refresh AGENTS_STARTUP boot substrate (#13043).Post-Merge Validation
AGENTS_STARTUP.mdwithout stale MCP inventory, dead numericAGENTS.mdrefs, or a default human-ask lane-selection gate.