gsdd-cli 0.2.0 → 0.16.1

package/distilled/workflows/progress.md

@@ -18,7 +18,7 @@ This is a read-only workflow. No files are created, modified, or deleted. If `.p
 Check for project artifacts in order:
 
 1. **No `.planning/` directory** — tell the user to run `gsdd init`. Stop.
-2. **No `.planning/ROADMAP.md` AND no `.planning/SPEC.md`** — project has no artifacts. Suggest running the `/gsdd:new-project` workflow. Stop.
+2. **No `.planning/ROADMAP.md` AND no `.planning/SPEC.md`** — project has no artifacts. Suggest running the `/gsdd-new-project` workflow. Stop.
 3. **No `.planning/ROADMAP.md` BUT `.planning/SPEC.md` exists** — this is a between-milestones state (milestone was completed and archived). Go to Branch F.
 4. **Both exist** — proceed to derive status.
 </check_existence>
@@ -51,6 +51,14 @@ Scan `.planning/phases/` for:
 
 **Quick task log:**
 If `.planning/quick/LOG.md` exists, check the last entry for a non-terminal status.
+
+<unmerged_commits_check>
+Run `git log main..HEAD --oneline` to detect commits on the current branch that have not been merged to `main`.
+
+- If the command exits non-zero or `main` does not exist, skip silently — do not surface an error or any output.
+- If the output is empty, record nothing — the silent path; no status line is added.
+- If the output is non-empty, record the commit lines and count them. This will be surfaced in the status block.
+</unmerged_commits_check>
 </derive_status>
 
 <recent_work>
@@ -78,7 +86,7 @@ Recent Work:
 - Phase [Y]: [one-liner from SUMMARY.md]
 
 [If .continue-here.md exists:]
-Checkpoint: paused work found — run /gsdd:resume to restore context
+Checkpoint: paused work found — run /gsdd-resume to restore context
 
 [If PLAN without SUMMARY found:]
 Incomplete execution: Phase [N] has PLAN but no SUMMARY
@@ -89,6 +97,11 @@ Unverified: Phase [N] has SUMMARY but no VERIFICATION
 [If incomplete quick task found:]
 Incomplete quick task: [description]
 
+[If unmerged commits found (git log main..HEAD --oneline returned output):]
+Unmerged commits: [N] commit(s) on this branch not yet merged to main
+  → Merge or push this branch before closing the milestone, or verify
+    these commits are intentional working-branch state.
+
 [If all phases [x]:]
 All phases complete — ready for milestone audit
 ```
@@ -107,8 +120,8 @@ Recent Work:
 Incomplete execution: Phase 3 has PLAN but no SUMMARY
 
 Suggested next action:
-  Run /gsdd:execute to continue Phase 3 execution
-  Also available: /gsdd:plan (re-plan), /gsdd:progress (refresh status)
+  Run /gsdd-execute to continue Phase 3 execution
+  Also available: /gsdd-plan (re-plan), /gsdd-progress (refresh status)
 ```
 
 No ASCII art, no progress bars. Keep it scannable.
@@ -122,8 +135,8 @@ Condition: `.continue-here.md` exists.
 
 ```
 Suggested next action:
-  Run /gsdd:resume to restore paused session context
-  Also available: /gsdd:execute (ignore checkpoint, continue current phase), /gsdd:progress (refresh)
+  Run /gsdd-resume to restore paused session context
+  Also available: /gsdd-execute (ignore checkpoint, continue current phase), /gsdd-progress (refresh)
 ```
 
 **Branch B: Execute (PLAN without SUMMARY in current phase)**
@@ -131,8 +144,8 @@ Condition: Current phase has a PLAN file but no matching SUMMARY.
 
 ```
 Suggested next action:
-  Run /gsdd:execute to continue Phase [N] execution
-  Also available: /gsdd:plan (re-plan current phase), /gsdd:verify (if prior phase needs verification)
+  Run /gsdd-execute to continue Phase [N] execution
+  Also available: /gsdd-plan (re-plan current phase), /gsdd-verify (if prior phase needs verification)
 ```
 
 **Branch C: Plan (no PLAN for current phase)**
@@ -140,8 +153,8 @@ Condition: Current phase has no PLAN files.
 
 ```
 Suggested next action:
