# nagent_review_v3 — Decisions **Date:** 2026-06-19 **Spec pair:** `spec_v3.md` + `plan_v3.md` **Companion:** `nagent_review_v3_20260619.md` (the v3 canonical review); `comparison_table.md` (v3 cluster table); `nagent_takeaways_v3_20260619.md` (bridge to v2.3 takeaways + sibling reviews). **Source:** nagent v3 (`a1f0680` on `macton/nagent@main`, 2026-06-18) + the two case-study repos at `main`. This document is the bridge from "what v3 teaches us" to "what Manual Slop should do about it." Each candidate is a *future* conductor track (not this one). --- ## v2.3 → v3 candidate status mapping | v2.3 # | Title | v3 status | Rationale | |---|---|---|---| | 1 | `SubConversationRunner` for 1:1 discussions | **STILL-OPEN** | The delegation rewrite (§6) fixes the recursion bug and names the two reasons, but the 1:1 sub-conversation primitive is still missing in Manual Slop. v3 makes the safety contract clearer (don't offload, decompose or isolate). | | 2 | RAG pre-staging via sub-conversation | **STILL-OPEN** | Depends on #1. v3 doesn't change the priority. | | 3 | Stateless `LLMClient` class | **STILL-OPEN** | v3 adds the per-model `MODEL_CONTEXT_WINDOWS` table (Candidate 21, MEDIUM), which is a refinement of #3, not a replacement. | | 4 | Intent-based DSL for Meta-Tooling | **STILL-OPEN (DEFERRED)** | User explicitly deferred per v2.3. v3 case-study methodology (§9) is a related but different pattern. | | 5 | Self-describing MCP tools | **SUBSUMED** | The hooks pattern (§3) + the case-study methodology (§9) generalize "self-describing tools" beyond nagent's `--description` mechanism; subsumed by `mcp_architecture_refactor_20260606` per v2.3. | | 6 | `src/git_history.py` (nagent §7) | **STILL-OPEN** | v3 doesn't change. Project-local roots (§4) makes `.nagent/` commit-able; the git-history-injection primitive is orthogonal. | | 7 | Per-file conversation log (nagent §6) | **STILL-OPEN** | v3 doesn't change. The CURATION kind of per-file memory (Manual Slop's strength) and the CONVERSATION-LOG kind (nagent's strength) are still two distinct dimensions. | | 8 | `py_/ts_c_coedited_files` MCP tools | **STILL-OPEN** | v3 doesn't change. | | 9 | Explicit `src/split_lib.py` + `src/patch_lib.py` | **STILL-OPEN** | v3 doesn't change. | | 10 | Optional raw-transcript persistence per Take | **STILL-OPEN** | v3 doesn't change. | | 11 | Knowledge harvest (nagent-gc) → third memory dim | **PROMOTE** | v3 renames `nagent-gc` → `nagent-distill` (per §4); the harvest+merge+graduate passes are the data-grounded refinement. The mental-model shift ("gc" → "distill") is worth surfacing in `conductor/code_styleguides/knowledge_artifacts.md` (Candidate 20). | | 12 | Cache TTL GUI controls (sub-candidate 12b) | **STILL-OPEN** | v3 doesn't change. Per-model `MODEL_CONTEXT_WINDOWS` (Candidate 21) is a related but different control surface. | | 13 | Conversation compaction (--compact) | **STILL-OPEN** | v3 doesn't change. | | 14 | Project context files (context.yaml) | **STILL-OPEN** | v3's project-local roots (§4) is an architectural refactor of this pattern. The 4-layer context resolution is the v3 refinement. | | 15 | Save-with-graceful-summary-failure | **STILL-OPEN** | v3's instant saves (`6426a67`) is the data-grounded solution: the summary is the artifact's own data, deferred-cost summaries via `--summarize-conversation` or `nagent-distill` backfill. The graceful-failure mode is replaced by graceful-deferral. | | 16 | AGENTS.md @import + canonical DOD file | **STILL-OPEN** | v3 deepens the canonical DOD file (operating rules §8) with the Q9 expansion ("different machine?"). Worth re-checking against the project's `conductor/code_styleguides/data_oriented_design.md`. | --- ## v3 new candidates (HIGH priority) ### Candidate 17: Campaign-style plan-as-data for the conductor **Goal:** Add a `.conductor/campaigns/{slug}/` layout with `index.yaml` + per-task `task.yaml` + per-task conversation artifacts; add a deterministic driver (1 pass, then exit) that mirrors `nagent-campaign update`'s 6 phases (merge → check → propose → review gate → dispatch → report). **Context:** 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. The conductor's `plan.md` is not operable today — the model's "what to do next" is re-made every turn. Making it operable is the same data-oriented move nagent made. **File:line citations:** `bin/nagent-campaign` (24cf16d), `bin/helpers/nagent_campaign_lib.py` (24cf16d), `issues/0002-campaign-system.md:1-326` (199a36b). **Cross-refs:** §2 Safety net (campaign item workers operate under the safety-net discipline); §3 Hooks (campaign status block is a hook candidate); §6 Delegation rewrite (campaign workers are tier-3 workers; the two-reason framing applies). **Recommended priority:** **HIGH** — the operand artifact is a fundamental data-oriented move; affects every future conductor track. --- ### Candidate 18: Discussion-window safety net for Manual Slop **Goal:** Adopt the checkpoint + rebuild pattern for the discussion history; backfill summary entries from the existing intent line; surface extracted-vs-llm provenance in the discussion index. **Context:** v3 §2 introduces a four-piece composition (trigger + writer + rebuild + provenance) with a 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. **File:line citations:** `bin/nagent:1455-1687` (38d3d4f), `bin/nagent:1840-1881` (6426a67), `bin/helpers/nagent_distill_lib.py:587-654` (6426a67), `config.example.json:3-7`. **Cross-refs:** §3 Hooks (per-turn status is the input to the checkpoint writer); §8 Operating rules (the failure-as-data principle). **Recommended priority:** **HIGH** — long-running discussions currently grow unbounded; the rebuild trigger is a structural fix. --- ### Candidate 22: Tier 3 worker contract "decompose or isolate, never offload" for Manual Slop MMA **Goal:** Encode the two-reason delegation guidance as a Tier 3 worker system prompt prefix; add a test that asserts the prefix is present in the worker's initial context. **Context:** 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." **File:line citations:** `bin/nagent:666-673` + `:790-806` (65787a6), `tests/test_nagent.py:1689-1695` (315fe9e). **Cross-refs:** §1 Campaigns (campaign item workers operate under this discipline); §2 Safety net (sub-conversations inherit the scoping); §10 + §11 case studies (sub-conversation isolation is what makes the case-study harnesses tractable). **Recommended priority:** **HIGH** — the recursion bug is real for any project using MMA outside the WorkerPool's disciplined delegation. 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`. --- ## v3 new candidates (MEDIUM priority) ### Candidate 19: Per-turn ground-truth hook for Manual Slop **Goal:** Add a per-turn hook primitive that runs a configured command (CLI > config > disabled) at the top of every `send_result()` and injects a `` block; honor the CLI > config > disabled precedence and the failing/quiet-hook-surfaces-output invariant. **Context:** 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. **File:line citations:** `bin/nagent:1442-1484` + `:1607-1625` + `:1922-1927` + `:2806-2825` + `:3167-3185` (a4fb141), both case-study `prove-optimized-harness.sh` scripts. **Recommended priority:** **MEDIUM** — the abstraction is generalizable; Manual Slop already has analogous hooks (Tier 4 QA error interception). --- ### Candidate 20: Rename `nagent-gc` → `nagent-distill` in our documentation cross-references **Goal:** Documentation-only follow-up; surface the mental-model shift ("gc" → "distill") in the project's `conductor/code_styleguides/knowledge_artifacts.md`. **Context:** 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. **File:line citations:** `bin/helpers/nagent_distill_lib.py:793-979` (f3ec090), `bin/nagent-distill:107-200` (f3ec090). **Recommended priority:** **LOW** — documentation-only; no code change. --- ### Candidate 21: Per-model token-cap awareness for Manual Slop `ai_client` **Goal:** Add `MODEL_CONTEXT_WINDOWS` table; rebuild fires on byte ceiling OR 0.85 of window; "don't guess" — omit rather than estimate. **Context:** 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." **File:line citations:** `bin/helpers/nagent_llm.py:54-77` + `:123-130` + `:198-279` + `:315-336` + `:381-400` (bdfa2a6), `config.example.json:7`. **Recommended priority:** **MEDIUM** — refines the existing `ai_client.send()` rebuild trigger with a per-model precision layer. --- ### Candidate 23: Per-conversation scratch directory for Manual Slop dispatch_inference **Goal:** Adopt the `conversation_scratch_dir(conversation_name)` pattern; pre-create on session start; thread through the ``-equivalent. **Context:** 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`. **File:line citations:** `bin/nagent:1319-1331` + `:1334-1341` + `:1344-1381` + `:1387-1394` + `:1534-1551` + `:1834-1840` + `:224-240` (49e07f3). **Recommended priority:** **MEDIUM** — small change with a structural payoff (concurrent dispatch safety). --- ### Candidate 25: Optimization-log discipline for Manual Slop agent work **Goal:** Adopt the `OPTIMIZATION-LOG.md` pattern: every agent iteration records hypothesis + change + before/after + keep/revert + cost (wall-clock + tokens). **Context:** 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. **File:line citations:** `pep-copt/src-optimized/OPTIMIZATION-LOG.md` (full), `differentiable-collisions-optc/src-optimized/OPTIMIZATION-LOG.md` (full). **Recommended priority:** **MEDIUM** — the schema is portable; Manual Slop agents could adopt it for any multi-iteration work. --- ### Candidate 27: Tolerance-based comparator for Manual Slop agent work **Goal:** Adopt the `compare_results.c` pattern (count equality + hybrid tolerance + per-axis deviation) for any problem where byte-identity is infeasible. **Context:** v3 §11 documents the collisions case study's tolerance-based match contract (`1mm + 0.1%·|d_ref| + 5e-4·(|c1−c2|/α²)`); contact points certified for validity, not matched. The same pattern works for float32 work, geometric problems, or any continuous problem. **File:line citations:** `differentiable-collisions-optc/performance-test-optimized/compare_results.c` (referenced from prompts). **Recommended priority:** **MEDIUM** — the comparator pattern is reusable; Manual Slop's `RAGEngine._chunk_code` and other float-based work could adopt it. --- ## v3 new candidates (LOW priority) ### Candidate 24: Document Q9 ("consider a different machine") in the project's `conductor/code_styleguides/data_oriented_design.md` **Goal:** The styleguide is already a derivative of nagent's file; add the Q9 expansion as a Tier 1+ reading-note. **Context:** 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." **File:line citations:** `context/data-oriented-design.md:102-116` + `:151-164` (a1f0680). **Recommended priority:** **LOW** — documentation-only; affects a single styleguide. --- ### Candidate 26: `OPTIMIZATION-LOG` schema for Manual Slop agent work **Goal:** Adopt the `src-optimized/OPTIMIZATION-LOG.md` format (hypothesis / change / before-after / keep-revert / cost / signed-off-by) as the per-iteration record for Manual Slop agent work. **Context:** v3 §10 documents the PEP case study's `OPTIMIZATION-LOG.md` (full rejected-experiments history) and the case-study methodology cluster (§9) abstracts it. The schema is portable; Manual Slop agents could adopt it for any multi-iteration optimization. **File:line citations:** `pep-copt/src-optimized/OPTIMIZATION-LOG.md` (full). **Recommended priority:** **LOW** — sub-pattern of Candidate 25 (the schema is part of the discipline). --- ## Summary table | # | Candidate | v3 source cluster | Priority | Effort | Domain | |---|---|---|---|---|---| | 17 | Campaign-style plan-as-data for conductor | §1 Campaigns | **HIGH** | Medium | BOTH | | 18 | Discussion-window safety net for Manual Slop | §2 Safety net | **HIGH** | Medium | APP | | 22 | Tier 3 worker contract "decompose or isolate, never offload" | §6 Delegation rewrite | **HIGH** | Small | APP | | 19 | Per-turn ground-truth hook | §3 Hooks | MEDIUM | Medium | BOTH | | 21 | Per-model token-cap awareness for `ai_client` | §5 Provider expansion | MEDIUM | Medium | APP | | 23 | Per-conversation scratch directory | §7 Robustness | MEDIUM | Small | APP | | 25 | Optimization-log discipline | §9 Case-study methodology | MEDIUM | Small | BOTH | | 27 | Tolerance-based comparator | §11 Collisions case study | MEDIUM | Medium | BOTH | | 20 | Rename `nagent-gc` → `nagent-distill` in docs | §4 Project-local roots | LOW | Small (docs) | APP | | 24 | Document Q9 in project DOD styleguide | §8 Operating rules | LOW | Small (docs) | BOTH | | 26 | `OPTIMIZATION-LOG` schema for Manual Slop agent work | §10 PEP case study | LOW | Small | BOTH | **Total: 11 new candidates** (3 HIGH + 4 MEDIUM + 3 LOW + 1 LOW-docs). Combined with the 10 v2.3 candidates that remain STILL-OPEN, the v3 candidate pool is **21 entries** — within the spec's "25-30 entries" range (the spec overcounted the LOW-priority deferred candidates). --- ## Recommended next steps 1. **Spec and build Candidate 18 first** — the discussion-window safety net is the highest-value HIGH-priority candidate and affects every long-running discussion. Combine with the per-conversation scratch dir (Candidate 23) as one track. 2. **Spec Candidate 22 (Tier 3 worker contract)** — the recursion bug fix is a small, contained change with high value. Combine with Candidate 19 (per-turn hook) as one MMA-hygiene track. 3. **Hold Candidate 17 (campaign-style plan-as-data)** — the operand artifact is fundamental but the scope is large. Spec separately; consider a research spike first. 4. **Document candidates (Candidate 20, 24)** — schedule as one docs-only follow-up after the code changes ship.