gsdd-cli 0.16.1 → 0.18.1

package/distilled/workflows/progress.md

@@ -12,25 +12,62 @@ 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 `node .planning/bin/gsdd.mjs phase-status` here.
+- If you recommend a next step that crosses a lifecycle boundary, the downstream mutating workflow must rerun its own `node .planning/bin/gsdd.mjs 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.
-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.
+2. **If `.planning/brownfield-change/CHANGE.md` exists** — treat this as the active medium-scope brownfield continuity state. Go to Branch F.
+3. **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.
+4. **No `.planning/ROADMAP.md` BUT `.planning/SPEC.md` exists** — this is a between-milestones state (milestone was completed and archived). Go to Branch F.
+5. **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:
+- `active_brownfield_change` — `.planning/brownfield-change/CHANGE.md` exists; read `CHANGE.md` first as the canonical operational anchor, then read `HANDOFF.md` for judgment-only context
+- `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 `active_brownfield_change`, `codebase_only`, and `quick_lane`, there is no active phase count. Record the non-phase state instead of trying to infer current milestone progress.
+
+**Active brownfield change:**
+If `.planning/brownfield-change/CHANGE.md` exists, extract:
+- change title from the first heading
+- current posture from `## Current Status`
+- current branch / integration surface from `## Current Status`
+- next action from `## Next Action`
+- declared write scope from `## PR Slice Ownership` when present
+
+If `.planning/brownfield-change/HANDOFF.md` exists, read it as judgment-only context:
+- active constraints
+- unresolved uncertainty
+- decision posture
+- anti-regression
+
+Do not treat `HANDOFF.md` as a co-equal status source. It explains the active change; `CHANGE.md` remains the operational anchor.
 
 **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 +78,38 @@ Determine:
 - Current phase: first `[-]` phase, or first `[ ]` if none in progress
 - Current phase name
 
-**Checkpoint:**
-Check if `.planning/.continue-here.md` exists. If yes, note the `workflow` and `phase` frontmatter and the `next_action` section.
+**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 only when there is no active brownfield change, or when a shared strict-match rule proves they still describe the active execution surface.
+  - `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`.
+- If `.planning/brownfield-change/CHANGE.md` also exists, apply one shared strict-match rule before letting a surviving `phase` or `quick` checkpoint outrank the operational anchor:
+  - branch alignment: the checkpoint branch, `CHANGE.md` integration surface, and current git branch all match
+  - scope alignment: the live dirty tree stays inside the declared brownfield write scope
+  - still-active execution state: the checkpoint still points at live unfinished `phase` or `quick` work
+- If any one of those checks fails, keep the checkpoint visible in the status block but continue routing from the active brownfield change instead of bouncing 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.
+**Quick task log:**
+If `.planning/quick/LOG.md` exists, check the last entry for a non-terminal status.
+
+**Artifact-versus-worktree mismatch:**
+If an active brownfield change exists, compare `CHANGE.md` to live git/worktree truth:
+- branch mismatch between `CHANGE.md` and the current git branch is a warning
+- dirty files outside the declared brownfield write scope are a warning
+- `CHANGE.md` may stay the operational anchor, but conflicting worktree truth must not remain silent
 
 <unmerged_commits_check>
 Run `git log main..HEAD --oneline` to detect commits on the current branch that have not been merged to `main`.
@@ -81,12 +140,28 @@ 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: [active brownfield change | between milestones | codebase map only | quick lane only]
+Completed: no active roadmap
+
+[If an active brownfield change exists:]
+Active change: [title]
+Status: [current posture]
+Integration surface: [branch / integration surface from CHANGE.md]
+Next action: [next action from CHANGE.md]
+Judgment context: `HANDOFF.md` remains the decision-critical context surface, not a co-equal status authority
+Growth boundary: stay in the bounded lane unless the work now needs multiple active streams, milestone-owned lifecycle state, or broader requirement tracking
+
+[If the active brownfield artifact conflicts with git/worktree truth:]
+Brownfield continuity warning: the active change artifact and live integration surface disagree
+  Review `CHANGE.md`, `HANDOFF.md`, and the current worktree before resuming
+
 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
