gsdd-cli 0.26.0 → 0.28.0

package/distilled/workflows/verify-work.md

@@ -17,9 +17,9 @@ No Pass/Fail buttons. No severity questions. Just: "Here's what should happen. D
 
 <load_context>
 Read these before any other action:
-1. `.planning/phases/{N}-*/` — all `*-SUMMARY.md` files for the target phase
-2. `.planning/SPEC.md` — requirements and acceptance criteria
-3. `.planning/ROADMAP.md` — phase goal and must-haves
+1. `.work/phases/{N}-*/` — all `*-SUMMARY.md` files for the target phase
+2. `.work/SPEC.md` — requirements and acceptance criteria
+3. `.work/ROADMAP.md` — phase goal and must-haves
 
 **$ARGUMENTS:** optional phase number, e.g., `/gsdd-verify-work 4`
 </load_context>
@@ -29,7 +29,7 @@ Before starting a new session, check for existing UAT state:
 
 ```bash
 # Check for existing UAT files in this phase
-ls .planning/phases/{N}-*/*-UAT.md 2>/dev/null || echo "none"
+ls .work/phases/{N}-*/*-UAT.md 2>/dev/null || echo "none"
 ```
 
 **If a UAT.md exists** with `status: testing`, offer to resume:
@@ -69,7 +69,7 @@ Wait for confirmation.
 </extract_tests>
 
 <create_uat_file>
