diff --git a/conductor/tracks/nagent_review_20260608/plan_v3.1.md b/conductor/tracks/nagent_review_20260608/plan_v3.1.md new file mode 100644 index 00000000..d3aac043 --- /dev/null +++ b/conductor/tracks/nagent_review_20260608/plan_v3.1.md @@ -0,0 +1,920 @@ +# nagent_review_v3.1 Implementation Plan + +> **For agentic workers:** v3.1 is Tier 1 sole-authored (mirroring v3 and `fable_review_20260617`). The "tasks" below describe the structure each piece of work must produce; the actual prose is written by the Tier 1 author during execution. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Produce the v3.1 delta thickening of the nagent review — expand the 11 cluster sections in `nagent_review_v3_20260619.md` from ~60 lines/cluster to 300-450 lines/cluster (per the chunking strategy), append 3 new top-level sections (§12 YAML avoidance, §13 Agent context-window observations, §14 Fine-tuning observations), refresh the side artifacts, and write a delta-summary doc + bridge doc. + +**Architecture:** 15 phases. Phase 1 is setup + audit. Phases 2-12 are one phase per cluster (thickening — each phase deepens the v3 cluster to the v3.1 chunking target). Phase 13 writes the 3 new sections. Phase 14 refreshes the side artifacts (comparison_table, decisions, new takeaways bridge). Phase 15 verifies the chunking strategy + format commitment. Each phase commits atomically with a git note. + +**Tech Stack:** Markdown (the deliverable). `git` for atomic per-phase commits + `git notes` for per-task summaries. `state.toml` for per-task commit SHA tracking. `manual-slop` MCP tools for file reads. `webfetch` for the GitHub commit/file fetches + the fine-tuning vendor pricing pages. + +**Spec pair:** This plan implements `spec_v3.1.md` in the same track directory. Read the spec first; the plan is executable against the spec. + +**Naming convention:** All v3.1 file basenames use `20260620` (today, the day v3.1 was initiated). The main review file (`nagent_review_v3_20260619.md`) keeps its v3 filename; only the new files use `20260620`. + +--- + +## File Structure + +### Files created in v3.1 + +| Path | Purpose | +|---|---| +| `conductor/tracks/nagent_review_20260608/plan_v3.1.md` | This file. | +| `conductor/tracks/nagent_review_20260608/spec_v3.1.md` | The v3.1 spec. | +| `conductor/tracks/nagent_review_20260608/nagent_review_v3_1_20260620.md` | The v3.1 delta summary doc. ~200 LOC. Points to the thickened sections + summarizes the new sections. | +| `conductor/tracks/nagent_review_20260608/nagent_takeaways_v3_1_20260620.md` | The v3.1 bridge doc. ~150 LOC. 5-part structure. | + +### Files refreshed in v3.1 (REPLACE / THICKEN in place) + +| Path | Refresh action | +|---|---| +| `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` | THICKEN: each cluster section grows from ~60 lines to 300-450 lines (per cluster) via the chunking strategy. 3 new sections (§12-§14) appended. Total target: ≥3,800 lines. | +| `conductor/tracks/nagent_review_20260608/comparison_table.md` | REPLACE: refreshed for v3.1. Adds rows for §12, §13, §14. Target: 100-130 lines. | +| `conductor/tracks/nagent_review_20260608/decisions.md` | REPLACE: refreshed for v3.1. Adds 3-5 new candidates (Candidates 27-30). Target: 180-220 lines. | +| `conductor/tracks/nagent_review_20260608/metadata.json` | REFRESH: v3.1 fields. | +| `conductor/tracks/nagent_review_20260608/state.toml` | REFRESH: v3.1 phases + tasks. | + +### Files NOT modified in v3.1 + +| Path | Why preserved | +|---|---| +| `conductor/tracks/nagent_review_20260608/spec_v3.md` + `plan_v3.md` | v3 spec/plan pair; historical. | +| `conductor/tracks/nagent_review_20260608/nagent_review_v2_*.md` + `report.md` | All v2.x historical. | +| `conductor/tracks/nagent_review_20260608/nagent_takeaways_v3_20260619.md` | v3-era bridge; preserved unchanged. | +| `conductor/tracks.md` | Per "B. Same track" decision. | + +### File responsibility boundaries + +- **`nagent_review_v3_20260619.md`** owns the thickened cluster sections + the 3 new top-level sections (§12-§14). The filename is preserved because the content grows in place — v3.1 is a delta thickening, not a new review. +- **`nagent_review_v3_1_20260620.md`** owns the delta summary — a quick-reference doc that points to the thickened sections + summarizes the new sections. The "v3.1 added X" reference. +- **`nagent_takeaways_v3_1_20260620.md`** owns the bridge doc (TL;DR + cross-ref table + new candidates + sibling pointer). +- **`comparison_table.md`** owns the flat side-by-side table for v3.1's 14 sections (11 clusters + 3 new). +- **`decisions.md`** owns the v3.1 candidate list (v3's 25-30 + v3.1's 3-5 new). +- **`metadata.json`** + **`state.toml`** own the machine-readable summary + per-task progress. + +--- + +## The Chunking Strategy (the new constraint) + +These targets are enforced per cluster. Phase 15 verifies all of them mechanically. + +| Metric | Target | Verification command | +|---|---|---| +| **Main review total LOC** | ≥3,800 lines | `wc -l conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` | +| **Per-cluster LOC** | 300-450 lines (deep-dive clusters §9-§11: 400-500) | per-cluster `wc -l` on the cluster section | +| **Per-cluster sub-sections** | 4-7 | per-cluster `grep -c "^#### §N\."` | +| **Per-cluster source-read citations** | ≥30 | per-cluster grep for `path/to/file:L[0-9]+` or `prompts/[a-z_-]+.md` or `bin/[a-z_-]+` or commit SHA | +| **Per-cluster honest gaps** | ≥6 | per-cluster grep for `Honest gaps` bullet count | +| **Per-cluster Manual Slop implications** | 2-3 paragraphs with file:line citations | manual inspection per cluster | +| **Frontmatter + §0 + §12-14 + references** | 200-400 lines | `wc -l` | + +A failure on any metric = back to the cluster phase, add depth, re-commit, re-verify. + +--- + +## Phase 1: Setup + audit + +Focus: Initialize v3.1's track-state plumbing + audit the v3 baseline. + +**Files:** +- Modify: `conductor/tracks/nagent_review_20260608/metadata.json` +- Modify: `conductor/tracks/nagent_review_20260608/state.toml` +- Create: `conductor/tracks/nagent_review_20260608/nagent_review_v3_1_20260620.md` (the delta summary skeleton) + +- [ ] **Step 1.1: Refresh `metadata.json` with v3.1 fields** + +Add v3.1 fields to `metadata.json` (preserving v3 fields below): + +```json +{ + "version": "v3.1", + "v3_1_initialized": "2026-06-20", + "v3_1_is_delta_of": "v3", + "v3_1_baseline": { + "v3_review_commit": "195b0f45", + "nagent_commit": "a1f0680", + "case_study_repos_at": "main" + }, + "chunking_strategy": { + "main_review_loc_floor": 3800, + "per_cluster_loc_target": "300-450", + "deep_dive_clusters_loc_target": "400-500", + "per_cluster_sub_sections": "4-7", + "per_cluster_source_read_citations": ">=30", + "per_cluster_honest_gaps": ">=6", + "per_cluster_manual_slop_implications": "2-3 paragraphs with file:line citations", + "frontmatter_and_new_sections_loc_target": "200-400" + }, + "scope_v3_1": { + "new_files": [ + "spec_v3.1.md", + "plan_v3.1.md", + "nagent_review_v3_1_20260620.md", + "nagent_takeaways_v3_1_20260620.md" + ], + "thickened_files": [ + "nagent_review_v3_20260619.md" + ], + "replaced_files": [ + "comparison_table.md", + "decisions.md" + ], + "refreshed_files": [ + "metadata.json", + "state.toml" + ], + "deleted_files": [] + }, + "v3_1_observations_added": [ + "YAML avoidance (no YAML in new Manual Slop artifacts; use markdown + custom DSL)", + "Agent context-window observations (warm-up ~100-150k; window up to ~500k MiniMax M3; safe zone 250-350k; compact-re-warm-continue cycle)", + "Fine-tuning observations (current generalized models bottlenecked by not having conventions baked in; Together.ai + 5-6 other prosumer fine-tuning vendors)" + ], + "verification_criteria_v3_1": [ + "Main review >=3,800 lines", + "Each cluster 300-450 lines (deep-dive clusters 400-500)", + "Each cluster has 4-7 sub-sections", + "Each cluster has >=30 source-read citations", + "Each cluster has >=6 honest-gap bullets", + "Each cluster has 2-3 paragraphs of Manual Slop implications with file:line citations", + "Format commitment verified (5 commitments)", + "Sections §12, §13, §14 present at target LOC ranges", + "comparison_table.md, decisions.md, nagent_takeaways_v3_1_20260620.md all committed with v3.1 deltas", + "spec_v3.1.md + plan_v3.1.md committed", + "metadata.json + state.toml refreshed", + "One commit per phase with git notes", + "v3 preserved (git log -p recoverable)" + ] +} +``` + +Preserve all v3 fields below. v3.1 fields above; v3 fields below. + +- [ ] **Step 1.2: Initialize `state.toml` v3.1 fields** + +Add v3.1 phase + task entries to `state.toml` below the v3 entries: + +```toml +[v3_1_phases] +phase_1 = { status = "in_progress", checkpointsha = "", name = "Setup + audit" } +phase_2 = { status = "pending", checkpointsha = "", name = "Thicken §1 Campaigns cluster" } +phase_3 = { status = "pending", checkpointsha = "", name = "Thicken §2 Conversation safety net cluster" } +phase_4 = { status = "pending", checkpointsha = "", name = "Thicken §3 Hooks cluster" } +phase_5 = { status = "pending", checkpointsha = "", name = "Thicken §4 Project-local roots cluster" } +phase_6 = { status = "pending", checkpointsha = "", name = "Thicken §5 Provider expansion cluster" } +phase_7 = { status = "pending", checkpointsha = "", name = "Thicken §6 Delegation rewrite cluster" } +phase_8 = { status = "pending", checkpointsha = "", name = "Thicken §7 Robustness cluster" } +phase_9 = { status = "pending", checkpointsha = "", name = "Thicken §8 Operating rules cluster" } +phase_10 = { status = "pending", checkpointsha = "", name = "Thicken §9 Case-study methodology cluster" } +phase_11 = { status = "pending", checkpointsha = "", name = "Thicken §10 PEP case study cluster" } +phase_12 = { status = "pending", checkpointsha = "", name = "Thicken §11 Collisions case study cluster" } +phase_13 = { status = "pending", checkpointsha = "", name = "Write new sections §12-§14 (YAML avoidance, Agent context-window, Fine-tuning)" } +phase_14 = { status = "pending", checkpointsha = "", name = "Refresh side artifacts (comparison_table, decisions, takeaways_v3_1)" } +phase_15 = { status = "pending", checkpointsha = "", name = "Chunking-strategy + format-commitment verification + final" } + +[v3_1_tasks] +t1_1 = { status = "in_progress", commit_sha = "", description = "Refresh metadata.json with v3.1 fields" } +t1_2 = { status = "pending", commit_sha = "", description = "Initialize state.toml v3.1 fields" } +t1_3 = { status = "pending", commit_sha = "", description = "Confirm spec_v3.1.md + plan_v3.1.md exist and are approved" } +t1_4 = { status = "pending", commit_sha = "", description = "Write nagent_review_v3_1_20260620.md delta summary skeleton" } +t1_5 = { status = "pending", commit_sha = "", description = "Commit Phase 1 setup" } + +[v3_1_verification] +v3_1_main_review_loc_floor_met = false +v3_1_per_cluster_depth_met = false +v3_1_per_cluster_sub_sections_met = false +v3_1_per_cluster_citations_met = false +v3_1_per_cluster_honest_gaps_met = false +v3_1_per_cluster_manual_slop_cited = false +v3_1_new_sections_present = false +v3_1_format_commitment_verified = false +v3_1_side_artifacts_refreshed = false +v3_1_track_artifacts_committed = false +v3_1_commits_with_notes = false +v3_1_v3_preserved = false +``` + +Preserve all v3 fields below. v3.1 fields above; v3 fields below. + +- [ ] **Step 1.3: Confirm `spec_v3.1.md` + `plan_v3.1.md` exist** + +Verify both files exist in the track directory. (If they don't, stop and report to the user.) + +- [ ] **Step 1.4: Write `nagent_review_v3_1_20260620.md` delta summary skeleton** + +Create the file with the skeleton: + +```markdown +# nagent_review_v3_1_20260620 — Delta Summary + +**Date:** 2026-06-20 +**Status:** Draft (Phase 1 setup complete; cluster thickening in progress) +**Owner:** Tier 1 Orchestrator +**Delta from:** v3 (`nagent_review_v3_20260619.md`, 664 lines, 2026-06-19) +**Spec pair:** `spec_v3.1.md` + `plan_v3.1.md` + +## What v3.1 changed + +### Per-cluster thickening (11 clusters) + +The main review file (`nagent_review_v3_20260619.md`) is thickened in place. Each cluster section grows from ~60 lines to 300-450 lines (or 400-500 for deep-dive clusters §9-§11). The thickening follows the chunking strategy (per spec_v3.1.md §4.1). + +| § | Cluster | v3 lines | v3.1 target | Phase | +|---|---|---|---|---| +| §1 | Campaigns | ~50 | 350-450 | Phase 2 | +| §2 | Conversation safety net | ~60 | 350-450 | Phase 3 | +| §3 | Hooks | ~60 | 350-450 | Phase 4 | +| §4 | Project-local roots | ~50 | 300-400 | Phase 5 | +| §5 | Provider expansion | ~50 | 300-400 | Phase 6 | +| §6 | Delegation rewrite | ~50 | 300-400 | Phase 7 | +| §7 | Robustness | ~60 | 350-450 | Phase 8 | +| §8 | Operating rules | ~60 | 300-400 | Phase 9 | +| §9 | Case-study methodology | ~65 | 400-500 | Phase 10 | +| §10 | PEP case study | ~50 | 400-500 | Phase 11 | +| §11 | Collisions case study | ~50 | 400-500 | Phase 12 | + +### Three new top-level sections (Phase 13) + +- **§12 YAML avoidance** (~200-300 lines): catalogs every YAML use site in nagent; flags them as "do not adopt" for Manual Slop; documents the markdown + custom DSL alternative. +- **§13 Agent context-window observations** (~200-300 lines): captures the user's OpenCode + MiniMax M3 empirical findings; 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** (~150-250 lines): captures the diagnosis + Together.ai observation + lists 6 prosumer fine-tuning vendors in a comparison table; flags that vendor analysis is out of scope. + +### Side artifacts refresh (Phase 14) + +- `comparison_table.md` REPLACED with v3.1 content (adds rows for §12, §13, §14). +- `decisions.md` REPLACED with v3.1 content (adds Candidates 27-30). +- `nagent_takeaways_v3_1_20260620.md` NEW bridge doc (~150 LOC, 5-part structure). + +## What v3.1 did not change + +- 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). + +## Verification + +Per spec_v3.1.md §7 verification criteria (12 criteria). All verified in Phase 15. +``` + +- [ ] **Step 1.5: Commit Phase 1 setup** + +```bash +cd C:/projects/manual_slop +git add conductor/tracks/nagent_review_20260608/spec_v3.1.md \ + conductor/tracks/nagent_review_20260608/plan_v3.1.md \ + conductor/tracks/nagent_review_20260608/metadata.json \ + conductor/tracks/nagent_review_20260608/state.toml \ + conductor/tracks/nagent_review_20260608/nagent_review_v3_1_20260620.md +git commit -m "conductor(track): nagent_review_v3.1 Phase 1 setup + audit" +git notes add -m "Phase 1 complete. Refreshed metadata.json with v3.1 fields (chunking strategy, scope_v3_1, observations_added, verification_criteria_v3_1). Initialized state.toml v3.1 phases + tasks. Wrote nagent_review_v3_1_20260620.md delta summary skeleton." $(git log -1 --format='%H') +``` + +Update `state.toml`: mark t1_1, t1_2, t1_3, t1_4, t1_5 as `completed` with their commit SHAs. + +--- + +## Phase 2: Thicken §1 Campaigns cluster + +Focus: Expand the §1 Campaigns cluster from ~50 lines to 350-450 lines per the chunking strategy. + +**Files:** +- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` (§1) +- Modify: `conductor/tracks/nagent_review_20260608/state.toml` + +**Source commits:** `24cf16d`, `199a36b`, `f3ec090`, `c1d2cad`, `6443d70`, `7a7e242` (unchanged from v3) + +- [ ] **Step 2.1: Read v3's §1 in full + identify what's thin** + +Use `manual-slop_read_file` or `get_file_slice` to read v3's §1 (lines ~18-64 of the main review). Identify what's thin: +- Per-commit detail (6 commits covered in 1 paragraph) +- Sub-sections (no §1.1 / §1.2 / etc.) +- Manual Slop implications (1 paragraph) +- Source-read citations (need to expand from current ~13 to ≥30) +- Honest gaps (currently 1 + 1 continued; need ≥6) + +- [ ] **Step 2.2: Source-read the 6 campaigns commits + their files** + +For each commit (`24cf16d`, `199a36b`, `f3ec090`, `c1d2cad`, `6443d70`, `7a7e242`): +- Fetch `https://github.com/macton/nagent/commit/` and extract the diff + full commit message. +- Read the actual files changed (e.g., `bin/nagent-campaign`, `bin/helpers/nagent_campaign_lib.py`, `bin/helpers/nagent_distill_lib.py:228-260` + `:793-979`, `bin/nagent-distill:107-200`, `prompts/campaign-decompose.md`, `prompts/campaign-item.md`, `prompts/knowledge-merge.md`, `prompts/knowledge-graduate.md`, `prompts/create-readme.md:248-251`, `issues/0002-campaign-system.md`, `tests/test_nagent_campaign.py`, `tests/test_nagent_distill.py`). + +Identify the per-commit detail to add (per-commit sub-section). + +- [ ] **Step 2.3: Read Manual Slop subsystems for the implications section** + +For the Manual Slop implications sub-section, read: +- `conductor/tracks/` layout + the per-track `state.toml` + `metadata.json` + `spec.md`/`plan.md` structure +- `src/multi_agent_conductor.py` (the MMA WorkerPool) +- `src/app_controller.py` (the `_predefined_callbacks` / `_gettable_fields` Hook API registries — the closest analog to the campaigns abstraction) +- `conductor/code_styleguides/knowledge_artifacts.md` + +Cite file:line for each Manual Slop claim. + +- [ ] **Step 2.4: Design the sub-section structure** + +§1 Campaigns cluster gets 6 sub-sections: + +- §1.1 What Campaigns Adds (overview, 30-50 lines) +- §1.2 The Driver Phases (the 6-phase `update` command, 50-70 lines, code-shape sketch) +- §1.3 The Invariants (the 4 load-bearing rules, 40-60 lines) +- §1.4 Per-Commit Detail (the 6 commits, 80-120 lines) +- §1.5 Manual Slop Implications (2-3 paragraphs with citations, 50-80 lines) +- §1.6 Honest Gaps (≥6 bullets, 40-60 lines) +- §1.7 Code-Shape Sketch (survey grammar + SSDL, 30-50 lines) + +Plus the closing fields (Source-read citations: ≥30 entries; Decision candidate; Cross-refs). + +- [ ] **Step 2.5: Write the thickened §1** + +Replace the §1 section in `nagent_review_v3_20260619.md` with the 6-sub-section version following the template (per spec_v3.1.md §4.2). Verify the chunking strategy metrics: +- §1 total: 350-450 lines +- §1 sub-sections: 6 +- §1 source-read citations: ≥30 +- §1 honest gaps: ≥6 +- §1 Manual Slop implications: 2-3 paragraphs with file:line citations + +- [ ] **Step 2.6: Commit §1 thickening + git note** + +```bash +cd C:/projects/manual_slop +git add conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md \ + conductor/tracks/nagent_review_20260608/state.toml +git commit -m "conductor(track): nagent_review_v3.1 thicken §1 Campaigns cluster" +git notes add -m "Phase 2 complete. §1 Campaigns thickened from ~50 lines to lines. 6 sub-sections, source-read citations, honest gaps, 3 Manual Slop implications with file:line citations. Chunking strategy metrics met for §1." $(git log -1 --format='%H') +``` + +Update `state.toml`: `phase_2.status = "completed"`, `phase_2.checkpointsha = ""`. + +--- + +## Phase 3: Thicken §2 Conversation safety net cluster + +Focus: Expand §2 from ~60 lines to 350-450 lines. + +**Files:** +- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` (§2) +- Modify: `conductor/tracks/nagent_review_20260608/state.toml` + +**Source commits:** `38d3d4f`, `6426a67` (unchanged from v3) + +- [ ] **Step 3.1: Read v3's §2 in full + identify what's thin** +- [ ] **Step 3.2: Source-read the 2 commits + their files** (`bin/nagent:1455-1687` + `:1840-1881` + `:2463-2677` + `:2819`, `bin/helpers/nagent_distill_lib.py:587-654` + `:851-862`, `config.example.json:3-7`, `prompts/checkpoint-conversation.md`, `issues/0004-conversation-safety-net.md`, `tests/test_nagent_safety.py`) +- [ ] **Step 3.3: Read Manual Slop subsystems for implications** (`conductor/code_styleguides/error_handling.md`, `src/discussion.py` or similar for the discussion save path, `src/ai_client.py:run_discussion_compression`) +- [ ] **Step 3.4: Design sub-section structure** (6 sub-sections) +- [ ] **Step 3.5: Write the thickened §2** — verify chunking metrics +- [ ] **Step 3.6: Commit §2 thickening + git note** + +```bash +git commit -m "conductor(track): nagent_review_v3.1 thicken §2 Conversation safety net cluster" +git notes add -m "Phase 3 complete. §2 thickened from ~60 lines to lines. Chunking strategy metrics met for §2." $(git log -1 --format='%H') +``` + +--- + +## Phase 4: Thicken §3 Hooks cluster + +Focus: Expand §3 from ~60 lines to 350-450 lines. + +**Files:** +- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` (§3) +- Modify: `conductor/tracks/nagent_review_20260608/state.toml` + +**Source commits:** `a4fb141` (nagent) + both case-study repos (unchanged from v3) + +- [ ] **Step 4.1: Read v3's §3 in full + identify what's thin** +- [ ] **Step 4.2: Source-read the hooks commit + the case-study harness scripts** +- [ ] **Step 4.3: Read Manual Slop subsystems for implications** (`docs/guide_ai_client.md` Tier 4 QA, `docs/guide_api_hooks.md` ApiHookClient, `src/app_controller.py:_predefined_callbacks`) +- [ ] **Step 4.4: Design sub-section structure** (6 sub-sections including a deep sub-section on the case-study harness scripts) +- [ ] **Step 4.5: Write the thickened §3** — verify chunking metrics +- [ ] **Step 4.6: Commit §3 thickening + git note** + +```bash +git commit -m "conductor(track): nagent_review_v3.1 thicken §3 Hooks cluster" +git notes add -m "Phase 4 complete. §3 thickened from ~60 lines to lines. Hooks deep-dive + both case-study harness scripts cited. Chunking strategy metrics met for §3." $(git log -1 --format='%H') +``` + +--- + +## Phase 5: Thicken §4 Project-local roots cluster + +Focus: Expand §4 from ~50 lines to 300-400 lines. + +**Files:** +- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` (§4) +- Modify: `conductor/tracks/nagent_review_20260608/state.toml` + +**Source commits:** `54c8741`, `557dd39`, `0b9d1a2`, `023e23a` (unchanged from v3) + +- [ ] **Step 5.1: Read v3's §4 in full + identify what's thin** +- [ ] **Step 5.2: Source-read the 4 commits + their files** (`bin/helpers/nagent_cli.py:11-86` + `:109-141`, `bin/helpers/nagent_llm.py:55-72`, `bin/nagent:640-748` + `:2075-2295`, `.gitignore`) +- [ ] **Step 5.3: Read Manual Slop subsystems for implications** (`src/paths.py` for the path resolution pattern, `[conductor].dir` in `manual_slop.toml`, `tests/artifacts/` gitignore discipline) +- [ ] **Step 5.4: Design sub-section structure** (5 sub-sections) +- [ ] **Step 5.5: Write the thickened §4** — verify chunking metrics +- [ ] **Step 5.6: Commit §4 thickening + git note** + +```bash +git commit -m "conductor(track): nagent_review_v3.1 thicken §4 Project-local roots cluster" +git notes add -m "Phase 5 complete. §4 thickened from ~50 lines to lines. Chunking strategy metrics met for §4." $(git log -1 --format='%H') +``` + +--- + +## Phase 6: Thicken §5 Provider expansion cluster + +Focus: Expand §5 from ~50 lines to 300-400 lines. + +**Files:** +- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` (§5) +- Modify: `conductor/tracks/nagent_review_20260608/state.toml` + +**Source commits:** `bdfa2a6`, `5075f6e`, `2edc7ee` (unchanged from v3) + +- [ ] **Step 6.1: Read v3's §5 in full + identify what's thin** +- [ ] **Step 6.2: Source-read the 3 commits + their files** (Together provider implementation, `MODEL_CONTEXT_WINDOWS`, `model_context_window()`, `--list-providers` CLI flag, claude-code billing fix, spinner name change) +- [ ] **Step 6.3: Read Manual Slop subsystems for implications** (`src/ai_client.py` for the multi-provider pattern, `conductor/tech-stack.md` for the 8 providers, `docs/guide_ai_client.md` for the cache strategy) +- [ ] **Step 6.4: Design sub-section structure** (5 sub-sections including a table of the 6 providers with their context windows) +- [ ] **Step 6.5: Write the thickened §5** — verify chunking metrics +- [ ] **Step 6.6: Commit §5 thickening + git note** + +```bash +git commit -m "conductor(track): nagent_review_v3.1 thicken §5 Provider expansion cluster" +git notes add -m "Phase 6 complete. §5 thickened from ~50 lines to lines. 6 providers table + per-model context windows. Chunking strategy metrics met for §5." $(git log -1 --format='%H') +``` + +--- + +## Phase 7: Thicken §6 Delegation rewrite cluster + +Focus: Expand §6 from ~50 lines to 300-400 lines. + +**Files:** +- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` (§6) +- Modify: `conductor/tracks/nagent_review_20260608/state.toml` + +**Source commits:** `d56f0f0`, `65787a6`, `315fe9e` (unchanged from v3) + +- [ ] **Step 7.1: Read v3's §6 in full + identify what's thin** +- [ ] **Step 7.2: Source-read the 3 commits + their files** (the recursion bug, the fix, the context-isolation rationale, the test fixup) +- [ ] **Step 7.3: Read Manual Slop subsystems for implications** (`src/multi_agent_conductor.py` MMA WorkerPool, `scripts/mma_exec.py` delegation, `docs/guide_mma.md`) +- [ ] **Step 7.4: Design sub-section structure** (5 sub-sections with a deep sub-section on the recursion bug) +- [ ] **Step 7.5: Write the thickened §6** — verify chunking metrics +- [ ] **Step 7.6: Commit §6 thickening + git note** + +```bash +git commit -m "conductor(track): nagent_review_v3.1 thicken §6 Delegation rewrite cluster" +git notes add -m "Phase 7 complete. §6 thickened from ~50 lines to lines. Recursion bug deep-dive + context-isolation rationale. Chunking strategy metrics met for §6." $(git log -1 --format='%H') +``` + +--- + +## Phase 8: Thicken §7 Robustness cluster + +Focus: Expand §7 from ~60 lines to 350-450 lines. + +**Files:** +- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` (§7) +- Modify: `conductor/tracks/nagent_review_20260608/state.toml` + +**Source commits:** `065168c`, `6b762da`, `12c35b7`, `49e07f3` (unchanged from v3) + +- [ ] **Step 8.1: Read v3's §7 in full + identify what's thin** +- [ ] **Step 8.2: Source-read the 4 commits + their files** (non-protocol tolerance, dedupe_nodes, shell-before-next ordering, per-conversation scratch) +- [ ] **Step 8.3: Read Manual Slop subsystems for implications** (`conductor/code_styleguides/error_handling.md`, `Result[T]` convention, `scripts/audit_exception_handling.py`) +- [ ] **Step 8.4: Design sub-section structure** (6 sub-sections, one per commit) +- [ ] **Step 8.5: Write the thickened §7** — verify chunking metrics +- [ ] **Step 8.6: Commit §7 thickening + git note** + +```bash +git commit -m "conductor(track): nagent_review_v3.1 thicken §7 Robustness cluster" +git notes add -m "Phase 8 complete. §7 thickened from ~60 lines to lines. 4 commits with per-commit sub-sections. Chunking strategy metrics met for §7." $(git log -1 --format='%H') +``` + +--- + +## Phase 9: Thicken §8 Operating rules cluster + +Focus: Expand §8 from ~60 lines to 300-400 lines. + +**Files:** +- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` (§8) +- Modify: `conductor/tracks/nagent_review_20260608/state.toml` + +**Source commits:** `a1f0680` (unchanged from v3) + +- [ ] **Step 9.1: Read v3's §8 in full + identify what's thin** +- [ ] **Step 9.2: Source-read the operating-rules commit + the full `data-oriented-design.md` file** (not just the diff) +- [ ] **Step 9.3: Read Manual Slop subsystems for implications** (`conductor/code_styleguides/data_oriented_design.md` — the project's derived styleguide; document the delta between nagent's file and the project's) +- [ ] **Step 9.4: Design sub-section structure** (5 sub-sections with a deep sub-section on the Q9 expansion) +- [ ] **Step 9.5: Write the thickened §8** — verify chunking metrics +- [ ] **Step 9.6: Commit §8 thickening + git note** + +```bash +git commit -m "conductor(track): nagent_review_v3.1 thicken §8 Operating rules cluster" +git notes add -m "Phase 9 complete. §8 thickened from ~60 lines to lines. Q9 expansion deep-dive. Chunking strategy metrics met for §8." $(git log -1 --format='%H') +``` + +--- + +## Phase 10: Thicken §9 Case-study methodology cluster + +Focus: Expand §9 from ~65 lines to 400-500 lines (deep-dive cluster). + +**Files:** +- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` (§9) +- Modify: `conductor/tracks/nagent_review_20260608/state.toml` + +**Source:** both `pep-copt` and `differentiable-collisions-optc` repos (unchanged from v3) + +- [ ] **Step 10.1: Read v3's §9 in full + identify what's thin** +- [ ] **Step 10.2: Source-read both case-study repos** (4 prompts in each + both harness scripts + both OPTIMIZATION-LOG.md files) +- [ ] **Step 10.3: Read Manual Slop subsystems for implications** (`conductor/code_styleguides/knowledge_artifacts.md`, `conductor/prompts/` if it exists, the project's own discussion history pattern) +- [ ] **Step 10.4: Design sub-section structure** (6 sub-sections including the 5-element pattern decomposition) +- [ ] **Step 10.5: Write the thickened §9** — verify chunking metrics +- [ ] **Step 10.6: Commit §9 thickening + git note** + +```bash +git commit -m "conductor(track): nagent_review_v3.1 thicken §9 Case-study methodology cluster" +git notes add -m "Phase 10 complete. §9 thickened from ~65 lines to lines. 5-element pattern decomposition deep-dive. Chunking strategy metrics met for §9." $(git log -1 --format='%H') +``` + +--- + +## Phase 11: Thicken §10 PEP case study cluster + +Focus: Expand §10 from ~50 lines to 400-500 lines (deep-dive cluster). + +**Files:** +- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` (§10) +- Modify: `conductor/tracks/nagent_review_20260608/state.toml` + +**Source:** `macton/pep-copt` (unchanged from v3) + +- [ ] **Step 11.1: Read v3's §10 in full + identify what's thin** +- [ ] **Step 11.2: Source-read the full pep-copt repo** (all 5 commits + README + OPTIMIZATION-LOG + 4 prompts + harness) +- [ ] **Step 11.3: Read Manual Slop subsystems for implications** (`conductor/code_styleguides/data_oriented_design.md` for the operating rules Acton applied) +- [ ] **Step 11.4: Design sub-section structure** (6 sub-sections including the per-image results table + the kept/rejected optimizations table + the size/speed frontier table) +- [ ] **Step 11.5: Write the thickened §10** — verify chunking metrics +- [ ] **Step 11.6: Commit §10 thickening + git note** + +```bash +git commit -m "conductor(track): nagent_review_v3.1 thicken §10 PEP case study cluster" +git notes add -m "Phase 11 complete. §10 thickened from ~50 lines to lines. Full per-image results + kept/rejected optimizations + size/speed frontier. Chunking strategy metrics met for §10." $(git log -1 --format='%H') +``` + +--- + +## Phase 12: Thicken §11 Collisions case study cluster + +Focus: Expand §11 from ~50 lines to 400-500 lines (deep-dive cluster). + +**Files:** +- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` (§11) +- Modify: `conductor/tracks/nagent_review_20260608/state.toml` + +**Source:** `macton/differentiable-collisions-optc` (unchanged from v3) + +- [ ] **Step 12.1: Read v3's §11 in full + identify what's thin** +- [ ] **Step 12.2: Source-read the full differentiable-collisions-optc repo** (all 5 commits + README + OPTIMIZATION-LOG + 4 prompts + harness + the cited arXiv paper) +- [ ] **Step 12.3: Read Manual Slop subsystems for implications** (`conductor/code_styleguides/data_oriented_design.md` for the operating rules Acton applied) +- [ ] **Step 12.4: Design sub-section structure** (6 sub-sections including the per-type specialization deep-dive + the match contract + the closed-form contact witnesses) +- [ ] **Step 12.5: Write the thickened §11** — verify chunking metrics +- [ ] **Step 12.6: Commit §11 thickening + git note** + +```bash +git commit -m "conductor(track): nagent_review_v3.1 thicken §11 Collisions case study cluster" +git notes add -m "Phase 12 complete. §11 thickened from ~50 lines to lines. Per-type specialization + match contract + closed-form contact witnesses. Chunking strategy metrics met for §11." $(git log -1 --format='%H') +``` + +--- + +## Phase 13: Write new sections §12-§14 + +Focus: Append the 3 new top-level sections to the main review. + +**Files:** +- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` (append §12, §13, §14) +- Modify: `conductor/tracks/nagent_review_20260608/state.toml` + +- [ ] **Step 13.1: Write §12 YAML avoidance (~200-300 lines)** + +Append the §12 section after §11. Follow the sub-section structure: +- §12.1 Where nagent uses YAML (catalog with file:line citations) +- §12.2 Why YAML is "do not adopt" for Manual Slop (4-5 reasons) +- §12.3 The markdown + custom DSL alternative (concrete proposal) +- §12.4 Cross-refs (intent_dsl_survey, superpowers_review, conductor/presets.py, conductor/personas.py) + +≥30 source-read citations. ≥6 honest gaps. 2-3 paragraphs of Manual Slop implications. + +- [ ] **Step 13.2: Write §13 Agent context-window observations (~200-300 lines)** + +Append §13. Sub-sections: +- §13.1 The warm-up + window + safe-zone numbers +- §13.2 nagent's enforcement (per-turn hooks + safety net + distill) +- §13.3 Manual Slop's partial mitigation (docs/ + conductor/ markdown navigation) +- §13.4 The shortcoming (agents forget/fail to read) +- §13.5 Decision candidate (Candidate 28: per-turn ground-truth hook) + +≥30 source-read citations. ≥6 honest gaps. 2-3 paragraphs of Manual Slop implications. + +- [ ] **Step 13.3: Write §14 Fine-tuning observations (~150-250 lines)** + +Append §14. Sub-sections: +- §14.1 The diagnosis (current models bottlenecked) +- §14.2 Together.ai as one noticed vendor +- §14.3 Prosumer fine-tuning vendor survey (the 6-vendor table) +- §14.4 Vendor analysis is out of scope for v3.1 + +≥20 source-read citations (fewer, since this is observational). ≥6 honest gaps. 2-3 paragraphs of Manual Slop implications (mostly the dataset-curation angle). + +- [ ] **Step 13.4: Commit §12-§14 + git note** + +```bash +cd C:/projects/manual_slop +git add conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md \ + conductor/tracks/nagent_review_20260608/state.toml +git commit -m "conductor(track): nagent_review_v3.1 §12-§14 new sections (YAML, agent context, fine-tuning)" +git notes add -m "Phase 13 complete. §12 YAML avoidance (~ lines), §13 Agent context-window observations (~ lines), §14 Fine-tuning observations (~ lines). Total new content: ~ lines. 3 new top-level sections appended to main review." $(git log -1 --format='%H') +``` + +--- + +## Phase 14: Refresh side artifacts + +Focus: Replace `comparison_table.md` + `decisions.md`; create `nagent_takeaways_v3_1_20260620.md`. Refresh the delta summary doc. + +**Files:** +- Replace: `conductor/tracks/nagent_review_20260608/comparison_table.md` +- Replace: `conductor/tracks/nagent_review_20260608/decisions.md` +- Create: `conductor/tracks/nagent_review_20260608/nagent_takeaways_v3_1_20260620.md` +- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_1_20260620.md` (fill in the summary with the actual thickened section LOC counts) + +- [ ] **Step 14.1: Write `comparison_table.md`** (target 100-130 lines) + +Per spec_v3.1.md §4.4.1. Includes 11 cluster rows + 3 new section rows + v2.3 update rows + sibling-review cross-refs. + +- [ ] **Step 14.2: Write `decisions.md`** (target 180-220 lines) + +Per spec_v3.1.md §4.4.2. Includes v2.3 → v3 → v3.1 status mapping at top + all 25-30 v3 candidates + 3-5 new v3.1 candidates (27-30). + +- [ ] **Step 14.3: Write `nagent_takeaways_v3_1_20260620.md`** (target ~150 LOC) + +Per spec_v3.1.md §4.4.3. 5-part structure: +1. TL;DR (1 paragraph) +2. Cross-reference table (~15 rows) +3. The new v3.1 candidates (3-5) +4. The v3 candidates v3.1 supersedes (0-2) +5. Sibling-review pointer (fable_review, intent_dsl_survey, superpowers_review, project files) + +- [ ] **Step 14.4: Update `nagent_review_v3_1_20260620.md` delta summary** + +Fill in the actual LOC counts for each cluster + the 3 new sections + the side artifact sizes. Reference the commits. + +- [ ] **Step 14.5: Commit Phase 14 + git note** + +```bash +git add conductor/tracks/nagent_review_20260608/comparison_table.md \ + conductor/tracks/nagent_review_20260608/decisions.md \ + conductor/tracks/nagent_review_20260608/nagent_takeaways_v3_1_20260620.md \ + conductor/tracks/nagent_review_20260608/nagent_review_v3_1_20260620.md \ + conductor/tracks/nagent_review_20260608/state.toml +git commit -m "conductor(track): nagent_review_v3.1 Phase 14 refresh side artifacts" +git notes add -m "Phase 14 complete. comparison_table.md ( rows), decisions.md ( candidates + status mapping), nagent_takeaways_v3_1_20260620.md ( LOC bridge), delta summary filled in." $(git log -1 --format='%H') +``` + +--- + +## Phase 15: Chunking-strategy + format-commitment verification + final + +Focus: Run the chunking-strategy + format-commitment verifications mechanically + final commit. + +**Files:** +- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` (only if verification reveals gaps) +- Modify: `conductor/tracks/nagent_review_20260608/state.toml` + +- [ ] **Step 15.1: Run chunking verification #1 (main review LOC floor)** + +```bash +cd C:/projects/manual_slop +wc -l conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md +``` + +Expected: ≥3,800 lines. + +- [ ] **Step 15.2: Run chunking verification #2 (per-cluster depth)** + +For each cluster §1-§11, count the lines in the section: + +```bash +# Example for §1 (Campaigns): extract lines between §1 and §2 markers +sed -n '/^## §1 Campaigns/,/^## §2 Conversation safety net/p' conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md | wc -l +``` + +Expected per cluster: +- §1: 350-450 lines +- §2: 350-450 lines +- §3: 350-450 lines +- §4: 300-400 lines +- §5: 300-400 lines +- §6: 300-400 lines +- §7: 350-450 lines +- §8: 300-400 lines +- §9: 400-500 lines (deep-dive) +- §10: 400-500 lines (deep-dive) +- §11: 400-500 lines (deep-dive) + +If a cluster is under the minimum, return to the relevant cluster phase and add depth. + +- [ ] **Step 15.3: Run chunking verification #3 (per-cluster sub-sections)** + +For each cluster, count `#### §N.x` headings: + +```bash +grep -cE '^#### §1\.' conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md +``` + +Expected: 4-7 sub-sections per cluster. + +- [ ] **Step 15.4: Run chunking verification #4 (per-cluster citations)** + +For each cluster, count file:line citations (file paths ending in `:L[0-9]+` or commit SHAs 7+ chars): + +```bash +# This is a heuristic; the per-cluster citation count is verified manually. +``` + +Expected: ≥30 per cluster. + +- [ ] **Step 15.5: Run chunking verification #5 (per-cluster honest gaps)** + +For each cluster, count bullet points under the "Honest gaps" sub-section. + +Expected: ≥6 per cluster. + +- [ ] **Step 15.6: Run chunking verification #6 (Manual Slop implications)** + +Manual inspection per cluster. Expected: 2-3 paragraphs with Manual Slop file:line citations. + +- [ ] **Step 15.7: Run format verification #7 (no JSON blocks)** + +```bash +grep -n '```json' conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md +``` + +Expected: no matches. + +- [ ] **Step 15.8: Run format verification #8 (7-column tables)** + +```bash +grep -c '^| Symbol |' conductor/tracks/nagent_review_20260608/comparison_table.md +``` + +Expected: ≥1. + +- [ ] **Step 15.9: Run format verification #9 (SSDL + survey grammar)** + +```bash +grep -nE '\{ssdl\}|name := value|for [a-z]+ \.\. [a-z]+|tape \{ |try \{ .* recover|sandbox \{ |audit msg|fuzzy \{ ' conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md +``` + +Expected: ≥1 of SSDL tags, ≥1 of survey grammar. + +- [ ] **Step 15.10: Run new-sections verification #10 (§12-§14 present)** + +```bash +grep -nE '^## §1[2-4]' conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md +``` + +Expected: 3 matches (§12, §13, §14). + +- [ ] **Step 15.11: Update `state.toml` v3.1_verification fields** + +Set all `[v3_1_verification]` fields to `true` if verification passed. Set to `false` for any that did not pass; the next iteration must address them. + +- [ ] **Step 15.12: Final commit + git note + state update** + +```bash +cd C:/projects/manual_slop +git add conductor/tracks/nagent_review_20260608/state.toml +git commit -m "conductor(track): nagent_review_v3.1 Phase 15 chunking-strategy + format-commitment verification + final" +git notes add -m "Phase 15 complete. All 12 verifications passed. Main review: lines (>=3,800 floor). Per-cluster depth: . Format commitment: . §12-§14: . Side artifacts: . Track complete; ready for archive." $(git log -1 --format='%H') +``` + +Update `state.toml`: `phase_15.status = "completed"`, `phase_15.checkpointsha = ""`. + +- [ ] **Step 15.13: Standalone-readability verification** + +The load-bearing principle (per spec_v3.1.md §5.5): v3.1 must be readable by a reader who has never read v2.3 or v3. Verification: + +1. Open ONLY the v3.1 artifacts (no prior versions, no git history of prior versions): + - `nagent_review_v3_20260619.md` (the thickened main review) + - `comparison_table.md` (the v3.1 comparison table) + - `decisions.md` (the v3.1 candidate list) + - `nagent_takeaways_v3_1_20260620.md` (the v3.1 bridge doc) + - `nagent_review_v3_1_20260620.md` (the v3.1 delta summary) + +2. Read end-to-end. The reading must give a complete picture of: + - (a) What nagent is at `a1f0680` (the primary review subject) + - (b) What the case-study repos show (`pep-copt`, `differentiable-collisions-optc`) + - (c) What the 3 new observations (YAML avoidance, agent context-window, fine-tuning) imply for Manual Slop + +3. Specific checks: + - Does the §0 TL;DR open with a self-contained statement of what nagent is + what v3.1 covers? + - Does each cluster's "Pattern summary" field make sense without consulting v2.3? + - Does `decisions.md` introduce each candidate without requiring prior context? + - Do any cross-refs to v2.3 / v3 / v1 break the reading? (Cross-refs should be optional lineage context, not load-bearing.) + - Does the §12-§14 content stand on its own? + +4. If any check fails, return to the relevant phase and fix the dependency. The fix is typically one of: + - Add a self-contained explanation where the content assumed prior context + - Replace "Pattern(s) vs v2.3" with the self-contained "Pattern summary" + - Remove the v2.3 → v3 → v3.1 status mapping from `decisions.md` + - Add a TL;DR sentence that opens with self-contained context + +- [ ] **Step 15.14: Track status update** + +Per `conductor/workflow.md` §"State.toml Template", set: + +```toml +[meta] +status = "completed" # was "active" +``` + +Commit this final state update: + +```bash +git add conductor/tracks/nagent_review_20260608/state.toml +git commit -m "conductor(track): nagent_review_v3.1 marked completed" +``` + +The track is now ready for archive. + +--- + +## Self-Review + +This is the inline self-review per the writing-plans skill. + +### 1. Spec coverage + +Each spec_v3.1.md requirement maps to a plan task: + +| Spec section | Plan coverage | +|---|---| +| §1.1 artifact table | Phase 1 (skeleton) + Phases 2-12 (cluster thickening) + Phase 13 (new sections) + Phase 14 (side artifact refresh) | +| §2 Current State Audit | Implicit baseline; not re-listed | +| §3 Goals | Each goal maps to a phase (goal 1-3 = phases 2-12, goal 4 = phase 13) | +| §4.1 chunking strategy | "The Chunking Strategy" section + Phase 15 verification | +| §4.2 sub-section template | Each cluster phase uses the template | +| §4.3.1 §12 YAML avoidance | Phase 13 (Step 13.1) | +| §4.3.2 §13 Agent context-window | Phase 13 (Step 13.2) | +| §4.3.3 §14 Fine-tuning | Phase 13 (Step 13.3) | +| §4.4 side artifacts | Phase 14 (Steps 14.1-14.4) | +| §4.5 cross-references | Per-cluster phases + Phase 13 + Phase 14 (in bridge doc) | +| §5.1 format commitment | Phase 15 verifications #7-#9 | +| §5.2 authoring tier | Plan-wide (Tier 1 sole-authored, per plan header) | +| §5.3 filename convention | Plan-wide (consistent `20260620` for new files, v3 filename preserved for thickening) | +| §5.4 track-state hygiene | Phase 1 (state.toml init) + each phase's commit (state.toml update) | +| §6 architecture reference | Implicit in the spec; not re-implemented in plan | +| §7 verification criteria (12) | Phase 15 (Steps 15.1-15.11) | +| §8 out of scope | Plan-wide (no candidate implementation, no sibling-review replication, no vendor analysis) | + +**No gaps detected.** + +### 2. Placeholder scan + +Searched the plan for: "TBD", "TODO", "implement later", "fill in details", "add appropriate", "similar to Task N". + +Found `` placeholders in the git note messages and verification step outputs — these are INTENDED. The Tier 1 author fills them with actual values when executing the phase. The git notes are templates; the actual numbers come from the source-read pass. + +No "TBD", "TODO", "implement later", "fill in details", "add appropriate", or "similar to Task N" markers found in the plan structure. + +### 3. Type consistency + +Type/name consistency checks: +- All `comparison_table.md` references match across phases (Phase 14 + Step 15.8). +- All `decisions.md` references match across phases (Phase 14). +- All `nagent_takeaways_v3_1_20260620.md` references match across phases (Phase 14). +- All `state.toml` `[v3_1_tasks]` keys (t1_1, t1_2, ...) and `[v3_1_phases]` keys (phase_1, ..., phase_15) match across phases. +- All `metadata.json` field names match (per spec_v3.1.md §1.1 and Step 1.1). +- All commit SHAs are referenced consistently (the 24 nagent SHAs + the 10 case-study commits are referenced in spec_v3.1.md §2.2 and used in the cluster phases). +- The chunking strategy metrics are consistent across §4.1, the per-phase tasks, and the Phase 15 verifications. + +**No type inconsistencies detected.** + +--- + +## Execution Handoff + +The plan is complete and saved to `conductor/tracks/nagent_review_20260608/plan_v3.1.md`. + +Per the project's conductor convention (per `conductor/workflow.md`): +- v3.1 is research-only (no `src/*.py` changes). +- Tier 1 Orchestrator sole-authored (mirrors v3, v2.3, and `fable_review_20260617`). +- 15 phases, 1 commit per phase (atomic rollback per phase). +- Git notes attached per commit. +- `state.toml` updated per phase. +- Chunking strategy metrics enforced via Phase 15 verifications. + +The Tier 1 author executes the plan in the current session (or in a follow-up session, per the user's preference). The "execution choice" prompt from the writing-plans skill (subagent-driven vs inline) does not apply for Tier 1 sole-authored research — the Tier 1 IS the inline executor. \ No newline at end of file diff --git a/conductor/tracks/nagent_review_20260608/spec_v3.1.md b/conductor/tracks/nagent_review_20260608/spec_v3.1.md new file mode 100644 index 00000000..6e7d339b --- /dev/null +++ b/conductor/tracks/nagent_review_20260608/spec_v3.1.md @@ -0,0 +1,468 @@ +# 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:** +**One-liner:** +**Pattern summary:** <1-2 sentence summary of the abstraction this cluster introduces, in nagent-internal terms (not "vs v2.3" terms)> + +#### §N.1 + + +#### §N.2 + + +... (4-7 sub-sections total) + +#### §N.x +<2-3 paragraphs, each with Manual Slop file:line citations> + +#### §N.x +<≥6 bullets> + +#### §N.x + + +**Source-read citations:** +- +- ... +(≥30 entries) + +**Decision candidate:** +**Cross-refs:** +**Pattern history (optional):** +``` + +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: + +```markdown +| 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. \ No newline at end of file