gsdd-cli 0.24.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/DESIGN.md

@@ -2818,7 +2818,7 @@ Posture compatibility is part of that closeout contract: `repo_closeout` and `ru
 
 ## D62 - Repo-Native UI Proof Contract
 
-**Decision (2026-04-28; revised 2026-05-08):** UI-sensitive work should carry a compact planned proof-slot contract and, when executed, an observed UI proof bundle that references artifacts by path or link while preserving the existing closure evidence kinds: `code`, `test`, `runtime`, `delivery`, and `human`. For live rendered UI proof, `agent-browser` is the default runtime evidence path for consumers, while existing Playwright tests remain the canonical repeatable browser-regression path when present. The deterministic `ui-proof` validator remains provider-agnostic structural validation, but it now validates planned slot specificity, concise tool provenance, local artifact path existence when validating from files, raw-artifact safety for paths and URLs, and failed/partial proof classification so the workflow cannot degrade back into unstructured "looks good" review.
+**Decision (2026-04-28; revised 2026-05-09):** UI-sensitive work should carry a compact planned proof-slot contract and, when executed, an observed UI proof bundle that references artifacts by path or link while preserving the existing closure evidence kinds: `code`, `test`, `runtime`, `delivery`, and `human`. For live rendered UI proof, `agent-browser` is the default runtime evidence path for consumers, while existing Playwright tests remain the canonical repeatable browser-regression path when present. The deterministic `ui-proof` validator remains provider-agnostic structural validation, but it now validates planned slot specificity, concise tool provenance, local artifact path existence when validating from files, raw-artifact safety for paths and URLs, and failed/partial proof classification so the workflow cannot degrade back into unstructured "looks good" review. Direct phase verification also treats plan frontmatter as the UI-proof declaration authority and fails closed on missing phase prerequisites, empty `ui_proof_slots: []` without `no_ui_proof_rationale`, and invalid required UI proof.
 
 **Context:**
 - UI proof targets the recurring failure mode where agents claim a UI works or looks good without rendered proof, matched observations, or explicit human judgment.
@@ -2828,6 +2828,9 @@ Posture compatibility is part of that closeout contract: `repo_closeout` and `ru
 
 **Decision:**
 - Planning must classify UI-sensitive work and require either `ui_proof_slots` or an explicit `no_ui_proof_rationale`.
+- Direct phase verification must read `ui_proof_slots` and `no_ui_proof_rationale` from plan frontmatter only; body prose, fenced examples, and stale sidecars are not declaration authority.
+- Direct phase verification must fail nonzero with structured blockers when no matching plan or summary exists, or when `ui_proof_slots: []` lacks a nonblank `no_ui_proof_rationale`.
+- When an explicit no-UI rationale exists, stale UI-proof sidecars are warning-level cleanup signals, not proof and not blockers.
 - Planned slots record claim, route/state, required evidence kinds, minimum observations, expected artifact types, runnable validation command, environment/viewport, manual-acceptance requirement, claim limit, and requirement IDs.
 - Observed proof bundles record claim, requirement/slot IDs, route/state, environment, viewport, evidence inputs, commands/manual steps, observations, artifacts, privacy metadata, result, and claim limits.
 - Planned slots must be tight enough for the plan checker to reject vague proof: specific route/state, viewport rationale or narrowed claim limit, minimum observations, expected artifact types, runnable validation, and matchability back to the exact UI claim.
@@ -2853,7 +2856,7 @@ Posture compatibility is part of that closeout contract: `repo_closeout` and `ru
 - `distilled/templates/ui-proof.md`
 - `distilled/workflows/plan.md`, `distilled/workflows/execute.md`, `distilled/workflows/quick.md`, `distilled/workflows/verify.md`
 - `agents/planner.md`, `agents/executor.md`, `agents/verifier.md`, `distilled/templates/delegates/plan-checker.md`
-- `bin/lib/templates.mjs`, `bin/lib/ui-proof.mjs`, `bin/lib/health.mjs`, `bin/lib/rendering.mjs`
+- `bin/lib/templates.mjs`, `bin/lib/ui-proof.mjs`, `bin/lib/health.mjs`, `bin/lib/phase.mjs`, `bin/lib/rendering.mjs`
 - `tests/phase.test.cjs`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.health.test.cjs`, `tests/gsdd.init.test.cjs`
 - GSD comparison: the upstream planner, executor, and verifier role patterns preserve lifecycle rigor, but they do not define UI proof slots or planned-vs-observed UI proof bundles.
 - OneShot QC source: `https://github.com/oneshot-repo/OneShot/tree/main/skills`
