gsdd-cli 0.25.0 → 0.26.0

package/bin/lib/workflows.mjs

@@ -0,0 +1,27 @@
+function defineWorkflow({ mutatesArtifacts = true, ...workflow }) {
+  return {
+    ...workflow,
+    mutatesArtifacts,
+    agent: mutatesArtifacts ? 'Code' : 'Plan',
+    opencodeType: mutatesArtifacts ? 'edit' : 'plan',
+  };
+}
+
+export const WORKFLOWS = [
+  defineWorkflow({ name: 'gsdd-new-project', workflow: 'new-project.md', description: 'New project - questioning, codebase audit, research, spec, roadmap' }),
+  defineWorkflow({ name: 'gsdd-map-codebase', workflow: 'map-codebase.md', description: 'Map or refresh codebase - 4 parallel mappers, staleness check, secrets scan' }),
+  defineWorkflow({ name: 'gsdd-plan', workflow: 'plan.md', description: 'Plan a phase - research check, backward planning, task creation' }),
+  defineWorkflow({ name: 'gsdd-execute', workflow: 'execute.md', description: 'Execute a phase plan - implement tasks, verify changes, follow repo git conventions' }),
+  defineWorkflow({ name: 'gsdd-verify', workflow: 'verify.md', description: 'Verify a completed phase - 3-level checks, anti-pattern scan' }),
+  defineWorkflow({ name: 'gsdd-verify-work', workflow: 'verify-work.md', description: 'Conversational UAT testing - validate user-facing behavior with structured gap tracking' }),
+  defineWorkflow({ name: 'gsdd-audit-milestone', workflow: 'audit-milestone.md', description: 'Audit a completed milestone - cross-phase integration, requirements coverage, E2E flows' }),
+  defineWorkflow({ name: 'gsdd-complete-milestone', workflow: 'complete-milestone.md', description: 'Complete milestone - archive, evolve spec, collapse roadmap' }),
+  defineWorkflow({ name: 'gsdd-new-milestone', workflow: 'new-milestone.md', description: 'New milestone - gather goals, define requirements, create roadmap phases' }),
+  defineWorkflow({ name: 'gsdd-plan-milestone-gaps', workflow: 'plan-milestone-gaps.md', description: 'Plan gap closure phases from audit results' }),
+  defineWorkflow({ name: 'gsdd-quick', workflow: 'quick.md', description: 'Quick task - plan and execute a sub-hour task outside the phase cycle' }),
+  defineWorkflow({ name: 'gsdd-pause', workflow: 'pause.md', description: 'Pause work - save session context for seamless resumption' }),
+  defineWorkflow({ name: 'gsdd-resume', workflow: 'resume.md', description: 'Resume work - restore context and route to next action' }),
+  defineWorkflow({ name: 'gsdd-progress', workflow: 'progress.md', description: 'Check progress - show project status and route to next action', mutatesArtifacts: false }),
+];
+
+export const FRAMEWORK_VERSION = 'v1.4';

package/distilled/README.md

@@ -1,9 +1,27 @@
 # Workspine
 
-A repo-native delivery spine for planning, checking, execution, verification, and handoff of long-horizon AI-assisted work.
+A repo-native delivery spine for the part of AI coding that still needs human judgment: planning, checking, execution, verification, and handoff.
 
 Workspine keeps planning, execution, verification, handoff, and progress state in the repo so work survives cold starts, runtime switches, and session loss. The retained package and CLI contracts remain `gsdd-cli` / `gsdd`.
 
+## Why It Matters
+
+AI coding agents make code cheaper to produce. They do not make architecture, scope control, review, security, or release confidence disappear. In practice, they move more of the work into deciding what should happen, checking whether it happened, and preserving enough context for the next session or runtime to continue safely.
+
+Workspine is built for that pressure. It gives serious AI-assisted work one repo-native path:
+
+```
+new-project -> plan -> execute -> verify
+```
+
+The plan is a reviewed contract before implementation starts. Execution is a separate step. Verification records what passed, what failed, and what still needs human judgment.
+
+## When To Use It
+
+Use Workspine when a change spans multiple files, sessions, agents, or runtimes; when architecture, data, security, or release confidence matter; or when proof needs to live in the repo instead of only in a chat transcript.
+
+Skip the full lifecycle for tiny, obvious edits. Direct prompting in your usual coding agent is cheaper for low-risk work. Workspine is for the work where guessing gets expensive.
+
 ## What This Is
 
 Workspine is a small set of workflow sources plus a CLI (`gsdd`) that:
