feat: continuous checkpoint mode with non-destructive WIP squash

Adds opt-in auto-commit during long sessions so work survives Claude
Code crashes, Conductor workspace handoffs, and context switches.
Local-only by default — pushing requires explicit opt-in.

Codex review caught multiple landmines that would have shipped:
1. checkpoint_push=true default would push WIP commits to shared
   branches, trigger CI/deploys, expose secrets. Now default false.
2. Plan's original /ship squash (git reset --soft to merge base) was
   destructive — uncommitted ALL branch commits, not just WIP, and
   caused non-fast-forward pushes. Redesigned: rebase --autosquash
   scoped to WIP commits only, with explicit fallback for WIP-only
   branches and STOP-and-ask for conflicts.
3. gstack-config get returned empty for missing keys with exit 0,
   ignoring the annotated defaults in the header comments. Fixed:
   get now falls back to a lookup_default() table that is the
   canonical source for defaults.
4. Telemetry default mismatched: header said 'anonymous' but runtime
   treated empty as 'off'. Aligned: default is 'off' everywhere.
5. /checkpoint resume only read markdown checkpoint files, not the
   WIP commit [gstack-context] bodies the plan referenced. Wired up
   parsing of [gstack-context] blocks from WIP commits as a second
   recovery trail alongside the markdown checkpoints.

Changes:
- bin/gstack-config: add checkpoint_mode (default explicit) and
  checkpoint_push (default false) to CONFIG_HEADER. Add lookup_default()
  as canonical default source. get() falls back to defaults when key
  absent. list now shows value + source (set/default). New 'defaults'
  subcommand to inspect the table.
- scripts/resolvers/preamble.ts: preamble bash reads _CHECKPOINT_MODE
  and _CHECKPOINT_PUSH, prints CHECKPOINT_MODE: and CHECKPOINT_PUSH: so
  the mode is visible. New generateContinuousCheckpoint() section in
  T2+ tier describes WIP commit format with [gstack-context] body and
  the rules (never git add -A, never commit broken tests, push only
  if opted in). Example deliberately shows a clean-state context so
  it doesn't contradict the rules.
- ship/SKILL.md.tmpl: new Step 5.75 WIP Commit Squash. Detects WIP
  count, exports [gstack-context] blocks before squash (as backup),
  uses rebase --autosquash for mixed branches and soft-reset only when
  VERIFIED WIP-only. Explicit anti-footgun rules against blind soft-
  reset. Aborts with BLOCKED status on conflict instead of destroying
  non-WIP commits.
- checkpoint/SKILL.md.tmpl: new Step 1.5 to parse [gstack-context]
  blocks from WIP commits via git log --grep="^WIP:". Merges with
  markdown checkpoint for fuller session recovery.
- Golden ship fixtures regenerated (ship is T4, preamble change shows up).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Garry Tan
2026-04-17 06:05:25 +08:00
parent 6c8cf6774f
commit fe34349966
39 changed files with 2065 additions and 8 deletions
+52 -1
View File
@@ -99,6 +99,11 @@ if [ -d ".claude/skills/gstack" ] && [ ! -L ".claude/skills/gstack" ]; then
fi
echo "VENDORED_GSTACK: $_VENDORED"
echo "MODEL_OVERLAY: ${ctx.model ?? 'none'}"
# Checkpoint mode (explicit = no auto-commit, continuous = WIP commits as you go)
_CHECKPOINT_MODE=$(${ctx.paths.binDir}/gstack-config get checkpoint_mode 2>/dev/null || echo "explicit")
_CHECKPOINT_PUSH=$(${ctx.paths.binDir}/gstack-config get checkpoint_push 2>/dev/null || echo "false")
echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE"
echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH"
# Detect spawned session (OpenClaw or other orchestrator)
[ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true
\`\`\``;
@@ -706,6 +711,52 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
available]. [Health score if available]." Keep it to 2-3 sentences.`;
}
function generateContinuousCheckpoint(): string {
return `## Continuous Checkpoint Mode
If \`CHECKPOINT_MODE\` is \`"continuous"\` (from preamble output): auto-commit work as
you go with \`WIP:\` prefix so session state survives crashes and context switches.
**When to commit (continuous mode only):**
- After creating a new file (not scratch/temp files)
- After finishing a function/component/module
- After fixing a bug that's verified by a passing test
- Before any long-running operation (install, full build, full test suite)
**Commit format** — include structured context in the body:
\`\`\`
WIP: <concise description of what changed>
[gstack-context]
Decisions: <key choices made this step>
Remaining: <what's left in the logical unit>
Tried: <failed approaches worth recording> (omit if none)
Skill: </skill-name-if-running>
[/gstack-context]
\`\`\`
**Rules:**
- Stage only files you intentionally changed. NEVER \`git add -A\` in continuous mode.
- Do NOT commit with known-broken tests. Fix first, then commit. The [gstack-context]
example values MUST reflect a clean state.
- Do NOT commit mid-edit. Finish the logical unit.
- Push ONLY if \`CHECKPOINT_PUSH\` is \`"true"\` (default is false). Pushing WIP commits
to a shared remote can trigger CI, deploys, and expose secrets — that is why push
is opt-in, not default.
- Background discipline — do NOT announce each commit to the user. They can see
\`git log\` whenever they want.
**When \`/checkpoint resume\` runs,** it parses \`[gstack-context]\` blocks from WIP
commits on the current branch to reconstruct session state. When \`/ship\` runs, it
filter-squashes WIP commits only (preserving non-WIP commits) via
\`git rebase --autosquash\` so the PR contains clean bisectable commits.
If \`CHECKPOINT_MODE\` is \`"explicit"\` (the default): no auto-commit behavior. Commit
only when the user explicitly asks, or when a skill workflow (like /ship) runs a
commit step. Ignore this section entirely.`;
}
function generateContextHealth(): string {
return `## Context Health (soft directive)
@@ -751,7 +802,7 @@ export function generatePreamble(ctx: TemplateContext): string {
generateSpawnedSessionCheck(),
generateModelOverlay(ctx),
generateVoiceDirective(tier),
...(tier >= 2 ? [generateContextRecovery(ctx), generateAskUserFormat(ctx), generateCompletenessSection(), generateContextHealth()] : []),
...(tier >= 2 ? [generateContextRecovery(ctx), generateAskUserFormat(ctx), generateCompletenessSection(), generateContinuousCheckpoint(), generateContextHealth()] : []),
...(tier >= 3 ? [generateRepoModeSection(), generateSearchBeforeBuildingSection(ctx)] : []),
generateCompletionStatus(ctx),
];