# Checkpoints And Auto-Run Policy

Use this reference before whole-flow, durable, auto-guided, tmux-worker, or
`/goal` runs and before crossing review, GSD, execution, cleanup, or
verification boundaries.

## Whole-Run Goal Preflight

Before starting a whole-flow or durable auto-run that may cross review, GSD
handoff, execution, cleanup, and verification, chat with the human until the run
contract is explicit. Do this before `autoplan`, `to-issues`, GSD ingest/plan,
`skill-runner`, autonomous execution, or auto-confirming downstream gates.

If a canonical plan already exists, inspect it first and summarize the inferred
contract instead of asking the user to restate everything.

Required run contract:

- Goal: concrete outcome
- Success criteria: observable done signals and required verification when known
- Stop condition: reviewed plan, GSD plan, implemented and verified code,
  PR-ready branch, or another boundary
- Boundaries/non-goals: only when needed to prevent scope, cost, safety, or
  compatibility drift

Prompt shape:

```text
Before I start the whole run, I want to lock the run contract.

Goal: <inferred or missing>
Success criteria: <inferred or missing>
Stop condition: <inferred or missing>
Boundaries/non-goals: <inferred or "none stated">

Is this the goal and success criteria you want me to execute against? If not,
what should change?
```

Start only after the user confirms/corrects the contract, or when their latest
message explicitly supplied the full contract and told you to use it as-is.

## Control Plane And Worker Sessions

For durable runs that may cross multiple stages, keep the main session as the
control plane and use `skill-runner`/tmux workers as the execution plane by
default.

Main session responsibilities:

- lock or infer the run contract
- choose the route and next sub-phase
- keep source-of-truth decisions coherent
- inspect worker artifacts, logs, diffs, commits, and verification evidence
- decide whether to continue, repair, stop, or ask the user

Worker session responsibilities:

- execute one bounded sub-phase
- use a local `/goal` only for that sub-phase when the host supports it
- use `/compact` only inside the worker when needed to preserve progress
- leave durable state before exit: artifact update, verification output, commit,
  or handoff summary
- clear the worker-local goal and exit or stop after the handoff

Do not use `/goal clear` or `/clear` in the main session during an active
durable flow. Those commands can remove the route memory and active goal the
main session needs for supervision. If the main session needs context relief,
use a handoff-style `/compact` and immediately re-check the canonical artifact.

Prefer closing a completed worker over clearing it and continuing. A fresh
worker per sub-phase gives cleaner boundaries and makes stale goals less likely.

For goal-driven workers, set a steering cadence, not a short hard timeout.
Choose the cadence per sub-phase from expected proof duration, risk, and
artifact rhythm:

| Task shape | Suggested review cadence |
| --- | --- |
| Tiny or low-risk edit | no worker, or 10-20 minutes if delegated |
| Normal implementation slice | 30-60 minutes |
| Broad refactor with active tests | 60-120 minutes |
| Known slow verification or migration | align with expected proof checkpoints |

Let a healthy long-running worker continue when it is producing durable progress
or running an expected long proof. If the worker is active after a review
interval without durable progress, or if it is pursuing the wrong artifact, the
main session should inspect the captured pane/logs/diff/canonical artifact and
either steer the worker with a follow-up, stop it as blocked, or relaunch a
fresh worker with a narrower corrected goal.

When stopping a bad goal, do not blindly resume. First answer:

- Was the original worker goal too broad, ambiguous, or wrong?
- Is the canonical artifact still the right source of truth?
- Is there a smaller sub-phase that can produce durable evidence?
- Should the next worker use the same skill path, a diagnostic path, or stop for
  user input?

## Decision Triage

During a confirmed durable run, classify each question or downstream gate:

| Class | Action |
| --- | --- |
| Soft continuation | Auto-answer the recommended/default option, log briefly, continue |
| Hard stop | Stop and ask once with concrete impact |
| Unclear impact | Investigate repo/docs context; if still materially risky, hard stop; otherwise choose the smallest reversible default |

Soft continuation examples:

- preserves the user's accepted plan
- restates premises already present in the canonical artifact
- chooses an existing repo convention
- runs normal review, test, verification, or doc sync
- updates the plan with accepted review findings
- chooses a reversible low-blast-radius default
- selects the only GSD handoff route supported by evidence

Hard-stop examples:

