docs: reduce redundant content across files; map references to canonical sources
Per user 'a bunch of docs just committed had redundant content across files. Can we do a reduction of that and instead map references to other files?' This commit reduces content duplication across 9 files. The canonical sources are kept as detailed references; the other files now point to them. Reductions (table replaced with 'see canonical' reference): 1. data_oriented_design.md §9: the 4-dim memory table (canonical: conductor/code_styleguides/agent_memory_dimensions.md §0) 2. guide_agent_memory_dimensions.md §0: the 4-dim memory table (canonical: conductor/code_styleguides/agent_memory_dimensions.md §0) 3. guide_caching_strategy.md §1: the 12-layer model (canonical: conductor/code_styleguides/cache_friendly_context.md §1) 4. guide_ai_client.md 'Cache strategy' section: the 12-layer model recap (canonical: conductor/code_styleguides/cache_friendly_context.md §1) 5. guide_knowledge_curation.md §1: the 5 category file details (canonical: conductor/code_styleguides/knowledge_artifacts.md §1) 6. product-guidelines.md 'Memory Dimensions' section: the 4-dim table (canonical: conductor/code_styleguides/agent_memory_dimensions.md §0) 7. guide_mma.md '4 memory dimensions' section: the MMA scope table (canonical: conductor/code_styleguides/agent_memory_dimensions.md §0) 8. docs/AGENTS.md §0 + §5-§8: 4-dim table + caching/knowledge/RAG/ feature flag tables (canonical: the per-topic styleguides in conductor/code_styleguides/) 9. AGENTS.md 'Code Styleguides' section: the 6-styleguide list (canonical: docs/AGENTS.md §2) The principle: each piece of content has ONE source of truth; other places point to it. The data-oriented way. Files retain their narrative flow and the 'what this is' intros, but the detailed tables are now in their canonical home. Net effect: -2100 bytes across 9 files (without losing any information - the canonical sources are unchanged). The 'cross-references' sections are kept; the duplicated content is removed.
This commit is contained in:
@@ -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`).
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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):
|
||||
|
||||
+16
-59
@@ -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}` |
|
||||
|
||||
|
||||
@@ -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:**
|
||||
|
||||
|
||||
+2
-14
@@ -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:
|
||||
|
||||
@@ -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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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`)
|
||||
|
||||
|
||||
+5
-8
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user