conductor(track): nagent_review_v3 Phase 13 refresh side artifacts

conductor/tracks/nagent_review_20260608/comparison_table.md

@@ -1,79 +1,72 @@
-# nagent vs Manual Slop: Comparison Table
+# nagent_review_v3 — Comparison Table
 
-**Companion to:** `report.md`
-**Date:** 2026-06-08 (revised same day)
-**Source:** nagent v1.0.0 (read 2026-06-08)
+**Date:** 2026-06-19
+**Spec pair:** `spec_v3.md` + `plan_v3.md`
+**Companion:** `nagent_review_v3_20260619.md` (the v3 canonical review); `decisions.md` (v3 candidate list); `nagent_takeaways_v3_20260619.md` (bridge to v2.3 takeaways + sibling reviews).
+**Source:** nagent v3 (`a1f0680` on `macton/nagent@main`, 2026-06-18) + the two case-study repos at `main` (`macton/pep-copt`, `macton/differentiable-collisions-optc`).
 
-Flat side-by-side reference. One row per nagent principle. Verdicts and pitfalls are in `report.md`.
+Flat side-by-side reference. One row per v3 cluster + one row per v2.3 pattern that v3 updates. Verdicts and pitfalls are in `nagent_review_v3_20260619.md`.
 
 ---
 
 ## Legend
 
-- **Verdict values:** PARITY (same shape), PARITY+ (Manual Slop is stronger), PARITY- (nagent is stronger), PARTIAL (one half, not the other), GAP (Manual Slop lacks the feature), DOMAIN MISMATCH (different scope).
+- **Verdict values:** PARITY (same shape), PARITY+ (Manual Slop is stronger), PARITY- (nagent is stronger), PARTIAL (one half, not the other), GAP (Manual Slop lacks the feature), ARCH-DIFF (different architecture, both correct in their domain), SUBSUMED (consumed by a follow-up track).
 - **Domain tags:** APP = Application domain, MT = Meta-Tooling domain, BOTH.