@@ -22,7 +40,7 @@ Launch proof posture:
 - Directly validated in repo truth: Claude Code, Codex CLI, OpenCode
 - Qualified support only: Cursor, Copilot, Gemini CLI can use the shared `.agents/skills/` surface plus optional governance when their skill or slash discovery sees it; proof and ergonomics differ from the directly validated runtimes
 - Codex CLI validation does not automatically cover Codex VS Code or the Codex app; use native discovery there when available, otherwise open or paste `.agents/skills/gsdd-*/SKILL.md`
-- Installed generated runtime surfaces are renderer-checked locally through `npx -y gsdd-cli health`, with deterministic repair through `npx -y gsdd-cli update` (bare `gsdd ...` is equivalent only when globally installed)
+- Repo-local generated runtime surfaces are renderer-checked through `npx -y gsdd-cli health`, with deterministic repair through `npx -y gsdd-cli update` (bare `gsdd ...` is equivalent only when globally installed)
 - Public proof entrypoints: `docs/BROWNFIELD-PROOF.md`, `docs/proof/consumer-node-cli/README.md`, `docs/RUNTIME-SUPPORT.md`, `docs/VERIFICATION-DISCIPLINE.md`
 
 ## Quick Start
@@ -34,6 +52,15 @@ npx -y gsdd-cli init
 
 In a TTY, `npx -y gsdd-cli init` opens a guided install wizard: choose runtimes first, then decide separately whether repo-wide `AGENTS.md` governance is worth installing. If `gsdd-cli` is globally installed, `gsdd init` is the equivalent shorthand.
 
+For personal cross-repo availability, run:
+
+```bash
+npx -y gsdd-cli install --global
+npx -y gsdd-cli install --global --tools claude,opencode,codex,copilot
+```
+
+Global install writes selected Workspine skills and native agent surfaces into user-level agent homes. It does not create `.planning/` in the current repo.
+
 Optional adapters:
 ```bash
 npx -y gsdd-cli init --tools claude
@@ -78,7 +105,7 @@ Helper command for long-running sessions:
 ```
 npx -y gsdd-cli control-map [--json] [--with-ignored] -> computed repo/worktree/planning state plus local annotations
 npx -y gsdd-cli control-map annotate set|clear -> optional stale-aware local intent maintenance
