gsdd-cli 0.18.4 → 0.19.0

package/bin/gsdd.mjs

@@ -1,66 +1,64 @@
-#!/usr/bin/env node
-
-// gsdd - Workspine CLI
-
+#!/usr/bin/env node
+
 import { realpathSync, readFileSync } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-import { createAdapterRegistry } from './adapters/index.mjs';
-import {
-  renderAgentsBoundedBlock,
-  renderAgentsFileContent,
-  renderOpenCodeCommandContent,
-  renderSkillContent,
-  upsertBoundedBlock,
-  getDelegateContent,
-} from './lib/rendering.mjs';
-import { loadProjectModelConfig, getRuntimeModelOverride, resolveRuntimeAgentModel, cmdModels } from './lib/models.mjs';
-import { createCmdInit, createCmdUpdate, cmdHelp } from './lib/init.mjs';
-import { cmdFindPhase, cmdVerify, cmdScaffold, cmdPhaseStatus } from './lib/phase.mjs';
-import { cmdFileOp } from './lib/file-ops.mjs';
-import { createCmdHealth } from './lib/health.mjs';
-import { cmdLifecyclePreflight } from './lib/lifecycle-preflight.mjs';
-
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { createAdapterRegistry } from './adapters/index.mjs';
+import {
+  renderAgentsBoundedBlock,
+  renderAgentsFileContent,
+  renderOpenCodeCommandContent,
+  renderSkillContent,
+  upsertBoundedBlock,
+  getDelegateContent,
+} from './lib/rendering.mjs';
+import { loadProjectModelConfig, getRuntimeModelOverride, resolveRuntimeAgentModel, cmdModels } from './lib/models.mjs';
+import { createCmdInit, createCmdUpdate, cmdHelp } from './lib/init.mjs';
+import { cmdFindPhase, cmdVerify, cmdScaffold, cmdPhaseStatus } from './lib/phase.mjs';
+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);
 const DISTILLED_DIR = join(__dirname, '..', 'distilled');
 const AGENTS_DIR = join(__dirname, '..', 'agents');
 const PACKAGE_JSON = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