+- **Cluster status:** NEW (didn't exist at v2.3), UPDATE (extends v2.3 pattern).
 
 ---
 
-| # | nagent Principle (verbatim summary) | nagent Mechanism | Manual Slop Equivalent | Verdict | Domain | Action |
+## v3 new clusters
+
+| # | Cluster | nagent source | Manual Slop equivalent | Verdict | Status | Domain |
 |---|---|---|---|---|---|---|
-| 1 | Durable work, disposable workers. The agent is not the thing; the data is the thing. | `bin/nagent` 700-line single-file loop, conversation is a text file | MMA workers are real subprocesses with Context Amnesia; **Application AI is long-lived by design** | **PARTIAL** | BOTH | Future-track: stateless `LLMClient` class (§15.4) |
-| 2 | Text in, text out. File in, text out is the smallest useful primitive. | `bin/nagent-llm-text` + `bin/helpers/nagent_llm.py` (4 providers) | `src/ai_client.py:send(...) -> str` (5 providers) | **PARITY** | BOTH | None |
-| 3 | Conversations are editable state. The conversation file is not chat history; it is working state. | `bin/nagent` exposes `--save/load/edit/summarize`; text files are user-editable (vim/cat/diff/cp the raw transcript) | Discussion Takes + branching + per-entry edit (A1-A7 in report §3) + discussion-level CRUD (B1-B11) + role management (B5) + UI snapshot undo/redo (C1-C5) | **PARITY (DIFFERENT FOCUS)** — Manual Slop edits abstracted typed entries (`disc_entries` is a `list[dict]` with role + content + ts + thinking_segments + usage). Both have comprehensive editing; Manual Slop's is more granular at the entry layer, nagent's is deeper at the raw-transcript layer. | APP | Future-track: optional raw-transcript persistence per Take (Candidate 10) |
-| 4 | Visible output protocol. Teach the model an output format; use a visible, parseable protocol. | `TAG_PATTERNS` regex list; `parse_response` strict; `MAX_FORMAT_RETRIES = 3` | Provider-native function calling (Gemini, Anthropic, etc.) | **ARCHITECTURAL DIFFERENCE** — Application's choice is correct (parallel tool calls, JSON mode) | BOTH | Future-track: intent-based DSL for Meta-Tooling calls |
-| 5 | The loop. Append, call, parse, act, append, repeat. | `bin/nagent:run_agent_loop()` 50 lines, single `while True` | Three parallel loops: `ai_client._send_*` (LLM), `ConductorEngine.run` (MMA), `WorkflowSimulator.run_discussion_turn_async` (App) | **PARITY** | BOTH | (Low priority) Future-track: extract a single `src/llm_loop.py:run_loop` |
-| 6 | Per-file memory. Each file gets its own persistent local memory. | `file_id_for_path` (st_dev:st_ino); `conversations/file-index-{pid}.json`; `nagent-file-edit` per-file subprocess | `FileItem` (path + view_mode + ast_mask + custom_slices); `ContextPreset` (saved set of FileItems); Structural File Editor | **PARITY (DIFFERENT KIND)** — Manual Slop's is *curation memory* (rich); nagent's is *conversation log memory* (plain text). Both real, both per-file, different optimization. | APP | Future-track: thin "last-investigation" log per file (Meta-Tooling-friendly) |
-| 7 | Repository history as data. Turn git history into editing context. | `git_file_history` + `summarize_new_file_commits` + `coedited_file_rows` + `format_file_history` | `_reread_file_items` (mtime-based, diff injection); git-linked discussion tracking in GUI; **no historical-context injection** | **PARTIAL** — diff injection is similar; historical-context injection is missing | APP | Future-track: `src/git_history.py` mirroring nagent's `file_edit_history_and_summary_block` |
-| 8 | Historical coupling & artifact neighborhoods. Files that change together are hints. | `coedited_file_rows` labels high/medium/low co-edit rate; guidance text "Use these files as hints. Do not edit unless the user request or evidence requires it." | None (closest: `py_get_hierarchy` is structural not historical) | **GAP** | APP | Future-track: `py_coedited_files` + `ts_c_coedited_files` MCP tools |
-| 9 | Disposable sub-conversations. Exploration creates noise; spawn disposable workers. | `<nagent-conversation>` tag spawns `nagent --invocation delegated` as subprocess; isolated conversation file; recursive token rollup | MMA Tier 3/4 workers (real subprocesses); **1:1 main discussion has no sub-conversation mechanism** | **PARITY for MMA; GAP for 1:1 discussions** | APP (and MT) | **USER-FLAGGED WANT**: Future-track `src/sub_conversation.py:SubConversationRunner` for 1:1 investigations |
-| 10 | Controlled writes. A loop that writes files needs explicit boundaries. Not a sandbox; just conventions. | `validate_write_path`: main mode → tmpdir only; file-edit mode → target or segments; rejected writes append `<nagent-write-result status="error">` | `mcp_client._is_allowed` (3-layer: allowlist + path validation + resolution gate); `run_powershell` requires GUI modal approval; PowerShell-only by default; 60s timeout + `taskkill` cleanup; optional Tier 4 QA | **PARITY+ (Manual Slop stronger)** — 3-layer security + HITL + sandbox is dramatically stricter than nagent's tmpdir check | APP (and MT) | None — current design is right |
-| 11 | Large files as explicit artifacts. Split, edit segments, patch. | `nagent-file-split` (11 langs, regex + line counts + brace/JSON/XML depth); `nagent-file-patch` (strict hash validation); `nagent-file-summarize` (per-segment + retry); 32 KB default; index.json with `source_path`, `sourcesha256`, `segments[]` | `aggregate.py:build_file_items` + `py_get_skeleton` (tree-sitter) + `ts_c_*_get_skeleton` (tree-sitter); `set_file_slice` / `edit_file` (mtime validation, not hash); `run_subagent_summarization` (in-process, no retry); `RAGEngine._chunk_code` (mtime-based, ChromaDB) | **PARITY (DIFFERENT MECHANISM)** — both have the insight; nagent uses per-language scoring functions + subprocess isolation + hash validation; Manual Slop uses tree-sitter + in-process + mtime validation | BOTH | Future-track: explicit `src/split_lib.py` + `src/patch_lib.py` mirroring nagent's design, with hash validation |
-| 12 | Tool discovery. Tool capability should be explicit data. | `collect_bin_tool_descriptions` runs each `bin/* --description`; auto-builds "Available tools:" block for initial context | None (45 tools in `mcp_client.py:dispatch` if/elif chain) | **GAP** — nagent's pattern is genuinely better; current dispatch is fine but not extensible | BOTH (especially MT) | Future-track: subsumed by `mcp_architecture_refactor_20260606` (sub-MCPs as self-describing modules) |
-| 13 | Differences from frameworks. The reframing table: memory→editable artifact, agent→temporary transformation function, context→explicit input data. | The philosophical frame | The applicable reframings: editable UI state, curated per-file memory, git history as data | **N/A** | BOTH | (Lens, not action) |
-| 14 | Build your own. 12-step buildable list. | The reference | Manual Slop has all 12, in different files, at different scale | **PARITY** | BOTH | (Checklist) |
+| 1 | Campaigns | `24cf16d`, `199a36b`, `f3ec090`, `c1d2cad`, `6443d70`, `7a7e242` | `conductor/tracks/` is project-scoped but plan.md is not operable | PARTIAL | NEW | BOTH |
+| 2 | Conversation safety net | `38d3d4f`, `6426a67` | No checkpoint/rebuild; no extracted-summary index | GAP | NEW | APP |
+| 3 | Hooks | `a4fb141` + both case-study harnesses | Tier 4 QA error interception is analogous; no per-run hook | PARTIAL | NEW | BOTH |
+| 4 | Project-local roots | `54c8741`, `557dd39`, `0b9d1a2`, `023e23a` | `conductor/tracks/` is already project-scoped; `[conductor].dir` per-project override | PARITY | NEW | BOTH |
+| 5 | Provider expansion | `bdfa2a6`, `5075f6e`, `2edc7ee` | Manual Slop has 8 providers (per tech-stack.md); per-model context windows new | PARITY (DIFFERENT COUNT) | UPDATE | APP |
+| 6 | Delegation rewrite | `d56f0f0`, `65787a6`, `315fe9e` | MMA WorkerPool disciplined; non-MMA recursion bug real | PARTIAL | UPDATE | APP |
+| 7 | Robustness | `065168c`, `6b762da`, `12c35b7`, `49e07f3` | Manual Slop uses `Result[T]` discipline + audit scripts (per `conductor/code_styleguides/error_handling.md`) | ARCH-DIFF | UPDATE | BOTH |
+| 8 | Operating rules | `a1f0680` | `conductor/code_styleguides/data_oriented_design.md` is derived from this file | PARITY (DERIVED) | UPDATE | BOTH |
+| 9 | Case-study methodology | both case-study repos (cross-cutting) | No equivalent yet | GAP | NEW | BOTH |
+| 10 | PEP case study | `macton/pep-copt` | n/a (empirical evidence for nagent, not Manual Slop) | n/a | NEW | n/a |
+| 11 | Collisions case study | `macton/differentiable-collisions-optc` | n/a | n/a | NEW | n/a |
 
 ---
 
-## The 6 Pitfalls (revised, after user-corrections)
+## v2.3 patterns updated by v3
 
-See `report.md §15` for full details. Quick reference:
-
-| # | Pitfall | Domain | Future-track | User flag? |
-|---|---|---|---|---|
-| 1 | No structured output protocol in Application AI (opaque function calling) | BOTH | Intent-based DSL for Meta-Tooling | Implicit ("intent based DSL to help with discovery") |
-| 2 | Provider-specific history in process globals (`_anthropic_history`, `_deepseek_history`, etc.) | APP | Stateless `LLMClient` class | No |
-| 3 | RAG is not "history as data" (fuzzy, not auditable) | APP | RAG pre-staging sub-conversation | **Yes** ("Would be cool to have a sub agent maybe prepare a rag chunks before I use them in a run") |
-| 4 | AI client is a stateful singleton with module-level globals (2,685-line file) | APP | Stateless `LLMClient` class (same as #2) | No |
-| 5 | No non-MMA disposable sub-conversations | APP (and MT) | `src/sub_conversation.py:SubConversationRunner` | **Yes** ("I probably want to add that for just 1:1 discussions where I use a sub-agent manually for specific points") |
-| 6 | Hard-coded tool discovery (45-tool if/elif chain) | BOTH | Subsumed by `mcp_architecture_refactor_20260606` | Implicit ("intent based DSL to help with discovery") |
-
-### Pitfalls removed by user-corrections
-
-- **(removed)** "Conversation state is buried in module-level globals" — overstated. Manual Slop has editable UI state (Takes, UISnapshot, ContextPreset); the lack of editable raw transcripts is a *different* design choice, not a gap. See `report.md §3`.
-- **(removed)** "No per-file memory" — overstated. Manual Slop *does* have per-file memory in the curation dimension (FileItem + ContextPreset + Fuzzy Anchors); what's missing is nagent's conversation-log dimension, which is a *different* optimization. See `report.md §6`.
+| # | v2.3 pattern | v3 update |
+|---|---|---|
+| 1 | Durable work, disposable workers | UPDATES: campaigns (§1) extend with explicit plan artifacts |
+| 3 | Conversations are editable state | UPDATES: project-local roots (§4) make conversation state project-scoped; hooks (§3) per-turn observability |
+| 4 | Visible output protocol | (no update in v3) |
+| 5 | The loop | UPDATES: safety net (§2) adds failure-recovery; robustness (§7) hardens 4 failure modes; hooks (§3) per-turn ground-truth |
+| 6 | Per-file memory | (no update in v3) |
+| 7 | Repository history as data | UPDATES: project-local roots (§4) make `.nagent/` commit-able |
+| 8 | Historical coupling & neighborhoods | (no update in v3) |
+| 9 | Disposable sub-conversations | UPDATES: delegation rewrite (§6) fixes recursion bug + names two reasons |
+| 11 | Large files as explicit artifacts | (no update in v3) |
+| 12 | Tool discovery | (no update in v3) |
+| 13 | Differences from frameworks | (no update in v3) |
+| 14 | Build your own | (no update in v3) |
 
 ---
 
-## Future-track candidates — priority list
+## Sibling-review cross-refs
 
-Ordered by user signal + implementation cost:
+| 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; Fable's watch-dogging is the anti-pattern of nagent's data-grounded operating rules (§8) |
+| `intent_dsl_survey_20260612` | Survey's Cluster 4 (meta-tooling DSLs) + Cluster 3 (intent-mapping) | Parallel: the 4-prompt case-study methodology (§9) is implicitly an intent-DSL for "drive nagent at an optimization problem" |
+| `superpowers_review_20260619` | superpowers `brainstorming` skill | Process parallel: structured questions to refine an idea before implementation, same role as the case-study 4 prompts |
 
-1. **`src/sub_conversation.py:SubConversationRunner`** — user-flagged as a want. Extract MMA's `mma_exec.py` pattern into a reusable App-callable class. Useful for 1:1 investigations. **High priority.** (Pitfall #5)
+---
 
-2. **RAG pre-staging via sub-conversation** — user-flagged as a want. A sub-agent pre-builds the RAG index for a planned run; the chunks become the discussion's starting memory. **High priority.** (Pitfall #3)
+## Honest notes
 
-3. **Stateless `LLMClient` class** — would unify Pitfall #2 and #4. Backwards-compatible with `ai_client.send()`. ~2-3 phases of careful refactor. **Medium priority.**
-
-4. **Intent-based DSL for Meta-Tooling tool calls** — user-noted as a want ("no where near that ideation yet"). **Low priority, research spike.**
-
-5. **Self-describing MCP tools (nagent §12 pattern)** — subsumed by `mcp_architecture_refactor_20260606`. **Low priority on its own.**
-
-6. **`src/git_history.py` for nagent §7 pattern** — historical context injection. **Medium priority, but only after #1-#2 are done.**
-
-7. **Per-file conversation log (nagent §6 conversation dimension)** — Meta-Tooling-friendly addition. **Low priority.**
-
-8. **`py_coedited_files` / `ts_c_coedited_files` MCP tools (nagent §8)** — small, contained. **Low priority.**
-
-9. **Explicit `src/split_lib.py` + `src/patch_lib.py` (nagent §11)** — only needed if very-large-file scenarios emerge. **Defer until needed.**
-
-10. **Optional raw-transcript persistence per Take (nagent §3 conversation dimension)** — niche. **Low priority.**
+- The v3 verdict for "Provider expansion" is PARITY (DIFFERENT COUNT) — Manual Slop has 8 providers per tech-stack.md (the qwen_llama_grok track adds 3 more); nagent v3 has 6 providers. The count is independent of the abstraction (per-model context windows, billing isolation, ground-truth harness).
+- The "Conversation safety net" GAP is the highest-value v3 candidate — the 3-number config (`checkpoint_interval_minutes`, `checkpoint_max_new_kb`, `rebuild_at_kb`) + the sync-checkpoint invariant are concrete patterns Manual Slop can adopt.
+- The "Case-study methodology" GAP is the methodology-level insight; the per-case-study sections (§10, §11) are the empirical evidence.
+- v3 candidates are in `decisions.md`; the bridge doc is `nagent_takeaways_v3_20260619.md`.