-Create `.planning/phases/{N}-{name}/{phase_num}-UAT.md`:
+Create `.work/phases/{N}-{name}/{phase_num}-UAT.md`:
 
 ```markdown
 ---
@@ -241,14 +241,14 @@ Then route to gap closure (see `<completion>`).
 Report to the user what was tested, then present the next step:
 
 ---
-**Completed:** UAT — created `.planning/phases/{phase_dir}/{phase_num}-UAT.md`.
+**Completed:** UAT — created `.work/phases/{phase_dir}/{phase_num}-UAT.md`.
 
 If no issues:
 **Next step:** `/gsdd-progress` — route to next phase or milestone audit
 
 If issues found:
 **Next step:** `/gsdd-plan` — plan gap closure using the diagnosed root causes in UAT.md
-- Open `.planning/phases/{phase_dir}/{phase_num}-UAT.md` for the plan context
+- Open `.work/phases/{phase_dir}/{phase_num}-UAT.md` for the plan context
 - Use `--gaps` mode if your runtime supports it
 
 Also available:

package/distilled/workflows/verify.md

@@ -7,35 +7,35 @@ You are skeptical by default. You verify claims, not promises.
 
 <load_context>
 Before starting, read these files:
-1. `.planning/ROADMAP.md` - success criteria for the completed phase
-2. `.planning/phases/{plan_id}-PLAN.md` - what was planned
-3. `.planning/phases/{plan_id}-SUMMARY.md` - what execution claims was built
-4. `.planning/SPEC.md` - requirements and constraints for the phase
+1. `.work/ROADMAP.md` - success criteria for the completed phase
+2. `.work/phases/{plan_id}-PLAN.md` - what was planned
+3. `.work/phases/{plan_id}-SUMMARY.md` - what execution claims was built
+4. `.work/SPEC.md` - requirements and constraints for the phase
 5. From the SUMMARY.md loaded in step 3, if a `<judgment>` section is present - read `<anti_regression>` rules as additional verification targets: confirm that invariants listed there were not broken by execution. Read `<active_constraints>` to calibrate verification scope.
 6. The relevant codebase files - the code that was actually built
-7. **Session-boundary fallback:** If the SUMMARY.md loaded in step 3 has no `<judgment>` section, check whether `.planning/.continue-here.bak` exists. If it does, read its `<judgment>` section. Treat `<anti_regression>` rules as additional verification targets and `<active_constraints>` to calibrate verification scope (same usage as step 5). After reading, run `node .planning/bin/gsdd.mjs file-op delete .planning/.continue-here.bak --missing ok` (auto-clean).
-8. `node .planning/bin/gsdd.mjs control-map --json` to reconcile workflow/lifecycle state and checkpoint presence (`.planning/.continue-here.md`) before deciding pass/fail.
+7. **Session-boundary fallback:** If the SUMMARY.md loaded in step 3 has no `<judgment>` section, check whether `.work/.continue-here.bak` exists. If it does, read its `<judgment>` section. Treat `<anti_regression>` rules as additional verification targets and `<active_constraints>` to calibrate verification scope (same usage as step 5). After reading, run `node .work/bin/gsdd.mjs file-op delete .work/.continue-here.bak --missing ok` (auto-clean).
+8. `node .work/bin/gsdd.mjs control-map --json` to reconcile workflow/lifecycle state and checkpoint presence (`.work/.continue-here.md`) before deciding pass/fail.
 
 Establish your verification basis (must-have sources, requirement scope, previous report status) before beginning code inspection. Do not jump to loose file reading until this basis is explicit.
 
-If a previous `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md` exists, read it first and treat this as re-verification.
+If a previous `.work/phases/{phase_dir}/{phase_num}-VERIFICATION.md` exists, read it first and treat this as re-verification.
 </load_context>
 
 <repo_root_helper_contract>
-All `node .planning/bin/gsdd.mjs ...` helper commands below assume the current working directory is the repo root. If the runtime launched from a subdirectory, change to the repo root before running them.
+All `node .work/bin/gsdd.mjs ...` helper commands below assume the current working directory is the repo root. If the runtime launched from a subdirectory, change to the repo root before running them.
 </repo_root_helper_contract>
 
 <lifecycle_preflight>
 Before code inspection or report writing, run:
 
-- `node .planning/bin/gsdd.mjs lifecycle-preflight verify {phase_num} --expects-mutation phase-status`
+- `node .work/bin/gsdd.mjs lifecycle-preflight verify {phase_num} --expects-mutation phase-status`
 
 If the preflight result is `blocked`, STOP and report the blocker instead of inferring lifecycle eligibility from prompt-local prose.
 
 Treat the preflight as an authorization seam over shared repo truth only:
 - it may authorize or reject verification
-- it does not mutate `.planning/ROADMAP.md` by itself
-- owned writes remain the verification artifact plus any explicit `node .planning/bin/gsdd.mjs phase-status` transition that occurs later on `passed`
+- it does not mutate `.work/ROADMAP.md` by itself
+- owned writes remain the verification artifact plus any explicit `node .work/bin/gsdd.mjs phase-status` transition that occurs later on `passed`
 </lifecycle_preflight>
 
 <runtime_contract>
@@ -244,7 +244,7 @@ Recording rules:
 </git_delivery_collection>
 
 <report_format>
-Write `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md` with structured frontmatter first:
+Write `.work/phases/{phase_dir}/{phase_num}-VERIFICATION.md` with structured frontmatter first:
 ```markdown
 ---
 phase: 01-foundation
@@ -365,12 +365,12 @@ Based on the verification result:
 ### `passed`
 
 - phase is ready to move forward
-- write `status: passed` in VERIFICATION.md, then run `node .planning/bin/gsdd.mjs phase-status {phase_num} done`
+- write `status: passed` in VERIFICATION.md, then run `node .work/bin/gsdd.mjs phase-status {phase_num} done`
 - communicate that the phase goal was verified successfully
 
 ### `gaps_found`
 
-- write `status: gaps_found` in VERIFICATION.md and leave ROADMAP.md open (`[-]` or `[ ]`); if it is currently `[x]`, run `node .planning/bin/gsdd.mjs phase-status {phase_num} in_progress`
+- write `status: gaps_found` in VERIFICATION.md and leave ROADMAP.md open (`[-]` or `[ ]`); if it is currently `[x]`, run `node .work/bin/gsdd.mjs phase-status {phase_num} in_progress`
 - do not run `phase-status {phase_num} done`
 
 Present a focused recommendation:
@@ -384,14 +384,14 @@ Present a focused recommendation:
 - list the exact manual checks
 - state the expected outcome for each one
 - do not convert human-needed status into passed until those checks are acknowledged
