From 79a7be8bc22b48b579b3a064710b48c092597637 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 19 Apr 2026 10:50:58 +0000 Subject: [PATCH 01/18] chore: gitignore .claude/settings.local.json (personal permission overrides) --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index 10a3d6f1..f415446f 100644 --- a/.gitignore +++ b/.gitignore @@ -58,3 +58,6 @@ knowledge_graph_data/ # Large model data (use GitHub Releases) crates/thinking-engine/data/Qwopus3.5-27B-v3-BF16-silu/token_embd_centroids_4096x5120.f32 crates/thinking-engine/data/Qwopus3.5-27B-v3-BF16-silu/token_embd_4096x4096.u8 + +# Claude Code personal overrides (per-project) +.claude/settings.local.json From 30861e0d421ec444397492cdf4b43fef97914c1b Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 19 Apr 2026 10:52:47 +0000 Subject: [PATCH 02/18] =?UTF-8?q?chore:=20model=20policy=20=E2=80=94=20opu?= =?UTF-8?q?s=20main=20thread,=20sonnet=20subagents,=20never=20haiku?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documents the token-budget pattern: deep thinking stays on the main thread (Opus + effortLevel high); mechanical drafting / grep / file ops offload to Sonnet-backed subagents via explicit model override. Haiku is excluded from the subagent pool regardless of task. Settings baseline (in gitignored settings.local.json): alwaysThinkingEnabled: true effortLevel: high fastModePerSessionOptIn: true --- CLAUDE.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 97dac6d6..30264ba6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,6 +6,21 @@ --- +## Model Policy (P0 — never violate) + +- **Main thread:** `claude-opus-4-7[1m]` (or current Opus) with deep + thinking. Synthesis, architecture, review, decisions. +- **Subagent drafting / search / file ops:** `sonnet` minimum. Pass + `model: "sonnet"` explicitly when spawning `Agent` tools for + mechanical work. +- **NEVER `haiku` for subagents in this workspace.** Quality floor is + Sonnet regardless of task simplicity. +- **Writing cheap, thinking deep:** delegate draft-from-spec, grep, + file survey work to Sonnet-backed subagents; keep the main thread + on Opus + `effortLevel: high` (`.claude/settings.local.json`). + +--- + ## What This Is Graph query engine AND cognitive codec stack for the Ada architecture. lance-graph is no longer From 550e27d7cc0202610f02e329df1ee36e93478d58 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 19 Apr 2026 10:53:36 +0000 Subject: [PATCH 03/18] chore(policy): carve out Explore subagent tier \u2014 Sonnet OK, not Opus --- CLAUDE.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 30264ba6..00aab77d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -10,11 +10,14 @@ - **Main thread:** `claude-opus-4-7[1m]` (or current Opus) with deep thinking. Synthesis, architecture, review, decisions. -- **Subagent drafting / search / file ops:** `sonnet` minimum. Pass - `model: "sonnet"` explicitly when spawning `Agent` tools for - mechanical work. -- **NEVER `haiku` for subagents in this workspace.** Quality floor is - Sonnet regardless of task simplicity. +- **`Plan` / code-review / architecture subagents:** Opus. The model + must match the judgment the agent is making. +- **`general-purpose` drafting / file-writing subagents:** Sonnet. + Pass `model: "sonnet"` explicitly when spawning. +- **`Explore` (read-only search) subagents:** Sonnet. Cheaper tier is + fine here — the work is pattern matching, not reasoning. +- **NEVER `haiku` for any subagent in this workspace.** Quality floor + is Sonnet regardless of task simplicity. - **Writing cheap, thinking deep:** delegate draft-from-spec, grep, file survey work to Sonnet-backed subagents; keep the main thread on Opus + `effortLevel: high` (`.claude/settings.local.json`). From 1a8a3d72bdf339c625c6d081885df12ec5cfe070 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 19 Apr 2026 10:54:40 +0000 Subject: [PATCH 04/18] chore(policy): split grindwork vs accumulation for subagent model choice MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Grindwork (single-task mechanical: write-file-from-spec, grep, list paths, run tests, draft a section) → Sonnet. Bounded input, known output shape, no cross-source synthesis. Accumulation (multi-source synthesis: harvest across repos, combine N docs into insights, trace architecture across files, judgment calls that require holding several inputs in mind together) → Opus. Cheaper tiers produce shallow outputs under accumulation; quality drop is visible. Concrete test before spawning: "Does this agent read N sources and produce something that only makes sense when those sources are held in mind together?" Yes → Opus. No → Sonnet. Retrospective: Phase 1 D4 + D6 agents (single-file draft from tight spec) were grindwork — Sonnet was correct default. Phase 1 D0 grammar-landscape agent (read 5 knowledge docs + synthesize into new doc) was accumulation — timed out on lower tier, should have been Opus. Still never Haiku, regardless of task. --- CLAUDE.md | 43 +++++++++++++++++++++++++++++++++---------- 1 file changed, 33 insertions(+), 10 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 00aab77d..e2bce96a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -8,19 +8,42 @@ ## Model Policy (P0 — never violate) +**The split that matters: grindwork vs accumulation.** + +- **Grindwork** (single-task mechanical): write-this-file-from-spec, + grep-this-pattern, list-these-paths, run-these-tests, draft-this- + section — **Sonnet**. Bounded input, known output shape, no + synthesis across sources. +- **Accumulation** (multi-source synthesis): harvest-across-repos, + combine-N-docs-into-insights, trace-architecture-across-files, + cross-reference and integrate, judgment calls that depend on + seeing several inputs at once — **Opus**. Cheaper tiers produce + shallow outputs when asked to accumulate; quality drop is visible + and costly. + +**By subagent type:** - **Main thread:** `claude-opus-4-7[1m]` (or current Opus) with deep - thinking. Synthesis, architecture, review, decisions. -- **`Plan` / code-review / architecture subagents:** Opus. The model - must match the judgment the agent is making. -- **`general-purpose` drafting / file-writing subagents:** Sonnet. - Pass `model: "sonnet"` explicitly when spawning. -- **`Explore` (read-only search) subagents:** Sonnet. Cheaper tier is - fine here — the work is pattern matching, not reasoning. + thinking. Synthesis, architecture, review, decisions — all + accumulation. +- **`Plan` subagent:** Opus. Planning is accumulation by definition. +- **Code-review subagent:** Opus. Review is multi-file judgment. +- **`general-purpose` subagent:** depends on task. Pure grindwork → + Sonnet. Anything accumulating → Opus. When in doubt: Opus. +- **`Explore` subagent:** Sonnet default. Search is pattern matching. + If the explore requires synthesis across many files (mapping an + architecture), escalate to Opus. - **NEVER `haiku` for any subagent in this workspace.** Quality floor is Sonnet regardless of task simplicity. -- **Writing cheap, thinking deep:** delegate draft-from-spec, grep, - file survey work to Sonnet-backed subagents; keep the main thread - on Opus + `effortLevel: high` (`.claude/settings.local.json`). + +**Concrete test before spawning a subagent:** +> "Does this agent have to read N sources and produce something that +> only makes sense when those sources are held in mind together?" +> +> **Yes → Opus.** No (one source in, one shape out) → Sonnet. + +**Settings baseline** (`.claude/settings.local.json`, gitignored): +`alwaysThinkingEnabled: true`, `effortLevel: high`, +`fastModePerSessionOptIn: true`. Main thread stays at full depth. --- From 167b2d598491a83b9188fe833fba1a4b588c962f Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 19 Apr 2026 10:56:22 +0000 Subject: [PATCH 05/18] chore(policy): zipball-for-reads, MCP-for-writes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every mcp__github__get_file_contents drops the full file into session context and re-bills on every subsequent turn. Cross-repo exploration using MCP costs ~20x what the same exploration costs via zipball + local grep (95% savings on read-heavy turns). Pattern: curl ... /repos///zipball/HEAD | unzip → /tmp/sources/ Then: Read / Grep / Glob on local files. Zero context cost until grep output. MCP github stays for: - create_pull_request (write, not replaceable) - add_issue_comment / review writes (state mutation) - pull_request_read on our PRs (tiny JSON) - get_me, subscribe_pr_activity (session setup) MCP github NOT for: - Cross-repo file exploration - Surveying many files from same repo - Directory listings Edge case: single targeted read when path is known → MCP is fine. Zipball pays off at 3+ reads per repo. Combined with the grindwork/accumulation split, this is the two- lever cost optimization for read-heavy harvest sessions. --- CLAUDE.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index e2bce96a..f5d50dc8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -47,6 +47,53 @@ --- +## GitHub Access Policy — Zipball for Reads, MCP for Writes + +Every `mcp__github__get_file_contents` call drops the full file into +session context and recharges on every subsequent turn. A 50 KB doc +read three times in a session = 150 KB of replayed context, not 50 KB. +This is the second-biggest cost lever after model choice. + +**Preferred pattern for cross-repo reads:** + +```bash +# One zipball per repo per session, stored under /tmp/sources/: +curl -H "Authorization: Bearer $GITHUB_TOKEN" \ + -L https://api.github.com/repos/AdaWorldAPI//zipball/HEAD \ + -o /tmp/.zip +unzip -q /tmp/.zip -d /tmp/sources/ +# Then use local Read, Grep, Glob — zero context cost until output. +``` + +Or via `pygithub`'s `repo.get_archive_link('zipball')` when Python +is already the path. + +**Use MCP github ONLY for:** + +- `create_pull_request` — can't be done via zipball. +- `add_issue_comment` / `add_reply_to_pull_request_comment` / review + thread writes — writes to GitHub state. +- `pull_request_read` on our own PRs to check reviews / comments — + tiny JSON, not worth zipball overhead. +- `get_me`, `subscribe_pr_activity` — session setup. + +**Do NOT use MCP github for:** + +- Cross-repo file exploration — zipball + local grep is 95 % cheaper. +- Surveying many files from the same repo — same reason. +- Directory listings — extracted tree is free to traverse locally. + +**Edge case:** single targeted read when the exact path is known and +you'll read once → `mcp__github__get_file_contents` is fine. Zipball +overhead (download + extract) only pays off at 3+ reads per repo. + +**This maps to the grindwork/accumulation split too:** +zipball-then-grep-then-synthesize is accumulation, and the synthesis +step (main thread or Opus subagent) reads just the relevant greps, +not whole files. + +--- + ## What This Is Graph query engine AND cognitive codec stack for the Ada architecture. lance-graph is no longer From a81cfde4c284a73968e537e35517eab258362e6d Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 19 Apr 2026 11:15:36 +0000 Subject: [PATCH 06/18] feat(knowledge): PR-arc inventory + latest-state + append-only governance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes the 30-turn cold-start tax — new sessions hallucinate what already exists, violate conventions locked in recent PRs, and burn context turns rediscovering structure. Two knowledge docs + CLAUDE.md header: 1. .claude/knowledge/LATEST_STATE.md — current contract inventory, recently merged PRs, active branches, queued Phase 2 work, explicit deferrals (what NOT to propose). 2. .claude/knowledge/PR_ARC_INVENTORY.md — chronological decision history per PR with Added / Locked / Deferred / Docs / Confidence. APPEND-ONLY: new PRs prepend; old entries are immutable historical record. The Confidence line is the ONLY mutable field — use to record "working", "superseded by PR #N", "broken — see PR #N for fix". Corrections append via "Correction (YYYY-MM-DD from PR #N)" line; do not edit the original claim. 3. CLAUDE.md header now mandates reading both files at session start, before proposing anything. Closes the cold-start gap: session loads CLAUDE.md (auto) → two mandatory files (explicit references) → domain knowledge docs (as triggered). Personal Edit-ask permissions on these files live in gitignored settings.local.json (team-level policy would use .claude/settings.json for shared enforcement). Target cold-start cost: 3-5 turns instead of 30. --- .claude/knowledge/LATEST_STATE.md | 100 ++++++++++++ .claude/knowledge/PR_ARC_INVENTORY.md | 220 ++++++++++++++++++++++++++ CLAUDE.md | 22 ++- 3 files changed, 341 insertions(+), 1 deletion(-) create mode 100644 .claude/knowledge/LATEST_STATE.md create mode 100644 .claude/knowledge/PR_ARC_INVENTORY.md diff --git a/.claude/knowledge/LATEST_STATE.md b/.claude/knowledge/LATEST_STATE.md new file mode 100644 index 00000000..5baac10d --- /dev/null +++ b/.claude/knowledge/LATEST_STATE.md @@ -0,0 +1,100 @@ +# LATEST_STATE — What Just Shipped (read this FIRST) + +> **Auto-injected at session start via SessionStart hook.** +> Updated after every merged PR. +> **Last updated:** 2026-04-19 post PR #210. +> +> Purpose: prevent new sessions from hallucinating structure that +> already exists or proposing features already shipped. Read this +> BEFORE proposing any grammar/crystal/contract changes. + +--- + +## Recently Shipped PRs (reverse chronological) + +| PR | Merged | Title | What it added | +|---|---|---|---| +| **#210** | 2026-04-19 | Phase 1 grammar + knowledge docs | ContextChain reasoning ops, role_keys slice catalogue, 3 knowledge docs (grammar-landscape, linguistic-epiphanies E13-E27, fractal-codec) | +| **#209** | 2026-04-19 | sandwich layout + bipolar cells | Crystal fingerprint sandwich, VSA_permute reference, lossless bundling corrections | +| **#208** | 2026-04-19 | grammar + crystal + AriGraph unbundle | Contract grammar/ + crystal/ modules, AriGraph episodic unbundle hooks with SIMD dispatch | +| **#206** | 2026-04-18 | state classification pillars | qualia.rs (17D), proprioception.rs (7 anchors), world_map.rs, sigma_rosetta 64 glyphs + 144 verbs, Pumpkin NPC example | +| **#205** | 2026-04-18 | engine bridge + CMYK/RGB qualia | engine_bridge.rs, 12-style unified mapping, 17D vs 18D qualia distinction | +| **#204** | 2026-04-18 | cognitive-shader-driver | New crate, ShaderDispatch/Resonance/Bus/Crystal DTOs, BindSpace struct-of-arrays, full ladybug-rs import | + +## Current Contract Inventory (lance-graph-contract) + +Types that EXIST — do NOT re-propose them: + +**`grammar/`**: `FailureTicket`, `PartialParse`, `CausalAmbiguity`, `TekamoloSlots`, `TekamoloSlot`, `WechselAmbiguity`, `WechselRole`, `FinnishCase`, `finnish_case_for_suffix`, `NarsInference`, `inference_to_style_cluster`, `ContextChain` (with coherence_at / total_coherence / replay_with_alternative / disambiguate / DisambiguationResult / WeightingKernel), `RoleKey` + 47 `LazyLock` instances + `Tense` enum + `finnish_case_key / tense_key / nars_inference_key` lookups. + +**`crystal/`**: `Crystal` trait, `CrystalKind`, `TruthValue`, `UNBUNDLE_HARDNESS_THRESHOLD = 0.8`, `CrystalFingerprint` (Binary16K / Structured5x5 / Vsa10kI8 / Vsa10kF32), `Structured5x5`, `Quorum5D`, `SentenceCrystal`, `ContextCrystal`, `DocumentCrystal`, `CycleCrystal`, `SessionCrystal`, sandwich layout constants. + +**`cognitive_shader`**: `ShaderDispatch`, `ShaderResonance`, `ShaderBus`, `ShaderCrystal`, `MetaWord` (u32 packed), `MetaFilter`, `ColumnWindow`, `StyleSelector`, `RungLevel`, `EmitMode`, `ShaderSink` trait, `CognitiveShaderDriver` trait. + +**`proprioception`**: 7 `StateAnchor` (Intake/Focused/Rest/Flow/Observer/Balanced/Baseline), 11-D `ProprioceptionAxes`, `StateClassifier` trait, `DefaultClassifier`, `hydrate()` softmax-weighted blend. + +**`qualia`**: 17-D `QualiaVector`, `qualia_to_state` projection (17→11). + +**`world_map`**: `WorldMapDto`, `WorldMapRenderer` trait, `DefaultRenderer`. + +**`world_model`**: `WorldModelDto` with `qualia`, `axes`, `proprioception`, `cycle_fingerprint`, `timestamp`, `cycle_index`, `is_self_recognised()` / `is_liminal()`. + +**`container`**: `Container = [u64; 256]` (16Kbit = 2KB), `CogRecord`. + +**`a2a_blackboard`**, **`collapse_gate`**, **`exploration`**, **`literal_graph`**, **`orchestration_mode`**, **`jit`**, **`nars`**, **`plan`**, **`orchestration`**, **`thinking`** (36 styles, 6 clusters), **`mul`**, **`sensorium`**, **`cam`**, **`high_heel`**. + +## Current AriGraph Inventory (lance-graph/src/graph/arigraph/) + +4696 LOC shipped, 7 modules: +- `episodic.rs` (210 LOC + unbundle hooks from #208) — `Episode`, `EpisodicMemory`, `unbundle_hardened`, `unbundle_targeted`, `rebundle_cold`, `UnbundleReport`, `RebundleReport`, `UNBUNDLE_HARDNESS_THRESHOLD = 0.8` +- `triplet_graph.rs` (1064 LOC) — SPO graph, NARS truth, BFS, spatial paths +- `retrieval.rs` (447 LOC) — fingerprint retrieval policies +- `sensorium.rs` (539 LOC) — observation → triplets +- `orchestrator.rs` (1562 LOC) — AriGraph coordinator +- `xai_client.rs` (521 LOC) — xAI enrichment +- `language.rs` (339 LOC) — LM bridge + +## Workspace Conventions (locked in CLAUDE.md) + +1. **Model policy:** main thread Opus + deep thinking; subagent grindwork → Sonnet; accumulation → Opus; NEVER Haiku. +2. **GitHub reads:** zipball to `/tmp/sources/` + local grep for 3+ reads per repo. MCP only for writes (PR, comments) and single-path reads. +3. **Contract zero-dep invariant:** `lance-graph-contract` has no external crate deps. Do not add any. +4. **Read before Write:** always Read a file before overwriting. Write-over-self without Read is the documented failure mode. +5. **No JSON serialization in types.** Serde stays out of types (debug-only). Wire formats are explicit. +6. **Pumpkin framing** for externally-visible examples (clinical / game-AI disguise for the AGI primitives). + +## Active Branches (local at /home/user/lance-graph) + +- `claude/deepnsm-grammar-phase1` — Phase 1 PR #210, merged into main. +- `main` — up-to-date post #210. + +## Immediate Next Work (Phase 2 — queued, NOT yet shipped) + +Per `/root/.claude/plans/elegant-herding-rocket.md`: + +- **D2** DeepNSM emits `FailureTicket` on low coverage (~150 LOC). +- **D3** Grammar Triangle wired into DeepNSM via `triangle_bridge.rs` (~220 LOC). +- **D5** Markov ±5 bundler with role-indexed VSA (~300 LOC). +- **D7** NARS-tested grammar thinking styles as meta-inference policies (~260 LOC). + +Total ~930 LOC, one PR when it ships. + +## Deferred (do NOT propose these — they're explicitly parked) + +- CausalityFlow TEKAMOLO extension (modal/local/instrument + beneficiary/goal/source, 9 total) — struct change deferred until after Phase 2. +- D8 story-context bridge, D9 ONNX arc export, D10 Animal Farm validation, D11 bundle-perturb emergence — Phase 3/4. +- Named Entity pre-pass (NER) — biggest OSINT blocker, separate PR. +- FP_WORDS = 160 migration (currently 157) — coordinated ndarray change. +- Crystal4K 41:1 persistence compression. +- 200-500 YAML TEKAMOLO templates per language — future training pipeline. +- Python/TypeScript grammar-stack convergence. + +## If You're Tempted to Propose Something + +Check this file first. Then check the KNOWLEDGE_INDEX.md for which +docs cover your domain. Then load only those docs. If you're still +uncertain whether something exists, grep the actual source before +proposing a new type. + +The fastest way to waste 30 turns is to re-invent what's already in +the contract. This file exists to prevent that. diff --git a/.claude/knowledge/PR_ARC_INVENTORY.md b/.claude/knowledge/PR_ARC_INVENTORY.md new file mode 100644 index 00000000..0284f48d --- /dev/null +++ b/.claude/knowledge/PR_ARC_INVENTORY.md @@ -0,0 +1,220 @@ +# PR Arc — Architectural Decision History + +> **Auto-loaded at session start.** Every merged PR, its meta, and +> the decisions it locked in. Read BEFORE proposing anything — a new +> proposal that contradicts a decision in this arc is a 30-turn +> rediscovery tax waiting to happen. +> +> ## APPEND-ONLY RULE (MANDATORY) +> +> 1. **New PRs PREPEND** a new section at the top (most-recent first). +> 2. **Old PR sections are IMMUTABLE HISTORY.** Never rewrite or +> delete a past PR's Added / Locked / Deferred / Docs entries. +> 3. **The ONE exception: Confidence annotations.** Each PR section +> may have a `**Confidence (YYYY-MM-DD):**` line that IS updatable. +> Use it to record: "working", "partial", "superseded by PR #N", +> "broken — see PR #N for fix". This is the only mutable field. +> 4. **Corrections append.** If a Locked claim turns out wrong, +> append a `**Correction (YYYY-MM-DD from PR #N):**` line to the +> same entry — do not edit the original Locked line. Both stay. +> 5. **Reversals are their own PR entry.** If a later PR explicitly +> undoes a decision, the later entry documents the reversal; the +> earlier entry's Confidence line references it. Both remain in +> the arc. +> +> The arc is the historical record. Rewriting it destroys the +> "why was this decided that way" context that prevents future +> rediscovery. Every entry stays. +> +> **Format:** reverse chronological. Each PR carries: +> - **Added** — new types / modules / LOC (immutable) +> - **Locked** — conventions / invariants / patterns (immutable) +> - **Deferred** — explicit parks (immutable) +> - **Docs** — knowledge files produced (immutable) +> - **Confidence (YYYY-MM-DD):** — the ONLY mutable field + +--- + +## #210 — Phase 1 grammar + knowledge docs (merged 2026-04-19) + +**Confidence (2026-04-19):** Working. All tests green at merge time. + +**Added:** +- `contract::grammar::context_chain` — coherence_at / total_coherence / replay_with_alternative / disambiguate / DisambiguationResult / WeightingKernel {Uniform, MexicanHat, Gaussian} (+396 LOC, 8 tests). +- `contract::grammar::role_keys` — 47 canonical role keys addressed as contiguous `[start:stop]` slices over 10,000 VSA dims. FNV-64 + per-dim LCG deterministic generation. `Tense` enum (12 variants). `finnish_case_key / tense_key / nars_inference_key` lookups (+404 LOC, 7 tests). + +**Locked:** +- **Role-key VSA addressing uses contiguous slices**, not scattered bits. Subject=[0..2000), Predicate=[2000..4000), Object=[4000..6000), Modifier=[6000..7500), Context=[7500..9000), TEKAMOLO slots=[9000..9900), Finnish cases=[9840..9910), tenses=[9910..9970), NARS inferences=[9970..10000). +- **All role-key slices are disjoint**; binding into one slice does not contaminate another. +- **ContextChain coherence is Hamming-based** on the Binary16K variant, graceful zero-score on other variants (zero-dep constraint). +- **Mexican-hat weight:** `(1 - 2x^2) · exp(-2x^2)` where `x = d / MARKOV_RADIUS`. Monotone on d=0..5. +- **DISAMBIGUATION_MARGIN_THRESHOLD = 0.1** — below this the `escalate_to_llm` flag fires. + +**Deferred:** +- CausalityFlow 3→9 slot extension (modal/local/instrument + beneficiary/goal/source). +- Phase 2 work: D2 FailureTicket emission, D3 Triangle bridge, D5 Markov bundler, D7 grammar thinking styles. +- All of Phase 3/4. + +**Docs:** +- `grammar-landscape.md` (429 lines) +- `linguistic-epiphanies-2026-04-19.md` (466 lines, E13-E27) +- `fractal-codec-argmax-regime.md` (256 lines, orthogonal thread) + +**Decisions for future PRs to respect:** +- Finnish object marking uses Nominative/Genitive/Partitive, NOT Latinate Accusative (except personal pronouns). +- Russian 6 cases include Instrumental (not omitted). +- Each language gets its native case terminology. +- Never spawn Haiku subagents. +- Explore subagents → Sonnet, `general-purpose` grindwork → Sonnet, accumulation → Opus. + +--- + +## #209 — sandwich layout + bipolar cells (merged 2026-04-19) + +**Confidence (2026-04-19):** Working. All tests green at merge time. + +**Added:** +- `CrystalFingerprint::Structured5x5` uses sandwich layout: 3,125 cells in middle (dims 3437..6562), 5 quorum floats (6562..6567), quorum sentinel (6567), plus leading/trailing role-binding space. +- Bipolar cell encoding: `u8 0..=255 → f32 [-1, 1]` via `v/127.5 - 1.0`. +- Lossless bundle/unbundle between Structured5x5 ↔ Vsa10kF32 sandwich. +- Codex-review fixes: Binary16K aliasing, i8 /128 clamp, `quorum: None` sentinel. + +**Locked:** +- **VSA operations stay in `ndarray::hpc::vsa`** (bind, unbind, bundle, permute, similarity, hamming, sequence, clean). DO NOT duplicate in contract. +- **10K f32 Vsa10kF32 (40 KB) is lossless under linear sum**, not a wire-only format; lancedb natively handles 10K VSA. +- **Signed 5^5 bipolar is lossless**; unsigned / bitpacked binary is lossy via saturation. +- **CAM-PQ projection is distance-preserving** (lossless across form transitions). +- **VSA convention is `[start:stop]` contiguous slices**, not scattered bits. +- `Structured5x5` is the native rich form; `Vsa10kF32` is native storage (not passthrough). + +**Deferred:** +- PhaseTag types (ladybug-rs owns them). +- Crystal4K 41:1 compression persistence (ladybug-rs owns it). +- ladybug-rs quantum 9-op set port. + +**Docs:** +- `crystal-quantum-blueprints.md` (existing, cross-referenced) +- Cross-repo-harvest H1-H14 (Born rule, phase tag, interference, Grammar Triangle ≡ ContextCrystal(w=1), NSM ≡ SPO axes, FP_WORDS=160, Mexican-hat, Int4State, Glyph5B, Crystal4K, teleport F=1, 144-verb, Three Mountains). + +--- + +## #208 — grammar + crystal + AriGraph unbundle (merged 2026-04-19) + +**Confidence (2026-04-19):** Working. All tests green at merge time. + +**Added:** +- `contract::grammar/` module (6 files): FailureTicket, PartialParse, CausalAmbiguity, TekamoloSlots/TekamoloSlot, WechselAmbiguity/WechselRole, FinnishCase, NarsInference (7 variants), ContextChain (ring buffer), LOCAL_COVERAGE_THRESHOLD = 0.9, MARKOV_RADIUS = 5. +- `contract::crystal/` module (7 files): Crystal trait, CrystalKind, TruthValue, CrystalFingerprint (Binary16K / Structured5x5 / Vsa10kI8 / Vsa10kF32), SentenceCrystal / ContextCrystal / DocumentCrystal / CycleCrystal / SessionCrystal. +- `lance-graph::graph::arigraph::episodic`: unbundle_hardened / unbundle_targeted / rebundle_cold with ndarray::hpc::bitwise::hamming_batch_raw SIMD dispatch under `ndarray-hpc` feature. +- `UNBUNDLE_HARDNESS_THRESHOLD = 0.8` synchronized in contract + arigraph. + +**Locked:** +- **AriGraph lives in-tree** at `lance-graph/src/graph/arigraph/` (not a standalone crate). 4696 LOC transcoded from Python AdaWorldAPI/AriGraph. +- **Crystals unbundle when hardness ≥ 0.8.** Rebundle for cold entries. +- **FailureTicket carries SPO × 2³ × TEKAMOLO × Wechsel decomposition** plus coverage + attempted_inference + recommended_next. +- **Finnish 15 cases, Russian 6 cases, Turkish 6 cases** + agglutinative chain, German 4 cases, Japanese particles — each in native terminology. + +**Deferred:** +- DeepNSM emission of FailureTicket (D2, Phase 2). +- Grammar Triangle bridge into DeepNSM (D3, Phase 2). + +**Docs:** +- `integration-plan-grammar-crystal-arigraph.md` (E1-E12 epiphanies). +- `crystal-quantum-blueprints.md` (Crystal vs Quantum modes). +- `endgame-holographic-agi.md` (5-layer stack). + +--- + +## #207 — session capstone + Wikidata plan (merged 2026-04-18) + +**Confidence (2026-04-19):** Working. All tests green at merge time. + +**Added:** +- `session-capstone-2026-04-18.md` — 8 epiphanies (E1-E8), Sleeping Beauties (SB1-7), Missing Bridges (MB1-5), Known Brittle (KB1-5), priority map. +- `wikidata-spo-nars-at-scale.md` — 1.2B triples → 14.4 GB scale demo plan. + +**Locked:** +- **§7 addendum correction:** AriGraph is SHIPPED, not deferred. Invalidates capstone's DD2 and MB3. +- **4-pillar inheritance** (NARS + thinking + qualia + proprioception) is compile-time contract. +- **CMYK (17D experienced) vs RGB (18D observed) qualia** — dim 17 = classification_distance. +- **Vocabulary IS semantics** — glyph names use pretraining-derived associations on purpose. + +--- + +## #206 — state classification pillars (merged 2026-04-18) + +**Confidence (2026-04-19):** Working. All tests green at merge time. + +**Added:** +- `contract::qualia` — 17-D QualiaVector + 17→11 projection. +- `contract::proprioception` — 7 StateAnchor (Intake/Focused/Rest/Flow/Observer/Balanced/Baseline), 11-D state vector, ProprioceptionAxes, StateClassifier trait, DefaultClassifier, softmax `hydrate()`. +- `contract::world_map` — WorldMapDto + WorldMapRenderer trait + DefaultRenderer. +- `world_model.rs` extended: `qualia`, `axes`, `proprioception`, `cycle_fingerprint`, `timestamp`, `cycle_index`, `is_self_recognised()`, `is_liminal()`. +- `cognitive-shader-driver::sigma_rosetta` — 64 glyphs (Σ11) × 144 verbs (Σ12 = 12 roots × 12 tenses), SigmaState, TriangleGestalt, QuadTriangleGestalt, InteractionKinematic (Σ13 dome), QPL ↔ sigma 17D bridge. +- REST (`serve` feature) + gRPC (`grpc` feature) endpoints. +- `examples/villager_ai.rs` — Pumpkin NPC AI reference. + +**Locked:** +- **Proprioception in the contract** = ontological self-recognition by compilation. +- **WorldMapRenderer pattern** — drop-in framing trait keeps contract vocabulary neutral. +- **Pumpkin / villager AI framing** for externally-visible examples (corporate disguise). +- **`proprioception::axes` named fields** (drive / arousal / dominance / …) — public API. +- **No code comments or PR descriptions** reveal the disguise scrubbing. Everything personal goes to ada-rs. + +--- + +## #205 — engine_bridge + CMYK/RGB qualia (merged 2026-04-18) + +**Confidence (2026-04-19):** Working. All tests green at merge time. + +**Added:** +- `cognitive-shader-driver::engine_bridge` — ingest_codebook_indices, dispatch_from_top_k, EngineBusBridge, persist_cycle, UNIFIED_STYLES[12] 3-way mapping (ThinkingStyle ↔ StyleSelector ↔ p64 StyleParams). +- CMYK vs RGB qualia decomposition — 17D experienced vs 18D observed, classification_distance as dim 17. + +**Locked:** +- **12 UNIFIED_STYLES** are the canonical style inventory (3-way mapping must stay aligned). +- **Named emotion archetypes** (fear/anger/sadness/joy/surprise/disgust) live in engine_bridge as classification references. + +--- + +## #204 — cognitive-shader-driver crate + Shader DTOs (merged 2026-04-18) + +**Confidence (2026-04-19):** Working. All tests green at merge time. + +**Added:** +- New crate `cognitive-shader-driver` (24 tests). +- `contract::cognitive_shader` — ShaderDispatch / ShaderResonance / ShaderBus / ShaderCrystal, MetaWord (u32 packed: thinking 6 + awareness 4 + nars_f 8 + nars_c 8 + free_e 6), CognitiveShaderDriver trait, ShaderSink commit-adapter. +- `auto_style` — 18D qualia → style ordinal. +- 630K LOC ladybug-rs import into `lance-graph-cognitive` (grammar, spo, learning, world, search, fabric, spectroscopy, container_bs, core_full). +- `crates/holograph` imported from RedisGraph, 10K→16K migration. +- `contract::container` — Container (16K fingerprint) + CogRecord (4KB = meta + content). +- `contract::collapse_gate` — GateDecision, MergeMode. + +**Locked:** +- **Shader IS the driver** (role reversal from thinking-engine-first). +- **MetaWord packing layout** — thinking(6) + awareness(4) + nars_f(8) + nars_c(8) + free_e(6). +- **BindSpace struct-of-arrays** — FingerprintColumns (4 planes × 256 u64), EdgeColumn, QualiaColumn (18 f32), MetaColumn (u32). +- **`ShaderBus::cycle_fingerprint: [u64; 256]`** IS `Container` IS `CrystalFingerprint::Binary16K` (same 2 KB backing). +- **No serde in types** (debug-only); wire formats explicit. + +**Docs:** +- `cognitive-shader-architecture.md` (canonical architecture reference). + +--- + +## How to Use This File + +1. **Opening a session on this workspace:** read the top 3 PRs + (most recent). That covers ~90 % of what you need to know about + current state. +2. **Before proposing a new type:** grep this file for the type + name. If it's listed under Added, stop and read the source. +3. **Before proposing a convention:** grep for the topic. If it's + listed under Locked, your proposal needs explicit justification + to overturn it. +4. **When a PR merges:** prepend a new section at the top of this + file. Old PRs stay — they are the arc. + +This file is the fastest bootstrap available for a new session on +this workspace. Load it, then load 1-2 knowledge docs as the domain +triggers, then start working. Target: 3-5 turn cold start, not 30. diff --git a/CLAUDE.md b/CLAUDE.md index f5d50dc8..ae1e8c29 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,11 +1,31 @@ # CLAUDE.md — lance-graph -> **Updated**: 2026-03-28 +> **Updated**: 2026-04-19 (post PR #210) > **Role**: The obligatory spine — query engine, codec stack, semantic transformer, and orchestration contract > **Status**: 11 crates, 5 in workspace, 4 excluded (standalone), Phases 1-2 DONE, Phase 3 IN PROGRESS --- +## Session Start — MANDATORY READS (in this order) + +A new session on this workspace MUST load these two files before +proposing anything, to avoid the 30-turn rediscovery tax: + +1. **`.claude/knowledge/LATEST_STATE.md`** — current contract + inventory, recently shipped PRs, active branches, queued work, + explicit deferrals. Prevents re-proposing what already exists. +2. **`.claude/knowledge/PR_ARC_INVENTORY.md`** — chronological + decision history. Each PR's Added / Locked / Deferred / Docs + + Confidence annotation. **APPEND-ONLY** — old entries are immutable + historical record; only the Confidence line is updatable. Adding + a new PR prepends; rewriting history is gated via permission. + +After those two, load domain-specific knowledge docs (see +`.claude/knowledge/*.md` index below) only as triggered by the +user's request. + +--- + ## Model Policy (P0 — never violate) **The split that matters: grindwork vs accumulation.** From b896f5bf190d41dff5591baaf01c58c0e66dbae7 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 19 Apr 2026 11:17:16 +0000 Subject: [PATCH 07/18] feat(settings): team-shared governance rules for append-only history MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit .claude/settings.json (committed, team-wide) encodes two rules: 1. ask-before-Edit on PR_ARC_INVENTORY.md and LATEST_STATE.md — any rewrite of architectural history surfaces as a permission prompt. Append-new-PR via Write stays uninterrupted (Write is separately allowed in personal settings.local.json). 2. deny on destructive operations: git force-push / branch-delete / reset --hard, rm -rf, MCP github merge/delete/fork/create-repo. These never should fire without explicit override. Personal preferences (model selection, extensive allow-list for routine operations) stay in gitignored settings.local.json. This file is the minimal shared policy floor. --- .claude/settings.json | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 .claude/settings.json diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 00000000..23e3af34 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,24 @@ +{ + "$schema": "https://json.schemastore.org/claude-code-settings.json", + "permissions": { + "ask": [ + "Edit(.claude/knowledge/PR_ARC_INVENTORY.md)", + "Edit(.claude/knowledge/LATEST_STATE.md)" + ], + "deny": [ + "Bash(git push --force:*)", + "Bash(git push -f:*)", + "Bash(git push --force-with-lease:*)", + "Bash(git branch -D:*)", + "Bash(git branch --delete:*)", + "Bash(git reset --hard:*)", + "Bash(rm -rf:*)", + "Bash(rm -fr:*)", + "mcp__github__merge_pull_request", + "mcp__github__delete_file", + "mcp__github__enable_pr_auto_merge", + "mcp__github__fork_repository", + "mcp__github__create_repository" + ] + } +} From f7792023271be231f1ddc5df9deecb9b7560ee16 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 19 Apr 2026 11:21:44 +0000 Subject: [PATCH 08/18] feat(agents): meta-agent cards, knowledge bootload, handover protocol MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Extends the existing agent ensemble README with three additions answering the user's "30-turn rediscovery" cost: 1. Meta-Agents section — names workspace-primer (first to wake on new session), integration-lead, adk-coordinator, adk-behavior-monitor, and truth-architect (elevated meta) as the coordinators. Each has a one-line scope and when-to-use guidance. Meta-agents run Opus; specialists run Sonnet for grindwork / Opus for accumulation; never Haiku. 2. Session-Start Knowledge Bootload — every subagent loads Tier-0 (LATEST_STATE.md + PR_ARC_INVENTORY.md) unconditionally, then Tier-1 domain docs via the Knowledge Activation trigger table. Knowledge Activation table extended with 9 new rows for the 2026-04-19 grammar / crystal / NARS / coreference / Markov / AriGraph / story-arc / codec / cross-repo-harvest domains. 3. Handover Protocol — .claude/handovers/YYYY-MM-DD-HHMM--to- .md format with required sections (What I did, FINDING, CONJECTURE, What I couldn't do, What you need to know, Open questions). APPEND-ONLY: handovers are immutable. Receiving agent's first action is to read the handover; main thread routes but is not a handover surface itself. CLAUDE.md links to the README from the new A2A Orchestration Two Layers section so a new session finds it naturally. --- .claude/agents/README.md | 147 ++++++++++++++++++++++++++++++++++++++- CLAUDE.md | 94 +++++++++++++++++++++++++ 2 files changed, 238 insertions(+), 3 deletions(-) diff --git a/.claude/agents/README.md b/.claude/agents/README.md index 7a7d0939..62754ffd 100644 --- a/.claude/agents/README.md +++ b/.claude/agents/README.md @@ -92,14 +92,155 @@ the frontier between conjecture and measurement. An insight that hasn't been probed is labeled CONJECTURE. An insight that has been probed and passed is labeled FINDING. The distinction must be visible in the doc. +## Meta-Agents (scopes and when to use) + +Meta-agents coordinate across specialists. They do NOT replace +specialist judgment — they route, prime, and compose. + +| Meta-agent | Scope | +|---|---| +| **`workspace-primer`** | Reads `LATEST_STATE.md` + `PR_ARC_INVENTORY.md`, reports current contract inventory, queued work, active branch. **First thing to wake on any new session.** | +| **`integration-lead`** | Composes specialist outputs into a coherent shipping plan. Use when ≥ 3 specialists have weighed in and their outputs need reconciliation before a PR. | +| **`adk-coordinator`** | Coordinates ADK tooling across crates. Use when orchestration crosses crate boundaries. | +| **`adk-behavior-monitor`** | Watches for drift between spec and implementation on multi-crate PRs. | +| **`truth-architect`** (elevated meta) | Mandatory reviewer on any proposal touching HHTL cascade, γ+φ, or claims-without-probes. | + +Meta-agents run on Opus. Specialists run on Sonnet for single-source +grindwork (draft-file-from-spec); Opus for multi-source accumulation. +Never Haiku. See `../CLAUDE.md § Model Policy`. + +## Session-Start Knowledge Bootload (per agent) + +Every subagent spawned on this workspace loads these in order: + +1. **Tier-0 (MANDATORY, all agents):** + - `.claude/knowledge/LATEST_STATE.md` — current contract inventory, + what's shipped, what's queued, what's explicitly deferred. + - `.claude/knowledge/PR_ARC_INVENTORY.md` — per-PR Added / Locked / + Deferred / Docs / Confidence. APPEND-ONLY. + +2. **Tier-1 (domain-triggered):** load matching docs per the + Knowledge Activation table below. + +3. **Tier-2 (on-demand):** `docs/*.md` loaded when referenced. + +Bootload cost: ~3 Read calls per agent. Fixed-cost insurance against +hallucinating structure that already exists. + +## Knowledge Activation Protocol (updated 2026-04-19) + +Agents do not operate in a vacuum. When woken, an agent MUST read the knowledge +documents listed in its trigger row BEFORE producing output. + +| Trigger | Agent(s) woken | Knowledge loaded first | +|---|---|---| +| Any HHTL cascade proposal | truth-architect + family-codec-smith | bf16-hhtl-terrain.md | +| γ+φ regime discussion | truth-architect | bf16-hhtl-terrain.md | +| φ-spiral / Zeckendorf math | savant-research + truth-architect | zeckendorf-spiral-proof.md, phi-spiral-reconstruction.md | +| Bucketing vs resolution claim | truth-architect | bf16-hhtl-terrain.md | +| Slot D / Slot V layout | container-architect + truth-architect | bf16-hhtl-terrain.md | +| New unification proposal | truth-architect (mandatory review) | bf16-hhtl-terrain.md probe queue | +| Fibonacci mod p traversal | savant-research | savant-research.md (§ golden-step) | +| Which encoding to use? | truth-architect + family-codec-smith | two-basin-routing.md | +| BGZ scope / claims | truth-architect | two-basin-routing.md (§ BGZ must win) | +| Pairwise vs centroid | truth-architect | two-basin-routing.md (§ pairwise rule) | +| Semantic vs distribution | truth-architect | two-basin-routing.md (§ two-basin doctrine) | +| Attribution / blame | truth-architect | two-basin-routing.md (§ attribution discipline) | +| Audio test / carrier+residual | savant-research + truth-architect | two-basin-routing.md (§ audio sanity test) | +| Composing subsystems / integration | truth-architect | frankenstein-checklist.md | +| New abstraction / new struct | truth-architect | frankenstein-checklist.md (§ redundant abstractions) | +| Performance budget question | truth-architect | frankenstein-checklist.md (§ correctness-first) | +| **Grammar / DeepNSM / TEKAMOLO** | integration-lead + truth-architect | grammar-landscape.md, grammar-tiered-routing.md, linguistic-epiphanies-2026-04-19.md | +| **Crystal / CrystalFingerprint / sandwich** | container-architect + family-codec-smith | crystal-quantum-blueprints.md, cross-repo-harvest-2026-04-19.md | +| **NARS inference / thinking styles** | truth-architect + bus-compiler | linguistic-epiphanies-2026-04-19.md (Chomsky isomorphism), integration-plan-grammar-crystal-arigraph.md | +| **Coreference / Markov ±5** | truth-architect + resonance-cartographer | grammar-landscape.md §5 §6, integration-plan-grammar-crystal-arigraph.md | +| **Cross-linguistic bundling** | integration-lead | grammar-landscape.md §4 case inventories, linguistic-epiphanies-2026-04-19.md E22 Rosetta | +| **AriGraph / episodic memory** | ripple-architect + integration-lead | LATEST_STATE.md (§AriGraph Inventory), PR_ARC_INVENTORY.md #208 | +| **Story arc / ONNX emergence** | ripple-architect + contradiction-cartographer | crystal-quantum-blueprints.md (§Quantum mode), endgame-holographic-agi.md | +| **Argmax / codec / PolarQuant** | truth-architect + family-codec-smith | fractal-codec-argmax-regime.md (ORTHOGONAL to grammar work) | +| **Cross-repo harvest** | savant-research | cross-repo-harvest-2026-04-19.md, linguistic-epiphanies-2026-04-19.md | + +**The insight update cycle:** + +``` +1. Agent proposes a claim +2. truth-architect checks: is there a probe for this? Has it run? +3. If NOT RUN → probe is the next deliverable, not more synthesis +4. If RUN + PASS → update .claude/knowledge/ with FINDING (not CONJECTURE) +5. If RUN + FAIL → update .claude/knowledge/ with correction +6. Commit knowledge update: docs(knowledge): probe [ID] — [result] +``` + +This cycle is MANDATORY. + +## Handover Protocol (agent A → agent B) + +When an agent completes work that feeds another agent's scope, the +handover goes through a **handover blackboard entry** — not verbal +chat, not main-thread summary. + +### The handover entry (file under `.claude/handovers/`) + +Path: `.claude/handovers/YYYY-MM-DD-HHMM--to-.md` + +Required sections: + +```markdown +# Handover: → +**Date:** YYYY-MM-DD HH:MM +**Scope:** one sentence — what's being handed off + +## What I did +Short factual list. Files touched, tests run, decisions made. +Include commit SHAs where applicable. + +## What I know (FINDING) +Claims I hold as measured / verified. Include the probe or test +that verifies each. + +## What I suspect (CONJECTURE) +Claims I hold as plausible-but-unverified. The receiving agent +should probe or escalate to truth-architect before building on these. + +## What I couldn't do +Blockers, out-of-scope items, ambiguities I punted on. Explicit. + +## What you need to know +Minimum context transfer. Point at knowledge docs + source files, +do not repeat their content. + +## Open questions +Questions the receiving agent must answer before proceeding. Each +bullet has an expected answer shape (yes/no, number, choice of N). +``` + +### Handover rules + +1. **Every multi-agent workflow writes at least one handover.** + Two-agent chain = 1 handover. N agents = N−1 handovers. +2. **Handovers are APPEND-ONLY.** Same governance as + `PR_ARC_INVENTORY.md` — don't rewrite a previous agent's + handover; append a follow-up if correction is needed. +3. **Receiving agent's FIRST action is to read the handover.** + Then load the knowledge docs it cites. Then start work. +4. **Handovers name their successor.** If agent B needs agent C + next, B's handover to C is its final deliverable. +5. **Main thread is the router, not a handover surface.** Main + orchestrates which agents run; agents write handovers that other + agents consume. Keeps main-thread context small. +6. **`truth-architect` review** is a valid handover target from any + agent before a PR lands. Default final link on HHTL / codec / + claims-without-probes work. + ## Orchestration Primary orchestration prompt: - `.claude/agent2agent-orchestrator-prompt.md` -Core knowledge: -- `.claude/knowledge.md` -- `.claude/ripple-project-readme.mde` +Core knowledge (workspace-wide): +- `.claude/knowledge/LATEST_STATE.md` (Tier-0, mandatory) +- `.claude/knowledge/PR_ARC_INVENTORY.md` (Tier-0, mandatory) +- `.claude/knowledge/*.md` (Tier-1, trigger-activated — see table above) - `docs/integrated-architecture-map.md` ## Rule of use diff --git a/CLAUDE.md b/CLAUDE.md index ae1e8c29..04783514 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -26,6 +26,100 @@ user's request. --- +## Agent-to-Agent (A2A) Orchestration — Two Layers + +Orchestration in this workspace runs at two distinct layers. Each +layer uses a different "blackboard" substrate; both must be respected +when spawning subagents or composing cognitive cycles. + +### Layer 1 — Runtime A2A (code-level, in the contract) + +For cognitive-cycle orchestration *inside* the running system: + +- **`lance_graph_contract::a2a_blackboard`** — `Blackboard` with + `entries: Vec` + `round: u32`. Each entry carries + `expert_id`, `capability`, `result`, `confidence`, `support [u16; 4]`, + `dissonance`, `cost_us`. Experts write; later rounds read prior + entries and build on them. This IS the A2A bus for multi-expert + inference. +- **`lance_graph_contract::orchestration::OrchestrationBridge`** — + trait bridging `StepDomain` (Codec / Thinking / Query / Semantic / + Persistence / Inference / Learning) into `UnifiedStep`. Each domain + contributes a `BridgeSlot`; orchestration routes steps across + domains without duplicating state. +- **`lance_graph_contract::orchestration_mode`** — explicit modes for + how a cycle composes (linear, parallel, blackboard-broadcast, etc.). +- **`ExpertCapability`** enum — the capability taxonomy experts + declare. Do NOT invent new capabilities ad-hoc; grep + `a2a_blackboard.rs` first. +- **Reference doc:** `docs/ORCHESTRATION_IS_GRAPH.md` — capstone + treating orchestration AS graph traversal (the runtime A2A is a + directed blackboard-graph). + +Use Layer 1 when the question is "how do two cognitive experts +compose their outputs at runtime." + +### Layer 2 — Session A2A (Claude-code-level, between subagents) + +For subagent coordination *during* this session: + +- **The mandatory-read files above (`LATEST_STATE.md` + + `PR_ARC_INVENTORY.md`) are the shared blackboard.** Every subagent + I spawn reads them to know the current state, same as a Layer-1 + expert reads prior blackboard entries to know current round state. +- **Knowledge docs in `.claude/knowledge/`** are the extended + blackboard — cross-session persistent entries. Each doc has a + `READ BY:` header declaring which subagent types load it (the + equivalent of `ExpertCapability` matchers). +- **`/root/.claude/plans/*.md`** — plan files authored via `Plan` + agents; session-scoped blackboard for multi-turn work. Other + agents reference the active plan for context. +- **Parallel subagent spawns** in one main-thread turn are the + cheapest Layer-2 A2A pattern. Independent work fans out; results + aggregate back to the main thread, which does the cross-source + synthesis (accumulation → main thread on Opus per policy above). + +Use Layer 2 when the question is "how do I coordinate N subagents +without burning main-thread turns re-reading the same state." + +### Agent ensemble, knowledge bootload, handover protocol + +See **`.claude/agents/README.md`** — it's the meta-card for the 19 +specialist agents + 5 meta-agents in this workspace. It covers: + +- **Meta-agent scopes** (`workspace-primer`, `integration-lead`, + `adk-coordinator`, `adk-behavior-monitor`, `truth-architect`). +- **Session-start knowledge bootload** — every subagent loads Tier-0 + (`LATEST_STATE.md` + `PR_ARC_INVENTORY.md`) unconditionally, then + Tier-1 knowledge docs by trigger table. +- **Knowledge Activation Protocol** — the trigger → agent → doc + mapping (updated 2026-04-19 with grammar / crystal / NARS / + coreference / AriGraph / codec rows). +- **Handover Protocol** — `.claude/handovers/YYYY-MM-DD-HHMM-- + to-.md` files carry What-I-did / FINDING / CONJECTURE / + Blockers / Open-questions. APPEND-ONLY. + +A new session doesn't reinvent the ensemble — it reads this README, +picks the agents whose objects are being touched, and lets them +bootload their own Tier-0 + Tier-1 docs. + +### Rule of thumb + +| Question | Layer | Primary substrate | +|---|---|---| +| "What expert capabilities compose this cycle?" | 1 | `contract::a2a_blackboard::Blackboard` | +| "How do cross-domain steps compose?" | 1 | `OrchestrationBridge` + `UnifiedStep` | +| "What does subagent A need to know before drafting?" | 2 | Mandatory reads + domain knowledge docs | +| "How do I not re-read the same context on every turn?" | 2 | Knowledge doc with `READ BY:` header | +| "How do I coordinate 3 subagents in parallel?" | 2 | Single main-thread turn with parallel `Agent` spawns | + +Layer 1 and Layer 2 do NOT conflict — they operate at different time +scales. A runtime A2A cycle inside a running shader does not involve +Claude subagents; a Claude-session subagent spawn does not write to +the runtime Blackboard. Keep them architecturally distinct. + +--- + ## Model Policy (P0 — never violate) **The split that matters: grindwork vs accumulation.** From 240faae46fdf8cdd4139c0b65b66e229159e7874 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 19 Apr 2026 11:22:25 +0000 Subject: [PATCH 09/18] chore(CLAUDE.md): elevate .claude/agents/README.md to Session Start mandatory read MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Honest amend — A2A orchestration was added reactively, not proactively. Fix: Session Start now mandates reading the agent ensemble README alongside LATEST_STATE and PR_ARC_INVENTORY, so a new session finds the 24-agent ensemble, Knowledge Activation table, and Handover Protocol at turn 0 instead of waiting for a domain trigger. --- CLAUDE.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 04783514..b6bad824 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -8,7 +8,7 @@ ## Session Start — MANDATORY READS (in this order) -A new session on this workspace MUST load these two files before +A new session on this workspace MUST load these three files before proposing anything, to avoid the 30-turn rediscovery tax: 1. **`.claude/knowledge/LATEST_STATE.md`** — current contract @@ -19,10 +19,16 @@ proposing anything, to avoid the 30-turn rediscovery tax: Confidence annotation. **APPEND-ONLY** — old entries are immutable historical record; only the Confidence line is updatable. Adding a new PR prepends; rewriting history is gated via permission. - -After those two, load domain-specific knowledge docs (see -`.claude/knowledge/*.md` index below) only as triggered by the -user's request. +3. **`.claude/agents/README.md`** — the agent ensemble meta-card. + Lists 19 specialist agents + 5 meta-agents (`workspace-primer`, + `integration-lead`, `adk-coordinator`, `adk-behavior-monitor`, + `truth-architect`), the Knowledge Activation trigger table + (what subagent + what docs load for which domain), and the + Handover Protocol spec. **This is the A2A orchestration + specification for this workspace** — see Layer 2 below. + +After these three, load domain-specific knowledge docs only as +triggered by the user's request. --- From 96ec5a9d305b57392e4b14d1a8df5df76018724e Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 19 Apr 2026 11:25:13 +0000 Subject: [PATCH 10/18] =?UTF-8?q?feat(boot):=20rename=20README.md=20?= =?UTF-8?q?=E2=86=92=20BOOT.md,=20add=20.claude/BOOT.md=20as=20session=20e?= =?UTF-8?q?ntry=20point?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README.md is generic and doesn't signal "mandatory session bootload." BOOT.md is explicit: the file you read at session start to avoid the 30-turn rediscovery tax. Changes: 1. .claude/BOOT.md — NEW. One-page session entry point. Names the three mandatory reads (LATEST_STATE + PR_ARC_INVENTORY + .claude/agents/BOOT.md), lists the seven governance rules, summarizes A2A two-layer orchestration, and cross-refs CLAUDE.md for detailed specs. Opens with "If you are a new session on this workspace, read this file first." 2. .claude/agents/README.md → .claude/agents/BOOT.md. Content unchanged; rename via git mv so history follows. Contains the 19-specialist + 5-meta-agent ensemble, Knowledge Activation trigger table, and Handover Protocol. 3. CLAUDE.md §Session Start now points at .claude/BOOT.md as the top-level entry ("start here"), with the three mandatory reads below. All internal references to agents/README.md updated to agents/BOOT.md. The naming convention: BOOT.md = "what to read at session start for this directory/domain." README.md stays conventional for human-readable general project descriptions; BOOT.md is the machine-oriented session bootload spec. --- .claude/BOOT.md | 123 ++++++++++++++++++++++++++ .claude/agents/{README.md => BOOT.md} | 0 CLAUDE.md | 34 +++---- 3 files changed, 140 insertions(+), 17 deletions(-) create mode 100644 .claude/BOOT.md rename .claude/agents/{README.md => BOOT.md} (100%) diff --git a/.claude/BOOT.md b/.claude/BOOT.md new file mode 100644 index 00000000..499a4dcf --- /dev/null +++ b/.claude/BOOT.md @@ -0,0 +1,123 @@ +# BOOT — Session Entry Point for lance-graph + +> **If you are a new session on this workspace, read this file first.** +> It is the one page that tells you everything you need to bootstrap +> before proposing any work. Target cold-start cost: 3–5 turns, not 30. + +--- + +## Read Order (MANDATORY) + +Read these in order before proposing anything: + +1. **`.claude/knowledge/LATEST_STATE.md`** — current contract + inventory, recently shipped PRs, active branches, queued work, + explicit deferrals. Tells you **what exists**. +2. **`.claude/knowledge/PR_ARC_INVENTORY.md`** — per-PR Added / + Locked / Deferred / Docs / Confidence, reverse-chronological. + APPEND-ONLY (only Confidence is mutable; corrections append as + new dated lines; reversals get their own PR entry). Tells you + **why it exists**. +3. **`.claude/agents/BOOT.md`** — the 19-specialist + 5-meta-agent + ensemble, the Knowledge Activation trigger table (domain → + agent → required knowledge docs), the Handover Protocol spec. + Tells you **how to coordinate**. + +These three files give you ~90 % of the context you need to avoid +re-proposing what's shipped or violating a locked convention. + +--- + +## The Governance Rules (never violate) + +1. **Append-only architectural history.** `PR_ARC_INVENTORY.md` and + `LATEST_STATE.md` are governed by the append-only rule — Edit + prompts for explicit approval, Write for appends is allowed. + Old PR entries are immutable historical record; only the + Confidence line per entry is updatable. +2. **Model policy.** Main thread on Opus with deep thinking. + Subagents: Sonnet for grindwork (single-source mechanical), + Opus for accumulation (multi-source synthesis). **Never Haiku**, + regardless of task. Full spec in CLAUDE.md §Model Policy. +3. **GitHub access.** Zipball to `/tmp/sources/` + local grep for + 3+ reads per external repo. MCP github only for writes (PR, + comments, reviews) and single-path reads. Full spec in + CLAUDE.md §GitHub Access Policy. +4. **Contract zero-dep invariant.** `lance-graph-contract` has no + external crate deps. Do not add any. +5. **Read before Write.** Always Read a file before overwriting. + Write-over-self without Read is the documented failure mode; + see CLAUDE.md §In-Session Orchestration Discipline. +6. **No JSON serialization in types.** Serde stays debug-only; wire + formats are explicit. +7. **Pumpkin framing** for externally-visible examples (clinical / + game-AI disguise for the AGI primitives). + +--- + +## A2A Orchestration — Two Layers + +Orchestration on this workspace runs at two distinct layers: + +- **Layer 1 — Runtime A2A:** `lance_graph_contract::a2a_blackboard` + `Blackboard` + `BlackboardEntry` (experts write, later rounds + read), `OrchestrationBridge` + `StepDomain` + `UnifiedStep`, + `orchestration_mode` for composition modes. For + cognitive-cycle composition inside the running system. +- **Layer 2 — Session A2A:** The mandatory-read files above are + the shared blackboard across subagents. `.claude/knowledge/*.md` + are extended blackboard entries. `.claude/handovers/*.md` + (created per agent chain) carry per-handover state. Parallel + `Agent` spawns in one main-thread turn are the cheapest + coordination pattern. + +Full description: CLAUDE.md §Agent-to-Agent (A2A) Orchestration. +Detailed agent ensemble + trigger table + handover protocol: +`.claude/agents/BOOT.md`. + +--- + +## The 30-Turn Rediscovery Tax (why this file exists) + +Without this BOOT.md, a new session would typically: + +1. Not know the current contract — propose duplicate types. +2. Not know recently locked conventions — violate them, get + reverted, propose again. +3. Not know queued work — suggest things already in the plan. +4. Not know the agent ensemble — re-invent subagent coordination. +5. Re-read the same large knowledge docs multiple times because + nothing tells it which docs matter for which work. + +Cumulative cost: 20–30 turns of main-thread context before the +session is productive. That's ~$20–40 in Opus charges per fresh +session, most of which is wasted rediscovery. + +Reading the three mandatory files above reduces this to ~3–5 turns. +The entire BOOT spec (this file) is ~2 KB. The three mandatory +reads total ~15 KB. Compared to 20–30 wasted turns, the bootload +is a 5–10× cost reduction on every session start. + +--- + +## Fallback — CLAUDE.md is the source of truth for everything else + +If this file doesn't answer your question, CLAUDE.md does. Tables +of contents: + +- CLAUDE.md §Session Start — mandatory reads (same three as above) +- CLAUDE.md §A2A Orchestration — both layers in detail +- CLAUDE.md §Model Policy — grindwork vs accumulation, never Haiku +- CLAUDE.md §GitHub Access Policy — zipball for reads +- CLAUDE.md §Workspace Structure — 11-crate layout +- CLAUDE.md §Knowledge Base — all `.claude/knowledge/` files +- CLAUDE.md §Knowledge Activation (MANDATORY) — agent protocol +- CLAUDE.md §In-Session Orchestration Discipline — Read before Write + +--- + +## One sentence + +**Read `LATEST_STATE.md`, `PR_ARC_INVENTORY.md`, and +`.claude/agents/BOOT.md` before proposing anything, then the +trigger-table domain doc, then start work.** diff --git a/.claude/agents/README.md b/.claude/agents/BOOT.md similarity index 100% rename from .claude/agents/README.md rename to .claude/agents/BOOT.md diff --git a/CLAUDE.md b/CLAUDE.md index b6bad824..5232dd2b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -8,24 +8,24 @@ ## Session Start — MANDATORY READS (in this order) -A new session on this workspace MUST load these three files before -proposing anything, to avoid the 30-turn rediscovery tax: +**Start here:** `.claude/BOOT.md` — the one-page session entry point. +It names the three files below as mandatory reads, so load them +whether you went through BOOT.md or landed here directly. 1. **`.claude/knowledge/LATEST_STATE.md`** — current contract inventory, recently shipped PRs, active branches, queued work, - explicit deferrals. Prevents re-proposing what already exists. -2. **`.claude/knowledge/PR_ARC_INVENTORY.md`** — chronological - decision history. Each PR's Added / Locked / Deferred / Docs + - Confidence annotation. **APPEND-ONLY** — old entries are immutable - historical record; only the Confidence line is updatable. Adding - a new PR prepends; rewriting history is gated via permission. -3. **`.claude/agents/README.md`** — the agent ensemble meta-card. - Lists 19 specialist agents + 5 meta-agents (`workspace-primer`, - `integration-lead`, `adk-coordinator`, `adk-behavior-monitor`, - `truth-architect`), the Knowledge Activation trigger table - (what subagent + what docs load for which domain), and the - Handover Protocol spec. **This is the A2A orchestration - specification for this workspace** — see Layer 2 below. + explicit deferrals. **What exists.** +2. **`.claude/knowledge/PR_ARC_INVENTORY.md`** — per-PR Added / + Locked / Deferred / Docs / Confidence, reverse chronological. + **APPEND-ONLY**; only the Confidence line is updatable; + corrections append as new dated lines; reversals get their own + PR entry. **Why it exists.** +3. **`.claude/agents/BOOT.md`** — the 19 specialist + 5 meta-agent + ensemble (`workspace-primer`, `integration-lead`, + `adk-coordinator`, `adk-behavior-monitor`, `truth-architect`), + the Knowledge Activation trigger table (domain → agent → docs), + and the Handover Protocol spec. **This is the A2A orchestration + specification for this workspace.** **How to coordinate.** After these three, load domain-specific knowledge docs only as triggered by the user's request. @@ -90,7 +90,7 @@ without burning main-thread turns re-reading the same state." ### Agent ensemble, knowledge bootload, handover protocol -See **`.claude/agents/README.md`** — it's the meta-card for the 19 +See **`.claude/agents/BOOT.md`** — it's the meta-card for the 19 specialist agents + 5 meta-agents in this workspace. It covers: - **Meta-agent scopes** (`workspace-primer`, `integration-lead`, @@ -513,7 +513,7 @@ their synergies, and their FINDING/CONJECTURE status. Never guess architecture. Every `.claude/knowledge/` document has a `READ BY:` header listing which agents MUST load it before producing output in that domain. When a knowledge trigger fires -(see `.claude/agents/README.md § Knowledge Activation Protocol`), the relevant +(see `.claude/agents/BOOT.md § Knowledge Activation Protocol`), the relevant knowledge docs are loaded BEFORE the agent responds. **Critical process rule:** `.claude/knowledge/bf16-hhtl-terrain.md` contains a From b4410358ab0e7234bee19e031647ee09281125ce Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 19 Apr 2026 11:35:30 +0000 Subject: [PATCH 11/18] =?UTF-8?q?feat(skill):=20cca2a=20=E2=80=94=20explan?= =?UTF-8?q?ation-only=20skill=20for=20the=20A2A=20pattern?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Not a scaffolder. Just documentation so future sessions can grok the pattern in one read instead of forcing the user to re-derive it for 30 turns. Files: - SKILL.md — YAML frontmatter (<1024 char description) + lean overview pointing at canonical workspace files. - concepts.md — two A2A layers (runtime a2a_blackboard vs session knowledge docs), governance rules (append-only, model policy, GitHub access). - divergence.md — audit of what's aligned with official Claude Code conventions, what's extended, what's recommended for adoption. Canonical files (BOOT.md, LATEST_STATE.md, PR_ARC_INVENTORY.md, agents/BOOT.md, agents/README.md, settings.json) stay at their normal workspace paths. The skill references them rather than maintaining template copies. --- .claude/skills/cca2a/SKILL.md | 46 +++++++++++++ .claude/skills/cca2a/concepts.md | 105 +++++++++++++++++++++++++++++ .claude/skills/cca2a/divergence.md | 99 +++++++++++++++++++++++++++ 3 files changed, 250 insertions(+) create mode 100644 .claude/skills/cca2a/SKILL.md create mode 100644 .claude/skills/cca2a/concepts.md create mode 100644 .claude/skills/cca2a/divergence.md diff --git a/.claude/skills/cca2a/SKILL.md b/.claude/skills/cca2a/SKILL.md new file mode 100644 index 00000000..1e4cdcb1 --- /dev/null +++ b/.claude/skills/cca2a/SKILL.md @@ -0,0 +1,46 @@ +--- +name: cca2a +description: > + Explains the Claude Code Agent-to-Agent (CCA2A) pattern used in + this workspace: BOOT.md session entry, agent ensemble with + meta-agents, append-only knowledge state (LATEST_STATE + + PR_ARC_INVENTORY), handover protocol, governance permissions. + Read this once to understand the pattern; then stop re-explaining + it across sessions. Canonical files live at their normal + workspace paths, not in this skill. +--- + +# CCA2A — Claude Code Agent-to-Agent + +Explanation-only skill. Documents the pattern so a new session can +grok it once instead of the user re-deriving it for 30 turns. + +**Canonical files** (read these, not template copies): + +- `.claude/BOOT.md` — session entry point. +- `.claude/knowledge/LATEST_STATE.md` — current contract inventory. +- `.claude/knowledge/PR_ARC_INVENTORY.md` — APPEND-ONLY decision arc. +- `.claude/agents/BOOT.md` — agent ensemble + Knowledge Activation + + Handover Protocol. +- `.claude/agents/README.md` — function inventory of all agents. +- `.claude/settings.json` — team-shared governance permissions. +- `CLAUDE.md` — workspace spec, links to all of the above. + +## What to read when + +- **New session on this workspace:** `.claude/BOOT.md` first, then + the three mandatory reads it lists. +- **Understanding the A2A two-layer model:** + [concepts.md](concepts.md). +- **Comparing to official Claude Code conventions:** + [divergence.md](divergence.md). + +## The idea in one paragraph + +Every new session pays a 30-turn rediscovery tax rebuilding context +about what types exist, which conventions are locked, what work is +queued. CCA2A is the scaffold that cuts that to 3-5 turns: two +mandatory knowledge files that state current inventory and decision +history, one agent ensemble file that routes subagents, one hook +that injects critical state after compaction. Append-only +governance on the history files so drift can't erode the arc. diff --git a/.claude/skills/cca2a/concepts.md b/.claude/skills/cca2a/concepts.md new file mode 100644 index 00000000..aeb2c760 --- /dev/null +++ b/.claude/skills/cca2a/concepts.md @@ -0,0 +1,105 @@ +# CCA2A — Concepts + +## The Problem + +A new Claude Code session on a non-trivial workspace burns 20-30 +turns rediscovering: +- What types / modules already exist (re-proposes duplicates). +- What conventions have been locked (violates them, gets reverted). +- What work is already queued (proposes things in the plan). +- How to coordinate subagents (re-invents the wheel). + +At ~$15-$75 per 1M tokens of Opus, that's **$20-$40 of waste per +cold start.** CCA2A is the scaffolding that reduces this to 3-5 +turns. + +## Two A2A Layers + +### Layer 1 — Runtime A2A (code-level inside the system) + +If the workspace is building a cognitive system, its runtime +orchestration needs a blackboard where experts write entries and +later rounds read them. Typical structure: + +```rust +struct Blackboard { + entries: Vec, + round: u32, +} + +struct BlackboardEntry { + expert_id: ExpertId, + capability: ExpertCapability, + result: u16, + confidence: f32, + support: [u16; 4], + dissonance: f32, + cost_us: u32, +} +``` + +This is the A2A bus for multi-expert inference inside the system. +Name it consistently; reference from BOOT.md. + +### Layer 2 — Session A2A (Claude Code subagent coordination) + +For subagent coordination *during a Claude session*: +- The two mandatory knowledge files (LATEST_STATE + + PR_ARC_INVENTORY) are the shared blackboard. +- Domain-specific knowledge docs are extended blackboard entries + (load-on-trigger via Knowledge Activation table). +- Handover files (`.claude/handovers/*.md`) carry per-chain state + transfer. +- Parallel subagent spawns in one main-thread turn is the cheapest + coordination pattern. + +Layers 1 and 2 don't conflict — they operate at different time +scales. Don't entangle them. + +## Governance Rules + +### Append-only history + +`PR_ARC_INVENTORY.md` and `LATEST_STATE.md` are immutable historical +record except for one mutable field per entry: `Confidence`. +Corrections append as `**Correction (YYYY-MM-DD from PR #N):**` +lines. Reversals get their own new PR entry; both remain in the arc. + +Enforced via `.claude/settings.json::permissions.ask` on +`Edit(.claude/knowledge/PR_ARC_INVENTORY.md)` and +`Edit(.claude/knowledge/LATEST_STATE.md)` — surfaces as approval +prompt. Write for appends stays unprompted. + +### Model policy + +- Main thread: Opus, deep thinking, full `effortLevel: high`. +- Subagent grindwork (single-source mechanical): Sonnet. +- Subagent accumulation (multi-source synthesis): Opus. +- NEVER Haiku — quality floor for this pattern is Sonnet. + +Concrete test before spawning a subagent: +> "Does this agent have to read N sources and produce something that +> only makes sense when those sources are held in mind together?" +> +> Yes → Opus. No → Sonnet. + +### GitHub access + +- Reads (3+ files from same repo): zipball to `/tmp/sources/` + + local grep. Each `mcp__github__get_file_contents` call drops the + full file into session context and re-bills on every subsequent + turn. Zipball-then-grep is ~20x cheaper. +- Reads (single targeted file, known path): MCP is fine. +- Writes (PR creation, comments, reviews, review threads): MCP. + +### Destructive ops denied globally + +`.claude/settings.json::permissions.deny` blocks: `git push --force`, +`git push -f`, `git branch -D`, `git reset --hard`, `rm -rf`, +MCP `merge_pull_request`, `delete_file`, `fork_repository`, +`create_repository`, `enable_pr_auto_merge`. + +## Why This Is Different From Official Claude Code Docs + +See [divergence.md](divergence.md) for what's official, what's +invented, and what's recommended for adoption. diff --git a/.claude/skills/cca2a/divergence.md b/.claude/skills/cca2a/divergence.md new file mode 100644 index 00000000..a5de7d84 --- /dev/null +++ b/.claude/skills/cca2a/divergence.md @@ -0,0 +1,99 @@ +# CCA2A — Divergence from Official Claude Code + +Audit of what CCA2A does vs what official Anthropic Claude Code +conventions prescribe. Per the 2026-04-19 audit of +`docs.claude.com/en/docs/claude-code/`. + +## Aligned with official + +| Area | Convention | +|---|---| +| Agent cards location | `.claude/agents/.md` with YAML frontmatter | +| Frontmatter fields | `name`, `description`, `tools`, `model` | +| Settings files | `.claude/settings.json` (project, committed) + `.claude/settings.local.json` (local, gitignored) | +| Model values | `sonnet`, `opus` (CCA2A excludes `haiku` by policy) | +| CLAUDE.md location | Project root or `.claude/CLAUDE.md` | +| Permissions arrays | `permissions.ask`, `permissions.allow`, `permissions.deny` | +| Hook events | `SessionStart`, `PostCompact`, etc. all official | + +## Extensions (invented by CCA2A, not in official docs) + +| Feature | What it adds | Why | +|---|---|---| +| `.claude/BOOT.md` | Single page entry point referenced from CLAUDE.md | Explicit bootstrap contract; official doesn't have this concept | +| `.claude/knowledge/LATEST_STATE.md` | Current-state snapshot, updated after every PR | Prevents re-proposing shipped work | +| `.claude/knowledge/PR_ARC_INVENTORY.md` | APPEND-ONLY decision history per PR | Locks architectural history against rewrite-drift | +| `.claude/handovers/*.md` | Agent-to-agent state transfer files | Official has subagents but no multi-step chain handover protocol | +| Knowledge Activation trigger table | Domain → agent → knowledge docs mapping | Extends `READ BY:` headers into an orchestration table | +| Grindwork vs accumulation model split | Per-task model selection rule | Official allows `model: sonnet` but doesn't codify the grindwork/accumulation split | +| Zipball-for-reads policy | Use curl zipball + local grep for 3+ cross-repo reads | Official doesn't cover cross-repo read cost optimization | + +These extensions do not conflict with official conventions. They +layer on top as workspace-specific conventions. A Claude Code +session without CCA2A installed still works with official +conventions; CCA2A just accelerates cold-start. + +## Recommended adoptions from official (future work) + +### 1. `.claude/rules/` with `paths:` frontmatter + +Official path-scoped knowledge loading. CCA2A's READ BY headers +pattern could be replaced or complemented by: + +```markdown +--- +paths: ["src/billing/**"] +--- +Load this rule when Claude works in src/billing/. +``` + +Deterministic (directory match) vs pattern-matched intent. Consider +migrating domain-specific knowledge docs into `.claude/rules/` +with path scopes where the mapping is literal. + +### 2. `SessionStart` hook with `matcher: startup` + +CCA2A already includes this. Official doc recommends it for +session-start context injection. Covered by the install. + +### 3. `PostCompact` hook + +CCA2A includes this. Critical — compaction otherwise drops the +workspace bootload, and the next turn rediscovers. Official doc +recommends this for compaction-resilient sessions. + +### 4. `Skill` fork + `agent:` field + +Skills can fork into named subagents via `agent: Explore` or similar +for read-only isolation. CCA2A doesn't use this yet; could be added +for pure-search skill variants (e.g. a read-only CCA2A audit skill +that reports divergence without installing). + +### 5. Auto memory + +`~/.claude/projects//memory/MEMORY.md` — Claude writes +automatically. CCA2A's LATEST_STATE.md is the curated alternative; +auto memory could be an unstructured addition for personal notes. + +## Drift to avoid + +- **Invented frontmatter fields.** Stick to the official schema for + `.claude/agents/*.md` frontmatter. Don't add workspace-specific + fields; put conventions in the prose body instead. +- **Custom hook JSON shapes.** Return only the fields official docs + support (`hookSpecificOutput.additionalContext`, + `hookSpecificOutput.hookEventName`, etc.). +- **Skill max frontmatter size.** 1024 chars. Keep `description` + short; offload detail to subpages referenced by the skill. + +## Compatibility + +CCA2A installs work alongside any existing `.claude/` setup: +- Doesn't replace existing agent cards. +- Doesn't clobber existing `settings.json` rules (merges). +- Doesn't overwrite existing CLAUDE.md (prepends a new section if + absent, skips if a Session Start section already exists). + +A workspace can adopt CCA2A partially: install only the knowledge +docs + governance rules without the handover protocol, or add +handovers later without reinstalling anything. From 3c500f0a2749df41861ed38fe7f1dfb8a6beb100 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 19 Apr 2026 11:36:13 +0000 Subject: [PATCH 12/18] feat(agents+skill): function-catalog README + CLAUDE.md link to cca2a skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two threads: 1. .claude/agents/README.md — function-catalog separation from BOOT.md. BOOT.md is the session-start orchestration spec (mandatory reads, Knowledge Activation triggers, Handover Protocol). README.md is the reference catalog of all 19 specialists + 5 meta-agents with one-paragraph function / scope / when-to-use per agent, grouped by concern (Meta, Codec, Architecture, Cognitive Structure, Perspective, Memory/Trajectory), plus a decision-flow section. 2. CLAUDE.md §Session Start now links .claude/skills/cca2a/SKILL.md explicitly as the "pattern explained" alternative to the three mandatory reads. Read the skill once to grok the A2A two-layer model, governance rules, and divergence audit; read the three canonical files when you need specifics. --- .claude/agents/README.md | 214 +++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 6 ++ 2 files changed, 220 insertions(+) create mode 100644 .claude/agents/README.md diff --git a/.claude/agents/README.md b/.claude/agents/README.md new file mode 100644 index 00000000..83f34b34 --- /dev/null +++ b/.claude/agents/README.md @@ -0,0 +1,214 @@ +# Agent Ensemble — Function Inventory + +> **Reference catalog.** Every agent on this workspace, grouped by +> concern, with one-paragraph function + scope + when-to-use. +> +> **Session-start spec** lives in `BOOT.md` (mandatory reads, +> Knowledge Activation triggers, Handover Protocol). Read BOOT.md +> when starting a session; read this file when deciding which +> specialist to wake for a specific task. + +Ensemble size: **19 specialists + 5 meta-agents**. Every card is at +`.claude/agents/.md`. Each card declares its own +`tools`, `model`, and `READ BY:` knowledge prerequisites. + +--- + +## Meta-Agents (orchestration, priming, review) + +Agents that coordinate other agents. All run on Opus. + +### `workspace-primer` +Onboarding agent for any new session that touches lance-graph, +ndarray, or related AdaWorldAPI crates. Distills ~20 canonical rules +and corrections from prior sessions so the next session starts +oriented instead of re-deriving them. +**Wake first** on any new session before proposing architecture. + +### `adk-coordinator` +Agent Development Kit style ensemble coordinator. Frames a problem +that needs multiple specialists, selects the **minimal** agent set, +requires object-level outputs, detects flattening between layers, +produces a consolidated verdict that names productive disagreements. +**Use when** a problem needs 3+ specialists and you need to avoid +noise / overlapping scopes / synthesis loops. + +### `adk-behavior-monitor` +Watches for behavioral anti-patterns during R&D sessions. Fires on: +premature commitment to untested projections, centroid-residual +framing on near-orthogonal data, "225/225 feels like success" +confirmation bias, new codec built when existing one hasn't been +measured, Python inference in a Rust-native pipeline, chained-score +multiplication without chain-collapse validation. **Flags and +redirects, does not block.** + +### `integration-lead` +Cross-session orchestration. Knows what's done, what's pending, what's +outdated across lance-graph and ndarray. Tracks dependencies and +phase gates. **Use when** planning work order, checking +prerequisites, or deciding which session to execute next. + +### `truth-architect` +Guards measurement-before-synthesis discipline and architectural +ground truth. Detects synthesis-to-measurement ratios worse than +1:0. Enforces probe-first protocol. Carries the BF16-HHTL correction +chain terrain. **Mandatory reviewer** when any proposal adds layers +without numbers, γ+φ placement is discussed, HHTL cascade is +touched, or any unification is proposed without a falsifying probe. + +--- + +## Codec / Compression + +### `palette-engineer` +bgz17 crate: palette compression, Base17 encoding, 256×256 distance +matrices, compose tables, PaletteSemiring, PaletteMatrix, PaletteCsr, +SIMD batch distance (AVX-512 / AVX2 / scalar). +**Use for** work in `crates/bgz17/`, palette optimizations, HHTL +layer-1 operations. + +### `family-codec-smith` +Shapes HEEL / HIP / BRANCH / TWIG / LEAF representation choices, +role-aware codebooks, palettes, residuals, family purity benchmarks. +**Use when** deciding how NOT to blur unlike functions into one +codec too early. + +### `savant-research` +ZeckBF17 compression, golden-step traversal, octave encoding, +distance metric design for the codec-research crate. Covers +zeckbf17.rs, accumulator crystallization, Diamond Markov invariant, +HHTL integration, cross-crate alignment with production neighborhood. +**Use for** codec-research work and compression fidelity / rank +correlation claims. + +--- + +## Architecture / Layout + +### `container-architect` +256-word metadata container layout, word-by-word field mapping, +bgz17 annex at W112–125, local palette CSR at W96–111, +scent/palette neighbor indices at W176–191 (WIDE), cascade stride-16 +sampling, checksum coverage. Guards the boundary between container +(structured) and planes (flat). +**Use for** any work touching container fields, Lance schemas +(`columnar.rs`, `storage.rs`), or container read/write paths. + +### `ripple-architect` +Ontology guardian for the ripple architecture. Keeps anatomy, field, +sweep, bus, and thought object distinct. **Use when** shaping +system-wide architecture, naming layers, proposing DTOs, or +preventing premature flattening of unlike functions. + +### `certification-officer` +Runs numerical certification of a derived format (lab BF16, Base17, +bgz-hhtl-d palette, compressed codebook) against a ground-truth +source file, reporting Pearson r, Spearman ρ, and Cronbach α to 4 +decimal places. Always reads real source bytes via `mmap`; samples +deterministically via SplitMix64 seed `0x9E3779B97F4A7C15`; scans for +NaN at every pipeline stage. **Refuses synthetic test inputs.** +**Use when** the task is "prove format X preserves properties of +format Y within target T." + +--- + +## Cognitive Structure + +### `resonance-cartographer` +Maps superpositional field state, candidate families, pressure, +contradiction, drift, and style mix **before** collapse. +**Use for** work on `ResonanceDto`, searchable fields, CLAM / HHTL +substrate, and sweep logic. + +### `bus-compiler` +Compiles explicit thought into accountable bus packets for `p64` +and CognitiveShader. **Use when** defining `BusDto`, mapping style +into bus knobs, or proving structure-first execution beats text- +first routing. + +### `contradiction-cartographer` +Protects contradiction as first-class structure across family, +branch, bus, and thought-object layers. **Use when** designing +signed residuals, branch encodings, support-vs-contra pressure, or +conflict-aware revision. + +### `thought-struct-scribe` +Shapes durable thought objects, blackboard semantics, revision +rules, and host-model glove interfaces. **Use when** defining +`ThoughtStruct`, blackboard persistence, provenance, or +metacognitive observation. + +--- + +## Perspective / Interaction + +### `host-glove-designer` +Designs the structured interface from explicit thought objects into +the host model. **Use for** prompt-side guidance, side-channel +payloads, adapter-like conditioning, and minimal glove experiments. + +### `perspective-weaver` +Models user, agent, topic, and angle as intertwined perspective +objects. **Use for** persona modeling, shared gestalt, angle masks, +perspective mismatch, and synthesis across multiple viewpoints. + +### `mirror-kernel-synthesist` +Explores semantic-kernel mediation, mirror-style perspective +modeling, hypothesis loops, and synthesis policies across +user-agent-topic frames. **Use when** designing compact mediation +layers between resonance, traversal, and response formation. + +--- + +## Memory / Trajectory + +### `trajectory-cartographer` +Models episodic memory, causal arcs, graph revision chains, and +spine trajectories over time. **Use for** AriGraph / episodic +integration, causal path persistence, stabilization, and +revision-aware memory design. + +--- + +## How to pick the right agent + +Decision flow: + +1. **Session just started?** → `workspace-primer` first. +2. **Problem needs 3+ specialists?** → `adk-coordinator` to frame. +3. **Proposal adds a layer or makes claims without measurement?** → + `truth-architect` is the mandatory reviewer; loop it in early. +4. **Otherwise** pick the specialist by what the work touches: + - Container words, Lance schemas → `container-architect`. + - HHTL / Base17 / palette distance → `palette-engineer`. + - Cascade family choice → `family-codec-smith`. + - Ontology drift / premature flattening → `ripple-architect`. + - Numerical certification → `certification-officer`. + - AriGraph / episodic → `trajectory-cartographer`. + - ResonanceDto / CLAM / sweep → `resonance-cartographer`. + - BusDto / p64 / CognitiveShader → `bus-compiler`. + - Contradiction handling → `contradiction-cartographer`. + - ThoughtStruct / blackboard persistence → `thought-struct-scribe`. + - Host-model glove / prompt-side → `host-glove-designer`. + - Persona / user / topic / angle → `perspective-weaver`. + - Kernel mediation / hypothesis loops → `mirror-kernel-synthesist`. + - codec-research / ZeckBF17 / golden-step → `savant-research`. + - Drift / anti-pattern check → `adk-behavior-monitor`. +5. **Before PR merge** on any HHTL / codec / claims work → + `truth-architect` review is the final link. + +The minimal agent set principle: **a crowded room is not +automatically a wiser room.** Only wake the agents whose objects +are actually being touched. + +## Cross-reference + +- **`BOOT.md`** (sibling) — session-start spec, Knowledge Activation + trigger table, Handover Protocol. +- **`../BOOT.md`** (top-level) — the one-page session entry point. +- **`../../CLAUDE.md` § Agent-to-Agent (A2A) Orchestration** — the + two-layer model (runtime A2A via `contract::a2a_blackboard` vs + session A2A via knowledge docs + handovers). +- **`../knowledge/LATEST_STATE.md`** — current contract inventory + (what every specialist's domain looks like right now). +- **`../knowledge/PR_ARC_INVENTORY.md`** — decision history per PR. diff --git a/CLAUDE.md b/CLAUDE.md index 5232dd2b..acfa3128 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -30,6 +30,12 @@ whether you went through BOOT.md or landed here directly. After these three, load domain-specific knowledge docs only as triggered by the user's request. +**If you want the pattern explained rather than the specifics:** +see **`.claude/skills/cca2a/SKILL.md`** — explanation-only skill +covering the A2A two-layer model, governance rules, and how this +workspace's conventions diverge from official Claude Code docs. +Read once to grok; then stop re-deriving across sessions. + --- ## Agent-to-Agent (A2A) Orchestration — Two Layers From 1b6ce71fcf7c2408d040d232bfbd17936e8423a7 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 19 Apr 2026 11:39:12 +0000 Subject: [PATCH 13/18] feat(hooks): SessionStart + PostCompact inject bootload context MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two shell hooks that emit valid JSON with hookSpecificOutput. additionalContext — Claude consumes the context as a system reminder at turn 0 (SessionStart) and after compaction (PostCompact). .claude/hooks/session-start.sh (1779 chars of context): - Lists the three mandatory reads (LATEST_STATE, PR_ARC_INVENTORY, agents/BOOT). - Restates governance rules (append-only, model policy, GitHub access, zero-dep contract invariant, read-before-write). - Names the A2A two-layer model. - Points at CCA2A skill for the pattern overview. .claude/hooks/post-compact.sh (849 chars of context): - Tells Claude to re-read LATEST_STATE + top 3 PR entries. - Conditionally load agents/BOOT.md and .claude/handovers/ if work-in-progress state. - Warns to re-grep LATEST_STATE before proposing types that may have existed before compaction dropped awareness. .claude/settings.json: hooks section wires both scripts. SessionStart matcher: "startup" PostCompact matcher: "" (catch-all) .claude/skills/cca2a/divergence.md: audit note 5 documents permissions.ask as intentional (surfaces edit attempt without blocking) vs allow (silent permit) vs deny (hard block). The allow / ask / deny split is why Edit triggers the prompt while Write (used for appending new PR entries) stays unprompted. Addresses audit recommendations 3 (PostCompact hook) and 5 (permissions.ask verification). --- .claude/hooks/post-compact.sh | 17 +++++++++++++++ .claude/hooks/session-start.sh | 17 +++++++++++++++ .claude/settings.json | 24 ++++++++++++++++++++++ .claude/skills/cca2a/divergence.md | 33 ++++++++++++++++++++++++++++++ 4 files changed, 91 insertions(+) create mode 100755 .claude/hooks/post-compact.sh create mode 100755 .claude/hooks/session-start.sh diff --git a/.claude/hooks/post-compact.sh b/.claude/hooks/post-compact.sh new file mode 100755 index 00000000..02a601bc --- /dev/null +++ b/.claude/hooks/post-compact.sh @@ -0,0 +1,17 @@ +#!/usr/bin/env bash +# PostCompact hook — re-inject critical state after context compaction +# drops the workspace bootload. Without this, the post-compact model +# turn rediscovers what existed before compaction at full cost. +# +# Wired from: .claude/settings.json +# Documented by: .claude/skills/cca2a/SKILL.md +set -euo pipefail + +cat <<'JSON' +{ + "hookSpecificOutput": { + "hookEventName": "PostCompact", + "additionalContext": "POST-COMPACT RE-INJECT (lance-graph, via cca2a pattern):\n\nCompaction just dropped prior context. Re-read mandatory state BEFORE answering the next turn:\n\n1. .claude/knowledge/LATEST_STATE.md — current contract inventory.\n2. .claude/knowledge/PR_ARC_INVENTORY.md — top 3 PR entries (reverse chronological).\n3. .claude/agents/BOOT.md — if this session was doing agent orchestration.\n4. .claude/handovers/ — if a chain was in progress, read the most recent handover file.\n\nDo NOT propose new types without re-grepping LATEST_STATE — compaction may have dropped your awareness that the type already exists.\n\nActive branch and current work-in-progress state should be discoverable via git status + the handover (if any). If no handover exists but work was clearly in progress, ask the user to clarify before resuming." + } +} +JSON diff --git a/.claude/hooks/session-start.sh b/.claude/hooks/session-start.sh new file mode 100755 index 00000000..f962f6d5 --- /dev/null +++ b/.claude/hooks/session-start.sh @@ -0,0 +1,17 @@ +#!/usr/bin/env bash +# SessionStart hook — inject workspace bootload context at turn 0. +# Emits JSON on stdout; Claude consumes hookSpecificOutput.additionalContext +# as a system reminder in the first model turn. +# +# Wired from: .claude/settings.json +# Documented by: .claude/skills/cca2a/SKILL.md +set -euo pipefail + +cat <<'JSON' +{ + "hookSpecificOutput": { + "hookEventName": "SessionStart", + "additionalContext": "WORKSPACE BOOTLOAD (lance-graph, via cca2a pattern):\n\n## Mandatory reads this session (in order)\n\n1. .claude/knowledge/LATEST_STATE.md — current contract inventory, recently shipped PRs, queued work, explicit deferrals. What exists.\n2. .claude/knowledge/PR_ARC_INVENTORY.md — APPEND-ONLY decision history per PR (Added / Locked / Deferred / Docs + mutable Confidence line). Why it exists.\n3. .claude/agents/BOOT.md — 19 specialist + 5 meta-agent ensemble, Knowledge Activation trigger table, Handover Protocol. How to coordinate.\n\nDo NOT propose any new type, module, or convention without grepping LATEST_STATE first.\n\n## Governance (never violate)\n\n- APPEND-ONLY: LATEST_STATE + PR_ARC_INVENTORY Edit prompts for approval; Write to append stays unprompted. Only the Confidence line per PR entry is updatable; corrections append as dated lines; reversals get their own PR entry.\n- Model policy: main thread Opus + deep thinking; subagent grindwork (single-source mechanical) → Sonnet; accumulation (multi-source synthesis) → Opus; NEVER Haiku.\n- GitHub reads: zipball to /tmp/sources/ + local grep for 3+ reads per external repo. MCP only for writes (PR, comments, reviews) and single-path reads.\n- Contract zero-dep invariant: lance-graph-contract has no external crate deps.\n- Read before Write: always Read a file before overwriting.\n- No JSON serialization in runtime types (serde is debug-only).\n\n## A2A two layers\n\n- Layer 1 (runtime): contract::a2a_blackboard. Cognitive-cycle bus.\n- Layer 2 (session): knowledge docs + .claude/handovers/*.md. Parallel subagent spawns in one main-thread turn is cheapest.\n\n## Pattern explained\n\n.claude/skills/cca2a/SKILL.md — read once to grok the pattern, skip re-deriving.\n\n## Full spec\n\nCLAUDE.md at workspace root." + } +} +JSON diff --git a/.claude/settings.json b/.claude/settings.json index 23e3af34..aa872954 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -20,5 +20,29 @@ "mcp__github__fork_repository", "mcp__github__create_repository" ] + }, + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { + "type": "command", + "command": "bash .claude/hooks/session-start.sh" + } + ] + } + ], + "PostCompact": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "bash .claude/hooks/post-compact.sh" + } + ] + } + ] } } diff --git a/.claude/skills/cca2a/divergence.md b/.claude/skills/cca2a/divergence.md index a5de7d84..19967f1f 100644 --- a/.claude/skills/cca2a/divergence.md +++ b/.claude/skills/cca2a/divergence.md @@ -86,6 +86,39 @@ auto memory could be an unstructured addition for personal notes. - **Skill max frontmatter size.** 1024 chars. Keep `description` short; offload detail to subpages referenced by the skill. +## Audit note 5 — `permissions.ask` is intentional, not a typo + +The official settings schema supports three permission rule arrays: +`permissions.allow`, `permissions.deny`, and `permissions.ask`. +CCA2A uses `permissions.ask` deliberately on the two append-only +history files: + +```json +"ask": [ + "Edit(.claude/knowledge/PR_ARC_INVENTORY.md)", + "Edit(.claude/knowledge/LATEST_STATE.md)" +] +``` + +The semantics are: +- **`allow`**: tool runs without prompting. +- **`deny`**: tool is blocked completely. +- **`ask`**: tool runs only after an explicit user-approval prompt, + even if it would otherwise be auto-allowed (e.g. via a broader + `Edit` allow rule in personal `settings.local.json`). + +The goal for append-only files is **surface the edit attempt**, not +block it. `deny` would make legitimate Confidence updates or +Correction appends impossible. `allow` (or absence from the lists) +would silently permit history rewrites. `ask` is the correct middle +ground — rewrites surface as a prompt the human can approve or +refuse. + +`Write` on the same paths stays in the personal `allow` list so that +appending a new PR entry at the top of the file doesn't trigger the +prompt. Append = Write; rewrite = Edit. This split is why both keys +show up together in the governance stack. + ## Compatibility CCA2A installs work alongside any existing `.claude/` setup: From b54e86345e6a56765715906245fa9709ad7128d6 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 19 Apr 2026 11:47:30 +0000 Subject: [PATCH 14/18] feat(boot): link existing prior-art directories explicitly in BOOT.md + CLAUDE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The workspace has ~100 curated files from prior sessions (.claude/prompts/ 41 files, .claude/*.md 61 top-level docs, .claude/knowledge/ structured, .claude/agents/ ensemble, .claude/hooks/, .claude/skills/cca2a/). A new session without pointers to this content either duplicates it or ignores it. Changes: 1. .claude/BOOT.md — new §Existing content section lists all prior- art locations with pointers and an explicit "don't duplicate" rule. Before creating a new .claude/*.md, grep existing for the topic. 2. CLAUDE.md §Session Start — new §Prior art subsection after the three mandatory reads pointer, listing the same directories with one-line role per location. 3. .claude/plans/elegant-herding-rocket-v1.md — the active integration plan moved INTO the workspace (was at /root/.claude/plans/ which is session-scoped, not committed). 4. .claude/knowledge/INTEGRATION_PLANS.md — APPEND-ONLY versioned index of all integration plans. v1 entry with Status (Active) + Confidence (Working) fields mutable; scope/path/deliverables immutable. Supersedure rule: new vN+1 entry references vN; prior plan's Status updated to "Superseded by vN+1". Rule locked: grep existing before writing new .claude/*.md. --- .claude/BOOT.md | 34 + .claude/knowledge/INTEGRATION_PLANS.md | 85 + .claude/plans/elegant-herding-rocket-v1.md | 2085 ++++++++++++++++++++ CLAUDE.md | 28 + 4 files changed, 2232 insertions(+) create mode 100644 .claude/knowledge/INTEGRATION_PLANS.md create mode 100644 .claude/plans/elegant-herding-rocket-v1.md diff --git a/.claude/BOOT.md b/.claude/BOOT.md index 499a4dcf..9de1cc48 100644 --- a/.claude/BOOT.md +++ b/.claude/BOOT.md @@ -100,6 +100,40 @@ is a 5–10× cost reduction on every session start. --- +## Existing content — don't duplicate, link + +This workspace already has substantial curated content. New work +should reference these, not recreate them: + +- **`.claude/prompts/`** — 41 scoped prompts (sessions, + certifications, probes, handovers, research surfaces). Each is a + self-contained task brief. See `.claude/prompts/SCOPED_PROMPTS.md` + as the natural index. +- **`.claude/plans/`** — versioned integration plans. Index at + `.claude/knowledge/INTEGRATION_PLANS.md` (APPEND-ONLY — new + versions prepend; prior plans stay with Status annotation). + Active: `.claude/plans/elegant-herding-rocket-v1.md`. +- **`.claude/*.md`** (top-level, 61 docs) — calibration reports, + handover logs, epiphanies compressed, integration-plan snapshots, + cross-repo audits, invariant matrices. Browse before writing new + reference docs. Examples: `EPIPHANIES_COMPRESSED.md` in prompts/, + `SESSION_CAPSTONE.md`, `INTEGRATIONSPLAN_2026_04_01.md`, + `INTEGRATION_SESSIONS.md`, `INVENTORY_MAP.md`. +- **`.claude/knowledge/*.md`** (newer, structured) — the knowledge + base proper with `READ BY:` headers + Knowledge Activation + triggers. See `.claude/agents/BOOT.md` § Knowledge Activation for + the trigger table. +- **`.claude/agents/*.md`** (19 specialists + 5 meta-agents) — + ensemble cards. See `.claude/agents/README.md` for the function + inventory or `BOOT.md` (sibling) for the orchestration spec. +- **`.claude/hooks/*.sh`** — SessionStart and PostCompact hooks + wired via `.claude/settings.json`. +- **`.claude/skills/cca2a/`** — the A2A pattern explanation skill. + +Before creating a new `.claude/*.md` file, grep the existing 61 +docs and 41 prompts for the topic. Most architectural concerns have +prior art. + ## Fallback — CLAUDE.md is the source of truth for everything else If this file doesn't answer your question, CLAUDE.md does. Tables diff --git a/.claude/knowledge/INTEGRATION_PLANS.md b/.claude/knowledge/INTEGRATION_PLANS.md new file mode 100644 index 00000000..14d56300 --- /dev/null +++ b/.claude/knowledge/INTEGRATION_PLANS.md @@ -0,0 +1,85 @@ +# Integration Plans — Versioned Index + +> **APPEND-ONLY.** Every integration plan ever authored for this +> workspace, versioned, with status. New plans append to the top +> as new entries. Superseded plans stay — they are the design arc. +> +> Governance: same rule as `PR_ARC_INVENTORY.md`. The **Status** +> field is the only mutable field per entry. Supersedure is marked +> by adding a new top entry that references the prior version; the +> prior entry is NOT deleted. + +--- + +## APPEND-ONLY RULE + +1. **New plans PREPEND** a new section at the top. +2. **Old plan entries are IMMUTABLE** except the **Status** line. +3. **Supersedure:** if plan vN is replaced by vN+1, prepend a new + entry for vN+1 that cites vN; update vN's **Status** to + "Superseded by vN+1". +4. **Corrections** to plan scope during its lifetime: append a + `**Correction (YYYY-MM-DD):**` line to the entry; do not edit + the original scope line. +5. **Retire but never delete.** When a plan is complete or + abandoned, update Status and move on. The entry stays. + +**Per-entry format:** + +- **Plan name + version** +- **Author + date** +- **Scope** — one-sentence goal (immutable) +- **Path** — workspace file location +- **Deliverables** — D-id list (immutable) +- **Status** — **mutable**: Active / Shipped / Superseded / Deferred / Abandoned +- **Confidence** — **mutable**: Working / Partial / Broken — see PR #N + +--- + +## v1 — Elegant Herding Rocket (authored 2026-04-19) + +**Author:** main-thread session 2026-04-19 +**Scope:** DeepNSM as full parser via Grammar Triangle wiring + Markov ±5 SPO+TEKAMOLO bundling + NARS-tested grammar thinking styles + coreference resolution + story-context bridge + ONNX arc emergence. +**Path:** `.claude/plans/elegant-herding-rocket-v1.md` (2,085 lines) +**Deliverables:** D0 landscape doc, D2 FailureTicket emission, D3 Triangle bridge, D4 ContextChain reasoning, D5 Markov ±5 bundler, D6 role keys, D7 grammar thinking styles, D8 story context + contradictions, D9 ONNX arc export, D10 Animal Farm validation harness, D11 bundle-perturb emergence. + +**Status (2026-04-19):** Active. Phase 1 (D0 + D4 + D6) shipped in PR #210. + +**Confidence (2026-04-19):** Phase 1 working (125 tests passing). +Phases 2–4 queued. + +**Phases:** + +- **Phase 1 — SHIPPED** (PR #210, merged): D0 landscape doc + D4 + ContextChain reasoning ops + D6 role keys. 125 tests passing. +- **Phase 2 — QUEUED:** D2 FailureTicket emission + D3 Triangle + bridge + D5 Markov bundler + D7 grammar thinking styles. + Estimate ~930 LOC, one PR. +- **Phase 3 — QUEUED:** D8 story-context/contradictions + D10 + Animal Farm validation harness. +- **Phase 4 — FUTURE:** D9 ONNX arc export + D11 bundle-perturb + emergence interface. + +--- + +## How to use this file + +1. **Starting a new session:** check top entry. If Status is Active, + that's the current plan. Read it at + `.claude/plans/.md`. +2. **Proposing a new plan:** prepend a new v entry; move prior + plan's Status to Superseded. +3. **Tracking deliverable progress:** use + `.claude/knowledge/STATUS_BOARD.md` for the cross-deliverable + view (which D-ids are in which phase / PR). +4. **User requests / open threads** that aren't yet a plan: capture + in `.claude/knowledge/OPEN_PROMPTS.md`. + +## Cross-references + +- **`STATUS_BOARD.md`** — deliverable-level status (D0 / D2 / D3 / … + across all plans). +- **`OPEN_PROMPTS.md`** — outstanding user questions / threads that + aren't yet scoped into a plan. +- **`PR_ARC_INVENTORY.md`** — shipped-PR decision history. +- **`LATEST_STATE.md`** — current-state snapshot. diff --git a/.claude/plans/elegant-herding-rocket-v1.md b/.claude/plans/elegant-herding-rocket-v1.md new file mode 100644 index 00000000..d55b77de --- /dev/null +++ b/.claude/plans/elegant-herding-rocket-v1.md @@ -0,0 +1,2085 @@ +# Plan — DeepNSM as Full Parser via Markov ±5 Context Upgrade + +## Context + +**Priority (user):** Making DeepNSM the language parser without LLM is +huge; it has priority. Markov ±5 SPO+TEKAMOLO bundling is **the +context upgrade to NARS + SPO 2³ + TEKAMOLO** — trajectory as +reasoning unit, not sentence. Crystal types are reused, not expanded. + +**Already documented** (do not duplicate, read as prerequisites): + +- `.claude/knowledge/grammar-tiered-routing.md` — the full 5-criterion + coverage detector, SPO×2³×TEKAMOLO×Wechsel failure decomposition, + morphology coverage table (Finnish 98 % > English 85 %), self- + improving loop, OSINT language priorities. +- `.claude/knowledge/integration-plan-grammar-crystal-arigraph.md` — + 12 epiphanies E1–E12 (grammar-tiered, morphology-easier, FailureTicket, + cross-lingual superposition, Markov ±5, NARS-about-grammar, crystal + hierarchy, CrystalFingerprint, 5D quorum, episodic unbundle, AriGraph + substrate, demo matrix). +- `.claude/knowledge/crystal-quantum-blueprints.md` — Crystal mode + (bundled Markov SPO chain, Structured5x5 middle cells, bipolar) vs + Quantum mode (holographic residual, Vsa10kF32 + PhaseTag, sandwich + wings for phase keys). +- `.claude/knowledge/cross-repo-harvest-2026-04-19.md` — H1 Born rule, + H2 phase-tag threshold, H3 interference truth, H4 Triangle ≡ + ContextCrystal(w=1), H5 NSM ≡ SPO axes, H6 FP_WORDS=160, H7 Mexican- + hat, H8 Int4State, H9 Glyph5B, H10 Crystal4K 41:1, H11 teleport F=1, + H12 144-verb taxonomy, H13 Three Mountains, H14 Triangle+Context + hybrid. +- `.claude/knowledge/session-capstone-2026-04-18.md` — SB1–SB7, MB1– + MB5, E1–E8, §7 AriGraph-already-shipped addendum. +- `.claude/knowledge/endgame-holographic-agi.md` — 5-layer stack, 12- + step holographic memory loop, P0/P1/P2/P3 priorities. + +## Shipped Today (merged to main) + +- PR #208 — grammar/ + crystal/ contract modules, AriGraph + unbundle hooks. +- PR #209 — sandwich layout, bipolar cells, Codex fixes. +- 112 contract tests + 11 episodic tests passing. + +## Today's Lossiness Epiphanies (not yet in a knowledge doc) + +| Form | Size | Lossy? | Why | +|---|---|---|---| +| 10 000-D f32 (Vsa10kF32) | 40 KB | **LOSSLESS** | 320 K bits of capacity ≫ any bundled signal; orthogonal role keys give exact unbundle | +| Signed 5^5 bipolar | 3 KB | **LOSSLESS** | Negative cancellation = VSA superposition; opposites cancel natively | +| Unsigned 5^5 | 3 KB | **LOSSY** | No cancellation; accumulation saturates | +| Binary bitpacked (10K or 16K) | 1.25 / 2 KB | **LOSSY** | Majority-vote bundle commits to 0/1, loses count | +| CAM-PQ projection (Binary16K → 10K) | 10 / 40 KB | **LOSSLESS** | Distance-preserving by construction | + +**VSA convention:** role keys use contiguous `[start:stop]` slices +(e.g. SUBJECT → [0..156], OBJECT → [156..312]), not scattered bits. +This is the `vsa_permute`-friendly layout. + +## First Concrete Target — Pronoun / Coreference Resolution + +Before any abstract architecture claim, there's a bounded problem that +exercises the entire meta-inference stack: **resolving grammatical +references** — "it", "he", "she", "they", "the company", "that" — +back to their antecedents. Every downstream pipeline (OSINT, chess +commentary, Wikidata triples) depends on it. LLM-based extractors +solve it via attention over tokens; we solve it via **logical +reasoning over the ±5 Markov chain**. + +**The problem:** + +``` +S_{-2} "Pentagon contracted OpenAI in December." +S_{-1} "Thiel was at the meeting." +S_{0} "It announced the deal on Tuesday." ← "it" = ? +S_{+1} "The stock jumped 4%." +``` + +"It" could refer to Pentagon, OpenAI, or the meeting. English leaves +it ambiguous. LLMs use attention heads. We use the context chain as +the candidate enumerator and meta-inference as the decision rule. + +**Grammatical roles ARE bundling — the VSA-native shortcut.** + +Each grammatical role owns a contiguous `[start:stop]` slice of the +10K VSA space (D6). At parse time, content is XOR-bound into its +role's slice and accumulated: + +``` +for token in sentence: + role_key = role_keys[token.grammatical_role] // per-slice key + bound = vsa_bind(content_fp(token), role_key) + trajectory = vsa_bundle(trajectory, bound) // accumulates +``` + +Because binding uses contiguous slices, bundling preserves +role-indexed content throughout. At retrieval: + +``` +subjects_bundle = vsa_unbind(trajectory, SUBJECT_KEY) // just subjects +objects_bundle = vsa_unbind(trajectory, OBJECT_KEY) +locatives_bundle = vsa_unbind(trajectory, LOKAL_KEY) +``` + +**The bundle IS the candidate store.** Candidate enumeration for +coreference becomes an O(1) slice unbind, not a search: + +- "She announced…" → `vsa_unbind(±5_trajectory, SUBJECT_KEY)` recovers + every subject played in the window. +- Then apply `vsa_clean` against a gender-feminine codebook to filter + to feminine-animate survivors. +- Typically 1-2 candidates remain; Deduction commits. + +**Why this matters:** without role-indexed bundling, candidate +enumeration scans the context chain and rebuilds the candidate set +every time. With role-indexed bundling, the bundle itself IS the +structured index — retrieval is a single XOR + clean. + +**Cross-lingual bundling is literally role-slice addition.** Finnish +parse of the same entity lands Finnish content into the same +SUBJECT_KEY slice as English content. When the two trajectories are +bundled together, the SUBJECT slice carries both parses' +role-committed content. Unbinding recovers the aggregate — and +Finnish case morphology has already committed slots the English +parse left ambiguous. + +**This is what D5 and D6 actually produce together.** D5's +`MarkovBundler` does the role-indexed bind-and-bundle. D6's role keys +are the slice addresses. Coreference resolution = D4 +`ContextChain::disambiguate` running counterfactual substitution over +the role-unbind candidate set. + +**How the stack resolves it — grounded in what we're shipping:** + +1. **Enumerate candidates from ±5 Markov chain** — extract every noun + in `ContextChain.preceding + focal + following` as a potential + antecedent. Weight by recency × grammatical salience (subjects > + objects > obliques) × Mexican-hat kernel. + +2. **Hydrate each candidate's SPO role** — from D3's Grammar Triangle + bridge, every prior sentence's SPO triple is available with Pearl + 2³ mask committed. Pentagon was Subject of "contracted"; OpenAI + was Object; meeting was Locative modifier. + +3. **Counterfactual axis test** — for each candidate, apply the + substitution: "Pentagon announced the deal" / "OpenAI announced + the deal" / "The meeting announced the deal". Score the SPO + coherence (does the verb fit the subject? "meetings don't + announce" → Pearl mask inconsistent → low score). + +4. **Markov axis test** — bind each candidate as the Subject of S_{0}, + replay the chain via `ContextChain::replay_with_alternative`, + measure `total_coherence`. The binding that maximises coherence + with ±5 context wins. + +5. **Joint reading (D7 meta-inference duality)** — counterfactual and + Markov axes must agree. If both say "Pentagon" → Deduction commits. + If they split (CF says Pentagon by subject-continuity; Markov says + OpenAI because stock jumped = company signal) → the disagreement + is diagnostic: + - One of them is measuring a surface bias (subject continuity + default) that the other correctly overrides. + - The style's permanent dispatch picks Abduction to weigh which + axis has grip on this signal profile. + +6. **NARS revision on outcome** (D7 empirical layer) — when the + ensemble agrees with a downstream confirmation (e.g. the LLM + fallback would have picked the same answer, or a named-entity + link confirms the binding), the `GrammarStyleAwareness` revises + its prior over "how often the subject-continuity default holds + on this content distribution." + +**Two-tier resolution by inherent factual content.** + +Pronouns split into two classes with different resolution costs: + +**Fixed Pronomen — carry inherent factual commitments:** + +| Pronoun | Inherent commits (axiomatic, permanent, language-specific) | +|---|---| +| I / we / me / us | Speaker-deictic (SPEAKER role) | +| you / thou | Addressee-deictic (ADDRESSEE role) | +| he / him / his | singular + animate + masculine | +| she / her | singular + animate + feminine | +| they (personal) | plural + animate | +| Proper names | rigid designators — committed entity | + +For fixed pronouns, the **inherent-feature filter over ±5 candidates +IS the resolution**. "She announced…" with candidate set +`{Pentagon(neuter), OpenAI(neuter), Marietje(fem)}` — the filter +eliminates 2/3 axiomatically. No counterfactual replay needed. This +is Deduction on inherent facts. Cheap, permanent. + +**Wechsel Pronomen — zero inherent commitment:** + +| Pronoun | Ambiguous on | +|---|---| +| it | referent (anything non-animate, or expletive) | +| that | demonstrative / relative / complementizer / conjunction | +| this | demonstrative / intensifier ("this big") | +| they (singular / expletive) | "they say…", singular they | +| one | indefinite / ordinal / pro-form | +| which | relative / interrogative | + +These need the **full meta-inference stack** (CF × Markov axes) from +the previous section — the expensive path. They're already on the +`WechselAmbiguity` list from D2. + +**Cross-linguistic commitment profiles vary per pronoun class — +another reversal from the morphology story:** + +| Language | Morphology (slot-filling) | Pronoun feature commitment | +|---|---|---| +| English | weak (word order) | moderate (he/she/it on 3sg) | +| German | moderate (4 cases) | **strong** (er/sie/es + case: ihn/ihm/seiner) | +| Russian | heavy (6 cases) | **strong** (он/она/оно + full case paradigm) | +| Finnish | **very heavy** (15 cases) | **weak** (single `hän` for he/she — gender-neutral) | +| Japanese | agglutinative particles | minimal (usually dropped) | +| Turkish | agglutinative | weak (single `o` for he/she/it) | + +**Finnish is the easiest language on morphological slot-filling but +NOT on pronoun feature resolution** (because `hän` is gender-neutral). +German and Russian are richest on pronoun features. + +A cross-lingual bundle (EN + DE + RU + FI) maximises both axes +simultaneously: each language contributes where its commitment is +strongest. Wechsel-heavy English + feature-weak Finnish + feature- +strong German/Russian = the complementary quartet for OSINT +resolution. + +**Resolution dispatch:** + +``` +pronoun = lex_classify(token) + │ + ├── FIXED → feature_filter(±5 candidates, pronoun.inherent_features) + │ → 1-2 survivors → Deduction commits + │ → no Markov / CF needed (usually) + │ + └── WECHSEL → full D7 meta-inference + (CF axis × Markov axis × cross-lingual bundle) + → WechselAmbiguity on the FailureTicket if both weak +``` + +**Categories of reference resolution this unlocks** (all same +mechanism, different candidate generators): + +| Reference type | Example | Candidate set | +|---|---|---| +| Anaphoric pronoun | "Pentagon … **it** announced …" | All preceding nouns, subject-weighted | +| Cataphoric pronoun | "If **he** calls, tell John …" | Next-mentioned proper noun | +| Dropped subject (Russian, Japanese, Italian) | "Пошёл домой." ("[he/she] went home") | Preceding subject, verb agreement narrows gender/number | +| Definite NP | "the company" | All prior company-mentioned entities | +| Demonstrative | "that", "this" | Most salient noun or fact by Markov coherence | +| Possessive | "his", "her", "its" | Possessor candidates filtered by animacy + agreement | +| Relative pronoun | "the man who …" | Immediate antecedent in syntactic scope | + +**Cross-lingual bonus** — dropped subjects are cheap in +morphologically-rich languages because verb agreement narrows the +candidate set before the Markov axis fires. Russian +`Пошла домой` — feminine verb ending → candidate restricted to +feminine antecedents in ±5. Japanese verb form + particle commits +discourse role. English has no such morphological narrowing, which is +why English coreference is *the* hard problem and everyone else is +easier. + +**What this means for shipping order.** + +The D2/D3/D4/D5/D6/D7 deliverables already cover everything needed. +The coreference problem is **the first verification target** — the +end-to-end test that proves the stack works: + +- D4 `ContextChain::disambiguate` runs the replay. +- D5 Markov bundle produces the trajectory fingerprints to score against. +- D6 role keys bind each candidate as the Subject in the counterfactual substitution. +- D7's meta-inference duality combines CF + Markov scores. +- D2 FailureTicket fires only when both axes are weak. + +**Integration test corpus: Orwell, *Animal Farm*.** + +Animal Farm is the canonical benchmark because: + +- Orwell is famous for deliberately-clean textbook English grammar — + plain, precise, unambiguous. Used in English-language teaching + precisely because every sentence parses cleanly. If we cannot hit + 85 %+ local on Animal Farm, the tiered-routing claim fails. +- Heavy named-entity density: Napoleon, Snowball, Squealer, Boxer, + Clover, Mollie, Benjamin, Old Major, Mr. Jones, Pilkington, + Frederick, Whymper. Each has committed animacy / gender / species / + social-role features — classic fixed-pronoun resolution targets. +- Gendered pronouns across species: "Mollie tossed her mane" / + "Napoleon issued his decree" / "the horses lost their strength" — + feature-filter resolution is unambiguous on 90 %+ of cases. +- Subject-continuity chains through chapters — Markov ±5 coherence is + measurable across whole narrative sequences. +- Clear causal chains (Squealer explains why X; Napoleon decrees + because Y) — SPO 2³ causal mask commits are testable. +- Public-domain (UK copyright expired 2020); ~40 K words; small + enough to process end-to-end in a single run; large enough to give + statistically meaningful coref accuracy. + +**Benchmark targets:** + +- Local (no LLM) coverage ≥ 85 % on full Animal Farm text. +- Fixed-pronoun coreference accuracy ≥ 95 % (he/she/his/her/their + against gendered named animals). +- Wechsel-pronoun ("it", "that") accuracy ≥ 75 % via CF+Markov meta- + inference. +- Cross-lingual bundle improvement: EN + DE (Orwell's German + translation is widely-available, textbook-grade) shows measurable + Wechsel-pronoun disambiguation improvement ≥ 5 %. +- End-to-end latency: full book parsed locally in ≤ 5 minutes + (< 10 µs/sentence × 40 K sentences = 400 ms; the rest is ±5 + buffering and bundle construction). + +--- + +## The Synthesis (what Markov ±5 actually buys) + +Pre-Markov reasoning unit = **sentence**. Thinking style applies NARS +inference to one SPO triple + TEKAMOLO slots. Isolated. Fragile on +Wechsel. + +Post-Markov reasoning unit = **trajectory**. Thinking style applies +NARS inference to a trajectory fingerprint that carries ±5 sentences +of context (position-permuted, Mexican-hat weighted). NARS doesn't +reason about "this sentence"; it reasons about "this sentence in +this flow." This is the context dimension upgrade to NARS+SPO2³+TEKAMOLO. + +Cross-linguistic corollary (AGI-grade per user): XOR-bundle a trajectory +from EN and FI of the same entity. Finnish case morphology (adessive +`-llä`, elative `-sta`) commits Wechsel-ambiguous English roles into +specific TEKAMOLO slots. The superposed trajectory carries +disambiguation for free. + +## To Build (one combined PR, ~1,555 LOC) + +### D0 — Knowledge doc + +**New:** `/home/user/lance-graph/.claude/knowledge/grammar-landscape.md` +(~320 lines). Three grammar stacks (Rust / Python / TypeScript) with +paths + LOCs; Triangle = NSM × Causality × Qualia; TEKAMOLO templates +with 3-slot gap flagged; YAML 200–500/language training pipeline as +future target; Markov ±5 as the context upgrade to NARS+SPO2³+TEKAMOLO. +Cross-refs to the five existing knowledge docs. + +**Includes a §Case Inventories Per Language** section with native- +terminology tables for at least: Finnish (15 — with the Accusative +correction), Russian (6 — full Nom/Gen/Dat/Acc/**Ins**/Prep), +German (4 — Nom/Gen/Dat/Akk), Turkish (6 + agglutinative chain), +Japanese (particles: が/を/に/で/へ/と/から/まで). Each case entry +maps to its permanent TEKAMOLO / SPO role and notes when a Latinate +label (e.g. "Accusative") would be misleading for that language. + +**Also updates (edit):** `grammar-tiered-routing.md` — patch the +Finnish case table with the correct Nominative/Genitive/Partitive +object marking and a note that true Accusative is personal-pronoun +only. Patch is ≤ 30 lines. + +**CausalityFlow extension scope (deferred from this PR, documented +in D0).** The original "3 new fields" (modal / local / instrument) +is insufficient. Full thematic-role inventory adds 3 more: + +- **Beneficiary** — "for whom" (dative of benefit). German + `für ihn`, Finnish Allative `-lle` in benefactive reading, Russian + Dative with `для` / `+dat`. +- **Goal / Direction** — "to where" (directional). Finnish Illative + `-Vn/-hVn/-seen`, Russian Accusative with `в/на`, German `nach/ + zu` + Dat. +- **Source** — "from where" (ablative origin). Finnish Elative + `-sta/-stä` or Ablative `-lta/-ltä`, Russian Genitive with `из/с`, + German `aus/von` + Dat. + +Optional later additions (language-specific): + +- **Path** — "through where" (prolative). Finnish Prolative + `-tse/-itse`, Turkish Instrumental-path construction. +- **Purpose / Finale** — "for what purpose". German `zum + Inf`, + Finnish Translative `-ksi` in purposive reading. +- **Result** — "leading to what". German `sodass`, Finnish + consequence constructions. + +Full extended CausalityFlow (deferred follow-up PR, not this one): + +```rust +pub struct CausalityFlow { + // existing (3/9 slots): + pub agent: Option, + pub action: Option, + pub patient: Option, + pub reason: Option, // Kausal + pub temporality: f32, // Temporal as float + pub agency: f32, + pub dependency_type: DependencyType, + + // TEKAMOLO completion (3 slots, the original "modal/local/instrument"): + pub modal: Option, + pub local: Option, + pub instrument: Option, + + // Thematic-role completion (3 more slots, classical theory): + pub beneficiary: Option, + pub goal: Option, + pub source: Option, +} +``` + +6 new `Option` fields in total (not 3) to reach the full +thematic-role inventory. Still trivial struct change; still deferred +from the current PR's scope (user decision). + +### D2 — DeepNSM emits FailureTicket + +**Edit:** `crates/deepnsm/src/parser.rs` (+30 LOC) — end-of-parse +coverage branch. **New:** `crates/deepnsm/src/ticket_emit.rs` (+120). +**Feature gate:** `contract-ticket` on deepnsm; default stays zero-dep. + +Ticket carries the SPO × 2³ × TEKAMOLO × Wechsel decomposition from +grammar-tiered-routing.md §"Combined failure ticket". Failure reason +itself is the routing signal (COCA miss → Wikidata; FSM incomplete → +LLM parse; slots unfillable → disambiguate; low primes → LLM; high +classification_distance → novel domain). + +### D3 — Grammar Triangle wired into DeepNSM + +**New:** `crates/deepnsm/src/triangle_bridge.rs` (+220 LOC). + +Thin adapter: DeepNSM FSM produces `SentenceStructure`; call +`lance_graph_cognitive::grammar::GrammarTriangle::analyze(text)` in +parallel to produce `(NSMField, CausalityFlow, Qualia18D)`; merge +into `SpoWithGrammar { triples, causality, nsm_field, +qualia_signature, classification_distance }`. + +**Feature gate:** `grammar-triangle` (additive). + +**Explicit non-scope:** CausalityFlow TEKAMOLO extension (modal/local/ +instrument) is **deferred** per user. Current 3/6 slots mapped. + +### D4 — ContextChain reasoning ops (coherence / replay / disambiguate) + +**Edit:** `crates/lance-graph-contract/src/grammar/context_chain.rs` +(+140 LOC). Upgrades ring-buffer to reasoning substrate: + +```rust +impl ContextChain { + pub fn coherence_at(&self, i: usize) -> f32; + pub fn total_coherence(&self) -> f32; + pub fn replay_with_alternative(&self, i: usize, + alt: CrystalFingerprint) -> (Self, f32); + pub fn disambiguate(&self, i: usize, candidates: I) + -> DisambiguationResult; +} +pub enum WeightingKernel { Uniform, MexicanHat, Gaussian } +``` + +Zero-dep preserved (internal Hamming on `Box<[u64; 256]>`; cosine for +VSA variants). Mexican-hat = harvest H7 landing. + +### D5 — Markov ±5 SPO+TEKAMOLO bundler (role-indexed) + +**New:** `crates/deepnsm/src/markov_bundle.rs` (+220 LOC). +**New:** `crates/deepnsm/src/trajectory.rs` (+80 LOC). + +`MarkovBundler` — **role-indexed bundling** (the VSA-native shortcut +for coreference): + +- Ring buffer of 11 `SentenceStructure`s. +- For each token, XOR-bind `content_fp(token)` with the appropriate + role key from D6: SUBJECT_KEY, PREDICATE_KEY, OBJECT_KEY, + MODIFIER_KEY, CONTEXT_KEY, TEMPORAL_KEY, KAUSAL_KEY, MODAL_KEY, + LOKAL_KEY, INSTRUMENT_KEY, or a language-specific case key + (Finnish Inessive, Russian Instrumental, etc.) when morphology + commits the role. +- Because role keys own disjoint `[start:stop]` slices of the 10K + vector, the bind lands content into its role's slice; no cross- + role contamination. +- `vsa_permute(v, position_offset)` per sentence in the window + (harvest H5 bit-chain). +- `vsa_bundle` with Mexican-hat weights (focal > ±1 > … > ±5). +- Produce `Trajectory { vsa_vector, context_chain, structured_5x5 }`. + Trajectory's fingerprint IS `SentenceCrystal::fingerprint` — no new + crystal type introduced. + +**Companion retrieval API on `Trajectory`:** + +```rust +impl Trajectory { + /// O(1) unbind of a role slice — recovers the role-indexed + /// content bundle without scanning the context chain. + pub fn role_bundle(&self, role: GrammaticalRole) -> Box<[f32; 10_000]>; + + /// Filter the role bundle through a codebook (e.g. feminine- + /// animate nouns for "she") to produce survivor candidates. + pub fn role_candidates( + &self, + role: GrammaticalRole, + filter_codebook: &[&[f32; 10_000]], + ) -> Vec; +} +``` + +This is what makes coreference O(1) per query: candidate +enumeration = slice unbind + codebook clean, not a context-chain scan. + +Target bundled form: **lossless** — `Vsa10kF32` sandwich (f32 wings +accumulate residuals; middle cells hold Structured5x5). Derived +`Binary16K` via sign-binarize for hot-path sweep. + +### D6 — Role-key catalogue + +**New:** `crates/lance-graph-contract/src/grammar/role_keys.rs` +(+160 LOC). Deterministic `LazyLock` `VsaVector`-shaped keys via FNV-64, +addressed as contiguous `[start:stop]` slices: + +- 5 SPO-role keys: SUBJECT [0..2000], PREDICATE [2000..4000], + OBJECT [4000..6000], MODIFIER [6000..8000], CONTEXT [8000..10000]. +- 5 TEKAMOLO-slot keys (TEMPORAL, KAUSAL, MODAL, LOKAL, INSTRUMENT; + last three future-ready). +- 15 Finnish case keys from `FinnishCase`. +- 12 tense keys (aligned with sigma_rosetta 144 = 12 × 12). +- 7 NARS inference keys. + +(Exact slice boundaries set so role-domains don't overlap; Hamming +similarity within a role-domain stays meaningful.) + +### D8 — Story Context = Episodic Memory + Triplet Graph (already shipped) + +**The story IS a graph.** AriGraph's `triplet_graph.rs` (1064 LOC, +shipped) stores every SPO triple with NARS truth and temporal +metadata. `episodic.rs` (210 LOC + unbundle hooks from PR #208) stores +each sentence as an Episode. Together they already represent the +narrative: entities are nodes, verbs are edges, temporal ordering +makes a Markov chain through the graph. No new `StoryContext` struct +needed — just query methods that traverse what's there. + +**Two-tier Markov chain via existing storage:** + +| Tier | Where it already lives | Query method | +|---|---|---| +| Working memory (±5) | `MarkovBundler::Trajectory` (D5, new) | `Trajectory::role_bundle` | +| Paragraph (±50) | `EpisodicMemory` Hamming retrieval | existing `retrieve_similar(fp, k)` | +| Document (±500) | `TripletGraph` BFS association + spatial paths | existing `triplet_graph.rs` | +| Permanent (rigid designator) | AriGraph unbundled facts (PR #208) | `EpisodicMemory::unbundle_hardened` | + +Each tier uses the **same role-indexed VSA bundling mechanism** and +the **same SPO store** — the scale is the query radius, not a new +data structure. + +**On the grammar side (already covered in D5):** + +`MarkovBundler` emits a `Trajectory` at each focal sentence. Feeds +into AriGraph via the existing `EpisodicMemory::add()`. + +**On the AriGraph side — two thin additions, no new module:** + +**(a) Graph direct lookup — objects as nodes, SPO as edges.** + +The existing `TripletGraph` (1,064 LOC shipped) already stores +objects as nodes addressed by fingerprint, with SPO triples as +edges carrying NARS truth + Pearl 2³ causal mask. For coref, this +is the right primitive: direct node lookup by feature index is +lossless and O(k) where k = matching nodes, vs a bundled vector's +√N-bounded recall. + +Three retrieval tiers, chosen by query type: + +**Tier 1 — direct graph lookup by feature (primary for coref).** + +```rust +impl TripletGraph { + /// Enumerate nodes whose feature bundle matches the filter + /// (e.g. masculine + animate for "he", feminine + animate for + /// "she"). Reads the feature indices maintained during commit. + pub fn nodes_matching( + &self, + features: &FeatureFilter, + ) -> Vec; + + /// Rank nodes by Markov proximity to a focal sentence — + /// recency-weighted via Mexican-hat over episode_index delta. + pub fn rank_by_proximity( + &self, + candidates: Vec, + focal_episode: u64, + ) -> Vec; +} +``` + +For coref resolution: + +``` +pronoun "he" at focal episode 9 + │ + ▼ +graph.nodes_matching(masculine + animate) + │ → [Napoleon, Boxer, Benjamin, Mr. Jones] (k small, lossless) + ▼ +graph.rank_by_proximity(..., focal=9) + │ → [Napoleon (score 0.8), Boxer (0.3), Benjamin (0.1), Jones (0.05)] + ▼ +commit top candidate if margin > threshold else FailureTicket +``` + +This is O(k) not O(√N). No bundle saturation. No tree walk. +Every committed entity remains individually addressable forever. + +**Tier 1.5 — orthogonal global-context superposition of known facts.** + +Every fact that crosses the hardness threshold (PR #208) or the +Abduction-confidence threshold (this PR) is **also** bundled into a +single 10 K orthogonal global-context vector — not per-role, just +the committed-facts field. Each fact is `vsa_permute`d by its +episode index before bundling so facts sit in orthogonal subspaces +and don't destructively interfere. + +```rust +impl EpisodicMemory { + /// Orthogonal superposition of all known (hardness- or + /// Abduction-committed) facts. Each fact permuted by its + /// episode index, then bundled. Staying within √N capacity + /// because only committed facts contribute — Animal Farm's + /// committed set is ~500, well below saturation. + pub fn global_context(&self) -> &[f32; 10_000]; + + /// Called on every unbundle (hardness or Abduction gate) — + /// O(1) incremental update: permute, XOR-accumulate. + fn integrate_into_global(&mut self, fact: &Triplet, ep_idx: u64); +} +``` + +**Coref query becomes a two-stage refinement:** + +``` +Stage A — ambient pre-filter (cheap, one superposition + unbind) + combined = vsa_bundle(trajectory, global_context) + ambient_subj = vsa_unbind(combined, SUBJECT_KEY) + ambient_survivors = vsa_clean(ambient_subj, feature_codebook) + → ~5-10 candidates from ±5 + whole-story committed facts + +Stage B — lossless refinement via graph direct lookup (Tier 1) + node_candidates = graph.nodes_matching(FeatureFilter { … }) + refined = intersect(ambient_survivors, node_candidates) + ranked = graph.rank_by_proximity(refined, focal_episode) + +Commit ranked[0] if margin > threshold else FailureTicket. +``` + +The global context is the **attention mask** over the graph: it +pre-filters the candidate pool before O(k) node enumeration. Graph +stays lossless; superposition keeps the common path cheap. + +**Why gate on hardness / Abduction threshold only:** uncommitted +content stays ±5-local. Only facts the system actually believes +contribute to global context. The global vector encodes "what we +know for sure about this story so far" — exactly the information a +reader accumulates about Animal Farm as they read it. + +**Tier 3 — CLAM tree for 5 B-sentence scale.** + +Only needed for Wikidata / chess-database regime where the graph has +billions of nodes and feature-index enumeration gets expensive. +Already shipped in `ndarray/src/hpc/clam.rs`. Escape hatch, not +primary path. + +**Why this ordering matters.** Coref is an **individual-entity** +query — "which specific noun does this pronoun refer to?" That's a +node lookup, not a bundle reconstruction. The graph IS the natural +data structure. Tier 2's bundle superposition is for a different +question (ambient texture), and Tier 3 is for a different scale +(billion-node corpus). Getting the tiering right keeps each +mechanism doing what it's best at. + +**(b) Abduction-threshold unbundle + epiphany/error-correction split.** + +Extend PR #208's `unbundle_hardened` with TWO complementary gates: + +```rust +/// Abduction-confidence threshold for direct fact promotion. +/// Parallel to UNBUNDLE_HARDNESS_THRESHOLD. +pub const UNBUNDLE_ABDUCTION_THRESHOLD: f32 = 0.88; + +/// Threshold above which a counterfactual loser is "epiphany +/// material" — retained alongside the winner rather than silently +/// discarded. Below this, losers are routine error corrections. +pub const EPIPHANY_SUPPORT_THRESHOLD: f32 = 0.55; + +impl EpisodicMemory { + /// Promote Abduction outcomes to the triplet graph as committed + /// facts when NARS confidence exceeds UNBUNDLE_ABDUCTION_THRESHOLD. + pub fn unbundle_abductive( + &mut self, + graph: &mut TripletGraph, + ) -> UnbundleReport; + + /// Emit a counterfactual outcome from meta-inference. Classifies + /// into epiphany or error-correction based on the loser's + /// independent Markov + graph support. + pub fn record_counterfactual( + &mut self, + graph: &mut TripletGraph, + winner: &Triplet, + loser: &Triplet, + winner_confidence: f32, + loser_independent_support: f32, + ) -> CounterfactualDisposition; +} + +pub enum CounterfactualDisposition { + /// Loser had no independent support — routine ambiguity + /// resolution. Apply truth decrement to the losing interpretation, + /// commit only the winner. Silent. + ErrorCorrection { winner_truth: TruthValue, + loser_decrement: f32 }, + + /// Loser has independent Markov / graph support — the + /// ambiguity IS the meaning (propaganda, sarcasm, unreliable + /// narrator). BOTH readings commit as separate triples with + /// their own NARS truth. The episode gets tagged as carrying + /// an "epiphany" marker for later surfacing. + Epiphany { winner_truth: TruthValue, + loser_truth: TruthValue, + reason_tag: EpiphanyTag }, +} + +pub enum EpiphanyTag { + /// Both readings coherent with ±5 Markov (legitimate ambiguity). + DualCoherence, + /// Graph carries hardened facts supporting the loser (narrative + /// unreliability / deliberate revision). + GraphConflictsWithLocal, + /// Cross-lingual bundle disagrees with English default + /// (colloquialism / idiom / translation-sensitive reading). + CrossLingualDivergence, + /// Thinking style self-flagged: this style's track record on + /// similar signal profile is low; flag the decision. + StyleLowConfidence, +} +``` + +**Routing via the two gates:** + +``` +Counterfactual outcome at meta-inference dispatch + │ + ├── winner_confidence > 0.88 AND loser_independent_support < 0.55 + │ → ErrorCorrection (routine; apply decrement silently) + │ + ├── winner_confidence > 0.88 AND loser_independent_support > 0.55 + │ → Epiphany (preserve BOTH; tag the episode) + │ + └── winner_confidence ≤ 0.88 + → FailureTicket (escalate; don't commit either) +``` + +**Animal Farm examples:** + +- *Routine error-correction:* "Boxer worked hard all day." CF test: + is "Boxer" a horse, a breed, a boxing verb? Graph carries Boxer as + hardened rigid-designator (masculine, horse, carthorse, strong). + Loser readings have zero independent support → silent error + correction, commit only the horse reading. + +- *Epiphany:* "The windmill fell." CF test: Snowball's sabotage (per + Napoleon's narrative in ch. 6) vs the storm (original cause, ch. 6 + before Napoleon's retelling). Graph carries BOTH as committed + facts with separate NARS truths. Loser's independent support + ≥ 0.55 → Epiphany with `GraphConflictsWithLocal` tag. Both + triples commit; the episode is flagged as carrying propaganda + dissonance. This IS the literary meaning of Animal Farm. + +- *Cross-lingual epiphany:* "All animals are equal." CF test: + straightforward reading ("every animal has equal status") vs + constitutional-axiom reading ("this is a founding rule"). Russian + translation uses different case marking ("равны" vs "равноправны") + that distinguishes the readings. Cross-lingual bundle disagrees + with English default → Epiphany with `CrossLingualDivergence`. + +**Why this matters for AGI.** A system that can only error-correct +treats all ambiguity as noise. A system that can distinguish +epiphany from error recognizes when ambiguity carries meaning — +which is what sarcasm, allegory, propaganda, and poetry are made of. +Animal Farm is the canonical test because the novel's mechanism is +exactly this — narratorial unreliability made visible through +committed-vs-retold facts diverging. + +**Naming pattern:** Abduction-threshold-unbundle uses the same NARS +revision rule as hardness-unbundle; epiphany preservation uses the +same triplet-graph storage as any committed fact. Zero new storage +primitives — all from PR #208's pattern plus a disposition tag. + +**Edit:** `crates/lance-graph/src/graph/arigraph/episodic.rs` (+80 LOC) +— `unbundle_abductive`, `role_candidates_wider`, `lookup_rigid`. + +**Edit:** `crates/lance-graph/src/graph/arigraph/triplet_graph.rs` (+40 LOC) +— `role_bundle()` accessor + incremental update when new triples land. + +**(c) Contradictions as phase + magnitude (Staunen markers).** + +Each committed triple gets an optional **complex amplitude** beyond +its NARS `TruthValue`. This is a targeted application of Path 2's +phase-tag machinery — not to the whole memory field, just to +contradictions: + +```rust +pub struct Contradiction { + /// Angular distance from consensus position, in normalized + /// units: 0 = fully agrees, π (= PhaseTag::pi()) = fully opposite. + pub phase: PhaseTag, // 128 bits, from ladybug-rs hologram types + /// Strength of the dissonance: 0 = no contradiction worth + /// tracking, 1 = strong contradiction that commands attention. + pub magnitude: f32, +} + +impl Triplet { + /// Optional contradiction record. Present when this triple + /// conflicts with prior commitments; None when clean. + pub contradiction: Option, +} + +impl TripletGraph { + /// When a new triple conflicts with existing content, compute + /// the phase angle from the consensus (via XOR of fingerprints) + /// and magnitude from NARS-truth divergence. Attach as + /// Contradiction to the new triple; fires Staunen if past + /// threshold. + pub fn commit_with_contradiction_check( + &mut self, + triple: Triplet, + ) -> CommitResult; +} + +pub enum CommitResult { + Clean, + Contradicts { staunen_fires: bool, magnitude: f32 }, +} +``` + +**Why this matters.** A flat NARS `TruthValue` represents belief +strength but can't carry **direction of disagreement**. Two triples +that disagree can have the same confidence but point opposite ways +in fact-space. Phase captures the direction; magnitude captures how +seriously we should take the disagreement. + +**Linkage to sigma_rosetta — Staunen → phase, Wisdom → magnitude.** + +The 64-glyph qualia vocabulary already contains the coordinates we +need. No new glyphs; just map: + +| Sigma family | Maps to | Interpretation | +|---|---|---| +| **Staunen family** (wonder, astonishment, unexpected — includes Staunen / Emberglow / Thornrose) | **phase** | Direction of the surprise. Which way does this contradiction point relative to consensus? Staunen at angle φ means "surprised *in this direction*." | +| **Wisdom family** (clarity, insight, understood, metacognition — typically in Cognitive glyphs 32-47) | **magnitude** | Depth of the insight. How much does this contradiction reveal? Wisdom near 1 = profound reveal; near 0 = shallow surprise. | + +Concretely: the per-cycle qualia vector's Staunen-family projection +becomes the `Contradiction.phase` angle, and its Wisdom-family +projection becomes the `magnitude`. Contradiction detection is no +longer a separate computation — it's a projection onto two axes of +the qualia vocabulary we already ship. + +```rust +impl Contradiction { + /// Build a Contradiction from the current cycle's QualiaVector + /// by projecting onto Staunen (phase) and Wisdom (magnitude) + /// subspaces of the sigma_rosetta 64-glyph vocabulary. + pub fn from_qualia(q: &QualiaVector) -> Self { + Self { + phase: PhaseTag::from_angle(q.staunen_projection()), + magnitude: q.wisdom_projection().clamp(0.0, 1.0), + } + } +} +``` + +**Animal Farm example revisited:** "Some are more equal" fires +Staunen-family glyphs hard (the surprise direction is clear: toward +hierarchy) AND Wisdom-family glyphs hard (the reader understands +something profound about power). Phase = Staunen-axis angle (≈ π +from the prior claim); magnitude = Wisdom-axis depth (≈ 0.9). Both +high → Staunen marker fires on the WorldModelDto, epiphany committed +with the phase direction preserved. + +Routine contradictions fire Staunen-family low (no clear surprise +direction) and Wisdom-family low (no deep insight). Phase noisy, +magnitude near 0 → silent error correction, no Staunen attention. + +**This is the epiphany-vs-error-correction distinction at the +storage layer**, with the sigma_rosetta qualia vocabulary as the +natural coordinate system. We already compute these qualia per +cycle; contradiction detection becomes free reuse of the existing +machinery. + +**Animal Farm example:** "All animals are equal" (ch. 2) gets +committed with magnitude 0. "All animals are equal, but some are +more equal than others" (ch. 10) commits with phase ≈ π from the +prior fact (opposite direction in equality-space), magnitude ≈ 0.9. +Staunen fires. The system has detected the book's central +contradiction as a first-class fact, not as a rewrite of the +earlier triple. + +**Files (folded into existing D8 scope):** +- `crates/lance-graph/src/graph/arigraph/triplet_graph.rs` — + +40 LOC for `Contradiction` struct, `commit_with_contradiction_check`, + phase computation via XOR + hamming. +- `crates/lance-graph-contract/src/grammar/mod.rs` — add + `STAUNEN_THRESHOLD` constant. +- No new files; ~40 LOC addition, ~30 LOC tests. + +**Edit:** `crates/lance-graph/src/graph/arigraph/mod.rs` — re-export. + +**Coref escalation path — the bridge that makes Animal Farm work:** + +``` +grammar: "He decreed it." ← "he"? + │ + ▼ +D4 ContextChain.disambiguate over ±5 (D5 Trajectory) + │ + ├── fixed pronoun? apply feature filter via D5 + │ Trajectory::role_candidates with masculine-animate codebook. + │ └── 1+ survivors? → commit. + │ + └── no candidate in ±5 → escalate via D8 + │ + ▼ + EpisodicMemory::role_candidates_wider(Subject, + masculine_codebook, StoryScale::Paragraph) + │ + ├── candidate at paragraph scope? → commit. + ├── else escalate to Chapter, then Document. + └── still nothing → lookup_rigid for hardened facts + (is "Napoleon" a committed masculine-animate boar + in the already-unbundled rigid-designator store?) + │ + ├── yes → commit with high-confidence NARS truth. + └── no → FailureTicket, LLM fallback. +``` + +**Why this ships with the grammar work:** without the bridge, coref +on Animal Farm fails on cross-chapter references. Napoleon appears +in chapter 1 and is referred to as "he" in chapter 9 — ±5-sentence +Markov can't reach chapter 1. The bridge resolves it because +Napoleon's masculine-animate commitments hardened early via PR #208's +`unbundle_hardened` and live as rigid-designator facts in the +existing triplet graph. + +**LOC estimate:** ~90 LOC on the AriGraph side (episodic.rs + +triplet_graph.rs edits + mod.rs + tests). No new module. Pure reuse +of shipped infrastructure. + +### D9 — Story-Arc as an ONNX Learning Graph (export interface only; training deferred) + +**The idea.** The story is not just a factual graph (D8) and a ±5 +Markov trajectory (D5) — it also has an **arc**, a learned pattern +of how state transitions unfold. Animal Farm has a recognisable +corruption arc (equality → ambiguity → dominance → totalitarianism); +fairy tales have propp-function arcs; news stories have +inverted-pyramid arcs. The arc is what predicts "what typically +happens next" given the committed state. + +**ONNX is the right format** because: +- It's already in our stack (CLAUDE.md Model Registry: + `jina-v5-onnx/` with `model.onnx` 2.3 GB). +- Rust ONNX runtimes exist (`ort`, `tract`) and are production-ready. +- ONNX graphs are portable — Netron visualizes them, any framework + consumes them, trained arcs can be shared across sessions and users. +- It's a **computational graph** at heart: nodes = states, edges = + transitions with weights. Exactly what a narrative arc is. + +**Three time scales of story representation (combined picture):** + +| Layer | Representation | Timescale | Purpose | +|---|---|---|---| +| Markov ±5 (D5) | VSA trajectory | Sentence / paragraph | Local coref / disambiguation | +| Episodic + Triplet graph (D8) | Node–edge graph | Session → Persistent | Committed facts lookup | +| Story arc (D9) | ONNX computational graph | Learned pattern | Predict next state given current | + +Each layer feeds the next. Committed facts populate the arc's +training signal; the arc predicts state transitions that the Markov +trajectory verifies. + +**Shipping scope for this PR (minimal):** + +1. **Export interface.** Add `graph.to_onnx()` on `TripletGraph` that + emits the committed-facts subgraph as a valid `.onnx` file. Nodes + = entity fingerprints; edges = SPO triples with NARS truth as + edge attributes. ONNX is graph-structured, not tensor-structured, + for this use — we use the GraphProto container with custom ops + for triples. +2. **Integration hook.** Reserve a `story_arc: Option` + field on the meta-inference context; default `None`. When set, the + predictor is consulted as a third axis alongside Counterfactual + and Markov during coref escalation. +3. **Arc-axis trait definition.** `ArcPredictor` trait with + `predict_next_state(current: &TrajectoryFingerprint) -> + StatePrediction`. No default implementation in this PR — + downstream crates or a future PR train the ONNX model and ship it + as a loadable asset. + +**Deferred to follow-up PR:** + +- Actual ONNX model training on committed-fact sequences. +- Pre-trained story-arc templates for common narrative patterns. +- Cross-story transfer (train on Animal Farm, apply to The Trial). +- Arc-axis integration into the meta-inference dispatch. + +**Arc pressure → awareness (architectural hook shipped now).** + +The arc carries two derivative signals that matter *now*, before +ONNX training lands: + +| Derivative | Interpretation | Awareness effect | +|---|---|---| +| `d(phase) / dt` | Direction of the arc is shifting | Plot twist / topic change / character reversal — widen attention | +| `d(magnitude) / dt` | Tension is accelerating | Climax / crisis / reveal — focus attention | +| Both low | Stable narrative flow | Routine dispatch, no special signal | +| Both high | Major arc event | Fire Staunen awareness | + +This is exactly how narrative theory defines "story beats" — the +moments the arc pivots. Computational detection is threshold +crossing on the derivative. The architectural hook ships now, the +ONNX training fills in the prediction later. + +```rust +/// Instantaneous arc pressure — computed per cycle from the +/// accumulated Markov trajectory + graph commitments. +pub struct ArcPressure { + /// Phase: direction of the arc (Staunen-family projection). + pub phase: f32, + /// Magnitude: tension / depth (Wisdom-family projection). + pub magnitude: f32, +} + +/// Rate of change between consecutive cycles. This is what the +/// cognitive shader reads as an awareness signal. +pub struct ArcDerivative { + pub dphase_dt: f32, + pub dmagnitude_dt: f32, +} + +impl ArcDerivative { + /// True when either derivative crosses the awareness threshold + /// — the system should surface this cycle as a story beat. + pub fn is_arc_shift(&self, threshold: f32) -> bool { + self.dphase_dt.abs() > threshold + || self.dmagnitude_dt.abs() > threshold + } +} +``` + +**Integration with the existing cognitive shader (shipped in +PR #204).** + +`MetaWord` in the contract already has 4 reserved awareness bits +(per PR #204 — `awareness: u8` packed into the u32). Use those bits +for arc-shift detection: + +``` +awareness 4 bits: + bit 0 — d(phase)/dt crossed threshold (arc direction shifting) + bit 1 — d(magnitude)/dt crossed threshold (tension accelerating) + bit 2 — Staunen marker fired (from D8 contradiction detection) + bit 3 — StateAnchor changed since last cycle (proprioception) +``` + +The shader's `MetaFilter.awareness_min` (shipped) already gates +dispatch on awareness. Arc shifts now contribute to this gate +without touching the shader code — they just set different bits. + +**Thinking-style dispatch reads arc pressure as a signal profile +axis** (extending D7's meta-inference duality to three axes: +Counterfactual / Markov / Arc). Styles can condition on it: + +- **Focused** style when tension accelerating + direction stable → + converge on the climax event. +- **Exploratory** style when direction shifting → widen candidate + enumeration, the narrative just changed frame. +- **Reflective** style when tension falling + shift complete → + integrate what just happened (NARS revision on recent commits). +- **Deliberate** style when both derivatives high → major arc pivot, + run the full inference pipeline, commit carefully. + +**ONNX training signal (deferred to follow-up).** Every cycle emits +a (state, arc_pressure, arc_derivative) tuple. These are the +training pairs for the ONNX narrative-arc model — the model learns +to predict the next arc_pressure given the current state. Once +trained, it fills the third axis of the meta-inference dispatch. + +**Awareness = noticing the arc change.** Computationally modest +(two subtractions + threshold check per cycle) but architecturally +meaningful: the system observes shifts in its own narrative +reasoning, not just the content. That's what "becoming aware of +shifts in the story arc as actual awareness" means in code — +derivative crossings feed the shader's awareness gate, which +changes which style dispatches, which changes what the system +notices about itself. + +**Files (folded into D9 scope):** +- `crates/lance-graph-contract/src/grammar/arc_predictor.rs` — + add `ArcPressure`, `ArcDerivative`, `is_arc_shift`. Keep zero-dep. + (~40 LOC added to the existing +60.) +- `crates/cognitive-shader-driver/src/engine_bridge.rs` — wire arc + derivative into the awareness bits of MetaWord. (~30 LOC edit.) +- No new crates; same deliverable, expanded scope. + +**Files:** + +- `crates/lance-graph/src/graph/arigraph/triplet_graph.rs` — + `to_onnx()` method (+80 LOC). Uses `prost` or raw `.onnx` protobuf + emission; no runtime dep on `ort` or `tract` in this PR. +- `crates/lance-graph-contract/src/grammar/arc_predictor.rs` — NEW + (+60 LOC). `ArcPredictor` trait, `StatePrediction` struct, + `StatePrediction::margin_above(threshold)` helper. Zero-dep; just + the interface. +- `crates/lance-graph-contract/src/grammar/mod.rs` — re-export. + +**LOC:** ~140 added to the total. Total still one PR. + +**Why ship the interface now even without the model:** the +meta-inference in D7 is defined with 2 axes (CF + Markov). Pushing +the arc predictor to a later PR means the meta-inference dispatch +has to be refactored then. Shipping the trait now lets D7 reserve +the slot, and the follow-up PR just lands the implementation. + +### D7 — Grammar Thinking Styles as Meta-Inference Policies + +**The frame.** The 7 NARS inferences are **permanent logical operators** +(Deduction / Induction / Abduction / Revision / Synthesis / +Extrapolation / Counterfactual). They don't change. What a thinking +style is, is a **meta-inference policy**: given the evidence signals +from an attempted parse, which logical operator fits? + +Meta-inference = inference *about* inference. Reasoning about the +reasoning. The style doesn't just "apply Deduction"; it evaluates +whether Deduction was the appropriate operator given the signal +profile, and if not, meta-reasons which operator to escalate to. + +**Permanent logical core.** The signal-profile → inference dispatch +rules are **axiomatic**, not empirical: + +| Signal from the grammar attempt | Logically implies | +|---|---| +| Morphology unambiguous (e.g. Finnish Inessive `-ssa` "in") | **Deduction** — rule directly applicable | +| ≥ 3 of 8 Pearl SPO 2³ masks plausible | **Abduction** — need best-explanation, deduction can't decide | +| All TEKAMOLO slots fill coherently | **Deduction** closed the parse | +| Any TEKAMOLO slot ambiguous | **Counterfactual Synthesis** — test alternative fillings | +| Markov coherence < threshold at focal | **Abduction** — re-explain this sentence given the flow | +| Novel surface form, no matching template | **Extrapolation** — extend nearest known pattern | +| Conflicting evidence between parses of same claim | **Revision** — merge truths | +| Multiple independent signals agree | **Synthesis** — bind into combined inference | + +These rules are permanent. They don't drift with data. A grammar style +that routes morphology-unambiguous-signal to Abduction is *logically +wrong*, regardless of how many parses it has revised. + +**The two orthogonal reasoning axes (the meta-inference duality).** + +A parse attempt is tested from two independent angles. Their agreement +or disagreement IS the awareness signal. + +``` + PARSE ATTEMPT + │ + ┌─────────────┴─────────────┐ + ▼ ▼ + COUNTERFACTUAL AXIS MARKOV CHAIN AXIS + (within-sentence) (cross-sentence) + │ │ + morphology + TEKAMOLO ±5 context chain + + SPO 2³ causal mask + Mexican-hat kernel + │ │ + enumerates the local scores this parse + alternative space against the discourse + (finite counterfactuals) flow (continuous coherence) + │ │ + ▼ ▼ + "Is this parse the best "Does this parse fit + among its plausible the surrounding flow?" + alternatives?" + │ │ + └──────────┬────────────────┘ + ▼ + JOINT READING: + · both strong → HIGH confidence (Synthesis) + · CF strong, Markov weak → topic shift / novelty at focal + · CF weak, Markov strong → locally ambiguous but contextually committed + → try cross-lingual bundle (Finnish etc.) + · both weak → genuine novelty → escalate (FailureTicket) +``` + +The counterfactual axis is where **heavy-grammar morphology earns its +keep**. Each morphological commitment *eliminates* counterfactual +branches: + +| Language | Surface form | Commits | Counterfactual space | +|---|---|---|---| +| English | "The book on the table" | nothing | 8 SPO 2³ × {Lokal, Modal, Topical} TEKAMOLO = 24 branches | +| Russian | "Книга **на столе**" (Prepositional `-е`) | Lokal slot | 8 × 1 = 8 branches | +| Finnish | "Kirja **pöydällä**" (Adessive `-llä`) | Lokal at-surface | 8 × 1 = 8 branches | +| Russian | "Резать **ножом**" (Instrumental `-ом`) | Modal / means | 8 × 1 = 8 branches | +| German | "mit dem Messer" (Dativ after `mit`) | Modal / means | 8 × 1 = 8 branches | +| Turkish | "masa-**da**" (Locative `-da`) | Lokal | 8 × 1 = 8 branches | + +A morphology-rich language hands you a counterfactual space that's 1/N +the size of English's. The counterfactual axis has less work to do, so +the Markov axis is what decides the remaining ambiguity — and the +Markov axis is where **Counterfactual Synthesis** (NARS inference) +tests alternatives against ±5 coherence. + +**Hydration, not extraction.** The SPO triple isn't just "S, P, O" — +it's **hydrated** with the Pearl 2³ causal mask from the morphology. +The Instrumental `-ом` in "Убил **ножом**" hydrates the SPO +(Killer, Killed, Knife) with mask bit 1 (enabling) committed — the +knife didn't CAUSE directly, it enabled. This hydration happens at +extraction time, no separate causal-inference pass needed. + +``` +Surface: "X убил Y ножом" + morphology: Acc(Y) + Ins(nóž) + ↓ +Extracted SPO: (X, убить, Y) + ↓ +Hydrated: (X, убить, Y) + + Pearl.direct = 1 (X performed the action) + + Pearl.enabling = 1 (knife enabled) + + Pearl.confounding = 0 + → mask = 0b011 = 0x03 + ↓ +Counterfactual space collapsed from 8 → 1 branch +because Instrumental morphology committed the enabling role. +``` + +In English "X killed Y with a knife" — the `with` preposition is a +Wechsel (could be Modal / Instrumental / Comitative). Counterfactual +space stays at 3 branches until Markov coherence or cross-lingual +bundle collapses it. + +**Markov vs Counterfactual: when each is primary.** + +| Situation | Primary axis | Reason | +|---|---|---| +| Heavy morphology, clear discourse | Neither — Deduction closes | Both axes agree trivially | +| Heavy morphology, weird discourse | **Markov primary** | Counterfactual already collapsed; surprise is cross-sentence | +| Light morphology (English), clear discourse | **Counterfactual primary** | ±5 context can't help if sentence itself is ambiguous; must enumerate SPO 2³ × TEKAMOLO branches | +| Light morphology, weird discourse | **Both weak → FailureTicket** | Escalate — neither axis has grip | +| Cross-lingual bundle available | **Bundle collapses CF** | Finnish / Russian morphology from bundled parse commits what English left ambiguous | + +This is what "meta-inference between permanent logical reasoning" +means: the style doesn't just pick a NARS operator — it evaluates +*which axis has grip* on this parse, then picks the operator for that +axis. The permanence is in the axes themselves and their combination +rules; the empirical layer is the prior over which axis wins on the +style's content distribution. + +**Linguistic-precision correction (fix from yesterday's draft).** The +Finnish case table in `grammar-tiered-routing.md` wrote "Accusative +`-n/-t` → Object" — this is a Latinate transplant. Finnish object +marking is actually: + +- Total object: **Nominative** (plural) or **Genitive `-n`** (singular) +- Partial / negated object: **Partitive `-a/-ä`** +- True **Accusative**: only for personal pronouns (`minut`, `sinut`, + `hänet`, `meidät`, `teidät`, `heidät`) + +The grammar-landscape doc (D0) corrects this. Each language's case +table uses its native case inventory, not a forced Latinate mapping. + +**Russian 6 cases — full inventory** (needed for the Russian priority +language per OSINT): + +| Case | Suffix pattern (sg masc / fem / neut) | Role | +|---|---|---| +| Nominative | -ø / -а, -я / -о, -е | Subject (S) | +| Genitive | -а, -я / -ы, -и / -а, -я | Possessor / negated object / partitive | +| Dative | -у, -ю / -е, -и / -у, -ю | Recipient — often TEKAMOLO Kausal indirect ("to X") | +| Accusative | = Nom (inanimate) / = Gen (animate) / -у, -ю / -о, -е | Direct object (O) | +| **Instrumental** | -ом, -ем / -ой, -ей / -ом, -ем | Means / agent in passive — **TEKAMOLO Modal** ("by means of X") | +| Prepositional (Locative) | -е / -е, -и / -е | Governed by `в`/`на`/`о` prepositions — TEKAMOLO Lokal or Temporal | + +Russian Instrumental is exactly the Finnish Adessive `-lla/-llä` +(means/instrument) plus the Finnish Essive `-na/-nä` (role/state) +folded together — it commits to TEKAMOLO Modal by morphology alone. +This is why morphologically-rich languages are easier: one case +ending carries a slot assignment that English would need surrounding +prepositions + word-order to infer. + +Analogous precision needed for every language priority on the OSINT +list: German 4 cases (Nom/Gen/Dat/Akk), Arabic 3 + trilateral root +system, Turkish 6 + agglutinative suffix chain, Japanese particles +(が / を / に / で / へ / と / から / まで), Hebrew no-cases with +root-pattern morphology. Each gets its native table. + +**What drifts (and where awareness lives).** Styles differ in their +**priors over signal-profile frequency** — how often each profile +occurs in the style's observed content distribution. Analytical style +expects clean morphology signals; Exploratory expects ambiguous ones. +These priors revise via NARS based on actual parse outcomes, but the +signal→inference dispatch rules underneath stay axiomatic. + +**So awareness has two layers:** + +1. **Permanent layer** (the logical core): signal-profile → + NARS-inference dispatch table. Shared across all styles. Not + revised by data. Encoded as a pure function, not as configuration. + +2. **Empirical layer** (the priors): each style's expected distribution + of signal profiles on its content. NARS-revised per style based on + parse outcomes. This IS the style's grammar awareness. + +The style's runtime behaviour = permanent dispatch rules × style's +empirical prior × current signal profile. + +Structural parallel: `agi-chat/src/grammar/grammar-awareness.ts` +(237 LOC) implements exactly this separation — the dispatch is +"permanent" via pure TypeScript rules; the `awareness` state is what +the style has learned about its content. + +**New:** `crates/lance-graph-contract/src/grammar/thinking_styles.rs` +(+260 LOC) — three types: + +```rust +/// Static prior loaded from YAML. +pub struct GrammarStyleConfig { + pub style: ThinkingStyle, + pub nars: NarsPriorityChain, // primary + fallback + pub morphology: MorphologyPolicy, // tables, agglutinative + pub tekamolo: TekamoloPolicy, // slot priority, require_fillable + pub markov: MarkovPolicy, // radius, kernel, replay + pub spo_causal: SpoCausalPolicy, // pearl_mask, tolerance + pub coverage: CoveragePolicy, // local_threshold, escalate_below +} + +/// NARS truth values per parameter slot. Mutates at runtime. +/// This is the "awareness" — the style's track record. +pub struct GrammarStyleAwareness { + pub style: ThinkingStyle, + /// Truth per (parameter_axis, value) pair. Updates on each parse. + pub param_truths: HashMap, + /// Aggregate success rate of this style over recent window. + pub recent_success: TruthValue, + /// Count of parses this style has driven. + pub parse_count: u64, +} + +pub enum ParamKey { + NarsPrimary(NarsInference), // did this inference work? + MorphologyTable(MorphologyTableId), // did this table help? + TekamoloSlot(TekamoloSlot), // did this slot fill right? + MarkovKernel(WeightingKernel), // did this kernel resolve? + SpoCausalMask(u8), // did this mask fit? +} + +impl GrammarStyleAwareness { + /// Revise a single parameter's truth after a parse outcome. + pub fn revise(&mut self, key: ParamKey, outcome: ParseOutcome); + + /// Derive a runtime config from prior + awareness. + /// Parameters with low accumulated truth get down-weighted. + pub fn effective_config(&self, prior: &GrammarStyleConfig) + -> GrammarStyleConfig; +} + +pub enum ParseOutcome { + LocalSuccess, // → truth +ε + LocalSuccessConfirmedByLLM, // → truth +2ε + EscalatedButLLMAgreed, // → truth +ε/2 + EscalatedAndLLMDisagreed, // → truth −ε + LocalFailureLLMSucceeded, // → truth −2ε +} +``` + +YAML parser: zero-dep mini-parser reading the subset used by +`grammar_styles/*.yaml` (plain key/value + simple lists, no nesting +beyond one level). Alternatively expose a pure `from_str` taking +pre-parsed `&[(key, value)]` so the contract stays zero-dep and +deepnsm does the YAML read. + +**New:** `crates/deepnsm/assets/grammar_styles/*.yaml` — the starter +catalogue (12 files). Each YAML config grounds a style in the 4 +dimensions: + +```yaml +# analytical.yaml — strict rule-apply, English SVO, case deductive +style: analytical +nars: + primary: Deduction + fallback: Abduction +morphology: + tables: [english_svo, finnish_case_table] # try SVO first + agglutinative_mode: false +tekamolo: + priority: [temporal, lokal, kausal, modal] # TE+LO > KA > MO + require_fillable: true # fail if slots ambiguous +markov: + radius: 5 + kernel: uniform # no anticipation + replay: forward # no backward replay +spo_causal: + pearl_mask: 0x01 # commit to direct causation only + ambiguity_tolerance: 0.1 +coverage: + local_threshold: 0.90 # strict + escalate_below: 0.85 +``` + +```yaml +# exploratory.yaml — counterfactual Wechsel resolution +style: exploratory +nars: + primary: CounterfactualSynthesis + fallback: Abduction +morphology: + tables: [english_svo, finnish_case_table, russian_case_table] + agglutinative_mode: true # peel suffixes R→L +tekamolo: + priority: [modal, kausal, lokal, temporal] # explore MO first + require_fillable: false # tolerate gaps +markov: + radius: 5 + kernel: mexican_hat # anticipation on + replay: both_and_compare # test both directions +spo_causal: + pearl_mask: 0xFF # all 8 causal configs plausible + ambiguity_tolerance: 0.4 +coverage: + local_threshold: 0.70 # permissive, try hard before escalating + escalate_below: 0.50 +``` + +12 starter configs: analytical / convergent / systematic / creative / +divergent / exploratory / focused / diffuse / peripheral / intuitive / +deliberate / metacognitive. Each is ≤ 40 lines YAML. + +**Edit:** `crates/deepnsm/src/ticket_emit.rs` (+60 LOC) — load style's +`effective_config` (prior ⊕ awareness) at dispatch; populate +`FailureTicket::attempted_inference` from the style's NARS-revised +top-ranked inference, not the static YAML primary. On ticket +resolution (LLM returns, or local success confirmed), call +`awareness.revise(ParamKey::NarsPrimary(...), outcome)`. + +**Edit:** `crates/deepnsm/src/markov_bundle.rs` (+50 LOC) — `MarkovBundler` +reads kernel shape + radius from the active style's effective config; +on bundle success/failure, revise +`ParamKey::MarkovKernel(kernel)`. + +**Edit:** `crates/lance-graph-contract/src/grammar/mod.rs` — re-export +`GrammarStyleConfig`, `GrammarStyleAwareness`, `ParamKey`, +`ParseOutcome`. + +**Awareness lifecycle:** + +1. **Bootstrap:** load YAML prior → `GrammarStyleConfig`. +2. **Initialize:** construct `GrammarStyleAwareness` with `param_truths` + at neutral `TruthValue { f: 0.5, c: 0.01 }` (no evidence yet). +3. **Per-parse:** derive `effective_config = prior ⊕ awareness`; run + parse; emit outcome; call `awareness.revise(...)` for each + parameter that fired. +4. **NARS revision rule** (already in contract): + `f_new = (f_old × c_old + f_observed × c_observed) / (c_old + c_observed)` + `c_new = (c_old + c_observed) / (c_old + c_observed + 1)` +5. **Promotion:** when `recent_success.c > 0.8 && recent_success.f > 0.75` + the style is "earned its confidence" and its effective config + diverges more aggressively from the prior. +6. **Persistence** (out of scope for this PR, flagged): serialize + `GrammarStyleAwareness` to `BindSpace` row or sled KV so awareness + survives session boundaries. Next PR. + +**Grounding summary** (the 4 axes per style): + +| Axis | What the style picks | +|---|---| +| **SPO 2³** | Which Pearl causal-mask bits to commit to (0x01 = direct only; 0xFF = all plausible); ambiguity tolerance | +| **Morphology** | Which case tables to consult, in what order; agglutinative suffix-peeling on/off | +| **TEKAMOLO** | Slot priority order; whether to require all slots fillable or tolerate gaps | +| **Markov bundling** | Radius (default 5); kernel shape (uniform / mexican_hat / gaussian); replay direction | + +The style IS the grammar-reasoning policy. The YAML makes it editable +without touching Rust. + +## Critical Files + +| File | Change | LOC | +|---|---|---| +| `.claude/knowledge/grammar-landscape.md` | NEW | +300 | +| `crates/deepnsm/Cargo.toml` | features | +10 | +| `crates/deepnsm/src/parser.rs` | coverage branch | +30 | +| `crates/deepnsm/src/ticket_emit.rs` | NEW + style-aware emission + revise on outcome | +180 | +| `crates/deepnsm/src/triangle_bridge.rs` | NEW | +220 | +| `crates/deepnsm/src/markov_bundle.rs` | NEW + style-driven kernel + revise | +270 | +| `crates/deepnsm/src/trajectory.rs` | NEW | +80 | +| `crates/deepnsm/src/lib.rs` | re-exports | +20 | +| `crates/deepnsm/assets/grammar_styles/*.yaml` | 12 YAML configs | +480 | +| `crates/lance-graph-contract/src/grammar/context_chain.rs` | reasoning ops | +140 | +| `crates/lance-graph-contract/src/grammar/role_keys.rs` | NEW | +160 | +| `crates/lance-graph-contract/src/grammar/thinking_styles.rs` | NEW — config + awareness + revise | +260 | +| `crates/lance-graph-contract/src/grammar/mod.rs` | re-export | +10 | +| `crates/deepnsm/tests/integration.rs` | NEW | +110 | +| `crates/deepnsm/tests/ticket.rs` | NEW | +40 | +| `crates/deepnsm/tests/triangle.rs` | NEW | +60 | +| `crates/deepnsm/tests/styles.rs` | NEW — YAML load + awareness revision + effective_config drift | +140 | +| `crates/deepnsm/benches/parse.rs` | NEW | +40 | + +**Total:** ~2,490 LOC, 18 files + 12 YAML configs, one PR. + +## Reused (not rebuilt) + +- Contract: `FailureTicket`, `PartialParse`, `CausalAmbiguity`, + `TekamoloSlots`, `WechselAmbiguity`, `FinnishCase`, `NarsInference`, + `ContextChain`, `SentenceCrystal`, `ContextCrystal`, + `CrystalFingerprint` (sandwich), `Structured5x5` bipolar. +- `lance-graph-cognitive::grammar::{GrammarTriangle, NSMField, + CausalityFlow, Qualia18D}` (1,929 LOC shipped). +- `ndarray::hpc::vsa::{vsa_bind, vsa_bundle, vsa_permute, + vsa_similarity, vsa_hamming}`. +- `ndarray::hpc::bitwise::hamming_batch_raw`. + +## The NARS + Morphology + TEKAMOLO Triad (unified mechanism) + +The three load-bearing concepts compose into a single inference +machine. Each layer supplies what the others need: + +``` + ┌──────────────── 144 VERB-ROLE TAXONOMY ────────────────┐ + │ 12 semantic families × 12 tense/aspect variants. │ + │ Each verb carries a prior over which TEKAMOLO slots │ + │ it expects filled (e.g. TRANSFER needs Kausal + Lokal; │ + │ STATE needs Modal; MOTION needs Lokal + Modal). │ + └────────────┬────────────────────────────────────────────┘ + │ verb-identification (DeepNSM FSM + COCA) + ▼ + ┌──────────── MORPHOLOGY (per-language cases) ────────────┐ + │ Russian Inst -ом → Modal (means/instrument) │ + │ Finnish Ade -lla → Modal (at/by) │ + │ Finnish Ine -ssa → Lokal (in/inside) │ + │ German Dat + mit → Modal │ + │ English «with» → Wechsel(Modal | Comitative | Topical) │ + └────────────┬────────────────────────────────────────────┘ + │ case-table lookup per token + ▼ + ┌──────────── TEKAMOLO SLOT CANDIDATES ───────────────────┐ + │ Each token's morphology proposes a slot + truth. │ + │ Unambiguous morphology → single slot with high truth. │ + │ Ambiguous (English prep, case syncretism) → multiple. │ + └────────────┬────────────────────────────────────────────┘ + │ propose + ▼ + ┌──────────── NARS INFERENCE OVER SLOTS ──────────────────┐ + │ Deduction : verb's slot-prior + morphology-committed │ + │ slot agree → commit with high truth. │ + │ Induction : N past sentences had same (verb, morphology │ + │ → slot) → reinforce the pattern's prior. │ + │ Abduction : ambiguous morphology → pick slot that best │ + │ explains the verb's prior + Markov context. │ + │ Revision : another parse of same sentence (cross- │ + │ lingual or re-read) → merge truths on slots.│ + │ Synthesis : multiple independent signals (morphology + │ + │ word-order + context) → bind into single │ + │ slot assignment. │ + │ Counterfactual : test alternative slot fillings against │ + │ ±5 Markov coherence + graph story context. │ + │ Extrapolation : novel morphology on known verb family → │ + │ extend by analogy. │ + └────────────┬────────────────────────────────────────────┘ + │ + ▼ + committed slot assignment with NARS truth; + role-indexed VSA bundling (D5) lands content in slot's slice. +``` + +**The reason 144 works.** The verb's slot-prior is what turns +TEKAMOLO from a 4-slot schema into a structured expectation: + +| Verb family (12) | Expected TEKAMOLO profile | +|---|---| +| BECOMES | Temporal + Modal | +| CAUSES | Subject + Object + Kausal | +| SUPPORTS | Object + Modal | +| CONTRADICTS | Object + Modal (adversative) | +| REFINES | Object + Modal | +| GROUNDS | Object + Lokal | +| ABSTRACTS | Object | +| ENABLES | Object + Kausal | +| PREVENTS | Object + Kausal (negated) | +| TRANSFORMS| Object + Temporal + Modal | +| MIRRORS | Object + Modal | +| DISSOLVES | Object + Temporal | + +× 12 tense/aspect/mood variants (present / past / future / perfect / +continuous / pluperfect / future-perfect / habitual / potential / +imperative / subjunctive / gerund) → 144 verb-role cells, each with +its own TEKAMOLO slot prior. Parsing a verb looks up its row; +morphology fills its columns; NARS inference reconciles them. + +**This is what turns parse into table lookup + truth aggregation.** +No search, no inference-time rule-walk — the (verb × tense) cell +IS the slot-filling policy, the morphology IS the slot-filler, and +NARS is the truth-merge operator. The 3,125 Structured5x5 cells are +large enough to index this space (5^5 > 144 × 10 × 10 for verb × +slot × value). + +### D11 — Bundle + Perturb Cognitive Stack (generative counterpart, interface only) + +**The core claim.** A generative cognitive stack doesn't need +QKV attention + up/down MLP + learned query. The same effect — +asking "what does this state want to emerge into?" — is a canonical +VSA operation when you already have role-indexed bundling + an +ONNX arc model: + +| Transformer primitive | Our substitute | Why it works | +|---|---|---| +| **Query vector (Q)** — what am I looking for? | The epiphany crystal itself (phase + magnitude + committed facts bundle) | The epiphany IS the query; no separate learned weights needed | +| **Key matrix (K)** — what's available? | Role-indexed slices of the triplet graph's story_vector + ±5 trajectory | Already present in D8 tier-1.5; slices ARE the keys | +| **Value matrix (V)** — what content comes back? | Role-unbound content from the slice | Unbind IS the retrieval | +| **Up-projection MLP** — expand to higher dim | `vsa_permute` by epiphany's phase-tag | Permutation widens the subspace without a learned projection | +| **Nonlinearity** — break linear combinatorics | **ONNX arc model perturbation** — apply the bundle as delta to the trained arc graph | The arc model IS the nonlinearity; input delta = perturbation | +| **Down-projection** — back to hidden-dim | Unbind via role key | XOR unbind recovers the role-specific content at the original dim | +| **Query-response (asking)** | **Bundle-perturb-unbind** | End-to-end: bundle epiphany with state → perturb ONNX arc → unbind target role → emergent content | + +**The stack for "what does this epiphany want to emerge?":** + +``` +epiphany_crystal (from D8: phase + magnitude + committed-facts bundle) + │ + ▼ vsa_bundle(epiphany, current_trajectory, story_vector) +state_bundle + │ + ▼ vsa_permute(state_bundle, epiphany.phase) — up-project equivalent +perturbed_input + │ + ▼ ONNX arc model forward pass with perturbed_input + │ (the learned arc is the "MLP nonlinearity") +emergent_state + │ + ▼ vsa_unbind(emergent_state, RoleKey::for_target(task)) +emerged_direction — what the epiphany "wants" to unfold +``` + +**Zero learned projections on our side.** The role keys (D6) are +canonical fingerprints; the bundle operations are algebraic; only +the ONNX arc model is learned — and it's orders of magnitude smaller +than a full transformer because it only has to predict *arc phase +and magnitude transitions*, not token probabilities. + +**Interpretability bonus.** Every step of the generative stack is +inspectable: +- The query is a crystal with explicit phase + magnitude + fact refs. +- The bundle is composable (you can add / remove contributors and + see the effect). +- The perturbation is a small arc-model input delta. +- The emerged direction is role-tagged content (not raw token soup). + +At every stage you can ask "why this next state?" and trace back +through bundle contributors + arc transitions. The stack is legible +in a way transformer internals are not. + +**"What it wants to emerge" is an operation, not a metaphor.** The +epiphany's phase direction under ONNX-arc perturbation picks out the +narrative trajectory that most consistently continues from the +committed contradiction. It's not generation guided by gradients on +token probabilities — it's arc continuation guided by phase +consistency on an already-learned narrative graph. + +**Shipping scope for this PR (interface only; generation deferred).** + +1. **Interface in the contract:** + ```rust + /// Ask what an epiphany wants to emerge into, given current state. + pub trait EpiphanyEmergence { + fn emerge( + &self, + epiphany: &Contradiction, + trajectory: &Trajectory, + graph: &TripletGraph, + target_role: GrammaticalRole, + ) -> EmergedDirection; + } + + pub struct EmergedDirection { + /// Role-unbound content bundle at target role. + pub content: Box<[f32; 10_000]>, + /// Predicted phase / magnitude of the emerged state. + pub arc_continuation: ArcPressure, + /// NARS truth that the emergence is coherent with history. + pub truth: TruthValue, + } + ``` + +2. **Reference implementation (stub)** — `DefaultEmergence` that + does the bundle + permute + (identity ONNX, since we don't have + a trained arc yet) + unbind. Returns a deterministic + `EmergedDirection` that's inspectable but not predictive until + the ONNX model lands. + +3. **Example test** on Animal Farm epiphany from D10: + - Input: ch. 3 epiphany "Napoleon takes puppies in secret," + current trajectory = ch. 1-3. + - Target role: FUTURE_EVENT (new role key). + - Emergence should produce a direction whose role-unbound + content overlaps (Hamming < 0.45) with ch. 5's actual facts + once the ONNX arc is trained in a follow-up PR. + - Until then, the test asserts the interface produces + deterministic output, not predictive correctness. + +**Files (folded into D9's scope since it shares the ONNX runtime):** +- `crates/lance-graph-contract/src/grammar/emergence.rs` — NEW + (~100 LOC). `EpiphanyEmergence` trait + `EmergedDirection` struct. +- `crates/lance-graph-contract/src/grammar/mod.rs` — re-export. +- `crates/deepnsm/src/emergence_impl.rs` — NEW (~80 LOC). + `DefaultEmergence` stub implementation. +- `crates/deepnsm/tests/emergence.rs` — NEW (~40 LOC). Interface + determinism test on Animal Farm ch. 3 epiphany. + +**LOC:** ~220 LOC added. Still one PR. + +**What this closes.** The stack becomes symmetric — D2-D8 extract +from text, D9-D11 generate back into text. Both sides use the same +VSA primitives; the only asymmetry is that extraction doesn't need +the ONNX arc model while generation does. Awareness (D9 derivatives) +drives dispatch; epiphanies (D8 + D10) drive emergence; validation +(D10) holds both accountable. No QKV, no MLP, no separate query +vectors — canonical operations all the way down. + +### D10 — Forward-Validation Harness (epiphanies as predictions, NARS-tested against future arc) + +**The proof-test.** Every epiphany the system records is implicitly a +prediction — "this contradiction carries meaning, and therefore the +arc will continue to deviate in this direction." The rest of the +text is ground truth. Forward-validation closes the loop: + +``` +Chapter 1-5 prefix + ↓ full extraction pipeline + ↓ commit facts to graph + ↓ fire N epiphanies (Staunen markers with phase + magnitude) + ↓ emit arc_derivatives at M cycles + ↓ + ┌───────────────────┘ + ▼ + For each epiphany and each arc_shift: + record the prediction: + - direction (phase) + - magnitude + - which facts / entities it implicates + +Chapter 6-10 suffix + ↓ full extraction pipeline + ↓ commit more facts + ↓ for each recorded epiphany / arc_shift: + ↓ check whether the committed suffix facts + ↓ confirm or refute the prediction + ↓ NARS revision on the recorded prediction: + f = confirmed ? raise : lower + c = c + c_new (always rises — new evidence seen) +``` + +**The measurement is standard NARS.** An epiphany's belief was +`TruthValue { f₀, c₀ }` when it fired. Future evidence arrives with +`TruthValue { f_obs, c_obs }` where `f_obs = 1` if confirmed, `0` if +refuted. Standard revision rule: + + f_new = (f₀·c₀ + f_obs·c_obs) / (c₀ + c_obs) + c_new = (c₀ + c_obs) / (c₀ + c_obs + 1) + +Applied retroactively, this revises the epiphany's truth against its +own future. The system LEARNS its awareness accuracy from the story +itself — no external labels needed. + +**Ground-truth labels on Animal Farm (hand-authored, < 200 lines).** + +| Chapter | Ground-truth epiphany | Expected direction | +|---|---|---| +| 2 | Animalism's 7 Commandments drafted | Baseline, arc start | +| 3 | Napoleon takes puppies in secret | **Prediction:** Napoleon will use dogs for coercion | +| 4 | Battle of Cowshed, Snowball shines | **Prediction:** Snowball's rise threatens Napoleon | +| 5 | Snowball expelled by dogs | Confirms ch. 3 prediction; arc shifts | +| 6 | Squealer revises the "Snowball hero" story | **Prediction:** narrative unreliability escalates | +| 7 | Commandments silently amended (sleeping-in-beds) | Confirms ch. 6; wisdom-magnitude spike | +| 8 | Boxer works himself to collapse | **Prediction:** Boxer will be betrayed | +| 9 | Boxer sold to knacker | Confirms ch. 8 ("Sundering of the loyal") | +| 10 | "All animals are equal BUT some more than others" | Max-magnitude contradiction with ch. 2; arc completes | + +**Metrics produced by the harness:** + +| Metric | What it measures | +|---|---| +| **Epiphany precision** | Of N epiphanies fired, how many were confirmed by future text? | +| **Epiphany recall** | Of M ground-truth beats, how many did the system flag as epiphanies? | +| **Arc-shift detection F1** | Did `d(phase)/dt` / `d(magnitude)/dt` spikes align with actual story pivots? | +| **Prediction direction accuracy** | Of confirmed epiphanies, was the predicted phase direction aligned with the suffix's factual direction? | +| **Retroactive-revision monotonicity** | NARS confidence should rise on every observation regardless of direction; truth (f) should converge to the ground-truth polarity | + +**Files:** + +- `crates/deepnsm/tests/animal_farm.rs` (NEW, ~220 LOC) — load + public-domain Animal Farm text, run the pipeline end-to-end on + 10 breakpoints, assert the metrics above. +- `crates/deepnsm/assets/animal_farm/ground_truth.yaml` (NEW, + ~200 lines) — hand-labelled beat list per chapter. +- `crates/lance-graph/src/graph/arigraph/episodic.rs` — add + `retroactive_revise(prediction_id, observation)` to expose NARS + revision on stored epiphanies (~40 LOC). + +**Benchmark targets:** + +- Epiphany precision ≥ 0.80 (most fired epiphanies should be confirmed). +- Epiphany recall ≥ 0.60 (catch most major beats). +- Arc-shift F1 ≥ 0.70 on ground-truth-labelled pivots. +- Prediction direction accuracy ≥ 0.85 on confirmed epiphanies. +- End-to-end metric-emitting run ≤ 10 minutes on a single core + (40 K words × <10 µs local + occasional LLM tail). + +**Why this ships with the PR, not later.** Without forward-validation +the awareness/epiphany claims are architectural prose. With it, the +PR description reports measured numbers on a canonical literary text, +and every follow-up PR can regression-test against the same benchmark. +Staunen / arc-shift / epiphany stop being metaphors and become +Spearman-ρ-grade measurements. **This is also what turns the arc- +awareness into genuine self-testing cognition** — the system's own +predictions are held accountable by the story that made them. + +## Challenges to the Universal-Grammar Claims (honest pushback) + +Before shipping, it's worth stress-testing the theoretical scaffolding. +Several load-bearing claims have real weaknesses. + +### C1 — "Morphology-heavy languages are easier" assumes textbook grammar + +The 98% Finnish vs 85% English coverage number works on textbook +Finnish. **Real-world Finnish** has: +- **Colloquial clipping** (`-ssa` drops to `-s` in speech and casual + writing): *kaupassa* → *kaupas*. +- **Clitic stacking** (`-kin`, `-kaan`, `-han`): *kirjakinpa* layers + three clitics onto one stem. +- **Dialect variation**: Savonian Finnish rewrites morphology + systematically; Western dialects preserve archaisms. +- **Vowel harmony interacting with gradation**: the table must handle + `-ssa` vs `-ssä` vs `-sta` vs `-stä` correctly; mis-segmenting + drops accuracy hard. + +Turkish agglutination is worse: *evlerimizdeydiler* = "they were at +our houses" = 6 stacked morphemes. Suffix segmentation is its **own** +ambiguity problem. Our D5 case table doesn't handle suffix order +disambiguation; the 98% number assumes clean segmentation. + +**What breaks:** the coverage gain from heavy morphology shrinks on +real text. Expect 95% on Finnish literary prose, 85-90% on +conversational Finnish, <80% on Turkish agglutination without a +dedicated morpheme-peeler. + +### C2 — Russian case syncretism: the "case" alone doesn't commit + +Russian masculine inanimate Accusative = Nominative. Feminine +Genitive singular = Nominative plural for many nouns. The ending +doesn't commit the case — you need gender + animacy + number + verb +context to disambiguate. The "one case = one TEKAMOLO slot" mapping +in D5 is a simplification that will produce wrong slot assignments +on ~15-20% of Russian NPs. + +**What breaks:** Russian coverage is closer to 88% than 92%. The +table needs case-syncretism resolution rules (gender × animacy × +number) to hit the higher number. + +### C3 — Cross-lingual bundling assumes semantically-parallel sources + +The "XOR-bundle EN+FI of the same entity, get disambiguation for +free" claim requires **translations**, not just mentions. For Animal +Farm we have authentic translations. For OSINT we'd have to rely on +machine-translated or independently-written sources — which don't +semantically align at the clause level. Bundling non-parallel texts +about the same entity averages noise, not meaning. + +**What breaks:** the cross-lingual shortcut works for canon literature +(Animal Farm, Wikidata entries) but NOT for news OSINT where no +parallel translation exists. Falls back to monolingual parsing plus +LLM disambiguation for the 10% tail. + +### C4 — ±5 window is arbitrary; literary text violates it + +Why ±5? No empirical justification was presented. Animal Farm has +chapter-spanning references ("as we agreed at the meeting in the +barn" — ch. 6 referring to ch. 1). ±5 has zero chance of reaching +chapter 1 from chapter 6. + +The D8 story-context bridge handles it, but that's a fallback +mechanism for what might actually be the *common* case in long-form +text — not the 5-10% exception. + +**What breaks:** the ±5 default is wrong for literary corpora. Needs +to be adaptive (widen when local coherence is low) or much larger +by default. Our 85% local coverage target may already assume the +bridge fires frequently. + +### C5 — Counterfactual threshold (0.55) is a continuum, not a split + +Epiphany vs error-correction is a useful conceptual distinction but +the real distribution of `loser_independent_support` is continuous. +A 0.55 cutoff turns a gray zone into two discrete classes. Many real +counterfactuals land at 0.45-0.65 — mis-classified in either +direction. + +Also **circularity**: "independent support" for the loser means +"previously committed facts that agree with the loser." If we +already committed the loser's reading earlier (via Napoleon's +propaganda), the graph naturally supports the loser, and we flag it +as epiphany — but it might actually be error compounding across +episodes. + +**What breaks:** the binary split needs to become a continuous +disposition score with three regions: high-confidence-winner (commit +only), high-support-loser (epiphany preserve), middle band (escalate +to LLM). The middle band might be 30-40% of all counterfactuals. + +### C6 — 90-99% coverage is a projection, not a measurement + +The "90-99% local, 1-10% LLM" tiering comes from: +- COCA 4096 = 98.4% of running **tokens** (not sentences). +- FSM handles 85% of English SVO **sentences** (different metric). +- Heavy-morphology languages: 95-98% (claimed, not measured). + +No harness has been run on any corpus to confirm that the joint +DeepNSM + grammar triangle + Markov + failure-ticket pipeline +actually hits 90%. The number is a stitched-together estimate. + +**What breaks:** until Animal Farm actually runs through and we +measure, the tiering claim is marketing. The PR should ship with +the measured number, whatever it is. + +### C6b — Research standing: what's established vs novel + +**Established in the literature (validates our direction):** + +| Paper | Contribution | +|---|---| +| [arxiv 2003.05171](https://arxiv.org/abs/2003.05171) — "VSA for Context-Free Grammars" (2020) | Chomsky-normal-form CFGs fully encodable in VSA via role-filler binding; recursive mapping of phrase-structure trees to Fock-space vectors; representation theorem proved. **This is the theoretical foundation for our approach.** | +| [arxiv 2111.06077](https://arxiv.org/abs/2111.06077) / [2112.15424](https://arxiv.org/abs/2112.15424) — HDC/VSA Surveys Part I+II | Canonical role-binding (XOR / circular convolution / elementwise multiply), superposition, permutation are the three standard operations. Exactly our bind / bundle / permute. | +| [arxiv 2512.14709](https://arxiv.org/html/2512.14709) — "Attention as Binding" | Transformer attention reinterpreted through VSA role-filler binding. Parallels our bgz-tensor attention-as-lookup. | +| [arxiv 2509.25045](https://arxiv.org/html/2509.25045) — "Hyperdimensional Probe" | LLM residual streams projected into interpretable VSA concepts. Parallel mechanism to our grammar-awareness. | +| [arxiv 2408.10734](https://arxiv.org/html/2408.10734) — "Vector Symbolic OSINT Discovery" | VSA applied directly to OSINT. Validates the OSINT vertical. | + +**What's novel in our combination (not published):** + +- **NSM 65 primes + VSA** — Wierzbicka's semantic-primes framework + encoded as role-filler binding in 10K VSA space. No published + paper combines these. +- **TEKAMOLO slot filling via case-morphology binding** — German + grammar-pedagogy template applied as VSA role-keys with Finnish / + Russian case endings as the filler commits. Novel. +- **NARS truth on VSA role-filler bindings** — truth revision at the + binding level, not just at the entity level. Novel combination. +- **Crystal-mode vs Quantum-mode duality** for memory consolidation + — structured (Markov SPO) vs holographic (phase-tagged residual) + on the same 10K substrate. Not in the surveys. +- **Cross-linguistic superposition as disambiguation mechanism** — + bundling parses from EN + FI + RU + DE via VSA to let heavy- + morphology languages disambiguate what English leaves ambiguous. + Novel pitch. +- **Grammar-tiered routing (local VSA 90-99 % + LLM 1-10 %)** with + structured FailureTicket (SPO 2³ × TEKAMOLO × Wechsel) as a + meta-inference reason trace. Novel architecture. +- **Counterfactual outcomes split into epiphany vs error-correction + classes** preserving narrative dissonance — novel distinction for + allegorical / propagandistic text (Animal Farm). + +**Practical upshot:** we're standing on a theoretically-proven +foundation (VSA-CFG encoding works) and adding several novel +combinations on top. The foundation paper is from 2020 and cites the +open question of *practical at-scale grammar extraction from VSA*; +our stack is one concrete answer. + +### C7 — NSM and TEKAMOLO are contested in linguistics + +- **NSM 65 primes** — Wierzbicka's framework is cited by cognitive + science and contested in mainstream linguistics. Universality + claims don't survive empirical testing on polysynthetic languages + (Mohawk, Inuit). Some "primes" are culturally loaded (the English + word for what's meant to be a universal). +- **TEKAMOLO** is a German grammar-pedagogy mnemonic, not a + cross-linguistic universal. Arabic has "hal" (state / accompaniment + adverbial) that doesn't fit the 4-slot schema. Mandarin "bǎ" + construction rearranges transitivity in ways TEKAMOLO can't + describe. +- **Chomskyan UG** — Tomasello, Evans & Levinson argue UG is + empirically weak. Building on it is philosophically risky. + +**What breaks:** the universal-grammar ideas are scaffolding for a +practical extraction pipeline, not a claim about linguistic +universals. The D0 doc should state this explicitly — TEKAMOLO is +a *useful slot template*, not a *linguistic universal*. Same for the +144-verb taxonomy (numerologically chosen, not empirically derived). + +### C8 — Named-Entity gap is the actual blocker + +Already flagged in `grammar-tiered-routing.md` as the biggest miss +(~90% of OSINT is proper nouns). COCA 4096 has zero coverage of +Altman, Anthropic, Riyadh. Every fingerprint collision there +fragments the graph. + +**What breaks:** Without a NER pre-pass + Wikidata/Wikipedia entity +linking, the 90% coverage claim fails on any realistic OSINT input. +This is out-of-scope for the D2-D8 PR but blocks the OSINT demo. +Needs a follow-up NER PR before the OSINT vertical ships. + +### C9 — Abduction-threshold unbundle may compound errors + +If Abduction confidence is miscalibrated (i.e., the threshold 0.88 +doesn't reliably predict ground-truth correctness), promoting +Abductive conclusions to the graph as committed facts **encodes +systematic errors**. Each subsequent coref escalation reads those +errors as ground truth, reinforcing them. + +**What breaks:** the confidence calibration of NARS-on-grammar hasn't +been measured. The 0.88 threshold is inherited from PR #208 without +empirical tuning for this domain. First Animal Farm run may need +threshold re-calibration or an introspection step that audits +recently-unbundled facts. + +### Summary of mitigations + +| Challenge | Mitigation in this PR | Deferred | +|---|---|---| +| C1 morphology colloquial | Start with literary-grade text (Animal Farm); flag as known-textbook baseline | Dialect / agglutination suffix-peeler — future PR | +| C2 case syncretism | D6 role keys include gender-gated variants for Russian | Full syncretism rules — follow-up | +| C3 non-parallel texts | Use Animal Farm authentic translation; flag news as needing LLM tail | OSINT bundle quality — future work | +| C4 ±5 inadequate | D8 story context bridge; make radius a style parameter in D7 | Adaptive-radius selection — future | +| C5 continuous disposition | Ship with 3-region (commit / epiphany / escalate) not 2-region | Calibrated thresholds per corpus — follow-up | +| C6 unmeasured coverage | Animal Farm benchmark IS the measurement | - | +| C7 contested linguistics | D0 doc explicitly states "useful templates, not universals" | - | +| C8 NER gap | Flagged as blocker; D2 FailureTicket emits COCA-miss as routing signal | Dedicated NER pre-pass PR | +| C9 Abduction calibration | Emit Abduction confidence distribution in test output for first run | Per-domain threshold tuning — follow-up | + +None of these kill the architecture. Several downgrade the +quantitative claims; all sharpen what the PR actually demonstrates. + +## Out of Scope + +- Path 2 (holographic residue at leaf). +- CausalityFlow TEKAMOLO extension (modal/local/instrument) — deferred. +- Phase tags, Bell-S>2, ladybug quantum 9-op set. +- Active multi-lingual parsers (EN+FI+RU+TR). Keys exist; parsers later. +- 200–500 YAML TEKAMOLO templates per language (future training). +- Named Entity gap (biggest OSINT blocker — pre-parser NER layer, separate PR). +- Cockpit Cypher, chess vertical. +- FP_WORDS=160 migration (H6), Crystal4K persistence (H10), Int4State + upper-nibble (H8), Glyph5B wide-container (H9). + +## Verification + +1. `cargo test -p deepnsm` — base zero-dep passes. +2. `cargo test -p deepnsm --features contract-ticket` — ticket tests pass. +3. `cargo test -p deepnsm --features grammar-triangle` — triangle bridge tests pass. +4. `cargo test -p lance-graph-contract` — 112 + 10 new → 122 (6 context_chain + role_keys + 4 thinking_styles). +5. `cargo bench -p deepnsm parse` — median ≤ 10 µs (FSM path). +6. `cargo bench -p deepnsm parse --features grammar-triangle` — ≤ 50 µs. +7. Property: same SPO, different temporals → Hamming ≥ 0.15 × 10 000. +8. Property: Wechsel-ambiguous + ±5 context → `disambiguate` margin > 0.1, no LLM. +9. Property: Mexican-hat weighting monotone by distance from focal. +10. `cargo check -p deepnsm --no-default-features` — zero-dep preserved. +11. **NARS-awareness property:** load analytical-style prior; feed 50 simulated parse outcomes favouring `NarsInference::Abduction`; verify `effective_config.nars.primary == Abduction` (awareness drifted from YAML-defined Deduction). +12. **NARS-awareness property:** 50 opposing outcomes → `recent_success.c` drops below 0.3 (low-confidence style, ready for escalation). +13. **NARS-awareness property:** revision is monotone under NARS rule — repeated positive outcomes raise `f` and `c`; repeated negative raise `c` but lower `f`. +14. **Awareness persistence** test skipped in this PR (persistence is follow-up) — but ensure `GrammarStyleAwareness` is `Clone + Debug` so snapshot/restore is trivial to add. +15. **Coreference resolution (the integration target):** + - `cargo test -p deepnsm --features grammar-triangle test_coref` + - 10-sentence English paragraph with 5 pronouns ("it" / "he" / "she" / "they" / "that"): each resolves to correct antecedent via joint CF + Markov scoring, no LLM call. + - Russian dropped-subject paragraph with 5 verb-only sentences: each resolves via morphological agreement + Markov axis; 95%+ accuracy. + - Ambiguous case where CF axis and Markov axis disagree → `FailureTicket` emitted with `recommended_next = Abduction` and the candidate disagreement surfaced as `WechselAmbiguity` (since pronouns ARE dual-role tokens). + - Cross-lingual bundle: same paragraph in EN + FI. Finnish morphology commits some pronouns that English leaves ambiguous; XOR-bundle improves English resolution accuracy by ≥ 5 %. + +## Branch / PR + +- New branch: `claude/deepnsm-markov-context-bundling` off main. +- Single PR, description cites the 5 prerequisite knowledge docs and + today's lossiness-epiphany table. +- Calls out: LLM cost avoided, morphology-rich languages easier not + harder, 200–500 YAML templates as the next milestone. + +## Post-Ship State + +- DeepNSM parses ≤ 10 µs / ≤ 50 µs (no triangle / with triangle) on + 90–99 % of traffic. +- Trajectory fingerprints carry ±5 context; NARS reasons about flows, + not isolated sentences. +- FailureTicket cleanly emitted with SPO×2³×TEKAMOLO×Wechsel + decomposition for the 1–10 % tail. +- Canonical role keys with slice addressing available. +- Grammar landscape documented. + +Path 2 (holographic residue), CausalityFlow extension, YAML template +training, and Named Entity NER layer land on top in subsequent PRs. diff --git a/CLAUDE.md b/CLAUDE.md index acfa3128..58505af9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -36,6 +36,34 @@ covering the A2A two-layer model, governance rules, and how this workspace's conventions diverge from official Claude Code docs. Read once to grok; then stop re-deriving across sessions. +### Prior art — reference before writing new docs + +This workspace accumulated substantial curated content across +prior sessions. Before drafting a new `.claude/*.md` or proposing +a new architectural direction, grep these: + +- **`.claude/prompts/`** (41 files) — scoped session / probe / + handover / research prompts. See `SCOPED_PROMPTS.md` as index. +- **`.claude/plans/`** + **`.claude/knowledge/INTEGRATION_PLANS.md`** + — versioned integration plans (APPEND-ONLY index; prior versions + retained with Status annotation). +- **`.claude/*.md`** (61 top-level docs) — calibration reports, + session handovers, epiphanies, integration-plan snapshots, + audits, inventory maps, invariant matrices. Examples: + `SESSION_CAPSTONE.md`, `INTEGRATIONSPLAN_2026_04_01.md`, + `INTEGRATION_SESSIONS.md`, `INVENTORY_MAP.md`, + `HANDOVER_NEXT_SESSION.md`, `KNOWLEDGE_SYNC_SIGNED_SESSION.md`. +- **`.claude/knowledge/*.md`** (newer, structured) — with + `READ BY:` headers + Knowledge Activation triggers. +- **`.claude/agents/*.md`** (19 specialists + 5 meta-agents) — see + `README.md` for function inventory, `BOOT.md` for orchestration. +- **`.claude/hooks/*.sh`** — SessionStart + PostCompact context + injectors. +- **`.claude/skills/cca2a/`** — the pattern explanation skill. + +**Rule:** grep the existing ~100 files before writing a new one. +Most architectural concerns have prior art in this workspace. + --- ## Agent-to-Agent (A2A) Orchestration — Two Layers From bedd4a6a400e2e6d2cc43c5627d3ab0d7a1bfaea Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 19 Apr 2026 11:51:10 +0000 Subject: [PATCH 15/18] =?UTF-8?q?feat(knowledge):=20STATUS=5FBOARD.md=20?= =?UTF-8?q?=E2=80=94=20deliverable-level=20dashboard=20+=20prior-art=20aud?= =?UTF-8?q?it?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cross-deliverable status view that fills the gap between INTEGRATION_PLANS.md (plan-level) and PR_ARC_INVENTORY.md (per-PR history). Status / PR columns are the only mutable fields; title + plan-version + scope are immutable. Sections: - elegant-herding-rocket-v1 phases: D0-D11 with phase grouping (Phase 1 shipped via #210; Phase 2-4 queued/backlog). - Infrastructure / governance: 15 items shipped via #211. - Infrastructure backlog (audit recommendations 2, 4, auto memory). - Research threads (orthogonal to grammar): NER, FP_WORDS=160, Crystal4K persistence, YAML templates, cross-linguistic parsers, fractal codec, UK Biobank, chess vertical, Wikidata, OSINT, TS/ Python convergence. - Prior-art audit: 61 top-level + 41 prompts = 102 existing docs indexed in BOOT.md + CLAUDE.md; per-file active/superseded status is a Backlog item (not urgent). Status legend: Shipped / In PR / In progress / Queued / Backlog / Deferred / Abandoned / Research / Active / Indexed. Update protocol documented: Shipped → fill PR column; phase moves → edit Status in place; abandoned → keep row with rationale. --- .claude/knowledge/STATUS_BOARD.md | 186 ++++++++++++++++++++++++++++++ 1 file changed, 186 insertions(+) create mode 100644 .claude/knowledge/STATUS_BOARD.md diff --git a/.claude/knowledge/STATUS_BOARD.md b/.claude/knowledge/STATUS_BOARD.md new file mode 100644 index 00000000..defa64c7 --- /dev/null +++ b/.claude/knowledge/STATUS_BOARD.md @@ -0,0 +1,186 @@ +# Status Board — Cross-Deliverable View + +> Deliverable-level status across all active integration plans. +> **Status** and **PR / Evidence** columns are the only mutable +> fields — title, plan-version, and scope are immutable. +> +> For plan-level status see `INTEGRATION_PLANS.md`. +> For per-PR decision history see `PR_ARC_INVENTORY.md`. +> For current contract inventory see `LATEST_STATE.md`. + +--- + +## Status Legend + +| Status | Meaning | +|---|---| +| **Shipped** | Merged to main. PR column cites the merge commit. | +| **In PR** | PR open, under review. Not yet merged. | +| **In progress** | Active branch, code in flight, not yet PR. | +| **Queued** | Next up; spec is clear; work not started. | +| **Backlog** | Future; still in scope but not yet queued for a phase. | +| **Deferred** | Explicitly parked. Rationale recorded. Will be revisited. | +| **Abandoned** | Removed from scope. Rationale recorded. Will not be revisited. | + +Rules: +- New rows APPEND (at the bottom of the relevant section). +- Status field is the ONLY field that gets edited in place. +- When a deliverable ships, record the PR number — never delete the + row. +- When a deliverable is superseded by a different design, keep the + row with Status = Abandoned and cite the replacement. + +--- + +## elegant-herding-rocket-v1 — Phase-structured + +Active integration plan, 12 deliverables D0 + D2–D11 (D1 dropped +early — CausalityFlow extension deferred). Plan path: +`.claude/plans/elegant-herding-rocket-v1.md`. + +### Phase 1 — Shipped (PR #210, merged 2026-04-19) + +| D-id | Title | Status | PR / Evidence | +|---|---|---|---| +| D0 | grammar-landscape.md + linguistic-epiphanies + fractal-codec knowledge docs | **Shipped** | #210 — 3 docs, 1151 LOC | +| D4 | ContextChain reasoning ops (coherence / replay / disambiguate / WeightingKernel) | **Shipped** | #210 — 396 LOC, 8 tests | +| D6 | Role-key catalogue with contiguous `[start:stop]` slice addressing | **Shipped** | #210 — 404 LOC, 7 tests | + +### Phase 2 — Queued + +| D-id | Title | Status | PR / Evidence | +|---|---|---|---| +| D2 | DeepNSM emits `FailureTicket` on low coverage | **Queued** | — | +| D3 | Grammar Triangle wired into DeepNSM via `triangle_bridge.rs` | **Queued** | — | +| D5 | Markov ±5 SPO+TEKAMOLO bundler with role-indexed VSA | **Queued** | — | +| D7 | NARS-tested grammar thinking styles (meta-inference policies) | **Queued** | — | + +### Phase 3 — Queued + +| D-id | Title | Status | PR / Evidence | +|---|---|---|---| +| D8 | Story-context bridge (AriGraph episodic + triplet-graph + orthogonal global-context) | **Queued** | — | +| D10 | Forward-validation harness (Animal Farm benchmark) | **Queued** | — | + +### Phase 4 — Backlog + +| D-id | Title | Status | PR / Evidence | +|---|---|---|---| +| D9 | ONNX story-arc export + ArcPressure / ArcDerivative awareness hook | **Backlog** | — | +| D11 | Bundle-perturb emergence interface (transformer-free generative stack) | **Backlog** | — | + +### Dropped / Deferred from the plan itself + +| D-id | Title | Status | Notes | +|---|---|---|---| +| D1 | CausalityFlow 3→9 slot extension (modal/local/instrument + beneficiary/goal/source) | **Deferred** | User decision; follow-up PR after Phase 2 | + +--- + +## Infrastructure / governance (not in elegant-herding-rocket) + +Workspace-level bootstrap work. Tracked here rather than PR_ARC +because it's process, not architecture. + +| Item | Status | PR / Evidence | +|---|---|---| +| CLAUDE.md §Session Start — three mandatory reads | **Shipped** | #211 | +| CLAUDE.md §A2A Orchestration — two layers (runtime + session) | **Shipped** | #211 | +| CLAUDE.md §Model Policy — grindwork vs accumulation + never Haiku | **Shipped** | #211 | +| CLAUDE.md §GitHub Access Policy — zipball-for-reads | **Shipped** | #211 | +| `.claude/BOOT.md` session entry + prior-art links | **Shipped** | #211 | +| `.claude/agents/BOOT.md` orchestration spec (renamed from README) | **Shipped** | #211 | +| `.claude/agents/README.md` function inventory | **Shipped** | #211 | +| `.claude/knowledge/LATEST_STATE.md` current-state snapshot | **Shipped** | #211 | +| `.claude/knowledge/PR_ARC_INVENTORY.md` append-only decision arc | **Shipped** | #211 | +| `.claude/knowledge/INTEGRATION_PLANS.md` versioned plan index | **Shipped** | #211 | +| `.claude/knowledge/STATUS_BOARD.md` this file | **Shipped** | #211 | +| `.claude/settings.json` team-shared governance (ask/deny + hooks) | **Shipped** | #211 | +| `.claude/hooks/session-start.sh` + `post-compact.sh` | **Shipped** | #211 | +| `.claude/skills/cca2a/` pattern-explanation skill | **Shipped** | #211 | +| `.claude/plans/elegant-herding-rocket-v1.md` plan in workspace | **Shipped** | #211 | + +## Infrastructure — queued + +| Item | Status | Notes | +|---|---|---| +| `.claude/rules/` with `paths:` frontmatter | **Backlog** | Audit rec 2; replace / complement `READ BY:` headers with path-scoped loading | +| Skill `context: fork` + `agent:` field | **Backlog** | Audit rec 4; read-only isolation for search-only skill variants | +| Auto memory (`~/.claude/projects//memory/`) | **Backlog** | Audit rec; unstructured addition to curated LATEST_STATE | + +--- + +## Cross-cutting research threads (orthogonal to grammar work) + +Separate research thread — not entangled with grammar/crystal/A2A. +Tracked here so it doesn't get lost. + +| Item | Status | Notes | +|---|---|---| +| Named-Entity pre-pass (NER) — biggest OSINT blocker | **Deferred** | Dedicated PR after Phase 2 | +| FP_WORDS = 160 migration (currently 157) | **Deferred** | Needs coordinated ndarray change | +| Crystal4K 41:1 persistence compression | **Deferred** | ladybug-rs owns it; would port later | +| 200–500 YAML TEKAMOLO templates per language | **Deferred** | Training pipeline; future | +| Cross-linguistic active parsers (EN+FI+RU+TR) | **Deferred** | Role keys exist; parsers later | +| Fractal-descriptor leaf codec (MFDFA on Hadamard) | **Research** | `.claude/knowledge/fractal-codec-argmax-regime.md`. 30-min probe first. | +| UK Biobank cardiac MRI benchmark | **Research** | Downstream of fractal-codec probe | +| Chess vertical (ruci + lichess-bot integration) | **Deferred** | Capstone Tier 0, parallel stream | +| Wikidata ingest (1.2 B triples → 14.4 GB) | **Deferred** | `.claude/knowledge/wikidata-spo-nars-at-scale.md` | +| OSINT pipeline (spider + reader-lm + DeepNSM) | **Deferred** | `.claude/knowledge/osint-pipeline-openclaw.md` | +| Python/TypeScript grammar-stack convergence | **Deferred** | `.claude/knowledge/grammar-landscape.md` §7 | + +--- + +## Prior-art audit (61 + 41 = 102 existing docs) + +Before this session, the workspace accumulated 61 `.claude/*.md` +top-level docs + 41 `.claude/prompts/*.md` files across prior +sessions. They are indexed in `.claude/BOOT.md §Existing content` +and `CLAUDE.md §Prior art`, but their individual **status** (still +active / superseded / archival) has not been audited. + +Status rows per bucket, not per file (102 rows would drown the +board — use filesystem + INTEGRATION_PLANS + PR_ARC for per-file +history): + +| Bucket | Count | Status | Notes | +|---|---|---|---| +| `.claude/*.md` top-level calibration reports / handovers / audits / snapshots | 61 | **Indexed** | Pointed at from BOOT.md + CLAUDE.md. Per-file active/superseded status: **Backlog** (needs one-pass audit). | +| `.claude/prompts/*.md` scoped session / probe / handover prompts | 41 | **Indexed** | Pointed at from BOOT.md via `SCOPED_PROMPTS.md` index. Per-file status: **Backlog**. | +| `.claude/knowledge/*.md` structured knowledge | 12 | **Active** | Current; each has `READ BY:` header; used by Knowledge Activation triggers. | +| `.claude/agents/*.md` specialist + meta-agent cards | 24 | **Active** | Current; used by spawning + Knowledge Activation. | +| `.claude/hooks/*.sh` | 2 | **Active** | Wired via settings.json. | +| `.claude/skills/cca2a/*.md` | 3 | **Active** | Current. | +| `.claude/plans/*.md` integration plans | 1 (v1) | **Active** | Elegant herding rocket v1, Phase 1 shipped. | + +**Backlog item — prior-art audit.** One-pass sweep across the +61+41 files. Per file: label as active / superseded / archival +with a one-line note. Deliverable = an `ARCHIVE_INDEX.md` that +splits the 102 into current vs historical, plus rename/move of +superseded files into an `archive/` subdirectory. Estimate ~200 +LOC of meta work, ~2 hours of reading. **Not urgent**; useful +before the next major planning session. + +## Update protocol + +When a deliverable ships: +1. Edit this file's Status column in place for the row → **Shipped**. +2. Fill in PR / Evidence column with the merge commit or PR #. +3. Append a new section to `PR_ARC_INVENTORY.md` (Added / Locked / + Deferred / Docs / Confidence). +4. Update `LATEST_STATE.md` (Recently Shipped PRs + Current Inventory + if types change). + +When a deliverable moves phase (e.g. Queued → In progress → In PR): +1. Edit Status column in place. Don't reorder rows. +2. If the move reflects scope correction, also update + `INTEGRATION_PLANS.md` Status line for the parent plan. + +When a new deliverable is added to a plan: +1. Append a new row at the bottom of the plan's section. +2. D-id is sequential in the plan (D12, D13, etc.). +3. Original scope becomes immutable once committed. + +When a deliverable is abandoned: +1. Edit Status → **Abandoned**. Don't remove the row. +2. Cite the replacement in Notes. From 6b7036c1cebb427f3fce6831d1ddeb03336d044a Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 19 Apr 2026 11:53:14 +0000 Subject: [PATCH 16/18] feat(boot+skill): link STATUS_BOARD + INTEGRATION_PLANS, unify append-only rule MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The four-file bookkeeping layer was split across BOOT.md, CLAUDE.md and the cca2a skill with inconsistent framing. Unifying it. BOOT.md changes: - §Read Order now flags STATUS_BOARD and INTEGRATION_PLANS as companion dashboards (mid-session references, not cold-start mandatory). - §Governance Rule 1 rewritten as a table: four files, per-file immutable rows, per-file mutable fields. Core invariant: rows are history; specific fields are state; never delete a row. CLAUDE.md changes: - §Session Start adds the two dashboards after the three mandatory reads, with "consult when X" guidance. cca2a skill changes: - SKILL.md — Canonical files section restructured into entry points / four bookkeeping files / agent ensemble / governance+hooks / active plans. - concepts.md — §Append-only history now documents all four files with mutable-field exceptions per file, ask-on-Edit enforcement only on the strictest two, core invariant explicit. Unified rule across all four files: - Rows are history (immutable). - Specific fields per file are state (mutable). - Never delete a row. Supersedure is a new row citing the old. --- .claude/BOOT.md | 35 +++++++++++++++++++++++++----- .claude/skills/cca2a/SKILL.md | 37 ++++++++++++++++++++++++++------ .claude/skills/cca2a/concepts.md | 36 +++++++++++++++++++++---------- CLAUDE.md | 11 ++++++++++ 4 files changed, 97 insertions(+), 22 deletions(-) diff --git a/.claude/BOOT.md b/.claude/BOOT.md index 9de1cc48..b44d7c34 100644 --- a/.claude/BOOT.md +++ b/.claude/BOOT.md @@ -26,15 +26,40 @@ Read these in order before proposing anything: These three files give you ~90 % of the context you need to avoid re-proposing what's shipped or violating a locked convention. +Two companion dashboards (consult when deliverable status or plan +version matters — typically mid-session, not at cold start): + +- **`.claude/knowledge/STATUS_BOARD.md`** — deliverable-level + dashboard. All D-ids across every active plan with Status + (Shipped / In PR / In progress / Queued / Backlog / Deferred / + Abandoned). Plus infrastructure status, research threads, and + the 102-file prior-art audit. +- **`.claude/knowledge/INTEGRATION_PLANS.md`** — versioned plan + index, APPEND-ONLY. New plan versions prepend; prior versions + stay with Status annotation. Active plan lives at + `.claude/plans/-v.md`. + --- ## The Governance Rules (never violate) -1. **Append-only architectural history.** `PR_ARC_INVENTORY.md` and - `LATEST_STATE.md` are governed by the append-only rule — Edit - prompts for explicit approval, Write for appends is allowed. - Old PR entries are immutable historical record; only the - Confidence line per entry is updatable. +1. **Append-only on bookkeeping files.** Four files carry the + workspace's historical record; rows / sections inside them are + immutable, with a short list of mutable fields per file. + `permissions.ask` in `.claude/settings.json` surfaces Edit + attempts on the two strictest files as approval prompts; Write + for append stays unprompted. + + | File | Immutable | Mutable fields | + |---|---|---| + | `PR_ARC_INVENTORY.md` | PR rows (Added / Locked / Deferred / Docs) | Confidence line per entry. Corrections APPEND as dated lines. | + | `LATEST_STATE.md` | Recently-shipped PR table rows | Snapshot sections (Current Inventory / Active Branches / Queued / Deferred) are updated by replacement, not history | + | `STATUS_BOARD.md` | Deliverable rows (D-id / title / plan-version / scope) | Status column, PR / Evidence column per row | + | `INTEGRATION_PLANS.md` | Plan entries (scope / path / deliverables) | Status and Confidence lines per entry | + + Core invariant: **rows are history; specific fields are state; + never delete a row.** Supersedure is a new row that cites the + old; the old row's Status updates to "Superseded by ". 2. **Model policy.** Main thread on Opus with deep thinking. Subagents: Sonnet for grindwork (single-source mechanical), Opus for accumulation (multi-source synthesis). **Never Haiku**, diff --git a/.claude/skills/cca2a/SKILL.md b/.claude/skills/cca2a/SKILL.md index 1e4cdcb1..fa7955a9 100644 --- a/.claude/skills/cca2a/SKILL.md +++ b/.claude/skills/cca2a/SKILL.md @@ -17,14 +17,39 @@ grok it once instead of the user re-deriving it for 30 turns. **Canonical files** (read these, not template copies): -- `.claude/BOOT.md` — session entry point. +**Entry points:** +- `.claude/BOOT.md` — session entry point (one page). +- `CLAUDE.md` — workspace spec, links to all of the below. + +**Four bookkeeping files (rows are history; specific fields are +state; never delete a row):** - `.claude/knowledge/LATEST_STATE.md` — current contract inventory. -- `.claude/knowledge/PR_ARC_INVENTORY.md` — APPEND-ONLY decision arc. -- `.claude/agents/BOOT.md` — agent ensemble + Knowledge Activation + - Handover Protocol. + Mutable: Current Inventory / Active Branches / Queued / Deferred + snapshots. +- `.claude/knowledge/PR_ARC_INVENTORY.md` — APPEND-ONLY per-PR arc. + Mutable: Confidence line per entry; corrections APPEND as dated + lines. +- `.claude/knowledge/STATUS_BOARD.md` — deliverable-level dashboard + across all plans. Mutable: Status + PR / Evidence columns per row. +- `.claude/knowledge/INTEGRATION_PLANS.md` — APPEND-ONLY versioned + plan index. Mutable: Status + Confidence per entry. + +**Agent ensemble + orchestration:** +- `.claude/agents/BOOT.md` — orchestration spec + Knowledge + Activation + Handover Protocol. - `.claude/agents/README.md` — function inventory of all agents. -- `.claude/settings.json` — team-shared governance permissions. -- `CLAUDE.md` — workspace spec, links to all of the above. + +**Governance + hooks:** +- `.claude/settings.json` — team-shared governance (ask-on-Edit for + the two strictest bookkeeping files, deny on destructive ops, + SessionStart + PostCompact hooks). +- `.claude/hooks/session-start.sh` / `post-compact.sh` — inject + bootload context at turn 0 / after compaction. + +**Active plans:** +- `.claude/plans/-v.md` — indexed via + `INTEGRATION_PLANS.md`. Old versions stay with Status annotation; + new versions prepend. ## What to read when diff --git a/.claude/skills/cca2a/concepts.md b/.claude/skills/cca2a/concepts.md index aeb2c760..dbe22db1 100644 --- a/.claude/skills/cca2a/concepts.md +++ b/.claude/skills/cca2a/concepts.md @@ -58,17 +58,31 @@ scales. Don't entangle them. ## Governance Rules -### Append-only history - -`PR_ARC_INVENTORY.md` and `LATEST_STATE.md` are immutable historical -record except for one mutable field per entry: `Confidence`. -Corrections append as `**Correction (YYYY-MM-DD from PR #N):**` -lines. Reversals get their own new PR entry; both remain in the arc. - -Enforced via `.claude/settings.json::permissions.ask` on -`Edit(.claude/knowledge/PR_ARC_INVENTORY.md)` and -`Edit(.claude/knowledge/LATEST_STATE.md)` — surfaces as approval -prompt. Write for appends stays unprompted. +### Append-only history (four bookkeeping files, unified rule) + +The workspace carries four bookkeeping files. Rows / entries inside +them are immutable historical record; specific fields per file are +mutable state. Never delete a row. Supersedure is a new row that +cites the old; the old row's Status updates to "Superseded by +". + +| File | Immutable (rows) | Mutable (state fields) | +|---|---|---| +| `PR_ARC_INVENTORY.md` | PR rows (Added / Locked / Deferred / Docs) | Confidence line per entry; Corrections APPEND as dated lines | +| `LATEST_STATE.md` | Recently-shipped PR table | Current Inventory / Active Branches / Queued / Deferred snapshots (updated by replacement) | +| `STATUS_BOARD.md` | Deliverable rows (D-id / title / plan-version / scope) | Status column + PR / Evidence column per row | +| `INTEGRATION_PLANS.md` | Plan entries (scope / path / deliverables) | Status + Confidence lines per entry | + +Governance enforcement: `.claude/settings.json::permissions.ask` on +Edit of `PR_ARC_INVENTORY.md` and `LATEST_STATE.md` surfaces any +edit as an approval prompt. Write for appends stays unprompted. +`STATUS_BOARD.md` and `INTEGRATION_PLANS.md` are less strict (Edit +is allowed without prompt since their Status fields move often) but +the same immutable-rows discipline applies by convention. + +Core invariant: **the arc is the record; rewriting it destroys the +"why was this decided that way" context that prevents future +rediscovery.** ### Model policy diff --git a/CLAUDE.md b/CLAUDE.md index 58505af9..d323bb72 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -30,6 +30,17 @@ whether you went through BOOT.md or landed here directly. After these three, load domain-specific knowledge docs only as triggered by the user's request. +**Companion dashboards (mid-session references, not cold-start +mandatory):** + +- **`.claude/knowledge/STATUS_BOARD.md`** — deliverable-level + dashboard. All D-ids across every active plan with Status. + Consult when asking "where is D5" or "is this shipped yet." +- **`.claude/knowledge/INTEGRATION_PLANS.md`** — versioned plan + index (APPEND-ONLY). Active plan lives at + `.claude/plans/-v.md`. Consult before proposing a new + plan. + **If you want the pattern explained rather than the specifics:** see **`.claude/skills/cca2a/SKILL.md`** — explanation-only skill covering the A2A two-layer model, governance rules, and how this From d104b85508bcb81b3e7946bde3c3222613f121db Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 19 Apr 2026 12:03:12 +0000 Subject: [PATCH 17/18] =?UTF-8?q?feat(knowledge):=204-file=20kanban=20?= =?UTF-8?q?=E2=80=94=20EPIPHANIES=20+=20ISSUES=20+=20IDEAS=20+=20TECH=5FDE?= =?UTF-8?q?BT?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds four append-only bookkeeping files that work as a self-organizing kanban / audit log so nothing falls through the cracks between sessions. Files: 1. EPIPHANIES.md — date-prefixed insight log. Reverse chronological. Every "aha" gets a YYYY-MM-DD entry with Status (FINDING / CONJECTURE / SUPERSEDED). Seeded with the 12 most recent epiphanies from this session; prior-art files (linguistic- epiphanies, cross-repo-harvest, integration-plan, session- capstone) cross-referenced as historical substrate. 2. ISSUES.md — bugs / regressions / invariant violations. Double- entry: Open Issues section + Resolved Issues section. Status transitions flip in place (Open row stays for chronology); Resolution line appends on close. 3. IDEAS.md — architectural speculation. Triple-entry: Open Ideas + Implemented Ideas + Integration Plan Update Log + Rejected/ Deferred. Each shipped idea gets an audit trail from speculation -> code -> plan consequence. 4. TECH_DEBT.md — knowingly-deferred work (shortcuts, stubs, missing probes, hardcoded thresholds). Double-entry: Open Debt + Paid Debt. Seeded with 5 concrete debts from PRs #204-#211 (ContextChain non-Binary16K coherence, CausalityFlow 3/9 slots, NER gap, FP_WORDS=160 migration, Abduction threshold calibration). ## Kanban discipline Every entry in ISSUES / IDEAS / TECH_DEBT carries: - Priority: P0 blocker / P1 high / P2 medium / P3 low. - Scope: @, D plan-id, domain:. Agents filter by their own @-mention. Nothing gets buried because every ticket has an owner named. ## Permission semantics flip (ask on Write, not Edit) permissions.ask in .claude/settings.json now gates Write (full overwrite) instead of Edit. Method hierarchy documented across BOOT.md, concepts.md, SKILL.md: 1. APPEND (preferred) — new dated row via Edit-prepend or Bash cat >>. No prompt. Double-bookkeeping. 2. Edit field with prior Read — Status flip, Confidence update. No prompt. Prior Read is workspace discipline. 3. Write (full overwrite) — prompts for approval. Escape hatch. Rule: when in doubt, APPEND. All 8 bookkeeping files now follow the same rule: PR_ARC_INVENTORY, LATEST_STATE, STATUS_BOARD, INTEGRATION_PLANS, EPIPHANIES, ISSUES, IDEAS, TECH_DEBT. BOOT.md + CLAUDE.md + cca2a/SKILL.md + cca2a/concepts.md all updated with the unified 8-file table + method hierarchy + kanban fields. --- .claude/BOOT.md | 41 +++++- .claude/knowledge/EPIPHANIES.md | 209 +++++++++++++++++++++++++++++++ .claude/knowledge/IDEAS.md | 173 +++++++++++++++++++++++++ .claude/knowledge/ISSUES.md | 125 ++++++++++++++++++ .claude/knowledge/TECH_DEBT.md | 188 +++++++++++++++++++++++++++ .claude/settings.json | 10 +- .claude/skills/cca2a/concepts.md | 71 +++++++---- 7 files changed, 790 insertions(+), 27 deletions(-) create mode 100644 .claude/knowledge/EPIPHANIES.md create mode 100644 .claude/knowledge/IDEAS.md create mode 100644 .claude/knowledge/ISSUES.md create mode 100644 .claude/knowledge/TECH_DEBT.md diff --git a/.claude/BOOT.md b/.claude/BOOT.md index b44d7c34..373ef2da 100644 --- a/.claude/BOOT.md +++ b/.claude/BOOT.md @@ -43,12 +43,33 @@ version matters — typically mid-session, not at cold start): ## The Governance Rules (never violate) -1. **Append-only on bookkeeping files.** Four files carry the +1. **Append-only on bookkeeping files.** Eight files carry the workspace's historical record; rows / sections inside them are immutable, with a short list of mutable fields per file. - `permissions.ask` in `.claude/settings.json` surfaces Edit - attempts on the two strictest files as approval prompts; Write - for append stays unprompted. + + **Method hierarchy (preferred → discouraged):** + + 1. **APPEND** (the method of choice) — add a NEW dated row to + an existing section. Either via Edit (prepend inside a `---` + bounded section) or Bash `cat >> file << EOF`. No prompt. + The old row stays untouched. This is the double-bookkeeping + pattern — new state enters as a new entry, not by mutating + the old. + 2. **Edit field with prior Read** — flip a mutable field + (Status / Confidence / Resolution / Payoff) on an existing + row after reading the file. No prompt. Use for clarifications, + status transitions, and minor updates. Prior Read is the + workspace discipline (already in `CLAUDE.md`). + 3. **Write (full overwrite)** — prompts for approval on every + bookkeeping file via `.claude/settings.json::permissions.ask`. + Discouraged; only for wholesale replacement of a file that's + been through explicit review. Never the default answer. + + Rule: **when in doubt, append**. The double-bookkeeping habit + (new row rather than edited old row) preserves the full arc and + keeps the audit trail legible. Edit-a-field is acceptable when + the change is clearly a status transition on an existing entry; + Write is the escape hatch that costs a confirmation. | File | Immutable | Mutable fields | |---|---|---| @@ -56,10 +77,22 @@ version matters — typically mid-session, not at cold start): | `LATEST_STATE.md` | Recently-shipped PR table rows | Snapshot sections (Current Inventory / Active Branches / Queued / Deferred) are updated by replacement, not history | | `STATUS_BOARD.md` | Deliverable rows (D-id / title / plan-version / scope) | Status column, PR / Evidence column per row | | `INTEGRATION_PLANS.md` | Plan entries (scope / path / deliverables) | Status and Confidence lines per entry | + | `EPIPHANIES.md` | Dated entry bodies | Status line (FINDING / CONJECTURE / SUPERSEDED) | + | `ISSUES.md` | Dated entry bodies | Status line (Open / Resolved / Wontfix / Superseded) + Resolution line (append on close) | + | `IDEAS.md` | Dated entry bodies | Status line (Open / Implemented / Rejected / Deferred / Reactivated) + Rationale (append) | + | `TECH_DEBT.md` | Dated entry bodies | Status line (Open / Paid / Moot) + Payoff line (append) + Priority / Scope (filled at creation, stable) | Core invariant: **rows are history; specific fields are state; never delete a row.** Supersedure is a new row that cites the old; the old row's Status updates to "Superseded by ". + + **Kanban discipline** — every entry in `ISSUES.md`, `IDEAS.md`, + `TECH_DEBT.md` carries `**Priority:**` (P0-P3) and + `**Scope:**` (@agent D domain:) fields. Agents filter + the board by their own `@`-mention or domain. Status moves + through Open → In Progress → Resolved/Implemented/Paid. Nothing + falls through the cracks because every ticket has an owner + mentioned by `@`. 2. **Model policy.** Main thread on Opus with deep thinking. Subagents: Sonnet for grindwork (single-source mechanical), Opus for accumulation (multi-source synthesis). **Never Haiku**, diff --git a/.claude/knowledge/EPIPHANIES.md b/.claude/knowledge/EPIPHANIES.md new file mode 100644 index 00000000..baf0e92d --- /dev/null +++ b/.claude/knowledge/EPIPHANIES.md @@ -0,0 +1,209 @@ +# Epiphanies — Append-Only Log (date-prefixed) + +> **APPEND-ONLY.** Every epiphany, realization, correction, or +> "aha" moment gets a dated entry here so nothing gets lost between +> sessions. Reverse chronological (newest first). Never delete an +> entry; correct via a new entry that cites the old one. +> +> **Format invariant:** every entry begins with a `## YYYY-MM-DD —` +> header. A CONJECTURE / FINDING / CORRECTION-OF label is optional +> but encouraged. Body is short: one paragraph + optional +> cross-reference. Long material goes in a dedicated knowledge +> doc; the epiphany here is the **pointer + one-line claim**. +> +> Mutable field: `**Status:**` line (FINDING / CONJECTURE / +> SUPERSEDED) is the only thing in an entry that can be updated. +> Everything else is immutable. + +--- + +## How to use + +**When a new insight surfaces** — stop, prepend an entry with today's +date at the top of the "Entries" section below. One paragraph. If +the full idea needs more room, create a dedicated knowledge doc +and reference it from the epiphany entry. + +**When an old epiphany is wrong** — prepend a new entry labeled +`CORRECTION-OF YYYY-MM-DD ` and update the old entry's +`**Status:**` line to `SUPERSEDED by <new-entry>`. Never edit the +old body. + +**When reading the log** — top N entries are the recent thinking; +deeper entries are the accumulated substrate. Everything is there. + +--- + +## Prior art (pre-existing epiphany collections — do not duplicate) + +These files already hold numbered epiphany sets from earlier work. +New epiphanies go in **this file** with date prefix; the files below +stay as historical references. + +| File | Contents | +|---|---| +| `linguistic-epiphanies-2026-04-19.md` | E13–E27 (Chomsky hierarchy, Σ10 Rubicon, sigma_rosetta, Markov living frame, resonanzsiebe, method grammar, 4D hashtag glyph, membrane, verbs as productions) | +| `cross-repo-harvest-2026-04-19.md` | H1–H14 (Born rule, phase-tag threshold, interference truth, Grammar Triangle ≡ ContextCrystal(w=1), NSM ≡ SPO axes, FP_WORDS=160, Mexican-hat, Int4State, Glyph5B, Crystal4K, teleport F=1, 144-verb, Three Mountains) | +| `integration-plan-grammar-crystal-arigraph.md` | E1–E12 (grammar-tiered, morphology-easier, FailureTicket, cross-lingual superposition, Markov ±5, NARS-about-grammar, crystal hierarchy, sandwich, 5D quorum, episodic unbundle, AriGraph substrate, demo matrix) | +| `session-capstone-2026-04-18.md` | 8 epiphanies from 2026-04-18 session (four-pillar inheritance, CMYK/RGB qualia, vocabulary IS semantics, WorldMapRenderer, Σ hierarchy maps to crate boundaries, proprioception as ontological self-recognition, BindSpace+cycle_fingerprint as latent episodic, two-frame DTO) | +| `crystal-quantum-blueprints.md` | Crystal mode vs Quantum mode split (bundled Markov SPO chain vs holographic residual) | +| `endgame-holographic-agi.md` | 5-layer stack, 12-step holographic memory loop, three-demo matrix | +| `fractal-codec-argmax-regime.md` | Orthogonal research thread — MFDFA on Hadamard-rotated coefficients as fractal-descriptor leaf | + +## Governance + +- **APPEND-ONLY.** Immutable body per entry. +- **Mutable:** `**Status:**` line only (FINDING / CONJECTURE / + SUPERSEDED by <date-title>). +- **Corrections APPEND as new dated entries.** The old entry's + Status changes to SUPERSEDED. +- **`permissions.ask` on Edit** (same rule as `PR_ARC_INVENTORY.md` + / `LATEST_STATE.md` — rewriting history prompts for approval; + Write for append stays unprompted). + +--- + +## Entries (reverse chronological) + +## 2026-04-19 — Mandatory epiphanies log (this file) + +**Status:** FINDING + +Every epiphany from prior sessions lived in separate doc (E1–E12 +here, H1–H14 there, E13–E27 somewhere else). No single place to +append a new one. This file is the unified target going forward. +Old files stay as historical substrate; new insights land here with +date prefix. Cross-reference: `BOOT.md`, `CLAUDE.md`, `cca2a/ +concepts.md` — all four bookkeeping files now plus this one. + +## 2026-04-19 — Cold-start tax is solvable with three mandatory reads + +**Status:** FINDING + +A new session on non-trivial workspace burns 20–30 turns rediscovering +what's shipped. Three files (`LATEST_STATE.md`, `PR_ARC_INVENTORY.md`, +`.claude/agents/BOOT.md`) + SessionStart hook closes the gap to +3–5 turns. Proven by PR #211. Savings per cold-start: ~$15–35 of +Opus. See `.claude/skills/cca2a/SKILL.md` for the full pattern. + +## 2026-04-19 — 10,000-D f32 VSA is lossless under linear sum + +**Status:** FINDING + +Earlier framing of "Vsa10kF32 is wire-only passthrough" was wrong. +10K × 32 = 320 K bits of capacity ≫ any single signal; orthogonal +role keys give exact unbundle. **10K f32 is native storage**, not +passthrough. lancedb famously supports 10K-D VSA natively. Cross-ref: +PR #209 refactor. + +## 2026-04-19 — Signed 5^5 bipolar is lossless; unsigned / bitpacked is lossy + +**Status:** FINDING + +Negative cancellation on bipolar cells is VSA-native; opposing cells +at the same sandwich dim cancel on bundling. Unsigned 5^5 saturates +under accumulation (lossy). Binary bitpacked commits to 0/1 via +majority vote (lossy). CAM-PQ projection is distance-preserving +(lossless cross-form). Cross-ref: PR #209 sandwich layout. + +## 2026-04-19 — VSA convention is `[start:stop]` contiguous slices, not scattered bits + +**Status:** FINDING + +Role keys own disjoint contiguous slices of the 10K VSA space — +SUBJECT=[0..2000), PREDICATE=[2000..4000), etc. Binding into one +slice does not contaminate another. Scattered-bit role encoding +(early draft) was the wrong pattern. Cross-ref: PR #210 D6 +role_keys.rs. + +## 2026-04-19 — Finnish object marking is Nominative/Genitive/Partitive, NOT Accusative + +**Status:** FINDING (CORRECTION-OF an earlier Latinate transplant) + +Prior draft wrote Finnish "Accusative `-n/-t` → Object" which is +a Latinate transplant. Finnish object marking actually uses: +Nominative (plural), Genitive `-n` (total singular), Partitive +`-a/-ä` (partial / negated). True Accusative is only for personal +pronouns (`minut`, `sinut`, `hänet`, `meidät`, `teidät`, `heidät`). +Each language gets its native case terminology. +Cross-ref: `grammar-landscape.md` §4.1. + +## 2026-04-19 — Morphology-rich languages are easier, not harder + +**Status:** FINDING + +Finnish 15 cases → 98%+ local coverage. English (word order only) → +85% (WORST case). Case endings directly encode TEKAMOLO slots; +morphology commits grammatical role at the morpheme level, +eliminating the inference English needs. Cross-ref: +`grammar-tiered-routing.md` §Morphology Coverage Table. + +## 2026-04-19 — Markov ±5 is the context upgrade to NARS+SPO 2³+TEKAMOLO + +**Status:** FINDING + +Pre-Markov reasoning unit = sentence. Post-Markov = trajectory. +NARS doesn't reason about "this sentence"; it reasons about "this +sentence in this flow." The context dimension is the whole point. +Cross-ref: `integration-plan-grammar-crystal-arigraph.md` E5. + +## 2026-04-19 — Grammar Triangle IS ContextCrystal at window=1 + +**Status:** FINDING + +Two parallel architectures turn out to be the same thing at +different window sizes. Triangle emits `Structured5x5` with S/O +collapsed + only t=2 populated; ContextCrystal populates all 5 +axes. Unification. Cross-ref: +`cross-repo-harvest-2026-04-19.md` H4, +`ladybug-rs/docs/GRAMMAR_VS_CRYSTAL.md`. + +## 2026-04-19 — NSM primes map directly to SPO + Qualia + Temporal axes + +**Status:** FINDING + +The 65 Wierzbicka primes aren't orthogonal to SPO — they ARE an +SPO encoding. I/YOU/SOMEONE → Subject; THINK/WANT/FEEL → +Predicate; SOMETHING/BODY → Object; GOOD/BAD → Qualia.valence; +BEFORE/AFTER → Temporal; BECAUSE/IF → Causality via Markov flow. +DeepNSM + Structured5x5 already speak NSM's vocabulary. +Cross-ref: `cross-repo-harvest-2026-04-19.md` H5. + +## 2026-04-19 — Chomsky hierarchy isomorphism with Pearl rungs and Σ tiers + +**Status:** FINDING + +Type-3 Regular = Pearl rung 1 = Σ1–Σ2 = DeepNSM FSM (LLM token +prediction lives here). Type-2 CF = rung 2 = Σ3–Σ5 = SPO 2³. Type-1 +CS = rung 3–4 = Σ6–Σ8 = Markov ±5 + coref + counterfactual. Type-0 +TM = rung 5 = Σ9–Σ10 = LLM escalation only. The 90–99% local / +1–10% LLM split is the Chomsky-hierarchy boundary between +context-sensitive-decidable and Turing-complete-undecidable. The +split is mathematically principled, not arbitrary. +Cross-ref: `linguistic-epiphanies-2026-04-19.md` E13, E26. + +## 2026-04-19 — Grindwork vs accumulation is the subagent model split + +**Status:** FINDING + +Grindwork (single-source mechanical: write-file-from-spec, grep, +list paths) → Sonnet. Accumulation (multi-source synthesis: +harvest across repos, combine N docs, trace architecture) → Opus. +Cheaper tiers produce shallow outputs under accumulation; quality +drop is visible. Never Haiku. +Cross-ref: `CLAUDE.md §Model Policy`. + +## 2026-04-19 — Zipball-for-reads is ~20× cheaper than MCP-per-file + +**Status:** FINDING + +`mcp__github__get_file_contents` drops the full file into context +and recharges on every subsequent turn. Zipball to `/tmp/sources/` ++ local grep lands only the grep output (typically 2–10 KB) vs +50 KB per file per turn. 95% savings on cross-repo harvest turns. +MCP stays for writes (PR creation, comments). +Cross-ref: `CLAUDE.md §GitHub Access Policy`. + +--- + +(append new epiphanies above this marker; format: `## YYYY-MM-DD — <title>`) diff --git a/.claude/knowledge/IDEAS.md b/.claude/knowledge/IDEAS.md new file mode 100644 index 00000000..2774ee81 --- /dev/null +++ b/.claude/knowledge/IDEAS.md @@ -0,0 +1,173 @@ +# Ideas Log — Open + Implemented + Integration (triple-entry, append-only) + +> **Append-only ledger** for every architectural idea, speculative +> design, "what if we tried X" moment. Ideas accumulate here +> whether or not they're ready to ship. When one gets implemented, +> it moves from Open → Implemented → Integration (a row linking +> the idea to the plan entry that scheduled it + the PR that +> shipped it). +> +> **Purpose:** a speculation has nowhere else to live until it's +> scoped into a plan. This file is the speculation surface. Ideas +> die or graduate here; nothing is lost. + +--- + +## Triple-entry discipline + +Every idea moves through three ledger sections in this file: + +1. **Open Ideas** — speculative; captured when proposed. +2. **Implemented Ideas** — idea became real; row appended with PR + anchor + integration-plan D-id reference. +3. **Integration Plan Update Log** — the paired "what the plan + changed when this idea landed" row, citing the specific + `INTEGRATION_PLANS.md` version bump or `STATUS_BOARD.md` row + flip triggered by the idea. + +The row in Open is NEVER moved; its Status flips. The Implemented +row is a NEW append that cites the Open anchor. The Integration +row is a THIRD append that cites both. + +This is **triple-entry bookkeeping** — three sections, same idea, +cross-linked. The cost is a bit more writing; the benefit is that +every shipped idea has an audit trail from speculation → code → +plan consequence. + +--- + +## Rejected / Deferred + +Ideas that don't graduate go into a fourth section: + +4. **Rejected / Deferred Ideas** — with `**Rationale:**` and cross- + ref to the original Open entry. The Open row's Status flips to + `Rejected YYYY-MM-DD` or `Deferred to <when>`. + +Deferred ideas can later reactivate — append a new Open entry +citing the Deferred one; Deferred row's Status flips to `Reactivated +YYYY-MM-DD <new-entry>`. + +--- + +## Governance + +- **Append-only.** Never delete a row. +- **Mutable fields:** `**Status:**` line, `**Rationale:**` line (if + added later with more context). +- **`permissions.ask` on Edit** (same rule as other bookkeeping + files). Write for appends stays unprompted. + +## Cross-references + +- `EPIPHANIES.md` — if an idea came from an epiphany, both entries + cross-reference each other. +- `INTEGRATION_PLANS.md` — the plan version that incorporated the + idea. +- `STATUS_BOARD.md` — the D-id status row that reflects the idea's + shipping status. +- `PR_ARC_INVENTORY.md` — the PR that landed the code. +- `ISSUES.md` — if implementing an idea surfaced a bug, both rows + link. + +--- + +## Kanban Format (priority + scope on every entry) + +Every idea carries: +- **Priority** — `P0` must-ship-this-phase / `P1` next-phase / `P2` + eventual / `P3` speculative. +- **Scope** — which agent / deliverable / domain: `@<agent-name>`, + `D<N>` (plan D-id), `domain:<grammar|codec|arigraph|infra|...>`. + +Ticket tag on each entry: `[P2 @family-codec-smith D7 domain:grammar]`. +Agents filter by `@`-mention or domain to see what's theirs. + +## Open Ideas + +(Prepend new ideas here with today's date. Format:) + +``` +## YYYY-MM-DD — <short title> +**Status:** Open +**Priority:** P0 | P1 | P2 | P3 +**Scope:** @<agent> D<N> domain:<tag> + +<one paragraph: what the idea is, rough scope, why it matters> + +Cross-ref: <epiphany entry / plan D-id / related knowledge doc> +``` + +--- + +## Implemented Ideas + +(When an Open idea ships, APPEND here with same title + PR anchor.) + +``` +## YYYY-MM-DD — <same title as Open entry> (from YYYY-MM-DD) +**Status:** Implemented YYYY-MM-DD via PR #NNN +**Shipped as:** D<N> in integration plan v<K> +**PR:** #NNN (commit SHA) + +<verbatim original Open paragraph> + +Cross-ref: <same + PR link + plan D-id> +``` + +The original Open entry's Status flips to `Implemented YYYY-MM-DD`. + +--- + +## Integration Plan Update Log + +(When an idea triggers a plan change — version bump, D-id status +move, new deliverable — APPEND here. This is the third-entry row.) + +``` +## YYYY-MM-DD — Plan consequence of <idea title> (from YYYY-MM-DD) +**Trigger idea:** <idea title> (YYYY-MM-DD) +**Plan change:** <version bump / D-id flip / deliverable added> +**Plan entry:** `INTEGRATION_PLANS.md` v<K> entry or new v<K+1> entry +**Status board update:** <D-id> → <new Status> + +<one paragraph: what the plan documented differently after this idea> +``` + +--- + +## Rejected / Deferred Ideas + +(Ideas that don't graduate go here.) + +``` +## YYYY-MM-DD — <same title as Open entry> (from YYYY-MM-DD) +**Status:** Rejected YYYY-MM-DD | Deferred to <when / trigger> +**Rationale:** <short explanation> + +<original Open paragraph> + +Cross-ref: <original + any related> +``` + +--- + +## How to use this file + +**When a new architectural idea surfaces** — prepend to **Open +Ideas** with today's date. One paragraph. If it needs more, create +a knowledge doc and link. + +**When an Open idea ships** — APPEND to **Implemented Ideas**; flip +Open Status to `Implemented YYYY-MM-DD`. Then APPEND to +**Integration Plan Update Log** with the plan consequence. + +**When an Open idea is rejected** — APPEND to **Rejected / +Deferred Ideas** with Rationale; flip Open Status. + +**When a deferred idea reactivates** — prepend a NEW Open entry +citing the deferred one; flip the deferred entry's Status to +`Reactivated YYYY-MM-DD <new-entry>`. + +Nothing is lost. Every idea has a trail from speculation to +disposition. diff --git a/.claude/knowledge/ISSUES.md b/.claude/knowledge/ISSUES.md new file mode 100644 index 00000000..86d2c405 --- /dev/null +++ b/.claude/knowledge/ISSUES.md @@ -0,0 +1,125 @@ +# Issues Log — Open + Resolved (double-entry, append-only) + +> **Append-only ledger.** Every issue (bug, regression, invariant +> violation, blocker) gets a dated entry here. Entries move from +> Open → Resolved by status-flip; they are NEVER deleted. +> +> **Format invariant:** every entry starts with `## YYYY-MM-DD — ` +> followed by a short title. Body is short — one paragraph of +> problem + cross-references. Full repro / fix / test details go +> in the PR or in a dedicated doc and are LINKED, not duplicated. +> +> **Mutable field:** `**Status:**` line only (Open / Resolved / +> Wontfix / Superseded). Resolved entries keep a `**Resolution:**` +> line pointing at the PR + commit SHA that fixed them. + +--- + +## Double-entry discipline + +Every issue has TWO corresponding rows, both in this file: +1. **Open section** — issue captured when first seen. +2. **Resolved section** — same entry, appended when closed, with + `**Resolution:**` line pointing at fix. + +The resolved entry cites the open entry's date as anchor. Old +"Open" entry's **Status:** flips to `Resolved YYYY-MM-DD` — it +stays in the Open section (never moved) so chronology is +preserved. The Resolved section accumulates fixes for discovery. + +This is **bookkeeping discipline**, not a storage optimization: +- Open section = what broke and when. +- Resolved section = how and when it was fixed. +- Both sections keep the same row forever; the view depends on + which section you're reading. + +--- + +## Governance + +- **Append-only.** Never delete a row from either section. +- **Mutable:** `**Status:**` and `**Resolution:**` fields only. +- **`permissions.ask` on Edit** (same rule as PR_ARC_INVENTORY). + Write for appends stays unprompted. +- **Supersedure:** if an issue turns out to be a duplicate of an + older one, Status → `Superseded by YYYY-MM-DD <title>`; old entry + stays. + +## Cross-references + +- `PR_ARC_INVENTORY.md` — which PR shipped the fix. +- `STATUS_BOARD.md` — deliverable-level view (an issue may block + one or more D-ids). +- `EPIPHANIES.md` — if debugging surfaced an architectural + insight, that lands in Epiphanies; this file tracks the concrete + fix. +- `TECH_DEBT.md` — if an issue is knowingly deferred rather than + fixed, it moves (via cross-ref) into technical debt. + +--- + +## Kanban Format (priority + scope on every entry) + +Every issue carries: +- **Priority** — `P0` blocker / `P1` high / `P2` medium / `P3` low. +- **Scope** — which agent / deliverable / domain owns it. One or + more of: `@<agent-name>`, `D<N>` (plan D-id), + `domain:<grammar|codec|infra|arigraph|...>`. + +Together they form the ticket tag: `[P1 @truth-architect D5 domain:grammar]`. +Agents filter by their own `@`-mention or their domain; nothing +gets buried. + +## Open Issues + +(No tracked open issues at initial commit. New issues PREPEND here +in reverse chronological order. Format below.) + +``` +## YYYY-MM-DD — <short title> +**Status:** Open +**Priority:** P0 | P1 | P2 | P3 +**Scope:** @<agent> D<N> domain:<tag> + +<one paragraph: what's broken, where it surfaces, rough impact> + +Cross-ref: <file:line or PR # or knowledge doc> +``` + +--- + +## Resolved Issues + +(No resolved issues at initial commit. When an Open issue is fixed, +APPEND a copy here with the same date anchor + `**Resolution:**` +line. Old Open entry's Status flips to `Resolved YYYY-MM-DD`. Old +entry stays in the Open section for chronology.) + +``` +## YYYY-MM-DD — <same title as Open entry> +**Status:** Resolved YYYY-MM-DD +**Resolution:** PR #NNN (commit SHA) — <one-line description> + +<original problem paragraph, verbatim> + +Cross-ref: <same as Open entry> +``` + +--- + +## How to use this file + +**When an issue is found** — prepend to **Open Issues** section with +today's date + `**Status:** Open` + one-paragraph description. + +**When an issue is fixed** — append to **Resolved Issues** section +with the same title and date anchor + `**Status:** Resolved +YYYY-MM-DD` + `**Resolution:** PR #NNN`. Don't edit the Open entry +body; just flip its Status to `Resolved YYYY-MM-DD`. + +**When an issue is a duplicate** — append a new entry in Resolved +section noting `**Resolution:** duplicate of YYYY-MM-DD <title>`; +flip Open entry to Superseded. + +**When an issue is deferred knowingly** — leave it Open here but +also append a row to `TECH_DEBT.md` with cross-ref back. diff --git a/.claude/knowledge/TECH_DEBT.md b/.claude/knowledge/TECH_DEBT.md new file mode 100644 index 00000000..edb35a45 --- /dev/null +++ b/.claude/knowledge/TECH_DEBT.md @@ -0,0 +1,188 @@ +# Technical Debt Log — Open + Paid (double-entry, append-only) + +> **Append-only ledger** for knowingly-deferred work: TODOs, shortcuts, +> workarounds, unsafe assumptions, missing probes, hardcoded +> thresholds, stubs, and anything else we shipped with intentional +> debt. Debt moves Open → Paid by status-flip; rows are NEVER +> deleted. +> +> **Purpose:** separate from `ISSUES.md` (bugs) and `IDEAS.md` +> (speculation). Tech debt is **code that works but we know +> something better is owed**. This file is where we admit it. + +--- + +## Double-entry discipline + +Same pattern as `ISSUES.md`: + +1. **Open Debt** — known shortcut or deferral, captured at shipping + time. +2. **Paid Debt** — when the shortcut is replaced with the proper + implementation, append here with PR anchor + Status flip on the + original Open entry to `Paid YYYY-MM-DD`. + +The Open entry stays in its section forever (chronology). The Paid +section accumulates retirements for audit. + +--- + +## Governance + +- **Append-only.** Never delete a row. +- **Mutable fields:** `**Status:**` and `**Payoff:**` lines only. +- **`permissions.ask` on Edit** (same rule as other bookkeeping + files). + +## Cross-references + +- `ISSUES.md` — an issue may become tech debt when knowingly + deferred rather than fixed. +- `IDEAS.md` — a rejected idea that was "the better way" often + leaves behind a debt entry documenting the compromise shipped + instead. +- `PR_ARC_INVENTORY.md` — which PR introduced the debt + which PR + paid it. +- `STATUS_BOARD.md` — debt items that block deliverables are + cross-referenced from the D-id row. +- `EPIPHANIES.md` — an epiphany often retroactively turns something + into tech debt (the old approach is now known to be suboptimal). + +--- + +## Kanban Format (priority + scope on every entry) + +Every debt item carries: +- **Priority** — `P0` must-pay-before-next-phase / `P1` pay-soon / + `P2` eventual / `P3` keep-tracked-but-low. +- **Scope** — which agent / deliverable / domain owes it: + `@<agent-name>`, `D<N>`, `domain:<tag>`. + +Ticket tag: `[P2 @truth-architect D10 domain:grammar]`. Same +filter discipline — agents pull their own debt by `@`-mention. + +## Open Debt + +(Seeded with known deferrals from recent PRs. New items PREPEND +with today's date.) + +``` +## YYYY-MM-DD — <short title> +**Status:** Open +**Priority:** P0 | P1 | P2 | P3 +**Scope:** @<agent> D<N> domain:<tag> +**Introduced by:** PR #NNN +**Payoff estimate:** <rough LOC / time> + +<one paragraph: what shortcut was taken, why, what the proper fix +looks like, any blocking dependencies> + +Cross-ref: <file:line / deliverable D-id / epiphany entry> +``` + +### Seeded from PRs #204–#211 + +## 2026-04-19 — Contract `ContextChain::coherence_at` returns 0 for non-Binary16K variants +**Status:** Open +**Priority:** P2 +**Scope:** @resonance-cartographer @container-architect D4 domain:grammar +**Introduced by:** PR #210 +**Payoff estimate:** ~80 LOC + tests + +D4 shipped with Hamming-based coherence on the `Binary16K` variant +only; other `CrystalFingerprint` variants (`Structured5x5`, +`Vsa10kI8`, `Vsa10kF32`) return 0 as a zero-dep fallback. Cosine +coherence on the f32 variants would unlock richer disambiguation +but requires adding a minimal linear-algebra shim without breaking +the zero-dep invariant of the contract. + +Cross-ref: `crates/lance-graph-contract/src/grammar/context_chain.rs`. + +## 2026-04-19 — CausalityFlow has 3/9 TEKAMOLO slots; modal/local/instrument + beneficiary/goal/source deferred +**Status:** Open +**Priority:** P1 +**Scope:** @integration-lead @truth-architect D1 domain:grammar +**Introduced by:** PR #208 + #210 (deliberate deferral) +**Payoff estimate:** 6 new `Option<String>` fields in +`lance-graph-cognitive/src/grammar/causality.rs` + tests + +Full thematic-role inventory needs 6 more slots on `CausalityFlow`. +Deferred per user decision; D2 ticket emission and D3 triangle +bridge map only the 3 existing slots for now. Phase 2 work is +consistent with 3/9; Phase 3 may benefit from the extension. + +Cross-ref: `grammar-landscape.md` §3, `STATUS_BOARD.md` D1 row. + +## 2026-04-19 — Named-Entity pre-pass (NER) is the biggest OSINT blocker; stubbed out +**Status:** Open +**Introduced by:** architectural choice (all PRs) +**Payoff estimate:** dedicated PR, ~800 LOC new crate / subsystem + +COCA 4096 has zero coverage of proper nouns (Altman, Anthropic, +Riyadh). Every unknown entity falls through to hash-bucket +collisions in the SPO graph. Grammar work proceeds without NER; +OSINT pipeline is blocked on this. + +Cross-ref: `grammar-tiered-routing.md` §C8, +`STATUS_BOARD.md` Research threads section. + +## 2026-04-19 — FP_WORDS = 157 (not 160); SIMD remainder loops remain +**Status:** Open +**Introduced by:** architectural choice (ndarray::hpc::vsa) +**Payoff estimate:** coordinated ndarray + lance-graph change, +~30 LOC in ndarray + 0 in lance-graph if field naming is stable + +160 u64 = 10,240 bits (SIMD-clean for AVX-512 / AVX2 / NEON), zero +remainder loop in every SIMD pass. Current 157 u64 has 5-word +scalar tail. Performance delta is measurable but not critical yet. + +Cross-ref: `cross-repo-harvest-2026-04-19.md` H6. + +## 2026-04-19 — Abduction-threshold for unbundle-to-graph is hand-picked (0.88) +**Status:** Open +**Introduced by:** #208 (inherits PR design) +**Payoff estimate:** empirical calibration run on real corpus + +~30 LOC threshold parameterization + +NARS Abduction confidence threshold for promoting facts into the +triplet graph is hand-picked at 0.88. Miscalibration on a specific +corpus (e.g. Animal Farm) would compound errors. Calibration is +pending D10 validation harness. + +Cross-ref: `integration-plan-grammar-crystal-arigraph.md` E8, +`STATUS_BOARD.md` D10 row. + +--- + +## Paid Debt + +(No debt paid at initial commit. When an Open entry is retired, +APPEND here with same title + PR anchor.) + +``` +## YYYY-MM-DD — <same title as Open entry> (from YYYY-MM-DD) +**Status:** Paid YYYY-MM-DD +**Payoff:** PR #NNN (commit SHA) — <one-line description> + +<verbatim original Open paragraph> + +Cross-ref: <same + PR link> +``` + +--- + +## How to use this file + +**When shipping with a known shortcut** — prepend to **Open Debt** +with `**Status:** Open` + `**Introduced by:** PR #NNN` + +`**Payoff estimate:**`. One paragraph describing what's owed. + +**When paying debt** — append to **Paid Debt** with the same title ++ date anchor + `**Status:** Paid YYYY-MM-DD` + `**Payoff:** PR +#NNN`. Flip the Open entry's Status to `Paid YYYY-MM-DD`. + +**When debt becomes irrelevant** (e.g. the feature it blocked got +abandoned) — flip Open Status to `Moot YYYY-MM-DD`. Keep the row. + +Nothing is lost. Every shortcut has a trail from introduction to +payoff (or abandonment). diff --git a/.claude/settings.json b/.claude/settings.json index aa872954..e2c72d7c 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -2,8 +2,14 @@ "$schema": "https://json.schemastore.org/claude-code-settings.json", "permissions": { "ask": [ - "Edit(.claude/knowledge/PR_ARC_INVENTORY.md)", - "Edit(.claude/knowledge/LATEST_STATE.md)" + "Write(.claude/knowledge/PR_ARC_INVENTORY.md)", + "Write(.claude/knowledge/LATEST_STATE.md)", + "Write(.claude/knowledge/STATUS_BOARD.md)", + "Write(.claude/knowledge/INTEGRATION_PLANS.md)", + "Write(.claude/knowledge/EPIPHANIES.md)", + "Write(.claude/knowledge/ISSUES.md)", + "Write(.claude/knowledge/IDEAS.md)", + "Write(.claude/knowledge/TECH_DEBT.md)" ], "deny": [ "Bash(git push --force:*)", diff --git a/.claude/skills/cca2a/concepts.md b/.claude/skills/cca2a/concepts.md index dbe22db1..223b56f7 100644 --- a/.claude/skills/cca2a/concepts.md +++ b/.claude/skills/cca2a/concepts.md @@ -58,27 +58,56 @@ scales. Don't entangle them. ## Governance Rules -### Append-only history (four bookkeeping files, unified rule) - -The workspace carries four bookkeeping files. Rows / entries inside -them are immutable historical record; specific fields per file are -mutable state. Never delete a row. Supersedure is a new row that -cites the old; the old row's Status updates to "Superseded by -<new>". - -| File | Immutable (rows) | Mutable (state fields) | -|---|---|---| -| `PR_ARC_INVENTORY.md` | PR rows (Added / Locked / Deferred / Docs) | Confidence line per entry; Corrections APPEND as dated lines | -| `LATEST_STATE.md` | Recently-shipped PR table | Current Inventory / Active Branches / Queued / Deferred snapshots (updated by replacement) | -| `STATUS_BOARD.md` | Deliverable rows (D-id / title / plan-version / scope) | Status column + PR / Evidence column per row | -| `INTEGRATION_PLANS.md` | Plan entries (scope / path / deliverables) | Status + Confidence lines per entry | - -Governance enforcement: `.claude/settings.json::permissions.ask` on -Edit of `PR_ARC_INVENTORY.md` and `LATEST_STATE.md` surfaces any -edit as an approval prompt. Write for appends stays unprompted. -`STATUS_BOARD.md` and `INTEGRATION_PLANS.md` are less strict (Edit -is allowed without prompt since their Status fields move often) but -the same immutable-rows discipline applies by convention. +### Append-only history (eight bookkeeping files, unified rule) + +The workspace carries eight bookkeeping files. Rows / entries +inside them are immutable historical record; specific fields per +file are mutable state. Never delete a row. Supersedure is a new +row that cites the old; the old row's Status updates to +"Superseded by <new>". + +| File | Role | Immutable (rows) | Mutable (state fields) | +|---|---|---|---| +| `PR_ARC_INVENTORY.md` | Per-PR decision arc | PR rows (Added / Locked / Deferred / Docs) | Confidence + Corrections APPEND | +| `LATEST_STATE.md` | Current-state snapshot | Recently-shipped PR table | Snapshot sections updated by replacement | +| `STATUS_BOARD.md` | Deliverable-level dashboard | Rows (D-id / title / plan / scope) | Status, PR/Evidence per row | +| `INTEGRATION_PLANS.md` | Versioned plan index | Entries (scope / path / deliverables) | Status + Confidence per entry | +| `EPIPHANIES.md` | Dated insight log | Entry bodies | Status line (FINDING/CONJECTURE/SUPERSEDED) | +| `ISSUES.md` | Open + Resolved bugs | Entry bodies | Status + Resolution line (append on close) | +| `IDEAS.md` | Open + Implemented + Rejected speculation | Entry bodies | Status + Rationale line (append) | +| `TECH_DEBT.md` | Open + Paid debt | Entry bodies | Status + Payoff line (append) | + +**Method hierarchy (preferred → discouraged):** + +1. **APPEND** (the method of choice) — add a NEW dated row. Either + Edit-to-prepend inside a bounded section, or `Bash cat >> + file << EOF`. No prompt. Old rows stay untouched. This is the + double-bookkeeping pattern: new state = new row, not mutation. +2. **Edit field with prior Read** — flip a mutable field + (Status / Confidence / Resolution / Payoff) on an existing row + after reading the file. No prompt. Use for clarifications and + status transitions on already-captured entries. +3. **Write (full overwrite)** — prompts via + `.claude/settings.json::permissions.ask`. Discouraged; only for + wholesale replacement after explicit review. + +**Rule:** when in doubt, APPEND. Double-bookkeeping keeps the +arc intact and makes the audit trail legible. Edit-a-field is the +lighter touch for clear status transitions. Write is the escape +hatch that costs a confirmation because it can destroy history. + +**Kanban discipline** — three files track work items that must +not get buried: `ISSUES.md`, `IDEAS.md`, `TECH_DEBT.md`. Every +entry carries: + +- **Priority** — P0 blocker / P1 high / P2 medium / P3 low. +- **Scope** — `@<agent-name>`, `D<N>` (plan D-id), + `domain:<grammar|codec|arigraph|infra|...>`. + +Agents filter by their own `@`-mention or their domain. Status +moves through Open → In Progress → Resolved / Implemented / Paid. +Nothing falls through the cracks because every ticket has an owner +named by `@`. Core invariant: **the arc is the record; rewriting it destroys the "why was this decided that way" context that prevents future From aa7e128328830727b06e7be92ab8e88cd968e2f3 Mon Sep 17 00:00:00 2001 From: Claude <noreply@anthropic.com> Date: Sun, 19 Apr 2026 12:03:45 +0000 Subject: [PATCH 18/18] chore(skill): update cca2a SKILL.md to reflect 4-file kanban expansion List now shows 8 bookkeeping files split into history/dashboards (4) and kanban/audit (4 new). Kanban files explicitly note their double/triple-entry discipline + Priority + Scope tagging. --- .claude/skills/cca2a/SKILL.md | 29 +++++++++++++++++++---------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/.claude/skills/cca2a/SKILL.md b/.claude/skills/cca2a/SKILL.md index fa7955a9..2aca8ed2 100644 --- a/.claude/skills/cca2a/SKILL.md +++ b/.claude/skills/cca2a/SKILL.md @@ -21,18 +21,27 @@ grok it once instead of the user re-deriving it for 30 turns. - `.claude/BOOT.md` — session entry point (one page). - `CLAUDE.md` — workspace spec, links to all of the below. -**Four bookkeeping files (rows are history; specific fields are -state; never delete a row):** +**Eight bookkeeping files** (rows are history; specific fields are +state; never delete a row; method hierarchy: APPEND preferred → +Edit-field after prior Read → Write prompts for confirmation): + +_History / dashboards:_ - `.claude/knowledge/LATEST_STATE.md` — current contract inventory. - Mutable: Current Inventory / Active Branches / Queued / Deferred - snapshots. - `.claude/knowledge/PR_ARC_INVENTORY.md` — APPEND-ONLY per-PR arc. - Mutable: Confidence line per entry; corrections APPEND as dated - lines. -- `.claude/knowledge/STATUS_BOARD.md` — deliverable-level dashboard - across all plans. Mutable: Status + PR / Evidence columns per row. -- `.claude/knowledge/INTEGRATION_PLANS.md` — APPEND-ONLY versioned - plan index. Mutable: Status + Confidence per entry. +- `.claude/knowledge/STATUS_BOARD.md` — deliverable-level dashboard. +- `.claude/knowledge/INTEGRATION_PLANS.md` — versioned plan index. + +_Kanban / audit (priority + scope tags on every entry):_ +- `.claude/knowledge/EPIPHANIES.md` — date-prefixed insight log. + Status: FINDING / CONJECTURE / SUPERSEDED. +- `.claude/knowledge/ISSUES.md` — Open + Resolved bugs / regressions. + Double-entry: issue captured on discovery; Resolution appends on + close. Priority P0-P3, Scope @agent D<N> domain:<tag>. +- `.claude/knowledge/IDEAS.md` — Open + Implemented + Rejected + speculation. Triple-entry: idea captured, shipped appended, + plan-update logged. Priority + Scope. +- `.claude/knowledge/TECH_DEBT.md` — Open + Paid knowingly-deferred + work. Priority + Scope + Introduced-by-PR + Payoff-estimate. **Agent ensemble + orchestration:** - `.claude/agents/BOOT.md` — orchestration spec + Knowledge