# 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).