gsdd-cli 0.18.1 → 0.18.2

package/README.md

@@ -104,7 +104,7 @@ In a terminal, `gsdd init` now opens a guided install wizard:
 
 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.
-Workflow-embedded helper commands use `node .planning/bin/gsdd.mjs ...`, so execution-time lifecycle helpers do not depend on a global `gsdd` binary after init.
+`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.
 
 ### Launch Proof Status
 

package/bin/lib/init-flow.mjs

@@ -1,6 +1,6 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync, cpSync } from 'fs';
-import { join, isAbsolute } from 'path';
-import { renderPlanningCliLauncher, renderSkillContent } from './rendering.mjs';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, cpSync } from 'fs';
+import { dirname, join, isAbsolute } from 'path';
+import { buildPlanningCliHelperEntries, renderSkillContent } from './rendering.mjs';
 import { buildManifest, readManifest, writeManifest } from './manifest.mjs';
 import { parseFlagValue, parseToolsFlag, parseAutoFlag } from './cli-utils.mjs';
 import { buildDefaultConfig, COST_PROFILES, RIGOR_PROFILES } from './models.mjs';
@@ -109,8 +109,8 @@ export function createCmdInit(ctx) {
     generateOpenStandardSkills(ctx.cwd, ctx.workflows);
     console.log('  - generated open-standard skills (.agents/skills/gsdd-*)');
 
-    generatePlanningCliLauncher(ctx);
-    console.log('  - generated local workflow helper (.planning/bin/gsdd.mjs)');
+    generatePlanningCliHelpers(ctx);
+    console.log('  - generated local workflow helpers (.planning/bin/gsdd*)');
 
     for (const adapter of resolveAdapters(ctx.adapters, interactiveSession.adapterTargets)) {
       adapter.generate();
@@ -159,10 +159,10 @@ export function createCmdUpdate(ctx) {
 
     if (existsSync(ctx.planningDir)) {
       if (isDry) {
-        console.log('  - would update local workflow helper (.planning/bin/gsdd.mjs)');
+        console.log('  - would update local workflow helpers (.planning/bin/gsdd*)');
       } else {
-        generatePlanningCliLauncher(ctx);
-        console.log('  - updated local workflow helper (.planning/bin/gsdd.mjs)');
+        generatePlanningCliHelpers(ctx);
+        console.log('  - updated local workflow helpers (.planning/bin/gsdd*)');
       }
       updated = true;
     }
@@ -207,16 +207,18 @@ function generateOpenStandardSkills(cwd, workflows) {
   }
 }
 
-function generatePlanningCliLauncher(ctx) {
-  const dir = join(ctx.planningDir, 'bin');
-  mkdirSync(dir, { recursive: true });
-  writeFileSync(
-    join(dir, 'gsdd.mjs'),
-    renderPlanningCliLauncher({
-      packageName: ctx.packageName,
-      packageVersion: ctx.packageVersion,
-    })
-  );
+function generatePlanningCliHelpers(ctx) {
+  for (const entry of buildPlanningCliHelperEntries({
+    packageName: ctx.packageName,
+    packageVersion: ctx.packageVersion,
+  })) {
+    const absolutePath = join(ctx.planningDir, entry.relativePath);
+    mkdirSync(dirname(absolutePath), { recursive: true });
+    writeFileSync(absolutePath, entry.content);
+    if (!absolutePath.endsWith('.cmd')) {
+      chmodSync(absolutePath, 0o755);
+    }
+  }
 }
 
 function buildUpdateManifest({ planningDir, frameworkVersion, updateTemplates }) {

package/bin/lib/init-runtime.mjs

@@ -199,7 +199,7 @@ Platforms (for --tools):
 
 Notes:
   - init always generates open-standard skills at .agents/skills/gsdd-* (portable workflow entrypoints)
-  - init also generates .planning/bin/gsdd.mjs so workflow-embedded helper commands do not depend on a global gsdd binary
+  - init also generates a local .planning/bin/gsdd* helper surface so workflow-embedded helper commands do not depend on a global gsdd binary
   - 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

package/bin/lib/rendering.mjs

@@ -62,6 +62,14 @@ function forwardResult(result, fallbackMessage) {
   }
 }
 
+function runPackagedCli() {
+  const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  return spawnSync(npmCommand, ['exec', '--yes', \`--package=\${packageSpec}\`, '--', 'gsdd', ...args], {
+    stdio: 'inherit',
+    env,
+  });
+}
+
 if (env.GSDD_CLI_PATH) {
   const localResult = spawnSync(process.execPath, [env.GSDD_CLI_PATH, ...args], {
     stdio: 'inherit',
@@ -69,16 +77,44 @@ if (env.GSDD_CLI_PATH) {
   });
   forwardResult(localResult, 'Failed to run the local GSDD CLI path from GSDD_CLI_PATH.');
 } else {
-  const npxCommand = process.platform === 'win32' ? 'npx.cmd' : 'npx';
-  const npxResult = spawnSync(npxCommand, ['--yes', packageSpec, ...args], {
-    stdio: 'inherit',
-    env,
-  });
-  forwardResult(npxResult, \`Failed to run \${packageSpec} via npx.\`);
+  const packagedResult = runPackagedCli();
+  forwardResult(packagedResult, \`Failed to run \${packageSpec} via npm exec.\`);
 }
 `;
 }
 