+[If .continue-here.md exists:]
+Checkpoint: paused work found — `phase`/`quick` checkpoints route through /gsdd-resume only when the strict-match rule still proves they are the active execution surface; `generic` checkpoints stay visible as informational context only
 
 [If PLAN without SUMMARY found:]
 Incomplete execution: Phase [N] has PLAN but no SUMMARY
@@ -102,8 +177,11 @@ 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]:]
+[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):
@@ -130,14 +208,17 @@ No ASCII art, no progress bars. Keep it scannable.
 <route_action>
 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.
-
-```
-Suggested next action:
-  Run /gsdd-resume to restore paused session context
-  Also available: /gsdd-execute (ignore checkpoint, continue current phase), /gsdd-progress (refresh)
-```
+**Branch A: Resume checkpoint**
+Condition: `.continue-here.md` exists, its `workflow` is `phase` or `quick`, and either no active brownfield change exists or the strict-match rule still proves that checkpoint is the active execution surface.
+
+```
+Suggested next action:
+  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.
+If an active brownfield change exists and a `phase` or `quick` checkpoint fails the strict-match rule, treat that checkpoint the same way: keep it visible in the status block, but keep evaluating Branch B-F so the active brownfield change remains the primary recommendation.
 
 **Branch B: Execute (PLAN without SUMMARY in current phase)**
 Condition: Current phase has a PLAN file but no matching SUMMARY.
@@ -166,8 +247,8 @@ Suggested next action:
   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:
@@ -175,22 +256,42 @@ Suggested next action:
   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/brownfield-change/CHANGE.md` exists, **or**
+- `.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 (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 (active brownfield change):
+  Run /gsdd-resume to restore the active brownfield change context from `.planning/brownfield-change/CHANGE.md`
+  Also available: inspect `.planning/brownfield-change/HANDOFF.md`, /gsdd-progress (refresh after the artifact or worktree changes), /gsdd-new-project (only if you intentionally want to widen this bounded change into the first milestone), /gsdd-new-milestone (only if the repo already has shipped milestone history and you intentionally want to widen this change into the next milestone cycle)
+
+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 (if you intentionally want to widen into full 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 (only if you intentionally want to widen this bounded change into 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 intentionally want to widen into 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.
@@ -199,8 +300,11 @@ If none of the above conditions match, report that the project is in a clean sta
 <edge_cases>
 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.
+- **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.
+- **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`.
+- **Active brownfield change + generic checkpoint:** Keep the generic checkpoint visible as informational context, but let the active brownfield change remain the continuity anchor and use Branch F for the primary recommendation.
+- **Active brownfield change + non-matching `phase`/`quick` checkpoint:** Show the checkpoint as surviving context, but let the active brownfield change stay primary unless branch alignment, scope alignment, and still-active execution state all match.
+- **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>

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
@@ -33,13 +33,15 @@ Store the response as `$DESCRIPTION`. If empty, re-prompt.
 
 ## Step 2: Initialize
 
-1. Read `.planning/config.json` for workflow toggles and git protocol.
-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.
+1. Read `.planning/config.json` for workflow toggles and git protocol.
+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/brownfield-change/CHANGE.md` exists, read it first as the current bounded brownfield continuity anchor. Capture the active goal, current posture, next action, and declared write scope as `$BROWNFIELD_CONTEXT`. If `.planning/brownfield-change/HANDOFF.md` exists, read it as supporting judgment context only. Do not let `/gsdd-new-project` become the default fallback when this active change already defines a concrete bounded lane.
+6. 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.
+7. 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`.
+8. **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 `node .planning/bin/gsdd.mjs file-op delete .planning/.continue-here.bak --missing ok` (auto-clean).
+9. 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`:
 
@@ -79,7 +81,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
 
@@ -101,7 +103,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 architecture and stack — use for orientation, not as constraints; empty if no codebase map exists)
+- 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`
 
