gsdd-cli 0.16.1 → 0.18.0

package/distilled/README.md

@@ -1,21 +1,27 @@
-# Northline
+# Workspine
 
-A repo-native workflow kernel for long-horizon AI software delivery.
+A repo-native delivery spine for planning, checking, execution, verification, and handoff of long-horizon AI-assisted work.
 
-Northline gives long-horizon AI-assisted software work a durable repo spine for planning, execution, verification, and handoff. The package and CLI remain `gsdd-cli` / `gsdd`.
+Workspine keeps planning, execution, verification, handoff, and progress state in the repo so work survives cold starts, runtime switches, and session loss. The retained package and CLI contracts remain `gsdd-cli` / `gsdd`.
 
 ## What This Is
 
-Northline is a small set of workflow sources plus a CLI (`gsdd`) that:
+Workspine is a small set of workflow sources plus a CLI (`gsdd`) that:
 - scaffolds a project planning workspace (`.planning/`)
 - generates portable workflow entrypoints as skills (`.agents/skills/gsdd-*/SKILL.md`)
 - optionally generates tool-specific adapters for runtimes that need extra native surfaces (root `AGENTS.md`, Claude skills + plan-command alias + native agents, OpenCode commands + native agents)
 
-It gives serious AI-assisted software work one durable repo workflow spine for planning, execution, verification, and handoff without pretending to be a hosted orchestration layer.
+It gives serious AI-assisted work one durable repo workflow spine for planning, checking, execution, verification, and handoff without pretending to be a hosted orchestration layer.
 
-Launch proof posture:
-- Directly validated in repo truth: Claude Code, Codex CLI, OpenCode
-- Qualified support only: Cursor, Copilot, Gemini CLI via the shared `.agents/skills/` surface plus optional governance
+Workspine is the product name. The package, CLI commands, workflow prefixes, and workspace directory remain `gsdd-cli`, `gsdd`, `gsdd-*`, and `.planning/` — these are retained technical contracts, not rename residue.
+
+Workspine began as a fork of Get Shit Done, whose long-horizon delivery spine proved the problem was real. Since the fork, upstream GSD has continued evolving into a broad multi-runtime framework. Workspine took a different path: a smaller repo-native delivery spine with fewer public workflow surfaces, generated runtime surfaces from a portable core, evidence-gated closure, and provenance-aware continuity.
+
+Launch proof posture:
+- Directly validated in repo truth: Claude Code, Codex CLI, OpenCode
+- Qualified support only: Cursor, Copilot, Gemini CLI support the same core workflow via the shared `.agents/skills/` surface plus optional governance; proof and ergonomics differ from the directly validated runtimes
+- Installed generated runtime surfaces are renderer-checked locally through `gsdd health`, with deterministic repair through `gsdd update`
+- Public proof entrypoints: `docs/BROWNFIELD-PROOF.md`, `docs/proof/consumer-node-cli/README.md`, `docs/RUNTIME-SUPPORT.md`, `docs/VERIFICATION-DISCIPLINE.md`
 
 ## Quick Start
 
