gsdd-cli 0.3.1 → 0.18.0

package/distilled/workflows/plan.md

@@ -13,17 +13,42 @@ Before starting, read these files:
 4. `.planning/phases/*-APPROACH.md` - approach decisions from user discussion (if exists)
 5. `.planning/phases/*-PLAN.md` - any previous plans that affect this phase
 6. Relevant source code - if this phase builds on existing code, read the key files
-
+7. `.planning/phases/*-SUMMARY.md` for the prior completed phase - if a `<judgment>` section is present, read all four sub-sections. The `<judgment>` carries forward active constraints, unresolved uncertainty, decision posture, and anti-regression rules from the prior phase. Honor these as input context alongside SPEC.md decisions and APPROACH.md choices.
+8. **Session-boundary fallback:** If no prior completed phase SUMMARY.md with a `<judgment>` section was found in step 7, check whether `.planning/.continue-here.bak` exists. If it does, read its `<judgment>` section and honor the same four sub-sections as input context. After reading, run `gsdd file-op delete .planning/.continue-here.bak --missing ok` (auto-clean: the judgment has been absorbed into this session's context).
 Identify the target phase: the first phase with status `[ ]` or `[-]` in `ROADMAP.md`.
 </load_context>
 
+<integration_surface_check>
+Before planning roadmap work, inspect the live integration surface separately from checkpoint or planning artifacts:
+- current branch name
+- divergence from `main` when available
+- staged, unstaged, and untracked local truth
+- whether the current branch appears stale/spent or mixed-scope
+
+If the planning truth says "next phase is X" but the git/worktree truth says the current branch is a stale or mixed execution surface, warn explicitly and treat the dirty branch as evidence only. Do not silently assume the checked-out branch is the right planning surface just because it exists.
+</integration_surface_check>
+
+<runtime_contract>
+Use the `Runtime` and `Assurance` types 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`.
+Assurance is ordered: `unreviewed` -> `self_checked` -> `cross_runtime_checked`.
+Same-runtime helpers never count as cross-runtime evidence.
+</runtime_contract>
+
+<assurance_check>
+After `<load_context>`, compare the current planning pass against the strongest upstream artifact available: same-phase prior plan first, otherwise prior completed phase SUMMARY or VERIFICATION.
+Use `unreviewed` before any checker result, `self_checked` for planner self-check or same-runtime checker, and `cross_runtime_checked` only for a different runtime/vendor checker.
+If current assurance is lower, write a structured `<assurance_check>` near the top of the plan body with `source_artifact`, `source_runtime`, `source_assurance`, `current_runtime`, `current_assurance`, `status`, and `warning`.
+If upstream runtime/assurance is missing, use `status: unknown`.
+</assurance_check>
+
 <context_fidelity>
 Before planning, acknowledge what is locked:
-
 - Decisions in `.planning/SPEC.md` "Key Decisions" - do not revisit them.
 - Decisions in APPROACH.md "Implementation Decisions" - these are user-validated choices. Implement the chosen approaches, not alternatives. "Agent's Discretion" items give you flexibility.
 - Patterns from previous phases - match existing conventions. Do not introduce new patterns without cause.
 - Deferred items - items marked v2, nice-to-have, or out of scope in SPEC.md or APPROACH.md. Do not plan for them.
+- Cross-check: if SPEC.md and APPROACH.md disagree on whether an item is must-have or deferred, stop and ask the user before planning. Do not silently adopt one classification over the other.
 
 If you need to challenge a locked decision: stop, ask the developer, and document the new decision explicitly.
 </context_fidelity>
@@ -58,9 +83,30 @@ Write to `.planning/research/{phase_number}-RESEARCH.md` with sections:
 - Research for this phase already exists and is still fresh
 - The phase uses only technologies already established in previous phases
 
-Quality gate: do not proceed to goal-backward planning if you have unresolved uncertainties about the implementation approach.
+Quality gate: do not proceed to goal-backward planning if you have unresolved uncertainties about the implementation approach. If research was skipped (skip conditions above apply), document the skip reason in the plan Notes section so the plan checker can verify the skip was justified.
 </research_check>
 
+<spec_quality_check>
+### When This Runs
+After research_check, before goal_backward_planning.
+
+### Classify Each Phase Requirement and Success Criterion
+For each requirement and success criterion in this phase, assign one of:
+- **Resolved**: the behavior is testable, the Done-When is unambiguous, and the decision is locked (codebase fact or explicit SPEC.md/APPROACH.md decision). Proceed.
+- **Open**: the requirement depends on a product or UX decision that has not been made. Cannot proceed.
+- **Ambiguous**: there are two or more reasonable interpretations of what "done" means. Cannot proceed.
+
+Trigger questions per item:
+- Is the Done-When criterion specific enough to write a verify command for?
+- Does this require a product or UX decision that is absent from SPEC.md, APPROACH.md, or ROADMAP.md?
+- Would two different developers reasonably implement this differently based only on the requirement text?
+
+### Quality Gate
+- If all items are **Resolved**: proceed to goal_backward_planning.
+- If any item is **Open** or **Ambiguous**: STOP. Report each item with the specific question that would resolve it. Do not produce an execution-ready plan until the user resolves these items.
+- Exception — **minor technical ambiguity** (e.g., exact error message wording, logging format) that does not change user-facing behavior: note it as a warning in the plan Notes section and proceed. Do not use this exception for behavioral or acceptance-criteria ambiguity.
+</spec_quality_check>
+
 <goal_backward_planning>
 Plan backward from success criteria.
 
@@ -96,6 +142,8 @@ phase: 01-foundation
 plan: 01
 type: execute
 wave: 1
+runtime: claude-code
+assurance: self_checked
 depends_on: []
 files-modified:
   - src/lib/auth.ts
@@ -196,6 +244,8 @@ phase: 01-foundation
 plan: 01
 type: execute
 wave: 1
+runtime: claude-code
+assurance: self_checked
 depends_on: []
 files-modified:
   - src/routes/users.ts
@@ -231,6 +281,16 @@ must_haves:
 1. [Observable truth from ROADMAP.md]
 2. [Observable truth from ROADMAP.md]
 
+<checks>
+<plan_check>
+checker: self | cross_runtime
+checker_runtime: claude-code
+status: passed | issues_found | skipped
+blocking: false
+notes: [What the checker actually validated or why it was skipped]
+</plan_check>
+</checks>
+
 ## Tasks
 
 <task id="01-01" type="auto">
@@ -250,6 +310,8 @@ must_haves:
 ## Notes
 [Gotchas, implementation notes, or explicit assumptions]
 ```
+
+**MANDATORY: You MUST write PLAN.md to disk at `.planning/phases/{phase_dir}/{plan_id}-PLAN.md`. Output to conversation alone is NOT sufficient. If this file is not written to disk, planning is NOT complete.**
 </plan_structure>
 
 <approach_exploration>
@@ -342,9 +404,7 @@ After the planner produces a draft plan, an independent checker reviews it in fr
 7. `context_compliance` - locked decisions are honored and deferred ideas stay out of scope
 8. `goal_achievement` - the plan, if executed perfectly, actually achieves the stated phase goal: goal addressed (tasks deliver the goal), success criteria reachable (each criterion traceable to a task verify output), and outcome observable (a human or automated check can confirm the goal was met)
 9. `approach_alignment` - when APPROACH.md exists, plans implement the chosen approaches, not alternatives. Blocker if plan contradicts an explicit user choice. Warning if plan drifts from recommendation without justification. Skipped when no APPROACH.md is provided.
-
 ### Invoking the Checker
-
 1. If `.planning/config.json` has `workflow.planCheck: false`, skip the independent checker. Perform the planner self-check below and report `reduced_assurance`.
 2. If plan checking is enabled, check if your runtime provides a `gsdd-plan-checker` agent.
 3. If a native checker agent is available, invoke it in a fresh context with only these explicit inputs:
@@ -375,9 +435,12 @@ After the planner produces a draft plan, an independent checker reviews it in fr
 6. If the checker returns `issues_found`, revise the existing plan files only where needed, then invoke the checker again.
 7. Maximum 3 checker cycles total. If blockers remain after cycle 3, stop and escalate to the user instead of pretending the plan is ready.
 8. If no native checker agent is available in your runtime, perform the planner self-check below and explicitly report `reduced_assurance` rather than claiming an independent checker ran.
-
+When the checker outcome is finalized, write the result into the plan artifact:
+- checker ran in same runtime or planner self-check only -> set frontmatter `assurance: self_checked`
+- checker ran in a different runtime/vendor and passed -> set frontmatter `assurance: cross_runtime_checked`
+- draft exists before any checker result is recorded -> keep `assurance: unreviewed`
+- record the structured outcome in the plan's `<checks>` block; do not leave the checker result only in chat context
 ### Orchestration Summary
-
 After plan checking completes, report:
 - target phase
 - whether independent plan checking ran
@@ -401,7 +464,6 @@ For every success criterion from `ROADMAP.md`:
 - [ ] At least one task produces an artifact that satisfies it
 - [ ] The task's `<verify>` section checks it specifically
 - [ ] The criterion is covered explicitly, not only implied
-
 ### Check Task Completeness
 For each task:
 - [ ] The `<files>` section lists every file to create or modify
@@ -430,6 +492,8 @@ Planning is done when all of these are true:
 - [ ] Success criteria from `ROADMAP.md` are represented as must-haves
 - [ ] Goal-backward derivation from criteria to artifacts to key links to tasks is explicit
 - [ ] Every plan has frontmatter with `phase`, `plan`, `type`, `wave`, `depends_on`, `files-modified`, `autonomous`, `requirements`, and `must_haves`
+- [ ] Every plan frontmatter records `runtime` and `assurance`
+- [ ] Every plan records checker outcome in a structured `<checks>` block
 - [ ] Every task has XML structure with `id`, `type`, `files`, `action`, `verify`, and `done`
 - [ ] Every task has at least one runnable verify command
 - [ ] Plan sizing stays within 2-5 tasks, preferring 2-3
@@ -442,12 +506,14 @@ Report to the user what was accomplished, then present the next step:
 
 ---
 **Completed:** Phase planning — created `.planning/phases/{phase_dir}/{plan_id}-PLAN.md`.
+**Planning stops here:** `gsdd-plan` ends after the plan artifact is written. Do not start implementation in this same run, and do not treat imperative handoff text as execution authorization.
+Installed generated runtime surfaces are trusted through rendering, not reviewer memory: `gsdd health` compares any local generated skill/adapter surfaces against current render output, and `gsdd update` regenerates them when they drift.
 
-**Next step:** `/gsdd:execute` — execute the plan
+**Next workflow:** `/gsdd-execute` — start execution in a separate run when the user explicitly wants implementation to begin
 
 Also available:
-- `/gsdd:plan` — create additional plans for the same phase (if multi-wave)
-- `/gsdd:progress` — check overall project status
+- `/gsdd-plan` — create additional plans for the same phase (if multi-wave)
+- `/gsdd-progress` — check overall project status
 
 Consider clearing context before starting the next workflow for best results.
 ---

package/distilled/workflows/progress.md

@@ -12,25 +12,44 @@ Scope boundary: you are NOT resume.md. You do not wait for user input, clean up
 This is a read-only workflow. No files are created, modified, or deleted. If `.planning/` does not exist, tell the user to run `gsdd init` and stop.
 </prerequisites>
 
+<lifecycle_boundary>
+`progress` stays read-only.
+
+- Derive lifecycle posture from repo truth only; do not mutate phase or milestone state from this workflow.
+- Do not call `gsdd phase-status` here.
+- If you recommend a next step that crosses a lifecycle boundary, the downstream mutating workflow must rerun its own `gsdd lifecycle-preflight ...` gate before acting.
+</lifecycle_boundary>
+
 <process>
 
 <check_existence>
 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`** — check for non-phase brownfield artifacts:
+   - if `.planning/codebase/` has substantive map documents, or `.planning/quick/` has LOG/task artifacts, treat this as a non-phase brownfield state. Go to Branch F.
+   - otherwise the 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.
+4. **Both exist** — proceed to derive status, including whether a retained `ROADMAP.md` already represents an archived milestone rather than an audit-ready one.
 </check_existence>
 
 <derive_status>
 Read the following and extract state:
 
 **Project identity:**
-Read `.planning/SPEC.md`. Extract the project name from the first heading.
+- If `.planning/SPEC.md` exists, read it and extract the project name from the first heading.
+- If `.planning/SPEC.md` does not exist, derive the project name from the repo root directory name.
+
+**Non-phase brownfield state:**
+If `.planning/ROADMAP.md` does not exist, determine whether the repo is currently in one of these Branch F states:
+- `between_milestones` — `.planning/SPEC.md` exists
+- `codebase_only` — `.planning/codebase/` has substantive map documents but `.planning/SPEC.md` does not exist
+- `quick_lane` — `.planning/quick/LOG.md` or quick task directories exist but `.planning/SPEC.md` and `.planning/ROADMAP.md` do not
+
+For `codebase_only` and `quick_lane`, there is no active phase count. Record the non-phase state instead of trying to infer current milestone progress.
 
 **Phase statuses:**
-Read `.planning/ROADMAP.md`. Parse phase statuses:
+If `.planning/ROADMAP.md` exists, read it and parse phase statuses:
 - `[ ]` = not started
 - `[-]` = in progress
 - `[x]` = done
@@ -41,16 +60,35 @@ Determine:
 - Current phase: first `[-]` phase, or first `[ ]` if none in progress
 - Current phase name
 
+**Archived milestone evidence:**
+If `ROADMAP.md` exists and all phases in the current milestone are `[x]`, determine whether this is still audit-ready or already archived-with-`ROADMAP.md`:
+- derive the current milestone/version from the active milestone heading in `ROADMAP.md`
+- check `.planning/MILESTONES.md` for a shipped entry matching that same milestone/version
+- check for the matching archived milestone audit artifact for that same milestone/version (for example `.planning/v1.1-MILESTONE-AUDIT.md`)
+- if both the shipped ledger entry and the matching archived audit artifact exist, treat the retained `ROADMAP.md` as archived milestone evidence and route to Branch F instead of Branch E
+- if either one is missing, keep the milestone in the audit-ready Branch E state
+
 **Checkpoint:**
 Check if `.planning/.continue-here.md` exists. If yes, note the `workflow` and `phase` frontmatter and the `next_action` section.
+- Treat checkpoint routing classes explicitly:
+  - `phase` and `quick` checkpoints remain blocking resume-owned surfaces for routing.
+  - `generic` checkpoints are informational-only for this read-only reporter: show the checkpoint and its `next_action`, but keep evaluating the real lifecycle recommendation instead of routing Branch A back through `/gsdd-resume`.
 
 **Incomplete work:**
-Scan `.planning/phases/` for:
+If `.planning/phases/` exists, scan it for:
 - PLAN files without a matching SUMMARY file (incomplete execution)
 - SUMMARY files without a matching VERIFICATION file (unverified, only relevant if `workflow.verifier` is enabled in `.planning/config.json`; if config.json cannot be read, assume verifier is disabled)
 
 **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>
@@ -73,12 +111,16 @@ Project: [name from SPEC.md]
 Phase: [current] of [total] — [phase name]
 Completed: [N] phases done
 
+[If no active roadmap and Branch F is handling a non-phase state:]
+State: [between milestones | codebase map only | quick lane only]
+Completed: no active roadmap
+
 Recent Work:
 - Phase [X]: [one-liner from SUMMARY.md]
 - 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 — `phase`/`quick` checkpoints still route through /gsdd-resume; `generic` checkpoints stay visible as informational context only
 
 [If PLAN without SUMMARY found:]
 Incomplete execution: Phase [N] has PLAN but no SUMMARY
@@ -89,8 +131,16 @@ Unverified: Phase [N] has SUMMARY but no VERIFICATION
 [If incomplete quick task found:]
 Incomplete quick task: [description]
 
-[If all phases [x]:]
+[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] and the current milestone is not yet archived:]
 All phases complete — ready for milestone audit
+
+[If all phases [x] and the current milestone is already archived-with-`ROADMAP.md`: ]
+All phases complete — archived milestone retained on disk; ready for the next milestone
 ```
 
 **Filled-in example** (fabricated but realistic):
@@ -107,8 +157,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.
@@ -118,21 +168,23 @@ No ASCII art, no progress bars. Keep it scannable.
 Evaluate in priority order. Present the single best next step as a suggestion with a formatted output block. Do not wait for user selection, do not present numbered menus, do not clean up files. This is purely informational.
 
 **Branch A: Resume checkpoint**
-Condition: `.continue-here.md` exists.
+Condition: `.continue-here.md` exists and its `workflow` is `phase` or `quick`.
 
 ```
 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)
 ```
 
+If `.continue-here.md` exists and its `workflow` is `generic`, do **not** route back through Branch A from this read-only reporter. Show the checkpoint in the status block, surface its `next_action`, and keep evaluating Branch B-F so the primary recommendation can advance toward the real next phase, verification, or milestone-close action.
+
 **Branch B: Execute (PLAN without SUMMARY in current phase)**
 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 +192,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,26 +201,50 @@ 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])**
