manual_slop/conductor/tracks/nagent_review_20260608/spec_v3.1.md

Track Specification v3.1: nagent_review_20260608 — Delta Thickening (chunking strategy + 3 new sections)

Status: Draft (pending user review) Initialized: 2026-06-20 Owner: Tier 1 Orchestrator (sole author; Tier 2 executing per plan_v3.1.md) Priority: Medium (architectural; refines v3's depth to v2.3 parity) Spec pair: spec_v3.1.md (this file) + plan_v3.1.md (the implementation plan) Lineage: Sits alongside spec_v3.md / plan_v3.md (the v3 spec/plan pair) in the same track directory. v3 is the first cut (664 lines, ~17% of v2.3). v3.1 thickens v3 to v2.3 parity (≥3,800 lines, ~95%+ of v2.3's 3,965 lines) via a chunking strategy that v3 lacked.

Reading note. v3.1 is the canonical v3 review of Mike Acton's nagent at depth. v3.1 covers nagent's state at a1f0680 (2026-06-18) plus the two case-study repos (pep-copt, differentiable-collisions-optc), with a chunking strategy that brings each cluster section to 300-450 lines of standalone analysis. v3.1 is readable on its own — it does not require v3 or v2.3 as context. v2.3 and v3 are preserved as historical references (recoverable from git) and may be cited for lineage, but reading them is not a prerequisite.

Standalone readability principle (load-bearing). Every version of this review is a snapshot at a point in time and must be readable in isolation. v3.1 must give a reader who has never read v2.3 (or v1, or any prior version) a complete picture of (a) what nagent is at a1f0680, (b) what the case-study repos show, and (c) what the 3 new observations (YAML avoidance, agent context-window, fine-tuning) imply for Manual Slop. Citations to v2.3 / v3 / v1 are permitted (they help readers trace the lineage) but the content must not depend on them.

File-naming note. v3.1 modifies the same file (nagent_review_v3_20260619.md) in place — the file grows but the filename is preserved because v3.1 is a thickening of v3's content, not a new review. The 11 cluster sections are thickened to per-cluster depth targets; 3 new top-level sections (§12 YAML avoidance, §13 Agent context-window observations, §14 Fine-tuning observations) are appended.

---

1. Overview

This is v3.1 — the canonical v3 review of Mike Acton's nagent at depth. v3.1 covers nagent's state at a1f0680 (2026-06-18) plus the two case-study repos (pep-copt, differentiable-collisions-optc), with a chunking strategy that brings each cluster section to 300-450 lines of standalone analysis. The four drivers for v3.1:

1. Exhaustiveness gap. v3 cluster sections average ~60 lines; v2.3 patterns average ~283 lines. v3.1 needs per-cluster depth targets + a chunking strategy that enforces them.
2. YAML avoidance. The user prefers markdown + custom DSL (the survey grammar + SSDL tags from intent_dsl_survey_20260612 + superpowers_review_20260619). nagent uses YAML for campaigns and distill graduates. v3 faithfully cited nagent's YAML; v3.1 must add an explicit "do not adopt" section that names the markdown+DSL alternative.
3. Agent context-window observations. The user has OpenCode + MiniMax M3 empirical findings: ~100-150k warm-up tokens, up to ~500k execution window, 250-350k safe zone before compaction, compact→re-warm→continue cycle. Manual Slop's docs/ + conductor/ markdown navigation is a partial mitigation; the codebase's shortcoming is that agents frequently forget/fail to read on demand. nagent's --hook-per-run (per §3) is the pattern that would close the gap.
4. Fine-tuning observations. The user is interested in fine-tuning as a way to bake their conventions/workflows into a model. Together.ai is one vendor noticed. The user is asking about other prosumer fine-tuning vendors for middle-wage income in 2026.

