gsdd-cli 0.26.0 → 0.28.0

package/bin/lib/phase.mjs

@@ -4,16 +4,9 @@
 // evaluate once, so CWD must be computed inside function bodies.
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'fs';
-import { dirname, join, relative } from 'path';
+import { basename, dirname, join, relative } from 'path';
 import { output } from './cli-utils.mjs';
-import { writeFingerprint } from './session-fingerprint.mjs';
 import { resolveWorkspaceContext } from './workspace-root.mjs';
-import {
-  compareUiProofSlots,
-  findUiProofBundleFiles,
-  parseUiProofSlotsContent,
-  readUiProofBundleFile,
-} from './ui-proof.mjs';
 
 const PHASE_STATUS_MARKERS = {
   not_started: '[ ]',
@@ -202,290 +195,6 @@ function evaluatePlanArtifacts(artifacts) {
   };
 }
 
-function normalizeUiProofIssue(issue) {
-  return {
-    ...issue,
-    severity: issue.severity || 'blocker',
-    fix_hint: issue.fix_hint || issue.fix || 'Fix the UI proof issue before claiming verification is complete.',
-  };
-}
-
-function stripInlineComment(value) {
-  return String(value || '').replace(/\s+#.*$/, '').trim();
-}
-
-function stripOuterScalarQuotes(value) {
-  return String(value)
-    .trim()
-    .replace(/^(['"])([\s\S]*)\1$/g, '$2')
-    .trim();
-}
-
-function normalizeNullableFrontmatterValue(value) {
-  const stripped = stripOuterScalarQuotes(value);
-  if (!stripped) return '';
-  if (stripped === '~') return '';
-  if (/^null$/i.test(stripped)) return '';
-  return stripped;
-}
-
-function extractUiProofSlotIds(value) {
-  const ids = [];
-  const slotPattern = /['"]?slot_id['"]?\s*:\s*['"]?([^,'"\]\s}]+)['"]?/g;
-  for (const match of String(value || '').matchAll(slotPattern)) {
-    ids.push(match[1].replace(/^['"]|['"]$/g, ''));
-  }
-  return ids;
-}
-
-function readPlanFrontmatter(planContent) {
-  const content = String(planContent || '');
-  if (!content.startsWith('---')) return '';
-  const lines = content.split(/\r?\n/);
-  const frontmatter = [];
-  for (let index = 1; index < lines.length; index += 1) {
-    if (lines[index].trim() === '---') return frontmatter.join('\n');
-    frontmatter.push(lines[index]);
-  }
-  return '';
-}
-
-function frontmatterKeyBlock(frontmatter, key) {
-  const lines = String(frontmatter || '').split(/\r?\n/);
-  const keyPattern = new RegExp(`^${key}:[ \\t]*(.*)$`);
-  for (let index = 0; index < lines.length; index += 1) {
-    const match = lines[index].match(keyPattern);
-    if (!match) continue;
-    const block = [];
-    for (let next = index + 1; next < lines.length; next += 1) {
-      const line = lines[next];
-      if (/^\S[^:\n]*:\s*/.test(line)) break;
-      block.push(line);
-    }
-    return { inline: stripInlineComment(match[1]), block };
-  }
-  return null;
-}
-
-function frontmatterScalar(frontmatter, key) {
-  const entry = frontmatterKeyBlock(frontmatter, key);
-  if (!entry) return null;
-  if (entry.inline && !['|', '>'].includes(entry.inline)) return entry.inline;
-  return entry.block
-    .map((line) => line.trim())
-    .filter(Boolean)
-    .join(' ')
-    .trim();
-}
-
-function readPlanUiProofContract(planContent) {
-  const frontmatter = readPlanFrontmatter(planContent);
-  const slotsEntry = frontmatterKeyBlock(frontmatter, 'ui_proof_slots');
-  const rationale = normalizeNullableFrontmatterValue(frontmatterScalar(frontmatter, 'no_ui_proof_rationale') || '');
-  const result = {
-    hasUiProofKey: Boolean(slotsEntry),
-    declaresSlots: false,
-    explicitEmptySlots: false,
-    noUiProofRationale: rationale,
-    hasNoUiProofRationale: Boolean(rationale.trim()),
-    slotIds: [],
-  };
-
-  if (!slotsEntry) return result;
-
-  if (slotsEntry.inline) {
-    if (['[]', 'null', '~'].includes(slotsEntry.inline)) {
-      result.explicitEmptySlots = true;
-      return result;
-    }
-    result.declaresSlots = true;
-    result.slotIds.push(...extractUiProofSlotIds(slotsEntry.inline));
-    return result;
-  }
-
-  let sawMeaningfulLine = false;
-  for (const line of slotsEntry.block) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith('#')) continue;
-    sawMeaningfulLine = true;
-    if (/^\s+-\s+/.test(line)) result.declaresSlots = true;
-    result.slotIds.push(...extractUiProofSlotIds(trimmed));
-  }
-
-  result.explicitEmptySlots = !result.declaresSlots && !sawMeaningfulLine;
-  return result;
-}
-
-function findUiProofSlotPlansAndFiles(planningDir, planDisplayPaths) {
-  const candidates = new Set();
-  const declaredPlans = [];
-  const declaredSlotIds = [];
-  const noUiPlans = [];
-  const contractErrors = [];
-  const names = new Set([
-    'ui-proof-slots.json',
-    'ui-proof-slots.md',
-    'UI-PROOF-SLOTS.json',
-    'UI-PROOF-SLOTS.md',
-    'planned-ui-proof.json',
-    'planned-ui-proof.md',
-  ]);
-
-  for (const planDisplayPath of planDisplayPaths) {
-    const fullPlanPath = join(planningDir, 'phases', planDisplayPath);
-    if (!existsSync(fullPlanPath)) continue;
-    const planContent = readFileSync(fullPlanPath, 'utf-8');
-    const relPlanPath = relative(planningDir, fullPlanPath).replace(/\\/g, '/');
-    const contract = readPlanUiProofContract(planContent);
-    const planDir = dirname(fullPlanPath);
-    const sidecars = [];
-    if (existsSync(planDir)) {
-      for (const entry of readdirSync(planDir, { withFileTypes: true })) {
-        if (entry.isFile() && names.has(entry.name)) {
-          sidecars.push(join(planDir, entry.name));
-        }
-      }
-    }
-
-    if (contract.hasUiProofKey && !contract.declaresSlots && !contract.hasNoUiProofRationale) {
-      contractErrors.push(normalizeUiProofIssue({
-        code: 'missing_no_ui_proof_rationale',
-        path: `${relPlanPath}.no_ui_proof_rationale`,
-        message: 'Plan declares empty ui_proof_slots but does not provide a no_ui_proof_rationale.',
-        fix: 'Add a nonblank no_ui_proof_rationale for non-UI work, or declare required UI proof slots and add a planned slots artifact.',
-      }));
-    }
-
-    if (contract.hasNoUiProofRationale && !contract.declaresSlots) {
-      noUiPlans.push({ plan: relPlanPath, sidecars });
-      continue;
-    }
-
-    if (!contract.declaresSlots) continue;
-
-    declaredPlans.push(relPlanPath);
-    for (const slotId of contract.slotIds) {
-      declaredSlotIds.push({ plan: relPlanPath, slot_id: slotId });
-    }
-    for (const entry of readdirSync(planDir, { withFileTypes: true })) {
-      if (entry.isFile() && names.has(entry.name)) {
-        candidates.add(join(planDir, entry.name));
-      }
-    }
-  }
-  return { declaredPlans, declaredSlotIds, noUiPlans, contractErrors, files: [...candidates].sort() };
-}
-
-function comparePhaseUiProof({ planningDir, workspaceRoot, planDisplayPaths }) {
-  const plannedDiscovery = findUiProofSlotPlansAndFiles(planningDir, planDisplayPaths);
-  const plannedFiles = plannedDiscovery.files;
-  const phaseDirs = new Set(planDisplayPaths.map((planDisplayPath) => dirname(join(planningDir, 'phases', planDisplayPath))));
-  const observedFiles = findUiProofBundleFiles(planningDir)
-    .filter((filePath) => phaseDirs.has(dirname(filePath)));
-
-  const plannedSlots = [];
-  const errors = [];
-  const warnings = [];
-  const planned = [];
-  const observed = [];
-
-  errors.push(...plannedDiscovery.contractErrors);
-  for (const noUiPlan of plannedDiscovery.noUiPlans) {
-    for (const filePath of noUiPlan.sidecars) {
-      warnings.push({
-        code: 'stale_ui_proof_sidecar_ignored',
-        severity: 'warn',
-        path: relative(workspaceRoot, filePath).replace(/\\/g, '/'),
-        message: `Plan ${noUiPlan.plan} records no_ui_proof_rationale, so the UI proof sidecar is ignored for closure.`,
-        fix_hint: 'Remove or classify the stale sidecar if it no longer belongs to this non-UI phase.',
-      });
-    }
-  }
-
-  for (const filePath of plannedFiles) {
-    const rel = relative(workspaceRoot, filePath).replace(/\\/g, '/');
-    const parsed = parseUiProofSlotsContent(readFileSync(filePath, 'utf-8'), rel);
-    planned.push(rel);
-    plannedSlots.push(...parsed.slots);
-    errors.push(...parsed.errors.map(normalizeUiProofIssue));
-  }
-
-  if (plannedSlots.length > 0 && plannedDiscovery.declaredSlotIds.length > 0) {
-    const plannedSlotIds = new Set(plannedSlots.map((slot) => String(slot?.slot_id || '')));
-    for (const declaredSlot of plannedDiscovery.declaredSlotIds) {
-      if (plannedSlotIds.has(String(declaredSlot.slot_id))) continue;
-      errors.push(normalizeUiProofIssue({
-        code: 'planned_ui_proof_slots_drift',
-        path: `${declaredSlot.plan}.ui_proof_slots`,
-        message: `Plan declares UI proof slot ${declaredSlot.slot_id}, but no matching slot exists in the planned UI proof artifact.`,
-        fix: 'Update ui-proof-slots.json or ui-proof-slots.md beside the plan so it matches the plan-declared slot IDs, or update the plan declaration.',
-      }));
-    }
-  }
-
-  const observedBundles = [];
-  for (const filePath of observedFiles) {
-    const rel = relative(workspaceRoot, filePath).replace(/\\/g, '/');
-    const parsed = readUiProofBundleFile(filePath);
-    observed.push(rel);
-    if (parsed.errors.length > 0) {
-      errors.push(...parsed.errors.map((error) => normalizeUiProofIssue({ ...error, path: error.path || rel })));
-      continue;
-    }
-    observedBundles.push({
-      source: rel,
-      bundle: parsed.bundle,
-      options: {
-        requireLocalArtifactExists: true,
-        workspaceRoot,
-        bundleDir: dirname(filePath),
-      },
-    });
-  }
-
-  if (plannedFiles.length === 0 && plannedDiscovery.declaredPlans.length > 0) {
-    const missingError = {
-      code: 'missing_planned_ui_proof_slots_file',
-      severity: 'blocker',
-      path: plannedDiscovery.declaredPlans[0],
-      message: 'Plan declares ui_proof_slots but no ui-proof-slots artifact was found beside the plan.',
-      fix_hint: 'Create ui-proof-slots.json or ui-proof-slots.md beside the plan, or set ui_proof_slots: [] with a no_ui_proof_rationale if the phase is not UI-sensitive.',
-    };
-    return {
-      planned,
-      observed,
-      status: 'missing',
-      comparison: { status: 'missing', slots: [], errors: [missingError] },
-      errors: [missingError],
-      warnings,
-    };
-  }
-
-  if (plannedFiles.length === 0) {
-    return {
-      planned,
-      observed,
-      status: errors.length > 0 ? 'partial' : 'not_applicable',
-      comparison: null,
-      errors,
-      warnings,
-    };
-  }
-
-  const comparison = errors.length > 0
-    ? { status: 'partial', slots: [], errors: errors.map(normalizeUiProofIssue) }
-    : compareUiProofSlots(plannedSlots, observedBundles);
-
-  return {
-    planned,
-    observed,
-    status: comparison.status,
-    comparison,
-    errors: comparison.errors || errors,
-    warnings,
-  };
-}
-
 export function updateRoadmapPhaseStatus(roadmap, phaseNumber, status) {
   const marker = PHASE_STATUS_MARKERS[status];
   if (!marker) {
@@ -568,6 +277,7 @@ export function cmdPhaseStatus(...args) {
     return;
   }
   const roadmapPath = join(planningDir, 'ROADMAP.md');
+  const stateName = basename(planningDir);
   const [phaseNumber, status] = normalizedArgs;
 
   if (!phaseNumber || !status) {
@@ -588,9 +298,8 @@ export function cmdPhaseStatus(...args) {
     const changed = updated !== roadmap;
     if (changed) {
       writeFileSync(roadmapPath, updated);
-      try { writeFingerprint(planningDir); } catch { /* best-effort */ }
     }
-    output({ phase: phaseNumber, status, roadmap: '.planning/ROADMAP.md', changed });
+    output({ phase: phaseNumber, status, roadmap: `${stateName}/ROADMAP.md`, changed });
   } catch (error) {
     console.error(error.message);
     process.exitCode = 1;
@@ -605,9 +314,10 @@ export function cmdFindPhase(...args) {
     return;
   }
   const phaseNum = normalizedArgs[0];
+  const stateName = basename(planningDir);
 
   if (!existsSync(planningDir)) {
-    output({ error: 'No .planning/ directory found. Run `npx -y gsdd-cli init` then the new-project workflow first.' });
+    output({ error: `No ${stateName}/ directory found. Run \`npx -y gsdd-cli init\` then the new-project workflow first.` });
     return;
   }
 
@@ -660,9 +370,10 @@ export function buildPhaseVerificationReport(...args) {
   if (!phaseNum) {
     return { ok: false, error: 'Usage: gsdd verify <phase-number>', exitCode: 1 };
   }
+  const stateName = basename(planningDir);
 
   if (!existsSync(planningDir)) {
-    return { ok: false, error: 'No .planning/ directory found.', exitCode: 1 };
+    return { ok: false, error: `No ${stateName}/ directory found.`, exitCode: 1 };
   }
   const phasesDir = join(planningDir, 'phases');
   const matchingPlans = findFiles(phasesDir, `${padPhase(phaseNum)}-PLAN`);
@@ -672,7 +383,7 @@ export function buildPhaseVerificationReport(...args) {
     prerequisiteBlockers.push({
       code: 'missing_phase_plan',
       severity: 'blocker',
-      path: `.planning/phases/${padPhase(phaseNum)}-*/${padPhase(phaseNum)}-PLAN.md`,
+      path: `${stateName}/phases/${padPhase(phaseNum)}-*/${padPhase(phaseNum)}-PLAN.md`,
       message: `No PLAN.md artifact was found for phase ${normalizePhaseToken(phaseNum)}.`,
       fix_hint: `Run /gsdd-plan ${normalizePhaseToken(phaseNum)} before verifying this phase.`,
     });
@@ -681,7 +392,7 @@ export function buildPhaseVerificationReport(...args) {
     prerequisiteBlockers.push({
       code: 'missing_phase_summary',
       severity: 'blocker',
-      path: `.planning/phases/${padPhase(phaseNum)}-*/${padPhase(phaseNum)}-SUMMARY.md`,
+      path: `${stateName}/phases/${padPhase(phaseNum)}-*/${padPhase(phaseNum)}-SUMMARY.md`,
       message: `No SUMMARY.md artifact was found for phase ${normalizePhaseToken(phaseNum)}.`,
       fix_hint: `Run /gsdd-execute ${normalizePhaseToken(phaseNum)} before verifying this phase.`,
     });
@@ -693,26 +404,12 @@ export function buildPhaseVerificationReport(...args) {
       : [];
   });
   const artifactStatus = evaluatePlanArtifacts(artifacts);
-  const uiProof = comparePhaseUiProof({
-    planningDir,
-    workspaceRoot,
-    planDisplayPaths: matchingPlans,
-  });
-  const uiProofSatisfied = ['satisfied', 'not_applicable'].includes(uiProof.status);
   const legacyVerified = matchingPlans.length > 0 && matchingSummaries.length > 0;
-  const uiProofGate = {
-    status: uiProof.status,
-    required: uiProof.status !== 'not_applicable',
-    satisfied: uiProofSatisfied,
-    blocks_verification: uiProof.status !== 'not_applicable' && !uiProofSatisfied,
-    required_block: uiProof.status !== 'not_applicable' && !uiProofSatisfied ? 'ui-proof-failed' : null,
-  };
   const blockedOn = [
     ...(prerequisiteBlockers.length > 0 ? ['prerequisites'] : []),
     ...(artifactStatus.satisfied ? [] : ['artifacts']),
-    ...(uiProofGate.blocks_verification ? ['ui_proof'] : []),
   ];
-  const closureVerified = legacyVerified && prerequisiteBlockers.length === 0 && artifactStatus.satisfied && uiProofSatisfied;
+  const closureVerified = legacyVerified && prerequisiteBlockers.length === 0 && artifactStatus.satisfied;
 
   const result = {
     phase: normalizePhaseToken(phaseNum),
@@ -722,7 +419,6 @@ export function buildPhaseVerificationReport(...args) {
     artifacts,
     allExist: artifacts.every((artifact) => artifact.exists),
     artifact_status: artifactStatus,
-    uiProof,
     verified: closureVerified,
     legacy_verified: legacyVerified,
     phase_artifacts_present: legacyVerified,
@@ -730,7 +426,6 @@ export function buildPhaseVerificationReport(...args) {
       satisfied: prerequisiteBlockers.length === 0,
       blockers: prerequisiteBlockers,
     },
-    ui_proof: uiProofGate,
     blocked_on: blockedOn,
     blocks_verification: blockedOn.length > 0,
   };

package/bin/lib/rendering.mjs

@@ -7,17 +7,27 @@ const __dirname = dirname(__filename);
 const DISTILLED_DIR = join(__dirname, '..', '..', 'distilled');
 const HELPER_LIB_FILES = Object.freeze([
   'cli-utils.mjs',
-  'closeout-report.mjs',
   'control-map.mjs',
-  'evidence-contract.mjs',
   'file-ops.mjs',
   'lifecycle-preflight.mjs',
   'lifecycle-state.mjs',
+  'next.mjs',
   'phase.mjs',
-  'session-fingerprint.mjs',
-  'ui-proof.mjs',
+  'state-dir.mjs',
+  'work-context.mjs',
   'workspace-root.mjs',
 ]);
+const DEFAULT_STATE_DIR_NAME = '.work';
+
+function normalizeStateDirName(stateDirName = DEFAULT_STATE_DIR_NAME) {
+  return stateDirName || DEFAULT_STATE_DIR_NAME;
+}
+
+function localizeStateDirReferences(content, { stateDirName = DEFAULT_STATE_DIR_NAME } = {}) {
+  const normalized = normalizeStateDirName(stateDirName);
+  if (normalized === DEFAULT_STATE_DIR_NAME) return content;
+  return String(content).replace(/\.work(?=\/|\\|`|'|"|\)|\]|\}|,|\.|:|;|\s|$)/g, normalized);
+}
 
 function getWorkflowContent(workflowFile) {
   const filePath = join(DISTILLED_DIR, 'workflows', workflowFile);
@@ -31,8 +41,8 @@ function getDelegateContent(delegateFile) {
   return `<!-- Delegate file not found: ${delegateFile} -->\n`;
 }
 
-function renderSkillContent(workflow) {
-  const workflowContent = getWorkflowContent(workflow.workflow);
+function renderSkillContent(workflow, options = {}) {
+  const workflowContent = localizeStateDirReferences(getWorkflowContent(workflow.workflow), options);
   return `---
 name: ${workflow.name}
 description: ${workflow.description}
@@ -43,60 +53,63 @@ agent: ${workflow.agent}
 ${workflowContent}`;
 }
 
-function renderPlanningCliLauncher() {
+function renderPlanningCliLauncher({ stateDirName = DEFAULT_STATE_DIR_NAME } = {}) {
+  const helperPath = `${normalizeStateDirName(stateDirName)}/bin/gsdd.mjs`;
+  const checkpointBackupPath = `${normalizeStateDirName(stateDirName)}/.continue-here.bak`;
   return `#!/usr/bin/env node
 
 import { cmdFileOp } from './lib/file-ops.mjs';
 import { cmdLifecyclePreflight } from './lib/lifecycle-preflight.mjs';
 import { cmdPhaseStatus, cmdVerify } from './lib/phase.mjs';
-import { cmdSessionFingerprint } from './lib/session-fingerprint.mjs';
-import { cmdUiProof } from './lib/ui-proof.mjs';
-import { cmdControlMap } from './lib/control-map.mjs';
-import { createCmdCloseoutReport } from './lib/closeout-report.mjs';
+import { buildControlMap } from './lib/control-map.mjs';
+import { createCmdNext } from './lib/next.mjs';
 import { bootstrapHelperWorkspace, consumeWorkspaceRootArg, resolveWorkspaceContext } from './lib/workspace-root.mjs';
 
 const HELPER_CONTEXT = {
+  cwd: process.cwd(),
   workflows: [],
   frameworkVersion: 'generated-helper',
 };
-const cmdCloseoutReport = createCmdCloseoutReport(HELPER_CONTEXT);
+const cmdNext = createCmdNext(HELPER_CONTEXT);
+
+function cmdControlMap(...controlArgs) {
+  const context = resolveWorkspaceContext([], { cwd: HELPER_CONTEXT.cwd });
+  const report = buildControlMap({
+    workspaceRoot: context.workspaceRoot,
+    planningDir: context.planningDir,
+    includeIgnoredPaths: controlArgs.includes('--with-ignored'),
+  });
+  console.log(JSON.stringify(report, null, 2));
+}
 
 const COMMANDS = {
+  'control-map': cmdControlMap,
   'file-op': cmdFileOp,
   'lifecycle-preflight': cmdLifecyclePreflight,
   'phase-status': cmdPhaseStatus,
   verify: cmdVerify,
-  'session-fingerprint': cmdSessionFingerprint,
-  'ui-proof': cmdUiProof,
-  'control-map': cmdControlMap,
-  'closeout-report': cmdCloseoutReport,
+  next: cmdNext,
 };
 
 function printHelp() {
   console.log([
-    'Usage: node .planning/bin/gsdd.mjs [--workspace-root <path>] <command> [args]',
+    'Usage: node ${helperPath} [--workspace-root <path>] <command> [args]',
     '',
     'Local workflow helper commands:',
+    '  control-map [--json] [--with-ignored]',
+    '                               Print computed repo/worktree/workflow state for workflow-internal checks',
     '  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',
+    '                               Example: node ${helperPath} file-op delete ${checkpointBackupPath} --missing ok',
     '  phase-status <N> <status>   Update ROADMAP.md phase status ([ ] / [-] / [x])',
-    '                               Example: node .planning/bin/gsdd.mjs phase-status 1 done',
-    '  verify <N>                  Run direct phase artifact and UI-proof gate checks',
-    '                               Example: node .planning/bin/gsdd.mjs verify 1',
+    '                               Example: node ${helperPath} phase-status 1 done',
+    '  verify <N>                  Run direct phase artifact checks',
+    '                               Example: node ${helperPath} verify 1',
     '  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',
-    '  session-fingerprint write [--allow-changed <ROADMAP.md,SPEC.md,config.json>]',
-    '                               Rebaseline planning-state drift after reviewing changed planning files',
-    '  ui-proof validate <path> [--claim <public|publication|tracked|delivery|release>]',
-    '                               Validate UI proof metadata; use --claim for stronger proof uses',
-    '  ui-proof compare <planned-slots-json> [observed-bundle-json ...]',
-    '                               Compare planned UI proof slots against observed bundles',
-    '  control-map [--json] [--with-ignored] [--annotations <path>]',
-    '                               Report computed repo/worktree/planning state and local annotations',
-    '  closeout-report [--json] [--phase <N>]',
-    '                               Replay read-only closeout status from control-map, health, preflight, verify, and UI-proof signals',
+    '                               Example: node ${helperPath} lifecycle-preflight verify 1 --expects-mutation phase-status',
+    '  next [--json] [--init]',
+    '                               Route to the next safe Workspine action from ${normalizeStateDirName(stateDirName)}, brownfield, planning, and repo truth',
     '',
     'Advanced option:',
     '  --workspace-root <path>     Override workspace root discovery before or after the subcommand',
@@ -106,6 +119,7 @@ function printHelp() {
 function applyWorkspaceRootOverride(workspaceRootArg) {
   if (!workspaceRootArg) {
     bootstrapHelperWorkspace(import.meta.url);
+    HELPER_CONTEXT.cwd = process.cwd();
     return true;
   }
 
@@ -117,6 +131,7 @@ function applyWorkspaceRootOverride(workspaceRootArg) {
   }
 
   process.env.GSDD_WORKSPACE_ROOT = context.workspaceRoot;
+  HELPER_CONTEXT.cwd = context.workspaceRoot;
   try {
     process.chdir(context.workspaceRoot);
   } catch {
@@ -183,11 +198,11 @@ function readHelperLibContent(fileName) {
   return readFileSync(join(__dirname, fileName), 'utf-8');
 }
 
-function buildPlanningCliHelperEntries() {
+function buildPlanningCliHelperEntries(options = {}) {
   return [
     {
       relativePath: 'bin/gsdd.mjs',
-      content: renderPlanningCliLauncher(),
+      content: renderPlanningCliLauncher(options),
     },
     {
       relativePath: 'bin/gsdd',
@@ -208,15 +223,15 @@ function buildPlanningCliHelperEntries() {
   ];
 }
 
-function buildPortableSkillEntries(workflows) {
+function buildPortableSkillEntries(workflows, options = {}) {
   return workflows.map((workflow) => ({
     relativePath: `.agents/skills/${workflow.name}/SKILL.md`,
-    content: renderSkillContent(workflow),
+    content: renderSkillContent(workflow, options),
   }));
 }
 
-function renderOpenCodeCommandContent(workflow) {
-  const workflowContent = getWorkflowContent(workflow.workflow);
+function renderOpenCodeCommandContent(workflow, options = {}) {
+  const workflowContent = localizeStateDirReferences(getWorkflowContent(workflow.workflow), options);
   return `---
 description: ${workflow.description}
 ---
@@ -224,19 +239,23 @@ description: ${workflow.description}
 ${workflowContent}`;
 }
 
-function renderAgentsBoundedBlock() {
+function renderAgentsBoundedBlock(options = {}) {
   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';
+  if (existsSync(blockPath)) return localizeStateDirReferences(readFileSync(blockPath, 'utf-8'), options).trim();
+  const stateDirName = normalizeStateDirName(options.stateDirName);
+  const planningLine = stateDirName === DEFAULT_STATE_DIR_NAME
+    ? 'Planning state: `.work/` (legacy `.planning/` workspaces are still read).'
+    : 'Planning state: `.planning/` (legacy workspace; new Workspine projects use `.work/`).';
+  return `## GSDD Governance (Generated)\n\n- Framework: GSDD\n- ${planningLine}\n- Workflows: .agents/skills/gsdd-*/SKILL.md`;
 }
 
-function renderAgentsFileContent() {
+function renderAgentsFileContent(options = {}) {
   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';
+    return template.replace('{{GSDD_BLOCK}}', renderAgentsBoundedBlock(options)).trimEnd() + '\n';
   }
-  const block = renderAgentsBoundedBlock();
+  const block = renderAgentsBoundedBlock(options);
   return `# AGENTS.md - GSDD Governance\n\n<!-- BEGIN GSDD -->\n${block}\n<!-- END GSDD -->\n`;
 }
 
@@ -274,6 +293,7 @@ export {
   buildPortableSkillEntries,
   getDelegateContent,
   getWorkflowContent,
+  localizeStateDirReferences,
   renderAgentsBoundedBlock,
   renderAgentsFileContent,
   renderOpenCodeCommandContent,