gsdd-cli 0.16.1 → 0.18.0

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,9 +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 `.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.
+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`:
 
@@ -79,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
 
@@ -101,7 +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 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 +179,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 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 +219,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 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.
 

package/distilled/workflows/resume.md

@@ -16,6 +16,19 @@ 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:
+
+- `gsdd lifecycle-preflight resume`
+
+If the preflight result is `blocked`, STOP and report the blocker instead of inferring resume eligibility from workflow-local prose.
+
+Treat the preflight as an authorization seam over shared repo truth only:
+- it may authorize or reject resume
+- it does not mutate phase or milestone state
+- the owned write for this workflow remains checkpoint cleanup when the user actually resumes from `.continue-here.md`
+</lifecycle_preflight>
+
 <process>
 
 <detect_state>
@@ -187,7 +200,7 @@ Evaluate in priority order and present the primary recommendation:
 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
+- `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.
 

package/distilled/workflows/verify.md

@@ -20,6 +20,19 @@ Establish your verification basis (must-have sources, requirement scope, previou
 If a previous `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md` exists, read it first and treat this as re-verification.
 </load_context>
 
+<lifecycle_preflight>
+Before code inspection or report writing, run:
+
+- `gsdd lifecycle-preflight verify {phase_num} --expects-mutation phase-status`
+
+If the preflight result is `blocked`, STOP and report the blocker instead of inferring lifecycle eligibility from prompt-local prose.
+
+Treat the preflight as an authorization seam over shared repo truth only:
+- it may authorize or reject verification
+- it does not mutate `.planning/ROADMAP.md` by itself
+- owned writes remain the verification artifact plus any explicit `gsdd phase-status` transition that occurs later on `passed`
+</lifecycle_preflight>
+
 <runtime_contract>
 Verification uses the same `Runtime` and `Assurance` types as planning and execution.
 Infer runtime from the launching surface when obvious: `.claude/` -> `claude-code`, `.codex/` or Codex portable skill -> `codex-cli`, `.opencode/` -> `opencode`, otherwise `other`.
@@ -75,28 +88,41 @@ Also check for orphan requirements:
 Risk classification:
 For each truth, assess: does it involve a behavioral change, UX change, or user-visible outcome without a clear, relevant acceptance criterion?
 
-- If yes → mark it `risk: high`. This truth will require `runtime-check` or `user-confirmation` proof in the proof contract step below. Code-evidence alone is insufficient.
-- If no → `risk: normal`. Code-evidence or repo-test is sufficient.
+- If yes → mark it `risk: high`. This truth will require runtime-grade evidence in the evidence contract step below. `code` alone is insufficient.
+- If no → `risk: normal`. `code` is the floor, and `test` is preferred when the repo has a direct automated check.
 
 This is the verifier's own internal judgment — not a field imported from the plan. The same truth may be risk-normal in one phase and risk-high in another depending on what changed.
 </must_haves>
 
-<proof_contract>
-Before beginning artifact inspection, classify each must-have truth by its required proof type. This step separates "did the artifact pass levels 1–3?" from "did the outcome have the right kind of proof?"
-Proof types (from SPEC.md `VerificationEvidence`):
-- `repo-test` — a passing automated test in the repo directly exercises this outcome
-- `code-evidence` — source inspection confirms the implementation is present and wired
-- `runtime-check` — a live execution confirms the behavior (script, curl, manual run)
-- `user-confirmation` — a human observer confirmed the user-visible outcome
+<evidence_contract>
+Before beginning artifact inspection, classify the phase closure posture and apply the fixed evidence kinds. This step separates "did the artifact pass levels 1–3?" from "did the outcome have the right kind of evidence?"
+
+Stable evidence kinds:
+- `code` — source inspection confirms the implementation is present and wired
+- `test` — a passing automated check in the repo directly exercises the outcome
+- `runtime` — a live execution confirms the behavior (script, curl, manual run)
+- `delivery` — shipped or distributable proof exists (merged PR, packaged artifact, published doc/proof pack, release evidence)
+- `human` — a human observer confirmed a visual or judgment-based outcome
+
+Delivery posture:
+- `repo_only` — the phase outcome stays inside repo truth; no shipped runtime or external delivery claim is needed
+- `delivery_sensitive` — the phase claims a live behavior, shipped UX, install/release posture, or other externally consumed runtime outcome
+
+Apply the shared `verify` matrix:
 
-Assign required proof type per truth using the risk classification from `<must_haves>`:
-- `risk: high` truths (behavioral/UX changes, user-visible outcomes without acceptance criteria) → require `runtime-check` or `user-confirmation`. Code-evidence alone is **not sufficient**.
-- `risk: normal` truths (structural or content changes) → `code-evidence` is sufficient. `repo-test` is always valid regardless of risk level.
+| delivery_posture     | required evidence | recommended evidence       | cannot carry closure alone |
+| -------------------- | ----------------- | -------------------------- | -------------------------- |
+| `repo_only`          | `code`            | `test`                     | `human`, `delivery`        |
+| `delivery_sensitive` | `code`, `runtime` | `test`, `delivery`, `human` | `code`, `human`            |
 
-If the required proof type cannot be collected programmatically (e.g., runtime environment unavailable) → route that truth to `human_verification` in the report, not to `gaps`.
+Rules:
+- repo-only work must not invent `runtime` or `delivery` proof just to satisfy a template
+- delivery-sensitive closure must not pass on prose, `code`-only inspection, or `human` confirmation without the required `runtime` evidence
+- `human` evidence supports ambiguous or visual outcomes; it does not replace required `code` or `runtime` evidence
+- if a required evidence kind cannot be collected, record it in `missing_evidence`; route purely human-observable follow-up to `human_verification` only when the blocking runtime/delivery requirement is already satisfied
 
-Note: this step does NOT replace levels 1–3. An artifact can satisfy the proof-type requirement and still fail Level 2 (substantive) or Level 3 (wired). Both checks must run.
-</proof_contract>
+Note: this step does NOT replace levels 1–3. An artifact can satisfy the evidence-kind requirement and still fail Level 2 (substantive) or Level 3 (wired). Both checks must run.
+</evidence_contract>
 
 <verification_levels>
 Check every artifact at three levels. A common failure mode is a file that exists but is still a stub.
@@ -215,6 +241,12 @@ assurance: cross_runtime_checked
 verified: 2026-03-11T12:00:00Z
 status: gaps_found
 score: 2/3 must-haves verified
+delivery_posture: delivery_sensitive
+evidence_contract:
+  required_kinds: [code, runtime]
+  recommended_kinds: [test, delivery, human]
+  observed_kinds: [code]
+  missing_kinds: [runtime]
 re_verification:
   previous_status: gaps_found
   previous_score: 1/3
@@ -226,7 +258,9 @@ re_verification:
 gaps:
   - truth: "Users can create a user from the page"
     status: failed
-    proof_type: runtime-check # required proof type for this truth
+    required_evidence: [code, runtime]
+    observed_evidence: [code]
+    missing_evidence: [runtime]
     severity: blocker # blocker = required proof absent; warning = artifact missing but proof exists via other means
     reason: "Form submits, but route returns placeholder data"
     artifacts:
@@ -304,10 +338,11 @@ Status rules:
 
 Frontmatter guidance:
 - `phase`, `runtime`, `assurance`, `verified`, `status`, and `score` are the minimal report fields
+- `delivery_posture` plus `evidence_contract.required_kinds|recommended_kinds|observed_kinds|missing_kinds` must reflect the shared verify matrix actually used for this phase
 - when gaps or human checks exist, keep them machine-readable in frontmatter — do not collapse them into prose-only body text
 - keep `re_verification`, `gaps`, and `human_verification` structured when they materially help re-verification, gap closure, or explicit human handoff
 - keep `<git_delivery_check>` in frontmatter with the observed `branch`, `commits_ahead_of_main`, and `pr_state` values from the delivery checks above
-- use `severity: warning` in gaps when an artifact is missing but proof exists through other means; use `severity: blocker` only when the required proof type (`runtime-check`, `repo-test`, or `user-confirmation` where mandated) could not be satisfied by any available evidence
+- use `severity: warning` in gaps when an artifact is missing but required evidence still exists through other means; use `severity: blocker` only when one or more required evidence kinds in `missing_evidence` could not be satisfied
 - if verification runs in the same runtime/vendor as execution, cap frontmatter `assurance` at `self_checked`
 - if verification runs in a different runtime/vendor than execution, set frontmatter `assurance: cross_runtime_checked`
 </report_format>

package/docs/BROWNFIELD-PROOF.md

@@ -0,0 +1,95 @@
+# Brownfield Proof
+
+This is the strongest tracked public proof for Workspine's release-floor claim: a real brownfield-style consumer repo that used the shipped workflow contract, hit a real failure, and recovered through the same `plan -> execute -> verify` loop.
+
+## What this proves
+
+In a fresh consumer repo, Workspine produced:
+
+- durable planning artifacts
+- runnable workflow entry surfaces
+- a concrete phase plan
+- a real execution summary
+- a failed verification
+- a real fix
+- a successful re-verification
+
+That proves the repo-native delivery contract is not just conceptual.
+
+## Public proof pack
+
+Open the tracked proof pack:
+
+- [Consumer proof pack index](proof/consumer-node-cli/README.md)
+
+Key exported artifacts:
+
+- [brief.md](proof/consumer-node-cli/brief.md)
+- [SPEC.md](proof/consumer-node-cli/SPEC.md)
+- [ROADMAP.md](proof/consumer-node-cli/ROADMAP.md)
+- [01-01-PLAN.md](proof/consumer-node-cli/phases/01-foundation/01-01-PLAN.md)
+- [01-01-SUMMARY.md](proof/consumer-node-cli/phases/01-foundation/01-01-SUMMARY.md)
+- [01-VERIFICATION.md](proof/consumer-node-cli/phases/01-foundation/01-VERIFICATION.md)
+
+## The worked flow
+
+### 1. Initialize a fresh consumer repo
+
+The exported proof pack comes from a new non-framework project that used the shipped `gsdd init` flow.
+
+The generated surface included:
+
+- portable `.agents/skills/gsdd-*`
+- consumer `.planning/` state
+- a Codex-native checker adapter
+- a compact consumer `AGENTS.md`
+
+### 2. Plan real work
+
+The consumer brief required a named greeting:
+
+- `node index.js --name Ada` should print `Hello, Ada!`
+
+That requirement is preserved in the exported [brief](proof/consumer-node-cli/brief.md), [spec](proof/consumer-node-cli/SPEC.md), and [phase plan](proof/consumer-node-cli/phases/01-foundation/01-01-PLAN.md).
+
+### 3. Execute and hit a real miss
+
+The first implementation missed the named-greeting requirement:
+
+- `node index.js --name Ada` returned `Hello, world!`
+
+That miss is preserved in the exported [verification report](proof/consumer-node-cli/phases/01-foundation/01-VERIFICATION.md).
+
+### 4. Verify, fix, and re-verify
+
+The consumer repo then followed the same framework contract to:
+
+- identify the failed requirement
+- update the implementation and test path
+- re-run verification
+- close with a passing result
+
+The final passing behavior is:
+
+- `node index.js --name Ada` returns `Hello, Ada!`
+
+## Why this matters
+
+This proof is stronger than a polished README claim because it shows the exact behavior Workspine is trying to preserve:
+
+- plan from durable artifacts
+- execute against real repo state
+- let verification catch a real miss
+- recover without losing the thread
+
+That is the release-floor claim in practice.
+
+## What this does not prove
+
+This proof does not claim:
+
+- equal runtime ergonomics across every supported runtime
+- parity validation on Cursor, Copilot, or Gemini CLI
+- enterprise-hardening or orchestration-platform behavior
+
+Those are outside the current proof floor.

package/docs/RUNTIME-SUPPORT.md

@@ -0,0 +1,77 @@
+# Runtime Support Matrix
+
+Workspine is designed as a portable multi-runtime delivery framework, but the proof bar is not the same for every runtime today.
+
+This matrix is the release-floor truth surface.
+
+## Support tiers
+
+### Directly validated
+
+The workflow contract has direct repo proof for these runtimes:
+
+- **Claude Code**
+- **Codex CLI**
+- **OpenCode**
+
+These are the strongest public runtime claims.
+
+### Same core workflow
+
+These runtimes use the same portable workflow surfaces, but this release does not claim equal runtime proof or equal ergonomics:
+
+- **Cursor**
+- **GitHub Copilot**
+- **Gemini CLI**
+
+### Fallback / manual use
+
+Any tool that can read the generated markdown workflows can still use the framework manually, but that is outside the current native-proof story.
+
+## Current runtime surfaces
+
+| Runtime | Current claim | Entry surface | Notes |
+| --- | --- | --- | --- |
+| Claude Code | Directly validated | `.claude/skills/`, `.claude/commands/`, `.claude/agents/` | Native surface was a mandatory Phase 32 validation target; installed generated files are freshness-checked locally |
+| OpenCode | Directly validated | `.opencode/commands/`, `.opencode/agents/` | Native command and checker path; installed generated files are freshness-checked locally |
+| Codex CLI | Directly validated | `.agents/skills/gsdd-*` plus `.codex/agents/gsdd-plan-checker.toml` | Portable skill entry, native checker adapter, mandatory Phase 32 validation target |
+| Cursor | Same core workflow | `.agents/skills/gsdd-*` | Skills-native path; generated skill files are freshness-checked locally, but the runtime is not claimed as parity-validated |
+| GitHub Copilot | Same core workflow | `.agents/skills/gsdd-*` | Skills-native path; generated skill files are freshness-checked locally, but the runtime is not claimed as parity-validated |
+| Gemini CLI | Same core workflow | `.agents/skills/gsdd-*` | Skills-native path; governance is optional, generated skill files are freshness-checked locally, and parity is not claimed |
+
+## Generated-surface freshness
+
+The authored source contract stays in `distilled/workflows/*`. Generated runtime-facing files are trusted only through deterministic rendering:
+
+- `gsdd health` compares any installed generated surfaces under `.agents/skills/`, `.claude/`, `.opencode/`, and `.codex/` against current render output.
+- `gsdd update` regenerates drifted generated surfaces from the authored workflow and delegate sources.
+- Missing generated surfaces are not treated as drift unless the corresponding runtime surface is actually installed locally.
+
+## What stays portable
+
+The portable invariant for this release is the workflow contract:
+
+- planning
+- checking and revision loops
+- execution discipline
+- verification
+- handoff and durable repo artifacts
+
+## What does not stay equal yet
+
+This release does **not** claim that every runtime has:
+
+- the same native adapter richness
+- the same invocation ergonomics
+- the same validation depth
+- the same checker/orchestration mechanics
+
+Portable contract does not mean equal UX everywhere.
+
+## Proof references
+
+- `README.md`
+- `docs/BROWNFIELD-PROOF.md`
+- `docs/proof/consumer-node-cli/README.md`
+- `docs/VERIFICATION-DISCIPLINE.md`
+- `gsdd health` / `gsdd update`