-const CWD = process.cwd();
-const IS_MAIN = process.argv[1]
-  ? realpathSync(process.argv[1]) === realpathSync(__filename)
-  : false;
-
-const [,, command, ...args] = process.argv;
-
-function defineWorkflow({ mutatesArtifacts = true, ...workflow }) {
-  return {
-    ...workflow,
-    mutatesArtifacts,
-    agent: mutatesArtifacts ? 'Code' : 'Plan',
-    opencodeType: mutatesArtifacts ? 'edit' : 'plan',
-  };
-}
-
-const WORKFLOWS = [
-  defineWorkflow({ name: 'gsdd-new-project', workflow: 'new-project.md', description: 'New project - questioning, codebase audit, research, spec, roadmap' }),
-  defineWorkflow({ name: 'gsdd-map-codebase', workflow: 'map-codebase.md', description: 'Map or refresh codebase - 4 parallel mappers, staleness check, secrets scan' }),
-  defineWorkflow({ name: 'gsdd-plan', workflow: 'plan.md', description: 'Plan a phase - research check, backward planning, task creation' }),
-  defineWorkflow({ name: 'gsdd-execute', workflow: 'execute.md', description: 'Execute a phase plan - implement tasks, verify changes, follow repo git conventions' }),
-  defineWorkflow({ name: 'gsdd-verify', workflow: 'verify.md', description: 'Verify a completed phase - 3-level checks, anti-pattern scan' }),
-  defineWorkflow({ name: 'gsdd-verify-work', workflow: 'verify-work.md', description: 'Conversational UAT testing - validate user-facing behavior with structured gap tracking' }),
-  defineWorkflow({ name: 'gsdd-audit-milestone', workflow: 'audit-milestone.md', description: 'Audit a completed milestone - cross-phase integration, requirements coverage, E2E flows' }),
-  defineWorkflow({ name: 'gsdd-complete-milestone', workflow: 'complete-milestone.md', description: 'Complete milestone - archive, evolve spec, collapse roadmap' }),
-  defineWorkflow({ name: 'gsdd-new-milestone', workflow: 'new-milestone.md', description: 'New milestone - gather goals, define requirements, create roadmap phases' }),
-  defineWorkflow({ name: 'gsdd-plan-milestone-gaps', workflow: 'plan-milestone-gaps.md', description: 'Plan gap closure phases from audit results' }),
-  defineWorkflow({ name: 'gsdd-quick', workflow: 'quick.md', description: 'Quick task - plan and execute a sub-hour task outside the phase cycle' }),
-  defineWorkflow({ name: 'gsdd-pause', workflow: 'pause.md', description: 'Pause work - save session context for seamless resumption' }),
-  defineWorkflow({ name: 'gsdd-resume', workflow: 'resume.md', description: 'Resume work - restore context and route to next action' }),
-  defineWorkflow({ name: 'gsdd-progress', workflow: 'progress.md', description: 'Check progress - show project status and route to next action', mutatesArtifacts: false }),
-];
-
-const FRAMEWORK_VERSION = 'v1.4';
-
+const IS_MAIN = process.argv[1]
+  ? realpathSync(process.argv[1]) === realpathSync(__filename)
+  : false;
+
+const [,, command, ...args] = process.argv;
+
+function defineWorkflow({ mutatesArtifacts = true, ...workflow }) {
+  return {
+    ...workflow,
+    mutatesArtifacts,
+    agent: mutatesArtifacts ? 'Code' : 'Plan',
+    opencodeType: mutatesArtifacts ? 'edit' : 'plan',
+  };
+}
+
+const WORKFLOWS = [
+  defineWorkflow({ name: 'gsdd-new-project', workflow: 'new-project.md', description: 'New project - questioning, codebase audit, research, spec, roadmap' }),
+  defineWorkflow({ name: 'gsdd-map-codebase', workflow: 'map-codebase.md', description: 'Map or refresh codebase - 4 parallel mappers, staleness check, secrets scan' }),
+  defineWorkflow({ name: 'gsdd-plan', workflow: 'plan.md', description: 'Plan a phase - research check, backward planning, task creation' }),
+  defineWorkflow({ name: 'gsdd-execute', workflow: 'execute.md', description: 'Execute a phase plan - implement tasks, verify changes, follow repo git conventions' }),
+  defineWorkflow({ name: 'gsdd-verify', workflow: 'verify.md', description: 'Verify a completed phase - 3-level checks, anti-pattern scan' }),
+  defineWorkflow({ name: 'gsdd-verify-work', workflow: 'verify-work.md', description: 'Conversational UAT testing - validate user-facing behavior with structured gap tracking' }),
+  defineWorkflow({ name: 'gsdd-audit-milestone', workflow: 'audit-milestone.md', description: 'Audit a completed milestone - cross-phase integration, requirements coverage, E2E flows' }),
+  defineWorkflow({ name: 'gsdd-complete-milestone', workflow: 'complete-milestone.md', description: 'Complete milestone - archive, evolve spec, collapse roadmap' }),
+  defineWorkflow({ name: 'gsdd-new-milestone', workflow: 'new-milestone.md', description: 'New milestone - gather goals, define requirements, create roadmap phases' }),
+  defineWorkflow({ name: 'gsdd-plan-milestone-gaps', workflow: 'plan-milestone-gaps.md', description: 'Plan gap closure phases from audit results' }),
+  defineWorkflow({ name: 'gsdd-quick', workflow: 'quick.md', description: 'Quick task - plan and execute a sub-hour task outside the phase cycle' }),
+  defineWorkflow({ name: 'gsdd-pause', workflow: 'pause.md', description: 'Pause work - save session context for seamless resumption' }),
+  defineWorkflow({ name: 'gsdd-resume', workflow: 'resume.md', description: 'Resume work - restore context and route to next action' }),
+  defineWorkflow({ name: 'gsdd-progress', workflow: 'progress.md', description: 'Check progress - show project status and route to next action', mutatesArtifacts: false }),
+];
+
+const FRAMEWORK_VERSION = 'v1.4';
+
 function createCliContext(cwd = process.cwd()) {
   return {
     cwd,
@@ -71,62 +69,71 @@ function createCliContext(cwd = process.cwd()) {
     packageVersion: PACKAGE_JSON.version,
     workflows: WORKFLOWS,
     frameworkVersion: FRAMEWORK_VERSION,
-    adapters: createAdapterRegistry({
-      cwd,
-      workflows: WORKFLOWS,
-      renderAgentsBoundedBlock,
-      renderAgentsFileContent,
-      renderOpenCodeCommandContent,
-      renderSkillContent,
-      upsertBoundedBlock,
-      getDelegateContent,
-      loadProjectModelConfig,
-      getRuntimeModelOverride,
-      resolveRuntimeAgentModel,
-    }),
-  };
-}
-
-const INIT_CONTEXT = createCliContext(CWD);
-
-const cmdInit = createCmdInit(INIT_CONTEXT);
-const cmdUpdate = createCmdUpdate(INIT_CONTEXT);
-const cmdHealth = createCmdHealth(INIT_CONTEXT);
-
-const COMMANDS = {
-  init: cmdInit,
-  update: cmdUpdate,
-  models: cmdModels,
-  health: cmdHealth,
-  'file-op': cmdFileOp,
-  'lifecycle-preflight': cmdLifecyclePreflight,
-  'find-phase': cmdFindPhase,
-  'phase-status': cmdPhaseStatus,
-  verify: cmdVerify,
-  scaffold: cmdScaffold,
-  help: cmdHelp,
-};
-
-async function runCli(cliCommand = command, ...cliArgs) {
-  const normalizedArgs = cliArgs.length === 0
-    ? args
-    : cliArgs.length === 1 && Array.isArray(cliArgs[0])
-      ? cliArgs[0]
-      : cliArgs;
-
-  process.exitCode = 0;
-
-  if (!cliCommand || !COMMANDS[cliCommand]) {
-    cmdHelp();
-    if (cliCommand) process.exitCode = 1;
-    return;
-  }
-
-  await COMMANDS[cliCommand](...normalizedArgs);
-}
-
-if (IS_MAIN) {
-  await runCli();
-}
-
-export { cmdHelp, cmdInit, cmdUpdate, cmdModels, cmdHealth, cmdFileOp, cmdLifecyclePreflight, cmdFindPhase, cmdPhaseStatus, cmdVerify, cmdScaffold, runCli, FRAMEWORK_VERSION, createCliContext };
+    adapters: createAdapterRegistry({
+      cwd,
+      workflows: WORKFLOWS,
+      renderAgentsBoundedBlock,
+      renderAgentsFileContent,
+      renderOpenCodeCommandContent,
+      renderSkillContent,
+      upsertBoundedBlock,
+      getDelegateContent,
+      loadProjectModelConfig,
+      getRuntimeModelOverride,
+      resolveRuntimeAgentModel,
+    }),
+  };
+}
+
+const INIT_CONTEXT = createCliContext(process.cwd());
+
+const cmdInit = createCmdInit(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,
+  models: cmdModels,
+  health: cmdHealth,
+  'file-op': cmdFileOp,
+  'lifecycle-preflight': cmdLifecyclePreflight,
+  'find-phase': cmdFindPhase,
+  'phase-status': cmdPhaseStatus,
+  verify: cmdVerify,
+  scaffold: cmdScaffold,
+  help: cmdHelp,
+};
+
+async function runCli(cliCommand = command, ...cliArgs) {
+  const normalizedArgs = cliArgs.length === 0
+    ? args
+    : cliArgs.length === 1 && Array.isArray(cliArgs[0])
+      ? cliArgs[0]
+      : cliArgs;
+
+  process.exitCode = 0;
+
+  if (!cliCommand || !COMMANDS[cliCommand]) {
+    cmdHelp();
+    if (cliCommand) process.exitCode = 1;
+    return;
+  }
+
+  await COMMANDS[cliCommand](...normalizedArgs);
+}
+
+if (IS_MAIN) {
+  await runCli();
+}
+
+export { cmdHelp, cmdInit, cmdUpdate, cmdModels, cmdHealth, cmdFileOp, cmdLifecyclePreflight, cmdFindPhase, cmdPhaseStatus, cmdVerify, cmdScaffold, runCli, FRAMEWORK_VERSION, createCliContext };

