# nagent Review v2.2 — Style + Intent DSL Survey Cross-References

**Track:** `nagent_review_20260608`
**Date:** 2026-06-12
**Author:** Tier 1 Orchestrator
**Companion to:** `nagent_review_v2_20260612.md` (v2 draft, preserved) + `nagent_review_v2_1_20260612.md` (user-revised, preserved)
**Purpose:** Apply the user's preferred data formats (table-based, forth/array-like, no JSON) and cross-reference the `intent_dsl_survey_20260612` report (which now formally codifies several v2.1 patterns as Claims 4-5 and Claims 9-10 of §6).

> **Why v2.2 exists.** v2.1 was the user-revised delta. Three things changed since v2.1 was committed:
>
> 1. The user published `intent_dsl_survey_20260612/report_v1.2.md` (1367 lines, 10 prior-art clusters, 4 anchor claims, ~42-verb vocab, 10 AI-Agent Properties).
> 2. The user said: *"I don't really like JSON, I like table based formats more, or things that are forth/array-like."*
> 3. The survey's §6 Claims 4 and 5 *explicitly reference* the v2.1 nagent review: *"per `conductor/tracks/nagent_review_20260608/nagent_review_v2_1_20260612.md §2.1`"* (line 526) and *"per nagent v2.1 §2.2 stable-to-volatile ordering"* (line 536). The v2.1 patterns are now formally codified; v2.2 is the in-dialogue update.
>
> v2.2 is **focused delta**, not a rewrite. The 6 §2.X sub-sections of v2.1 are now 5 (the per-file knowledge notes pattern is folded into §2.1 knowledge harvest). The tables adopt the §4.4 7-column "Symbol | Name | Signature | Semantics | Example | Borrowed from | Shape" layout from the intent DSL survey. JSON blocks become tables. The comparison table (§5) and future-track candidate list (§6) are reformatted in the survey's style.
>
> **What v2.2 does NOT change.** v1 artifacts (preserved per user instruction), v2 draft (preserved), v2.1 (preserved). The 6 patterns in v2.1 §2.1-2.10 are correct; v2.2 just *re-formats* them in the user's preferred style and adds cross-references. The new styleguides + new agent-facing files proposed in v2.1 §4 are still the proposed artifacts; v2.2 §11 notes they should follow the intent DSL survey's format.

---

## 0. TL;DR (reformatted in §4.4 style)

| # | nagent v2 pattern | Maps to (intent DSL survey) | Manual Slop equivalent | Verdict | Shape | New candidate |
|---|---|---|---|---|---|---|
| 1 | Knowledge harvest (`nagent-gc` → `~/.nagent/knowledge/`) | §6 Claim 4 (4 memory dimensions) | THIRD memory dimension: curation + discussion + RAG (opt-in) + knowledge | GAP | `o->` (codecycle: harvest → digest → inject) | **11 (HIGH)** |
| 2 | Prompt caching w/ stable-to-volatile ordering | §6 Claim 5 | `_add_history_cache_breakpoint` + `cache_control` blocks (mechanism present, ordering not enforced); no cache TTL GUI | PARTIAL | `->M->` (merge at volatile boundary) | **12a (MED)** |
| 2b | Cache TTL GUI controls | (NEW; no survey claim) | Anthropic ephemeral 5min + Gemini explicit 1h, no GUI | GAP (UX) | `=>` (per-provider control surface) | **12b (MED)** |
| 3 | Conversation compaction (`--compact`) | (NEW; no survey claim) | `run_discussion_compression` = summarize, not compact | GAP | `->B->` (try/recover envelope) | **13 (MED)** |
| 4 | Project context files (`context.yaml`) | (no survey claim) | `manual_slop.toml` per-project (TOML ≠ YAML) | PARITY-DIFFERENT-MECHANISM | `[I]` | 14 (LOW) |
| 5 | claude-code provider (5th provider, sub. auth) | (no survey claim) | `_send_gemini_cli` (parallel pattern) | PARITY | `[I]` | none (provider add) |
| 6 | Per-file knowledge notes (`knowledge/files/{file_id}.md`) | §6 Claim 4 (knowledge dim) | `FileItem.notes` absent | GAP | `[I]` | 11.1 (bundle) |
| 7 | "Delete to turn off" feature flags | (no survey claim) | `[ai_settings.toml]` toggles | PARITY-DIFFERENT-MECHANISM | `[I]` | none (styleguide) |
| 8 | Save-with-graceful-summary-failure | §6 Claim 6 (Result[T] envelope) | `run_discussion_compression` failure mode **TBD** | UNKNOWN | `->B->` | 15 (TBD) |
| 9 | AGENTS.md `@import` pattern | §6 Claim 1 (Domain = Meta-Tooling) | `AGENTS.md` exists, no canonical rules file | GAP | `[I]` | **16 (HIGH)** |
| 10 | Delegation = context mgmt, not parallelism | §1 Claim 3 (immediate-mode) | MMA subprocess + Context Amnesia (already does this) | PARITY (new framing) | `=>` | none (styleguide) |
| 11 | RAG integration discipline | (NEW; no survey claim) | `src/rag_engine.py` opt-in; no codified discipline | GAP (doc) | `[I]` | styleguide |

