From 85be5eb900bf8d4241d909890f33c246efb0a5f7 Mon Sep 17 00:00:00 2001 From: "russell@unturf.com" Date: Sun, 10 May 2026 09:03:48 -0400 Subject: [PATCH] CLAUDE.md: substrate/ convention + fix broken import landed in 654d923 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CLAUDE.md ========= Architecture diagram refreshed to include every current arborist/ subdir (was missing capital/, concepts/, memory/, mesh/, pi_star/, selfmodel/, substrate/, world/ and several top-level modules) and the qa/ tree got the recently-landed members (canonical_cache.py #000027, witness.py #000028, warrant_resolver.py #000031). New explanatory paragraph names the topic-named convention explicitly: > Topic-named, never version-prefixed. The substrate-paper version > (v7 plastic-training, v8 selection/consensus, v9 falsification > controller, …) and the live SQLite schema version (v9.8) are two > unrelated numbering schemes that share decimals; version-prefixed > dirs were tried 2026-05-10 and retired the same day because > readers asked "is this schema-v7 or paper-v7?". Future blackops shifts looking at where to put a new module now find the answer in CLAUDE.md instead of having to reverse-engineer the convention. arborist/substrate/fork_score.py — fix broken import ==================================================== Previous commit 654d923 (the v7+v8 → substrate refactor) shipped broken. Sequence: 1. ``git mv arborist/v8/fork_score.py arborist/substrate/fork_score.py`` — staged the rename. 2. Edited the file to flip ``from arborist.v8.weights ...`` → ``from arborist.substrate.weights ...`` — modified the working tree but did NOT re-stage. 3. Selective ``git add`` of the other touched files (cli.py, substrate/__init__.py, docs, tests) — fork_score.py's import edit was NOT in the staged change set. 4. ``git commit`` shipped the rename WITHOUT the import fix. HEAD's fork_score.py imports ``arborist.v8.weights`` — a path that 654d923 itself deleted. Tests passed locally because the disk had the edit; a fresh checkout from origin/main breaks at import time. This commit lands the import edit. Verified: ``git show HEAD:arborist/substrate/fork_score.py`` now has ``arborist.substrate.weights``; full suite re-runs at 1643 passed. Lesson: ``git mv`` stages the rename only. Modifications after that need their own ``git add``. Selective-add commits should run ``git diff --cached`` (not just ``git diff``) before commit. Adding this to my own habit list. --- CLAUDE.md | 36 ++++++++++++++++++++++++++++++-- arborist/substrate/fork_score.py | 2 +- 2 files changed, 35 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index d6edfb3..5496268 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -48,6 +48,10 @@ arborist/ ├── source.py # Source ABC: iter_documents() ├── ingest.py # batched normalize → chunk → merkle → upsert ├── evict.py # hot↔cold + rehydrate (v9.8 falsification on drift) +├── compress.py # chunk pack/unpack (zstd dictionary trained on corpus) +├── snapshot.py # snapshot.db creation + load +├── journal.py # NDJSON unfirehose journal sink +├── wikitext.py # to_base(): wikitext → plain prose (BASE_VERSION-pinned) ├── search/ # SearchBackend ABC + AuditMode + FTS5 ├── sources/ # one file per corpus (wikipedia, html_page, │ # claim_pack, textbook_tex, grok, vcs, …) @@ -62,13 +66,41 @@ arborist/ │ ├── quantifier.py # broad-quantifier classifier (#000008 P1) │ ├── model_profiles.py # per-model claim-cap profiles (#000008 P2) │ ├── quantifier_reminder.py # broad-query reminder text (#000008 P3) +│ ├── canonical_cache.py # canonical-projection persistence (#000027) +│ ├── witness.py # multi-witness fan-out (#000028) +│ ├── warrant_resolver.py # claim-pack warrant chain resolution (#000031) │ └── runner.py # ask(): cache → infer → verify → write -├── wikitext.py # to_base(): wikitext → plain prose (BASE_VERSION-pinned) +├── concepts/ # corpus-derived synonym + rivalry layer (#000018 sib.) +├── pi_star/ # canonical projection π* registry (#000015) +│ # arithmetic@v1, logic-kernel@v1, algebra-symbolic@v1, … +├── memory/ # MemoryRoot lifelong-learning audit chain (#000017) +├── selfmodel/ # SelfModel snapshot + falsify (#000014) +├── capital/ # 8-form capital ledger (#000020) +├── substrate/ # Merkle-AGI substrate primitives (paper-spec'd) +│ ├── anchor_prg.py # φ_PRG HMAC-SHA-512 (v7 §9.10; #000035) +│ ├── fork_score.py # ScoredFork decision fn (v8; #000012 P1a) +│ └── weights.py # ForkScore weight set +├── world/ # v7-W spatial-temporal substrate reservation (#000013; +│ # namespace stub; future kernels under world/pi_star/, +│ # world/frontier/, world/adapters/) +├── mesh/ # mesh wire format + group-key state machine └── cli.py # ingest / search / verify / stats / distill / # evict / rehydrate / ask / providence / emergent / - # reclassify / inspect / analyze + # reclassify / inspect / analyze / canon / sweep / + # warrant-resolve / alias / capital / selfmodel ``` +**Dir naming convention.** Topic-named, never version-prefixed. The +substrate-paper version (v7 plastic-training, v8 selection/consensus, +v9 falsification controller, …) and the live SQLite schema version +(v9.8) are two unrelated numbering schemes that share decimals; +version-prefixed dirs (``arborist/v7/``, ``arborist/v8/``) were tried +2026-05-10 and retired the same day because readers asked "is this +schema-v7 or paper-v7?". Substrate-paper-spec'd primitives now live +under ``arborist/substrate/``; topic dirs (``capital/``, ``memory/``, +``selfmodel/``, ``concepts/``, ``pi_star/``) hold cross-version +mechanisms. + ## Build, test, run Every workflow is a `make` target. Bare python is not the user diff --git a/arborist/substrate/fork_score.py b/arborist/substrate/fork_score.py index e6b2d3e..7ed1e1e 100644 --- a/arborist/substrate/fork_score.py +++ b/arborist/substrate/fork_score.py @@ -27,7 +27,7 @@ import math from dataclasses import asdict, dataclass, field from typing import Iterable, Optional -from arborist.v8.weights import DEFAULT_WEIGHTS, WeightSet +from arborist.substrate.weights import DEFAULT_WEIGHTS, WeightSet SIGNAL_FLOOR = 0.05