gsdd-cli 0.18.4 → 0.19.0

package/bin/lib/plan-constants.mjs

@@ -1,30 +1,30 @@
-export const PLAN_CHECK_DIMENSIONS = [
-  'requirement_coverage',
-  'task_completeness',
-  'dependency_correctness',
-  'key_link_completeness',
-  'scope_sanity',
-  'must_have_quality',
-  'context_compliance',
-  'goal_achievement',
-  'approach_alignment',
-];
-
-export const MAX_CHECKER_CYCLES = 3;
-
-export const CHECKER_STATUSES = ['passed', 'issues_found'];
-
-export const CHECKER_JSON_SCHEMA = {
-  status: 'passed | issues_found',
-  summary: 'string',
-  issues: [
-    {
-      dimension: 'string',
-      severity: 'blocker | warning',
-      description: 'string',
-      plan: 'string',
-      task: 'string',
-      fix_hint: 'string',
-    },
-  ],
-};
+export const PLAN_CHECK_DIMENSIONS = [
+  'requirement_coverage',
+  'task_completeness',
+  'dependency_correctness',
+  'key_link_completeness',
+  'scope_sanity',
+  'must_have_quality',
+  'context_compliance',
+  'goal_achievement',
+  'approach_alignment',
+];
+
+export const MAX_CHECKER_CYCLES = 3;
+
+export const CHECKER_STATUSES = ['passed', 'issues_found'];
+
+export const CHECKER_JSON_SCHEMA = {
+  status: 'passed | issues_found',
+  summary: 'string',
+  issues: [
+    {
+      dimension: 'string',
+      severity: 'blocker | warning',
+      description: 'string',
+      plan: 'string',
+      task: 'string',
+      fix_hint: 'string',
+    },
+  ],
+};

package/bin/lib/provenance.mjs