**Headline.** v2.1's 4 memory dimensions and stable-to-volatile cache ordering are now **formally codified** in the intent DSL survey as §6 Claims 4 and 5. The v2.1 review *was the seed* for those survey claims (the survey cites v2.1:50 and v2.1 §2.2 by name). The new styleguides + canonical DOD file proposed in v2.1 §4 should follow the survey's table format (Symbol, Name, Signature, Semantics, Example, Borrowed from, Shape).

---

## 1. The 4 anchor claims (from intent DSL survey §1) — applied to the nagent review

The intent DSL survey establishes 4 anchor claims for the Meta-Tooling domain. The nagent v2.1 review was hand-waving the same 4 claims in the Application/Meta-Tooling framing. v2.2 makes the cross-reference explicit:

| # | Anchor claim | Source | nagent v2.1/v2.2 application |
|---|---|---|---|
| 1 | **Intent is declarative** | Jofito heritage (per `intent_dsl_survey_20260612` §1.1) | The user names the *intent* (knowledge harvest, compaction, caching); the verbs and infrastructure handle the *how*. The 4 memory dimensions are the *user's intent verbs*; the bridge script and MCP tools are the *how*. |
| 2 | **Hardware is the truth** | Onat/Lottes 2-register model (per survey §1.2) | The stable-to-volatile cache ordering maps to Anthropic's `cache_control` block boundaries (`bin/nagent:970-1014`); the per-file knowledge notes key by inode (`st_dev:st_ino`) because the *filesystem* is the durable hardware. |
| 3 | **The pipeline is immediate-mode** | O'Donnell IMGUI (per survey §1.3) | The 4 memory dimensions are *immediate-mode* projections of underlying data; the digest is regenerated per turn from category files, not maintained as state. The harvest itself is a `try { ... } recover { ... }` codepath. |
| 4 | **The vocabulary is the user surface** | CoSy (per survey §1.4) | The 4 memory dimensions, the 3 compaction operations (Keep/Compress/Compact), the cache TTL controls, the 33 Command Palette commands — these ARE the user surface. A future spec for an agent doesn't need a new API; it just adds a new vocabulary item. |

The 4 claims compose: a user expresses intent (Claim 1) using a vocabulary verb (Claim 4) that maps to a hardware/software stage (Claim 2) in an immediate-mode composition (Claim 3). The nagent v2 patterns are *working examples* of this composition.

---

## 2. Revised new-pattern analysis (style applied)

### 2.1 Knowledge harvest — re-framed as THIRD memory dimension