-  Run /gsdd:plan to create a plan for Phase [N]: [phase name]
-  Also available: /gsdd:quick (sub-hour task outside phases), /gsdd:map-codebase (refresh codebase maps)
+  Run /gsdd-plan to create a plan for Phase [N]: [phase name]
+  Also available: /gsdd-quick (sub-hour task outside phases), /gsdd-map-codebase (refresh codebase maps)
 ```
 
 **Branch D: Verify (SUMMARY without VERIFICATION)**
@@ -149,8 +162,8 @@ Condition: Current phase has SUMMARY but no VERIFICATION file (verifier enabled)
 
 ```
 Suggested next action:
-  Run /gsdd:verify to validate Phase [N]
-  Also available: /gsdd:execute (continue to next phase), /gsdd:plan (plan next phase)
+  Run /gsdd-verify to validate Phase [N]
+  Also available: /gsdd-execute (continue to next phase), /gsdd-plan (plan next phase)
 ```
 
 **Branch E: Audit milestone (all phases [x])**
@@ -158,17 +171,26 @@ Condition: All phases in ROADMAP.md are marked `[x]`.
 
 ```
 Suggested next action:
-  Run /gsdd:audit-milestone to audit the completed milestone
-  Also available: /gsdd:verify (re-verify a specific phase), /gsdd:quick (sub-hour task)
+  Run /gsdd-audit-milestone to audit the completed milestone
+  Also available: /gsdd-verify (re-verify a specific phase), /gsdd-quick (sub-hour task)
 ```
 
 **Branch F: Between milestones (SPEC.md exists, ROADMAP.md absent)**
 Condition: `.planning/SPEC.md` exists but `.planning/ROADMAP.md` does not — a milestone was completed and archived.
 
+Check `.planning/MILESTONES.md`:
+- If MILESTONES.md exists and has at least one milestone entry → this is a subsequent milestone
+- If MILESTONES.md does not exist or is empty → this is the first milestone setup
+
 ```
