The 6 error-classifier functions in ai_client.py, openai_compatible.py,
and qwen_adapter.py now return ErrorInfo (data-oriented) instead of
ProviderError. Each takes a source: str parameter for telemetry
provenance. ProviderError class is still used in production code paths
(Task 3.4) and will be removed in Task 3.7.
Strictly additive: existing _resolve_and_check, read_file, list_directory,
and search_files are unchanged. The new variants return Result[Path] or
Result[str] using the data-oriented ErrorInfo/ErrorKind convention.
Add forward-references to the 5 new canonical sources added by the 2026-06-12 doc sync (commits 35c6cca1 + 434b6d0d): data_oriented_design.md, agent_memory_dimensions.md, rag_integration_discipline.md, knowledge_artifacts.md, docs/AGENTS.md. All 5 cite this track as the canonical error-handling convention; the 4 memory dimensions and 12 nagent TDD protocols are orthogonal to error handling so no plan changes were needed. Verification recorded in state.toml [doc_sync_20260612].
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.
ed