gsdd-cli 0.18.0 → 0.18.2

package/README.md

@@ -12,7 +12,7 @@ npx gsdd-cli init
 ```
 
 **Directly validated today:** Claude Code, Codex CLI, and OpenCode.
-**Qualified support:** Cursor, Copilot, and Gemini CLI support the same core workflow through the shared `.agents/skills/` surface; this release does not claim the same runtime proof or ergonomics.
+**Qualified support:** Cursor, Copilot, and Gemini CLI support the same core workflow through the shared `.agents/skills/` surface; they do not carry the same runtime proof or ergonomics.
 
 </div>
 
@@ -63,7 +63,7 @@ Verification is a separate workflow with a separate context window, not a checkb
 <details>
 <summary>How it works</summary>
 
-Invariant suites (I-series), guard suites (G-series), and scenario suites (S-series) run on every change. Each assertion includes a `FIX:` instruction so failures are actionable. 52 documented design decisions in `distilled/DESIGN.md` record the rationale with evidence trails.
+Invariant suites (I-series), guard suites (G-series), and scenario suites (S-series) run on every change. Each assertion includes a `FIX:` instruction so failures are actionable. 58 documented design decisions in `distilled/DESIGN.md` record the rationale with evidence trails.
 
 </details>
 
@@ -102,13 +102,14 @@ In a terminal, `gsdd init` now opens a guided install wizard:
 - Step 2: decide separately whether repo-wide `AGENTS.md` governance is worth installing
 - Step 3: configure planning defaults in the same guided flow
 
-Portable `.agents/skills/gsdd-*` skills are always generated. The wizard controls extra native adapters and optional governance, not the portable baseline.
-When those generated surfaces exist locally, `gsdd health` checks them against current render output instead of asking you to trust manual review.
+Portable `.agents/skills/gsdd-*` skills are always generated. The wizard controls extra native adapters and optional governance, not the portable baseline.
+When those generated surfaces exist locally, `gsdd health` checks them against current render output instead of asking you to trust manual review.
+`init` generates a local `.planning/bin/gsdd*` helper surface. Workflow-embedded helper commands still use `node .planning/bin/gsdd.mjs ...` as the portable contract, so execution-time lifecycle helpers do not depend on a global `gsdd` binary after init.
 
 ### Launch Proof Status
 
 - **Directly validated:** Claude Code, Codex CLI, and OpenCode have recorded `plan -> execute -> verify` evidence for the core lifecycle.
-- **Qualified support:** Cursor, Copilot, and Gemini CLI support the same core workflow through the shared `.agents/skills/` surface; this release does not claim the same runtime proof or ergonomics.
+- **Qualified support:** Cursor, Copilot, and Gemini CLI support the same core workflow through the shared `.agents/skills/` surface; they do not carry the same runtime proof or ergonomics.
 - **Runtime-surface freshness:** Installed generated skills and native adapters are renderer-checked locally; repair stays deterministic through `npx gsdd-cli update`.
 
 Start with the public proof pack:
@@ -504,7 +505,7 @@ For detailed troubleshooting and recovery procedures, see the [User Guide](docs/
 
 ## Design Decisions
 
-This repo records 52 documented design decisions relative to GSD, each with evidence from source files and external research. See [`distilled/DESIGN.md`](distilled/DESIGN.md) for the full rationale.
+This repo records 58 documented design decisions relative to GSD, each with evidence from source files and external research. See [`distilled/DESIGN.md`](distilled/DESIGN.md) for the full rationale.
 
 Key choices:
 - **4-file codebase standard** — drop state that rots (STRUCTURE, INTEGRATIONS, TESTING), keep rules that don't

package/bin/gsdd.mjs

@@ -2,7 +2,7 @@
 
 // gsdd - Workspine CLI
 
-import { realpathSync } from 'fs';
+import { realpathSync, readFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { createAdapterRegistry } from './adapters/index.mjs';
@@ -21,11 +21,12 @@ import { cmdFileOp } from './lib/file-ops.mjs';
 import { createCmdHealth } from './lib/health.mjs';
 import { cmdLifecyclePreflight } from './lib/lifecycle-preflight.mjs';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const DISTILLED_DIR = join(__dirname, '..', 'distilled');
-const AGENTS_DIR = join(__dirname, '..', 'agents');
-const CWD = process.cwd();
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const DISTILLED_DIR = join(__dirname, '..', 'distilled');
+const AGENTS_DIR = join(__dirname, '..', 'agents');
+const PACKAGE_JSON = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
+const CWD = process.cwd();
 const IS_MAIN = process.argv[1]
   ? realpathSync(process.argv[1]) === realpathSync(__filename)
   : false;
@@ -60,14 +61,16 @@ const WORKFLOWS = [
 
 const FRAMEWORK_VERSION = 'v1.4';
 
-function createCliContext(cwd = process.cwd()) {
-  return {
-    cwd,
-    planningDir: join(cwd, '.planning'),
-    distilledDir: DISTILLED_DIR,
-    agentsDir: AGENTS_DIR,
-    workflows: WORKFLOWS,
-    frameworkVersion: FRAMEWORK_VERSION,
+function createCliContext(cwd = process.cwd()) {
+  return {
+    cwd,
+    planningDir: join(cwd, '.planning'),
+    distilledDir: DISTILLED_DIR,
+    agentsDir: AGENTS_DIR,
+    packageName: PACKAGE_JSON.name,
+    packageVersion: PACKAGE_JSON.version,
+    workflows: WORKFLOWS,
+    frameworkVersion: FRAMEWORK_VERSION,
     adapters: createAdapterRegistry({
       cwd,
       workflows: WORKFLOWS,

package/bin/lib/health-truth.mjs

@@ -87,14 +87,14 @@ export function runTruthChecks(planningDir, frameworkDir, actualCheckIds, option
     }
   }
 
-  if (options.runtimeFreshnessReport?.issueCount > 0) {
-    warnings.push({
-      id: 'W11',
-      severity: 'WARN',
-      message: `Installed generated runtime surfaces drift from current render output (${summarizeRuntimeFreshnessIssues(options.runtimeFreshnessReport)})`,
-      fix: getRuntimeFreshnessRepairGuidance(options.runtimeFreshnessReport),
-    });
-  }
+  if (options.runtimeFreshnessReport?.issueCount > 0) {
+    warnings.push({
+      id: 'W11',
+      severity: 'WARN',
+      message: `Installed generated runtime and workflow-helper surfaces drift from current render output (${summarizeRuntimeFreshnessIssues(options.runtimeFreshnessReport)})`,
+      fix: getRuntimeFreshnessRepairGuidance(options.runtimeFreshnessReport),
+    });
+  }
 
   const drift = checkDrift(planningDir);
   if (drift.drifted) {

package/bin/lib/health.mjs

@@ -21,7 +21,7 @@ export function createCmdHealth(ctx) {
     const cwd = process.cwd();
     const planningDir = join(cwd, '.planning');
     const frameworkSourceMode = isFrameworkSourceRepo(cwd);
-    const healthCheckIds = ['E1', 'E2', 'E3', 'E4', 'E5', 'E6', 'E7', 'E8', 'W1', 'W2', 'W3', 'W4', 'W5', 'W6', ...TRUTH_CHECK_IDS, 'I1', 'I2', 'I3'];
+    const healthCheckIds = ['E1', 'E2', 'E3', 'E4', 'E5', 'E6', 'E7', 'E8', 'W1', 'W2', 'W3', 'W4', 'W5', 'W6', ...TRUTH_CHECK_IDS, 'I1', 'I2', 'I3'];
 
     // Pre-init guard
     if (!existsSync(join(planningDir, 'config.json'))) {
@@ -57,8 +57,10 @@ export function createCmdHealth(ctx) {
     }
 
     // E3: templates/ missing
-    const templatesDir = join(planningDir, 'templates');
-    const hasTemplatesDir = existsSync(templatesDir);
+    const templatesDir = join(planningDir, 'templates');
+    const runtimeHelpersDir = join(planningDir, 'bin');
+    const hasTemplatesDir = existsSync(templatesDir);
+    const hasRuntimeHelpersDir = existsSync(runtimeHelpersDir);
     const rolesDir = join(templatesDir, 'roles');
     const delegatesDir = join(templatesDir, 'delegates');
     const hasRolesDir = hasTemplatesDir && existsSync(rolesDir);
@@ -121,32 +123,33 @@ export function createCmdHealth(ctx) {
     // --- WARNING checks ---
 
     // W1: generation-manifest.json missing
-    const manifest = skipInstalledTemplateChecks ? null : readManifest(planningDir);
-    if (!manifest && !skipInstalledTemplateChecks) {
-      warnings.push({ id: 'W1', severity: 'WARN', message: 'generation-manifest.json missing', fix: 'Run `gsdd update --templates` to create' });
-    }
+    const manifest = skipInstalledTemplateChecks ? null : readManifest(planningDir);
+    if (!manifest && !skipInstalledTemplateChecks) {
+      warnings.push({ id: 'W1', severity: 'WARN', message: 'generation-manifest.json missing', fix: 'Run `gsdd update` to create' });
+    }
 
     // W2 + W3: template/role hash mismatches and missing files
     if (manifest && hasTemplatesDir) {
-      const allCategories = [
-        { name: 'delegates', dir: delegatesDir, hashes: hasDelegatesDir ? manifest.templates?.delegates : null },
-        { name: 'research', dir: join(templatesDir, 'research'), hashes: manifest.templates?.research },
-        { name: 'codebase', dir: join(templatesDir, 'codebase'), hashes: manifest.templates?.codebase },
-        { name: 'root templates', dir: templatesDir, hashes: manifest.templates?.root },
-        { name: 'roles', dir: rolesDir, hashes: hasRolesDir ? manifest.roles : null },
-      ];
-
-      for (const cat of allCategories) {
-        if (!cat.hashes) continue;
-        const result = detectModifications(cat.dir, cat.hashes);
-        if (result.modified.length > 0) {
-          warnings.push({ id: 'W2', severity: 'WARN', message: `${cat.name}: ${result.modified.length} file(s) modified locally (${result.modified.join(', ')})`, fix: 'Intentional? Run `gsdd update --templates` to reset' });
-        }
-        if (result.missing.length > 0) {
-          warnings.push({ id: 'W3', severity: 'WARN', message: `${cat.name}: ${result.missing.length} file(s) missing from disk (${result.missing.join(', ')})`, fix: 'Run `gsdd update --templates` to restore' });
-        }
-      }
-    }
+      const allCategories = [
+        { name: 'delegates', dir: delegatesDir, hashes: hasDelegatesDir ? manifest.templates?.delegates : null, fixCommand: 'gsdd update --templates' },
+        { name: 'research', dir: join(templatesDir, 'research'), hashes: manifest.templates?.research, fixCommand: 'gsdd update --templates' },
+        { name: 'codebase', dir: join(templatesDir, 'codebase'), hashes: manifest.templates?.codebase, fixCommand: 'gsdd update --templates' },
+        { name: 'root templates', dir: templatesDir, hashes: manifest.templates?.root, fixCommand: 'gsdd update --templates' },
+        { name: 'roles', dir: rolesDir, hashes: hasRolesDir ? manifest.roles : null, fixCommand: 'gsdd update --templates' },
+        { name: 'runtime helpers', dir: planningDir, hashes: hasRuntimeHelpersDir ? manifest.runtimeHelpers : null, fixCommand: 'gsdd update' },
+      ];
+
+      for (const cat of allCategories) {
+        if (!cat.hashes) continue;
+        const result = detectModifications(cat.dir, cat.hashes);
+        if (result.modified.length > 0) {
+          warnings.push({ id: 'W2', severity: 'WARN', message: `${cat.name}: ${result.modified.length} file(s) modified locally (${result.modified.join(', ')})`, fix: `Intentional? Run \`${cat.fixCommand}\` to reset` });
+        }
+        if (result.missing.length > 0) {
+          warnings.push({ id: 'W3', severity: 'WARN', message: `${cat.name}: ${result.missing.length} file(s) missing from disk (${result.missing.join(', ')})`, fix: `Run \`${cat.fixCommand}\` to restore` });
+        }
+      }
+    }
 
     // W4: ROADMAP.md references phases not found in .planning/phases/
     const roadmapPath = join(planningDir, 'ROADMAP.md');

