Files
claude/lib/capitalize-commit.md
T

6.2 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. -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 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. Two causes, named on stderr: a line removed inside an existing v2 entry (only appends pass), or a NEW culprit (duplicate ID, heading shape); an open code fence counts even when it predates the commit. 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.