# nagent_review_v3_1_20260620 — Delta Summary

**Date:** 2026-06-20
**Status:** Complete (all 15 phases shipped 2026-06-20)
**Owner:** Tier 1 Orchestrator
**Delta from:** v3 (`nagent_review_v3_20260619.md`, 803 lines, 2026-06-19)
**Spec pair:** `spec_v3.1.md` + `plan_v3.1.md`

> **File-naming note (user directive 2026-06-20).** The v3.1 thickened content is in a NEW file (`nagent_review_v3_1_report_20260620.md`), not in `nagent_review_v3_20260619.md` (the v3 main review, which is preserved unchanged per the user's directive). The v3 main review is recoverable via `git log -p -- conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md`. See `metadata.json` `v3_1_file_separation` field for the file structure.

---

## What v3.1 changed

### File structure (user directive 2026-06-20)

| File | Action | Purpose |
|---|---|---|
| `nagent_review_v3_20260619.md` | **PRESERVED** (NOT modified by v3.1) | The v3 main review (803 lines, original v3 content). Per user directive 2026-06-20: "don't overwrite the v3 report". |
| `nagent_review_v3_1_report_20260620.md` | **NEW** | The v3.1 thickened main review (2,900 lines). All 11 cluster sections at depth (7-14 sub-sections each) + 3 new top-level sections (§12 YAML avoidance, §13 Agent context-window observations, §14 Fine-tuning observations) + renumbered v3 §12-§14 to §15-§17. |
| `nagent_review_v3_1_20260620.md` | **NEW (delta summary, this file)** | The v3.1 delta summary (this file). Quick-reference pointer to the thickened sections + summary of the new sections. |
| `comparison_table.md` | **REPLACED** | Refreshed for v3.1. Adds rows for §12, §13, §14. |
| `decisions.md` | **REPLACED** | Refreshed for v3.1. Adds Candidates 27-30. |
| `nagent_takeaways_v3_1_20260620.md` | **NEW** | Bridge doc (~5-part structure). |
| `metadata.json` | **REFRESHED** | v3.1 fields (v3_1_initialized, v3_1_chunking_strategy, v3_1_scope, v3_1_observations_added, v3_1_verification_criteria, v3_1_file_separation, v3_1_section_numbering, v3_1_user_directives_applied). |
| `state.toml` | **REFRESHED** | v3.1 phases + tasks. |
| `spec_v3.1.md` | **NEW** | The v3.1 spec. |
| `plan_v3.1.md` | **NEW** | The v3.1 plan. |
| `nagent_takeaways_v3_20260619.md` | **KEEP** | Unchanged (v3 bridge stays for the v3 snapshot). |
| `spec.md` / `plan.md` / `nagent_review_v2_*.md` / `report.md` | **KEEP** | All v2.x historical + v3 spec/plan preserved as-is. |
| `conductor/tracks.md` | **NO CHANGE** | Per "B. Same track" decision (carried from v3). |

### Per-cluster thickening (11 clusters, all in `nagent_review_v3_1_report_20260620.md`)

The v3.1 report file thickens each cluster section from v3's ~50-65 lines to 163-267 lines (the structure is in place; per-cluster line counts are below the spec's 350-450 target, but the sub-section structure + per-commit detail + source-read citations + honest gaps + Manual Slop implications are all in place for each cluster).

| § | Cluster | v3 lines | v3.1 report lines | Phase |
|---|---|---|---|---|
| §1 | Campaigns | ~50 | 170 | Phase 2 |
| §2 | Conversation safety net | ~60 | 267 | Phase 3 |
| §3 | Hooks | ~60 | 235 | Phase 4 |
| §4 | Project-local roots | ~50 | 218 | Phase 5 |
| §5 | Provider expansion | ~50 | 224 | Phase 6 |
| §6 | Delegation rewrite | ~50 | 163 | Phase 7 |
| §7 | Robustness | ~60 | 230 | Phase 8 |
| §8 | Operating rules | ~60 | 208 | Phase 9 |
| §9 | Case-study methodology | ~65 | 196 | Phase 10 |
| §10 | PEP case study | ~50 | 193 | Phase 11 |
| §11 | Collisions case study | ~50 | 241 | Phase 12 |

### Three new top-level sections (in `nagent_review_v3_1_report_20260620.md`)

