Files
claude/lib/capitalize-commit.md
bchanot e0311f4d4f feat(memory): check --staged refuses a new entry that skips or reuses an ID
A new ## entry must carry the next free ID, replayed in line order the way add allocates it. The rule runs only on a v2 HEAD with entries, so upgrade, first commits and template imports pass.
2026-11-15 21:59:04 +01:00

140 lines
7.5 KiB
Markdown

# CAPITALIZE-COMMIT — couple the memory commit to the dev flow
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; § WRITE then
writes them through lib/memory.sh and the COMMIT is automated here.
## WHEN TO RUN
At the capitalize step, once the approved entries are written to
`.claude/memory/*` (and any `.claude/tasks/TODO.md` reconcile is done), with the
code already committed.
- Inline-commit flows (feat / hotfix / bugfix / commit-change): run it right
after writing the entries, on the current branch.
- Orchestrators that integrate via `gitflow finish` (the upstream
finishing-a-development-branch is not vendored; ship-feature / init-project):
run it BEFORE the FINISH step — otherwise the memory commit strands outside
the merge/PR. See ORDERING.
This snippet commits whatever is PENDING under `.claude/memory` + `.claude/tasks`;
it does NOT decide content. A flow whose gate wrote only a journal line yields a
`chore(memory): journal — …` commit (one memory commit per flow — Frame 2 / F3).
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. Every verb takes
`-C <project root>` when the cwd is not the project root; it `cd`s first, so
give `--body-file` an absolute path. Captured text (memory_pending lines,
commands, excerpts) goes into the body file only, written through a quoted
heredoc with a unique delimiter (`MEMCAP_EOF_<random>`), never `echo`/`printf`,
never a shell argument.
- 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.
- 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,
an unfenced body line starting `## ` (use `###` or indent it),
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
`chore(memory): <IDs> — <flow> <short>`. Examples:
- `chore(memory): BDR-034 + LRN-051 — feat dark-mode toggle`
- `chore(memory): BLK-010 resolved — bugfix profile path`
- `chore(memory): journal — hotfix copy typo` (journal-only, nothing else)
2. Commit surgically via the helper, capturing the memory-commit hash it prints:
mem_hash=$(bash "$HOME/.claude/lib/memory-commit.sh" commit "<message>")
rc=$?
3. Report by (rc, mem_hash):
- rc 0, mem_hash non-empty → `✅ mémoire committée <mem_hash>`
- rc 0, mem_hash empty → `CAPITALIZE: rien à committer` (helper no-op)
- rc 3 → unsafe git state (detached / merge in progress);
memory stays in the working tree for a manual
commit — surface the helper's stderr.
- rc 5 → `git commit` rejected (hook, protected branch,
signing); nothing committed, surface stderr.
- rc 6 → `memory.sh check --staged` refused, nothing
committed, nothing left staged. Causes,
named on stderr: a line removed inside an
existing v2 entry (only appends pass), a NEW
culprit (duplicate ID, heading shape), a new
entry whose ID is not the next free ID
(stderr names the expected one; a committed
ID is never renamed: fix only the uncommitted
new heading and every uncommitted mention of
its ID, the `superseded by` line `add
--supersedes` wrote, the journal line, or
drop the new entry and that line and re-add
it with memory.sh add), or a HEAD or staged
blob git cannot read; an open
code fence counts even when it predates the
commit. A path staged apart from its working
tree loses that stage: stderr names it with
its blob id and the git update-index restore
command. Fix the file, then commit the fix
with /commit-change; never bypass the helper.
`<mem_hash>` is the MEMORY commit (the one that ADDS the entries). It is NOT
the code-commit hash that capitalize anchored INSIDE the entries
(`Reference: commit <code-hash>`). Two commits, two hashes — never report the
code hash here.
## HARD RULE — surgical scope
The helper stages and commits ONLY `.claude/memory` + `.claude/tasks`, filtered
to paths with real changes, via pathspec — never `git add -A` / `git add .` /
`git commit -a`. Automation removes the human diff review that would catch an
accidental stage, so the scope IS the safety. Do NOT bypass the helper with a
manual `git add` / `git commit`: that reintroduces the exact risk the helper
removes (proven: dangling code, untracked or pre-staged, is never embarked; a
no-match pathspec is filtered, not fatal).
## ORDERING (orchestrators only)
`finishing-a-development-branch` (upstream superpowers skill, not vendored
here; `gitflow finish` is the only integration path) may merge-and-delete the
branch or push a PR. A memory commit created AFTER it lands outside the
integrated history — stranded on the PR path. So in ship-feature / init-project
this snippet runs BEFORE FINISH. The code commits already exist (implementation
step), so the entries' hash references are valid at this point.
## WHAT THIS DOES NOT DO
- Does NOT commit code — the code commit happened upstream (implementation step).
- Does NOT push — pushing / merging is FINISH's job, which runs AFTER this in
orchestrators.
- Does NOT decide WHAT to capitalize — the scan + approval gate upstream own
that; this only commits what was already approved and written.
- Does NOT reference or echo the code-commit hash anchored in the entries — it
reports only the memory-commit hash the helper returns.
- Does NOT run if you hand-roll `git add` / `git commit` instead of the helper —
bypassing it drops the surgical-scope guarantee. Always call the helper.
## IDEMPOTENT
Safe to run when memory is already clean: the helper no-ops (exit 0, empty
stdout, no commit). Running it twice creates at most one commit.