-npx -y gsdd-cli closeout-report [--json] [--phase <N>] -> read-only replay of closeout blockers, warnings, and next safe action
+npx -y gsdd-cli closeout-report [--json] [--phase <N>] -> read-only replay of closeout blockers, warnings, fixes, and next safe action
 ```
 
 ## Brownfield Entry Contract

package/distilled/templates/agents.block.md

@@ -6,6 +6,7 @@ Lifecycle: `new-project -> plan -> execute -> verify -> audit-milestone`.
 
 Core skills: `gsdd-new-project`, `gsdd-plan`, `gsdd-execute`, `gsdd-verify`, `gsdd-progress`.
 Planning state: `.planning/`. Portable workflows: `.agents/skills/gsdd-*/SKILL.md`.
+Install/repair: `npx -y gsdd-cli init` creates repo-local skills and planning state; `npx -y gsdd-cli health` verifies repo-local generated surfaces; `npx -y gsdd-cli update` repairs repo-local drift. Global personal skills use `npx -y gsdd-cli install --global` and are repaired by rerunning that install for the selected targets.
 
 Invoke: `/gsdd-plan` (Claude, OpenCode; Cursor/Copilot/Gemini when skill discovery is available) · `$gsdd-plan` (Codex CLI, plan-only until `$gsdd-execute`) · open SKILL.md directly elsewhere.
 
@@ -18,4 +19,3 @@ Rules:
 6. Git guidance in `.planning/config.json` -> `gitProtocol` is advisory; follow the repo's own conventions first.
 
 If `.planning/` is missing, run `npx -y gsdd-cli init` then `gsdd-new-project`; bare `gsdd init` is equivalent only when globally installed.
-

package/distilled/templates/agents.md

@@ -3,4 +3,3 @@
 <!-- BEGIN GSDD -->
 {{GSDD_BLOCK}}
 <!-- END GSDD -->
-

package/distilled/templates/codebase/architecture.md

@@ -107,4 +107,3 @@ To find the most-imported file in a layer: grep for imports of each candidate fi
 ---
 
 *Architecture analysis: [date]*
-

package/distilled/templates/codebase/concerns.md

@@ -92,4 +92,3 @@ Ranking heuristic: a concern that blocks 3 change-routing rows ranks above one t
 ---
 
 *Concerns audit: [date]*
-

package/distilled/templates/codebase/conventions.md

@@ -190,4 +190,3 @@ If no single file exemplifies multiple conventions, list the best per-category f
 ---
 
 *Convention analysis: [date]*
-

package/distilled/templates/codebase/stack.md

@@ -93,4 +93,3 @@ Example (good):
 ---
 
 *Stack analysis: [date]*
-

package/distilled/templates/roadmap.md

@@ -71,4 +71,3 @@ For each v1 requirement in .planning/SPEC.md:
 
 If a requirement doesn't map to any phase: add a phase or expand an existing one.
 If a requirement maps to multiple phases: clarify which phase owns it.
-

package/distilled/templates/spec.md

@@ -107,4 +107,3 @@ When a major milestone completes:
 1. The SPEC.md "Current State" section reflects the new state
 2. Completed phases have summaries in `.planning/phases/{N}-SUMMARY.md`
 3. SPEC.md itself stays lean - don't accumulate history here
-

package/distilled/workflows/new-project.md

@@ -99,7 +99,7 @@ This is an internal prerequisite of `new-project`, not a user-facing routing req
 
 If `.planning/brownfield-change/CHANGE.md` exists, keep it as the current bounded continuity anchor while you do this work. Do not treat its presence as evidence that the user should have used another command instead. The only question is whether they intentionally want to widen that bounded brownfield change into full milestone planning.
 
-Read and follow `.agents/skills/gsdd-map-codebase/SKILL.md` now. Execute its full flow (check existing, spawn mappers, validate, secrets scan). When map-codebase completes, return here and continue from Brownfield Validated Requirements Inference below.
+Read and follow the `gsdd-map-codebase` skill now. Prefer the repo-local `.agents/skills/gsdd-map-codebase/SKILL.md` when it exists; otherwise use the globally installed `gsdd-map-codebase` skill available in the current runtime. Execute its full flow (check existing, spawn mappers, validate, secrets scan). When map-codebase completes, return here and continue from Brownfield Validated Requirements Inference below.
 
 ### Brownfield Validated Requirements Inference
 

package/docs/RUNTIME-SUPPORT.md

@@ -4,7 +4,11 @@ Workspine is a repo-native delivery spine with portable multi-runtime workflow s
 
 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.
+Human repo 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. For cross-repo personal use, `npx -y gsdd-cli install --global` installs reusable Workspine skills and native runtime surfaces into selected agent homes.
+
+The install contract is deliberately skills-first: `npx -y gsdd-cli init` always creates `.agents/skills/gsdd-*` and `.planning/bin/gsdd*`; runtime-specific adapters are optional discovery or orchestration helpers layered on top.
+
+Global install is separate from repo bootstrap. It does not create `.planning/`; it writes selected runtime surfaces under user-level agent homes and records Workspine ownership in per-runtime manifests.
 
 ## Support tiers
 
@@ -49,15 +53,31 @@ Two surfaces matter for users:
 | 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
+## Global install surfaces
+
+`npx -y gsdd-cli install --global` can install personal cross-repo surfaces for these targets:
+
+| Target | Global surfaces |
+| --- | --- |
+| Claude Code | `~/.claude/skills`, `~/.claude/commands`, `~/.claude/agents` |
+| OpenCode | `~/.agents/skills`, `~/.config/opencode/commands`, `~/.config/opencode/agents` |
+| Codex CLI | `~/.agents/skills`, `~/.codex/agents` |
+| GitHub Copilot CLI | `~/.agents/skills`, `~/.copilot/agents` |
+
+Install availability is not a parity claim. GitHub Copilot CLI can receive global Workspine surfaces, but it remains in the qualified-support tier unless the release-floor proof for Copilot is raised deliberately.
+
+When `OPENCODE_CONFIG_DIR` is set, OpenCode commands and agents are installed under that custom config root. Skills remain under the shared agent-compatible global root (`~/.agents/skills`), which OpenCode, Codex CLI, and GitHub Copilot CLI can all discover.
+
+## Repo-Local Generated-Surface Freshness
 
 The authored source contract stays in `distilled/workflows/*`. Generated runtime-facing files are trusted only through deterministic rendering:
 
-- `npx -y gsdd-cli health` compares any installed generated surfaces under `.agents/skills/`, `.planning/bin/`, `.claude/`, `.opencode/`, and `.codex/` against current render output.
+- `npx -y gsdd-cli health` compares generated surfaces in the current repo-local `.planning/` workspace 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.
+- Global user-home installs are refreshed by rerunning `npx -y gsdd-cli install --global --tools <targets>`; global runtime probes remain an internal pressure-harness concern, not a public install flag.
 
 ## Entry and helper surfaces
 

package/docs/USER-GUIDE.md

@@ -4,8 +4,24 @@ A detailed reference for Workspine workflows, troubleshooting, and configuration
 
 ---
 
+## Fast Path
+
+For a new project or a broad brownfield effort:
+
+1. Run `npx -y gsdd-cli init` from the repo root.
+2. Start with `gsdd-new-project` unless the change is already small and concrete.
+3. Review the plan from `gsdd-plan` before starting `gsdd-execute`.
+4. Run `gsdd-verify` before calling the phase done.
+
+Use `npx -y gsdd-cli init` for repo-local setup. Use `npx -y gsdd-cli install --global` to install reusable Workspine skills and native runtime surfaces into selected agent homes without creating `.planning/` in the current repo.
+
+For a bounded existing-code change, use `gsdd-quick`. For an unfamiliar or risky repo, use `gsdd-map-codebase` before choosing between `gsdd-quick` and `gsdd-new-project`.
+
+---
+
 ## Table of Contents
 
+- [Fast Path](#fast-path)
 - [Workflow Diagrams](#workflow-diagrams)
 - [Command Reference](#command-reference)
 - [Configuration Reference](#configuration-reference)
@@ -159,6 +175,24 @@ The 7 check dimensions: requirement coverage, task completeness, dependency corr
 
 ## Command Reference
 
+### Install Modes
+
+Use local repo install when the project should own `.planning/`, `.agents/skills`, and optional repo-local runtime adapters:
+
+```bash
+npx -y gsdd-cli init
+npx -y gsdd-cli init --auto --tools all
+```
+
+Use global agent install when you want Workspine workflows available across repos from your personal agent home:
+
+```bash
+npx -y gsdd-cli install --global
+npx -y gsdd-cli install --global --tools claude,opencode,codex,copilot
+```
+
+Global install writes Workspine-managed files under selected agent homes and records per-runtime manifests. It does not bootstrap project planning state.
+
 ### Workflows (run via generated skills or adapters)
 
 | Workflow | Purpose | When to Use |
@@ -186,6 +220,7 @@ The 7 check dimensions: requirement coverage, task completeness, dependency corr
 | `npx -y gsdd-cli update [--tools <platform>]` | Regenerate skills/adapters from latest sources |
 | `npx -y gsdd-cli update --templates` | Refresh role contracts and delegates (warns about user modifications) |
 | `npx -y gsdd-cli control-map [--json] [--with-ignored]` | Show computed repo/worktree/planning state, dirty buckets, optional ignored-path scan, local annotations, and safe next interventions |
+| `npx -y gsdd-cli closeout-report [--json] [--phase <N>]` | Read-only closeout replay: blockers, warnings, fixes, and next safe action (composed from control-map, health/preflight, verify, and UI-proof signals) |
 | `npx -y gsdd-cli find-phase [N]` | Show phase info as JSON (for agent consumption) |
 | `npx -y gsdd-cli verify <N>` | Run artifact checks for phase N |
 | `npx -y gsdd-cli scaffold phase <N> [name]` | Create a new phase plan file |
@@ -200,10 +235,11 @@ If `gsdd-cli` is globally installed, you can use the shorter `gsdd ...` form for
 
 Normal user flow:
 
-1. Run `npx gsdd-cli init`.
+1. Run `npx -y gsdd-cli init`.
 2. Enter workflows through your runtime surface: `/gsdd-*` or `$gsdd-*`.
-3. Use `gsdd health` to check installed generated surfaces.
-4. Use `npx gsdd-cli update` when generated surfaces drift or you want the latest shipped output.
+3. Use `npx -y gsdd-cli health` to check repo-local generated surfaces.
+4. Use `npx -y gsdd-cli update` when repo-local generated surfaces drift or you want the latest shipped output.
+5. For personal global installs, rerun `npx -y gsdd-cli install --global --tools <targets>` to repair or refresh selected agent homes.
 
 Surface split:
 
@@ -410,7 +446,7 @@ If you've modified any templates, the generation manifest detects this and warns
 
 ### Generated Surfaces Drift Or A Runtime Command Goes Missing
 
-Start with `gsdd health`. If it reports drift or missing installed generated surfaces, run `npx gsdd-cli update` for the whole workspace or `npx gsdd-cli update --tools <runtime>` for a specific runtime.
+In a repo-local `.planning/` workspace, start with `npx -y gsdd-cli health`. If it reports drift or missing installed generated surfaces, run `npx -y gsdd-cli update` for the whole workspace or `npx -y gsdd-cli update --tools <runtime>` for a specific runtime. For global personal installs, rerun `npx -y gsdd-cli install --global --tools <targets>`.
 
 That repair path is deterministic for generated files. It does not imply that every runtime has equal native ergonomics or equal validation depth.
 

package/docs/VERIFICATION-DISCIPLINE.md

@@ -2,6 +2,8 @@
 
 Workspine is not just a set of prompts. Its core delivery claim depends on explicit checking and verification loops that survive across runtimes.
 
+AI output is cheap enough that the scarce part is often proof: whether the change fits the codebase, whether the right behavior is wired in, and whether the remaining risk is visible to a human reviewer. Workspine treats that proof as part of the workflow, not as an optional cleanup note.
+
 ## The delivery contract
 
 The durable loop is:
@@ -46,7 +48,7 @@ See `docs/BROWNFIELD-PROOF.md` for the reader-facing narrative and `docs/proof/c
 
 ## What this note does and does not claim
 
-This note explains the release-floor discipline that Workspine can prove publicly today.
+This note explains the release-floor discipline that Workspine can prove publicly in this release.
 
 It does **not** claim:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsdd-cli",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Workspine — a repo-native delivery spine for long-horizon AI-assisted work, with directly validated support for Claude Code, Codex CLI, and OpenCode, published as gsdd-cli.",
   "type": "module",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "test": "npm run test:gsdd",
-    "test:gsdd": "node tests/gsdd.init.test.cjs && node tests/gsdd.models.test.cjs && node tests/gsdd.consumer-ceremony.test.cjs && node tests/gsdd.manifest.test.cjs && node tests/gsdd.plan.adapters.test.cjs && node tests/gsdd.audit-milestone.test.cjs && node tests/gsdd.invariants.test.cjs && node tests/gsdd.guards.test.cjs && node tests/gsdd.health.test.cjs && node tests/gsdd.scenarios.test.cjs && node tests/gsdd.cross-runtime.test.cjs && node tests/gsdd.control-map.test.cjs && node tests/gsdd.closeout-report.test.cjs && node tests/phase.test.cjs && node tests/session-fingerprint.test.cjs",
+    "test:gsdd": "node tests/gsdd.init.test.cjs && node tests/gsdd.models.test.cjs && node tests/gsdd.consumer-ceremony.test.cjs && node tests/gsdd.manifest.test.cjs && node tests/gsdd.plan.adapters.test.cjs && node tests/gsdd.global-install-pressure.test.cjs && node tests/gsdd.audit-milestone.test.cjs && node tests/gsdd.invariants.test.cjs && node tests/gsdd.guards.test.cjs && node tests/gsdd.health.test.cjs && node tests/gsdd.scenarios.test.cjs && node tests/gsdd.cross-runtime.test.cjs && node tests/gsdd.control-map.test.cjs && node tests/gsdd.closeout-report.test.cjs && node tests/gsdd.next.test.cjs && node tests/phase.test.cjs && node tests/session-fingerprint.test.cjs",
     "prepublishOnly": "node -e \"const ok=process.env.GITHUB_ACTIONS==='true'&&process.env.GITHUB_REF_NAME==='main'&&process.env.GITHUB_WORKFLOW==='Release'; if(!ok){console.error('Refusing to publish gsdd-cli outside the GitHub Actions Release workflow on main.'); process.exit(1)}\""
   },
   "devDependencies": {