stick-shift: handoff-grade .sdlc — commit/cycle stamps + increment lifecycle

[JoshuaOliphant]

Why

A three-experiment study on a real stick-shift session asked: can a fresh agent, handed only the persisted .sdlc/ record (+ specs + code), pick the work up cold and continue correctly? Each experiment varied one affordance and surfaced a distinct gap:

Experiment	Isolated	Finding
1 — .sdlc/ only	record self-sufficiency	entries had no pointer to the code they describe; AC text lives in specs/
2 — full disk access	can it continue?	yes — the record is an excellent handoff (cold agent shipped the next increment)
3 — run /spec to resume	resume/lifecycle path	no clean "DONE → next increment" — only an off-graph DONE→SPEC nudge that left feature/request stale and the records undelimited

This PR fixes the two real gaps (1 and 3). A third observation — stick-shift's commit-per-phase getting swept by other automation — was an artifact of rehearsing inside an active vault repo, not a plugin gap, so it's intentionally not addressed.

A. Record ↔ git foreign key

transition, decide, and init now stamp the short commit SHA and the increment cycle onto each history/decision entry; init captures branch. status and journal surface them.

The SHA is a join key from the reasoning record into git: git log <entry-sha>..<next-sha> recovers a phase's work. (Captured at write time; since a phase is committed after its transition, consecutive entries bracket the phase — documented in git_head's docstring.)

B. increment — the missing lifecycle verb

DONE was a terminal sink and init is resume-only (it silently dropped a new --feature on an existing session), so increment 2 was only reachable by improvising an off-graph transition. New command:

session_state.py increment --feature <new> --request "<task>"

archives the finished increment into increments[], retargets feature/request (so status never lies), bumps cycle so records stay grouped, and resets to INIT — so the next /spec transitions on-graph, no nudge. The /spec command doc and README now point at this path instead of the off-graph hack.

Tests

• 17 pass (6 new, written TDD red→green), ruff clean.
• Smoke-tested end-to-end in a real git repo: SHAs captured, branch tracked, DONE → increment → INIT → SPEC clean with no nudge, prior increment archived.

v0.4.0 → v0.5.0 (plugin.json + marketplace.json).

🤖 Generated with Claude Code