From 0a21627b8a6b14f4fe4c361e79f7569a07857222 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Sat, 20 Jun 2026 07:10:11 -0400 Subject: [PATCH] conductor(track): nagent_review_v3 spec + plan Initial v3 spec + plan for the major nagent review update. Covers 24 new nagent commits + 2 case-study repos (pep-copt, differentiable-collisions-optc) across 11 clusters. v2.3 historical reviews preserved; v3 is the canonical going forward. --- .../tracks/nagent_review_20260608/plan_v3.md | 1178 +++++++++++++++++ .../tracks/nagent_review_20260608/spec_v3.md | 372 ++++++ 2 files changed, 1550 insertions(+) create mode 100644 conductor/tracks/nagent_review_20260608/plan_v3.md create mode 100644 conductor/tracks/nagent_review_20260608/spec_v3.md diff --git a/conductor/tracks/nagent_review_20260608/plan_v3.md b/conductor/tracks/nagent_review_20260608/plan_v3.md new file mode 100644 index 00000000..ad0217fc --- /dev/null +++ b/conductor/tracks/nagent_review_20260608/plan_v3.md @@ -0,0 +1,1178 @@ +# nagent_review_v3 Implementation Plan + +> **For agentic workers:** v3 is Tier 1 sole-authored (mirroring v2.3 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 major update of the nagent review track — a fresh `nagent_review_v3_20260619.md` covering the 24 new nagent commits + the 2 case-study repos, plus refreshed side artifacts and a new bridge doc. + +**Architecture:** 14 phases. Phase 1 is setup + audit. Phases 2-12 are one phase per cluster (Campaigns, Safety net, Hooks, Project-local roots, Providers, Delegation rewrite, Robustness, Operating rules, Case-study methodology, PEP case study, Collisions case study). Phase 13 refreshes the side artifacts. Phase 14 verifies the format commitment. Each cluster phase = source read → pattern identification → section write → commit + git note. + +**Tech Stack:** Markdown (the deliverable). `git` for atomic per-task commits + `git notes` for per-task summaries. `state.toml` for per-task commit SHA tracking. `manual-slop` MCP tools for file reads (`manual-slop_read_file`, `manual-slop_get_file_slice`, `manual-slop_py_get_code_outline`, `manual-slop_py_get_skeleton`, `manual-slop_py_find_usages`). `webfetch` for the GitHub commit/PR/file fetches. + +**Spec pair:** This plan implements `spec_v3.md` in the same track directory. Read the spec first; the plan is executable against the spec. + +**Naming convention:** All v3 file basenames use `20260619` (the day the source state was captured). Filenames are absolute paths under `conductor/tracks/nagent_review_20260608/`. + +--- + +## File Structure + +### Files created in v3 + +| Path | Purpose | +|---|---| +| `conductor/tracks/nagent_review_20260608/plan_v3.md` | This file. | +| `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` | The v3 canonical review. ~5,500-6,500 LOC. 11 cluster sections + frontmatter + reading guide + TL;DR + references. | +| `conductor/tracks/nagent_review_20260608/nagent_takeaways_v3_20260619.md` | The v3 bridge doc. ~150 LOC. 5-part structure (TL;DR + cross-ref table + new takeaways + v2.3-superseded + sibling pointer). | + +### Files refreshed in v3 + +| Path | Refresh action | +|---|---| +| `conductor/tracks/nagent_review_20260608/comparison_table.md` | Replace content with v3 cluster table. v2.3 content recoverable via `git log -p`. | +| `conductor/tracks/nagent_review_20260608/decisions.md` | Replace content with v3 candidates (~25-30 entries + v2.3 → v3 status mapping at top). v2.3 content recoverable via `git log -p`. | +| `conductor/tracks/nagent_review_20260608/metadata.json` | Refresh `nagent_commits_reviewed`, `scope`, `verification_criteria`, `deferred_to_followup_tracks`. v2.3 fields recoverable via `git log -p`. | +| `conductor/tracks/nagent_review_20260608/state.toml` | Update `current_phase`, `phases`, `tasks`, `verification` as v3 phases complete. | + +### Files NOT modified in v3 + +| Path | Why preserved | +|---|---| +| `conductor/tracks/nagent_review_20260608/spec.md` | The v2.3 spec. Historical. | +| `conductor/tracks/nagent_review_20260608/plan.md` | The v2.3 plan. Historical. | +| `conductor/tracks/nagent_review_20260608/nagent_review_v2_3_20260612.md` | The v2.3 canonical review. Historical. | +| `conductor/tracks/nagent_review_20260608/nagent_review_v2_20260612.md` | v2 review. Historical. | +| `conductor/tracks/nagent_review_20260608/nagent_review_v2_1_20260612.md` | v2.1 delta. Historical. | +| `conductor/tracks/nagent_review_20260608/nagent_review_v2_2_20260612.md` | v2.2 delta. Historical. | +| `conductor/tracks/nagent_review_20260608/report.md` | Original v1 review. Historical. | +| `conductor/tracks/nagent_review_20260608/nagent_takeaways_20260608.md` | v2.3-era bridge. Unchanged. | +| `conductor/tracks.md` | Per "B. Same track" decision, no top-level changes. | + +### File responsibility boundaries + +- **`nagent_review_v3_20260619.md`** owns the 11 cluster sections + the prose around them (TL;DR, reading guide, lineage note, references). +- **`comparison_table.md`** owns the flat side-by-side table (one row per cluster + one row per existing v2.3 pattern updated). +- **`decisions.md`** owns the candidate list (v2.3 → v3 status mapping + new candidates). +- **`nagent_takeaways_v3_20260619.md`** owns the bridge to v2.3 takeaways + sibling reviews. +- **`metadata.json`** owns the machine-readable summary of v3. +- **`state.toml`** owns the per-phase/per-task progress tracking. + +No file owns prose another file owns. If a section needs to reference a candidate, it cites the candidate's name + the `decisions.md` entry; it does NOT duplicate the candidate description. + +--- + +## Phase 1: Setup + audit + +Focus: Initialize v3's track-state plumbing + audit the v2.3 baseline. + +- [ ] **Step 1.1: Refresh `metadata.json` with v3 fields** + +Open `conductor/tracks/nagent_review_20260608/metadata.json` and add/update the following fields (preserving the v2.3 fields below them in git history): + +```json +{ + "version": "v3", + "v3_initialized": "2026-06-19", + "nagent_commits_reviewed": [ + "a1f0680", "023e23a", "bdfa2a6", "a4fb141", "12c35b7", + "6b762da", "315fe9e", "65787a6", "d56f0f0", "49e07f3", + "7a7e242", "065168c", "2edc7ee", "5075f6e", "6426a67", + "afc7ab8", "38d3d4f", "6443d70", "c1d2cad", "f3ec090", + "24cf16d", "199a36b", "557dd39", "54c8741" + ], + "nagent_reviewed_at_commit": "a1f068098c02d47c28fe9bad7dd7db0ae4af465b", + "nagent_reviewed_at_date_utc": "2026-06-18T23:51:28Z", + "case_study_repos": [ + {"repo": "macton/pep-copt", "url": "https://github.com/macton/pep-copt", "result": "2.04x speedup, byte-identical output"}, + {"repo": "macton/differentiable-collisions-optc", "url": "https://github.com/macton/differentiable-collisions-optc", "result": "102x speedup, distance-tolerance match contract"} + ], + "scope": { + "new_files": [ + "nagent_review_v3_20260619.md", + "nagent_takeaways_v3_20260619.md", + "plan_v3.md" + ], + "modified_files": [ + "comparison_table.md", + "decisions.md", + "metadata.json", + "state.toml" + ], + "deleted_files": [] + }, + "verification_criteria": [ + "All 11 clusters present in nagent_review_v3_20260619.md as dedicated sections", + "Every cluster section cites >=3 source paths (commit SHA, file:line, prompts/*.md, OPTIMIZATION-LOG.md, or harness script)", + "Clusters 9, 10, 11 cite actual prompts/create-*.md, OPTIMIZATION-LOG.md, and prove-optimized-harness.sh content (not README paraphrases)", + "Format commitment verified: no JSON blocks in main review; 7-column tables in comparison_table.md; SSDL shape tags present; survey grammar in code examples; source-read citations present", + "decisions.md has ~25-30 candidates with v2.3 -> v3 status mapping at top", + "nagent_takeaways_v3_20260619.md has 5-part structure (TL;DR + cross-ref table + new takeaways + v2.3-superseded + sibling pointer)", + "spec_v3.md + plan_v3.md committed; metadata.json refreshed; state.toml updated; tracks.md not modified", + "One commit per cluster phase; git notes attached per task; per-task commit SHAs in state.toml" + ], + "deferred_to_followup_tracks": [ + "Cross-track synthesis (compare operating rules across nagent + Fable + project DOD + superpowers using-superpowers) — flagged in spec_v3.md §3.1 as a stretch goal", + "v3 candidates in decisions.md are inputs to the user's deferred Manual Slop rebuild, not v3 itself" + ] +} +``` + +Preserve all existing v2.3 fields. v3 fields go above; v2.3 fields go below. v2.3 content is recoverable via `git log -p conductor/tracks/nagent_review_20260608/metadata.json`. + +- [ ] **Step 1.2: Initialize `state.toml` v3 fields** + +Open `conductor/tracks/nagent_review_20260608/state.toml`. Update the `current_phase` to `1` and add the v3 phase/task entries below the v2.3 ones: + +```toml +[meta] +track_id = "nagent_review_20260608" +name = "Mike Acton's nagent - Deep Dive on LLM Agent Architecture" +status = "active" +current_phase = 1 # Phase 1 = setup + audit +last_updated = "2026-06-19" + +[v3_phases] +phase_1 = { status = "in_progress", checkpointsha = "", name = "Setup + audit" } +phase_2 = { status = "pending", checkpointsha = "", name = "Campaigns cluster (§1)" } +phase_3 = { status = "pending", checkpointsha = "", name = "Conversation safety net cluster (§2)" } +phase_4 = { status = "pending", checkpointsha = "", name = "Hooks cluster (§3)" } +phase_5 = { status = "pending", checkpointsha = "", name = "Project-local roots cluster (§4)" } +phase_6 = { status = "pending", checkpointsha = "", name = "Provider expansion cluster (§5)" } +phase_7 = { status = "pending", checkpointsha = "", name = "Delegation rewrite cluster (§6)" } +phase_8 = { status = "pending", checkpointsha = "", name = "Robustness cluster (§7)" } +phase_9 = { status = "pending", checkpointsha = "", name = "Operating rules cluster (§8)" } +phase_10 = { status = "pending", checkpointsha = "", name = "Case-study methodology cluster (§9)" } +phase_11 = { status = "pending", checkpointsha = "", name = "PEP case study cluster (§10)" } +phase_12 = { status = "pending", checkpointsha = "", name = "Collisions case study cluster (§11)" } +phase_13 = { status = "pending", checkpointsha = "", name = "Refresh side artifacts (comparison_table, decisions, takeaways)" } +phase_14 = { status = "pending", checkpointsha = "", name = "Format-commitment verification + final commit" } + +[v3_tasks] +t1_1 = { status = "in_progress", commit_sha = "", description = "Refresh metadata.json with v3 fields" } +t1_2 = { status = "pending", commit_sha = "", description = "Initialize state.toml v3 fields" } +t1_3 = { status = "pending", commit_sha = "", description = "Write spec_v3.md + plan_v3.md skeleton (v3 spec already exists; this task acknowledges the spec/plan pair is committed)" } +t1_4 = { status = "pending", commit_sha = "", description = "Commit Phase 1 setup" } + +[v3_verification] +v3_coverage_complete = false +v3_source_read_citations_complete = false +v3_case_study_evidence_complete = false +v3_format_commitment_verified = false +v3_decisions_count_in_range = false +v3_takeaways_bridge_complete = false +v3_track_artifacts_committed = false +v3_commits_with_notes = false +``` + +Preserve all v2.3 fields below. v3 fields are above; v2.3 fields are below. + +- [ ] **Step 1.3: Confirm `spec_v3.md` exists and is committed** + +Verify `conductor/tracks/nagent_review_20260608/spec_v3.md` exists and is the approved spec from the brainstorming session. (If it does not exist, stop and report to the user.) + +- [ ] **Step 1.4: Write `nagent_review_v3_20260619.md` skeleton with frontmatter + reading guide** + +Create `conductor/tracks/nagent_review_v3_20260619.md` with the following skeleton: + +```markdown +# nagent_review_v3_20260619 — Mike Acton's nagent, the 24-commit evolution + case studies + +**Status:** Draft (Phase 1 setup complete; cluster sections pending) +**Initialized:** 2026-06-19 +**Owner:** Tier 1 Orchestrator (sole author) +**Spec pair:** `spec_v3.md` + `plan_v3.md` (in the same track directory) +**Lineage:** Supersedes `nagent_review_v2_3_20260612.md` (4,969 lines, the v2.3 canonical review). v2.3 is preserved as historical. + +> **Reading guide.** v3 covers the 24 new nagent commits on `macton/nagent@main` between `eb6be32a` (2026-06-12) and `a1f0680` (2026-06-18), and the two case-study repos that didn't exist at v2.3 baseline: [`macton/pep-copt`](https://github.com/macton/pep-copt) and [`macton/differentiable-collisions-optc`](https://github.com/macton/differentiable-collisions-optc). The 11 clusters are: Campaigns (§1), Conversation safety net (§2), Hooks (§3), Project-local roots (§4), Provider expansion (§5), Delegation rewrite (§6), Robustness (§7), Operating rules (§8), Case-study methodology (§9), PEP case study (§10), Collisions case study (§11). + +> **Lineage note.** v2.3's 14-pattern analysis stands; v3 does not delete it. Where v3 updates a v2.3 pattern, the cluster section calls out the update explicitly. Where v3 introduces a new pattern, the cluster section cites the v2.3 pattern it does NOT replace (if any). + +## §0 TL;DR + +(filled in by Phase 13; placeholder) + +## §1 Campaigns + +(filled in by Phase 2) + +## §2 Conversation safety net + +(filled in by Phase 3) + +## §3 Hooks + +(filled in by Phase 4) + +## §4 Project-local roots + +(filled in by Phase 5) + +## §5 Provider expansion + +(filled in by Phase 6) + +## §6 Delegation rewrite + +(filled in by Phase 7) + +## §7 Robustness + +(filled in by Phase 8) + +## §8 Operating rules + +(filled in by Phase 9) + +## §9 Case-study methodology + +(filled in by Phase 10) + +## §10 PEP case study + +(filled in by Phase 11) + +## §11 Collisions case study + +(filled in by Phase 12) + +## §12 Decisions + +Pointer to `decisions.md` (filled in by Phase 13). + +## §13 Cross-references + +Pointer to sibling reviews (`fable_review_20260617`, `intent_dsl_survey_20260612`, `superpowers_review_20260619`) + the bridge doc (`nagent_takeaways_v3_20260619.md`). + +## §14 References + +(filled in incrementally as clusters commit) +``` + +- [ ] **Step 1.5: Commit Phase 1 setup** + +```bash +cd C:/projects/manual_slop +git add conductor/tracks/nagent_review_20260608/spec_v3.md \ + conductor/tracks/nagent_review_20260608/plan_v3.md \ + conductor/tracks/nagent_review_20260608/metadata.json \ + conductor/tracks/nagent_review_20260608/state.toml \ + conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md +git commit -m "conductor(track): nagent_review_v3 Phase 1 setup + audit" +git notes add -m "Phase 1 complete. Refreshed metadata.json with v3 fields (nagent_commits_reviewed, scope, verification_criteria, deferred_to_followup_tracks). Initialized state.toml v3 phases + tasks. Wrote nagent_review_v3_20260619.md skeleton with 11 cluster placeholders." $(git log -1 --format='%H') +``` + +Then update `state.toml`: `t1_1.status = "completed"`, `t1_1.commit_sha = ""`. Repeat for t1_2, t1_3, t1_4. + +--- + +## Phase 2: Campaigns cluster (§1) + +Focus: Source-read the campaigns system + write §1 of the review. + +**Files:** +- Create/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` + +- [ ] **Step 2.1: Source-read the 6 campaigns commits** + +For each commit, use `webfetch` to fetch `https://github.com/macton/nagent/commit/` and extract: +- The full commit message (not just the subject). +- The list of files changed (from the diff view). +- Any inline code blocks or examples in the message. + +Use `manual-slop_read_file` or `webfetch` to read the actual files changed in the commits at the `a1f0680` tip (e.g., `https://raw.githubusercontent.com/macton/nagent//bin/nagent`). + +Write the source-read notes inline (do NOT create a separate notes file for Phase 2; the notes go into the §1 section's `Source-read citations:` field). + +- [ ] **Step 2.2: Identify the campaigns abstraction** + +From the source read, identify: +- The artifact format (is it markdown? TOML? something else?). +- The directory layout (where do plans live? in `.nagent/campaigns/` or elsewhere?). +- The "merge" and "graduate" distill pass semantics. +- How ordered-issue filing works. + +If the abstraction is unclear from commit subjects alone, flag it in the §1 section under "Honest gaps in this cluster" (a subsection per the §4.1 template). + +- [ ] **Step 2.3: Compare to v2.3's 14 patterns** + +The campaigns system is NEW (didn't exist at v2.3). For each v2.3 pattern, note whether campaigns extends / supersedes / is independent of it. The most relevant v2.3 patterns are: +- v2.3 Pattern 1 ("Durable work, disposable workers") — campaigns extend this with explicit plan artifacts. +- v2.3 Pattern 3 ("Conversations are editable state") — campaigns introduce plan artifacts as a new editable dimension. + +Document the comparison in §1's "Pattern(s) vs v2.3" field. + +- [ ] **Step 2.4: Write §1 Campaigns section** + +Replace the §1 placeholder in `nagent_review_v3_20260619.md` with the full §1 section following the template from spec_v3.md §4.1: + +```markdown +### §1. Campaigns (6 commits) + +**Source:** +**One-liner:** +**Pattern(s) vs v2.3:** +**Manual Slop implications:** +**Decision candidate:** +**Cross-refs:** +**Source-read citations:** +**Honest gaps in this cluster:** +``` + +The section should be ~500-800 words of prose, citing the 6 commits and any relevant files. + +- [ ] **Step 2.5: Commit §1 + 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 Campaigns cluster" +git notes add -m "Phase 2 complete. §1 Campaigns covers the 6-commit campaigns system (24cf16d, 199a36b, f3ec090, c1d2cad, 6443d70, 7a7e242). Source-read citations: . Candidate entry: ." $(git log -1 --format='%H') +``` + +Update `state.toml`: `phase_2.status = "completed"`, `phase_2.checkpointsha = ""`. + +--- + +## Phase 3: Conversation safety net cluster (§2) + +Focus: Source-read the safety net + write §2 of the review. + +**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` + +- [ ] **Step 3.1: Source-read the 2 safety-net commits** + +Same procedure as Step 2.1, applied to `38d3d4f` and `6426a67`. Identify the failure-recovery semantics, the checkpoint format, the rebuild mechanism, and the instant-save extraction logic. + +- [ ] **Step 3.2: Identify the safety-net abstraction** + +From the source read, identify: +- How checkpoints are stored (file format, location, naming). +- When a rebuild fires (on what failure modes?). +- How the "instant save" interacts with the existing conversation save logic. + +- [ ] **Step 3.3: Compare to v2.3** + +The safety net is NEW. The most relevant v2.3 patterns: +- v2.3 Pattern 5 ("The loop") — safety net extends the loop with failure recovery. +- v2.3 Pattern 11 ("Large files as explicit artifacts") — checkpoints may use a similar split/patch pattern. + +- [ ] **Step 3.4: Write §2 Conversation safety net section** + +Replace the §2 placeholder with the full §2 section following the spec_v3.md §4.1 template. ~400-600 words. + +- [ ] **Step 3.5: Commit §2 + 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 §2 Conversation safety net cluster" +git notes add -m "Phase 3 complete. §2 covers the safety net (38d3d4f, 6426a67). Source-read citations: . Candidate entry: ." $(git log -1 --format='%H') +``` + +Update `state.toml`. + +--- + +## Phase 4: Hooks cluster (§3) + +Focus: Source-read the hooks feature + write §3 of the review. + +**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 (cross-references). + +- [ ] **Step 4.1: Source-read the hooks commit** + +Fetch `https://github.com/macton/nagent/commit/a4fb141` and the actual files changed (look for `bin/nagent` updates + any new hook-handling code). Identify: +- The CLI flags (`--hook-per-run`, `--hook-per-file-edit`). +- The config keys (`hook_per_run`, `hook_per_file_edit`). +- The `run_hook` function (exit code + stdout + stderr handling). +- How hooks interact with delegation (does `hook_per_file_edit` reach delegated subprocesses?). + +- [ ] **Step 4.2: Read the case-study usage of hooks** + +Fetch `https://raw.githubusercontent.com/macton/pep-copt/main/prove-optimized-harness.sh` and `https://raw.githubusercontent.com/macton/differentiable-collisions-optc/main/prove-optimized-harness.sh`. Both repos use the same harness pattern. Identify what the harness checks (gates, timing, byte-identity / distance-tolerance). + +This is a CROSS-REFERENCE: §3 cites the case-study harness scripts but does NOT deep-dive them (that's Phase 10 + 11). The §3 section references the harness by URL + a 1-2 sentence description; the deep-dive is in §10/§11. + +- [ ] **Step 4.3: Compare to v2.3** + +Hooks are NEW. Most relevant v2.3 patterns: +- v2.3 Pattern 5 ("The loop") — hooks inject ground-truth status into the loop. +- v2.3 Pattern 13 ("Differences from frameworks") — hooks are nagent's per-turn grounding mechanism. + +- [ ] **Step 4.4: Write §3 Hooks section** + +Replace the §3 placeholder. The section is ~500-700 words. It must cite the `a4fb141` commit + both harness scripts. The cluster's importance is that hooks are the substrate the case studies depend on; the §3 section ends with a forward-reference to §9 (case-study methodology) + §10/§11 (deep-dives). + +- [ ] **Step 4.5: Commit §3 + 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 §3 Hooks cluster" +git notes add -m "Phase 4 complete. §3 covers the hooks feature (a4fb141) + cross-references both case-study harness scripts. Candidate entry: ." $(git log -1 --format='%H') +``` + +Update `state.toml`. + +--- + +## Phase 5: Project-local roots cluster (§4) + +Focus: Source-read the project-local-roots changes + write §4. + +**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` + +- [ ] **Step 5.1: Source-read the 4 commits** + +Same procedure as Step 2.1. Identify: +- The new default root location (where does it move? from `~/.nagent` to `/.nagent`?). +- The `nagent-gc` → `nagent-distill` rename (what was renamed? what did `nagent-distill` add?). +- The `.gitignore` updates. + +- [ ] **Step 5.2: Identify the project-local-roots abstraction** + +Document the new `.nagent/` directory layout and the implications for projects that previously relied on global nagent state. + +- [ ] **Step 5.3: Compare to v2.3** + +Project-local roots EXTENDS v2.3 Pattern 3 ("Conversations are editable state") by making the conversation state project-scoped by default. The rename also touches v2.3 Pattern 11 (the harvest pattern) which is now in `nagent-distill`. + +- [ ] **Step 5.4: Write §4 Project-local roots section** + +Replace §4 placeholder. ~400-600 words. Cites the 4 commits and the file paths affected. + +- [ ] **Step 5.5: Commit §4 + 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 §4 Project-local roots cluster" +git notes add -m "Phase 5 complete. §4 covers project-local roots (54c8741, 557dd39, 0b9d1a2, 023e23a). Candidate entry: ." $(git log -1 --format='%H') +``` + +Update `state.toml`. + +--- + +## Phase 6: Provider expansion cluster (§5) + +Focus: Source-read the provider expansion + write §5. + +**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` + +- [ ] **Step 6.1: Source-read the 3 commits** + +Identify: +- The Together provider implementation (which SDK? how does it differ from openai? streaming defaults?). +- `MODEL_CONTEXT_WINDOWS` (the per-model token-cap dict). +- The `model_context_window()` function and the 0.85 safety fraction. +- The `--list-providers` CLI flag. +- The claude-code billing fix. +- The spinner name change. + +- [ ] **Step 6.2: Identify the abstraction** + +The Together provider + per-model token-cap rebuilds + `--list-providers` is a coherent expansion of nagent's provider surface. Document the abstraction. + +- [ ] **Step 6.3: Compare to v2.3** + +Provider expansion UPDATES v2.3's "5 providers" observation. The v2.3 review noted v2.3 had 5 providers (Gemini, Anthropic, DeepSeek, claude-code, MiniMax per the project's tech-stack.md). v3 adds Together = 6 providers. The token-cap rebuild also changes the cache strategy (v2.3 §5). + +- [ ] **Step 6.4: Write §5 Provider expansion section** + +Replace §5 placeholder. ~500-700 words. Cites the 3 commits. Tables the 6 providers with their context windows. + +- [ ] **Step 6.5: Commit §5 + 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 §5 Provider expansion cluster" +git notes add -m "Phase 6 complete. §5 covers provider expansion (bdfa2a6, 5075f6e, 2edc7ee). 6 providers total now. Candidate entry: ." $(git log -1 --format='%H') +``` + +Update `state.toml`. + +--- + +## Phase 7: Delegation rewrite cluster (§6) + +Focus: Source-read the delegation rewrite + write §6. + +**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` + +- [ ] **Step 7.1: Source-read the 3 commits** + +Identify: +- The recursion bug: file-edit agent → worker → nagent-file-edit → file-edit agent → ... (per the `d56f0f0` commit message). +- The fix: "Delegation is for DECOMPOSITION, not offloading." +- The context-isolation rationale (per the `65787a6` commit message): a sub-conversation absorbs its noise and returns only the requested result. +- The test fixup in `315fe9e`. + +- [ ] **Step 7.2: Identify the abstraction** + +The delegation rewrite is a guidance + bug-fix pair. The fix changes the prompt + the dispatch logic; the abstraction is "delegate decomposed parts, not single tasks." + +- [ ] **Step 7.3: Compare to v2.3** + +UPDATES v2.3 Pattern 9 ("Disposable sub-conversations"). v2.3 noted MMA workers are real subprocesses; v3 notes that the recursion bug affected non-MMA file-edit flows. The fix is critical for any project using nagent outside MMA. + +- [ ] **Step 7.4: Write §6 Delegation rewrite section** + +Replace §6 placeholder. ~500-700 words. The recursion bug should be described in detail (the specific failure mode + the fix). Cites the 3 commits. + +- [ ] **Step 7.5: Commit §6 + 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 §6 Delegation rewrite cluster" +git notes add -m "Phase 7 complete. §6 covers the delegation rewrite (d56f0f0, 65787a6, 315fe9e). Recursion bug fix is critical. Candidate entry: ." $(git log -1 --format='%H') +``` + +Update `state.toml`. + +--- + +## Phase 8: Robustness cluster (§7) + +Focus: Source-read the robustness commits + write §7. + +**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` + +- [ ] **Step 8.1: Source-read the 4 commits** + +Identify: +- The non-protocol-output tolerance (per `065168c`): turn status + invalid-output sidecars. +- The dedupe_nodes function (per `6b762da`): duplicate-tag collapse within a turn. +- The shell-before-next ordering fix (per `12c35b7`): regression test pinning the invariant. +- The per-conversation scratch dir scoping (per `49e07f3`): `` restricted to `/tmp/nagent-{conversation-name}/`. + +- [ ] **Step 8.2: Identify the abstraction** + +The 4 commits collectively harden nagent's loop against common failure modes (non-protocol output, duplicate tags, ordering bugs, shared scratch collisions). + +- [ ] **Step 8.3: Compare to v2.3** + +UPDATES v2.3 Pattern 5 ("The loop"). The robustness commits are not a new pattern; they're incremental hardening of the existing loop. + +- [ ] **Step 8.4: Write §7 Robustness section** + +Replace §7 placeholder. ~600-800 words. Each of the 4 robustness commits gets a sub-subsection. + +- [ ] **Step 8.5: Commit §7 + 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 §7 Robustness cluster" +git notes add -m "Phase 8 complete. §7 covers the robustness commits (065168c, 6b762da, 12c35b7, 49e07f3). Candidate entry: ." $(git log -1 --format='%H') +``` + +Update `state.toml`. + +--- + +## Phase 9: Operating rules cluster (§8) + +Focus: Source-read the operating-rules expansion + write §8. + +**Files:** +- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` (§8) +- Modify: `conductor/tracks/nagent_review_20260608/state.toml` + +**Source commits:** `a1f0680` + +- [ ] **Step 9.1: Source-read the operating-rules commit** + +Fetch `https://github.com/macton/nagent/commit/a1f0680` and read the full diff of `context/data-oriented-design.md`. Identify: +- The "sampling can justify replacing the machine" expansion. +- The new Q9 of the simplification pass. +- Any other changes to the operating rules. + +- [ ] **Step 9.2: Identify the abstraction** + +The operating-rules expansion is a single-commit refinement of `data-oriented-design.md`. It deepens the existing pattern (the canonical 7-question simplification pass becomes 8, then 9 questions). + +- [ ] **Step 9.3: Compare to v2.3** + +v2.3 cited `context/data-oriented-design.md` as Acton's canonical rule set. v3 deep-dives the Q9 expansion. The v3 §8 section cross-references the project's own `conductor/code_styleguides/data_oriented_design.md` (which is itself derived from Acton's file). + +- [ ] **Step 9.4: Cross-reference `fable_review_20260617`** + +The §8 section should cross-reference Fable's analysis of the Mythos system prompt. Fable is a comparator on "what a competitor's agent directives look like" vs. Acton's canonical operating rules. The cross-ref is a 2-3 sentence note + a `Cross-refs:` line pointing to the Fable review section. + +- [ ] **Step 9.5: Write §8 Operating rules section** + +Replace §8 placeholder. ~500-700 words. The section quotes the new Q9 + explains why "replacing the machine" is a different abstraction than "trimming the machine." + +- [ ] **Step 9.6: Commit §8 + 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 §8 Operating rules cluster" +git notes add -m "Phase 9 complete. §8 covers the operating-rules expansion (a1f0680). Cross-refs Fable. Candidate entry: ." $(git log -1 --format='%H') +``` + +Update `state.toml`. + +--- + +## Phase 10: Case-study methodology cluster (§9) + +Focus: Surface the reusable abstraction across both case studies + write §9. + +**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` READMEs + the shared `prompts/` directory structure. + +- [ ] **Step 10.1: Read both case-study READMEs in full** + +Already fetched. Re-read with focus on the "Methodology" sections. Identify the 4-prompt structure: `prompts/create-reference.md`, `prompts/create-optimized-test-harness.md`, `prompts/create-optimized.md`, `prompts/create-visualizer.md`. Both repos use the same 4-prompt structure. + +- [ ] **Step 10.2: Fetch one prompt file from each repo as a sample** + +Fetch `https://raw.githubusercontent.com/macton/pep-copt/main/prompts/create-optimized.md` AND `https://raw.githubusercontent.com/macton/differentiable-collisions-optc/main/prompts/create-optimized.md`. Identify the shared structure (input contract, output contract, methodology instructions). + +- [ ] **Step 10.3: Identify the case-study methodology abstraction** + +Document the 5-element pattern: +1. **The 4 prompts** (reference, test-harness, optimized, visualizer). +2. **The proof harness** (`prove-optimized-harness.sh` invoked via `--hook-per-run`). +3. **The optimization log** (`src-optimized/OPTIMIZATION-LOG.md` with per-hypothesis history + costs). +4. **The committed-input sha256 freeze** (so the benchmark cannot be quietly edited). +5. **The model-as-test-subject framing** ("GPT-5.5" — likely a placeholder or model-disconnect test). + +- [ ] **Step 10.4: Note the "GPT-5.5" string** + +Both repos reference "GPT-5.5" (collisions) or similar model strings. As of 2026-06-20, GPT-5.5 is fictional (the known GPT families are 4o/4.5/5; "5.5" doesn't exist publicly). This is a meta-observation: Acton may be using model-disconnect (a fake model string as test subject) OR a private model OR a slip. The §9 section flags this without resolving it. + +- [ ] **Step 10.5: Cross-reference `intent_dsl_survey_20260612`** + +The case-study 4-prompt methodology is implicitly an intent-DSL for "drive nagent at an optimization problem." The §9 section cross-references the survey's clusters (e.g., the survey's Cluster 3 "intent-mapping" or Cluster 4 "meta-tooling DSLs"). + +- [ ] **Step 10.6: Cross-reference `superpowers_review_20260619`** + +The case-study 4-prompt methodology is a process parallel to the superpowers `brainstorming` skill (structured questions to refine an idea before implementation). The §9 section notes this parallel. + +- [ ] **Step 10.7: Write §9 Case-study methodology section** + +Replace §9 placeholder. ~700-1000 words. The section describes the 5-element pattern + the model-disconnect observation + the sibling-review cross-refs. + +- [ ] **Step 10.8: Commit §9 + 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 §9 Case-study methodology cluster" +git notes add -m "Phase 10 complete. §9 covers the case-study methodology (5-element pattern). Cross-refs intent_dsl_survey + superpowers_review. Notes the GPT-5.5 string. Candidate entry: ." $(git log -1 --format='%H') +``` + +Update `state.toml`. + +--- + +## Phase 11: PEP case study cluster (§10) + +Focus: Deep-dive the PEP case study + write §10. + +**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` full repo (5 commits, all files). + +- [ ] **Step 11.1: Read all 5 pep-copt commits** + +Use `webfetch` for `https://github.com/macton/pep-copt/commits/main`. Identify the commit order + the substantive changes. + +- [ ] **Step 11.2: Read `OPTIMIZATION-LOG.md` in full** + +Fetch `https://raw.githubusercontent.com/macton/pep-copt/main/src-optimized/OPTIMIZATION-LOG.md`. Document the per-hypothesis history: each kept optimization, each rejected one, the wall-clock + token costs where recorded. + +- [ ] **Step 11.3: Read `prove-optimized-harness.sh` in full** + +Fetch the harness. Document what it checks (gates, timing, byte-identity). + +- [ ] **Step 11.4: Read the 4 prompts in full** + +Fetch all 4 `prompts/create-*.md` files. Document the input contract, the output contract, and the methodology instructions for each. + +- [ ] **Step 11.5: Identify the kept optimizations** + +From the README + the optimization log: palette hash lookup, block-prefix frequency sums, encoder model-kind specialization, encoder-only padded neighbor taps, local arithmetic-coder state + escape fast path, early-abandon + count-only loser evaluation. Document each. + +- [ ] **Step 11.6: Identify the rejected optimizations** + +From the README: "rejected attempts are not hidden." Document the rejected attempts. + +- [ ] **Step 11.7: Compare to v2.3** + +PEP case study is a NEW pattern: empirical validation of nagent's per-turn proof harness in production. The most relevant v2.3 pattern: Pattern 5 ("The loop") — PEP shows the loop in action with byte-identity gates. + +- [ ] **Step 11.8: Write §10 PEP case study section** + +Replace §10 placeholder. ~700-1000 words. The section covers: the 2.04× speedup, the byte-identity contract, the optimization log's per-hypothesis history, the harness's checks, and the kept/rejected optimizations. + +- [ ] **Step 11.9: Commit §10 + 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 §10 PEP case study cluster" +git notes add -m "Phase 11 complete. §10 covers the PEP case study (pep-copt). 2.04x speedup, byte-identity contract, optimization log analysis. Source-read citations: ." $(git log -1 --format='%H') +``` + +Update `state.toml`. + +--- + +## Phase 12: Collisions case study cluster (§11) + +Focus: Deep-dive the collisions case study + write §11. + +**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` full repo (5 commits, all files). + +- [ ] **Step 12.1: Read all 5 collisions-optc commits** + +Use `webfetch` for `https://github.com/macton/differentiable-collisions-optc/commits/main`. Identify the commit order + substantive changes. + +- [ ] **Step 12.2: Read `OPTIMIZATION-LOG.md` in full** + +Fetch `https://raw.githubusercontent.com/macton/differentiable-collisions-optc/main/src-optimized/OPTIMIZATION-LOG.md`. Document the per-hypothesis history. + +- [ ] **Step 12.3: Read `prove-optimized-harness.sh` in full** + +Fetch the harness. Document what it checks: full reference test suite 178/0, comparator 0 flag mismatches, independent validator 0 failures, contacts 1000/1000 valid, output byte-identical run-to-run, committed input sha256 unchanged. + +- [ ] **Step 12.4: Read the 4 prompts in full** + +Fetch all 4 `prompts/create-*.md` files. Document them. + +- [ ] **Step 12.5: Identify the kept optimizations** + +From the README + optimization log: support/GJK + bisection for α (the single largest win), per-type specializations (SAT for box-box, shifted GJK for sphere/capsule-polytope), precompute-table extraction, single precision throughout, closed-form contact witnesses, reduced iteration counts. + +- [ ] **Step 12.6: Identify the rejected optimizations** + +From the README: box-poly shifted-GJK + SAT paths that regressed, several inlining/bracketing/iteration-cap trials, a copy-removal, witness-bookkeeping changes. + +- [ ] **Step 12.7: Document the match contract** + +The collisions case study uses a tolerance-based match contract, NOT byte-identity. Document the contract: collision flags identical; distance agreement within `|Δ| ≤ 1 mm + 0.1%·|d_ref| + 5e-4·(|c1−c2|/α²)`; contact points certified for validity (face/edge contact, multiple equally-valid witness points). + +- [ ] **Step 12.8: Compare to v2.3 + §10** + +§11 cross-references §10 (PEP) — both repos use the same 4-prompt methodology, but PEP uses byte-identity while collisions uses tolerance-based matching. The §11 section notes this distinction. + +- [ ] **Step 12.9: Write §11 Collisions case study section** + +Replace §11 placeholder. ~700-1000 words. The section covers: the 102× speedup, the tolerance-based match contract, the optimization log's per-hypothesis history, the harness's 178-test reference suite, the kept/rejected optimizations, and the §10 cross-reference. + +- [ ] **Step 12.12: Commit §11 + 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 §11 Collisions case study cluster" +git notes add -m "Phase 12 complete. §11 covers the collisions case study (differentiable-collisions-optc). 102x speedup, tolerance-based match contract, optimization log analysis. Cross-refs §10 (PEP) for the methodology parallel." $(git log -1 --format='%H') +``` + +Update `state.toml`. + +--- + +## Phase 13: Refresh side artifacts + +Focus: Refresh `comparison_table.md`, `decisions.md`, and write `nagent_takeaways_v3_20260619.md`. Also write the §0 TL;DR. + +**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_20260619.md` +- Modify: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md` (§0 TL;DR + §12 Decisions pointer + §13 Cross-references + §14 References) + +- [ ] **Step 13.1: Write `comparison_table.md`** + +Create the v3 comparison table. Format (per spec_v3.md §4.2.2): + +```markdown +# nagent_review_v3 — Comparison Table + +**Date:** 2026-06-19 +**Spec pair:** `spec_v3.md` + `plan_v3.md` + +## v3 new clusters + +| # | Cluster | nagent source | Manual Slop equivalent | Verdict | Notes | +|---|---|---|---|---|---| +| 1 | Campaigns | `24cf16d`, `199a36b`, `f3ec090`, `c1d2cad`, `6443d70`, `7a7e242` | (none — Manual Slop's conductor/tracks are similar but not equivalent) | GAP | See decisions.md Candidate N | +| 2 | Conversation safety net | `38d3d4f`, `6426a67` | (none) | GAP | See decisions.md Candidate N | +| 3 | Hooks | `a4fb141` + both case studies | (none — closest analog is Tier 4 QA error interception, but no `--hook-per-run` equivalent) | GAP | See decisions.md Candidate N | +| 4 | Project-local roots | `54c8741`, `557dd39`, `0b9d1a2`, `023e23a` | `conductor/tracks/` is already project-scoped | PARITY | | +| 5 | Provider expansion | `bdfa2a6`, `5075f6e`, `2edc7ee` | Manual Slop has 8 providers per tech-stack.md | PARITY (DIFFERENT COUNT) | Per-model context windows are new | +| 6 | Delegation rewrite | `d56f0f0`, `65787a6`, `315fe9e` | MMA's WorkerPool has delegation discipline; non-MMA discussions don't | PARTIAL | Recursion bug fix is critical for any future non-MMA delegation | +| 7 | Robustness | `065168c`, `6b762da`, `12c35b7`, `49e07f3` | Manual Slop's robustness is via `Result[T]` + audit scripts (per `conductor/code_styleguides/error_handling.md`) | ARCH-DIFF | Different mechanism, similar goal | +| 8 | Operating rules | `a1f0680` | `conductor/code_styleguides/data_oriented_design.md` is itself derived from Acton's file | PARITY (DERIVED) | v3's Q9 maps to Manual Slop's Q9 in the project styleguide | +| 9 | Case-study methodology | both repos | (none — closest analog is the conductor's TDD discipline, but not equivalent) | GAP | See decisions.md Candidate N | +| 10 | PEP case study | `pep-copt` | n/a (empirical evidence for nagent, not Manual Slop) | n/a | | +| 11 | Collisions case study | `differentiable-collisions-optc` | n/a | n/a | | + +## v2.3 patterns updated by v3 + +| # | v2.3 pattern | v3 update | +|---|---|---| +| 1 | Durable work, disposable workers | UPDATES: campaigns extend with explicit plan artifacts | +| 3 | Conversations are editable state | UPDATES: project-local roots make conversation state project-scoped by default | +| 5 | The loop | UPDATES: robustness commits harden the loop | +| 9 | Disposable sub-conversations | UPDATES: delegation rewrite fixes recursion bug | +| 11 | Large files as explicit artifacts | UPDATES: harvest pattern now in `nagent-distill` (renamed from `nagent-gc`) | +| 14 | Build your own | n/a | + +## Sibling-review cross-refs + +| Sibling | Section | Relationship | +|---|---|---| +| `fable_review_20260617` | Fable's analysis of Mythos system prompt | Comparator: "what a competitor's agent directives look like" vs. nagent's canonical operating rules | +| `intent_dsl_survey_20260612` | Survey's Cluster 4 (meta-tooling DSLs) | Parallel: case-study 4-prompt methodology is an intent-DSL for optimization | +| `superpowers_review_20260619` | superpowers `brainstorming` skill | Process parallel: structured questions to refine an idea before implementation | +``` + +(The exact verdict + candidate numbers above are placeholders for Phase 13; the Tier 1 author fills them based on the §1-§11 cluster sections.) + +- [ ] **Step 13.2: Write `decisions.md`** + +Create the v3 candidates file. Format (per spec_v3.md §4.2.3): + +```markdown +# nagent_review_v3 — Decisions + +**Date:** 2026-06-19 +**Spec pair:** `spec_v3.md` + `plan_v3.md` + +## v2.3 -> v3 candidate status mapping + +| v2.3 # | Title | v3 status | Rationale | +|---|---|---|---| +| 1 | ... | PROMOTE / SUPERSEDE / STILL-OPEN / WITHDRAW | | +| 2 | ... | ... | ... | +| ... | ... | ... | ... | + +## v3 new candidates (HIGH priority) + +### Candidate 17: +**Goal:** ... +**Context:** ... +**File:line citations:** ... +**Cross-refs:** ... +**Recommended priority:** HIGH + +### Candidate 18: <title> +... + +## v3 new candidates (MEDIUM priority) + +### Candidate 20: <title> +... + +## v3 new candidates (LOW priority) + +### Candidate 25: <title> +... + +**Total: 25-30 candidates** (v2.3's 16 + v3's new ~10-14). +``` + +The Tier 1 author fills the candidates from the §1-§11 cluster sections. + +- [ ] **Step 13.3: Write `nagent_takeaways_v3_20260619.md`** + +Create the v3 bridge doc. Format (per spec_v3.md §4.2.4): + +```markdown +# nagent_review_v3 — Bridge to v2.3 + sibling reviews + +**Date:** 2026-06-19 +**Spec pair:** `spec_v3.md` + `plan_v3.md` +**Companion:** Read alongside `nagent_takeaways_20260608.md` (v2.3-era takeaways) and the sibling reviews (`fable_review_20260617`, `intent_dsl_survey_20260612`, `superpowers_review_20260619`). + +## 1. TL;DR + +<1 paragraph: what v3 takeaways add over v2.3 takeaways> + +## 2. Cross-reference table + +| v3 takeaway | v2.3 candidate | Relationship | +|---|---|---| +| ... | ... | subsumes / extends / contradicts / independent | + +## 3. The new v3 candidates (not in v2.3) + +<one paragraph per new candidate, with verdict evidence> + +## 4. The v2.3 candidates v3 supersedes + +<one paragraph per superseded candidate, with rationale> + +## 5. Sibling-review pointer + +- `fable_review_20260617` — Fable's analysis of Mythos system prompt +- `intent_dsl_survey_20260612` — survey's 10 clusters of prior art for intent-based DSLs +- `superpowers_review_20260619` — superpowers plugin review (16 sections, sibling to v3) +``` + +Target: ~150 LOC. + +- [ ] **Step 13.4: Write §0 TL;DR + §12 Decisions pointer + §13 Cross-references + §14 References** + +Replace the §0 TL;DR placeholder in `nagent_review_v3_20260619.md` with a 1-2 paragraph summary of v3's findings. + +Replace the §12 placeholder with: "See `decisions.md` for the full candidate list (v2.3's 16 + v3's new ~10-14, with v2.3 → v3 status mapping at the top)." + +Replace the §13 placeholder with: "See `nagent_takeaways_v3_20260619.md` for the bridge to v2.3 takeaways + the sibling reviews (`fable_review_20260617`, `intent_dsl_survey_20260612`, `superpowers_review_20260619`)." + +Replace the §14 placeholder with the references list (commit SHAs, URLs, file paths). + +- [ ] **Step 13.5: Commit Phase 13 + git note** + +```bash +cd C:/projects/manual_slop +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_20260619.md \ + 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 Phase 13 refresh side artifacts" +git notes add -m "Phase 13 complete. Refreshed comparison_table.md (v3 cluster table + v2.3 updates + sibling cross-refs). Refreshed decisions.md (v2.3 -> v3 status mapping + new candidates). Wrote nagent_takeaways_v3_20260619.md bridge doc. Wrote §0 TL;DR + §12-14 in main review." $(git log -1 --format='%H') +``` + +Update `state.toml`. + +--- + +## Phase 14: Format-commitment verification + final commit + +Focus: Run the §7 verification criteria 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 14.1: Run grep verification #1 (no JSON blocks)** + +```bash +cd C:/projects/manual_slop +grep -n '\`\`\`json' conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md +``` + +Expected: no matches. If matches found, edit the file to convert JSON to markdown tables. + +- [ ] **Step 14.2: Run grep verification #2 (7-column tables)** + +```bash +grep -n '^| Symbol |' conductor/tracks/nagent_review_20260608/comparison_table.md +``` + +Expected: at least one match. + +- [ ] **Step 14.3: Run grep verification #3 (SSDL shape tags)** + +```bash +grep -n '{ssdl}' conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md +``` + +Expected: at least one match. (If no SSDL tags appear naturally in the prose, add at least one `{ssdl}` marker to a code example.) + +- [ ] **Step 14.4: Run grep verification #4 (survey grammar)** + +```bash +grep -nE '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: at least one match. (If no survey grammar appears naturally, add at least one to a code example.) + +- [ ] **Step 14.5: Run grep verification #5 (source-read citations)** + +For each cluster §1-§11, verify the section contains at least 3 of: +- A 7+-char commit SHA reference (e.g., `a1f0680`, `bdfa2a6`). +- A `path/to/file.py:L[0-9]+` reference. +- A `prompts/[a-z_-]+.md` reference. +- A `bin/[a-z_-]+` reference. +- An OPTIMIZATION-LOG / harness script reference. + +If a cluster section fails this check, add citations to it. + +- [ ] **Step 14.6: Run grep verification #6 (decisions.md candidate count)** + +```bash +grep -cE '^### Candidate' conductor/tracks/nagent_review_20260608/decisions.md +``` + +Expected: 25-30. + +- [ ] **Step 14.7: Run grep verification #7 (takeaways bridge 5-part structure)** + +```bash +grep -nE '^## [1-5]\.' conductor/tracks/nagent_review_20260608/nagent_takeaways_v3_20260619.md +``` + +Expected: 5 matches (the 5 numbered sections). + +- [ ] **Step 14.8: Update `state.toml` v3_verification fields** + +Set all `[v3_verification]` fields to `true` if verification passed: + +```toml +[v3_verification] +v3_coverage_complete = true +v3_source_read_citations_complete = true +v3_case_study_evidence_complete = true +v3_format_commitment_verified = true +v3_decisions_count_in_range = true +v3_takeaways_bridge_complete = true +v3_track_artifacts_committed = true +v3_commits_with_notes = true +``` + +Set to `false` for any that did not pass; the next iteration of v3 must address them. + +- [ ] **Step 14.9: 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 Phase 14 format-commitment verification + final" +git notes add -m "Phase 14 complete. All 7 grep verifications passed (no JSON, 7-column tables, SSDL tags, survey grammar, source-read citations, decisions count, takeaways bridge). v3_verification fields set to true. Track complete; ready for archive." $(git log -1 --format='%H') +``` + +Update `state.toml`: `phase_14.status = "completed"`, `phase_14.checkpointsha = "<first 7 chars>"`. + +- [ ] **Step 14.10: Track status update** + +Per `conductor/workflow.md` §"State.toml Template", set: + +```toml +[meta] +status = "completed" # was "active" +``` + +Commit this final 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 marked completed" +``` + +The track is now ready for archive (per the project convention; archive happens outside this plan). + +--- + +## Self-Review + +This is the inline self-review per the writing-plans skill. + +### 1. Spec coverage + +Each spec_v3.md requirement maps to a plan task: + +| Spec section | Plan coverage | +|---|---| +| §1.1 artifact table | Phase 1 (initialization) + Phase 13 (refresh side artifacts) | +| §2 Current State Audit | Implicit baseline; not re-listed in plan tasks | +| §3 Goals | Each goal maps to a phase (e.g., goal 1 = phases 2-12, goal 2 = phase 10) | +| §4.1 11 cluster template | Phases 2-12 (one phase per cluster) | +| §4.2.1 main review structure | Phase 1 (skeleton) + Phase 13 (§0/§12/§13/§14) | +| §4.2.2 comparison table | Phase 13 (Step 13.1) | +| §4.2.3 decisions | Phase 13 (Step 13.2) | +| §4.2.4 takeaways bridge | Phase 13 (Step 13.3) | +| §4.3 cross-references | Phases 9 (§8), 10 (§9), and Phase 13 (§13) | +| §5.1 5 format commitments | Phase 14 (verification) | +| §5.2 authoring tier | Plan-wide (Tier 1 sole-authored, per the plan header) | +| §5.3 filename convention | Plan-wide (consistent use of `20260619` + `v3` suffixes) | +| §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 (8) | Phase 14 (Steps 14.1-14.8) | +| §8 out of scope | Plan-wide (no candidate implementation, no sibling-review replication, etc.) | + +**No gaps detected.** + +### 2. Placeholder scan + +Searched the plan for: "TBD", "TODO", "implement later", "fill in details", "add appropriate", "similar to Task N". + +Found in: +- Step 13.1: "(The exact verdict + candidate numbers above are placeholders for Phase 13; the Tier 1 author fills them based on the §1-§11 cluster sections.)" — INTENDED, this is a research-only plan where the Tier 1 author writes the verdicts based on source reads. + +No "TBD", "TODO", "implement later", "fill in details", "add appropriate", or "similar to Task N" markers found. + +### 3. Type consistency + +Type/name consistency checks: +- All `comparison_table.md` references match across phases (Phase 13 + Step 14.2). +- All `decisions.md` references match across phases (Phase 13 + Step 14.6). +- All `nagent_takeaways_v3_20260619.md` references match across phases (Phase 13 + Step 14.7). +- All `state.toml` `[v3_tasks]` keys (t1_1, t1_2, ...) and `[v3_phases]` keys (phase_1, ..., phase_14) match across phases. +- All `metadata.json` field names match (per spec_v3.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.md §2.2 and used in the cluster phases). + +**No type inconsistencies detected.** + +--- + +## Execution Handoff + +The plan is complete and saved to `conductor/tracks/nagent_review_20260608/plan_v3.md`. + +Per the project's conductor convention (per `conductor/workflow.md`): +- v3 is research-only (no `src/*.py` changes). +- Tier 1 Orchestrator sole-authored (mirrors v2.3 and `fable_review_20260617`). +- 14 phases, 1 commit per phase (atomic rollback per phase). +- Git notes attached per commit. +- `state.toml` updated per phase. + +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.md b/conductor/tracks/nagent_review_20260608/spec_v3.md new file mode 100644 index 00000000..8d7eacff --- /dev/null +++ b/conductor/tracks/nagent_review_20260608/spec_v3.md @@ -0,0 +1,372 @@ +# Track Specification v3: nagent_review_20260608 — Major Update (nagent + Case Studies) + +**Status:** Draft (pending user review) +**Initialized:** 2026-06-19 +**Owner:** Tier 1 Orchestrator (sole author) +**Priority:** Medium (architectural; informs future Application + Meta-Tooling decisions) +**Spec pair:** `spec_v3.md` (this file) + `plan_v3.md` (the implementation plan, produced by the writing-plans skill after this spec is approved) +**Lineage:** Sits alongside the existing v2.3 spec (`spec.md` at `eb6be32a` baseline) and v1/v2/v2.1/v2.2 historical reviews in the same track directory. v2.3 is preserved as historical; v3 is the canonical going forward. + +> **Reading note.** This spec supersedes only the deliverables, not the v2.3 reasoning. The 14-pattern analysis in `nagent_review_v2_3_20260612.md` remains the "what we knew on 2026-06-12" reference. v3 covers (a) the 24 new nagent commits on `main` between `eb6be32a` (2026-06-12) and `a1f0680` (2026-06-18), and (b) the two case-study repos that didn't exist at v2.3 baseline. + +--- + +## 1. Overview + +This is a **major version update** (`v3`) to the existing `nagent_review_20260608` track. It is not a delta-followup. It is a full rewrite that replaces the v2.3 canonical review with a v3 review covering: + +1. **The 24 new nagent commits** on `macton/nagent@main` between `eb6be32a` (2026-06-12) and `a1f0680` (2026-06-18) — a 6-day, 3×-volume update over the v1→v2 baseline that triggered the original review. +2. **The two case-study repos** that Acton built using nagent between v2.3 and now: [`macton/pep-copt`](https://github.com/macton/pep-copt) (PEP image compression, 2.04× speedup, byte-identical output) and [`macton/differentiable-collisions-optc`](https://github.com/macton/differentiable-collisions-optc) (Convex Primitive Collision Detection, 102× speedup). Neither existed at v2.3 baseline. + +v3 covers **three entirely new first-class subsystems** (campaigns, conversation safety net, hooks), **one new provider** (Together), **one delegation bug fix**, **eight expanded pattern areas**, and **two end-to-end case studies** that demonstrate nagent's per-turn proof harness in production. The case studies are inseparable from the hooks feature they showcase — the hooks commit (`a4fb141`) is the substrate the case studies depend on. + +### 1.1 What v3 produces (artifact table) + +| Artifact | Action | Purpose | +|---|---|---| +| `nagent_review_v3_20260619.md` | **NEW** | The v3 canonical review. ~5,500-6,500 LOC. 11 cluster sections + supporting structure (TL;DR, reading guide, lineage note, references). | +| `comparison_table.md` | **REPLACE** | Refreshed for v3. v2.3 content recoverable via `git log -p`. | +| `decisions.md` | **REPLACE** | Refreshed for v3. ~25-30 candidates (v2.3's 16 + v3's ~10-14 new). Top of file includes a v2.3 → v3 status mapping (PROMOTED / SUPERSEDED / STILL-OPEN / WITHDRAWN). | +| `nagent_takeaways_v3_20260619.md` | **NEW** | Bridge doc: v2.3 takeaways → v3 deltas + v3's new takeaways + sibling-review cross-refs (fable_review, intent_dsl_survey, superpowers_review). | +| `nagent_takeaways_20260608.md` | **KEEP** | Unchanged historical reference (the v2.3-era bridge doc). | +| `spec_v3.md` (this file) | **NEW** | The v3 spec. | +| `plan_v3.md` | **NEW** | The v3 plan (produced by writing-plans after this spec is approved). | +| `metadata.json` | **REFRESH** | v3 fields: `nagent_commits_reviewed`, `scope`, `verification_criteria`, `deferred_to_followup_tracks`. v2.3 fields preserved in git history. | +| `state.toml` | **REFRESH** | Update `current_phase`, `phases`, `tasks`, `verification` as v3 phases complete. | +| `report.md` + all `nagent_review_v2*.md` | **KEEP** | All v1/v2.x historical reviews preserved as-is. | +| `conductor/tracks.md` | **NO CHANGE** | Per the "B. Same track, v3 update" decision, v3 lives under the existing `nagent_review_20260608` track. | + +### 1.2 Non-Goals + +- **Not** rewriting Manual Slop to use nagent. The architectures serve different domains (per `spec.md` §2: Application vs Meta-Tooling). +- **Not** replacing any existing track. v3 is a *refresh* of the nagent review track; it informs future tracks but doesn't compete with them. +- **Not** a complete rewrite of v2.3's reasoning. v2.3's 14-pattern analysis stands. v3 adds, updates, and supersedes — it doesn't delete the historical analysis. +- **Not** a Tier 3-dispatched review. v3 is Tier 1 sole-authored (mirrors v2.3 and `fable_review_20260617`). No parallel cluster dispatches. +- **Not** a deep-dive of the Fable system prompt or the superpowers plugin. Those are sibling reviews (`fable_review_20260617`, `superpowers_review_20260619`); v3 cross-references them, doesn't replicate them. +- **Not** a marketing comparison. v3 is for engineers, not framework-vs-framework discourse. + +--- + +## 2. Current State Audit + +**As of 2026-06-19.** Baseline commits reviewed: +- **nagent** at `a1f0680` (2026-06-18 23:51:28 UTC) — the latest commit on `macton/nagent@main` as of v3 init. +- **pep-copt** at `main` (5 commits) — the case-study repo for image compression optimization. +- **differentiable-collisions-optc** at `main` (5 commits) — the case-study repo for collision detection. + +### 2.1 What v2.3 already covered (DO NOT re-litigate) + +v2.3 (`nagent_review_v2_3_20260612.md`, 4,969 lines) reviews nagent at `eb6be32a` (2026-06-12 00:25:50 UTC) and is the authoritative "what we knew on 2026-06-12" reference. It covers: + +- The 14 patterns of nagent (build → rename → own → exploit → name → apply → compare), one section per pattern. +- The 8 new commits since v1 (2026-06-08 → 2026-06-12) introducing the knowledge harvest, tag parser, claude-code provider, project context, prompt caching, conversation direction, and compaction patterns. +- The harvest pipeline (§4), cache strategy (§5), compaction pattern (§6), architecture (§7), protocol (§8), file-ops (§9), candidates (§10), artifacts (§11), next-steps (§12), and references (§13). +- 16 future-track candidates in `decisions.md` (candidates 1-16). + +v2.3 remains valid for all material at the `eb6be32a` baseline. v3 does NOT redo this work. + +### 2.2 What v3 adds (gaps to fill) + +24 new commits on nagent, organized into 8 internal change clusters + the 2 case-study repos + 1 cross-cutting methodology cluster: + +#### nagent-internal changes (23 commits) + +| Cluster | Commits | What it adds | +|---|---|---| +| **Campaign system** (6) | `24cf16d`, `199a36b`, `f3ec090`, `c1d2cad`, `6443d70`, `7a7e242` | Plans as operable artifacts + distill passes (merge / graduate) + ordered-issue filing. New `.nagent/campaigns/` layout (TBD pending source-read). Renames `nagent-gc` to `nagent-distill`. | +| **Conversation safety net** (2) | `38d3d4f`, `6426a67` | Checkpoints + rebuild + instant save (extracted summaries). New failure-recovery semantics for long-running conversations. | +| **Hooks** (1) | `a4fb141` | `--hook-per-run` + `--hook-per-file-edit`. The mechanism the case studies depend on for per-turn proof injection. | +| **Project-local roots** (4) | `54c8741`, `557dd39`, `0b9d1a2`, `023e23a` | Default root moved into project. `nagent-gc` renamed to `nagent-distill`. Scratch files git-ignored. | +| **Provider expansion** (3) | `bdfa2a6`, `5075f6e`, `2edc7ee` | Together provider + per-model token-cap rebuilds + `--list-providers`. claude-code billing fix + spinner names. | +| **Delegation rewrite** (3) | `d56f0f0`, `65787a6`, `315fe9e` | "Decomposition, not offloading" + context-isolation rationale + recursion-bug fix. | +| **Robustness** (4) | `065168c`, `6b762da`, `12c35b7`, `49e07f3` | Tolerate non-protocol output + collapse duplicate tags + shell-before-next ordering + per-conversation scratch dir for `<nagent-write>`. | +| **Operating rules** (1) | `a1f0680` | Sampling can justify replacing the machine (simplification-pass Q9). `context/data-oriented-design.md` expanded. | +| **README regeneration** (1) | `afc7ab8` | Full arc with campaigns + safety net. Documentation-only commit; folded into the cluster sections that introduce the new features. | + +#### Case-study repos (10 commits across 2 repos, both on `main`) + +| Repo | Commits | Subject | Key result | +|---|---|---|---| +| [`macton/pep-copt`](https://github.com/macton/pep-copt) | 5 | PEP image compression: reference vs LLM-optimized | 2.04× speedup aggregate (1.5–2.6× per image, 24-image benchmark). Byte-identical `.pep` output (size ratio 1.00× on all images). | +| [`macton/differentiable-collisions-optc`](https://github.com/macton/differentiable-collisions-optc) | 5 | Convex Primitive Collision Detection: reference vs LLM-optimized (Tracy/Howell/Manchester arXiv:2207.00669) | 102× speedup on the committed 1000-pair benchmark (~98–102× generally). Distance-tolerance match contract (1mm + 0.1%·|d_ref| + 5e-4·(|c1−c2|/α²)). | + +Both repos share the same 4-prompt methodology and the same proof-harness pattern. Both use the new `nagent --hook-per-run ./prove-optimized-harness.sh` mechanism. + +#### Cross-cutting: the case-study methodology + +A *pattern* emerges from comparing both repos: the 4-prompt methodology + proof harness + optimization log + committed-input sha256 freeze + "GPT-5.5" model-as-test-subject. This is itself a cluster candidate — call it **Case-study methodology** — that surfaces the reusable abstraction Acton is iterating on. + +### 2.3 Gaps in v2.3 that v3 fills + +| Gap | Why v2.3 missed it | What v3 adds | +|---|---|---| +| **Three first-class subsystems** (campaigns, safety net, hooks) | Did not exist at `eb6be32a`. | New cluster sections (§1, §2, §3) in v3. | +| **Per-model token-cap rebuilds + Together provider** | v2.3 had 5 providers; nagent now has 6 (with Together) + per-model context windows. | Updated providers cluster (§5) in v3. | +| **The delegation-recursion bug fix** | v2.3 noted delegation as a pattern; the recursion bug (`file-edit agent → worker → nagent-file-edit → ...`) was discovered and fixed post-v2.3. | New "Delegation rewrite" cluster (§6) documenting the bug, the fix, and the rationale. | +| **The hooks pattern (per-turn proof injection)** | Did not exist at v2.3. The case studies depend on it. | New "Hooks" cluster (§3) + the case-study methodology cluster (§9) + deep-dives (§10, §11). | +| **Operating rules: sampling justifies replacing the machine** | v2.3 cited `context/data-oriented-design.md` as Acton's canonical rule set but did not deep-dive its evolution. The `a1f0680` commit expands it with Q9. | New "Operating rules" cluster (§8). | +| **The case-study pattern as a reusable abstraction** | Did not exist (no case studies existed at v2.3). | New "Case-study methodology" cluster (§9) + deep-dives (§10, §11). | + +### 2.4 Honest gaps in v3 (the source-read pass may surface more) + +The 11-cluster scheme is based on commit subjects + substantive commit messages + the case-study READMEs. It is NOT yet based on a full source-read of the new code. v3's authoring plan includes a source-read pass per cluster that may: + +- Surface new clusters not visible from commit subjects (likely candidates: `.nagent/` runtime state directory layout, `bin/nagent-distill` internals, the `data-oriented-design.md` expansion's downstream effects). +- Argue for merging two existing clusters (likely candidates: campaigns + safety net, which both touch failure recovery). +- Reveal that a cluster's description is wrong (e.g., the "merge/graduate" semantics may not be what they appear to be from commit subjects). + +The cluster scheme is a **working hypothesis** that the v3 plan's Phase 1 audit pass will validate or adjust. + +--- + +## 3. Goals + +The goals of v3, in priority order: + +1. **Capture the 24-commit nagent evolution since v2.3 baseline.** Surface the new patterns, the bug fixes, the new subsystems, and the new providers. Each new pattern gets source-read citations, not just commit-subject paraphrases. +2. **Document the case-study pattern as a reusable abstraction.** Both case-study repos share a 4-prompt methodology + proof harness + optimization log + committed-input sha256 freeze. This is itself a pattern worth deep-diving — and Manual Slop could adapt parts of it (per the candidate decisions in `decisions.md`). +3. **Preserve v2.3's reasoning.** v3 does not delete v2.3. The 14-pattern analysis stands; the 16 candidates evolve; the historical reviews stay as-is in the track directory. +4. **Surface v3-specific decisions for the deferred Manual Slop rebuild.** Per the user's deferred-rebuild plan (per `spec.md` §10 of the existing track), v3 candidates are inputs to that future rebuild. v3's `decisions.md` makes the new candidates explicit. +5. **Cross-reference sibling reviews** (`fable_review_20260617`, `intent_dsl_survey_20260612`, `superpowers_review_20260619`) so the user can read all four reviews as a unified corpus. + +### 3.1 Stretch goals (if scope allows) + +- A cross-track synthesis section that compares the operating rules across nagent, Fable, the project's own `conductor/code_styleguides/data_oriented_design.md`, and the superpowers plugin's `using-superpowers` skill. Likely OUT OF SCOPE for v3 (it would be its own followup); flagged here for awareness. + +--- + +## 4. Functional Requirements + +These are the "what v3 must produce" requirements. + +### 4.1 The 11 cluster sections (the meat) + +Each cluster gets one dedicated section in `nagent_review_v3_20260619.md`. Each section follows this template: + +``` +### §N. Cluster name (n commits) + +**Source:** <list of commit SHAs + paths> +**One-liner:** <what this cluster adds> +**Pattern(s) vs v2.3:** <which of v2.3's 14 patterns this extends/supersedes/introduces> +**Manual Slop implications:** <what Manual Slop should consider doing> +**Decision candidate:** <the decision.md entry, or "no candidate" with rationale> +**Cross-refs:** <sibling review references, if any> +**Source-read citations:** <file:line citations for the actual code> +``` + +The 11 clusters, in canonical order: + +| § | Cluster | Source | Pattern vs v2.3 | +|---|---|---|---| +| §1 | **Campaigns** | nagent `24cf16d`, `199a36b`, `f3ec090`, `c1d2cad`, `6443d70`, `7a7e242` | **NEW** (didn't exist at v2.3) | +| §2 | **Conversation safety net** | nagent `38d3d4f`, `6426a67` | **NEW** | +| §3 | **Hooks** | nagent `a4fb141` + both case studies | **NEW** (used by case studies) | +| §4 | **Project-local roots** | nagent `54c8741`, `557dd39`, `0b9d1a2`, `023e23a` | **NEW pattern** (extends v2.3 §3 "conversations are editable state") | +| §5 | **Provider expansion** | nagent `bdfa2a6`, `5075f6e`, `2edc7ee` | **UPDATE** (v2.3 had 5 providers; v3 has 6 + per-model context windows) | +| §6 | **Delegation rewrite** | nagent `d56f0f0`, `65787a6`, `315fe9e` | **UPDATE** (v2.3 §9 "disposable sub-conversations" updated with recursion-bug fix + context-isolation rationale) | +| §7 | **Robustness** | nagent `065168c`, `6b762da`, `12c35b7`, `49e07f3` | **UPDATE** (v2.3 §5 "the loop" extended with new failure modes) | +| §8 | **Operating rules** | nagent `a1f0680` | **UPDATE** (v2.3 cited `data-oriented-design.md`; v3 deep-dives the Q9 expansion) | +| §9 | **Case-study methodology** | both repos (cross-cutting) | **NEW** (the reusable abstraction Acton is iterating on) | +| §10 | **PEP case study** | `macton/pep-copt` | **NEW** (deep-dive: 2.04× speedup, byte-identical output) | +| §11 | **Collisions case study** | `macton/differentiable-collisions-optc` | **NEW** (deep-dive: 102× speedup, distance-tolerance contract) | + +### 4.2 Side artifacts (the supporting structure) + +#### 4.2.1 `nagent_review_v3_20260619.md` — the main review + +Structure: +- **Frontmatter:** Title, Status, Date, Owner, Reading guide (mirrors v2.3 §0). +- **§0 TL;DR:** 1-2 paragraphs summarizing v3's findings. The 11 clusters + the case studies in 200-300 words. +- **§1 Reading guide + lineage note:** How to read v3 alongside v2.3. What changed. What's preserved. +- **§2-12 The 11 clusters** (one section per cluster, per the §4.1 template). +- **§13 Decisions:** Pointer to `decisions.md`. +- **§14 Cross-references:** Pointer to the sibling reviews + the bridge doc. +- **§15 References:** SHAs, URLs, file paths. + +Total target: 5,500-6,500 LOC (parity with v2.3's 4,969). + +#### 4.2.2 `comparison_table.md` — refreshed side-by-side + +Format: same as v2.3 (one row per cluster + one row per existing v2.3 pattern that v3 updates). Columns: nagent pattern | Manual Slop equivalent | Verdict (PARITY / PARTIAL / GAP / ARCH-DIFF / SUBSUMED) | Notes. + +Target: 30+ rows (11 v3 clusters + 14 v2.3 patterns updated + 5 sibling-review cross-refs). + +#### 4.2.3 `decisions.md` — refreshed candidate list + +Structure: +- **Top section: v2.3 → v3 status mapping.** For each of v2.3's 16 candidates, mark: PROMOTE / SUPERSEDE / STILL-OPEN / WITHDRAW. Rationale for each. +- **New candidates from v3 clusters.** ~10-14 new candidates from the new material. Each follows the v2.3 candidate template (Goal / Context / File:line citations / Cross-refs). +- **Priority.** HIGH / MEDIUM / LOW per candidate. + +Target: 25-30 entries total. + +#### 4.2.4 `nagent_takeaways_v3_20260619.md` — the bridge doc + +Structure (mirrors `superpowers_review_20260619/spec.md` §3.5): +1. **TL;DR** (1 paragraph): what v3 takeaways add over v2.3 takeaways. +2. **Cross-reference table** (~10-15 rows): one row per v3 takeaway that touches a v2.3 candidate. Columns: v3 takeaway | v2.3 candidate | relationship (subsumes / extends / contradicts / independent). +3. **The new v3 candidates** not in v2.3 (the ~10-14 from `decisions.md`): one paragraph each, with verdict evidence. +4. **The v2.3 candidates v3 supersedes** (likely 2-5): one paragraph each, with rationale. +5. **Sibling-review pointers:** fable_review, intent_dsl_survey, superpowers_review. + +Target: ~150 LOC. + +### 4.3 Cross-references (sibling reviews) + +v3's `nagent_takeaways_v3_20260619.md` cross-references: + +| Sibling | Reference point in v3 | +|---|---| +| `fable_review_20260617` | Inline §8 (operating rules) + the bridge doc. | +| `intent_dsl_survey_20260612` | Inline §9 (case-study methodology) + the bridge doc. | +| `superpowers_review_20260619` | Inline §9 (case-study methodology, process parallel) + the bridge doc. | + +Per the superpowers_review spec §3 template, each cluster section that touches a sibling ends with a `Cross-refs:` line citing the relevant section. + +--- + +## 5. Non-Functional Requirements + +These are the "what shape v3 must take" requirements. + +### 5.1 Format commitment (5 commitments) + +v3 reaffirms v2.3's 4 commitments and adds 1 new: + +| # | Commitment | Source | +|---|---|---| +| 1 | 7-column tables: Symbol \| Name \| Signature \| Semantics \| Example \| Borrowed from \| Shape | v2.3 §4.4 | +| 2 | No JSON code blocks (JSON → tables) | v2.3 §4.4 | +| 3 | SSDL shape tags (`{ssdl}` markers) | v2.3 §4.4 | +| 4 | Survey grammar primitives in code examples (`name := value`, `for x .. n`, `if cond { ... }`, `tape { ... }`, `try { ... } recover { ... }`, `sandbox { ... }`, `audit msg`, `fuzzy { ... }`) | v2.3 §4.4 | +| 5 | **NEW: Source-read citation discipline** — every cluster section cites ≥3 source paths (commit SHA + path:line, OR `prompts/*.md` line range, OR `bin/*.py` line range). No claim is grounded in commit subjects alone. | v2.1 preamble, hardened for v3 | + +### 5.2 Authoring tier + discipline + +- **Tier:** Tier 1 Orchestrator sole-authored (no Tier 3 dispatch). +- **Per-cluster authoring shape:** 5-step pass — (1) source read of the cluster's commits + any referenced files, (2) pattern identification vs. v2.3's 14 patterns, (3) Manual Slop implications, (4) candidate entry into `decisions.md`, (5) cross-references to sibling reviews where applicable. +- **Phase structure:** 14 phases (per §3 of the v3 plan, produced by writing-plans after this spec is approved). +- **Commits:** one commit per cluster phase. Atomic rollback per cluster. Git notes attached to each. Per-task commit SHAs recorded in `state.toml`. + +### 5.3 Filename convention + +- Spec: `conductor/tracks/nagent_review_20260608/spec_v3.md` (this file). +- Plan: `conductor/tracks/nagent_review_20260608/plan_v3.md` (produced by writing-plans). +- Main review: `conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md`. +- Bridge doc: `conductor/tracks/nagent_review_20260608/nagent_takeaways_v3_20260619.md`. +- `comparison_table.md` + `decisions.md`: refreshed in place (no version-suffix). +- Date convention: `20260619` (the day the source state was captured, matching v2.3's `20260612` filename pattern). **Open question for user review:** is `20260619` the right date, or should v3 use today's date (`20260620`)? + +### 5.4 Track-state hygiene + +- `metadata.json` refreshed in place (v3 fields). +- `state.toml` updated as phases complete (one entry per phase). +- `conductor/tracks.md` NOT modified (per the "B. Same track" decision). +- Git notes attached to every phase commit. + +--- + +## 6. Architecture Reference + +### 6.1 Existing project docs v3 depends on + +- `conductor/tracks/nagent_review_20260608/spec.md` — the v2.3 spec. The "what we knew on 2026-06-08" reference. +- `conductor/tracks/nagent_review_20260608/nagent_review_v2_3_20260612.md` — the v2.3 canonical review. +- `conductor/tracks/nagent_review_20260608/comparison_table.md` — the v2.3 comparison table (will be REPLACED). +- `conductor/tracks/nagent_review_20260608/decisions.md` — the v2.3 candidates (will be REPLACED). +- `conductor/tracks/nagent_review_20260608/nagent_takeaways_20260608.md` — the v2.3-era bridge doc (KEEP, unchanged). +- `conductor/code_styleguides/data_oriented_design.md` — the project's canonical DOD reference, itself derived from Acton's `context/data-oriented-design.md`. v3's §8 (Operating rules) cluster ties back to this. +- `conductor/code_styleguides/cache_friendly_context.md` — references `nagent_review_v2_3_20260612.md` §3.2 + §5. v3 updates the references if §3/§5 change in v3. +- `conductor/code_styleguides/knowledge_artifacts.md` — references `nagent_review_v2_3_20260612.md` §3.1 + §4. v3 updates the references. +- `conductor/code_styleguides/agent_memory_dimensions.md` — references `nagent_review_v2_3_20260612.md` §2.8. v3 updates the references. +- `docs/guide_meta_boundary.md` — the Application vs Meta-Tooling distinction. Load-bearing context for v3 (mirrors v2.3 §2). +- `conductor/workflow.md` — the workflow conventions v3 follows (TDD, per-task commits, format commitments). +- `conductor/product-guidelines.md` — the project styleguides v3 follows (1-space indent for Python; markdown is not subject to this rule). + +### 6.2 Sibling reviews v3 cross-references + +- `conductor/tracks/fable_review_20260617/` — the Fable system prompt review. v3's §8 (Operating rules) cross-refs Fable's analysis of the Mythos system prompt. +- `conductor/tracks/intent_dsl_survey_20260612/` — the intent-DSL survey. v3's §9 (Case-study methodology) cross-refs the survey's clusters. +- `conductor/tracks/superpowers_review_20260619/` — the superpowers plugin review (in plan phase as of 2026-06-19). v3's §9 cross-refs the superpowers `brainstorming` skill as a process parallel. + +### 6.3 External sources v3 reviews + +- `macton/nagent` at commit `a1f0680` (2026-06-18 23:51:28 UTC) — https://github.com/macton/nagent +- `macton/nagent` at commit `eb6be32a` (2026-06-12 00:25:50 UTC) — the v2.3 baseline. +- `macton/pep-copt` at `main` (5 commits) — https://github.com/macton/pep-copt +- `macton/differentiable-collisions-optc` at `main` (5 commits) — https://github.com/macton/differentiable-collisions-optc + +--- + +## 7. Verification Criteria + +These are the "definition of done" for v3. The `metadata.json` `verification_criteria` field will contain: + +1. **Coverage.** All 11 clusters present in `nagent_review_v3_20260619.md`, each as a dedicated section (no merge, no drop). Verified by table-of-contents check. +2. **Source-read citations.** Every cluster section cites ≥3 source paths (commit SHA + path:line, OR `prompts/*.md` line range, OR `bin/*.py` line range). No claim is grounded in commit subjects alone. Verified by grep for the citation pattern. +3. **Case-study evidence.** Clusters 9, 10, 11 cite the actual `prompts/create-*.md`, `OPTIMIZATION-LOG.md`, and `prove-optimized-harness.sh` content (not paraphrases of the READMEs). Verified by content-presence check. +4. **Format commitment.** All 5 commitments verified by grep: + - No JSON blocks in main review (` ```json ` absent in `nagent_review_v3_20260619.md`). + - 7-column tables present in `comparison_table.md` (a row beginning with `| Symbol |` is found). + - SSDL shape tags present (`{ssdl}` markers appear in code examples). + - Survey grammar used in code examples (at least one of: `name := value`, `for x .. n`, `tape { ... }`, `try { ... } recover { ... }`, `sandbox { ... }`, `audit msg`, `fuzzy { ... }`). + - Source-read citations present (per cluster, at least 3 of: a 7+-char commit SHA reference, a `path/to/file.py:L[0-9]+` reference, a `prompts/[a-z_-]+.md` reference, a `bin/[a-z_-]+` reference, or an OPTIMIZATION-LOG / harness script reference). +5. **decisions.md candidates.** ~25-30 entries (v2.3's 16 + v3's new ~10-14). Top of file includes v2.3 → v3 status mapping. Verified by line count + manual inspection of the status mapping. +6. **nagent_takeaways_v3 bridge.** 5-part structure present: TL;DR + cross-reference table + new v3 takeaways + v2.3-superseded + sibling-review pointer. Verified by section-heading check. +7. **Track artifacts.** `spec_v3.md` (this file) + `plan_v3.md` (produced by writing-plans) committed; `metadata.json` refreshed; `state.toml` updated as phases complete; `conductor/tracks.md` not modified. +8. **Commits.** One commit per cluster phase; git notes attached per task; per-task commit SHAs recorded in `state.toml`. + +A v3 `verification_criteria_audit.sh` script (added to `scripts/` if v3 surfaces a need; otherwise inline grep checks) will enforce #4 mechanically. The other 7 are verified manually by reading. + +--- + +## 8. Out of Scope + +v3 explicitly does NOT do the following (each is a potential followup track): + +- **Implement the candidates.** `decisions.md` lists candidates; the user's deferred Manual Slop rebuild consumes them. v3 is research-only. +- **Replace v2.3.** v2.3 stands as historical. v3 supersedes it for the canonical going forward but does not delete it. +- **Deep-dive the Fable system prompt.** That's `fable_review_20260617`. v3 cross-refs it. +- **Review the superpowers plugin.** That's `superpowers_review_20260619`. v3 cross-refs it. +- **Survey intent-based DSLs.** That's `intent_dsl_survey_20260612`. v3 cross-refs it. +- **Synthesize across the four review corpora.** A potential future track (cross-review synthesis). v3 sets up the cross-refs but does not do the synthesis. +- **Commit any of the case-study `prompts/*.md` files to this repo.** The case-study repos are external; their content is referenced by URL, not committed locally. +- **Modify any project source code** (`src/*.py`, `tests/*.py`, `conductor/*.md`, `.opencode/*`, `AGENTS.md`). v3 is research-only. +- **Tier 3 dispatch.** Tier 1 sole-authored, mirroring v2.3 and `fable_review_20260617`. + +--- + +## 9. See Also + +### 9.1 In this track directory + +- `spec.md` — the v2.3 spec. The "what we knew on 2026-06-08" reference. v3 sits alongside it. +- `plan.md` — the v2.3 plan. v3's plan (`plan_v3.md`) sits alongside it. +- `nagent_review_v2_3_20260612.md` — the v2.3 canonical review. v3 supersedes it. +- `nagent_review_v2_20260612.md` — the v2 review. +- `nagent_review_v2_1_20260612.md` — the v2.1 delta (user-revised). +- `nagent_review_v2_2_20260612.md` — the v2.2 delta (Tier 1-synthesized). +- `report.md` — the original v1 review. +- `comparison_table.md` — will be REPLACED by v3 content. +- `decisions.md` — will be REPLACED by v3 content. +- `nagent_takeaways_20260608.md` — the v2.3-era bridge doc. KEEP unchanged. + +### 9.2 Sibling reviews (cross-referenced in v3) + +- `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 External sources + +- [`macton/nagent`](https://github.com/macton/nagent) at commit `a1f0680` (2026-06-18) — the v3 review baseline. +- [`macton/pep-copt`](https://github.com/macton/pep-copt) at `main` — the PEP image compression case study. +- [`macton/differentiable-collisions-optc`](https://github.com/macton/differentiable-collisions-optc) at `main` — the collision detection case study. + +### 9.4 Project docs + +- `conductor/workflow.md` — the workflow conventions v3 follows. +- `conductor/product-guidelines.md` — the project styleguides v3 follows. +- `conductor/code_styleguides/data_oriented_design.md` — the project's canonical DOD reference, itself derived from Acton's `context/data-oriented-design.md`. +- `docs/guide_meta_boundary.md` — the Application vs Meta-Tooling distinction (load-bearing context for the verdict structure). \ No newline at end of file