- target user, demand premise, narrowest wedge, product direction
- scope boundary, public contract, data model, phase split, roadmap ownership
- security/privacy posture, paid infrastructure, external service, API key use
- destructive action, real-device/local-dev requirement, or unavailable proof
- locked-doc/ADR conflict, multiple plausible phases, or user intent override

For `autoplan` premise gates, auto-confirm only when premises restate the plan
or add low-risk assumptions needed for review. Stop when a premise is new,
contradicted by repo evidence, disputed by review voices, or changes product,
scope, contract, security, privacy, cost, data, services, or ownership.

If a downstream skill asks a `Confirm`/`Revise` style question and the gate is a
soft continuation, answer `Confirm` with a one-line rationale instead of waiting
for the user.

For worker-local `/goal` prompts, phrase the goal as one sub-phase, not the full
project. Include the artifact to update, required proof, and stop condition.

```text
/goal <sub-phase outcome>; update <artifact>; run <proof>; stop with handoff
```

If a worker reports `RECOMMENDED_GOAL_REVISION`, or if the babysitter stops it
for drift/timeout, treat that as evidence for the next route decision. The main
session may revise the worker goal and relaunch only after checking actual
artifacts and diff state.

## GSD Handoff Gates

Auto-continue when exactly one routing row applies:

- existing roadmap phase clearly matches -> `gsd-plan-phase <phase> --prd`
- `.planning/` missing -> manifest + `gsd-ingest-docs --mode new`, inspect
  phase, then `gsd-plan-phase --prd`
- `.planning/` exists and no phase matches -> manifest +
  `gsd-ingest-docs --mode merge`, inspect created/changed phase, then
  `gsd-plan-phase --prd`

Stop for multiple plausible existing phases, more than one new phase, locked
doc conflicts, or changes to roadmap ownership beyond the accepted plan.

## Required Checkpoints

Apply decision triage before crossing these boundaries:

1. Whole-run goal preflight: always human-owned unless the latest message
   supplied the full run contract and told you to use it as-is.
2. Idea-shaping route: ask direct vs auto-guided for fuzzy ideas unless already
   clear.
3. Auto-guided user-owned decision: ask before target user, demand premise,
   wedge, scope, public contract, services, cost, phase split, or overrides.
4. Pre-plan -> Review: confirm the plan file is ready for review unless the run
   contract already says to continue.
5. Review -> In-place update: update plan only after approval or soft-continuation
   classification.
6. Review -> Issues/GSD: continue only when execution is covered by the request
   or active run contract.
7. GSD handoff choice: auto-select only with one clear route.
8. Issues -> GSD: ask if GitHub issue tracking vs direct GSD is material.
9. GSD plan -> Execute: continue only when execution is covered by request or
   run contract.
10. Many phases: ask before creating more than three phases.
11. Main -> Worker: for durable multi-stage execution, launch a bounded
   `skill-runner`/tmux worker instead of running host-local goal/clear mechanics
   in the main session. For goal-driven workers, choose and record a
   task-adjusted review cadence plus a long enough timeout for the expected
   proof. Direct main-session execution is acceptable only for tiny direct
   edits, read-only probes, or local repairs that do not threaten route
   continuity.
12. Worker -> Main: before trusting completion, inspect the worker handoff,
   changed files, logs, commits, and verification evidence. Continue only after
   durable state exists outside the worker context.
13. Worker drift -> Revised worker: if the worker loops, broadens scope, lacks
   durable progress at a review point, or pursues the wrong artifact, inspect
   captured logs and state. Steer the current worker only when a concise
   correction is enough; otherwise stop it and relaunch with a narrower
   corrected goal or stop for a hard decision. Do not keep the same bad goal
   running.
14. Code slice -> Next slice/cleanup: when local code changed and commits are
   enabled, create a semantic slice commit after focused proof before starting
   the next slice or cleanup pass.
15. Simplify -> Verify: skip only for docs-only/trivial changes or explicit user
   instruction.
16. Refactor scope -> Execute: require accepted P0/P1 checklist and stop
   condition.
17. Refactor doc cleanup: auto-run focused doc status; ask before broad
   moves/deletions or protected docs outside scope.
18. Local-dev gate: stop when proof needs real simulator, Gateway, VLM, Docker,
   GPU, API keys, or similar unavailable resources.