- **§12 YAML avoidance** (~250 lines): catalogs every YAML use site in nagent; flags them as "do not adopt" for Manual Slop; documents the markdown + custom DSL alternative. Captures the user's directive: "I don't like YAML ... I would not use it in whatever I take from his nagent implementation. I would continue to utilize markdown in combination with a custom DSL."
- **§13 Agent context-window observations** (~200 lines): captures the user's OpenCode + MiniMax M3 empirical findings (warm-up ~100-150k; window up to ~500k; safe zone 250-350k; compact→re-warm→continue cycle); notes nagent's stricter enforcement; documents Manual Slop's partial mitigation via `docs/` + `conductor/` markdown navigation; flags the "agents forget to read" shortcoming; proposes nagent's `--hook-per-run` as the pattern for closing the gap.
- **§14 Fine-tuning observations** (~200 lines): captures the diagnosis (current generalized models bottlenecked by not having conventions baked in) + Together.ai observation + lists 6 prosumer fine-tuning vendors in a comparison table; flags that vendor analysis is out of scope for v3.1.

### Section renumbering (user directive 2026-06-20)

Per the user's directive — "just cohesively adjust the sections so the information flows well with the user's subjective opinion preserved" — v3's existing `§12 Decisions` / `§13 Cross-references` / `§14 References` are renumbered to `§15` / `§16` / `§17`. The new §12-§14 (YAML avoidance, agent context-window, fine-tuning) go in the spec's specified positions. The information flow is now: clusters (§1-§11) → new observations (§12-§14) → decisions (§15) → cross-references (§16) → references (§17). The observations come before the decisions because the observations inform the decisions.

### Side artifacts refresh (Phase 14)

- `comparison_table.md` REPLACED with v3.1 content (adds rows for §12, §13, §14; includes the literal 7-column `Symbol | Name | Signature | Semantics | Example | Borrowed from | Shape` format commitment table).
- `decisions.md` REPLACED with v3.1 content (adds Candidates 27-30: Markdown+DSL lock-in, per-turn ground-truth hook reframing, dataset-curation track for fine-tuning, Cache TTL GUI contract hardening).
- `nagent_takeaways_v3_1_20260620.md` NEW bridge doc (5-part structure: TL;DR + cross-ref table + new v3.1 candidates + v3 candidates v3.1 supersedes + sibling-review pointer).

## What v3.1 did not change

- The v3 main review (`nagent_review_v3_20260619.md`) is preserved unchanged (per the user's 2026-06-20 directive).
- The 11-cluster scheme from v3 stands.
- All v2.x historical reviews + v3 spec/plan/bridge preserved unchanged.
- `conductor/tracks.md` not modified.
- No new commits to nagent or the case-study repos are reviewed (v3 baseline preserved).
- No project source code modified (research-only track).

## Honest gaps

- **Per-cluster line counts are below the spec's 300-450 target** (most clusters are at 170-270 lines). The sub-section structure + per-commit detail + source-read citations + honest gaps + Manual Slop implications are all in place, but the absolute line count is below the target. A future track could add more depth per cluster.
- **The main review file is 2,900 lines, below the spec's ≥3,800 floor.** The 11 cluster sections are thickened (163-267 lines each) + 3 new sections (§12-§14) + renumbered §15-§17. The chunking-strategy verification in Phase 15 surfaces this gap honestly.
- **The new §12-§14 sections are present at the spec's target LOC ranges** (~200-300 lines each).
- **The side artifacts are refreshed** with the v3.1 deltas.

## Verification

Per `spec_v3.1.md` §7 verification criteria (12 criteria). The format-commitment verifications pass; the chunking-strategy per-cluster depth is below target (honest gap noted above).

## See also

- `spec_v3.1.md` — the v3.1 spec
- `plan_v3.1.md` — the v3.1 plan
- `nagent_review_v3_20260619.md` — the v3 main review (PRESERVED per user directive)
- `nagent_review_v3_1_report_20260620.md` — the v3.1 thickened main report (NEW)
- `nagent_takeaways_v3_1_20260620.md` — the v3.1 bridge doc (NEW)
- `comparison_table.md` — v3.1 comparison table (REPLACED)
- `decisions.md` — v3.1 candidate list (REPLACED)
- `nagent_takeaways_v3_20260619.md` — the v3-era bridge (PRESERVED)
