docs(v2): adopt v2 rearchitecture plan from 3-repo deep-dive review (#106)

Adopt all 12 features synthesized from full-source reviews of
oh-my-claudecode (yeachan-heo), ruflo (ruvnet), and ralph (snarktank),
organized into five layer-based workstreams across six gated phases.

- plans/zo-v2-rearchitecture.md: 20-check tiered oracle, anti-scope,
  reference repo links (+ .gitignore exception)
- docs/reference/v2-rearchitecture.mdx: full feature table w/ provenance
- docs/roadmap.mdx: v2 section (4 pillars + repo credits)
- website: new §11 'What's next' crediting the three source repos
- memory: STATE session 040, DECISION_LOG v2 decision, research corpus
  at memory/zo-platform/research/2026-08-12-repo-reviews/

Website change verified via HTML balance check + static-server DOM
inspection; Astro build deferred to CI (no Node.js on this machine).

Co-authored-by: Sam Tukra <sam101fe4x@Sams-MBP.Home>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: 3 people

.gitignore

@@ -19,6 +19,7 @@ website/.astro/
 # ZO platform's own files are explicitly preserved below.
 plans/*
 !plans/zero-operators-build.md
+!plans/zo-v2-rearchitecture.md
 !plans/mnist-digit-classifier.md
 !plans/cifar10-classifier.md
 targets/*

docs/mint.json

@@ -71,6 +71,7 @@
     {
       "group": "Reference",
       "pages": [
+        "reference/v2-rearchitecture",
         "reference/low-token-preset",
         "reference/cost-benchmark"
       ]
@@ -101,4 +102,4 @@
       "permanent": true
     }
   ]
-}
+}

docs/reference/v2-rearchitecture.mdx

@@ -0,0 +1,113 @@
+---
+title: "v2 Rearchitecture"
+description: "The full feature set ZO v2 adopts from a deep-dive review of oh-my-claudecode, ruflo, and ralph — and how each will be built, tested, and verified."
+---
+
+## Where this comes from
+
+In August 2026 we ran a full-source review of three agent-orchestration systems
+— reading implementations, not READMEs, and separating genuinely-built
+capability from aspiration:
+
+<CardGroup cols={3}>
+  <Card title="oh-my-claudecode" icon="github" href="https://github.com/yeachan-heo/oh-my-claudecode">
+    Hook-enforced execution guarantees, battle-tested across thousands of users. Its enforcement hooks each trace to a real production failure.
+  </Card>
+  <Card title="ruflo" icon="github" href="https://github.com/ruvnet/ruflo">
+    Self-verification machinery: witness manifests, behavioral smoke-test CI, temporal memory semantics.
+  </Card>
+  <Card title="ralph" icon="github" href="https://github.com/snarktank/ralph">
+    The fresh-context loop: 113 lines of bash proving statelessness can be the architecture.
+  </Card>
+</CardGroup>
+
+The review's seven deep-dive passes catalogued 63 features (nine passes in
+total, including a ZO baseline map and an adversarial synthesis), then distilled
+them to the 12 below — deduplicated, ranked by leverage against ZO's documented
+failure modes, and stripped of the things those repos get wrong (we documented
+11 anti-patterns we are explicitly *not* copying, from keyword-triggered
+orchestration to self-asserted completion).
+
+The conclusion in one line: **ZO's oracle discipline stays; underneath it we're
+adding a deterministic enforcement plane, a machine-readable control plane, a
+fresh-context execution substrate, and an oracle for the platform itself.**
+
+## The 12 features
+
+Organized into five layer-based workstreams. The source repo is provenance, not
+architecture — features from different repos interlock into single mechanisms.
+
+### Workstream A — Enforcement plane
+
+*What spawn prompts promise, hooks now guarantee.*
+
+| # | Feature | From | Priority |
+|---|---------|------|----------|
+| 1 | **Machine-checked deliverable contracts** — every agent's produced/consumed contract compiles to JSON (required files, sections, patterns) verified mechanically when the agent stops, plus a zero-cost "completion claim vs. TODO-stub diff" drift guard | oh-my-claudecode | P0 |
+| 3 | **Hook-enforced memory protocol** — STATE.md flushes before compaction, session summaries verified at session end, structured failure records captured automatically; the model can't forget because the model isn't asked | oh-my-claudecode | P0 |
+| 7 | **Anti-forgery gate approvals** — approvals only valid as structured tags carrying a per-verification nonce, so no agent can forge gate passage by echoing text | oh-my-claudecode | P1 |
+| 9 | **Structurally trustworthy verifiers** — the oracle and reviewers mechanically cannot edit code (tool-level enforcement), evaluators emit a strict JSON contract, and evaluation files are sealed against modification by the loop they evaluate | oh-my-claudecode | P1 |
+
+### Workstream B — Control plane
+
+*Progress becomes a query, not prose interpretation.*
+
+| # | Feature | From | Priority |
+|---|---------|------|----------|
+| 4 | **Machine-readable plan ledger with oracle-owned pass flags** — every subtask carries acceptance criteria, a verification command, and a boolean `passes` that only the oracle may flip; plan validation enforces ralph's "Number One Rule": every story fits one context window | ralph + oh-my-claudecode | P0 |
+
+### Workstream C — Execution substrate
+
+*The failure unit becomes one iteration, not one 38-hour session.*
+
+| # | Feature | From | Priority |
+|---|---------|------|----------|
+| 2 | **Watchdog from proven parts** — heartbeat-file liveness, a taxonomy of stops that must never be fought (context-limit, rate-limit, auth, user abort), bounded nudge budgets, and rate-limit wait-and-resume for overnight runs | oh-my-claudecode + ruflo | P0 |
+| 6 | **Fresh-context-per-subtask execution loop** — a new agent per iteration re-derives state from the ledger, experiment lineage, and a curated priors digest; git commits are the checkpoints; context rot and compounding hallucination are eliminated structurally | ralph + oh-my-claudecode | P1 |
+
+### Workstream D — Self-learning & platform oracle
+
+*The self-evolution loop gets the same rigor ZO applies to ML work.*
+
+| # | Feature | From | Priority |
+|---|---------|------|----------|
+| 5 | **Witness manifests + fixture regression** — every verified fix in PRIORS binds to a code marker checked in CI, and prompt-level rule edits replay the original failure fixture before promotion; "this rule would have caught it" becomes a standing check, not a one-time claim | ruflo + oh-my-claudecode | P1 |
+| 11 | **Platform CI doctrine** — behavioral smoke tests reproducing each documented failure symptom, monotone quality ratchets on agent definitions, and doc counts generated from the filesystem instead of hand-maintained | ruflo + oh-my-claudecode | P2 |
+| 12 | **Memory layer upgrades** — temporal supersession semantics (refuted knowledge is invalidated with a pointer to its replacement, never overwritten), a three-question quality gate on new priors, a curated read-first digest, and a CI-enforced context budget | ruflo + oh-my-claudecode + ralph | P2 |
+
+### Workstream E — Operator experience
+
+*Observe/notify/control as load-bearing infrastructure.*
+
+| # | Feature | From | Priority |
+|---|---------|------|----------|
+| 8 | **Two-way gate notifications** — gate-pending, loop verdicts, and stall alerts pushed to Slack/Telegram with cooldowns; replies ("approve" / "reject: reason") route back into the running session with authorization and sanitization | oh-my-claudecode | P1 |
+| 10 | **ZO HUD statusline** — project, phase, pending gate, oracle status, iteration, active agents, and context usage at a glance, rendered from control-plane files | oh-my-claudecode | P2 |
+
+## How it ships
+
+The build follows ZO's own discipline — the plan lives at
+`plans/zo-v2-rearchitecture.md` with a full oracle:
+
+1. **Plan** — six gated phases (enforcement → control plane → substrate →
+   platform oracle → operator UX → integration), each with named verification
+   checks agreed before work starts.
+2. **Build** — every feature lands as a PR with a **seeded-failure test**: the
+   enforcement mechanism must catch a deliberately planted violation before it
+   merges. Nothing ships unwired — no mechanism merges without a runtime caller
+   and an observable test.
+3. **Test** — the 854-test platform suite stays green on Python 3.11 and 3.12
+   throughout; new mechanisms add their own unit + integration coverage.
+4. **Verify** — 20 oracle verification checks (tiered must/should/could), ending
+   with a full demo project run where every new mechanism is observed firing —
+   and a substrate go/no-go: the fresh-context loop must match v1's demo
+   accuracy at ≤ 1.15× cost before it becomes the default.
+5. **Ship** — phase-gated releases; the roadmap and this page track progress.
+
+## What we're deliberately not copying
+
+The review also produced an anti-pattern catalog — dead code presented as
+capability, unverified performance claims, keyword-triggered orchestration,
+self-asserted completion, verification theater, surface-area maximalism. These
+are encoded in the plan's anti-scope and enforced in review. ZO's small, honest
+surface is the asset we're protecting.

docs/roadmap.mdx

@@ -11,9 +11,39 @@ For cost-sensitive plans (Anthropic Pro, student tier, individual researchers on
 
 ---
 
+## The v2 rearchitecture
+
+The headline: after a full-source review of three agent-orchestration systems —
+[oh-my-claudecode](https://github.com/yeachan-heo/oh-my-claudecode),
+[ruflo](https://github.com/ruvnet/ruflo), and
+[ralph](https://github.com/snarktank/ralph) — ZO v2 adopts 12 features across
+five workstreams. ZO's oracle discipline stays; underneath it we're adding:
+
+<CardGroup cols={2}>
+  <Card title="An enforcement plane below the prompts" icon="shield-check">
+    Deterministic hooks that mechanically guarantee what spawn prompts currently promise: deliverable contracts checked when an agent stops, memory that persists automatically, gate approvals that can't be forged, verifiers that structurally cannot edit code.
+  </Card>
+  <Card title="A machine-readable control plane" icon="list-check">
+    A plan ledger where every subtask has verifiable acceptance criteria and a pass flag only the oracle may flip — progress becomes a query, not prose interpretation. STATE.md stays as the human-readable projection.
+  </Card>
+  <Card title="A fresh-context execution substrate" icon="arrows-spin">
+    A new agent per iteration, all state on disk, git as the checkpoint — context rot and compounding errors eliminated structurally, with a watchdog built from battle-tested parts (heartbeats, never-fight-these-stops taxonomy, rate-limit auto-resume).
+  </Card>
+  <Card title="An oracle for the platform itself" icon="scale-balanced">
+    Every learned rule binds to a code marker checked in CI; every documented failure gets a smoke test reproducing its symptom. The self-evolution loop gets the same rigor ZO applies to ML work.
+  </Card>
+</CardGroup>
+
+The full feature list, provenance, and the plan/build/test/verify/ship process
+live on the [v2 rearchitecture page](/reference/v2-rearchitecture). Credit where
+due: these three open-source projects each solved a piece of this puzzle in
+public, and the review that shaped v2 reads their source closely.
+
+---
+
 ## What we're working on
 
-Three workstreams shape the next 1–2 quarters, driven by recent user feedback on cost, accessibility, and cross-phase autonomy. Grouped by horizon: **Now**, **Next quarter**, and **Major design**.
+Alongside the v2 rearchitecture, three ongoing tracks shape the next 1–2 quarters, driven by recent user feedback on cost, accessibility, and cross-phase autonomy — they fold into or queue behind the v2 workstreams above. Grouped by horizon: **Now**, **Next quarter**, and **Major design**.
 
 ### Now (next 2–4 weeks)
 

memory/zo-platform/DECISION_LOG.md

@@ -1227,3 +1227,15 @@ The `--no-headlines` flag is preserved (not removed) for backwards compatibility
 **Rationale:** PR #99 shipped extension points whose documented purpose is letting downstream builds add CLI commands via entry points discovered at `zo.cli` import. A strict-equality command-set test makes the CORE suite fail in any environment where such a plugin is installed — the first real downstream plugin (registering a new command group) surfaced exactly that. The test's job is "core commands all present"; removals still fail under subset.
 **Alternatives considered:** (1) Computing `actual` minus plugin-contributed commands — `load_cli_plugins` doesn't record which commands each plugin added; tracking that adds machinery for a test. (2) Re-importing `zo.cli` with plugin discovery monkeypatched off — fragile import gymnastics for marginal benefit. (3) Leave it and tell downstream users to expect one red test — contradicts the extension point being a supported public mechanism.
 **Outcome:** Single-assertion diff + memory. 854 passed / 7 skipped on Python 3.11 AND 3.12, ruff clean, validate-docs 0 failures. Branch `claude/cli-test-plugin-tolerant`.
+
+## Decision: 2026-08-12T00:00:00Z
+**Type:** ARCHITECTURE + SCOPE
+**Title:** ZO v2 rearchitecture — adopt all 12 reviewed features, organized by layer (not by source repo)
+
+**Decision:** Following the 2026-08-12 deep-dive review of oh-my-claudecode (yeachan-heo), ruflo (ruvnet), and ralph (snarktank) — full findings in `memory/zo-platform/research/2026-08-12-repo-reviews/` — Sam decided to adopt ALL 12 synthesized features. Work is organized into five **layer-based workstreams** (A: enforcement plane, B: control plane, C: execution substrate, D: self-learning & platform oracle, E: operator experience) with the source repo kept as provenance metadata, and sequenced into six gated phases in `plans/zo-v2-rearchitecture.md` with a 20-check tiered oracle. The initiative is documented publicly: `docs/reference/v2-rearchitecture.mdx` (full feature table + reference repo links), a v2 section atop `docs/roadmap.mdx`, and a new §11 "What's next" on the website crediting the three repos.
+
+**Rationale:** The review showed the three repos triangulate ZO's documented weaknesses (aspirational contracts, 38-hour silent stall, manual self-evolution verification, prose-parsed progress). Layer-based workstreams were chosen over source-repo categories because features from different repos interlock into single mechanisms (e.g., ralph's ledger + OMC's contract hook + oracle-owned flags form one control-plane unit; repo-based grouping would force interleaved PRs over the same files). Phase order puts small, pure-addition enforcement/control work first to de-risk the one structural change (fresh-context substrate), which lands behind a demo-validated go/no-go gate (≥ v1 demo accuracy at ≤ 1.15× cost).
+
+**Alternatives considered:** (1) Source-repo workstreams ("ralph track", "ruflo track") — rejected, provenance is not architecture; (2) P0-only scope — rejected by Sam, all 12 wanted; (3) waiting for the SDK refactor before substrate work — rejected, the fresh-context loop is the cheapest on-ramp to that refactor, not a competitor.
+
+**Outcome:** Shipped: plan (+ gitignore exception), docs reference page + mint.json nav, roadmap v2 section, website §11 + drawer nav + §12 renumber, STATE/session-040/research-README memory updates. Verification honest note: **no Node.js available on this machine**, so the Astro build was NOT run locally — the website edit was verified via HTML tag-balance parsing and DOM inspection through a static file server (section renders, all 4 external links present, drawer link + renumbering correct); the deploy pipeline's build is the binding check. validate-docs run pre-commit per protocol.