@@ -63,32 +69,41 @@ gsdd init                  -> bootstrap (create .planning/, copy templates, gene
 /gsdd-progress             -> show status, route to next action
 ```
 
-## Current Status (updated 2026-04-10)
-
-| Workflow | Status | Notes |
-|----------|--------|-------|
-| `new-project.md` | [OK] Defined, source-audited | Covers greenfield + brownfield + milestone context |
-| `plan.md` | [OK] Defined, source-audited | Portable workflow defines the planner contract and supports independent plan checking through generated native adapters |
-| `execute.md` | [OK] Source-audited | Mandatory read enforcement, auth-gate routing, deviation-rule examples, and substantive summary quality gate |
-| `verify.md` | [OK] Source-audited | 5 gap closures against hardened verifier role contract: grouped-gap guidance, orphan detection, frontmatter enforcement, verification basis emphasis, requirements coverage chain |
-| `audit-milestone.md` | [OK] Defined, source-audited | Aggregates phase verification, cross-phase integration audit, auth protection checks, requirement reconciliation, and orphan detection into `MILESTONE-AUDIT.md` |
-| `complete-milestone.md` | [OK] Defined | Archives milestone, evolves SPEC.md, collapses ROADMAP.md — no gsd-tools.cjs dependency |
-| `new-milestone.md` | [OK] Defined | Brownfield milestone continuation: goals, SPEC.md requirements, ROADMAP.md phases |
-| `plan-milestone-gaps.md` | [OK] Defined (unvalidated) | Gap closure phases from MILESTONE-AUDIT.md results |
-| `quick.md` | [OK] | Quick-work lane for sub-hour tasks outside the phase cycle (D11) |
-| `pause.md` | [OK] Source-audited | Session checkpoint writer with conversational handoff (D12) |
-| `resume.md` | [OK] Source-audited | Session context restorer with priority-ordered routing (D12) |
-| `progress.md` | [OK] Source-audited | Read-only status reporter with 6 named route branches, recent work, between-milestones detection (D12) |
-| `map-codebase.md` | [OK] Defined, source-audited | Standalone codebase mapping/refresh |
-| `verify-work.md` | [OK] Defined | Conversational UAT validation with structured gap tracking |
+## Brownfield Entry Contract
+
+Use the same three-way routing everywhere:
+
+- `gsdd-new-project` is the full initializer for greenfield work, fuzzy brownfield scope, or milestone-shaped work. Users do not need to pre-run `map-codebase`; `new-project` does that internally when needed.
+- `gsdd-quick` is the bounded brownfield lane when the change is already concrete. It uses existing codebase maps when present and otherwise builds a just-enough inline baseline.
+- `gsdd-map-codebase` is the deeper orientation pass for unfamiliar or higher-risk repos before choosing between `quick` and `new-project`.
+
+## Workflow Surface (updated 2026-04-19)
+
+| Workflow | What ships |
+|----------|------------|
+| `new-project.md` | Greenfield + brownfield + milestone initialization |
+| `plan.md` | Portable planner contract with independent plan checking through generated native adapters |
+| `execute.md` | Mandatory reads, auth-gate routing, deviation rules, and substantive summary quality gate |
+| `verify.md` | Phase verification with orphan detection, frontmatter enforcement, and requirements coverage chain |
+| `audit-milestone.md` | Cross-phase integration audit, auth protection checks, requirement reconciliation, and orphan detection into `MILESTONE-AUDIT.md` |
+| `complete-milestone.md` | Milestone archive, spec evolution, and roadmap collapse |
+| `new-milestone.md` | Brownfield milestone continuation: goals, requirements, and roadmap phases |
+| `plan-milestone-gaps.md` | Gap-closure phases from `MILESTONE-AUDIT.md` results |
+| `quick.md` | Quick-work lane for sub-hour tasks outside the phase cycle |
+| `pause.md` | Session checkpoint writer with conversational handoff |
+| `resume.md` | Session context restorer with priority-ordered routing |
+| `progress.md` | Read-only status reporter with recent work, archived-milestone detection, and non-phase brownfield routing |
+| `map-codebase.md` | Standalone codebase mapping/refresh and deeper brownfield orientation |
+| `verify-work.md` | Conversational UAT validation with structured gap tracking |
 
 Architecture notes:
 - `bin/gsdd.mjs` remains the thin generator entrypoint, while vendor-specific rendering lives in adapter modules.
 - Codex CLI uses the always-generated `.agents/skills/gsdd-*` surface as its entry path and can add a native `.codex/agents/gsdd-plan-checker.toml` checker agent.
+- `gsdd health` now compares any installed generated runtime surfaces against current render output and routes repairs back through `gsdd update`.
 - Portable lifecycle contracts now align to the roadmap template status grammar: `[ ]`, `[-]`, `[x]`.
 - Phase verification and milestone integration audit are treated as separate concerns.
 - Canonical role contracts use bounded sections, typed output examples, and checklist-driven completion where those structures materially improve downstream reliability.
-- Public launch wording is conservative by design: direct proof is claimed only for runtimes with recorded lifecycle evidence in `.planning/research/09-RESEARCH.md`.
+- Public launch wording is conservative by design: direct proof is claimed only for runtimes with recorded lifecycle evidence in the repo.
 
 ## Init Workflow Agent Count (by config)
 
@@ -149,7 +164,7 @@ Note: `parallelization: false` keeps the same mapper/researcher set but runs the
 
 ```
 distilled/
-  DESIGN.md                # design decisions and rationale (39 decisions, evidence-backed)
+  DESIGN.md                # design decisions and rationale (52 decisions, evidence-backed)
   EVIDENCE-INDEX.md        # source-to-decision index for durable research-backed claims
   SKILL.md                 # primary entry point (plain markdown)
   workflows/
@@ -178,6 +193,7 @@ distilled/
       mapper-quality.md
       mapper-concerns.md
       plan-checker.md
+      approach-explorer.md
       researcher-stack.md
       researcher-features.md
       researcher-architecture.md

package/distilled/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: GSDD (Spec-Driven Development)
-description: Disciplined, lightweight workflow for AI-assisted development. Spec first, then build, then verify.
+name: Workspine (published as gsdd-cli)
+description: Disciplined repo-native workflow for AI-assisted development. Spec first, then build, then verify.
 ---
 
 <role>
-You are an AI agent following the GSDD workflow. You are a disciplined engineer, not a code generator.
+You are an AI agent following the Workspine workflow. You are a disciplined engineer, not a code generator.
 Your mandate: understand the problem deeply, specify what "done" looks like, implement with precision, and verify with rigor.
 </role>
 
@@ -45,7 +45,7 @@ Mandatory:
 </governance>
 
 <project_structure>
-GSDD uses `.planning/` as the durable workspace:
+Workspine uses `.planning/` as the durable workspace:
 
 ```
 .planning/

package/distilled/templates/agents.block.md

@@ -7,7 +7,7 @@ Lifecycle: `new-project -> plan -> execute -> verify -> audit-milestone`.
 Core skills: `gsdd-new-project`, `gsdd-plan`, `gsdd-execute`, `gsdd-verify`, `gsdd-progress`.
 Planning state: `.planning/`. Portable workflows: `.agents/skills/gsdd-*/SKILL.md`.
 
-Invoke: `/gsdd-plan` (Claude, OpenCode, Cursor, Copilot, Gemini) · `$gsdd-plan` (Codex) · open SKILL.md directly elsewhere.
+Invoke: `/gsdd-plan` (Claude, OpenCode, Cursor, Copilot, Gemini) · `$gsdd-plan` (Codex, plan-only until `$gsdd-execute`) · open SKILL.md directly elsewhere.
 
 Rules:
 1. Read before writing roadmap work: `.planning/SPEC.md`, `.planning/ROADMAP.md`, `.planning/config.json`, and the relevant phase plan when one exists.

package/distilled/workflows/audit-milestone.md

@@ -13,6 +13,45 @@ Before starting, read these files:
 5. `.planning/AUTH_MATRIX.md` (if it exists) — authorization matrix for matrix-driven auth verification
 </load_context>
 
+<lifecycle_preflight>
+Before determining milestone scope or spawning the integration checker, run:
+
+- `gsdd lifecycle-preflight audit-milestone`
+
+If the preflight result is `blocked`, STOP and report the blocker instead of inferring milestone eligibility from workflow-local prose.
+
+Treat the preflight as an authorization seam over shared repo truth only:
+- it may authorize or reject milestone audit
+- it does not archive or mutate milestone state
+- the owned write for this workflow remains `.planning/v{version}-MILESTONE-AUDIT.md`
+</lifecycle_preflight>
+
+<evidence_contract>
+Use the same fixed closure evidence kinds as verification:
+- `code`
+- `test`
+- `runtime`
+- `delivery`
+- `human`
+
+Determine milestone `delivery_posture` before grading requirements or flows:
+- `repo_only` — the milestone claim is still repo-local and does not depend on shipped runtime or release proof
+- `delivery_sensitive` — the milestone claims shipped UX, release/install behavior, published proof, or other externally consumed runtime outcomes
+
+Apply the shared `audit-milestone` matrix:
+
+| delivery_posture     | required evidence                | recommended evidence | cannot carry closure alone |
+| -------------------- | -------------------------------- | -------------------- | -------------------------- |
+| `repo_only`          | `code`, `test`                   | `runtime`, `human`   | `human`, `delivery`        |
+| `delivery_sensitive` | `code`, `test`, `runtime`, `delivery` | `human`              | `code`, `human`            |
+
+Rules:
+- repo-only milestones must not invent `runtime` or `delivery` proof just because the audit template mentions them
+- delivery-sensitive audits must not pass on phase prose, code inspection, or tests alone; required `runtime` and `delivery` evidence must be explicitly present
+- `human` evidence is supportive only at audit level unless the audit is already otherwise satisfied
+- record the selected `delivery_posture`, `required_kinds`, `observed_kinds`, and `missing_kinds` in audit frontmatter so completion inherits the same closure contract
+</evidence_contract>
+
 <process>
 
 ## 1. Determine Milestone Scope
@@ -70,6 +109,7 @@ Either way, the integration check happens. The quality level is documented.
 Combine:
 - Phase-level gaps and tech debt (from step 2)
 - Integration checker's report (wiring gaps, auth gaps, broken flows, requirements integration map)
+- Evidence observations by kind (`code`, `test`, `runtime`, `delivery`, `human`) from phase verifications, summaries, integration findings, and delivery metadata
 
 ## 5. 3-Source Cross-Reference
 
@@ -125,6 +165,11 @@ milestone: v{version}
 audited: {ISO-8601 timestamp}
 status: passed | gaps_found | tech_debt
 reduced_assurance: false
+delivery_posture: repo_only | delivery_sensitive
+evidence_contract:
+  required_kinds: [code, test]
+  observed_kinds: [code, test]
+  missing_kinds: []
 scores:
   requirements: N/M
   phases: N/M
@@ -160,6 +205,11 @@ Plus full markdown report body with tables for requirements, phases, integration
 - `gaps_found` - critical blockers exist (unsatisfied requirements, unprotected sensitive flows, broken flows, or missing verifications)
 - `tech_debt` - no blockers but accumulated deferred items need review
 
+Evidence gate:
+- a `passed` audit must have no `missing_kinds` for the selected `delivery_posture`
+- `delivery_sensitive` audits cannot pass without explicit `runtime` and `delivery` evidence
+- `repo_only` audits cannot be downgraded merely because `runtime` or `delivery` evidence was never relevant
+
 **MANDATORY: The milestone audit report must exist at `.planning/v{version}-MILESTONE-AUDIT.md` on disk before presenting results. If the file was not written, STOP and report the write failure. Do NOT present audit results from conversation context alone — this is the highest-cost artifact to regenerate. Do NOT downgrade a write failure into "results shown inline anyway."**
 
 ## 7. Present Results

package/distilled/workflows/complete-milestone.md

@@ -25,6 +25,41 @@ Before starting, read these files:
 6. Most recent `.planning/v*-MILESTONE-AUDIT.md` — audit status (passed / gaps_found)
 </load_context>
 
+<lifecycle_preflight>
+Before verifying readiness or gathering archive stats, run:
+
+- `gsdd lifecycle-preflight complete-milestone`
+
+If the preflight result is `blocked`, STOP and report the blocker instead of inferring milestone-close eligibility from workflow-local prose.
+
+Treat the preflight as an authorization seam over shared repo truth only:
+- it may authorize or reject milestone completion
+- it does not mutate lifecycle state by itself
+- owned writes remain the archive artifacts, `MILESTONES.md`, `.planning/SPEC.md`, and the retained `ROADMAP.md` collapse
+</lifecycle_preflight>
+
+<evidence_contract>
+Milestone completion inherits the closure posture proven by the passed milestone audit.
+
+Stable evidence kinds carried forward from audit:
+- `code`
+- `test`
+- `runtime`
+- `delivery`
+- `human`
+
+Read the audit frontmatter and preserve:
+- `delivery_posture`
+- `evidence_contract.required_kinds`
+- `evidence_contract.observed_kinds`
+- `evidence_contract.missing_kinds`
+
+Shared closure rules:
+- `repo_only` completion may proceed with repo-local closure evidence only; do not invent `runtime` or `delivery` proof
+- `delivery_sensitive` completion must not proceed on code/prose-only evidence; the audit must already show required `code`, `test`, `runtime`, and `delivery` evidence with no missing required kinds
+- if the audit omits the evidence contract or still has missing required kinds, STOP and route back to `/gsdd-audit-milestone` or `/gsdd-plan-milestone-gaps` instead of silently closing the milestone
+</evidence_contract>
+
 <process>
 
 ## 1. Verify Readiness
@@ -32,10 +67,11 @@ Before starting, read these files:
 Check:
 - **Phase completion**: Are all ROADMAP.md phases for this milestone marked `[x]`? List any that are not.
 - **Audit status**: Does a MILESTONE-AUDIT.md exist and have status `passed`? If it has status `gaps_found`, the milestone has open gaps.
+- **Audit evidence posture**: Does the passed audit frontmatter include `delivery_posture` and an `evidence_contract` block with no missing required kinds?
 - **Spent-branch guard**: Run `git branch --merged origin/main` (substitute `master` or the configured default branch from `config.json → gitProtocol.branch` if different) and verify HEAD is not a spent/already-merged branch. If the current branch already backs a merged PR, STOP - do not instruct any commit or tag operations. Prompt the user to check out a fresh active branch before continuing.
 - **Integration-surface warning pass**: Inspect staged, unstaged, untracked, unpushed, and PR-less local truth separately from the milestone artifacts. Warn if the archive is being attempted from a mixed-scope or stale branch even when the milestone documents themselves look complete.
 
-**If phases incomplete or audit not passed:**
+**If phases incomplete, audit not passed, or the audit evidence contract is missing/insufficient:**
 
 Present options:
 1. **Proceed anyway** — archive with known gaps noted in MILESTONES.md
@@ -47,7 +83,7 @@ Present options:
 
 Exception: if `config.json -> mode` is `yolo`, skip the stop gate and proceed with a note about any gaps.
 
-**If all phases complete and audit passed:** Proceed.
+**If all phases complete, audit passed, and the audit evidence contract is satisfied:** Proceed.
 
 ## 2. Determine Version
 

package/distilled/workflows/execute.md

@@ -17,6 +17,19 @@ CRITICAL: Read every file below before performing any other actions. This is you
 7. **Session-boundary fallback:** If no prior completed phase SUMMARY.md with a `<judgment>` section was found in step 6, check whether `.planning/.continue-here.bak` exists. If it does, read its `<judgment>` section. Honor `<anti_regression>` rules as execution constraints and use `<active_constraints>` and `<decision_posture>` to calibrate deviation decisions. After reading, run `gsdd file-op delete .planning/.continue-here.bak --missing ok` (auto-clean).
 </load_context>
 
+<lifecycle_preflight>
+Before implementing or mutating any lifecycle artifact, run:
+
+- `gsdd lifecycle-preflight execute {phase_num} --expects-mutation phase-status`
+
+If the preflight result is `blocked`, STOP and surface the blocker instead of inferring eligibility from workflow-local prose.
+
+Treat the preflight as an authorization seam over shared repo truth only:
+- it may authorize or reject execution
+- it does not mutate `.planning/ROADMAP.md` by itself
+- owned writes remain execution artifacts, and ROADMAP mutation stays explicit in `<state_updates>` via `gsdd phase-status`
+</lifecycle_preflight>
+
 <runtime_contract>
 Execution uses the same `Runtime` and `Assurance` types as planning and verification.
 Infer runtime from the launching surface when obvious: `.claude/` -> `claude-code`, `.codex/` or Codex portable skill -> `codex-cli`, `.opencode/` -> `opencode`, otherwise `other`.

package/distilled/workflows/map-codebase.md

@@ -1,5 +1,5 @@
 <role>
-You are a Codebase Mapper Orchestrator. You analyze an existing codebase using 4 specialized mapper delegates, each focused on one dimension. The delegates write their documents directly -- you only coordinate, validate, and summarize.
+You are a Codebase Mapper Orchestrator. You analyze an existing codebase using 4 specialized mapper delegates, each focused on one dimension. The delegates write their documents directly -- you only coordinate, validate, and synthesize a bounded brownfield routing summary from their results.
 
 Output: `.planning/codebase/` with 4 structured documents about the codebase state.
 </role>
@@ -9,11 +9,13 @@ Use this workflow when:
 - Starting work on a brownfield (existing) codebase for the first time
 - Codebase maps are missing or stale (major refactors, dependency upgrades, new modules)
 - Explicitly requested as a standalone re-mapping
+- You want a deeper brownfield orientation pass before choosing between bounded `quick` work and full `new-project` setup
 
 Do NOT use when:
 - Greenfield project with no existing code
 - Maps already exist and are fresh (use Skip)
 - You are in the middle of a plan/execute/verify cycle (use existing maps)
+- You only need a small bounded brownfield change and the repo is already familiar enough for `quick` to build an inline baseline safely
 </when_to_use>
 
 <load_context>
@@ -146,6 +148,7 @@ These 4 documents are consumed by downstream GSDD workflows:
 | `plan` (future) | ARCHITECTURE + CONVENTIONS for implementation planning |
 | `execute` (future) | CONVENTIONS for code style, ARCHITECTURE for file placement |
 | `verify` (future) | CONCERNS for regression awareness |
+| `/gsdd-quick` | All 4 -- bounded brownfield context for safe feature work |
 
 **What this means for mapper output quality:**
 
@@ -230,9 +233,17 @@ Report to the user what was accomplished, then present the next step:
 ---
 **Completed:** Codebase mapping — 4 documents written to `.planning/codebase/` (STACK.md, ARCHITECTURE.md, CONVENTIONS.md, CONCERNS.md).
 
+**Brownfield routing summary:** Synthesize this directly from the 4 generated documents before recommending the next workflow.
+- Safest next change lane — which module or surface looks cheapest and safest to modify first
+- Highest-risk zones — areas to avoid or isolate unless the task explicitly needs them
+- Must-know traps — convention, dependency, or architecture constraints likely to cause mistakes
+- Recommended next workflow — choose `/gsdd-quick` for bounded brownfield work or `/gsdd-new-project` for full lifecycle setup, and say why
+
+Use only the 4 generated documents for this synthesis. Do NOT create a fifth persistent artifact or write an additional routing-summary file.
+
 **Next step:** Choose based on what you need:
-- `/gsdd-new-project` — full project initialization (spec, roadmap, phased delivery)
-- `/gsdd-quick` — brownfield feature work without full ceremony (bug fixes, small features, one-off tasks)
+- `/gsdd-new-project` — full project initialization (spec, roadmap, phased delivery), especially if you have not yet defined the bounded change
+- `/gsdd-quick` — bounded brownfield feature work without full ceremony (bug fixes, small features, one-off tasks)
 
 Also available:
 - `/gsdd-map-codebase` — re-map if results need refinement

package/distilled/workflows/new-milestone.md

@@ -23,6 +23,19 @@ Before starting, read these files:
 4. `.planning/config.json` — `workflow.research`, `researchDepth`, `gitProtocol`
 </load_context>
 
+<lifecycle_preflight>
+Before presenting the last milestone or gathering new milestone goals, run:
+
+- `gsdd lifecycle-preflight new-milestone`
+
+If the preflight result is `blocked`, STOP and report the blocker instead of inferring milestone-start eligibility from workflow-local prose.
+
+Treat the preflight as an authorization seam over shared repo truth only:
+- it may authorize or reject new milestone creation
+- it does not mutate milestone or roadmap state by itself
+- owned writes remain the new milestone requirements, roadmap entries, and phase-directory scaffolding
+</lifecycle_preflight>
+
 <integration_surface_check>
 Before mutating milestone truth, inspect the current branch/worktree as a separate provenance surface:
 - current branch

package/distilled/workflows/new-project.md

@@ -83,6 +83,8 @@ Check whether `.planning/codebase/STACK.md`, `.planning/codebase/ARCHITECTURE.md
 
 Inform the user: "No codebase maps found. Running codebase mapping before continuing."
 
+This is an internal prerequisite of `new-project`, not a user-facing routing requirement. If the user started with `/gsdd-new-project` on a brownfield repo, do not bounce them out and tell them to restart with `/gsdd-map-codebase`. Run the mapping dependency, then continue this workflow.
+
 Read and follow `.agents/skills/gsdd-map-codebase/SKILL.md` now. Execute its full flow (check existing, spawn mappers, validate, secrets scan). When map-codebase completes, return here and continue from Brownfield Validated Requirements Inference below.
 
 ### Brownfield Validated Requirements Inference
@@ -415,7 +417,7 @@ Report to the user what was accomplished, then present the next step:
 
 Also available:
 - `/gsdd-progress` — check overall project status
-- `/gsdd-map-codebase` — map existing codebase (if not already done)
+- `/gsdd-map-codebase` — deeper brownfield baseline or refresh (optional; `new-project` already runs it when needed)
 
 Consider clearing context before starting the next workflow for best results.
 ---

package/distilled/workflows/plan.md

@@ -506,8 +506,10 @@ 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)

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,11 +60,22 @@ 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)
 
@@ -81,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
@@ -102,8 +136,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):
@@ -131,7 +168,7 @@ 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:
@@ -139,6 +176,8 @@ Suggested next action:
   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.
 
@@ -166,8 +205,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,8 +214,11 @@ 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/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
@@ -191,6 +233,18 @@ Suggested next action (incomplete milestone state — SPEC.md exists but no mile
   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.
@@ -200,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>