gsdd-cli 0.18.4 → 0.18.5

package/README.md

@@ -88,13 +88,17 @@ Invariant suites (I-series), guard suites (G-series), and scenario suites (S-ser
 npx gsdd-cli init
 ```
 
-This creates:
+This creates:
 
-1. `.planning/` — durable workspace with templates, role contracts, and config
-2. `.agents/skills/gsdd-*` — portable workflow entrypoints
-3. Tool-specific adapters you choose in the install wizard (Claude skills/commands/agents, OpenCode commands/agents, Codex agents, optional governance)
-
-Then run the new-project workflow to produce `.planning/SPEC.md` and `.planning/ROADMAP.md`.
+1. `.planning/` — durable workspace with templates, role contracts, config, and internal local helpers
+2. `.agents/skills/gsdd-*` — portable workflow entrypoints your runtime invokes as `/gsdd-*` or `$gsdd-*`
+3. Tool-specific adapters you choose in the install wizard (Claude skills/commands/agents, OpenCode commands/agents, Codex agents, optional governance)
+
+Then pick the first workflow lane that matches your situation:
+
+- `gsdd-new-project` for greenfield work, fuzzy brownfield work, or milestone-shaped work
+- `gsdd-quick` for a concrete bounded brownfield change
+- `gsdd-map-codebase` first when the repo is unfamiliar, risky, or needs a deeper baseline before choosing a lane
 
 In a terminal, `gsdd init` now opens a guided install wizard:
 
@@ -102,9 +106,9 @@ In a terminal, `gsdd init` now opens a guided install wizard:
 - Step 2: decide separately whether repo-wide `AGENTS.md` governance is worth installing
 - Step 3: configure planning defaults in the same guided flow
 
-Portable `.agents/skills/gsdd-*` skills are always generated. The wizard controls extra native adapters and optional governance, not the portable baseline.
-When those generated surfaces exist locally, `gsdd health` checks them against current render output instead of asking you to trust manual review.
-`init` generates a local `.planning/bin/gsdd*` helper surface. Workflow-embedded helper commands still use `node .planning/bin/gsdd.mjs ...` as the portable contract, so execution-time lifecycle helpers do not depend on a global `gsdd` binary after init.
+Portable `.agents/skills/gsdd-*` skills are always generated. They are the shared workflow entry surface. The wizard controls extra native adapters and optional governance, not the portable baseline.
+When generated surfaces exist locally, `gsdd health` checks them against current render output instead of asking you to trust manual review.
+`init` also generates `.planning/bin/gsdd*`, but that is an internal local helper surface for workflow-embedded lifecycle mechanics. It is not the normal first-run user entrypoint.
 
 ### Launch Proof Status
 
@@ -123,11 +127,16 @@ Start with the public proof pack:
 
 Runtime floor: Node 20+.
 
-Your tool determines how you invoke workflows:
+Your tool determines how you invoke workflows after `npx gsdd-cli init`:
 
 - **Claude Code / OpenCode / Cursor / Copilot / Gemini:** Use slash commands directly — `/gsdd-new-project`, `/gsdd-plan`, etc.
 - **Codex CLI:** Use skill references — `$gsdd-new-project`, `$gsdd-plan`, etc. `$gsdd-plan` writes the plan and stops; start a separate `$gsdd-execute` run when you want implementation to begin.
-- **Other AI tools:** Open `.agents/skills/gsdd-<workflow>/SKILL.md` and follow the instructions.
+- **Other AI tools:** Open `.agents/skills/gsdd-<workflow>/SKILL.md` and follow the instructions manually.
+
+For repair and refresh:
+
+- `gsdd health` checks whether installed generated surfaces still match the current renderer output.
+- `npx gsdd-cli update` regenerates installed generated surfaces when they drift or when you want the latest shipped wording/templates. If `gsdd` is already on your PATH, `gsdd update` is the same repair path.
 
 If you generate the root `AGENTS.md` block, it adds the framework's behavioral governance. For Cursor, Copilot, and Gemini, that governance is optional discipline on top of native skill discovery — not the mechanism that makes workflows discoverable.
 
@@ -162,13 +171,15 @@ npx gsdd-cli init --tools all        # All of the above
 | **Cursor / Copilot / Gemini** | Same core workflow | Skills-native discovery from `.agents/skills/`; optional root `AGENTS.md` block adds behavioral governance, and the generated skill surface is freshness-checked locally |
 | **Other AI tools** | Fallback only | Open `.agents/skills/gsdd-*/SKILL.md` directly |
 
-### Updating
+### Updating And Repair
 
 ```bash
-npx gsdd-cli update                    # Regenerate adapters from latest sources
-npx gsdd-cli update --tools claude     # Update specific platform only
-npx gsdd-cli update --templates        # Refresh .planning/templates/ and role contracts from framework source
-```
+npx gsdd-cli update                    # Regenerate adapters from latest sources
+npx gsdd-cli update --tools claude     # Update specific platform only
+npx gsdd-cli update --templates        # Refresh .planning/templates/ and role contracts from framework source
+```
+
+Use `gsdd health` first when you want a status check. Use `npx gsdd-cli update` when the generated runtime-facing surfaces are missing, drifted, or you want the latest generated output. If a runtime is only in the qualified-support tier, `health` and `update` still cover generated-surface drift; they do not imply parity-level runtime proof.
 
 ### Non-Interactive Mode (CI / Automation)
 
@@ -325,18 +336,24 @@ Workflows are agent skills or commands, not plain shell utilities. How you invok
 
 ## CLI Commands
 
-| Command | What it does |
-|---------|--------------|
-| `gsdd init [--tools <platform>]` | Set up `.planning/`, generate adapters |
-| `gsdd update [--tools <platform>] [--templates]` | Regenerate adapters; `--templates` refreshes `.planning/templates/` and role contracts |
-| `gsdd health [--json]` | Check workspace integrity (healthy/degraded/broken) |
-| `gsdd file-op <copy\|delete\|regex-sub>` | Run deterministic workspace-confined file copy, delete, and regex substitution |
-| `gsdd find-phase [N]` | Show phase info as JSON (for agent consumption) |
-| `gsdd phase-status <N> <status>` | Update a single ROADMAP phase status through the status-aware helper |
-| `gsdd verify <N>` | Run artifact checks for phase N |
-| `gsdd scaffold phase <N> [name]` | Create a new phase plan file |
-| `gsdd models [show\|profile\|set\|...]` | Inspect and manage model profile propagation |
-| `gsdd help` | Show all commands |
+| Command | What it does |
+|---------|--------------|
+| `npx gsdd-cli init [--tools <platform>]` | First-run setup: create `.planning/`, `.agents/skills/`, and selected runtime adapters |
+| `gsdd health [--json]` | Check installed generated surfaces and workspace state (healthy/degraded/broken) |
+| `npx gsdd-cli update [--tools <platform>] [--templates]` | Regenerate installed runtime surfaces; `--templates` also refreshes `.planning/templates/` and role contracts |
+| `gsdd models [show\|profile\|set\|...]` | Inspect and manage model profile propagation |
+| `gsdd help` | Show all commands, including advanced/internal helpers |
+
+Advanced/internal helpers kept available for automation, workflow internals, or repair:
+
+| Command | What it does |
+|---------|--------------|
+| `gsdd file-op <copy\|delete\|regex-sub>` | Deterministic workspace-confined file copy, delete, and regex substitution |
+| `gsdd lifecycle-preflight <surface> [phase]` | Inspect deterministic lifecycle gate results for a workflow surface |
+| `gsdd find-phase [N]` | Show phase info as JSON (for agent consumption) |
+| `gsdd phase-status <N> <status>` | Update a single ROADMAP phase status through the status-aware helper |
+| `gsdd verify <N>` | Run artifact checks for phase N |
+| `gsdd scaffold phase <N> [name]` | Create a new phase plan file |
 
 ---
 

package/bin/lib/file-ops.mjs

@@ -1,6 +1,7 @@
-import { cpSync, existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'fs';
-import { dirname, isAbsolute, relative, resolve } from 'path';
-import { output, parseFlagValue } from './cli-utils.mjs';
+import { cpSync, existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'fs';
+import { dirname, isAbsolute, relative, resolve } from 'path';
+import { output, parseFlagValue } from './cli-utils.mjs';
+import { resolveWorkspaceContext } from './workspace-root.mjs';
 
 class FileOpError extends Error {}
 
@@ -133,21 +134,26 @@ function cmdRegexSub(cwd, args) {
   output({ operation: 'regex-sub', target: targetArg, changed, replacements: replacementCount });
 }
 
-export function cmdFileOp(...args) {
-  const cwd = process.cwd();
-  const [operation, ...rest] = args;
-
-  try {
-    switch (operation) {
-      case 'copy':
-        cmdCopy(cwd, rest);
-        return;
-      case 'delete':
-        cmdDelete(cwd, rest);
-        return;
-      case 'regex-sub':
-        cmdRegexSub(cwd, rest);
-        return;
+export function cmdFileOp(...args) {
+  const { args: normalizedArgs, workspaceRoot, invalid, error } = resolveWorkspaceContext(args);
+  if (invalid) {
+    console.error(error);
+    process.exitCode = 1;
+    return;
+  }
+  const [operation, ...rest] = normalizedArgs;
+
+  try {
+    switch (operation) {
+      case 'copy':
+        cmdCopy(workspaceRoot, rest);
+        return;
+      case 'delete':
+        cmdDelete(workspaceRoot, rest);
+        return;
+      case 'regex-sub':
+        cmdRegexSub(workspaceRoot, rest);
+        return;
       default:
         fail('Usage: gsdd file-op <copy|delete|regex-sub> ...');
     }

package/bin/lib/health.mjs

@@ -6,21 +6,31 @@
 import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { readManifest, detectModifications } from './manifest.mjs';
-import { output } from './cli-utils.mjs';
-import { runTruthChecks, TRUTH_CHECK_IDS } from './health-truth.mjs';
-import { evaluateLifecycleState } from './lifecycle-state.mjs';
-import { evaluateRuntimeFreshness } from './runtime-freshness.mjs';
+import { output } from './cli-utils.mjs';
+import { runTruthChecks, TRUTH_CHECK_IDS } from './health-truth.mjs';
+import { evaluateLifecycleState } from './lifecycle-state.mjs';
+import { evaluateRuntimeFreshness } from './runtime-freshness.mjs';
+import { resolveWorkspaceContext } from './workspace-root.mjs';
 
 /**
  * Factory function returning the health command.
  * ctx should provide: { frameworkVersion, workflows }
  */
 export function createCmdHealth(ctx) {
-  return async function cmdHealth(...healthArgs) {
-    const jsonMode = healthArgs.includes('--json');
-    const cwd = process.cwd();
-    const planningDir = join(cwd, '.planning');
-    const frameworkSourceMode = isFrameworkSourceRepo(cwd);
+  return async function cmdHealth(...healthArgs) {
+    const jsonMode = healthArgs.includes('--json');
+    const { planningDir, workspaceRoot, invalid, error } = resolveWorkspaceContext(healthArgs);
+    if (invalid) {
+      if (jsonMode) {
+        output({ status: 'broken', errors: [{ id: 'E1', severity: 'ERROR', message: error, fix: 'Pass --workspace-root with a real path or remove the flag.' }], warnings: [], info: [] });
+      } else {
+        console.log(error);
+      }
+      process.exitCode = 1;
+      return;
+    }
+    const cwd = workspaceRoot;
+    const frameworkSourceMode = isFrameworkSourceRepo(cwd);
     const healthCheckIds = ['E1', 'E2', 'E3', 'E4', 'E5', 'E6', 'E7', 'E8', 'W1', 'W2', 'W3', 'W4', 'W5', 'W6', ...TRUTH_CHECK_IDS, 'I1', 'I2', 'I3'];
 
     // Pre-init guard

package/bin/lib/init-flow.mjs

@@ -122,12 +122,12 @@ export function createCmdInit(ctx) {
     writeManifest(ctx.planningDir, manifest);
     console.log('  - wrote generation manifest');
 
-    console.log('\nGSDD initialized.');
-    printInitSummary(interactiveSession.config ?? buildDefaultConfig({ autoAdvance: isAuto }));
-    console.log('Next: run the new-project workflow to produce SPEC.md and ROADMAP.md:\n');
-    printPostInitRouting(interactiveSession.selectedRuntimes);
-  };
-}
+    console.log('\nGSDD initialized.');
+    printInitSummary(interactiveSession.config ?? buildDefaultConfig({ autoAdvance: isAuto }));
+    console.log('Next: choose the starting lane that fits your repo and current scope:\n');
+    printPostInitRouting(interactiveSession.selectedRuntimes);
+  };
+}
 
 export function createCmdUpdate(ctx) {
   return function cmdUpdate(...updateArgs) {

package/bin/lib/init-runtime.mjs

@@ -147,17 +147,17 @@ export function resolveWizardAdapterTargets(selectedRuntimes, installGovernance)
   return adapterTargets;
 }
 
-export function getPostInitRoutingLines(selectedRuntimes) {
-  const lines = [];
-  if (selectedRuntimes.includes('claude')) lines.push('  Claude Code:  /gsdd-new-project');
-  if (selectedRuntimes.includes('opencode')) lines.push('  OpenCode:     /gsdd-new-project');
-  if (selectedRuntimes.includes('codex')) lines.push('  Codex CLI:    $gsdd-new-project');
-  if (selectedRuntimes.includes('cursor')) lines.push('  Cursor:       /gsdd-new-project');
-  if (selectedRuntimes.includes('copilot')) lines.push('  Copilot:      /gsdd-new-project');
-  if (selectedRuntimes.includes('gemini')) lines.push('  Gemini CLI:   /gsdd-new-project');
-  lines.push('  Any tool:     open .agents/skills/gsdd-new-project/SKILL.md');
-  return lines;
-}
+export function getPostInitRoutingLines(selectedRuntimes) {
+  const lines = [];
+  if (selectedRuntimes.includes('claude')) lines.push('  Claude Code:  /gsdd-new-project  |  /gsdd-quick  |  /gsdd-map-codebase');
+  if (selectedRuntimes.includes('opencode')) lines.push('  OpenCode:     /gsdd-new-project  |  /gsdd-quick  |  /gsdd-map-codebase');
+  if (selectedRuntimes.includes('codex')) lines.push('  Codex CLI:    $gsdd-new-project  |  $gsdd-quick  |  $gsdd-map-codebase');
+  if (selectedRuntimes.includes('cursor')) lines.push('  Cursor:       /gsdd-new-project  |  /gsdd-quick  |  /gsdd-map-codebase');
+  if (selectedRuntimes.includes('copilot')) lines.push('  Copilot:      /gsdd-new-project  |  /gsdd-quick  |  /gsdd-map-codebase');
+  if (selectedRuntimes.includes('gemini')) lines.push('  Gemini CLI:   /gsdd-new-project  |  /gsdd-quick  |  /gsdd-map-codebase');
+  lines.push('  Any tool:     open .agents/skills/gsdd-new-project/SKILL.md, gsdd-quick/SKILL.md, or gsdd-map-codebase/SKILL.md');
+  return lines;
+}
 
 export function getHelpText() {
   return `
@@ -197,22 +197,24 @@ Platforms (for --tools):
   gemini    Generate root AGENTS.md governance block; workflows are already discovered natively from .agents/skills/ (legacy alias kept for backward compatibility)
   all       Generate all adapters (Claude, OpenCode, Codex, AGENTS.md, Cursor, Copilot, Gemini)
 
-Notes:
-  - init always generates open-standard skills at .agents/skills/gsdd-* (portable workflow entrypoints)
-  - init also generates a local .planning/bin/gsdd* helper surface so workflow-embedded helper commands do not depend on a global gsdd binary
+Notes:
+  - init always generates open-standard skills at .agents/skills/gsdd-*; this is the shared workflow entry surface
+  - init also generates a local .planning/bin/gsdd* helper surface for workflow-embedded lifecycle helpers; it is internal/advanced, not the normal first-run user entrypoint
   - Workspine is the public product name; the retained package, command, workflow, and workspace contracts stay gsdd-cli, gsdd, gsdd-*, and .planning/
-  - running plain \`gsdd init\` in a terminal opens the guided runtime-selection wizard
-  - the wizard lets you pick runtimes first, then separately decide whether repo-wide AGENTS.md governance is worth installing
-  - \`gsdd health\` compares any installed generated runtime surfaces against current render output and points back to \`gsdd update\` when they drift
-  - directly validated launch surfaces in this repo are Claude Code, OpenCode, and Codex CLI
-  - Cursor, Copilot, and Gemini are qualified support through the shared .agents/skills/ surface plus optional governance
-  - --tools remains the advanced/manual path and preserves legacy runtime aliases for backward compatibility
-  - --tools codex generates .codex/agents/gsdd-plan-checker.toml (portable skill is the entry surface; $gsdd-plan is plan-only until explicit $gsdd-execute)
-  - root AGENTS.md is only written on init when explicitly requested via --tools agents, --tools all, or the wizard governance opt-in
-
-Examples:
-  npx gsdd-cli init
-  npx gsdd-cli init --tools claude
+  - running plain \`gsdd init\` in a terminal opens the guided runtime-selection wizard
+  - the wizard lets you pick runtimes first, then separately decide whether repo-wide AGENTS.md governance is worth installing
+  - \`gsdd health\` compares any installed generated runtime surfaces against current render output and points back to \`gsdd update\` when they drift
+  - directly validated launch surfaces in this repo are Claude Code, OpenCode, and Codex CLI
+  - Cursor, Copilot, and Gemini are qualified support through the shared .agents/skills/ surface plus optional governance
+  - --tools remains the advanced/manual path and preserves legacy runtime aliases for backward compatibility
+  - --tools codex generates .codex/agents/gsdd-plan-checker.toml (portable skill is the entry surface; $gsdd-plan is plan-only until explicit $gsdd-execute)
+  - root AGENTS.md is only written on init when explicitly requested via --tools agents, --tools all, or the wizard governance opt-in
+  - normal user path: npx gsdd-cli init -> run /gsdd-* or $gsdd-* -> gsdd health -> npx gsdd-cli update when repair or refresh is needed
+  - post-init, choose your starting lane honestly: new-project for greenfield or fuzzy/milestone work, quick for a concrete bounded change, map-codebase first when the repo needs deeper orientation
+
+Examples:
+  npx gsdd-cli init
+  npx gsdd-cli init --tools claude
   npx gsdd-cli init --tools cursor
   npx gsdd-cli init --auto --tools claude --brief project-idea.md
   npx gsdd-cli init --auto --tools all
@@ -230,7 +232,7 @@ Examples:
 
 Workflows (run via skills/adapters generated by init, not direct CLI):
   gsdd-new-project          Full initializer: questioning, brownfield audit, research, spec, roadmap
-  gsdd-map-codebase         Map or refresh brownfield codebase context
+  gsdd-map-codebase         Map or refresh brownfield codebase context before choosing or refreshing a work lane
   gsdd-plan                 Research, plan, and fresh-context plan check for a phase
   gsdd-execute              Execute a phase plan and write phase summaries
   gsdd-verify               Verify a completed phase with 3-level checks
@@ -243,5 +245,15 @@ Workflows (run via skills/adapters generated by init, not direct CLI):
   gsdd-pause                Save session context to checkpoint
   gsdd-resume               Restore context and route to the next action
   gsdd-progress             Read-only status and routing surface
+
+Starting lanes after init:
+  gsdd-new-project          Greenfield, fuzzy brownfield scope, or milestone-shaped work
+  gsdd-quick                Concrete bounded brownfield change
+  gsdd-map-codebase         Deeper brownfield orientation before choosing the lane above
+
+Advanced/internal helpers (kept available, but not the primary first-run user story):
+  lifecycle-preflight       Inspect deterministic lifecycle gate results for a workflow surface
+  phase-status              Update ROADMAP.md phase status through the local helper surface
+  file-op                   Deterministic workspace-confined file copy/delete/text mutation
 `;
 }

package/bin/lib/lifecycle-preflight.mjs

@@ -1,9 +1,10 @@
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
-import { output } from './cli-utils.mjs';
-import { describeEvidenceSurface } from './evidence-contract.mjs';
-import { evaluateLifecycleState, normalizePhaseToken } from './lifecycle-state.mjs';
-import { checkDrift } from './session-fingerprint.mjs';
+import { output } from './cli-utils.mjs';
+import { describeEvidenceSurface } from './evidence-contract.mjs';
+import { evaluateLifecycleState, normalizePhaseToken } from './lifecycle-state.mjs';
+import { checkDrift } from './session-fingerprint.mjs';
+import { resolveWorkspaceContext } from './workspace-root.mjs';
 
 const SURFACE_POLICIES = {
   progress: {
@@ -297,10 +298,14 @@ function blocker(code, message, artifacts) {
   return { code, message, artifacts };
 }
 
-export function cmdLifecyclePreflight(...args) {
-  const cwd = process.cwd();
-  const planningDir = join(cwd, '.planning');
-  const [surface, maybePhase, ...rest] = args;
+export function cmdLifecyclePreflight(...args) {
+  const { args: normalizedArgs, planningDir, invalid, error } = resolveWorkspaceContext(args);
+  if (invalid) {
+    console.error(error);
+    process.exitCode = 1;
+    return;
+  }
+  const [surface, maybePhase, ...rest] = normalizedArgs;
 
   if (!surface) {
     console.error('Usage: gsdd lifecycle-preflight <surface> [phase] [--expects-mutation <none|phase-status>]');

package/bin/lib/phase.mjs

@@ -3,10 +3,11 @@
 // IMPORTANT: No module-scope process.cwd() — ESM caching means sub-modules
 // evaluate once, so CWD must be computed inside function bodies.
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'fs';
-import { join, basename } from 'path';
-import { output } from './cli-utils.mjs';
-import { writeFingerprint } from './session-fingerprint.mjs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'fs';
+import { join, basename } from 'path';
+import { output } from './cli-utils.mjs';
+import { writeFingerprint } from './session-fingerprint.mjs';
+import { resolveWorkspaceContext } from './workspace-root.mjs';
 
 const PHASE_STATUS_MARKERS = {
   not_started: '[ ]',
@@ -151,11 +152,15 @@ export function updateRoadmapPhaseStatus(roadmap, phaseNumber, status) {
   return updated;
 }
 
-export function cmdPhaseStatus(...args) {
-  const cwd = process.cwd();
-  const planningDir = join(cwd, '.planning');
-  const roadmapPath = join(planningDir, 'ROADMAP.md');
-  const [phaseNumber, status] = args;
+export function cmdPhaseStatus(...args) {
+  const { args: normalizedArgs, planningDir, invalid, error } = resolveWorkspaceContext(args);
+  if (invalid) {
+    console.error(error);
+    process.exitCode = 1;
+    return;
+  }
+  const roadmapPath = join(planningDir, 'ROADMAP.md');
+  const [phaseNumber, status] = normalizedArgs;
 
   if (!phaseNumber || !status) {
     console.error('Usage: gsdd phase-status <phase-number> <not_started|todo|in_progress|done>');
@@ -184,10 +189,14 @@ export function cmdPhaseStatus(...args) {
   }
 }
 
-export function cmdFindPhase(...args) {
-  const cwd = process.cwd();
-  const planningDir = join(cwd, '.planning');
-  const phaseNum = args[0];
+export function cmdFindPhase(...args) {
+  const { args: normalizedArgs, planningDir, invalid, error } = resolveWorkspaceContext(args);
+  if (invalid) {
+    output({ error });
+    process.exitCode = 1;
+    return;
+  }
+  const phaseNum = normalizedArgs[0];
 
   if (!existsSync(planningDir)) {
     output({ error: 'No .planning/ directory found. Run `gsdd init` then the new-project workflow first.' });
@@ -234,10 +243,14 @@ export function cmdFindPhase(...args) {
   });
 }
 
-export function cmdVerify(...args) {
-  const cwd = process.cwd();
-  const planningDir = join(cwd, '.planning');
-  const phaseNum = args[0];
+export function cmdVerify(...args) {
+  const { args: normalizedArgs, workspaceRoot, planningDir, invalid, error } = resolveWorkspaceContext(args);
+  if (invalid) {
+    console.error(error);
+    process.exitCode = 1;
+    return;
+  }
+  const phaseNum = normalizedArgs[0];
   if (!phaseNum) {
     console.error('Usage: gsdd verify <phase-number>');
     process.exitCode = 1; return;
@@ -271,7 +284,7 @@ export function cmdVerify(...args) {
   }
 
   const results = expectedFiles.map((f) => {
-    const fullPath = join(cwd, f);
+      const fullPath = join(workspaceRoot, f);
     const exists = existsSync(fullPath);
     let substantive = false;
     if (exists) {
@@ -292,7 +305,7 @@ export function cmdVerify(...args) {
   for (const r of results) {
     if (!r.exists) continue;
     try {
-      const content = readFileSync(join(cwd, r.file), 'utf-8');
+        const content = readFileSync(join(workspaceRoot, r.file), 'utf-8');
       const lines = content.split('\n');
       lines.forEach((line, i) => {
         if (/TODO|FIXME|HACK|XXX/.test(line)) {
@@ -317,10 +330,14 @@ export function cmdVerify(...args) {
   });
 }
 
-export function cmdScaffold(...args) {
-  const cwd = process.cwd();
-  const planningDir = join(cwd, '.planning');
-  const [type, ...rest] = args;
+export function cmdScaffold(...args) {
+  const { args: normalizedArgs, planningDir, invalid, error } = resolveWorkspaceContext(args);
+  if (invalid) {
+    console.error(error);
+    process.exitCode = 1;
+    return;
+  }
+  const [type, ...rest] = normalizedArgs;
 
   if (type !== 'phase') {
     console.error('Usage: gsdd scaffold phase <number> [name]');

package/bin/lib/rendering.mjs

@@ -2,9 +2,19 @@ import { existsSync, readFileSync } from 'fs';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const DISTILLED_DIR = join(__dirname, '..', '..', 'distilled');
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const DISTILLED_DIR = join(__dirname, '..', '..', 'distilled');
+const HELPER_LIB_FILES = Object.freeze([
+  'cli-utils.mjs',
+  'evidence-contract.mjs',
+  'file-ops.mjs',
+  'lifecycle-preflight.mjs',
+  'lifecycle-state.mjs',
+  'phase.mjs',
+  'session-fingerprint.mjs',
+  'workspace-root.mjs',
+]);
 
 function getWorkflowContent(workflowFile) {
   const filePath = join(DISTILLED_DIR, 'workflows', workflowFile);
@@ -30,71 +40,57 @@ agent: ${workflow.agent}
 ${workflowContent}`;
 }
 
-function renderPlanningCliLauncher({ packageName = 'gsdd-cli', packageVersion }) {
-  if (!packageVersion) {
-    throw new Error('renderPlanningCliLauncher requires packageVersion');
-  }
+function renderPlanningCliLauncher() {
+  return `#!/usr/bin/env node
 
-  const packageSpec = `${packageName}@${packageVersion}`;
+import { cmdFileOp } from './lib/file-ops.mjs';
+import { cmdLifecyclePreflight } from './lib/lifecycle-preflight.mjs';
+import { cmdPhaseStatus } from './lib/phase.mjs';
+import { bootstrapHelperWorkspace } from './lib/workspace-root.mjs';
 
-  return `#!/usr/bin/env node
+bootstrapHelperWorkspace(import.meta.url);
 
-import { spawnSync } from 'node:child_process';
+const COMMANDS = {
+  'file-op': cmdFileOp,
+  'lifecycle-preflight': cmdLifecyclePreflight,
+  'phase-status': cmdPhaseStatus,
+};
 
-const packageSpec = ${JSON.stringify(packageSpec)};
-const args = process.argv.slice(2);
-const env = { ...process.env };
+function printHelp() {
+  console.log([
+    'Usage: node .planning/bin/gsdd.mjs <command> [args]',
+    '',
+    'Local workflow helper commands:',
+    '  file-op <copy|delete|regex-sub>',
+    '                               Run deterministic workspace-confined file operations',
+    '  phase-status <N> <status>   Update ROADMAP.md phase status ([ ] / [-] / [x])',
+    '  lifecycle-preflight <surface> [phase]',
+    '                               Inspect lifecycle gate results for a workflow surface',
+    '',
+    'Advanced option:',
+    '  --workspace-root <path>     Override workspace root discovery when needed',
+  ].join('\\n'));
+}
 
-function forwardResult(result, fallbackMessage) {
-  if (result.error) {
-    console.error(fallbackMessage ?? result.error.message);
-    process.exitCode = 1;
-    return;
-  }
+async function main() {
+  const [command, ...args] = process.argv.slice(2);
 
-  if (typeof result.status === 'number') {
-    process.exitCode = result.status;
+  if (!command || command === 'help' || command === '--help') {
+    printHelp();
     return;
   }
 
-  if (result.signal) {
+  const handler = COMMANDS[command];
+  if (!handler) {
+    printHelp();
     process.exitCode = 1;
-  }
-}
-
-function runPackagedCli() {
-  if (process.platform === 'win32') {
-    const powershellScript = [
-      '$argList = @($env:GSDD_LAUNCH_ARGS | ConvertFrom-Json)',
-      \`& npm exec --yes "--package=\${packageSpec}" -- gsdd @argList\`,
-      'exit $LASTEXITCODE',
-    ].join('; ');
-
-    return spawnSync('powershell.exe', ['-NoProfile', '-Command', powershellScript], {
-      stdio: 'inherit',
-      env: {
-        ...env,
-        GSDD_LAUNCH_ARGS: JSON.stringify(args),
-      },
-    });
+    return;
   }
 
-  return spawnSync('npm', ['exec', '--yes', \`--package=\${packageSpec}\`, '--', 'gsdd', ...args], {
-    stdio: 'inherit',
-    env,
-  });
+  await handler(...args);
 }
 
-if (env.GSDD_CLI_PATH) {
-  const localResult = spawnSync(process.execPath, [env.GSDD_CLI_PATH, ...args], {
-    stdio: 'inherit',
-    env,
-  });
-  forwardResult(localResult, 'Failed to run the local GSDD CLI path from GSDD_CLI_PATH.');
-} else {
-  const packagedResult = runPackagedCli();
-  forwardResult(packagedResult, \`Failed to run \${packageSpec} via npm exec.\`);
-}
+await main();
 `;
 }
 
@@ -113,11 +109,23 @@ node "%~dp0gsdd.mjs" %*
 `;
 }
 
-function buildPlanningCliHelperEntries({ packageName = 'gsdd-cli', packageVersion }) {
+function renderPlanningCliPowerShellShim() {
+  return `#!/usr/bin/env pwsh
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+node (Join-Path $scriptDir 'gsdd.mjs') @args
+exit $LASTEXITCODE
+`;
+}
+
+function readHelperLibContent(fileName) {
+  return readFileSync(join(__dirname, fileName), 'utf-8');
+}
+
+function buildPlanningCliHelperEntries() {
   return [
     {
       relativePath: 'bin/gsdd.mjs',
-      content: renderPlanningCliLauncher({ packageName, packageVersion }),
+      content: renderPlanningCliLauncher(),
     },
     {
       relativePath: 'bin/gsdd',
@@ -127,6 +135,14 @@ function buildPlanningCliHelperEntries({ packageName = 'gsdd-cli', packageVersio
       relativePath: 'bin/gsdd.cmd',
       content: renderPlanningCliCmdShim(),
     },
+    {
+      relativePath: 'bin/gsdd.ps1',
+      content: renderPlanningCliPowerShellShim(),
+    },
+    ...HELPER_LIB_FILES.map((fileName) => ({
+      relativePath: `bin/lib/${fileName}`,
+      content: readHelperLibContent(fileName),
+    })),
   ];
 }
 

package/bin/lib/runtime-freshness.mjs

@@ -203,11 +203,13 @@ export function collectExpectedRuntimeSurfaceGroups({ cwd = process.cwd(), workf
   ];
 }
 
-export function evaluateRuntimeFreshness({ cwd = process.cwd(), workflows = [] }) {
-  const groups = collectExpectedRuntimeSurfaceGroups({ cwd, workflows }).map((group) => {
-    const installed = existsSync(join(cwd, group.root));
-    const comparisons = installed
-      ? group.entries.map((entry) => compareGeneratedFile({
+export function evaluateRuntimeFreshness({ cwd = process.cwd(), workflows = [] }) {
+  const groups = collectExpectedRuntimeSurfaceGroups({ cwd, workflows }).map((group) => {
+    const installed = group.runtime === 'workspace-helper'
+      ? existsSync(join(cwd, '.planning'))
+      : existsSync(join(cwd, group.root));
+    const comparisons = installed
+      ? group.entries.map((entry) => compareGeneratedFile({
         cwd,
         runtime: group.runtime,
         relativePath: entry.relativePath,

package/bin/lib/workspace-root.mjs

@@ -0,0 +1,131 @@
+import { existsSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+function normalizePath(value, cwd) {
+  return resolve(cwd, String(value));
+}
+
+function hasPlanningMarker(root) {
+  return existsSync(join(root, '.planning', 'config.json')) || existsSync(join(root, '.planning'));
+}
+
+export function consumeWorkspaceRootArg(rawArgs = []) {
+  const args = [];
+  let workspaceRootArg = null;
+  let invalid = false;
+
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const arg = rawArgs[index];
+    if (arg !== '--workspace-root') {
+      args.push(arg);
+      continue;
+    }
+
+    const value = rawArgs[index + 1] ?? null;
+    if (!value || value.startsWith('--')) {
+      invalid = true;
+      continue;
+    }
+
+    workspaceRootArg = value;
+    index += 1;
+  }
+
+  return { args, workspaceRootArg, invalid };
+}
+
+export function findWorkspaceRoot(startDir = process.cwd()) {
+  let current = resolve(startDir);
+
+  while (true) {
+    if (hasPlanningMarker(current)) return current;
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+export function deriveWorkspaceRootFromHelperLocation(entryFileUrl) {
+  if (!entryFileUrl) return null;
+
+  const entryPath = entryFileUrl.startsWith('file:')
+    ? fileURLToPath(entryFileUrl)
+    : resolve(String(entryFileUrl));
+  const binDir = dirname(entryPath);
+  const planningDir = dirname(binDir);
+  const workspaceRoot = dirname(planningDir);
+
+  if (hasPlanningMarker(workspaceRoot) && binDir === join(planningDir, 'bin')) {
+    return workspaceRoot;
+  }
+
+  return null;
+}
+
+export function resolveWorkspaceContext(rawArgs = [], { cwd = process.cwd(), env = process.env } = {}) {
+  const { args, workspaceRootArg, invalid } = consumeWorkspaceRootArg(rawArgs);
+  if (invalid) {
+    return {
+      args,
+      invalid: true,
+      error: 'Usage: --workspace-root <path>',
+      workspaceRoot: resolve(cwd),
+      planningDir: join(resolve(cwd), '.planning'),
+    };
+  }
+
+  if (workspaceRootArg) {
+    const explicitRoot = normalizePath(workspaceRootArg, cwd);
+    if (!hasPlanningMarker(explicitRoot)) {
+      return {
+        args,
+        invalid: true,
+        error: `Workspace root does not contain .planning/: ${workspaceRootArg}`,
+        workspaceRoot: explicitRoot,
+        planningDir: join(explicitRoot, '.planning'),
+      };
+    }
+  }
+
+  const candidates = [];
+
+  if (workspaceRootArg) candidates.push(normalizePath(workspaceRootArg, cwd));
+  if (env.GSDD_WORKSPACE_ROOT) candidates.push(normalizePath(env.GSDD_WORKSPACE_ROOT, cwd));
+
+  const discovered = findWorkspaceRoot(cwd);
+  if (discovered) candidates.push(discovered);
+
+  candidates.push(resolve(cwd));
+
+  for (const candidate of candidates) {
+    if (hasPlanningMarker(candidate)) {
+      return {
+        args,
+        invalid: false,
+        workspaceRoot: candidate,
+        planningDir: join(candidate, '.planning'),
+      };
+    }
+  }
+
+  const fallbackRoot = candidates[0] ?? resolve(cwd);
+  return {
+    args,
+    invalid: false,
+    workspaceRoot: fallbackRoot,
+    planningDir: join(fallbackRoot, '.planning'),
+  };
+}
+
+export function bootstrapHelperWorkspace(entryFileUrl, env = process.env) {
+  const helperRoot = deriveWorkspaceRootFromHelperLocation(entryFileUrl);
+  if (!helperRoot) return null;
+  env.GSDD_WORKSPACE_ROOT = helperRoot;
+  try {
+    process.chdir(helperRoot);
+  } catch {
+    // best-effort: commands also resolve from env/upward search
+  }
+  return helperRoot;
+}

package/distilled/DESIGN.md

@@ -2584,18 +2584,20 @@ Sub-gap (b) was closed by D28's `<persistence>` mandate and guarded by G30. Sub-
 
 ## D58 - Local Workflow Helper Launcher
 
-**Decision (2026-04-22):** Workflow-embedded CLI helper commands must run through a generated local helper surface under `.planning/bin/`, with `.planning/bin/gsdd.mjs` as the canonical launcher, instead of assuming a bare `gsdd` binary is available on the consumer repo's PATH.
+**Decision (2026-04-22, revised 2026-04-23):** Workflow-embedded CLI helper commands must run through a generated local helper runtime under `.planning/bin/`, with `.planning/bin/gsdd.mjs` as the canonical launcher and copied support modules under `.planning/bin/lib/`, instead of assuming a bare `gsdd` binary is available on the consumer repo's PATH or proxying helper execution back through `npm exec` at workflow runtime.
 
 **Context:**
 - Public onboarding already leads with `npx gsdd-cli init`, which works even when the package is not globally installed.
 - The authored workflow surfaces had drifted into a different assumption: embedded helper commands such as `lifecycle-preflight`, `file-op`, and `phase-status` were written as bare `gsdd ...` invocations.
 - That split contract caused consumer friction in the exact place the deterministic helper seam was supposed to help: a workflow could initialize successfully, then fail later because the repo did not have a global `gsdd` on PATH.
 - The helper surface must stay out of `.agents/` ownership so it does not pollute unrelated `.agents` folders or leak into generated governance.
+- The first `.planning/bin/gsdd.mjs` repair still left the wrong runtime dependency in place: the generated file was a trampoline back through `npm exec --package=gsdd-cli@... -- gsdd ...`, so helper execution still depended on npm/package resolution and shell quirks at the exact moment deterministic local mechanics were supposed to be the reliable fallback.
 
 **Decision:**
-- Generate `.planning/bin/gsdd.mjs` plus thin repo-local shell shims (`.planning/bin/gsdd`, `.planning/bin/gsdd.cmd`) on `gsdd init` for every initialized workspace.
+- Generate `.planning/bin/gsdd.mjs` as a self-contained local helper runtime plus repo-local shell shims (`.planning/bin/gsdd`, `.planning/bin/gsdd.cmd`, `.planning/bin/gsdd.ps1`) on `gsdd init` for every initialized workspace.
 - Regenerate that helper surface on `gsdd update` whenever `.planning/` exists.
-- Keep the launcher machine-independent by resolving back to the published `gsdd-cli` package version used for generation rather than embedding framework checkout paths, and invoke the packaged `gsdd` bin explicitly through `npm exec --package=... -- gsdd ...` instead of the fragile bare `npx <package>` form.
+- Copy the minimal helper support modules into `.planning/bin/lib/` so workflow-time helper execution needs only Node, not npm/package-manager resolution.
+- Bootstrap the workspace root from the generated helper location and shared root-resolution logic so helper commands operate on repo truth instead of raw `process.cwd()`.
 - Route workflow-embedded helper commands through `node .planning/bin/gsdd.mjs ...` for the deterministic helper seam:
   - `lifecycle-preflight`
   - `file-op`
@@ -2606,10 +2608,16 @@ Sub-gap (b) was closed by D28's `<persistence>` mandate and guarded by G30. Sub-
 - It preserves the existing skills-first architecture instead of inventing a second discovery or governance path.
 - It fixes the actual consumer DX failure at the point where workflows invoke deterministic helper commands.
 - It keeps ownership aligned with `.planning/`, which already holds the other local runtime mechanics and generation-manifest state.
+- It removes npm/package fetches from the helper hot path, which is the stronger cross-platform ownership model for Linux, WSL, and Windows consumers.
+- It lets both the generated helper runtime and the main CLI share one root-resolution seam instead of relying on repo-root `cwd` as an unstated precondition.
 
 **Evidence:**
 - `bin/lib/init-flow.mjs`
 - `bin/lib/rendering.mjs`
+- `bin/lib/workspace-root.mjs`
+- `bin/lib/file-ops.mjs`
+- `bin/lib/phase.mjs`
+- `bin/lib/lifecycle-preflight.mjs`
 - `bin/lib/runtime-freshness.mjs`
 - `bin/lib/manifest.mjs`
 - `bin/lib/health.mjs`
@@ -2619,12 +2627,14 @@ Sub-gap (b) was closed by D28's `<persistence>` mandate and guarded by G30. Sub-
 - `tests/gsdd.init.test.cjs`
 - `tests/gsdd.health.test.cjs`
 - `tests/gsdd.manifest.test.cjs`
+- `tests/phase.test.cjs`
 - `tests/gsdd.scenarios.test.cjs`
 
 **Consequences:**
-- Consumer repos no longer need a global `gsdd` binary for workflow-embedded helper mechanics after init.
+- Consumer repos no longer need a global `gsdd` binary or workflow-time `npm exec` trampoline for embedded helper mechanics after init.
 - Helper-command freshness is now owned under `.planning/` without widening `.agents` install detection.
 - Generated governance remains compact and routing-focused because helper-surface instructions stay out of `AGENTS.md`.
+- Cross-platform proof is stronger for the local-helper seam itself, but direct live validation still needs to stay conservative by environment: the repo now has focused tests plus Windows fixture proof; Linux/WSL live consumer validation remains a separate evidence question.
 
 ## Maintenance
 

package/distilled/EVIDENCE-INDEX.md

@@ -445,11 +445,12 @@
 - `get-shit-done/workflows/new-project.md`, `get-shit-done/workflows/quick.md`
 
 ## D58 — Local Workflow Helper Launcher
-- `bin/lib/rendering.mjs` (`renderPlanningCliLauncher` and `.planning/bin/gsdd*` shim rendering for a machine-independent local helper surface)
+- `bin/lib/rendering.mjs` (`renderPlanningCliLauncher`, `.planning/bin/gsdd*` shim rendering, and copied `.planning/bin/lib/*` helper-runtime support modules)
 - `bin/lib/init-flow.mjs` (`gsdd init` / `gsdd update` generation of `.planning/bin/gsdd*`)
+- `bin/lib/workspace-root.mjs`, `bin/lib/file-ops.mjs`, `bin/lib/phase.mjs`, `bin/lib/lifecycle-preflight.mjs`
 - `bin/lib/runtime-freshness.mjs`, `bin/lib/manifest.mjs`, `bin/lib/health.mjs`, `bin/lib/health-truth.mjs`
 - `distilled/workflows/execute.md`, `distilled/workflows/verify.md`, `distilled/workflows/resume.md`, `distilled/workflows/progress.md`
-- `tests/gsdd.init.test.cjs`, `tests/gsdd.health.test.cjs`, `tests/gsdd.manifest.test.cjs`, `tests/gsdd.scenarios.test.cjs`
+- `tests/gsdd.init.test.cjs`, `tests/gsdd.health.test.cjs`, `tests/gsdd.manifest.test.cjs`, `tests/phase.test.cjs`, `tests/gsdd.scenarios.test.cjs`
 
 ---
 

package/docs/RUNTIME-SUPPORT.md

@@ -28,24 +28,31 @@ These runtimes use the same portable workflow surfaces, but they do not carry eq
 
 Any tool that can read the generated markdown workflows can still use the framework manually, but that is outside the current native-proof story.
 
-## Current runtime surfaces
-
-| Runtime | Current claim | Entry surface | Notes |
-| --- | --- | --- | --- |
-| Claude Code | Directly validated | `.claude/skills/`, `.claude/commands/`, `.claude/agents/` | Native surface was a mandatory Phase 32 validation target; installed generated files are freshness-checked locally |
-| 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, mandatory Phase 32 validation target |
+## Current runtime surfaces
+
+Two surfaces matter for users:
+
+- `.agents/skills/gsdd-*` is the shared workflow entry surface. Depending on the runtime, users invoke those workflows as `/gsdd-*`, `$gsdd-*`, or by opening the skill markdown directly.
+- `.planning/bin/gsdd*` is an internal local helper surface used by workflow-embedded lifecycle mechanics after init. It is not the primary user entry surface.
+
+| Runtime | Current claim | Entry surface | Notes |
+| --- | --- | --- | --- |
+| Claude Code | Directly validated | `.claude/skills/`, `.claude/commands/`, `.claude/agents/` | Native surface was a mandatory Phase 32 validation target; installed generated files are freshness-checked locally |
+| OpenCode | Directly validated | `.opencode/commands/`, `.opencode/agents/` | Native command and checker path; installed generated files are freshness-checked locally |
+| Codex CLI | Directly validated | `.agents/skills/gsdd-*` plus `.codex/agents/gsdd-plan-checker.toml` | Portable skill entry remains the user workflow surface; the native checker adapter supports plan checking |
 | Cursor | Same core workflow | `.agents/skills/gsdd-*` | Skills-native path; generated skill files are freshness-checked locally, but the runtime is not claimed as parity-validated |
 | GitHub Copilot | Same core workflow | `.agents/skills/gsdd-*` | Skills-native path; generated skill files are freshness-checked locally, but the runtime is not claimed as parity-validated |
 | Gemini CLI | Same core workflow | `.agents/skills/gsdd-*` | Skills-native path; governance is optional, generated skill files are freshness-checked locally, and parity is not claimed |
 
 ## Generated-surface freshness
 
-The authored source contract stays in `distilled/workflows/*`. Generated runtime-facing files are trusted only through deterministic rendering:
-
-- `gsdd health` compares any installed generated surfaces under `.agents/skills/`, `.claude/`, `.opencode/`, and `.codex/` against current render output.
-- `gsdd update` regenerates drifted generated surfaces from the authored workflow and delegate sources.
-- Missing generated surfaces are not treated as drift unless the corresponding runtime surface is actually installed locally.
+The authored source contract stays in `distilled/workflows/*`. Generated runtime-facing files are trusted only through deterministic rendering:
+
+- `gsdd health` compares any installed generated surfaces under `.planning/bin/`, `.agents/skills/`, `.claude/`, `.opencode/`, and `.codex/` against current render output.
+- `npx gsdd-cli update` regenerates drifted generated surfaces from the authored workflow and delegate sources.
+- Missing generated surfaces are not treated as drift unless the corresponding runtime surface is actually installed locally.
+
+This is a generated-surface repair story, not a blanket runtime-parity claim. `health` and `update` can tell you whether installed files are current and can deterministically regenerate them. They cannot make an unsupported runtime become directly validated.
 
 ## What stays portable
 
@@ -74,4 +81,4 @@ Portable contract does not mean equal UX everywhere.
 - `docs/BROWNFIELD-PROOF.md`
 - `docs/proof/consumer-node-cli/README.md`
 - `docs/VERIFICATION-DISCIPLINE.md`
-- `gsdd health` / `gsdd update`
+- `gsdd health` / `npx gsdd-cli update`

package/docs/USER-GUIDE.md

@@ -178,24 +178,48 @@ The 7 check dimensions: requirement coverage, task completeness, dependency corr
 | `gsdd-resume` | Restore context from checkpoint and route to next action | Starting a new session |
 | `gsdd-progress` | Show project status and route to next action | "Where am I?" |
 
-### CLI Commands
-
-| Command | Purpose |
-|---------|---------|
-| `gsdd init [--tools <platform>]` | Set up `.planning/`, generate adapters |
-| `gsdd update [--tools <platform>]` | Regenerate adapters from latest sources |
-| `gsdd update --templates` | Refresh role contracts and delegates (warns about user modifications) |
-| `gsdd find-phase [N]` | Show phase info as JSON (for agent consumption) |
-| `gsdd verify <N>` | Run artifact checks for phase N |
-| `gsdd scaffold phase <N> [name]` | Create a new phase plan file |
-| `gsdd models show` | Display effective model state across all runtimes |
-| `gsdd models profile <tier>` | Set global model profile (`quality`/`balanced`/`budget`) |
-| `gsdd models agent-profile --agent <id> --profile <tier>` | Per-agent semantic override |
-| `gsdd models set --runtime <rt> --agent <id> --model <id>` | Exact runtime model override |
-| `gsdd models clear --runtime <rt> --agent <id>` | Remove runtime override |
+### CLI Commands
+
+| Command | Purpose |
+|---------|---------|
+| `npx gsdd-cli init [--tools <platform>]` | First-run setup: create `.planning/`, `.agents/skills/`, and selected runtime adapters |
+| `gsdd health [--json]` | Check installed generated surfaces and workspace state |
+| `npx gsdd-cli update [--tools <platform>]` | Regenerate installed runtime surfaces from latest sources |
+| `npx gsdd-cli update --templates` | Refresh role contracts and delegates (warns about user modifications) |
+| `gsdd models show` | Display effective model state across all runtimes |
+| `gsdd models profile <tier>` | Set global model profile (`quality`/`balanced`/`budget`) |
+| `gsdd models agent-profile --agent <id> --profile <tier>` | Per-agent semantic override |
+| `gsdd models set --runtime <rt> --agent <id> --model <id>` | Exact runtime model override |
+| `gsdd models clear --runtime <rt> --agent <id>` | Remove runtime override |
 | `gsdd help` | Show all commands |
 
-`init` generates a local `.planning/bin/gsdd*` helper surface. Workflow-embedded helper commands still use `node .planning/bin/gsdd.mjs ...` as the portable contract, so lifecycle preflight, file-op, and phase-status mechanics do not depend on a global `gsdd` binary after init.
+Normal user flow:
+
+1. Run `npx 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.
+
+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.
+
+Advanced/internal helper commands remain available:
+
+| Command | Purpose |
+|---------|---------|
+| `gsdd file-op <copy\|delete\|regex-sub>` | Deterministic workspace-confined file copy, delete, and text mutation |
+| `gsdd phase-status <N> <status>` | Update a single ROADMAP phase status through the local helper surface |
+| `gsdd lifecycle-preflight <surface> [phase]` | Inspect deterministic lifecycle gate results for a workflow surface |
+
+Other CLI commands that remain available outside the first-run path:
+
+| Command | Purpose |
+|---------|---------|
+| `gsdd find-phase [N]` | Show phase info as JSON (for agent consumption) |
+| `gsdd verify <N>` | Run artifact checks for phase N |
+| `gsdd scaffold phase <N> [name]` | Create a new phase plan file |
 
 ### Platform flags for `--tools`
 
@@ -304,10 +328,11 @@ Cursor, Copilot, and Gemini use the same core workflow through installed `.agent
 - `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
 - `Cursor / Copilot / Gemini`: use the matching slash commands once the skills are installed, with the same routing as above
 
-### Existing Codebase
-
-`npx gsdd-cli init`
-
+### Existing Codebase
+
+`npx gsdd-cli init`
+
+- Choose one starting lane after init:
 - `Claude/OpenCode`: `/gsdd-quick` for a concrete bounded change, `/gsdd-new-project` for fuzzy or milestone-shaped work, or `/gsdd-map-codebase` first when the repo needs a deeper brownfield baseline
 - `Codex`: `$gsdd-quick` for a concrete bounded change, `$gsdd-new-project` for fuzzy or milestone-shaped work, or `$gsdd-map-codebase` first when the repo needs a deeper brownfield baseline
 - `Cursor / Copilot / Gemini`: `/gsdd-quick`, `/gsdd-new-project`, or `/gsdd-map-codebase` from the slash command menu once the skills are installed, using the same routing rules above
@@ -369,13 +394,19 @@ Run `gsdd-progress`. It reads all artifacts and tells you where you are and what
 
 Do not re-run `gsdd-execute`. Use `gsdd-quick` for targeted fixes, or `gsdd-verify` to systematically identify issues.
 
-### Template Refresh After Update
+### Template Refresh After Update
 
 ```bash
 npx 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 `.planning/generation-manifest.json`.
+
+### 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.
+
+That repair path is deterministic for generated files. It does not imply that every runtime has equal native ergonomics or equal validation depth.
 
 ### Model Costs Too High
 
@@ -407,7 +438,9 @@ Switch to budget profile: `gsdd models profile budget`. Disable research and pla
   bin/
     gsdd                    # POSIX shim for the local helper surface
     gsdd.cmd                # Windows shim for the local helper surface
-    gsdd.mjs                # Canonical local workflow-helper launcher
+    gsdd.mjs                # Canonical self-contained local helper runtime
+    gsdd.ps1                # PowerShell shim for the local helper surface
+    lib/                    # Copied helper-runtime support modules
   generation-manifest.json  # SHA-256 hashes for template versioning
   .continue-here.md         # Session checkpoint (created by pause, consumed by resume)
   research/                 # Domain research outputs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsdd-cli",
-  "version": "0.18.4",
+  "version": "0.18.5",
   "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": {
@@ -58,4 +58,4 @@
     "url": "https://github.com/PatrickSys/workspine/issues"
   },
   "homepage": "https://github.com/PatrickSys/workspine#readme"
-}
+}