feat: add brownfield change continuity flow

Integrate the bounded brownfield change lane with resume/progress continuity, shipped templates, lifecycle preflight, and generated helper/runtime hardening while preserving current release automation.

Author: PatrickSys

CHANGELOG.md

@@ -30,7 +30,7 @@ Milestone: **v1.4.0 — Launch Surface Coherence**
 * .mailmap for contributor identity consolidation
 * FUNDING.yml and SECURITY.md references updated
 * FRAMEWORK_VERSION bumped to v1.4
-* framework state: 52 design decisions, 14 workflows, 1,381 tests across 13 suites
+* framework state: 52 design decisions, 14 workflows, 1,381 tests across 13 test files
 * npm tarball now ships public docs/proof surfaces plus `distilled/EVIDENCE-INDEX.md` and `distilled/SKILL.md`
 * `gsdd help` now reflects the full workflow surface and helper commands more cleanly
 * launch docs now align on Node 20+, qualified-support caveats, and milestone-continuation surfaces

README.md

@@ -95,7 +95,11 @@ This creates:
 3. `.planning/bin/gsdd.mjs` — repo-local helper runtime for deterministic workflow commands inside generated skills (run helper commands from the repo root)
 4. Optional tool-specific adapters you choose in the install wizard (Claude skills/commands/agents, OpenCode commands/agents, Codex CLI agents, optional governance)
 
-Then run the new-project workflow to produce `.planning/SPEC.md` and `.planning/ROADMAP.md`.
+Then pick the first workflow lane that matches your situation:
+
+- `gsdd-new-project` for greenfield work, fuzzy brownfield work, or milestone-shaped work
+- `gsdd-quick` for a concrete bounded brownfield change
+- `gsdd-map-codebase` first when the repo is unfamiliar, risky, or needs a deeper baseline before choosing a lane
 
 In a terminal, `npx -y gsdd-cli init` opens a guided install wizard. If you installed the package globally, `gsdd init` is the equivalent shorthand:
 
@@ -123,7 +127,7 @@ Start with the public proof pack:
 
 Runtime floor: Node 20+.
 
-Your tool determines how you invoke workflows:
+Your tool determines how you invoke workflows after `npx gsdd-cli init`:
 
 - **Claude Code / OpenCode:** Use native slash commands directly — `/gsdd-new-project`, `/gsdd-plan`, etc.
 - **Codex CLI:** Use skill references — `$gsdd-new-project`, `$gsdd-plan`, etc. `$gsdd-plan` writes the plan and stops; start a separate `$gsdd-execute` run when you want implementation to begin.
@@ -172,14 +176,16 @@ npx -y gsdd-cli init --tools all        # All of the above
 | **Cursor / Copilot / Gemini** | Qualified support | Uses `.agents/skills/` when skill/slash discovery is available; optional root `AGENTS.md` block adds behavioral governance, and the generated skill surface is freshness-checked locally |
 | **Other AI tools** | Fallback only | Open `.agents/skills/gsdd-*/SKILL.md` directly |
 
-### Updating
+### Updating And Repair
 
 ```bash
 npx -y gsdd-cli update                    # Regenerate adapters from latest sources
 npx -y gsdd-cli update --tools claude     # Update specific platform only
 npx -y gsdd-cli update --templates        # Refresh .planning/templates/ and role contracts from framework source
 ```
 
+Use `gsdd health` first when you want a status check. Use `npx gsdd-cli update` when the generated runtime-facing surfaces are missing, drifted, or you want the latest generated output. If a runtime is only in the qualified-support tier, `health` and `update` still cover generated-surface drift; they do not imply parity-level runtime proof.
+
 ### Non-Interactive Mode (CI / Automation)
 
 For non-interactive environments:

bin/gsdd.mjs

@@ -1,8 +1,6 @@
 #!/usr/bin/env node
 
-// 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';
@@ -26,7 +24,7 @@ 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 PACKAGE_JSON = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
 const IS_MAIN = process.argv[1]
   ? realpathSync(process.argv[1]) === realpathSync(__filename)
   : false;