-Condition: All phases in ROADMAP.md are marked `[x]`.
+**Branch E: Audit milestone (all phases [x], not yet archived)**
+Condition: All phases in the current milestone are marked `[x]`, and the current roadmap milestone/version does **not** yet have both a shipped entry in `.planning/MILESTONES.md` and the matching archived milestone audit artifact.
 
 ```
 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.
+**Branch F: Non-phase state (no active roadmap, or retained roadmap already archived)**
+Condition:
+- `.planning/SPEC.md` exists but `.planning/ROADMAP.md` does not, **or**
+- `.planning/codebase/` or `.planning/quick/` exists while both `.planning/SPEC.md` and `.planning/ROADMAP.md` are absent, **or**
+- `.planning/ROADMAP.md` still exists, but the current roadmap milestone/version already has both a shipped entry in `.planning/MILESTONES.md` and the matching archived milestone audit artifact — this is the archived-with-`ROADMAP.md` state, not a second trip through audit
+
+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.
+
+Suggested next action (codebase-only brownfield state):
+  Run /gsdd-quick if the bounded change is already concrete.
+  Also available: /gsdd-new-project (define broader lifecycle work), /gsdd-map-codebase (refresh or deepen the baseline)
+
+Suggested next action (quick-lane brownfield state with incomplete quick work):
+  Run /gsdd-quick to continue or finish the current bounded change.
+  Also available: /gsdd-new-project (switch to full lifecycle setup), /gsdd-progress (refresh after the quick task is updated)
+
+Suggested next action (quick-lane brownfield state with no incomplete quick work):
+  Run /gsdd-quick for the next bounded change.
+  Also available: /gsdd-new-project (if you now need SPEC.md + ROADMAP.md), /gsdd-map-codebase (if the repo baseline feels stale)
 ```
 
 If none of the above conditions match, report that the project is in a clean state with no obvious next action.
