checkpoint

The scope-dialed fit-and-intent organ. One lens — does this serve the original point, cohere with the whole, and what did I learn? — delivered at three zoom levels (one verb, no altitude gaps, batch findings). Delegates orientation, baseline-diff, rendering, routing, and persistence to retrospect-core.

Where it sits. Today's diff reviewers (review on local code or a PR, code-review correctness) judge a change in isolation; the corpus passes audit the whole by governance category. checkpoint is the middle and the lens: it asks fit-and-intent at whatever zoom you're at. Its corpus scope carries the passes absorbed from the retired retrospect + system-review organs — see corpus-passes.md. memory-audit (mechanical integrity) and recap (per-session episodic) stay separate lenses.

When to run

• /checkpoint — auto-detect the scope (below) and audit at that zoom.
• /checkpoint --scope diff|module|corpus — force the zoom.
• Natural language: "does this change fit the bigger picture", "did I drift from what I wanted", "do these modules I just built actually fit together", "step back on what we shipped".
• Do not auto-fire. Mode A, user-invoked. No hook, no session-end trigger.

1. Resolve scope

Auto-detect from what checkpoint is pointed at; surface the resolved scope in the report header so it's transparent and correctable. --scope always overrides.

"Just-built" for module scope = the modules touched since the last commit (or this session's Edit/Write targets), grouped by top-level subtree. State which modules it resolved so the user can correct.

2. The lens at each scope

Every scope produces Finding objects per the retrospect-core shape (pass, locator, verdict, severity, what, route, proposed_action).

diff scope — fit on a change (compose, don't duplicate)

1. Correctness (compose). Invoke code-review on the change for bugs + cleanup. If code-review is unavailable, note it and proceed with the fit-pass only.
2. Fit-pass (the added lens). Read the slug's intent (vision/spec if present) + the surrounding architecture (codemap, the touched module's boundaries). Ask: does this change serve where we're going, and cohere with the whole — not just "is it locally correct". Findings: scope creep, a change that contradicts the stated intent, a boundary it quietly crosses, a simpler shape that fits better.
   • Size the fit question to the autonomy contract's stopping posture (autonomize — read the effective contract): under criteria-met (default), ask the full fit question above plus gold-plating (any finished item tracing to no stated criterion?). Under user-anytime, do not flag "more could be done" as drift — the posture is freeze-a-coherent-best-so-far and record what remains; the fit question becomes is what's here coherent and honestly scoped, not is it complete. Under diminishing-returns / budget, treat "stopped before perfect" as intended, not a finding. The contract selects which fit question to ask; checkpoint does not redefine fit.
3. Render one report, two sections (correctness from code-review + fit from the fit-pass). One action, both lenses.

Failure modes. No intent docs found (no vision, no spec) → the fit-pass runs against the surrounding architecture only, and the report header states that it did. Module resolution comes back empty (a clean tree, nothing touched this session) → do not guess a scope; ask the user which module to check.

module scope — the post-build checkpoint (the core need)

Over the just-built module(s), four passes:

• Drift — does the built work still serve the original point (vision/spec intent)? Flag where the implementation wandered from what was asked.
• Integration-fit — the sharpest blade: do the just-built modules actually cohere with each other — consistent boundaries, assumptions, and seams — or did they drift apart while built heads-down? Nothing else in the system checks this.
• Continue-or-kill — now that it's real, is the direction still worth it, or did building reveal it's not?
• Lessons — what did building this teach (capture-worthy)? Routes to /capture.

When a module-scope checkpoint confirms a built unit is good and worth keeping (drift clean, coheres, continue), offer a changelog ship line: "<unit> checks out — log it to CHANGELOG? (y/N)". On y, invoke skills/update-changelog/SKILL.md with the unit — it composes a ship line behind its own accept/edit/reject gate. checkpoint is a doorway, not the changelog writer. Skip when the checkpoint kills/defers the work (nothing shipped to log).

corpus scope — the history + system audit

Runs the eight corpus passes defined in corpus-passes.md — decision & delivery (decision integrity, intent-vs-shipped, uncaptured lessons, consolidation) and organ surface (responsibility overlap, dead config, pipeline gaps, coherence vs vision) — through retrospect-core. A slug argument narrows to the conformance sub-mode (spec→ship MET/PARTIAL/MISSING/EXTRA) defined there.

3. Findings flow — batch, then apply selected

1. retrospect-core.orient + the scope's passes → findings.
2. retrospect-core.diff(findings, baseline) → NEW/CARRIED/RESOLVED tagging (baseline at .claude/checkpoints/<scope-slug>/latest.md).
3. retrospect-core.render(report) → the review-output-contract batch report: header (with the resolved scope), the findings, a Severity × Pass matrix, the mandatory diagram, the structurally-required "looks bad but actually fine" section.
4. Select, don't loop. Present the whole batch, then ask the user to pick which findings to apply/route in one pass (e.g. "apply 1,3,4 / all / none / wontfix <id> <reason> / show <id>") — a wontfix selection carries per the engine's WONT_FIX semantics (durable reason, carried forward tagged, suppressed from Quick wins) — not a per-finding confirm sequence. This is the efficiency "conversations" axis: one round-trip, not N.
5. retrospect-core.route on the selected set only — each routes by its route (capture / memory-audit / proposal / direct-fix). Unselected findings stay in the persisted report for next time.
6. retrospect-core.persist(report, scope-slug) — the next run's baseline.

7. Record findings to scratch. Write one entry per finding via the write_memory MCP tool (tier: scratch, current session_id) — the same tier /execute §3d.1 writes to, never a parallel path. Applies at every scope (diff / module / corpus): a fit-and-intent observation accrues exactly like a verification outcome, so a resumed session knows what this checkpoint already found instead of re-deriving it.

   • salience: normal for every finding — a checkpoint finding is never routine, so none of them are the low-salience case.
   • provenance: user-said for a finding the user confirmed or raised in the select step; model-inferred for one the passes produced on their own. A user's ruling on a finding is their judgment, not the model's inference.
   • Write all findings, not just the selected ones. An unselected finding is precisely the context a resumed session would otherwise re-derive and re-present — and the persisted report already keeps it for next time.
   • Where a finding overturns an earlier in-session observation, set supersedes to that entry's ts so the corrected reading replaces the stale one.

   Best-effort, same as §3d.1 in execute: a failed scratch write never blocks the findings flow, but repeated failures are surfaced once rather than swallowed. Scratch is disposable and TTL'd — nothing here reaches durable memory except through the capture route in step 5.

What checkpoint does NOT do

• Does not auto-fire. Mode A, user-invoked.
• Does not fix in place. It routes — lessons → /capture, integrity fixes → /memory-audit, system/decision changes → a proposals/ stub, self-evident edits → direct-fix. Never silently rewrites.
• Does not duplicate code-review. At diff scope it invokes it for correctness and adds the fit lens; the lenses stay distinct.
• Does not absorb memory-audit or recap. Mechanical integrity and per-session episodic are different lenses; both stay separate (recap feeds the corpus scope).
• Does not re-implement the engine. orient / diff / render / route / persist are retrospect-core's.

Relationship to other organs

• retrospect-core — the shared engine (orient/diff/render/route/persist + the batch-select render/route mode this organ uses).
• corpus-passes.md — the corpus-scope pass definitions (absorbed from the retired retrospect / system-review organs).
• code-review — composed at diff scope for the correctness lens.
• capture / memory-audit / proposals — the routing targets.
• recap — the per-session feeder to the corpus scope (unchanged).
• review — the other diff reviewer (local code or a PR, from one or more angles); checkpoint adds the fit-and-intent lens, it does not replace them.