gsdd-cli 0.3.1 → 0.18.0

package/README.md

@@ -1,40 +1,84 @@
 <div align="center">
 
-# GSD Distilled
+# Workspine
 
-**A portable, spec-driven development kernel for AI coding agents.**
-
-Extracted from [Get Shit Done](https://github.com/gsd-build/get-shit-done). Same long-horizon delivery spine — fewer moving parts.
+**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)
-[![Tests](https://img.shields.io/badge/assertions-862_passing-brightgreen?style=for-the-badge)](tests/)
 
 ```bash
 npx gsdd-cli init
 ```
 
-**Works with Claude Code, OpenCode, Codex CLI, Cursor, Copilot, and Gemini CLI.**
+**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
 
-GSDD is a distilled fork of GSD. It preserves the high-leverage parts of long-horizon AI-assisted development:
+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).
+
+</details>
+
+### 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). GSDD has 10 workflows and 10 roles.
+<details>
+<summary>How it works</summary>
 
-**Target user:** Developer or small team that wants a spec-driven long-horizon kernel, not full operator comfort.
+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.
 
 ---
 
@@ -59,22 +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:** 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`.
+
+Start with the public proof pack:
 
-### Quickstart (after init)
+- [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)
 
-Your tool determines how you invoke workflows:
+### 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.
 
-First workflow to run: **new-project** — it asks about your goals, audits the codebase (if brownfield), and produces `.planning/SPEC.md` + `.planning/ROADMAP.md`.
+### Choose Your Starting Workflow
+
+| 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)
@@ -86,14 +152,14 @@ npx gsdd-cli init --tools cursor     # Backward-compatible AGENTS.md governance
 npx gsdd-cli init --tools all        # All of the above
 ```
 
-| Platform | Tier | What's generated |
-|----------|------|-----------------|
-| **All** (default) | Open standard | `.agents/skills/gsdd-*/SKILL.md` — portable workflow entrypoints (always generated) |
-| **Claude Code** | Native | `.claude/skills/`, `.claude/commands/`, `.claude/agents/` — slash commands work immediately |
-| **OpenCode** | Native | `.opencode/commands/`, `.opencode/agents/` — slash commands work immediately |
-| **Codex CLI** | Native | `.codex/agents/gsdd-plan-checker.toml` — skill reference `$gsdd-plan` works immediately |
-| **Cursor / Copilot / Gemini** | Skills-native runtime + optional governance | Native slash-command discovery from `.agents/skills/`; optional root `AGENTS.md` block adds behavioral governance |
-| **Other AI tools** | Open standard fallback | Open `.agents/skills/gsdd-*/SKILL.md` directly |
+| 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, 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
 
@@ -103,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:
 
@@ -112,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.
 
@@ -142,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)
 
@@ -158,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/`
 
@@ -225,17 +293,21 @@ Use for: bug fixes, small features, config changes, one-off tasks.
 
 ## Workflows
 
-GSDD has 10 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 |
+| `gsdd-verify-work` | Conversational UAT testing: validate user-facing behavior with structured gap tracking |
 | `gsdd-audit-milestone` | Audit milestone: cross-phase integration, requirements coverage, E2E flows |
-| `gsdd-quick` | Quick task: plan and execute sub-hour work outside the phase cycle |
+| `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: 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 |
@@ -257,7 +329,9 @@ Workflows are agent skills or commands, not plain shell utilities. How you invok
 | `gsdd init [--tools <platform>]` | Set up `.planning/`, generate adapters |
 | `gsdd update [--tools <platform>] [--templates]` | Regenerate adapters; `--templates` refreshes `.planning/templates/` and role contracts |
 | `gsdd health [--json]` | Check workspace integrity (healthy/degraded/broken) |
+| `gsdd file-op <copy\|delete\|regex-sub>` | Run deterministic workspace-confined file copy, delete, and regex substitution |
 | `gsdd find-phase [N]` | Show phase info as JSON (for agent consumption) |
+| `gsdd phase-status <N> <status>` | Update a single ROADMAP phase status through the status-aware helper |
 | `gsdd verify <N>` | Run artifact checks for phase N |
 | `gsdd scaffold phase <N> [name]` | Create a new phase plan file |
 | `gsdd models [show\|profile\|set\|...]` | Inspect and manage model profile propagation |
@@ -269,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 |
 |------|---------------|