package/bin/lib/init-flow.mjs

@@ -1,7 +1,7 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync, cpSync } from 'fs';
-import { join, isAbsolute } from 'path';
-import { renderSkillContent } from './rendering.mjs';
-import { buildManifest, writeManifest } from './manifest.mjs';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, cpSync } from 'fs';
+import { dirname, join, isAbsolute } from 'path';
+import { buildPlanningCliHelperEntries, renderSkillContent } from './rendering.mjs';
+import { buildManifest, readManifest, writeManifest } from './manifest.mjs';
 import { parseFlagValue, parseToolsFlag, parseAutoFlag } from './cli-utils.mjs';
 import { buildDefaultConfig, COST_PROFILES, RIGOR_PROFILES } from './models.mjs';
 import { installProjectTemplates, refreshTemplates } from './templates.mjs';
@@ -106,8 +106,11 @@ export function createCmdInit(ctx) {
       console.log('  - copied project brief to .planning/PROJECT_BRIEF.md');
     }
 
-    generateOpenStandardSkills(ctx.cwd, ctx.workflows);
-    console.log('  - generated open-standard skills (.agents/skills/gsdd-*)');
+    generateOpenStandardSkills(ctx.cwd, ctx.workflows);
+    console.log('  - generated open-standard skills (.agents/skills/gsdd-*)');
+
+    generatePlanningCliHelpers(ctx);
+    console.log('  - generated local workflow helpers (.planning/bin/gsdd*)');
 
     for (const adapter of resolveAdapters(ctx.adapters, interactiveSession.adapterTargets)) {
       adapter.generate();
@@ -144,15 +147,25 @@ export function createCmdUpdate(ctx) {
       updated = true;
     }
 
-    if (platforms.length > 0 || existsSync(join(ctx.cwd, '.agents', 'skills'))) {
-      if (isDry) {
-        console.log('  - would update open-standard skills (.agents/skills/gsdd-*)');
-      } else {
-        generateOpenStandardSkills(ctx.cwd, ctx.workflows);
+    if (platforms.length > 0 || existsSync(join(ctx.cwd, '.agents', 'skills'))) {
+      if (isDry) {
+        console.log('  - would update open-standard skills (.agents/skills/gsdd-*)');
+      } else {
+        generateOpenStandardSkills(ctx.cwd, ctx.workflows);
         console.log('  - updated open-standard skills (.agents/skills/gsdd-*)');
-      }
-      updated = true;
-    }
+      }
+      updated = true;
+    }
+
+    if (existsSync(ctx.planningDir)) {
+      if (isDry) {
+        console.log('  - would update local workflow helpers (.planning/bin/gsdd*)');
+      } else {
+        generatePlanningCliHelpers(ctx);
+        console.log('  - updated local workflow helpers (.planning/bin/gsdd*)');
+      }
+      updated = true;
+    }
 
     for (const adapter of getAdaptersToUpdate(ctx.adapters, platforms)) {
       if (isDry) {
@@ -167,26 +180,72 @@ export function createCmdUpdate(ctx) {
 
     if (!updated) {
       console.log('  - no adapters found to update (run `gsdd init` first)');
-    } else if (isDry) {
-      console.log('\nDry run complete. No files were written.\n');
-    } else {
-      if (doTemplates && existsSync(ctx.planningDir)) {
-        const manifest = buildManifest({ planningDir: ctx.planningDir, frameworkVersion: ctx.frameworkVersion });
-        writeManifest(ctx.planningDir, manifest);
-        console.log('  - updated generation manifest');
-      }
-      console.log('\nAdapters updated.\n');
-    }
-  };
-}
-
-function generateOpenStandardSkills(cwd, workflows) {
-  for (const workflow of workflows) {
-    const dir = join(cwd, '.agents', 'skills', workflow.name);
-    mkdirSync(dir, { recursive: true });
-    writeFileSync(join(dir, 'SKILL.md'), renderSkillContent(workflow));
-  }
-}
+    } else if (isDry) {
+      console.log('\nDry run complete. No files were written.\n');
+    } else {
+      if (existsSync(ctx.planningDir)) {
+        const manifest = buildUpdateManifest({
+          planningDir: ctx.planningDir,
+          frameworkVersion: ctx.frameworkVersion,
+          updateTemplates: doTemplates,
+        });
+        if (manifest) {
+          writeManifest(ctx.planningDir, manifest);
+          console.log('  - updated generation manifest');
+        }
+      }
+      console.log('\nAdapters updated.\n');
+    }
+  };
+}
+
+function generateOpenStandardSkills(cwd, workflows) {
+  for (const workflow of workflows) {
+    const dir = join(cwd, '.agents', 'skills', workflow.name);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'SKILL.md'), renderSkillContent(workflow));
+  }
+}
+
+function generatePlanningCliHelpers(ctx) {
+  for (const entry of buildPlanningCliHelperEntries({
+    packageName: ctx.packageName,
+    packageVersion: ctx.packageVersion,
+  })) {
+    const absolutePath = join(ctx.planningDir, entry.relativePath);
+    mkdirSync(dirname(absolutePath), { recursive: true });
+    writeFileSync(absolutePath, entry.content);
+    if (!absolutePath.endsWith('.cmd')) {
+      chmodSync(absolutePath, 0o755);
+    }
+  }
+}
+
+function buildUpdateManifest({ planningDir, frameworkVersion, updateTemplates }) {
+  const existingManifest = readManifest(planningDir);
+  const nextManifest = buildManifest({ planningDir, frameworkVersion });
+
+  if (existingManifest && !updateTemplates) {
+    nextManifest.templates = existingManifest.templates ?? nextManifest.templates;
+    nextManifest.roles = existingManifest.roles ?? nextManifest.roles;
+  }
+
+  if (existingManifest && manifestsEqualIgnoringTimestamp(existingManifest, nextManifest)) {
+    return null;
+  }
+
+  return nextManifest;
+}
+
+function manifestsEqualIgnoringTimestamp(left, right) {
+  return JSON.stringify(stripManifestTimestamp(left)) === JSON.stringify(stripManifestTimestamp(right));
+}
+
+function stripManifestTimestamp(manifest) {
+  if (!manifest || typeof manifest !== 'object') return manifest;
+  const { generatedAt, ...rest } = manifest;
+  return rest;
+}
 
 async function ensureConfig({ cwd, planningDir, isAuto, promptApi, preselectedConfig = null }) {
   const configFile = join(planningDir, 'config.json');

package/bin/lib/init-runtime.mjs

@@ -161,8 +161,8 @@ export function getPostInitRoutingLines(selectedRuntimes) {
 
 export function getHelpText() {
   return `
-gsdd - Workspine CLI
-Portable multi-runtime software delivery framework for AI coding agents.
+gsdd - Workspine CLI
+Repo-native delivery spine for long-horizon AI-assisted work across coding runtimes.
 
 Usage: gsdd <command> [args]
 
@@ -198,8 +198,9 @@ Platforms (for --tools):
   all       Generate all adapters (Claude, OpenCode, Codex, AGENTS.md, Cursor, Copilot, Gemini)
 
 Notes:
-  - init always generates open-standard skills at .agents/skills/gsdd-* (portable workflow entrypoints)
-  - Workspine is the public product name; the retained package, command, workflow, and workspace contracts stay gsdd-cli, gsdd, gsdd-*, and .planning/
+  - init always generates open-standard skills at .agents/skills/gsdd-* (portable workflow entrypoints)
+  - init also generates a local .planning/bin/gsdd* helper surface so workflow-embedded helper commands do not depend on a global gsdd binary
+  - Workspine is the public product name; the retained package, command, workflow, and workspace contracts stay gsdd-cli, gsdd, gsdd-*, and .planning/
   - running plain \`gsdd init\` in a terminal opens the guided runtime-selection wizard
   - the wizard lets you pick runtimes first, then separately decide whether repo-wide AGENTS.md governance is worth installing
   - \`gsdd health\` compares any installed generated runtime surfaces against current render output and points back to \`gsdd update\` when they drift

package/bin/lib/lifecycle-state.mjs

@@ -1,5 +1,7 @@
-import { existsSync, readFileSync, readdirSync } from 'fs';
-import { join } from 'path';
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+
+const BROWNFIELD_CHANGE_DIR = 'brownfield-change';
 
 const PHASE_LINE_RE = /^\s*[-*]\s*\[([ x-])\]\s*\*\*Phase\s+(\d+(?:\.\d+)*[a-z]?):\s*(.+?)\*\*(?:\s+—\s+\[([^\]]+)])?/i;
 const ACTIVE_MILESTONE_HEADING_RE = /^###\s+(v[^\s]+)\s+(.+)$/im;
@@ -15,9 +17,16 @@ export function evaluateLifecycleState({ planningDir, provenance = null } = {})
   const milestonesPath = join(planningDir, 'MILESTONES.md');
   const phasesDir = join(planningDir, 'phases');
 
-  const spec = readTextIfExists(specPath);
-  const roadmap = readTextIfExists(roadmapPath);
-  const milestones = readTextIfExists(milestonesPath);
+  const spec = readTextIfExists(specPath);
+  const roadmap = readTextIfExists(roadmapPath);
+  const milestones = readTextIfExists(milestonesPath);
+  const brownfieldChange = readBrownfieldChangeState(planningDir);
+  const nonPhaseState = deriveNonPhaseState({
+    planningDir,
+    hasSpec: Boolean(spec.trim()),
+    hasRoadmap: Boolean(roadmap.trim()),
+    brownfieldChange,
+  });
 
   const phases = parseActiveRoadmapPhases(roadmap);
   const phaseArtifacts = collectPhaseArtifacts(phasesDir);
@@ -69,10 +78,12 @@ export function evaluateLifecycleState({ planningDir, provenance = null } = {})
     phases: enrichedPhases,
     currentPhase: enrichedPhases.find((phase) => phase.status === 'in_progress') || null,
     nextPhase: enrichedPhases.find((phase) => phase.status === 'not_started') || null,
-    counts,
-    phaseArtifacts,
-    incompletePlans,
-    requirementAlignment: evaluateRequirementAlignment(spec, enrichedPhases),
+    counts,
+    phaseArtifacts,
+    incompletePlans,
+    brownfieldChange,
+    nonPhaseState,
+    requirementAlignment: evaluateRequirementAlignment(spec, enrichedPhases),
     provenance: provenance
       ? {
           provided: true,
@@ -86,9 +97,13 @@ function readTextIfExists(filePath) {
   return existsSync(filePath) ? readFileSync(filePath, 'utf-8') : '';
 }
 
-function normalizeContent(content) {
-  return String(content || '').replace(/\r\n/g, '\n');
-}
+function normalizeContent(content) {
+  return String(content || '').replace(/\r\n/g, '\n');
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
 
 export function normalizePhaseToken(value) {
   const raw = String(value || '').trim().toLowerCase();
@@ -108,8 +123,8 @@ function normalizePhaseStatus(marker) {
   return 'not_started';
 }
 
-function parseActiveRoadmapPhases(roadmap) {
-  if (!roadmap) return [];
+function parseActiveRoadmapPhases(roadmap) {
+  if (!roadmap) return [];
 
   const phases = [];
   let inDetails = false;
@@ -135,12 +150,74 @@ function parseActiveRoadmapPhases(roadmap) {
       requirements: splitRequirementList(match[4]),
     });
   }
-
-  return phases;
-}
-
-function splitRequirementList(rawRequirements = '') {
-  return String(rawRequirements)
+
+  return phases;
+}
+
+export function readBrownfieldChangeState(planningDir) {
+  const dir = join(planningDir, BROWNFIELD_CHANGE_DIR);
+  const changePath = join(dir, 'CHANGE.md');
+  const handoffPath = join(dir, 'HANDOFF.md');
+
+  if (!existsSync(changePath)) {
+    return {
+      exists: false,
+      dir,
+      changePath,
+      handoffPath,
+      title: null,
+      changeId: null,
+      currentStatus: null,
+      currentIntegrationSurface: null,
+      currentOwnerRuntime: null,
+      nextAction: null,
+      declaredOwnedPaths: [],
+      handoff: null,
+    };
+  }
+
+  const changeArtifact = readMarkdownArtifact(changePath);
+  const handoffArtifact = existsSync(handoffPath) ? readMarkdownArtifact(handoffPath) : null;
+  const currentStatusSection = extractMarkdownSection(changeArtifact.body, 'Current Status');
+  const nextActionSection = extractMarkdownSection(changeArtifact.body, 'Next Action');
+  const sliceSection = extractMarkdownSection(changeArtifact.body, 'PR Slice Ownership');
+
+  return {
+    exists: true,
+    dir,
+    changePath,
+    handoffPath,
+    title: extractMarkdownHeading(changeArtifact.body),
+    changeId: changeArtifact.frontmatter.change || null,
+    currentStatus: changeArtifact.frontmatter.status || extractBulletLabel(currentStatusSection, 'Current posture'),
+    currentIntegrationSurface: extractBulletLabel(currentStatusSection, 'Current branch / integration surface'),
+    currentOwnerRuntime: extractBulletLabel(currentStatusSection, 'Current owner / runtime'),
+    nextAction: collapseMarkdownSection(nextActionSection),
+    declaredOwnedPaths: parseOwnedPathHints(sliceSection),
+    handoff: handoffArtifact
+      ? {
+          updated: handoffArtifact.frontmatter.updated || null,
+          activeConstraints: collapseMarkdownSection(extractMarkdownSection(handoffArtifact.body, 'Active Constraints')),
+          unresolvedUncertainty: collapseMarkdownSection(extractMarkdownSection(handoffArtifact.body, 'Unresolved Uncertainty')),
+          decisionPosture: collapseMarkdownSection(extractMarkdownSection(handoffArtifact.body, 'Decision Posture')),
+          antiRegression: collapseMarkdownSection(extractMarkdownSection(handoffArtifact.body, 'Anti-Regression')),
+          nextActionContext: collapseMarkdownSection(extractMarkdownSection(handoffArtifact.body, 'Next Action')),
+        }
+      : null,
+  };
+}
+
+export function deriveNonPhaseState({ planningDir, hasSpec, hasRoadmap, brownfieldChange } = {}) {
+  if (brownfieldChange?.exists) return 'active_brownfield_change';
+  if (hasRoadmap) return null;
+  if (hasSpec) return 'between_milestones';
+  if (hasSubstantiveCodebaseMaps(planningDir)) return 'codebase_only';
+  if (hasQuickLaneArtifacts(planningDir)) return 'quick_lane';
+  return null;
+}
+
+function splitRequirementList(rawRequirements = '') {
+  return String(rawRequirements)
     .split(',')
     .map((entry) => entry.trim())
     .filter(Boolean);
@@ -262,10 +339,10 @@ function deriveCurrentMilestone({ roadmap, planningDir, milestoneLedger, counts
   };
 }
 
-function evaluateRequirementAlignment(spec, phases) {
-  const checkedRequirements = new Set(
-    [...normalizeContent(spec).matchAll(/- \[x\] \*\*\[([A-Z0-9-]+)]\*\*/g)].map((result) => result[1])
-  );
+function evaluateRequirementAlignment(spec, phases) {
+  const checkedRequirements = new Set(
+    [...normalizeContent(spec).matchAll(/- \[x\] \*\*\[([A-Z0-9-]+)]\*\*/g)].map((result) => result[1])
+  );
 
   const roadmapRequirements = new Map();
   for (const phase of phases) {
@@ -287,7 +364,113 @@ function evaluateRequirementAlignment(spec, phases) {
 
   return {
     checkedRequirements,
-    roadmapRequirements,
-    mismatches,
-  };
-}
+    roadmapRequirements,
+    mismatches,
+  };
+}
+
+function readMarkdownArtifact(filePath) {
+  const raw = readTextIfExists(filePath);
+  const normalized = normalizeContent(raw);
+  const match = normalized.match(/^---\n([\s\S]*?)\n---\n?/);
+  if (!match) {
+    return {
+      raw: normalized,
+      frontmatter: {},
+      body: normalized,
+    };
+  }
+
+  return {
+    raw: normalized,
+    frontmatter: parseFrontmatter(match[1]),
+    body: normalized.slice(match[0].length),
+  };
+}
+
+function parseFrontmatter(content) {
+  const data = {};
+  for (const line of normalizeContent(content).split('\n')) {
+    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.+)$/);
+    if (!match) continue;
+    data[match[1]] = match[2].trim();
+  }
+  return data;
+}
+
+function extractMarkdownHeading(content) {
+  return normalizeContent(content).match(/^#\s+(.+)$/m)?.[1]?.trim() || null;
+}
+
+function extractMarkdownSection(content, heading) {
+  const normalized = normalizeContent(content);
+  const headingMatch = new RegExp(`^##\\s+${escapeRegExp(heading)}\\s*$`, 'm').exec(normalized);
+  if (!headingMatch) return '';
+
+  const start = headingMatch.index + headingMatch[0].length;
+  const remainder = normalized.slice(start).replace(/^\n/, '');
+  const nextHeading = /\n##\s+/.exec(remainder);
+  const end = nextHeading ? nextHeading.index : remainder.length;
+  return remainder.slice(0, end).trim();
+}
+
+function extractBulletLabel(section, label) {
+  const match = normalizeContent(section).match(
+    new RegExp(`^[-*]\\s+${escapeRegExp(label)}\\s*:\\s*(.+)$`, 'im')
+  );
+  return match ? match[1].trim() : null;
+}
+
+function collapseMarkdownSection(section) {
+  return normalizeContent(section)
+    .split('\n')
+    .map((line) => line.replace(/^[-*]\s+/, '').trim())
+    .filter(Boolean)
+    .join(' ');
+}
+
+function parseOwnedPathHints(section) {
+  const lines = normalizeContent(section)
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith('|'));
+  const paths = [];
+
+  for (const line of lines.slice(2)) {
+    const columns = line.split('|').map((column) => column.trim());
+    const owned = columns[3];
+    if (!owned) continue;
+
+    for (const candidate of owned.split(',')) {
+      const normalized = normalizeOwnedPathHint(candidate);
+      if (normalized) paths.push(normalized);
+    }
+  }
+
+  return [...new Set(paths)];
+}
+
+function normalizeOwnedPathHint(value) {
+  const normalized = String(value || '')
+    .replace(/[`[\]]/g, '')
+    .trim()
+    .replace(/\\/g, '/');
+  if (!normalized) return null;
+  if (/^(disjoint write set|owned files \/ modules|what this slice does|planned)$/i.test(normalized)) {
+    return null;
+  }
+  if (!/[/.\\*]/.test(normalized)) return null;
+  return normalized;
+}
+
+function hasSubstantiveCodebaseMaps(planningDir) {
+  const dir = join(planningDir, 'codebase');
+  if (!existsSync(dir)) return false;
+  return readdirSync(dir).some((entry) => entry.toLowerCase().endsWith('.md'));
+}
+
+function hasQuickLaneArtifacts(planningDir) {
+  const dir = join(planningDir, 'quick');
+  if (!existsSync(dir)) return false;
+  return readdirSync(dir).length > 0;
+}