gsdd-cli 0.18.5 → 0.19.1

package/docs/VERIFICATION-DISCIPLINE.md

@@ -1,59 +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.
+# 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

@@ -1,98 +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)
+> **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

@@ -1,37 +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.
+# 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

@@ -1,14 +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.
+# 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

@@ -1,17 +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`
+# 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

@@ -1,9 +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
+# 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

package/docs/proof/consumer-node-cli/phases/01-foundation/01-01-PLAN.md

@@ -1,34 +1,34 @@
----
-phase: 01-foundation
-plan: 01
-runtime: codex-cli
-assurance: self_checked
----
-
-# Phase 1 Plan
-
-## Objective
-
-Ship the first runnable version of `hello-proof` and document how to run and test it.
-
-## Tasks
-
-<task id="01-01" type="code">
-  <files>
-    - CREATE: package.json
-    - CREATE: index.js
-    - CREATE: tests/cli.test.cjs
-    - CREATE: README.md
-  </files>
-  <action>
-    Create a minimal Node CLI with a default greeting, add one automated test command, and document how to run it.
-  </action>
-  <verify>
-    - `node index.js`
-    - `node index.js --name Ada`
-    - `npm test`
-  </verify>
-  <done>
-    The CLI runs locally, the test command is wired, and README explains the run/test path.
-  </done>
-</task>
+---
+phase: 01-foundation
+plan: 01
+runtime: codex-cli
+assurance: self_checked
+---
+
+# Phase 1 Plan
+
+## Objective
+
+Ship the first runnable version of `hello-proof` and document how to run and test it.
+
+## Tasks
+
+<task id="01-01" type="code">
+  <files>
+    - CREATE: package.json
+    - CREATE: index.js
+    - CREATE: tests/cli.test.cjs
+    - CREATE: README.md
+  </files>
+  <action>
+    Create a minimal Node CLI with a default greeting, add one automated test command, and document how to run it.
+  </action>
+  <verify>
+    - `node index.js`
+    - `node index.js --name Ada`
+    - `npm test`
+  </verify>
+  <done>
+    The CLI runs locally, the test command is wired, and README explains the run/test path.
+  </done>
+</task>

package/docs/proof/consumer-node-cli/phases/01-foundation/01-01-SUMMARY.md

@@ -1,10 +1,10 @@
----
-phase: 01-foundation
-plan: 01
-runtime: codex-cli
-assurance: self_checked
----
-
-# Phase 1 Summary
-
-Created the first runnable `hello-proof` CLI, added a fast Node test command, documented how to run and test the project, and completed the missing `--name` greeting path after verification caught it.
+---
+phase: 01-foundation
+plan: 01
+runtime: codex-cli
+assurance: self_checked
+---
+
+# Phase 1 Summary
+
+Created the first runnable `hello-proof` CLI, added a fast Node test command, documented how to run and test the project, and completed the missing `--name` greeting path after verification caught it.

package/docs/proof/consumer-node-cli/phases/01-foundation/01-VERIFICATION.md

@@ -1,30 +1,30 @@
----
-phase: 01-foundation
-runtime: codex-cli
-assurance: self_checked
-status: passed
----
-
-# Phase 1 Verification
-
-## Initial Verification
-
-- `node index.js` -> `Hello, world!`
-- `node index.js --name Ada` -> `Hello, world!`
-- `npm test` -> passed, but only covered the default greeting
-
-Result: failed. The phase goal required the named greeting path, and the implementation ignored the provided `--name` value.
-
-## Fix Applied
-
-- Updated `index.js` to read the value after `--name`
-- Extended `tests/cli.test.cjs` to assert the named greeting path
-- Updated the phase summary to reflect the verification-driven fix
-
-## Re-Verification
-
-- `node index.js` -> `Hello, world!`
-- `node index.js --name Ada` -> `Hello, Ada!`
-- `npm test` -> passed with both greeting paths covered
-
-Result: passed. The phase now satisfies all three roadmap success criteria.
+---
+phase: 01-foundation
+runtime: codex-cli
+assurance: self_checked
+status: passed
+---
+
+# Phase 1 Verification
+
+## Initial Verification
+
+- `node index.js` -> `Hello, world!`
+- `node index.js --name Ada` -> `Hello, world!`
+- `npm test` -> passed, but only covered the default greeting
+
+Result: failed. The phase goal required the named greeting path, and the implementation ignored the provided `--name` value.
+
+## Fix Applied
+
+- Updated `index.js` to read the value after `--name`
+- Extended `tests/cli.test.cjs` to assert the named greeting path
+- Updated the phase summary to reflect the verification-driven fix
+
+## Re-Verification
+
+- `node index.js` -> `Hello, world!`
+- `node index.js --name Ada` -> `Hello, Ada!`
+- `npm test` -> passed with both greeting paths covered
+
+Result: passed. The phase now satisfies all three roadmap success criteria.