@@ -178,8 +180,10 @@ Evaluate the plan against quick-scope boundaries. Read the plan file and check:
 | 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 `.planning/brownfield-change/CHANGE.md` already defines a concrete bounded lane, treat `/gsdd-new-project` as an intentional widen path rather than the default fallback." |
 
-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.
@@ -216,11 +220,15 @@ 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-new-project":** clean up the task directory, then stop quick workflow and report: "Use `/gsdd-new-project` to define or intentionally widen the work into full lifecycle planning. 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.
 

package/distilled/workflows/resume.md

@@ -16,14 +16,28 @@ Infer runtime from the launching surface when obvious: `.claude/` -> `claude-cod
 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:
+
+- `node .planning/bin/gsdd.mjs 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.
-3. **Both exist** — proceed to load state.
+1. **No `.planning/` directory** — route user to run `gsdd init`. Stop.
+2. **If `.planning/brownfield-change/CHANGE.md` exists** — this repo has an active medium-scope brownfield change. Proceed to load brownfield continuity state even if there is no active roadmap.
+3. **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.
+4. **Both exist** — proceed to load state.
 </detect_state>
 
 <load_artifacts>
@@ -41,10 +55,28 @@ Determine:
 - Next phase (first `[ ]` after current)
 - Completed phase count
 
-**SPEC.md:**
-Read `.planning/SPEC.md`. Extract:
-- Project name or description (first heading or "What This Is" section)
-- Current state summary if present
+**SPEC.md:**
+Read `.planning/SPEC.md`. Extract:
+- Project name or description (first heading or "What This Is" section)
+- Current state summary if present
+
+**Active brownfield change:**
+If `.planning/brownfield-change/CHANGE.md` exists, read it first as the canonical operational continuity anchor and extract:
+- change title from the first heading
+- current posture from `## Current Status`
+- current branch / integration surface from `## Current Status`
+- current owner / runtime from `## Current Status`
+- next action from `## Next Action`
+- declared write scope from `## PR Slice Ownership` when present
+
+If `.planning/brownfield-change/HANDOFF.md` exists, read it as judgment-only context:
+- active constraints
+- unresolved uncertainty
+- decision posture
+- anti-regression
+- next-action context
+
+Do not flatten `CHANGE.md` and `HANDOFF.md` into co-equal operational sources. `CHANGE.md` stays the live status/next-action anchor; `HANDOFF.md` explains why that posture exists.
 
 **Checkpoint file:**
 Check if `.planning/.continue-here.md` exists. If yes, read it and extract:
@@ -74,25 +106,38 @@ Collect the live integration-surface facts separately from checkpoint narrative
 </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
