get-shit-done-cc 1.42.1 → 1.42.2

package/README.md

@@ -144,6 +144,8 @@ GSD is built for frictionless automation. Skip-permissions is how it's intended
 
 Install only the skills you need with `--profile=core` (six core-loop skills), `--profile=standard` (core + phase management), or the default full install. Profiles compose: `--profile=core,audit`. `--minimal` is an alias for `--profile=core`. See **[docs/USER-GUIDE.md](docs/USER-GUIDE.md)** for the full walkthrough, non-interactive install flags for all 15 runtimes, and permissions configuration. See [ADR-0011](docs/adr/0011-skill-surface-budget-module.md) for the profile model and runtime surface control.
 
+Current release highlights are in [docs/RELEASE-v1.42.1.md](docs/RELEASE-v1.42.1.md): package legitimacy checks, safer installer migrations, runtime surface control, custom ship PR sections, reviewer defaults, fallow structural review, and quota-aware execution recovery.
+
 ---
 
 ## Commands
@@ -196,6 +198,8 @@ Key dials:
 
 Optional structural review: set `code_quality.fallow.enabled` to `true` to add a fallow pre-pass to `/gsd-code-review`. GSD writes `.planning/phases/<phase>/FALLOW.json` and surfaces a `Structural Findings (fallow)` section in `REVIEW.md`. Install with `npm install -D fallow@^2.70.0` (or system-wide via `cargo install fallow`; note that the Rust binary's JSON schema must match the documented v2.70+ contract — older versions may produce silent zero-finding output).
 
+Package legitimacy checks are built into the research, planning, and execution path: recommended dependencies get audited, unverified packages require a human checkpoint, and failed installs stop instead of trying similarly named alternatives.
+
 For the full configuration reference — all settings, git branching strategies, per-runtime model overrides, workstream config inheritance, agent skills injection — see **[docs/CONFIGURATION.md](docs/CONFIGURATION.md)**.
 
 ---

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

@@ -726,6 +726,31 @@ function normalizePhaseName(phase) {
   return str;
 }
 
+/**
+ * Render a regex source fragment matching a phase number against ROADMAP/STATE
+ * prose regardless of zero-padding on either side. Skills pass the resolved
+ * padded form (`02.7`), but human-authored ROADMAP prose is conventionally
+ * un-padded (`### Phase 2.7:`); a naive `escapeRegex(phaseNum)` fragment never
+ * matches when the two diverge. Strips leading zeros from the integer part
+ * before re-emitting with a `0*` prefix, so the fragment matches both `2.7`
+ * and `02.7` (and `002.7`).
+ *
+ * Falls back to `escapeRegex(phaseNum)` for non-numeric IDs (custom project
+ * codes like `PROJ-42`) so callers can substitute it unconditionally.
+ *
+ * See #3537 — wired into every ROADMAP-prose regex builder.
+ */
+function phaseMarkdownRegexSource(phaseNum) {
+  const stripped = String(phaseNum).replace(/^[A-Z]{1,6}-(?=\d)/i, '');
+  const match = stripped.match(/^0*(\d+)([A-Z])?((?:\.\d+)*)$/i);
+  if (!match) return escapeRegex(phaseNum);
+
+  const integer = match[1].replace(/^0+/, '') || '0';
+  const letter = match[2] ? escapeRegex(match[2]) : '';
+  const decimal = match[3] ? escapeRegex(match[3]) : '';
+  return `0*${escapeRegex(integer)}${letter}${decimal}`;
+}
+
 function comparePhaseNum(a, b) {
   // Strip optional project_code prefix before comparing (e.g., 'CK-01-name' → '01-name')
   const sa = String(a).replace(/^[A-Z]{1,6}-/, '');
@@ -1071,19 +1096,13 @@ function getRoadmapPhaseInternal(cwd, phaseNum) {
     const roadmapRaw = platformReadSync(roadmapPath);
     if (roadmapRaw === null) throw new Error('missing');
     const content = extractCurrentMilestone(roadmapRaw, cwd);
-    // Strip leading zeros from purely numeric phase numbers so "03" matches "Phase 3:"
-    // in canonical ROADMAP headings. Non-numeric IDs (e.g. "PROJ-42") are kept as-is.
-    const normalized = /^\d+$/.test(String(phaseNum))
-      ? String(phaseNum).replace(/^0+(?=\d)/, '')
-      : String(phaseNum);
-    const escapedPhase = escapeRegex(normalized);
-    // Match both numeric and custom (Phase PROJ-42:) headers.
-    // For purely numeric phases allow optional leading zeros so both "Phase 1:" and
-    // "Phase 01:" are matched regardless of whether the ROADMAP uses padded numbers.
-    const isNumeric = /^\d+$/.test(String(phaseNum));
-    const phasePattern = isNumeric
-      ? new RegExp(`#{2,4}\\s*Phase\\s+0*${escapedPhase}:\\s*([^\\n]+)`, 'i')
-      : new RegExp(`#{2,4}\\s*Phase\\s+${escapedPhase}:\\s*([^\\n]+)`, 'i');
+    // #3537: route through canonical padding-tolerant fragment. The prior
+    // hand-rolled `isNumeric` branch only stripped padding on integer-only
+    // ids and missed decimal padding (`02.7` against `Phase 2.7:` headings).
+    const phasePattern = new RegExp(
+      `#{2,4}\\s*Phase\\s+${phaseMarkdownRegexSource(phaseNum)}:\\s*([^\\n]+)`,
+      'i'
+    );
     const headerMatch = content.match(phasePattern);
     if (!headerMatch) return null;
 
@@ -1880,6 +1899,7 @@ module.exports = {
   isGitIgnored,
   escapeRegex,
   normalizePhaseName,
+  phaseMarkdownRegexSource,
   comparePhaseNum,
   searchPhaseInDir,
   extractPhaseToken,

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

@@ -4,7 +4,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { escapeRegex, loadConfig, normalizePhaseName, comparePhaseNum, findPhaseInternal, getArchivedPhaseDirs, generateSlugInternal, getMilestonePhaseFilter, stripShippedMilestones, extractCurrentMilestone, replaceInCurrentMilestone, toPosixPath, output, error, readSubdirectories, phaseTokenMatches } = require('./core.cjs');
+const { escapeRegex, loadConfig, normalizePhaseName, phaseMarkdownRegexSource, comparePhaseNum, findPhaseInternal, getArchivedPhaseDirs, generateSlugInternal, getMilestonePhaseFilter, stripShippedMilestones, extractCurrentMilestone, replaceInCurrentMilestone, toPosixPath, output, error, readSubdirectories, phaseTokenMatches } = require('./core.cjs');
 const { platformWriteSync, platformReadSync, platformEnsureDir } = require('./shell-command-projection.cjs');
 const { planningDir, withPlanningLock } = require('./planning-workspace.cjs');
 const { extractFrontmatter } = require('./frontmatter.cjs');
@@ -170,8 +170,10 @@ function cmdPhaseNextDecimal(cwd, basePhase, raw) {
     if (fs.existsSync(roadmapPath)) {
       try {
         const roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
+        // #3537: padding-tolerant on both sides — `0*${escapeRegex(...)}`
+        // tolerated extra padding but not missing.
         const phasePattern = new RegExp(
-          `#{2,4}\\s*Phase\\s+0*${escapeRegex(normalized)}\\.(\\d+)\\s*:`, 'gi'
+          `#{2,4}\\s*Phase\\s+${phaseMarkdownRegexSource(normalized)}\\.(\\d+)\\s*:`, 'gi'
         );
         let pm;
         while ((pm = phasePattern.exec(roadmapContent)) !== null) {
@@ -691,13 +693,14 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
     const rawContent = fs.readFileSync(roadmapPath, 'utf-8');
     const content = extractCurrentMilestone(rawContent, cwd);
 
-    // Normalize input then strip leading zeros for flexible matching
+    // Normalize input then route through canonical padding-tolerant fragment
+    // (#3537). The prior hand-rolled `0*${unpadded}` worked for the integer
+    // base but duplicated logic — funnel it through the shared helper.
     const normalizedAfter = normalizePhaseName(afterPhase);
-    const unpadded = normalizedAfter.replace(/^0+/, '');
-    const afterPhaseEscaped = unpadded.replace(/\./g, '\\.');
-    const targetPattern = new RegExp(`#{2,4}\\s*Phase\\s+0*${afterPhaseEscaped}:`, 'i');
+    const afterPhaseEscaped = phaseMarkdownRegexSource(normalizedAfter);
+    const targetPattern = new RegExp(`#{2,4}\\s*Phase\\s+${afterPhaseEscaped}:`, 'i');
     if (!targetPattern.test(content)) {
-      const checklistPattern = new RegExp(`-\\s*\\[[ x]\\]\\s*\\*\\*Phase\\s+0*${afterPhaseEscaped}:`, 'i');
+      const checklistPattern = new RegExp(`-\\s*\\[[ x]\\]\\s*\\*\\*Phase\\s+${afterPhaseEscaped}:`, 'i');
       if (checklistPattern.test(content)) {
         error(`Phase ${afterPhase} exists in roadmap summary but is missing a detail section (### Phase ${afterPhase}: ...).`);
       }
@@ -719,9 +722,11 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
       }
     } catch { /* intentionally empty */ }
 
-    // Also scan ROADMAP.md content (already loaded) for decimal entries
+    // Also scan ROADMAP.md content (already loaded) for decimal entries.
+    // #3537: padding-tolerant fragment so un-padded `Phase 2.7:` is found
+    // when caller passes the padded base `02`.
     const rmPhasePattern = new RegExp(
-      `#{2,4}\\s*Phase\\s+0*${escapeRegex(normalizedBase)}\\.(\\d+)\\s*:`, 'gi'
+      `#{2,4}\\s*Phase\\s+${phaseMarkdownRegexSource(normalizedBase)}\\.(\\d+)\\s*:`, 'gi'
     );
     let rmMatch;
     while ((rmMatch = rmPhasePattern.exec(rawContent)) !== null) {
@@ -745,7 +750,7 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
     const phaseEntry = `\n### Phase ${_decimalPhase}: ${description} (INSERTED)\n\n**Goal:** [Urgent work - to be planned]\n**Requirements**: TBD\n**Depends on:** Phase ${afterPhase}\n**Plans:** 0 plans\n\nPlans:\n- [ ] TBD (run /gsd:plan-phase ${_decimalPhase} to break down)\n`;
 
     // Insert after the target phase section
-    const headerPattern = new RegExp(`(#{2,4}\\s*Phase\\s+0*${afterPhaseEscaped}:[^\\n]*\\n)`, 'i');
+    const headerPattern = new RegExp(`(#{2,4}\\s*Phase\\s+${afterPhaseEscaped}:[^\\n]*\\n)`, 'i');
     const headerMatch = rawContent.match(headerPattern);
     if (!headerMatch) {
       error(`Could not find Phase ${afterPhase} header`);
@@ -1030,14 +1035,16 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
       let roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
 
       // Checkbox: - [ ] Phase N: → - [x] Phase N: (...completed DATE)
+      // #3537: padding-tolerant fragment so the caller-resolved padded id
+      // matches un-padded ROADMAP prose.
+      const phaseEscaped = phaseMarkdownRegexSource(phaseNum);
       const checkboxPattern = new RegExp(
-        `(-\\s*\\[)[ ](\\]\\s*.*Phase\\s+${escapeRegex(phaseNum)}[:\\s][^\\n]*)`,
+        `(-\\s*\\[)[ ](\\]\\s*.*Phase\\s+${phaseEscaped}[:\\s][^\\n]*)`,
         'i'
       );
       roadmapContent = roadmapContent.replace(checkboxPattern, `$1x$2 (completed ${today})`);
 
       // Progress table: update Status to Complete, add date (handles 4 or 5 column tables)
-      const phaseEscaped = escapeRegex(phaseNum);
       const tableRowPattern = new RegExp(
         `^(\\|\\s*${phaseEscaped}\\.?\\s[^|]*(?:\\|[^\\n]*))$`,
         'im'
@@ -1093,8 +1100,10 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
       // Update REQUIREMENTS.md traceability for this phase's requirements
       const reqPath = path.join(planningDir(cwd), 'REQUIREMENTS.md');
       if (fs.existsSync(reqPath)) {
-        // Extract the current phase section from roadmap (scoped to avoid cross-phase matching)
-        const phaseEsc = escapeRegex(phaseNum);
+        // Extract the current phase section from roadmap (scoped to avoid cross-phase matching).
+        // #3537: padding-tolerant fragment so an un-padded `Phase 2.7:` heading
+        // is found when caller resolved to padded `02.7`.
+        const phaseEsc = phaseMarkdownRegexSource(phaseNum);
         const currentMilestoneRoadmap = extractCurrentMilestone(roadmapContent, cwd);
         const phaseSectionMatch = currentMilestoneRoadmap.match(
           new RegExp(`(#{2,4}\\s*Phase\\s+${phaseEsc}[:\\s][\\s\\S]*?)(?=#{2,4}\\s*Phase\\s+|$)`, 'i')

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

@@ -4,7 +4,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { escapeRegex, normalizePhaseName, output, error, findPhaseInternal, stripShippedMilestones, extractCurrentMilestone, replaceInCurrentMilestone, phaseTokenMatches } = require('./core.cjs');
+const { escapeRegex, normalizePhaseName, phaseMarkdownRegexSource, output, error, findPhaseInternal, stripShippedMilestones, extractCurrentMilestone, replaceInCurrentMilestone, phaseTokenMatches } = require('./core.cjs');
 const { platformWriteSync } = require('./shell-command-projection.cjs');
 const { planningPaths, withPlanningLock } = require('./planning-workspace.cjs');
 const scanPhasePlans = require('./plan-scan.cjs');
@@ -52,16 +52,8 @@ function countPhasePlansAndSummaries(phaseDir) {
   };
 }
 
-function phaseMarkdownRegexSource(phaseNum) {
-  const stripped = String(phaseNum).replace(/^[A-Z]{1,6}-(?=\d)/i, '');
-  const match = stripped.match(/^0*(\d+)([A-Z])?((?:\.\d+)*)$/i);
-  if (!match) return escapeRegex(phaseNum);
-
-  const integer = match[1].replace(/^0+/, '') || '0';
-  const letter = match[2] ? escapeRegex(match[2]) : '';
-  const decimal = match[3] ? escapeRegex(match[3]) : '';
-  return `0*${escapeRegex(integer)}${letter}${decimal}`;
-}
+// `phaseMarkdownRegexSource` moved to core.cjs (#3537) so phase.cjs and
+// core.cjs itself can consume it without circular deps. Imported above.
 
 /**
  * Search for a phase header (and its section) within the given content string.
@@ -147,8 +139,9 @@ function cmdRoadmapGetPhase(cwd, phaseNum, raw) {
     const rawContent = fs.readFileSync(roadmapPath, 'utf-8');
     const milestoneContent = extractCurrentMilestone(rawContent, cwd);
 
-    // Escape special regex chars in phase number, handle decimal
-    const escapedPhase = escapeRegex(phaseNum);
+    // #3537: padding-tolerant fragment so callers passing `02.7` still match
+    // un-padded ROADMAP prose (`### Phase 2.7:`).
+    const escapedPhase = phaseMarkdownRegexSource(phaseNum);
 
     // Search the current milestone slice first, then fall back to full roadmap.
     // A malformed_roadmap result (checklist-only) from the milestone should not
@@ -248,8 +241,11 @@ function cmdRoadmapAnalyze(cwd, raw) {
       }
     } catch { /* intentionally empty */ }
 
-    // Check ROADMAP checkbox status
-    const checkboxPattern = new RegExp(`-\\s*\\[(x| )\\]\\s*.*Phase\\s+${escapeRegex(phaseNum)}[:\\s]`, 'i');
+    // Check ROADMAP checkbox status.
+    // #3537: padding-tolerant fragment — the heading discovered above may use
+    // a different padding than the summary-bullet checkbox below it (mixed
+    // padding inside one ROADMAP is legal and seen in real projects).
+    const checkboxPattern = new RegExp(`-\\s*\\[(x| )\\]\\s*.*Phase\\s+${phaseMarkdownRegexSource(phaseNum)}[:\\s]`, 'i');
     const checkboxMatch = content.match(checkboxPattern);
     const roadmapComplete = checkboxMatch ? checkboxMatch[1] === 'x' : false;
 
@@ -511,8 +507,10 @@ function cmdRoadmapAnnotateDependencies(cwd, phaseNum, raw) {
   withPlanningLock(cwd, () => {
     let content = fs.readFileSync(roadmapPath, 'utf-8');
 
-    // Find the phase section
-    const phaseEscaped = escapeRegex(phaseNum);
+    // Find the phase section.
+    // #3537: padding-tolerant fragment so the caller's resolved padded id
+    // matches un-padded ROADMAP headings.
+    const phaseEscaped = phaseMarkdownRegexSource(phaseNum);
     const phaseHeaderPattern = new RegExp(`(#{2,4}\\s*Phase\\s+${phaseEscaped}:[^\\n]*)`, 'i');
     const phaseMatch = content.match(phaseHeaderPattern);
     if (!phaseMatch) return;

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

@@ -1,122 +1,12 @@
 'use strict';
 
 /**
- * STATE.md Document Module
+ * STATE.md Document Module — CJS adapter.
  *
- * Pure transforms for STATE.md text. This module does not read the filesystem
- * and does not own persistence or locking.
+ * The implementation is generated from sdk/src/query/state-document.ts and
+ * lives in state-document.generated.cjs. This file is a thin re-export so
+ * that existing call sites (state.cjs, workstream-inventory.cjs, init.cjs,
+ * and tests) can continue to require('./state-document') unchanged.
  */
 
-function escapeRegex(str) {
-  return String(str).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
-function stateExtractField(content, fieldName) {
-  const escaped = escapeRegex(fieldName);
-  const boldPattern = new RegExp(`\\*\\*${escaped}:\\*\\*[ \\t]*(.+)`, 'i');
-  const boldMatch = content.match(boldPattern);
-  if (boldMatch) return boldMatch[1].trim();
-  const plainPattern = new RegExp(`^${escaped}:[ \\t]*(.+)`, 'im');
-  const plainMatch = content.match(plainPattern);
-  return plainMatch ? plainMatch[1].trim() : null;
-}
-
-function stateReplaceField(content, fieldName, newValue) {
-  const escaped = escapeRegex(fieldName);
-  const boldPattern = new RegExp(`(\\*\\*${escaped}:\\*\\*\\s*)(.*)`, 'i');
-  if (boldPattern.test(content)) {
-    return content.replace(boldPattern, (_match, prefix) => `${prefix}${newValue}`);
-  }
-  const plainPattern = new RegExp(`(^${escaped}:\\s*)(.*)`, 'im');
-  if (plainPattern.test(content)) {
-    return content.replace(plainPattern, (_match, prefix) => `${prefix}${newValue}`);
-  }
-  return null;
-}
-
-function stateReplaceFieldWithFallback(content, primary, fallback, value) {
-  let result = stateReplaceField(content, primary, value);
-  if (result) return result;
-  if (fallback) {
-    result = stateReplaceField(content, fallback, value);
-    if (result) return result;
-  }
-  return content;
-}
-
-function normalizeStateStatus(status, pausedAt) {
-  let normalizedStatus = status || 'unknown';
-  const statusLower = (status || '').toLowerCase();
-  if (statusLower.includes('paused') || statusLower.includes('stopped') || pausedAt) {
-    normalizedStatus = 'paused';
-  } else if (statusLower.includes('executing') || statusLower.includes('in progress')) {
-    normalizedStatus = 'executing';
-  } else if (statusLower.includes('planning') || statusLower.includes('ready to plan')) {
-    normalizedStatus = 'planning';
-  } else if (statusLower.includes('discussing')) {
-    normalizedStatus = 'discussing';
-  } else if (statusLower.includes('verif')) {
-    normalizedStatus = 'verifying';
-  } else if (statusLower.includes('complete') || statusLower.includes('done')) {
-    normalizedStatus = 'completed';
-  } else if (statusLower.includes('ready to execute')) {
-    normalizedStatus = 'executing';
-  }
-  return normalizedStatus;
-}
-
-function computeProgressPercent(completedPlans, totalPlans, completedPhases, totalPhases) {
-  const hasPlanData = totalPlans !== null && totalPlans > 0 && completedPlans !== null;
-  const hasPhaseData = totalPhases !== null && totalPhases > 0 && completedPhases !== null;
-
-  if (!hasPlanData && !hasPhaseData) return null;
-
-  const planFraction = hasPlanData ? completedPlans / totalPlans : 1;
-  const phaseFraction = hasPhaseData ? completedPhases / totalPhases : 1;
-
-  return Math.min(100, Math.round(Math.min(planFraction, phaseFraction) * 100));
-}
-
-function toFiniteNumber(value) {
-  const number = Number(value);
-  return Number.isFinite(number) ? number : null;
-}
-
-function existingProgressExceedsDerived(existingProgress, derivedProgress, key) {
-  const existing = toFiniteNumber(existingProgress[key]);
-  const derived = toFiniteNumber(derivedProgress[key]);
-  return existing !== null && derived !== null && existing > derived;
-}
-
-function shouldPreserveExistingProgress(existingProgress, derivedProgress) {
-  if (!existingProgress || typeof existingProgress !== 'object') return false;
-  if (!derivedProgress || typeof derivedProgress !== 'object') return false;
-
-  return (
-    existingProgressExceedsDerived(existingProgress, derivedProgress, 'total_phases') ||
-    existingProgressExceedsDerived(existingProgress, derivedProgress, 'completed_phases') ||
-    existingProgressExceedsDerived(existingProgress, derivedProgress, 'total_plans') ||
-    existingProgressExceedsDerived(existingProgress, derivedProgress, 'completed_plans')
-  );
-}
-
-function normalizeProgressNumbers(progress) {
-  if (!progress || typeof progress !== 'object') return progress;
-
-  const normalized = { ...progress };
-  for (const key of ['total_phases', 'completed_phases', 'total_plans', 'completed_plans', 'percent']) {
-    const number = toFiniteNumber(normalized[key]);
-    if (number !== null) normalized[key] = number;
-  }
-  return normalized;
-}
-
-module.exports = {
-  computeProgressPercent,
-  normalizeProgressNumbers,
-  normalizeStateStatus,
-  shouldPreserveExistingProgress,
-  stateExtractField,
-  stateReplaceField,
-  stateReplaceFieldWithFallback,
-};
+module.exports = require('./state-document.generated.cjs');

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

@@ -0,0 +1,127 @@
+'use strict';
+
+/**
+ * GENERATED FILE — DO NOT EDIT.
+ *
+ * Source: sdk/src/query/state-document.ts
+ * Regenerate: cd sdk && npm run gen:state-document
+ *
+ * STATE.md Document Module — pure transforms for STATE.md text.
+ * This module does not read the filesystem and does not own persistence or locking.
+ */
+
+// Internal helpers
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function toFiniteNumber(value) {
+    const number = Number(value);
+    return Number.isFinite(number) ? number : null;
+}
+
+function existingProgressExceedsDerived(existingProgress, derivedProgress, key) {
+    const existing = toFiniteNumber(existingProgress[key]);
+    const derived = toFiniteNumber(derivedProgress[key]);
+    return existing !== null && derived !== null && existing > derived;
+}
+
+function stateExtractField(content, fieldName) {
+    const escaped = escapeRegex(fieldName);
+    const boldPattern = new RegExp(`\\*\\*${escaped}:\\*\\*[ \\t]*(.+)`, 'i');
+    const boldMatch = content.match(boldPattern);
+    if (boldMatch)
+        return boldMatch[1].trim();
+    const plainPattern = new RegExp(`^${escaped}:[ \\t]*(.+)`, 'im');
+    const plainMatch = content.match(plainPattern);
+    return plainMatch ? plainMatch[1].trim() : null;
+}
+
+function stateReplaceField(content, fieldName, newValue) {
+    const escaped = escapeRegex(fieldName);
+    const boldPattern = new RegExp(`(\\*\\*${escaped}:\\*\\*\\s*)(.*)`, 'i');
+    if (boldPattern.test(content)) {
+        return content.replace(boldPattern, (_match, prefix) => `${prefix}${newValue}`);
+    }
+    const plainPattern = new RegExp(`(^${escaped}:\\s*)(.*)`, 'im');
+    if (plainPattern.test(content)) {
+        return content.replace(plainPattern, (_match, prefix) => `${prefix}${newValue}`);
+    }
+    return null;
+}
+
+function stateReplaceFieldWithFallback(content, primary, fallback, value) {
+    let result = stateReplaceField(content, primary, value);
+    if (result)
+        return result;
+    if (fallback) {
+        result = stateReplaceField(content, fallback, value);
+        if (result)
+            return result;
+    }
+    return content;
+}
+
+function normalizeStateStatus(status, pausedAt) {
+    let normalizedStatus = status || 'unknown';
+    const statusLower = (status || '').toLowerCase();
+    if (statusLower.includes('paused') || statusLower.includes('stopped') || pausedAt) {
+        normalizedStatus = 'paused';
+    }
+    else if (statusLower.includes('executing') || statusLower.includes('in progress')) {
+        normalizedStatus = 'executing';
+    }
+    else if (statusLower.includes('planning') || statusLower.includes('ready to plan')) {
+        normalizedStatus = 'planning';
+    }
+    else if (statusLower.includes('discussing')) {
+        normalizedStatus = 'discussing';
+    }
+    else if (statusLower.includes('verif')) {
+        normalizedStatus = 'verifying';
+    }
+    else if (statusLower.includes('complete') || statusLower.includes('done')) {
+        normalizedStatus = 'completed';
+    }
+    else if (statusLower.includes('ready to execute')) {
+        normalizedStatus = 'executing';
+    }
+    return normalizedStatus;
+}
+
+function computeProgressPercent(completedPlans, totalPlans, completedPhases, totalPhases) {
+    const hasPlanData = totalPlans !== null && totalPlans > 0 && completedPlans !== null;
+    const hasPhaseData = totalPhases !== null && totalPhases > 0 && completedPhases !== null;
+    if (!hasPlanData && !hasPhaseData)
+        return null;
+    const planFraction = hasPlanData ? completedPlans / totalPlans : 1;
+    const phaseFraction = hasPhaseData ? completedPhases / totalPhases : 1;
+    return Math.min(100, Math.round(Math.min(planFraction, phaseFraction) * 100));
+}
+
+function shouldPreserveExistingProgress(existingProgress, derivedProgress) {
+    if (!existingProgress || typeof existingProgress !== 'object')
+        return false;
+    if (!derivedProgress || typeof derivedProgress !== 'object')
+        return false;
+    const existing = existingProgress;
+    const derived = derivedProgress;
+    return (existingProgressExceedsDerived(existing, derived, 'total_phases') ||
+        existingProgressExceedsDerived(existing, derived, 'completed_phases') ||
+        existingProgressExceedsDerived(existing, derived, 'total_plans') ||
+        existingProgressExceedsDerived(existing, derived, 'completed_plans'));
+}
+
+function normalizeProgressNumbers(progress) {
+    if (!progress || typeof progress !== 'object')
+        return progress;
+    const normalized = { ...progress };
+    for (const key of ['total_phases', 'completed_phases', 'total_plans', 'completed_plans', 'percent']) {
+        const number = toFiniteNumber(normalized[key]);
+        if (number !== null)
+            normalized[key] = number;
+    }
+    return normalized;
+}
+
+module.exports = { stateExtractField, stateReplaceField, stateReplaceFieldWithFallback, normalizeStateStatus, computeProgressPercent, shouldPreserveExistingProgress, normalizeProgressNumbers };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "get-shit-done-cc",
-  "version": "1.42.1",
+  "version": "1.42.2",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code, OpenCode, Gemini and Codex by TÂCHES.",
   "bin": {
     "get-shit-done-cc": "bin/install.js",
@@ -62,6 +62,7 @@
     "build:hooks": "node scripts/build-hooks.js",
     "build:sdk": "cd sdk && npm ci && npm run build",
     "check:alias-drift": "cd sdk && npm run check:alias-drift",
+    "check:state-document-fresh": "cd sdk && npm run check:state-document-fresh",
     "prepublishOnly": "npm run build:hooks && npm run build:sdk",
     "pretest": "npm run build:sdk && npm run lint:skill-deps",
     "pretest:coverage": "npm run build:sdk",

package/sdk/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@gsd-build/sdk",
-  "version": "1.42.1",
+  "version": "1.42.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@gsd-build/sdk",
-      "version": "1.42.1",
+      "version": "1.42.2",
       "license": "MIT",
       "dependencies": {
         "@anthropic-ai/claude-agent-sdk": "^0.2.84",
@@ -18,6 +18,7 @@
       "devDependencies": {
         "@types/node": "^22.0.0",
         "@types/ws": "^8.18.1",
+        "tsx": "^4.22.0",
         "typescript": "^5.7.0",
         "vitest": "^3.1.1"
       },
@@ -1754,6 +1755,509 @@
         "node": ">=14.0.0"
       }
     },
+    "node_modules/tsx": {
+      "version": "4.22.0",
+      "resolved": "https://registry.npmjs.org/tsx/-/tsx-4.22.0.tgz",
+      "integrity": "sha512-8ccZMPD69s1AbKXx0C5ddTNZfNjwV04iIKgjZmKfKxMynEtSYcK0Lh7iQFh53fI5Yu4pb9usgAiqyPmEONaALg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "esbuild": "~0.28.0"
+      },
+      "bin": {
+        "tsx": "dist/cli.mjs"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/aix-ppc64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.0.tgz",
+      "integrity": "sha512-lhRUCeuOyJQURhTxl4WkpFTjIsbDayJHih5kZC1giwE+MhIzAb7mEsQMqMf18rHLsrb5qI1tafG20mLxEWcWlA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/android-arm": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.0.tgz",
+      "integrity": "sha512-wqh0ByljabXLKHeWXYLqoJ5jKC4XBaw6Hk08OfMrCRd2nP2ZQ5eleDZC41XHyCNgktBGYMbqnrJKq/K/lzPMSQ==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/android-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.0.tgz",
+      "integrity": "sha512-+WzIXQOSaGs33tLEgYPYe/yQHf0WTU0X42Jca3y8NWMbUVhp7rUnw+vAsRC/QiDrdD31IszMrZy+qwPOPjd+rw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/android-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.0.tgz",
+      "integrity": "sha512-+VJggoaKhk2VNNqVL7f6S189UzShHC/mR9EE8rDdSkdpN0KflSwWY/gWjDrNxxisg8Fp1ZCD9jLMo4m0OUfeUA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/darwin-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.0.tgz",
+      "integrity": "sha512-0T+A9WZm+bZ84nZBtk1ckYsOvyA3x7e2Acj1KdVfV4/2tdG4fzUp91YHx+GArWLtwqp77pBXVCPn2We7Letr0Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/darwin-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.0.tgz",
+      "integrity": "sha512-fyzLm/DLDl/84OCfp2f/XQ4flmORsjU7VKt8HLjvIXChJoFFOIL6pLJPH4Yhd1n1gGFF9mPwtlN5Wf82DZs+LQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.0.tgz",
+      "integrity": "sha512-l9GeW5UZBT9k9brBYI+0WDffcRxgHQD8ShN2Ur4xWq/NFzUKm3k5lsH4PdaRgb2w7mI9u61nr2gI2mLI27Nh3Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/freebsd-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.0.tgz",
+      "integrity": "sha512-BXoQai/A0wPO6Es3yFJ7APCiKGc1tdAEOgeTNy3SsB491S3aHn4S4r3e976eUnPdU+NbdtmBuLncYir2tMU9Nw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/linux-arm": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.0.tgz",
+      "integrity": "sha512-CjaaREJagqJp7iTaNQjjidaNbCKYcd4IDkzbwwxtSvjI7NZm79qiHc8HqciMddQ6CKvJT6aBd8lO9kN/ZudLlw==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/linux-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.0.tgz",
+      "integrity": "sha512-RVyzfb3FWsGA55n6WY0MEIEPURL1FcbhFE6BffZEMEekfCzCIMtB5yyDcFnVbTnwk+CLAgTujmV/Lgvih56W+A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/linux-ia32": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.0.tgz",
+      "integrity": "sha512-KBnSTt1kxl9x70q+ydterVdl+Cn0H18ngRMRCEQfrbqdUuntQQ0LoMZv47uB97NljZFzY6HcfqEZ2SAyIUTQBQ==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/linux-loong64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.0.tgz",
+      "integrity": "sha512-zpSlUce1mnxzgBADvxKXX5sl8aYQHo2ezvMNI8I0lbblJtp8V4odlm3Yzlj7gPyt3T8ReksE6bK+pT3WD+aJRg==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/linux-mips64el": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.0.tgz",
+      "integrity": "sha512-2jIfP6mmjkdmeTlsX/9vmdmhBmKADrWqN7zcdtHIeNSCH1SqIoNI63cYsjQR8J+wGa4Y5izRcSHSm8K3QWmk3w==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/linux-ppc64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.0.tgz",
+      "integrity": "sha512-bc0FE9wWeC0WBm49IQMPSPILRocGTQt3j5KPCA8os6VprfuJ7KD+5PzESSrJ6GmPIPJK965ZJHTUlSA6GNYEhg==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/linux-riscv64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.0.tgz",
+      "integrity": "sha512-SQPZOwoTTT/HXFXQJG/vBX8sOFagGqvZyXcgLA3NhIqcBv1BJU1d46c0rGcrij2B56Z2rNiSLaZOYW5cUk7yLQ==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/linux-s390x": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.0.tgz",
+      "integrity": "sha512-SCfR0HN8CEEjnYnySJTd2cw0k9OHB/YFzt5zgJEwa+wL/T/raGWYMBqwDNAC6dqFKmJYZoQBRfHjgwLHGSrn3Q==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/linux-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.0.tgz",
+      "integrity": "sha512-us0dSb9iFxIi8srnpl931Nvs65it/Jd2a2K3qs7fz2WfGPHqzfzZTfec7oxZJRNPXPnNYZtanmRc4AL/JwVzHQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.0.tgz",
+      "integrity": "sha512-CR/RYotgtCKwtftMwJlUU7xCVNg3lMYZ0RzTmAHSfLCXw3NtZtNpswLEj/Kkf6kEL3Gw+BpOekRX0BYCtklhUw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/netbsd-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.0.tgz",
+      "integrity": "sha512-nU1yhmYutL+fQ71Kxnhg8uEOdC0pwEW9entHykTgEbna2pw2dkbFSMeqjjyHZoCmt8SBkOSvV+yNmm94aUrrqw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.0.tgz",
+      "integrity": "sha512-cXb5vApOsRsxsEl4mcZ1XY3D4DzcoMxR/nnc4IyqYs0rTI8ZKmW6kyyg+11Z8yvgMfAEldKzP7AdP64HnSC/6g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/openbsd-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.0.tgz",
+      "integrity": "sha512-8wZM2qqtv9UP3mzy7HiGYNH/zjTA355mpeuA+859TyR+e+Tc08IHYpLJuMsfpDJwoLo1ikIJI8jC3GFjnRClzA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/openharmony-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.0.tgz",
+      "integrity": "sha512-FLGfyizszcef5C3YtoyQDACyg95+dndv79i2EekILBofh5wpCa1KuBqOWKrEHZg3zrL3t5ouE5jgr94vA+Wb2w==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/sunos-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.0.tgz",
+      "integrity": "sha512-1ZgjUoEdHZZl/YlV76TSCz9Hqj9h9YmMGAgAPYd+q4SicWNX3G5GCyx9uhQWSLcbvPW8Ni7lj4gDa1T40akdlw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/win32-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.0.tgz",
+      "integrity": "sha512-Q9StnDmQ/enxnpxCCLSg0oo4+34B9TdXpuyPeTedN/6+iXBJ4J+zwfQI28u/Jl40nOYAxGoNi7mFP40RUtkmUA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/win32-ia32": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.0.tgz",
+      "integrity": "sha512-zF3ag/gfiCe6U2iczcRzSYJKH1DCI+ByzSENHlM2FcDbEeo5Zd2C86Aq0tKUYAJJ1obRP84ymxIAksZUcdztHA==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/win32-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.0.tgz",
+      "integrity": "sha512-pEl1bO9mfAmIC+tW5btTmrKaujg3zGtUmWNdCw/xs70FBjwAL3o9OEKNHvNmnyylD6ubxUERiEhdsL0xBQ9efw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/esbuild": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.0.tgz",
+      "integrity": "sha512-sNR9MHpXSUV/XB4zmsFKN+QgVG82Cc7+/aaxJ8Adi8hyOac+EXptIp45QBPaVyX3N70664wRbTcLTOemCAnyqw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.28.0",
+        "@esbuild/android-arm": "0.28.0",
+        "@esbuild/android-arm64": "0.28.0",
+        "@esbuild/android-x64": "0.28.0",
+        "@esbuild/darwin-arm64": "0.28.0",
+        "@esbuild/darwin-x64": "0.28.0",
+        "@esbuild/freebsd-arm64": "0.28.0",
+        "@esbuild/freebsd-x64": "0.28.0",
+        "@esbuild/linux-arm": "0.28.0",
+        "@esbuild/linux-arm64": "0.28.0",
+        "@esbuild/linux-ia32": "0.28.0",
+        "@esbuild/linux-loong64": "0.28.0",
+        "@esbuild/linux-mips64el": "0.28.0",
+        "@esbuild/linux-ppc64": "0.28.0",
+        "@esbuild/linux-riscv64": "0.28.0",
+        "@esbuild/linux-s390x": "0.28.0",
+        "@esbuild/linux-x64": "0.28.0",
+        "@esbuild/netbsd-arm64": "0.28.0",
+        "@esbuild/netbsd-x64": "0.28.0",
+        "@esbuild/openbsd-arm64": "0.28.0",
+        "@esbuild/openbsd-x64": "0.28.0",
+        "@esbuild/openharmony-arm64": "0.28.0",
+        "@esbuild/sunos-x64": "0.28.0",
+        "@esbuild/win32-arm64": "0.28.0",
+        "@esbuild/win32-ia32": "0.28.0",
+        "@esbuild/win32-x64": "0.28.0"
+      }
+    },
     "node_modules/typescript": {
       "version": "5.9.3",
       "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",

package/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsd-build/sdk",
-  "version": "1.42.1",
+  "version": "1.42.2",
   "description": "GSD SDK — programmatic interface for running GSD plans via the Agent SDK",
   "type": "module",
   "main": "dist/index.js",
@@ -36,6 +36,8 @@
   "scripts": {
     "build": "tsc",
     "check:alias-drift": "npm run build && node scripts/check-command-aliases-fresh.mjs",
+    "gen:state-document": "npm run build && npx tsx scripts/gen-state-document.ts",
+    "check:state-document-fresh": "npm run build && node scripts/check-state-document-fresh.mjs",
     "prepublishOnly": "rm -rf dist && tsc && chmod +x dist/cli.js",
     "test": "vitest run",
     "test:unit": "vitest run --project unit",
@@ -48,6 +50,7 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "@types/ws": "^8.18.1",
+    "tsx": "^4.22.0",
     "typescript": "^5.7.0",
     "vitest": "^3.1.1"
   }

package/sdk/src/query/state-document.test.ts

@@ -0,0 +1,197 @@
+/**
+ * Unit tests for STATE.md Document Module — stateExtractField.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  stateExtractField,
+  stateReplaceField,
+  stateReplaceFieldWithFallback,
+  normalizeStateStatus,
+  computeProgressPercent,
+  shouldPreserveExistingProgress,
+  normalizeProgressNumbers,
+} from './state-document.js';
+
+describe('stateExtractField', () => {
+  it('extracts value from bold pattern', () => {
+    const content = 'Some content\n**FieldName:** the value\nMore content';
+    expect(stateExtractField(content, 'FieldName')).toBe('the value');
+  });
+
+  it('extracts value from plain pattern', () => {
+    const content = 'Some content\nFieldName: the value\nMore content';
+    expect(stateExtractField(content, 'FieldName')).toBe('the value');
+  });
+
+  it('returns null when field is missing', () => {
+    const content = 'Some content\nOtherField: something\nMore content';
+    expect(stateExtractField(content, 'FieldName')).toBeNull();
+  });
+});
+
+describe('stateReplaceField', () => {
+  it('replaces value in bold pattern', () => {
+    const content = 'Some content\n**Status:** old value\nMore content';
+    const result = stateReplaceField(content, 'Status', 'new value');
+    expect(result).toBe('Some content\n**Status:** new value\nMore content');
+  });
+
+  it('replaces value in plain pattern', () => {
+    const content = 'Some content\nStatus: old value\nMore content';
+    const result = stateReplaceField(content, 'Status', 'new value');
+    expect(result).toBe('Some content\nStatus: new value\nMore content');
+  });
+
+  it('returns null when field is missing', () => {
+    const content = 'Some content\nOtherField: something\nMore content';
+    const result = stateReplaceField(content, 'Status', 'new value');
+    expect(result).toBeNull();
+  });
+});
+
+describe('stateReplaceFieldWithFallback', () => {
+  it('replaces primary field when it exists', () => {
+    const content = 'Status: old\nState: backup';
+    const result = stateReplaceFieldWithFallback(content, 'Status', 'State', 'new');
+    expect(result).toBe('Status: new\nState: backup');
+  });
+
+  it('replaces fallback field when primary is missing', () => {
+    const content = 'Other: something\nState: backup';
+    const result = stateReplaceFieldWithFallback(content, 'Status', 'State', 'new');
+    expect(result).toBe('Other: something\nState: new');
+  });
+
+  it('returns content unchanged when neither field exists', () => {
+    const content = 'Other: something\nAnother: value';
+    const result = stateReplaceFieldWithFallback(content, 'Status', 'State', 'new');
+    expect(result).toBe(content);
+  });
+});
+
+describe('normalizeStateStatus', () => {
+  it('returns paused for status containing "paused"', () => {
+    expect(normalizeStateStatus('paused')).toBe('paused');
+  });
+
+  it('returns paused for status containing "stopped"', () => {
+    expect(normalizeStateStatus('stopped')).toBe('paused');
+  });
+
+  it('returns paused when non-null pausedAt is provided', () => {
+    expect(normalizeStateStatus('active', '2024-01-01')).toBe('paused');
+  });
+
+  it('returns executing for status containing "executing"', () => {
+    expect(normalizeStateStatus('executing')).toBe('executing');
+  });
+
+  it('returns executing for status "in progress"', () => {
+    expect(normalizeStateStatus('in progress')).toBe('executing');
+  });
+
+  it('returns executing for status "ready to execute"', () => {
+    expect(normalizeStateStatus('ready to execute')).toBe('executing');
+  });
+
+  it('returns planning for status containing "planning"', () => {
+    expect(normalizeStateStatus('planning')).toBe('planning');
+  });
+
+  it('returns discussing for status containing "discussing"', () => {
+    expect(normalizeStateStatus('discussing')).toBe('discussing');
+  });
+
+  it('returns verifying for status containing "verif"', () => {
+    expect(normalizeStateStatus('verifying')).toBe('verifying');
+  });
+
+  it('returns completed for status containing "complete"', () => {
+    expect(normalizeStateStatus('completed')).toBe('completed');
+  });
+
+  it('returns completed for status containing "done"', () => {
+    expect(normalizeStateStatus('done')).toBe('completed');
+  });
+
+  it('returns unknown for unrecognized status', () => {
+    expect(normalizeStateStatus('something-else')).toBe('something-else');
+  });
+
+  it('returns unknown for null status', () => {
+    expect(normalizeStateStatus(null)).toBe('unknown');
+  });
+});
+
+describe('computeProgressPercent', () => {
+  it('uses only plans data when phases data is absent', () => {
+    expect(computeProgressPercent(3, 10, null, null)).toBe(30);
+  });
+
+  it('uses only phases data when plans data is absent', () => {
+    expect(computeProgressPercent(null, null, 2, 4)).toBe(50);
+  });
+
+  it('uses minimum fraction when both plans and phases data are present', () => {
+    // plans: 8/10 = 80%, phases: 3/10 = 30% → min = 30%
+    expect(computeProgressPercent(8, 10, 3, 10)).toBe(30);
+  });
+
+  it('returns null when neither plans nor phases data is present', () => {
+    expect(computeProgressPercent(null, null, null, null)).toBeNull();
+  });
+
+  it('returns null when total is 0 (treated as no data)', () => {
+    expect(computeProgressPercent(0, 0, null, null)).toBeNull();
+  });
+});
+
+describe('shouldPreserveExistingProgress', () => {
+  it('returns true when existing total_phases exceeds derived', () => {
+    expect(shouldPreserveExistingProgress({ total_phases: 10 }, { total_phases: 5 })).toBe(true);
+  });
+
+  it('returns false when derived exceeds existing', () => {
+    expect(shouldPreserveExistingProgress({ total_phases: 5 }, { total_phases: 10 })).toBe(false);
+  });
+
+  it('returns false when existingProgress is not an object', () => {
+    expect(shouldPreserveExistingProgress(null, { total_phases: 5 })).toBe(false);
+  });
+
+  it('returns false when both are null', () => {
+    expect(shouldPreserveExistingProgress(null, null)).toBe(false);
+  });
+});
+
+describe('normalizeProgressNumbers', () => {
+  it('coerces all five tracked keys to numbers', () => {
+    const input = {
+      total_phases: '10',
+      completed_phases: '3',
+      total_plans: '5',
+      completed_plans: '2',
+      percent: '60',
+    };
+    expect(normalizeProgressNumbers(input)).toEqual({
+      total_phases: 10,
+      completed_phases: 3,
+      total_plans: 5,
+      completed_plans: 2,
+      percent: 60,
+    });
+  });
+
+  it('returns non-object input unchanged', () => {
+    expect(normalizeProgressNumbers(null)).toBeNull();
+    expect(normalizeProgressNumbers('string')).toBe('string');
+  });
+
+  it('preserves extra keys untouched', () => {
+    const input = { total_phases: '4', extra_key: 'hello' };
+    const result = normalizeProgressNumbers(input) as Record<string, unknown>;
+    expect(result.total_phases).toBe(4);
+    expect(result.extra_key).toBe('hello');
+  });
+});