diff --git a/conductor/tracks/nagent_review_20260608/metadata.json b/conductor/tracks/nagent_review_20260608/metadata.json index 35ed2050..30e2ba2c 100644 --- a/conductor/tracks/nagent_review_20260608/metadata.json +++ b/conductor/tracks/nagent_review_20260608/metadata.json @@ -229,5 +229,42 @@ "https://github.com/macton/nagent (nagent source code)", "https://github.com/macton/nagent/blob/main/README.md (nagent README)" ] + }, + "v2_2_review": { + "date": "2026-06-12", + "report": "nagent_review_v2_2_20260612.md", + "status": "v2.2 is the focused delta applying the user's data-format preferences and cross-referencing intent_dsl_survey_20260612; v2 and v2.1 are preserved", + "user_input_acknowledged": [ + "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)", + "User said: 'I don't really like JSON, I like table based formats more, or things that are forth/array-like'", + "Survey's §6 Claims 4 and 5 explicitly cite nagent_review_v2_1 §2.1 and §2.2 as the source for the 4 memory dimensions and stable-to-volatile cache ordering" + ], + "v2_2_user_corrections_applied": [ + "Data-format preferences: tables (§4.4 7-column format from survey), SSDL shape tags, no JSON, forth/array notation (for x .. n, name := value, if cond { ... }, tape { ... }, try { ... } recover err { ... }, sandbox { ... })", + "JSON block in v2.1 §2.1 (harvest output schema) replaced with a §4.4-style table", + "Comparison table (§5) reformatted with SSDL shape tags", + "Future-track candidate list (§6) reformatted as a single 16-row table with metadata columns (Symbol, Name, Domain, Priority, Effort, Shape, Depends on, Cross-refs)", + "Proposed new artifacts (§8) reformatted in table form", + "New §11: 'In dialogue with the intent DSL survey' — the 9 mutual cross-references" + ], + "intent_dsl_survey_dependencies": [ + "report_v1.2.md §1 (4 anchor claims) — applied to the nagent review", + "report_v1.2.md §3.5 (try/recover envelope) — applied to the compaction pattern", + "report_v1.2.md §4.4 (Tier 4 table format) — adopted as the new style for the nagent review", + "report_v1.2.md §6 Claim 4 (4 memory dimensions) — formally codifies nagent v2.1 §2.1", + "report_v1.2.md §6 Claim 5 (stable-to-volatile cache ordering) — formally codifies nagent v2.1 §2.2", + "report_v1.2.md §6 Claim 9 (sandbox as IEventTarget) — referenced", + "report_v1.2.md §6 Claim 10 (reads are free) — referenced" + ], + "v2_2_focused_delta": "v2.2 is a FOCUSED DELTA, not a full rewrite. Tables adopt the survey's §4.4 7-column layout. JSON blocks become tables. The 16 future-track candidates are a single table with all metadata columns. The 9 cross-references to the survey are consolidated in a new §11.", + "next_turn_format_commitment": "All new styleguides and project docs proposed in v2.1/v2.2 §8 will follow the §4.4 7-column table format. No JSON code blocks. SSDL shape tags where applicable. Survey grammar primitives (name := value, for x .. n, if cond { ... }, tape { ... }, try { ... } recover err { ... }, sandbox { ... }, audit msg, fuzzy { ... }) used in code examples.", + "preserved_files_NOT_modified": [ + "nagent_review_v2_20260612.md (v2 draft, preserved per user instruction)", + "nagent_review_v2_1_20260612.md (v2.1 user-revised, preserved per user instruction)", + "report.md, comparison_table.md, decisions.md, nagent_takeaways_20260608.md (v1 review artifacts, preserved)", + "Readme.md (project root, human-facing, preserved)", + "docs/Readme.md (docs index, human-facing, preserved)", + "spec.md (preserved)" + ] } } diff --git a/conductor/tracks/nagent_review_20260608/nagent_review_v2_2_20260612.md b/conductor/tracks/nagent_review_20260608/nagent_review_v2_2_20260612.md new file mode 100644 index 00000000..8ec68001 --- /dev/null +++ b/conductor/tracks/nagent_review_20260608/nagent_review_v2_2_20260612.md @@ -0,0 +1,452 @@ +# 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) | `===>W===>` (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) | `===>W===>` | 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 `` 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()] + │ + ▼ +[Q:offset of \nInstance:?] + │ + ├──► [I:boundaries.append(offset)] + │ + ▼ +[Q:end of < 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) | `===>W===>` (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 | `===>W===>` | 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 | `===>W===>` | 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) | `` 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 | `===>W===>` | +| **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)** | `===>W===>` | +| **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. diff --git a/conductor/tracks/nagent_review_20260608/state.toml b/conductor/tracks/nagent_review_20260608/state.toml index b8cdef28..d49b7f49 100644 --- a/conductor/tracks/nagent_review_20260608/state.toml +++ b/conductor/tracks/nagent_review_20260608/state.toml @@ -77,6 +77,30 @@ t_v2_1_review_pending_06 = { status = "pending", commit_sha = "", description = t_v2_1_review_pending_07 = { status = "pending", commit_sha = "", description = "Update existing workflow docs (conductor/workflow.md, conductor/product-guidelines.md, docs/guide_mma.md, docs/guide_ai_client.md) with v2.1 patterns" } t_v2_1_review_pending_08 = { status = "pending", commit_sha = "", description = "Verify Candidate 15 (save-with-graceful-summary-failure) by reading src/ai_client.py:run_discussion_compression" } +# v2.2 review (2026-06-12, third iteration): user finished intent_dsl_survey_20260612 report_v1.2; +# v2.1 was the seed for survey §6 Claims 4 and 5; v2.2 applies the new style preferences (tables, +# SSDL tags, no JSON) and explicitly cross-references the survey +# v2 and v2.1 are PRESERVED; v2.2 is non-destructive new file +t_v2_2_review_01 = { status = "completed", commit_sha = "", description = "v2.2: read intent_dsl_survey_20260612/report_v1.2.md §1, §3, §4, §5, §6, §7 (~600 lines; 10 prior-art clusters, 4 anchor claims, ~42-verb vocab, 10 AI-Agent Properties)" } +t_v2_2_review_02 = { status = "completed", commit_sha = "", description = "v2.2: applied the user's data-format preferences (table-based, forth/array-like, no JSON) — JSON blocks in v2.1 §2.1 replaced with §4.4 7-column tables (Symbol, Name, Signature, Semantics, Example, Borrowed from, Shape)" } +t_v2_2_review_03 = { status = "completed", commit_sha = "", description = "v2.2: adopted SSDL shape tags ([I], ===>, o==>, [B], [M], [N], [Q], [S], ───) for the comparison table and future-track candidate list" } +t_v2_2_review_04 = { status = "completed", commit_sha = "", description = "v2.2: cross-referenced the intent DSL survey's 10 AI-Agent Properties (§6 Claims 1-10) — Claims 4 and 5 explicitly cite v2.1 §2.1 and §2.2 as their source" } +t_v2_2_review_05 = { status = "completed", commit_sha = "", description = "v2.2: applied the survey's grammar primitives (name := value, for x .. n, if cond { ... }, tape { ... }, try { ... } recover err { ... }, sandbox { ... }, audit msg, fuzzy { ... }) where applicable" } +t_v2_2_review_06 = { status = "completed", commit_sha = "", description = "v2.2: added new §11 'In dialogue with intent DSL survey' — the 9 mutual cross-references and the 3 the user should know about" } +t_v2_2_review_07 = { status = "completed", commit_sha = "", description = "v2.2: reformatted §3 future-track candidates as a single 16-row table with all metadata columns (Symbol, Name, Domain, Priority, Effort, Shape, Depends on, Cross-refs)" } +t_v2_2_review_08 = { status = "completed", commit_sha = "", description = "v2.2: added Candidate 12b (cache TTL GUI controls) and Candidate 16 (AGENTS.md @import + canonical DOD file) to the table; re-ranked priorities" } +t_v2_2_review_09 = { status = "completed", commit_sha = "", description = "v2.2: wrote nagent_review_v2_2_20260612.md (new file, ~35KB) — focused delta, not a full rewrite; v2 and v2.1 are preserved" } +t_v2_2_review_10 = { status = "completed", commit_sha = "", description = "v2.2: format commitment for the upcoming next-turn artifacts — all new styleguides and project docs will follow the §4.4 table format" } + +# v2.2 pending (for the next turn) +t_v2_2_review_pending_01 = { status = "pending", commit_sha = "", description = "User review of v2.2 + confirmation of which new artifacts to create in the next turn" } +t_v2_2_review_pending_02 = { status = "pending", commit_sha = "", description = "Create canonical DOD file at conductor/code_styleguides/data_oriented_design.md (in §4.4 table format)" } +t_v2_2_review_pending_03 = { status = "pending", commit_sha = "", description = "Update AGENTS.md to add @conductor/code_styleguides/data_oriented_design.md import (in §4.4 table format)" } +t_v2_2_review_pending_04 = { status = "pending", commit_sha = "", description = "Create ./docs/AGENTS.md as agent-facing mirror of docs/Readme.md (in §4.4 table format)" } +t_v2_2_review_pending_05 = { status = "pending", commit_sha = "", description = "Write 5 new styleguides in §4.4 table format (agent_memory_dimensions.md, rag_integration_discipline.md, cache_friendly_context.md, knowledge_artifacts.md, feature_flags.md)" } +t_v2_2_review_pending_06 = { status = "pending", commit_sha = "", description = "Write 3 new project docs in §4.4 table format (guide_knowledge_curation.md, guide_caching_strategy.md, guide_agent_memory_dimensions.md)" } +t_v2_2_review_pending_07 = { status = "pending", commit_sha = "", description = "Update existing workflow docs (conductor/workflow.md, conductor/product-guidelines.md, docs/guide_mma.md, docs/guide_ai_client.md) using survey grammar primitives and §4.4 table format" } + [user_wants_recorded] # User explicitly wants these in priority order (see decisions.md for full detail) want_1_sub_conversation_runner = "EXPLICIT: 'I probably want to add that for just 1:1 discussions where I use a sub-agent manually for specific points'"