diff --git a/AGENTS.md b/AGENTS.md index 9e97b175..24652df3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,15 +30,16 @@ This is the canonical DOD reference. The same file is injected into the Applicat ## Code Styleguides (the convention catalog) -Per-domain rules live in `conductor/code_styleguides/`. Read the relevant one before starting work in a new area: +Per-domain rules live in `conductor/code_styleguides/`. The full list is in `./docs/AGENTS.md` §2 (the canonical 6-styleguide catalog with one-line summaries + when-to-read). This section is a pointer. -- `conductor/code_styleguides/data_oriented_design.md` — The canonical DOD reference (Tier 0/1/2; 3 defaults to reject; 7-question simplification pass) -- `conductor/code_styleguides/agent_memory_dimensions.md` — The 4 memory dimensions (curation / discussion / RAG / knowledge) and when to use each -- `conductor/code_styleguides/rag_integration_discipline.md` — The conservative-RAG rule: opt-in, complements never replaces, provenance required, no mutation -- `conductor/code_styleguides/cache_friendly_context.md` — Stable-to-volatile context ordering; the cache TTL GUI contract; the byte-comparison test -- `conductor/code_styleguides/knowledge_artifacts.md` — The knowledge harvest pattern: category files, provenance, sha256 ledger, digest regeneration -- `conductor/code_styleguides/feature_flags.md` — Codifies "delete to turn off" (file presence) + "config.toml flag" (config); when to use each +**The short version (the 6 styleguides):** +- `data_oriented_design.md` — The canonical DOD reference (Tier 0/1/2; 3 defaults to reject; 7-question simplification pass) +- `agent_memory_dimensions.md` — The 4 memory dimensions (curation / discussion / RAG / knowledge) and when to use each +- `rag_integration_discipline.md` — The conservative-RAG rule: opt-in, complement, provenance, no mutation +- `cache_friendly_context.md` — Stable-to-volatile context ordering; the cache TTL GUI contract; the byte-comparison test +- `knowledge_artifacts.md` — The knowledge harvest pattern: category files, provenance, sha256 ledger, digest regeneration +- `feature_flags.md` — Codifies "delete to turn off" (file presence) + config flags; when to use each ## Human-Facing Documentation For understanding, using, and maintaining the tool, see `docs/Readme.md` (the canonical teaching document) and `./docs/AGENTS.md` (the agent-facing mirror of `docs/Readme.md`). diff --git a/conductor/code_styleguides/data_oriented_design.md b/conductor/code_styleguides/data_oriented_design.md index ca042ea7..acb93d03 100644 --- a/conductor/code_styleguides/data_oriented_design.md +++ b/conductor/code_styleguides/data_oriented_design.md @@ -180,19 +180,18 @@ Design with the actual hardware's properties — cache hierarchy, memory bandwid ## 9. The 4 memory dimensions (the Manual Slop context) -The conversation data has 4 distinct memory dimensions. Each lives at a different layer; each serves a different purpose. The wrong shape for the wrong layer is a common mistake. +The conversation data has 4 distinct memory dimensions (curation / discussion / RAG / knowledge). Each lives at a different layer; each serves a different purpose. -| # | Dim | Where it lives | What it stores | How it's edited | How it's queried | SSDL | -|---|---|---|---|---|---|---| -| 1 | **Curation** | `FileItem` + `ContextPreset` + Fuzzy Anchors | *How to render a file* in the AI's context window | Structural File Editor; project TOML | Implicit in `aggregate.py:run` at discussion start | `[Q]` | -| 2 | **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==>` | -| 3 | **RAG** | `src/rag_engine.py` (ChromaDB) | *Semantic fingerprints* of indexed files | (opaque vector store) | `RAGEngine.search()` at LLM call time | `[Q]` | -| 4 | **Knowledge** | `~/.manual_slop/knowledge/*.md` + per-file + digest + ledger | *Durable learnings* from past sessions | Plain markdown edit | Bounded digest as stable prefix | `o==>` | +**The canonical reference is `conductor/code_styleguides/agent_memory_dimensions.md` §0** (the full 4-dim table + per-dim deep-dives + boundaries + decision tree). This section is a pointer. -**The shape rule:** curation is per-file structural; discussion is per-turn conversational; RAG is opt-in semantic; knowledge is per-project durable. A feature that wants one should use the matching dimension; mixing them is a maintenance liability. +**The one-line summary:** -See `conductor/code_styleguides/agent_memory_dimensions.md` for the full styleguide. +- **Curation** is per-file structural (the `FileItem` schema) +- **Discussion** is per-turn conversational (the `disc_entries` list) +- **RAG** is opt-in semantic (the ChromaDB vector store) +- **Knowledge** is per-project durable (the markdown files at `~/.manual_slop/knowledge/`) +**The shape rule.** A feature that wants one should use the matching dimension; mixing them is a maintenance liability. --- ## 10. Enforceable deliverables (tier 2) diff --git a/conductor/product-guidelines.md b/conductor/product-guidelines.md index 37cf38d9..8a2d13dc 100644 --- a/conductor/product-guidelines.md +++ b/conductor/product-guidelines.md @@ -113,16 +113,13 @@ The product guidelines are best understood alongside the per-source-file guides - **[code_styleguides/config_state_owner.md](code_styleguides/config_state_owner.md):** Config I/O state ownership — `AppController` is the single source of truth; direct calls to `models.save_config`/`models.load_config` in `src/` are forbidden (enforced by `scripts/audit_no_models_config_io.py`). ## Memory Dimensions (added 2026-06-12) -The conversation data has 4 distinct memory dimensions. Features touch 1-2 typically; some touch 3. The dimensions are not interchangeable. +The conversation data has 4 distinct memory dimensions (curation / discussion / RAG / knowledge). Features touch 1-2 typically; some touch 3. The dimensions are not interchangeable. -| Dim | Where | What it stores | User-editable | Status | -|---|---|---|---|---| -| Curation | `FileItem` + `ContextPreset` | *How to render a file* | Structural File Editor | Existing, strong | -| Discussion | `disc_entries` + branching + UISnapshot | *What was said* | GUI `[Edit]` mode; undo/redo | Existing, strong | -| RAG | `src/rag_engine.py` (ChromaDB) | *Semantic fingerprints* | (opaque) | Opt-in | -| Knowledge | `~/.manual_slop/knowledge/*.md` + per-file + digest | *Durable learnings* | Plain markdown | Proposed (Candidate 8) | +**The full canonical 4-dim table is in `conductor/code_styleguides/agent_memory_dimensions.md` §0** (with the SSDL shape tag per dim + per-dim deep-dives + the decision tree). This section is the product-level summary. -**The product decision.** When scoping a new feature, identify which dimension(s) the feature touches. Pick the matching dimension; don't reach for the wrong shape. The full cross-cutting guide is `docs/guide_agent_memory_dimensions.md`. The canonical styleguide is `conductor/code_styleguides/agent_memory_dimensions.md`. +**The one-line summary:** curation is per-file structural; discussion is per-turn conversational; RAG is opt-in semantic; knowledge is per-project durable. Pick the matching dimension; don't reach for the wrong shape. + +**The cross-cutting guide is `docs/guide_agent_memory_dimensions.md`.** The canonical styleguide is `conductor/code_styleguides/agent_memory_dimensions.md`. **The 6 design rules (the product implications).** @@ -132,7 +129,6 @@ The conversation data has 4 distinct memory dimensions. Features touch 1-2 typic 4. **Knowledge is durable, user-editable, provenance-aware.** The category files are the source of truth; the digest is a projection. "Delete to turn off": `rm digest.md`. 5. **Cache hits only on the stable prefix** (layers 1-7 of the 12-layer model). The volatile suffix (layers 8-12) is never cached. 6. **Feature flags are data, not config.** File presence ("delete to turn off") for side artifacts; config flags for persistent preferences; CLI flags for one-shot overrides. - ## See Also — Updated (2026-06-12) The canonical styleguide catalog (per the nagent_review v2.3 + intent_dsl_survey cross-references): diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 8924cb1b..5f8842f9 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -12,16 +12,11 @@ ## 0. The 4 memory dimensions (the cross-cutting lens) -The conversation data has 4 distinct memory dimensions. Most features touch 1-2; some touch 3. Use this lens to identify which dimension(s) your feature needs. +The conversation data has 4 distinct memory dimensions (curation / discussion / RAG / knowledge). Most features touch 1-2; some touch 3. Use this lens to identify which dimension(s) your feature needs. -| # | Dim | Where it lives | Use when | Styleguide | -|---|---|---|---|---| -| 1 | **Curation** | `FileItem` + `ContextPreset` + Fuzzy Anchors | "How to render a file" | (the curation is per `docs/guide_context_curation.md`) | -| 2 | **Discussion** | `app.disc_entries` + branching + UISnapshot | "What was said in this chat" | (the discussion is per `docs/guide_architecture.md` §"Threading model") | -| 3 | **RAG** | `src/rag_engine.py` (ChromaDB) | "What similar content exists" (opt-in) | `conductor/code_styleguides/rag_integration_discipline.md` | -| 4 | **Knowledge** | `~/.manual_slop/knowledge/*.md` + per-file + digest | "What we learned from past sessions" | `conductor/code_styleguides/knowledge_artifacts.md` | +**The full canonical 4-dim table is in `conductor/code_styleguides/agent_memory_dimensions.md` §0** (with the SSDL shape tag per dim). The cross-cutting guide is `docs/guide_agent_memory_dimensions.md`. -See `docs/guide_agent_memory_dimensions.md` for the full cross-cutting guide. +**The one-line summary:** curation is per-file structural; discussion is per-turn conversational; RAG is opt-in semantic; knowledge is per-project durable. Pick the matching dimension; don't reach for the wrong shape. --- @@ -151,21 +146,9 @@ See `docs/guide_agent_memory_dimensions.md` for the full cross-cutting guide. If the feature builds the initial context (in `aggregate.py:run`) or calls the LLM (in `ai_client.py:send`), the cache strategy matters. -**The 12-layer model:** +**The 12-layer model:** the full table is in `conductor/code_styleguides/cache_friendly_context.md` §1. The short version: layers 1-7 (role, schema, tools, system prompt, persona, project context, knowledge digest) are byte-identical across turns and cacheable; layers 8-12 (discussion metadata, active preset, per-file details, prior tool results, user message) are per-turn and NOT cached. Cache boundary is at layer 7/8. -| # | Layer | Stable across turns? | Where the cache hits | -|---|---|---|---| -| 1-7 | Role instructions, function-calling schema, tool descriptions, system prompt, persona, project context, knowledge digest | **YES** (cacheable) | Anthropic `cache_control`, Gemini `cachedContent`, OpenAI implicit | -| 8-12 | Discussion metadata, active preset, per-file details, prior tool results, user message | **NO** (per turn) | NOT cached | - -**The byte-comparison test** (the design contract for the stable prefix): - -```python -def test_aggregate_stable_to_volatile_ordering(): - """The first N characters of the context should be identical across turns - of the same conversation, when no stable-layer inputs change.""" - ... -``` +**The byte-comparison test** (the design contract for the stable prefix): the test in `tests/test_aggregate_caching.py` ensures the first N characters of the context are identical across turns. The implementation is `aggregate.stable_prefix_length(ctrl) -> N`. See `conductor/code_styleguides/cache_friendly_context.md` §2. **The provider-specific TTLs:** @@ -175,62 +158,36 @@ def test_aggregate_stable_to_volatile_ordering(): | Gemini explicit | 1 h | yes (per-discussion override) | | OpenAI implicit | 5-10 min (provider-managed) | no | -**The GUI exposure** is a "Caching" Operations Hub sub-panel (per the v2.3 §5.3 sketch). See `docs/guide_caching_strategy.md` for the full guide and `conductor/code_styleguides/cache_friendly_context.md` for the styleguide. +**The GUI exposure** is a "Caching" Operations Hub sub-panel. See `docs/guide_caching_strategy.md` for the full guide and `conductor/code_styleguides/cache_friendly_context.md` for the styleguide. --- ## 6. The knowledge harvest (the durable layer) -The 4th memory dimension (knowledge) is *opt-in but encouraged* — it's the durable, user-editable, provenance-aware store of facts / decisions / questions / playbooks / per-file notes. +The 4th memory dimension (knowledge) is *opt-in but encouraged* — it's the durable, user-editable, provenance-aware store. -**The directory layout** (per the user's `~/.manual_slop/knowledge/`): +**The canonical reference is `conductor/code_styleguides/knowledge_artifacts.md` §0-§4** (the directory layout + the 5 category files + the digest + the ledger + the harvest workflow). The user-facing guide is `docs/guide_knowledge_curation.md`. -``` -knowledge/ -├── facts.md # - {statement} {provenance} -├── decisions.md # - {statement, reason} {provenance} -├── questions.md # - {question} {provenance} -├── playbooks.md # - **{name}**: {steps} {provenance} -├── tasks.md # ## Open / ## Done -├── files/{file_id}.md # per-file notes (keyed by inode) -├── digest.md # bounded 4KB; the projection; "delete to turn off" -├── ledger.json # sha256-of-content audit log -└── prompts/harvest-conversation.md # user-editable -``` - -**The harvest CLI:** `python -m src.knowledge_harvest [--apply] [--no-harvest] [--max-harvest-bytes N]`. Default: dry-run. - -**The LLM output is strict JSON** (no prose, no markdown fence) with 7 categories. The retry budget is 2 attempts. - -**The "delete to turn off" pattern:** `rm ~/.manual_slop/knowledge/digest.md` → no `{knowledge}` block injected. Re-enable by running the harvest. - -See `docs/guide_knowledge_curation.md` for the full guide and `conductor/code_styleguides/knowledge_artifacts.md` for the styleguide. +**The one-line summary:** the user can `rm ~/.manual_slop/knowledge/digest.md` to turn off the knowledge injection (file presence as the feature flag). Re-enable by running `python -m src.knowledge_harvest --apply`. The LLM output is strict JSON with 7 categories; the retry budget is 2 attempts. --- ## 7. The RAG discipline (the opt-in fuzzy dimension) -RAG is the *fuzzy semantic search* dimension. It's *opt-in* (default-off in new projects). The 6 rules: +RAG is the *fuzzy semantic search* dimension. It's *opt-in* (default-off in new projects). -1. **Opt-in.** Default-off in new projects -2. **Complements; never replaces.** RAG is one of 4 dimensions, not a substitute -3. **Provenance required.** Every result shows file + chunk -4. **No mutation.** RAG results never write to `disc_entries`, `FileItem`, or disk -5. **Feature-gated.** A feature must explicitly request RAG in its scope -6. **Graceful failure.** Failed search returns empty; the request continues - -See `docs/guide_rag.md` for the full RAG guide and `conductor/code_styleguides/rag_integration_discipline.md` for the styleguide. +**The canonical reference is `conductor/code_styleguides/rag_integration_discipline.md`** (the 6 rules: opt-in, complement, provenance, no mutation, feature-gated, graceful failure). The user-facing guide is `docs/guide_rag.md`. --- ## 8. The feature flag patterns (when to use what) -When adding a new feature with an "on/off" toggle, choose the right pattern: +When adding a new feature with an "on/off" toggle, choose the right pattern. -| Pattern | When to use | Example | -|---|---|---| -| **File presence** ("delete to turn off") | The feature produces a side artifact; the user might want to clean up by `rm`-ing it | `~/.manual_slop/knowledge/digest.md` | -| **Config flag** | The feature is always on; the flag is a persistent preference | `[ai_settings.toml] rag.enabled` | +**The canonical reference is `conductor/code_styleguides/feature_flags.md`** (file presence vs config flag vs CLI flag vs track metadata flag; the decision tree; the forbidden patterns). The short version: + +- **File presence** ("delete to turn off") — the feature produces a side artifact; the user might want to clean up by `rm`-ing it (e.g., `~/.manual_slop/knowledge/digest.md`) +- **Config flag** — the feature is always on; the flag is a persistent preference (e.g., `[ai_settings.toml] rag.enabled`) | **CLI flag** | The feature is invoked from the CLI; the flag is a one-shot override | `python -m src.knowledge_harvest --apply` | | **Track metadata flag** | The track's implementation uses a feature; this is *static documentation* | `metadata.json`: `{"uses_rag": true}` | diff --git a/docs/guide_agent_memory_dimensions.md b/docs/guide_agent_memory_dimensions.md index 350ad87c..9a6b926a 100644 --- a/docs/guide_agent_memory_dimensions.md +++ b/docs/guide_agent_memory_dimensions.md @@ -10,14 +10,9 @@ ## 0. The 30-second version -Manual Slop has 4 memory dimensions for the conversation data: +Manual Slop has 4 memory dimensions for the conversation data. **The full canonical table is in `conductor/code_styleguides/agent_memory_dimensions.md` §0** (curation / discussion / RAG / knowledge, with the SSDL shape tag per dim). -| # | Dim | Where it lives | What it stores | Status | -|---|---|---|---|---| -| 1 | **Curation** | `FileItem` + `ContextPreset` + Fuzzy Anchors | *How to render a file* in the AI's context window | Existing, strong | -| 2 | **Discussion** | `app.disc_entries` + branching + UISnapshot | *What was said* in the conversation | Existing, strong | -| 3 | **RAG** | `src/rag_engine.py` (ChromaDB) | *Semantic fingerprints* of indexed files | Opt-in | -| 4 | **Knowledge** | `~/.manual_slop/knowledge/*.md` + per-file + digest | *Durable learnings* from past sessions | Proposed (Candidate 8) | +**The one-line summary:** curation is per-file structural; discussion is per-turn conversational; RAG is opt-in semantic; knowledge is per-project durable. Pick the matching dimension; don't reach for the wrong shape. **The decision tree:** diff --git a/docs/guide_ai_client.md b/docs/guide_ai_client.md index 17097ce4..6ba5fbde 100644 --- a/docs/guide_ai_client.md +++ b/docs/guide_ai_client.md @@ -709,21 +709,9 @@ The nagent review (v2.3, §3.2 + §5) formalizes the cache strategy that this cl ### The 12-layer model (the recap) -| # | Layer | Stable? | Where | -|---|---|---|---| -| 1 | Role instructions | yes | `_get_combined_system_prompt` | -| 2 | Function-calling schema | yes | per provider | -| 3 | Discovered tool descriptions | yes | `mcp_client.get_tool_schemas()` | -| 4 | System prompt preset | yes | `app_state.ai_settings.system_prompt` | -| 5 | Persona profile | yes | `app_state.active_persona` | -| 6 | Project context (per `manual_slop.toml`) | yes | NEW (Candidate 14) | -| 7 | Knowledge digest (per `knowledge/digest.md`) | yes (within gc cycle) | NEW (Candidate 8) | -| 8 | Discussion metadata | no | `disc_entries[:1]` or `disc_meta` | -| 9 | Active preset (FileItem set) | no | `self.context_files` | -| 10 | Per-file details | no | per `FileItem` | -| 11 | Prior tool results | no | per `_reread_file_items` | -| 12 | User message | no | the input | +**The canonical reference is `conductor/code_styleguides/cache_friendly_context.md` §1** (the full 12-layer table with the stable/volatile classification + the `───` data markings + the byte-comparison test). This section is a pointer. +**The one-line summary:** layers 1-7 (role instructions, function-calling schema, tool descriptions, system prompt, persona, project context, knowledge digest) are byte-identical across turns and cacheable. Layers 8-12 are per-turn and NOT cached. The cache boundary is at layer 7/8. ### The byte-comparison test (the design contract) The test in `tests/test_aggregate_caching.py` ensures the first N characters of the context are byte-identical across turns: diff --git a/docs/guide_caching_strategy.md b/docs/guide_caching_strategy.md index 6e672175..6e6d282d 100644 --- a/docs/guide_caching_strategy.md +++ b/docs/guide_caching_strategy.md @@ -37,22 +37,9 @@ ## 1. The 12-layer model (the stable-to-volatile ordering) -| # | Layer | Stable across turns? | Source | SSDL | -|---|---|---|---|---| -| 1 | Role instructions (model + provider) | yes | `_get_combined_system_prompt` | `[I]` | -| 2 | Function-calling schema | yes | per provider | `[I]` | -| 3 | Discovered tool descriptions | yes | `mcp_client.get_tool_schemas()` | `[I]` | -| 4 | System prompt preset | yes | `app_state.ai_settings.system_prompt` | `[I]` | -| 5 | Persona profile | yes | `app_state.active_persona` | `[I]` | -| 6 | Project context (per `manual_slop.toml`) | yes | NEW | `[I]` | -| 7 | Knowledge digest (per `knowledge/digest.md`) | yes (within a gc cycle) | NEW | `[I]` | -| 8 | Discussion metadata (name, role count) | no (per turn) | `disc_entries[:1]` or `disc_meta` | `───` | -| 9 | Active preset (FileItem set) | no (per turn) | `self.context_files` | `───` | -| 10 | Per-file details (history, slices, notes) | no (per file) | per `FileItem` | `───` | -| 11 | Tool-call results from prior turns | no (per turn) | per `_reread_file_items` | `───` | -| 12 | The user message | no (per turn) | the input | `───` | +**The canonical reference is `conductor/code_styleguides/cache_friendly_context.md` §1** (the full 12-layer table with the stable/volatile classification + the byte-comparison test contract + the per-layer `───` data markings). This section is a pointer. -**The cache boundary is at layer 7/8.** Layers 1-7 are byte-identical across turns of the same discussion (and across discussions of the same mode). Layers 8-12 change per turn. +**The one-line summary:** layers 1-7 (role instructions, function-calling schema, tool descriptions, system prompt, persona, project context, knowledge digest) are byte-identical across turns and cacheable. Layers 8-12 (discussion metadata, active preset, per-file details, prior tool results, user message) are per-turn and NOT cached. The cache boundary is at layer 7/8. --- diff --git a/docs/guide_knowledge_curation.md b/docs/guide_knowledge_curation.md index 13a59d38..5448df28 100644 --- a/docs/guide_knowledge_curation.md +++ b/docs/guide_knowledge_curation.md @@ -29,74 +29,21 @@ prompts/ # user-editable harvest prompt ## 1. The 5 category files (the source of truth) -### 1.1 `facts.md` (durable statements) +**The canonical reference is `conductor/code_styleguides/knowledge_artifacts.md` §1** (the full per-category formats + the `───` data shape markers + the append-only rule + the user-editable contract). This section is the user-facing summary. -```markdown -# Facts - -- The MCP dispatch uses a flat if/elif chain. 4 places, 45 tools. [from: 2026-05-12-investigate-dispatch, 2026-05-12] -- ai_client.py has 5 separate per-provider history lists, each with their own lock. Switching providers mid-session loses history. [from: 2026-05-13-state-mutation-matrix, 2026-05-13] -- RAG is opt-in. Default-off in new projects. [from: 2026-06-12-rag-discipline, 2026-06-12] -``` - -**The shape:** `- {statement} {provenance}`. Plain markdown. Append-only. User-editable. +| File | Shape | What it stores | +|---|---|---| +| `facts.md` | `- {statement} {provenance}` | Durable statements about systems, repos, tools | +| `decisions.md` | `- {statement, reason} {provenance}` | Decisions that were made | +| `questions.md` | `- {question} {provenance}` | Unanswered questions | +| `playbooks.md` | `- **{name}**: {steps} {provenance}` | Reusable command sequences | +| `tasks.md` | `- {task}` (## Open / ## Done) | Open and done tasks | **The provenance string:** `[from: {conversation_name}, {date}]`. The `date` is the ISO-8601 date prefix of the harvest timestamp. -**The user can edit any fact.** The LLM's output is a *suggestion*; the user is the editor. If a fact is wrong, the user deletes it. If a fact needs more detail, the user adds it. The harvest will *append*; it will not *overwrite*. +**The user can edit any of the 5.** The LLM's output is a *suggestion*; the user is the editor. The harvest will *append*; it will not *overwrite*. -### 1.2 `decisions.md` (decisions with reasons) - -```markdown -# Decisions - -- Knowledge harvest is a complement to curation + discussion, not a RAG replacement. [from: 2026-06-12-candidate-11, 2026-06-12] -- Cache TTL defaults to 5 min (Anthropic) + 60 min (Gemini); configurable per-discussion. [from: 2026-06-12-cache-strategy, 2026-06-12] -- Per-file knowledge notes are keyed by st_dev:st_ino, not by path. [from: 2026-06-12-candidate-11, 2026-06-12] -``` - -**The shape:** `- {statement} {provenance}`. The "why" lives in the LLM's harvest output's `detail` field. The user's edits override. - -### 1.3 `questions.md` (unanswered questions) - -```markdown -# Questions - -- Where does intent resolution live — per-verb, per-block, or global? [from: 2026-06-12-follow-up-b, 2026-06-12] -- How should the knowledge digest TTL be exposed in the GUI? [from: 2026-06-12-cache-ttl, 2026-06-12] -``` - -**The shape:** `- {question} {provenance}`. Open questions are *valuable* — they're the TODO list the next session can act on. - -### 1.4 `playbooks.md` (reusable sequences) - -```markdown -# Playbooks - -- **Knowledge Harvest**: scan -> classify -> LLM-distill -> append -> digest -> reclaim. [from: 2026-06-12-candidate-11, 2026-06-12] -- **Stable-to-Volatile Cache Ordering**: identify Instance: boundary -> pass to --cache-prefix-chars. [from: 2026-06-12-candidate-12, 2026-06-12] -- **Candidate Verification (TBD)**: read src/ai_client.py:run_discussion_compression -> check failure mode. [from: 2026-06-12-candidate-15, 2026-06-12] -``` - -**The shape:** `- **{name}**: {steps} {provenance}`. Playbooks are the "I did this once; here it is" record. Future workers use them directly. - -### 1.5 `tasks.md` (open and done) - -```markdown -# Tasks - -## Open -- Create canonical DOD file at conductor/code_styleguides/data_oriented_design.md. [from: 2026-06-12-candidate-16, 2026-06-12] -- Verify Candidate 15 by reading src/ai_client.py:run_discussion_compression. [from: 2026-06-12-candidate-15, 2026-06-12] - -## Done -- Read nagent source in full (18 files). [from: 2026-05-15, 2026-05-15] -- Wrote v2.3 review (272KB / 3965 lines). [from: 2026-06-12-v2.3, 2026-06-12] -``` - -**The shape:** `- {task} {provenance}`. The two sections are manually maintained; the harvest places open items in `## Open` and done items in `## Done`. - ---- +**The example listings** (per-file path / file `facts.md`, etc.) are in `conductor/code_styleguides/knowledge_artifacts.md` §1.1-§1.5. This section is a pointer. ## 2. The per-file notes (`files/{file_id}.md`) diff --git a/docs/guide_mma.md b/docs/guide_mma.md index 4d3530fa..48fe542b 100644 --- a/docs/guide_mma.md +++ b/docs/guide_mma.md @@ -643,15 +643,12 @@ class SubConversationRunner: The MMA tracks operate on `disc_entries` (the Discussion dim) and `manual_slop.toml` (the project config). They do NOT typically touch the Curation dim (per-track ticket specs) or the Knowledge dim (per-track session reports). They MAY touch the RAG dim if the ticket scope includes RAG integration (declared in `metadata.json`). -**The MMA scope, in the 4-dim framework:** - -| Dim | MMA scope? | Why | -|---|---|---| -| Curation | per-ticket only | A ticket might add a `FileItem` if the feature touches curation; not a default | -| Discussion | YES (the work) | The MMA worker's prompt is built from the active discussion | -| RAG | per-ticket only | A ticket might use RAG if the feature includes RAG; declared in `metadata.json` | -| Knowledge | per-track only | The track's session synthesis (in `docs/reports/`) is the durable knowledge | +**The MMA scope, in the 4-dim framework:** the canonical 4-dim table is in `conductor/code_styleguides/agent_memory_dimensions.md` §0. The short version: +- **Curation** — per-ticket only (a ticket might add a `FileItem` if the feature touches curation; not a default) +- **Discussion** — YES (the MMA worker's prompt is built from the active discussion) +- **RAG** — per-ticket only (declared in `metadata.json`) +- **Knowledge** — per-track only (the track's session synthesis in `docs/reports/` is the durable knowledge) **The implication for MMA workers.** MMA workers are given Context Amnesia (`ai_client.reset_session()` at the start of `run_worker_lifecycle`). The worker sees: - The ticket's prompt (the scoped work) - The `manual_slop.toml [agent.context_files]` (the project context)