+function renderPlanningCliShellShim() {
+  return `#!/usr/bin/env sh
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+exec node "$SCRIPT_DIR/gsdd.mjs" "$@"
+`;
+}
+
+function renderPlanningCliCmdShim() {
+  return `@echo off
+setlocal
+node "%~dp0gsdd.mjs" %*
+`;
+}
+
+function buildPlanningCliHelperEntries({ packageName = 'gsdd-cli', packageVersion }) {
+  return [
+    {
+      relativePath: 'bin/gsdd.mjs',
+      content: renderPlanningCliLauncher({ packageName, packageVersion }),
+    },
+    {
+      relativePath: 'bin/gsdd',
+      content: renderPlanningCliShellShim(),
+    },
+    {
+      relativePath: 'bin/gsdd.cmd',
+      content: renderPlanningCliCmdShim(),
+    },
+  ];
+}
+
 function buildPortableSkillEntries(workflows) {
   return workflows.map((workflow) => ({
     relativePath: `.agents/skills/${workflow.name}/SKILL.md`,
@@ -140,10 +176,11 @@ function upsertBoundedBlock(existing, blockContent) {
   return `${bounded}\n\n${existing}`.replace(/\n{3,}/g, '\n\n');
 }
 
-export {
-  buildPortableSkillEntries,
-  getDelegateContent,
-  getWorkflowContent,
+export {
+  buildPlanningCliHelperEntries,
+  buildPortableSkillEntries,
+  getDelegateContent,
+  getWorkflowContent,
   renderAgentsBoundedBlock,
   renderAgentsFileContent,
   renderOpenCodeCommandContent,

package/bin/lib/runtime-freshness.mjs

@@ -2,9 +2,9 @@ import { existsSync, readFileSync } from 'fs';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import {
+  buildPlanningCliHelperEntries,
   buildPortableSkillEntries,
   getDelegateContent,
-  renderPlanningCliLauncher,
   renderOpenCodeCommandContent,
   renderSkillContent,
 } from './rendering.mjs';
@@ -151,15 +151,13 @@ function buildCodexEntries({ cwd }) {
 }
 
 function buildWorkspaceHelperEntries() {
-  return [
-    {
-      relativePath: '.planning/bin/gsdd.mjs',
-      expectedContent: renderPlanningCliLauncher({
-        packageName: PACKAGE_JSON.name,
-        packageVersion: PACKAGE_JSON.version,
-      }),
-    },
-  ];
+  return buildPlanningCliHelperEntries({
+    packageName: PACKAGE_JSON.name,
+    packageVersion: PACKAGE_JSON.version,
+  }).map((entry) => ({
+    relativePath: `.planning/${entry.relativePath}`,
+    expectedContent: entry.content,
+  }));
 }
 
 export function collectExpectedRuntimeSurfaceGroups({ cwd = process.cwd(), workflows }) {

package/distilled/DESIGN.md

@@ -2584,18 +2584,18 @@ 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 launcher at `.planning/bin/gsdd.mjs` instead of assuming a bare `gsdd` binary is available on the consumer repo's PATH.
+**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.
 
 **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 launcher must stay out of `.agents/` ownership so it does not pollute unrelated `.agents` folders or leak into generated governance.
+- The helper surface must stay out of `.agents/` ownership so it does not pollute unrelated `.agents` folders or leak into generated governance.
 
 **Decision:**
-- Generate `.planning/bin/gsdd.mjs` on `gsdd init` for every initialized workspace.
-- Regenerate that launcher 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.
+- 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.
+- 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.
 - Route workflow-embedded helper commands through `node .planning/bin/gsdd.mjs ...` for the deterministic helper seam:
   - `lifecycle-preflight`
   - `file-op`
@@ -2624,7 +2624,7 @@ Sub-gap (b) was closed by D28's `<persistence>` mandate and guarded by G30. Sub-
 **Consequences:**
 - Consumer repos no longer need a global `gsdd` binary for workflow-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 launcher instructions stay out of `AGENTS.md`.
+- Generated governance remains compact and routing-focused because helper-surface instructions stay out of `AGENTS.md`.
 
 ## Maintenance
 

package/distilled/EVIDENCE-INDEX.md

@@ -445,8 +445,8 @@
 - `get-shit-done/workflows/new-project.md`, `get-shit-done/workflows/quick.md`
 
 ## D58 — Local Workflow Helper Launcher
-- `bin/lib/rendering.mjs` (`renderPlanningCliLauncher` for a machine-independent local helper launcher)
-- `bin/lib/init-flow.mjs` (`gsdd init` / `gsdd update` generation of `.planning/bin/gsdd.mjs`)
+- `bin/lib/rendering.mjs` (`renderPlanningCliLauncher` and `.planning/bin/gsdd*` shim rendering for a machine-independent local helper surface)
+- `bin/lib/init-flow.mjs` (`gsdd init` / `gsdd update` generation of `.planning/bin/gsdd*`)
 - `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`

package/docs/USER-GUIDE.md

@@ -195,7 +195,7 @@ The 7 check dimensions: requirement coverage, task completeness, dependency corr
 | `gsdd models clear --runtime <rt> --agent <id>` | Remove runtime override |
 | `gsdd help` | Show all commands |
 
-Workflow-embedded helper commands use `node .planning/bin/gsdd.mjs ...`, so lifecycle preflight, file-op, and phase-status mechanics do not depend on a global `gsdd` binary after init.
+`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.
 
 ### Platform flags for `--tools`
 
@@ -405,7 +405,9 @@ Switch to budget profile: `gsdd models profile budget`. Disable research and pla
   ROADMAP.md                # Phased delivery plan with inline status
   config.json               # Project configuration
   bin/
-    gsdd.mjs                # Local workflow-helper launcher for embedded CLI mechanics
+    gsdd                    # POSIX shim for the local helper surface
+    gsdd.cmd                # Windows shim for the local helper surface
+    gsdd.mjs                # Canonical local workflow-helper launcher
   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.1",
+  "version": "0.18.2",
   "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": {