manual_slop/docs/AGENTS.md

./docs/AGENTS.md (the agent-facing mirror)

Status: Agent-facing mirror of docs/Readme.md (the human-facing docs index, which is preserved as-is). For agents (any tier), this is the recommended first read for understanding the project's docs structure. Date: 2026-06-12 (updated 2026-06-16 with §"Convention Enforcement") Cross-refs: docs/Readme.md (human-facing); AGENTS.md (project root); the 6 styleguides in conductor/code_styleguides/.

What this is. docs/Readme.md is the human-facing docs index. This file is the agent-facing equivalent: it organizes the 14 deep-dive guides under docs/ by MMA tier, and it cross-references the canonical styleguides. The 2 files cover the same docs but with different audiences and different reading paths.

The reading path. If you're an agent scoping a feature, read this file first; then read the 1-2 guide_*.md files for the layers your feature touches; then read the 1-2 styleguides for the patterns the feature uses. The expected reading time for a typical feature: 10-15 minutes.

---

Convention Enforcement (Added 2026-06-16; updated 2026-06-25 with §"Core Value")

READ THIS BEFORE WRITING ANY PYTHON IN THIS REPO.

Core Value (Added 2026-06-25)

C11/Odin/Jai semantics in a Python runtime. The project is written in Python because of practical constraints (time, dependencies, LLM codegen ability), but the convention is to make Python behave as close to a statically-typed value-typed language as the runtime allows.

LLMs default to opaque types (dict[str, Any], Any, Optional[T], hasattr() polymorphism) because that's what idiomatic Python training data looks like. That defaults to mediocrity. This rule overrides it.

The canonical mandate is in conductor/code_styleguides/data_oriented_design.md §8.5. The banned patterns are in conductor/code_styleguides/python.md §17. The boundary-layer concept is in conductor/code_styleguides/type_aliases.md.

Every section of this document, every styleguide in conductor/code_styleguides/, and every deep-dive guide in docs/guide_*.md MUST be read through the lens of this Core Value. If a section suggests dict[str, Any], Any, Optional[T], or hasattr() for entity dispatch in non-boundary code, that's an anti-pattern; flag it and ask.

The 4 enforcement mechanisms (defense-in-depth)

1. conductor/code_styleguides/data_oriented_design.md §8.5 (The Python Type Promotion Mandate) — the canonical mandate. Banned patterns: dict[str, Any], Any, Optional[T], hasattr() for entity dispatch, getattr() for type-dispatch, .get() on known fields.

2. conductor/code_styleguides/python.md §17 (LLM Default Anti-Patterns) — the explicit cheatsheet. Each banned pattern has a before/after example.

3. conductor/code_styleguides/error_handling.md — the Result[T] + NIL_T convention. Replaces Optional[T] returns.

