gsdd-cli 0.18.0 → 0.18.1

package/bin/lib/manifest.mjs

@@ -39,9 +39,10 @@ export function hashDirectory(dir, baseDir = dir) {
 /**
  * Build a full manifest snapshot from installed project files.
  */
-export function buildManifest({ planningDir, frameworkVersion }) {
-  const templatesDir = join(planningDir, 'templates');
-  const rolesDir = join(templatesDir, 'roles');
+export function buildManifest({ planningDir, frameworkVersion }) {
+  const templatesDir = join(planningDir, 'templates');
+  const rolesDir = join(templatesDir, 'roles');
+  const runtimeHelpersDir = join(planningDir, 'bin');
 
   // Template subcategories
   const delegatesHashes = hashDirectory(join(templatesDir, 'delegates'), join(templatesDir, 'delegates'));
@@ -59,28 +60,31 @@ export function buildManifest({ planningDir, frameworkVersion }) {
     }
   }
 
-  // Role contracts
-  const rolesHashes = {};
-  if (existsSync(rolesDir)) {
-    for (const entry of readdirSync(rolesDir)) {
-      if (entry.endsWith('.md')) {
-        rolesHashes[entry] = fileHash(join(rolesDir, entry));
-      }
-    }
-  }
-
-  return {
-    frameworkVersion,
-    generatedAt: new Date().toISOString(),
+  // Role contracts
+  const rolesHashes = {};
+  if (existsSync(rolesDir)) {
+    for (const entry of readdirSync(rolesDir)) {
+      if (entry.endsWith('.md')) {
+        rolesHashes[entry] = fileHash(join(rolesDir, entry));
+      }
+    }
+  }
+
+  const runtimeHelpersHashes = hashDirectory(runtimeHelpersDir, planningDir);
+
+  return {
+    frameworkVersion,
+    generatedAt: new Date().toISOString(),
     templates: {
       delegates: delegatesHashes,
       research: researchHashes,
       codebase: codebaseHashes,
       root: rootHashes,
-    },
-    roles: rolesHashes,
-  };
-}
+    },
+    roles: rolesHashes,
+    runtimeHelpers: runtimeHelpersHashes,
+  };
+}
 
 /**
  * Read existing manifest from planningDir, or return null if missing/corrupt.

package/bin/lib/provenance.mjs

@@ -14,9 +14,9 @@ function normalizeCheckpointWorkflow(workflow) {
   return ['phase', 'quick', 'generic'].includes(normalized) ? normalized : 'generic';
 }
 
-export function classifyCheckpointRouting(workflow) {
-  const normalizedWorkflow = normalizeCheckpointWorkflow(workflow);
-  const progressBlocks = normalizedWorkflow === 'phase' || normalizedWorkflow === 'quick';
+export function classifyCheckpointRouting(workflow) {
+  const normalizedWorkflow = normalizeCheckpointWorkflow(workflow);
+  const progressBlocks = normalizedWorkflow === 'phase' || normalizedWorkflow === 'quick';
 
   return {
     workflow: normalizedWorkflow,
@@ -26,7 +26,7 @@ export function classifyCheckpointRouting(workflow) {
   };
 }
 
-export function parseGitStatusShort(statusText = '') {
+export function parseGitStatusShort(statusText = '') {
   const lines = statusText
     .replace(/\r\n/g, '\n')
     .split('\n')
@@ -51,27 +51,161 @@ export function parseGitStatusShort(statusText = '') {
     });
   }
 
-  return {
-    files,
-    stagedCount: files.filter((file) => file.staged).length,
-    unstagedCount: files.filter((file) => file.unstaged).length,
-    untrackedCount: files.filter((file) => file.untracked).length,
-    dirty: files.length > 0,
-  };
-}
-
-export function buildProvenanceSnapshot({
-  checkpoint = {},
-  planning = {},
-  git = {},
-} = {}) {
-  const checkpointRouting = classifyCheckpointRouting(checkpoint.workflow);
-  const status = parseGitStatusShort(git.statusShort || '');
-  const commitsAheadOfMain = normalizeCount(git.commitsAheadOfMain);
-  const commitsAheadOfRemote = normalizeCount(git.commitsAheadOfRemote);
-  const prState = normalizePrState(git.prState);
-
-  const warnings = [];
+  return {
+    files,
+    stagedCount: files.filter((file) => file.staged).length,
+    unstagedCount: files.filter((file) => file.unstaged).length,
+    untrackedCount: files.filter((file) => file.untracked).length,
+    dirty: files.length > 0,
+  };
+}
+
+export function classifyBrownfieldCheckpointPrecedence({
+  checkpoint = {},
+  planning = {},
+  quick = {},
+  brownfieldChange = {},
+  git = {},
+  status = parseGitStatusShort(git.statusShort || ''),
+} = {}) {
+  const checkpointRouting = classifyCheckpointRouting(checkpoint.workflow);
+  if (!brownfieldChange?.exists) {
+    return {
+      primary: checkpointRouting.progressBlocks ? 'checkpoint' : 'none',
+      checkpointRouting,
+      branchAligned: false,
+      scopeAligned: false,
+      executionActive: false,
+      checkpointCanOverrideBrownfield: false,
+      strictMatchRequired: false,
+    };
+  }
+
+  if (checkpointRouting.workflow === 'generic') {
+    return {
+      primary: 'brownfield_change',
+      checkpointRouting,
+      branchAligned: false,
+      scopeAligned: false,
+      executionActive: false,
+      checkpointCanOverrideBrownfield: false,
+      strictMatchRequired: true,
+    };
+  }
+
+  const brownfieldMismatch = classifyBrownfieldArtifactMismatch({
+    brownfieldChange,
+    git,
+    status,
+  });
+  const currentBranch = normalizeBranchName(git.branch);
+  const checkpointBranch = normalizeBranchName(checkpoint.branch);
+  const brownfieldBranch = normalizeBranchName(brownfieldChange.currentIntegrationSurface);
+  const branchAligned = Boolean(
+    currentBranch
+    && checkpointBranch
+    && brownfieldBranch
+    && checkpointBranch === currentBranch
+    && brownfieldBranch === currentBranch
+  );
+  const scopeAligned = !brownfieldMismatch.warnings.some((warning) =>
+    warning.id === 'brownfield_scope_mismatch' || warning.id === 'brownfield_status_mismatch'
+  );
+  const executionActive = checkpointExecutionIsActive({
+    checkpoint,
+    checkpointRouting,
+    planning,
+    quick,
+  });
+  const checkpointCanOverrideBrownfield = branchAligned && scopeAligned && executionActive;
+
+  return {
+    primary: checkpointCanOverrideBrownfield ? 'checkpoint' : 'brownfield_change',
+    checkpointRouting,
+    branchAligned,
+    scopeAligned,
+    executionActive,
+    checkpointCanOverrideBrownfield,
+    strictMatchRequired: true,
+  };
+}
+
+export function classifyBrownfieldArtifactMismatch({
+  brownfieldChange = {},
+  git = {},
+  status = parseGitStatusShort(git.statusShort || ''),
+} = {}) {
+  if (!brownfieldChange?.exists) {
+    return {
+      warnings: [],
+      requiresAcknowledgement: false,
+      outsideOwnedPaths: [],
+    };
+  }
+
+  const warnings = [];
+  const declaredBranch = normalizeDeclaredBranch(brownfieldChange.currentIntegrationSurface);
+  const branch = String(git.branch || '').trim().toLowerCase();
+  if (declaredBranch && branch && declaredBranch !== branch) {
+    warnings.push({
+      id: 'brownfield_branch_mismatch',
+      severity: 'acknowledgement_required',
+      summary: `CHANGE.md says the active integration surface is "${brownfieldChange.currentIntegrationSurface}", but git reports "${git.branch}".`,
+    });
+  }
+
+  const ownedPaths = normalizeOwnedPaths(brownfieldChange.declaredOwnedPaths || []);
+  const outsideOwnedPaths = ownedPaths.length === 0
+    ? []
+    : status.files
+      .map((file) => file.path)
+      .filter((filePath) => !ownedPaths.some((ownedPath) => matchesOwnedPath(filePath, ownedPath)));
+  if (outsideOwnedPaths.length > 0) {
+    warnings.push({
+      id: 'brownfield_scope_mismatch',
+      severity: 'acknowledgement_required',
+      summary: `Dirty files fall outside the CHANGE.md write scope: ${outsideOwnedPaths.join(', ')}`,
+    });
+  }
+
+  if ((brownfieldChange.currentStatus === 'closed' || brownfieldChange.currentStatus === 'ready_for_verification') && status.dirty) {
+    warnings.push({
+      id: 'brownfield_status_mismatch',
+      severity: 'acknowledgement_required',
+      summary: `CHANGE.md marks the change as "${brownfieldChange.currentStatus}", but the live worktree is still dirty.`,
+    });
+  }
+
+  return {
+    warnings,
+    requiresAcknowledgement: warnings.some((warning) => warning.severity === 'acknowledgement_required'),
+    outsideOwnedPaths,
+  };
+}
+
+export function buildProvenanceSnapshot({
+  checkpoint = {},
+  planning = {},
+  quick = {},
+  brownfieldChange = {},
+  git = {},
+} = {}) {
+  const checkpointRouting = classifyCheckpointRouting(checkpoint.workflow);
+  const status = parseGitStatusShort(git.statusShort || '');
+  const commitsAheadOfMain = normalizeCount(git.commitsAheadOfMain);
+  const commitsAheadOfRemote = normalizeCount(git.commitsAheadOfRemote);
+  const prState = normalizePrState(git.prState);
+  const brownfieldMismatch = classifyBrownfieldArtifactMismatch({ brownfieldChange, git, status });
+  const brownfieldRouting = classifyBrownfieldCheckpointPrecedence({
+    checkpoint,
+    planning,
+    quick,
+    brownfieldChange,
+    git,
+    status,
+  });
+
+  const warnings = [];
 
   if (status.dirty) {
     warnings.push({
@@ -121,31 +255,50 @@ export function buildProvenanceSnapshot({
     });
   }
 
-  if (git.materialCheckpointMismatch) {
-    warnings.push({
-      id: 'checkpoint_mismatch',
-      severity: 'acknowledgement_required',
-      summary: 'Checkpoint narrative truth materially understates or conflicts with the live branch/worktree truth.',
-    });
-  }
-
-  return {
-    checkpoint: {
-      workflow: checkpointRouting.workflow,
-      phase: checkpoint.phase ?? null,
-      runtime: checkpoint.runtime || 'unknown',
-      hasNarrative: Boolean(checkpoint.hasNarrative),
-      routing: checkpointRouting,
-    },
-    planning: {
-      currentPhase: planning.currentPhase || null,
-      nextPhase: planning.nextPhase || null,
-      completedPhaseCount: Number.isFinite(Number(planning.completedPhaseCount))
-        ? Number(planning.completedPhaseCount)
-        : 0,
-    },
-    git: {
-      branch: git.branch || 'unknown',
+  if (git.materialCheckpointMismatch) {
+    warnings.push({
+      id: 'checkpoint_mismatch',
+      severity: 'acknowledgement_required',
+      summary: 'Checkpoint narrative truth materially understates or conflicts with the live branch/worktree truth.',
+    });
+  }
+
+  warnings.push(...brownfieldMismatch.warnings);
+
+  return {
+    checkpoint: {
+      workflow: checkpointRouting.workflow,
+      phase: checkpoint.phase ?? null,
+      branch: checkpoint.branch || null,
+      runtime: checkpoint.runtime || 'unknown',
+      hasNarrative: Boolean(checkpoint.hasNarrative),
+      routing: checkpointRouting,
+    },
+    planning: {
+      currentPhase: planning.currentPhase || null,
+      nextPhase: planning.nextPhase || null,
+      completedPhaseCount: Number.isFinite(Number(planning.completedPhaseCount))
+        ? Number(planning.completedPhaseCount)
+        : 0,
+    },
+    brownfieldChange: {
+      exists: Boolean(brownfieldChange?.exists),
+      title: brownfieldChange?.title || null,
+      currentStatus: brownfieldChange?.currentStatus || null,
+      currentIntegrationSurface: brownfieldChange?.currentIntegrationSurface || null,
+      nextAction: brownfieldChange?.nextAction || null,
+      declaredOwnedPaths: brownfieldChange?.declaredOwnedPaths || [],
+    },
+    routing: {
+      primary: brownfieldRouting.primary,
+      strictMatchRequired: brownfieldRouting.strictMatchRequired,
+      checkpointCanOverrideBrownfield: brownfieldRouting.checkpointCanOverrideBrownfield,
+      branchAligned: brownfieldRouting.branchAligned,
+      scopeAligned: brownfieldRouting.scopeAligned,
+      executionActive: brownfieldRouting.executionActive,
+    },
+    git: {
+      branch: git.branch || 'unknown',
       prState,
       commitsAheadOfMain,
       commitsAheadOfRemote,
@@ -154,12 +307,81 @@ export function buildProvenanceSnapshot({
       untrackedCount: status.untrackedCount,
       dirty: status.dirty,
     },
-    integrationSurface: {
-      staleBranch: Boolean(git.staleBranch),
-      mixedScope: Boolean(git.mixedScope),
-      materialCheckpointMismatch: Boolean(git.materialCheckpointMismatch),
-    },
-    warnings,
-    requiresAcknowledgement: warnings.some((warning) => warning.severity === 'acknowledgement_required'),
-  };
-}
+    integrationSurface: {
+      staleBranch: Boolean(git.staleBranch),
+      mixedScope: Boolean(git.mixedScope),
+      materialCheckpointMismatch: Boolean(git.materialCheckpointMismatch),
+      materialBrownfieldMismatch: brownfieldMismatch.requiresAcknowledgement,
+    },
+    warnings,
+    requiresAcknowledgement: warnings.some((warning) => warning.severity === 'acknowledgement_required'),
+  };
+}
+
+function normalizeBranchName(value) {
+  return String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/\\/g, '/');
+}
+
+function normalizeDeclaredBranch(value) {
+  return normalizeBranchName(value);
+}
+
+function normalizeOwnedPaths(values) {
+  return values
+    .map((value) => String(value || '').trim().replace(/\\/g, '/'))
+    .filter(Boolean);
+}
+
+function matchesOwnedPath(filePath, ownedPath) {
+  if (ownedPath.includes('*')) {
+    const prefix = ownedPath.split('*')[0];
+    return filePath.startsWith(prefix);
+  }
+  return filePath === ownedPath
+    || filePath.startsWith(`${ownedPath}/`)
+    || ownedPath.startsWith(`${filePath}/`);
+}
+
+function checkpointExecutionIsActive({
+  checkpoint = {},
+  checkpointRouting = classifyCheckpointRouting(checkpoint.workflow),
+  planning = {},
+  quick = {},
+} = {}) {
+  if (checkpointRouting.workflow === 'quick') {
+    return quick.hasIncompleteWork === true;
+  }
+
+  if (checkpointRouting.workflow !== 'phase') {
+    return false;
+  }
+
+  const checkpointPhase = normalizePhaseRef(checkpoint.phase);
+  if (!checkpointPhase) return false;
+
+  const phases = Array.isArray(planning.phases) ? planning.phases : [];
+  if (phases.length > 0) {
+    const matchingPhase = phases.find((phase) => normalizePhaseRef(phase.number) === checkpointPhase);
+    return Boolean(matchingPhase && matchingPhase.status !== 'done');
+  }
+
+  const currentPhase = normalizePhaseRef(planning.currentPhase);
+  const nextPhase = normalizePhaseRef(planning.nextPhase);
+  return checkpointPhase === currentPhase || checkpointPhase === nextPhase;
+}
+
+function normalizePhaseRef(value) {
+  const raw = String(value || '').trim().toLowerCase();
+  if (!raw) return '';
+
+  const match = raw.match(/^(\d+(?:\.\d+)*)([a-z]?)$/i);
+  if (!match) return raw;
+
+  const numericSegments = match[1]
+    .split('.')
+    .map((segment) => String(parseInt(segment, 10)));
+  return `${numericSegments.join('.')}${match[2] || ''}`;
+}

package/bin/lib/rendering.mjs

@@ -18,23 +18,72 @@ function getDelegateContent(delegateFile) {
   return `<!-- Delegate file not found: ${delegateFile} -->\n`;
 }
 
-function renderSkillContent(workflow) {
-  const workflowContent = getWorkflowContent(workflow.workflow);
-  return `---
-name: ${workflow.name}
-description: ${workflow.description}
+function renderSkillContent(workflow) {
+  const workflowContent = getWorkflowContent(workflow.workflow);
+  return `---
+name: ${workflow.name}
+description: ${workflow.description}
 context: fork
 agent: ${workflow.agent}
 ---
 
-${workflowContent}`;
-}
-
-function buildPortableSkillEntries(workflows) {
-  return workflows.map((workflow) => ({
-    relativePath: `.agents/skills/${workflow.name}/SKILL.md`,
-    content: renderSkillContent(workflow),
-  }));
+${workflowContent}`;
+}
+
+function renderPlanningCliLauncher({ packageName = 'gsdd-cli', packageVersion }) {
+  if (!packageVersion) {
+    throw new Error('renderPlanningCliLauncher requires packageVersion');
+  }
+
+  const packageSpec = `${packageName}@${packageVersion}`;
+
+  return `#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+
+const packageSpec = ${JSON.stringify(packageSpec)};
+const args = process.argv.slice(2);
+const env = { ...process.env };
+
+function forwardResult(result, fallbackMessage) {
+  if (result.error) {
+    console.error(fallbackMessage ?? result.error.message);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (typeof result.status === 'number') {
+    process.exitCode = result.status;
+    return;
+  }
+
+  if (result.signal) {
+    process.exitCode = 1;
+  }
+}
+
+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 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.\`);
+}
+`;
+}
+
+function buildPortableSkillEntries(workflows) {
+  return workflows.map((workflow) => ({
+    relativePath: `.agents/skills/${workflow.name}/SKILL.md`,
+    content: renderSkillContent(workflow),
+  }));
 }
 
 function renderOpenCodeCommandContent(workflow) {
@@ -95,9 +144,10 @@ export {
   buildPortableSkillEntries,
   getDelegateContent,
   getWorkflowContent,
-  renderAgentsBoundedBlock,
-  renderAgentsFileContent,
-  renderOpenCodeCommandContent,
-  renderSkillContent,
-  upsertBoundedBlock,
-};
+  renderAgentsBoundedBlock,
+  renderAgentsFileContent,
+  renderOpenCodeCommandContent,
+  renderPlanningCliLauncher,
+  renderSkillContent,
+  upsertBoundedBlock,
+};

package/bin/lib/runtime-freshness.mjs

@@ -1,11 +1,13 @@
-import { existsSync, readFileSync } from 'fs';
-import { join } from 'path';
-import {
-  buildPortableSkillEntries,
-  getDelegateContent,
-  renderOpenCodeCommandContent,
-  renderSkillContent,
-} from './rendering.mjs';
+import { existsSync, readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import {
+  buildPortableSkillEntries,
+  getDelegateContent,
+  renderPlanningCliLauncher,
+  renderOpenCodeCommandContent,
+  renderSkillContent,
+} from './rendering.mjs';
 import {
   CLAUDE_MODEL_PROFILES,
   renderClaudeApproachExplorer,
@@ -22,11 +24,15 @@ import {
   renderCodexApproachExplorer,
   renderCodexPlanChecker,
 } from '../adapters/codex.mjs';
-import {
-  getRuntimeModelOverride,
-  loadProjectModelConfig,
-  resolveRuntimeAgentModel,
-} from './models.mjs';
+import {
+  getRuntimeModelOverride,
+  loadProjectModelConfig,
+  resolveRuntimeAgentModel,
+} from './models.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PACKAGE_JSON = JSON.parse(readFileSync(join(__dirname, '..', '..', 'package.json'), 'utf-8'));
 
 function normalizeContent(content) {
   return String(content).replace(/\r\n/g, '\n');
@@ -127,7 +133,7 @@ function buildOpenCodeEntries({ cwd, workflows }) {
   return entries;
 }
 
-function buildCodexEntries({ cwd }) {
+function buildCodexEntries({ cwd }) {
   const config = loadProjectModelConfig(cwd);
   const checkerModelId = getRuntimeModelOverride(config, 'codex', 'plan-checker');
   const explorerModelId = getRuntimeModelOverride(config, 'codex', 'approach-explorer');
@@ -142,13 +148,32 @@ function buildCodexEntries({ cwd }) {
       expectedContent: renderCodexApproachExplorer(getDelegateContent('approach-explorer.md'), explorerModelId),
     },
   ];
-}
-
-export function collectExpectedRuntimeSurfaceGroups({ cwd = process.cwd(), workflows }) {
-  return [
-    {
-      runtime: 'portable',
-      label: 'portable skills',
+}
+
+function buildWorkspaceHelperEntries() {
+  return [
+    {
+      relativePath: '.planning/bin/gsdd.mjs',
+      expectedContent: renderPlanningCliLauncher({
+        packageName: PACKAGE_JSON.name,
+        packageVersion: PACKAGE_JSON.version,
+      }),
+    },
+  ];
+}
+
+export function collectExpectedRuntimeSurfaceGroups({ cwd = process.cwd(), workflows }) {
+  return [
+    {
+      runtime: 'workspace-helper',
+      label: 'workspace workflow helper',
+      root: '.planning/bin',
+      repairCommand: 'gsdd update',
+      entries: buildWorkspaceHelperEntries(),
+    },
+    {
+      runtime: 'portable',
+      label: 'portable skills',
       root: '.agents/skills',
       repairCommand: 'gsdd update',
       entries: buildPortableSkillEntries(workflows).map((entry) => ({