cc-checkpoint

Read the conversation history from the current session.

Identify and extract:

1. Decisions made — architectural choices, approach selections, rejected alternatives
2. Conventions established — naming patterns, file organization, code style choices
3. Technical debt — shortcuts taken, known limitations, deferred work
4. Workarounds — non-obvious solutions and why they were needed

Update .claude/memory/project.md (append only, never delete):

• Add a timestamped section: ## Checkpoint [YYYY-MM-DD HH:MM]
• List decisions, conventions, and debt from this session

Then update its ## Current State section, the bounded digest at the top of project.md that phase commands read with a limit instead of the whole file:

• If the section is absent, make the one-time bootstrap insert: add this skeleton directly after the file's # Project Memory intro paragraph, in one Edit. It inserts a new section and never rewrites an existing line, so it keeps the BUG-003 invariant.

## Current State
<!-- Bounded digest, max 40 lines, each line max 200 characters. History below is append-only. -->
- Active spec: none
- Last checkpoint: none
### Conventions
### Debt
<!-- end current state -->

• Replace the single - Last checkpoint: line with the heading text of the entry just appended, without its leading ## .
• Add each new convention as a bullet under ### Conventions and each new debt item or workaround as a bullet under ### Debt, one Edit per bullet.
• Caps: the section stays within 40 lines, each list within 12 bullets, each line within 200 characters. Before adding to a full list, remove the one bullet that is superseded or resolved, in its own Edit. A removed or shortened bullet loses nothing: the history entry holds the full text.
• If the <!-- end current state --> line is missing, report the malformed section and leave it as it is. Never rewrite it in bulk.

Staging that update, where the workflow commits it: stage by tracked-ness, with an explicit path. A project.md that is already tracked takes git add -u ".claude/memory/project.md"; one that is not yet tracked takes plain git add ".claude/memory/project.md", or git add -f where the project ignores .claude/. Never an unconditional -u here. This command is global and also runs in freshly scaffolded projects, which do not ignore .claude/ and whose project.md is not yet tracked: there -u exits 128 and would halt the checkpoint before its DB tail, trading a defect those projects never had for one they would.

Update .claude/memory/personal.md (local only):

• Add any developer preferences observed this session

Report:

• Timestamp of this checkpoint
• What was saved to project.md (2–3 bullets)
• What was saved to personal.md (1–2 bullets)

Suggest running /cc-checkpoint automatically: before /compact, after completing a feature, after any key architectural decision.

---

Fail-open DB tail (best-effort, synchronous)

Run only after the project.md append succeeded (authoritative). Any failure here is non-fatal — never block or revert the project.md update.

1. Ensure .conductor/ exists (mkdir -p .conductor, best-effort); if that fails, skip the tail.
2. Derive c — the full-40 git rev-parse HEAD (lowercased, /^[0-9a-f]{7,40}$/, "0000000" fallback on non-zero/timeout/git-absent/format-mismatch; shell timeout only if the binary exists).
3. Resolve the id: id="$(node .claude/scripts/session-id.mjs 2>>.conductor/last-write.log)".
4. Derive ph by carry-forward: with a bounded ~5 s outer timeout (only if timeout exists; conductor-db's internal 2 s busy_timeout bounds real contention otherwise), run node <probe-flags> .claude/scripts/conductor-db.mjs get-session "$id"; if it prints a row whose phase is a non-empty enum member, reuse it. On no row, empty phase, DB unavailable, or timeout, default to "impl".
5. Set pr to the verbatim ## Checkpoint … section body just appended to project.md (the same in-context string) — so project.md and the snapshot's pr are byte-identical. pr is always non-empty here, so the blob is always v2.
6. Project d / x from that section (best-effort): match headings /^#{2,4}[ \t]+(.+?)[ \t]*$/; normalize the heading text by removing all *, _, ` then .trim() + lowercase; a heading containing decision or convention opens a d block, one containing debt, workaround, or limitation opens an x block. The d set is tested first and wins (a heading matching both opens one d block). The parent ## Checkpoint … heading matches no keyword, so it opens no block and closes any open one. Within a block, bullet lines /^[ \t]*[-*][ \t]+(\S.*?)[ \t]*$/ contribute their trimmed capture (line-based; continuation lines ignored — the full text survives in pr). If unstructured, d/x may be empty (valid).
7. Defaults: n=[], f=[], s= the active spec stem or "none".
8. Build the v2 blob: pipe {ph, c, s, n, f, d, x, pr} on stdin to node .claude/scripts/snap-build.mjs; capture its stdout. If it exits non-zero, skip the DB write (fail-open).
9. Write the rows (both argv double-quoted; blob on stdin; all output to the log):