docs: ENG2 v2 rebuild runbook + perf/test agent rules

[aram-devdocs]

Commits the authoritative v2 rebuild runbook and the agent-config improvements that back the ENG2 program (master tracking issue #810, 102 phase issues + 7 Throne adoption issues).

What this adds

• docs/src/runbook/ (wired into the mdBook SUMMARY.md):
  • index.md, phase-index.md, per-phase specs phases/phase-0..9.md, full phase-specs.md + phase-specs-expansion.md
  • perf-dod.md — the perf definition of done + named scenes S1–S5/H1 with super-high-FPS targets (120+ FPS, tens of thousands of visible entities, O(visible) not O(total))
  • testing-strategy.md — unit/isolation/integration/E2E/spec tiers, the scene story gallery ("Storybook for the engine"), determinism/property/fuzz, Docker CI
  • throne-sync.md, issue-template.md
• Archives ALPHA_ROADMAP.md with a header correcting the false "v2 Core Performance COMPLETE" claim.
• New agent rules .agents/rules/{perf-work,render-v2,testing-v2}.md — perf definition of done, O(visible) render invariants, spec-first/story testing discipline; AGENTS.md points at the runbook.

Why

A 12-subsystem, file:line-verified audit found the engine's 1–17 FPS on Throne traces to O(total) per-object render submission and a 3-global-lock / triple-implemented component store, with instrumentation that reported zero. This runbook is the plan to fix it; the issues (#810 and children) are the execution.

Validation

• scripts/check-agents-md.sh passes (AGENTS.md 54 lines; no stale patterns)
• mdbook build succeeds with the runbook rendered
• docs:-prefixed so release-please cuts no release

🤖 Generated with Claude Code

[claude]

Claude finished @aram-devdocs's task in 3m 27s —— View job

---

Review complete ✅

Todo list

• Read AGENTS.md and repo rules for conventions
• Review diff (git diff origin/main...HEAD)
• Phase 1-2: Context + architecture check (docs-only PR — N/A, no code layers touched)
• Phase 3: Anti-pattern scan (comment-slop blocklist, stale patterns)
• Phase 4: Quality assessment (content correctness, cross-links, mdBook SUMMARY wiring)
• Phase 5: Security (N/A — no code/FFI changes)
• Phase 6: Scope verification vs PR description
• Phase 7: Post structured verdict

Verdict: CHANGES REQUESTED

This is a docs-only PR (no Rust/FFI/SDK code), so Phases 2/3/5 of the standard review (architecture, FFI anti-patterns, security) are N/A. Full review focused on content correctness, mdBook wiring, and the documentation-standards.md comment-slop rules.

BLOCKERS

#	File:Line	Issue
1	docs/src/runbook/phases/phase-9.md:94-98, docs/src/runbook/phase-specs.md:602-606	Leaks the author's local absolute filesystem paths (/Users/aramhammoudeh/dev/game/GoudEngine/..., /Users/aramhammoudeh/dev/game/throne_ge/...) into checked-in, book-rendered docs. These are reader-facing pages (wired via docs/src/SUMMARY.md:37,48), not scratch notes — should be repo-relative paths.

WARNINGS

#	File:Line	Issue
1	docs/src/runbook/phases/phase-9.md:43-98	Duplicates, near-verbatim, the "open-issue disposition map," "issue count summary," and "critical files" sections already in phase-specs.md:551-606. Two copies of the same content will drift; consider trimming phase-9.md to a cross-reference.
2	phase-9.md:89, phase-specs.md:596	Issue-count summary table reports the stale pre-expansion total (91 engine / 98 overall), which contradicts phase-specs-expansion.md:7,119's 102 engine / 109 overall — the two totals were never reconciled in this PR despite both being added in the same commit.
3	phase-9.md:91, phase-specs.md:599	References a path that doesn't match reality: docs/runbook/v2/phases/. The actual wired location is docs/src/runbook/phases/.
4	phase-specs-expansion.md:1,7, issue-template.md:43	References a file design-technical.md (and design-expansion.md) as the base spec — no such file exists in this PR; the actual file is phase-specs.md/phase-specs-expansion.md. Looks like a leftover from an earlier working filename.
5	AGENTS.md	Now 54 lines against the check-agents-md.sh cap of 55 — passes, but only 1 line of headroom before the next edit trips the gate.

Verified clean

• SUMMARY.md wiring: all 18 new files under docs/src/runbook/ are referenced in docs/src/SUMMARY.md:31-48, and every reference resolves to a real file — no orphaned pages, no dead links.
• .agents/rules/{perf-work,render-v2,testing-v2}.md: no attribution lines, dates, change-narration, or AI filler — clean against documentation-standards.md. Phase labels ("ENG2 Phases 2 & 6") are legitimate work-item references, not diff narration.
• ALPHA_ROADMAP.md: the correction is done right — the false [x] ... COMPLETE claim is changed to [ ] ... SUPERSEDED by ENG2 (was falsely marked COMPLETE) with evidence linked, not silently deleted. This preserves the historical record while correcting it, per discovery-first.md's "fix the stale doc in the same change" rule.
• Core runbook pages (index.md, phase-index.md, perf-dod.md, testing-strategy.md, throne-sync.md, issue-template.md): internally consistent (S1–S5/H1/cull_scaling scene names match verbatim everywhere they're used), relative links resolve correctly, no slop patterns.
• mdbook build: not verified — mdbook is not installed in this sandbox and couldn't be added. Recommend confirming the book build in CI before merge.

Positive callouts

• The ALPHA_ROADMAP.md correction approach (mark superseded + link evidence, don't delete) is exactly right for a doc correcting a prior false claim.
• The three new .agents/rules/*.md files are tight, evidence-grounded, and match the existing rule-file style (no fluff, concrete invariants, cross-links via [perf-work]/[render-v2]/[testing-v2] tags).
• Scene naming (S1–S5/H1/cull_scaling) and phase numbering are consistent across every file that references them except for the one reconciliation gap noted above (Warning C# sdk #2).

Recommendation: fix Blocker #1 (strip local paths) before merge; Warnings are non-blocking but #2 (stale issue counts) is worth a quick fix since it's the kind of number someone will cite later.

Fix this →

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!