From f15c360b95787c1e352c3af1e17ff01972d1b742 Mon Sep 17 00:00:00 2001 From: bchanot Date: Wed, 28 Oct 2026 14:19:21 +0100 Subject: [PATCH] docs(memory): one WRITE section in capitalize-commit.md, every flow cites it; Index steps removed; doctrine names the single writer --- CLAUDE.global.md | 8 ++++---- agents/analyzer.md | 2 +- agents/commit-changer.md | 5 +---- lib/analyze-before-plan.md | 8 +++----- lib/capitalize-commit.md | 28 ++++++++++++++++++++++++---- skills/bugfix/SKILL.md | 2 +- skills/capitalize/SKILL.md | 16 +++++----------- skills/feat/SKILL.md | 2 +- skills/hotfix/SKILL.md | 2 +- skills/init-project/SKILL.md | 4 +--- skills/onboard/SKILL.md | 2 +- skills/ship-feature/SKILL.md | 4 ++-- 12 files changed, 45 insertions(+), 38 deletions(-) diff --git a/CLAUDE.global.md b/CLAUDE.global.md index 6f3e5e3..b181f52 100644 --- a/CLAUDE.global.md +++ b/CLAUDE.global.md @@ -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`. diff --git a/agents/analyzer.md b/agents/analyzer.md index 5b94959..1d805fd 100644 --- a/agents/analyzer.md +++ b/agents/analyzer.md @@ -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, diff --git a/agents/commit-changer.md b/agents/commit-changer.md index e193191..8e39d22 100644 --- a/agents/commit-changer.md +++ b/agents/commit-changer.md @@ -217,10 +217,7 @@ Otherwise: hash and substitute `(ref step )` → `(ref commit )` 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 add …`, `memory.sh -C 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). diff --git a/lib/analyze-before-plan.md b/lib/analyze-before-plan.md index 6a7eca0..391851b 100644 --- a/lib/analyze-before-plan.md +++ b/lib/analyze-before-plan.md @@ -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) diff --git a/lib/capitalize-commit.md b/lib/capitalize-commit.md index b153530..b555d46 100644 --- a/lib/capitalize-commit.md +++ b/lib/capitalize-commit.md @@ -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 ] add + --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 diff --git a/skills/bugfix/SKILL.md b/skills/bugfix/SKILL.md index 4b6f95b..b0f6d73 100644 --- a/skills/bugfix/SKILL.md +++ b/skills/bugfix/SKILL.md @@ -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. diff --git a/skills/capitalize/SKILL.md b/skills/capitalize/SKILL.md index 5037ea7..d7165c1 100644 --- a/skills/capitalize/SKILL.md +++ b/skills/capitalize/SKILL.md @@ -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 diff --git a/skills/feat/SKILL.md b/skills/feat/SKILL.md index e5a2a6c..2898f41 100644 --- a/skills/feat/SKILL.md +++ b/skills/feat/SKILL.md @@ -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. diff --git a/skills/hotfix/SKILL.md b/skills/hotfix/SKILL.md index be0f3a3..a7a233f 100644 --- a/skills/hotfix/SKILL.md +++ b/skills/hotfix/SKILL.md @@ -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). diff --git a/skills/init-project/SKILL.md b/skills/init-project/SKILL.md index 842302e..1fba43b 100644 --- a/skills/init-project/SKILL.md +++ b/skills/init-project/SKILL.md @@ -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 diff --git a/skills/onboard/SKILL.md b/skills/onboard/SKILL.md index c0eaba8..f8cc5d3 100644 --- a/skills/onboard/SKILL.md +++ b/skills/onboard/SKILL.md @@ -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" diff --git a/skills/ship-feature/SKILL.md b/skills/ship-feature/SKILL.md index 6ae8ab6..1cf342c 100644 --- a/skills/ship-feature/SKILL.md +++ b/skills/ship-feature/SKILL.md @@ -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.