fix: harden repo-local helper launcher resolution

Harden repo-local helper generation, update repair behavior, ROADMAP lifecycle status reconciliation, and npx-first runtime guidance.

Author: PatrickSys

README.md

@@ -20,6 +20,7 @@ import { cmdFindPhase, cmdVerify, cmdScaffold, cmdPhaseStatus } from './lib/phas
 import { cmdFileOp } from './lib/file-ops.mjs';
 import { createCmdHealth } from './lib/health.mjs';
 import { cmdLifecyclePreflight } from './lib/lifecycle-preflight.mjs';
+import { resolveWorkspaceContext } from './lib/workspace-root.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -87,9 +88,18 @@ function createCliContext(cwd = process.cwd()) {
 const INIT_CONTEXT = createCliContext(CWD);
 
 const cmdInit = createCmdInit(INIT_CONTEXT);
-const cmdUpdate = createCmdUpdate(INIT_CONTEXT);
 const cmdHealth = createCmdHealth(INIT_CONTEXT);
 
+const cmdUpdate = (...updateArgs) => {
+  const { args: normalizedArgs, workspaceRoot, invalid, error } = resolveWorkspaceContext(updateArgs, { cwd: INIT_CONTEXT.cwd });
+  if (invalid) {
+    console.error(error);
+    process.exitCode = 1;
+    return;
+  }
+  return createCmdUpdate(createCliContext(workspaceRoot))(...normalizedArgs);
+};
+
 const COMMANDS = {
   init: cmdInit,
   update: cmdUpdate,

bin/gsdd.mjs

@@ -1,6 +1,7 @@
-import { cpSync, existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'fs';
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, 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 {}
 
@@ -21,6 +22,36 @@ function resolveWorkspacePath(cwd, target) {
   fail(`Path must stay inside the workspace: ${target}`);
 }
 
+function ensureRealPathInsideWorkspace(workspaceRoot, candidate, label) {
+  const realWorkspaceRoot = realpathSync(workspaceRoot);
+  const realCandidate = realpathSync(candidate);
+  const rel = relative(realWorkspaceRoot, realCandidate);
+  if (rel === '' || (!rel.startsWith('..') && !isAbsolute(rel))) {
+    return realCandidate;
+  }
+  fail(`${label} must stay inside the workspace: ${candidate}`);
+}
+
+function ensureExistingFilePathInsideWorkspace(workspaceRoot, candidate, label) {
+  const stats = lstatSync(candidate);
+  if (stats.isSymbolicLink()) {
+    fail(`${label} cannot be a symlink: ${candidate}`);
+  }
+  return ensureRealPathInsideWorkspace(workspaceRoot, candidate, label);
+}
+
+function ensureParentPathInsideWorkspace(workspaceRoot, candidate, label) {
+  let current = dirname(candidate);
+  while (!existsSync(current)) {
+    const parent = dirname(current);
+    if (parent === current) {
+      fail(`${label} must stay inside the workspace: ${candidate}`);
+    }
+    current = parent;
+  }
+  ensureExistingFilePathInsideWorkspace(workspaceRoot, current, label);
+}
+
 function getMissingBehavior(args) {
   const parsed = parseFlagValue(args, '--missing');
   if (!parsed.present) return 'error';
@@ -36,6 +67,7 @@ function cmdCopy(cwd, args) {
   }
 
   const missingBehavior = getMissingBehavior(flags);
+  const workspaceRoot = resolve(cwd);
   const source = resolveWorkspacePath(cwd, sourceArg);
   const destination = resolveWorkspacePath(cwd, destinationArg);
 
@@ -51,6 +83,12 @@ function cmdCopy(cwd, args) {
     fail(`Copy only supports files in this phase: ${sourceArg}`);
   }
 
+  ensureExistingFilePathInsideWorkspace(workspaceRoot, source, 'Source path');
+  if (existsSync(destination)) {
+    ensureExistingFilePathInsideWorkspace(workspaceRoot, destination, 'Destination path');
+  }
+  ensureParentPathInsideWorkspace(workspaceRoot, destination, 'Destination path');
+
   mkdirSync(dirname(destination), { recursive: true });
   cpSync(source, destination, { force: true });
   output({ operation: 'copy', source: sourceArg, destination: destinationArg, changed: true });
@@ -63,6 +101,7 @@ function cmdDelete(cwd, args) {
   }
 
   const missingBehavior = getMissingBehavior(flags);
+  const workspaceRoot = resolve(cwd);
   const target = resolveWorkspacePath(cwd, targetArg);
 
   if (!existsSync(target)) {
@@ -77,6 +116,7 @@ function cmdDelete(cwd, args) {
     fail(`Delete only supports files in this phase: ${targetArg}`);
   }
 
+  ensureExistingFilePathInsideWorkspace(workspaceRoot, target, 'Target path');
   unlinkSync(target);
   output({ operation: 'delete', target: targetArg, changed: true });
 }
@@ -93,6 +133,7 @@ function cmdRegexSub(cwd, args) {
   }
 
   const missingBehavior = getMissingBehavior(flags);
+  const workspaceRoot = resolve(cwd);
   const target = resolveWorkspacePath(cwd, targetArg);
 
   if (!existsSync(target)) {
@@ -107,6 +148,8 @@ function cmdRegexSub(cwd, args) {
     fail(`regex-sub only supports files in this phase: ${targetArg}`);
   }
 
+  ensureExistingFilePathInsideWorkspace(workspaceRoot, target, 'Target path');
+
   let regex;
   try {
     regex = new RegExp(pattern, regexFlags.value || 'g');
@@ -134,19 +177,24 @@ function cmdRegexSub(cwd, args) {
 }
 
 export function cmdFileOp(...args) {
-  const cwd = process.cwd();
-  const [operation, ...rest] = 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(cwd, rest);
+        cmdCopy(workspaceRoot, rest);
         return;
       case 'delete':
-        cmdDelete(cwd, rest);
+        cmdDelete(workspaceRoot, rest);
         return;
       case 'regex-sub':
-        cmdRegexSub(cwd, rest);
+        cmdRegexSub(workspaceRoot, rest);
         return;
       default:
         fail('Usage: gsdd file-op <copy|delete|regex-sub> ...');

bin/lib/file-ops.mjs

@@ -75,8 +75,11 @@ export function runTruthChecks(planningDir, frameworkDir, actualCheckIds, option
     }
   }
 
-  if (existsSync(specPath) && existsSync(roadmapPath)) {
-    const mismatches = lifecycle.requirementAlignment.mismatches;
+  if (existsSync(roadmapPath)) {
+    const mismatches = [
+      ...(existsSync(specPath) ? lifecycle.requirementAlignment.mismatches : []),
+      ...lifecycle.phaseStatusAlignment.mismatches,
+    ];
     if (mismatches.length > 0) {
       warnings.push({
         id: 'W10',

bin/lib/health-truth.mjs

@@ -10,6 +10,7 @@ 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.
@@ -18,17 +19,26 @@ import { evaluateRuntimeFreshness } from './runtime-freshness.mjs';
 export function createCmdHealth(ctx) {
   return async function cmdHealth(...healthArgs) {
     const jsonMode = healthArgs.includes('--json');
-    const cwd = process.cwd();
-    const planningDir = join(cwd, '.planning');
+    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
     if (!existsSync(join(planningDir, 'config.json'))) {
       if (jsonMode) {
-        output({ status: 'broken', errors: [{ id: 'E1', severity: 'ERROR', message: '.planning/config.json missing', fix: 'Run `gsdd init`' }], warnings: [], info: [] });
+        output({ status: 'broken', errors: [{ id: 'E1', severity: 'ERROR', message: '.planning/config.json missing', fix: 'Run `npx -y gsdd-cli init`' }], warnings: [], info: [] });
       } else {
-        console.log('Not initialized. Run `gsdd init`.');
+        console.log('Not initialized. Run `npx -y gsdd-cli init`. If `gsdd` is installed globally, `gsdd init` is also fine.');
       }
       process.exitCode = 1;
       return;
@@ -50,71 +60,73 @@ export function createCmdHealth(ctx) {
       const requiredFields = ['researchDepth', 'modelProfile', 'initVersion'];
       const missing = requiredFields.filter((f) => !(f in config));
       if (missing.length > 0) {
-        errors.push({ id: 'E2', severity: 'ERROR', message: `config.json missing required fields: ${missing.join(', ')}`, fix: 'Run `gsdd init` to regenerate' });
+        errors.push({ id: 'E2', severity: 'ERROR', message: `config.json missing required fields: ${missing.join(', ')}`, fix: 'Run `npx -y gsdd-cli init` to regenerate' });
       }
     } catch {
-      errors.push({ id: 'E1', severity: 'ERROR', message: '.planning/config.json is unparseable', fix: 'Run `gsdd init`' });
+      errors.push({ id: 'E1', severity: 'ERROR', message: '.planning/config.json is unparseable', fix: 'Run `npx -y gsdd-cli init`' });
     }
 
     // E3: templates/ missing
     const templatesDir = join(planningDir, 'templates');
+    const runtimeHelpersDir = join(planningDir, 'bin');
     const hasTemplatesDir = existsSync(templatesDir);
+    const hasRuntimeHelpersDir = existsSync(runtimeHelpersDir);
     const rolesDir = join(templatesDir, 'roles');
     const delegatesDir = join(templatesDir, 'delegates');
     const hasRolesDir = hasTemplatesDir && existsSync(rolesDir);
     const hasDelegatesDir = hasTemplatesDir && existsSync(delegatesDir);
     const skipInstalledTemplateChecks = !hasTemplatesDir && frameworkSourceMode;
 
     if (!hasTemplatesDir && !skipInstalledTemplateChecks) {
-      errors.push({ id: 'E3', severity: 'ERROR', message: '.planning/templates/ missing', fix: 'Run `gsdd update --templates`' });
+      errors.push({ id: 'E3', severity: 'ERROR', message: '.planning/templates/ missing', fix: 'Run `npx -y gsdd-cli update --templates`' });
     } else if (hasTemplatesDir) {
       // E4: roles/ missing or empty
       if (!hasRolesDir) {
-        errors.push({ id: 'E4', severity: 'ERROR', message: '.planning/templates/roles/ missing', fix: 'Run `gsdd update --templates`' });
+        errors.push({ id: 'E4', severity: 'ERROR', message: '.planning/templates/roles/ missing', fix: 'Run `npx -y gsdd-cli update --templates`' });
       } else {
         const roleFiles = readdirSync(rolesDir).filter((f) => f.endsWith('.md'));
         if (roleFiles.length === 0) {
-          errors.push({ id: 'E4', severity: 'ERROR', message: '.planning/templates/roles/ has 0 role files', fix: 'Run `gsdd update --templates`' });
+          errors.push({ id: 'E4', severity: 'ERROR', message: '.planning/templates/roles/ has 0 role files', fix: 'Run `npx -y gsdd-cli update --templates`' });
         }
       }
 
       // E5: delegates/ missing or empty
       if (!hasDelegatesDir) {
-        errors.push({ id: 'E5', severity: 'ERROR', message: '.planning/templates/delegates/ missing', fix: 'Run `gsdd update --templates`' });
+        errors.push({ id: 'E5', severity: 'ERROR', message: '.planning/templates/delegates/ missing', fix: 'Run `npx -y gsdd-cli update --templates`' });
       } else {
         const delegateFiles = readdirSync(delegatesDir).filter((f) => f.endsWith('.md'));
         if (delegateFiles.length === 0) {
-          errors.push({ id: 'E5', severity: 'ERROR', message: '.planning/templates/delegates/ has 0 delegate files', fix: 'Run `gsdd update --templates`' });
+          errors.push({ id: 'E5', severity: 'ERROR', message: '.planning/templates/delegates/ has 0 delegate files', fix: 'Run `npx -y gsdd-cli update --templates`' });
         }
       }
 
       // E6: research/ missing or empty
       const researchDir = join(templatesDir, 'research');
       if (!existsSync(researchDir)) {
-        errors.push({ id: 'E6', severity: 'ERROR', message: '.planning/templates/research/ missing', fix: 'Run `gsdd update --templates`' });
+        errors.push({ id: 'E6', severity: 'ERROR', message: '.planning/templates/research/ missing', fix: 'Run `npx -y gsdd-cli update --templates`' });
       } else {
         const researchFiles = readdirSync(researchDir).filter((f) => f.endsWith('.md'));
         if (researchFiles.length === 0) {
-          errors.push({ id: 'E6', severity: 'ERROR', message: '.planning/templates/research/ has 0 template files', fix: 'Run `gsdd update --templates`' });
+          errors.push({ id: 'E6', severity: 'ERROR', message: '.planning/templates/research/ has 0 template files', fix: 'Run `npx -y gsdd-cli update --templates`' });
         }
       }
 
       // E7: codebase/ missing or empty
       const codebaseDir = join(templatesDir, 'codebase');
       if (!existsSync(codebaseDir)) {
-        errors.push({ id: 'E7', severity: 'ERROR', message: '.planning/templates/codebase/ missing', fix: 'Run `gsdd update --templates`' });
+        errors.push({ id: 'E7', severity: 'ERROR', message: '.planning/templates/codebase/ missing', fix: 'Run `npx -y gsdd-cli update --templates`' });
       } else {
         const codebaseFiles = readdirSync(codebaseDir).filter((f) => f.endsWith('.md'));
         if (codebaseFiles.length === 0) {
-          errors.push({ id: 'E7', severity: 'ERROR', message: '.planning/templates/codebase/ has 0 template files', fix: 'Run `gsdd update --templates`' });
+          errors.push({ id: 'E7', severity: 'ERROR', message: '.planning/templates/codebase/ has 0 template files', fix: 'Run `npx -y gsdd-cli update --templates`' });
         }
       }
 
       // E8: critical root template files missing
       const requiredRootFiles = ['spec.md', 'roadmap.md', 'auth-matrix.md'];
       const missingRoot = requiredRootFiles.filter((f) => !existsSync(join(templatesDir, f)));
       if (missingRoot.length > 0) {
-        errors.push({ id: 'E8', severity: 'ERROR', message: `.planning/templates/ missing critical root files: ${missingRoot.join(', ')}`, fix: 'Run `gsdd update --templates`' });
+        errors.push({ id: 'E8', severity: 'ERROR', message: `.planning/templates/ missing critical root files: ${missingRoot.join(', ')}`, fix: 'Run `npx -y gsdd-cli update --templates`' });
       }
     }
 
@@ -123,27 +135,28 @@ export function createCmdHealth(ctx) {
     // W1: generation-manifest.json missing
     const manifest = skipInstalledTemplateChecks ? null : readManifest(planningDir);
     if (!manifest && !skipInstalledTemplateChecks) {
-      warnings.push({ id: 'W1', severity: 'WARN', message: 'generation-manifest.json missing', fix: 'Run `gsdd update --templates` to create' });
+      warnings.push({ id: 'W1', severity: 'WARN', message: 'generation-manifest.json missing', fix: 'Run `npx -y gsdd-cli update` to create' });
     }
 
     // W2 + W3: template/role hash mismatches and missing files
     if (manifest && hasTemplatesDir) {
       const allCategories = [
-        { name: 'delegates', dir: delegatesDir, hashes: hasDelegatesDir ? manifest.templates?.delegates : null },
-        { name: 'research', dir: join(templatesDir, 'research'), hashes: manifest.templates?.research },
-        { name: 'codebase', dir: join(templatesDir, 'codebase'), hashes: manifest.templates?.codebase },
-        { name: 'root templates', dir: templatesDir, hashes: manifest.templates?.root },
-        { name: 'roles', dir: rolesDir, hashes: hasRolesDir ? manifest.roles : null },
+        { name: 'delegates', dir: delegatesDir, hashes: hasDelegatesDir ? manifest.templates?.delegates : null, fixCommand: 'npx -y gsdd-cli update --templates' },
+        { name: 'research', dir: join(templatesDir, 'research'), hashes: manifest.templates?.research, fixCommand: 'npx -y gsdd-cli update --templates' },
+        { name: 'codebase', dir: join(templatesDir, 'codebase'), hashes: manifest.templates?.codebase, fixCommand: 'npx -y gsdd-cli update --templates' },
+        { name: 'root templates', dir: templatesDir, hashes: manifest.templates?.root, fixCommand: 'npx -y gsdd-cli update --templates' },
+        { name: 'roles', dir: rolesDir, hashes: hasRolesDir ? manifest.roles : null, fixCommand: 'npx -y gsdd-cli update --templates' },
+        { name: 'runtime helpers', dir: planningDir, hashes: hasRuntimeHelpersDir ? manifest.runtimeHelpers : null, fixCommand: 'npx -y gsdd-cli update' },
       ];
 
       for (const cat of allCategories) {
         if (!cat.hashes) continue;
         const result = detectModifications(cat.dir, cat.hashes);
         if (result.modified.length > 0) {
-          warnings.push({ id: 'W2', severity: 'WARN', message: `${cat.name}: ${result.modified.length} file(s) modified locally (${result.modified.join(', ')})`, fix: 'Intentional? Run `gsdd update --templates` to reset' });
+          warnings.push({ id: 'W2', severity: 'WARN', message: `${cat.name}: ${result.modified.length} file(s) modified locally (${result.modified.join(', ')})`, fix: `Intentional? Run \`${cat.fixCommand}\` to reset` });
         }
         if (result.missing.length > 0) {
-          warnings.push({ id: 'W3', severity: 'WARN', message: `${cat.name}: ${result.missing.length} file(s) missing from disk (${result.missing.join(', ')})`, fix: 'Run `gsdd update --templates` to restore' });
+          warnings.push({ id: 'W3', severity: 'WARN', message: `${cat.name}: ${result.missing.length} file(s) missing from disk (${result.missing.join(', ')})`, fix: `Run \`${cat.fixCommand}\` to restore` });
         }
       }
     }
@@ -186,20 +199,30 @@ export function createCmdHealth(ctx) {
     ];
     const hasAnyAdapter = adapterPaths.some((p) => existsSync(p));
     if (!hasAnyAdapter) {
-      warnings.push({ id: 'W6', severity: 'WARN', message: 'No adapter surfaces detected', fix: 'Run `gsdd init --tools <platform>`' });
+      warnings.push({ id: 'W6', severity: 'WARN', message: 'No adapter surfaces detected', fix: 'Run `npx -y gsdd-cli init --tools <platform>`' });
     }
 
     const runtimeFreshnessReport = configOk && Array.isArray(ctx.workflows)
       ? evaluateRuntimeFreshness({ cwd, workflows: ctx.workflows })
       : null;
 
-    warnings.push(...runTruthChecks(planningDir, cwd, healthCheckIds, { runtimeFreshnessReport }));
+    warnings.push(...runTruthChecks(planningDir, cwd, healthCheckIds, { runtimeFreshnessReport }).map((warning) => {
+      if (warning.id !== 'W10') return warning;
+      return {
+        ...warning,
+        message: warning.message.replace(
+          /^ROADMAP\/SPEC requirement status drift/,
+          'ROADMAP lifecycle status drift (requirement checkbox and/or overview/detail phase status mismatch)'
+        ),
+        fix: 'Reconcile .planning/ROADMAP.md overview/detail phase markers and .planning/SPEC.md requirement checkboxes',
+      };
+    }));
 
     // --- INFO checks ---
 
     // I1: generation manifest was produced by a different framework version
     if (manifest && manifest.frameworkVersion && manifest.frameworkVersion !== ctx.frameworkVersion) {
-      info.push({ id: 'I1', severity: 'INFO', message: `Generation manifest frameworkVersion (${manifest.frameworkVersion}) differs from current framework version (${ctx.frameworkVersion})`, fix: 'Run `gsdd update --templates`' });
+      info.push({ id: 'I1', severity: 'INFO', message: `Generation manifest frameworkVersion (${manifest.frameworkVersion}) differs from current framework version (${ctx.frameworkVersion})`, fix: 'Run `npx -y gsdd-cli update --templates`' });
     }
 
     // I2: Phase completion count
@@ -250,4 +273,3 @@ export function createCmdHealth(ctx) {
 function isFrameworkSourceRepo(cwd) {
   return existsSync(join(cwd, 'distilled', 'templates')) && existsSync(join(cwd, 'distilled', 'workflows'));
 }
-