-Suggested next action:
-  Run /gsdd:new-project to start the next milestone cycle (create a new ROADMAP.md)
-  Also available: /gsdd:progress (refresh after milestone setup)
+Suggested next action (subsequent milestone):
+  Run /gsdd-new-milestone to start the next milestone cycle (gather goals, define requirements, create ROADMAP.md)
+  Also available: /gsdd-progress (refresh after milestone setup)
+
+Suggested next action (incomplete milestone state — SPEC.md exists but no milestone archived yet):
+  Inspect .planning/ manually — a milestone is likely still in progress.
+  If a ROADMAP.md was deleted prematurely, re-run /gsdd-new-milestone to restore it.
+  Do NOT run /gsdd-new-project — SPEC.md already exists and re-running would overwrite it.
 ```
 
 If none of the above conditions match, report that the project is in a clean state with no obvious next action.
@@ -178,7 +200,7 @@ If none of the above conditions match, report that the project is in a clean sta
 Handle compound states:
 
 - **Checkpoint + unexecuted plan:** Both `.continue-here.md` exists and a PLAN lacks a SUMMARY. Prioritize checkpoint (Branch A) but mention the unexecuted plan in the status block.
-- **All phases complete + checkpoint:** All phases `[x]` but a checkpoint exists. Mention both — suggest clearing the stale checkpoint via `/gsdd:resume`, then routing to milestone audit.
+- **All phases complete + checkpoint:** All phases `[x]` but a checkpoint exists. Mention both — suggest clearing the stale checkpoint via `/gsdd-resume`, then routing to milestone audit.
 - **Phase done but next unplanned:** Current phase has both PLAN and SUMMARY, but the next phase has no PLAN. Show the current phase as complete and suggest planning the next phase (Branch C targeting the next phase).
 - **No matching condition:** If the project state does not match any branch, report it clearly and suggest the user inspect `.planning/` manually.
 </edge_cases>
@@ -193,7 +215,8 @@ Handle compound states:
 - [ ] Routing suggestion is specific (includes phase number and branch-specific output block)
 - [ ] Named branch output format used with "Also available" alternatives
 - [ ] No files created, modified, or deleted (read-only workflow)
-- [ ] All workflow references use portable `/gsdd:*` command format
+- [ ] All workflow references use portable `/gsdd-*` command format
 - [ ] No interactive menus, no numbered option lists, no waiting for user selection
 - [ ] Edge cases handled for compound states
+- [ ] Unmerged-commit warning only appears when `git log main..HEAD --oneline` returns output; silent when empty
 </success_criteria>

package/distilled/workflows/quick.md

@@ -5,6 +5,16 @@ Quick tasks are for sub-hour work: bug fixes, small features, config changes, on
 They reuse the same planner, executor, and verifier roles but skip research and synthesizer.
 </role>
 
+<anti_patterns>
+- Do not execute before the user sees the plan preview (Step 3.7 must complete before Step 4)
+- Do not proceed past file verification gates if the expected file does not exist on disk — a plan that exists only in conversation context will be lost on compaction
+- Do not ask more than 2 approach clarification questions — if 3+ grey areas exist, recommend /gsdd-plan instead
+- Do not create APPROACH.md for quick tasks — use inline $APPROACH_CONTEXT only
+- Do not update ROADMAP.md or SPEC.md from quick tasks — these are phase-level artifacts
+- Do not skip config.json reads — workflow toggles (discuss, planCheck, verifier) control flow
+- Do not expand scope mid-execution — if the plan reveals architectural work, surface the scope signal (Step 3.6) and let the user decide
+</anti_patterns>
+
 <prerequisites>
 `.planning/` must exist (from `gsdd init`). ROADMAP.md is NOT required -- quick tasks work during any project phase.
 
@@ -27,6 +37,9 @@ Store the response as `$DESCRIPTION`. If empty, re-prompt.
 2. Scan `.planning/quick/` for existing task directories. Calculate `$NEXT_NUM` as the next 3-digit number (001, 002, ...).
 3. Generate `$SLUG` from `$DESCRIPTION` (lowercase, hyphens, max 40 chars).
 4. Create `.planning/quick/$NEXT_NUM-$SLUG/`.
+5. If `.planning/codebase/` exists, read `.planning/codebase/ARCHITECTURE.md` and `.planning/codebase/STACK.md`. Summarize key findings in <=500 words as `$CODEBASE_CONTEXT`. If `.planning/codebase/` does not exist, set `$CODEBASE_CONTEXT` to empty.
+6. **Session-boundary fallback:** If `.planning/.continue-here.bak` exists, read its `<judgment>` section. Use `<active_constraints>` and `<anti_regression>` rules as task-scoping context (do not violate active constraints; do not regress on listed invariants). After reading, run `gsdd file-op delete .planning/.continue-here.bak --missing ok` (auto-clean).
+7. Inspect the live branch/worktree surface separately from checkpoint or planning artifacts. If the current branch appears stale/spent, PR-less with overlapping write scope, or otherwise like the wrong execution surface, warn before proceeding. This is advisory for quick tasks unless the mismatch makes the task description materially misleading.
 
 If `.planning/quick/` does not exist, create it along with an empty `LOG.md`:
 
@@ -39,6 +52,44 @@ If `.planning/quick/` does not exist, create it along with an empty `LOG.md`:
 
 ---
 
+## Step 2.5: Approach clarification (conditional)
+
+Read `.planning/config.json`.
+- If `workflow.discuss` is `false` (or key missing): set `$APPROACH_CONTEXT` to empty, skip to Step 3.
+- If `workflow.discuss` is `true`: evaluate `$DESCRIPTION` for ambiguity signals.
+
+### Ambiguity signals
+
+| Signal | Detection | Example |
+|--------|-----------|---------|
+| Multiple valid approaches | Description could be solved via distinct patterns | "add caching" (Redis? in-memory? HTTP headers?) |
+| Destructive operations | Contains: `delete`, `remove`, `migrate`, `rename`, `replace`, `rewrite`, `drop` | "remove the old auth middleware" |
+| Vague scope | Contains: `improve`, `fix`, `update`, `refactor`, `clean up`, `optimize` without specifying target | "improve error handling" |
+| Trade-off present | Description implies competing goals (performance vs simplicity, DRY vs explicit) | "make it faster" |
+
+If **no signals fire**: set `$APPROACH_CONTEXT` to empty, skip to Step 3 silently.
+
+If **any signal fires**: identify 1-2 grey areas and ask targeted questions.
+
+### Question format
+
+For each grey area, present 2-3 concrete options with a recommended default:
+
+"I'd approach this with **{recommendation}** because {reason}. Want me to proceed, or do you prefer {alternative}?"
+
+- If user says "go ahead" / "your call" / presses Enter → use the recommendation.
+- If user specifies a preference → record it.
+- Maximum 2 questions. If the task has 3+ grey areas, it's not a quick task.
+
+### Output
+
+Store confirmed decisions as `$APPROACH_CONTEXT` — a short string of user-validated choices.
+Example: "User confirmed: use in-memory LRU cache, not Redis. Keep existing error format."
+
+No APPROACH.md file is created. This is inline context only.
+
+---
+
 ## Step 3: Plan
 
 Delegate to the planner role in quick mode.
@@ -49,10 +100,13 @@ Delegate to the planner role in quick mode.
 
 **Context to provide:**
 - Task description: `$DESCRIPTION`
+- Approach context: `$APPROACH_CONTEXT` (user-confirmed decisions from Step 2.5 — treat as locked constraints, do not revisit)
+- Codebase context: `$CODEBASE_CONTEXT` (existing architecture and stack — use for orientation, not as constraints; empty if no codebase map exists)
 - Mode: quick (single plan, 1-3 tasks, no research phase)
 - Output path: `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-PLAN.md`
 
 **Constraints:**
+- If `$APPROACH_CONTEXT` is non-empty, implement the user's confirmed choices — do not substitute alternatives
 - Create a SINGLE plan with 1-3 focused tasks
 - Quick tasks are atomic and self-contained
 - No research phase, no ROADMAP requirements
@@ -66,13 +120,116 @@ Delegate to the planner role in quick mode.
 </delegate>
 
 After the planner returns:
-1. Verify the plan file exists.
-2. If not found, report the error and stop.
+
+**STOP. Verify that `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-PLAN.md` exists on disk before proceeding to execution. If the file does not exist, report the error to the user and do NOT proceed. A plan that exists only in conversation context will be lost.**
+
+### Quick Plan Self-Check
+
+Before proceeding to execution, verify the plan meets minimum quality:
+- [ ] Plan has at least 1 task with `<action>` and `<verify>` sections
+- [ ] Each task's `<verify>` has at least one runnable command
+- [ ] Plan tasks do not exceed 3 (quick scope constraint)
+
+This is a self-check, not an independent plan-check. Failures are noted but do NOT block execution — report `reduced_assurance` in the completion summary.
+
+---
+
+## Step 3.5: Independent plan check (conditional)
+
+Read `.planning/config.json`.
+- If `workflow.planCheck` is `false` (or key missing): skip to Step 3.6.
+- If `workflow.planCheck` is `true`: delegate to the plan-checker with quick-scoped dimensions.
+
+<delegate>
+**Identity:** Plan Checker (quick mode)
+**Instruction:** Read `.planning/templates/delegates/plan-checker.md` for your role contract, then check this quick task plan.
+
+**Context to provide:**
+- Task description: `$DESCRIPTION` (treat as the phase goal equivalent)
+- Plan: `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-PLAN.md`
+- Mode: quick
+
+**Constraints:**
+- Check 5 dimensions only: `requirement_coverage`, `task_completeness`, `dependency_correctness`, `scope_sanity`, `must_have_quality`
+- Skip: `key_link_completeness`, `context_compliance`, `goal_achievement`, `approach_alignment`
+- Maximum 1 revision cycle (if blockers found, send back to planner once, then accept result)
+- Blocker threshold: only block on `task_completeness` or `scope_sanity` violations
+- Warnings for other dimensions are noted but do not block
+
+**Output:** Checker response (passed | issues_found) with issue details.
+**Return:** Status and issue summary.
+</delegate>
+
+If the checker returns `issues_found` with blockers and this is the first cycle:
+1. Send the issue list back to the planner for targeted revision of the plan file.
+2. Re-run the checker once more.
+3. If blockers remain after 1 revision cycle, store `$CHECKER_ISSUES` for display in the plan preview. Do NOT block — the user decides in Step 3.7.
+
+If the checker returns `passed`, or `workflow.planCheck` is false, `$CHECKER_ISSUES` is empty.
+
+---
+
+## Step 3.6: Scope signal evaluation
+
+Evaluate the plan against quick-scope boundaries. Read the plan file and check:
+
+| Signal | Threshold | `$SCOPE_WARNING` text |
+|--------|-----------|----------------------|
+| Files modified | >8 distinct files in plan | "This task touches {N} files — consider `/gsdd-plan` for full ceremony." |
+| Architecture keywords in `$DESCRIPTION` | contains: `refactor`, `migration`, `security`, `auth`, `API design`, `schema`, `database` | "This looks like architectural work — consider `/gsdd-plan` for approach exploration." |
+| New public APIs | Plan tasks create new route files, API endpoints, or exported interfaces | "New public surface area detected — consider `/gsdd-plan` for approach exploration." |
+
+If any signal fires, set `$SCOPE_WARNING` to the first matching advisory text. Multiple signals concatenate.
+If no signals fire, `$SCOPE_WARNING` is empty.
+
+This is advisory only — it does NOT block execution.
+
+---
+
+## Step 3.7: Plan preview
+
+Present the plan summary to the user before execution begins.
+
+Read the plan file and extract:
+- Task count and task names
+- List of files to be modified/created (from plan task `<files>` sections)
+- A 1-sentence approach summary (first sentence of the plan's objective or goal)
+
+Display:
+
+```
+Quick Task Plan Preview:
+- Tasks: {count} ({task_names})
+- Files: {file_list}
+- Approach: {1-sentence summary}
+```
+
+If `$SCOPE_WARNING` is non-empty, append:
+```
+Scope signal: {$SCOPE_WARNING}
+```
+
+If `$CHECKER_ISSUES` is non-empty, append:
+```
+Plan check issues: {$CHECKER_ISSUES}
+```
+
+Present options (default-yes — pressing Enter proceeds):
+- If `$SCOPE_WARNING` is empty: `[Enter to proceed / edit description / abort]`
+- If `$SCOPE_WARNING` is non-empty: `[Enter to proceed / switch to /gsdd-plan / edit description / abort]`
+
+Handle response:
+- **Enter (or "yes"):** proceed to Step 4.
+- **"edit description":** clean up the task directory, then return to Step 1 with `$DESCRIPTION` pre-filled as the starting point.
+- **"switch to /gsdd-plan":** clean up the task directory, then stop quick workflow and report: "Use `/gsdd-plan` for full ceremony with approach exploration. Task description: {$DESCRIPTION}"
+- **"abort":** clean up the task directory, report cancellation, stop.
 
 ---
 
 ## Step 4: Execute
 
+**Only reached after the user has seen the plan preview in Step 3.7.**
+
 Delegate to the executor role.
 
 <delegate>
@@ -96,8 +253,8 @@ Delegate to the executor role.
 </delegate>
 
 After the executor returns:
-1. Verify the summary file exists.
-2. If not found, report the error and stop.
+
+**STOP. Verify the SUMMARY file exists at `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-SUMMARY.md` on disk. If it does not exist, report the write failure. Do NOT proceed to verification or LOG.md update without a persisted summary.**
 
 ---
 
@@ -125,6 +282,8 @@ Read `.planning/config.json`.
 **Return:** Verification status (passed | gaps_found | human_needed).
 </delegate>
 
+**STOP. Verify the VERIFICATION file exists at `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-VERIFICATION.md` on disk (when verifier ran). If it does not exist, report the write failure. Do NOT proceed to LOG.md update without a persisted verification report.**
+
 ---
 
 ## Step 6: Update LOG.md
@@ -154,9 +313,13 @@ Report to the user:
 
 <success_criteria>
 - [ ] User provided a task description
+- [ ] Approach clarification ran (only if workflow.discuss is true AND ambiguity detected)
 - [ ] `.planning/quick/` directory exists (created if needed)
 - [ ] Task directory created at `.planning/quick/NNN-slug/`
 - [ ] `NNN-PLAN.md` created by planner (1-3 tasks)
+- [ ] Independent plan check ran (only if workflow.planCheck is true)
+- [ ] Plan preview presented to user before execution
+- [ ] User confirmed (or pressed Enter) before execution proceeded
 - [ ] `NNN-SUMMARY.md` created by executor
 - [ ] `NNN-VERIFICATION.md` created by verifier (only if workflow.verifier is true)
 - [ ] `LOG.md` updated with task row
@@ -175,12 +338,12 @@ Created:
 - `.planning/quick/{next_num}-{slug}/{next_num}-VERIFICATION.md` (if verifier enabled)
 - Updated `.planning/quick/LOG.md`
 
-**Next step:** `/gsdd:progress` — check project status and continue phase work
+**Next step:** `/gsdd-progress` — check project status and continue phase work
 
 Also available:
-- `/gsdd:quick` — run another quick task
-- `/gsdd:plan` — plan the next phase
-- `/gsdd:pause` — save context for later if stopping work
+- `/gsdd-quick` — run another quick task
+- `/gsdd-plan` — plan the next phase
+- `/gsdd-pause` — save context for later if stopping work
 
 Consider clearing context before starting the next workflow for best results.
 ---

package/distilled/workflows/resume.md

@@ -10,13 +10,19 @@ Scope boundary: unlike progress.md, you have side effects — checkpoint cleanup
 `.planning/` should exist. If it does not, route the user to `gsdd init`.
 </prerequisites>
 
+<runtime_contract>
+Use the `Runtime` type from `.planning/SPEC.md`.
+Infer runtime from the launching surface when obvious: `.claude/` -> `claude-code`, `.codex/` or Codex portable skill -> `codex-cli`, `.opencode/` -> `opencode`, otherwise `other`.
+When a checkpoint's `runtime` differs from the inferred current runtime, surface it as an informational note in `<present_status>` — it is context, not a gate.
+</runtime_contract>
+
 <process>
 
 <detect_state>
 Check for project artifacts in order:
 
 1. **No `.planning/` directory** — route user to run `gsdd init`. Stop.
-2. **No `.planning/SPEC.md` or no `.planning/ROADMAP.md`** — `.planning/` exists but the project is not fully initialized (partial init). Route user to run the `/gsdd:new-project` workflow. Stop.
+2. **No `.planning/SPEC.md` or no `.planning/ROADMAP.md`** — `.planning/` exists but the project is not fully initialized (partial init). Route user to run the `/gsdd-new-project` workflow. Stop.
 3. **Both exist** — proceed to load state.
 </detect_state>
 
@@ -44,7 +50,9 @@ Read `.planning/SPEC.md`. Extract:
 Check if `.planning/.continue-here.md` exists. If yes, read it and extract:
 - `workflow` frontmatter (phase/quick/generic)
 - `phase` frontmatter
+- `runtime` frontmatter (the runtime that wrote the checkpoint; use `unknown` if field absent)
 - All 6 sections: current_state, completed_work, remaining_work, decisions, blockers, next_action
+- `<judgment>` if present, including `<active_constraints>`, `<unresolved_uncertainty>`, `<decision_posture>`, and `<anti_regression>`
 
 **Phase directories:**
 Scan `.planning/phases/` for:
@@ -53,8 +61,67 @@ Scan `.planning/phases/` for:
 
 **Quick task log:**
 If `.planning/quick/LOG.md` exists, read the last entry. Check if it has a non-terminal status (not `done`/`passed`).
+
+**Git/worktree truth:**
+Collect the live integration-surface facts separately from checkpoint narrative truth:
+- current branch name
+- branch divergence from `main` (and tracked remote when available)
+- staged pending truth
+- unstaged local edits
+- untracked local files
+- PR presence/state when available
+- whether the current branch appears stale/spent or the dirty tree appears mixed-scope
 </load_artifacts>
 
+<provenance_reconciliation>
+Before routing, reconstruct and compare these truth buckets explicitly:
+
+1. **Checkpoint narrative truth** — what `.planning/.continue-here.md` claims was happening
+2. **Planning/artifact truth** — what ROADMAP, SPEC, phase files, and quick-task logs say
+3. **Git/worktree truth** — what the live branch and working tree say now
+
+Treat them as separate inputs. Do not flatten them into one continuity story.
+
+Material mismatch signals include:
+- checkpoint narrative describes only a narrow slice of a broader dirty tree
+- current branch is stale/spent relative to the next intended integration surface
+- dirty files suggest overlapping write sets or mixed phase scope
+
+If git/worktree truth materially disagrees with checkpoint narrative truth:
+- record a mismatch flag
+- keep ordinary git risk warning-level by default
+- require explicit user acknowledgement before routing onward
+- do not allow a quick "continue" shortcut to skip that acknowledgement
+</provenance_reconciliation>
+
+<validate_checkpoint>
+Only run this step when `.planning/.continue-here.md` was found in `<load_artifacts>`. If no checkpoint exists, skip this step entirely.
+
+Cross-validate checkpoint fields against current roadmap state in this order:
+
+1. Extract the checkpoint `workflow` and `phase` frontmatter fields.
+2. If `phase` is non-null, look up that exact phase name in `.planning/ROADMAP.md`.
+   - If the matching roadmap entry is `[x]`, mark the checkpoint as stale.
+   - Record the specific reason in this form: `checkpoint references phase "[phase]" which is already complete [x] in ROADMAP.md`.
+   - Stop further staleness checks after recording this reason.
+3. If `workflow` is `phase` and `phase` is null, mark the checkpoint as potentially stale.
+   - Record the reason in this form: `checkpoint workflow is "phase" but checkpoint phase is missing`.
+4. If `workflow` is `phase` and `phase` is non-null but no matching roadmap entry exists, mark the checkpoint as potentially stale.
+   - Record the reason in this form: `checkpoint workflow is "phase" but phase "[phase]" was not found in ROADMAP.md`.
+5. If `workflow` is `phase` and `phase` matches a roadmap entry with status `[ ]` or `[-]`, do not mark it stale based only on missing execution artifacts. Continue normally.
+6. If no structural staleness rule applied, skip validation cleanly. This includes `generic` or `quick` checkpoints with null `phase`.
+
+When staleness is detected:
+- Record a staleness flag and keep the full reason text.
+- Record only one staleness reason string. Do not append additional reasons after the first matching rule.
+- Do NOT delete the checkpoint.
+- Do NOT suppress the checkpoint contents.
+
+The output of this step is either:
+- no staleness flag, or
+- a staleness flag with a specific reason string that flows into `<present_status>` and `<determine_action>`.
+</validate_checkpoint>
+
 <present_status>
 Present a compact status to the user:
 
@@ -64,10 +131,43 @@ Phase: [current] of [total] — [phase name]
 Completed: [N] phases done
 
 [If .continue-here.md exists:]
+[If stale checkpoint flag set:]
+⚠ Stale checkpoint detected
+  Reason: [specific staleness reason]
+  Review the checkpoint contents below and decide whether to resume from it or continue without it.
+
 Checkpoint found: [workflow type] — [phase name or task description]
   Last paused: [timestamp from frontmatter]
+  Paused by: [runtime from checkpoint, or unknown if field absent]
+  Resuming in: [inferred current runtime]
   Next action: [next_action section content]
 
+[If <judgment> was present in checkpoint:]
+  Judgment context:
+    Constraints:
+[Full content of <active_constraints>]
+    Uncertainty:
+[Full content of <unresolved_uncertainty>]
+    Posture:
+[Full content of <decision_posture>]
+    Anti-regression:
+[Full content of <anti_regression>]
+
+[If git/worktree truth was collected:]
+Git/worktree truth:
+  Branch: [current branch]
+  Divergence: [ahead/behind or unknown]
+  Staged: [count]
+  Unstaged: [count]
+  Untracked: [count]
+  PR: [open|closed|merged|none|unknown]
+  Integration surface: [clean | warning | stale/spent | mixed-scope]
+
+[If material checkpoint/worktree mismatch flag set:]
+⚠ Checkpoint/worktree mismatch
+  The checkpoint narrative no longer matches the live branch/worktree scope.
+  Review both truth surfaces before choosing the next action.
+
 [If incomplete phase execution found:]
 Incomplete execution: Phase [N] has a PLAN but no SUMMARY
 
@@ -76,6 +176,8 @@ Incomplete quick task: [description from LOG.md]
 ```
 
 No ASCII art, no progress bars. Keep it scannable.
