Fix planning drift preflight gating (#93)

* fix: gate planning drift before lifecycle writes

* fix: preserve fingerprint drift compatibility

* fix: document fingerprint helper command

Author: PatrickSys

README.md

@@ -349,6 +349,7 @@ Workflows are agent skills or commands, not plain shell utilities. How you invok
 | `npx -y gsdd-cli file-op <copy\|delete\|regex-sub>` | Run deterministic workspace-confined file copy, delete, and regex substitution |
 | `npx -y gsdd-cli find-phase [N]` | Show phase info as JSON (for agent consumption) |
 | `npx -y gsdd-cli phase-status <N> <status>` | Update a single ROADMAP phase status through the status-aware helper |
+| `npx -y gsdd-cli session-fingerprint write` | Refresh the local planning-state drift baseline |
 | `npx -y gsdd-cli verify <N>` | Run artifact checks for phase N |
 | `npx -y gsdd-cli scaffold phase <N> [name]` | Create a new phase plan file |
 | `npx -y gsdd-cli models [show\|profile\|set\|...]` | Inspect and manage model profile propagation |

bin/gsdd.mjs

@@ -18,16 +18,15 @@ import { cmdFindPhase, cmdVerify, cmdScaffold, cmdPhaseStatus } from './lib/phas
 import { cmdFileOp } from './lib/file-ops.mjs';
 import { createCmdHealth } from './lib/health.mjs';
 import { cmdLifecyclePreflight } from './lib/lifecycle-preflight.mjs';
+import { cmdSessionFingerprint } from './lib/session-fingerprint.mjs';
 import { resolveWorkspaceContext } from './lib/workspace-root.mjs';
 
 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 IS_MAIN = process.argv[1]
-  ? realpathSync(process.argv[1]) === realpathSync(__filename)
-  : false;
+const IS_MAIN = process.argv[1] ? realpathSync(process.argv[1]) === realpathSync(__filename) : false;
 
 const [,, command, ...args] = process.argv;
 
@@ -107,6 +106,7 @@ const COMMANDS = {
   health: cmdHealth,
   'file-op': cmdFileOp,
   'lifecycle-preflight': cmdLifecyclePreflight,
+  'session-fingerprint': cmdSessionFingerprint,
   'find-phase': cmdFindPhase,
   'phase-status': cmdPhaseStatus,
   verify: cmdVerify,
@@ -136,4 +136,4 @@ if (IS_MAIN) {
   await runCli();
 }
 
-export { cmdHelp, cmdInit, cmdUpdate, cmdModels, cmdHealth, cmdFileOp, cmdLifecyclePreflight, cmdFindPhase, cmdPhaseStatus, cmdVerify, cmdScaffold, runCli, FRAMEWORK_VERSION, createCliContext };
+export { cmdHelp, cmdInit, cmdUpdate, cmdModels, cmdHealth, cmdFileOp, cmdLifecyclePreflight, cmdSessionFingerprint, cmdFindPhase, cmdPhaseStatus, cmdVerify, cmdScaffold, runCli, FRAMEWORK_VERSION, createCliContext };

bin/lib/health-truth.mjs

@@ -105,8 +105,8 @@ export function runTruthChecks(planningDir, frameworkDir, actualCheckIds, option
       id: 'W12',
       severity: 'WARN',
       message: `Planning state drifted since last recorded session (${drift.details.join('; ')})`,
-      fix: 'Review the changes, then run a lifecycle workflow to update the fingerprint',
-    });
+        fix: 'Review the changed planning files. If the drift is intentional, rebaseline with `node .planning/bin/gsdd.mjs session-fingerprint write`, then rerun the blocked lifecycle preflight.',
+      });
   }
 
   return warnings;

bin/lib/init-runtime.mjs

@@ -186,6 +186,7 @@ Commands:
   phase-status <N> <status>   Update ROADMAP.md phase status ([ ] / [-] / [x])
   lifecycle-preflight <surface> [phase]
                               Inspect deterministic lifecycle gate results for a workflow surface