@@ -281,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
@@ -292,15 +367,15 @@ 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 | Kind | Strategy |
-|---------|------|----------|
-| **Claude Code** | `native_capable` adapter + skills-native runtime | Skill-primary plan surface (stays in main context to spawn checker subagent), thin command alias, native `gsdd-plan-checker` agent |
-| **OpenCode** | `native_capable` adapter + skills-native runtime | Specialized `/gsdd-plan` command (`subtask: false`), hidden `gsdd-plan-checker` subagent (`mode: subagent`) |
-| **Codex CLI** | `native_capable` adapter + skills-native runtime | Portable skill as entry surface, `.codex/agents/gsdd-plan-checker.toml` (read-only, high reasoning effort) |
-| **Cursor / Copilot / Gemini** | skills-native runtime + `governance_only` adapter | Runtime discovers `.agents/skills/` natively; optional root `AGENTS.md` block adds behavioral governance only |
-| **agents** (`--tools agents`) | `governance_only` adapter | Root `AGENTS.md` block for tools that benefit from governance or need open-standard fallback guidance |
+| 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), 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.
 
@@ -323,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
@@ -375,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`
@@ -415,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 |
@@ -428,7 +504,7 @@ For detailed troubleshooting and recovery procedures, see the [User Guide](docs/
 
 ## Design Decisions
 
-GSDD makes 36 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
@@ -446,7 +522,7 @@ Key choices:
 
 ## Testing
 
-GSDD has 862 structural assertions across 9 test files — 41 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)
 
@@ -458,7 +534,7 @@ Structural contracts that prevent drift between roles, delegates, workflows, and
 | **I2** | Role section structure — 10 roles have role def, scope, output format, success criteria |
 | **I3** | Delegate thinness — no leaked role-contract sections in delegates |
 | **I3-gate** | New-project approval gates — required human checkpoints present |
-| **I4** | Workflow references — 10 workflows, all delegate/role refs resolve |
+| **I4** | Workflow references — 14 workflows, all delegate/role refs resolve |
 | **I5** | Session management — no vendor APIs, no STATE.md, checkpoint contract |
 | **I5b** | Session workflow scope boundaries |
 | **I6** | Artifact schema definitions |
@@ -518,26 +594,14 @@ Golden-path eval tests that verify artifact-chain contracts across end-to-end wo
 | Health | Pre-init guard, all check categories, verdict logic, JSON/human output |
 
 ```bash
-npm run test:gsdd
+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/control-plane 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/DISTILLATION.md

@@ -356,21 +356,23 @@ Do not add speculative content. Every entry must reference actual source files a
 
 Cross-source best practices applied to GSDD role contracts, audited against 6 external resources. These principles govern how role contracts should be written and revised. Ranked by impact.
 
+> **Source note:** "Anthropic CE" in this section refers to Anthropic's "Building effective agents" (Dec 2024) for orchestration and sub-agent patterns, and LangChain's "Context Engineering for Agents" (2025) for Write/Select/Compress/Isolate context management patterns. They are cited separately where attribution is precise.
+
 ### Architecture-Level (highest leverage)
 
 | Principle | What It Means | Source | GSDD Implementation |
 |-----------|--------------|--------|---------------------|