@@ -178,7 +254,8 @@ 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.
+- **Generic checkpoint + current phase work:** A `workflow: generic` checkpoint may coexist with an incomplete plan, unverified phase, or completed milestone. Keep the checkpoint visible in the status block, but let Branch B-F supply the primary recommendation instead of bouncing back to `/gsdd-resume`.
+- **All phases complete + checkpoint:** All phases `[x]` but a checkpoint exists. If the checkpoint is `phase` or `quick`, mention both and suggest `/gsdd-resume` before continuing. If the checkpoint is `generic`, keep it visible as informational context and still route the primary recommendation 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 +270,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

@@ -8,7 +8,7 @@ They reuse the same planner, executor, and verifier roles but skip research and
 <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 ask more than 2 approach clarification questions — if the bounded change is still undefined, recommend `/gsdd-new-project`; if the change is defined but 3+ grey areas remain, 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
@@ -37,6 +37,10 @@ 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 whichever of `.planning/codebase/ARCHITECTURE.md`, `.planning/codebase/STACK.md`, `.planning/codebase/CONVENTIONS.md`, and `.planning/codebase/CONCERNS.md` are present. Summarize key findings from available docs in <=500 words as `$CODEBASE_CONTEXT`, emphasizing: safest surfaces to touch, risky zones to avoid, must-know conventions/traps, and what must be re-verified after change. Note any missing docs in the summary.
+6. If `.planning/codebase/` does not exist, build a just-enough inline brownfield baseline instead of stopping. Read the repo root guidance that is cheap and stable (`README.md`, root manifest such as `package.json` / `pyproject.toml` / `Cargo.toml` when present, top-level app entrypoints, and any obviously relevant config or module files surfaced by `$DESCRIPTION`). Summarize the findings in <=500 words as `$CODEBASE_CONTEXT`, explicitly labeling it as a provisional baseline and calling out unknowns. Emphasize: likely implementation surface, likely dependency boundaries, conventions already visible, risky areas to avoid touching blindly, and what must be re-verified after the change. If the repo is still too unclear after this pass, keep that uncertainty explicit so Step 3.6 can recommend `/gsdd-map-codebase`.
+7. **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).
+8. 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`:
 
@@ -76,7 +80,7 @@ For each grey area, present 2-3 concrete options with a recommended default:
 
 - 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.
+- Maximum 2 questions. If the bounded change is still undefined after clarification, recommend `/gsdd-new-project`. If the change is defined but the task still has 3+ grey areas, it's not a quick task — recommend `/gsdd-plan`.
 
 ### Output
 
@@ -98,6 +102,7 @@ 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 brownfield codebase summary from codebase maps when they exist, otherwise the inline brownfield baseline from Step 2 — use for orientation and risk awareness, not as hard constraints)
 - Mode: quick (single plan, 1-3 tasks, no research phase)
 - Output path: `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-PLAN.md`
 
@@ -171,11 +176,13 @@ 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." |
+| 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." |
+| Orientation gap | No `.planning/codebase/` exists AND the inline brownfield baseline still cannot name a clear implementation surface, dependency boundary, or safe-to-touch module | "This repo still needs deeper orientation — consider `/gsdd-map-codebase` before changing code." |
+| Undefined bounded change | `$DESCRIPTION` still does not identify a concrete bug, feature, target surface, or observable outcome after clarification | "This does not yet describe a bounded change — use `/gsdd-new-project` to define the work first." |
 
-If any signal fires, set `$SCOPE_WARNING` to the first matching advisory text. Multiple signals concatenate.
+If any signals fire, concatenate the matching advisory text in the listed order as `$SCOPE_WARNING`. If the undefined bounded change signal fires, keep that advisory first so the routing recommendation stays explicit.
 If no signals fire, `$SCOPE_WARNING` is empty.
 
 This is advisory only — it does NOT block execution.
@@ -212,12 +219,16 @@ 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]`
+- If `$SCOPE_WARNING` contains `/gsdd-new-project`: `[Enter to proceed / switch to /gsdd-new-project / edit description / abort]`
+- Otherwise if `$SCOPE_WARNING` contains `/gsdd-map-codebase`: `[Enter to proceed / switch to /gsdd-map-codebase / edit description / abort]`
+- Otherwise 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}"
+- **"switch to /gsdd-new-project":** clean up the task directory, then stop quick workflow and report: "Use `/gsdd-new-project` to define the bounded work first. Task description: {$DESCRIPTION}"
+- **"switch to /gsdd-map-codebase":** clean up the task directory, then stop quick workflow and report: "Use `/gsdd-map-codebase` for a deeper brownfield baseline before quick work. Task description: {$DESCRIPTION}"
+- **"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.
 
 ---
@@ -334,12 +345,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.
 ---