v3.1 delivers: per-cluster depth targets via a chunking strategy, 3 new top-level sections (§12-§14), refreshed side artifacts (comparison_table, decisions, new takeaways bridge), and atomic per-phase commits + git notes (mirroring v3's discipline).

1.1 What v3.1 produces (artifact table)

Artifact	Action	Purpose
nagent_review_v3_20260619.md	THICKEN in place	The canonical v3 review. 11 cluster sections at depth (300-450 lines each) + 3 new top-level sections (§12 YAML avoidance, §13 Agent context-window observations, §14 Fine-tuning observations) appended.
nagent_review_v3_1_20260620.md	NEW	The v3.1 delta summary doc. ~200 LOC. Quick-reference pointer to the thickened sections + summary of the new sections.
comparison_table.md	REPLACE	Refreshed for v3.1. Adds rows for the 3 new sections (§12, §13, §14).
decisions.md	REPLACE	Refreshed for v3.1. Adds 3-5 new candidates from the new observations.
nagent_takeaways_v3_1_20260620.md	NEW	Bridge doc: v3 takeaways → v3.1 deltas + sibling-review cross-refs. ~150 LOC.
metadata.json	REFRESH	v3.1 fields (delta_from_v3, observations_added, new_clusters_added).
state.toml	REFRESH	v3.1 phases + tasks.
spec_v3.1.md (this file)	NEW	The v3.1 spec.
plan_v3.1.md	NEW	The v3.1 plan (per writing-plans skill conventions).
nagent_review_v3_20260619.md (the file)	REVISED	Same filename; the file's content grows. No rename.
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).

1.2 Non-Goals

