conductor(track): nagent_review_v3 spec + plan

Initial v3 spec + plan for the major nagent review update. Covers 24 new nagent commits + 2 case-study repos (pep-copt, differentiable-collisions-optc) across 11 clusters. v2.3 historical reviews preserved; v3 is the canonical going forward.
2026-06-20 07:10:11 -04:00
parent 8f54deda9f
commit 0a21627b8a
2 changed files with 1550 additions and 0 deletions
@@ -0,0 +1,372 @@
+# Track Specification v3: nagent_review_20260608 — Major Update (nagent + Case Studies)
+
+**Status:** Draft (pending user review)
+**Initialized:** 2026-06-19
+**Owner:** Tier 1 Orchestrator (sole author)
+**Priority:** Medium (architectural; informs future Application + Meta-Tooling decisions)
+**Spec pair:** `spec_v3.md` (this file) + `plan_v3.md` (the implementation plan, produced by the writing-plans skill after this spec is approved)
+**Lineage:** Sits alongside the existing v2.3 spec (`spec.md` at `eb6be32a` baseline) and v1/v2/v2.1/v2.2 historical reviews in the same track directory. v2.3 is preserved as historical; v3 is the canonical going forward.
+
+> **Reading note.** This spec supersedes only the deliverables, not the v2.3 reasoning. The 14-pattern analysis in `nagent_review_v2_3_20260612.md` remains the "what we knew on 2026-06-12" reference. v3 covers (a) the 24 new nagent commits on `main` between `eb6be32a` (2026-06-12) and `a1f0680` (2026-06-18), and (b) the two case-study repos that didn't exist at v2.3 baseline.
+
+---
+
+## 1. Overview
+
+This is a **major version update** (`v3`) to the existing `nagent_review_20260608` track. It is not a delta-followup. It is a full rewrite that replaces the v2.3 canonical review with a v3 review covering:
+
+1. **The 24 new nagent commits** on `macton/nagent@main` between `eb6be32a` (2026-06-12) and `a1f0680` (2026-06-18) — a 6-day, 3×-volume update over the v1→v2 baseline that triggered the original review.
+2. **The two case-study repos** that Acton built using nagent between v2.3 and now: [`macton/pep-copt`](https://github.com/macton/pep-copt) (PEP image compression, 2.04× speedup, byte-identical output) and [`macton/differentiable-collisions-optc`](https://github.com/macton/differentiable-collisions-optc) (Convex Primitive Collision Detection, 102× speedup). Neither existed at v2.3 baseline.
+
+v3 covers **three entirely new first-class subsystems** (campaigns, conversation safety net, hooks), **one new provider** (Together), **one delegation bug fix**, **eight expanded pattern areas**, and **two end-to-end case studies** that demonstrate nagent's per-turn proof harness in production. The case studies are inseparable from the hooks feature they showcase — the hooks commit (`a4fb141`) is the substrate the case studies depend on.
+
+### 1.1 What v3 produces (artifact table)
+
+| Artifact | Action | Purpose |
+|---|---|---|
+| `nagent_review_v3_20260619.md` | **NEW** | The v3 canonical review. ~5,500-6,500 LOC. 11 cluster sections + supporting structure (TL;DR, reading guide, lineage note, references). |
+| `comparison_table.md` | **REPLACE** | Refreshed for v3. v2.3 content recoverable via `git log -p`. |
+| `decisions.md` | **REPLACE** | Refreshed for v3. ~25-30 candidates (v2.3's 16 + v3's ~10-14 new). Top of file includes a v2.3 → v3 status mapping (PROMOTED / SUPERSEDED / STILL-OPEN / WITHDRAWN). |
+| `nagent_takeaways_v3_20260619.md` | **NEW** | Bridge doc: v2.3 takeaways → v3 deltas + v3's new takeaways + sibling-review cross-refs (fable_review, intent_dsl_survey, superpowers_review). |
+| `nagent_takeaways_20260608.md` | **KEEP** | Unchanged historical reference (the v2.3-era bridge doc). |
+| `spec_v3.md` (this file) | **NEW** | The v3 spec. |
+| `plan_v3.md` | **NEW** | The v3 plan (produced by writing-plans after this spec is approved). |
+| `metadata.json` | **REFRESH** | v3 fields: `nagent_commits_reviewed`, `scope`, `verification_criteria`, `deferred_to_followup_tracks`. v2.3 fields preserved in git history. |
+| `state.toml` | **REFRESH** | Update `current_phase`, `phases`, `tasks`, `verification` as v3 phases complete. |
+| `report.md` + all `nagent_review_v2*.md` | **KEEP** | All v1/v2.x historical reviews preserved as-is. |
+| `conductor/tracks.md` | **NO CHANGE** | Per the "B. Same track, v3 update" decision, v3 lives under the existing `nagent_review_20260608` track. |
+
+### 1.2 Non-Goals
+
+- **Not** rewriting Manual Slop to use nagent. The architectures serve different domains (per `spec.md` §2: Application vs Meta-Tooling).
+- **Not** replacing any existing track. v3 is a *refresh* of the nagent review track; it informs future tracks but doesn't compete with them.
+- **Not** a complete rewrite of v2.3's reasoning. v2.3's 14-pattern analysis stands. v3 adds, updates, and supersedes — it doesn't delete the historical analysis.
+- **Not** a Tier 3-dispatched review. v3 is Tier 1 sole-authored (mirrors v2.3 and `fable_review_20260617`). No parallel cluster dispatches.
+- **Not** a deep-dive of the Fable system prompt or the superpowers plugin. Those are sibling reviews (`fable_review_20260617`, `superpowers_review_20260619`); v3 cross-references them, doesn't replicate them.
+- **Not** a marketing comparison. v3 is for engineers, not framework-vs-framework discourse.
+
+---
+
+## 2. Current State Audit
+
+**As of 2026-06-19.** Baseline commits reviewed:
+- **nagent** at `a1f0680` (2026-06-18 23:51:28 UTC) — the latest commit on `macton/nagent@main` as of v3 init.
+- **pep-copt** at `main` (5 commits) — the case-study repo for image compression optimization.
+- **differentiable-collisions-optc** at `main` (5 commits) — the case-study repo for collision detection.
+
+### 2.1 What v2.3 already covered (DO NOT re-litigate)
+
+v2.3 (`nagent_review_v2_3_20260612.md`, 4,969 lines) reviews nagent at `eb6be32a` (2026-06-12 00:25:50 UTC) and is the authoritative "what we knew on 2026-06-12" reference. It covers:
+
+- The 14 patterns of nagent (build → rename → own → exploit → name → apply → compare), one section per pattern.
+- The 8 new commits since v1 (2026-06-08 → 2026-06-12) introducing the knowledge harvest, tag parser, claude-code provider, project context, prompt caching, conversation direction, and compaction patterns.
+- The harvest pipeline (§4), cache strategy (§5), compaction pattern (§6), architecture (§7), protocol (§8), file-ops (§9), candidates (§10), artifacts (§11), next-steps (§12), and references (§13).
+- 16 future-track candidates in `decisions.md` (candidates 1-16).
+
+v2.3 remains valid for all material at the `eb6be32a` baseline. v3 does NOT redo this work.
+
+### 2.2 What v3 adds (gaps to fill)
+
+24 new commits on nagent, organized into 8 internal change clusters + the 2 case-study repos + 1 cross-cutting methodology cluster:
+
+#### nagent-internal changes (23 commits)
+
+| Cluster | Commits | What it adds |
+|---|---|---|
+| **Campaign system** (6) | `24cf16d`, `199a36b`, `f3ec090`, `c1d2cad`, `6443d70`, `7a7e242` | Plans as operable artifacts + distill passes (merge / graduate) + ordered-issue filing. New `.nagent/campaigns/` layout (TBD pending source-read). Renames `nagent-gc` to `nagent-distill`. |
+| **Conversation safety net** (2) | `38d3d4f`, `6426a67` | Checkpoints + rebuild + instant save (extracted summaries). New failure-recovery semantics for long-running conversations. |
+| **Hooks** (1) | `a4fb141` | `--hook-per-run` + `--hook-per-file-edit`. The mechanism the case studies depend on for per-turn proof injection. |
+| **Project-local roots** (4) | `54c8741`, `557dd39`, `0b9d1a2`, `023e23a` | Default root moved into project. `nagent-gc` renamed to `nagent-distill`. Scratch files git-ignored. |
+| **Provider expansion** (3) | `bdfa2a6`, `5075f6e`, `2edc7ee` | Together provider + per-model token-cap rebuilds + `--list-providers`. claude-code billing fix + spinner names. |
+| **Delegation rewrite** (3) | `d56f0f0`, `65787a6`, `315fe9e` | "Decomposition, not offloading" + context-isolation rationale + recursion-bug fix. |
+| **Robustness** (4) | `065168c`, `6b762da`, `12c35b7`, `49e07f3` | Tolerate non-protocol output + collapse duplicate tags + shell-before-next ordering + per-conversation scratch dir for `<nagent-write>`. |
+| **Operating rules** (1) | `a1f0680` | Sampling can justify replacing the machine (simplification-pass Q9). `context/data-oriented-design.md` expanded. |
+| **README regeneration** (1) | `afc7ab8` | Full arc with campaigns + safety net. Documentation-only commit; folded into the cluster sections that introduce the new features. |
+
+#### Case-study repos (10 commits across 2 repos, both on `main`)
+
+| Repo | Commits | Subject | Key result |
+|---|---|---|---|
+| [`macton/pep-copt`](https://github.com/macton/pep-copt) | 5 | PEP image compression: reference vs LLM-optimized | 2.04× speedup aggregate (1.5–2.6× per image, 24-image benchmark). Byte-identical `.pep` output (size ratio 1.00× on all images). |
+| [`macton/differentiable-collisions-optc`](https://github.com/macton/differentiable-collisions-optc) | 5 | Convex Primitive Collision Detection: reference vs LLM-optimized (Tracy/Howell/Manchester arXiv:2207.00669) | 102× speedup on the committed 1000-pair benchmark (~98–102× generally). Distance-tolerance match contract (1mm + 0.1%·|d_ref| + 5e-4·(|c1−c2|/α²)). |
+
+Both repos share the same 4-prompt methodology and the same proof-harness pattern. Both use the new `nagent --hook-per-run ./prove-optimized-harness.sh` mechanism.
+
+#### Cross-cutting: the case-study methodology
+
+A *pattern* emerges from comparing both repos: the 4-prompt methodology + proof harness + optimization log + committed-input sha256 freeze + "GPT-5.5" model-as-test-subject. This is itself a cluster candidate — call it **Case-study methodology** — that surfaces the reusable abstraction Acton is iterating on.
+
+### 2.3 Gaps in v2.3 that v3 fills
+
+| Gap | Why v2.3 missed it | What v3 adds |
+|---|---|---|
+| **Three first-class subsystems** (campaigns, safety net, hooks) | Did not exist at `eb6be32a`. | New cluster sections (§1, §2, §3) in v3. |
+| **Per-model token-cap rebuilds + Together provider** | v2.3 had 5 providers; nagent now has 6 (with Together) + per-model context windows. | Updated providers cluster (§5) in v3. |
+| **The delegation-recursion bug fix** | v2.3 noted delegation as a pattern; the recursion bug (`file-edit agent → worker → nagent-file-edit → ...`) was discovered and fixed post-v2.3. | New "Delegation rewrite" cluster (§6) documenting the bug, the fix, and the rationale. |
+| **The hooks pattern (per-turn proof injection)** | Did not exist at v2.3. The case studies depend on it. | New "Hooks" cluster (§3) + the case-study methodology cluster (§9) + deep-dives (§10, §11). |
+| **Operating rules: sampling justifies replacing the machine** | v2.3 cited `context/data-oriented-design.md` as Acton's canonical rule set but did not deep-dive its evolution. The `a1f0680` commit expands it with Q9. | New "Operating rules" cluster (§8). |
+| **The case-study pattern as a reusable abstraction** | Did not exist (no case studies existed at v2.3). | New "Case-study methodology" cluster (§9) + deep-dives (§10, §11). |
+
+### 2.4 Honest gaps in v3 (the source-read pass may surface more)
+
+The 11-cluster scheme is based on commit subjects + substantive commit messages + the case-study READMEs. It is NOT yet based on a full source-read of the new code. v3's authoring plan includes a source-read pass per cluster that may:
+
+- Surface new clusters not visible from commit subjects (likely candidates: `.nagent/` runtime state directory layout, `bin/nagent-distill` internals, the `data-oriented-design.md` expansion's downstream effects).
+- Argue for merging two existing clusters (likely candidates: campaigns + safety net, which both touch failure recovery).
+- Reveal that a cluster's description is wrong (e.g., the "merge/graduate" semantics may not be what they appear to be from commit subjects).
+
+The cluster scheme is a **working hypothesis** that the v3 plan's Phase 1 audit pass will validate or adjust.
+
+---
+
+## 3. Goals
+
+The goals of v3, in priority order:
+
+1. **Capture the 24-commit nagent evolution since v2.3 baseline.** Surface the new patterns, the bug fixes, the new subsystems, and the new providers. Each new pattern gets source-read citations, not just commit-subject paraphrases.
+2. **Document the case-study pattern as a reusable abstraction.** Both case-study repos share a 4-prompt methodology + proof harness + optimization log + committed-input sha256 freeze. This is itself a pattern worth deep-diving — and Manual Slop could adapt parts of it (per the candidate decisions in `decisions.md`).
+3. **Preserve v2.3's reasoning.** v3 does not delete v2.3. The 14-pattern analysis stands; the 16 candidates evolve; the historical reviews stay as-is in the track directory.
+4. **Surface v3-specific decisions for the deferred Manual Slop rebuild.** Per the user's deferred-rebuild plan (per `spec.md` §10 of the existing track), v3 candidates are inputs to that future rebuild. v3's `decisions.md` makes the new candidates explicit.
+5. **Cross-reference sibling reviews** (`fable_review_20260617`, `intent_dsl_survey_20260612`, `superpowers_review_20260619`) so the user can read all four reviews as a unified corpus.
+
+### 3.1 Stretch goals (if scope allows)
+
+- A cross-track synthesis section that compares the operating rules across nagent, Fable, the project's own `conductor/code_styleguides/data_oriented_design.md`, and the superpowers plugin's `using-superpowers` skill. Likely OUT OF SCOPE for v3 (it would be its own followup); flagged here for awareness.
+
+---
+
+## 4. Functional Requirements
+
+These are the "what v3 must produce" requirements.
+
+### 4.1 The 11 cluster sections (the meat)
+
+Each cluster gets one dedicated section in `nagent_review_v3_20260619.md`. Each section follows this template:
+
+```
+### §N. Cluster name (n commits)
+
+**Source:** <list of commit SHAs + paths>
+**One-liner:** <what this cluster adds>
+**Pattern(s) vs v2.3:** <which of v2.3's 14 patterns this extends/supersedes/introduces>
+**Manual Slop implications:** <what Manual Slop should consider doing>
+**Decision candidate:** <the decision.md entry, or "no candidate" with rationale>
+**Cross-refs:** <sibling review references, if any>
+**Source-read citations:** <file:line citations for the actual code>
+```
+
+The 11 clusters, in canonical order:
+
+| § | Cluster | Source | Pattern vs v2.3 |
+|---|---|---|---|
+| §1 | **Campaigns** | nagent `24cf16d`, `199a36b`, `f3ec090`, `c1d2cad`, `6443d70`, `7a7e242` | **NEW** (didn't exist at v2.3) |
+| §2 | **Conversation safety net** | nagent `38d3d4f`, `6426a67` | **NEW** |
+| §3 | **Hooks** | nagent `a4fb141` + both case studies | **NEW** (used by case studies) |
+| §4 | **Project-local roots** | nagent `54c8741`, `557dd39`, `0b9d1a2`, `023e23a` | **NEW pattern** (extends v2.3 §3 "conversations are editable state") |
+| §5 | **Provider expansion** | nagent `bdfa2a6`, `5075f6e`, `2edc7ee` | **UPDATE** (v2.3 had 5 providers; v3 has 6 + per-model context windows) |
+| §6 | **Delegation rewrite** | nagent `d56f0f0`, `65787a6`, `315fe9e` | **UPDATE** (v2.3 §9 "disposable sub-conversations" updated with recursion-bug fix + context-isolation rationale) |
+| §7 | **Robustness** | nagent `065168c`, `6b762da`, `12c35b7`, `49e07f3` | **UPDATE** (v2.3 §5 "the loop" extended with new failure modes) |
+| §8 | **Operating rules** | nagent `a1f0680` | **UPDATE** (v2.3 cited `data-oriented-design.md`; v3 deep-dives the Q9 expansion) |
+| §9 | **Case-study methodology** | both repos (cross-cutting) | **NEW** (the reusable abstraction Acton is iterating on) |
+| §10 | **PEP case study** | `macton/pep-copt` | **NEW** (deep-dive: 2.04× speedup, byte-identical output) |
+| §11 | **Collisions case study** | `macton/differentiable-collisions-optc` | **NEW** (deep-dive: 102× speedup, distance-tolerance contract) |
+
+### 4.2 Side artifacts (the supporting structure)
+
+#### 4.2.1 `nagent_review_v3_20260619.md` — the main review
+
+Structure:
+- **Frontmatter:** Title, Status, Date, Owner, Reading guide (mirrors v2.3 §0).
+- **§0 TL;DR:** 1-2 paragraphs summarizing v3's findings. The 11 clusters + the case studies in 200-300 words.
+- **§1 Reading guide + lineage note:** How to read v3 alongside v2.3. What changed. What's preserved.
+- **§2-12 The 11 clusters** (one section per cluster, per the §4.1 template).
+- **§13 Decisions:** Pointer to `decisions.md`.
+- **§14 Cross-references:** Pointer to the sibling reviews + the bridge doc.
+- **§15 References:** SHAs, URLs, file paths.
+
+Total target: 5,500-6,500 LOC (parity with v2.3's 4,969).
+
+#### 4.2.2 `comparison_table.md` — refreshed side-by-side
+
+Format: same as v2.3 (one row per cluster + one row per existing v2.3 pattern that v3 updates). Columns: nagent pattern | Manual Slop equivalent | Verdict (PARITY / PARTIAL / GAP / ARCH-DIFF / SUBSUMED) | Notes.
+
+Target: 30+ rows (11 v3 clusters + 14 v2.3 patterns updated + 5 sibling-review cross-refs).
+
+#### 4.2.3 `decisions.md` — refreshed candidate list
+
+Structure:
+- **Top section: v2.3 → v3 status mapping.** For each of v2.3's 16 candidates, mark: PROMOTE / SUPERSEDE / STILL-OPEN / WITHDRAW. Rationale for each.
+- **New candidates from v3 clusters.** ~10-14 new candidates from the new material. Each follows the v2.3 candidate template (Goal / Context / File:line citations / Cross-refs).
+- **Priority.** HIGH / MEDIUM / LOW per candidate.
+
+Target: 25-30 entries total.
+
+#### 4.2.4 `nagent_takeaways_v3_20260619.md` — the bridge doc
+
+Structure (mirrors `superpowers_review_20260619/spec.md` §3.5):
+1. **TL;DR** (1 paragraph): what v3 takeaways add over v2.3 takeaways.
+2. **Cross-reference table** (~10-15 rows): one row per v3 takeaway that touches a v2.3 candidate. Columns: v3 takeaway | v2.3 candidate | relationship (subsumes / extends / contradicts / independent).
+3. **The new v3 candidates** not in v2.3 (the ~10-14 from `decisions.md`): one paragraph each, with verdict evidence.
+4. **The v2.3 candidates v3 supersedes** (likely 2-5): one paragraph each, with rationale.
+5. **Sibling-review pointers:** fable_review, intent_dsl_survey, superpowers_review.
+
+Target: ~150 LOC.
+
+### 4.3 Cross-references (sibling reviews)
+
+v3's `nagent_takeaways_v3_20260619.md` cross-references:
+
+| Sibling | Reference point in v3 |
+|---|---|
+| `fable_review_20260617` | Inline §8 (operating rules) + the bridge doc. |
+| `intent_dsl_survey_20260612` | Inline §9 (case-study methodology) + the bridge doc. |
+| `superpowers_review_20260619` | Inline §9 (case-study methodology, process parallel) + the bridge doc. |
+
+Per the superpowers_review spec §3 template, each cluster section that touches a sibling ends with a `Cross-refs:` line citing the relevant section.
+
+---
+
+## 5. Non-Functional Requirements
+
+These are the "what shape v3 must take" requirements.
+
+### 5.1 Format commitment (5 commitments)
+
+v3 reaffirms v2.3's 4 commitments and adds 1 new:
+
+| # | Commitment | Source |
+|---|---|---|
+| 1 | 7-column tables: Symbol \| Name \| Signature \| Semantics \| Example \| Borrowed from \| Shape | v2.3 §4.4 |
+| 2 | No JSON code blocks (JSON → tables) | v2.3 §4.4 |
+| 3 | SSDL shape tags (`{ssdl}` markers) | v2.3 §4.4 |
+| 4 | Survey grammar primitives in code examples (`name := value`, `for x .. n`, `if cond { ... }`, `tape { ... }`, `try { ... } recover { ... }`, `sandbox { ... }`, `audit msg`, `fuzzy { ... }`) | v2.3 §4.4 |
+| 5 | **NEW: Source-read citation discipline** — every cluster section cites ≥3 source paths (commit SHA + path:line, OR `prompts/*.md` line range, OR `bin/*.py` line range). No claim is grounded in commit subjects alone. | v2.1 preamble, hardened for v3 |
+
+### 5.2 Authoring tier + discipline
+
+- **Tier:** Tier 1 Orchestrator sole-authored (no Tier 3 dispatch).
+- **Per-cluster authoring shape:** 5-step pass — (1) source read of the cluster's commits + any referenced files, (2) pattern identification vs. v2.3's 14 patterns, (3) Manual Slop implications, (4) candidate entry into `decisions.md`, (5) cross-references to sibling reviews where applicable.
+- **Phase structure:** 14 phases (per §3 of the v3 plan, produced by writing-plans after this spec is approved).
+- **Commits:** one commit per cluster phase. Atomic rollback per cluster. Git notes attached to each. Per-task commit SHAs recorded in `state.toml`.
+
+### 5.3 Filename convention
+
+- Spec: `conductor/tracks/nagent_review_20260608/spec_v3.md` (this file).
+- Plan: `conductor/tracks/nagent_review_20260608/plan_v3.md` (produced by writing-plans).
+- Main review: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md`.
+- Bridge doc: `conductor/tracks/nagent_review_20260608/nagent_takeaways_v3_20260619.md`.
+- `comparison_table.md` + `decisions.md`: refreshed in place (no version-suffix).
+- Date convention: `20260619` (the day the source state was captured, matching v2.3's `20260612` filename pattern). **Open question for user review:** is `20260619` the right date, or should v3 use today's date (`20260620`)?
+
+### 5.4 Track-state hygiene
+
+- `metadata.json` refreshed in place (v3 fields).
+- `state.toml` updated as phases complete (one entry per phase).
+- `conductor/tracks.md` NOT modified (per the "B. Same track" decision).
+- Git notes attached to every phase commit.
+
+---
+
+## 6. Architecture Reference
+
+### 6.1 Existing project docs v3 depends on
+
+- `conductor/tracks/nagent_review_20260608/spec.md` — the v2.3 spec. The "what we knew on 2026-06-08" reference.
+- `conductor/tracks/nagent_review_20260608/nagent_review_v2_3_20260612.md` — the v2.3 canonical review.
+- `conductor/tracks/nagent_review_20260608/comparison_table.md` — the v2.3 comparison table (will be REPLACED).
+- `conductor/tracks/nagent_review_20260608/decisions.md` — the v2.3 candidates (will be REPLACED).
+- `conductor/tracks/nagent_review_20260608/nagent_takeaways_20260608.md` — the v2.3-era bridge doc (KEEP, unchanged).
+- `conductor/code_styleguides/data_oriented_design.md` — the project's canonical DOD reference, itself derived from Acton's `context/data-oriented-design.md`. v3's §8 (Operating rules) cluster ties back to this.
+- `conductor/code_styleguides/cache_friendly_context.md` — references `nagent_review_v2_3_20260612.md` §3.2 + §5. v3 updates the references if §3/§5 change in v3.
+- `conductor/code_styleguides/knowledge_artifacts.md` — references `nagent_review_v2_3_20260612.md` §3.1 + §4. v3 updates the references.
+- `conductor/code_styleguides/agent_memory_dimensions.md` — references `nagent_review_v2_3_20260612.md` §2.8. v3 updates the references.
+- `docs/guide_meta_boundary.md` — the Application vs Meta-Tooling distinction. Load-bearing context for v3 (mirrors v2.3 §2).
+- `conductor/workflow.md` — the workflow conventions v3 follows (TDD, per-task commits, format commitments).
+- `conductor/product-guidelines.md` — the project styleguides v3 follows (1-space indent for Python; markdown is not subject to this rule).
+
+### 6.2 Sibling reviews v3 cross-references
+
+- `conductor/tracks/fable_review_20260617/` — the Fable system prompt review. v3's §8 (Operating rules) cross-refs Fable's analysis of the Mythos system prompt.
+- `conductor/tracks/intent_dsl_survey_20260612/` — the intent-DSL survey. v3's §9 (Case-study methodology) cross-refs the survey's clusters.
+- `conductor/tracks/superpowers_review_20260619/` — the superpowers plugin review (in plan phase as of 2026-06-19). v3's §9 cross-refs the superpowers `brainstorming` skill as a process parallel.
+
+### 6.3 External sources v3 reviews
+
+- `macton/nagent` at commit `a1f0680` (2026-06-18 23:51:28 UTC) — https://github.com/macton/nagent
+- `macton/nagent` at commit `eb6be32a` (2026-06-12 00:25:50 UTC) — the v2.3 baseline.
+- `macton/pep-copt` at `main` (5 commits) — https://github.com/macton/pep-copt
+- `macton/differentiable-collisions-optc` at `main` (5 commits) — https://github.com/macton/differentiable-collisions-optc
+
+---
+
+## 7. Verification Criteria
+
+These are the "definition of done" for v3. The `metadata.json` `verification_criteria` field will contain:
+
+1. **Coverage.** All 11 clusters present in `nagent_review_v3_20260619.md`, each as a dedicated section (no merge, no drop). Verified by table-of-contents check.
+2. **Source-read citations.** Every cluster section cites ≥3 source paths (commit SHA + path:line, OR `prompts/*.md` line range, OR `bin/*.py` line range). No claim is grounded in commit subjects alone. Verified by grep for the citation pattern.
+3. **Case-study evidence.** Clusters 9, 10, 11 cite the actual `prompts/create-*.md`, `OPTIMIZATION-LOG.md`, and `prove-optimized-harness.sh` content (not paraphrases of the READMEs). Verified by content-presence check.
+4. **Format commitment.** All 5 commitments verified by grep:
+   - No JSON blocks in main review (` ```json ` absent in `nagent_review_v3_20260619.md`).
+   - 7-column tables present in `comparison_table.md` (a row beginning with `| Symbol |` is found).
+   - SSDL shape tags present (`{ssdl}` markers appear in code examples).
+   - Survey grammar used in code examples (at least one of: `name := value`, `for x .. n`, `tape { ... }`, `try { ... } recover { ... }`, `sandbox { ... }`, `audit msg`, `fuzzy { ... }`).
+   - Source-read citations present (per cluster, at least 3 of: a 7+-char commit SHA reference, a `path/to/file.py:L[0-9]+` reference, a `prompts/[a-z_-]+.md` reference, a `bin/[a-z_-]+` reference, or an OPTIMIZATION-LOG / harness script reference).
+5. **decisions.md candidates.** ~25-30 entries (v2.3's 16 + v3's new ~10-14). Top of file includes v2.3 → v3 status mapping. Verified by line count + manual inspection of the status mapping.
+6. **nagent_takeaways_v3 bridge.** 5-part structure present: TL;DR + cross-reference table + new v3 takeaways + v2.3-superseded + sibling-review pointer. Verified by section-heading check.
+7. **Track artifacts.** `spec_v3.md` (this file) + `plan_v3.md` (produced by writing-plans) committed; `metadata.json` refreshed; `state.toml` updated as phases complete; `conductor/tracks.md` not modified.
+8. **Commits.** One commit per cluster phase; git notes attached per task; per-task commit SHAs recorded in `state.toml`.
+
+A v3 `verification_criteria_audit.sh` script (added to `scripts/` if v3 surfaces a need; otherwise inline grep checks) will enforce #4 mechanically. The other 7 are verified manually by reading.
+
+---
+
+## 8. Out of Scope
+
+v3 explicitly does NOT do the following (each is a potential followup track):
+
+- **Implement the candidates.** `decisions.md` lists candidates; the user's deferred Manual Slop rebuild consumes them. v3 is research-only.
+- **Replace v2.3.** v2.3 stands as historical. v3 supersedes it for the canonical going forward but does not delete it.
+- **Deep-dive the Fable system prompt.** That's `fable_review_20260617`. v3 cross-refs it.
+- **Review the superpowers plugin.** That's `superpowers_review_20260619`. v3 cross-refs it.
+- **Survey intent-based DSLs.** That's `intent_dsl_survey_20260612`. v3 cross-refs it.
+- **Synthesize across the four review corpora.** A potential future track (cross-review synthesis). v3 sets up the cross-refs but does not do the synthesis.
+- **Commit any of the case-study `prompts/*.md` files to this repo.** The case-study repos are external; their content is referenced by URL, not committed locally.
+- **Modify any project source code** (`src/*.py`, `tests/*.py`, `conductor/*.md`, `.opencode/*`, `AGENTS.md`). v3 is research-only.
+- **Tier 3 dispatch.** Tier 1 sole-authored, mirroring v2.3 and `fable_review_20260617`.
+
+---
+
+## 9. See Also
+
+### 9.1 In this track directory
+
+- `spec.md` — the v2.3 spec. The "what we knew on 2026-06-08" reference. v3 sits alongside it.
+- `plan.md` — the v2.3 plan. v3's plan (`plan_v3.md`) sits alongside it.
+- `nagent_review_v2_3_20260612.md` — the v2.3 canonical review. v3 supersedes it.
+- `nagent_review_v2_20260612.md` — the v2 review.
+- `nagent_review_v2_1_20260612.md` — the v2.1 delta (user-revised).
+- `nagent_review_v2_2_20260612.md` — the v2.2 delta (Tier 1-synthesized).
+- `report.md` — the original v1 review.
+- `comparison_table.md` — will be REPLACED by v3 content.
+- `decisions.md` — will be REPLACED by v3 content.
+- `nagent_takeaways_20260608.md` — the v2.3-era bridge doc. KEEP unchanged.
+
+### 9.2 Sibling reviews (cross-referenced in v3)
+
+- `conductor/tracks/fable_review_20260617/` — the Fable system prompt review.
+- `conductor/tracks/intent_dsl_survey_20260612/` — the intent-based DSL survey.
+- `conductor/tracks/superpowers_review_20260619/` — the superpowers plugin review.
+
+### 9.3 External sources
+
+- [`macton/nagent`](https://github.com/macton/nagent) at commit `a1f0680` (2026-06-18) — the v3 review baseline.
+- [`macton/pep-copt`](https://github.com/macton/pep-copt) at `main` — the PEP image compression case study.
+- [`macton/differentiable-collisions-optc`](https://github.com/macton/differentiable-collisions-optc) at `main` — the collision detection case study.
+
+### 9.4 Project docs
+
+- `conductor/workflow.md` — the workflow conventions v3 follows.
+- `conductor/product-guidelines.md` — the project styleguides v3 follows.
+- `conductor/code_styleguides/data_oriented_design.md` — the project's canonical DOD reference, itself derived from Acton's `context/data-oriented-design.md`.
+- `docs/guide_meta_boundary.md` — the Application vs Meta-Tooling distinction (load-bearing context for the verdict structure).