+
+Only show the staleness banner when `<validate_checkpoint>` produced a staleness flag. Even when flagged, still show the checkpoint details immediately below the banner.
 </present_status>
 
 <determine_action>
@@ -83,21 +185,25 @@ Evaluate in priority order and present the primary recommendation:
 
 **Checkpoint exists (`.continue-here.md`):**
 Route based on the `workflow` frontmatter:
-- `phase` — route to `/gsdd:execute` (or `/gsdd:plan`/`/gsdd:verify` based on checkpoint context)
-- `quick` — route to `/gsdd:quick` to complete the task
+- `phase` — route to `/gsdd-execute` (or `/gsdd-plan`/`/gsdd-verify` based on checkpoint context)
+- `quick` — route to `/gsdd-quick` to complete the task
 - `generic` — present the next_action and let the user decide
 
+If `<validate_checkpoint>` marked the checkpoint as stale, keep the same routing logic. The user may still choose to resume from the checkpoint after reviewing the warning. If the user chooses a different path, leave the checkpoint in place and continue without it.
+
+If `<provenance_reconciliation>` marked a material checkpoint/worktree mismatch, keep the same routing logic but require explicit acknowledgement before continuing. The workflow should not silently route onward from a materially misleading checkpoint narrative.
+
 **Incomplete plan execution (PLAN without SUMMARY):**