-- write `status: human_needed` in VERIFICATION.md and leave ROADMAP.md open (`[-]` or `[ ]`); if it is currently `[x]`, run `node .planning/bin/gsdd.mjs phase-status {phase_num} in_progress`
+- write `status: human_needed` in VERIFICATION.md and leave ROADMAP.md open (`[-]` or `[ ]`); if it is currently `[x]`, run `node .work/bin/gsdd.mjs phase-status {phase_num} in_progress`
 - do not run `phase-status {phase_num} done`
 </next_steps>
 
 <persistence>
 MANDATORY: Write the verification report to disk.
 
-File: `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md`
+File: `.work/phases/{phase_dir}/{phase_num}-VERIFICATION.md`
 
 This is non-negotiable. Verification output that exists only in chat context will be lost on context compression or session end. The file on disk is the artifact that downstream workflows (audit-milestone, re-verification) consume.
 
@@ -399,9 +399,9 @@ If you cannot write the file (permissions, path issue), STOP and report the bloc
 
 Before any ROADMAP closure step, confirm the required phase `SUMMARY.md` still exists on disk. If `SUMMARY.md` is missing, STOP and report the blocker — do NOT treat verification as terminally successful and do NOT close ROADMAP state from conversation context alone.
 
-After writing VERIFICATION.md, if `status: passed`, run `node .planning/bin/gsdd.mjs phase-status {phase_num} done` to close the phase entry in `.planning/ROADMAP.md`. Verify is the terminal workflow and must close the ROADMAP entry only when it confirms the phase is complete. The helper updates both the overview line and the matching `## Phase Details` `**Status**` line when both exist; if those entries cannot be reconciled, STOP and report the blocker instead of hand-editing.
+After writing VERIFICATION.md, if `status: passed`, run `node .work/bin/gsdd.mjs phase-status {phase_num} done` to close the phase entry in `.work/ROADMAP.md`. Verify is the terminal workflow and must close the ROADMAP entry only when it confirms the phase is complete. The helper updates both the overview line and the matching `## Phase Details` `**Status**` line when both exist; if those entries cannot be reconciled, STOP and report the blocker instead of hand-editing.
 
-If `status: gaps_found` or `status: human_needed`, do not close ROADMAP.md. If ROADMAP currently marks the phase `[x]`, run `node .planning/bin/gsdd.mjs phase-status {phase_num} in_progress` to reopen/reconcile both status locations before reporting the result.
+If `status: gaps_found` or `status: human_needed`, do not close ROADMAP.md. If ROADMAP currently marks the phase `[x]`, run `node .work/bin/gsdd.mjs phase-status {phase_num} in_progress` to reopen/reconcile both status locations before reporting the result.
 </persistence>
 
 <success_criteria>
@@ -420,7 +420,7 @@ Verification is done when all of these are true:
 - [ ] Verification explicitly reviewed SUMMARY `<handoff>` and `<deltas>` content
 - [ ] Status is one of `passed`, `gaps_found`, or `human_needed`
 - [ ] The required phase `SUMMARY.md` still exists before any ROADMAP closure on passed status
-- [ ] If status is `passed`, ROADMAP.md phase entry is `[x]` via `node .planning/bin/gsdd.mjs phase-status`
+- [ ] If status is `passed`, ROADMAP.md phase entry is `[x]` via `node .work/bin/gsdd.mjs phase-status`
 - [ ] If status is `gaps_found` or `human_needed`, ROADMAP.md phase entry is not `[x]`
 - [ ] The developer was informed of the result and recommended next step
 - [ ] Related failures grouped by concern, not returned as a flat symptom list
@@ -431,7 +431,7 @@ Verification is done when all of these are true:
 Report the verification result to the user, then present the next step:
 
 ---
