6.6 KiB
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.
- 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.-Cwhen 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,
an unfenced body line starting
##(use###or indent it), unknown ID, lock busy): fix the input and re-run.
DO
-
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 togglechore(memory): BLK-010 resolved — bugfix profile pathchore(memory): journal — hotfix copy typo(journal-only, nothing else)
-
Commit surgically via the helper, capturing the memory-commit hash it prints:
mem_hash=$(bash "$HOME/.claude/lib/memory-commit.sh" commit "<message>") rc=$? -
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 commitrejected (hook, protected branch, signing); nothing committed, surface stderr. - rc 6 →
memory.sh check --stagedrefused, 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), 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. - rc 0, mem_hash non-empty →
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 commitinstead 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.