gsdd-cli 0.18.5 → 0.19.0

package/docs/BROWNFIELD-PROOF.md

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

package/docs/RUNTIME-SUPPORT.md

@@ -1,84 +1,95 @@
-# Runtime Support Matrix
-
+# Runtime Support Matrix
+
 Workspine is a repo-native delivery spine with portable multi-runtime workflow surfaces, but the proof bar is not the same for every runtime today.
-
-This matrix is the release-floor truth surface.
-
-## Support tiers
-
-### Directly validated
-
-The workflow contract has direct repo proof for these runtimes:
-
-- **Claude Code**
-- **Codex CLI**
-- **OpenCode**
-
-These are the strongest public runtime claims.
-
-### Same core workflow
-
+
+This matrix is the release-floor truth surface.
+
+Human setup and repair commands in this document use `npx -y gsdd-cli ...` because that works without a global install. If you installed `gsdd-cli` globally, the equivalent bare `gsdd ...` command is fine.
+
+## Support tiers
+
+### Directly validated
+
+The workflow contract has direct repo proof for these runtimes:
+
+- **Claude Code**
+- **Codex CLI**
+- **OpenCode**
+
+These are the strongest public runtime claims.
+
+### Qualified support
+
 These runtimes use the same portable workflow surfaces, but they do not carry equal runtime proof or equal ergonomics today:
-
-- **Cursor**
-- **GitHub Copilot**
-- **Gemini CLI**
-
-### Fallback / manual use
-
-Any tool that can read the generated markdown workflows can still use the framework manually, but that is outside the current native-proof story.
-
+
+- **Cursor**
+- **GitHub Copilot**
+- **Gemini CLI**
+
+Codex CLI support means the terminal Codex CLI runtime. It does not automatically prove equal behavior in the Codex VS Code extension or Codex app; for those surfaces, use native discovery when available or open/paste the generated skill file manually.
+
+### Fallback / manual use
+
+Any tool that can read the generated markdown workflows can still use the framework manually, but that is outside the current native-proof story.
+
 ## Current runtime surfaces
 
 Two surfaces matter for users:
 
 - `.agents/skills/gsdd-*` is the shared workflow entry surface. Depending on the runtime, users invoke those workflows as `/gsdd-*`, `$gsdd-*`, or by opening the skill markdown directly.
 - `.planning/bin/gsdd*` is an internal local helper surface used by workflow-embedded lifecycle mechanics after init. It is not the primary user entry surface.
-
+
 | Runtime | Current claim | Entry surface | Notes |
 | --- | --- | --- | --- |
-| Claude Code | Directly validated | `.claude/skills/`, `.claude/commands/`, `.claude/agents/` | Native surface was a mandatory Phase 32 validation target; installed generated files are freshness-checked locally |
+| Claude Code | Directly validated | `.claude/skills/`, `.claude/commands/`, `.claude/agents/` | Native surface has direct lifecycle evidence; installed generated files are freshness-checked locally |
 | OpenCode | Directly validated | `.opencode/commands/`, `.opencode/agents/` | Native command and checker path; installed generated files are freshness-checked locally |
-| Codex CLI | Directly validated | `.agents/skills/gsdd-*` plus `.codex/agents/gsdd-plan-checker.toml` | Portable skill entry remains the user workflow surface; the native checker adapter supports plan checking |
-| Cursor | Same core workflow | `.agents/skills/gsdd-*` | Skills-native path; generated skill files are freshness-checked locally, but the runtime is not claimed as parity-validated |
-| GitHub Copilot | Same core workflow | `.agents/skills/gsdd-*` | Skills-native path; generated skill files are freshness-checked locally, but the runtime is not claimed as parity-validated |
-| Gemini CLI | Same core workflow | `.agents/skills/gsdd-*` | Skills-native path; governance is optional, generated skill files are freshness-checked locally, and parity is not claimed |
-
-## Generated-surface freshness
-
+| Codex CLI | Directly validated | `.agents/skills/gsdd-*` plus `.codex/agents/gsdd-plan-checker.toml` | Portable skill entry, native checker adapter, direct lifecycle evidence, and generated-surface freshness checks |
+| Codex VS Code / app | Fallback only | `.agents/skills/gsdd-*` opened or pasted manually unless discovery is available | Separate product surface from Codex CLI; no equal runtime-proof claim |
+| Cursor | Qualified support | `.agents/skills/gsdd-*` | Skill/slash path when discovery is available; generated skill files are freshness-checked locally, but the runtime is not claimed as parity-validated |
+| GitHub Copilot | Qualified support | `.agents/skills/gsdd-*` | Skill/slash path when discovery is available; generated skill files are freshness-checked locally, but the runtime is not claimed as parity-validated |
+| Gemini CLI | Qualified support | `.agents/skills/gsdd-*` | Skill/slash path when discovery is available; governance is optional, generated skill files are freshness-checked locally, and parity is not claimed |
+
+## Generated-surface freshness
+
 The authored source contract stays in `distilled/workflows/*`. Generated runtime-facing files are trusted only through deterministic rendering:
 
