claude: add the Persistent memory section — point at the /snapshot canon, don't restate it
Adds "## Persistent memory (`persistent-memory.md`)" to the global CLAUDE.md, placed directly after the cognitive-load-reduction section because persistent memory is that mission's instrument: it is what lets the operator re-enter a project without reloading its context. Deliberately a POINTER, not a copy. The canon is the /snapshot skill (~/.claude/skills/snapshot -> ~/development/galdrabok/skills/snapshot, version-controlled there); the section says so explicitly and forbids restating it here or in a project CLAUDE.md, because a second copy is a sync surface that drifts silently. What it does carry is the four things a session needs BEFORE it loads the skill: read persistent-memory.md at session start; check /tmp/<althing-handle>-handoff.md and its 1h staleness rule; never bulk-read persistent-memory.d/; commit memory alongside the work. Plus the three-way split (project CLAUDE.md / auto-memory / persistent-memory) with the redundancy test, because that boundary is the one sessions actually get wrong. Fleet state at time of writing: 48 repos carry persistent-memory.md, 18 carry persistent-memory.d/. Stamped with the date so it reads as a snapshot rather than a standing fact.
This commit is contained in:
@@ -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/<althing-handle>-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/<slug>.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/<sanitized-cwd>/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
|
||||
|
||||
Reference in New Issue
Block a user