@opengsd/gsd-core 1.2.0 → 1.3.0-rc.1

package/get-shit-done/bin/lib/shell-command-projection.cjs

@@ -41,6 +41,39 @@ function formatHookCommandForRuntime(command, opts = {}) {
   return hookCommandNeedsPowerShellCallOperator(opts) ? `& ${command}` : command;
 }
 
+// #166/#580: Claude Code on Windows executes hook command strings inside Git
+// Bash. A `.sh` hook wrapped with an explicit bash.exe path makes bash try to
+// exec bash itself ("C:/.../bash.exe: cannot execute binary file"). Both install
+// paths — global (buildHookCommand) and local (buildLocalShellHookCommand) — must
+// drop the bash runner in this case and emit only the anchored script path.
+// Centralized here so the two paths cannot silently drift apart again: the local
+// path missed this guard and reintroduced the #166/#377 failure (#580).
+function shellHookOmitsBashRunner({ platform = process.platform, runtime = 'generic', isShellHook = false } = {}) {
+  return platform === 'win32' && runtime === 'claude' && isShellHook;
+}
+
+// Builds the command string for a local-install managed `.sh` hook. Mirrors the
+// global buildHookCommand path but uses the $CLAUDE_PROJECT_DIR-anchored prefix
+// instead of an absolute configDir. On Claude/Windows the bash runner is dropped
+// (see shellHookOmitsBashRunner) and the anchored script path is emitted alone —
+// matching the global path. Elsewhere the resolved bash runner is required; a
+// null runner yields null so callers skip registration instead of emitting a
+// broken hook (#3393).
+function buildLocalShellHookCommand({ localPrefix, hookFile, bashRunner, runtime = 'generic', platform = process.platform }) {
+  if (!localPrefix || !hookFile) return null;
+  const scriptPath = `${localPrefix}/hooks/${hookFile}`;
+  if (shellHookOmitsBashRunner({ platform, runtime, isShellHook: true })) {
+    return formatHookCommandForRuntime(scriptPath, { platform, runtime });
+  }
+  if (!bashRunner) return null;
+  return projectShellCommandText({
+    runnerToken: bashRunner,
+    argTokens: [scriptPath],
+    runtime,
+    platform,
+  });
+}
+
 /**
  * Project a managed hook script path token for serialized shell commands.
  * Windows managed hook commands normalize to forward slashes so the same path
@@ -476,6 +509,8 @@ function platformEnsureDir(dirPath) {
 module.exports = {
   hookCommandNeedsPowerShellCallOperator,
   formatHookCommandForRuntime,
+  shellHookOmitsBashRunner,
+  buildLocalShellHookCommand,
   formatManagedHookScriptToken,
   projectLocalHookPrefix,
   projectPortableHookBaseDir,

package/get-shit-done/bin/lib/state-document.cjs

@@ -238,10 +238,6 @@ function isStateTemplateDefault(field, value) {
 function stateReplaceFieldIfTemplate(content, field, knownDefaults, newValue) {
     if (newValue === null || newValue === undefined) return content;
     const existing = stateExtractField(content, field);
-    // Build a temporary KNOWN_TEMPLATE_DEFAULTS-compatible lookup so we can reuse
-    // the isStateTemplateDefault logic for the provided knownDefaults array.
-    const tempField = '__tmp__';
-    const tempDefaults = { [tempField]: knownDefaults || [] };
     // Inline check: absent/blank → always write; in list → write; else → skip.
     if (existing === null || existing === undefined || existing.trim() === '') {
         return stateReplaceField(content, field, newValue) || content;

package/get-shit-done/bin/lib/state.cjs

@@ -4,7 +4,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { escapeRegex, loadConfig, getMilestoneInfo, getMilestonePhaseFilter, output, error } = require('./core.cjs');
+const { escapeRegex, loadConfig, getMilestoneInfo, getMilestonePhaseFilter, extractCurrentMilestone, output, error } = require('./core.cjs');
 const { platformWriteSync, platformReadSync, platformEnsureDir } = require('./shell-command-projection.cjs');
 const { planningDir, planningPaths } = require('./planning-workspace.cjs');
 const { realClock } = require('./clock.cjs');
@@ -886,9 +886,31 @@ function buildStateFrontmatter(bodyContent, cwd) {
             diskTotalSummaries += summaryCount;
             if (completed) diskCompletedPhases++;
           }
+          // Count phase headings from ROADMAP using a digit-containing pattern
+          // that matches both numeric phases (01, 05.1) and project-code phases
+          // (PROJ-42, CK-05) but excludes pure-word section headers like
+          // `## Phase Overview:` or `## Phase Details:` — single source of
+          // truth for total_phases (#549).
+          let roadmapPhaseCount = 0;
+          try {
+            const roadmapPath = path.join(planningDir(cwd), 'ROADMAP.md');
+            const roadmapRaw = platformReadSync(roadmapPath);
+            if (roadmapRaw !== null) {
+              const roadmapScope = extractCurrentMilestone(roadmapRaw, cwd);
+              const phaseHeadingPattern = /#{2,4}\s*Phase\s+([\w][\w.-]*)\s*:/gi;
+              let m;
+              while ((m = phaseHeadingPattern.exec(roadmapScope)) !== null) {
+                // Only count tokens that contain at least one digit — excludes
+                // pure-word section headings (Overview, Details) while keeping
+                // numeric phases (01, 05.1) and project-code IDs (PROJ-42).
+                if (/\d/.test(m[1])) roadmapPhaseCount++;
+              }
+            }
+          } catch { /* fall through: phaseDirs.length used as sole count */ }
+
           cached = {
-            totalPhases: isDirInMilestone.phaseCount > 0
-              ? Math.max(phaseDirs.length, isDirInMilestone.phaseCount)
+            totalPhases: roadmapPhaseCount > 0
+              ? Math.max(phaseDirs.length, roadmapPhaseCount)
               : phaseDirs.length,
             completedPhases: diskCompletedPhases,
             totalPlans: diskTotalPlans,
@@ -1651,9 +1673,22 @@ function cmdStateSync(cwd, options, raw) {
   // Mirrors the logic in buildStateFrontmatter so both report consistent percents (#3242 Bug B).
   let syncTotalPhases = null;
   try {
-    const isDirInMilestone = getMilestonePhaseFilter(cwd);
-    if (isDirInMilestone.phaseCount > 0) {
-      syncTotalPhases = Math.max(entries.length, isDirInMilestone.phaseCount);
+    let roadmapPhaseCount = 0;
+    const roadmapPath = path.join(planningDir(cwd), 'ROADMAP.md');
+    const roadmapRaw = platformReadSync(roadmapPath);
+    if (roadmapRaw !== null) {
+      const roadmapScope = extractCurrentMilestone(roadmapRaw, cwd);
+      const phaseHeadingPattern = /#{2,4}\s*Phase\s+([\w][\w.-]*)\s*:/gi;
+      let m;
+      while ((m = phaseHeadingPattern.exec(roadmapScope)) !== null) {
+        // Only count tokens that contain at least one digit — excludes
+        // pure-word section headings (Overview, Details) while keeping
+        // numeric phases (01, 05.1) and project-code IDs (PROJ-42).
+        if (/\d/.test(m[1])) roadmapPhaseCount++;
+      }
+    }
+    if (roadmapPhaseCount > 0) {
+      syncTotalPhases = Math.max(entries.length, roadmapPhaseCount);
     } else {
       syncTotalPhases = entries.length;
     }

package/get-shit-done/bin/lib/ui-safety-gate.cjs

@@ -0,0 +1,111 @@
+'use strict';
+
+/**
+ * UI Safety Gate — shell-free implementation (#3706, #3718)
+ *
+ * Replaces the bash shell-based one-liner that silently degraded on Windows
+ * PowerShell / cmd.exe because the locale env-var prefix was not recognised.
+ * This module runs inside Node.js — no shell dependency, works identically
+ * on bash, Git-Bash, PowerShell, and cmd.exe.
+ *
+ * Word-boundary anchoring:
+ *   (^|[^a-zA-Z0-9])(TOKEN)([^a-zA-Z0-9]|$)
+ * Equivalent to POSIX ERE [^[:alnum:]] — matches tokens only when they are not
+ * interior substrings of alphanumeric compound words (e.g. "microfrontend" is NOT
+ * matched; "micro-frontend" and "micro frontend" ARE matched).
+ *
+ * Public API:
+ *   checkUiPresence(text: string): { hasUI: boolean, tokens: string[] }
+ *
+ * CLI usage — reads phase-section text from STDIN to avoid ARG_MAX limits:
+ *   echo "$PHASE_SECTION" | node get-shit-done/bin/lib/ui-safety-gate.cjs
+ *   echo $?   → 0 if UI tokens found, 1 if not, 2 on usage error
+ *
+ * Exit codes mirror grep: 0 = match found, 1 = no match, 2 = usage error.
+ *
+ * Canonical location: get-shit-done/bin/lib/ui-safety-gate.cjs (#448)
+ * This path is deployed by the GSD installer to $RUNTIME_DIR/get-shit-done/bin/lib/.
+ * bin/lib/ui-safety-gate.cjs (root) is retained for source-repo and npm usage.
+ */
+
+const UI_TOKENS = [
+  'UI',
+  'interface',
+  'frontend',
+  'component',
+  'layout',
+  'page',
+  'screen',
+  'view',
+  'form',
+  'dashboard',
+  'widget',
+];
+
+/**
+ * Built once at module load — no per-call compilation overhead.
+ * ASCII word boundaries — matches the original ASCII-grep intent of #3706.
+ * Note: JS [a-zA-Z0-9] is ASCII-only and NOT equivalent to POSIX [[:alnum:]],
+ * which is locale-sensitive and includes accented characters.
+ */
+const UI_GATE_PATTERN = new RegExp(
+  '(^|[^a-zA-Z0-9])(' + UI_TOKENS.join('|') + ')([^a-zA-Z0-9]|$)',
+  'i'
+);
+
+// Global-flagged variant for extracting ALL matches per line (matchAll).
+const UI_GATE_PATTERN_GLOBAL = new RegExp(UI_GATE_PATTERN.source, 'gi');
+
+/**
+ * Check a roadmap phase section string for frontend UI indicators.
+ *
+ * @param {string} text - The roadmap phase section content (may be multi-line, CRLF or LF).
+ * @returns {{ hasUI: boolean, tokens: string[] }}
+ *   hasUI — true if any UI token was matched as a standalone word.
+ *   tokens — matched token strings (lowercased), deduplicated.
+ */
+function checkUiPresence(text) {
+  if (typeof text !== 'string') {
+    return { hasUI: false, tokens: [] };
+  }
+
+  // Normalise CRLF so the pattern sees consistent line boundaries.
+  const normalised = text.replace(/\r\n/g, '\n');
+
+  const found = new Set();
+  for (const line of normalised.split('\n')) {
+    // Reset lastIndex before each line so the global pattern restarts from 0.
+    UI_GATE_PATTERN_GLOBAL.lastIndex = 0;
+    for (const m of line.matchAll(UI_GATE_PATTERN_GLOBAL)) {
+      found.add(m[2].toLowerCase());
+    }
+  }
+
+  return { hasUI: found.size > 0, tokens: [...found] };
+}
+
+module.exports = { checkUiPresence, UI_TOKENS };
+
+// ── CLI entry point ─────────────────────────────────────────────────────────
+// Reads phase-section text from STDIN (not argv) to avoid OS ARG_MAX limits.
+// Invoked by workflow .md bash blocks as: echo "$PHASE_SECTION" | node .../ui-safety-gate.cjs
+// Exit 0 = UI found, 1 = no UI, 2 = startup error.
+
+if (require.main === module) {
+  // Collect stdin chunks asynchronously.
+  const chunks = [];
+  process.stdin.setEncoding('utf-8');
+
+  process.stdin.on('data', (chunk) => chunks.push(chunk));
+
+  process.stdin.on('end', () => {
+    const input = chunks.join('');
+    const result = checkUiPresence(input);
+    process.exit(result.hasUI ? 0 : 1);
+  });
+
+  process.stdin.on('error', (err) => {
+    process.stderr.write(`ERROR: ui-safety-gate.cjs stdin read failed: ${err.message}\n`);
+    process.exit(2);
+  });
+}

package/get-shit-done/bin/lib/validate.cjs

@@ -29,8 +29,13 @@
  */
 
 // ── Issue #26: regex constants (W005, W006-archived) ────────────────────────
-const phaseDirNameRe = /^\d{2,}(?:\.\d+)*-[\w-]+$/;
-const PHASE_TOKEN_FROM_DIR_RE = /^(?:[A-Z]{1,6}-)?(\d+[A-Z]?(?:\.\d+)*)(?:-|$)/i;
+// Matches legacy numeric dirs (01-setup), milestone-prefixed dirs (02-01-setup),
+// deep dirs (02-04-01-deep), and project-code-prefixed variants (GSD-02-01-setup).
+const phaseDirNameRe = /^(?:[A-Z]{1,6}-)?\d{2,}(?:-\d+)*(?:\.\d+)*-[\w-]+$/i;
+// Extracts the full phase token from a directory name, including milestone-prefixed
+// multi-segment tokens like "02-01" from "02-01-setup" or "GSD-02-01-setup".
+// Greedily captures all leading all-digit segments before the first letter-start segment.
+const PHASE_TOKEN_FROM_DIR_RE = /^(?:[A-Z]{1,6}-)?(\d+(?:-\d+)*[A-Z]?(?:\.\d+)*)(?:-[a-z]|$)/i;
 const MILESTONE_ARCHIVE_DIR_RE = /^v\d+.*-phases$/i;
 
 // ── Issue #26: I001 canonicalization ────────────────────────────────────────
@@ -41,26 +46,46 @@ function canonicalPlanStem(stem) {
 
 // ── Issue #6: phase variant helpers (W006/W007) ──────────────────────────────
 function phaseVariants(phase) {
+  const variants = new Set([phase]);
+  const dotIdx = phase.indexOf('.');
+  const head = dotIdx === -1 ? phase : phase.slice(0, dotIdx);
+  const tail = dotIdx === -1 ? '' : phase.slice(dotIdx);
 
-                const variants = new Set([phase]);
-                const dotIdx = phase.indexOf('.');
-                const head = dotIdx === -1 ? phase : phase.slice(0, dotIdx);
-                const tail = dotIdx === -1 ? '' : phase.slice(dotIdx);
-                const headMatch = head.match(/^(\d+)([A-Z]?)$/i);
-                if (!headMatch)
-                    return variants;
-                const numericHead = headMatch[1];
-                const letterSuffix = headMatch[2] || '';
-                variants.add(`${String(parseInt(numericHead, 10))}${letterSuffix}${tail}`);
-                variants.add(`${numericHead.padStart(2, '0')}${letterSuffix}${tail}`);
-                return variants;
-            
+  // Milestone-prefixed IDs: M-NN or M-N-N. Add padding-normalized variant.
+  // e.g. "2-01" → also "02-01"; "02-01" → also "2-01"
+  const milestoneHeadMatch = head.match(/^(\d+)((?:-\d+)+)([A-Z]?)$/i);
+  if (milestoneHeadMatch) {
+    const major = milestoneHeadMatch[1];
+    const subSegs = milestoneHeadMatch[2]; // e.g. "-01" or "-04-01"
+    const letter = milestoneHeadMatch[3] || '';
+    const paddedMajor = major.padStart(2, '0');
+    const unpaddedMajor = String(parseInt(major, 10));
+    // Pad/unpad sub-segments individually
+    const paddedSubs = subSegs.slice(1).split('-').map(s => s.padStart(2, '0')).join('-');
+    const unpaddedSubs = subSegs.slice(1).split('-').map(s => String(parseInt(s, 10))).join('-');
+    variants.add(`${paddedMajor}-${paddedSubs}${letter}${tail}`);
+    variants.add(`${unpaddedMajor}-${unpaddedSubs}${letter}${tail}`);
+    variants.add(`${unpaddedMajor}-${paddedSubs}${letter}${tail}`);
+    variants.add(`${paddedMajor}-${unpaddedSubs}${letter}${tail}`);
+    return variants;
+  }
+
+  // Plain numeric/decimal IDs: "1", "01", "12A", "12.1"
+  const headMatch = head.match(/^(\d+)([A-Z]?)$/i);
+  if (!headMatch) return variants;
+  const numericHead = headMatch[1];
+  const letterSuffix = headMatch[2] || '';
+  variants.add(`${String(parseInt(numericHead, 10))}${letterSuffix}${tail}`);
+  variants.add(`${numericHead.padStart(2, '0')}${letterSuffix}${tail}`);
+  return variants;
 }
 
 function buildRoadmapPhaseVariants(roadmapContent) {
   const roadmapPhases = new Set();
   const roadmapPhaseVariants = new Set();
-  const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:/gi;
+  // Matches both legacy numeric (Phase 1:), decimal (Phase 2.1:), milestone-prefixed (Phase 2-01:),
+  // and bracket-prefixed (### [GSD] Phase 2-01:) headings.
+  const phasePattern = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*(?:-[\w.-]+)*)\s*:/gi;
   let m;
   while ((m = phasePattern.exec(roadmapContent)) !== null) {
     roadmapPhases.add(m[1]);
@@ -71,7 +96,8 @@ function buildRoadmapPhaseVariants(roadmapContent) {
 
 function buildNotStartedPhaseVariants(roadmapContent) {
   const notStartedPhases = new Set();
-  const uncheckedPattern = /-\s*\[\s\]\s*\*{0,2}Phase\s+(\d+[A-Z]?(?:\.\d+)*)[:\s*]/gi;
+  // Also matches milestone-prefixed and bracket-prefixed checklist items.
+  const uncheckedPattern = /-\s*\[\s\]\s*\*{0,2}Phase\s+([\w][\w.-]*(?:-[\w.-]+)*)[:\s*]/gi;
   let um;
   while ((um = uncheckedPattern.exec(roadmapContent)) !== null) {
     for (const variant of phaseVariants(um[1])) notStartedPhases.add(variant);

package/get-shit-done/bin/lib/verify.cjs

@@ -12,7 +12,7 @@ const {
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { loadConfig, normalizePhaseName, escapeRegex, findPhaseInternal, getMilestoneInfo, stripShippedMilestones, extractCurrentMilestone, output, error, checkAgentsInstalled, CONFIG_DEFAULTS, inspectWorktreeHealth } = require('./core.cjs');
+const { loadConfig, normalizePhaseName, phaseTokenMatches, escapeRegex, findPhaseInternal, getMilestoneInfo, stripShippedMilestones, extractCurrentMilestone, output, error, checkAgentsInstalled, CONFIG_DEFAULTS, inspectWorktreeHealth } = require('./core.cjs');
 const { execGit, platformReadSync: safeReadFile, platformWriteSync } = require('./shell-command-projection.cjs');
 const { PACKAGE_NAME } = require('./package-identity.cjs');
 const { planningDir } = require('./planning-workspace.cjs');
@@ -507,6 +507,34 @@ function collectDiskPhases(planBase) {
   return diskPhases;
 }
 
+// W021: phase ID integer prefix doesn't match its enclosing milestone section
+// Only fires when phase_id_convention is 'milestone-prefixed' (opt-in).
+// Returns array of mismatch objects: { phaseId, foundInMilestone, expectedMilestone }
+function checkMilestonePrefixMismatches(roadmapContent, { getMilestoneFromPhaseId }) {
+  const mismatches = [];
+  // Find all milestone sections (## vN.N or ## [code] vN.N)
+  const sections = [];
+  const sectionRx = /^#{1,3}\s+(?:\[[^\]]+\]\s*)?.*v(\d+\.\d+)/gim;
+  let m;
+  while ((m = sectionRx.exec(roadmapContent)) !== null) {
+    if (sections.length > 0) sections[sections.length - 1].end = m.index;
+    sections.push({ version: `v${m[1]}`, start: m.index, end: roadmapContent.length });
+  }
+  for (const section of sections) {
+    const content = roadmapContent.slice(section.start, section.end);
+    const phaseRx = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*)\s*:/gi;
+    let pm;
+    while ((pm = phaseRx.exec(content)) !== null) {
+      const phaseId = pm[1];
+      const expectedMilestone = getMilestoneFromPhaseId(phaseId);
+      if (expectedMilestone !== null && expectedMilestone !== section.version) {
+        mismatches.push({ phaseId, foundInMilestone: section.version, expectedMilestone });
+      }
+    }
+  }
+  return mismatches;
+}
+
 function cmdValidateConsistency(cwd, raw) {
   const planBase = planningDir(cwd);
   const roadmapPath = path.join(planBase, 'ROADMAP.md');
@@ -527,7 +555,9 @@ function cmdValidateConsistency(cwd, raw) {
   // stripped). Used for the "in ROADMAP but not on disk" check — we only require
   // disk dirs for the active milestone's phases.
   const roadmapPhases = new Set();
-  const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:/gi;
+  // Matches both legacy numeric (Phase 1:), decimal (Phase 2.1:), and
+  // milestone-prefixed (Phase 2-01:) headings, including bracket-prefixed form.
+  const phasePattern = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*(?:-[\w.-]+)*)\s*:/gi;
   let m;
   while ((m = phasePattern.exec(roadmapContent)) !== null) {
     roadmapPhases.add(m[1]);
@@ -539,7 +569,7 @@ function cmdValidateConsistency(cwd, raw) {
   // though it is absent from the active-milestone scope. Without this, narrowing
   // the scope (#501) would flag every shipped phase dir as a spurious orphan.
   const fullRoadmapPhases = new Set();
-  const fullPhasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:/gi;
+  const fullPhasePattern = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*(?:-[\w.-]+)*)\s*:/gi;
   let fm;
   while ((fm = fullPhasePattern.exec(roadmapContentRaw)) !== null) {
     fullRoadmapPhases.add(fm[1]);
@@ -558,8 +588,12 @@ function cmdValidateConsistency(cwd, raw) {
   // Check: phases on disk but not in ROADMAP (compared against the FULL roadmap
   // so shipped-milestone phase dirs are not flagged as orphans — #501)
   for (const p of diskPhases) {
+    // For plain numeric IDs, also try the unpadded form (e.g. "02" → "2").
+    // For milestone-prefixed IDs (e.g. "02-01"), use normalizePhaseName to
+    // canonicalize padding before comparing with the ROADMAP entries.
+    const normalized = normalizePhaseName(p);
     const unpadded = String(parseInt(p, 10));
-    if (!fullRoadmapPhases.has(p) && !fullRoadmapPhases.has(unpadded)) {
+    if (!fullRoadmapPhases.has(p) && !fullRoadmapPhases.has(normalized) && !fullRoadmapPhases.has(unpadded)) {
       warnings.push(`Phase ${p} exists on disk but not in ROADMAP.md`);
     }
   }
@@ -1059,6 +1093,31 @@ function cmdValidateHealth(cwd, options, raw) {
     }
   } catch { /* git worktree not available or not a git repo — skip silently */ }
 
+  // ─── Check 11b: Phase ID / milestone-section mismatch (W021) ─────────────
+  // Only active when phase_id_convention === 'milestone-prefixed' in config.json.
+  try {
+    const phaseConvention = (() => {
+      if (!fs.existsSync(configPath)) return null;
+      try {
+        const configRaw = fs.readFileSync(configPath, 'utf-8');
+        const configParsed = JSON.parse(configRaw);
+        return configParsed.phase_id_convention || null;
+      } catch { return null; }
+    })();
+    if (phaseConvention === 'milestone-prefixed') {
+      if (fs.existsSync(roadmapPath)) {
+        const roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
+        const { getMilestoneFromPhaseId } = require('./core.cjs');
+        const mismatches = checkMilestonePrefixMismatches(roadmapContent, { getMilestoneFromPhaseId });
+        for (const m of mismatches) {
+          addIssue('warning', 'W021',
+            `Phase ${m.phaseId}: integer prefix implies ${m.expectedMilestone} but listed under ${m.foundInMilestone}`,
+            'Run `gsd-tools roadmap upgrade --convention milestone-prefixed` to migrate (dry-run by default)');
+        }
+      }
+    }
+  } catch { /* W021 check is advisory — skip on error */ }
+
   // ─── Check 12: MILESTONES.md / archive snapshot drift (#2446) ─────────────
   const milestonesPath = path.join(planBase, 'MILESTONES.md');
   const milestonesArchiveDir = path.join(planBase, 'milestones');
@@ -1107,6 +1166,50 @@ function cmdValidateHealth(cwd, options, raw) {
     }
   } catch { /* artifact check is advisory — skip on error */ }
 
+  // ─── Check 14: milestone-status vs. roadmap-progress incoherence (W021) ───
+  try {
+    if (fs.existsSync(statePath) && fs.existsSync(roadmapPath)) {
+      const stateRaw = fs.readFileSync(statePath, 'utf-8');
+      const statusMatch = stateRaw.match(/^status:\s*(.+)/im);
+      const stateStatus = statusMatch ? statusMatch[1].trim().toLowerCase() : '';
+      const isMarkedComplete = /milestone complete|archived/.test(stateStatus);
+      if (isMarkedComplete) {
+        // Inline phase scan: read roadmap, extract current milestone section,
+        // then check for phases with no directory on disk (unstarted).
+        const roadmapRaw = fs.readFileSync(roadmapPath, 'utf-8');
+        const scopedContent = extractCurrentMilestone(roadmapRaw, cwd);
+        const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:\s*([^\n]+)/gi;
+        const unstarted = [];
+        let pm;
+        const planningWorkspace = require('./planning-workspace.cjs');
+        const phasesDir2 = planningWorkspace.planningPaths(cwd).phases;
+        const phaseDirNames2 = (() => {
+          try {
+            return fs.readdirSync(phasesDir2, { withFileTypes: true })
+              .filter(e => e.isDirectory()).map(e => e.name);
+          } catch { return []; }
+        })();
+        while ((pm = phasePattern.exec(scopedContent)) !== null) {
+          const phaseNum = pm[1];
+          const normalized = normalizePhaseName(phaseNum);
+          // Phase is unstarted (disk_status: no_directory) if no directory
+          // with a matching token exists on disk. Use phaseTokenMatches (same
+          // helper as roadmap.analyze) to correctly handle decimal (2.1) and
+          // letter-suffix (12A) phase IDs without false positives.
+          const hasDirectory = phaseDirNames2.some(d => phaseTokenMatches(d, normalized));
+          if (!hasDirectory) {
+            unstarted.push(phaseNum);
+          }
+        }
+        if (unstarted.length > 0) {
+          addIssue('warning', 'W021',
+            `STATE says milestone complete but ROADMAP lists ${unstarted.length} unstarted phase(s) (e.g. Phase ${unstarted[0]})`,
+            'Run validate consistency or re-run complete-milestone after verifying all phases are done');
+        }
+      }
+    }
+  } catch { /* W021 check is advisory — skip on error */ }
+
   // ─── Perform repairs if requested ─────────────────────────────────────────
   const repairActions = [];
   if (options.repair && repairs.length > 0) {

package/get-shit-done/bin/shared/config-defaults.manifest.json

@@ -11,6 +11,7 @@
   "context_window": 200000,
   "phase_naming": "sequential",
   "project_code": null,
+  "phase_id_convention": null,
   "mode": "interactive",
   "claude_md_path": "./CLAUDE.md",
   "git": {

package/get-shit-done/bin/shared/config-schema.manifest.json

@@ -83,6 +83,7 @@
     "features.global_learnings",
     "learnings.max_inject",
     "project_code",
+    "phase_id_convention",
     "phase_naming",
     "manager.flags.discuss",
     "manager.flags.plan",
@@ -100,7 +101,12 @@
     "effort.default",
     "fast_mode.enabled",
     "plan_review.source_grounding",
-    "plan_review.source_grounding_authority"
+    "plan_review.source_grounding_authority",
+    "model_policy.provider",
+    "model_policy.budget",
+    "model_policy.high",
+    "model_policy.medium",
+    "model_policy.low"
   ],
   "runtimeStateKeys": [
     "workflow._auto_chain_active"
@@ -170,6 +176,11 @@
       "topLevel": "review",
       "source": "^review\\.max_prompt_tokens_per_reviewer\\.[a-zA-Z0-9_-]+$",
       "description": "review.max_prompt_tokens_per_reviewer.<reviewer-slug>"
+    },
+    {
+      "topLevel": "model_policy",
+      "source": "^model_policy\\.runtime_tiers\\.[a-zA-Z0-9_-]+\\.(opus|sonnet|haiku)$",
+      "description": "model_policy.runtime_tiers.<runtime>.<opus|sonnet|haiku>"
     }
   ]
 }

package/get-shit-done/bin/shared/model-catalog.json

@@ -83,6 +83,33 @@
       "haiku": null
     }
   },
+  "providerPresets": {
+    "anthropic": {
+      "opus":   { "low": { "model": "claude-opus-4-5" }, "medium": { "model": "claude-opus-4-8" }, "high": { "model": "claude-opus-4-8" } },
+      "sonnet": { "low": { "model": "claude-haiku-4-5" }, "medium": { "model": "claude-sonnet-4-6" }, "high": { "model": "claude-opus-4-8" } },
+      "haiku":  { "low": { "model": "claude-haiku-4-5" }, "medium": { "model": "claude-haiku-4-5" }, "high": { "model": "claude-sonnet-4-6" } }
+    },
+    "openai": {
+      "opus":   { "low": { "model": "gpt-5.3-codex", "reasoning_effort": "medium" }, "medium": { "model": "gpt-5.5", "reasoning_effort": "high" }, "high": { "model": "gpt-5.5", "reasoning_effort": "xhigh" } },
+      "sonnet": { "low": { "model": "gpt-5.4-mini", "reasoning_effort": "low" }, "medium": { "model": "gpt-5.3-codex", "reasoning_effort": "medium" }, "high": { "model": "gpt-5.5", "reasoning_effort": "medium" } },
+      "haiku":  { "low": { "model": "gpt-5.4-mini", "reasoning_effort": "minimal" }, "medium": { "model": "gpt-5.4-mini", "reasoning_effort": "medium" }, "high": { "model": "gpt-5.3-codex", "reasoning_effort": "medium" } }
+    },
+    "google": {
+      "opus":   { "low": { "model": "gemini-2.5-flash-lite" }, "medium": { "model": "gemini-3-flash" }, "high": { "model": "gemini-3-pro" } },
+      "sonnet": { "low": { "model": "gemini-2.5-flash-lite" }, "medium": { "model": "gemini-3-flash" }, "high": { "model": "gemini-3-flash" } },
+      "haiku":  { "low": { "model": "gemini-2.5-flash-lite" }, "medium": { "model": "gemini-2.5-flash-lite" }, "high": { "model": "gemini-3-flash" } }
+    },
+    "qwen": {
+      "opus":   { "low": { "model": "qwen3-coder-plus" }, "medium": { "model": "qwen3-max-2026-01-23" }, "high": { "model": "qwen3-max-2026-01-23" } },
+      "sonnet": { "low": { "model": "qwen3-coder-next" }, "medium": { "model": "qwen3-coder-plus" }, "high": { "model": "qwen3-max-2026-01-23" } },
+      "haiku":  { "low": { "model": "qwen3-coder-next" }, "medium": { "model": "qwen3-coder-next" }, "high": { "model": "qwen3-coder-plus" } }
+    },
+    "generic": {
+      "opus":   { "low": null, "medium": null, "high": null },
+      "sonnet": { "low": null, "medium": null, "high": null },
+      "haiku":  { "low": null, "medium": null, "high": null }
+    }
+  },
   "agents": {
     "gsd-planner":                { "golden": "opus",   "balanced": "opus",   "budget": "sonnet", "phaseType": "planning",     "routingTier": "heavy" },
     "gsd-roadmapper":             { "golden": "opus",   "balanced": "sonnet", "budget": "sonnet", "phaseType": "planning",     "routingTier": "heavy" },

package/get-shit-done/references/checkpoints.md

@@ -18,7 +18,7 @@ Plans execute autonomously. Checkpoints formalize interaction points where human
 
 **When:** Claude completed automated work, human confirms it works correctly.
 
-> **Default mode (#3309): `workflow.human_verify_mode = end-of-phase`.** New projects do NOT halt mid-flight at `checkpoint:human-verify`. The planner suppresses those task emissions and embeds the verification details into the relevant `auto` task's `<verify><human-check>` block; the verifier harvests every `<verify><human-check>` at end-of-phase (Step 8) and consolidates them into the existing `human_needed` → HUMAN-UAT.md flow in `workflows/execute-phase.md`. The user reviews everything in one batch.
+> **Default mode (#3309): `workflow.human_verify_mode = end-of-phase`.** New projects do NOT halt mid-flight at `checkpoint:human-verify`. The planner suppresses those task emissions and embeds the verification details into the relevant `auto` task's `<verify><human-check>` block; the verifier harvests every `<verify><human-check>` at end-of-phase (Step 8) and consolidates them into the existing `human_needed` → `{phase_num}-UAT.md` flow in `workflows/execute-phase.md`. The user reviews everything in one batch.
 >
 > **Why this is the default:** every mid-flight halt costs a full executor cold-start (CLAUDE.md, MEMORY.md, STATE.md, plan re-read on respawn) because subagent context is discarded across the pause. A plan with N human-verify checkpoints pays the cold-start cost N+1 times — measured at "tens of thousands of tokens" per round-trip on real projects.
 >

package/get-shit-done/references/planner-human-verify-mode.md

@@ -27,7 +27,7 @@ Instead, fold each would-be verification step into the relevant `auto` task usin
 </task>
 ```
 
-The verifier (Step 8) harvests every `<verify><human-check>` block at end-of-phase and consolidates them into the existing `human_needed` → HUMAN-UAT.md path in `workflows/execute-phase.md`. The user reviews everything in one batch instead of paying a cold-start cost per item.
+The verifier (Step 8) harvests every `<verify><human-check>` block at end-of-phase and consolidates them into the existing `human_needed` → `{phase_num}-UAT.md` path in `workflows/execute-phase.md`. The user reviews everything in one batch instead of paying a cold-start cost per item.
 
 ### `mid-flight` (opt-back-in — pre-#3309 behavior)
 

package/get-shit-done/references/ui-brand.md

@@ -83,10 +83,12 @@ Plans: 3/5 complete
 
 ## Spawning Indicators
 
+**Liveness convention:** Every spawn announcement must carry the canonical phrase `runs in a subagent` inline so users know that silence during a subagent run is expected. Without this, a healthy 1–5 minute agent looks identical to a frozen session. Single spawns use the singular form; parallel spawns use the plural form.
+
 ```
-◆ Spawning researcher...
+◆ Spawning researcher... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
 
-◆ Spawning 4 researchers in parallel...
+◆ Spawning 4 researchers in parallel... (each runs in a subagent — no output until they return, ~1–5 min; expected, not a freeze)
   → Stack research
   → Features research
   → Architecture research

package/get-shit-done/workflows/audit-fix.md

@@ -94,7 +94,7 @@ final output — do not proceed to fixing.
 <step name="fix-loop">
 For each **auto-fixable** finding (up to `--max`, ordered by severity desc):
 
-**a. Spawn executor agent:**
+**a. Spawn executor agent** (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)**:**
 ```
 Agent(
   prompt="Fix finding {ID}: {description}. Files: {file_refs}. Make the minimal change to resolve this specific finding. Do not refactor surrounding code.",

package/get-shit-done/workflows/audit-milestone.md

@@ -67,6 +67,8 @@ With phase context collected:
 
 Extract `MILESTONE_REQ_IDS` from REQUIREMENTS.md traceability table — all REQ-IDs assigned to phases in this milestone.
 
+Print: "Spawning integration checker (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)"
+
 ```
 Agent(
   prompt="Check cross-phase integration and E2E flows.