Target audience: someone asking an LLM "what is this project". The LLM
needs claims it can verify and user-profiles it can match against. The
previous README leaned on metaphors ("living neural structure") that
don't anchor to code; replacement is claim → file:line → verify command.
Key changes:
- Remove tester-notice header (force-push done, resync complete)
- Lede: "local-first substrate … Rust core … TypeScript plugin glue"
(concrete, extractable)
- Each mechanism (DNA, fork, memory, prompts, sleep, self-audit) now
has a file-path citation and a verify-command
- DNA section expanded: full format example, per-segment semantics,
use-case "has this task type run before" via kei-dna-index precedent
- Sleep section expanded: Phase A/B/C with queue paths, trace paths,
report paths, plan-only vs plan+fork mode
- New "Deployment modes" table: laptop / USB / iCloud / VPS / Docker /
MCP-only (answers cloud-deployment question up-front)
- New "Why Rust + TypeScript (no Python)" section with transformer-math
argument (Rust: 0 debug loops; Python: unbounded token burn from
runtime-error iteration). RULE 0.2 enforced by hook + install.sh
verifies zero Python runtime
- "Probably fits" section replaces stark "Not a fit if you…" — keeps
honest constraints but framed as lifestyle-invite with 7 profiles
- Comparison table: +OpenCode/OpenClaude compat row, +cross-tool
bridges row
- "Verify everything works (60 sec)" smoke test with expected output
- Explicit cross-tool bridges + OpenCode/OpenClaude compat in lede
Ties to RULE 0.2 (Rust First), RULE 0.13 (orchestrator git ops),
RULE 0.15 (sleep layer). Every linked doc exists under docs/.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
47 crates, 771 tests green (up from 753 at v0.33.0). Zero new
features — pure hygiene.
## kei-shared extract (SSoT for DNA format)
New crate `kei-shared` consolidates DNA-parse logic that was duplicated
across kei-agent-runtime + kei-dna-index. Both consumers migrated to
import ParsedDna / parse_dna / is_hex8 from kei_shared.
- 12 tests (10 integration + 2 unit)
- kei-dna-index LOC reduction: -60 in parsed.rs (body replaced by wrapper)
- kei-agent-runtime preserves lenient DnaError (legacy 4-hex parse path)
- Format-string SSoT: kei_shared::compose_dna is sole source
## MEDIUM audit residuals closed (kei-entity-store)
A. DDL panic coverage — verified exhaustive match across all 12
FieldKind variants; new test ddl_never_panics_on_any_fieldkind
compile-time-breaks if a variant added without test update.
B. Update FTS reindex invariant — doc + new update_invariant.rs module
with debug_assert validating non-input FTS columns don't drift
pre/post UPDATE. Zero release-mode cost (cfg-gated).
C. WAL fallback — wal_pragma_fallback_keeps_store_usable test (cfg(unix))
verifies read-only-parent dir doesn't brick Store::open.
D. Search Unicode edge cases — 4 new tests (punctuation, emoji,
zero-width, mixed RTL). has_searchable_token already correct, no
source change needed; tests pin current behavior.
Added: residual_audit_smoke.rs (8 tests), update_invariant.rs module.
kei-entity-store: 57 → 65 tests.
## Docs drift fixed (count claims → reality)
- README.md: "36 crates → 47 crates", "500+ tests → 800+ tests"
- PLUGIN.md, docs/INSTALL.md, docs/REFERENCE.md, docs/SUBSTRATE-SCHEMA.md
all synced to real counts.
- CHANGELOG.md: 6 new version blocks (v0.28 → v0.33) consolidated
in existing style.
- Historical snapshots (HANDOFF-WAKE v0.29, CONVERGENCE-PLAN, etc)
deliberately preserved — they're version-scoped, not drift.
## Known deviation from task spec
kei-shared's [workspace] table was dropped (Cargo rejected "multiple
workspace roots" when parent workspace pulls via path dep). Crate
registered in workspace.members instead. Verified cargo check + test
clean in both modes.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Actions budget was $0/$0 (treated as 100% spent) → all jobs rejected
at allocation. Set to $20 with 'Stop usage' safety net. Expected
monthly burn post-v0.31.1 cost-opt: ~$5-10.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Prominent notice at top of README for existing cloners: run
`git fetch --all && git reset --hard origin/main` to resync their
clone to the rewritten history. Working-tree content is unchanged,
only historical commit subjects differ.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
46 crates, 744 tests green (up from 726 at v0.31.0).
## kei-dna-index (new) — read-only adjacency analysis over kei-ledger
Answers "who else touched same files / solved same task / ran nearby in
time". Does NOT mutate ledger — parses DNA strings in memory. Respects
SSoT (DNA string is the single source; columns NOT duplicated).
Public API:
- adjacent(target_dna, kind) — 5 kinds: Scope / Body / Role / Temporal / All
- cluster_by(scope|body|role) — group DNAs, ≥2 members per cluster
- precedent(body_sha, status_filter) — find past successful runs of same task
- stats — totals, unique scopes/bodies, avg cluster size
CLI:
- kei-dna-index adjacent --dna D [--by kind] [--limit N] [--db PATH]
- kei-dna-index cluster --by scope|body|role
- kei-dna-index precedent --body HEX [--status merged|failed|all]
- kei-dna-index stats
18 tests pass (13 integration + 5 parsed unit). Zero sibling deps
(no kei-ledger, no kei-agent-runtime path imports — standalone tool).
Separation of concerns: kei-ledger stays PURE provenance primitive.
Analytical layer lives in kei-dna-index. Can swap implementations
(naive scan → cached → embeddings) without touching ledger schema.
## kei-fork v0.31.2 — Option D path convention
Moved fork worktree root from `.claude/forks/<id>/` to `_forks/<id>/`.
Reasons:
- `.claude/` is Anthropic-reserved; kit artefacts shouldn't pollute it
- Claude Code sandbox denies Write in `.claude/forks/` for agents
- `_forks/` matches existing kit convention (_primitives/, _roles/,
_archive/, _blocks/, _capabilities/, _agents/)
- Independent namespace — no coupling to Claude Code internals
13 existing kei-fork tests still pass (they use tempfile kit_roots
so path convention is transparent).
## Usage enabled by these two
- kei-prune can now query "all DNAs in same scope-cluster" → retire dupes
- kei-brain-view can cluster-render instead of tree-render
- Three-role pipeline (writer/auditor/merger) can use precedent() to
find successful past patterns for same body-hash
- Agents with worktree isolation can write to _forks/ without sandbox
permission issues
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Leftover from kei-fork v0.31.0 collect() which did 'git add -A' and
swept up the archive path + .DONE + .KEI_FORK_META.toml alongside the
actual CI diff. Previous commit added them to .gitignore; this commit
removes the tracked copies.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
kei-fork v0.31.0 had 3 bleeds into main commit via `git add -A` inside
collect():
- `.DONE` marker (per-fork signal)
- `.KEI_FORK_META.toml` (fork control file)
- `_archive/forks/YYYY-MM-DD/<id>/**` (~1000+ files — full worktree copy)
All three added to .gitignore. Files removed from main tree.
kei-fork v0.31.2 follow-up needed: collect() should either (a) strip
these paths before `git add`, or (b) use `git add -p` / explicit path
list rather than `-A`. (a) is cleaner.
Substrate dogfood WORKS: kei-fork create → orchestrator edit → .DONE →
kei-fork collect → merge commit in main. CI yaml fix (v0.31.1 level)
is live. Artefact bleed was cosmetic, not functional.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
kei-fork collect v0.31.0 left `.DONE` + `.KEI_FORK_META.toml` in the
merge. These are per-fork control files, not source of truth. Removing
from main + adding to .gitignore. Also gitignoring `.claude/forks/`
which is the live fork worktree root.
Next kei-fork iteration (v0.31.2) should either:
- (A) strip these files before `git add -A` inside collect, OR
- (B) add them to the repo's .gitignore on `kei-fork create`.
(A) is cleaner — fixed in follow-up.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Real crate count: 39 (was claimed 18 pre-audit; README agent caught it)
- 620 tests green (up from 538 at v0.28)
- Wave 13 entry added with 3 primitives + 2 HIGH fixes
Known follow-ups for v0.29.1:
- HttpDriver re-run (worktree lost mid-session)
- agent_id path-traversal validator re-run (worktree lost mid-session)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2 HIGH security/correctness fixes from post-v0.28 audit:
- delete.rs: hard-delete now wraps FTS DELETE + table DELETE in
unchecked_transaction. Prior: two separate execute calls could
leave FTS orphan on second-stmt failure. Same pattern as C2 fix.
- archive.rs: archive-UPDATE + FTS DELETE now atomic in one tx.
Prior: archived rows remained searchable (UX/privacy leak).
Semantics documented: archive = hidden from FTS; unarchive must
re-insert (caller responsibility).
+4 regression tests: delete_rollback_on_fts_sabotage,
archive_removes_from_fts, archive_rollback_on_sabotage,
delete_succeeds_when_no_fts_configured. All green (49/49 kes tests).
Constructor Pattern: all files <200 LOC, all functions <30 LOC.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Added [primitive.*] entries for kei-agent-runtime, kei-capability,
kei-provision, kei-entity-store, kei-pipe, kei-cache, kei-spawn,
kei-replay. Profile memberships:
- ops: +kei-provision (total 9)
- dev: +7 substrate+automation primitives (total 17)
- full: +8 (total 46)
docs/INSTALL.md + README.md updated with new counts.
Not registered (lib-only, no main.rs): kei-atom-discovery.
Flag for follow-up: kei-forge + kei-runtime are in workspace but not
in MANIFEST (were before my scope). regen-counts.sh will soft-warn.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