@@ -1,56 +1,59 @@
-function normalizePrState(prState) {
-  if (!prState) return 'none';
-  return String(prState).trim().toLowerCase();
-}
-
-function normalizeCount(value) {
-  if (value === 'unknown' || value === null || value === undefined) return 'unknown';
-  const numeric = Number(value);
-  return Number.isFinite(numeric) ? numeric : 'unknown';
-}
-
-function normalizeCheckpointWorkflow(workflow) {
-  const normalized = String(workflow || 'generic').trim().toLowerCase();
-  return ['phase', 'quick', 'generic'].includes(normalized) ? normalized : 'generic';
-}
-
+function normalizePrState(prState) {
+  if (!prState) return 'none';
+  return String(prState).trim().toLowerCase();
+}
+
+function normalizeCount(value) {
+  if (value === 'unknown' || value === null || value === undefined) return 'unknown';
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : 'unknown';
+}
+
+function normalizeCheckpointWorkflow(workflow) {
+  const normalized = String(workflow || 'generic').trim().toLowerCase();
+  return ['phase', 'quick', 'generic'].includes(normalized) ? normalized : 'generic';
+}
+
 export function classifyCheckpointRouting(workflow) {
   const normalizedWorkflow = normalizeCheckpointWorkflow(workflow);
   const progressBlocks = normalizedWorkflow === 'phase' || normalizedWorkflow === 'quick';
-
-  return {
-    workflow: normalizedWorkflow,
-    routingClass: progressBlocks ? 'blocking' : 'informational',
-    progressBlocks,
-    resumeOwnsCleanup: true,
-  };
-}
-
+
+  return {
+    workflow: normalizedWorkflow,
+    routingClass: progressBlocks ? 'blocking' : 'informational',
+    progressBlocks,
+    resumeOwnsCleanup: true,
+  };
+}
+
 export function parseGitStatusShort(statusText = '') {
-  const lines = statusText
-    .replace(/\r\n/g, '\n')
-    .split('\n')
-    .map((line) => line.trimEnd())
-    .filter(Boolean);
-
-  const files = [];
-  for (const line of lines) {
-    const match = line.match(/^(.)(.)\s+(.+)$/);
-    if (!match) continue;
-
-    const indexStatus = match[1];
-    const worktreeStatus = match[2];
-    if (indexStatus === '!' && worktreeStatus === '!') continue;
-
-    const filePath = match[3].replace(/\\/g, '/');
-    files.push({
-      path: filePath,
-      staged: indexStatus !== ' ' && indexStatus !== '?' && indexStatus !== '!',
-      unstaged: worktreeStatus !== ' ' && worktreeStatus !== '?' && worktreeStatus !== '!',
-      untracked: indexStatus === '?' || worktreeStatus === '?',
-    });
-  }
-
+  const lines = statusText
+    .replace(/\r\n/g, '\n')
+    .split('\n')
+    .map((line) => line.trimEnd())
+    .filter(Boolean);
+
+  const files = [];
+  for (const line of lines) {
+    const match = line.match(/^(.)(.)\s+(.+)$/);
+    if (!match) continue;
+
+    const indexStatus = match[1];
+    const worktreeStatus = match[2];
+    if (indexStatus === '!' && worktreeStatus === '!') continue;
+
+    const rawPath = match[3].replace(/\\/g, '/');
+    const renameMatch = rawPath.match(/^(.*?)\s+->\s+(.*?)$/);
+    const filePath = renameMatch ? renameMatch[2] : rawPath;
+    files.push({
+      path: filePath,
+      fromPath: renameMatch ? renameMatch[1] : null,
+      staged: indexStatus !== ' ' && indexStatus !== '?' && indexStatus !== '!',
+      unstaged: worktreeStatus !== ' ' && worktreeStatus !== '?' && worktreeStatus !== '!',
+      untracked: indexStatus === '?' || worktreeStatus === '?',
+    });
+  }
+
   return {
     files,
     stagedCount: files.filter((file) => file.staged).length,
@@ -206,55 +209,55 @@ export function buildProvenanceSnapshot({
   });
 
   const warnings = [];
-
-  if (status.dirty) {
-    warnings.push({
-      id: 'dirty_worktree',
-      severity: 'warning',
-      summary: 'Local worktree contains staged, unstaged, or untracked changes.',
-    });
-  }
-
-  if (commitsAheadOfMain !== 'unknown' && commitsAheadOfMain > 0) {
-    warnings.push({
-      id: 'ahead_of_main',
-      severity: 'warning',
-      summary: `${commitsAheadOfMain} commit(s) are ahead of main on the current branch.`,
-    });
-  }
-
-  if (commitsAheadOfRemote !== 'unknown' && commitsAheadOfRemote > 0) {
-    warnings.push({
-      id: 'unpushed_commits',
-      severity: 'warning',
-      summary: `${commitsAheadOfRemote} commit(s) are ahead of the tracked remote branch.`,
-    });
-  }
-
-  if (prState === 'none') {
-    warnings.push({
-      id: 'missing_pr',
-      severity: 'warning',
-      summary: 'No pull request is associated with the current branch.',
-    });
-  }
-
-  if (git.staleBranch) {
-    warnings.push({
-      id: 'stale_branch',
-      severity: 'warning',
-      summary: 'The current branch is stale or spent relative to the intended integration surface.',
-    });
-  }
-
-  if (git.mixedScope) {
-    warnings.push({
-      id: 'mixed_scope',
-      severity: 'warning',
-      summary: 'The current worktree appears to mix multiple write scopes or phases.',
-    });
-  }
-
+
+  if (status.dirty) {
+    warnings.push({
+      id: 'dirty_worktree',
+      severity: 'warning',
+      summary: 'Local worktree contains staged, unstaged, or untracked changes.',
+    });
+  }
+
+  if (commitsAheadOfMain !== 'unknown' && commitsAheadOfMain > 0) {
+    warnings.push({
+      id: 'ahead_of_main',
+      severity: 'warning',
+      summary: `${commitsAheadOfMain} commit(s) are ahead of main on the current branch.`,
+    });
+  }
+
+  if (commitsAheadOfRemote !== 'unknown' && commitsAheadOfRemote > 0) {
+    warnings.push({
+      id: 'unpushed_commits',
+      severity: 'warning',
+      summary: `${commitsAheadOfRemote} commit(s) are ahead of the tracked remote branch.`,
+    });
+  }
+
+  if (prState === 'none') {
+    warnings.push({
+      id: 'missing_pr',
+      severity: 'warning',
+      summary: 'No pull request is associated with the current branch.',
+    });
+  }
+
+  if (git.staleBranch) {
+    warnings.push({
+      id: 'stale_branch',
+      severity: 'warning',
+      summary: 'The current branch is stale or spent relative to the intended integration surface.',
+    });
+  }
+
+  if (git.mixedScope) {
+    warnings.push({
+      id: 'mixed_scope',
+      severity: 'warning',
+      summary: 'The current worktree appears to mix multiple write scopes or phases.',
+    });
+  }
+
   if (git.materialCheckpointMismatch) {
     warnings.push({
       id: 'checkpoint_mismatch',
@@ -299,14 +302,14 @@ export function buildProvenanceSnapshot({
     },
     git: {
       branch: git.branch || 'unknown',
-      prState,
-      commitsAheadOfMain,
-      commitsAheadOfRemote,
-      stagedCount: status.stagedCount,
-      unstagedCount: status.unstagedCount,
-      untrackedCount: status.untrackedCount,
-      dirty: status.dirty,
-    },
+      prState,
+      commitsAheadOfMain,
+      commitsAheadOfRemote,
+      stagedCount: status.stagedCount,
+      unstagedCount: status.unstagedCount,
+      untrackedCount: status.untrackedCount,
+      dirty: status.dirty,
+    },
     integrationSurface: {
       staleBranch: Boolean(git.staleBranch),
       mixedScope: Boolean(git.mixedScope),

package/bin/lib/rendering.mjs

@@ -1,100 +1,128 @@
-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');
-
-function getWorkflowContent(workflowFile) {
-  const filePath = join(DISTILLED_DIR, 'workflows', workflowFile);
-  if (existsSync(filePath)) return readFileSync(filePath, 'utf-8');
-  return `<!-- Workflow file not found: ${workflowFile} -->\n`;
-}
-
-function getDelegateContent(delegateFile) {
-  const filePath = join(DISTILLED_DIR, 'templates', 'delegates', delegateFile);
-  if (existsSync(filePath)) return readFileSync(filePath, 'utf-8');
-  return `<!-- Delegate file not found: ${delegateFile} -->\n`;
-}
-
+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 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);
+  if (existsSync(filePath)) return readFileSync(filePath, 'utf-8');
+  return `<!-- Workflow file not found: ${workflowFile} -->\n`;
+}
+
+function getDelegateContent(delegateFile) {
+  const filePath = join(DISTILLED_DIR, 'templates', 'delegates', delegateFile);
+  if (existsSync(filePath)) return readFileSync(filePath, 'utf-8');
+  return `<!-- Delegate file not found: ${delegateFile} -->\n`;
+}
+
 function renderSkillContent(workflow) {
   const workflowContent = getWorkflowContent(workflow.workflow);
   return `---
 name: ${workflow.name}
 description: ${workflow.description}
-context: fork
-agent: ${workflow.agent}
----
-
+context: fork
+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, consumeWorkspaceRootArg, resolveWorkspaceContext } from './lib/workspace-root.mjs';
 
-  return `#!/usr/bin/env node
+const COMMANDS = {
+  'file-op': cmdFileOp,
+  'lifecycle-preflight': cmdLifecyclePreflight,
+  'phase-status': cmdPhaseStatus,
+};
 
-import { spawnSync } from 'node:child_process';
+function printHelp() {
+  console.log([
+    'Usage: node .planning/bin/gsdd.mjs [--workspace-root <path>] <command> [args]',
+    '',
+    'Local workflow helper commands:',
+    '  file-op <copy|delete|regex-sub>',
+    '                               Run deterministic workspace-confined file operations',
+    '                               Example: node .planning/bin/gsdd.mjs file-op delete .planning/.continue-here.bak --missing ok',
+    '  phase-status <N> <status>   Update ROADMAP.md phase status ([ ] / [-] / [x])',
+    '                               Example: node .planning/bin/gsdd.mjs phase-status 1 done',
+    '  lifecycle-preflight <surface> [phase]',
+    '                               Inspect lifecycle gate results for a workflow surface',
+    '                               Example: node .planning/bin/gsdd.mjs lifecycle-preflight verify 1 --expects-mutation phase-status',
+    '',
+    'Advanced option:',
+    '  --workspace-root <path>     Override workspace root discovery before or after the subcommand',
+  ].join('\\n'));
+}
 
-const packageSpec = ${JSON.stringify(packageSpec)};
-const args = process.argv.slice(2);
-const env = { ...process.env };
+function applyWorkspaceRootOverride(workspaceRootArg) {
+  if (!workspaceRootArg) {
+    bootstrapHelperWorkspace(import.meta.url);
+    return true;
+  }
 
-function forwardResult(result, fallbackMessage) {
-  if (result.error) {
-    console.error(fallbackMessage ?? result.error.message);
+  const context = resolveWorkspaceContext(['--workspace-root', workspaceRootArg]);
+  if (context.invalid) {
+    console.error(context.error);
     process.exitCode = 1;
-    return;
+    return false;
   }
 
-  if (typeof result.status === 'number') {
-    process.exitCode = result.status;
-    return;
+  process.env.GSDD_WORKSPACE_ROOT = context.workspaceRoot;
+  try {
+    process.chdir(context.workspaceRoot);
+  } catch {
+    // best-effort: command handlers also resolve from GSDD_WORKSPACE_ROOT
   }
+  return true;
+}
 
-  if (result.signal) {
+async function main() {
+  const parsed = consumeWorkspaceRootArg(process.argv.slice(2));
+  if (parsed.invalid) {
+    console.error('Usage: --workspace-root <path>');
     process.exitCode = 1;
+    return;
   }
-}
 
-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),
-      },
-    });
+  if (!applyWorkspaceRootOverride(parsed.workspaceRootArg)) return;
+
+  const [command, ...args] = parsed.args;
+
+  if (!command || command === 'help' || command === '--help') {
+    printHelp();
+    return;
   }
 
-  return spawnSync('npm', ['exec', '--yes', \`--package=\${packageSpec}\`, '--', 'gsdd', ...args], {
-    stdio: 'inherit',
-    env,
-  });
-}
+  const handler = COMMANDS[command];
+  if (!handler) {
+    printHelp();
+    process.exitCode = 1;
+    return;
+  }
 
-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 handler(...args);
 }
+
+await main();
 `;
 }
 
@@ -113,11 +141,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 +167,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),
+    })),
   ];
 }
 