package/bin/lib/cli-utils.mjs

@@ -1,28 +1,28 @@
-// cli-utils.mjs — Pure CLI utility functions (no external deps)
-
-export function parseFlagValue(flagArgs, flagName) {
-  const idx = flagArgs.indexOf(flagName);
-  if (idx === -1) return { present: false, value: null, invalid: false };
-
-  const value = flagArgs[idx + 1];
-  if (!value || value.startsWith('--')) {
-    return { present: true, value: null, invalid: true };
-  }
-
-  return { present: true, value, invalid: false };
-}
-
-export function parseToolsFlag(flagArgs) {
-  const { value } = parseFlagValue(flagArgs, '--tools');
-  if (!value) return [];
-  if (value === 'all') return ['claude', 'opencode', 'codex', 'agents', 'cursor', 'copilot', 'gemini'];
-  return value.split(',').map((v) => v.trim()).filter(Boolean);
-}
-
-export function parseAutoFlag(flagArgs) {
-  return flagArgs.includes('--auto');
-}
-
-export function output(data) {
-  console.log(JSON.stringify(data, null, 2));
-}
+// cli-utils.mjs — Pure CLI utility functions (no external deps)
+
+export function parseFlagValue(flagArgs, flagName) {
+  const idx = flagArgs.indexOf(flagName);
+  if (idx === -1) return { present: false, value: null, invalid: false };
+
+  const value = flagArgs[idx + 1];
+  if (!value || value.startsWith('--')) {
+    return { present: true, value: null, invalid: true };
+  }
+
+  return { present: true, value, invalid: false };
+}
+
+export function parseToolsFlag(flagArgs) {
+  const { value } = parseFlagValue(flagArgs, '--tools');
+  if (!value) return [];
+  if (value === 'all') return ['claude', 'opencode', 'codex', 'agents', 'cursor', 'copilot', 'gemini'];
+  return value.split(',').map((v) => v.trim()).filter(Boolean);
+}
+
+export function parseAutoFlag(flagArgs) {
+  return flagArgs.includes('--auto');
+}
+
+export function output(data) {
+  console.log(JSON.stringify(data, null, 2));
+}

