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 —
|
requirement. `/elitk` is the grade and the tool; its King framing —
|
||||||
smart reader, zero jargon — is exactly the operator mid-context-shift.
|
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
|
## Conversational register / personality
|
||||||
|
|
||||||
In conversation, be a bit less dry — you have a personality, use it.
|
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:
|
Discipline** — the canonical full pipeline, end to end:
|
||||||
|
|
||||||
> **concept** (heid refinement optional) → **contract** → **contract
|
> **concept** (heid refinement optional) → **contract** → **contract
|
||||||
> review** → **TDD slices** (all of them) → **heid code-review** →
|
> review** → **seam review** → **TDD slices** (all of them) → **heid
|
||||||
> **fixup** → **heid bug-hunt** → **fixup** → **merge/commit**
|
> code-review** → **fixup** → **heid bug-hunt** → **fixup** →
|
||||||
|
> **merge/commit**
|
||||||
|
|
||||||
As numbered stages:
|
As numbered stages:
|
||||||
|
|
||||||
@@ -323,20 +377,53 @@ As numbered stages:
|
|||||||
first per the rule above).
|
first per the rule above).
|
||||||
3. **Contract review.** `/heid-contract-review`, then **fixup** the
|
3. **Contract review.** `/heid-contract-review`, then **fixup** the
|
||||||
contract per triaged findings.
|
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.
|
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.
|
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
|
crashes, leaks, removed guards, caller breaks, false rejects), then
|
||||||
**fixup** per triaged findings.
|
**fixup** per triaged findings.
|
||||||
7. **Merge/commit** when clean.
|
8. **Merge/commit** when clean.
|
||||||
|
|
||||||
**Partial discipline for surgical fixes.** Surgical / localized work —
|
**Partial discipline for surgical fixes.** Surgical / localized work —
|
||||||
one-liners, small bug fixes, surgical test updates — does not need the
|
one-liners, small bug fixes, surgical test updates — does not need the
|
||||||
full front matter: **TDD + bug-hunt is the acceptable reduced
|
full front matter: **TDD + bug-hunt is the acceptable reduced
|
||||||
discipline** (drop the concept → contract → contract-review ceremony,
|
discipline** (drop the concept → contract → contract-review → seam-review
|
||||||
keep the two implementation-quality gates). Composes with the
|
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
|
Contract-skip privilege above: skip *authoring* a contract, but update
|
||||||
any live contract governing the touched behavior in the same commit so
|
any live contract governing the touched behavior in the same commit so
|
||||||
it stays canonical. When in doubt about whether a fix is "surgical
|
it stays canonical. When in doubt about whether a fix is "surgical
|
||||||
|
|||||||
Reference in New Issue
Block a user