diff --git a/home_root/.claude/CLAUDE.md b/home_root/.claude/CLAUDE.md index 8c591f4..b6f5499 100644 --- a/home_root/.claude/CLAUDE.md +++ b/home_root/.claude/CLAUDE.md @@ -117,6 +117,59 @@ decisions, and sharpens it with the decision-tree-for-pending-calls requirement. `/elitk` is the grade and the tool; its King framing — smart reader, zero jargon — is exactly the operator mid-context-shift. +## Persistent memory (`persistent-memory.md`) + +Most Corviduo repos carry a `persistent-memory.md` at their root — the +durable record of **intent and supporting evidence** (goals, dated +decisions, foot-gun warnings, in-flight state) that survives a context +reset. As of 2026-08-07, 48 repos have one and 18 have the companion +`persistent-memory.d/`. It is the direct instrument of the +cognitive-load-reduction mission above: it is what lets the operator +re-enter a project without reloading its context from scratch. + +**The canon lives in the `/snapshot` skill** +(`~/.claude/skills/snapshot/SKILL.md`, contract alongside it) — file +schema, section taxonomy, the two-tier index/detail split, the soft +cap and its archival guards, the handoff file. **Do not restate that +canon here or in a project `CLAUDE.md`.** A second copy is a sync +surface that drifts silently; point at the skill instead. Read it when +writing memory, not from recall. + +What every session needs before it loads the skill: + +1. **Read `persistent-memory.md` at session start**, alongside the + project `CLAUDE.md` and auto-memory. It is one input among three, + not the single source of truth. +2. **Check the handoff.** `persistent-memory.md` opens with a + handoff-check header naming `/tmp/-handoff.md`. If + that file exists and its `Written:` stamp is under an hour old, read + it, then delete it. Older: stale — delete unread. This is the + post-`/clear` resume vector; no pasted prompt required. +3. **Never bulk-read `persistent-memory.d/`.** The dated log sections + are two-tier: a one-line index entry lives in `persistent-memory.md`, + the full body in `persistent-memory.d/.md`. Pull a detail file + only when its index line is relevant. Bulk-reading defeats the entire + point of the split. +4. **Commit memory alongside the work.** Any pending + `persistent-memory.md`, `persistent-memory.d/` or + `archival-memory.md` changes ship in the same commit as whatever + prompted them. Durable memory that lags the code defeats its own + purpose. (Memory-snapshot-only commits still skip the version bump — + see the SemVer SKIP list.) + +**The three-way split, restated because sessions get it wrong:** +project `CLAUDE.md` owns mechanical conventions (how code is written — +stable per repo); `~/.claude/projects//memory/` owns +user/feedback/project/reference traits (durable across sessions); +`persistent-memory.md` owns temporal state and dated decisions (what +`CLAUDE.md` by design cannot carry). Before adding a row to +persistent-memory, ask: *could a session that read only `CLAUDE.md` +figure this out?* If yes, it belongs in `CLAUDE.md`. + +**`/snapshot` is operator-invoked, never automatic.** Reset hygiene is +his call. `/handoff` is the sibling for transferring active work to an +agent of another family — different artifact, different purpose. + ## Conversational register / personality In conversation, be a bit less dry — you have a personality, use it. @@ -311,8 +364,9 @@ For work implemented directly in-session. This is the **House Code Discipline** — the canonical full pipeline, end to end: > **concept** (heid refinement optional) → **contract** → **contract -> review** → **TDD slices** (all of them) → **heid code-review** → -> **fixup** → **heid bug-hunt** → **fixup** → **merge/commit** +> review** → **seam review** → **TDD slices** (all of them) → **heid +> code-review** → **fixup** → **heid bug-hunt** → **fixup** → +> **merge/commit** As numbered stages: @@ -323,20 +377,53 @@ As numbered stages: first per the rule above). 3. **Contract review.** `/heid-contract-review`, then **fixup** the contract per triaged findings. -4. **TDD slices.** `/tdd` — red-green-refactor against the contract, +4. **Seam review — the sibling-aware second gate.** + `/heid-contract-review` is **artifact-only by design**: the arms read + one `.contract.md` and are forbidden the `depends_on` siblings, the + config, and the design docs. That firewall is exactly what buys the + fresh-eyes property — and it means the cold pass **structurally + cannot check a single cross-module seam.** + + So after the cold pass and its fixup, run a pass that *does* see the + siblings: for every symbol, type, field, and comparand the contract + borrows from a `depends_on` module, check it against **the real + module surface** — the actual `.py`, not the sibling contract's + prose. Caller-side, in-session, no dispatch. It is a reading, not a + consult; do it directly rather than delegating, because the value is + in holding both surfaces at once. + + **What it catches that neither neighbour can.** The cold panel cannot + see the sibling. A same-model self-review shares the author's priming + and converges with it. Type and comparand drift across a module + boundary is invisible to both. Expected symptom: a contract naming a + field, parameter, or return shape the sibling module does not + actually have. + + **Provenance.** All four arms of the 2026-08-01 Edict U7 panel + proposed this independently in their meta-notes — 4-of-4, unprompted, + in no flag list, and the only thing they agreed on without being + asked. Converges with the pass that had already caught three real + mismatches before U5's first line of code, and that found + `core.config.load_catalog` never validated its slot keys, days before + U7's contract would have depended on it. +5. **TDD slices.** `/tdd` — red-green-refactor against the contract, through *all* the slices, not just a single tracer bullet. -5. **Heid code-review.** `/heid-code-review` (code-vs-contract drift), +6. **Heid code-review.** `/heid-code-review` (code-vs-contract drift), then **fixup** the code per triaged findings. -6. **Heid bug-hunt.** `/heid-bug-hunt` (diff-scoped robustness hunt — +7. **Heid bug-hunt.** `/heid-bug-hunt` (diff-scoped robustness hunt — crashes, leaks, removed guards, caller breaks, false rejects), then **fixup** per triaged findings. -7. **Merge/commit** when clean. +8. **Merge/commit** when clean. **Partial discipline for surgical fixes.** Surgical / localized work — one-liners, small bug fixes, surgical test updates — does not need the full front matter: **TDD + bug-hunt is the acceptable reduced -discipline** (drop the concept → contract → contract-review ceremony, -keep the two implementation-quality gates). Composes with the +discipline** (drop the concept → contract → contract-review → seam-review +front matter, keep the two implementation-quality gates). One exception +worth naming: if a surgical fix *changes a signature or a shared value +shape*, keep the seam review — that is precisely the change whose blast +radius lands in another module, and it is cheap when the diff is small. +Composes with the Contract-skip privilege above: skip *authoring* a contract, but update any live contract governing the touched behavior in the same commit so it stays canonical. When in doubt about whether a fix is "surgical