-**Completed:** Phase verification — created `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md`.
+**Completed:** Phase verification — created `.work/phases/{phase_dir}/{phase_num}-VERIFICATION.md`.
 If status is `passed`: **Next step:** `/gsdd-progress` — route to the next phase or milestone audit.
 If status is `gaps_found`: **Next step:** `/gsdd-plan` — re-plan to close the identified gaps.
 If status is `human_needed`: **Next step:** `/gsdd-verify-work`, then rerun `/gsdd-verify` with UAT results.

package/docs/BROWNFIELD-PROOF.md

@@ -40,7 +40,7 @@ The exported proof pack comes from a new non-framework project that used the shi
 The generated surface included:
 
 - portable `.agents/skills/gsdd-*`
-- consumer `.planning/` state
+- consumer `.work/` state
 - a Codex-native checker adapter
 - a compact consumer `AGENTS.md`
 

package/docs/RUNTIME-SUPPORT.md

@@ -1,26 +1,26 @@
 # 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.
+Workspine is a Spec Driven Development framework 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.
 
-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.
+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 --auto` installs reusable Workspine skills and native runtime surfaces into detected 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.
+The install contract is deliberately skills-first: `npx -y gsdd-cli init` always creates `.agents/skills/gsdd-*` and `.work/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.
+Global install is separate from repo bootstrap. It does not create `.work/`; it writes selected runtime surfaces under user-level agent homes and records Workspine ownership in per-runtime manifests.
 
 ## Support tiers
 
-### Directly validated
+### Recorded proof
 
-The workflow contract has direct repo proof for these runtimes:
+The workflow contract has recorded repo proof for these runtimes:
 
 - **Claude Code**
 - **Codex CLI**
 - **OpenCode**
 
-These are the strongest public runtime claims.
+These are the strongest public runtime claims, but they are not broad parity claims across every related app or extension surface.
 
 ### Qualified support
 
@@ -41,13 +41,13 @@ Any tool that can read the generated markdown workflows can still use the framew
 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.
