From b44791bb1b9d3f4b73a81c5a33c8fc54590498f9 Mon Sep 17 00:00:00 2001 From: Bastien Chanot Date: Fri, 26 Jun 2026 12:46:51 +0200 Subject: [PATCH] chore(lib): capitalize-commit include protocol Shared snippet referenced by every dev flow's capitalize step (design-gate.md pattern). Tail of capitalize: commit the already-approved memory via memory-commit.sh, surgically. Documents the stdout hash contract, the 2-hash non-confusion (memory commit vs code-commit anchored in entries), the orchestrator ordering (before FINISH), and what it must NOT do. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01W9sqAwZxBMZSynZoVrEJhd --- lib/capitalize-commit.md | 89 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 lib/capitalize-commit.md diff --git a/lib/capitalize-commit.md b/lib/capitalize-commit.md new file mode 100644 index 0000000..5c96210 --- /dev/null +++ b/lib/capitalize-commit.md @@ -0,0 +1,89 @@ +# 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 +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. + +## 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 `superpowers:finishing-a-development-branch` + (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. + +## DO + +1. Compose the message from the IDs just written + the flow, matching repo style + `chore(memory): — `. 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 "") + rc=$? + +3. Report by (rc, mem_hash): + - rc 0, mem_hash non-empty → `✅ mémoire committée ` + - 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. + + `` 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 `). 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` 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.