| Dim | Where it lives | What it stores | How edited | How queried | SSDL shape |
|---|---|---|---|---|---|
| Curation | `FileItem` + `ContextPreset` + Fuzzy Anchors | *How to render a file* in the AI's context window | Structural File Editor; project TOML | `aggregate.py:run` at discussion start | `[Q]` |
| Discussion | `app.disc_entries` + branching + UISnapshot | *What was said* in the conversation | GUI `[Edit]` mode; `[Branch]`; undo/redo | `build_markdown` renders as prior context | `o->` (entries accumulate) |
| RAG | `src/rag_engine.py` (ChromaDB) | *Semantic fingerprints* of indexed files | (opaque vector store) | `RAGEngine.search()` at LLM call time | `[Q]` (vector similarity) |
| Knowledge (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 | Plain markdown edit | Bounded digest injected as stable prefix | `o->` (harvest → digest → inject) |

**The harvest output schema** (was JSON in v2.1 §2.1; now a table per the user's style):

| Category | Type | Example | Provenance? | Per-file? |
|---|---|---|---|---|
| `facts` | `{statement, detail}` | `"The system has 4 memory dimensions"` | yes | no |
| `decisions` | `{statement, detail}` | `"Knowledge harvest is a complement to RAG, not a replacement"` | yes | no |
| `tasks_done` | `{statement, detail}` | `"v2.1 review identified 10 future-track candidates"` | yes | no |
| `tasks_open` | `{statement, detail}` | `"Create canonical DOD file at conductor/code_styleguides/data_oriented_design.md"` | yes | no |
| `questions` | `{statement, detail}` | `"Where does intent resolution live — per-verb, per-block, or global?"` | yes | no |
| `playbooks` | `{name, steps}` | `"Knowledge Harvest: scan → classify → LLM-distill → append → digest → reclaim"` | yes | no |
| `files` | `{path, note}` | `"src/ai_client.py: Add cache TTL GUI for Anthropic + Gemini"` | yes | yes (keyed by inode) |

**The harvest codepath** (was a paragraph; now SSDL notation):

```
[Q:conversation]
   │
   ▼
[Q:size > 64KB?]
   ├─ yes ──► [I:summarize] ──► [I:build_harvest_prompt]
   └─ no  ─────────────────────► [I:build_harvest_prompt]
                                   │
                                   ▼
                              [I:LLM call (up to 2 attempts)]
                                   │
                              [B:valid JSON?]
                              ├─ yes ──► [I:merge_harvest] ──► [I:regenerate_digest]
                              └─ no  ──► [I:retry with "Return only JSON" suffix]
                                                                 │
                                                                 ▼
                                                            [S:reclaim]
```

Per `bin/helpers/nagent_gc_lib.py` (the actual source for the v2.1 review). The `try { harvest } recover { audit_failure }` envelope returns a `Result[list[KnowledgeBullet], ErrorInfo]` per the survey's §6 Claim 6.

**Cross-reference to intent DSL survey §6 Claim 4:** *"The DSL does not replace any of the 4 memory dimensions (per nagent_review_v2_1 §2.1)."* The v2.1 review is the seed; the survey is the formal codification.

### 2.2 Caching strategy — stable-to-volatile ordering + cache TTL GUI

**Part A: stable-to-volatile context ordering** (the v2.1 pattern, grounded in source)

The block order in `bin/nagent:606-745` `build_initial_context`:

| Layer | Layer name | Stable across turns? | SSDL | Source |
|---|---|---|---|---|
| 1 | `NAGENT_PREAMBLE` | yes | `[I]` | `bin/nagent:692` |
| 2 | `role_instructions` | yes | `[I]` | `bin/nagent:694` |
| 3 | Protocol rules + tag list | yes | `[I]` | `bin/nagent:696-712` |
| 4 | Context management rules | yes | `[I]` | `bin/nagent:715-731` |
| 5 | `file_edit_rules` | yes | `[I]` | `bin/nagent:733` |
| 6 | `tools_block` | yes | `[I]` | `bin/nagent:734` |
| 7 | `install_context_block` | yes | `[I]` | `bin/nagent:638-640` |
| 8 | `project_context_block` | yes | `[I]` | `bin/nagent:645-656` |
| 9 | `root_context_block` | yes | `[I]` | `bin/nagent:657-658` |
| 10 | `knowledge_block` | yes (regenerated per gc, but stable within a gc cycle) | `[I]` | `bin/nagent:677-685` |
| 11 | `file_edit_detail_block` | yes (for the same file_edit) | `[I]` | `bin/nagent:659-675` |
| 12 | `Instance:` | **NO** (volatile) | `───` (data, not code) | `bin/nagent:735-738` |
| 13 | `Environment:` | **NO** (volatile) | `───` (data, not code) | `bin/nagent:740-745` |

Cache boundaries computed at `bin/nagent:970-987` (`conversation_cache_boundaries`):
- Boundary 1: `volatile_at` = offset of `\nInstance:` (start of volatile)
- Boundary 2: `span[1]` = end of the `<initial_context>` block

These are passed to `bin/helpers/nagent_llm.py:cache_prefix_blocks` which wraps each prefix in `cache_control: {"type": "ephemeral"}` (max 3 prefix blocks per Anthropic's 4-breakpoint limit).

**The codepath** (SSDL):

```
[Q:conversation_text]
   │
   ▼
[I:find_block_span(<initial_context>)]
   │
   ▼
[Q:offset of \nInstance:?]
   │
   ├──► [I:boundaries.append(offset)]
   │
   ▼
[Q:end of <initial_context> < len(text)?]
   │
   ├──► [I:boundaries.append(end)]
   │
   ▼
[I:cache_prefix_blocks(text, boundaries)]
   │
   ▼
[I:anthropic.messages.create(content=prefix_blocks)]
   │
[T:return LlmResult]
```

**Part B: cache TTL GUI controls** (the v2.1 new sub-candidate)

| Provider | Cache type | Default TTL | Configurable? | GUI control needed? |
|---|---|---|---|---|
| Anthropic | ephemeral | 5 min (per-request) | yes (via prompt cache breakpoints) | per-discussion cache state; TTL display |
| Google (Gemini) | explicit | 1 h (default) | yes (via `ttl` field) | per-discussion cache state; TTL override |
| OpenAI | implicit (auto) | 5-10 min (provider-managed) | no (provider-managed) | cache hit rate only |
| Others | varies | varies | varies | varies |

The proposed GUI surface (a "Caching" tab in Operations Hub):

```
+------------------------------------------------------+
| Caching                                              |
+------------------------------------------------------+
| [Anthropic]   in:340 cache:80  hit:23%  ttl:4:32   |  <- per-provider summary
| [Gemini]      in:120 cache:0   hit:0%   ttl:0:00   |
| [OpenAI]      in:560 cache:200 hit:35%  ttl:n/a    |
+------------------------------------------------------+
| Discussion "refactor auth"                           |
|   cached: yes (Anthropic)                            |
|   expires: 2026-06-12T15:32 (in 4:32)                |
|   [Invalidate cache] [Disable caching for this]      |
+------------------------------------------------------+
| Global settings                                      |
|   [X] Enable Anthropic ephemeral caching             |
|   [X] Enable Gemini explicit caching                 |
|   [ ] Allow >1h Gemini caches (charges may apply)    |
|   Anthropic default TTL: [5 min v]                   |
|   Gemini default TTL:    [60 min v]                  |
+------------------------------------------------------+
```

**Cross-reference to intent DSL survey §6 Claim 5:** *"The DSL's `tape { }` blocks are cache-friendly per nagent v2.1 §2.2 stable-to-volatile ordering. The DSL's audit logs (Tier 4 `audit` verb) are a stable layer that can be cached across turns. The DSL's pipeline output is a volatile layer appended per turn."* The v2.1 pattern + the cache TTL GUI controls = Candidate 12.

### 2.3 Conversation compaction

| nagent v2 | Manual Slop today | Verdict | Shape | Source |
|---|---|---|---|---|
| `--compact` (rewrites conversation preserving structure) | `run_discussion_compression` (summarizes; loses structure) | GAP | `->B->` (try/recover envelope) | `bin/nagent:1975-2019` + `prompts/compact-conversation.md` |

**The compaction prompt's self-review checklist** (10 yes/no questions, abbreviated):

| # | Self-review question | Verifies |
|---|---|---|
| 1 | Can another worker continue immediately? | preserved capability |
| 2 | Would expensive investigation need to be repeated? | preserved artifacts |
| 3 | Are accepted decisions preserved? | decision retention |
| 4 | Are constraints preserved? | constraint retention |
| 5 | Are important failures preserved? | failure retention |
| 6 | Are artifact references preserved? | ref retention |
| 7 | Has duplicated information been removed? | dedup |
| 8 | Has chronology been replaced with state? | state vs flow |
| 9 | Is the conversation substantially smaller? | compression |
| 10 | Is future capability unchanged or improved? | outcome preservation |

This is a contract for the compaction operation. Manual Slop's `Compress` button doesn't have a contract; a future `Compact` button should adopt this checklist.

### 2.4 Project context files + AGENTS.md `@import` pattern

| nagent v2 | Manual Slop today | Verdict | Shape | Action |
|---|---|---|---|---|
| `context.yaml` at git toplevel (markdown/YAML) | `manual_slop.toml` (TOML, project-level) | PARITY-DIFFERENT-MECHANISM | `[I]` | 14 (LOW) |
| `CLAUDE.md` imports `context/data-oriented-design.md` via `@import` | `AGENTS.md` exists, no canonical rules file to import | GAP | `[I]` | **16 (HIGH)** |
| Same file injected via `context.yaml` for runtime | (would inject via `manual_slop.toml [agent]` section or similar) | GAP | `[I]` | **16 (HIGH)** |

The pattern: a canonical rules file (`conductor/code_styleguides/data_oriented_design.md`) imported by `AGENTS.md` (for the agent harness) AND injected via project config (for the Application's RAG/context assembly). One source of truth, two consumers.

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

| nagent v2 (5th provider) | Manual Slop equivalent | Verdict | Shape |
|---|---|---|---|
| `claude-code` via Claude Agent SDK; `model=None` for default mode; tools disabled by default | `_send_gemini_cli` (local subprocess auth) | PARITY | `[I]` |

Source: `bin/helpers/nagent_llm.py:65-80` + `_claude_code_generate` (lines 195-220). Not a new track; provider addition only if user wants.

### 2.6 Per-file knowledge notes

| nagent v2 | Manual Slop today | Verdict | Shape |
|---|---|---|---|
| `knowledge/files/{file_id}.md` keyed by inode (`st_dev:st_ino`) | `FileItem.notes: str = ""` (absent) | GAP | `[I]` |

Source: `bin/helpers/nagent_gc_lib.py:merge_harvest` "files" branch. If path resolves → `file_knowledge_path(root, file_id)`; else fall back to `facts.md`. Bundle with Candidate 11.

### 2.7 "Delete to turn off" feature flags

| nagent v2 | Manual Slop today | Verdict | Shape |
|---|---|---|---|
| `rm digest.md` → `build_initial_context` `if knowledge_digest:` check skips injection | `[ai_settings.toml]` toggles + GUI checkboxes | PARITY-DIFFERENT-MECHANISM | `[I]` |

Source: `bin/helpers/nagent_gc_lib.py:regenerate_digest` deletes the file when sections are empty; `bin/nagent:677-685` checks for existence. The "feature flag is a file" pattern. Worth a styleguide.

### 2.8 Save-with-graceful-summary-failure

| nagent v2 | Manual Slop today | Verdict | Shape |
|---|---|---|---|
| Save indexes the copy even when summary LLM fails; `(summary unavailable)` marker | `run_discussion_compression` failure mode **TBD** | UNKNOWN | `->B->` |

Cross-reference to intent DSL survey §6 Claim 6: `Result[T]` envelope with side-channel errors. The graceful-failure pattern is the *concrete instance* of the `Result[T]` convention.

### 2.9 Delegation = context management, not parallelism

| nagent v2 | Manual Slop today | Verdict | Shape |
|---|---|---|---|
| "Hand off when noisy: distill goal/state/decisions into a sub-conversation prompt, delegate the rest" | MMA worker pool (subprocess + Context Amnesia) | PARITY (new framing) | `=>` (wide: parent + child codepaths) |

Source: `bin/nagent:730` (the "Hand off when noisy" line in `build_initial_context`). Update `docs/guide_mma.md` with the new framing; matches intent DSL survey §1 Claim 3 (immediate-mode).

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

| Where RAG fits | Where RAG does NOT fit | Source |
|---|---|---|
| Semantic search across large codebases ("where does X happen?") | Per-file curation (FileItem + ContextPreset) | v2.1 §2.10 |
| Concept-level discovery ("how does the execution clutch work?") | Per-discussion context (discussion memory) | v2.1 §2.10 |
| Cross-file pattern matching grep can't do | Knowledge harvest (third memory dimension) | v2.1 §2.10 |
| | Per-file knowledge notes | v2.1 §2.10 |

**The discipline** (codified as a styleguide in v2.1 §4.2):

1. RAG is opt-in. Default-off in new projects.
2. RAG complements, never replaces, the other memory dimensions.
3. RAG results 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.
6. RAG failure mode is graceful: failed search returns empty, never crashes.

---

## 3. v2.2's revised future-track candidate list (16 candidates, table format)

Each candidate row: Symbol-like ID, Name, Domain, Priority, Effort, Shape, Dependencies, Cross-references.

| # | Name | Domain | Priority | Effort | Shape | Depends on | Cross-refs |
|---|---|---|---|---|---|---|---|
| 1 | `SubConversationRunner` (1:1 sub-convos) | App + MT | HIGH | Med | `=>` | none | survey §6 Claim 1 |
| 2 | RAG pre-staging via sub-convo | App | MED (down) | Sm | `o->` | 1 | survey §6 Claim 4 (knowledge dim) |
| 3 | Stateless `LLMClient` class | App | MED | Lg | `[I]` | none | survey §1 Claim 3 (immediate-mode) |
| 4 | Intent DSL for Meta-Tooling | MT | LOW | research | `[I]` | none | **`intent_dsl_survey_20260612` is the substantiation** |
| 5 | Self-describing MCP tools | BOTH | LOW (subsumed) | Med | `[I]` | `mcp_architecture_refactor` | survey Cluster 4 (Metadesk) |
| 6 | `src/git_history.py` (nagent §7) | App | MED | Med | `[I]` | none | (no survey claim) |
| 7 | Per-file conversation log | App | LOW | Sm | `[I]` | 3 | survey §6 Claim 4 (knowledge dim, per-file) |
| 8 | `py_/ts_c_coedited_files` tools | App | LOW | Sm | `[I]` | 6 | (no survey claim) |
| 9 | Explicit `split_lib.py` / `patch_lib.py` | App | DEFER | Med | `[I]` | none | (no survey claim) |
| 10 | Raw-transcript persistence per Take | App | LOW | Sm | `[I]` | 3 | (no survey claim) |
| **11** | **Knowledge memory (third dimension)** | App | **HIGH** | Lg | `o->` | `data_oriented_error_handling` | **survey §6 Claim 4** |
| **12a** | Stable-to-volatile cache ordering | App | MED | Sm | `->M->` | none | **survey §6 Claim 5** |
| **12b** | Cache TTL GUI controls | App | MED | Med | `=>` | 12a | (no survey claim) |
| **13** | Conversation compaction | App | MED | Sm | `->B->` | none | survey §6 Claim 6 (Result envelope) |
| **14** | Project context file | App | LOW | Sm | `[I]` | none | (no survey claim) |
| **15** | Save-with-graceful-summary-failure | App | TBD | Sm | `->B->` | none | survey §6 Claim 6 |
| **16** | **AGENTS.md `@import` + canonical DOD** | BOTH | **HIGH** | Sm | `[I]` | none | survey §1 (the 4 anchor claims) |

**Net effect.** 16 candidates (up from 10 in v1; up from 11 in v2; up from 12 in v2.1). 4 are HIGH priority (1, 11, 16; + SubConversationRunner). 5 are MEDIUM (2, 3, 6, 12a, 12b, 13). 3 are subsumed/deferred (4, 5, 9). 4 are LOW (7, 8, 10, 14). 1 is TBD (15).

---

## 4. v2.2's revised comparison table (5 new rows, in §4.4 style)

| # | nagent v2 pattern | Survey cross-ref | Manual Slop equivalent | Verdict | Shape |
|---|---|---|---|---|---|
| 1-5, 10, 12-14 | (v1 rows, mostly unchanged) | ... | ... | ... | ... |
| 3 (editable state) | `--compact`, `--branch-conversation`, editable compaction prompt | §3.5 (try/recover envelope) | Take/branching + per-entry edit + UISnapshot; summarize, not compact | PARITY (DIFF FOCUS) on editing; GAP on compaction | `->B->` |
| 6 (per-file memory) | per-file conversation + per-file knowledge notes | §6 Claim 4 (per-file knowledge) | `FileItem` + `ContextPreset` + Fuzzy Anchors; no `notes` field | PARITY (DIFF KIND) on curation; GAP on notes | `[I]` |
| 9 (sub-convos) | `<nagent-conversation conversation-file="name">` worker reuse; "delegation is context management" | §1 Claim 3 (immediate-mode) | MMA worker pool (subprocess) + 1:1 gap; new framing in docs | PARITY for MMA; GAP for 1:1; design pattern update | `=>` |
| **Knowledge harvest** (NEW) | `nagent-gc` → `~/.nagent/knowledge/` + provenance + sha256 ledger + digest | **§6 Claim 4** | **THIRD memory dimension** alongside curation + discussion; RAG is opt-in, not the comparison | **GAP (Application)** | `o->` |
| **Prompt caching strategy** (NEW) | `bin/nagent:970-1014` boundaries; `nagent_llm.py:cache_prefix_blocks` | **§6 Claim 5** | `_add_history_cache_breakpoint`; ordering not enforced; no TTL GUI | **PARTIAL + GAP (UX)** | `->M->` |
| **Conversation compaction** (NEW) | `--compact` with editable `prompts/compact-conversation.md` | §3.5 (envelope) | `run_discussion_compression` (summarize, not compact) | **GAP** | `->B->` |
| **Project context files** (NEW) | `context.yaml` at git toplevel, install → project → root | (no survey claim) | `manual_slop.toml` per-project (TOML ≠ YAML) | **PARITY (DIFF MECH)** | `[I]` |
| **AGENTS.md `@import`** (NEW) | nagent `CLAUDE.md` → `context/data-oriented-design.md` | **§1 (the 4 anchor claims)** | `AGENTS.md` exists, no canonical rules file; `./docs/AGENTS.md` not created | **GAP** | `[I]` |
| **Cache TTL exposure** (NEW) | (n/a — providers do this) | (no survey claim) | Anthropic 5min ephemeral + Gemini 1h explicit, no GUI | **GAP (UX)** | `=>` |
| **RAG integration discipline** (NEW) | (n/a — nagent has no RAG) | (no survey claim) | `src/rag_engine.py` opt-in; no codified discipline | **GAP (doc)** | `[I]` |

---

## 5. Staleness in v1 (cross-referenced to survey)

| v1 section | Staleness | Action | Cross-ref to survey |
|---|---|---|---|
| §1 (Durable Work) | PARTIALLY stale (no knowledge harvest or stable-to-volatile ordering) | Append knowledge harvest as a "what files buy you" consequence | §6 Claim 4 |
| §3 (Editable State) | STALE (no `--compact`, `--branch-conversation`, compaction guidance) | Add sub-section on compaction as distinct from summarization | §3.5 (envelope) + §6 Claim 6 |
| §6 (Per-File Memory) | STALE (no per-file knowledge notes) | Add a paragraph on per-file notes as a NEW dimension | §6 Claim 4 (per-file) |
| §7 (Repository History) | STILL CORRECT | none | (analogue of harvest; both are "preserve and project durable inputs") |
| §8 (Neighborhoods) | STALE (no "everything else files buy you") | Add cross-reference to survey §1 Claim 4 (vocabulary is surface) | §1 Claim 4 |
| §9 (Sub-Conversations) | STALE (no worker-reuse or compaction-via-handoff) | Add paragraph on reframing + worker-reuse | §1 Claim 3 |
| §14 (Build Your Own) | STALE (12 → 13 steps; harvest added) | Bump to 13 | §1 (4 anchor claims) |
| §15 (Pitfalls) | STALE (no knowledge / no stable-volatile / no compaction) | Add 3 new pitfalls (or replace 3 of 6) | §6 Claims 4, 5, 6 |

---

## 6. v2.2 changes vs v2.1 (the delta)

| v2.1 section | v2.2 change | Reason |
|---|---|---|
| §0 (TL;DR) | Reformatted in §4.4 style with SSDL shape tags | user style preference |
| §2.1 (Knowledge Harvest) | JSON block → table; added cross-ref to survey §6 Claim 4 | user style + survey codification |
| §2.2 (Caching) | Block order table (12 layers); added Part B (cache TTL GUI) | user style + v2.1 sub-candidate |
| §2.4 (Project Context) | Swapped CLAUDE.md → AGENTS.md; added Candidate 16 | v2.1 correction |
| §2.5-§2.9 (other patterns) | Mostly unchanged; shape tags added | user style |
| §2.10 (RAG discipline) | Unchanged | n/a |
| §3 (Build Your Own) | Unchanged | n/a |
| §4 (proposed artifacts) | Will be updated in §8 below | user style |
| §5 (comparison table) | Reformatted in §4.4 style; 5 new rows | user style + survey codification |
| §6 (future-track candidates) | Reformatted as a single 16-row table with all metadata columns | user style |
| §7 (staleness) | Updated with cross-refs to survey | survey codification |
| §8 (changes vs v2) | Renumbered to §9 | n/a |
| §9 (next steps) | Updated to reflect the new style + survey cross-refs | n/a |
| §10 (references) | Renumbered to §10; added `intent_dsl_survey_20260612` | n/a |
| **NEW §11: in dialogue with intent DSL survey** | Added (see below) | survey cross-refs |

---

## 7. Source reads in full (unchanged from v2.1)

v2.2 re-uses v2.1's source-read table. The intent DSL survey added 8 new "source reads" (the 8 research clusters). Cross-references to those clusters are inline throughout v2.2.

---

## 8. Proposed new artifacts (next turn, in §4.4 table format)

| File path | Type | Purpose | Cross-ref |
|---|---|---|---|
| `conductor/code_styleguides/data_oriented_design.md` | NEW styleguide | Canonical DOD reference (cloned/adapted from nagent's `context/data-oriented-design.md`) | survey §1 (4 anchor claims) |
| `AGENTS.md` | UPDATE | Add `@conductor/code_styleguides/data_oriented_design.md` import | nagent CLAUDE.md pattern |
| `./docs/AGENTS.md` | NEW | Agent-facing mirror of `docs/Readme.md` | survey §6 Claim 1 (Meta-Tooling) |
| `conductor/code_styleguides/agent_memory_dimensions.md` | NEW | Codify the 4 memory dimensions | survey §6 Claim 4 |
| `conductor/code_styleguides/rag_integration_discipline.md` | NEW | Codify the conservative-RAG rule | v2.1 §2.10 |
| `conductor/code_styleguides/cache_friendly_context.md` | NEW | Codify stable-to-volatile ordering + TTL GUI contract | survey §6 Claim 5 |
| `conductor/code_styleguides/knowledge_artifacts.md` | NEW | Codify knowledge harvest pattern | survey §6 Claim 4 |
| `conductor/code_styleguides/feature_flags.md` | NEW | Codify "delete to turn off" pattern | nagent `regenerate_digest` |
| `docs/guide_knowledge_curation.md` | NEW | The third memory dimension guide | survey §6 Claim 4 |
| `docs/guide_caching_strategy.md` | NEW | Caching across providers | survey §6 Claim 5 |
| `docs/guide_agent_memory_dimensions.md` | NEW | Cross-cutting: 4 memory dimensions | survey §6 Claim 4 |
| `conductor/workflow.md` | UPDATE | Add TDD protocol for new patterns | survey §3 (grammar) |
| `conductor/product-guidelines.md` | UPDATE | Add memory dimensions section | survey §1 (anchor claims) |
| `docs/guide_mma.md` | UPDATE | Use "context management" framing | survey §1 Claim 3 |
| `docs/guide_ai_client.md` | UPDATE | Add cache TTL section | survey §6 Claim 5 |

**Format commitment for the new artifacts.** All new files (styleguides, project docs, workflow doc updates) will follow the §4.4 7-column table format (Symbol, Name, Signature, Semantics, Example, Borrowed from, Shape) where applicable. JSON blocks become tables. Code examples use the survey's grammar primitives (`name := value`, `for x .. n`, `if cond { ... }`, `tape { ... }`, `try { ... } recover { ... }`, `sandbox { ... }`, `audit msg`, `fuzzy { ... }`).

---

## 9. Recommended next steps

1. **User review of v2.2** + confirmation of which new artifacts to create in the next turn.
2. **I create the canonical DOD file** at `conductor/code_styleguides/data_oriented_design.md` (cloned/adapted from nagent's `context/data-oriented-design.md`). This is the foundation.
3. **I update `AGENTS.md`** to add the `@import` line + "what this is" section (in the §4.4 table format).
4. **I create `./docs/AGENTS.md`** as the agent-facing mirror of `docs/Readme.md`. Note the survey's `docs/guide_meta_boundary.md` §"Domain 2" framing.
5. **I write the 5 new styleguides** + 3 new project docs in the §4.4 table format.
6. **I update the existing workflow docs** (`conductor/workflow.md`, `conductor/product-guidelines.md`, `docs/guide_mma.md`, `docs/guide_ai_client.md`) to use the survey's grammar primitives and the §4.4 table format.
7. **I verify Candidate 15** (save-with-graceful-summary-failure) by reading `src/ai_client.py:run_discussion_compression`. Cheap source-read; high potential value.
8. **After integration**, I update `conductor/tracks.md` to reflect the new artifacts and the v2.2 cross-references.

---

## 10. References

- **Intent DSL survey** (the new formal codification): `conductor/tracks/intent_dsl_survey_20260612/report_v1.2.md` (1367 lines, 10 prior-art clusters, 4 anchor claims, ~42-verb vocab, 10 AI-Agent Properties)
- **nagent source:** https://github.com/macton/nagent (at commit `eb6be32a`, 2026-06-12 00:25:50 UTC)
- **v2 review (preserved):** `nagent_review_v2_20260612.md`
- **v2.1 review (preserved):** `nagent_review_v2_1_20260612.md`
- **v1 review (preserved):** `report.md` + `comparison_table.md` + `decisions.md` + `nagent_takeaways_20260608.md`
- **Other format references:**
  - `docs/reports/computational_shapes_ssdl_digest_20260608.md` (the 6 SSDL primitives)
  - `docs/reports/ascii_sketch_ux_workflow_20260608.md` (the 10 ASCII sketch conventions)
  - `docs/reports/proposed_new_tracks_20260608.md` (the 4-tier proposal format)

---

## 11. In dialogue with the intent DSL survey (NEW in v2.2)

The intent DSL survey is the **formal codification** of the patterns the nagent v2.1 review identified. The v2.1 review was the seed; the survey grew out of it. The cross-references:

| nagent v2.1 pattern | Intent DSL survey codification | Survey citation |
|---|---|---|
| 4 memory dimensions (curation, discussion, RAG, knowledge) | §6 Claim 4 — *"The DSL does not replace any of the 4 memory dimensions (per nagent_review_v2_1 §2.1)"* | `report_v1.2.md:524-532` |
| Stable-to-volatile cache ordering (Candidate 12) | §6 Claim 5 — *"per nagent v2.1 §2.2 stable-to-volatile ordering"* | `report_v1.2.md:534-536` |
| Sandbox as IEventTarget boundary | §6 Claim 9 — *"O'Donnell's IEventTarget pattern as the `sandbox` verb"* | `report_v1.2.md:550-554` |
| Cheap Tier 2 verbs ("reads are free") | §6 Claim 10 — *"O'Donnell's 'reads are free' claim as the rationale for cheap verbs"* | `report_v1.2.md:556-562` |
| Result envelope on AI-fuzzing tolerance | §6 Claim 6 — *"`Result[T]` envelope"* (also Cluster 7) | `report_v1.2.md:538-540` |
| Candidate 4 (Intent DSL for Meta-Tooling) | The intent DSL survey IS Candidate 4's substantiation | `report_v1.2.md` (whole report) |
| 4 anchor claims (intent, hardware, immediate-mode, vocabulary) | §1 — anchors the whole report; the nagent v2.1 review shares the "immediate-mode" + "vocabulary is surface" claims | `report_v1.2.md:19-70` |
| `try { ... } recover { ... }` error envelope | §3.5 — the formal grammar (vs. v2.1's prose description) | `report_v1.2.md:347-361` |
| "Reads are free, writes formalized" (O'Donnell) | §1 Claim 3 + §6 Claims 9-10 | `report_v1.2.md:42-51, 550-562` |

**The dialogue pattern.** v2.1 was the *ground* the survey built on. v2.2 is the *ground the survey built* — the v2.1 review is now better-grounded by the survey's formal claims. The next turn's artifacts (the new styleguides + agent-facing files) will be the *consolidation* — applying both v2.1's patterns and the survey's formalization to a single set of canonical Manual Slop docs.

**The 3 mutual cross-references that the user should know about:**

1. **v2.1 §2.1 (Knowledge Harvest) is referenced in `report_v1.2.md:526`.** The v2.1 reframe as "third memory dimension" is what the survey's Claim 4 inherited.
2. **v2.1 §2.2 (Stable-to-Volatile Cache Ordering) is referenced in `report_v1.2.md:536`.** The v2.1 cache ordering analysis is what the survey's Claim 5 inherited.
3. **The "delete to turn off" pattern (v2.1 §2.7) is now part of the survey's broader "feature flag is a file" framing** (per the survey's Cluster 0 + Cluster 5 + Claim 4 discussion).

End of v2.2 report.