+- `.work/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 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, native checker adapter, direct lifecycle evidence, and generated-surface freshness checks |
+| Claude Code | Recorded proof | `.claude/skills/`, `.claude/commands/`, `.claude/agents/` | Native surface has recorded lifecycle evidence; installed generated files are freshness-checked locally |
+| OpenCode | Recorded proof | `.opencode/commands/`, `.opencode/agents/` | Native command and checker path; installed generated files are freshness-checked locally |
+| Codex CLI | Recorded proof | `.agents/skills/gsdd-*` plus `.codex/agents/gsdd-plan-checker.toml` | Portable skill entry, native checker adapter, recorded 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 |
@@ -55,7 +55,7 @@ Two surfaces matter for users:
 
 ## Global install surfaces
 
-`npx -y gsdd-cli install --global` can install personal cross-repo surfaces for these targets:
+`npx -y gsdd-cli install --global --auto` can install personal cross-repo surfaces for detected agent homes. Use `npx -y gsdd-cli install --global --tools <targets>` to override detection explicitly. Supported targets:
 
 | Target | Global surfaces |
 | --- | --- |
@@ -72,17 +72,17 @@ When `OPENCODE_CONFIG_DIR` is set, OpenCode commands and agents are installed un
 
 The authored source contract stays in `distilled/workflows/*`. Generated runtime-facing files are trusted only through deterministic rendering:
 
-- `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 health` compares generated surfaces in the current repo-local `.work/` workspace under `.agents/skills/`, `.work/bin/`, `.claude/`, `.opencode/`, and `.codex/` against current render output.
+- Workflow-internal deterministic helper commands run through `node .work/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.
+- Global user-home installs are refreshed by rerunning `npx -y gsdd-cli install --global --auto` or explicitly scoped with `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
 
 - `.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.
+- `.work/bin/gsdd.mjs` is the internal repo-local helper runtime. Generated workflows use `node .work/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

package/docs/USER-GUIDE.md

@@ -1,6 +1,6 @@
 # Workspine User Guide
 
-A detailed reference for Workspine workflows, troubleshooting, and configuration. Workspine is the public product name; the package, CLI, workflow names, and workspace remain `gsdd-cli`, `gsdd`, `gsdd-*`, and `.planning/` as retained technical contracts. Runtime floor: Node 20+. For quick-start setup and the public proof pack, start with the [README](../README.md). Human install/update commands use `npx -y gsdd-cli ...`; bare `gsdd ...` is shorthand only when the package is globally installed.
+A detailed reference for Workspine workflows, troubleshooting, and configuration. Workspine is the public product name; the package, CLI, workflow names, and workspace remain `gsdd-cli`, `gsdd`, `gsdd-*`, and `.work/` as retained technical contracts. Runtime floor: Node 20+. For quick-start setup and the public proof pack, start with the [README](../README.md). Human install/update commands use `npx -y gsdd-cli ...`; bare `gsdd ...` is shorthand only when the package is globally installed.
 
 ---
 
@@ -13,7 +13,7 @@ For a new project or a broad brownfield effort:
 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.
+Use `npx -y gsdd-cli init` for repo-local setup. Use `npx -y gsdd-cli install --global --auto` to install reusable Workspine skills and native runtime surfaces into detected agent homes without creating `.work/` 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`.
 
@@ -69,7 +69,7 @@ For a bounded existing-code change, use `gsdd-quick`. For an unfamiliar or risky
 Optional closure and milestone-continuation workflows in the shipped surface:
 
 - `gsdd-verify-work` adds conversational UAT when user-facing behavior needs explicit validation.
-- `gsdd-plan-milestone-gaps` turns audit findings into gap-closure phases when a milestone is not ready to ship.
+- `gsdd-plan` also handles amend/extend planning when audit findings need gap-closure phases before a milestone is ready to ship.
 - `gsdd-complete-milestone` archives a shipped milestone, evolves `SPEC.md`, and collapses `ROADMAP.md`.
 - `gsdd-new-milestone` starts the next milestone after closure.
 
@@ -177,7 +177,7 @@ The 7 check dimensions: requirement coverage, task completeness, dependency corr
 
 ### Install Modes
 
-Use local repo install when the project should own `.planning/`, `.agents/skills`, and optional repo-local runtime adapters:
+Use local repo install when the project should own `.work/`, `.agents/skills`, and optional repo-local runtime adapters:
 
 ```bash
 npx -y gsdd-cli init
@@ -188,9 +188,12 @@ Use global agent install when you want Workspine workflows available across repo
 
 ```bash
 npx -y gsdd-cli install --global
+npx -y gsdd-cli install --global --auto
 npx -y gsdd-cli install --global --tools claude,opencode,codex,copilot
 ```
 
+Use `--auto` for non-interactive global install into detected local agent homes. Use `--tools <targets>` when you want to install a specific target set regardless of detection.
+
 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)
@@ -206,7 +209,6 @@ Global install writes Workspine-managed files under selected agent homes and rec
 | `gsdd-audit-milestone` | Cross-phase integration, requirements coverage, E2E flows | When all phases are done |
 | `gsdd-complete-milestone` | Archive a shipped milestone, evolve `SPEC.md`, collapse `ROADMAP.md` | When the audited milestone is ready to ship |
 | `gsdd-new-milestone` | Start the next milestone with goals, requirements, and roadmap phases | After closing a milestone and starting the next one |
-| `gsdd-plan-milestone-gaps` | Turn milestone audit findings into gap-closure phases | When audit findings need planned follow-up before shipment |
 | `gsdd-quick` | Plan and execute sub-hour work outside the phase cycle | Bug fixes, small features, config changes when the bounded change is already concrete |
 | `gsdd-pause` | Save session context to checkpoint | Stopping mid-phase |
 | `gsdd-resume` | Restore context from checkpoint and route to next action | Starting a new session |
@@ -216,11 +218,9 @@ Global install writes Workspine-managed files under selected agent homes and rec
 
 | Command | Purpose |
 |---------|---------|
-| `npx -y gsdd-cli init [--tools <platform>]` | Set up `.planning/`, generate skills/adapters |
+| `npx -y gsdd-cli init [--tools <platform>]` | Set up `.work/`, generate skills/adapters |
 | `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 |
@@ -231,7 +231,7 @@ Global install writes Workspine-managed files under selected agent homes and rec
 | `npx -y gsdd-cli models clear --runtime <rt> --agent <id>` | Remove runtime override |
 | `npx -y gsdd-cli help` | Show all commands |
 
-If `gsdd-cli` is globally installed, you can use the shorter `gsdd ...` form for the same commands. Generated workflow helper calls do not use the global binary; they run through `node .planning/bin/gsdd.mjs ...` from the repo root.
+If `gsdd-cli` is globally installed, you can use the shorter `gsdd ...` form for the same commands. Generated workflow helper calls do not use the global binary; they run through `node .work/bin/gsdd.mjs ...` from the repo root.
 
 Normal user flow:
 
@@ -239,12 +239,12 @@ Normal user flow:
 2. Enter workflows through your runtime surface: `/gsdd-*` or `$gsdd-*`.
 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.
+5. For personal global installs, rerun `npx -y gsdd-cli install --global --auto` to repair or refresh detected agent homes, or use `npx -y gsdd-cli install --global --tools <targets>` to scope the target set explicitly.
 
 Surface split:
 
 - `.agents/skills/gsdd-*` is the workflow entry surface.
-- `.planning/bin/gsdd*` is an internal local helper surface used by workflow-embedded lifecycle mechanics. It is kept available, but it is not the normal first-run user entrypoint.
+- `.work/bin/gsdd*` is an internal local helper surface used by workflow-embedded lifecycle mechanics. It is kept available, but it is not the normal first-run user entrypoint.
 
 Advanced/internal helper commands remain available:
 
@@ -268,7 +268,7 @@ Other CLI commands that remain available outside the first-run path:
 |------|-----------------|
 | `claude` | `.claude/skills/`, `.claude/commands/`, `.claude/agents/` |
 | `opencode` | `.opencode/commands/`, `.opencode/agents/` |
-| `codex` | `.codex/agents/gsdd-plan-checker.toml` (`.agents/skills/gsdd-*` and `.planning/bin/gsdd.mjs` are always generated; `$gsdd-plan` stays plan-only until explicit `$gsdd-execute`) |
+| `codex` | `.codex/agents/gsdd-plan-checker.toml` (`.agents/skills/gsdd-*` and `.work/bin/gsdd.mjs` are always generated; `$gsdd-plan` stays plan-only until explicit `$gsdd-execute`) |
 | `agents` | Bounded fallback block in root `AGENTS.md` |
 | `all` | All of the above |
 | *(none)* | Auto-detect installed tools |
@@ -277,7 +277,7 @@ Other CLI commands that remain available outside the first-run path:
 
 ## Configuration Reference
 
-`npx -y gsdd-cli init` creates `.planning/config.json` interactively (or with defaults via `--auto`).
+`npx -y gsdd-cli init` creates `.work/config.json` interactively (or with defaults via `--auto`).
 
 ### Full config.json Schema
 
@@ -306,7 +306,7 @@ Other CLI commands that remain available outside the first-run path:
 |---------|---------|---------|------------------|
 | `researchDepth` | `fast`, `balanced`, `deep` | `balanced` | Research thoroughness per phase |
 | `parallelization` | `true`, `false` | `true` | Run independent agents simultaneously |
-| `commitDocs` | `true`, `false` | `true` | Track `.planning/` in git |
+| `commitDocs` | `true`, `false` | `true` | Track `.work/` in git |
 | `modelProfile` | `balanced`, `quality`, `budget` | `balanced` | Portable semantic model tier |
 
 ### Workflow Toggles
@@ -366,8 +366,8 @@ Cursor, Copilot, and Gemini can use the installed `.agents/skills/` surfaces whe
 
 ### Milestone Continuation
 
-- `Claude/OpenCode`: `/gsdd-plan-milestone-gaps` when audit findings need closure work, or `/gsdd-complete-milestone -> /gsdd-new-milestone` when the milestone is ready to ship
-- `Codex`: `$gsdd-plan-milestone-gaps` when audit findings need closure work, or `$gsdd-complete-milestone -> $gsdd-new-milestone` when the milestone is ready to ship
+- `Claude/OpenCode`: `/gsdd-plan` amend/extend mode when audit findings need closure work, or `/gsdd-complete-milestone -> /gsdd-new-milestone` when the milestone is ready to ship
+- `Codex`: `$gsdd-plan` amend/extend mode when audit findings need closure work, or `$gsdd-complete-milestone -> $gsdd-new-milestone` when the milestone is ready to ship
 - `Cursor / Copilot / Gemini`: use the matching slash commands when skill discovery is available, with the same routing as above
 
 ### Existing Codebase
@@ -442,11 +442,11 @@ Do not re-run `gsdd-execute`. Use `gsdd-quick` for targeted fixes, or `gsdd-veri
 npx -y gsdd-cli update --templates       # Refreshes role contracts and delegates
 ```
 
-If you've modified any templates, the generation manifest detects this and warns you before overwriting. The SHA-256 hash of each generated file is tracked in `.planning/generation-manifest.json`.
+If you've modified any templates, the generation manifest detects this and warns you before overwriting. The SHA-256 hash of each generated file is tracked in `.work/generation-manifest.json`.
 
 ### Generated Surfaces Drift Or A Runtime Command Goes Missing
 
-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>`.
+In a repo-local `.work/` 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 --auto` or scope it explicitly with `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.
 
@@ -473,7 +473,7 @@ Switch to budget profile: `npx -y gsdd-cli models profile budget` (or `gsdd mode
 ## Project File Structure
 
 ```
-.planning/
+.work/
   SPEC.md                   # Living specification (goals, constraints, decisions)
   ROADMAP.md                # Phased delivery plan with inline status
   config.json               # Project configuration
@@ -503,7 +503,7 @@ Switch to budget profile: `npx -y gsdd-cli models profile budget` (or `gsdd mode
 
 agents/                     # 10 canonical role contracts
 .agents/skills/gsdd-*/      # Portable workflow entrypoints (open standard)
