25 KiB
nagent_review_v3.1 — Decisions
Date: 2026-06-20
Spec pair: spec_v3.1.md + plan_v3.1.md
Companion: nagent_review_v3_1_report_20260620.md (the v3.1 thickened main review); comparison_table.md (v3.1 cluster table); nagent_takeaways_v3_1_20260620.md (bridge to v3 takeaways + sibling reviews); nagent_review_v3_20260619.md (the v3 main review, preserved unchanged per user directive 2026-06-20).
Source: nagent v3.1 (a1f0680 on macton/nagent@main, 2026-06-18) + the two case-study repos at main + user's 3 new observations (YAML avoidance, agent context-window, fine-tuning).
File-naming note (user directive 2026-06-20). The v3.1 thickened content is in a NEW file (
nagent_review_v3_1_report_20260620.md), not innagent_review_v3_20260619.md(the v3 main review, which is preserved unchanged). The delta summary isnagent_review_v3_1_20260620.md. Seemetadata.jsonv3_1_file_separationfield for the file structure.
This document is the bridge from "what v3.1 teaches us" to "what Manual Slop should do about it." Each candidate is a future conductor track (not this one).
v2.3 → v3 → v3.1 candidate status mapping
| v2.3 # | Title | v3 status | v3.1 status | Rationale |
|---|---|---|---|---|
| 1 | SubConversationRunner for 1:1 discussions |
STILL-OPEN | 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.1 §13 reframes the per-turn hook as the structural mechanism for the cycle. |
| 2 | RAG pre-staging via sub-conversation | STILL-OPEN | STILL-OPEN | Depends on #1. v3.1 doesn't change the priority. |
| 3 | Stateless LLMClient class |
STILL-OPEN | STILL-OPEN | v3 adds the per-model MODEL_CONTEXT_WINDOWS table (Candidate 21, MEDIUM), which is a refinement of #3, not a replacement. v3.1 §14 notes that fine-tuning could bake the conventions into the model itself. |
| 4 | Intent-based DSL for Meta-Tooling | STILL-OPEN (DEFERRED) | STILL-OPEN (DEFERRED) | User explicitly deferred per v2.3. v3.1 §12 (YAML avoidance) cites the intent_dsl_survey_20260612 Cluster 5 SSDL primitives as the project's DSL intent. |
| 5 | Self-describing MCP tools | SUBSUMED | 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. v3.1 §12 reframes the artifact format as markdown + DSL, not YAML. |
| 6 | src/git_history.py (nagent §7) |
STILL-OPEN | STILL-OPEN | v3.1 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 | STILL-OPEN | v3.1 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 | STILL-OPEN | v3.1 doesn't change. |
| 9 | Explicit src/split_lib.py + src/patch_lib.py |
STILL-OPEN | STILL-OPEN | v3.1 doesn't change. |
| 10 | Optional raw-transcript persistence per Take | STILL-OPEN | STILL-OPEN | v3.1 doesn't change. |
| 11 | Knowledge harvest (nagent-gc) → third memory dim | PROMOTE | PROMOTE | v3 renames nagent-gc → nagent-distill (per §4); the harvest+merge+graduate passes are the data-grounded refinement. v3.1 §12 notes that the artifact format is markdown + DSL, not YAML. |
| 12 | Cache TTL GUI controls (sub-candidate 12b) | STILL-OPEN | STILL-OPEN | v3.1 §14 Candidate 30 (Cache TTL GUI contract hardening) is a refinement: the per-turn grounding primitive also tracks cache state. |
| 13 | Conversation compaction (--compact) | STILL-OPEN | STILL-OPEN | v3.1 §13 reframes compaction as part of the warm-up + window + safe-zone cycle. |
| 14 | Project context files (context.yaml) | STILL-OPEN | STILL-OPEN | v3's project-local roots (§4) is an architectural refactor of this pattern. v3.1 §12 notes the artifact format is markdown + DSL, not YAML. |
| 15 | Save-with-graceful-summary-failure | STILL-OPEN | 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. v3.1 §13 reframes this in the context-window framing. |
| 16 | AGENTS.md @import + canonical DOD file | STILL-OPEN | STILL-OPEN | v3 deepens the canonical DOD file (operating rules §8) with the Q9 expansion ("different machine?"); v3.1 §14 notes the Q9 expansion as a fine-tuning target. |
v3 new candidates (carried forward, with v3.1 amendments)
Candidate 17: Campaign-style plan-as-data for the conductor
Goal: Add a .conductor/campaigns/{slug}/ layout with index + per-task task + 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).
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.
v3.1 amendment (per §12): The artifact format is markdown + frontmatter, not YAML. The markdown body holds the human-readable content (goal, tasks, done criteria, notes); the TOML frontmatter (between +++ markers) holds the machine-readable fields (slug, status, created). The custom DSL (survey grammar + SSDL) is the project's intent for inline computation, not configuration.
File:line citations: bin/nagent-campaign (24cf16d), bin/helpers/nagent_campaign_lib.py (24cf16d), issues/0002-campaign-system.md:1-326 (199a36b).
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); §12 YAML avoidance (artifact format is markdown + DSL, not YAML).
Recommended priority: HIGH — the operand artifact is a fundamental data-oriented move; affects every future conductor track.
Candidate 18: Discussion-window safety net for Manual Slop
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.
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.
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.
Cross-refs: §3 Hooks (per-turn status is the input to the checkpoint writer); §8 Operating rules (the failure-as-data principle); §13 Agent context-window observations (the safety net is the structural mechanism for the warm-up + window + safe-zone cycle).
Recommended priority: HIGH — long-running discussions currently grow unbounded; the rebuild trigger is a structural fix.
Candidate 22: Tier 3 worker contract "decompose or isolate, never offload" for Manual Slop MMA
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.
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."
File:line citations: bin/nagent:666-673 + :790-806 (65787a6), tests/test_nagent.py:1689-1695 (315fe9e).
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).
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.
v3 new candidates (MEDIUM priority, with v3.1 amendments)
Candidate 19: Per-turn ground-truth hook for Manual Slop
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.
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.
v3.1 amendment (per §13, see Candidate 28): The hook is not just a status command, but a structured "what to read next" status block that surfaces the relevant guidance for the current task. The hook closes the three failure modes of Manual Slop's docs/ + conductor/ markdown navigation: (1) forget to read, (2) fail to read on demand, (3) read but ignore.
File:line citations: bin/nagent:1442-1484 + :1607-1625 + :1922-1927 + :2806-2825 + :3167-3185 (a4fb141), both case-study prove-optimized-harness.sh scripts.
Recommended priority: MEDIUM — the abstraction is generalizable; Manual Slop already has analogous hooks (Tier 4 QA error interception).
Candidate 20: Rename nagent-gc → nagent-distill in our documentation cross-references
Goal: Documentation-only follow-up; surface the mental-model shift ("gc" → "distill") in the project's conductor/code_styleguides/knowledge_artifacts.md.
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.
File:line citations: bin/helpers/nagent_distill_lib.py:793-979 (f3ec090), bin/nagent-distill:107-200 (f3ec090).
Recommended priority: LOW — documentation-only; no code change.
Candidate 21: Per-model token-cap awareness for Manual Slop ai_client
Goal: Add MODEL_CONTEXT_WINDOWS table; rebuild fires on byte ceiling OR 0.85 of window; "don't guess" — omit rather than estimate.
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."
File:line citations: bin/helpers/nagent_llm.py:54-77 + :123-130 + :198-279 + :315-336 + :381-400 (bdfa2a6), config.example.json:7.
Recommended priority: MEDIUM — refines the existing ai_client.send() rebuild trigger with a per-model precision layer.
Candidate 23: Per-conversation scratch directory for Manual Slop dispatch_inference
Goal: Adopt the conversation_scratch_dir(conversation_name) pattern; pre-create on session start; thread through the <nagent-write>-equivalent.
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.
File:line citations: bin/nagent:1319-1331 + :1334-1341 + :1344-1381 + :1387-1394 + :1534-1551 + :1834-1840 + :224-240 (49e07f3).
Recommended priority: MEDIUM — small change with a structural payoff (concurrent dispatch safety).
Candidate 25: Optimization-log discipline for Manual Slop agent work
Goal: Adopt the OPTIMIZATION-LOG.md pattern: every agent iteration records hypothesis + change + before/after + keep/revert + cost (wall-clock + tokens).
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.
File:line citations: pep-copt/src-optimized/OPTIMIZATION-LOG.md (full), differentiable-collisions-optc/src-optimized/OPTIMIZATION-LOG.md (full).
Recommended priority: MEDIUM — the schema is portable; Manual Slop agents could adopt it for any multi-iteration work.
Candidate 27: Tolerance-based comparator for Manual Slop agent work
Goal: Adopt the compare_results.c pattern (count equality + hybrid tolerance + per-axis deviation) for any problem where byte-identity is infeasible.
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.
File:line citations: differentiable-collisions-optc/performance-test-optimized/compare_results.c (referenced from prompts).
Recommended priority: MEDIUM — the comparator pattern is reusable; Manual Slop's RAGEngine._chunk_code and other float-based work could adopt it.
v3 new candidates (LOW priority)
Candidate 24: Document Q9 ("consider a different machine") in the project's conductor/code_styleguides/data_oriented_design.md
Goal: The styleguide is already a derivative of nagent's file; add the Q9 expansion as a Tier 1+ reading-note.
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."
v3.1 amendment (per §14): The Q9 expansion is a candidate for the fine-tuning dataset (Candidate 29). The fine-tuning would bake the Q9 insight into the model, so the model automatically considers "different machine" when the data's shape points to it.
File:line citations: context/data-oriented-design.md:102-116 + :151-164 (a1f0680).
Recommended priority: LOW — documentation-only; affects a single styleguide.
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).
v3.1 new candidates (from §12-§14)
Candidate 27: Markdown + custom DSL lock-in (NEW v3.1, HIGH)
Goal: Explicitly adopt markdown + survey grammar + SSDL for campaign-style artifacts; reject YAML for new project artifacts. The Candidate 17 (campaign-style plan-as-data) is amended: the artifact format is markdown + frontmatter, not YAML.
Context: v3.1 §12 catalogs every YAML use site in nagent (campaigns, distill, knowledge, graduates) and flags them as "do not adopt" for Manual Slop. The markdown + DSL alternative is concrete: each campaign-style artifact becomes a markdown file with structured headings + a TOML frontmatter block (project config precedent) + optional SSDL-annotated code blocks for any inline computation.
File:line citations: bin/nagent-campaign (24cf16d), bin/helpers/nagent_campaign_lib.py:index_yaml_path() (24cf16d), bin/nagent-distill:107-200 (f3ec090), issues/0001-foundations.md (nagent's own issue files use markdown, not YAML — the closest nagent gets to the Manual Slop convention).
Cross-refs: intent_dsl_survey_20260612 Cluster 5 (SSDL shape primitives), superpowers_review_20260619 (markdown-driven conventions), conductor/presets.py + conductor/personas.py (TOML precedent for project config).
Recommended priority: HIGH — the format commitment is a project-wide convention; affects every future conductor track + every styleguide + every project doc.
Candidate 28: Per-turn ground-truth hook for Manual Slop (NEW v3.1, MEDIUM — reframing of Candidate 19)
Goal: Adopt nagent's --hook-per-run model; inject a "what to read next" status block at the top of every send_result(). The Candidate 19 (per-turn hook) is amended: the hook is not just a status command, but a structured "what to read next" status block that surfaces the relevant guidance for the current task. The hook is configured per-project (via [conductor].hook_per_run in manual_slop.toml); the default is a no-op (the hook is opt-in).
Context: v3.1 §13 captures the user's empirical findings (warm-up ~100-150k; window up to ~500k MiniMax M3; safe zone 250-350k; compact→re-warm→continue cycle) and notes that Manual Slop's docs/ + conductor/ markdown navigation is a partial mitigation. The shortcoming is that agents frequently forget to read or fail to read on demand. nagent's --hook-per-run pattern is the structural mechanism that closes the gap.
File:line citations: bin/nagent:1442-1484 + :1922-1927 + :3167-3185 (a4fb141), AGENTS.md (the project's canonical operating instructions), conductor/workflow.md (the workflow conventions), the 6 styleguides in conductor/code_styleguides/, the 14 deep-dive guides in docs/.
Cross-refs: §3 Hooks (the per-turn hook primitive), §2 Safety net (the per-turn hook is the input to the checkpoint writer), §13 Agent context-window observations (the structural mechanism for the cycle).
Recommended priority: MEDIUM — the abstraction is generalizable; Manual Slop already has analogous hooks (Tier 4 QA error interception).
Candidate 29: Dataset-curation track for fine-tuning (NEW v3.1, MEDIUM)
Goal: Separate track to curate the Manual Slop conventions/workflows dataset for fine-tuning; vendor selection deferred. The dataset would include: per-track spec.md + plan.md + state.toml (the per-track planning artifacts); per-cluster section in the nagent review (the conventions/workflows); per-styleguide in conductor/code_styleguides/ (the 6 styleguides); per-deep-dive in docs/guide_*.md (the 14 deep-dive guides).
Context: v3.1 §14 captures the diagnosis (current generalized models are bottlenecked by not having the user's core conventions/workflows baked in) + the user's interest in fine-tuning as the mitigation + the Together.ai observation + 5-6 other prosumer fine-tuning vendors surveyed.
File:line citations: conductor/presets.py + conductor/personas.py + conductor/context_presets.py + conductor/tool_presets.py + conductor/tool_bias.py (the TOML precedent for project config), the 6 styleguides in conductor/code_styleguides/, the 14 deep-dive guides in docs/, per-track spec.md + plan.md + state.toml + metadata.json, the 4-tier MMA architecture (per docs/guide_mma.md), the Hook API (per docs/guide_api_hooks.md), the MCP tools (per docs/guide_mcp_client.md).
Cross-refs: conductor/code_styleguides/agent_memory_dimensions.md (the 4 memory dimensions are a candidate for fine-tuning), conductor/code_styleguides/data_oriented_design.md (the canonical DOD is a candidate for fine-tuning), conductor/code_styleguides/cache_friendly_context.md (the cache TTL contract is a candidate for fine-tuning).
Recommended priority: MEDIUM — the dataset is the user's call; the vendor selection is a separate effort; the validation is a separate effort.
Candidate 30: Cache TTL GUI contract hardening (NEW v3.1, LOW)
Goal: Make the per-turn grounding primitive (Candidate 28) also track cache state; cross-ref cache_friendly_context.md. The §13 agent context-window observations note that the per-turn hook is the structural mechanism for the cycle; the cache TTL GUI contract (per conductor/code_styleguides/cache_friendly_context.md) is the cache version of the same insight. The hardening would add cache-state tracking to the per-turn hook, so the model sees the cache state (TTL, invalidated, etc.) as part of the status block.
Context: v3.1 §14 cross-refs cache_friendly_context.md (the cache TTL GUI contract). The hardening is a small change to the per-turn hook: the hook block includes cache state (which files are in cache, which are invalidated, the cache TTL, etc.) so the model responds against the cache state in addition to the other measured state.
File:line citations: bin/nagent:970-987 (v2.3's conversation_cache_boundaries), bin/nagent:1922-1927 (v3's hook_per_run injection site), conductor/code_styleguides/cache_friendly_context.md (the project's canonical cache TTL contract).
Cross-refs: §13 Agent context-window observations (the per-turn hook is the structural mechanism), conductor/code_styleguides/cache_friendly_context.md (the cache TTL contract).
Recommended priority: LOW — small change; sub-pattern of Candidate 28.
Summary table
| # | Candidate | v3.1 source | Priority | Effort | Domain |
|---|---|---|---|---|---|
| 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 |
| 27 | Markdown + custom DSL lock-in | §12 YAML avoidance | HIGH | Small (docs + convention) | BOTH |
| 19 | Per-turn ground-truth hook | §3 Hooks (reframed by §13) | 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 (alt) | Tolerance-based comparator | §11 Collisions case study | MEDIUM | Medium | BOTH |
| 28 | Per-turn ground-truth hook (v3.1 reframing) | §13 Agent context-window | MEDIUM | Medium | BOTH |
| 29 | Dataset-curation track for fine-tuning | §14 Fine-tuning observations | MEDIUM | Large (separate track) | 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 |
| 30 | Cache TTL GUI contract hardening | §14 Fine-tuning observations | LOW | Small | BOTH |
Total: 14 candidates (4 HIGH + 7 MEDIUM + 4 LOW) — within the spec's "25-30 entries" range. Note: the v3.1 numbering (Candidates 17-30) is sequential from the v2.3 → v3 candidate pool; Candidate 27 appears twice in the table (the YAML-avoidance is a new candidate, the tolerance-based comparator is the v3.1 amendment of the v3 candidate).
Recommended next steps
- Spec and build Candidate 27 (Markdown + custom DSL lock-in) first — the format commitment is project-wide; affects every future conductor track + every styleguide + every project doc. Combine with the v3.1 amendment of Candidate 17 (campaign-style plan-as-data uses markdown + frontmatter, not YAML) as one track.
- Spec Candidate 18 first (was the v3 top priority) — 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.
- Spec Candidate 22 (Tier 3 worker contract) — the recursion bug fix is a small, contained change with high value. Combine with Candidate 28 (per-turn ground-truth hook, v3.1 reframing) as one MMA-hygiene track.
- 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.
- Document candidates (Candidate 20, 24) — schedule as one docs-only follow-up after the code changes ship.
- Defer Candidate 29 (dataset-curation track for fine-tuning) to a separate future track. The dataset is the user's call; the vendor selection is a separate effort; the validation is a separate effort. The v3.1 §14 section is the marker; the implementation is a future track.