gsdd-cli 0.3.1 → 0.18.0

package/distilled/workflows/resume.md

@@ -10,13 +10,32 @@ 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>
+
+<lifecycle_preflight>
+Before loading checkpoint state or cleaning up any checkpoint file, run:
+
+- `gsdd lifecycle-preflight resume`
+
+If the preflight result is `blocked`, STOP and report the blocker instead of inferring resume eligibility from workflow-local prose.
+
+Treat the preflight as an authorization seam over shared repo truth only:
+- it may authorize or reject resume
+- it does not mutate phase or milestone state
+- the owned write for this workflow remains checkpoint cleanup when the user actually resumes from `.continue-here.md`
+</lifecycle_preflight>
+
 <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 +63,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 +74,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 +144,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 +189,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 +198,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
-- `generic` — present the next_action and let the user decide
+- `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 checkpoint `next_action` and let the user decide. This workflow still owns checkpoint cleanup only if the user explicitly resumes from that checkpoint, but downstream read-only `progress` routing must treat the surviving generic checkpoint as informational context rather than an automatic blocker.
+
+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 +231,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 +271,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>

package/distilled/workflows/verify-work.md

@@ -0,0 +1,260 @@
+<purpose>
+Validate built features through conversational testing with persistent state.
+Creates UAT.md that tracks test progress, survives context resets, and feeds gaps into `/gsdd-plan`.
+
+User tests, Claude records. One test at a time. Plain text responses.
+</purpose>
+
+<philosophy>
+**Show expected, ask if reality matches.**
+
+Present what SHOULD happen. User confirms or describes what's different.
+- "yes" / "y" / "pass" / empty → pass
+- Anything else → logged as issue, severity inferred from natural language
+
+No Pass/Fail buttons. No severity questions. Just: "Here's what should happen. Does it?"
+</philosophy>
+
+<load_context>
+Read these before any other action:
+1. `.planning/phases/{N}-*/` — all `*-SUMMARY.md` files for the target phase
+2. `.planning/SPEC.md` — requirements and acceptance criteria
+3. `.planning/ROADMAP.md` — phase goal and must-haves
+
+**$ARGUMENTS:** optional phase number, e.g., `/gsdd-verify-work 4`
+</load_context>
+
+<session_detection>
+Before starting a new session, check for existing UAT state:
+
+```bash
+# Check for existing UAT files in this phase
+ls .planning/phases/{N}-*/*-UAT.md 2>/dev/null || echo "none"
+```
+
+**If a UAT.md exists** with `status: testing`, offer to resume:
+```
+UAT in progress: Phase {N} — {passed}/{total} tests done, {issues} issues found so far.
+Reply "resume" to continue from where you left off, or "restart" to begin fresh.
+```
+
+**If no UAT.md exists** or user says "restart", proceed to `<extract_tests>`.
+</session_detection>
+
+<extract_tests>
+From each `*-SUMMARY.md` in the phase directory, extract testable deliverables:
+
+1. Read **Accomplishments** and **Notes for Verification** sections.
+2. Focus on **user-observable outcomes** — UI behavior, API responses, workflow outputs. Skip refactors, type changes, internal restructures.
+3. For each deliverable, define:
+   - `name`: brief test name
+   - `expected`: what the user should see or experience (specific and observable)
+
+Examples:
+- Accomplishment: "Added comment threading" → Test: "Reply to a comment" → Expected: "Clicking Reply opens inline composer. Reply appears nested under parent with visual indent."
+- Accomplishment: "JWT auth with refresh rotation" → Test: "Token refresh on expiry" → Expected: "After token expires, next request silently refreshes and succeeds. User is not logged out."
+
+Present the test list to the user for a quick scan:
+```
+Phase {N} — {count} tests extracted
+
+1. {Test Name}
+2. {Test Name}
+...
+
+Reply "start" to begin, or add/remove tests before starting.
+```
+
+Wait for confirmation.
+</extract_tests>
+
+<create_uat_file>
+Create `.planning/phases/{N}-{name}/{phase_num}-UAT.md`:
+
+```markdown
+---
+status: testing
+phase: {N}-{name}
+source: [{list of SUMMARY.md files read}]
+started: {ISO timestamp}
+updated: {ISO timestamp}
+---
+
+## Current Test
+
+number: 1
+name: {first test name}
+expected: |
+  {what user should observe}
+awaiting: user response
+
+## Tests
+
+### 1. {Test Name}
+expected: {observable behavior}
+result: pending
+
+### 2. {Test Name}
+expected: {observable behavior}
+result: pending
+
+...
+
+## Summary
+
+total: {N}
+passed: 0
+issues: 0
+pending: {N}
+skipped: 0
+
+## Gaps
+
+[none yet]
+```
+
+**MANDATORY: Write UAT.md to disk before presenting the first test.** This ensures progress survives a context reset.
+</create_uat_file>
+
+<testing_loop>
+**Present one test at a time:**
+
+```
+Test {N}/{total}: {Test Name}
+──────────────────────────────────────────────────
+Expected: {what should happen}
+
+→ Reply "pass" (or just press Enter) — or describe what went wrong
+──────────────────────────────────────────────────
+```
+
+**Process the response:**
+
+| Response | Action |
+|----------|--------|
+| empty, "yes", "y", "ok", "pass", "next" | Mark `result: pass` |
+| "skip", "n/a", "can't test" | Mark `result: skipped`, capture reason |
+| anything else | Treat as issue description — infer severity |
+
+**Severity inference from natural language (never ask):**
+
+| User says | Infer |
+|-----------|-------|
+| "crashes", "error", "exception", "fails completely" | `blocker` |
+| "doesn't work", "nothing happens", "wrong behavior" | `major` |
+| "works but...", "slow", "weird", "minor" | `minor` |
+| "color", "spacing", "alignment", "looks off" | `cosmetic` |
+| unclear | `major` (default) |
+
+**On issue:** Write immediately to disk (append to Gaps section):
+```yaml
+- truth: "{expected behavior from test}"
+  status: failed
+  reason: "User reported: {verbatim response}"
+  severity: {inferred}
+  test: {N}
+  root_cause: pending
+```
+
+**After each response:** Update Summary counts and frontmatter `updated` timestamp in UAT.md.
+
+Advance to the next pending test. Repeat until all tests have a result.
+</testing_loop>
+
+<diagnosis_protocol>
+When all tests are done and **issues > 0**, run inline diagnosis before routing to planning.
+
+For each gap in the Gaps section:
+
+1. Read the source files most likely responsible (infer from the expected behavior and `*-SUMMARY.md` "Notes for Verification").
+2. Form a root-cause hypothesis:
+   - Look for missing implementation, wrong logic, stale wiring, or missing state.
+3. Update the gap's `root_cause` field in UAT.md:
+   ```yaml
+   root_cause: "{one-sentence hypothesis: what is missing or wrong and where}"
+   ```
+4. Optionally add:
+   ```yaml
+   artifacts: ["{file path}"]
+   missing: ["{what is absent}"]
+   ```
+
+Do not attempt fixes during diagnosis — only gather evidence.
+
+After all gaps are diagnosed, write UAT.md to disk with the updated root causes.
+</diagnosis_protocol>
+
+<complete_session>
+**Finalize the UAT file:**
+
+Update frontmatter:
+```yaml
+status: complete
+updated: {now}
+```
+
+Clear the Current Test block:
+```
+## Current Test
+
+[testing complete]
+```
+
+Write final UAT.md to disk.
+
+**If no issues found:**
+```
+UAT complete — all {N} tests passed.
+
+Next step: /gsdd-progress — route to next phase or milestone audit
+```
+
+**If issues found:**
+
+Present summary:
+```
+UAT complete — Phase {N}
+
+| Result  | Count |
+|---------|-------|
+| Passed  | {N}   |
+| Issues  | {N}   |
+| Skipped | {N}   |
+
+Diagnosed {N} root cause(s). Ready to plan fixes.
+```
+
+Then route to gap closure (see `<completion>`).
+</complete_session>
+
+<success_criteria>
+- [ ] Phase SUMMARY files read before extracting tests
+- [ ] UAT.md written to disk before the first test is presented
+- [ ] Tests presented one at a time with specific expected behavior
+- [ ] Severity inferred from description — never asked
+- [ ] UAT.md updated after each issue (not batched to end)
+- [ ] Inline diagnosis completed for each issue before routing to planning
+- [ ] UAT.md finalized on disk with `status: complete`
+</success_criteria>
+
+<completion>
+Report to the user what was tested, then present the next step:
+
+---
+**Completed:** UAT — created `.planning/phases/{phase_dir}/{phase_num}-UAT.md`.
+
+If no issues:
+**Next step:** `/gsdd-progress` — route to next phase or milestone audit
+
+If issues found:
+**Next step:** `/gsdd-plan` — plan gap closure using the diagnosed root causes in UAT.md
+- Open `.planning/phases/{phase_dir}/{phase_num}-UAT.md` for the plan context
+- Use `--gaps` mode if your runtime supports it
+
+Also available:
+- `/gsdd-verify` — re-run formal phase verification after fixes are implemented
+- `/gsdd-pause` — save context for later if stopping work
+
+Consider clearing context before starting the next workflow for best results.
+---
+</completion>