+  session-fingerprint write    Rebaseline planning-state drift after reviewing changed planning files
   help                        Show this summary
 
 Platforms (for --tools):
@@ -254,6 +255,7 @@ Starting lanes after init:
 
 Advanced/internal helpers (kept available, but not the primary first-run user story):
   lifecycle-preflight       Inspect deterministic lifecycle gate results for a workflow surface
+  session-fingerprint       Rebaseline the local planning-state fingerprint after review
   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

@@ -12,6 +12,12 @@ const SURFACE_POLICIES = {
     ownedWrites: [],
     explicitLifecycleMutation: 'none',
   },
+  plan: {
+    classification: 'owned_write',
+    ownedWrites: ['research', 'plan'],
+    explicitLifecycleMutation: 'none',
+    phaseRequired: true,
+  },
   execute: {
     classification: 'owned_write',
     ownedWrites: ['summary'],
@@ -125,15 +131,33 @@ export function evaluateLifecyclePreflight({
   }
 
   const warnings = [];
+  let planningState = null;
 
   if (existsSync(planningDir)) {
     const drift = checkDrift(planningDir);
+    planningState = {
+      classification: drift.classification,
+      drifted: drift.drifted,
+      noBaseline: drift.noBaseline,
+      details: drift.details,
+      files: drift.files,
+    };
     if (drift.drifted) {
-      warnings.push({
+      const driftNotice = {
         code: 'planning_state_drift',
-        message: `Planning state has drifted since the last recorded session: ${drift.details.join('; ')}`,
+        message: `${surface} cannot proceed because planning state drifted since the last recorded session: ${drift.details.join('; ')}`,
         artifacts: ['.planning/ROADMAP.md', '.planning/SPEC.md', '.planning/config.json'],
-      });
+        details: drift.details,
+        files: drift.files,
+      };
+      if (policy.classification === 'owned_write') {
+        blockers.push(driftNotice);
+      } else {
+        warnings.push({
+          ...driftNotice,
+          message: `Planning state has drifted since the last recorded session: ${drift.details.join('; ')}`,
+        });
+      }
     }
   }
 
@@ -158,6 +182,7 @@ export function evaluateLifecyclePreflight({
     reason: blockers[0]?.code ?? null,
     blockers,
     warnings,
+    planningState,
     lifecycle: {
       currentMilestone: lifecycle.currentMilestone,
       currentPhase: lifecycle.currentPhase ? lifecycle.currentPhase.number : null,
@@ -187,6 +212,16 @@ function buildPhaseBlockers({ lifecycle, phaseToken, surface }) {
     (artifact) => !summaryArtifacts.some((candidate) => candidate.dir === artifact.dir && candidate.baseId === artifact.baseId)
   );
 
+  if (surface === 'plan' && phaseEntry.status === 'done') {
+    blockers.push(
+      blocker(
+        'phase_already_complete',
+        `Phase ${phaseToken} is already complete. Reopen the phase before writing a new PLAN artifact.`,
+        ['.planning/ROADMAP.md']
+      )
+    );
+  }
+
   if (surface === 'execute') {
     if (planArtifacts.length === 0) {
       blockers.push(

bin/lib/rendering.mjs

@@ -46,12 +46,14 @@ function renderPlanningCliLauncher() {
 import { cmdFileOp } from './lib/file-ops.mjs';
 import { cmdLifecyclePreflight } from './lib/lifecycle-preflight.mjs';
 import { cmdPhaseStatus } from './lib/phase.mjs';
+import { cmdSessionFingerprint } from './lib/session-fingerprint.mjs';
 import { bootstrapHelperWorkspace, consumeWorkspaceRootArg, resolveWorkspaceContext } from './lib/workspace-root.mjs';
 
 const COMMANDS = {
   'file-op': cmdFileOp,
   'lifecycle-preflight': cmdLifecyclePreflight,
   'phase-status': cmdPhaseStatus,
+  'session-fingerprint': cmdSessionFingerprint,
 };
 
 function printHelp() {
@@ -67,6 +69,8 @@ function printHelp() {
     '  lifecycle-preflight <surface> [phase]',
     '                               Inspect lifecycle gate results for a workflow surface',
     '                               Example: node .planning/bin/gsdd.mjs lifecycle-preflight verify 1 --expects-mutation phase-status',
+    '  session-fingerprint write',
+    '                               Rebaseline planning-state drift after reviewing changed planning files',
     '',
     'Advanced option:',
     '  --workspace-root <path>     Override workspace root discovery before or after the subcommand',

bin/lib/session-fingerprint.mjs

@@ -11,9 +11,13 @@
 import { createHash } from 'crypto';
 import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
+import { output } from './cli-utils.mjs';
+import { resolveWorkspaceContext } from './workspace-root.mjs';
 
 const FINGERPRINT_FILE = '.state-fingerprint.json';
 const FINGERPRINT_SOURCES = ['ROADMAP.md', 'SPEC.md', 'config.json'];
+const FINGERPRINT_SCHEMA_VERSION = 2;
+const FINGERPRINT_ALGORITHM = 'sha256:v2:exists-content';
 
 /**
  * Compute a SHA-256 fingerprint from the planning truth files.
@@ -23,15 +27,52 @@ const FINGERPRINT_SOURCES = ['ROADMAP.md', 'SPEC.md', 'config.json'];
 export function computeFingerprint(planningDir) {
   const hash = createHash('sha256');
   const sources = {};
+  const files = {};
   for (const file of FINGERPRINT_SOURCES) {
     const filePath = join(planningDir, file);
-    const content = existsSync(filePath) ? readFileSync(filePath, 'utf-8') : '';
+    const exists = existsSync(filePath);
+    const content = exists ? readFileSync(filePath, 'utf-8') : '';
+    hash.update(`${file}:${exists ? 'exists' : 'missing'}:${content}\n`);
+    sources[file] = exists;
+    files[file] = {
+      exists,
+      hash: createHash('sha256').update(content).digest('hex'),
+    };
+  }
+  return { hash: hash.digest('hex'), sources, files };
+}
+
+function computeLegacyFingerprint(planningDir) {
+  const hash = createHash('sha256');
+  const sources = {};
+  for (const file of FINGERPRINT_SOURCES) {
+    const filePath = join(planningDir, file);
+    const exists = existsSync(filePath);
+    const content = exists ? readFileSync(filePath, 'utf-8') : '';
     hash.update(`${file}:${content}\n`);
-    sources[file] = existsSync(filePath);
+    sources[file] = exists;
   }
   return { hash: hash.digest('hex'), sources };
 }
 
+export function cmdSessionFingerprint(...args) {
+  const { args: normalizedArgs, planningDir, invalid, error } = resolveWorkspaceContext(args);
+  if (invalid) {
+    console.error(error);
+    process.exitCode = 1;
+    return;
+  }
+
+  const [action] = normalizedArgs;
+  if (action !== 'write') {
+    console.error('Usage: node .planning/bin/gsdd.mjs session-fingerprint write');
+    process.exitCode = 1;
+    return;
+  }
+
+  output({ operation: 'session-fingerprint write', fingerprint: writeFingerprint(planningDir) });
+}
+
 /**
  * Read the stored fingerprint from .planning/.state-fingerprint.json.
  * Returns null if the file does not exist or is unparseable.
@@ -50,10 +91,13 @@ export function readStoredFingerprint(planningDir) {
  * Write the current fingerprint to .planning/.state-fingerprint.json.
  */
 export function writeFingerprint(planningDir) {
-  const { hash, sources } = computeFingerprint(planningDir);
+  const { hash, sources, files } = computeFingerprint(planningDir);
   const data = {
+    schemaVersion: FINGERPRINT_SCHEMA_VERSION,
+    algorithm: FINGERPRINT_ALGORITHM,
     hash,
     sources,
+    files,
     timestamp: new Date().toISOString(),
   };
   writeFileSync(join(planningDir, FINGERPRINT_FILE), JSON.stringify(data, null, 2) + '\n');
@@ -69,27 +113,33 @@ export function writeFingerprint(planningDir) {
  */
 export function checkDrift(planningDir) {
   const stored = readStoredFingerprint(planningDir);
-  const { hash: currentHash, sources: currentSources } = computeFingerprint(planningDir);
+  const { hash: currentHash, sources: currentSources, files: currentFiles } = computeFingerprint(planningDir);
 
   if (!stored) {
     return {
       drifted: false,
       noBaseline: true,
+      classification: 'no_baseline',
       details: ['No stored fingerprint found — first session or fingerprint was cleared.'],
       stored: null,
-      current: { hash: currentHash, sources: currentSources },
+      current: { hash: currentHash, sources: currentSources, files: currentFiles },
+      files: [],
     };
   }
 
-  const drifted = stored.hash !== currentHash;
+  const isLegacy = !stored.schemaVersion && !stored.files;
+  const comparison = isLegacy ? computeLegacyFingerprint(planningDir) : { hash: currentHash };
+  const drifted = stored.hash !== comparison.hash;
   const details = [];
+  const files = drifted
+    ? FINGERPRINT_SOURCES.map((file) => classifyFileDrift(file, stored, currentSources, currentFiles, { legacy: isLegacy }))
+    : FINGERPRINT_SOURCES.map((file) => ({ file, status: 'unchanged' }));
   if (drifted) {
-    for (const file of FINGERPRINT_SOURCES) {
-      const was = stored.sources?.[file] ?? false;
-      const now = currentSources[file];
-      if (was && !now) details.push(`${file} was removed`);
-      else if (!was && now) details.push(`${file} was created`);
-      else if (was && now) details.push(`${file} may have changed`);
+    for (const file of files) {
+      if (file.status === 'created') details.push(`${file.file} created`);
+      else if (file.status === 'removed') details.push(`${file.file} removed`);
+      else if (file.status === 'changed') details.push(`${file.file} changed`);
+      else if (file.status === 'unknown') details.push(`${file.file} may have changed`);
     }
     if (details.length === 0) {
       details.push('Planning state hash changed since last recorded session.');
@@ -99,8 +149,35 @@ export function checkDrift(planningDir) {
   return {
     drifted,
     noBaseline: false,
+    classification: drifted ? 'planning_state_drift' : 'clean',
+    compatibility: isLegacy ? 'legacy_v1' : null,
+    needsBaselineRefresh: isLegacy && !drifted,
     details,
-    stored: { hash: stored.hash, timestamp: stored.timestamp },
-    current: { hash: currentHash, sources: currentSources },
+    files,
+    stored: {
+      hash: stored.hash,
+      timestamp: stored.timestamp,
+      schemaVersion: stored.schemaVersion ?? null,
+      algorithm: stored.algorithm ?? null,
+      files: stored.files ?? null,
+    },
+    current: { hash: currentHash, sources: currentSources, files: currentFiles },
+  };
+}
+
+function classifyFileDrift(file, stored, currentSources, currentFiles, { legacy = false } = {}) {
+  const was = stored.sources?.[file] ?? false;
+  const now = currentSources[file];
+
+  if (was && !now) return { file, status: 'removed' };
+  if (!was && now) return { file, status: 'created' };
+  if (!was && !now) return { file, status: 'unchanged' };
+  if (legacy) return { file, status: 'unknown' };
+
+  const storedFile = stored.files?.[file];
+  if (!storedFile?.hash) return { file, status: 'unknown' };
+  return {
+    file,
+    status: storedFile.hash === currentFiles[file].hash ? 'unchanged' : 'changed',
   };
 }

distilled/DESIGN.md

@@ -2157,7 +2157,8 @@ Sub-gap (b) was closed by D28's `<persistence>` mandate and guarded by G30. Sub-
   - it reports blockers, owned writes, mutation expectations, and lifecycle posture
   - it does not mutate ROADMAP or milestone state itself
 - Keep `gsdd phase-status` as the only explicit ROADMAP mutator for phase-state transitions.
-- Require transition-sensitive workflow contracts to call the shared preflight seam instead of narrating their own lifecycle inference.
+- Require transition-sensitive workflow contracts, including plan creation, to call the shared preflight seam instead of narrating their own lifecycle inference.
+- Treat planning-state drift as warning-only for read-only surfaces and blocking for owned-write surfaces, with file-level drift details from the session fingerprint helper.
 - Preserve `progress` as read-only and make it explicitly defer any recommended transition back to the downstream workflow's own preflight gate.
 
 **Why this fits the codebase:**
@@ -2170,7 +2171,9 @@ Sub-gap (b) was closed by D28's `<persistence>` mandate and guarded by G30. Sub-
 - `.planning/ROADMAP.md` (Phase 30 success criteria)
 - `bin/lib/lifecycle-preflight.mjs`
 - `bin/lib/lifecycle-state.mjs`
+- `bin/lib/session-fingerprint.mjs`
 - `bin/gsdd.mjs`
+- `distilled/workflows/plan.md`
 - `distilled/workflows/execute.md`
 - `distilled/workflows/verify.md`
 - `distilled/workflows/audit-milestone.md`
@@ -2188,7 +2191,7 @@ Sub-gap (b) was closed by D28's `<persistence>` mandate and guarded by G30. Sub-
 - `progress` can continue reporting lifecycle posture without inheriting write authority or becoming a hidden transition surface.
 - Phase 31 can build evidence-gated closure on top of a stable deterministic preflight contract instead of competing lifecycle entry logic.
 
-**GSDD implementation:** `bin/lib/lifecycle-preflight.mjs`, `bin/lib/lifecycle-state.mjs`, `bin/gsdd.mjs`, `bin/lib/init.mjs`, `distilled/workflows/execute.md`, `distilled/workflows/verify.md`, `distilled/workflows/audit-milestone.md`, `distilled/workflows/complete-milestone.md`, `distilled/workflows/new-milestone.md`, `distilled/workflows/resume.md`, `distilled/workflows/progress.md`, `tests/phase.test.cjs`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.scenarios.test.cjs`
+**GSDD implementation:** `bin/lib/lifecycle-preflight.mjs`, `bin/lib/lifecycle-state.mjs`, `bin/lib/session-fingerprint.mjs`, `bin/gsdd.mjs`, `bin/lib/init.mjs`, `distilled/workflows/plan.md`, `distilled/workflows/execute.md`, `distilled/workflows/verify.md`, `distilled/workflows/audit-milestone.md`, `distilled/workflows/complete-milestone.md`, `distilled/workflows/new-milestone.md`, `distilled/workflows/resume.md`, `distilled/workflows/progress.md`, `tests/phase.test.cjs`, `tests/session-fingerprint.test.cjs`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.scenarios.test.cjs`
 
 ---
 

distilled/EVIDENCE-INDEX.md

@@ -357,12 +357,12 @@
 ## D49 — Deterministic Lifecycle Preflight Gates
 - `.planning/SPEC.md` (`ENGINE-01`, `ENGINE-02`, `ENGINE-03`)
 - `.planning/ROADMAP.md` (Phase 30)
-- `bin/lib/lifecycle-preflight.mjs`, `bin/lib/lifecycle-state.mjs`
+- `bin/lib/lifecycle-preflight.mjs`, `bin/lib/lifecycle-state.mjs`, `bin/lib/session-fingerprint.mjs`
 - `bin/gsdd.mjs`, `bin/lib/init.mjs`
-- `distilled/workflows/execute.md`, `distilled/workflows/verify.md`
+- `distilled/workflows/plan.md`, `distilled/workflows/execute.md`, `distilled/workflows/verify.md`
 - `distilled/workflows/audit-milestone.md`, `distilled/workflows/complete-milestone.md`
 - `distilled/workflows/new-milestone.md`, `distilled/workflows/resume.md`, `distilled/workflows/progress.md`
-- `tests/phase.test.cjs`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.scenarios.test.cjs`
+- `tests/phase.test.cjs`, `tests/session-fingerprint.test.cjs`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.scenarios.test.cjs`
 - `get-shit-done/workflows/progress.md`
 
 ## D50 — Evidence-Gated Closure Matrix