-| **Context isolation** | Research and heavy reads go in subagents; only compressed summaries enter the main context | Anthropic CE: "sub-agents perform deep technical work, returning condensed summaries" | Approach explorer research subagents return ~1000-token summaries; plan-checker runs in fresh context |
-| **JIT context loading** | Never say "read everything." Specify what to extract from each file | Anthropic CE: "maintain lightweight identifiers and use these references to dynamically load data into context at runtime" | `<input_contract>` with extraction guidance: "From SPEC.md read ONLY locked decisions" |
-| **Intermediate persistence** | For long interactions, write confirmed state to disk incrementally | Anthropic CE: "Agent regularly writes notes persisted to memory outside of the context window" | Approach explorer writes decisions to disk as they're confirmed during conversation |
-| **Progressive disclosure** | Don't front-load all context; let agents discover incrementally | Anthropic CE: "agents can assemble understanding layer by layer" | Gray areas presented individually; research loaded per area on demand |
+| **Context isolation** | Research and heavy reads go in subagents; only compressed summaries enter the main context | Anthropic "Building effective agents" (Dec 2024): orchestrator-worker pattern — sub-agents do deep technical work and return condensed summaries | Approach explorer research subagents return ~1000-token summaries; plan-checker runs in fresh context |
+| **JIT context loading** | Never say "read everything." Specify what to extract from each file | LangChain "Context Engineering for Agents" (2025): Select step of Write/Select/Compress/Isolate — load only the specific content needed, not full files | `<input_contract>` with extraction guidance: "From SPEC.md read ONLY locked decisions" |
+| **Intermediate persistence** | For long interactions, write confirmed state to disk incrementally | Anthropic BEA: agent memory outside context window. LangChain CE: Write pattern — confirmed state persisted to disk | Approach explorer writes decisions to disk as they're confirmed during conversation |
+| **Progressive disclosure** | Don't front-load all context; let agents discover incrementally | LangChain CE: Compress/Isolate patterns — agents assemble understanding incrementally rather than loading everything upfront | Gray areas presented individually; research loaded per area on demand |
 
 ### Prompt Structure (medium leverage)
 
 | Principle | What It Means | Source | GSDD Implementation |
 |-----------|--------------|--------|---------------------|
 | **XML semantic structure** | Use XML tags to separate role, instructions, examples, inputs, outputs, anti-patterns | Anthropic Claude: "XML tags help Claude parse complex prompts unambiguously" | All roles use `<role>`, most use `<quality_guarantees>`, `<anti_patterns>`. Approach-explorer adds `<algorithm>`, `<examples>`, `<scope_guardrail>` |
-| **Anti-patterns early** | Place "don't do this" instructions near the top, after role definition | Anthropic CE: critical information at the beginning gets more attention. NeoLab: early placement for high attention weight | `<anti_patterns>` placed immediately after `<role>` in all roles that have them |
+| **Anti-patterns early** | Place "don't do this" instructions near the top, after role definition | Anthropic Claude prompting docs: critical information at the beginning receives more attention (primacy effect in long-context prompts) | `<anti_patterns>` placed immediately after `<role>` in all roles that have them |
 | **Few-shot examples** | Show the pattern of interaction, not just output format | Anthropic Claude: "3-5 examples for best results." Examples in `<example>` tags | Approach-explorer: 3 examples. Other roles use inline format examples within algorithm sections |
 | **Self-check before output** | Run an explicit checklist before producing the final artifact | OpenAI: "verification loops." Anthropic Claude: "Ask Claude to self-check" | Approach-explorer step 7; planner `<plan_self_check>`; executor completion verification |
 | **Scope boundaries with heuristics** | Don't just list in/out of scope — give the agent a judgment rule | Novel, validated in approach-explorer | "Does this clarify implementation within the phase, or does it add a capability that could be its own phase?" |
@@ -379,7 +381,7 @@ Cross-source best practices applied to GSDD role contracts, audited against 6 ex
 
 | Principle | What It Means | Source | GSDD Implementation |
 |-----------|--------------|--------|---------------------|
-| **Authority language: intentional leverage** | Anthropic Claude 4.6 warns "CRITICAL:" can overtrigger on newer models. NeoLab persuasion research found imperative language doubled compliance (33%→72%). GSDD decision: **keep CRITICAL: for mandatory initial-read** — this is a genuine compliance-critical instruction where skipping it causes cascading failures. Use normal language for non-critical instructions. | Anthropic Claude 4.6 vs. NeoLab persuasion research (direct conflict). GSDD sides with NeoLab for this specific use case | `CRITICAL: Mandatory initial read` kept in all 7 roles. `NEVER` kept for security (mapper secret protection). Normal language used for algorithm steps, scope guidance, and quality rules |
+| **Authority language: intentional leverage** | Anthropic Claude warns "CRITICAL:" can overtrigger on newer models. GSDD decision: **keep CRITICAL: for mandatory initial-read** — a genuine compliance-critical instruction where skipping causes cascading failures. Emphasis markers work when rare and specific (signal-to-noise principle: one CRITICAL: in a role contract is a load-bearing gate; ten would be noise). Use normal language for algorithm steps, scope guidance, and quality rules. | Anthropic Claude prompting docs (overtriggering caution) + technical writing signal-to-noise principle. GSDD applies the caution selectively: only compliance-critical context gates use CRITICAL: | `CRITICAL: Mandatory initial read` kept in all 7 roles. `NEVER` kept for security (mapper secret protection). Normal language used for algorithm steps, scope guidance, and quality rules |
 | **Tell what to do, not just what not to do** | Anti-patterns alone are insufficient; pair with positive instructions | Anthropic Claude: "Tell Claude what to do instead of what not to do" | Every role has both `<anti_patterns>` AND positive algorithm/process sections |
 | **Context for instructions** | Explain WHY a rule exists so the agent can generalize | Anthropic Claude: "Providing context or motivation behind your instructions helps Claude better understand your goals" | Research quality rules explain WHY: "Training data is a hypothesis. Verify before asserting." |
 