-.planning/bin/gsdd.mjs      # Internal repo-local helper runtime for deterministic workflow commands (run from repo root)
+.work/bin/gsdd.mjs          # Internal repo-local helper runtime for deterministic workflow commands (run from repo root)
 ```
 
 Platform-specific adapters (generated by `npx -y gsdd-cli init`, or `gsdd init` when globally installed):
@@ -521,4 +521,4 @@ Platform-specific adapters (generated by `npx -y gsdd-cli init`, or `gsdd init`
 AGENTS.md                   # Optional governance block (useful for agents that consume AGENTS.md)
 ```
 
-`.agents/skills/` is the workflow entry surface. `.planning/bin/` is the internal helper runtime used by those workflows. Native adapters and governance files are optional ergonomics, not required prompt bulk.
+`.agents/skills/` is the workflow entry surface. `.work/bin/` is the internal helper runtime used by those workflows. Native adapters and governance files are optional ergonomics, not required prompt bulk.

package/docs/claude/context-monitor.md

@@ -58,7 +58,7 @@ The bridge file is a simple JSON object:
 
 ## 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.
+GSDD's `gsdd-pause` workflow saves execution state to `.work/.continue-here.md`. The WARNING message suggests using it. The CRITICAL message instructs immediate state save.
 
 ## Setup
 

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

@@ -30,7 +30,7 @@ The proof pack shows one full release-floor loop:
 
 - 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.
+- The legacy `.planning/live-proof/consumer-node-cli` tree (still read as old folder source material; new projects use `.work/`) remains evidence-only source material and is intentionally not the public entry surface.
 
 ## Why this pack exists
 

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "gsdd-cli",
-  "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.",
+  "version": "0.28.0",
+  "description": "Workspine — plan, execute, and verify AI-assisted work from files in your repo, with proof before done. Published as gsdd-cli.",
   "type": "module",
   "bin": {
     "gsdd": "bin/gsdd.mjs"
   },
   "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.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",
+    "test:gsdd": "node tests/run-all.cjs --covers=gsdd.next-card.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": {