LearnNewsExamplesServices
Frontmatter
id13043
titleAGENTS_STARTUP.md overhaul: organ inventory, gate-mirror drift, dead references
stateClosed
labels
bugdocumentationai
assigneesneo-gpt
createdAtJun 13, 2026, 2:19 AM
updatedAtJun 21, 2026, 2:16 AM
githubUrlhttps://github.com/neomjs/neo/issues/13043
authorneo-fable
commentsCount0
parentIssuenull
subIssues[]
subIssuesCompleted0
subIssuesTotal0
blockedBy[]
blocking[]
closedAtJun 13, 2026, 5:15 AM

AGENTS_STARTUP.md overhaul: organ inventory, gate-mirror drift, dead references

Closed v13.1.0/archive-v13-1-0-chunk-1 bugdocumentationai
neo-fable
neo-fable commented on Jun 13, 2026, 2:19 AM

Context

Operator finding (2026-06-13): AGENTS_STARTUP.md is "vastly outdated, wrong references, wrong content." V-B-A at filing confirms three structural staleness classes (receipts below). This is repo-wide boot substrate consumed by every harness's cold session — drift here actively mis-grounds new sessions.

The Problem — V-B-A'd staleness receipts

  1. Wrong organ inventory: claims "four MCP servers" (knowledge-base, memory-core, github-workflow, chrome-devtools) — neural-link has ZERO mentions in the file, and chrome-devtools is not part of the current canonical neo server set. The boot document mis-lists the organism's own organs.
  2. §0 mirror drift: the file mirrors "eight rules" while the live turn-loaded substrate carries NINE critical gates (the client-names gate is absent; gate 7's suppression-fallback nuance likewise). The mirror covenant ("updates here MUST also land in AGENTS.md §0 and vice versa") failed in exactly the direction the #10736 AC11 note feared.
  3. Dead references: the AGENTS.md §15–§21 numeric pointers reference a section scheme that no longer exists (current substrate uses named anchors: §verify_before_assert, §knowledge_base_primary_truth, etc.). Step-1 boot-read paths and the Strategic Workflows pointer need re-verification against the current tree.

Prior art: #10586 (a single silently-false boot claim, fixed) — this is the same failure class at file scale.

The Architectural Reality

  • Boot substrate across ALL harnesses (Claude Code via symlink wiring, Codex, Antigravity) — changes need turn-memory-pre-flight discipline and cross-harness thinking.
  • The #10736 AC11 decision is due: the §0 mirror exists "until active-harness boot transcripts verify AGENTS.md loads reliably before AGENTS_STARTUP execution." That verification condition should be evaluated NOW — if met, replace the mirror with a short canonical pointer (kills the drift class permanently); if not met, fix the mirror AND record why it stays.
  • The .agents/workflows/ convention (sibling leaf) may absorb some of this file's per-mission content — the overhaul should leave AGENTS_STARTUP scoped to: one-time boot sequence + Memory Core healthcheck + worktree bootstrap mechanics, exactly as its own closing note already claims.

The Fix

One PR: (1) correct the MCP server inventory (+neural-link, current canonical set, source it from a single authority — ADR/config — rather than hand-listing); (2) resolve the §0 mirror per the #10736 AC11 evaluation (pointer-replacement preferred if the condition holds); (3) fix or remove the dead §-references (point at named anchors); (4) re-verify every boot-read path (Step 1 docs, tree.json claim, StrategicWorkflows) against the live tree; (5) prune content the skills/workflows substrate now owns.

Acceptance Criteria

  • MCP server inventory correct + single-sourced (no hand-maintained list drift).
  • §0 mirror either replaced by the canonical pointer (with the #10736 AC11 evaluation recorded) OR synchronized to nine gates with the drift-cause noted.
  • Zero dead references (every pointer resolves against the live substrate).
  • Every mandated boot-read path verified to exist.
  • File scope honors its own closing note (boot sequence + healthcheck + worktree mechanics only).
  • turn-memory-pre-flight pass documented in the PR (substrate-mutation gate).

Out of Scope

  • The .agents/workflows/agent-harness.md creation (sibling leaf under Epic #13012).
  • AGENTS.md / CLAUDE.md changes beyond what the mirror decision strictly requires.

Related

  • Operator finding provenance: 2026-06-13 session-end review. Prior art: #10586, #10736 (AC11 mirror condition), #10782/#10784 (last STARTUP retrofit wave).
  • Sibling: the workflows-convention leaf (filed alongside).

Origin Session ID: c4caff26-d818-486b-8663-19b85ac3cc11 Retrieval Hint: "AGENTS_STARTUP outdated overhaul mirror drift nine gates neural-link missing boot substrate"

tobiu referenced in commit 26b2974 - "fix(agentos): refresh AGENTS_STARTUP boot substrate (#13043) (#13047)" on Jun 13, 2026, 5:15 AM
tobiu closed this issue on Jun 13, 2026, 5:15 AM