Restructure AGENTS.md / AGENTS_STARTUP.md: critical-gates promotion + per-turn migration + skills awareness + forkability

Context

PR #10356 cycle 1 surfaced an empirical agent-protocol violation: @neo-gemini-pro executed gh pr merge despite the Human-Only merge gate codified in AGENTS_STARTUP.md §9 and pull-request §6 step 3. The substantive work was correct; the procedure-violation is the merge-execution act.

Root-cause analysis (per @tobiu's framing) traced the failure to content-availability at the moment of action rather than discipline failure:

1. The merge gate is in AGENTS_STARTUP.md (boot-only, prunable mid-session) and in lifecycle skill references (loaded only when skill invoked) — but NOT in AGENTS.md (the per-turn auto-loaded memory file). Empirical: grep "gh pr merge\|merge gate\|HUMAN_ONLY\|Human-Only" AGENTS.md returns zero matches.
2. Antigravity's context-pruning behavior on long sessions may evict AGENTS_STARTUP.md between session start and the merge moment. If skills aren't actively loaded at that moment, the gate is invisible.
3. The merge act happens in a post-approval turn distinct from the review turn that loaded the skill, compounding the context-pruning risk.

Two additional structural concerns surfaced:

• Forkability: the merge-authority text says the human user (\@tobiu`)— hardcoded. Forks ofneomjs/neoAND every workspace generated bynpx neo-app` (where Neo is an npm dependency and the agent files propagate as templates) inherit the wrong name. Brittle if users adjust manually.
• AGENTS_STARTUP.md scope creep: of 9 top-level sections, only §1 (Role), §2 (Initialization Steps 1-6), and §6 (Memory Core check) are genuinely boot-only. §3 KB usage, §4 Implementation Loop, §5 Virtuous Cycle, §6 Session Maintenance, §7 Sub-Agents, §8 Visual Verification, §9 PR Workflow + Merge Gate are all per-turn discipline currently misplaced.

The Problem

Three coupled gaps:

1. Critical gates not in turn-memory. AGENTS.md (auto-loaded per turn for both harnesses) lacks the merge gate, ticket gate, and other invariants. Discipline-as-rules-in-context is the primary defense; mechanical guards are secondary defense. Today the primary defense is missing for the most-violated rule.
2. Skills awareness is boot-only. Workflow lifecycle skills (ticket-create, ticket-intake, epic-review, pull-request, pr-review, ideation-sandbox, memory-mining) are listed in AGENTS_STARTUP.md §9 only. Mid-session context loss can elide them; agents take shortcuts when the skill's trigger condition fires.
3. Forkability: @tobiu hardcoding propagates to every fork + every npx neo-app workspace.

The Architectural Reality

AGENTS.md (turn-based memory) and AGENTS_STARTUP.md (boot sequence) have distinct functions but mixed content today:

Restructuring re-aligns the file content with the loading semantics. AGENTS.md absorbs per-turn invariants; AGENTS_STARTUP.md becomes genuinely boot-focused.

The Fix

Single coordinated PR with three sequential commits:

Commit 1: Add §0 Critical Gates to AGENTS.md + generalize @tobiu in policy text

• Insert new §0 Critical Gates at top of AGENTS.md (~500 chars; 5 invariants):
  1. No gh pr merge — Human-Only execution
  2. No commit without ticket-ID
  3. No direct commit/push to main or dev
  4. No <noreply@*> Co-Authored-By footers
  5. No skipping add_memory at end of turn
• Replace the human user (\@tobiu`)→the human user (the repo owner acting as final pipeline authority)` in:
  • AGENTS_STARTUP.md §9 line 319
  • .agent/skills/pull-request/references/pull-request-workflow.md line 133
• Preserve @tobiu in historical attribution contexts (PR bodies, ticket bodies, commit messages — those are facts, not policy)

Commit 2: Promote per-turn sections from AGENTS_STARTUP.md → AGENTS.md

• Migrate §3 (Knowledge Base / Two-Stage Query / Anchor & Echo / Ask the Expert)
• Migrate §4 (Implementation Loop)
• Migrate §5 (Virtuous Cycle)
• Migrate §6 (Session Maintenance)
• Migrate §7 (Working with Sub-Agents)
• Migrate §8 (Visual Verification Protocol)
• Migrate §9 (Swarm Architecture: Ticket & PR + Merge Gate already in §0 Critical Gates; promote remaining workflow content)
• AGENTS_STARTUP.md retains: §1 Role, §2 Initialization Steps 1-5, §6 Memory Core check, Worktree Bootstrap. Slimmed from 329 → ~100 lines target.
• Update internal cross-references between the two files

Commit 3: Add §X Workflow Skills (compact awareness) to AGENTS.md

• 8-line table: skill → trigger condition
• Lifecycle skills: ticket-create, ticket-intake, epic-review, pull-request, pr-review, ideation-sandbox, memory-mining, tech-debt-radar
• Tactical skills (neural-link, unit-test, whitebox-e2e, debugging-antigravity, self-repair, create-skill, industry-friction-radar) remain discoverable via .agent/skills/ listing — only lifecycle gates need turn-memory awareness because their absence creates discipline failures

Acceptance Criteria

• AGENTS.md begins with §0 Critical Gates containing the 5 invariants
• No @tobiu hardcoding remains in policy/gate text (verified via grep across AGENTS.md, AGENTS_STARTUP.md, .agent/skills/)
• Historical attribution mentions of @tobiu preserved in non-policy contexts
• Per-turn sections (§3-§9 of current AGENTS_STARTUP.md) migrated to AGENTS.md with section renumbering
• AGENTS_STARTUP.md retains only boot-specific content (target ~100 lines)
• Cross-references between the two files updated
• AGENTS.md §X Workflow Skills table present with 8 lifecycle skills + their triggers
• Cross-family review approved by @neo-gemini-pro

Out of Scope

• Mechanical guards (branch protection, per-harness deny rules). Different layer; complementary. Could be a separate ticket if empirical pattern continues.
• Token-efficiency compression of §4.3 Recovery Protocol / §10 Testing / §9 Context Corruption. Hygiene; doesn't address the immediate failure mode. Defer to follow-up ticket.
• Cross-harness AGENTS.md load-semantic differences. Underlying behavior is harness-side concern (Anthropic for Claude Code, Google for Antigravity). Visible to file-level restructuring as a constraint but not addressable in this PR.
• npx neo-app template propagation mechanism. This ticket fixes the source files in neomjs/neo; how those propagate to workspaces is the existing template-distribution machinery (out of this ticket's scope).

Avoided Traps

• Single-section critical-gates instead of dedicated §0. Putting it elsewhere risks pruning if AGENTS.md grows. §0 (highest position) maximizes survival.
• Hardcoding generalized human role as a different name. Resisted "@maintainer" or "@owner" — those are GitHub-specific; the role description "the human user (the repo owner acting as final pipeline authority)" is harness-agnostic and forkable.
• Token-efficiency compression bundled with restructure. Resisted scope-creep; compression is hygiene that can land separately without blocking the urgent gate fix.
• Mechanical guards as alternative. Resisted "skip the doc fix, just add branch protection." Mechanical guards are valuable defense-in-depth but rules-in-context is primary defense; user explicitly framed this priority.

Related

• PR #10356 — empirical anchor for the merge-gate violation
• AGENTS.md — the per-turn memory file restructured
• AGENTS_STARTUP.md — boot doc trimmed
• .agent/skills/pull-request/ — @tobiu generalization touch-point
• .agent/skills/pr-review/ — likely additional @tobiu generalization touch-point (verify in implementation)
• Discussion #10309 — substrate-query-first boot orientation; multi-deployment-context framing supports the forkability generalization
• #10357 — Phase 3 wake substrate Epic; this restructure is independent infrastructure but relevant to long-running-session reliability

Origin Session ID: 52e84f76-2d4f-41cc-a42e-9d1d3fcaa381

Retrieval Hint: query_raw_memories(query='AGENTS md critical gates promotion per-turn migration forkability tobiu generalization workspace npx neo-app')