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.
v2.3 (nagent_review_v2_3_20260612.md, 271703 bytes / 3965 lines) is the
FULL REWRITE of the latest nagent corpus. Per user instruction:
- 'I want a full rewrite via a v2.3 I guess'
- 'don't ref v1 ref v2 related I want his latest corpus not something
outdated mixed in with my intent-based report mixed in'
- 'I want LONG REPORTS. make v2.3 the longest'
- 'You actually trucated info with 2.3. 2.1 had the breadth. you
should make 2.3 have both 2.1 breadth and 2.2 terse DSL stuff'
Stand-alone (no references to v1/v2/v2.1/v2.2 or the intent_dsl_survey).
Pure nagent corpus focus.
Length: 271703 bytes (longer than v2 at 68KB, v2.1 at 59KB, v2.2 at
35KB). Combined v2.1's breadth with v2.2's terse DSL style + full
source-line citations + new content the prior reviews did not have.
Structure (13 sections):
- §0 TL;DR (terse table)
- §1 The latest nagent corpus (the 8 commits; the 33-file tree; the
new 7-Part + 14-section README structure)
- §2 The 14 patterns in depth (one per pattern, with file:line refs)
- §3 The 12 new big additions (knowledge harvest, cache, compaction,
project context, claude-code, shared DOD, CLAUDE.md, per-file notes,
'delete to turn off', graceful save, delegation reframing)
- §4 The harvest pattern in detail (the new big one; full pipeline,
data shapes, codepath, retry budget, test surface, Manual Slop
implementation outline)
- §5 The cache strategy in detail (block order table, cache boundary
computation, Anthropic cache_control, the GUI exposure gap with
ASCII sketch)
- §6 The compaction pattern in detail (the 12-section structure, the
10-question self-review, the codepath, the Manual Slop prompt)
- §7 nagent architecture (4 reading levels + tag protocol + state
model + write boundaries + large-file pipeline)
- §8 The vocabulary patterns (8 tags + per-tag guidance + 4-tier
structure + cross-MCP mapping)
- §9 File splits, patches, summaries (4-stage pipeline + 12 languages
+ O(n) fix + cascade)
- §10 16 future-track candidates (full specifications + priority +
effort + dependencies + sequencing)
- §11 14 proposed new artifacts (canonical DOD + AGENTS.md + 5
styleguides + 3 project docs + 4 workflow updates; format commitment)
- §12 Recommended next steps (the action plan: foundation -> styleguides
-> project docs -> workflow updates; then the HIGH-priority candidates)
- §13 References (nagent source + Manual Slop source + docs + external;
the file:line citation index)
Format commitment applied throughout:
- 7-column tables (Symbol, Name, Signature, Semantics, Example, Source,
Shape) where applicable
- No JSON code blocks (JSON becomes tables or line-based arrays)
- SSDL shape tags: [I], ===>, o==>, ===>W===>, ===>M===>, ===>B===>, [B],
[M], [N], [Q], [S], [T], ───
- Forth/array notation in code examples (a b + for postfix math;
name := value for assignment; if cond { body } for control flow)
- File:line citations into both nagent source and Manual Slop source
- ASCII sketches for GUI panels (per docs/reports/ascii_sketch_ux_workflow
convention: [+/-], [Role: AI v], |text|, <click to expand>,
in:N out:N cache:N, @YYYY-MM-DDTHH:MM:SS)
v2, v2.1, v2.2 are preserved (per repeated user instructions).
Readme.md and docs/Readme.md stay human-facing. v1 review artifacts
preserved.
v2.2 (nagent_review_v2_2_20260612.md, ~35KB) is a focused delta, not a full
rewrite. Two user inputs drove it:
1. The user published intent_dsl_survey_20260612/report_v1.2.md (1367 lines,
10 prior-art clusters, 4 anchor claims, ~42-verb vocab, 10 AI-Agent
Properties in §6). The survey's §6 Claims 4 and 5 explicitly cite
nagent_review_v2_1 §2.1 and §2.2 as the source for the 4 memory
dimensions and stable-to-volatile cache ordering — so the v2.1 patterns
are now formally codified by the survey.
2. The user said: 'I don't really like JSON, I like table based formats
more, or things that are forth/array-like.'
v2.2 applies the data-format preferences:
- JSON block in v2.1 §2.1 (harvest output schema) replaced with a §4.4
7-column table (Symbol, Name, Signature, Semantics, Example,
Borrowed from, Shape)
- Comparison table (§5) reformatted with SSDL shape tags
- Future-track candidate list (§6) reformatted as a single 16-row table
with all metadata columns
- Proposed new artifacts (§8) in table form
v2.2 adopts survey grammar primitives (name := value, for x .. n,
if cond { ... }, tape { ... }, try { ... } recover err { ... },
sandbox { ... }, audit msg, fuzzy { ... }) where applicable.
v2.2 adds:
- Candidate 12b (cache TTL GUI controls) - the v2.1 sub-candidate
- Candidate 16 (AGENTS.md @import + canonical DOD file) - HIGH priority,
the foundation for all the other styleguides
- New §11 'In dialogue with intent DSL survey' - the 9 mutual cross-refs
v2 and v2.1 are preserved (per user instruction). All v1 artifacts and
the human Readme files are preserved. Format commitment for the
next-turn artifacts: all new styleguides and project docs will follow
the §4.4 table format.
Two annotations added to v1.2 of the report:
1. A.8 Glossary 'tape' entry now has a term-choice note (v1.2) that
documents:
(a) The rename rationale: 'tape' fits the sequential data-flow use
case (Lottes tape-drive metaphor) better than 'arena' (which
implies bulk allocation).
(b) Explicit reservation of 'arena' for a future, separate concept
(NOT a synonym for tape). The two would compose:
tape { arena { ... } } is a pipeline stage that uses an
arena-backed buffer.
(c) The intended semantic split:
- tape { } = sequential data flow (pre-scatter, source-as-you-go)
- arena { } (FUTURE) = bulk memory allocation (bulk-allocate,
bulk-free, host decides lifetime)
2. A.7.9 New Open Question 9 added: 'Future reservation of arena { }
for a separate concept'. Documents:
- Background: the v1.2 rename was not a synonym swap; 'arena' is
reserved for a different, future concept.
- Proposed split with a comparison table (semantic, implementation,
tier fit, examples).
- Composition: tape { arena { ... } } is valid and meaningful.
- Trade-offs: pro/con of split vs. unify; recommendation is split.
- Concrete next step for the follow-up B track: define the arena
grammar rule, allocation strategy, and 2-3 example uses.
These annotations close the loop on the term-choice discussion. The
follow-up B track (interpreter prototype) can now implement the
arena { } block without re-litigating the naming.
Survey now covers 10 prior-art clusters (was 8). New clusters per
user direction (Option A in the v1.2 cluster-fit discussion):
NEW: research/cluster_8_metadesk.md (research sub-report):
- Metadesk (Ryan Fleury + Allen Webster, Dion Systems, 2020-2021)
- 5 distinctive design properties: uniform 'lego-brick' AST, tags
as dispatch keys, multiple interchangeable delimiters, comment
+ source-location preservation, first-class C interop with
copy-paste distribution
- 2 citable anchor quotes with source URLs
- Synthesis: maps to Tier 3 (read/edit/discover) and Tier 4
(audit/fuzzy) verbs
NEW: research/cluster_9_verse.md (research sub-report):
- Verse (Simon Peyton Jones + Tim Sweeney, Epic Games, 2021-)
- 5 distinctive design properties: transactional semantics with
speculative execution, failure as first-class control flow, effect
tracking in function signature, new Verse Calculus (ICFP 2023
Distinguished Paper), everything-is-an-expression + live variables
- 3 citable anchor quotes
- Synthesis: maps to Tier 4 (try/recover/sandbox/audit) verbs;
two-layer failure model maps to Cluster 7's Result convention
UPDATED: report_v1.2.md (1343 lines, +42 from v1.2 base):
- Inserted Cluster 8 (Metadesk) and Cluster 9 (Verse) sections
between Cluster 7 and the section 2/3 divider
- Updated §2 intro to say '10 clusters' (was '8')
- Updated glossary 'clusters' entry to list all 10
- Updated v1.2 changelog note (4) to document the cluster additions
UPDATED: tracks.md:
- Track #23 status line now lists all 10 clusters
- Goal line updated to say '10 clusters' (was '8')
UPDATED: state.toml deliverable_summary:
- Added v1.2_changes[4] for the cluster additions
- Added cluster_count = 10
- research_sub_reports now lists 7 cluster files (0-9)
The spec/plan/review files still say '8 clusters' — left as
historical context (spec is approved with 8; expanding to 10 is
an editorial decision the user has now made; future revisions of
spec/plan should reflect 10).
Three bookkeeping files updated to reflect the v1.2 deliverable:
- metadata.json: deliverable now points at report_v1.2.md; added
deliverable_v1_1, final_commit=213e4994
- tracks.md: track #23 heading shows COMPLETE: 213e4994; status
line lists v1.0 -> v1.1 -> v1.2 history with the 3 v1.2 changes
(rename, postfix heuristic, nagent fix)
- state.toml: added version='v1.2'; deliverable_summary updated with
v1_2, v1_1, v1_0 fields and v1_2_changes list
Three files changed:
1. report_v1.2.md (NEW, 1301 lines) — v1.2 of the report with:
(a) Renamed arena { } to tape { } (better term; aligns syntax with
the Lottes tape-drive metaphor). All 46 occurrences replaced;
3 awkward double-tape phrases cleaned up (heading 3.6,
table cell, glossary entry).
(b) Mixed postfix/infix notation for math (per user heuristic):
- Strictly postfix for math primitives with precedence:
+ - * / ^, math indexing [], reducers sum/product.
- Infix for structural ops (no precedence concern):
:=, function calls, control flow (for/if), field access,
block delimiters.
- Heuristic: 'if the operator has precedence, postfix it;
if it doesn't, infix it.' Mixed examples like
'result := Matrix(m.rows 1 -, m.columns 1 -)' are canonical.
(c) nagent attribution corrected: previously said nagent is
Jody Bruchon's; it is Mike Acton's (github.com/macton/nagent;
per conductor/tracks/nagent_review_20260608/). Jofito stays
correctly attributed to Jody Bruchon.
(d) Added v1.2 changelog note at top + heuristic table at start
of section 3.
2. report_v1.1.md — nagent attribution fix propagated (post-hoc
correction; the original v1.1 commit had the same error in the
glossary line 1671).
3. research/cluster_3_intent_mapping.md — nagent attribution fix
in 2 places (header at line 188, body at line 190).
Appendix A.3 (EBNF) and A.4 (Tier 1 vocab) retain v1.1 form
pending a sync pass; noted in the v1.2 changelog at the top of
the report.
Three files updated to close out the track:
1. state.toml — all 28 tasks marked completed with their commit SHAs;
current_phase = complete; all 14 verification flags = true; added
deliverable_summary section pointing at report_v1.1.md, reportreview.md,
and the 5 research/ sub-reports.
2. metadata.json — status: complete; added deliverable_v1_0, review,
and final_commit fields.
3. tracks.md — track #23 heading now reads 'COMPLETE: c7e92896';
added a 'Status: 2026-06-12 — COMPLETE' line summarizing the
v1.1 deliverable (1301 lines, 7 sections + 9-subsection appendix,
42-verb vocab, 8 prior-art clusters, 14-grammar primitives, 4
hardware anchor claims, 10 AI-agent properties, 8 open questions).
This is the final bookkeeping for the track. nagent v2.2 can now
reference the report's Section 6 (AI-Agent Properties) and Section 7
(Open Questions) for its 'Future-Track Candidate #4: Intent-based
DSL' planning.
Two files:
1. reportreview.md (154 lines) — the final secondary review pass.
- Verified 29+ load-bearing claims across 5 sub-reports against
their actual sources (johno.se URLs, Onat/Lottes refs, Jofito
codeberg README, nagent docs, mcp_architecture spec, etc.)
- 28 claims confirmed accurate; 1 inaccuracy found: the user's
XML/JSON rejection quote was cited as decisions.md:50 but
that line doesn't contain it (the quote is from the brainstorming
session, not a project file)
- Recommendation: write report_v1.1.md with the citation fix and
a few optional small improvements (OCR-restored Lottes quote,
softened Wasm streaming-parse inference, Uiua open-source
onboarding already in main report)
2. report_v1.1.md (1301 lines, +883 over report.md) — the v1.1 report
with:
(a) The v1.0 corrections:
- Fixed XML/JSON rejection citation (now points to the
brainstorming session, not a project file)
- OCR-restored the Lottes X.com quote ('actually' added)
- Softened the Wasm streaming-parse inference
(b) A substantially expanded Appendix (Deep-Dives):
- A.1 Section 1 Deep-Dive: 4 anchor claims in detail
- A.2 Section 2 Deep-Dive: full text of all prior-art entries
(O'Donnell's 4 anchor claims with full context; all 6
Concatenative entries; all 4 Array entries; all 4
Intent-Mapping entries; all 4 Meta-Tooling entries; full
SSDL table; full 33 Command Palette commands; full Result
convention details)
- A.3 Section 3 Deep-Dive: formal EBNF grammar spec
- A.4 Section 4 Deep-Dive: full vocab reference for all 42
verbs (with signatures, semantics, examples, edge cases)
- A.5 Section 5 Deep-Dive: register allocation + memory
layout + FFI bridge
- A.6 Section 6 Deep-Dive: implementation notes per claim
- A.7 Section 7 Deep-Dive: open questions with proposed
solutions and trade-offs
- A.8 Glossary
- A.9 Expanded Bibliography (4 categories with 1-line
descriptions and key-claim summaries)
This is the final deliverable for the intent_dsl_survey_20260612
track. v1.1.md is what nagent v2.2 will reference for its
'Future-Track Candidate #4: Intent-based DSL' section.
ed