package/bin/lib/evidence-contract.mjs

@@ -1,112 +1,112 @@
-const EVIDENCE_KINDS = Object.freeze(['code', 'test', 'runtime', 'delivery', 'human']);
-const DELIVERY_POSTURES = Object.freeze(['repo_only', 'delivery_sensitive']);
-const CLOSURE_SURFACES = Object.freeze(['verify', 'audit-milestone', 'complete-milestone']);
-
-const LEGACY_EVIDENCE_ALIASES = Object.freeze({
-  code: 'code',
-  test: 'test',
-  runtime: 'runtime',
-  delivery: 'delivery',
-  human: 'human',
-  'code-evidence': 'code',
-  'repo-test': 'test',
-  'runtime-check': 'runtime',
-  'user-confirmation': 'human',
-});
-
-const EVIDENCE_MATRIX = Object.freeze({
-  verify: Object.freeze({
-    repo_only: Object.freeze({
-      requiredKinds: Object.freeze(['code']),
-      recommendedKinds: Object.freeze(['test']),
-      blockedSoloKinds: Object.freeze(['human', 'delivery']),
-    }),
-    delivery_sensitive: Object.freeze({
-      requiredKinds: Object.freeze(['code', 'runtime']),
-      recommendedKinds: Object.freeze(['test', 'delivery', 'human']),
-      blockedSoloKinds: Object.freeze(['code', 'human']),
-    }),
-  }),
-  'audit-milestone': Object.freeze({
-    repo_only: Object.freeze({
-      requiredKinds: Object.freeze(['code', 'test']),
-      recommendedKinds: Object.freeze(['runtime', 'human']),
-      blockedSoloKinds: Object.freeze(['human', 'delivery']),
-    }),
-    delivery_sensitive: Object.freeze({
-      requiredKinds: Object.freeze(['code', 'test', 'runtime', 'delivery']),
-      recommendedKinds: Object.freeze(['human']),
-      blockedSoloKinds: Object.freeze(['code', 'human']),
-    }),
-  }),
-  'complete-milestone': Object.freeze({
-    repo_only: Object.freeze({
-      requiredKinds: Object.freeze(['code', 'test']),
-      recommendedKinds: Object.freeze(['runtime']),
-      blockedSoloKinds: Object.freeze(['human', 'delivery']),
-    }),
-    delivery_sensitive: Object.freeze({
-      requiredKinds: Object.freeze(['code', 'test', 'runtime', 'delivery']),
-      recommendedKinds: Object.freeze(['human']),
-      blockedSoloKinds: Object.freeze(['code', 'human']),
-    }),
-  }),
-});
-
-export { CLOSURE_SURFACES, DELIVERY_POSTURES, EVIDENCE_KINDS };
-
-export function normalizeEvidenceKind(kind) {
-  if (!kind) {
-    return null;
-  }
-
-  return LEGACY_EVIDENCE_ALIASES[kind] ?? null;
-}
-
-export function normalizeEvidenceKinds(kinds = []) {
-  const normalized = [];
-  for (const kind of kinds) {
-    const resolved = normalizeEvidenceKind(kind);
-    if (resolved && !normalized.includes(resolved)) {
-      normalized.push(resolved);
-    }
-  }
-  return normalized;
-}
-
-export function isClosureSurface(surface) {
-  return CLOSURE_SURFACES.includes(surface);
-}
-
-export function getEvidenceContract(surface, deliveryPosture) {
-  const matrix = EVIDENCE_MATRIX[surface];
-  if (!matrix) {
-    throw new Error(`Unsupported closure evidence surface: ${surface}`);
-  }
-
-  const posture = matrix[deliveryPosture];
-  if (!posture) {
-    throw new Error(`Unsupported delivery posture for ${surface}: ${deliveryPosture}`);
-  }
-
-  return {
-    surface,
-    deliveryPosture,
-    supportedKinds: [...EVIDENCE_KINDS],
-    requiredKinds: [...posture.requiredKinds],
-    recommendedKinds: [...posture.recommendedKinds],
-    blockedSoloKinds: [...posture.blockedSoloKinds],
-  };
-}
-
-export function describeEvidenceSurface(surface) {
-  if (!isClosureSurface(surface)) {
-    return null;
-  }
-
-  return {
-    surface,
-    supportedKinds: [...EVIDENCE_KINDS],
-    deliveryPostures: DELIVERY_POSTURES.map((deliveryPosture) => getEvidenceContract(surface, deliveryPosture)),
-  };
-}
+const EVIDENCE_KINDS = Object.freeze(['code', 'test', 'runtime', 'delivery', 'human']);
+const DELIVERY_POSTURES = Object.freeze(['repo_only', 'delivery_sensitive']);
+const CLOSURE_SURFACES = Object.freeze(['verify', 'audit-milestone', 'complete-milestone']);
+
+const LEGACY_EVIDENCE_ALIASES = Object.freeze({
+  code: 'code',
+  test: 'test',
+  runtime: 'runtime',
+  delivery: 'delivery',
+  human: 'human',
+  'code-evidence': 'code',
+  'repo-test': 'test',
+  'runtime-check': 'runtime',
+  'user-confirmation': 'human',
+});
+
+const EVIDENCE_MATRIX = Object.freeze({
+  verify: Object.freeze({
+    repo_only: Object.freeze({
+      requiredKinds: Object.freeze(['code']),
+      recommendedKinds: Object.freeze(['test']),
+      blockedSoloKinds: Object.freeze(['human', 'delivery']),
+    }),
+    delivery_sensitive: Object.freeze({
+      requiredKinds: Object.freeze(['code', 'runtime']),
+      recommendedKinds: Object.freeze(['test', 'delivery', 'human']),
+      blockedSoloKinds: Object.freeze(['code', 'human']),
+    }),
+  }),
+  'audit-milestone': Object.freeze({
+    repo_only: Object.freeze({
+      requiredKinds: Object.freeze(['code', 'test']),
+      recommendedKinds: Object.freeze(['runtime', 'human']),
+      blockedSoloKinds: Object.freeze(['human', 'delivery']),
+    }),
+    delivery_sensitive: Object.freeze({
+      requiredKinds: Object.freeze(['code', 'test', 'runtime', 'delivery']),
+      recommendedKinds: Object.freeze(['human']),
+      blockedSoloKinds: Object.freeze(['code', 'human']),
+    }),
+  }),
+  'complete-milestone': Object.freeze({
+    repo_only: Object.freeze({
+      requiredKinds: Object.freeze(['code', 'test']),
+      recommendedKinds: Object.freeze(['runtime']),
+      blockedSoloKinds: Object.freeze(['human', 'delivery']),
+    }),
+    delivery_sensitive: Object.freeze({
+      requiredKinds: Object.freeze(['code', 'test', 'runtime', 'delivery']),
+      recommendedKinds: Object.freeze(['human']),
+      blockedSoloKinds: Object.freeze(['code', 'human']),
+    }),
+  }),
+});
+
+export { CLOSURE_SURFACES, DELIVERY_POSTURES, EVIDENCE_KINDS };
+
+export function normalizeEvidenceKind(kind) {
+  if (!kind) {
+    return null;
+  }
+
+  return LEGACY_EVIDENCE_ALIASES[kind] ?? null;
+}
+
+export function normalizeEvidenceKinds(kinds = []) {
+  const normalized = [];
+  for (const kind of kinds) {
+    const resolved = normalizeEvidenceKind(kind);
+    if (resolved && !normalized.includes(resolved)) {
+      normalized.push(resolved);
+    }
+  }
+  return normalized;
+}
+
+export function isClosureSurface(surface) {
+  return CLOSURE_SURFACES.includes(surface);
+}
+
+export function getEvidenceContract(surface, deliveryPosture) {
+  const matrix = EVIDENCE_MATRIX[surface];
+  if (!matrix) {
+    throw new Error(`Unsupported closure evidence surface: ${surface}`);
+  }
+
+  const posture = matrix[deliveryPosture];
+  if (!posture) {
+    throw new Error(`Unsupported delivery posture for ${surface}: ${deliveryPosture}`);
+  }
+
+  return {
+    surface,
+    deliveryPosture,
+    supportedKinds: [...EVIDENCE_KINDS],
+    requiredKinds: [...posture.requiredKinds],
+    recommendedKinds: [...posture.recommendedKinds],
+    blockedSoloKinds: [...posture.blockedSoloKinds],
+  };
+}
+
+export function describeEvidenceSurface(surface) {
+  if (!isClosureSurface(surface)) {
+    return null;
+  }
+
+  return {
+    surface,
+    supportedKinds: [...EVIDENCE_KINDS],
+    deliveryPostures: DELIVERY_POSTURES.map((deliveryPosture) => getEvidenceContract(surface, deliveryPosture)),
+  };
+}