@@ -394,17 +396,17 @@ These patterns emerged from GSDD's specific needs and were validated through imp
 | **5-dimension assumption surfacing** | Forces transparency about inferences vs. confirmed facts, with confidence levels | Approach-explorer step 6 |
 | **Agent's Discretion delegation** | User can explicitly say "you decide" — reduces fatigue on low-stakes choices | Approach-explorer step 4, planner `<approach_decisions>` |
 | **Domain classification table** | SEE/CALL/RUN/READ/ORGANIZED determines gray area focus per phase type | Approach-explorer step 2 |
-| **Degrees of freedom mapping** | Taste=high freedom, technical=low freedom (research-constrained). Maps to NeoLab's concept | Approach-explorer classification system |
+| **Degrees of freedom mapping** | Taste=high freedom, technical=low freedom (research-constrained). GSDD-originated: applies statistical degrees-of-freedom concept to prompt design scope | Approach-explorer classification system |
 
 ### Source Ranking
 
 Sources are ranked by soundness for agent prompt design. Higher-ranked sources take precedence when sources disagree.
 
-1. **Anthropic — Effective Context Engineering for AI Agents** — Architecture-level patterns with real production evidence (Claude Code, Pokémon). Most authoritative for context window management, sub-agent design, and information flow.
-2. **Anthropic — Claude Prompting Best Practices (Claude 4.6)** — Model-specific, up-to-date. Critical for behavioral warnings (overtriggering, subagent overuse). Supersedes general guidance for Claude-targeted agents.
-3. **OpenAI — Prompt Guidance (GPT-5.4)** — Deepest general-purpose reference. Novel concepts: completeness contracts, verification loops, tool persistence rules, empty result recovery. Model-specific but patterns transfer.
-4. **NeoLab Context Engineering Kit** — Good synthesis. "Degrees of Freedom" concept is useful. Persuasion research contradicts Anthropic on authority language (trust Anthropic for Claude).
-5. **OpenAI Cookbook — Meta-Prompting** — Narrow scope: LLM-as-judge evaluation, iterative prompt refinement. Useful technique, not a framework.
+1. **Anthropic — "Building effective agents" (Dec 2024)** — Agent architecture patterns with production evidence (Claude Code). Most authoritative for orchestrator-worker design, sub-agent fresh context, and task decomposition.
+2. **LangChain — "Context Engineering for Agents" (2025)** — Write/Select/Compress/Isolate framework. Most authoritative for context window management, JIT loading, and information flow patterns.
+3. **Anthropic — Claude Prompting Best Practices (Claude 4.6)** — Model-specific, up-to-date. Critical for behavioral warnings (overtriggering, subagent overuse). Supersedes general guidance for Claude-targeted agents.
+4. **OpenAI — Prompt Guidance (GPT-5.4)** — Deepest general-purpose reference. Novel concepts: completeness contracts, verification loops, tool persistence rules, empty result recovery. Model-specific but patterns transfer.
+5. **OpenAI Cookbook — Meta-Prompting** — Narrow scope: LLM-as-judge evaluation, iterative prompt refinement. Useful technique, not a framework. See also: Suzgun & Kalai "Meta-Prompting" (2024, arXiv 2401.12954).
 6. **JBurlison/MetaPrompts** — Structural skeleton (agent/skill/prompt/instruction hierarchy). Minimal actual guidance on prompt quality.
 
 ### Key Discrepancy Resolution
@@ -413,7 +415,7 @@ When sources conflict, these resolutions apply:
 
 | Conflict | Resolution | Why |
 |----------|------------|-----|