-- `gsdd health` compares any installed generated surfaces under `.planning/bin/`, `.agents/skills/`, `.claude/`, `.opencode/`, and `.codex/` against current render output.
-- `npx gsdd-cli update` regenerates drifted generated surfaces from the authored workflow and delegate sources.
+- `npx -y gsdd-cli health` compares any installed generated surfaces under `.agents/skills/`, `.planning/bin/`, `.claude/`, `.opencode/`, and `.codex/` against current render output.
+- Workflow-internal deterministic helper commands run through `node .planning/bin/gsdd.mjs ...`.
+- `npx -y gsdd-cli update` regenerates drifted generated surfaces from the authored workflow and delegate sources.
+- Bare `gsdd health` and `gsdd update` are equivalent only when `gsdd-cli` is globally installed.
 - Missing generated surfaces are not treated as drift unless the corresponding runtime surface is actually installed locally.
 
-This is a generated-surface repair story, not a blanket runtime-parity claim. `health` and `update` can tell you whether installed files are current and can deterministically regenerate them. They cannot make an unsupported runtime become directly validated.
-
-## What stays portable
-
-The portable invariant for this release is the workflow contract:
-
-- planning
-- checking and revision loops
-- execution discipline
-- verification
-- handoff and durable repo artifacts
-
-## What does not stay equal yet
-
-This release does **not** claim that every runtime has:
-
-- the same native adapter richness
-- the same invocation ergonomics
-- the same validation depth
-- the same checker/orchestration mechanics
-
-Portable contract does not mean equal UX everywhere.
-
-## Proof references
-
-- `README.md`
-- `docs/BROWNFIELD-PROOF.md`
-- `docs/proof/consumer-node-cli/README.md`
-- `docs/VERIFICATION-DISCIPLINE.md`
-- `gsdd health` / `npx gsdd-cli update`
+## Entry and helper surfaces
+
+- `.agents/skills/gsdd-*/SKILL.md` is the compact open-standard workflow entry surface. Agents read these files to know what workflow to run.
+- `.planning/bin/gsdd.mjs` is the internal repo-local helper runtime. Generated workflows use `node .planning/bin/gsdd.mjs ...` for deterministic file, lifecycle, and status helpers instead of depending on an ambient global binary.
+- Native adapter and governance surfaces are optional ergonomics. They can improve discovery or routing in a specific runtime, but they are not required for the portable workflow contract.
+
+## What stays portable
+
+The portable invariant for this release is the workflow contract:
+
+- planning
+- checking and revision loops
+- execution discipline
+- verification
+- handoff and durable repo artifacts
+
+## What does not stay equal yet
+
+This release does **not** claim that every runtime has:
+
+- the same native adapter richness
+- the same invocation ergonomics
+- the same validation depth
+- the same checker/orchestration mechanics
+
+Portable contract does not mean equal UX everywhere.
+
+## Proof references
+
+- `README.md`
+- `docs/BROWNFIELD-PROOF.md`
+- `docs/proof/consumer-node-cli/README.md`
+- `docs/VERIFICATION-DISCIPLINE.md`
+- `npx -y gsdd-cli health` / `npx -y gsdd-cli update` (or bare `gsdd ...` when globally installed)