@@ -67,6 +65,8 @@ function createCliContext(cwd = process.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({
@@ -85,7 +85,7 @@ function createCliContext(cwd = process.cwd()) {
   };
 }
 
-const INIT_CONTEXT = createCliContext(CWD);
+const INIT_CONTEXT = createCliContext(process.cwd());
 
 const cmdInit = createCmdInit(INIT_CONTEXT);
 const cmdHealth = createCmdHealth(INIT_CONTEXT);

bin/lib/health-truth.mjs

@@ -94,7 +94,7 @@ export function runTruthChecks(planningDir, frameworkDir, actualCheckIds, option
     warnings.push({
       id: 'W11',
       severity: 'WARN',
-      message: `Installed generated runtime surfaces drift from current render output (${summarizeRuntimeFreshnessIssues(options.runtimeFreshnessReport)})`,
+      message: `Installed generated runtime and workflow-helper surfaces drift from current render output (${summarizeRuntimeFreshnessIssues(options.runtimeFreshnessReport)})`,
       fix: getRuntimeFreshnessRepairGuidance(options.runtimeFreshnessReport),
     });
   }

bin/lib/health.mjs

@@ -31,7 +31,7 @@ export function createCmdHealth(ctx) {
     }
     const cwd = workspaceRoot;
     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', 'E9', 'W1', 'W2', 'W3', 'W4', 'W5', 'W6', ...TRUTH_CHECK_IDS, 'I1', 'I2', 'I3'];
 
     // Pre-init guard
     if (!existsSync(join(planningDir, 'config.json'))) {
@@ -128,6 +128,16 @@ export function createCmdHealth(ctx) {
       if (missingRoot.length > 0) {
         errors.push({ id: 'E8', severity: 'ERROR', message: `.planning/templates/ missing critical root files: ${missingRoot.join(', ')}`, fix: 'Run `npx -y gsdd-cli update --templates`' });
       }
+
+      const brownfieldChangeDir = join(templatesDir, 'brownfield-change');
+      if (!existsSync(brownfieldChangeDir)) {
+        errors.push({ id: 'E9', severity: 'ERROR', message: '.planning/templates/brownfield-change/ missing', fix: 'Run `npx -y gsdd-cli update --templates`' });
+      } else {
+        const missingBrownfield = ['CHANGE.md', 'HANDOFF.md', 'VERIFICATION.md'].filter((file) => !existsSync(join(brownfieldChangeDir, file)));
+        if (missingBrownfield.length > 0) {
+          errors.push({ id: 'E9', severity: 'ERROR', message: `.planning/templates/brownfield-change/ missing critical files: ${missingBrownfield.join(', ')}`, fix: 'Run `npx -y gsdd-cli update --templates`' });
+        }
+      }
     }
 
     // --- WARNING checks ---
@@ -144,6 +154,7 @@ export function createCmdHealth(ctx) {
         { name: 'delegates', dir: delegatesDir, hashes: hasDelegatesDir ? manifest.templates?.delegates : null, fixCommand: 'npx -y gsdd-cli update --templates' },
         { name: 'research', dir: join(templatesDir, 'research'), hashes: manifest.templates?.research, fixCommand: 'npx -y gsdd-cli update --templates' },
         { name: 'codebase', dir: join(templatesDir, 'codebase'), hashes: manifest.templates?.codebase, fixCommand: 'npx -y gsdd-cli update --templates' },
+        { name: 'brownfield-change', dir: join(templatesDir, 'brownfield-change'), hashes: manifest.templates?.brownfieldChange, fixCommand: 'npx -y gsdd-cli update --templates' },
         { name: 'root templates', dir: templatesDir, hashes: manifest.templates?.root, fixCommand: 'npx -y gsdd-cli update --templates' },
         { name: 'roles', dir: rolesDir, hashes: hasRolesDir ? manifest.roles : null, fixCommand: 'npx -y gsdd-cli update --templates' },
         { name: 'runtime helpers', dir: planningDir, hashes: hasRuntimeHelpersDir ? manifest.runtimeHelpers : null, fixCommand: 'npx -y gsdd-cli update' },

bin/lib/init-runtime.mjs

@@ -233,7 +233,7 @@ Examples:
 
 Workflows (run via skills/adapters generated by init, not direct CLI):
   gsdd-new-project          Full initializer: questioning, brownfield audit, research, spec, roadmap
-  gsdd-map-codebase         Map or refresh brownfield codebase context
+  gsdd-map-codebase         Map or refresh brownfield codebase context before choosing or refreshing a work lane
   gsdd-plan                 Research, plan, and fresh-context plan check for a phase
   gsdd-execute              Execute a phase plan and write phase summaries
   gsdd-verify               Verify a completed phase with 3-level checks
@@ -246,5 +246,15 @@ Workflows (run via skills/adapters generated by init, not direct CLI):
   gsdd-pause                Save session context to checkpoint
   gsdd-resume               Restore context and route to the next action
   gsdd-progress             Read-only status and routing surface
+
+Starting lanes after init:
+  gsdd-new-project          Greenfield, fuzzy brownfield scope, or milestone-shaped work
+  gsdd-quick                Concrete bounded brownfield change
+  gsdd-map-codebase         Deeper brownfield orientation before choosing the lane above
+
+Advanced/internal helpers (kept available, but not the primary first-run user story):
+  lifecycle-preflight       Inspect deterministic lifecycle gate results for a workflow surface
+  phase-status              Update ROADMAP.md phase status through the local helper surface
+  file-op                   Deterministic workspace-confined file copy/delete/text mutation
 `;
 }

bin/lib/lifecycle-preflight.mjs

@@ -120,8 +120,8 @@ export function evaluateLifecyclePreflight({
     }
   }
 
-  if (surface === 'resume' && !existsSync(checkpointPath)) {
-    blockers.push(blocker('missing_checkpoint', 'resume requires .planning/.continue-here.md to exist.', ['.planning/.continue-here.md']));
+  if (surface === 'resume' && !existsSync(checkpointPath) && lifecycle.nonPhaseState !== 'active_brownfield_change') {
+    blockers.push(blocker('missing_checkpoint', 'resume requires .planning/.continue-here.md unless an active .planning/brownfield-change/CHANGE.md continuity anchor exists.', ['.planning/.continue-here.md', '.planning/brownfield-change/CHANGE.md']));
   }
 
   const warnings = [];

bin/lib/lifecycle-state.mjs

@@ -1,6 +1,8 @@
 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 PHASE_DETAIL_HEADING_RE = /^(#{3,})\s+Phase\s+(\d+(?:\.\d+)*[a-z]?)(?::|\b)/i;
 const PHASE_DETAIL_STATUS_RE = /^\s*\*\*Status\*\*:\s*\[([ x-])\]/i;
@@ -22,6 +24,13 @@ export function evaluateLifecycleState({ planningDir, provenance = null } = {})
   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 phaseStatusAlignment = evaluateRoadmapPhaseStatusAlignment(roadmap);
@@ -77,6 +86,8 @@ export function evaluateLifecycleState({ planningDir, provenance = null } = {})
     counts,
     phaseArtifacts,
     incompletePlans,
+    brownfieldChange,
+    nonPhaseState,
     phaseStatusAlignment,
     requirementAlignment: evaluateRequirementAlignment(spec, enrichedPhases, phaseStatusAlignment),
     provenance: provenance
@@ -174,6 +185,10 @@ 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();
   const match = raw.match(/^(\d+(?:\.\d+)*)([a-z]?)$/i);
@@ -223,6 +238,68 @@ function parseActiveRoadmapPhases(roadmap) {
   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(',')
@@ -375,3 +452,109 @@ function evaluateRequirementAlignment(spec, phases, phaseStatusAlignment = { mis
     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;
+}