-| Authority language ("YOU MUST" vs. normal) | Keep CRITICAL: for mandatory initial-read (compliance-critical). Use normal language elsewhere | NeoLab's doubled-compliance research applies to instructions where skipping causes cascading failures. Anthropic's overtriggering concern applies to general guidance, not load-bearing context gates |
+| Authority language ("YOU MUST" vs. normal) | Keep CRITICAL: for mandatory initial-read (compliance-critical). Use normal language elsewhere | Emphasis markers work when rare and specific (signal-to-noise). Anthropic's overtriggering concern applies to general guidance; a single CRITICAL: for a mandatory context gate is a load-bearing instruction, not noise |
 | Example count (2 vs. 3-5) | Target 3+ for conversational agents; inline format examples are sufficient for structured output agents | Anthropic's 3-5 recommendation is general; interactive roles benefit more than output-only roles |
 | Subagent return size (200 vs. 1000-2000 tokens) | Use 300-500 tokens | Anthropic's 1000-2000 is upper bound; 200 was too tight for structured approach summaries with trade-offs |
 | "Don't invent alternatives" vs. "try fallback strategies" | Keep "don't invent" for approach research; use fallbacks for information retrieval | These solve different problems: manufacturing fake options is worse than acknowledging one viable path |

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/agents/planner.md

@@ -238,6 +238,8 @@ Before returning, self-check against the checker dimensions:
 5. scope sanity
 6. must-have quality
 7. context compliance
+8. goal achievement
+9. approach alignment (when APPROACH.md exists)
 
 Task completeness rules:
 - every task has files, action, verify, and done

package/bin/adapters/agents.mjs

@@ -6,6 +6,7 @@ function createRootAgentsAdapter({ cwd, renderAgentsBoundedBlock, renderAgentsFi
     id: 'agents',
     name,
     kind: 'governance_only',
+    subagentFiles: [],
     detect() {
       return false;
     },

package/bin/adapters/claude.mjs

@@ -1,5 +1,10 @@
 import { existsSync, mkdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
+import {
+  PLAN_CHECK_DIMENSIONS,
+  MAX_CHECKER_CYCLES,
+  CHECKER_STATUSES,
+} from '../lib/plan-constants.mjs';
 
 const CLAUDE_MODEL_PROFILES = {
   quality: 'opus',
@@ -75,7 +80,7 @@ Execution flow:
      "summary": "One sentence overall assessment",
      "issues": [
        {
-         "dimension": "requirement_coverage | task_completeness | dependency_correctness | key_link_completeness | scope_sanity | must_have_quality | context_compliance | goal_achievement | approach_alignment",
+         "dimension": "${PLAN_CHECK_DIMENSIONS.join(' | ')}",
          "severity": "blocker | warning",
          "description": "What is wrong",
          "plan": "01-PLAN",
@@ -84,10 +89,10 @@ Execution flow:
        }
      ]
    }
-   Status must be either "passed" or "issues_found".
+   Status must be either "${CHECKER_STATUSES[0]}" or "${CHECKER_STATUSES[1]}".
 9. If the checker returns \`passed\`, finish and summarize.
 10. If the checker returns \`issues_found\`, revise the existing plan files only where needed, then run the checker again.
-11. Maximum 3 checker cycles total. If blockers remain after cycle 3, stop and escalate to the user instead of pretending the plan is ready.
+11. Maximum ${MAX_CHECKER_CYCLES} checker cycles total. If blockers remain after cycle ${MAX_CHECKER_CYCLES}, stop and escalate to the user instead of pretending the plan is ready.
 
 Return a concise orchestration summary:
 - target phase
@@ -125,6 +130,10 @@ function createClaudeAdapter({ cwd, workflows, renderSkillContent, getDelegateCo
     id: 'claude',
     name: 'claude',
     kind: 'native_capable',
+    subagentFiles: [
+      '.claude/agents/gsdd-plan-checker.md',
+      '.claude/agents/gsdd-approach-explorer.md',
+    ],
     detect() {
       return existsSync(join(cwd, 'CLAUDE.md')) || existsSync(join(cwd, '.claude'));
     },
@@ -172,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

@@ -44,6 +44,10 @@ function createCodexAdapter({
     id: 'codex',
     name: 'codex',
     kind: 'native_capable',
+    subagentFiles: [
+      '.codex/agents/gsdd-plan-checker.toml',
+      '.codex/agents/gsdd-approach-explorer.toml',
+    ],
     detect() {
       return existsSync(join(cwd, '.codex'));
     },
@@ -74,4 +78,8 @@ function createCodexAdapter({
   };
 }
 
-export { createCodexAdapter };
+export {
+  createCodexAdapter,
+  renderCodexApproachExplorer,
+  renderCodexPlanChecker,
+};