gsdd-cli 0.16.1 → 0.18.0

package/README.md

@@ -1,10 +1,8 @@
 <div align="center">
 
-# Northline
+# Workspine
 
-**A repo-native workflow kernel for long-horizon AI software delivery.**
-
-Northline gives long-horizon AI-assisted software work one repo-native planning, execution, verification, and handoff spine so progress survives runtime switching and session loss. The package and CLI remain `gsdd-cli` / `gsdd`.
+**AI development that stays consistent across agents and sessions.** Plans are checked, work is verified, and progress is tracked in the repo.
 
 [![npm version](https://img.shields.io/npm/v/gsdd-cli?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/gsdd-cli)
 [![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
@@ -13,32 +11,74 @@ Northline gives long-horizon AI-assisted software work one repo-native planning,
 npx gsdd-cli init
 ```
 
-**Directly validated today:** Claude Code, Codex CLI, and OpenCode.  
-**Qualified support:** Cursor, Copilot, and Gemini CLI use the same portable skill surfaces, but this launch does not present them as parity-validated runtimes.
+**Directly validated today:** Claude Code, Codex CLI, and OpenCode.
+**Qualified support:** Cursor, Copilot, and Gemini CLI support the same core workflow through the shared `.agents/skills/` surface; this release does not claim the same runtime proof or ergonomics.
 
 </div>
 
+One repo-native spine for planning, checking, execution, verification, and handoff — so AI-assisted work survives cold starts, runtime switches, and session loss.
+
 ---
 
 ## What This Is
 
-Northline gives serious AI-assisted software work one repo-native planning, execution, verification, and handoff spine so progress survives long horizons, runtime switching, and session loss without turning into a dashboard or orchestration control plane.
+Workspine is a repo-native delivery spine for long-horizon AI-assisted software work. It keeps planning, execution, verification, handoff, and progress state in the repo so work survives cold starts, runtime switches, and session loss.
+
+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.
+
+### Lineage
+
+Workspine began as a fork of [Get Shit Done](https://github.com/gsd-build/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 — as of April 2026, GSD v1 documents 81 commands and 78 workflows across 33 agents. Workspine took a different path: 14 public workflow surfaces, generated runtime adapters from a portable core, evidence-gated closure, and provenance-aware continuity. The trade-off is deliberate: a narrower surface with stricter closure and fewer moving parts for the human operator.
+
+---
+
+## What's Different
+
+### Context survives cold starts, tool switches, and session loss
+
+Planning, phase artifacts, verification reports, and handoff checkpoints live in `.planning/`. When you switch runtimes or come back after a week, the repo still knows what was planned, what was executed, what was verified, and where you stopped.
+
+<details>
+<summary>How it works</summary>
+
+Three-layer continuity model: durable project truth (SPEC, ROADMAP, design decisions), live workflow state (phase plans, summaries, checkpoints), and compressed judgment (active constraints, anti-regression rules). Pause/resume workflows write and read these layers explicitly. No session memory required.
+
+</details>
+
+### Done means verified, not merely generated
+
+Verification is a separate workflow with a separate context window, not a checkbox at the end of execution. It checks three levels — do the files exist, is the code substantive (not stubs), and is it actually wired into the system — plus an anti-pattern scan.
+
+<details>
+<summary>How it works</summary>
+
+`gsdd-verify` runs after execution and produces a typed verification report. `gsdd-audit-milestone` checks cross-phase integration, requirement coverage, and end-to-end flows. Evidence-gated closure prevents marking work done without the right evidence kinds (code, test, runtime, delivery, human).
 
-The current package and CLI stay `gsdd-cli` and `gsdd`. Northline is the public product brand layered on top of that stable install surface.
+</details>
 
-It preserves the high-leverage parts of long-horizon AI-assisted development:
+### Rules that must be consistent are enforced by code, not by memory
 
-- **Persistent artifacts** — SPEC.md, ROADMAP.md, and config.json as the durable workspace
-- **Codebase mapping** — 4 parallel mappers produce STACK, ARCHITECTURE, CONVENTIONS, CONCERNS
-- **Scoped planning** — research, backward planning, fresh-context adversarial plan checking
-- **Execution** — wave-based parallel execution with fresh context per plan
-- **Verification** — Exists/Substantive/Wired gate, anti-pattern scan
-- **Milestone audit** — cross-phase integration, requirements coverage, E2E flows
-- **Session management** — pause work with checkpoint, resume with context restoration and routing
+1,381 tests across 13 test files guard properties that PRs repeatedly broke: delegate-role reference integrity, workflow vendor-API cleanliness, artifact schema consistency, plan-checker dimension coverage, and cross-document drift.
 
-What it strips: GSD's broader operator surface (32 workflows, 11 agents, discovery modes, sprint ceremony, a settings flow, and additional operator ergonomics). Northline keeps 14 workflows and 10 roles.
+<details>
+<summary>How it works</summary>
 
-**Target user:** Developer or small team that wants a repo-native, spec-driven workflow kernel with durable proof and handoff, not a dashboard or orchestration control plane.
+Invariant suites (I-series), guard suites (G-series), and scenario suites (S-series) run on every change. Each assertion includes a `FIX:` instruction so failures are actionable. 52 documented design decisions in `distilled/DESIGN.md` record the rationale with evidence trails.
+
+</details>
+
+### Smaller surface, stricter closure
+
+14 workflows. 10 roles. One CLI. Lifecycle progression goes through deterministic preflight gates — not conversational inference. Plans are checked by a separate agent in a separate context before execution begins. Closure requires evidence, not just file existence.
+
+<details>
+<summary>How it works</summary>
+
+`gsdd-plan` is terminal: it writes planning artifacts and stops. Execution requires an explicit `gsdd-execute` transition. `lifecycle-preflight` evaluates eligibility from repo artifacts before allowing state changes. `phase-status` is the only explicit ROADMAP mutator. `progress` is read-only.
+
+</details>
+
+**Target user:** Developer or small team that wants one durable delivery spine across coding runtimes, with explicit checks and repo-native proof instead of a dashboard or orchestration control plane.
 
 ---
 
@@ -63,27 +103,44 @@ In a terminal, `gsdd init` now opens a guided install wizard:
 - Step 3: configure planning defaults in the same guided flow
 
 Portable `.agents/skills/gsdd-*` skills are always generated. The wizard controls extra native adapters and optional governance, not the portable baseline.
+When those generated surfaces exist locally, `gsdd health` checks them against current render output instead of asking you to trust manual review.
 
 ### Launch Proof Status
 
-- **Directly validated in this repo:** Claude Code, Codex CLI, and OpenCode have recorded `plan -> execute -> verify` evidence for the core lifecycle.
-- **Qualified support:** Cursor, Copilot, and Gemini CLI use the shared `.agents/skills/` surface plus optional governance, but this launch does not describe them as equally proven native runtimes.
+- **Directly validated:** Claude Code, Codex CLI, and OpenCode have recorded `plan -> execute -> verify` evidence for the core lifecycle.
+- **Qualified support:** Cursor, Copilot, and Gemini CLI support the same core workflow through the shared `.agents/skills/` surface; this release does not claim the same runtime proof or ergonomics.
+- **Runtime-surface freshness:** Installed generated skills and native adapters are renderer-checked locally; repair stays deterministic through `npx gsdd-cli update`.
 
-### Quickstart (after init)
+Start with the public proof pack:
 
-Your tool determines how you invoke workflows:
+- [Brownfield proof](docs/BROWNFIELD-PROOF.md)
+- [Exported consumer proof pack](docs/proof/consumer-node-cli/README.md)
+- [Runtime support matrix](docs/RUNTIME-SUPPORT.md)
+- [Verification discipline](docs/VERIFICATION-DISCIPLINE.md)
+
+### Quickstart (after init)
+
+Runtime floor: Node 20+.
+
+Your tool determines how you invoke workflows:
 
 - **Claude Code / OpenCode / Cursor / Copilot / Gemini:** Use slash commands directly — `/gsdd-new-project`, `/gsdd-plan`, etc.
-- **Codex CLI:** Use skill references — `$gsdd-new-project`, `$gsdd-plan`, etc.
+- **Codex CLI:** Use skill references — `$gsdd-new-project`, `$gsdd-plan`, etc. `$gsdd-plan` writes the plan and stops; start a separate `$gsdd-execute` run when you want implementation to begin.
 - **Other AI tools:** Open `.agents/skills/gsdd-<workflow>/SKILL.md` and follow the instructions.
 
-If you generate the root `AGENTS.md` block, it adds GSDD behavioral governance. For Cursor, Copilot, and Gemini, that governance is optional discipline on top of native skill discovery — not the mechanism that makes workflows discoverable.
+If you generate the root `AGENTS.md` block, it adds the framework's behavioral governance. For Cursor, Copilot, and Gemini, that governance is optional discipline on top of native skill discovery — not the mechanism that makes workflows discoverable.
+
+### Choose Your Starting Workflow
 
-First workflow to run: **new-project** — it asks about your goals, audits the codebase (if brownfield), and produces `.planning/SPEC.md` + `.planning/ROADMAP.md`.
+| Situation | Start here | Why |
+|----------|------------|-----|
+| Greenfield project, or brownfield work that is fuzzy / broad / milestone-shaped | `gsdd-new-project` | This is the full initializer. On brownfield repos it will run codebase mapping internally when it needs it. |
+| Brownfield repo and the bounded change is already concrete | `gsdd-quick` | This is the bounded-change lane. It can use existing codebase maps when present and otherwise builds a just-enough inline brownfield baseline. |
+| Brownfield repo is unfamiliar, risky, or you want a deeper baseline before choosing the lane | `gsdd-map-codebase` | This is the deeper orientation pass. Use it when the inline quick baseline would be too weak, then continue with `gsdd-quick` or `gsdd-new-project`. |
 
 ### Platform Adapters
 
-GSDD generates adapters for whichever tools you use:
+Workspine generates adapters for whichever tools you use:
 
 ```bash
 npx gsdd-cli init                    # Guided install wizard (detected runtimes preselected)
@@ -98,10 +155,10 @@ npx gsdd-cli init --tools all        # All of the above
 | Platform | Public claim | What's generated |
 |----------|--------------|-----------------|
 | **All** (default) | Shared portable surface | `.agents/skills/gsdd-*/SKILL.md` — portable workflow entrypoints (always generated) |
-| **Claude Code** | Directly validated | `.claude/skills/`, `.claude/commands/`, `.claude/agents/` — native workflow surfaces |
-| **OpenCode** | Directly validated | `.opencode/commands/`, `.opencode/agents/` — native workflow surfaces |
-| **Codex CLI** | Directly validated | Portable skill entry plus `.codex/agents/gsdd-plan-checker.toml` |
-| **Cursor / Copilot / Gemini** | Qualified support | Skills-native discovery from `.agents/skills/`; optional root `AGENTS.md` block adds behavioral governance |
+| **Claude Code** | Directly validated | `.claude/skills/`, `.claude/commands/`, `.claude/agents/` — native workflow surfaces, freshness-checked when generated locally |
+| **OpenCode** | Directly validated | `.opencode/commands/`, `.opencode/agents/` — native workflow surfaces, freshness-checked when generated locally |
+| **Codex CLI** | Directly validated | Portable skill entry plus `.codex/agents/gsdd-plan-checker.toml`; planning stays locked until explicit `$gsdd-execute`, and installed surfaces are freshness-checked locally |
+| **Cursor / Copilot / Gemini** | Same core workflow | Skills-native discovery from `.agents/skills/`; optional root `AGENTS.md` block adds behavioral governance, and the generated skill surface is freshness-checked locally |
 | **Other AI tools** | Fallback only | Open `.agents/skills/gsdd-*/SKILL.md` directly |
 
 ### Updating
@@ -112,7 +169,7 @@ npx gsdd-cli update --tools claude     # Update specific platform only
 npx gsdd-cli update --templates        # Refresh .planning/templates/ and role contracts from framework source
 ```
 
-### Headless Mode (CI / Automation)
+### Non-Interactive Mode (CI / Automation)
 
 For non-interactive environments:
 
@@ -121,7 +178,7 @@ npx gsdd-cli init --auto --tools claude
 npx gsdd-cli init --auto --tools claude --brief path/to/PRD.md
 ```
 
-`--auto` skips interactive prompts, uses smart defaults (`autoAdvance: true` in config). `--brief` copies a project document to `.planning/PROJECT_BRIEF.md` for `new-project` to consume.
+`--auto` skips the interactive install wizard and uses default configuration. It does **not** run downstream workflows (`new-project`, `plan`, `execute`, `verify`) — those are always explicit. `--brief` copies a project document to `.planning/PROJECT_BRIEF.md` for `new-project` to consume.
 
 If you already know exactly what to generate, `--tools ...` remains the manual path. The wizard is the primary onboarding UX; flags remain the advanced/headless contract.
 
@@ -151,7 +208,7 @@ init → [plan → execute → verify] × N phases → audit-milestone → done
 Run the `gsdd-new-project` workflow. The system:
 
 1. **Questions** — asks until it understands your idea (goals, constraints, tech, edge cases)
-2. **Codebase audit** — if brownfield, runs 4 parallel mappers (or prompts for `/gsdd-map-codebase` first)
+2. **Codebase map** — if brownfield and a deeper baseline is needed, maps the codebase across stack, architecture, conventions, and concerns; users do not need to pre-run `map-codebase` before `new-project`
 3. **Research** — spawns parallel researchers to investigate the domain (configurable depth: fast/balanced/deep)
 4. **Spec + Roadmap** — produces `SPEC.md` (living specification) and `ROADMAP.md` (phased delivery plan)
 
@@ -167,7 +224,9 @@ Run `gsdd-plan` for the current phase. The system:
 2. **Plans** — creates atomic task plans with XML structure
 3. **Checks** — a separate agent in a fresh context window reviews the plan against 7 dimensions (requirement coverage, task completeness, dependency correctness, key-link completeness, scope sanity, must-have quality, context compliance). If the plan fails, it revises and re-checks — up to 3 cycles before escalating to the human. Output is typed JSON so orchestration is machine-parseable, not prompt-dependent.
 
-Each plan is small enough to execute in a fresh context window. The checker runs in a separate context from the planner — this is the [ICLR-validated](https://arxiv.org/abs/2310.12397) pattern for catching blind spots the planner inherits from its own reasoning.
+Each plan is small enough to execute in a fresh context window. The checker runs in a separate context from the planner — this is the [ICLR-validated](https://arxiv.org/abs/2310.01798) pattern for catching blind spots the planner inherits from its own reasoning.
+
+`gsdd-plan` is terminal for the current run: it writes planning artifacts only. Execution begins only after an explicit `gsdd-execute` / `/gsdd-execute` / `$gsdd-execute` transition, depending on the runtime.
 
 **Creates:** Phase plans in `.planning/phases/`
 
@@ -234,12 +293,12 @@ Use for: bug fixes, small features, config changes, one-off tasks.
 
 ## Workflows
 
-GSDD has 14 workflows, run via generated skills or adapters:
+Workspine has 14 workflows, run via generated skills or adapters:
 
 | Workflow | What it does |
 |----------|--------------|
-| `gsdd-new-project` | Full initialization: questioning, codebase audit, research, spec, roadmap |
-| `gsdd-map-codebase` | Map existing codebase with 4 parallel mappers |
+| `gsdd-new-project` | Full initialization: questioning, brownfield audit when needed, research, spec, roadmap |
+| `gsdd-map-codebase` | Deeper brownfield orientation and refresh before `quick` or `new-project` |
 | `gsdd-plan` | Research + plan + check for a phase |
 | `gsdd-execute` | Execute phase plan: implement tasks, verify changes |
 | `gsdd-verify` | Verify completed phase: 3-level checks, anti-pattern scan |
@@ -248,7 +307,7 @@ GSDD has 14 workflows, run via generated skills or adapters:
 | `gsdd-complete-milestone` | Archive shipped milestone, evolve spec, collapse roadmap |
 | `gsdd-new-milestone` | Start next milestone: gather goals, define requirements, create roadmap phases |
 | `gsdd-plan-milestone-gaps` | Create gap-closure phases from audit results |
-| `gsdd-quick` | Quick task: plan and execute sub-hour work outside the phase cycle |
+| `gsdd-quick` | Quick task: bounded brownfield change lane with inline baseline when full mapping is unnecessary |
 | `gsdd-pause` | Pause work: save session context to checkpoint for seamless resumption |
 | `gsdd-resume` | Resume work: restore context from artifacts and route to next action |
 | `gsdd-progress` | Show project status and route to next action |
@@ -284,7 +343,7 @@ Workflows are agent skills or commands, not plain shell utilities. How you invok
 
 ### Roles (10 canonical)
 
-GSDD consolidates GSD's agent surface into 10 roles with durable contracts:
+Workspine consolidates GSD's agent surface into 10 roles with durable contracts:
 
 | Role | Responsibility |
 |------|---------------|
@@ -296,6 +355,7 @@ GSDD consolidates GSD's agent surface into 10 roles with durable contracts:
 | **Verifier** | Phase verification — Exists/Substantive/Wired gate |
 | **Roadmapper** | Roadmap generation from spec |
 | **Integration Checker** | Cross-phase wiring, API coverage, auth protection, E2E flows |
+| **Approach Explorer** | Implementation approach alignment before planning begins |
 | **Debugger** | Utility role for systematic debugging |
 
 ### Two-Layer Architecture
@@ -307,14 +367,14 @@ GSDD consolidates GSD's agent surface into 10 roles with durable contracts:
 
 ### Adapter Architecture
 
-GSDD generates vendor-specific files from vendor-agnostic markdown — it does not convert from one vendor format to another. This means every adapter gets first-class output shaped to its platform's native capabilities.
+Workspine generates vendor-specific files from vendor-agnostic markdown — it does not convert from one vendor format to another. This means every adapter gets first-class output shaped to its platform's native capabilities.
 
 | Adapter | Evidence posture | Strategy |
 |---------|------------------|----------|
 | **Claude Code** | Directly validated | Skill-primary plan surface, thin command alias, native `gsdd-plan-checker` agent |
 | **OpenCode** | Directly validated | Specialized `/gsdd-plan` command (`subtask: false`), hidden `gsdd-plan-checker` subagent (`mode: subagent`) |
-| **Codex CLI** | Directly validated | Portable skill as entry surface, `.codex/agents/gsdd-plan-checker.toml` (read-only, high reasoning effort) |
-| **Cursor / Copilot / Gemini** | Qualified support | Runtime discovers `.agents/skills/` natively; optional root `AGENTS.md` block adds behavioral governance only |
+| **Codex CLI** | Directly validated | Portable skill as entry surface, `.codex/agents/gsdd-plan-checker.toml` (read-only, high reasoning effort), explicit `$gsdd-execute` unlock |
+| **Cursor / Copilot / Gemini** | Same core workflow | Runtime discovers `.agents/skills/` natively; optional root `AGENTS.md` block adds behavioral governance only |
 | **agents** (`--tools agents`) | Governance-only helper | Root `AGENTS.md` block for tools that benefit from governance or need open-standard fallback guidance |
 
 All adapters render the plan-checker from a single source (`distilled/templates/delegates/plan-checker.md`). Each adapter shapes the output to its platform's native mechanics, and the portable skill remains the shared workflow source.
@@ -338,7 +398,7 @@ Model IDs pass through a two-layer injection guard: a regex whitelist (`/^[a-zA-
 
 ### Advisory Git Protocol
 
-GSDD does not impose commit formats, branch naming, or one-commit-per-task rules. Git guidance is advisory — repository and team conventions take precedence:
+Workspine does not impose commit formats, branch naming, or one-commit-per-task rules. Git guidance is advisory — repository and team conventions take precedence:
 
 - **Branching** — follow existing repo conventions
 - **Commits** — group changes logically, no framework-imposed format
@@ -390,8 +450,8 @@ Optional model-control keys:
 
 Runtime behavior:
 - Claude translates semantic tiers to native aliases for the checker agent.
-- OpenCode inherits its runtime model by default; GSDD only injects an exact OpenCode `model:` when you set an explicit runtime override.
-- Codex inherits its session model by default; GSDD only injects an explicit `model` in the TOML when you set an explicit runtime override.
+- OpenCode inherits its runtime model by default; Workspine only injects an exact OpenCode `model:` when you set an explicit runtime override.
+- Codex inherits its session model by default; Workspine only injects an explicit `model` in the TOML when you set an explicit runtime override.
 
 CLI:
 - `gsdd models show`
@@ -430,6 +490,7 @@ Advisory defaults, overridden by repo conventions:
 | Problem | What to do |
 |---------|------------|
 | Workspace feels broken | `gsdd health` — checks errors, warnings, info |
+| `gsdd health` reports generated runtime-surface drift | `npx gsdd-cli update` (or `npx gsdd-cli update --tools <runtime>`) — regenerates installed skills/adapters from current render output |
 | Lost track of progress | Run `gsdd-progress` — reads artifacts, shows status |
 | Need context from last session | Run `gsdd-resume` — restores state, routes to next action |
 | Plans seem wrong | Check `workflow.research: true` in config |
@@ -443,7 +504,7 @@ For detailed troubleshooting and recovery procedures, see the [User Guide](docs/
 
 ## Design Decisions
 
-GSDD makes 39 documented design decisions relative to GSD, each with evidence from source files and external research. See [`distilled/DESIGN.md`](distilled/DESIGN.md) for the full rationale.
+This repo records 52 documented design decisions relative to GSD, each with evidence from source files and external research. See [`distilled/DESIGN.md`](distilled/DESIGN.md) for the full rationale.
 
 Key choices:
 - **4-file codebase standard** — drop state that rots (STRUCTURE, INTEGRATIONS, TESTING), keep rules that don't
@@ -461,7 +522,7 @@ Key choices:
 
 ## Testing
 
-GSDD has 1228 structural assertions across 10 test files — named suites that guard properties PRs repeatedly fixed manually. These are not unit tests for application code; they are invariant checks on the specification itself.
+The framework has 1,381 tests across 13 test files — named suites that guard properties PRs repeatedly fixed manually. These are not unit tests for application code; they are invariant checks on the specification itself.
 
 ### Invariant Suites (I-series)
 
@@ -538,21 +599,9 @@ npm test
 
 ---
 
-## Relationship to GSD
-
-GSDD is a distilled fork of [Get Shit Done](https://github.com/gsd-build/get-shit-done). It is **not** a full replacement for current upstream GSD.
-
-**What GSDD preserves** (~76% of core method): the long-horizon delivery spine — persistent artifacts, codebase mapping, scoped planning, execution, verification, and milestone auditing.
-
-**What GSDD does not cover** (~44% of full upstream surface): GSD currently exposes 32 workflow files and 11 agent files including discovery modes, a settings flow, extra operator ergonomics, and broader session-management surface area. GSDD intentionally does not recreate this full surface.
-
-**The trade-off:** Fewer moving parts for the human operator. Cleaner role contracts and a simpler artifact model. But reduced operator comfort and limited control-plane features (no telemetry, no artifact linting). Health diagnostics are available via `gsdd health`.
-
----
-
 ## Credits
 
-GSDD is a distilled fork of [Get Shit Done](https://github.com/gsd-build/get-shit-done) by [Lex Christopherson](https://github.com/glittercowboy), licensed under MIT.
+Workspine is a fork of [Get Shit Done](https://github.com/gsd-build/get-shit-done) by [Lex Christopherson](https://github.com/glittercowboy), licensed under MIT. Original git history is retained for attribution.
 
 ---
 

package/agents/README.md

@@ -1,6 +1,6 @@
 # Canonical Role Library
 
-Vendor-agnostic role contracts for GSDD's agent architecture.
+Vendor-agnostic role contracts for Workspine's agent architecture.
 
 ## Two-Layer Architecture
 

package/bin/adapters/claude.mjs

@@ -181,4 +181,11 @@ function createClaudeAdapter({ cwd, workflows, renderSkillContent, getDelegateCo
   };
 }
 
-export { createClaudeAdapter, CLAUDE_MODEL_PROFILES };
+export {
+  createClaudeAdapter,
+  CLAUDE_MODEL_PROFILES,
+  renderClaudeApproachExplorer,
+  renderClaudePlanChecker,
+  renderClaudePlanCommand,
+  renderClaudePlanSkill,
+};

package/bin/adapters/codex.mjs

@@ -78,4 +78,8 @@ function createCodexAdapter({
   };
 }
 
-export { createCodexAdapter };
+export {
+  createCodexAdapter,
+  renderCodexApproachExplorer,
+  renderCodexPlanChecker,
+};

package/bin/adapters/opencode.mjs

@@ -269,4 +269,10 @@ function createOpenCodeAdapter({
   };
 }
 
-export { createOpenCodeAdapter, detectOpenCodeConfiguredModel };
+export {
+  createOpenCodeAdapter,
+  detectOpenCodeConfiguredModel,
+  renderOpenCodeApproachExplorer,
+  renderOpenCodePlanChecker,
+  renderOpenCodePlanCommand,
+};

package/bin/gsdd.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-// gsdd - GSD Distilled CLI
+// gsdd - Workspine CLI
 
 import { realpathSync } from 'fs';
 import { join, dirname } from 'path';
@@ -19,6 +19,7 @@ import { createCmdInit, createCmdUpdate, cmdHelp } from './lib/init.mjs';
 import { cmdFindPhase, cmdVerify, cmdScaffold, cmdPhaseStatus } from './lib/phase.mjs';
 import { cmdFileOp } from './lib/file-ops.mjs';
 import { createCmdHealth } from './lib/health.mjs';
+import { cmdLifecyclePreflight } from './lib/lifecycle-preflight.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -57,7 +58,7 @@ const WORKFLOWS = [
   defineWorkflow({ name: 'gsdd-progress', workflow: 'progress.md', description: 'Check progress - show project status and route to next action', mutatesArtifacts: false }),
 ];
 
-const FRAMEWORK_VERSION = 'v1.3';
+const FRAMEWORK_VERSION = 'v1.4';
 
 function createCliContext(cwd = process.cwd()) {
   return {
@@ -87,7 +88,7 @@ const INIT_CONTEXT = createCliContext(CWD);
 
 const cmdInit = createCmdInit(INIT_CONTEXT);
 const cmdUpdate = createCmdUpdate(INIT_CONTEXT);
-const cmdHealth = createCmdHealth({ frameworkVersion: FRAMEWORK_VERSION });
+const cmdHealth = createCmdHealth(INIT_CONTEXT);
 
 const COMMANDS = {
   init: cmdInit,
@@ -95,6 +96,7 @@ const COMMANDS = {
   models: cmdModels,
   health: cmdHealth,
   'file-op': cmdFileOp,
+  'lifecycle-preflight': cmdLifecyclePreflight,
   'find-phase': cmdFindPhase,
   'phase-status': cmdPhaseStatus,
   verify: cmdVerify,
@@ -124,4 +126,4 @@ if (IS_MAIN) {
   await runCli();
 }
 
-export { cmdHelp, cmdInit, cmdUpdate, cmdModels, cmdHealth, cmdFileOp, cmdFindPhase, cmdPhaseStatus, cmdVerify, cmdScaffold, runCli, FRAMEWORK_VERSION, createCliContext };
+export { cmdHelp, cmdInit, cmdUpdate, cmdModels, cmdHealth, cmdFileOp, cmdLifecyclePreflight, cmdFindPhase, cmdPhaseStatus, cmdVerify, cmdScaffold, runCli, FRAMEWORK_VERSION, createCliContext };

package/bin/lib/evidence-contract.mjs

@@ -0,0 +1,112 @@
+const EVIDENCE_KINDS = Object.freeze(['code', 'test', 'runtime', 'delivery', 'human']);
+const DELIVERY_POSTURES = Object.freeze(['repo_only', 'delivery_sensitive']);
+const CLOSURE_SURFACES = Object.freeze(['verify', 'audit-milestone', 'complete-milestone']);
+
+const LEGACY_EVIDENCE_ALIASES = Object.freeze({
+  code: 'code',
+  test: 'test',
+  runtime: 'runtime',
+  delivery: 'delivery',
+  human: 'human',
+  'code-evidence': 'code',
+  'repo-test': 'test',
+  'runtime-check': 'runtime',
+  'user-confirmation': 'human',
+});
+
+const EVIDENCE_MATRIX = Object.freeze({
+  verify: Object.freeze({
+    repo_only: Object.freeze({
+      requiredKinds: Object.freeze(['code']),
+      recommendedKinds: Object.freeze(['test']),
+      blockedSoloKinds: Object.freeze(['human', 'delivery']),
+    }),
+    delivery_sensitive: Object.freeze({
+      requiredKinds: Object.freeze(['code', 'runtime']),
+      recommendedKinds: Object.freeze(['test', 'delivery', 'human']),
+      blockedSoloKinds: Object.freeze(['code', 'human']),
+    }),
+  }),
+  'audit-milestone': Object.freeze({
+    repo_only: Object.freeze({
+      requiredKinds: Object.freeze(['code', 'test']),
+      recommendedKinds: Object.freeze(['runtime', 'human']),
+      blockedSoloKinds: Object.freeze(['human', 'delivery']),
+    }),
+    delivery_sensitive: Object.freeze({
+      requiredKinds: Object.freeze(['code', 'test', 'runtime', 'delivery']),
+      recommendedKinds: Object.freeze(['human']),
+      blockedSoloKinds: Object.freeze(['code', 'human']),
+    }),
+  }),
+  'complete-milestone': Object.freeze({
+    repo_only: Object.freeze({
+      requiredKinds: Object.freeze(['code', 'test']),
+      recommendedKinds: Object.freeze(['runtime']),
+      blockedSoloKinds: Object.freeze(['human', 'delivery']),
+    }),
+    delivery_sensitive: Object.freeze({
+      requiredKinds: Object.freeze(['code', 'test', 'runtime', 'delivery']),
+      recommendedKinds: Object.freeze(['human']),
+      blockedSoloKinds: Object.freeze(['code', 'human']),
+    }),
+  }),
+});
+
+export { CLOSURE_SURFACES, DELIVERY_POSTURES, EVIDENCE_KINDS };
+
+export function normalizeEvidenceKind(kind) {
+  if (!kind) {
+    return null;
+  }
+
+  return LEGACY_EVIDENCE_ALIASES[kind] ?? null;
+}
+
+export function normalizeEvidenceKinds(kinds = []) {
+  const normalized = [];
+  for (const kind of kinds) {
+    const resolved = normalizeEvidenceKind(kind);
+    if (resolved && !normalized.includes(resolved)) {
+      normalized.push(resolved);
+    }
+  }
+  return normalized;
+}
+
+export function isClosureSurface(surface) {
+  return CLOSURE_SURFACES.includes(surface);
+}
+
+export function getEvidenceContract(surface, deliveryPosture) {
+  const matrix = EVIDENCE_MATRIX[surface];
+  if (!matrix) {
+    throw new Error(`Unsupported closure evidence surface: ${surface}`);
+  }
+
+  const posture = matrix[deliveryPosture];
+  if (!posture) {
+    throw new Error(`Unsupported delivery posture for ${surface}: ${deliveryPosture}`);
+  }
+
+  return {
+    surface,
+    deliveryPosture,
+    supportedKinds: [...EVIDENCE_KINDS],
+    requiredKinds: [...posture.requiredKinds],
+    recommendedKinds: [...posture.recommendedKinds],
+    blockedSoloKinds: [...posture.blockedSoloKinds],
+  };
+}
+
+export function describeEvidenceSurface(surface) {
+  if (!isClosureSurface(surface)) {
+    return null;
+  }
+
+  return {
+    surface,
+    supportedKinds: [...EVIDENCE_KINDS],
+    deliveryPostures: DELIVERY_POSTURES.map((deliveryPosture) => getEvidenceContract(surface, deliveryPosture)),
+  };
+}

package/bin/lib/health-truth.mjs

@@ -1,9 +1,15 @@
 import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
+import { evaluateLifecycleState } from './lifecycle-state.mjs';
+import {
+  getRuntimeFreshnessRepairGuidance,
+  summarizeRuntimeFreshnessIssues,
+} from './runtime-freshness.mjs';
+import { checkDrift } from './session-fingerprint.mjs';
 
-export const TRUTH_CHECK_IDS = ['W7', 'W8', 'W9', 'W10'];
+export const TRUTH_CHECK_IDS = ['W7', 'W8', 'W9', 'W10', 'W11', 'W12'];
 
-export function runTruthChecks(planningDir, frameworkDir, actualCheckIds) {
+export function runTruthChecks(planningDir, frameworkDir, actualCheckIds, options = {}) {
   const warnings = [];
   const designPath = join(frameworkDir, 'distilled', 'DESIGN.md');
   const readmePath = join(frameworkDir, 'distilled', 'README.md');
@@ -11,6 +17,7 @@ export function runTruthChecks(planningDir, frameworkDir, actualCheckIds) {
   const gapsPath = join(frameworkDir, '.internal-research', 'gaps.md');
   const specPath = join(planningDir, 'SPEC.md');
   const roadmapPath = join(planningDir, 'ROADMAP.md');
+  const lifecycle = evaluateLifecycleState({ planningDir });
 
   if (existsSync(designPath)) {
     const documentedIds = extractHealthTableIds(readFileSync(designPath, 'utf-8'));
@@ -69,16 +76,7 @@ export function runTruthChecks(planningDir, frameworkDir, actualCheckIds) {
   }
 
   if (existsSync(specPath) && existsSync(roadmapPath)) {
-    const spec = readFileSync(specPath, 'utf-8');
-    const roadmap = readFileSync(roadmapPath, 'utf-8');
-    const checkedRequirements = extractCheckedRequirements(spec);
-    const roadmapRequirements = extractRoadmapRequirements(roadmap);
-    const mismatches = [];
-    for (const [requirementId, roadmapStatus] of roadmapRequirements.entries()) {
-      const specChecked = checkedRequirements.has(requirementId);
-      if (roadmapStatus && !specChecked) mismatches.push(`${requirementId} phase complete but SPEC unchecked`);
-      if (!roadmapStatus && specChecked) mismatches.push(`${requirementId} SPEC checked but phase incomplete`);
-    }
+    const mismatches = lifecycle.requirementAlignment.mismatches;
     if (mismatches.length > 0) {
       warnings.push({
         id: 'W10',
@@ -89,6 +87,25 @@ export function runTruthChecks(planningDir, frameworkDir, actualCheckIds) {
     }
   }
 
+  if (options.runtimeFreshnessReport?.issueCount > 0) {
+    warnings.push({
+      id: 'W11',
+      severity: 'WARN',
+      message: `Installed generated runtime surfaces drift from current render output (${summarizeRuntimeFreshnessIssues(options.runtimeFreshnessReport)})`,
+      fix: getRuntimeFreshnessRepairGuidance(options.runtimeFreshnessReport),
+    });
+  }
+
+  const drift = checkDrift(planningDir);
+  if (drift.drifted) {
+    warnings.push({
+      id: 'W12',
+      severity: 'WARN',
+      message: `Planning state drifted since last recorded session (${drift.details.join('; ')})`,
+      fix: 'Review the changes, then run a lifecycle workflow to update the fingerprint',
+    });
+  }
+
   return warnings;
 }
 
@@ -167,22 +184,3 @@ function extractSection(content, startMarker, endMarker) {
 function normalizeContent(content) {
   return content.replace(/\r\n/g, '\n');
 }
-
-function extractCheckedRequirements(content) {
-  const checked = new Set();
-  for (const result of content.matchAll(/- \[x\] \*\*\[([A-Z0-9-]+)]\*\*/g)) {
-    checked.add(result[1]);
-  }
-  return checked;
-}
-
-function extractRoadmapRequirements(content) {
-  const mapped = new Map();
-  for (const result of content.matchAll(/- \[([ x-])] \*\*Phase\s+\d+[a-z]?:.*?\*\*\s+—\s+\[([^\]]+)]/g)) {
-    const requirementIds = result[2].split(',').map((id) => id.trim());
-    for (const requirementId of requirementIds) {
-      mapped.set(requirementId, result[1].toLowerCase() === 'x');
-    }
-  }
-  return mapped;
-}