gsdd-cli 0.27.0 → 0.29.0

package/bin/lib/plan-constants.mjs

@@ -7,11 +7,6 @@ export const PLAN_CHECK_DIMENSIONS = [
   'must_have_quality',
   'context_compliance',
   'goal_achievement',
-  'scope_boundaries',
-  'anti_regression_capture',
-  'escalation_integrity',
-  'closure_honesty',
-  'high_leverage_review',
   'approach_alignment',
 ];
 

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,

package/bin/lib/runtime-freshness.mjs

@@ -28,7 +28,8 @@ import {
   getRuntimeModelOverride,
   loadProjectModelConfig,
   resolveRuntimeAgentModel,
-} from './models.mjs';
+} from './config.mjs';
+import { resolveStateDir } from './state-dir.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -68,7 +69,7 @@ function compareGeneratedFile({ cwd, runtime, relativePath, expectedContent, rep
   };
 }
 
-function buildClaudeEntries({ cwd, workflows }) {
+function buildClaudeEntries({ cwd, workflows, stateDirName = '.work' }) {
   const checkerModelAlias = resolveRuntimeAgentModel({
     cwd,
     runtime: 'claude',
@@ -85,8 +86,8 @@ function buildClaudeEntries({ cwd, workflows }) {
   const entries = workflows.map((workflow) => ({
     relativePath: `.claude/skills/${workflow.name}/SKILL.md`,
     expectedContent: workflow.name === 'gsdd-plan'
-      ? renderClaudePlanSkill()
-      : renderSkillContent(workflow),
+      ? renderClaudePlanSkill({ stateDirName })
+      : renderSkillContent(workflow, { stateDirName }),
   }));
 
   entries.push(
@@ -107,7 +108,7 @@ function buildClaudeEntries({ cwd, workflows }) {
   return entries;
 }
 
-function buildOpenCodeEntries({ cwd, workflows }) {
+function buildOpenCodeEntries({ cwd, workflows, stateDirName = '.work' }) {
   const config = loadProjectModelConfig(cwd);
   const checkerModelId = getRuntimeModelOverride(config, 'opencode', 'plan-checker');
   const explorerModelId = getRuntimeModelOverride(config, 'opencode', 'approach-explorer');
@@ -115,8 +116,8 @@ function buildOpenCodeEntries({ cwd, workflows }) {
   const entries = workflows.map((workflow) => ({
     relativePath: `.opencode/commands/${workflow.name}.md`,
     expectedContent: workflow.name === 'gsdd-plan'
-      ? renderOpenCodePlanCommand()
-      : renderOpenCodeCommandContent(workflow),
+      ? renderOpenCodePlanCommand({ stateDirName })
+      : renderOpenCodeCommandContent(workflow, { stateDirName }),
   }));
 
   entries.push(
@@ -150,31 +151,33 @@ function buildCodexEntries({ cwd }) {
   ];
 }
 
-function buildWorkspaceHelperEntries() {
+function buildWorkspaceHelperEntries(stateDirName) {
   return buildPlanningCliHelperEntries({
     packageName: PACKAGE_JSON.name,
     packageVersion: PACKAGE_JSON.version,
+    stateDirName,
   }).map((entry) => ({
-    relativePath: `.planning/${entry.relativePath}`,
+    relativePath: `${stateDirName}/${entry.relativePath}`,
     expectedContent: entry.content,
   }));
 }
 
 export function collectExpectedRuntimeSurfaceGroups({ cwd = process.cwd(), workflows }) {
+  const stateDirName = resolveStateDir(cwd).name;
   return [
     {
       runtime: 'workspace-helper',
       label: 'workspace workflow helper',
-      root: '.planning/bin',
+      root: `${stateDirName}/bin`,
       repairCommand: 'npx -y gsdd-cli update',
-      entries: buildWorkspaceHelperEntries(),
+      entries: buildWorkspaceHelperEntries(stateDirName),
     },
     {
       runtime: 'portable',
       label: 'portable skills',
       root: '.agents/skills',
       repairCommand: 'npx -y gsdd-cli update',
-      entries: buildPortableSkillEntries(workflows).map((entry) => ({
+      entries: buildPortableSkillEntries(workflows, { stateDirName }).map((entry) => ({
         relativePath: entry.relativePath,
         expectedContent: entry.content,
       })),
@@ -184,14 +187,14 @@ export function collectExpectedRuntimeSurfaceGroups({ cwd = process.cwd(), workf
       label: 'Claude Code native surfaces',
       root: '.claude',
       repairCommand: 'npx -y gsdd-cli update --tools claude',
-      entries: buildClaudeEntries({ cwd, workflows }),
+      entries: buildClaudeEntries({ cwd, workflows, stateDirName }),
     },
     {
       runtime: 'opencode',
       label: 'OpenCode native surfaces',
       root: '.opencode',
       repairCommand: 'npx -y gsdd-cli update --tools opencode',
-      entries: buildOpenCodeEntries({ cwd, workflows }),
+      entries: buildOpenCodeEntries({ cwd, workflows, stateDirName }),
     },
     {
       runtime: 'codex',
@@ -206,7 +209,7 @@ export function collectExpectedRuntimeSurfaceGroups({ cwd = process.cwd(), workf
 export function evaluateRuntimeFreshness({ cwd = process.cwd(), workflows = [] }) {
   const groups = collectExpectedRuntimeSurfaceGroups({ cwd, workflows }).map((group) => {
     const installed = group.runtime === 'workspace-helper'
-      ? existsSync(join(cwd, '.planning'))
+      ? existsSync(resolveStateDir(cwd).dir)
       : existsSync(join(cwd, group.root));
     const comparisons = installed
       ? group.entries.map((entry) => compareGeneratedFile({

package/bin/lib/state-dir.mjs

@@ -0,0 +1,45 @@
+// state-dir.mjs — Single source of truth for the Workspine state directory.
+//
+// Workspine keeps everything in ONE folder: .work/. Older projects used
+// .planning/. This module is the only place that decides which folder the tool
+// reads and writes for a given repo root. No other module may hardcode the name.
+
+import { existsSync } from 'fs';
+import { join } from 'path';
+
+export const STATE_DIR_NAME = '.work';
+export const LEGACY_STATE_DIR_NAME = '.planning';
+
+export const MIGRATION_NOTICE =
+  'Note: reading legacy .planning/ — new Workspine projects use .work/. Your .planning/ still works; move its files under .work/ when convenient.';
+
+// True when a repo root already holds Workspine state in EITHER the current
+// (.work) or legacy (.planning) location. Used for workspace-root discovery.
+export function hasStateMarker(root) {
+  return (
+    existsSync(join(root, STATE_DIR_NAME, 'config.json')) ||
+    existsSync(join(root, STATE_DIR_NAME)) ||
+    existsSync(join(root, LEGACY_STATE_DIR_NAME, 'config.json')) ||
+    existsSync(join(root, LEGACY_STATE_DIR_NAME))
+  );
+}
+
+// Decide which state directory to use for a repo root.
+// Precedence (config.json is the "really initialized" marker):
+//   1. .work/config.json     -> .work     (migration done / new project)
+//   2. .planning/config.json -> .planning (legacy; dual-read + notice)
+//   3. .work/ dir            -> .work
+//   4. .planning/ dir        -> .planning (legacy; dual-read + notice)
+//   5. neither               -> .work     (brand-new repo default)
+export function resolveStateDir(root) {
+  const workDir = join(root, STATE_DIR_NAME);
+  const legacyDir = join(root, LEGACY_STATE_DIR_NAME);
+  const work = { dir: workDir, name: STATE_DIR_NAME, legacy: false, migrationNotice: null };
+  const legacy = { dir: legacyDir, name: LEGACY_STATE_DIR_NAME, legacy: true, migrationNotice: MIGRATION_NOTICE };
+
+  if (existsSync(join(workDir, 'config.json'))) return work;
+  if (existsSync(join(legacyDir, 'config.json'))) return legacy;
+  if (existsSync(workDir)) return work;
+  if (existsSync(legacyDir)) return legacy;
+  return work;
+}

package/bin/lib/templates.mjs

@@ -1,17 +1,20 @@
 // templates.mjs - Project template and role installation/refresh helpers
 
-import { existsSync, mkdirSync, readdirSync, cpSync, unlinkSync } from 'fs';
-import { join } from 'path';
+import { createHash } from 'crypto';
+import { existsSync, mkdirSync, readdirSync, cpSync, unlinkSync, readFileSync, statSync, writeFileSync } from 'fs';
+import { basename, join } from 'path';
 import { fileHash, readManifest } from './manifest.mjs';
+import { localizeStateDirReferences } from './rendering.mjs';
 
-export function installProjectTemplates({ planningDir, distilledDir, agentsDir }) {
+export function installProjectTemplates({ planningDir, distilledDir, agentsDir, stateDirName = '.work' }) {
   const localTemplatesDir = join(planningDir, 'templates');
   const globalTemplatesDir = join(distilledDir, 'templates');
+  const stateName = basename(planningDir);
 
   if (!existsSync(localTemplatesDir)) {
     if (existsSync(globalTemplatesDir)) {
-      cpSync(globalTemplatesDir, localTemplatesDir, { recursive: true });
-      console.log('  - copied templates to .planning/templates/');
+      copyTemplateTree(globalTemplatesDir, localTemplatesDir, { stateDirName });
+      console.log(`  - copied templates to ${stateName}/templates/`);
       // Warn-only by design: init should not fail on missing templates because
       // the user may still proceed and fix later. The hard gate lives in
       // `gsdd health` (E6/E7/E8) which reports these as errors. This is the
@@ -33,7 +36,7 @@ export function installProjectTemplates({ planningDir, distilledDir, agentsDir }
       console.log('  - WARN: missing distilled/templates/; cannot copy templates');
     }
   } else {
-    console.log('  - .planning/templates/ already exists');
+    console.log(`  - ${stateName}/templates/ already exists`);
   }
 
   const localRolesDir = join(localTemplatesDir, 'roles');
@@ -41,18 +44,18 @@ export function installProjectTemplates({ planningDir, distilledDir, agentsDir }
     if (existsSync(agentsDir)) {
       mkdirSync(localRolesDir, { recursive: true });
       for (const file of listRoleFiles(agentsDir)) {
-        cpSync(join(agentsDir, file), join(localRolesDir, file));
+        copyTemplateFile(join(agentsDir, file), join(localRolesDir, file), { stateDirName });
       }
-      console.log('  - copied role contracts to .planning/templates/roles/');
+      console.log(`  - copied role contracts to ${stateName}/templates/roles/`);
     } else {
       console.log('  - WARN: missing agents/; cannot copy role contracts');
     }
   } else {
-    console.log('  - .planning/templates/roles/ already exists');
+    console.log(`  - ${stateName}/templates/roles/ already exists`);
   }
 }
 
-export function refreshTemplates({ planningDir, distilledDir, agentsDir, isDry = false }) {
+export function refreshTemplates({ planningDir, distilledDir, agentsDir, isDry = false, stateDirName = '.work' }) {
   const existingManifest = readManifest(planningDir);
   const globalTemplatesDir = join(distilledDir, 'templates');
   const localTemplatesDir = join(planningDir, 'templates');
@@ -65,11 +68,45 @@ export function refreshTemplates({ planningDir, distilledDir, agentsDir, isDry =
   ];
 
   for (const category of categories) {
-    refreshCategory(category, existingManifest, isDry);
+    refreshCategory(category, existingManifest, isDry, { stateDirName });
   }
 
-  refreshRootTemplates(globalTemplatesDir, localTemplatesDir, existingManifest, isDry);
-  refreshRoles(agentsDir, join(localTemplatesDir, 'roles'), existingManifest, isDry);
+  refreshRootTemplates(globalTemplatesDir, localTemplatesDir, existingManifest, isDry, { stateDirName });
+  refreshRoles(agentsDir, join(localTemplatesDir, 'roles'), existingManifest, isDry, { stateDirName });
+}
+
+function contentHash(content) {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+function localizedTemplateContent(srcPath, { stateDirName = '.work' } = {}) {
+  return localizeStateDirReferences(readFileSync(srcPath, 'utf-8'), { stateDirName });
+}
+
+function sourceTemplateHash(srcPath, { stateDirName = '.work' } = {}) {
+  if (!srcPath.endsWith('.md')) return fileHash(srcPath);
+  return contentHash(localizedTemplateContent(srcPath, { stateDirName }));
+}
+
+function copyTemplateFile(srcPath, destPath, { stateDirName = '.work' } = {}) {
+  if (!srcPath.endsWith('.md')) {
+    cpSync(srcPath, destPath);
+    return;
+  }
+  writeFileSync(destPath, localizedTemplateContent(srcPath, { stateDirName }));
+}
+
+function copyTemplateTree(srcDir, destDir, { stateDirName = '.work' } = {}) {
+  mkdirSync(destDir, { recursive: true });
+  for (const entry of readdirSync(srcDir)) {
+    const srcPath = join(srcDir, entry);
+    const destPath = join(destDir, entry);
+    if (statSync(srcPath).isDirectory()) {
+      copyTemplateTree(srcPath, destPath, { stateDirName });
+    } else {
+      copyTemplateFile(srcPath, destPath, { stateDirName });
+    }
+  }
 }
 
 function listRoleFiles(agentsDir) {
@@ -78,7 +115,7 @@ function listRoleFiles(agentsDir) {
   );
 }
 
-function refreshCategory({ name, src, dest, manifestKey }, existingManifest, isDry) {
+function refreshCategory({ name, src, dest, manifestKey }, existingManifest, isDry, { stateDirName = '.work' } = {}) {
   if (!existsSync(src)) return;
   if (!existsSync(dest) && !isDry) {
     mkdirSync(dest, { recursive: true });
@@ -91,7 +128,7 @@ function refreshCategory({ name, src, dest, manifestKey }, existingManifest, isD
   for (const file of sourceFiles) {
     const srcPath = join(src, file);
     const destPath = join(dest, file);
-    const srcHash = fileHash(srcPath);
+    const srcHash = sourceTemplateHash(srcPath, { stateDirName });
 
     if (existsSync(destPath)) {
       const destHash = fileHash(destPath);
@@ -106,7 +143,7 @@ function refreshCategory({ name, src, dest, manifestKey }, existingManifest, isD
     if (isDry) {
       console.log(`  - would refresh ${name}/${file}`);
     } else {
-      cpSync(srcPath, destPath);
+      copyTemplateFile(srcPath, destPath, { stateDirName });
       console.log(`  - refreshed ${name}/${file}`);
     }
   }
@@ -126,7 +163,7 @@ function refreshCategory({ name, src, dest, manifestKey }, existingManifest, isD
   }
 }
 
-function refreshRootTemplates(globalTemplatesDir, localTemplatesDir, existingManifest, isDry) {
+function refreshRootTemplates(globalTemplatesDir, localTemplatesDir, existingManifest, isDry, { stateDirName = '.work' } = {}) {
   if (!existsSync(globalTemplatesDir)) return;
 
   const manifestHashes = existingManifest?.templates?.root || null;
@@ -135,7 +172,7 @@ function refreshRootTemplates(globalTemplatesDir, localTemplatesDir, existingMan
   for (const file of sourceFiles) {
     const srcPath = join(globalTemplatesDir, file);
     const destPath = join(localTemplatesDir, file);
-    const srcHash = fileHash(srcPath);
+    const srcHash = sourceTemplateHash(srcPath, { stateDirName });
 
     if (existsSync(destPath)) {
       const destHash = fileHash(destPath);
@@ -150,7 +187,7 @@ function refreshRootTemplates(globalTemplatesDir, localTemplatesDir, existingMan
     if (isDry) {
       console.log(`  - would refresh templates/${file}`);
     } else {
-      cpSync(srcPath, destPath);
+      copyTemplateFile(srcPath, destPath, { stateDirName });
       console.log(`  - refreshed templates/${file}`);
     }
   }
@@ -174,7 +211,7 @@ function refreshRootTemplates(globalTemplatesDir, localTemplatesDir, existingMan
   }
 }
 
-function refreshRoles(agentsDir, localRolesDir, existingManifest, isDry) {
+function refreshRoles(agentsDir, localRolesDir, existingManifest, isDry, { stateDirName = '.work' } = {}) {
   if (!existsSync(agentsDir)) return;
   if (!existsSync(localRolesDir) && !isDry) {
     mkdirSync(localRolesDir, { recursive: true });
@@ -189,7 +226,7 @@ function refreshRoles(agentsDir, localRolesDir, existingManifest, isDry) {
   for (const file of sourceFiles) {
     const srcPath = join(agentsDir, file);
     const destPath = join(localRolesDir, file);
-    const srcHash = fileHash(srcPath);
+    const srcHash = sourceTemplateHash(srcPath, { stateDirName });
 
     if (existsSync(destPath)) {
       const destHash = fileHash(destPath);
@@ -204,7 +241,7 @@ function refreshRoles(agentsDir, localRolesDir, existingManifest, isDry) {
     if (isDry) {
       console.log(`  - would refresh roles/${file}`);
     } else {
-      cpSync(srcPath, destPath);
+      copyTemplateFile(srcPath, destPath, { stateDirName });
       console.log(`  - refreshed roles/${file}`);
     }
   }

package/bin/lib/work-context.mjs

@@ -12,6 +12,8 @@ import {
   writeSync,
 } from 'fs';
 import { basename, dirname, join, relative, resolve } from 'path';
+import { evaluateLifecycleState } from './lifecycle-state.mjs';
+import { resolveStateDir } from './state-dir.mjs';
 
 export const WORK_DIR_NAME = '.work';
 
@@ -657,14 +659,22 @@ export function inspectWorkContext(cwd = process.cwd()) {
   const questions = readOpenQuestions(paths.workDir);
   const evidence = readJsonIfExists(paths.evidenceManifest);
   const graph = readGraphEvents(paths.workDir);
-  const planningDir = join(paths.root, '.planning');
+  const { dir: planningDir, name: stateDirName, migrationNotice } = resolveStateDir(paths.root);
+  const lifecycle = evaluateLifecycleState({ planningDir });
   const planning = {
     exists: existsSync(planningDir),
     has_spec: existsSync(join(planningDir, 'SPEC.md')),
     has_roadmap: existsSync(join(planningDir, 'ROADMAP.md')),
     has_milestones: existsSync(join(planningDir, 'MILESTONES.md')),
     has_config: existsSync(join(planningDir, 'config.json')),
+    has_brownfield_change: lifecycle.brownfieldChange.exists,
+    non_phase_state: lifecycle.nonPhaseState,
+    brownfield_change: lifecycle.brownfieldChange,
+    current_phase: lifecycle.currentPhase?.number || null,
+    next_phase: lifecycle.nextPhase?.number || null,
+    counts: lifecycle.counts,
     phases: scanPhaseEvidence(planningDir),
+    state_dir_name: stateDirName,
   };
   return {
     paths,
@@ -676,6 +686,7 @@ export function inspectWorkContext(cwd = process.cwd()) {
     evidence,
     graph,
     planning,
+    migration_notice: migrationNotice,
     milestone: inspectWorkMilestone(paths.workDir),
     focus_exists: existsSync(paths.focus),
     handoff_exists: existsSync(paths.handoff),

package/bin/lib/workflows.mjs

@@ -17,7 +17,6 @@ export const WORKFLOWS = [
   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' }),