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.
Per user request 'use your remaining context to update agent workflow
docs and then regular docs based on what was discussed in this report',
this commit creates/updates 15 files derived from the v2.3 nagent
review (the 12 new nagent additions + the 4 memory dimensions
reframing + the cache strategy + the RAG discipline + the knowledge
harvest pattern).
Agent workflow docs (4 files):
- AGENTS.md (UPDATE): add @import line to canonical DOD + 'Code
Styleguides' section pointing to the 6 new styleguides + new
'Human-Facing Documentation' section pointing to ./docs/AGENTS.md
- conductor/workflow.md (UPDATE): new section 'Additions (2026-06-12)
- the 12 patterns from the latest nagent corpus' with TDD
protocols for knowledge harvest, cache ordering, compaction, RAG
discipline
- conductor/product-guidelines.md (UPDATE): new sections 'Memory
Dimensions (added 2026-06-12)' + 'See Also - Updated' with the
6-styleguide catalog
- docs/AGENTS.md (NEW): the agent-facing mirror of docs/Readme.md
(per the nagent CLAUDE.md pattern). 10 sections + the per-tier
reading path + the 4 memory dimensions + the caching strategy +
the knowledge harvest + the RAG discipline + the feature flags
Regular docs (11 files):
- 6 new styleguides (the convention catalog):
* data_oriented_design.md: the canonical DOD reference (Tier
0/1/2; 3 defaults to reject; 8 core defaults; 7-question
simplification pass; 10-question self-check; 4 memory
dimensions in Manual Slop context)
* agent_memory_dimensions.md: the 4 memory dims (curation /
discussion / RAG / knowledge) + when to use each + the
boundaries
* rag_integration_discipline.md: the conservative-RAG rule
(opt-in, complement, provenance, no mutation, feature-gated,
graceful failure)
* 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, 'delete to turn off')
* feature_flags.md: file presence vs config flags vs CLI flags
- 3 new project docs (the cross-cutting guides):
* guide_agent_memory_dimensions.md: the cross-cutting guide on
the 4 dims + the decision tree
* guide_caching_strategy.md: caching across providers +
stable-to-volatile ordering + cache TTL GUI + the byte-
comparison test + the 5th provider (claude-code)
* guide_knowledge_curation.md: the knowledge memory guide (4th
dim) + the 5 category files + per-file notes + the digest +
the ledger + the harvest workflow
- 2 existing doc updates:
* guide_mma.md: new sections 'Delegation as context management'
+ 'The 4 memory dimensions (the MMA scope)'
* guide_ai_client.md: new section 'Cache strategy and the 12-
layer model' + the 5th provider (claude-code)
All files use the same style as the v2.3 review (the user's preferred
format): 7-column tables, no JSON, SSDL shape tags, forth/array
notation, file:line citations, ASCII sketches where useful. The
human Readme files (Readme.md, docs/Readme.md) are NOT modified
(per repeated user instruction).
The 5th provider (claude-code) is documented in guide_ai_client.md
+ the data_oriented_design.md references the nagent pattern as the
source of the canonical rules.
The cross-references are bidirectional: the 6 styleguides reference
the 3 project docs; the 3 project docs reference the 6 styleguides;
the 2 doc updates reference both; AGENTS.md + ./docs/AGENTS.md
provide the entry points.
The user called out the LLM training data bias: 'small files are
good, large files are bad.' This is wrong for production codebases.
Unreal has 15K+ line files; OS kernels, game engines, compilers all
routinely have 10K+ line files. File size is a non-issue. Cognitive
load is managed via naming, regions, and navigation tools (the
manual-slop MCP) — NOT via file splitting.
Updates:
1. AGENTS.md (master agent guidance):
- Added 'File Size and Naming Convention' section
- Added the hard rule: 'New namespaced src/<thing>.py files may
only be created on the user's explicit request. If you find
yourself about to create one, ASK FIRST.'
- Defaults: helpers and sub-systems go in the parent module
2. conductor/workflow.md (Guiding Principles):
- Removed 'Do NOT perform large file writes directamente' from
principle 7 (it was a delegating rule, but 'large file writes'
carried the propaganda)
- Added principle 8: 'File Naming Convention (HARD RULE)' that
references AGENTS.md
- Re-phrased principle 9 (Research-First) to clarify it's about
navigation efficiency, not file size
3. conductor/code_styleguides/python.md:
- Removed the 'extremely large files that violate the Anti-OOP
rule by necessity' framing
- Added the new rule about new src/<thing>.py files
4. .opencode/agents/tier3-worker.md and .opencode/agents/tier4-qa.md:
- Re-phrased 'Do NOT read full large files' to 'Use skeleton
tools to navigate any file regardless of size. File size is
not a concern; the right tools are.'
- Added the new rule about not creating new src/<thing>.py
files unless user explicitly requests it
5. conductor/tracks/qwen_llama_grok_followup_20260611/plan.md:
- Updated the 'Naming Convention' section to reference the new
'user explicit request' rule
This is docs-only. No code changes. The rule is now codified:
agents must ASK FIRST before creating new top-level src/ files.
Lesson 5 from the 4-day test-hell saga. The chroma cache lives at
tests/artifacts/.slop_cache/chroma_<collection>/, NOT at the per-run
live_gui_workspace_<timestamp>/ subdir. The trailing-slash bug in
Path(active_project_path).parent places the cache one level higher
than expected.
RAG tests must pre-clean the cache to avoid persistent state from
prior batched runs. Documents the cleanup pattern (shutil.rmtree with
ignore_errors=True), the auto-recovery mechanism (_validate_collection_dim),
and 3 anti-patterns (assuming per-run, not cleaning, asserting on
first chunk in batched context).
One addition to conductor/code_styleguides/python.md §8
"AI-Agent Specific Conventions":
- **No diagnostic noise in production code (Added
2026-06-09).** `sys.stderr.write(f"[XYZ_DIAG] ...") lines
in src/*.py are technical debt. The right place for
one-time investigation output is tests/artifacts/<test>.diag.log
(a log file) or a standalone /tmp/diag_<name>.py script.
If you must instrument production code, the diag lines
are part of the same atomic commit as the fix.
- **Test files ARE allowed to be diagnostic.** The rule
applies to src/*.py only; tests/test_*.py may use
print(..., file=sys.stderr) freely.
Markdown only. No code modified.
Eliminates 22 call sites that bypassed the AppController state owner
and read/wrote config.toml directly. AppController is now the single
source of truth for self.config; gui_2.py, commands.py, etc. go
through controller.save_config() / controller.load_config().
Production changes:
- src/models.py: rename load_config -> _load_config_from_disk,
save_config -> _save_config_to_disk (private I/O primitives)
- src/app_controller.py: add public load_config()/save_config() methods
that own the state. Update 3 internal call sites and 3 ConductorEngine
call sites to pass max_workers from self.config
- src/multi_agent_conductor.py: ConductorEngine.__init__ now takes
max_workers as a parameter (caller responsibility, not I/O primitive)
- src/external_editor.py: get_default_launcher() takes config as a
parameter; gui_2.py:1311,4776 pass app.config
- src/gui_2.py: 17 sites of models.save_config(X.config) replaced with
X.save_config() (delegates via __getattr__ to controller)
- src/commands.py: save_all() uses app.save_config()
Test changes (route through controller, not I/O primitive):
- tests/conftest.py: mock_app and app_instance fixtures now patch
AppController.load_config/save_config instead of models I/O primitives
- 18 other test files: patches renamed from models._save_config_to_disk
to AppController.save_config (and same for load_config)
- tests/test_app_controller_mcp.py: use SLOP_CONFIG env var instead of
patching removed CONFIG_PATH module constant
- tests/test_parallel_execution.py: pass max_workers=2 explicitly to
ConductorEngine (caller no longer reads config)
- tests/test_gui_paths.py: add save_config=MagicMock() to MockApp;
assert on controller method, not I/O primitive
- tests/test_models_no_top_level_tomli_w.py: still calls private
_save_config_to_disk directly (the only allowed exception; tests
the lazy-load behavior of the primitive itself)
New files:
- scripts/audit_no_models_config_io.py: enforces the rule (--strict,
--json modes; AST-based docstring detection to avoid false positives)
- conductor/code_styleguides/config_state_owner.md: documents the rule
Verification:
- 67 targeted tests pass
- scripts/audit_no_models_config_io.py --strict returns 0
This is the architectural cleanup that surfaced during the
audit_architectural_cheats_20260607 review. Closes the smoke-gun
CONFIG_PATH module constant (already done in 0c7ebf22) AND the
free-function models.load_config/save_config smell.
[conductor(checkpoint): config-iO-refactor-20260607]
- Add section 10 (Anti-OOP Conventions) to python.md with hard rules,
class justification requirements, and Strangler Fig refactoring pattern
- Create conductor/refactor_oop.md tracker with 4 phases for class elimination
- Add ruff PLR rules (PLR0912, PLR6301, PLR0206) to pyproject.toml for
OOP anti-patterns
Addresses AI agent scope misinterpretation issues by enforcing flat
function-call graphs over deep class hierarchies.
Replaces Google Python Style Guide with project-specific conventions:
1-space indentation, strict type hints on all signatures/vars,
minimal blank lines, 120-char soft limit, AI-agent conventions.
Also marks type hinting task complete in plan.md.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
ed
conductor-tier2