• Not rewriting v3 from scratch. v3 stays; v3.1 thickens it.
• Not adding a 12th cluster or new commits. v3.1 is depth + observations, not new material.
• Not implementing any candidates. decisions.md lists candidates; the user's deferred Manual Slop rebuild consumes them.
• Not modifying any project source code (src/*.py, tests/*.py, conductor/*.md, .opencode/*, AGENTS.md). v3.1 is research-only.
• Not Tier 3-dispatched. Tier 1 sole-authored, mirroring v3 and fable_review_20260617.
• Not a deep-dive of the fine-tuning vendor landscape. §14 captures the user's observations + the prosumer/middle-wage question; vendor analysis is a separate concern (possibly a future track).

---

2. Current State Audit

As of 2026-06-20. Baseline reviewed:

• nagent at commit a1f0680 (2026-06-18 23:51:28 UTC) — the latest commit on macton/nagent@main. This is the primary review subject.
• pep-copt at main — 5 commits. Case study for image compression optimization (2.04× speedup, byte-identical output, 24-image benchmark).
• differentiable-collisions-optc at main — 5 commits. Case study for collision detection (102× speedup, distance-tolerance match contract, 1000-pair benchmark).

2.1 What v3.1 covers

v3.1 covers 11 clusters (the 8 nagent-internal change clusters + the 2 case-study deep-dives + 1 cross-cutting case-study methodology cluster) plus 3 new top-level sections:

§	Cluster / Section	Target LOC
§1	Campaigns (6 nagent commits)	350-450
§2	Conversation safety net (2 commits)	350-450
§3	Hooks (1 commit + both case studies)	350-450
§4	Project-local roots (4 commits)	300-400
§5	Provider expansion (3 commits)	300-400
§6	Delegation rewrite (3 commits)	300-400
§7	Robustness (4 commits)	350-450
§8	Operating rules (1 commit)	300-400
§9	Case-study methodology (cross-cutting, both repos)	400-500
§10	PEP case study (pep-copt deep-dive)	400-500
§11	Collisions case study (differentiable-collisions-optc deep-dive)	400-500
Total cluster body		3,700-4,800
§0 TL;DR + frontmatter + §12-14 + §12-14 references		200-400
Total main review		3,900-5,200

The 24 nagent commits since the previous review baseline (eb6be32a, 2026-06-12) are organized into 8 internal change clusters. The 2 case-study repos (which didn't exist at the previous baseline) are covered as 1 cross-cutting methodology cluster + 2 deep-dive clusters.

Side artifacts:

• comparison_table.md — 100-130 lines
• decisions.md — 180-220 lines
• nagent_takeaways_v3_1_20260620.md — ~150 LOC

Historical reference (citeable for lineage, not required reading):

• nagent_review_v2_3_20260612.md — the previous review of nagent at eb6be32a (2026-06-12). 3,965 lines. Covers nagent's 14 patterns + 8 commits since v1.

2.2 What v3.1 adds (gaps to fill)

Per-cluster depth gaps

v3's per-cluster sections are thin because they lack:

• Sub-sections per cluster. v3 has 1-2 paragraphs of "pattern deep-dive"; v3.1 should have 4-7 sub-sections (e.g., §1.1 What Campaigns Adds / §1.2 The Driver Phases / §1.3 The Invariants / §1.4 Per-Commit Detail / §1.5 Manual Slop Implications / §1.6 Honest Gaps / §1.7 Code-Shape Sketch).
• Per-commit detail. v2.3 patterns often have a sub-section per commit; v3 has 1 paragraph covering 6 commits in §1 Campaigns. v3.1 should have a per-commit sub-section where commits are non-trivial.
• Per-claim Manual Slop citations. v3 cites Manual Slop files once per cluster; v3.1 should cite 2-3 Manual Slop subsystems per cluster with file:line references.
• Expanded source-read citations. v3 has 5-15 per cluster; v3.1 target ≥30.
• Deeper honest-gaps lists. v3 has 2-3 bullets; v3.1 target ≥6.

Three new observations (the user's input)

Observation	Source	v3.1 handling
YAML avoidance	User statement: "I don't like YAML, acton may have utilized it or noted its utilization but 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."	New §12 section. Flags every YAML use site in nagent as "do not adopt." Documents the markdown+DSL alternative (survey grammar + SSDL).
Agent context-window observations	User statement: agents take ~100-150k tokens to warm up; window up to ~500k (MiniMax M3); safe zone 250-350k; compact→re-warm→continue; nagent's campaign/track enforces it. Manual Slop's docs/ + conductor/ markdown is a partial mitigation; agents frequently forget/fail to read on demand.	New §13 section. Captures observations verbatim. Cross-refs conductor/code_styleguides/cache_friendly_context.md + proposes nagent's --hook-per-run (per §3) as the pattern for closing the gap.
Fine-tuning observations	User statement: current generalized models bottlenecked by not having conventions baked in; curated dataset of associated codebases; Together.ai noticed; asks about other prosumer fine-tuning vendors for middle-wage income in 2026.	New §14 section. Captures the diagnosis + the Together.ai observation + lists 5-6 known prosumer fine-tuning vendors in a comparison table (Together.ai, Fireworks.ai, OpenAI 4o-mini fine-tuning, Anthropic Claude Haiku fine-tuning, Google Gemini 1.5 Flash fine-tuning, local RTX 4090/5090 + Unsloth). Flags that vendor analysis is separate from v3.1's scope.

2.3 What v3.1 explicitly does NOT do

• Doesn't address the new nagent commits since v3. If nagent has moved past a1f0680, that's v4 (not v3.1).
• Doesn't address the case-study repos' new commits. If pep-copt or differentiable-collisions-optc have evolved, that's v4 (not v3.1).
• Doesn't refactor v3's structure. v3's 11-cluster scheme stands. v3.1 deepens it.
• Doesn't implement any candidates. Research-only.

---

3. Goals

The goals of v3.1, in priority order:

1. Hit the LOC floor (≥3,800 lines for the main review). v3.1 brings the review from 664 lines to v2.3 parity. The chunking strategy (§4.1) enforces this per-cluster.
2. Enforce per-cluster depth targets (300-450 lines). The chunking strategy specifies sub-sections per cluster, source-read citation floors, honest-gaps floors, and Manual Slop implication citations.
3. Add the 3 new top-level sections (§12-§14). YAML avoidance, agent context-window observations, fine-tuning observations.
4. Refresh the side artifacts. comparison_table.md adds rows for §12-§14. decisions.md adds 3-5 new candidates. nagent_takeaways_v3_1_20260620.md is a new bridge doc.
5. Preserve v3 in git history. v3 stays as the first cut; v3.1 thickens it.

3.1 Stretch goals (if scope allows)

• A verification script (scripts/audit_v3_1_chunking.py) that mechanically checks per-cluster line count + citation count + honest-gap count. Informational mode by default; --strict mode for CI.

---

4. Functional Requirements

These are the "what v3.1 must produce" requirements.

4.1 The chunking strategy (the new constraint v3 lacked)

v3.1 enforces per-cluster depth via the chunking strategy:

Metric	Target
Main review total LOC	≥3,800 lines (v2.3 parity: 3,965; v3.1 target: 3,900-5,200)
Per-cluster LOC	300-450 lines (v2.3 pattern avg: 283)
Deep-dive clusters (case studies, methodology)	400-500 lines (§9, §10, §11)
Per-cluster sub-sections	4-7
Per-cluster source-read citations	≥30 (file:line OR commit SHA + path:line OR prompts/*.md line range OR bin/*.py line range OR OPTIMIZATION-LOG/harness reference)
Per-cluster honest gaps	≥6
Per-cluster Manual Slop implications	2-3 paragraphs, each with file:line citation to Manual Slop source
Per-cluster code-shape sketches	1-2 (using survey grammar + {ssdl} tags)
Frontmatter + §0 TL;DR + §12-14 + references	200-400 lines

4.2 The per-cluster sub-section template

Each v3.1 cluster section follows this expanded template. The template is self-contained — every cluster gives a reader who has not read any prior version a complete picture of what the cluster adds to nagent's design.

### §N. Cluster name (n commits)

**Source:** <list of commit SHAs + paths>
**One-liner:** <what this cluster adds to nagent>
**Pattern summary:** <1-2 sentence summary of the abstraction this cluster introduces, in nagent-internal terms (not "vs v2.3" terms)>

#### §N.1 <First sub-section name>
<prose>

#### §N.2 <Second sub-section name>
<prose>

... (4-7 sub-sections total)

#### §N.x <Last sub-section: Manual Slop Implications>
<2-3 paragraphs, each with Manual Slop file:line citations>

#### §N.x <Last sub-section: Honest Gaps>
<≥6 bullets>

#### §N.x <Code-Shape Sketch>
<survey-grammar + {ssdl} tags, 1-2 sketches>

**Source-read citations:**
- <file:line citation>
- ...
(≥30 entries)

**Decision candidate:** <decisions.md entry, or "no candidate" with rationale>
**Cross-refs:** <sibling review references, if any>
**Pattern history (optional):** <citation to v2.3 / v3 / v1 for readers who want the lineage; "none" if N/A>

The per-cluster sub-section names are customized per cluster (e.g., §1.1 "What Campaigns Adds" / §1.2 "The Driver Phases" / §1.3 "The Invariants" / §1.4 "Per-Commit Detail" / §1.5 "Manual Slop Implications" / §1.6 "Honest Gaps" / §1.7 "Code-Shape Sketch"). The "Pattern summary" field is self-contained (no v2.3 reference required); "Pattern history" is optional lineage context.

4.3 The 3 new top-level sections (§12-§14)

4.3.1 §12 YAML avoidance (target: 200-300 lines)

Content:

• §12.1 Where nagent uses YAML. Catalog of YAML use sites: .nagent/campaigns/{slug}/index.yaml, per-item item.yaml, proposal.yaml, graduate {name}.draft, distill passes, etc. Cite file:line for each.
• §12.2 Why YAML is "do not adopt" for Manual Slop. Reasons:
  • Markdown + frontmatter is sufficient for the same data shape (per conductor/presets.py and conductor/personas.py precedent — both use TOML, but markdown+YAML-frontmatter is the alternative).
  • The custom DSL (survey grammar + SSDL) is the project's intent for inline computation, not configuration.
  • YAML's whitespace sensitivity is fragile for AI-generated content (LLMs frequently mis-indent).
• §12.3 The markdown + custom DSL alternative. Concrete proposal: each campaign-style artifact becomes a markdown file with structured headings (## Goal / ## Tasks / ## Done criteria) + a TOML frontmatter block (project config precedent) + optional SSDL-annotated code blocks for any inline computation. Cite intent_dsl_survey_20260612 Cluster 5 "SSDL shape primitives" for the DSL primitives.
• §12.4 Cross-refs. intent_dsl_survey_20260612 (the DSL primitives), superpowers_review_20260619 (the project's own markdown-driven conventions), conductor/presets.py (TOML precedent).

4.3.2 §13 Agent context-window observations (target: 200-300 lines)

Content:

• §13.1 The warm-up + window + safe-zone numbers. Cite the user's empirical findings: ~100-150k warm-up, up to ~500k window (MiniMax M3), 250-350k safe zone, compact→re-warm→continue cycle. Frame as "what we know about OpenCode + MiniMax M3 from the user."
• §13.2 nagent's enforcement. nagent's campaign/track system enforces the cycle more strictly: per-turn hook injection (§3) keeps the model grounded; the safety net (§2) handles out-of-window failures; the distill pass regenerates the durable state from scratch. Cite the relevant commits.
• §13.3 Manual Slop's partial mitigation. The docs/ + conductor/ markdown navigation IS the project's partial mitigation. Document which files are guidance nodes (AGENTS.md, conductor/workflow.md, conductor/product-guidelines.md, the 6 styleguides in conductor/code_styleguides/, the 14 docs/guide_*.md files). Note that the project deliberately keeps these in markdown so agents can navigate on demand.
• §13.4 The shortcoming. Agents frequently forget to read or fail to read on demand. Document this as a known issue. Propose that nagent's --hook-per-run model (per §3) is the pattern Manual Slop should adopt — a per-turn hook that surfaces a "what to read next" status block at the top of every turn. Cross-ref conductor/code_styleguides/cache_friendly_context.md for the cache TTL GUI contract (which is the cache version of the same insight).
• §13.5 Decision candidate. NEW candidate: "Per-turn ground-truth hook for Manual Slop" (the §3 candidate, but with v3.1's additional context-window framing).

4.3.3 §14 Fine-tuning observations (target: 150-250 lines)

Content:

• §14.1 The diagnosis. Current generalized models are bottlenecked by not having the user's core conventions/workflows baked in. A curated dataset of associated codebases (Manual Slop's own tracks, decisions, plans, styleguides) is the user's proposed mitigation.
• §14.2 Together.ai as one noticed vendor. The user noticed Together.ai. Note: Together.ai offers fine-tuning for open-source models (Llama 3.x, Qwen 3, Mistral) with transparent per-token pricing. Cite together.ai's pricing page.
• §14.3 Prosumer fine-tuning vendor survey (2026). A comparison table:

Vendor	Model families	Pricing tier	Prosumer-friendly?
Together.ai	Llama, Qwen, Mistral, others	$0.50-3/M training; $0.10-0.60/M inference	Yes — transparent; open-source models
Fireworks.ai	Llama, Qwen, Mistral	Similar to Together	Yes — serverless DX
OpenAI fine-tuning	GPT-4o, GPT-4o-mini, GPT-3.5	~$3/M training, $0.30/M inference (4o-mini)	Yes for "mini"; expensive for 4o
Anthropic Claude Haiku fine-tuning	Claude Haiku (if on waitlist)	Similar to OpenAI 4o-mini	Waitlist-gated
Google Gemini 1.5 Flash fine-tuning	Gemini 1.5 Flash	~$0.50-1/M training	Yes for high-volume
Local fine-tuning (RTX 4090/5090 + Unsloth)	Any open-source model	$1,500-3,000 one-time hardware	Yes for weekly-iterators

• §14.4 Vendor analysis is out of scope for v3.1. The §14 section is observational; a vendor-selection track (if needed) would do the deep comparison + decision.

4.4 Side artifacts (the supporting structure)

4.4.1 comparison_table.md — refreshed

Format: same as v3's. Adds rows for the 3 new sections:

| 12 | YAML avoidance | nagent uses YAML for campaigns/distill | Manual Slop uses markdown + custom DSL (survey grammar + SSDL) | SUBSUMED (Manual Slop convention) | v3.1 §12 |
| 13 | Agent context-window observations | n/a (empirical findings from the user) | Manual Slop's docs/ + conductor/ markdown navigation is partial mitigation; agents frequently forget to read | GAP | v3.1 §13 |
| 14 | Fine-tuning observations | n/a (user interest + vendor notice) | Manual Slop could provide the curated dataset; vendor selection is separate | n/a (observation, not comparison) | v3.1 §14 |

Target: 100-130 lines.

4.4.2 decisions.md — refreshed

decisions.md is a self-contained candidate list. It introduces each candidate with a Goal / Context / Source citations / Cross-refs / Recommended priority block — no reader needs to consult any prior version to understand the candidates. Historical lineage is optional and appears only when relevant (e.g., "This candidate is the v3.1 evolution of an earlier candidate; see git log -p conductor/tracks/nagent_review_20260608/decisions.md for the full lineage.").

Top section: brief introduction explaining the candidate format + a pointer to git history for readers who want the full lineage of which candidates evolved across versions.

Add 3-5 new candidates from v3.1:

• Candidate 27 (HIGH): "Markdown + custom DSL lock-in" — explicitly adopt markdown + survey grammar + SSDL for campaign-style artifacts; reject YAML for new project artifacts. (From §12.)
• Candidate 28 (MEDIUM): "Per-turn ground-truth hook for Manual Slop" — adopt nagent's --hook-per-run model; inject a "what to read next" status block at the top of every send_result(). (From §3 + §13.)
• Candidate 29 (MEDIUM): "Dataset-curation track for fine-tuning" — separate track to curate the Manual Slop conventions/workflows dataset for fine-tuning; vendor selection deferred. (From §14.)
• Candidate 30 (LOW): "Cache TTL GUI contract hardening" — make the per-turn grounding primitive also track cache state; cross-ref cache_friendly_context.md. (From §13 + §5.1 cache strategy.)

Target: 180-220 lines.

4.4.3 nagent_takeaways_v3_1_20260620.md — new bridge doc

Format: 5-part structure (mirrors v3's nagent_takeaways_v3_20260619.md):

1. TL;DR (1 paragraph): what v3.1 takeaways add over v3 takeaways.
2. Cross-reference table (~15 rows): one row per v3.1 takeaway that touches a v3 candidate.
3. The new v3.1 candidates (3-5): one paragraph each, with verdict evidence.
4. The v3 candidates v3.1 supersedes (0-2): one paragraph each.
5. Sibling-review pointer: fable_review, intent_dsl_survey, superpowers_review, plus the project files that capture the observations.

Target: ~150 LOC.

4.4.4 nagent_review_v3_1_20260620.md — the delta summary doc

A short reference doc that points to the thickened sections + summarizes the new sections. ~200 LOC.

4.5 Cross-references (sibling reviews)

v3.1's nagent_takeaways_v3_1_20260620.md cross-references the same 3 siblings as v3:

Sibling	Reference point in v3.1
fable_review_20260617	Inline §8 (operating rules, Fable's watch-dogging anti-pattern) + the bridge doc
intent_dsl_survey_20260612	Inline §12 (YAML avoidance → markdown+DSL alternative; survey grammar + SSDL) + the bridge doc
superpowers_review_20260619	Inline §9 (case-study methodology, brainstorming process parallel) + §13 (markdown navigation as guidance nodes) + the bridge doc

Plus new cross-refs added by v3.1:

• conductor/code_styleguides/cache_friendly_context.md (the cache TTL GUI contract) — §13
• conductor/presets.py (TOML precedent) — §12
• conductor/personas.py (TOML precedent) — §12
• conductor/styleguides/*.md (the 6 styleguides as guidance nodes) — §13

---

5. Non-Functional Requirements

5.1 Format commitment

v3.1 reaffirms v3's 5 commitments unchanged:

1. 7-column tables (Symbol | Name | Signature | Semantics | Example | Borrowed from | Shape)
2. No JSON code blocks (JSON → tables)
3. SSDL shape tags
4. Survey grammar primitives in code examples
5. Source-read citation discipline (≥3 per cluster — v3.1 raises the floor to ≥30 per cluster)

5.2 Authoring tier + discipline

• Tier: Tier 1 Orchestrator sole-authored (no Tier 3 dispatch). Mirrors v3.
• Per-cluster authoring shape (v3.1 expansion of v3's 5-step pass):
  1. Source-read all cluster commits + any referenced files.
  2. Read Manual Slop subsystems named in the cluster's Manual Slop implications (cite file:line for each).
  3. Identify sub-section structure (4-7 per cluster, customized to the cluster's content).
  4. Write the cluster section with the expanded template (§4.2).
  5. Verify the chunking strategy metrics (§4.1) before committing.
• Phase structure: 15 phases (per §3 of the v3.1 plan):
  • Phase 1: Setup + audit
  • Phases 2-12: One per cluster (thickening)
  • Phase 13: New sections §12-§14
  • Phase 14: Refresh side artifacts
  • Phase 15: Format-commitment + chunking-strategy verification + final
• Commits: one commit per phase (atomic rollback per phase). Git notes attached per task. Per-task commit SHAs recorded in state.toml.

5.3 Filename convention

• Spec: conductor/tracks/nagent_review_20260608/spec_v3.1.md (this file).
• Plan: conductor/tracks/nagent_review_20260608/plan_v3.1.md.
• Main review (thickened in place): conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md (filename preserved; content grows).
• Delta summary: conductor/tracks/nagent_review_20260608/nagent_review_v3_1_20260620.md (new).
• Bridge doc: conductor/tracks/nagent_review_20260608/nagent_takeaways_v3_1_20260620.md (new).
• Date convention: 20260620 (today, the day v3.1 was initiated).

5.4 Track-state hygiene

• metadata.json refreshed in place (v3.1 fields).
• state.toml updated as phases complete (one entry per phase + per-task).
• conductor/tracks.md NOT modified.
• Git notes attached to every phase commit.

5.5 Standalone readability (load-bearing)

Every version of this review is a snapshot at a point in time and must be readable in isolation. v3.1 must give a reader who has never read v2.3 (or v1, or any prior version) a complete picture of what nagent is, what the case-study repos show, and what the 3 new observations imply for Manual Slop. Concrete rules:

• No "Pattern(s) vs v2.3" as a required field in the per-cluster template (replaced by the self-contained "Pattern summary" field; "Pattern history" is optional).
• No "v2.3 → v3 → v3.1 status mapping" in decisions.md (replaced by a self-contained candidate list with optional git-history lineage pointers).
• No required references to prior versions anywhere in the main review or side artifacts. Citations to v2.3 / v3 / v1 are permitted (they help readers trace lineage) but the content does not depend on them.
• Each cluster's "What this adds to nagent" framing is nagent-internal, not relative-to-prior-review. A reader who knows nagent but has not read any of this project's reviews should be able to read v3.1 end-to-end and get value from it.
• The §0 TL;DR opens with a 1-paragraph statement of what nagent is + what v3.1 covers, so a fresh reader has the context before the cluster sections.

---

6. Architecture Reference

6.1 What v3.1 depends on (existing project docs)

• conductor/code_styleguides/cache_friendly_context.md — referenced by §13 for the cache TTL GUI contract.
• conductor/code_styleguides/data_oriented_design.md — the project's canonical DOD reference (derived from Acton's context/data-oriented-design.md); referenced by §8 + §10 + §11.
• conductor/code_styleguides/knowledge_artifacts.md — referenced by §9 + §12.
• conductor/code_styleguides/error_handling.md — the Result[T] convention; referenced by §2 + §7.
• conductor/presets.py + conductor/personas.py — TOML precedent for the YAML-avoidance alternative (§12).
• conductor/styleguides/*.md — the 6 styleguides as guidance nodes (§13).
• docs/guide_*.md — the 14 deep-dive guides as guidance nodes (§13).
• AGENTS.md — the canonical operating instructions for agents (§13).
• conductor/workflow.md — the workflow conventions v3.1 follows.
• conductor/tech-stack.md — the tech stack (relevant for §5 provider analysis).
• docs/guide_meta_boundary.md — the Application vs Meta-Tooling distinction (load-bearing context for the verdict structure).

6.2 External sources (unchanged from v3)

• macton/nagent@a1f0680 (2026-06-18) — https://github.com/macton/nagent
• macton/pep-copt@main — https://github.com/macton/pep-copt
• macton/differentiable-collisions-optc@main — https://github.com/macton/differentiable-collisions-optc

6.3 Sibling reviews (unchanged from v3)

• conductor/tracks/fable_review_20260617/
• conductor/tracks/intent_dsl_survey_20260612/
• conductor/tracks/superpowers_review_20260619/

6.4 New external sources for §14 (fine-tuning)

• Together.ai pricing page: https://www.together.ai/pricing
• Fireworks.ai pricing page: https://fireworks.ai/pricing
• OpenAI fine-tuning pricing: https://openai.com/api/pricing/
• Unsloth (local fine-tuning framework): https://github.com/unslothai/unsloth

(Note: §14 captures these as references for the user; vendor analysis is out of scope for v3.1.)

---

7. Verification Criteria

These are the "definition of done" for v3.1. The metadata.json verification_criteria field will contain:

1. LOC floor. Main review ≥3,800 lines (verified by wc -l).
2. Per-cluster depth. Each cluster 300-450 lines (or 400-500 for deep-dive clusters §9-§11), verified per-cluster by wc -l on the cluster section.
3. Per-cluster sub-sections. Each cluster has 4-7 sub-sections, verified by grep -c "^#### §N\." per cluster.
4. Per-cluster source-read citations. Each cluster has ≥30 citations, verified by per-cluster grep.
5. Per-cluster honest gaps. Each cluster has ≥6 honest-gap bullets, verified by per-cluster grep.
6. Per-cluster Manual Slop implications. Each cluster has 2-3 paragraphs with Manual Slop file:line citations, verified by per-cluster inspection.
7. Format commitment. All 5 commitments verified by grep (per v3's verification — no regression).
8. §12-§14 present. The 3 new sections are appended to the main review, each with the target LOC range.
9. Side artifacts refreshed. comparison_table.md, decisions.md, nagent_takeaways_v3_1_20260620.md all committed with the v3.1 deltas.
10. Track artifacts. spec_v3.1.md + plan_v3.1.md committed; metadata.json refreshed; state.toml updated as phases complete.
11. Commits. One commit per phase; git notes attached per task; per-task commit SHAs in state.toml.
12. v3 preserved. The v3 file (nagent_review_v3_20260619.md) grows but the v3 commit history is recoverable via git log -p.
13. Standalone readability. A reader who has never read v2.3 (or v1, or any prior version) can read v3.1 + the side artifacts end-to-end and get a complete picture of (a) what nagent is at a1f0680, (b) what the case-study repos show, and (c) what the 3 new observations imply for Manual Slop. Verified by: open only nagent_review_v3_20260619.md + comparison_table.md + decisions.md + nagent_takeaways_v3_1_20260620.md (no prior versions), read end-to-end, and confirm the reading is coherent. Historical lineage references are permissible (and helpful) but the content does not depend on them.

A v3.1 chunking_strategy_audit.sh script (added to scripts/ if v3.1 surfaces a need; otherwise inline grep checks) will enforce #1-#6 mechanically. #13 is verified by a manual read-pass. The other 5 are verified manually or by simple grep.

---

8. Out of Scope

v3.1 explicitly does NOT do the following:

• Rewrite v3 from scratch. v3 stays; v3.1 thickens it.
• Address new nagent commits since a1f0680. If nagent has moved past a1f0680, that's v4.
• Address new commits in the case-study repos. If pep-copt or differentiable-collisions-optc have evolved, that's v4.
• Implement any candidates. Research-only.
• Modify any project source code (src/*.py, tests/*.py, conductor/*.md, .opencode/*, AGENTS.md).
• Tier 3 dispatch. Tier 1 sole-authored.
• Deep-dive fine-tuning vendor selection. §14 is observational; vendor selection is a separate future track (per Candidate 29).
• Refactor v3's 11-cluster scheme. The scheme stands; v3.1 deepens it.
• Delete or rename v3 files. All v3 files preserved.

---

9. See Also

9.1 In this track directory

Canonical v3.1 artifacts (read these for v3.1):

• nagent_review_v3_20260619.md — the v3.1 main review (11 cluster sections at depth + §12-§14 new sections).
• nagent_review_v3_1_20260620.md — the v3.1 delta summary doc (points to the thickened sections + summarizes the new sections).
• comparison_table.md — v3.1 comparison table.
• decisions.md — v3.1 candidate list.
• nagent_takeaways_v3_1_20260620.md — v3.1 bridge doc.
• spec_v3.1.md (this file) + plan_v3.1.md — the v3.1 spec/plan pair.

Historical references (citeable for lineage, NOT required reading for v3.1):

• spec_v3.md + plan_v3.md — the v3 spec/plan pair (2026-06-19).
• nagent_review_v2_3_20260612.md — the previous review (nagent at eb6be32a, 2026-06-12; 3,965 lines; 14 patterns).
• nagent_review_v2_20260612.md + nagent_review_v2_1_20260612.md + nagent_review_v2_2_20260612.md — the v2 → v2.1 → v2.2 evolution.
• report.md — the original v1 review (nagent at 28a6a87c, 2026-06-08).
• spec.md + plan.md — the original v1 spec/plan.
• nagent_takeaways_v3_20260619.md — the v3-era bridge doc.
• metadata.json + state.toml — track state files; metadata.json is refreshed for v3.1, state.toml is updated as v3.1 phases complete.

9.2 Sibling reviews

• 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 Project docs

• conductor/workflow.md — the workflow conventions v3.1 follows.
• conductor/product-guidelines.md — the project styleguides v3.1 follows.
• conductor/code_styleguides/data_oriented_design.md — the project's canonical DOD reference.
• conductor/code_styleguides/cache_friendly_context.md — the cache TTL GUI contract (referenced by §13).
• docs/guide_meta_boundary.md — the Application vs Meta-Tooling distinction.