docs(memory): one WRITE section in capitalize-commit.md, every flow cites it; Index steps removed; doctrine names the single writer

This commit is contained in:
bchanot committed 2026-10-28 14:19:21 +01:00
1 parent 6c9bb7c58b
commit f15c360b95
12 files changed
+45 -38

No files matched your search

+4 -4
View File
@@ -107,8 +107,8 @@ code" wins. Repo-specific instructions override both.
## Memory registries (`.claude/memory/`)
Five registries persist across sessions; capitalize during and after work.
Append-only: never rewrite past entries; curation (merge, supersede,
compress) only via `/prune-memory`.
Append-only, written only through `bash ~/.claude/lib/memory.sh` (add,
status, journal), never by Edit; curation only via `/prune-memory`.
| File | ID | Purpose |
|---|---|---|
@@ -124,8 +124,8 @@ log → journal; whether the output actually worked → evals.
**Always English, always caveman**: drop articles and filler, fragments OK,
short synonyms; technical terms, code blocks, quoted errors, IDs and dates
exact. Pattern `[thing] [action] [reason]. [next step].` Registries load
every session; caveman cuts ~40% of the tokens with no substance lost.
exact. Pattern `[thing] [action] [reason]. [next step].` Planning flows
read the registries; caveman cuts ~40% of every read, no substance lost.
Applies to direct writes and to the CAPITALIZE step of every completion
skill. Prompts to the user may mirror their language; the entry is English.
Legacy entries: compress on demand via `/prune-memory`.
+1 -1
View File
@@ -96,7 +96,7 @@ A surfaced ID left undisposed is the gap this closes. You judge bearing; the mai
plan decides what to DO.
Read-only here too: reading registries is within Read/Grep; the "Do not modify files" rule
still forbids any write — Index backfill or new entries are never your job. Empty or absent
still forbids any write — new entries or status lines are never your job (writes go through lib/memory.sh). Empty or absent
registries → omit the section (no-op).
Tracing what a destructive tool would do (a mirror, a sync with delete, a
recursive rm, a deploy script) is done by reading it, never by running it,
+1 -4
View File
@@ -217,10 +217,7 @@ Otherwise:
hash and substitute `(ref step <n>)` → `(ref commit <hash>)` in every
entry before writing. An entry that names no step (e.g. a pure LRN
pattern) needs no ref.
2. Append the resolved entries to their target registry file(s)
(`.claude/memory/decisions.md`, `blockers.md`, `learnings.md`) and
update each file's `## Index` table. Add a one-line summary of the
commit batch to today's heading in `.claude/memory/journal.md`.
2. Write each resolved entry and one journal line for the batch per `$HOME/.claude/lib/capitalize-commit.md` § WRITE (`memory.sh -C <repo root> add …`, `memory.sh -C <repo root> journal …`; no Index to update).
3. **Language rule**: written entries are ALWAYS in English and caveman,
regardless of the language used in the dispatcher's approval exchange
(CLAUDE.md "Memory registries", Always English, always caveman).
+3 -5
View File
@@ -39,8 +39,7 @@ blocker already solved.
no-match) → no-op naturally; only the ABSENT / no-file case needed the guard. The REGEX
is the filter, not the file list: the glob also reads journal.md (date-keyed
`## YYYY-MM-DD`) and any non-entry file, which contribute zero matches — no need to
exclude them. Do NOT read the `## Index` table: it drifts (entries land in the body, the
manual Index update lapses — measured 32-40% missing on a mature repo); headings cannot.
exclude them. Do NOT read a `## Index` table (v1 registries may still carry one; it drifted 32-40% on a mature repo; v2 has none); headings cannot drift.
3. SELECT — IDs whose title bears on $REQUEST. Judge on titles (one dense line each), not
on bodies. Over-inclusion is SAFE: an entry that proves non-binding costs one bare ref
@@ -97,9 +96,8 @@ is not the current flow having TREATED it as a constraint. Re-surfacing is the f
## HARD RULE — read-only
Touches nothing. No write, no Index update, no memory mutation. Symmetric to
capitalize-commit's surgical scope (there: stage ONLY memory; here: stage NOTHING). Index
backfill, if ever wanted, is `/prune-memory` passe D — never this snippet.
Touches nothing. No write, no memory mutation. Symmetric to
capitalize-commit's surgical scope (there: stage ONLY memory; here: stage NOTHING). Registry writes go through `lib/memory.sh`, never this snippet.
## ORDERING (orchestrators only)
+24 -4
View File
@@ -1,13 +1,13 @@
# CAPITALIZE-COMMIT — couple the memory commit to the dev flow
Inline snippet. Include at the END of any dev flow's CAPITALIZE step, AFTER the
approved registry / journal / TODO entries are written. It commits ONLY the
Inline snippet for any dev flow's CAPITALIZE step: § WRITE says how the approved
registry and journal entries are written, then the rest commits ONLY the
memory, surgically, so the flow never leaves an uncommitted `.claude/memory`
behind and never embarks dangling code.
This is the TAIL of capitalize, not a replacement: the SCAN + APPROVAL GATE that
decide WHAT to write are unchanged and run before this snippet. Only the COMMIT
of the already-approved entries is automated here.
decide WHAT to write are unchanged and run before this snippet; § WRITE then
writes them through lib/memory.sh and the COMMIT is automated here.
## WHEN TO RUN
@@ -29,6 +29,26 @@ If a flow should stay fully silent on a trivial run, that is the FLOW's gate
policy (e.g. hotfix skipping the journal line), not this snippet's concern —
tune it there.
## WRITE (before the commit)
Registry entries and journal lines are written only by `lib/memory.sh`,
never by Edit or append; there is no `## Index` to update.
- Entry: caveman body to a scratch file, then
`bash "$HOME/.claude/lib/memory.sh" [-C <project root>] add
<decision|learning|blocker|eval> --title "<title>" --body-file <file>
[--status <status>] [--supersedes <ID>]`. One call per entry; it
allocates the ID under a lock and prints it. A blocker body quotes ≥1
error in backticks. `-C` when the cwd is not the project root.
- Status change on an existing entry:
`bash "$HOME/.claude/lib/memory.sh" status <ID> "<word> …"`, the text
starting with a status word (`resolved abc1234`, `open, reopened by …`,
`superseded by BDR-NNN`).
- Journal: `bash "$HOME/.claude/lib/memory.sh" journal "<line>"`.
- rc 2 names its reason (title chars, empty body, a status not starting
with a status word, an open code fence in the body or the registry,
unknown ID, lock busy): fix the input and re-run.
## DO
1. Compose the message from the IDs just written + the flow, matching repo style
+1 -1
View File
@@ -272,7 +272,7 @@ A bugfix with an understood root cause is almost always worth one entry:
[LRN-XXX — <pattern>] (optionnel)
Valider ? (all / blockers-only / edit / skip)
```
4. Append approved entries + update the Index. Add a line to today's heading in `.claude/memory/journal.md`.
4. Write approved entries per `lib/capitalize-commit.md` § WRITE: a new blocker `add blocker … --status resolved`, an existing one now fixed `status <BLK-ID> "resolved <hash>"`, an LRN `add learning …` (no status); the journal line `memory.sh journal`.
**Language rule**: written entries are ALWAYS English AND caveman — fragments, articles dropped, code/IDs/quoted errors verbatim — per CLAUDE.md "Memory registries" (Always English, always caveman). The interactive gate may mirror the user's language; the appended entries must not.
+5 -11
View File
@@ -140,7 +140,7 @@ with no dedup.
For every candidate from STEP 1 (and STEP 1B), check whether it is already
captured before proposing it. Pull the distinctive keyword(s) of the candidate
and grep the relevant registry (Index + bodies):
and grep the relevant registry (headings + bodies):
```bash
# Example: candidate is a learning about "cd -P symlink resolution"
@@ -246,14 +246,8 @@ Registries first (in registry order), then the TODO.
Registry entries — for each approved:
1. Read the target registry file.
2. Next sequential ID = scan existing `## <PREFIX>-NNN` body headings, take max,
+1 (e.g. last `## BDR-018` → `BDR-019`). Never reuse, never renumber.
3. Append the full entry at the **end** of the body (never rewrite existing
entries — append-only).
4. Add one row to the `## Index` table at the top: `| <ID> | <date> | <title>
| <status> |` (column set varies per file — match that file's header row).
5. Body in **caveman English** per CLAUDE.md memory format: drop articles +
1. Write each approved entry per `lib/capitalize-commit.md` § WRITE (`memory.sh add`, one call each; a resolved blocker: `memory.sh status <ID> "resolved <hash>"`).
2. Body in **caveman English** per CLAUDE.md memory format: drop articles +
filler, fragments OK, short synonyms. Keep code/URLs/error-quotes/IDs/dates
verbatim. Entries are ALWAYS English even if the STEP 3 prompt mirrored the
user's language.
@@ -269,8 +263,7 @@ TODO — for each approved:
Write one timeline line under today's `## YYYY-MM-DD` heading — even if every
candidate was skipped or already captured.
- Heading exists → append a bullet.
- Missing → create `## YYYY-MM-DD` and write 3-5 bullets summarizing the session.
- `bash "$HOME/.claude/lib/memory.sh" journal "<line>"` per bullet (it creates today's heading when missing).
Reference any IDs written this run AND the TODO ops:
`BDR-019 + LRN-026 capitalized; checked 1 done, added 1 task.`
@@ -302,6 +295,7 @@ Follow `~/.claude/lib/capitalize-commit.md`:
- **rc 3** → unsafe git state (detached / merge / rebase) or not a git repo:
memory stays in the working tree, surface the helper's stderr, do NOT retry.
The flush is safe on disk; STEP 6 must say NOT committed, not ✅-all.
- **rc 5 / rc 6** → nothing committed; surface the helper's stderr; meaning and recovery in `lib/capitalize-commit.md` (rc 6: fix the registry, then /commit-change). STEP 6 says NOT committed.
- **rc 0, hash EMPTY → must NOT happen from this step.** STEP 5 always writes
the journal line, so memory is ALWAYS pending at 5B → the helper always has
≥1 change → the hash is non-empty by construction. An empty hash here means
+1 -1
View File
@@ -245,7 +245,7 @@ CAPITALIZE — proposé
Valider ? (all / <IDs> / edit / skip)
```
Always append a 1-line entry to today's heading in `.claude/memory/journal.md`.
Approved entries and the always-written 1-line journal entry: per `lib/capitalize-commit.md` § WRITE (`memory.sh add` / `memory.sh journal`).
**Language rule**: written entries are ALWAYS English AND caveman — fragments, articles dropped, code/IDs/quoted errors verbatim — per CLAUDE.md "Memory registries" (Always English, always caveman). The interactive gate may mirror the user's language; the appended entries must not.
+1 -1
View File
@@ -231,7 +231,7 @@ Hotfixes are often trivial (typo, config, import) — skip by default. But if th
Default behaviour: `CAPITALIZE: hotfix trivial, skip` (no prompt, no output).
Ask the user only when there is an actual candidate to propose.
Always append a 1-line entry to today's heading in `.claude/memory/journal.md` (even trivial hotfix — journal is timeline, not signal).
Always append a 1-line journal entry (even trivial hotfix — journal is timeline, not signal) and any approved BLK/LRN per `lib/capitalize-commit.md` § WRITE.
**Language rule**: the journal line and any proposed BLK/LRN entries are ALWAYS written English AND caveman — fragments, articles dropped, code/IDs/quoted errors verbatim — per CLAUDE.md "Memory registries" (Always English, always caveman).
+1 -3
View File
@@ -298,9 +298,7 @@ capitalizes NOTHING. Do NOT fabricate a BDR to fill the step. Print
[ decisions.md ] BDR-XXX — <decision> — <1-line why>
Valider lesquels ? (all / <IDs> / edit / skip)
```
3. Append approved entries to the existing registries (bootstrapped at STEP 5,
in the root commit) + update the Index. Append a journal line under today's
heading in `.claude/memory/journal.md`.
3. Write approved entries to the registries bootstrapped at STEP 5 (in the root commit), and the journal line, per `lib/capitalize-commit.md` § WRITE.
**Hash rule — founding decisions carry NO commit hash; use path + date only.**
This is by nature, not an omission: a founding decision is made at DESIGN
+1 -1
View File
@@ -1179,7 +1179,7 @@ per the project's commit convention), and verifies every rule is in
hash and `git -C <ROOT> show --stat <hash>`, the user decides.
S7 — AFTER. `claude -p "/context"` again from `<ROOT>`; append to that
project's `.claude/memory/journal.md` under today's date: `CLAUDE.md
project's journal (`bash "$HOME/.claude/lib/memory.sh" -C <ROOT> journal`): `CLAUDE.md
split: <k> sections → .claude/rules/ (<names>), always-on <before> →
<after>`. Tell the user the proof step: a fresh session in that project
that Reads one file per rule, then `jq -c 'select(.memory_type=="Project"
+2 -2
View File
@@ -270,8 +270,8 @@ Feature shipped implies at least one design decision worth capturing. Run this B
Valider lesquels ? (all / <IDs> / edit / skip)
```
4. Append approved entries to the registries. Update the Index table at the top of each file.
5. Append a one-line entry to `.claude/memory/journal.md` under today's date heading (`## YYYY-MM-DD`).
4. Write approved entries per `lib/capitalize-commit.md` § WRITE (`memory.sh add`, one call each; no Index to update).
5. Journal line: `memory.sh journal` (same section).
**Language rule**: written entries are ALWAYS English AND caveman — fragments, articles dropped, code/IDs/quoted errors verbatim — per CLAUDE.md "Memory registries" (Always English, always caveman). The interactive gate above may mirror the user's language; the appended entries must not.