-Route to `/gsdd:execute` for that phase.
+Route to `/gsdd-execute` for that phase.
 
 **Phase needs planning (next `[ ]` phase, no PLAN file exists):**
-Route to `/gsdd:plan` for that phase.
+Route to `/gsdd-plan` for that phase.
 
 **Phase needs verification (SUMMARY exists but no VERIFICATION):**
-Route to `/gsdd:verify` for that phase (only if `workflow.verifier` is enabled in config.json; if config.json cannot be read, assume verifier is disabled).
+Route to `/gsdd-verify` for that phase (only if `workflow.verifier` is enabled in config.json; if config.json cannot be read, assume verifier is disabled).
 
 **All phases complete (all `[x]`):**
-Route to `/gsdd:audit-milestone`.
+Route to `/gsdd-audit-milestone`.
 </determine_action>
 
 <present_options>
@@ -112,17 +218,21 @@ What would you like to do?
 4. Something else
 ```
 
-**Quick-resume shortcut:** If the user says "continue", "go", or "resume" without further input, skip the options and execute the primary action directly.
+**Quick-resume shortcut:** If there is no stale-checkpoint banner and no material checkpoint/worktree mismatch, the user may say "continue", "go", or "resume" without further input to execute the primary action directly.
+
+**Mismatch acknowledgement:** If material checkpoint/worktree mismatch was detected, require an explicit acknowledgement such as "continue despite mismatch" or a different selected path. Do not let a bare "continue" skip the warning.
 
 Wait for user selection.
 </present_options>
 
 <cleanup_checkpoint>
 Immediately after the user confirms their action selection (before routing to the target workflow):
-- If the user chose to resume from `.continue-here.md`, delete it now — before dispatching to the target workflow.
+- If the user chose to resume from `.continue-here.md`:
+  1. Run `gsdd file-op copy .planning/.continue-here.md .planning/.continue-here.bak`.
+  2. After the copy succeeds, run `gsdd file-op delete .planning/.continue-here.md`.
 - If the user chose a different action (not based on the checkpoint), leave `.continue-here.md` in place for a future resume.
 
-Deleting before routing ensures a failed or interrupted workflow does not leave a stale checkpoint that would mislead the next resume invocation.
+Copying before deleting ensures the checkpoint survives a session crash between deletion and dispatch. `.continue-here.bak` is cleaned up by the downstream workflow after absorbing the judgment, or by the next `pause.md` run.
 </cleanup_checkpoint>
 
 </process>
@@ -148,5 +258,5 @@ Present to the user before dispatching:
 Consider clearing context before starting the next workflow for best results.
 ---
 
-Then dispatch to the selected `/gsdd:*` workflow.
+Then dispatch to the selected `/gsdd-*` workflow.
 </completion>