gsdd-cli 0.16.1 → 0.18.1

package/docs/USER-GUIDE.md

@@ -0,0 +1,443 @@
+# Workspine User Guide
+
+A detailed reference for Workspine workflows, troubleshooting, and configuration. Workspine is the public product name; the package, CLI, workflow names, and workspace remain `gsdd-cli`, `gsdd`, `gsdd-*`, and `.planning/` as retained technical contracts. Runtime floor: Node 20+. For quick-start setup and the public proof pack, start with the [README](../README.md).
+
+---
+
+## Table of Contents
+
+- [Workflow Diagrams](#workflow-diagrams)
+- [Command Reference](#command-reference)
+- [Configuration Reference](#configuration-reference)
+- [Usage Examples](#usage-examples)
+- [Troubleshooting](#troubleshooting)
+- [Recovery Quick Reference](#recovery-quick-reference)
+
+---
+
+## Workflow Diagrams
+
+### Full Project Lifecycle
+
+```
+  ┌──────────────────────────────────────────────────┐
+  │                   NEW PROJECT                    │
+  │  gsdd-new-project                                │
+  │  Questions -> Research -> Spec -> Roadmap        │
+  └─────────────────────────┬────────────────────────┘
+                            │
+             ┌──────────────▼─────────────┐
+             │      FOR EACH PHASE:       │
+             │                            │
+             │  ┌────────────────────┐    │
+             │  │ gsdd-plan          │    │  <- Research + Plan + Check
+             │  └──────────┬─────────┘    │
+             │             │              │
+             │  ┌──────────▼─────────┐    │
+             │  │ gsdd-execute       │    │  <- Wave-based execution
+             │  └──────────┬─────────┘    │
+             │             │              │
+             │  ┌──────────▼─────────┐    │
+             │  │ gsdd-verify        │    │  <- 3-level gate
+             │  └──────────┬─────────┘    │
+             │             │              │
+             │     Next Phase?────────────┘
+             │             │ No
+             └─────────────┼──────────────┘
+                           │
+             ┌──────────────▼──────────────┐
+             │  gsdd-audit-milestone       │
+             └─────────────────────────────┘
+```
+
+Optional closure and milestone-continuation workflows in the shipped surface:
+
+- `gsdd-verify-work` adds conversational UAT when user-facing behavior needs explicit validation.
+- `gsdd-plan-milestone-gaps` turns audit findings into gap-closure phases when a milestone is not ready to ship.
+- `gsdd-complete-milestone` archives a shipped milestone, evolves `SPEC.md`, and collapses `ROADMAP.md`.
+- `gsdd-new-milestone` starts the next milestone after closure.
+
+### Planning Agent Coordination
+
+```
+  gsdd-plan (phase N)
+         │
+         ├── Phase Researcher (x4 parallel)
+         │     ├── Stack researcher
+         │     ├── Features researcher
+         │     ├── Architecture researcher
+         │     └── Pitfalls researcher
+         │           │
+         │     ┌─────▼───────┐
+         │     │ RESEARCH.md │
+         │     └─────┬───────┘
+         │           │
+         │     ┌─────▼──────┐
+         │     │  Planner   │  <- Reads SPEC.md, ROADMAP.md, RESEARCH.md
+         │     └─────┬──────┘
+         │           │
+         │     ┌─────▼──────────────┐     ┌────────┐
+         │     │  Plan Checker      │────>│ PASS?  │
+         │     │  (fresh context,   │     └───┬────┘
+         │     │   7 dimensions,    │         │
+         │     │   typed JSON)      │    Yes  │  No
+         │     └────────────────────┘     │   │   │
+         │                                │   └───┘  (max 3 cycles)
+         │                                │
+         │                          ┌─────▼──────┐
+         │                          │ PLAN files │
+         │                          └────────────┘
+         └── Done
+```
+
+The plan checker runs in a **separate context window** from the planner. This prevents the checker from inheriting the planner's blind spots — the same reasoning error that produced the plan cannot suppress the review of that plan. This is the [ICLR-validated](https://arxiv.org/abs/2310.01798) pattern for LLM self-refinement.
+
+The 7 check dimensions: requirement coverage, task completeness, dependency correctness, key-link completeness, scope sanity, must-have quality, context compliance.
+
+### Execution Wave Coordination
+
+```
+  gsdd-execute (phase N)
+         │
+         ├── Analyze plan dependencies
+         │
+         ├── Wave 1 (independent plans):
+         │     ├── Executor A (fresh 200K context) -> commit
+         │     └── Executor B (fresh 200K context) -> commit
+         │
+         ├── Wave 2 (depends on Wave 1):
+         │     └── Executor C (fresh 200K context) -> commit
+         │
+         └── Phase summary written to disk
+```
+
+### Brownfield Workflow (Existing Codebase)
+
+```
+  Brownfield repo
+        │
+        ├── bounded change already concrete
+        │        │
+        │        ▼
+        │   gsdd-quick
+        │   bounded feature work
+        │   with inline baseline
+        │
+        ├── repo unfamiliar / risky / deeper orientation needed
+        │        │
+        │        ▼
+        │   gsdd-map-codebase
+        │        │
+        │        └── continue with gsdd-quick or gsdd-new-project
+        │
+        └── fuzzy scope / full lifecycle setup
+                 │
+                 ▼
+           gsdd-new-project
+           canonical initializer
+```
+
+### Verification Gate
+
+```
+  gsdd-verify (phase N)
+         │
+         ├── Level 1: EXISTS
+         │     └── Do the expected files exist?
+         │
+         ├── Level 2: SUBSTANTIVE
+         │     └── Is the code real, not stubs?
+         │
+         ├── Level 3: WIRED
+         │     └── Is it connected and functional?
+         │
+         └── Anti-pattern scan
+               └── TODO/FIXME/HACK markers, empty catches
+```
+
+---
+
+## Command Reference
+
+### Workflows (run via generated skills or adapters)
+
+| Workflow | Purpose | When to Use |
+|----------|---------|-------------|
+| `gsdd-new-project` | Full project init: questioning, brownfield audit when needed, research, spec, roadmap | Greenfield, fuzzy brownfield scope, or full lifecycle setup |
+| `gsdd-map-codebase` | Map existing codebase for reusable brownfield context | When the repo is unfamiliar, risky, or you want a deeper baseline before choosing `quick` vs `new-project` |
+| `gsdd-plan` | Research + plan + adversarial check for current phase; writes planning artifacts only | Before executing a phase |
+| `gsdd-execute` | Execute phase plans in parallel waves | After planning is complete |
+| `gsdd-verify` | 3-level verification gate + anti-pattern scan | After execution completes |
+| `gsdd-verify-work` | Conversational UAT validation with structured gap tracking | When user-facing behavior needs explicit validation beyond repo artifacts |
+| `gsdd-audit-milestone` | Cross-phase integration, requirements coverage, E2E flows | When all phases are done |
+| `gsdd-complete-milestone` | Archive a shipped milestone, evolve `SPEC.md`, collapse `ROADMAP.md` | When the audited milestone is ready to ship |
+| `gsdd-new-milestone` | Start the next milestone with goals, requirements, and roadmap phases | After closing a milestone and starting the next one |
+| `gsdd-plan-milestone-gaps` | Turn milestone audit findings into gap-closure phases | When audit findings need planned follow-up before shipment |
+| `gsdd-quick` | Plan and execute sub-hour work outside the phase cycle | Bug fixes, small features, config changes when the bounded change is already concrete |
+| `gsdd-pause` | Save session context to checkpoint | Stopping mid-phase |
+| `gsdd-resume` | Restore context from checkpoint and route to next action | Starting a new session |
+| `gsdd-progress` | Show project status and route to next action | "Where am I?" |
+
+### CLI Commands
+
+| Command | Purpose |
+|---------|---------|
+| `gsdd init [--tools <platform>]` | Set up `.planning/`, generate adapters |
+| `gsdd update [--tools <platform>]` | Regenerate adapters from latest sources |
+| `gsdd update --templates` | Refresh role contracts and delegates (warns about user modifications) |
+| `gsdd find-phase [N]` | Show phase info as JSON (for agent consumption) |
+| `gsdd verify <N>` | Run artifact checks for phase N |
+| `gsdd scaffold phase <N> [name]` | Create a new phase plan file |
+| `gsdd models show` | Display effective model state across all runtimes |
+| `gsdd models profile <tier>` | Set global model profile (`quality`/`balanced`/`budget`) |
+| `gsdd models agent-profile --agent <id> --profile <tier>` | Per-agent semantic override |
+| `gsdd models set --runtime <rt> --agent <id> --model <id>` | Exact runtime model override |
+| `gsdd models clear --runtime <rt> --agent <id>` | Remove runtime override |
+| `gsdd help` | Show all commands |
+
+Workflow-embedded helper commands use `node .planning/bin/gsdd.mjs ...`, so lifecycle preflight, file-op, and phase-status mechanics do not depend on a global `gsdd` binary after init.
+
+### Platform flags for `--tools`
+
+| Flag | What's generated |
+|------|-----------------|
+| `claude` | `.claude/skills/`, `.claude/commands/`, `.claude/agents/` |
+| `opencode` | `.opencode/commands/`, `.opencode/agents/` |
+| `codex` | `.codex/agents/gsdd-plan-checker.toml` (portable skill is always generated; `$gsdd-plan` stays plan-only until explicit `$gsdd-execute`) |
+| `agents` | Bounded fallback block in root `AGENTS.md` |
+| `all` | All of the above |
+| *(none)* | Auto-detect installed tools |
+
+---
+
+## Configuration Reference
+
+`gsdd init` creates `.planning/config.json` interactively (or with defaults via `--auto`).
+
+### Full config.json Schema
+
+```json
+{
+  "researchDepth": "balanced",
+  "parallelization": true,
+  "commitDocs": true,
+  "modelProfile": "balanced",
+  "workflow": {
+    "research": true,
+    "planCheck": true,
+    "verifier": true
+  },
+  "gitProtocol": {
+    "branch": "Follow existing repo conventions",
+    "commit": "Logical grouping, no phase/task IDs",
+    "pr": "Follow existing review workflow"
+  }
+}
+```
+
+### Core Settings
+
+| Setting | Options | Default | What it Controls |
+|---------|---------|---------|------------------|
+| `researchDepth` | `fast`, `balanced`, `deep` | `balanced` | Research thoroughness per phase |
+| `parallelization` | `true`, `false` | `true` | Run independent agents simultaneously |
+| `commitDocs` | `true`, `false` | `true` | Track `.planning/` in git |
+| `modelProfile` | `balanced`, `quality`, `budget` | `balanced` | Portable semantic model tier |
+
+### Workflow Toggles
+
+Each adds quality but costs tokens and time:
+
+| Setting | Default | What it Controls |
+|---------|---------|------------------|
+| `workflow.research` | `true` | Research domain before planning each phase |
+| `workflow.planCheck` | `true` | Fresh-context adversarial plan checking (max-3 cycle loop) |
+| `workflow.verifier` | `true` | 3-level verification gate after execution |
+
+Disable these to speed up phases in familiar domains or when conserving tokens. Disabling `planCheck` engages reduced-assurance mode — the planner self-checks but without the independent reviewer.
+
+### Model Control
+
+Optional keys for fine-grained model selection:
+
+| Setting | What it Controls |
+|---------|------------------|
+| `agentModelProfiles.<agent>` | Per-agent semantic override (currently: `plan-checker`) |
+| `runtimeModelOverrides.<runtime>.<agent>` | Exact runtime-native model override |
+
+Supported runtimes: `claude`, `opencode`, `codex`.
+
+Runtime behavior:
+- **Claude** translates semantic tiers to native aliases (`opus`/`sonnet`/`haiku`) for the checker agent
+- **OpenCode** inherits its runtime model by default; Workspine only injects a model when you set an explicit runtime override
+- **Codex** inherits its session model by default; Workspine only injects a model in the TOML when you set an explicit runtime override
+
+### Git Protocol
+
+Advisory defaults — repository and team conventions take precedence:
+
+| Setting | Default |
+|---------|---------|
+| `gitProtocol.branch` | Follow existing repo conventions |
+| `gitProtocol.commit` | Logical grouping, no framework-imposed format |
+| `gitProtocol.pr` | Follow existing review workflow |
+
+Workspine does not impose commit formats, branch naming, or one-commit-per-task rules.
+
+---
+
+## Usage Examples
+
+### New Project (Full Cycle)
+
+`npx gsdd-cli init`
+
+Cursor, Copilot, and Gemini use the same core workflow through installed `.agents/skills/` surfaces. The difference is runtime proof and ergonomics, not workflow shape.
+
+- `Claude/OpenCode`: `/gsdd-new-project -> /gsdd-plan -> /gsdd-execute -> /gsdd-verify -> /gsdd-audit-milestone`
+- `Codex`: `$gsdd-new-project -> $gsdd-plan -> $gsdd-execute -> $gsdd-verify -> $gsdd-audit-milestone` (`$gsdd-plan` ends at plan creation; `$gsdd-execute` is a separate explicit unlock)
+- `Cursor / Copilot / Gemini`: `/gsdd-new-project -> /gsdd-plan -> /gsdd-execute -> /gsdd-verify -> /gsdd-audit-milestone` from the slash command menu once the skill is installed
+
+### Milestone Continuation
+
+- `Claude/OpenCode`: `/gsdd-plan-milestone-gaps` when audit findings need closure work, or `/gsdd-complete-milestone -> /gsdd-new-milestone` when the milestone is ready to ship
+- `Codex`: `$gsdd-plan-milestone-gaps` when audit findings need closure work, or `$gsdd-complete-milestone -> $gsdd-new-milestone` when the milestone is ready to ship
+- `Cursor / Copilot / Gemini`: use the matching slash commands once the skills are installed, with the same routing as above
+
+### Existing Codebase
+
+`npx gsdd-cli init`
+
+- `Claude/OpenCode`: `/gsdd-quick` for a concrete bounded change, `/gsdd-new-project` for fuzzy or milestone-shaped work, or `/gsdd-map-codebase` first when the repo needs a deeper brownfield baseline
+- `Codex`: `$gsdd-quick` for a concrete bounded change, `$gsdd-new-project` for fuzzy or milestone-shaped work, or `$gsdd-map-codebase` first when the repo needs a deeper brownfield baseline
+- `Cursor / Copilot / Gemini`: `/gsdd-quick`, `/gsdd-new-project`, or `/gsdd-map-codebase` from the slash command menu once the skills are installed, using the same routing rules above
+
+### Quick Bug Fix
+
+- `Claude/OpenCode`: `/gsdd-quick`
+- `Codex`: `$gsdd-quick`
+- `Cursor / Copilot / Gemini`: `/gsdd-quick` from the slash command menu once the skill is installed
+
+### Resuming After a Break
+
+- `Claude/OpenCode`: `/gsdd-progress` or `/gsdd-resume`
+- `Codex`: `$gsdd-progress` or `$gsdd-resume`
+- `Cursor / Copilot / Gemini`: use the matching skill from the slash command menu once installed
+
+### Pausing Mid-Work
+
+- `Claude/OpenCode`: `/gsdd-pause`
+- `Codex`: `$gsdd-pause`
+- `Cursor / Copilot / Gemini`: `/gsdd-pause` from the slash command menu once the skill is installed
+
+### Speed vs Quality Presets
+
+| Scenario | Research Depth | Model Profile | Research | Plan Check | Verifier |
+|----------|---------------|---------------|----------|------------|----------|
+| Prototyping | `fast` | `budget` | off | off | off |
+| Normal dev | `balanced` | `balanced` | on | on | on |
+| Production | `deep` | `quality` | on | on | on |
+
+### Headless Init (CI / Automation)
+
+```bash
+npx gsdd-cli init --auto --tools claude           # Non-interactive, default config
+npx gsdd-cli init --auto --tools claude --brief path/to/PRD.md  # Seed from existing document
+```
+
+---
+
+## Troubleshooting
+
+### Context Degradation During Long Sessions
+
+Clear your context window between major workflows. Workspine is designed around fresh contexts — every delegate gets a clean context window. If quality drops in the main session, clear and use `gsdd-resume` or `gsdd-progress` to restore state.
+
+### Plans Seem Wrong or Misaligned
+
+Check that research ran before planning (`workflow.research: true`). Most plan quality issues come from the planner making assumptions that domain research would have prevented. If plan-checking is enabled, the checker should catch alignment issues — but it cannot fix missing domain context.
+
+### Execution Produces Stubs
+
+Plans should have 2-5 tasks maximum. If tasks are too large, they exceed what a single context window can produce reliably. Re-plan with smaller scope.
+
+### Lost Track of Where You Are
+
+Run `gsdd-progress`. It reads all artifacts and tells you where you are and what to do next.
+
+### Need to Change Something After Execution
+
+Do not re-run `gsdd-execute`. Use `gsdd-quick` for targeted fixes, or `gsdd-verify` to systematically identify issues.
+
+### Template Refresh After Update
+
+```bash
+npx gsdd-cli update --templates       # Refreshes role contracts and delegates
+```
+
+If you've modified any templates, the generation manifest detects this and warns you before overwriting. The SHA-256 hash of each generated file is tracked in `.planning/generation-manifest.json`.
+
+### Model Costs Too High
+
+Switch to budget profile: `gsdd models profile budget`. Disable research and plan-check via config if the domain is familiar.
+
+---
+
+## Recovery Quick Reference
+
+| Problem | Solution |
+|---------|----------|
+| Lost context / new session | `gsdd-resume` or `gsdd-progress` |
+| Phase went wrong | `git revert` the phase commits, then re-plan |
+| Quick targeted fix | `gsdd-quick` |
+| Something broke | Use the debugger role for systematic debugging |
+| Costs running high | `gsdd models profile budget`, disable workflow toggles |
+| Templates out of date | `npx gsdd-cli update --templates` |
+| Adapters out of date | `npx gsdd-cli update` |
+
+---
+
+## Project File Structure
+
+```
+.planning/
+  SPEC.md                   # Living specification (goals, constraints, decisions)
+  ROADMAP.md                # Phased delivery plan with inline status
+  config.json               # Project configuration
+  bin/
+    gsdd.mjs                # Local workflow-helper launcher for embedded CLI mechanics
+  generation-manifest.json  # SHA-256 hashes for template versioning
+  .continue-here.md         # Session checkpoint (created by pause, consumed by resume)
+  research/                 # Domain research outputs
+  codebase/                 # Codebase maps (4 files: STACK, ARCHITECTURE, CONVENTIONS, CONCERNS)
+  phases/
+    XX-phase-name/
+      PLAN.md               # Atomic execution plans with XML task structure
+      SUMMARY.md            # Execution outcomes
+      VERIFICATION.md       # Post-execution verification results
+  quick/
+    NNN-slug/
+      PLAN.md               # Quick task plan
+      SUMMARY.md            # Quick task outcome
+  templates/
+    delegates/              # 11 delegate instruction files
+  LOG.md                    # Quick task log
+
+agents/                     # 10 canonical role contracts
+.agents/skills/gsdd-*/      # Portable workflow entrypoints (open standard)
+```
+
+Platform-specific adapters (generated by `gsdd init`):
+
+```
+.claude/skills/             # Claude Code skill files
+.claude/commands/           # Claude Code command aliases
+.claude/agents/             # Claude Code native agents
+
+.opencode/commands/         # OpenCode command files
+.opencode/agents/           # OpenCode native agents
+
+.codex/agents/              # Codex CLI agent TOML files
+
+AGENTS.md                   # Governance fallback block (useful for agents that consume AGENTS.md)
+```

package/docs/VERIFICATION-DISCIPLINE.md

@@ -0,0 +1,59 @@
+# Verification Discipline
+
+Workspine is not just a set of prompts. Its core delivery claim depends on explicit checking and verification loops that survive across runtimes.
+
+## The delivery contract
+
+The durable loop is:
+
+`init -> plan -> execute -> verify`
+
+Within that loop, the framework preserves two important review seams.
+
+### 1. Plan checking
+
+`gsdd-plan` does not stop at "write a plan."
+
+It includes a review loop where the plan is checked against concrete dimensions such as:
+
+- requirement coverage
+- task completeness
+- dependency correctness
+- scope sanity
+- context compliance
+
+On runtimes with stronger native support, that can be a fresh-context checker path. On weaker surfaces, the framework stays honest about reduced assurance instead of pretending the same check happened.
+
+### 2. Verification after execution
+
+`gsdd-verify` uses a three-level gate:
+
+- **Exists** — the expected artifacts are present
+- **Substantive** — the output is real, not empty or stubbed
+- **Wired** — the behavior is connected and actually works
+
+This is paired with anti-pattern checks so "files exist" does not get mistaken for "the work is done."
+
+## Anti-false-closure in practice
+
+The exported brownfield proof pack demonstrates the intended behavior:
+
+- the first implementation missed a real requirement
+- verification caught it
+- the repo then recorded the fix and the successful re-verification
+
+See `docs/BROWNFIELD-PROOF.md` for the reader-facing narrative and `docs/proof/consumer-node-cli/README.md` for the tracked artifact chain.
+
+## What this note does and does not claim
+
+This note explains the release-floor discipline that Workspine can prove publicly today.
+
+It does **not** claim:
+
+- perfect parity of checker mechanics on every runtime
+- autonomous orchestration platform behavior
+- proof of every possible brownfield workflow shape
+
+It claims something narrower and more defensible:
+
+Workspine keeps a repo-native delivery contract with explicit review and verification seams, and that contract is already strong enough to catch and recover from real misses.

package/docs/claude/context-monitor.md

@@ -0,0 +1,98 @@
+> **Claude Code only.** This feature uses Claude Code's `statusLine` and `PostToolUse` hook APIs. Other platforms do not support this hook mechanism.
+
+# Context Window Monitor
+
+A PostToolUse hook that warns the agent when context window usage is high.
+
+## Problem
+
+The statusline shows context usage to the **user**, but the **agent** has no awareness of context limits. When context runs low, the agent continues working until it hits the wall — potentially mid-task with no state saved.
+
+## How It Works
+
+1. The statusline hook writes context metrics to `/tmp/claude-ctx-{session_id}.json`
+2. After each tool use, the context monitor reads these metrics
+3. When remaining context drops below thresholds, it injects a warning as `additionalContext`
+4. The agent receives the warning in its conversation and can act accordingly
+
+## Thresholds
+
+| Level | Remaining | Agent Behavior |
+|-------|-----------|----------------|
+| Normal | > 35% | No warning |
+| WARNING | <= 35% | Wrap up current task, avoid starting new complex work |
+| CRITICAL | <= 25% | Stop immediately, save state (`gsdd-pause`) |
+
+## Debounce
+
+To avoid spamming the agent with repeated warnings:
+- First warning always fires immediately
+- Subsequent warnings require 5 tool uses between them
+- Severity escalation (WARNING -> CRITICAL) bypasses debounce
+
+## Architecture
+
+```
+Statusline Hook (gsd-statusline.js)
+    | writes
+    v
+/tmp/claude-ctx-{session_id}.json
+    ^ reads
+    |
+Context Monitor (gsd-context-monitor.js, PostToolUse)
+    | injects
+    v
+additionalContext -> Agent sees warning
+```
+
+The bridge file is a simple JSON object:
+
+```json
+{
+  "session_id": "abc123",
+  "remaining_percentage": 28.5,
+  "used_pct": 71,
+  "timestamp": 1708200000
+}
+```
+
+## Integration with GSDD
+
+GSDD's `gsdd-pause` workflow saves execution state to `.planning/.continue-here.md`. The WARNING message suggests using it. The CRITICAL message instructs immediate state save.
+
+## Setup
+
+Register both hooks manually in your Claude Code settings:
+
+- **Statusline** (writes bridge file): Registered as `statusLine` in settings.json
+- **Context Monitor** (reads bridge file): Registered as `PostToolUse` hook in settings.json
+
+Manual registration in `~/.claude/settings.json`:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "node ~/.claude/hooks/gsd-statusline.js"
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ~/.claude/hooks/gsd-context-monitor.js"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Safety
+
+- The hook wraps everything in try/catch and exits silently on error
+- It never blocks tool execution — a broken monitor should not break the agent's workflow
+- Stale metrics (older than 60s) are ignored
+- Missing bridge files are handled gracefully (subagents, fresh sessions)

package/docs/proof/consumer-node-cli/README.md

@@ -0,0 +1,37 @@
+# Consumer Node CLI Proof Pack
+
+This tracked proof pack is the public export of the Phase 22 release-floor brownfield run. It preserves the smallest artifact chain a reader needs to inspect the real consumer story without opening local-only planning state.
+
+## What is in this pack
+
+- `brief.md` — the original project brief
+- `SPEC.md` — the consumer spec created from that brief
+- `ROADMAP.md` — the single-phase roadmap used for the proof run
+- `phases/01-foundation/01-01-PLAN.md` — the execution plan
+- `phases/01-foundation/01-01-SUMMARY.md` — the execution summary
+- `phases/01-foundation/01-VERIFICATION.md` — the verification record that captured the miss and the fix
+
+## Release-floor story
+
+The proof pack shows one full release-floor loop:
+
+1. `gsdd init` created a real consumer workspace with portable skills and Codex checker support.
+2. The brief required both the default greeting and the `--name Ada` greeting path.
+3. The first implementation shipped `Hello, world!` for both commands, so verification failed for the named greeting.
+4. The implementation and tests were corrected, then verification passed with `Hello, Ada!`.
+
+## Key proof strings
+
+- `node index.js` -> `Hello, world!`
+- `node index.js --name Ada` -> `Hello, Ada!`
+- `--name Ada` appears in both the brief and the phase artifacts
+
+## Provenance and scope
+
+- Exported from the Phase 22 launch-proof consumer run.
+- This is the tracked reader-facing release-floor proof surface.
+- The local `.planning/live-proof/consumer-node-cli` tree remains evidence-only source material and is intentionally not the public entry surface.
+
+## Why this pack exists
+
+Public proof should be inspectable from tracked docs. This pack keeps the concrete brownfield evidence in-repo while letting the local live-proof workspace stay an implementation input instead of the public citation target.

package/docs/proof/consumer-node-cli/ROADMAP.md

@@ -0,0 +1,14 @@
+# Roadmap
+
+- [x] **Phase 1: Foundation** - ship a runnable greeting CLI with one fast test command
+
+### Phase 1: Foundation
+**Goal:** Create a runnable `hello-proof` CLI that supports the default greeting, a `--name` override, and one immediate automated test command.
+**Success Criteria:**
+- `node index.js` prints `Hello, world!`
+- `node index.js --name Ada` prints `Hello, Ada!`
+- `npm test` passes in a fresh clone
+
+### Current Phase
+
+Phase 1 is the active launch-proof phase.

package/docs/proof/consumer-node-cli/SPEC.md

@@ -0,0 +1,17 @@
+# Hello Proof Spec
+
+## Product
+
+`hello-proof` is a tiny framework-free Node CLI used to prove Workspine's launch flow in a fresh consumer repo.
+
+## Must-Have Requirements
+
+- `HP-01`: Running `node index.js` prints `Hello, world!`
+- `HP-02`: Running `node index.js --name Ada` prints `Hello, Ada!`
+- `HP-03`: A stranger can run one automated test command immediately after setup
+
+## Constraints
+
+- Keep the project intentionally small
+- Use plain Node.js without a framework
+- Document the run and test commands in `README.md`

package/docs/proof/consumer-node-cli/brief.md

@@ -0,0 +1,9 @@
+# Hello Proof
+
+Build a tiny Node CLI called `hello-proof`.
+
+Requirements:
+- Running `node index.js` prints `Hello, world!`
+- Running `node index.js --name Ada` prints `Hello, Ada!`
+- Include one automated test command that a stranger can run immediately
+- Keep the project intentionally small and framework-free