+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, quick-task logs, and the active brownfield change artifacts 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>
+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
+- `CHANGE.md` names a different branch / integration surface than the current git branch
+- dirty files fall outside the active brownfield write scope declared in `CHANGE.md`
+
+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
+
+If git/worktree truth materially disagrees with the active brownfield artifact:
+- keep `CHANGE.md` as the operational anchor
+- surface the mismatch explicitly
+- require acknowledgement before continuing the brownfield change from this workflow
+- keep ordinary git warnings separate from this stronger continuity gate
+- When a checkpoint also exists, let that checkpoint outrank the brownfield anchor only if a strict-match rule proves it is still the active execution surface:
+  - branch alignment: checkpoint branch, `CHANGE.md` integration surface, and current git branch all match
+  - scope alignment: the live dirty tree stays inside the declared brownfield write scope
+  - still-active execution state: the checkpoint still points at unfinished `phase` or `quick` work
+- If any one of those checks fails, keep the checkpoint visible but do not let it become the primary resume target.
+</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.
@@ -126,21 +171,45 @@ The output of this step is either:
 Present a compact status to the user:
 
 ```
-Project: [name from SPEC.md]
-Phase: [current] of [total] — [phase name]
-Completed: [N] phases done
-
-[If .continue-here.md exists:]
-[If stale checkpoint flag set:]
-⚠ Stale checkpoint detected
+Project: [name from SPEC.md]
+Phase: [current] of [total] — [phase name]
+Completed: [N] phases done
+
+[If an active brownfield change exists:]
+Active brownfield change: [title]
+  Status: [current posture]
+  Integration surface: [branch / integration surface from CHANGE.md]
+  Next action: [next action from CHANGE.md]
+  Judgment source: `HANDOFF.md` explains constraints/posture but does not override the operational state in `CHANGE.md`
+  Growth boundary: stay in the bounded lane unless the work now needs multiple active streams, milestone-owned lifecycle state, or broader requirement tracking
+
+[If `HANDOFF.md` exists for the active brownfield change:]
+  Brownfield judgment:
+    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 .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]
+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 an active brownfield change also exists and the checkpoint fails the strict-match rule:]
+Checkpoint note:
+  This checkpoint no longer cleanly matches the active brownfield execution surface.
+  Keep it reviewable, but do not treat it as the primary resume target unless the user explicitly chooses it.
 
 [If <judgment> was present in checkpoint:]
   Judgment context:
@@ -163,10 +232,15 @@ Git/worktree truth:
   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 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 material brownfield artifact/worktree mismatch flag set:]
+⚠ Brownfield continuity mismatch
+  `CHANGE.md` no longer cleanly matches the live branch/worktree truth.
+  Review `CHANGE.md`, `HANDOFF.md`, and the dirty tree before choosing the next action.
 
 [If incomplete phase execution found:]
 Incomplete execution: Phase [N] has a PLAN but no SUMMARY
@@ -183,18 +257,29 @@ Only show the staleness banner when `<validate_checkpoint>` produced a staleness
 <determine_action>
 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
-
-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.
+**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 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.
+If an active brownfield change also exists, apply the same strict-match rule before making a `phase` or `quick` checkpoint primary. A checkpoint only stays primary when branch alignment, scope alignment, and still-active execution state all hold at once. Otherwise, keep the checkpoint visible and user-selectable, but fall through to the active brownfield change as the default resume target.
+
+**Active brownfield change (`.planning/brownfield-change/CHANGE.md`):**
+If there is no checkpoint, or if the surviving checkpoint does not satisfy the strict-match rule against the active brownfield change:
+- present the `CHANGE.md` next action as the primary resume target
+- keep `HANDOFF.md` as supporting judgment context only
+- if artifact/worktree mismatch is material, require explicit acknowledgement before continuing
+- if the user does not want to continue immediately, let them review `CHANGE.md` or `HANDOFF.md` without deleting any checkpoint file
+- do not force this state back through `/gsdd-new-project` or milestone routing just because there is no active roadmap
+- keep `/gsdd-new-project` and `/gsdd-new-milestone` as explicit widen-only choices when the bounded change no longer fits one active stream or now needs milestone-owned lifecycle state
+- use `/gsdd-new-project` for first-milestone setup and `/gsdd-new-milestone` when the repo already has shipped milestone history
+
+**Incomplete plan execution (PLAN without SUMMARY):**
+Route to `/gsdd-execute` for that phase.
 
 **Phase needs planning (next `[ ]` phase, no PLAN file exists):**
 Route to `/gsdd-plan` for that phase.
@@ -212,24 +297,26 @@ Present a numbered list of actions based on the state analysis:
 ```
 What would you like to do?
 
-1. [Primary action from above] (recommended)
-2. [Secondary action if applicable]
-3. Review ROADMAP.md
-4. Something else
-```
-
-**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>
+1. [Primary action from above] (recommended)
+2. [Secondary action if applicable]
+3. Review ROADMAP.md
+4. Something else
+```
+
+When the primary action is an active brownfield change rather than a checkpoint or lifecycle workflow, replace option 3 with `Review CHANGE.md or HANDOFF.md` if there is no active roadmap to inspect.
+
+**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 or material brownfield artifact/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`:
-  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`.
+  1. Run `node .planning/bin/gsdd.mjs file-op copy .planning/.continue-here.md .planning/.continue-here.bak`.
+  2. After the copy succeeds, run `node .planning/bin/gsdd.mjs 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.
 
 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.