# nagent_review_v3 — Bridge to v2.3 + sibling reviews

**Date:** 2026-06-19
**Spec pair:** `spec_v3.md` + `plan_v3.md`
**Companions:**
- `nagent_takeaways_20260608.md` — the v2.3-era takeaways (10 actionable patterns; unchanged).
- `nagent_review_v3_20260619.md` — the v3 canonical review (11 cluster sections).
- `comparison_table.md` — the v3 cluster table.
- `decisions.md` — the v3 candidate list (11 new + 16 v2.3 status mapping).

**Sibling reviews:**
- `fable_review_20260617` — Fable's analysis of Mythos system prompt
- `intent_dsl_survey_20260612` — survey's 10 prior-art clusters for intent-based DSLs
- `superpowers_review_20260619` — superpowers plugin review

---

## 1. TL;DR

v3 takeaways add **three first-class subsystems** (Campaigns, Conversation safety net, Hooks), **one new provider** (Together), **one delegation bug fix** (recursion), **eight expanded pattern areas** (Operating rules Q9, Robustness 4 hardening commits, Provider expansion per-model context windows, etc.), and **two end-to-end case studies** (PEP 2.04× byte-identity-strict, Collisions 101.06× tolerance-based) that demonstrate the methodology in production. The case-study methodology itself (§9) is the new abstraction: 5-element pattern (prompts + harness + log + freeze + subject) with a parameterizable match contract. The Operating rules §8 gain the Q9 expansion ("consider a different machine when filing plateaus"). The Project-local roots §4 rename `nagent-gc` → `nagent-distill` (the operation refines, not collects). The v3 candidate pool is **21 entries** (11 new + 10 v2.3 STILL-OPEN).

---

## 2. Cross-reference table

| v3 takeaway | v2.3 candidate | Relationship |
|---|---|---|
| Campaigns (§1) as operable artifacts | (new in v3) | independent |
| Discussion-window safety net (§2) | (new in v3) | independent |
| Per-turn ground-truth hook (§3) | Candidate 5 (Self-describing MCP tools) | extends: hooks are a more general "per-turn ground-truth injection" surface |
| Project-local roots + 4-layer resolution (§4) | Candidate 14 (Project context files) | supersedes: the v2.3 pattern is a refinement of the v3 architectural refactor |
| Per-model token-cap awareness (§5) | Candidate 3 (Stateless LLMClient) | extends: the windows table is a refinement of the stateless client |
| Delegation rewrite: decompose-or-isolate (§6) | Candidate 1 (SubConversationRunner) | extends: the recursion bug + two-reason framing tighten the contract |
| Robustness: 4 hardening commits (§7) | (new in v3) | independent |
| Operating rules Q9: different machine (§8) | Candidate 16 (AGENTS.md @import + canonical DOD) | extends: Q9 is a v3 refinement of the canonical DOD |
| Case-study methodology: 5-element pattern (§9) | (new in v3) | independent |
| PEP case study: 2.04× byte-identity (§10) | (empirical evidence, not candidate) | independent |
| Collisions case study: 101.06× tolerance-based (§11) | (empirical evidence, not candidate) | independent |

---

## 3. The new v3 candidates (not in v2.3)

These are the v3-only candidates — see `decisions.md` for the full entry per candidate.

### Candidate 17: Campaign-style plan-as-data for the conductor

The conductor's `plan.md` is not operable today — the model's "what to do next" is re-made every turn. v3 §1 introduces campaigns as a four-piece composition (artifact + driver + invariants + context surfaces) with four load-bearing invariants: **one pass then exit; one writer for the tree; review gate not cap; schema is the whole schema**. Making the conductor's plan operable is the same data-oriented move. **HIGH priority.**

### Candidate 18: Discussion-window safety net for Manual Slop

v3 §2 introduces a four-piece composition (trigger + writer + rebuild + provenance) with the critical invariant: rebuild runs a synchronous checkpoint first, and the writer's failure widens the tail instead of blocking. The 3-number config (`checkpoint_interval_minutes`, `checkpoint_max_new_kb`, `rebuild_at_kb`) is a model Manual Slop should follow. Long-running discussions currently grow unbounded; the rebuild trigger is a structural fix. **HIGH priority.**

### Candidate 19: Per-turn ground-truth hook for Manual Slop

v3 §3 introduces hooks as a three-piece composition (resolve + invoke + inject). The case-study harness scripts ARE the hooks: `prove-optimized-harness.sh` is the command wired into `--hook-per-run`. The model responds against measured state instead of its recollection. **MEDIUM priority.**

### Candidate 20: Rename `nagent-gc` → `nagent-distill` in our documentation cross-references

v3 §4 renames `nagent-gc` to `nagent-distill` (no compatibility alias). The new name encodes the operation's true semantic: knowledge becomes capability, gated by review. The merge/graduate passes are an explicit consequence. **LOW priority (docs only).**

### Candidate 21: Per-model token-cap awareness for Manual Slop `ai_client`

v3 §5 introduces the verified-windows table (10 models verified against the Together API). Unknown models return `None` and fall back to byte-only behavior — not a guessed default. The 0.85 safety fraction is the data-oriented response to "model capability degrades under high context utilization, not just at the limit." **MEDIUM priority.**

