state-reconciliation

State Reconciliation Skill

A pre-dispatch invariant. Before the verification ladder runs (or any auto-loop unit dispatches), reconcile the three state sources — DB / disk / in-memory — and surface any divergence as a blocker, not a silent re-dispatch.

When to Use

• Before Phase 1 of verification-loop if the project tracks runtime state outside source control (sqlite, KV, redis, completed-units.json, milestone JSON, lockfiles).
• Before any auto-loop iteration in long-running sessions.
• After a crash, pause/resume, or context compaction — the in-memory loop state is gone but DB and disk persist.
• When a flag like is_sketch, in_progress, or a stale lock keeps re-firing the same unit.

Why This Skill Exists

GSD-2's CONTEXT.md names "State Reconciliation" as one of four runtime invariant modules. Common failure modes it catches:

• Stale flags re-dispatch completed units — is_sketch, stale worker rows, stale sequence/dependency rows that no one cleared.
• Disk artifacts present, DB status lags — PROJECT.md milestone registration, completion timestamps, roadmap divergence.
• Recovery helpers exist but aren't wired into dispatch — divergence accrues silently between iterations.

A verification ladder that runs against unreconciled state reports green on the wrong inputs.

The Reconciliation Contract

For every state class the project tracks, define and run before dispatch:

1. Authority — which surface is the source of truth (DB, disk artifact, in-memory loop state).
2. Projection — direction of state flow (DB → disk, disk → DB, or both with a named winner).
3. Reconciliation — the deterministic check that proves authority and projection match.
4. Failure mode — what happens on divergence (block dispatch, repair, ask operator).

Output a single fenced block before any dispatch, so the operator sees the resolved state before it costs a misread:

state-reconciliation (resolved):
  participants table:        DB authoritative; disk projection at data/participants.json — match (1247 rows)
  completed_units.json:      project root authoritative after crash; worktree projection — match
  is_sketch flag:            DB authoritative — clear (no re-dispatch risk)
  open lock at /tmp/foo.lck: stale (PID 1234 not running) — STALE, blocks dispatch
  milestone registration:    PROJECT.md authoritative; DB row — DIVERGED (DB shows in_progress, disk shows complete)