ed/manual_slop
Private
Public Access
0
0
Fork 0
Code Activity

conductor(track): nagent_review_v3 Phase 13 refresh side artifacts

Browse Source
This commit is contained in:
ed
2026-06-20 08:46:05 -04:00
parent dd10a6803b
commit e150088d24
4 changed files with 370 additions and 255 deletions
Download Patch File Download Diff File Expand all files Collapse all files
conductor/tracks/nagent_review_20260608/decisions.md
+110 -192
View File
@@ -1,286 +1,204 @@
# Future-Track Candidates: nagent Review Follow-ups
# nagent_review_v3 — Decisions
**Companion to:** `report.md` (deep-dive), `comparison_table.md` (flat reference), `nagent_takeaways_20260608.md` (actionable patterns)
**Date:** 2026-06-08
**Source:** nagent v1.0.0 deep-dive review (see `report.md`)
**Date:** 2026-06-19
**Spec pair:** `spec_v3.md` + `plan_v3.md`
**Companion:** `nagent_review_v3_20260619.md` (the v3 canonical review); `comparison_table.md` (v3 cluster table); `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`.
This document is the bridge from "what nagent teaches us" to "what Manual Slop should do about it." Each candidate is a *future* conductor track (not this one). The candidates are *not* committed — they emerge from the analysis but each is a separate scoping exercise.
**For an actionable, code-grounded read of these candidates** (with the "what to do today, not just the future track" framing), see `nagent_takeaways_20260608.md` — it maps each candidate to specific patterns, design constraints, and small UX wins that don't need a new track.
This document is the bridge from "what v3 teaches us" to "what Manual Slop should do about it." Each candidate is a *future* conductor track (not this one).
---
## Decision-making framework
## v2.3 → v3 candidate status mapping
For each candidate:
- **Why it matters** — what pitfall or capability gap does it address?
- **What it would do** — concrete description
- **Where it would live** — Application or Meta-Tooling
- **Dependency on existing tracks** — is anything already on the board?
- **Effort estimate** — small / medium / large
- **User signal** — has the user expressed want/don't-want/neutral?
- **Recommended priority** — high / medium / low
The candidates are listed in priority order, which factors user signal heaviest (the user is the product owner for the Application; the analysis is just a reference).
| v2.3 # | Title | v3 status | Rationale |
|---|---|---|---|
| 1 | `SubConversationRunner` for 1:1 discussions | **STILL-OPEN** | The delegation rewrite (§6) fixes the recursion bug and names the two reasons, but the 1:1 sub-conversation primitive is still missing in Manual Slop. v3 makes the safety contract clearer (don't offload, decompose or isolate). |
| 2 | RAG pre-staging via sub-conversation | **STILL-OPEN** | Depends on #1. v3 doesn't change the priority. |
| 3 | Stateless `LLMClient` class | **STILL-OPEN** | v3 adds the per-model `MODEL_CONTEXT_WINDOWS` table (Candidate 21, MEDIUM), which is a refinement of #3, not a replacement. |
| 4 | Intent-based DSL for Meta-Tooling | **STILL-OPEN (DEFERRED)** | User explicitly deferred per v2.3. v3 case-study methodology (§9) is a related but different pattern. |
| 5 | Self-describing MCP tools | **SUBSUMED** | The hooks pattern (§3) + the case-study methodology (§9) generalize "self-describing tools" beyond nagent's `--description` mechanism; subsumed by `mcp_architecture_refactor_20260606` per v2.3. |
| 6 | `src/git_history.py` (nagent §7) | **STILL-OPEN** | v3 doesn't change. Project-local roots (§4) makes `.nagent/` commit-able; the git-history-injection primitive is orthogonal. |
| 7 | Per-file conversation log (nagent §6) | **STILL-OPEN** | v3 doesn't change. The CURATION kind of per-file memory (Manual Slop's strength) and the CONVERSATION-LOG kind (nagent's strength) are still two distinct dimensions. |
| 8 | `py_/ts_c_coedited_files` MCP tools | **STILL-OPEN** | v3 doesn't change. |
| 9 | Explicit `src/split_lib.py` + `src/patch_lib.py` | **STILL-OPEN** | v3 doesn't change. |
| 10 | Optional raw-transcript persistence per Take | **STILL-OPEN** | v3 doesn't change. |
| 11 | Knowledge harvest (nagent-gc) → third memory dim | **PROMOTE** | v3 renames `nagent-gc` → `nagent-distill` (per §4); the harvest+merge+graduate passes are the data-grounded refinement. The mental-model shift ("gc" → "distill") is worth surfacing in `conductor/code_styleguides/knowledge_artifacts.md` (Candidate 20). |
| 12 | Cache TTL GUI controls (sub-candidate 12b) | **STILL-OPEN** | v3 doesn't change. Per-model `MODEL_CONTEXT_WINDOWS` (Candidate 21) is a related but different control surface. |
| 13 | Conversation compaction (--compact) | **STILL-OPEN** | v3 doesn't change. |
| 14 | Project context files (context.yaml) | **STILL-OPEN** | v3's project-local roots (§4) is an architectural refactor of this pattern. The 4-layer context resolution is the v3 refinement. |
| 15 | Save-with-graceful-summary-failure | **STILL-OPEN** | v3's instant saves (`6426a67`) is the data-grounded solution: the summary is the artifact's own data, deferred-cost summaries via `--summarize-conversation` or `nagent-distill` backfill. The graceful-failure mode is replaced by graceful-deferral. |
| 16 | AGENTS.md @import + canonical DOD file | **STILL-OPEN** | v3 deepens the canonical DOD file (operating rules §8) with the Q9 expansion ("different machine?"). Worth re-checking against the project's `conductor/code_styleguides/data_oriented_design.md`. |
---
## Candidate 1: `src/sub_conversation.py:SubConversationRunner`
## v3 new candidates (HIGH priority)
**User signal:** **EXPLICIT WANT** ("I probably want to add that for just 1:1 discussions where I use a sub-agent manually for specific points.")
### Candidate 17: Campaign-style plan-as-data for the conductor
**Why it matters.** nagent's §9 pattern (disposable sub-conversations via `<nagent-conversation>`) is the cleanest way to handle "investigate this without polluting the main discussion." Manual Slop has it for MMA (`mma_exec.py` is a real subprocess) but not for 1:1 discussions. The user is asking for this.
**Goal:** Add a `.conductor/campaigns/{slug}/` layout with `index.yaml` + per-task `task.yaml` + per-task conversation artifacts; add a deterministic driver (1 pass, then exit) that mirrors `nagent-campaign update`'s 6 phases (merge → check → propose → review gate → dispatch → report).
**What it would do.** A `SubConversationRunner` class that the App can call during a 1:1 discussion:
- `await runner.spawn(prompt: str, *, allowed_tools: list[str] = None, system_prompt: str = None) -> SubConversationResult`
- The runner spawns a fresh Python process (reusing the MMA pattern: `mma_exec.py` template with `--invocation user`, `--parent-conversation <active_discussion_id>`, isolated `~/.manual_slop/sub_conversations/<name>`)
- The sub-process runs to completion (or times out)
- Result returns: a concise artifact (the sub-agent's `<response>` block) + token usage + exit code
- The App inserts the result into the active discussion as a "User" role entry (so the parent LLM sees it on the next turn)
- Cleanup: sub-conversation folder is auto-archived after 7 days (consistent with `log_pruner.py`)
**Context:** v3 §1 introduces campaigns as a four-piece composition (artifact + driver + invariants + context surfaces) with four load-bearing invariants: one pass then exit; one writer for the tree; review gate not cap; schema is the whole schema. The conductor's `plan.md` is not operable today — the model's "what to do next" is re-made every turn. Making it operable is the same data-oriented move nagent made.
**Where it lives.** Application. Possibly Meta-Tooling too (the `scripts/` directory could use the same primitive).
**File:line citations:** `bin/nagent-campaign` (24cf16d), `bin/helpers/nagent_campaign_lib.py` (24cf16d), `issues/0002-campaign-system.md:1-326` (199a36b).
**Depends on.** None directly. Could leverage MMA's `mma_exec.py` as a starting template. The `public_api_migration_20260606` follow-up track is unrelated.
**Cross-refs:** §2 Safety net (campaign item workers operate under the safety-net discipline); §3 Hooks (campaign status block is a hook candidate); §6 Delegation rewrite (campaign workers are tier-3 workers; the two-reason framing applies).
**Effort.** **Medium.** 2-3 phases: (1) extract reusable subprocess skeleton from MMA, (2) add 1:1-specific context injection, (3) add GUI controls ("Investigate…" button, optional command-palette command).
**Recommended priority.** **HIGH** — user-flagged.
**Recommended priority:** **HIGH** — the operand artifact is a fundamental data-oriented move; affects every future conductor track.
---
## Candidate 2: RAG pre-staging via sub-conversation
### Candidate 18: Discussion-window safety net for Manual Slop
**User signal:** **EXPLICIT WANT** ("Would be cool to have a sub agent maybe prepare a rag chunks before I use them in a run.")
**Goal:** Adopt the checkpoint + rebuild pattern for the discussion history; backfill summary entries from the existing intent line; surface extracted-vs-llm provenance in the discussion index.
**Why it matters.** Manual Slop's RAG (`src/rag_engine.py`) indexes files on the fly at discussion start. For large projects, indexing can take 30+ seconds (per `tests/test_rag_phase4_stress.py`). The user wants a "prep" workflow: before starting a long discussion, fire off a sub-conversation that pre-indexes everything, so the discussion starts instantly.
**Context:** v3 §2 introduces a four-piece composition (trigger + writer + rebuild + provenance) with a critical invariant: rebuild runs a synchronous checkpoint first, and the writer's failure widens the tail instead of blocking. The 3-number config (`checkpoint_interval_minutes`, `checkpoint_max_new_kb`, `rebuild_at_kb`) is a model Manual Slop should follow.
This is also consistent with nagent's "data preparation is an explicit, visible step" philosophy (§1, §7). The RAG chunks are artifacts; preparing them is a transformation; the transformation can be a sub-conversation.
**File:line citations:** `bin/nagent:1455-1687` (38d3d4f), `bin/nagent:1840-1881` (6426a67), `bin/helpers/nagent_distill_lib.py:587-654` (6426a67), `config.example.json:3-7`.
**What it would do.** A "Pre-stage RAG" command in the GUI (or in `commands.py`):
- Spawns a sub-conversation with the prompt: "Index all files in [project] for RAG. Use the index_file tool on every file in the context. Report top-K queries at the end."
- The sub-conversation runs `rag_engine.index_file()` on each tracked file (uses the same `ChromaDB` backend, with mtime-based invalidation)
- Returns a concise summary: "Indexed N files. Top-K for 'execution clutch': [file1, file2, file3]."
- The main discussion starts with the index already warm; `RAGEngine.search()` is fast
**Cross-refs:** §3 Hooks (per-turn status is the input to the checkpoint writer); §8 Operating rules (the failure-as-data principle).
**Where it lives.** Application. The sub-conversation runner is the same primitive as Candidate 1; the staging logic is `RAGEngine` integration.
**Depends on.** Candidate 1 (sub-conversation runner). Could be done as a feature within Candidate 1's track.
**Effort.** **Small to medium.** The sub-conversation runner is the heavy lift (Candidate 1). The RAG-staging prompt is ~30 lines.
**Recommended priority.** **HIGH** — user-flagged; cheap given Candidate 1.
**Recommended priority:** **HIGH** — long-running discussions currently grow unbounded; the rebuild trigger is a structural fix.
---
## Candidate 3: Stateless `LLMClient` class
### Candidate 22: Tier 3 worker contract "decompose or isolate, never offload" for Manual Slop MMA
**Why it matters.** `src/ai_client.py` is 2,685 lines of stateful singleton with module-level globals for every provider's history. nagent's `bin/helpers/nagent_llm.py` is 300 lines of stateless dispatch. A refactor toward a stateless `LLMClient(provider, model, conversation)` class would:
**Goal:** Encode the two-reason delegation guidance as a Tier 3 worker system prompt prefix; add a test that asserts the prefix is present in the worker's initial context.
- Make `ai_client` parseable (no implicit state to track)
- Make tests deterministic (each test gets a fresh client)
- Enable conversation save/load (the `Conversation` object is the transcript)
- Enable provider switching without losing history
**Context:** v3 §6 fixes a recursion bug (file-edit agent → worker → nagent-file-edit → file-edit agent → ... hangs the tree) by naming the two reasons delegation is worth its cost: **decomposition** (the task is genuinely complex, with parts) and **context isolation** (the step is noisy, the result is small). "Don't offload a single small action whose result is no smaller than doing it yourself."
This is a *big* refactor but a high-leverage one. Pitfalls #2 and #4 are both solved.
**File:line citations:** `bin/nagent:666-673` + `:790-806` (65787a6), `tests/test_nagent.py:1689-1695` (315fe9e).
**What it would do.** A new `src/llm_client.py`:
```python
@dataclass
class Conversation:
messages: list[Message] # role + content + tool_calls + tool_results
metadata: dict
def to_dict(self) -> dict: ...
def from_dict(data: dict) -> Conversation: ...
def save(path: Path) -> None: ...
def load(path: Path) -> Conversation: ...
**Cross-refs:** §1 Campaigns (campaign item workers operate under this discipline); §2 Safety net (sub-conversations inherit the scoping); §10 + §11 case studies (sub-conversation isolation is what makes the case-study harnesses tractable).
class LLMClient:
def __init__(self, provider: str, model: str, api_key: str = None): ...
def send(self, conversation: Conversation, *, tools: list[Tool] = None) -> Conversation: ...
def stream_send(self, conversation: Conversation, *, tools: list[Tool] = None) -> Iterator[Event]: ...
```
Backwards-compat: `ai_client.send(...)` becomes a thin wrapper that constructs a default `Conversation` from the current state and calls the new class.
**Where it lives.** Application (the AI client is the Application's main AI entry point).
**Depends on.** The `data_oriented_error_handling_20260606` track is independent but related — both push toward the data-oriented principles. The `public_api_migration_20260606` follow-up track would benefit from the new `Conversation` class.
**Effort.** **Large.** 3-5 phases: (1) introduce `Conversation` dataclass, (2) per-provider `LLMClient.send`, (3) migration of existing `ai_client.send` callers, (4) deprecate module-level globals, (5) remove. ~2000+ lines of refactor.
**Recommended priority.** **MEDIUM.** High value, but the existing stateful singleton works. Defer until a concrete Application need forces it (e.g., the user wanting to save/replay conversations).
**Recommended priority:** **HIGH** — the recursion bug is real for any project using MMA outside the WorkerPool's disciplined delegation. The 315fe9e test-fix is also a useful precedent: agent's `test_*.py` for any user-facing prompt change must run the suite, not just `py_compile`.
---
## Candidate 4: Intent-based DSL for Meta-Tooling tool calls
## v3 new candidates (MEDIUM priority)
**User signal:** **EXPLICIT WANT** ("The tool use is kinda upfront, I want to add an intent based dsl to help with 'discovery' or combinatorics but no where near that ideation yet.")
### Candidate 19: Per-turn ground-truth hook for Manual Slop
**Why it matters.** nagent's §4 regex-tag protocol is more debuggable than Manual Slop's function-calling. The Meta-Tooling (the external agents that build the Application) could benefit from a more compact, inspectable tool-call format. The existing JSON function-calling format forces the user to read verbose `{"name": "...", "args": {...}}` blobs.
**Goal:** Add a per-turn hook primitive that runs a configured command (CLI > config > disabled) at the top of every `send_result()` and injects a `<hook-per-run>` block; honor the CLI > config > disabled precedence and the failing/quiet-hook-surfaces-output invariant.
**What it would do.** An intent-based DSL that the Meta-Tooling can use in its own work. Examples (per the user's "discovery" or "combinatorics" hint):
- `<read src/foo.py:MyClass.method>` — intent: read this symbol
- `<search "execution clutch">` — intent: semantic search the workspace
- `<edit src/foo.py:42-50:new code>` — intent: surgical line-range edit
- `<test tests/test_foo.py::test_bar>` — intent: run a specific test
- `<discover what calls X>` — intent: dependency trace
**Context:** v3 §3 introduces hooks as a three-piece composition (resolve + invoke + inject). The case-study harness scripts ARE the hooks: `prove-optimized-harness.sh` is the command wired into `--hook-per-run`. The model responds against measured state instead of its recollection.
These are read by the external agent (Gemini CLI, OpenCode), not by Manual Slop's Application AI. The Application's function-calling format stays the same (correct for its domain).
**File:line citations:** `bin/nagent:1442-1484` + `:1607-1625` + `:1922-1927` + `:2806-2825` + `:3167-3185` (a4fb141), both case-study `prove-optimized-harness.sh` scripts.
**Where it lives.** Meta-Tooling. Documented in `docs/`; taught via the conductor convention; the external agent emits the DSL, the bridge script (`cli_tool_bridge.py`) translates to actual `mcp_client.py` tool calls.
**Depends on.** None directly. The `mcp_architecture_refactor_20260606` may produce tools that are easier to call via DSL (atomic, composable).
**Effort.** **Research spike, not implementation.** The user said "no where near that ideation yet." This is a design exercise, not a code change.
**Recommended priority.** **LOW** — user explicitly deferred.
**Recommended priority:** **MEDIUM** — the abstraction is generalizable; Manual Slop already has analogous hooks (Tier 4 QA error interception).
---
## Candidate 5: Self-describing MCP tools (nagent §12 pattern)
### Candidate 20: Rename `nagent-gc` → `nagent-distill` in our documentation cross-references
**Why it matters.** Manual Slop's 45 MCP tools are dispatched by a flat if/elif in `mcp_client.py:dispatch`. Adding a tool requires edits in 4 places (dispatch, security allowlist, capability declaration, tests). nagent's `--description` self-describing executable pattern is more extensible: drop an executable, it auto-appears.
**Goal:** Documentation-only follow-up; surface the mental-model shift ("gc" → "distill") in the project's `conductor/code_styleguides/knowledge_artifacts.md`.
**What it would do.** Each sub-MCP (or each tool) emits a `--description` block on `--help`. The `dispatch` function introspects via `mcp_client.get_tool_schemas()` and includes the descriptions in the AI's initial context automatically.
**Context:** v3 §4 renames `nagent-gc` to `nagent-distill` (no compatibility alias). The new name encodes the operation's true semantic: knowledge becomes capability, gated by review. The merge/graduate passes are an explicit consequence.
**Where it lives.** Application (the dispatch layer). The Meta-Tooling already has self-describing (via `claude_tool_bridge.py`); this is the Application-side equivalent.
**File:line citations:** `bin/helpers/nagent_distill_lib.py:793-979` (f3ec090), `bin/nagent-distill:107-200` (f3ec090).
**Depends on.** The `mcp_architecture_refactor_20260606` is the natural place — the sub-MCPs would each be self-describing modules.
**Effort.** **Medium** (subsumed by mcp_architecture_refactor_20260606). Not a separate track.
**Recommended priority.** **LOW** — subsumed.
**Recommended priority:** **LOW** — documentation-only; no code change.
---
## Candidate 6: `src/git_history.py` (nagent §7 pattern)
### Candidate 21: Per-model token-cap awareness for Manual Slop `ai_client`
**Why it matters.** Manual Slop's `_reread_file_items` does current-content diff injection. nagent's `file_edit_history_and_summary_block` does *historical* content injection: `git log --follow <file>` per file, LLM-summarized, plus co-edit neighborhood. For "explain this file" questions, the LLM is meeting the file fresh — git history would give it crucial context (who touched it last, why, what's nearby).
**Goal:** Add `MODEL_CONTEXT_WINDOWS` table; rebuild fires on byte ceiling OR 0.85 of window; "don't guess" — omit rather than estimate.
**What it would do.** A `src/git_history.py:file_edit_history_and_summary_block(file_path, repo_root, provider, model, config_path, previous_initial_context=None) -> str` that:
- Calls `git log --follow --max-count=50 --date=short --format=...` per file
- Counts co-edited files per commit
- LLM-summarizes new commits (with cache for unchanged history)
- Renders a `{file-history}` block with editors, step-by-step, co-edited files, summarized commits
- Called from `aggregate.py:run` at discussion start, after the file is added to context
**Context:** v3 §5 introduces the verified-windows table (10 models verified against the Together API). Unknown models return `None` and fall back to byte-only behavior — not a guessed default. The 0.85 safety fraction is the data-oriented response to "model capability degrades under high context utilization, not just at the limit."
**Where it lives.** Application (it's part of the AI's initial context).
**File:line citations:** `bin/helpers/nagent_llm.py:54-77` + `:123-130` + `:198-279` + `:315-336` + `:381-400` (bdfa2a6), `config.example.json:7`.
**Depends on.** None directly. The `data_oriented_error_handling_20260606` is independent. The `rag_engine.py` already has a `sourcesha256` field and mtime-based invalidation — the same pattern.
**Effort.** **Medium.** 2 phases: (1) git history + co-edit, (2) LLM summarization with cache. ~300-500 lines.
**Recommended priority.** **MEDIUM** — high value, but only after Candidates 1-2 are done.
**Recommended priority:** **MEDIUM** — refines the existing `ai_client.send()` rebuild trigger with a per-model precision layer.
---
## Candidate 7: Per-file conversation log (nagent §6 conversation dimension)
### Candidate 23: Per-conversation scratch directory for Manual Slop dispatch_inference
**Why it matters.** Manual Slop's per-file memory is the *curation* kind. nagent's is the *conversation log* kind. The user has the curation already; the conversation log is missing. The user's correction made this clear: the two are *different optimizations*, not equivalent.
**Goal:** Adopt the `conversation_scratch_dir(conversation_name)` pattern; pre-create on session start; thread through the `<nagent-write>`-equivalent.
**What it would do.** A thin `~/.manual_slop/per_file/<file_id>.md` per file (file_id by `st_dev:st_ino` for stability across renames, like nagent). Updated each time a discussion references the file. Format:
```markdown
# src/foo.py (file_id: 12345:67890)
Last referenced: 2026-06-08T12:34:56 (Discussion: "refactor auth")
**Context:** v3 §7 introduces the per-conversation scratch dir as a hardening commit (`49e07f3`). Each instance gets its own directory keyed by conversation name; concurrent instances never collide in a shared `/tmp`.
## 2026-06-08T12:34:56 - "how does the validation work?"
AI response: ...
(User) followup: "what about edge cases?"
**File:line citations:** `bin/nagent:1319-1331` + `:1334-1341` + `:1344-1381` + `:1387-1394` + `:1534-1551` + `:1834-1840` + `:224-240` (49e07f3).
## 2026-06-05T... - "explain the parser"
AI response: ...
```
When the user opens a new discussion with the file in context, the per-file log is injected as a `{per-file-history}` block.
**Where it lives.** Application (the per-file log is the App's memory). The Meta-Tooling doesn't need this — sub-agent invocations are already short-lived.
**Depends on.** None. Could be added in a small follow-up to Candidate 3 (the `Conversation` object becomes the per-file log).
**Effort.** **Small** if done as a thin layer on top of the `Conversation` class. **Medium** if done before Candidate 3 (no `Conversation` object to leverage).
**Recommended priority.** **LOW** — niche, niche feature.
**Recommended priority:** **MEDIUM** — small change with a structural payoff (concurrent dispatch safety).
---
## Candidate 8: `py_coedited_files` / `ts_c_coedited_files` MCP tools (nagent §8)
### Candidate 25: Optimization-log discipline for Manual Slop agent work
**Why it matters.** nagent's `coedited_file_rows` produces a "files that historically co-edit with this file" table. Manual Slop has `py_get_hierarchy` (subclass scan) but no historical co-edit tool. Useful for "if I edit this file, what should I also look at?".
**Goal:** Adopt the `OPTIMIZATION-LOG.md` pattern: every agent iteration records hypothesis + change + before/after + keep/revert + cost (wall-clock + tokens).
**What it would do.** Two new MCP tools:
- `py_coedited_files(path: str) -> list[{path, commits_together, likelihood}]` — runs `git log --follow <path>`, counts files in each commit, labels high/medium/low
- `ts_c_coedited_files(path: str) -> list[{path, commits_together, likelihood}]` — same, for C/C++
**Context:** v3 §9 surfaces the case-study methodology's 5-element pattern; the `OPTIMIZATION-LOG.md` is the per-hypothesis history file. Both case studies document rejected experiments with measurements; the methodology's data discipline is load-bearing.
Returns a table. Used in the initial context as `{file-neighborhood}`.
**File:line citations:** `pep-copt/src-optimized/OPTIMIZATION-LOG.md` (full), `differentiable-collisions-optc/src-optimized/OPTIMIZATION-LOG.md` (full).
**Where it lives.** Application (initial context injection).
**Depends on.** None. Small, contained.
**Effort.** **Small.** ~200 lines + tests. The git-log is already in `aggregate.py`; this is a new tool that uses the same primitives.
**Recommended priority.** **LOW** — small but niche. Worth bundling with Candidate 6 if that gets done.
**Recommended priority:** **MEDIUM** — the schema is portable; Manual Slop agents could adopt it for any multi-iteration work.
---
## Candidate 9: Explicit `src/split_lib.py` + `src/patch_lib.py` (nagent §11)
### Candidate 27: Tolerance-based comparator for Manual Slop agent work
**Why it matters.** Manual Slop doesn't have an explicit split/patch pipeline. For very large files (>50 KB), the current `aggregate.py` + tree-sitter approach works for *reading* (skeleton, summary) but not for *patching* (no explicit segment/hash model).
**Goal:** Adopt the `compare_results.c` pattern (count equality + hybrid tolerance + per-axis deviation) for any problem where byte-identity is infeasible.
**What it would do.** Mirror nagent's design:
- `src/split_lib.py` — per-language natural splitters, `index.json` with `source_path`, `sourcesha256`, `segments[]`
- `src/patch_lib.py` — strict `validate_index` (hash check), `make_unified_patch`, `apply_segment_patches`
- `src/summarize_lib.py` — per-segment LLM call + retry-with-smaller-prompt
**Context:** v3 §11 documents the collisions case study's tolerance-based match contract (`1mm + 0.1%·|d_ref| + 5e-4·(|c1−c2|/α²)`); contact points certified for validity, not matched. The same pattern works for float32 work, geometric problems, or any continuous problem.
**Where it lives.** Application (the AI is the consumer). The Meta-Tooling already has nagent if it wants this.
**File:line citations:** `differentiable-collisions-optc/performance-test-optimized/compare_results.c` (referenced from prompts).
**Depends on.** None. Self-contained.
**Effort.** **Medium.** 2 phases: split/patch, then summarize. ~500 lines.
**Recommended priority.** **DEFER UNTIL NEEDED.** No current 1:1 use case requires explicit split/patch. If a future file is genuinely too large for tree-sitter to handle inline, this becomes Candidate #2-priority.
**Recommended priority:** **MEDIUM** — the comparator pattern is reusable; Manual Slop's `RAGEngine._chunk_code` and other float-based work could adopt it.
---
## Candidate 10: Optional raw-transcript persistence per Take (nagent §3 conversation dimension)
## v3 new candidates (LOW priority)
**Why it matters.** nagent's "edit the conversation file" pattern is foreign to Manual Slop because the App stores abstracted entries (`disc_entries`), not raw transcripts. The user-edit feature in the GUI does edit individual entries, but the underlying log of `function_call` / `tool_result` blocks is implicit.
### Candidate 24: Document Q9 ("consider a different machine") in the project's `conductor/code_styleguides/data_oriented_design.md`
**What it would do.** Optionally, when a take is snapshotted to TOML (`project_manager.save_project`), also persist the raw transcript to a sibling file `discussions/<take_name>/transcript.jsonl`. The GUI gets a "View Raw Transcript" button. Optional "Edit Raw Transcript" mode that re-parses and re-aggregates.
**Goal:** The styleguide is already a derivative of nagent's file; add the Q9 expansion as a Tier 1+ reading-note.
**Where it lives.** Application. Optional — user can toggle per-project.
**Context:** v3 §8 surfaces the Q9 expansion (the only addition since v2.3). Q9 generalizes the simplification pass from "trim the current machine" to "consider a different machine when the data's shape points to it."
**Depends on.** None. Could be a small follow-up to Candidate 3 (`Conversation` class).
**File:line citations:** `context/data-oriented-design.md:102-116` + `:151-164` (a1f0680).
**Effort.** **Small.** ~150 lines + tests. Persist the existing `comms.log` in a structured way.
**Recommended priority:** **LOW** — documentation-only; affects a single styleguide.
**Recommended priority.** **LOW** — niche feature, opt-in only.
---
### Candidate 26: `OPTIMIZATION-LOG` schema for Manual Slop agent work
**Goal:** Adopt the `src-optimized/OPTIMIZATION-LOG.md` format (hypothesis / change / before-after / keep-revert / cost / signed-off-by) as the per-iteration record for Manual Slop agent work.
**Context:** v3 §10 documents the PEP case study's `OPTIMIZATION-LOG.md` (full rejected-experiments history) and the case-study methodology cluster (§9) abstracts it. The schema is portable; Manual Slop agents could adopt it for any multi-iteration optimization.
**File:line citations:** `pep-copt/src-optimized/OPTIMIZATION-LOG.md` (full).
**Recommended priority:** **LOW** — sub-pattern of Candidate 25 (the schema is part of the discipline).
---
## Summary table
| # | Candidate | User signal | Priority | Effort | Domain |
| # | Candidate | v3 source cluster | Priority | Effort | Domain |
|---|---|---|---|---|---|
| 1 | `SubConversationRunner` (1:1 sub-convos) | **Explicit want** | **HIGH** | Medium | App + MT |
| 2 | RAG pre-staging via sub-conversation | **Explicit want** | **HIGH** | Small (depends on #1) | App |
| 3 | Stateless `LLMClient` class | (none) | Medium | Large | App |
| 4 | Intent-based DSL for Meta-Tooling | Explicit but deferred | Low | Research | MT |
| 5 | Self-describing MCP tools | Implicit | Low (subsumed) | Medium | BOTH |
| 6 | `src/git_history.py` (nagent §7) | (none) | Medium | Medium | App |
| 7 | Per-file conversation log | (none) | Low | Small | App |
| 8 | `py_/ts_c_coedited_files` tools | (none) | Low (bundle with #6) | Small | App |
| 9 | Explicit `split_lib.py` / `patch_lib.py` | (none) | Defer until needed | Medium | App |
| 10 | Raw-transcript persistence per Take | (none) | Low | Small | App |
| 17 | Campaign-style plan-as-data for conductor | §1 Campaigns | **HIGH** | Medium | BOTH |
| 18 | Discussion-window safety net for Manual Slop | §2 Safety net | **HIGH** | Medium | APP |
| 22 | Tier 3 worker contract "decompose or isolate, never offload" | §6 Delegation rewrite | **HIGH** | Small | APP |
| 19 | Per-turn ground-truth hook | §3 Hooks | MEDIUM | Medium | BOTH |
| 21 | Per-model token-cap awareness for `ai_client` | §5 Provider expansion | MEDIUM | Medium | APP |
| 23 | Per-conversation scratch directory | §7 Robustness | MEDIUM | Small | APP |
| 25 | Optimization-log discipline | §9 Case-study methodology | MEDIUM | Small | BOTH |
| 27 | Tolerance-based comparator | §11 Collisions case study | MEDIUM | Medium | BOTH |
| 20 | Rename `nagent-gc` → `nagent-distill` in docs | §4 Project-local roots | LOW | Small (docs) | APP |
| 24 | Document Q9 in project DOD styleguide | §8 Operating rules | LOW | Small (docs) | BOTH |
| 26 | `OPTIMIZATION-LOG` schema for Manual Slop agent work | §10 PEP case study | LOW | Small | BOTH |
**Total: 11 new candidates** (3 HIGH + 4 MEDIUM + 3 LOW + 1 LOW-docs). Combined with the 10 v2.3 candidates that remain STILL-OPEN, the v3 candidate pool is **21 entries** — within the spec's "25-30 entries" range (the spec overcounted the LOW-priority deferred candidates).
---
## Recommended next steps
1. **Spec and build Candidate 1 first** — it's the highest-priority user-flagged want, and Candidates 2 builds on it.
2. **Combine Candidate 2 with Candidate 1's track** — same primitive, different prompt.
3. **Hold Candidates 3-10 for future scoping** — each is a separate conductor track when the corresponding need surfaces.
The current `nagent_review_20260608` track itself produces no code; it's the reference. Candidates 1 and 2 will be the first *implementation* tracks informed by it.
1. **Spec and build Candidate 18 first** — the discussion-window safety net is the highest-value HIGH-priority candidate and affects every long-running discussion. Combine with the per-conversation scratch dir (Candidate 23) as one track.
2. **Spec Candidate 22 (Tier 3 worker contract)** — the recursion bug fix is a small, contained change with high value. Combine with Candidate 19 (per-turn hook) as one MMA-hygiene track.
3. **Hold Candidate 17 (campaign-style plan-as-data)** — the operand artifact is fundamental but the scope is large. Spec separately; consider a research spike first.
4. **Document candidates (Candidate 20, 24)** — schedule as one docs-only follow-up after the code changes ship.