4. The enforcement audit scripts — the project-level enforcement set:

   • scripts/audit_weak_types.py --strict — flags dict[str, Any], Any, anonymous tuples
   • scripts/audit_optional_returns.py --strict — flags Optional[T] return types in ALL src/*.py (post-2026-06-27 successor to audit_optional_in_3_files.py)
   • scripts/audit_exception_handling.py --strict — the data-oriented error handling convention
   • scripts/audit_main_thread_imports.py — always strict; the import graph gate
   • scripts/audit_no_models_config_io.py — the config-I/O ownership gate
   • The boundary-layer audit (planned in conductor/tracks/cruft_elimination_20260627/spec.md) — documents every Metadata usage

Pre-commit workflow (recommended):

# Run before claiming "done"
uv run python scripts/audit_weak_types.py
uv run python scripts/audit_optional_returns.py
uv run python scripts/audit_exception_handling.py
uv run python scripts/audit_main_thread_imports.py
uv run python scripts/audit_no_models_config_io.py

Why this is enforced: the convention prevents the LLM-training-data problem. Without these mechanisms, AI agents writing new code will revert to idiomatic patterns (dict[str, Any], Any, Optional[T], hasattr()) — exactly the "tech rot" the user is preventing. The 5+ mechanisms (Core Value + 3 styleguides + 5 audit scripts) are the defense-in-depth. See the project-level rules in AGENTS.md "Critical Anti-Patterns" (top of file) and conductor/product-guidelines.md "Core Value" for the canonical reference.

---

0. The 4 memory dimensions (the cross-cutting lens)

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.

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.

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.

---

1. The 14 deep-dive guides (organized by MMA tier)

Tier	Guide	What it covers	When to read
T1	docs/guide_architecture.md	Threading model; cross-thread state sync	When scoping any cross-cutting feature
T1	docs/guide_meta_boundary.md	The Application vs Meta-Tooling split	When scoping a Meta-Tooling-side feature
T2	docs/guide_app_controller.md	The headless controller; AppState dataclass	When implementing controller-side logic
T2	docs/guide_ai_client.md	The multi-provider LLM client	When implementing LLM-side logic
T2	docs/guide_mma.md	The 4-tier MMA orchestration	When implementing MMA-side logic
T2	docs/guide_tools.md	The MCP tool inventory + Hook API	When implementing MCP tools or Hook endpoints
T2	docs/guide_mcp_client.md	The 45 tools + 3-layer security	When implementing new MCP tools or sub-MCPs
T3	docs/guide_context_curation.md	Granular AST Control + Fuzzy Anchors + Structural File Editor	When implementing curation-side features
T3	docs/guide_personas.md	The unified agent profile model	When implementing persona-side features
T3	docs/guide_rag.md	The RAG subsystem	When implementing RAG-side features (rare; opt-in)
T3	docs/guide_gui_2.md	The ImGui application	When implementing GUI-side features
All	docs/guide_testing.md	The test suite architecture (251 test files; 7 conftest fixtures)	When writing any test
All	docs/guide_command_palette.md	The 33 commands + "Everything" mode	When implementing command-palette features
NEW	docs/guide_knowledge_curation.md	The knowledge memory guide (4th dim)	When implementing knowledge-side features
NEW	docs/guide_caching_strategy.md	Caching across providers; stable-to-volatile ordering; cache TTL GUI	When implementing cache-side features
NEW	docs/guide_agent_memory_dimensions.md	Cross-cutting: the 4 memory dimensions	When scoping any feature that touches memory

---

2. The 6 canonical styleguides (the convention catalog)

Styleguide	What it codifies	When to read
conductor/code_styleguides/data_oriented_design.md	The canonical DOD reference (Tier 0/1/2; 3 defaults to reject; 7-question simplification pass; 10-question self-check)	Before any non-trivial work
conductor/code_styleguides/agent_memory_dimensions.md	The 4 memory dimensions and when to use each	When the feature touches memory
conductor/code_styleguides/rag_integration_discipline.md	The conservative-RAG rule (opt-in; complements; provenance; no mutation; feature-gated; graceful failure)	When the feature uses RAG
conductor/code_styleguides/cache_friendly_context.md	Stable-to-volatile context ordering; the cache TTL GUI contract; the byte-comparison test	When the feature builds context or caches
conductor/code_styleguides/knowledge_artifacts.md	The knowledge harvest pattern (category files, provenance, sha256 ledger, digest regeneration)	When the feature uses the knowledge dim
conductor/code_styleguides/feature_flags.md	File presence ("delete to turn off") vs config flags vs CLI flags; when to use each	When adding a new feature toggle

---

3. The per-tier reading path

Tier 1 (Orchestrator) — what to read

For scoping a feature, understanding the architecture, and planning:

Read	Why
docs/guide_architecture.md	The threading model; the cross-thread data flow
docs/guide_meta_boundary.md	The Application vs Meta-Tooling split (load-bearing)
docs/guide_agent_memory_dimensions.md	The 4 memory dimensions (which dim does my feature touch?)
conductor/code_styleguides/data_oriented_design.md	The 3 defaults to reject; the simplification pass; the final self-check
AGENTS.md (project root)	The project-root agent-facing rules
This file (.docs/AGENTS.md)	The docs structure

Tier 1 does NOT typically read: guide_*.md for the specific subsystems (T2 reads those).

Tier 2 (Tech Lead) — what to read

For track design, ticket generation, and architecture:

Read	Why
All of Tier 1's reads	(foundational)
docs/guide_app_controller.md	The headless controller; the _predefined_callbacks and _gettable_fields registries
docs/guide_ai_client.md	The LLM client; the providers; the cache strategy
docs/guide_mma.md	The 4-tier MMA; the DAG engine; the worker pool
docs/guide_tools.md	The MCP tool inventory; the Hook API; the 3-layer security
conductor/code_styleguides/agent_memory_dimensions.md	(for memory-touching tracks)
conductor/code_styleguides/cache_friendly_context.md	(for context-building tracks)

Tier 2 does NOT typically read: guide_context_curation.md, guide_personas.md, guide_rag.md, guide_gui_2.md (T3 reads those).

Tier 3 (Worker) — what to read

For surgical implementation:

Read	Why
All of Tier 2's reads (selectively)	(the system context)
The 1-2 guide_*.md files for the specific layers the ticket touches	(the implementation surface)
The 1-2 code_styleguides/...md files for the patterns the ticket uses	(the convention)
The ticket itself (conductor/tracks/<id>/plan.md)	(the specific task)

Tier 3 reads in depth, not in breadth. A typical T3 worker reads 2-4 docs total.

Tier 4 (QA) — what to read

For error analysis and bug reproduction:

Read	Why
All of Tier 2's reads (selectively)	(the system context)
The 1-2 guide_*.md files for the failing layer	(the reproduction surface)
The test file (if any)	(the verification surface)
The audit scripts (scripts/audit_*.py)	(the static analysis surface)

Tier 4 reads narrowly. The bug is in 1-2 files; the read is in 1-2 docs.

---

4. The 4 memory dimensions (the cross-cutting lens, in detail)

Most features touch 1-2 dimensions. Use this decision tree:

Q: What is the *data* the feature needs?
   │
   ├── "How to render a file"          ──► Curation (FileItem)
   ├── "What was said in this chat"     ──► Discussion (disc_entries)
   ├── "What similar content exists"    ──► RAG (RAGEngine.search)  [opt-in]
   └── "What we learned from past runs" ──► Knowledge (knowledge/digest.md)

Pick the matching dimension. If the feature needs 2+, use 2+ — but be explicit about which is primary and which is secondary.

The wrong shape for the right question is a common mistake:

• "Where does X happen?" → RAG (semantic search)
• "How do I configure how file Y is rendered?" → Curation (FileItem)
• "What was the user asking about 3 turns ago?" → Discussion (disc_entries)
• "What did we decide last time about Z?" → Knowledge (digest)

See docs/guide_agent_memory_dimensions.md for the full cross-cutting guide.

---

5. The caching strategy (the cross-cutting concern)

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 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.

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:

Provider	Default TTL	Configurable?
Anthropic ephemeral	5 min	yes (per-provider control surface)
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. 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.

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.

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 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.

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} |

See conductor/code_styleguides/feature_flags.md for the full guide.

---

9. The cross-cutting principles (the data-oriented foundation)

All 14 docs and 6 styleguides share the same foundation (per data_oriented_design.md):

• The data is the thing. The conversation, the file items, the knowledge digest — these are the source of truth
• Behavior is transformation over data. Not object graphs; not hidden state; not opaque handles
• Avoid hidden mutable state. Errors are data, not exceptions. State is on disk, not in memory
• Separate durable artifacts from temporary execution. Workers are disposable; artifacts are durable
• Optimize the shape, availability, and maintenance of the data. Editable, provenance-aware, user-editable

When in doubt, read conductor/code_styleguides/data_oriented_design.md first.

---

10. The reading path (the 1-page summary)

For an agent scoping a feature:

1. Read this file (10 min)
2. Read the 1-2 guide_*.md for the layers your feature touches (5-10 min each)
3. Read the 1-2 code_styleguides/...md for the patterns your feature uses (5-10 min each)
4. Read the ticket (conductor/tracks/<id>/plan.md) for the specific task (variable)

Total: 20-45 min for a typical feature. The investment pays back across the feature's lifetime.

If a guide is missing or stale, that's a bug; file a docs issue (or update the guide inline, per the project's "edit the source of truth, not this file" pattern).

End of agent-facing mirror.