@@ -135,62 +183,62 @@ function buildPortableSkillEntries(workflows) {
     relativePath: `.agents/skills/${workflow.name}/SKILL.md`,
     content: renderSkillContent(workflow),
   }));
-}
-
-function renderOpenCodeCommandContent(workflow) {
-  const workflowContent = getWorkflowContent(workflow.workflow);
-  return `---
-description: ${workflow.description}
----
-
-${workflowContent}`;
-}
-
-function renderAgentsBoundedBlock() {
-  const blockPath = join(DISTILLED_DIR, 'templates', 'agents.block.md');
-  if (existsSync(blockPath)) return readFileSync(blockPath, 'utf-8').trim();
-  return '## GSDD Governance (Generated)\n\n- Framework: GSDD\n- Planning: .planning/\n- Workflows: .agents/skills/gsdd-*/SKILL.md';
-}
-
-function renderAgentsFileContent() {
-  const templatePath = join(DISTILLED_DIR, 'templates', 'agents.md');
-  if (existsSync(templatePath)) {
-    const template = readFileSync(templatePath, 'utf-8');
-    return template.replace('{{GSDD_BLOCK}}', renderAgentsBoundedBlock()).trimEnd() + '\n';
-  }
-  const block = renderAgentsBoundedBlock();
-  return `# AGENTS.md - GSDD Governance\n\n<!-- BEGIN GSDD -->\n${block}\n<!-- END GSDD -->\n`;
-}
-
-function escapeRegExp(value) {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
-function upsertBoundedBlock(existing, blockContent) {
-  const begin = '<!-- BEGIN GSDD -->';
-  const end = '<!-- END GSDD -->';
-  const bounded = `${begin}\n${blockContent.trimEnd()}\n${end}`;
-
-  const re = new RegExp(`${escapeRegExp(begin)}[\\s\\S]*?${escapeRegExp(end)}`, 'm');
-  if (re.test(existing)) return existing.replace(re, bounded);
-
-  const lines = existing.split(/\r?\n/);
-  const h1Idx = lines.findIndex((line) => /^#\s+/.test(line));
-  if (h1Idx !== -1) {
-    const insertAt = h1Idx + 1;
-    const out = [
-      ...lines.slice(0, insertAt),
-      '',
-      bounded,
-      '',
-      ...lines.slice(insertAt),
-    ];
-    return out.join('\n').replace(/\n{3,}/g, '\n\n');
-  }
-
-  return `${bounded}\n\n${existing}`.replace(/\n{3,}/g, '\n\n');
-}
-
+}
+
+function renderOpenCodeCommandContent(workflow) {
+  const workflowContent = getWorkflowContent(workflow.workflow);
+  return `---
+description: ${workflow.description}
+---
+
+${workflowContent}`;
+}
+
+function renderAgentsBoundedBlock() {
+  const blockPath = join(DISTILLED_DIR, 'templates', 'agents.block.md');
+  if (existsSync(blockPath)) return readFileSync(blockPath, 'utf-8').trim();
+  return '## GSDD Governance (Generated)\n\n- Framework: GSDD\n- Planning: .planning/\n- Workflows: .agents/skills/gsdd-*/SKILL.md';
+}
+
+function renderAgentsFileContent() {
+  const templatePath = join(DISTILLED_DIR, 'templates', 'agents.md');
+  if (existsSync(templatePath)) {
+    const template = readFileSync(templatePath, 'utf-8');
+    return template.replace('{{GSDD_BLOCK}}', renderAgentsBoundedBlock()).trimEnd() + '\n';
+  }
+  const block = renderAgentsBoundedBlock();
+  return `# AGENTS.md - GSDD Governance\n\n<!-- BEGIN GSDD -->\n${block}\n<!-- END GSDD -->\n`;
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function upsertBoundedBlock(existing, blockContent) {
+  const begin = '<!-- BEGIN GSDD -->';
+  const end = '<!-- END GSDD -->';
+  const bounded = `${begin}\n${blockContent.trimEnd()}\n${end}`;
+
+  const re = new RegExp(`${escapeRegExp(begin)}[\\s\\S]*?${escapeRegExp(end)}`, 'm');
+  if (re.test(existing)) return existing.replace(re, bounded);
+
+  const lines = existing.split(/\r?\n/);
+  const h1Idx = lines.findIndex((line) => /^#\s+/.test(line));
+  if (h1Idx !== -1) {
+    const insertAt = h1Idx + 1;
+    const out = [
+      ...lines.slice(0, insertAt),
+      '',
+      bounded,
+      '',
+      ...lines.slice(insertAt),
+    ];
+    return out.join('\n').replace(/\n{3,}/g, '\n\n');
+  }
+
+  return `${bounded}\n\n${existing}`.replace(/\n{3,}/g, '\n\n');
+}
+
 export {
   buildPlanningCliHelperEntries,
   buildPortableSkillEntries,