@@ -2875,7 +2878,7 @@ Posture compatibility is part of that closeout contract: `repo_closeout` and `ru
 
 ## D63 - Computed-First Control Map
 
-**Decision (2026-05-08):** Long-running multi-agent and multi-worktree control uses a computed-first `gsdd control-map` helper rather than a new lifecycle workflow or a vendor session parser. The helper computes repo/worktree/planning truth live and overlays optional local annotations only for intent that git cannot know.
+**Decision (2026-05-08; revised 2026-05-09):** Long-running multi-agent and multi-worktree control uses a computed-first `gsdd control-map` helper rather than a new lifecycle workflow or a vendor session parser. The helper computes repo/worktree/planning truth live and overlays optional local annotations only for intent that git cannot know.
 
 **Context:**
 - Gap I52 showed that ordinary `git status` can be clean while sibling worktrees, detached runtime worktrees, ignored/generated surfaces, snapshots, dirty local WIP, and cleanup obligations remain unexplained.
@@ -2885,21 +2888,24 @@ Posture compatibility is part of that closeout contract: `repo_closeout` and `ru
 
 **Decision:**
 - Add `gsdd control-map [--json] [--with-ignored] [--annotations <path>]` to the main CLI and generated `.planning/bin/gsdd.mjs` helper runtime.
+- Add `gsdd control-map annotate set|clear` as the minimal mutation surface for local annotation intent. `set` creates or updates workspace-local annotation files with live branch/head snapshots, normalized write sets, cleanup state, owner/scope/next-step metadata, and stale-update refusal unless `--refresh` is explicit. `clear` removes an annotation by id or path, including stale or missing-worktree entries, without deleting branches, pruning worktrees, or cleaning files.
+- Add `gsdd closeout-report [--json] [--phase <N>]` as a read-only replay helper over the same local-state authority. It defaults to the latest completed phase and reports blockers, warnings, next safe action, control-map status, health/preflight status, direct phase verification, and UI-proof status without mutating ROADMAP status, fingerprints, annotations, branches, worktrees, generated surfaces, release state, or report files.
 - Compute authority from live git/worktree state first: canonical checkout, branch, HEAD, upstream divergence when comparable, tracked/untracked dirty buckets, optional ignored-path scans through `--with-ignored`, sibling git worktrees, detached/bare state, invalid git access, planning drift, checkpoint existence, lifecycle state, and repo-local runtime worktree directories.
-- Read optional annotations from `.planning/.local/control-map.annotations.json`. Annotations may record `runtime_owner`, intended scope, write set, cleanup state, proof state, next step, branch, and last known head.
+- Read optional annotations from `.planning/.local/control-map.annotations.json`. Annotations may record `runtime_owner`, intended scope, write set, cleanup state, next step, branch, last known head, and update timestamp.
 - Treat annotations as stale-checkable intent only. They never outrank repo truth, planning artifacts, or checkpoint reconciliation.
+- Emit explicit transition-risk semantics from computed truth: concrete annotation write-set overlap, live dirty-path/write-set overlap, upstream divergence, detached candidate worktrees, stale annotation mismatches, and tracked dirty canonical work behind upstream. Only concrete block-level risks should stop owned-write lifecycle transitions; ordinary dirty or detached local state remains warning-level guidance.
 - Keep transcript/session stores out of the helper. Vendor session evidence may support postmortems, but it is not live product truth.
 - Wire the control map into portable workflow behavior by having `progress`, `resume`, `pause`, `quick`, `plan`, and `execute` consult it when available. This is guidance plus deterministic helper output, not a new workflow lane.
 
 **Leverage:**
 - Lost: a pure zero-file model cannot preserve non-computable intent such as owner/runtime, intended scope, and cleanup obligation.
 - Kept: Workspine remains a lightweight repo-native spine; no new lifecycle workflow, no dashboard/control plane, no vendor session authority, and no change to the five evidence kinds.
