docs: document the Zero swarm architecture

[christopherjnelson]

PR 5 of the zero-swarm migration. Follows #68.

Why

PRs 1–4 removed the legacy multi-agent architecture from the code, but the documentation was never updated. It had drifted into describing a product that no longer exists — 212 references across these files to personalities, agent-to-agent communication, alliances and diplomacy, worker goals, prose memories, the Behavior Trace, and the text-flat-json-v8 per-agent contract. The README opened by describing agents that "communicate and conduct formal alliance diplomacy", then documented an eight-entry memory ledger and a 12 km communication range.

+630 / −762 across eight files.

What

• README.md — rewritten around the delivered architecture: one Agent Zero planning call per tick under swarm-planner-v1, structured directives, TypeSafe Jev reflex workers, schema v12 only.
• docs/ARCHITECTURE.md — the heaviest change. The Formal alliance state section is deleted; Tick flow is rewritten as a 7-step sequence verified against executeNextTick in simulation-service.ts; the API route list drops eight routes absent from app.ts and gains five setup routes that were present but undocumented; worker dispatch is corrected to sequential (for…of with await), which had been documented as concurrent.
• docs/TESTING.md — rewritten against the real 26-file suite, with the scripted seams (scripted-swarm-test, scripted-reflex-test, the deterministic-worker ablation baseline) and the owner validation sequence confirmed against the root package.json.
• docs/SECURITY.md — the untrusted-agent-text surface is now accurately narrow: Agent Zero's strategy summary and directive notes, and Jev's structured output. The goal-text and memory-text sections are gone, with their shared untrusted-input principle folded into the surviving prose rather than lost.
• docs/GAMEPLAY_FOUNDATION.md — treated as the forward-looking design document it declares itself to be, distinguishing current behavior, accepted future direction, and removed features instead of deleting design rationale.
• ROADMAP.md — historical PR entries preserved as a delivery record and annotated where their features were later removed.
• docs/EXPERIMENT_ARCHIVE.md — the carry-forward item flagged in-file for this PR.
• AGENTS.md — see below.

Per ADR 0033, the retirement case is stated as structural rather than measured throughout: the legacy path made one generative call per agent per tick, so cost and latency scaled with roster size. No run in this repository has compared the two architectures on real providers for cost, latency, or quality, and no document here claims otherwise.

Stale beyond this migration

Three things were already wrong before PR 1 and are fixed here:

• pnpm smoke:openrouter does not exist. It was documented in both the README and the testing guide. git log -S shows it was removed in refactor: make zero swarm the sole cognition architecture #65 along with the legacy contract it exercised. Both files now describe the real opt-in real-provider paths: the World Lab Test Agent Zero planner probe and pnpm compare:live.
• docs/EXPERIMENT_ARCHIVE.md documented a pnpm experiment:db patient-zero command that is not in the CLI dispatch, and storage-schema prose predating migrations 4–6. Commands and tables are now verified against cli.ts and migrations.ts.
• Several # headings that should have been ##.

Correction to a known open item

The tracked note that the movement-direction metrics read zero because "no fromCell→toCell direction helper exists" is wrong. The helper exists — geographicDirectionBetweenCells in apps/game-api/src/geographic-direction.ts, already used by swarm pressure and reflex execution. The actual cause is that movementDirectionDistribution, longestRepeatedDirectionStreak and recentCellRevisits are declared in the shared metrics schema but never assigned, so they fall back to schema defaults; ResolvedWorldAction carries only the move target, not the originating cell. The roadmap now records this accurately, alongside calculateExperimentMetrics receiving an empty resolved-action array. Both are owned by the follow-on PR.

Two calls worth reviewing

AGENTS.md is outside the documentation set this PR was scoped to. Its product boundaries still stated that "one optional public or range-limited direct communication and one optional formal diplomacy intent may accompany that action", and that formal alliances were a supported feature. Left unchanged, the governing document would direct future work to rebuild exactly what this migration removed. Revert that hunk if you would rather handle it separately.

Alliances in GAMEPLAY_FOUNDATION.md are marked removed, with the original design rationale preserved as history and the question of whether they return for a future Player Mode deliberately left open. That is a product decision this PR does not make; it belongs in a dedicated ADR.

Validation

Run locally by the repository owner and reported green:

pnpm validate     # 223 tests passed, Prettier clean, no new lint warnings
pnpm test:e2e     # 2 passed

🤖 Generated with Claude Code