### Candidate 22: Tier 3 worker contract "decompose or isolate, never offload"

v3 §6 fixes a recursion bug (file-edit agent → worker → nagent-file-edit → file-edit agent → ... hangs the tree) by naming the two reasons delegation is worth its cost: **decomposition** (the task is genuinely complex, with parts) and **context isolation** (the step is noisy, the result is small). "Don't offload a single small action whose result is no smaller than doing it yourself." The 315fe9e test-fix is also a useful precedent: agent's `test_*.py` for any user-facing prompt change must run the suite, not just `py_compile`. **HIGH priority.**

### Candidate 23: Per-conversation scratch directory for Manual Slop dispatch_inference

v3 §7 introduces the per-conversation scratch dir as a hardening commit (`49e07f3`). Each instance gets its own directory keyed by conversation name; concurrent instances never collide in a shared `/tmp`. **MEDIUM priority.**

### Candidate 24: Document Q9 ("consider a different machine") in the project's `conductor/code_styleguides/data_oriented_design.md`

v3 §8 surfaces the Q9 expansion (the only addition since v2.3). Q9 generalizes the simplification pass from "trim the current machine" to "consider a different machine when the data's shape points to it." **LOW priority (docs only).**

### Candidate 25: Optimization-log discipline for Manual Slop agent work

v3 §9 surfaces the case-study methodology's 5-element pattern; the `OPTIMIZATION-LOG.md` is the per-hypothesis history file. Both case studies document rejected experiments with measurements; the methodology's data discipline is load-bearing. **MEDIUM priority.**

### Candidate 26: `OPTIMIZATION-LOG` schema for Manual Slop agent work

The schema is portable; Manual Slop agents could adopt it for any multi-iteration optimization. Sub-pattern of Candidate 25. **LOW priority.**

### Candidate 27: Tolerance-based comparator for Manual Slop agent work

v3 §11 documents the collisions case study's tolerance-based match contract. The comparator pattern is reusable; Manual Slop's `RAGEngine._chunk_code` and other float-based work could adopt it. **MEDIUM priority.**

---

## 4. The v2.3 candidates v3 supersedes

Of the 16 v2.3 candidates, v3 supersedes **1** (Candidate 5, Self-describing MCP tools — subsumed by the v3 hooks pattern + `mcp_architecture_refactor_20260606`) and **promotes 1** (Candidate 11, Knowledge harvest — the v3 rename to `nagent-distill` + merge/graduate passes is the data-grounded refinement).

The remaining 14 v2.3 candidates remain **STILL-OPEN** per `decisions.md` §"v2.3 → v3 candidate status mapping." The v3 doesn't invalidate them; it adds new patterns that are orthogonal to most of the v2.3 candidates.

---

## 5. Sibling-review pointers

### `fable_review_20260617` — Fable's analysis of Mythos system prompt

The Fable review analyzes the Mythos system prompt's "watch-dogging" pattern (be careful, watch yourself, never claim something you can't verify). v3 §8 is the data-oriented response: Acton's operating rules ("sampling can justify replacing the machine") are the data-grounded alternative to persona-based caution. Fable's anti-pattern (mental-health watch-dogging, refusal framing) is the opposite of nagent's pattern (sample the data, replace the machine). The two reviews together surface the philosophical difference between persona-based safety and data-grounded safety. Touchpoints: v3 §8 (Operating rules) + the project styleguide's Q9 candidate (Candidate 24).

### `intent_dsl_survey_20260612` — survey's 10 prior-art clusters

The survey's Cluster 4 ("Meta-Tooling DSLs") is the closest prior art to v3 §9's case-study methodology (the 4 prompts ARE an intent-DSL for "drive nagent at an optimization problem"). The survey's Cluster 3 ("intent-mapping") is the philosophical anchor: mapping user intent to tool invocations is what DSLs do, and nagent's prompts are a primitive form of that mapping. Touchpoints: v3 §9 (Case-study methodology) + §10 + §11.

### `superpowers_review_20260619` — superpowers plugin review

The superpowers `brainstorming` skill asks structured questions to refine an idea before implementation; the case-study 4 prompts serve the same role. Both encode "the model should not skip the early work." Touchpoints: v3 §9 (Case-study methodology).

---

## What v3 takeaways ADD over v2.3 takeaways

The v2.3 takeaways (`nagent_takeaways_20260608.md`) are 10 actionable patterns. v3 adds:

1. **3 first-class subsystems** (Campaigns, Safety net, Hooks) — each is a coherent module with its own invariant set
2. **1 new provider** (Together) with per-model context windows as a new precision layer
3. **1 delegation bug fix** (recursion) with a documented test-fix precedent
4. **8 expanded pattern areas** — Operating rules Q9, Robustness 4 hardening commits, Provider expansion, etc.
5. **2 case studies** demonstrating the methodology in production (PEP, Collisions)
6. **1 new abstraction** (case-study methodology, §9) — the 5-element pattern with parameterizable match contract
7. **1 rename with semantic shift** (`nagent-gc` → `nagent-distill`)
8. **11 new candidates** for Manual Slop follow-up tracks (3 HIGH, 4 MEDIUM, 4 LOW)

The v2.3 takeaways are not invalidated; they are a foundation v3 builds on. Read both: v2.3 for the durable principles, v3 for the empirical demonstration.