-- Gained: agents can explain "clean" precisely across tracked, untracked, sibling, detached, stale, and annotated state by default, and across ignored/generated local surfaces when the caller requests the explicit `--with-ignored` scan before planning, execution, resume, cleanup, or milestone continuation.
+- Gained: agents can explain "clean" precisely across tracked, untracked, sibling, detached, stale, and annotated state by default, and across ignored/generated local surfaces when the caller requests the explicit `--with-ignored` scan before planning, execution, resume, cleanup, or milestone continuation. Owned-write preflight can also consume the same computed risk output, operators can update stale-aware local intent without hand-editing JSON, and closeout replay can join existing verification signals into one typed report without inventing a branch lease, control plane, or cleanup workflow.
 
 **Evidence:**
-- `bin/lib/control-map.mjs`, `bin/gsdd.mjs`, `bin/lib/rendering.mjs`
+- `bin/lib/control-map.mjs`, `bin/lib/closeout-report.mjs`, `bin/lib/health.mjs`, `bin/lib/phase.mjs`, `bin/lib/init-runtime.mjs`, `bin/lib/lifecycle-preflight.mjs`, `bin/gsdd.mjs`, `bin/lib/rendering.mjs`
 - `distilled/workflows/progress.md`, `resume.md`, `pause.md`, `quick.md`, `plan.md`, `execute.md`
-- `tests/gsdd.control-map.test.cjs`
+- `tests/gsdd.control-map.test.cjs`, `tests/gsdd.closeout-report.test.cjs`, `tests/gsdd.health.test.cjs`, `tests/phase.test.cjs`, `tests/gsdd.guards.test.cjs`
 - `.internal-research/gaps.md` Gap I52 and Gap I54
 - `.internal-research/lessons-learned.md` entries on multi-worktree registry, clean-vs-editor-visible noise, checkpoint/worktree truth split, and subagent stop conditions
 - GSD comparison: upstream GSD preserves lifecycle rigor but does not define a vendor-agnostic computed worktree/control-map helper.
@@ -2908,8 +2914,10 @@ Posture compatibility is part of that closeout contract: `repo_closeout` and `ru
 
 **Consequences:**
 - Future cleanup, resume, and parallel-worktree work should start from `gsdd control-map --json` rather than repeated ad hoc repo audits; use `--with-ignored` before making a clean-workspace claim that includes ignored or generated surfaces.
-- A future mutation command may update annotations, but the current helper intentionally stays computed/read-first and safe to call from status surfaces.
-- Future health or preflight hardening can consume the same helper output for stricter blocking, but must avoid turning local annotations into product truth.
+- Annotation mutation is intentionally confined to `control-map annotate`; ordinary `control-map` reads remain computed-first and safe to call from status surfaces.
+- Lifecycle preflight may consume block-level control-map risks for owned-write transitions, but read-only status surfaces must not turn warning-level local state into blockers.
+- `closeout-report` is a compact replay/report helper, not `progress`, `verify`, milestone audit, release automation, cleanup, or a dashboard. The source CLI path includes full health diagnostics; the generated helper reports health availability as a typed warning if the full health builder is not present in that helper runtime.
+- Future health hardening can consume the same helper output for stricter reporting, but must avoid turning local annotations into product truth.
 
 ---
 

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
@@ -77,6 +104,8 @@ 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, fixes, and next safe action
 ```
 
 ## Brownfield Entry Contract
@@ -109,7 +138,7 @@ Use the same three-way routing everywhere:
 Architecture notes:
 - `bin/gsdd.mjs` remains the thin generator entrypoint, while vendor-specific rendering lives in adapter modules.
 - Codex CLI uses the always-generated `.agents/skills/gsdd-*` surface as its entry path, relies on `.planning/bin/gsdd.mjs` for deterministic helper calls, and can add a native `.codex/agents/gsdd-plan-checker.toml` checker agent.
-- `control-map` is a helper command, not a lifecycle workflow: it computes repo/worktree/planning truth first and treats `.planning/.local/` annotations as local intent only.
+- `control-map` is a helper command, not a lifecycle workflow: it computes repo/worktree/planning truth first and treats `.planning/.local/` annotations as local intent only. `control-map annotate` can maintain those annotations, but cannot create ownership, cleanup, or lifecycle authority.
 - Codex VS Code/app are separate surfaces from Codex CLI; do not claim the CLI proof for them unless they expose compatible skill discovery. Fallback is opening or pasting the generated `SKILL.md`.
 - `npx -y gsdd-cli health` now compares any installed generated runtime surfaces against current render output and routes repairs back through `npx -y gsdd-cli update`.
 - Portable lifecycle contracts now align to the roadmap template status grammar: `[ ]`, `[-]`, `[x]`.

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/distilled/workflows/verify.md

