"CHECKPOINT: Verification Required" Recommendation

[Mondreykr]

What happens

When an executor hits a checkpoint:human-verify and the user describes an issue instead of typing "approved," the orchestrator spawns a continuation executor that tries to fix the bug inline. This continuation agent is working in bloated context with no planning step, no debug agents, and no structured diagnosis — it just improvises a fix using the deviation rules, which were designed for issues discovered during execution, not for user-reported problems at verification checkpoints.

Why it feels wrong

This is the one place in GSD where the "orchestrator coordinates, executor executes" principle breaks down. Everywhere else — plan-phase, verify-work, debug — there's a clear cycle: identify problem → plan → spawn agent with fresh context → verify. But at a checkpoint, the user's bug report gets handed directly to an executor that tries to patch things on the spot.

The gap

The [execute-phase.md](http://execute-phase.md/) orchestrator references a [continuation-prompt.md](http://continuation-prompt.md/) template (line 208) that doesn't exist. The executor's continuation_handling only says "after human-verify → continue" with no branch for "user reported an issue." There's no defined protocol for this path.

Possible direction

When a user reports an issue at a checkpoint, the orchestrator could close the plan (task 1 done, checkpoint not passed), log the issue, and route to the existing diagnosis/gap-closure cycle rather than asking an executor to be an improvised debugger. The machinery for structured fixes already exists in verify-work — this would just connect the checkpoint flow to it.

[baeyensT]

Took your idea and ran it through Claude CLI, which resulted in the following upgrade. did include other ideas as well.

GSD Workflow Enhancements: 8 Upgrades Plan
Context
After implementing 5 hardening upgrades (input validation, error recovery, context budget, tests, dedup), analysis revealed 7 structural workflow gaps plus 1 critical checkpoint handling issue. These 8
enhancements address: missing dependency validation, no plan integrity verification, surprising auto-advance config mutation, overlapping discovery/research, unprotected state mutations, no context
refresh opportunity, fragmented verification chain, and broken checkpoint continuation routing.

 Dependency Graph

 E1 (Dependency Pre-flight) ──┐
                               ├──► E7 (Unified Verification Chain)
 E2 (Plan Hash Seal) ─────────┘
 E3 (Unify --auto)             [independent]
 E4 (Consolidate Discovery)    [independent]
 E5 (State Versioning)         [independent]
 E6 (Context Refresh Gate)     [independent]
 E8 (Checkpoint Continuation)  [independent]

 Execution Order

 ┌──────┬────────────────────────────────┬────────────────────────────┬───────────┐
 │ Wave │          Enhancement           │            Type            │ New Tests │
 ├──────┼────────────────────────────────┼────────────────────────────┼───────────┤
 │ 1    │ E3: Unify --auto               │ Workflow-only              │ 0         │
 ├──────┼────────────────────────────────┼────────────────────────────┼───────────┤
 │ 1    │ E6: Context Refresh Gate       │ Workflow-only              │ 0         │
 ├──────┼────────────────────────────────┼────────────────────────────┼───────────┤
 │ 2    │ E1: Dependency Pre-flight      │ Code + Workflow            │ +4        │
 ├──────┼────────────────────────────────┼────────────────────────────┼───────────┤
 │ 2    │ E5: State Versioning           │ Code                       │ +4        │
 ├──────┼────────────────────────────────┼────────────────────────────┼───────────┤
 │ 3    │ E2: Plan Hash Seal             │ Code + Workflow            │ +3        │
 ├──────┼────────────────────────────────┼────────────────────────────┼───────────┤
 │ 3    │ E4: Consolidate Discovery      │ Workflow-only              │ 0         │
 ├──────┼────────────────────────────────┼────────────────────────────┼───────────┤
 │ 4    │ E8: Checkpoint Continuation    │ Code + Workflow + New File │ +2        │
 ├──────┼────────────────────────────────┼────────────────────────────┼───────────┤
 │ 5    │ E7: Unified Verification Chain │ Code + Workflow            │ +2        │
 └──────┴────────────────────────────────┴────────────────────────────┴───────────┘

 Test target: 107 existing + 15 new = 122 tests

 ---
 E3: Unify --auto Handling

 Files: workflows/discuss-phase.md, workflows/transition.md, workflows/execute-phase.md, workflows/plan-phase.md

 Problem: discuss-phase SETS workflow.auto_advance config (lines 434-441), transition CLEARS it (lines 454-457). The --auto flag is supposed to be invocation-scoped but persists via config mutation.

 ┌────────┬──────────────────────────────────────────────────────────────────────────────────────┬────────────────────────────────────────────┐
 │ Change │                                         What                                         │                   Where                    │
 ├────────┼──────────────────────────────────────────────────────────────────────────────────────┼────────────────────────────────────────────┤
 │ 3A     │ Remove config mutation block — delete the config-set workflow.auto_advance true call │ discuss-phase.md lines 434-441             │
 ├────────┼──────────────────────────────────────────────────────────────────────────────────────┼────────────────────────────────────────────┤
 │ 3B     │ Remove config clear block — delete the config-set workflow.auto_advance false call   │ transition.md lines 454-457                │
 ├────────┼──────────────────────────────────────────────────────────────────────────────────────┼────────────────────────────────────────────┤
 │ 3C     │ Change auto-advance detection from config read to --auto flag check only             │ execute-phase.md lines 207-209 and 412-416 │
 ├────────┼──────────────────────────────────────────────────────────────────────────────────────┼────────────────────────────────────────────┤
 │ 3D     │ Same flag-only check for auto-advance                                                │ plan-phase.md lines 366-368                │
 └────────┴──────────────────────────────────────────────────────────────────────────────────────┴────────────────────────────────────────────┘

 Mechanism: Each workflow already passes --auto to the NEXT workflow when spawning. So the flag propagates through discuss→plan→execute→transition without config.

 ---
 E6: Context Refresh Gate

 File: workflows/plan-phase.md

 Problem: If user wants to refine CONTEXT.md after seeing research results, they must restart the entire plan-phase.

 ┌────────┬──────────────────────────────────────────────────────────────────────────────┬───────────────────────────────────────────────────────────┐
 │ Change │                                     What                                     │                           Where                           │
 ├────────┼──────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────┤
 │ 6A     │ Insert "Research Review Gate" step between research return and planner spawn │ plan-phase.md, new step 7.5 (between lines ~155 and ~170) │
 └────────┴──────────────────────────────────────────────────────────────────────────────┴───────────────────────────────────────────────────────────┘

 Logic:
 - Skip if --auto flag, --skip-research, or research was pre-existing (not fresh)
 - Display brief research summary (first 10 lines of ## Summary section)
 - Ask user: "Want to refine CONTEXT.md before planning?" (default: no)
 - If yes: display CONTEXT.md, let user describe changes, re-read from disk after edit
 - If no: proceed to planner

 ---
 E1: Dependency Pre-flight Check

 Files: bin/gsd-tools.cjs, workflows/execute-phase.md

 Problem: depends_on field exists in PLAN frontmatter but cmdPhasePlanIndex (line 1935) never extracts it. No orphan reference detection, no circular dependency detection, no wave ordering validation.

 ┌────────┬─────────────────────────────────────────────────────────────────────────────────────────────┬───────────────────────────────────────────────┐
 │ Change │                                            What                                             │                     Where                     │
 ├────────┼─────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────┤
 │ 1A     │ Extract depends_on from each plan's frontmatter in cmdPhasePlanIndex                        │ gsd-tools.cjs line ~1989 (after wave parsing) │
 ├────────┼─────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────┤
 │ 1B     │ Build dependency_graph map + validate: orphan refs, circular deps, wave ordering            │ gsd-tools.cjs after plan loop (~line 2030)    │
 ├────────┼─────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────┤
 │ 1C     │ Add dependency_graph, dep_errors, dep_warnings to return object                             │ gsd-tools.cjs line ~2032                      │
 ├────────┼─────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────┤
 │ 1D     │ Add dependency validation to pre_flight_validation step — block on errors, warn on warnings │ execute-phase.md lines 74-99                  │
 └────────┴─────────────────────────────────────────────────────────────────────────────────────────────┴───────────────────────────────────────────────┘

 Validation logic (1B):
 For each plan:
   - Check all depends_on refs exist in allPlanIds → orphan errors
   - Check depends_on refs are in earlier/same wave → wave ordering warnings
 DFS cycle detection across full graph → circular dep errors

 Tests (4):
 - depends_on extracted from frontmatter
 - orphan dependency detected (depends on nonexistent plan)
 - circular dependency detected (A→B→A)
 - wave ordering warning (wave 1 depends on wave 2)

 ---
 E5: State Versioning & Conflict Detection

 File: bin/gsd-tools.cjs

 Problem: 9 STATE.md mutation functions (lines 1223-1501) use read→regex→write with no locking. Parallel agents can corrupt STATE.md.

 Change: 5A
 What: Add readStateWithVersion(statePath) helper — extracts **State Version:** N field
 Where: New helper, insert near line 1275
 ────────────────────────────────────────
 Change: 5B
 What: Add writeStateAtomic(statePath, content, expectedVersion) — temp file + rename, version increment, optimistic lock
 Where: New helper, after 5A
 ────────────────────────────────────────
 Change: 5C
 What: Update all 10 mutation functions to use read/write helpers
 Where: cmdStatePatch(1242), cmdStateUpdate(1263), cmdStateAdvancePlan(1307,1314), cmdStateRecordMetric(1347), cmdStateUpdateProgress(1384), cmdStateAddDecision(1411), cmdStateAddBlocker(1434),
   cmdStateResolveBlocker(1466), cmdStateRecordSession(1501)
 ────────────────────────────────────────
 Change: 5D
 What: Add state_version to cmdStateSnapshot output
 Where: gsd-tools.cjs line ~2043

 Atomic write pattern:
 const tmpPath = statePath + '.tmp.' + process.pid;
 fs.writeFileSync(tmpPath, content, 'utf-8');
 fs.renameSync(tmpPath, statePath);  // atomic on same filesystem

 Optimistic lock: Re-read version before write. If version changed since read, return {error: 'version_conflict'} instead of corrupting.

 Tests (4):
 - state update increments version
 - state version starts at 0 if field missing
 - atomic write produces valid file
 - state-snapshot includes state_version

 ---
 E2: Plan Hash Seal

 Files: bin/gsd-tools.cjs, workflows/plan-phase.md, workflows/execute-phase.md

 Problem: Plans can change after plan-phase verification. Execute-phase has no way to detect drift.

 ┌────────┬─────────────────────────────────────────────────────────────────────────────────────────────────────┬───────────────────────────────────────────────────┐
 │ Change │                                                What                                                 │                       Where                       │
 ├────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────┤
 │ 2A     │ Add cmdPlanSeal(cwd, phase, raw) — SHA-256 hash of all PLAN.md files, writes {phase_dir}/.plan-seal │ New function after cmdPhasePlanIndex (~line 2041) │
 ├────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────┤
 │ 2B     │ Add cmdPlanSealVerify(cwd, phase, raw) — reads seal, recomputes, compares                           │ New function after 2A                             │
 ├────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────┤
 │ 2C     │ Add plan-seal and plan-seal-verify cases to CLI router                                              │ Switch block (~line 5350)                         │
 ├────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────┤
 │ 2D     │ After plan-phase verification passes (step 13), call plan-seal                                      │ plan-phase.md, insert step 13.5                   │
 ├────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────┤
 │ 2E     │ In execute-phase pre-flight, call plan-seal-verify. Warn on mismatch, proceed on no-seal            │ execute-phase.md lines 74-99                      │
 └────────┴─────────────────────────────────────────────────────────────────────────────────────────────────────┴───────────────────────────────────────────────────┘

 Seal file format (.plan-seal):
 {
   "seal": "sha256_hex",
   "hashes": {"01-01-PLAN.md": "sha256_hex", ...},
   "plan_count": 3,
   "created_at": "ISO8601"
 }

 Tests (3):
 - plan-seal creates seal file with correct hash
 - plan-seal-verify passes for unmodified plans
 - plan-seal-verify detects modification

 ---
 E4: Consolidate Discovery into Plan-Phase

 Files: workflows/plan-phase.md, workflows/discovery-phase.md

 Problem: discovery-phase says "Called from plan-phase's mandatory_discovery step" but plan-phase doesn't actually call it. Two overlapping research mechanisms with no routing.

 ┌────────┬───────────────────────────────────────────────────────────────────────────────┬───────────────────────────────┐
 │ Change │                                     What                                      │             Where             │
 ├────────┼───────────────────────────────────────────────────────────────────────────────┼───────────────────────────────┤
 │ 4A     │ Add depth auto-detection block before research step                           │ plan-phase.md, before line 76 │
 ├────────┼───────────────────────────────────────────────────────────────────────────────┼───────────────────────────────┤
 │ 4B     │ Route to discovery-phase at detected depth, or fall through to research agent │ plan-phase.md, within step 5  │
 ├────────┼───────────────────────────────────────────────────────────────────────────────┼───────────────────────────────┤
 │ 4C     │ Clarify invocation model in purpose section                                   │ discovery-phase.md lines 1-8  │
 └────────┴───────────────────────────────────────────────────────────────────────────────┴───────────────────────────────┘

 Depth detection logic (4A):
 - CONTEXT.md has "Claude's Discretion" with library/API choices → depth=standard
 - CONTEXT.md has architectural decisions needing validation → depth=deep
 - Simple phase, known stack (prior SUMMARYs cover it) → depth=verify (skip research agent)
 - No CONTEXT.md → existing research agent path (unchanged)

 Routing (4B):
 - verify: Quick Context7 check, skip full research
 - standard/deep: Spawn discovery-phase at detected depth, skip research agent
 - No detection: Fall through to existing researcher agent

 ---
 E8: Checkpoint Continuation Routing

 Files: templates/continuation-prompt.md (NEW), workflows/execute-phase.md, references/checkpoints.md, bin/gsd-tools.cjs

 Problem: When user reports a bug at human-verify checkpoint, continuation executor tries to fix inline with no planning, no debug agents, no structured diagnosis. continuation-prompt.md (referenced at
 execute-phase.md line 232) doesn't exist. {resume_instructions} is never defined.

 Change: 8A
 What: Create continuation-prompt.md template with variables, prompt structure, and resume instructions per classification (approved/issue_report-minor/issue_report-major/decision)
 Where: NEW: templates/continuation-prompt.md
 ────────────────────────────────────────
 Change: 8B
 What: Add response classification logic to checkpoint_handling step
 Where: execute-phase.md lines 231-237
 ────────────────────────────────────────
 Change: 8C
 What: Add cmdClassifyCheckpointResponse(response, raw) — classifies as approved/issue_report/decision with severity
 Where: gsd-tools.cjs, new function + router case
 ────────────────────────────────────────
 Change: 8D
 What: Add bug-report handling section
 Where: references/checkpoints.md, after line ~358

 Response classification (8B/8C):

 ┌────────────────────────────────────────────────────────────┬──────────────────────┐
 │                          Pattern                           │    Classification    │
 ├────────────────────────────────────────────────────────────┼──────────────────────┤
 │ "approved", "done", "yes", "lgtm", "looks good"            │ approved             │
 ├────────────────────────────────────────────────────────────┼──────────────────────┤
 │ Contains "issue", "bug", "wrong", "broken", "fix", "error" │ issue_report         │
 ├────────────────────────────────────────────────────────────┼──────────────────────┤
 │ "completely wrong", "start over", "wrong approach"         │ issue_report (major) │
 ├────────────────────────────────────────────────────────────┼──────────────────────┤
 │ Matches option from decision checkpoint                    │ decision             │
 └────────────────────────────────────────────────────────────┴──────────────────────┘

 Routing by classification:
 - approved → spawn continuation with proceed instructions
 - issue_report (minor) → spawn continuation with targeted fix instructions + Deviation Rule 1
 - issue_report (major) → do NOT spawn continuation; present to user with suggestion: /gsd:debug or re-plan
 - decision → spawn continuation with chosen option applied

 Tests (2):
 - classifies "approved" correctly
 - classifies issue description as issue_report

 ---
 E7: Unified Verification Chain

 Files: bin/gsd-tools.cjs, workflows/plan-phase.md, workflows/execute-phase.md

 Problem: 4 verification points (plan-checker, pre-flight, verifier agent, spot-checks) with no chain of trust. Plans can diverge from requirements. Verification outcomes don't flow downstream.

 ┌────────┬───────────────────────────────────────────────────────────────────────────────────┬─────────────────────────────────────────┐
 │ Change │                                       What                                        │                  Where                  │
 ├────────┼───────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────┤
 │ 7A     │ Add phase_req_ids extraction from ROADMAP.md to cmdInitExecutePhase return        │ gsd-tools.cjs line ~4292                │
 ├────────┼───────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────┤
 │ 7B     │ Add plan_seal_status to cmdInitExecutePhase return                                │ gsd-tools.cjs line ~4310                │
 ├────────┼───────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────┤
 │ 7C     │ Record verification outcome to STATE.md after checker passes                      │ plan-phase.md, after step 13            │
 ├────────┼───────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────┤
 │ 7D     │ Pass plan verification outcome + seal status + requirement IDs to verifier prompt │ execute-phase.md verify_phase_goal step │
 └────────┴───────────────────────────────────────────────────────────────────────────────────┴─────────────────────────────────────────┘

 Verification chain: plan-checker outcome → STATE.md → plan-seal → execute-phase init → verifier agent. Each link carries evidence from the previous.

 Tests (2):
 - init execute-phase returns phase_req_ids
 - init execute-phase returns plan_seal_status

 ---
 Step-by-Step Implementation Sequence

 Wave 1 (Workflow-only, zero code risk)

 1. discuss-phase.md: remove auto-advance config mutation (E3A)
 2. transition.md: remove auto-advance config clear (E3B)
 3. execute-phase.md: change auto-advance to flag-only check (E3C)
 4. plan-phase.md: change auto-advance to flag-only check (E3D)
 5. plan-phase.md: add research review gate step 7.5 (E6A)
 6. Verify: read workflow files, confirm no syntax breaks

 Wave 2 (Foundation code)

 7. gsd-tools.cjs: extract depends_on in cmdPhasePlanIndex (E1A)
 8. gsd-tools.cjs: add dependency validation + graph (E1B, E1C)
 9. execute-phase.md: add dependency check to pre-flight (E1D)
 10. gsd-tools.cjs: add readStateWithVersion + writeStateAtomic helpers (E5A, E5B)
 11. gsd-tools.cjs: update all 10 state mutation functions (E5C)
 12. gsd-tools.cjs: add state_version to cmdStateSnapshot (E5D)
 13. Run tests — 107 must pass
 14. gsd-tools.test.cjs: add E1 tests (4) + E5 tests (4)
 15. Run tests — 115 must pass

 Wave 3 (Seal + Discovery)

 16. gsd-tools.cjs: add cmdPlanSeal + cmdPlanSealVerify + router cases (E2A-C)
 17. plan-phase.md: add seal creation after verification (E2D)
 18. execute-phase.md: add seal verify to pre-flight (E2E)
 19. plan-phase.md: add depth auto-detection before research (E4A, E4B)
 20. discovery-phase.md: update purpose section (E4C)
 21. gsd-tools.test.cjs: add E2 tests (3)
 22. Run tests — 118 must pass

 Wave 4 (Checkpoint)

 23. Create templates/continuation-prompt.md (E8A)
 24. gsd-tools.cjs: add cmdClassifyCheckpointResponse + router case (E8C)
 25. execute-phase.md: rewrite checkpoint_handling with classification (E8B)
 26. checkpoints.md: add bug-report handling section (E8D)
 27. gsd-tools.test.cjs: add E8 tests (2)
 28. Run tests — 120 must pass

 Wave 5 (Verification chain)

 29. gsd-tools.cjs: add phase_req_ids + plan_seal_status to cmdInitExecutePhase (E7A, E7B)
 30. plan-phase.md: record verification outcome to STATE.md (E7C)
 31. execute-phase.md: pass verification chain to verifier prompt (E7D)
 32. gsd-tools.test.cjs: add E7 tests (2)
 33. Run tests — 122 must pass

 Final

 34. Full test suite: node --test bin/gsd-tools.test.cjs — 122 pass, 0 fail
 35. Manual tests: dependency validation, plan seal, checkpoint classification
 36. Workflow spot-checks: --auto propagation without config mutation

 Critical Files

 ┌──────────────────────────────────┬────────────────────┬───────────┐
 │               File               │    Enhancements    │   Type    │
 ├──────────────────────────────────┼────────────────────┼───────────┤
 │ bin/gsd-tools.cjs                │ E1, E2, E5, E7, E8 │ Code      │
 ├──────────────────────────────────┼────────────────────┼───────────┤
 │ bin/gsd-tools.test.cjs           │ E1, E2, E5, E7, E8 │ Tests     │
 ├──────────────────────────────────┼────────────────────┼───────────┤
 │ workflows/execute-phase.md       │ E1, E2, E3, E7, E8 │ Workflow  │
 ├──────────────────────────────────┼────────────────────┼───────────┤
 │ workflows/plan-phase.md          │ E2, E4, E6, E7     │ Workflow  │
 ├──────────────────────────────────┼────────────────────┼───────────┤
 │ workflows/discuss-phase.md       │ E3                 │ Workflow  │
 ├──────────────────────────────────┼────────────────────┼───────────┤
 │ workflows/transition.md          │ E3                 │ Workflow  │
 ├──────────────────────────────────┼────────────────────┼───────────┤
 │ workflows/discovery-phase.md     │ E4                 │ Workflow  │
 ├──────────────────────────────────┼────────────────────┼───────────┤
 │ references/checkpoints.md        │ E8                 │ Reference │
 ├──────────────────────────────────┼────────────────────┼───────────┤
 │ templates/continuation-prompt.md │ E8                 │ NEW file  │
 └──────────────────────────────────┴────────────────────┴───────────┘