# nagent Review v2.1: User-Revision of v2

**Track:** `nagent_review_20260608`
**Date:** 2026-06-12
**Author:** Tier 1 Orchestrator
**Companion to:** `nagent_review_v2_20260612.md` (the v2 draft, preserved as-is)
**Status:** v2.1 is a user-driven revision of v2; v2 remains the draft, v2.1 is the corrected version.
**Read this if:** the v2 framing was off in places, the heavy RAG emphasis was wrong, the CLAUDE.md swap needs to be AGENTS.md, or the new agent-facing docs need to be planned.

> **Revision note (2026-06-12).** v2 (`nagent_review_v2_20260612.md`, ~68KB) was the first delta report. The user reviewed it and pushed back on five points. v2.1 incorporates all five corrections:
>
> 1. **CLAUDE.md → AGENTS.md swap.** nagent added a `CLAUDE.md`; Manual Slop has `AGENTS.md` (and not `CLAUDE.md`) in active use. All "CLAUDE.md pattern" references in v2 are now "AGENTS.md pattern" in v2.1.
> 2. **Heavy RAG emphasis is wrong.** RAG is opt-in, not mandatory, and the user is conservative about wiring it. Candidate 11 (Knowledge Harvest) should be reframed as a **third memory dimension** that complements Manual Slop's existing **curation** (FileItem + ContextPreset) and **discussion editing** (per-entry A1-A7) — *not* as a RAG replacement. v2 had a 4-paragraph RAG-comparison table that was the wrong shape; v2.1 reframes Candidate 11 around the existing memory landscape and adds a new "RAG integration discipline" sub-section that says *where* RAG fits (and where it does not).
> 3. **No restructuring of `Readme.md` or `docs/Readme.md`.** Those are human-facing docs and stay that way. v2.1 proposes **new agent-facing files** instead: `AGENTS.md` updates (add `@import` pattern) and a **new `./docs/AGENTS.md`** that mirrors the nagent CLAUDE.md model. The human Readme files are not touched.
> 4. **Cache TTL GUI controls.** v2 had no mention of explicit cache TTL per provider. The user wants GUI controls for: (a) which discussions get cached, (b) when to invalidate, (c) how long caches are available (Gemini explicit caching has a default 1-hour TTL; Anthropic ephemeral caching has a 5-minute default). v2.1 adds these as sub-candidates under Candidate 12.
> 5. **Source reads in full.** v2 was based on the README + commit messages. v2.1 is based on the full source: `bin/nagent` (2524 lines), `bin/helpers/nagent_gc_lib.py` (the harvest lib), `bin/helpers/nagent_tags.py`, `bin/helpers/nagent_llm.py` (cache_prefix_blocks), `bin/nagent-gc`, the prompts (`prompts/compact-conversation.md`, `prompts/harvest-conversation.md`), the canonical `context/data-oriented-design.md`, and `CLAUDE.md` (for the import pattern). v2.1 has file:line citations throughout.
>
> **Net effect.** v2 is preserved (it's a useful baseline). v2.1 supersedes v2 in substance but does not delete or overwrite v2. v1 is preserved (per the original user instruction).

---

## 0. TL;DR (revised)

| New in nagent | Manual Slop equivalent (corrected) | Verdict | New future-track candidate? |
|---|---|---|---|
| **Knowledge harvest** (`nagent-gc` → `~/.nagent/knowledge/`) | **THIRD memory dimension**, alongside (a) **curation** memory (`FileItem` + `ContextPreset` + Fuzzy Anchors) and (b) **discussion** memory (`disc_entries` + branching + UISnapshot A1-A7). RAG (`src/rag_engine.py`) is opt-in and not in the comparison. | **GAP (Application).** Knowledge dimension absent; curation and discussion dimensions are present and strong. | **YES** — Candidate 11 (REFRAMED) |
| **Prompt caching with stable-to-volatile context ordering** (`bin/nagent:1013-1014` passes `--cache-prefix-chars`; `bin/helpers/nagent_llm.py:cache_prefix_blocks` splits at offsets and adds `cache_control: {"type": "ephemeral"}`) | `src/ai_client.py:_add_history_cache_breakpoint`, `_send_anthropic` already use `cache_control` | **PARTIAL.** Mechanism present; ordering not enforced. Cache TTL not exposed in GUI. | **YES** — Candidate 12 (EXPANDED with cache TTL GUI controls) |
| **Conversation compaction** (`--compact` with editable `prompts/compact-conversation.md`; root-first resolution) | `src/gui_2.py:4252` `Compress` button → `run_discussion_compression` (summarization, not compaction) | **GAP.** Summarize, not compact. | **YES** — Candidate 13 |
| **Project context files** (`context.yaml` at git toplevel) | `manual_slop.toml` per-project (different syntax) | **PARITY-DIFFERENT-MECHANISM.** | Maybe — Candidate 14 |
| **claude-code provider** (5th provider, subscription auth via Claude Agent SDK; `default` model = local config) | `src/ai_client.py:_send_gemini_cli` (parallel pattern: local subprocess auth) | **PARITY.** No new track; provider addition only if user wants. | No |
| **Per-file knowledge notes** (`knowledge/files/{file_id}.md` keyed by inode) | `models.FileItem` has no `notes` field | **GAP.** | Bundle with Candidate 11 |
| **"Delete to turn off" feature flags** (`rm digest.md` → injection off) | `[ai_settings.toml]` toggles, GUI checkboxes | **PARITY-DIFFERENT-MECHANISM.** Design pattern, not a track. | N/A |
| **Save-with-graceful-summary-failure** (summary fails → save still completes with `(summary unavailable)` marker) | `ai_client.run_discussion_compression` failure mode **NEEDS SOURCE READ** | **UNKNOWN.** | Candidate 15 (TBD) |
| **AGENTS.md / `@import` pattern** (nagent's `CLAUDE.md` imports `context/data-oriented-design.md`) | Manual Slop has `AGENTS.md` already; canonical reference file is absent | **GAP.** Need to add the canonical rules file and the `@import` pattern. | Yes (workflow doc update, not a separate track) |
| **Delegation reframed as "context management, not parallelism"** | MMA already does this implicitly | **PARITY (new framing).** Design pattern, not a track. | N/A |
| **Cache TTL exposure** (nagent doesn't expose this — providers do) | Manual Slop has Gemini explicit cache + Anthropic ephemeral cache; no GUI for TTL | **GAP (UX).** | Sub-candidate under 12 |

**Verdict in one sentence (revised):** v2 nagent's major new pattern is **knowledge harvest**, which fits as a **third memory dimension** alongside Manual Slop's existing curation and discussion memory. The caching pattern is **partially present** (mechanism, no ordering discipline, no GUI exposure of TTL). Compaction is **absent** (we have summarize, not compact). The AGENTS.md `@import` pattern is **absent** in Manual Slop and is the foundation for a new canonical rules file.

---

## 1. Source reads in full (new in v2.1)

The v2 report was based on the README + commit messages. v2.1 is grounded in the actual source:

| File | Lines | What was learned (key citations) |
|---|---|---|
| `bin/nagent` | 2524 | `build_initial_context` at line 606-745 (the full block order, see §2.4 below); `conversation_cache_boundaries` at line 970-987 (the two stable/volatile boundary points); `call_llm` at line 990-1019 (passes `--cache-prefix-chars` per boundary at line 1013-1014); `compact_conversation` at line 1975-2019 (compaction is implemented as `edit_conversation` with a `compact_guidance` prompt); `--save-conversation` at line 2147; `--branch-conversation` at line 2157; `--compact` at line 2178; the `<nagent-conversation conversation-file="name">` and `conversation-name="name"` worker-reuse tags at line 704-706 |
| `bin/helpers/nagent_gc_lib.py` | ~700 (27KB) | The full knowledge harvest pipeline: `ITEM_CATEGORIES = ("facts", "decisions", "tasks_done", "tasks_open", "questions", "playbooks", "files")` (line ~30); `DIGEST_MAX_BYTES = 4 * 1024` (line ~13); `MAX_HARVEST_SOURCE_BYTES = 1024 * 1024` (line 14, the 1MB budget); `HARVEST_MAX_ATTEMPTS = 2` (line 15, retry budget); `merge_harvest` appends bullets with provenance `[from: conversation_name, date]` (line ~285); the file_notes branch: if path resolves to existing file → `knowledge/files/{file_id}.md`; else fall back to `facts.md` (line ~325); `regenerate_digest` orders sections (Open tasks, Open questions, Decisions, Facts, Playbooks) and reverses bullets for newest-first (line ~395); `run_gc` ledger gate (line ~510); "too-large" handling (line ~595); "already harvested" path (line ~570) |
| `bin/helpers/nagent_tags.py` | ~160 (6KB) | The new explicit tag parser. Replaces regex parsing. `TagNode` dataclass with `name, attrs, content, self_closing, start, end`. `parse_tag_document` walks whitespace + elements. `find_block_span`, `extract_block`, `replace_first_block`, `remove_first_block` are the public helpers. **The protocol is XML-ish, not XML** — first matching close tag wins; no entity escaping. |
| `bin/helpers/nagent_llm.py` | ~440 (20KB) | 5 providers (openai, anthropic, google, cursor, claude-code); `CREDENTIAL_ENV` is empty for claude-code (local login); `cache_prefix_blocks` at the bottom: splits message at given char offsets (max 3 prefix blocks per Anthropic's 4-breakpoint limit), adds `cache_control: {"type": "ephemeral"}` to each prefix; `_result_with_usage` folds `cache_read_input_tokens + cache_creation_input_tokens` into `input_tokens` so "input_tokens stays 'tokens sent' across providers"; `claude-code` provider uses `Claude Agent SDK`, `model=None` for default, `max_turns=1` for text gen, `max_turns=None` for file-upload mode |
| `bin/nagent-gc` | ~150 (5KB) | The CLI wrapper. `run_gc` is library-callable; CLI defaults to dry-run. `--apply` mutates; `--no-harvest` reclaims without LLM pass; `--max-harvest-bytes N` caps the conversation bytes sent to the LLM this run (deferral pattern). |
| `prompts/compact-conversation.md` | 3237 bytes | The compaction guidance prompt. Key sections: "Core Principle: The agent is not the thing. The data is the thing."; "Data-Oriented Rules" (what to keep / what to remove); "Transformation Rules" (replace many shell commands with verified outcomes, etc.); "Preserve Artifact Knowledge" (keep references to root context, per-file conversations, file summaries, repository history summaries); "Preserve Failure Knowledge" (keep failed experiments, rejected designs, dangerous edge cases); "Required Output Structure" (User Intent, Current Objective, Accepted Decisions, Constraints, Durable Knowledge, etc.); "Self Review" (10 yes/no questions) |
| `prompts/harvest-conversation.md` | 1674 bytes | The harvest prompt. Strict JSON output, no prose, no markdown fence. Categories: `facts, decisions, tasks_done, tasks_open, questions, playbooks, files`. Per-category rules ("facts: durable statements about systems... not assumed"). "Empty arrays are valid and expected: most conversations contain nothing durable. Do not invent items to fill categories." |
| `context/data-oriented-design.md` | 13084 bytes | The canonical DOD reference. Defines "Tier 0/1/2" complexity levels (analogous to the 4-tier MMA). The "three default beliefs to reject" (tools are not the platform; design around a model of the world; solution matters more than the data). The "simplification pass" (7 questions: not do this; only once; fewer times; approximate; small lookup; large lookup; small buffer). The "data protocols between systems" section. The "enforceable deliverables (tier 2)" section (batch transform contract, plural/batch path, justification for any pointer-heavy hot path, explicit out-of-range behavior, unresolved design questions as local issue files). The "final self-check" checklist. **This is the file that should be the canonical reference for Manual Slop's DOD principles.** |
| `CLAUDE.md` | 5832 bytes | The agent-facing rules file. Imports the canonical DOD file via `@context/data-oriented-design.md`. Has a "What this is" section, "Commands" section, "Architecture" section (the 4 reading levels: bin/nagent, helpers, CLI front-ends, lib), "The structured-tag protocol" section, "Durable state lives under `~/.nagent/`" section, "Write boundaries" section, "Large files" section, "Conventions for changes" section. **This is the pattern Manual Slop should mirror with `AGENTS.md` (project root) + a new `./docs/AGENTS.md` (docs root).** |
| `bin/helpers/nagent_cli.py` | 2642 bytes | `exit_on_description()` (the `--description` self-describing pattern); `collect_bin_tool_descriptions()` (iterates `bin/` and runs `--description` on each); `WaitSpinner` (animated spinner with `enabled` flag for non-TTY). |
| `bin/helpers/nagent_file_split_lib.py` | 15427 bytes | `source_sha256()` (the hash function for split validation); `SPLIT_TYPES` (11 languages); per-language scoring (regex + line counts + brace/JSON/XML depth); the recent O(n²) → O(n) perf fix. |
| `bin/helpers/nagent_file_edit_lib.py` | 5232 bytes | `file_id_for_path(path) -> "{st_dev}:{st_ino}"`; the per-file conversation index; the file-edit conversation file naming. |
| `bin/helpers/nagent_file_patch_lib.py` | 5086 bytes | `validate_index` (the strict hash check); `merge_segments`; `make_unified_patch`; `apply_segment_patches`. |
| `bin/helpers/nagent_file_summarize_lib.py` | 3884 bytes | `SUMMARY_MAX_ATTEMPTS = 2`; `summarize_content` (per-segment LLM call with retry); `combined_summary_from_index`. |
| `prompts/create-readme.md` | 28245 bytes | The README-generation prompt. **Not relevant to v2.1**; it's a workflow tool, not a system pattern. |
| `context.yaml` | 34 bytes | A pointer: `paths: [context/data-oriented-design.md]` |
| `requirements.txt` | 94 bytes | Dependencies: `claude-agent-sdk` (new), plus the standard openai/anthropic/google SDKs |

**v1.1 implication:** v1's report said it read the nagent source in full. v2.1 confirms that and adds the explicit file:line citations for the v2 patterns. The v1 spec.md claim "All 11 source files read in full" is now verifiable.

---

## 2. Revised new-pattern analysis

### 2.1 Knowledge Harvest (REFRAMED — was: "RAG alternative", now: "third memory dimension")

**The reframing.** v2 framed Candidate 11 as "Manual Slop's RAG is fuzzy + opaque; nagent's knowledge store is exact + editable + provenance-aware." This is the wrong shape. RAG is opt-in, not mandatory, and the user is conservative about wiring it. The correct framing:

**Manual Slop has two memory dimensions today. The new candidate adds a third.**

| Dimension | Where it lives | What it stores | How it's edited | How it's queried |
|---|---|---|---|---|
| **Curation memory** (existing) | `FileItem` (path + view_mode + ast_mask + custom_slices) + `ContextPreset` (saved set of FileItems) + `models.py:510-559` | *How to render a file* in the AI's context window. Per-file, per-discussion. | GUI Structural File Editor; project TOML edit | Implicit in `aggregate.py:run` at discussion start |
| **Discussion memory** (existing) | `app.disc_entries` (`gui_2.py:3770-3853` per-entry A1-A7; `gui_2.py:4239-4260` discussion-level B1-B11; `src/history.py:8-63` UISnapshot A1-C5) | *What was said* in the conversation. Per-discussion, multi-turn. | GUI `[Edit]` mode per entry; `[Branch]` button; `UISnapshot` undo/redo | `aggregate.py:build_markdown` renders as the LLM's prior context |
| **RAG memory** (opt-in) | `src/rag_engine.py` (ChromaDB vector store) | *Semantic fingerprints* of indexed files. Cross-file, cross-discussion. | None (vector store is opaque) | `RAGEngine.search()` at LLM call time |
| **Knowledge memory** (proposed) | `~/.manual_slop/knowledge/{facts,decisions,questions,playbooks}.md` + `knowledge/files/{file_id}.md` + `knowledge/digest.md` + `knowledge/ledger.json` | *Durable learnings* harvested from past sessions: facts, decisions, tasks, questions, playbooks, per-file notes. Cross-discussion, provenance-aware. | Plain markdown edit (user can correct any "fact") | Bounded digest injected as a stable prefix at discussion start |

**The harvest pattern in detail (from the source).** The `prompts/harvest-conversation.md` template produces strict JSON:

```json
{
  "facts": [{"statement": "...", "detail": "..."}],
  "decisions": [{"statement": "...", "detail": "..."}],
  "tasks_done": [{"statement": "...", "detail": "..."}],
  "tasks_open": [{"statement": "...", "detail": "..."}],
  "questions": [{"statement": "...", "detail": "..."}],
  "playbooks": [{"name": "...", "steps": "..."}],
  "files": [{"path": "...", "note": "..."}]
}
```

Each bullet is appended to a category file with provenance: `f"{text} [from: {conversation_name}, {date}]"`. The `files` category is special: if the path resolves to an existing file, the note goes to `knowledge/files/{file_id}.md` (keyed by inode, like nagent's per-file conversations). If the path doesn't resolve, the note falls back to `facts.md` (the note survives, just loses the per-file binding).

The digest (`regenerate_digest`, `bin/helpers/nagent_gc_lib.py:395+`) is a bounded (4KB max) regeneration from the category files. Sections in fixed order: Open tasks, Open questions, Decisions, Facts, Playbooks. **Newest first** within each section (because the category files are append-only). Truncation is explicit: "(truncated; see the category files for the rest)".

The **ledger** (`bin/helpers/nagent_gc_lib.py:130+`) gates deletion on a sha256-of-content entry. Two conversations with identical content share a ledger entry. Identical content never pays the LLM twice. The `run_gc` "already harvested" branch reclaims without re-distilling: `if existing.get("status") == "harvested": reclaimed += size; path.unlink()`.

**What "delete to turn off" means.** `regenerate_digest` deletes `digest.md` when there are no sections (`if not sections: if target.is_file(): target.unlink()`). The injection path in `build_initial_context` checks for the digest file's existence: `if knowledge_digest:` (line 677). Delete the file → no injection. The "feature flag" is the file's presence.

**The user's specific instruction:** "I rather reframe manual slops current state with 'knowledge harvest' or curation to what is done with context composition relative to files & media, and direct discussion entry editing. I can expose more explicit controls in the future for handling discussion caching and what not.. also expose how long the caches are available for (gemini has a limit for example)."

**The applied reframing:**
- "Knowledge harvest or curation" — the new dimension is "knowledge" in the sense of *durable, user-editable, provenance-aware learnings*, not curation (which is already well-covered by FileItem/ContextPreset).
- "what is done with context composition relative to files & media" — the existing curation memory is the FileItem/ContextPreset story. Don't compete with it; complement it.
- "direct discussion entry editing" — the existing discussion memory is the A1-A7/B1-B11/C1-C5 story. Don't compete with it; complement it.
- "expose more explicit controls in the future for handling discussion caching" — see §2.2 below (expanded Candidate 12).
- "how long the caches are available for (gemini has a limit for example)" — see §2.2 below (cache TTL GUI controls).
- **"we just make targeted wiring of rag usage across features where it may be beneficial but we should be conservative"** — see §2.10 below (RAG integration discipline).

**Verdict (revised).** **GAP (Application)** for the third memory dimension. The first two dimensions (curation, discussion) are well-covered. RAG is opt-in. Knowledge memory is the missing fourth.

**Domain tag:** Both. The user-facing knowledge store is Application; the harvest/regen cycle is Application-orchestrated but could be Meta-Tooling-triggered.

**Effort:** Large (3-5 phases). See Candidate 11 in §6.

**Recommended priority:** **HIGH** (unchanged from v2).

---

### 2.2 Prompt Caching + Cache TTL GUI Controls (EXPANDED Candidate 12)

**The two-part scope.** v2 had only "stable-to-volatile context ordering." v2.1 adds **cache TTL GUI controls** as a second sub-candidate.

**Part A: Stable-to-volatile context ordering (same as v2).** The mechanism is grounded in the source.

`bin/nagent:970-987` (`conversation_cache_boundaries`):
```python
def conversation_cache_boundaries(text: str) -> list[int]:
    """Character offsets ending the stable prefixes of a conversation file.
    Two boundaries when the file starts with an initial-context block: the
    start of the volatile Instance section (shared byte-for-byte across
    conversations of the same mode and root) and the end of the context block
    (stable across every turn of this conversation)."""
    span = find_block_span(text, INITIAL_CONTEXT_BLOCK)
    if span is None or span[0] != 0:
        return []
    boundaries: list[int] = []
    volatile_at = text.find("\nInstance:", span[0], span[1])
    if volatile_at > 0:
        boundaries.append(volatile_at)
    if span[1] < len(text):
        boundaries.append(span[1])
    return boundaries
```

`bin/nagent:1013-1014` (`call_llm`):
```python
for boundary in conversation_cache_boundaries(conversation_text):
    command.extend(["--cache-prefix-chars", str(boundary)])
```

`bin/helpers/nagent_llm.py` (`cache_prefix_blocks`):
```python
def cache_prefix_blocks(message: str, cache_boundaries: list[int] | None):
    """Split a message into content blocks at the given character offsets,
    marking each prefix block with cache_control so providers that cache on
    block boundaries can reuse stable prefixes. At most 3 prefix blocks
    (provider limit is 4 breakpoints per request)."""
```

This is the *implementation* of "stable-to-volatile ordering as data, not convention." The boundaries are *computed from the file* (the `\nInstance:` marker), not hard-coded. The `--cache-prefix-chars` flow is CLI-visible. The Anthropic-specific path wraps the message in `content` blocks with `cache_control: {"type": "ephemeral"}`.

`bin/nagent:606-745` (`build_initial_context`) shows the actual block order — see §2.4 below.

**Part B: Cache TTL GUI controls (NEW in v2.1).** The user said: "I can expose more explicit controls in the future for handling discussion caching and what not.. also expose how long the caches are available for (gemini has a limit for example)."

The Manual Slop current state:
- `src/ai_client.py:_send_gemini` has explicit caching (`get_gemini_cache_stats` is exported per the summary; `_GEMINI_CACHE_TTL` is a constant).
- `src/ai_client.py:_send_anthropic` has ephemeral caching via `cache_control` blocks.
- The GUI has no exposure of either: no per-discussion cache toggle, no TTL display, no cache hit rate, no "this discussion is currently cached" indicator.

The user's specific ask:
1. **"Handling discussion caching"** — per-discussion decisions: cache this discussion? When to invalidate? Show the cache state in the GUI.
2. **"How long the caches are available for"** — TTL exposure. Gemini explicit cache default is 1 hour (configurable in API call). Anthropic ephemeral cache default is 5 minutes (per-request, not configurable). Google has its own model.
3. **"Targeted wiring of rag usage across features where it may be beneficial but we should be conservative"** — see §2.10.

**The proposed GUI surface** (sub-candidate 12a):
- A "Caching" tab in Operations Hub (parallel to the planned Vendor State tab per Phase 8 UI Polish).
- Per-provider cache configuration: TTL override, model eligibility, default mode (ephemeral vs explicit vs none).
- Per-discussion cache state: which discussion is currently cached, when the cache was created, when it expires.
- Cache hit rate per provider (aggregated from `_send_anthropic` usage metadata which has `cache_read_input_tokens` and `cache_creation_input_tokens`).

**Verdict (revised).** **PARTIAL** for ordering; **GAP (UX)** for cache TTL exposure.

**Domain tag:** Application (UX + AI client internals).

**Effort:** 
- Part A (ordering): Small (1-2 phases) IF the existing cache_control calls are mostly correct.
- Part B (TTL GUI): Medium (2-3 phases) — new panel, AI client telemetry, per-discussion state tracking.

**Recommended priority:** **MEDIUM** for Part A, **MEDIUM** for Part B (the user explicitly wants this).

---

### 2.3 Conversation Compaction (unchanged from v2)

**Verdict:** **GAP (Application).** Manual Slop has `run_discussion_compression` (summarization). Compaction is the rewrite-in-place variant.

**The source-grounded pattern.** `bin/nagent:1975-2019` (`compact_conversation`) is implemented as `edit_conversation` driven by the `compact_guidance` prompt. The compaction prompt (`prompts/compact-conversation.md`) defines:
- "Core Principle: The agent is not the thing. The data is the thing."
- "Data-Oriented Rules": keep decisions, user requirements, constraints, discovered invariants, successful/failed experiments; remove repeated reasoning, repeated shell output, duplicated summaries, obsolete hypotheses, intermediate exploration, dead conversations.
- "Transformation Rules": replace many shell commands with verified outcomes; replace long investigations with "conclusion + evidence"; merge duplicate investigations.
- "Preserve Artifact Knowledge": keep references to root context, per-file conversations, file summaries, repository history summaries, historical coupling, split indexes, patch artifacts. **Prefer references over duplication.**
- "Preserve Failure Knowledge": keep failed experiments, rejected designs, dangerous edge cases, corrected assumptions.
- "Required Output Structure": User Intent, Current Objective, Accepted Decisions, Constraints, Durable Knowledge (Global, Artifact Local, Repository History, Historical Coupling), Verified Facts, Important Failed Attempts, Open Questions, TODO, Minimal Context Needed To Continue.
- "Self Review": 10 yes/no questions, including "Can another worker continue immediately?", "Would expensive investigation need to be repeated?", "Has chronology been replaced with state?", "Is future capability unchanged or improved?".

**Domain tag:** Application.

**Effort:** Small to medium (1-2 phases).

**Recommended priority:** **MEDIUM** (unchanged from v2).

---

### 2.4 Project Context Files (AGENTS.md swap applied)

**The user's swap instruction.** "for the 3rd commit, we have an AGENTS.md but not a CLAUDE.md in active use. So lets swap that if posible."

**What nagent v2 added.** Commit `d86bce8` "Add CLAUDE.md importing the shared data-oriented design rules" (2026-06-11 23:10:12). The CLAUDE.md file is 5832 bytes and imports the canonical `context/data-oriented-design.md` via `@context/data-oriented-design.md`. The same file is injected into every nagent conversation via the repo's `context.yaml`. One source of truth for both harnesses.

**The pattern Manual Slop should mirror.** Manual Slop already has `AGENTS.md` (the project root, ~5.4KB per the AGENTS.md content I have). The pattern would be:
1. Create a canonical rules file at `conductor/code_styleguides/data_oriented_design.md` (new).
2. Add `@conductor/code_styleguides/data_oriented_design.md` to `AGENTS.md` (existing).
3. Inject the same file via `[agent]` section in `manual_slop.toml` (or equivalent project config) so the Application's RAG / context assembly picks it up.

**The v2 CLAUDE.md content** (relevant excerpt):
```markdown
# CLAUDE.md
This file provides guidance to Claude Code when working with code in this repository.

## Operating rules
@context/data-oriented-design.md
The same file is injected into every nagent conversation via the repo's context.yaml —
one source of truth for both harnesses. Edit it there; do not duplicate rules into this file.

## What this is
**nagent** ("not-an-agent") is a small reference implementation of a data-oriented LLM
workflow loop. The thesis drives every design decision and should drive yours:
**the data is the thing, not the agent.** ...
```

**Where the canonical rules file would live for Manual Slop.** `conductor/code_styleguides/data_oriented_design.md` is the right place. It's already a directory of canonical styleguides (`chroma_cache.md`, `config_state_owner.md`, `error_handling.md`, `python.md`, `workspace_paths.md`). The DOD file would be the sixth.

**The "human Readme files" constraint.** The user said: "I don't want to restructure my ./Readme or ./docs/Readme.md to be tailored towards agents. I want to keep those as human interfacing docs, I rather you make an agents readme (which is technically AGENTS.md, and a another for ./docs if necessary)."

So:
- `Readme.md` (project root) — human-facing, **unchanged**.
- `docs/Readme.md` (docs index) — human-facing, **unchanged**.
- `AGENTS.md` (project root) — **agent-facing**; exists already, gets `@import` update.
- `./docs/AGENTS.md` (NEW) — **agent-facing** mirror of `docs/Readme.md`; the "another for ./docs if necessary" the user mentioned.

The new `./docs/AGENTS.md` would be the agent-facing equivalent of `docs/Readme.md`. It would import the canonical DOD file, point to the relevant styleguides, and explain which `docs/guide_*.md` files are most useful for which tier (Tier 1/2/3/4 MMA).

**Verdict (revised).** **PARITY-DIFFERENT-MECHANISM** for the project-context pattern (nagent uses `context.yaml`/markdown; Manual Slop uses TOML). **GAP** for the AGENTS.md `@import` pattern (Manual Slop has `AGENTS.md` but no canonical rules file to import).

**Domain tag:** Both (the file is in the repo; the consumer is the agent harness *and* the Application's RAG injection).

**Effort:** Small (1 phase). Write the canonical file, update `AGENTS.md`, create `./docs/AGENTS.md`, inject via `manual_slop.toml`.

**Recommended priority:** **HIGH** — the foundation for the new agent-facing docs. Without this, the other styleguides (knowledge, caching) lack a home.

**Cross-references:** See §4 (Proposed new artifacts for the next turn) for the full list.

---

### 2.5 claude-code provider (unchanged from v2)

**Verdict:** **PARITY** with Manual Slop's `_send_gemini_cli` (the existing local-CLI subscription-auth pattern). No new track; provider addition only if user wants.

**The source.** `bin/helpers/nagent_llm.py:65-80`:
- `PROVIDERS = ("openai", "anthropic", "google", "gemini", "cursor", "claude-code")` (note: 6 entries, not 5; `gemini` is an alias for `google`)
- `CREDENTIAL_ENV["claude-code"] = ()` (empty tuple — no env var read; uses local Claude Code login)
- `_claude_code_generate` uses `claude_agent_sdk`, `model=None` for "default" mode, `max_turns=1` for text gen
- Tools are disabled for plain text; `nagent-llm-upload` permits only the Read tool so Claude Code can read the file locally

**Domain tag:** Application.

**Effort:** Medium (a new provider is ~200-400 lines).

**Recommended priority:** **LOW** (unchanged from v2).

---

### 2.6 Per-file knowledge notes (unchanged from v2)

**Verdict:** **GAP.** FileItem has no notes field.

**The source.** `bin/helpers/nagent_gc_lib.py:merge_harvest` "files" branch:
- If the path resolves to an existing file → `_append_bullets(file_knowledge_path(root, file_id), f"# {target.resolve()}", [f"{note} {provenance}"])` where `file_id = file_id_for_path(target)` (the st_dev:st_ino)
- If the path doesn't resolve → fall back to `_append_bullets(knowledge / "facts.md", "# Facts", [f"{prefix}{note} {provenance}"])` where `prefix = f"{path_text}: "` — the note survives as a fact, just loses the per-file binding

This is the per-file memory dimension that v1 §6 (Per-File Memory) didn't fully capture. nagent's per-file memory is: (a) per-file conversation (v1 §6) + (b) per-file knowledge notes (v2 addition). The combination is the *complete* per-file memory.

**Domain tag:** Application. Bundle with Candidate 11.

**Effort:** Small (1 phase) — add `notes: str = ""` to `FileItem`, GUI text area, `aggregate.py:run` integration.

**Recommended priority:** **LOW** (bundle with Candidate 11).

---

### 2.7 "Delete to turn off" feature flags (unchanged from v2)

**Verdict:** **PARITY-DIFFERENT-MECHANISM.** Design pattern, not a track. Worth a styleguide.

**The source.** `bin/helpers/nagent_gc_lib.py:regenerate_digest` (line ~395): `if not sections: if target.is_file(): target.unlink() return None`. The `build_initial_context` injection check at line 677: `if knowledge_digest:`. Delete the file → no injection. The file is the switch.

**Domain tag:** Both. Design pattern.

**Effort:** N/A (styleguide, not a track).

**Recommended priority:** **LOW.** Styleguide update, not a track.

**Cross-references:** Add to `conductor/code_styleguides/feature_flags.md` (new styleguide) or as a section in `data_oriented_design.md`.

---

### 2.8 Save-with-graceful-summary-failure (unchanged from v2)

**Verdict:** **UNKNOWN** without reading the source. v2.1 still has this as Candidate 15 (TBD).

**The nagent source.** `bin/nagent:2150-2180` (`--save-conversation` and `--branch-conversation`) shows the save path. The harvest path (`bin/helpers/nagent_gc_lib.py:harvest_conversation`) handles failures gracefully: `except (OSError, RuntimeError, ValueError, UnicodeDecodeError) as exc: failures.append(...); entries[sha] = {"status": "harvest-failed", ...}; emit(...)` — the artifact is *kept* (not deleted) on failure, the failure is recorded in the ledger, the user sees it.

**What Manual Slop needs to verify.** `src/ai_client.py:run_discussion_compression` — does it raise on LLM failure (destructive) or fall back to the original (graceful)? Per the v1 takeaways, the v1 reviewer noted this is a concern but didn't verify the source.

**Recommended priority:** **TBD** until the source is read.

---

### 2.9 Delegation reframed as "context management, not parallelism" (unchanged from v2)

**Verdict:** **PARITY (new framing).** Design pattern.

**The source.** `bin/nagent:715-731` (inside `build_initial_context`, the "Context management" section): "Hand off when noisy: if this conversation is mostly stale tool output, distill goal/state/decisions into a sub-conversation prompt, delegate the rest, and tell your caller about the handoff. Never rewrite your own conversation file while running."

**The MMA analog.** `src/multi_agent_conductor.py` already does this implicitly. The new framing is for documentation, not implementation.

**Recommended priority:** **LOW.** Update `docs/guide_mma.md` with the new framing.

---

### 2.10 RAG integration discipline (NEW in v2.1)

**The user's instruction.** "the rag introduces the vector db fuzz which is not required, its something the user can opt into so at worst case we just make targeted wiring of rag usage across features where it may be beneficial but we should be conservative."

**The current RAG surface in Manual Slop.** Per the v1 review:
- `src/rag_engine.py:1-384` — the RAG engine, 384 lines, ChromaDB-backed
- `tests/test_rag_engine.py` — RAG tests
- `tests/test_rag_phase4_stress.py` — phase 4 stress tests
- `tests/test_rag_collection_dim_mismatch_recreates_collection` + `test_rag_collection_dim_match_preserves_collection` — recent dim-mismatch regression tests (commit `16412ad5`)
- GUI: a RAG section in the AI Settings (likely in `gui_2.py`; would need verification)

**Where RAG fits well (the user's "beneficial" cases):**
- Semantic search across a large codebase when the user asks "where does X happen?"
- Concept-level discovery ("how does the execution clutch work?") where keyword search misses
- Cross-file pattern matching that grep can't do

**Where RAG does NOT fit (the user's "conservative" warning):**
- Per-file curation (FileItem + ContextPreset is the right tool; RAG would be redundant)
- Per-discussion context (the discussion memory is already structured; RAG would be lossy)
- Knowledge harvest (the *third* memory dimension; RAG is a different shape)
- Per-file knowledge notes (the harvest pattern; RAG would be the wrong granularity)

**The proposed discipline.** A new `conductor/code_styleguides/rag_integration_discipline.md` (or a section in `data_oriented_design.md`) that codifies:
1. RAG is opt-in. Default-off in new projects.
2. RAG complements, never replaces, the other memory dimensions.
3. RAG results must be displayed with provenance (which file, which chunk).
4. RAG never mutates state (no auto-injection, no auto-update).
5. RAG integration is feature-gated: a feature must explicitly request RAG in its scope.
6. RAG's failure mode is graceful: a failed search returns empty, never crashes the request.

**Verdict (new).** **GAP (documentation).** The discipline is implicit; not codified.

**Domain tag:** Both.

**Effort:** Small (1 phase) — write the styleguide.

**Recommended priority:** **MEDIUM** — without the discipline, future RAG integration will be ad-hoc.

---

## 3. The 13-step "Build Your Own" list (unchanged from v2)

v1's 12-step list is now 13. New step 10: "Harvest dead conversations into a knowledge store; inject a bounded digest." The implication for v1's Appendix A is unchanged from v2: bump from 12 to 13.

---

## 4. Proposed new artifacts (for the next turn)

The user said: "I definitely want to make new docs that related ot the ones v1 originally made but not override them. I definitely also want to update the workflwo docs."

The v2.1 proposals. **All new files; none override v1 artifacts or human Readmes.**

### 4.1 New agent-facing files (the AGENTS.md family)

| File | Type | Source for content | Why |
|---|---|---|---|
| `conductor/code_styleguides/data_oriented_design.md` | NEW | Cloned from nagent's `context/data-oriented-design.md` (13084 bytes), adapted to Manual Slop | The canonical DOD reference. Imported by `AGENTS.md` and injected via `manual_slop.toml`. |
| `AGENTS.md` (existing, ~5.4KB) | **UPDATE** | Add `@conductor/code_styleguides/data_oriented_design.md` to top | Per nagent's `CLAUDE.md` pattern: import the canonical rules file; one source of truth for both harnesses |
| `./docs/AGENTS.md` | NEW | Mirror of nagent's `CLAUDE.md` content: what is Manual Slop; the 4 memory dimensions; the caching strategy; the tier-scoped docs (which `docs/guide_*.md` is for which MMA tier) | The agent-facing mirror of `docs/Readme.md` (which stays human-facing) |
| `./docs/agents/` (optional) | NEW directory | For per-agent-type doc collections if `./docs/AGENTS.md` grows | "another for ./docs if necessary" per the user |

### 4.2 New styleguides (the manual's style guides)

| File | Type | Source | Why |
|---|---|---|---|
| `conductor/code_styleguides/agent_memory_dimensions.md` | NEW | Combines v1 §3, §6 + v2.1 §2.1 | Codifies the 4 memory dimensions (curation, discussion, RAG, knowledge) and the rules for when to use each |
| `conductor/code_styleguides/rag_integration_discipline.md` | NEW | Per §2.10 above | Codifies the RAG opt-in default, provenance requirement, and the no-mutation rule |
| `conductor/code_styleguides/cache_friendly_context.md` | NEW | Per §2.2 above | Codifies the stable-to-volatile context ordering, the cache TTL GUI contract, and the per-discussion caching decision |
| `conductor/code_styleguides/knowledge_artifacts.md` | NEW | Per §2.1 above | Codifies the knowledge harvest pattern: category files, provenance, sha256 ledger, digest regeneration, "delete to turn off" |
| `conductor/code_styleguides/feature_flags.md` | NEW | Per §2.7 above | The "delete to turn off" pattern codified as a general feature-flag convention |

### 4.3 New project docs (the docs/ guides)

| File | Type | Source | Why |
|---|---|---|---|
| `docs/guide_knowledge_curation.md` | NEW | Per v2.1 §2.1; complements v1's `docs/guide_context_curation.md` | "The third memory dimension" — what the knowledge store is, how it differs from curation/discussion/RAG, how to write to it, how to query it |
| `docs/guide_caching_strategy.md` | NEW | Per v2.1 §2.2; complements `docs/guide_ai_client.md` | "Caching across providers" — the stable-to-volatile pattern, the cache TTL GUI, the per-discussion caching decision |
| `docs/guide_agent_memory_dimensions.md` | NEW | Cross-cutting: curation + discussion + RAG + knowledge | Maps each Manual Slop feature to the memory dimension(s) it uses; useful for new-feature scoping |

### 4.4 Updates to existing workflow docs

| File | Type | What changes | Why |
|---|---|---|---|
| `AGENTS.md` | UPDATE | Add `@import` for canonical DOD file | Per nagent's pattern |
| `conductor/workflow.md` | UPDATE | Add TDD protocol sections for: cache TTL control, knowledge harvest, conversation compaction, RAG discipline | The workflow should reflect the new patterns |
| `conductor/product-guidelines.md` | UPDATE | Add a "memory dimensions" section that codifies the 4 dimensions and the rules for which to use when | The product guidelines should reflect the v2.1 framing |
| `docs/guide_mma.md` | UPDATE | Use the new "delegation is context management" framing in the Token Firewalling section | Per §2.9 |
| `docs/guide_ai_client.md` | UPDATE | Add the cache TTL section, the per-discussion caching decision, the cache health panel | Per §2.2 |

### 4.5 v1 artifacts (preserved, NOT updated in this turn)

| File | Status | Why |
|---|---|---|
| `conductor/tracks/nagent_review_20260608/report.md` | **Preserved** | v1's 14-section deep-dive. The structure is still correct. v2.1's findings are *additions*, not contradictions. |
| `conductor/tracks/nagent_review_20260608/comparison_table.md` | **Preserved** | Same. |
| `conductor/tracks/nagent_review_20260608/decisions.md` | **Preserved** | The 10 v1 candidates are still real candidates. v2.1 adds 5 new ones. |
| `conductor/tracks/nagent_review_20260608/nagent_takeaways_20260608.md` | **Preserved** | The 10 v1 takeaways are still grounded. v2.1 adds 3 more. |
| `conductor/tracks/nagent_review_20260608/nagent_review_v2_20260612.md` | **Preserved** (v2 draft) | Per the user's instruction "I want to keep this v2 draft" |
| `conductor/tracks/nagent_review_20260608/nagent_review_v2_1_20260612.md` | **This file** (v2.1) | The user-revised version |
| `Readme.md` (project root) | **Preserved** | Human-facing, unchanged |
| `docs/Readme.md` | **Preserved** | Human-facing, unchanged |

---

## 5. v2.1's revised future-track candidate list (15 candidates, up from 10)

### Candidate 11: Knowledge Memory (third memory dimension) — REFRAMED, HIGH

**The reframing.** Manual Slop has two strong memory dimensions today (curation, discussion). RAG is opt-in. The new candidate adds a third dimension (knowledge memory) — user-editable, provenance-aware, durable learnings from past sessions. Not a RAG alternative. Not a curation replacement. Not a discussion replacement. A *complement*.

**What it would do.** A new `src/knowledge_store.py`:
- `KnowledgeStore` class with `add_bullet(category, text, provenance)`, `get_digest(budget_chars=4096)`, `regenerate_digest()`, `delete_digest()` (turn-off switch), `edit_category(category, bullets)` (user-editable)
- `KnowledgeHarvester` class with `harvest_conversation(discussion) -> Result[list[KnowledgeBullet], ErrorInfo]` (LLM call against an editable `prompts/harvest-conversation.md`)
- A new `src/harvest_cli.py` (or GUI panel) that does the dry-run → apply cycle, like `nagent-gc`
- A bounded `{knowledge}` block injected into `aggregate.py:run` initial context — the *stable* position (cache-friendly, per the v2.1 cache ordering)
- A "Knowledge" panel in the GUI (parallel to the Logs Management panel) for browsing, editing, pruning
- Per-file knowledge notes in `~/.manual_slop/knowledge/files/{file_id}.md` (parallel to `FileItem.notes` extension)

**Per-file knowledge notes (sub-candidate 11.1).** Add `notes: str = ""` to `FileItem` (one-line schema change). The harvest "files" category writes per-file notes keyed by inode. The Structural File Editor gets a "Notes" text area.

**Where it lives.** Application.

**Depends on.** `data_oriented_error_handling_20260606` (the `Result`/`ErrorInfo` pattern for the harvest LLM call's return type).

**Effort.** **Large.** 3-5 phases: (1) KnowledgeStore + digest regeneration, (2) KnowledgeHarvester + harvest-conversation prompt, (3) GUI panel + file picker, (4) aggregate.py integration + cache-position verification, (5) per-file notes + FileItem extension. ~500-800 lines + tests.

**Recommended priority.** **HIGH** (re-rank from v1; unchanged from v2).

**Cross-references:**
- v1 §6 (Per-File Memory) — adds a *knowledge* dimension alongside the *curation* dimension.
- `docs/guide_context_curation.md` (existing) — the related-but-different story.
- `docs/guide_rag.md` (existing) — the opt-in third dimension; v2.1's "RAG integration discipline" styleguide codifies when RAG fits.
- `data_oriented_error_handling_20260606` — the harvest LLM call benefits from `Result[str, list[KnowledgeBullet], ErrorInfo]`.

---

### Candidate 12: Caching Strategy (EXPANDED with cache TTL GUI) — MEDIUM

**The expansion.** v2 had only "stable-to-volatile context ordering." v2.1 adds **cache TTL GUI controls** as a sub-candidate, per the user's explicit ask.

**Part A: Stable-to-volatile context ordering (sub-candidate 12a).**
- A refactor of `src/ai_client.py:_get_combined_system_prompt` and the Anthropic-specific call site to enforce stable-to-volatile ordering
- **Stable layers** (in order, identical across turns of the same mode):
  1. Role instructions (model + provider)
  2. Tag protocol / tool protocol / function-calling schema
  3. Discovered tool descriptions
  4. System prompt (the user's chosen preset)
  5. Persona profile (if any)
  6. Project context (per `manual_slop.toml` — Candidate 14)
  7. Knowledge digest (if Candidate 11 is built)
- **Volatile layers** (per-turn, not cached):
  8. Instance facts (current discussion, current file items)
  9. Tool-call results from prior turns
  10. The user message
- The boundaries between stable and volatile are passed to Anthropic as `cache_control` breakpoints (mirroring nagent's `cache_prefix_blocks`)

**Part B: Cache TTL GUI controls (sub-candidate 12b).**
- A "Caching" tab in Operations Hub (parallel to the planned Vendor State tab)
- Per-provider cache configuration: TTL override, model eligibility, default mode (ephemeral vs explicit vs none)
- Per-discussion cache state: which discussion is currently cached, when the cache was created, when it expires
- Cache hit rate per provider (aggregated from `cache_read_input_tokens` + `cache_creation_input_tokens` usage metadata)

**Where it lives.** Application.

**Depends on.** None directly. Could leverage `qwen_llama_grok_followup_20260611`'s `send_openai_compatible()` helper for the Anthropic-specific call site.

**Effort.** Small for 12a (1-2 phases). Medium for 12b (2-3 phases).

**Recommended priority.** **MEDIUM** (unchanged from v2). The user explicitly wants the GUI controls, so 12b is part of this candidate.

**Cross-references:**
- `docs/guide_ai_client.md` §"Anthropic ephemeral + Gemini explicit caching" — the existing pattern.
- v1 §5 (The Loop) — the loop's append/parse/act structure is the volatility; the cache lives in the stable prefix.

---

### Candidate 13: Conversation Compaction — MEDIUM (unchanged from v2)

**Where it lives.** Application. The Compress button in the GUI is currently summarization; Compaction is a separate "Compact" button next to it.

**Effort.** Small to medium (1-2 phases).

**Recommended priority.** **MEDIUM** (unchanged from v2).

**Cross-references:**
- v1 §3 (Editable State) — the "compaction guidance is user-editable" pattern parallels nagent's `prompts/compact-conversation.md`.
- v1 §15.2 (Provider-specific history in process globals) — compaction might be a stepping stone to the Stateless LLMClient refactor (Candidate 3): if the conversation is compacted to a known shape, the projection of `disc_entries` to provider history becomes trivial.

---

### Candidate 14: Project Context File — LOW (unchanged from v2)

**Where it lives.** Application. `aggregate.py:run` is the consumer.

**Effort.** Small (1 phase). ~100 lines + a documentation note.

**Recommended priority.** **LOW** (unchanged from v2).

---

### Candidate 15: Save-with-Graceful-Summary-Failure — TBD (unchanged from v2)

**Where it lives.** Application.

**Effort.** **Small** (1 phase) IF the current behavior is "raise on failure." Trivial (just a test) IF the current behavior is "fall back to original."

**Recommended priority.** **TBD** — MEDIUM if the current behavior is destructive (it would be a latent bug). LOW if not. Verification first.

---

### NEW Candidate 16: AGENTS.md `@import` Pattern + Canonical DOD File — HIGH

**The user's swap instruction.** nagent added a `CLAUDE.md` that imports `context/data-oriented-design.md` via `@import`. Manual Slop has `AGENTS.md` (existing) but no canonical rules file to import. The candidate:

1. Create `conductor/code_styleguides/data_oriented_design.md` (cloned/adapted from nagent's `context/data-oriented-design.md`)
2. Update `AGENTS.md` to add `@conductor/code_styleguides/data_oriented_design.md` at the top
3. Create `./docs/AGENTS.md` (the agent-facing mirror of `docs/Readme.md`)
4. Add the same canonical file to `manual_slop.toml` `[agent.context_files]` (or equivalent) so the Application's RAG / context assembly picks it up

**Why this is HIGH priority.** Without the canonical file:
- The new styleguides (knowledge, caching, RAG discipline) lack a home
- The AGENTS.md file is just a thin pointer to itself (no actual rules)
- The agent-facing docs mirror the human-facing docs by *importing* the same rules

**Where it lives.** Both (project root, `docs/`, `conductor/code_styleguides/`).

**Effort.** Small to medium (1-2 phases). The canonical file is mostly an adaptation of nagent's; the `@import` line is one line; the `docs/AGENTS.md` is parallel to the existing `docs/Readme.md`.

**Recommended priority.** **HIGH** (re-rank from LOW in v2, because the user's AGENTS.md swap is explicit and foundational).

**Cross-references:**
- `CLAUDE.md` in nagent (the pattern source)
- `context/data-oriented-design.md` in nagent (the canonical content)
- `AGENTS.md` in Manual Slop (the existing file that gets the `@import` line)
- `docs/Readme.md` in Manual Slop (the human-facing file that stays human-facing; `./docs/AGENTS.md` is the agent mirror)

---

## 6. v2.1's revised comparison table (5 new rows, 4 updates)

| # | nagent pattern | Manual Slop equivalent (v2.1) | Verdict (v2.1) | Domain | New candidate |
|---|---|---|---|---|---|
| 1-5, 10, 12-14 | (existing v1 rows, mostly unchanged) | ... | ... | ... | ... |
| **3 (editable state)** | `--compact`, `--branch-conversation`, editable compaction prompt | Manual Slop has Take/branching + per-entry edit + UISnapshot; **has summarization, not compaction** | PARITY (DIFFERENT FOCUS) on editing; GAP on compaction | APP | 13 |
| **6 (per-file memory)** | per-file conversation + per-file knowledge notes | `FileItem` + `ContextPreset` (curation) + Fuzzy Anchors; **no `notes` field; no per-file knowledge** | PARITY (DIFFERENT KIND) on curation; GAP on notes | APP | 11 (notes sub-task) |
| **9 (sub-conversations)** | `<nagent-conversation conversation-file="name">` worker reuse; "delegation is context management" | MMA worker pool (subprocess) + 1:1 gap; new framing in docs | PARITY for MMA; GAP for 1:1; design pattern update | APP | 1 (unchanged) |
| **NEW: knowledge harvest** | `nagent-gc` → `~/.nagent/knowledge/` with provenance + sha256 ledger + digest | **THIRD memory dimension** alongside curation + discussion; RAG is opt-in and not the comparison | **GAP (Application)** | APP | **11** |
| **NEW: prompt caching strategy** | `bin/nagent:970-1014` computes boundaries; `nagent_llm.py:cache_prefix_blocks` injects `cache_control` | Manual Slop has the mechanism (`_add_history_cache_breakpoint`); ordering not enforced; no cache TTL GUI | **PARTIAL (mechanism); GAP (UX)** | APP | **12a + 12b** |
| **NEW: conversation compaction** | `--compact` with editable `prompts/compact-conversation.md` | Manual Slop has `run_discussion_compression` (summarize, not compact) | **GAP (Application)** | APP | **13** |
| **NEW: project context files** | `context.yaml` at git toplevel, install → project → root | `manual_slop.toml` per-project (TOML, different syntax) | **PARITY (DIFFERENT MECHANISM)** | APP | 14 |
| **NEW: AGENTS.md `@import` pattern** | nagent `CLAUDE.md` → `context/data-oriented-design.md` | Manual Slop has `AGENTS.md` but no canonical rules file; `./docs/AGENTS.md` not created | **GAP (Application)** | BOTH | **16** |
| **NEW: cache TTL exposure** | (nagent doesn't expose TTL; providers do) | Manual Slop has Anthropic ephemeral + Gemini explicit; no GUI for TTL or per-discussion cache | **GAP (UX)** | APP | **12b** |
| **NEW: RAG integration discipline** | (n/a — nagent has no RAG) | Manual Slop's RAG is opt-in; no codified discipline for when/where to wire it | **GAP (documentation)** | BOTH | New styleguide |

---

## 7. Staleness in v1 (revisited)

The v2 staleness map (§4 in v2) is still mostly correct. v2.1 adds:

- **§6 (Per-File Memory) of v1 is now MORE relevant.** The per-file knowledge notes pattern is a *new* dimension that complements v1's per-file curation. The v1 review said Manual Slop is "STRONGER in curation dimension" — true, but the *knowledge notes* dimension is absent. v2.1's Candidate 11 (with sub-task 11.1) addresses this.

- **§3 (Conversations Are Editable State) of v1 needs a new sub-section on compaction** (per v2.1 Candidate 13).

- **§7 (Repository History) of v1 is the analog of the new knowledge harvest.** Both are "preserve and project durable inputs." v2.1 makes this cross-reference explicit.

- **The new pattern table in v2.1's §6 is the flat reference** for the comparison. The v1 `comparison_table.md` is still correct; v2.1's 5 new rows are *additions* to that table.

---

## 8. What v2.1 changes vs v2 (the delta)

| Section in v2 | What v2.1 changes |
|---|---|
| §0 (TL;DR) | Added "reframed" labels; re-ordered rows; added cache TTL row; added RAG discipline row |
| §1 (8 new commits) | **PROMOTED** to §1 (unchanged) |
| §2.1 (Knowledge Harvest) | **REFRAMED** from "RAG alternative" to "third memory dimension"; added detailed comparison of 4 memory dimensions; added source-level citations |
| §2.2 (Prompt Caching) | **EXPANDED** to include cache TTL GUI controls (new sub-candidate 12b) |
| §2.3 (Compaction) | Added source-level citations (compaction prompt's self-review checklist, the artifact-knowledge-preservation rules) |
| §2.4 (Project Context) | **SWAPPED** CLAUDE.md → AGENTS.md; added the `docs/AGENTS.md` (new) proposal |
| §2.5-§2.9 (other patterns) | Mostly unchanged; added source-level citations |
| §2.10 (RAG integration discipline) | **NEW** — per the user's "conservative" instruction |
| §3 (13-step list) | Unchanged |
| §4 (v1 staleness) | Updated; added "RAG is not the comparison" note |
| §5 (What's still correct) | Unchanged |
| §6 (future-track candidates) | **EXPANDED** from 11 to 16 (added 12b, 16); reframed 11 |
| §7 (impact on existing candidates) | Updated to reflect new priority re-rankings |
| §8 (verification needs) | Updated; some items now have source-level evidence (e.g., Candidate 12 is now grounded in `bin/nagent:970-1014`) |
| §9 (recommended next steps) | Updated to reflect the new docs/workflow update plan (§4 above) |
| **NEW §10: source reads in full** | Lists the 13 source files I read in full with key file:line citations |
| **NEW §4 (in v2.1): proposed new artifacts** | The full list of new files for the next turn (5 new docs + 1 new styleguide dir + AGENTS.md update + workflow doc updates); explicit "do not touch" list for v1 artifacts and human Readmes |
| §10 (v2 references) | Renumbered to §11; updated |

---

## 9. Recommended next steps (revised)

1. **You review v2.1** and confirm Candidate 16 (AGENTS.md `@import` + canonical DOD file) is the right place to start. This is the foundation; the other styleguides (knowledge, caching, RAG) all need the canonical file.

2. **I create the canonical DOD file** at `conductor/code_styleguides/data_oriented_design.md` (cloned from nagent's `context/data-oriented-design.md`, adapted to Manual Slop's context). This is a 1-2 hour task; no code changes.

3. **I update `AGENTS.md`** to add the `@conductor/code_styleguides/data_oriented_design.md` line at the top, plus a "what this is" section that mirrors the nagent CLAUDE.md content but for Manual Slop. 1-2 hours.

4. **I create `./docs/AGENTS.md`** as the agent-facing mirror of `docs/Readme.md` (the human-facing docs index stays human-facing). The new file explains: which `docs/guide_*.md` is for which MMA tier; the 4 memory dimensions; the caching strategy; the styleguide index. 1-2 hours.

5. **I write the 5 new styleguides** at `conductor/code_styleguides/`:
   - `agent_memory_dimensions.md`
   - `rag_integration_discipline.md`
   - `cache_friendly_context.md`
   - `knowledge_artifacts.md`
   - `feature_flags.md` (or fold into `data_oriented_design.md`)

6. **I write the 3 new project docs** at `docs/`:
   - `guide_knowledge_curation.md`
   - `guide_caching_strategy.md`
   - `guide_agent_memory_dimensions.md`

7. **I update the existing workflow docs**:
   - `conductor/workflow.md` (add TDD protocol for the new patterns)
   - `conductor/product-guidelines.md` (add the memory dimensions section)
   - `docs/guide_mma.md` (use the new "context management" framing)
   - `docs/guide_ai_client.md` (add cache TTL section)

8. **After integration**, I update `conductor/tracks.md` to reflect the new artifacts and the v2.1 framing. The v1 track stays as-is (preserved).

9. **Verification of Candidate 15 (save-with-graceful-summary-failure)** can be done in parallel by reading `src/ai_client.py:run_discussion_compression`. Cheap source-read; high potential value.

---

## 10. v2.1 references

- **nagent source:** https://github.com/macton/nagent (at commit `eb6be32a`, 2026-06-12 00:25:50 UTC)
- **nagent v2 README:** https://github.com/macton/nagent/blob/main/README.md
- **nagent v2 commits:** `2c3c78b` (compaction), `67a3ea5` (knowledge harvest + tag parser + claude-code), `d86bce8` (CLAUDE.md), `ee72cb4` (README rewrite), `5e269ca` (project context + prompt caching + conversation direction)
- **v2 review (draft, preserved):** `conductor/tracks/nagent_review_20260608/nagent_review_v2_20260612.md` (~68KB)
- **v1 review (preserved):** `conductor/tracks/nagent_review_20260608/report.md` + `comparison_table.md` + `decisions.md` + `nagent_takeaways_20260608.md`
- **nagent source files read in full for v2.1:** `bin/nagent`, `bin/helpers/nagent_gc_lib.py`, `bin/helpers/nagent_tags.py`, `bin/helpers/nagent_llm.py`, `bin/helpers/nagent_cli.py`, `bin/helpers/nagent_file_edit_lib.py`, `bin/helpers/nagent_file_split_lib.py`, `bin/helpers/nagent_file_patch_lib.py`, `bin/helpers/nagent_file_summarize_lib.py`, `bin/nagent-gc`, `bin/nagent-llm-text`, `prompts/compact-conversation.md`, `prompts/harvest-conversation.md`, `context/data-oriented-design.md`, `CLAUDE.md`, `context.yaml`, `requirements.txt`, `config.example.json`

End of v2.1 report.