@@ -130,7 +130,7 @@ Note: this step does NOT replace levels 1–3. An artifact can satisfy the evide
 </evidence_contract>
 
 <ui_proof_comparison>
-If the plan defines non-empty `ui_proof_slots`, compare planned UI proof against observed bundles before closure. Prefer `gsdd ui-proof compare <planned-slots-json> [observed-bundle-json ...]` when planned slots are available as JSON or fenced JSON; otherwise perform the same field-by-field comparison and record reduced assurance if no deterministic command could run. If the plan records only `no_ui_proof_rationale`, verify the rationale instead of requiring a bundle. Each observed bundle must include top-level `proof_bundle_version`, `scope`, `route_state`, `environment`, `viewport`, `evidence_inputs`, `commands_or_manual_steps`, `observations`, `artifacts`, `privacy`, `result`, and `claim_limits`.
+Before closure, direct `gsdd verify <phase>` and this workflow must fail closed when the target phase has no matching PLAN.md or SUMMARY.md; report structured prerequisite blockers instead of treating missing artifacts as an empty success. Read UI proof declaration authority from the plan frontmatter contract only: body prose, fenced examples, stale sidecars, and markdown snippets do not declare UI proof intent. If frontmatter defines non-empty `ui_proof_slots`, compare planned UI proof against observed bundles before closure. Prefer `gsdd ui-proof compare <planned-slots-json> [observed-bundle-json ...]` when planned slots are available as JSON or fenced JSON; otherwise perform the same field-by-field comparison and record reduced assurance if no deterministic command could run. If frontmatter records `ui_proof_slots: []`, it must also contain a nonblank `no_ui_proof_rationale`; otherwise verification blocks. If the plan records only `no_ui_proof_rationale`, verify the rationale instead of requiring a bundle, and treat stale planned/observed sidecars as warnings rather than proof or blockers. Each observed bundle must include top-level `proof_bundle_version`, `scope`, `route_state`, `environment`, `viewport`, `evidence_inputs`, `commands_or_manual_steps`, `observations`, `artifacts`, `privacy`, `result`, and `claim_limits`.
 Classify each slot as exactly one of: `satisfied`, `partial`, `missing`, `waived`, `deferred`, or `not_applicable`. Deterministic comparison issues include `severity` and `fix_hint`; use those as the normal repair feedback loop before closing verification. Waiver/deferment narrows the claim; it is not proof. Screenshots, traces, videos, reports, accessibility scans, Gherkin, visual diffs, and manual notes are artifact types or activities mapped onto existing evidence kinds, not new evidence kinds. Artifact count is never proof; each artifact must tie to the slot claim, route/state, observation, artifact path/link, privacy metadata, and claim limit.
 For live UI runtime proof, expect `agent-browser` as the default captured tool unless the observed bundle explains a project-native equivalent or an availability constraint. Do not fail solely because another browser tool was used, but downgrade vague proof that lacks exact route/state, planned viewport coverage or rationale, interactive steps/refs where relevant, screenshot/report artifacts, or relevant console/network observations. Existing Playwright tests count as canonical repeatable regression evidence, not a replacement for scoped runtime evidence when the slot requires `runtime`.
 Artifact privacy metadata must include `visibility`, `retention`, `sensitivity`, and `safe_to_publish`; raw screenshots, traces, videos, DOM snapshots, and reports default to local-only and unsafe unless sanitized. Run `gsdd ui-proof validate <path>` or treat `gsdd health` E10 as blocking; add `--claim <...>` when relying on the bundle for public, tracked, delivery, release, or publication proof. Visual taste, accessibility judgment, baseline acceptance, subjective polish/layout quality, and privacy publication require human evidence or explicit waiver; human approval does not replace required `code`, `test`, `runtime`, or `delivery` evidence. Source annotations, AST/cAST findings, semantic search, comments, and Semble-like retrieval are discovery hints only.

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.24.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/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": {