gsdd-cli 0.20.0 → 0.21.0

package/bin/lib/init-runtime.mjs

@@ -186,9 +186,12 @@ 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
+  session-fingerprint write [--allow-changed <ROADMAP.md,SPEC.md,config.json>]
+                              Rebaseline planning-state drift after reviewing changed planning files
   ui-proof validate <path> [--claim <public|publication|tracked|delivery|release>]
                               Validate UI proof metadata; use --claim for stronger proof uses
+  ui-proof compare <planned-slots-json> [observed-bundle-json ...]
+                              Compare planned UI proof slots against observed bundles
   help                        Show this summary
 
 Platforms (for --tools):
@@ -259,7 +262,7 @@ Advanced/internal helpers (kept available, but not the primary first-run user st
   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
-  ui-proof                  Validate UI proof metadata; use --claim for stronger proof uses
+  ui-proof                  Validate UI proof metadata and compare planned slots to observed bundles
   file-op                   Deterministic workspace-confined file copy/delete/text mutation
 `;
 }

package/bin/lib/lifecycle-preflight.mjs

@@ -52,6 +52,11 @@ const SURFACE_POLICIES = {
     ownedWrites: ['spec', 'roadmap', 'phase-directories'],
     explicitLifecycleMutation: 'none',
   },
+  'plan-milestone-gaps': {
+    classification: 'owned_write',
+    ownedWrites: ['roadmap', 'phase-directories'],
+    explicitLifecycleMutation: 'none',
+  },
   resume: {
     classification: 'owned_write',
     ownedWrites: ['checkpoint-cleanup'],

package/bin/lib/rendering.mjs

@@ -72,10 +72,12 @@ 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',
+    '  session-fingerprint write [--allow-changed <ROADMAP.md,SPEC.md,config.json>]',
     '                               Rebaseline planning-state drift after reviewing changed planning files',
     '  ui-proof validate <path> [--claim <public|publication|tracked|delivery|release>]',
     '                               Validate UI proof metadata; use --claim for stronger proof uses',
+    '  ui-proof compare <planned-slots-json> [observed-bundle-json ...]',
+    '                               Compare planned UI proof slots against observed bundles',
     '',
     'Advanced option:',
     '  --workspace-root <path>     Override workspace root discovery before or after the subcommand',

package/bin/lib/session-fingerprint.mjs

@@ -63,16 +63,56 @@ export function cmdSessionFingerprint(...args) {
     return;
   }
 
-  const [action] = normalizedArgs;
+  const [action, ...flags] = normalizedArgs;
   if (action !== 'write') {
-    console.error('Usage: node .planning/bin/gsdd.mjs session-fingerprint write');
+    console.error('Usage: node .planning/bin/gsdd.mjs session-fingerprint write [--allow-changed <ROADMAP.md,SPEC.md,config.json>]');
     process.exitCode = 1;
     return;
   }
 
+  const allowChanged = parseAllowChanged(flags);
+  if (allowChanged.invalid) {
+    console.error('Usage: node .planning/bin/gsdd.mjs session-fingerprint write [--allow-changed <ROADMAP.md,SPEC.md,config.json>]');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (allowChanged.files.length > 0) {
+    const drift = checkDrift(planningDir);
+    const changedFiles = drift.files.filter((file) => file.status !== 'unchanged').map((file) => file.file);
+    const unexpected = changedFiles.filter((file) => !allowChanged.files.includes(file));
+    if (unexpected.length > 0) {
+      output({
+        operation: 'session-fingerprint write',
+        changedFiles,
+        allowedChanged: allowChanged.files,
+        written: false,
+        reason: 'unexpected_planning_drift',
+        unexpected,
+      });
+      process.exitCode = 1;
+      return;
+    }
+  }
+
   output({ operation: 'session-fingerprint write', fingerprint: writeFingerprint(planningDir) });
 }
 
+function parseAllowChanged(flags) {
+  const files = [];
+  for (let index = 0; index < flags.length; index += 1) {
+    if (flags[index] !== '--allow-changed') return { invalid: true, files: [] };
+    const value = flags[index + 1];
+    if (!value || value.startsWith('--')) return { invalid: true, files: [] };
+    files.push(...value.split(',').map((entry) => entry.trim()).filter(Boolean));
+    index += 1;
+  }
+  for (const file of files) {
+    if (!FINGERPRINT_SOURCES.includes(file)) return { invalid: true, files: [] };
+  }
+  return { invalid: false, files: [...new Set(files)] };
+}
+
 /**
  * Read the stored fingerprint from .planning/.state-fingerprint.json.
  * Returns null if the file does not exist or is unparseable.

package/bin/lib/ui-proof.mjs

@@ -305,6 +305,301 @@ function validateObservationArtifactRefs(bundle, artifactRefs, errors) {
   }
 }
 
+function stableString(value) {
+  return JSON.stringify(canonicalize(value));
+}
+
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (!isPlainObject(value)) return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]));
+}
+
+function valuesMatch(planned, observed) {
+  if (!hasValue(planned)) return true;
+  if (!hasValue(observed)) return false;
+  return stableString(planned) === stableString(observed);
+}
+
+function slotId(slot, index) {
+  return slot?.slot_id || slot?.slotId || slot?.id || `ui-proof-slot-${index + 1}`;
+}
+
+function observationText(observation) {
+  if (typeof observation === 'string') return observation;
+  if (isPlainObject(observation) && typeof observation.observation === 'string') return observation.observation;
+  return '';
+}
+
+function includesObservation(observations, expected) {
+  const expectedText = typeof expected === 'string' ? expected.trim() : observationText(expected).trim();
+  if (!expectedText) return true;
+  return observations.some((observation) => observationText(observation).includes(expectedText));
+}
+
+function normalizeObservedBundle(entry) {
+  if (entry?.bundle) {
+    return {
+      bundle: entry.bundle,
+      validation: entry.validation || validateUiProofBundle(entry.bundle, entry.options || {}),
+      source: entry.source || entry.filePath || 'observed bundle',
+    };
+  }
+  return {
+    bundle: entry,
+    validation: validateUiProofBundle(entry),
+    source: 'observed bundle',
+  };
+}
+
+function compareSlotToBundle(slot, slotIdValue, observed) {
+  const issues = [];
+  const bundle = observed.bundle;
+  const observations = normalizeArray(bundle?.observations);
+  if (!observed.validation.valid) {
+    issues.push({
+      code: 'invalid_observed_bundle',
+      path: observed.source,
+      message: `Observed UI proof bundle for slot ${slotIdValue} failed metadata validation.`,
+      details: observed.validation.errors,
+    });
+  }
+
+  const bundleStatus = bundle?.result?.comparison_status_by_slot?.[slotIdValue];
+  if (bundle?.result?.claim_status !== 'passed') {
+    issues.push({
+      code: 'unsatisfied_observed_claim_status',
+      path: 'result.claim_status',
+      message: `Observed UI proof bundle claim status is ${bundle?.result?.claim_status || 'missing'} for slot ${slotIdValue}.`,
+    });
+  }
+  if (bundleStatus !== 'satisfied') {
+    issues.push({
+      code: 'unsatisfied_observed_comparison_status',
+      path: `result.comparison_status_by_slot.${slotIdValue}`,
+      message: `Observed UI proof bundle reports ${bundleStatus || 'missing'} for slot ${slotIdValue}.`,
+    });
+  }
+
+  const requiredKinds = normalizeArray(slot?.required_evidence_kinds || slot?.requiredEvidenceKinds);
+  const observedKinds = normalizeArray(bundle?.evidence_inputs?.kinds);
+  const missingKinds = requiredKinds.filter((kind) => !observedKinds.includes(kind));
+  if (missingKinds.length > 0) {
+    issues.push({
+      code: 'missing_required_evidence_kind',
+      path: 'evidence_inputs.kinds',
+      message: `Observed UI proof for slot ${slotIdValue} is missing required evidence kind(s): ${missingKinds.join(', ')}.`,
+    });
+  }
+  const missingNonHuman = missingKinds.filter((kind) => kind !== 'human');
+  if (missingNonHuman.length > 0 && observedKinds.includes('human')) {
+    issues.push({
+      code: 'human_evidence_cannot_bypass_required_non_human_evidence',
+      path: 'evidence_inputs.kinds',
+      message: `Human evidence cannot satisfy missing non-human UI proof evidence for slot ${slotIdValue}: ${missingNonHuman.join(', ')}.`,
+    });
+  }
+
+  if (!valuesMatch(slot?.route_state || slot?.routeState, bundle?.route_state)) {
+    issues.push({
+      code: 'route_state_mismatch',
+      path: 'route_state',
+      message: `Observed UI proof route/state does not match planned slot ${slotIdValue}.`,
+    });
+  }
+
+  if (!valuesMatch(slot?.environment, bundle?.environment)) {
+    issues.push({
+      code: 'environment_mismatch',
+      path: 'environment',
+      message: `Observed UI proof environment does not match planned slot ${slotIdValue}.`,
+    });
+  }
+
+  if (!valuesMatch(slot?.viewport, bundle?.viewport)) {
+    issues.push({
+      code: 'viewport_mismatch',
+      path: 'viewport',
+      message: `Observed UI proof viewport does not match planned slot ${slotIdValue}.`,
+    });
+  }
+
+  const requirementId = slot?.requirement_id || slot?.requirementId;
+  if (hasValue(requirementId) && !normalizeArray(bundle?.scope?.requirement_ids).includes(requirementId)) {
+    issues.push({
+      code: 'requirement_mismatch',
+      path: 'scope.requirement_ids',
+      message: `Observed UI proof bundle does not declare planned requirement ${requirementId} for slot ${slotIdValue}.`,
+    });
+  }
+
+  if (hasValue(slot?.claim) && bundle?.scope?.claim !== slot.claim) {
+    issues.push({
+      code: 'claim_mismatch',
+      path: 'scope.claim',
+      message: `Observed UI proof bundle claim does not match planned slot ${slotIdValue}.`,
+    });
+  }
+
+  if (hasValue(slot?.claim) && !observations.some((observation) => observation?.claim === slot.claim)) {
+    issues.push({
+      code: 'observation_claim_mismatch',
+      path: 'observations[].claim',
+      message: `Observed UI proof observations do not support the exact planned claim for slot ${slotIdValue}.`,
+    });
+  }
+
+  const supportingObservations = observations
+    .map((observation, index) => ({ observation, index }))
+    .filter(({ observation }) => !hasValue(slot?.claim) || observation?.claim === slot.claim);
+
+  if (hasValue(slot?.route_state || slot?.routeState)) {
+    for (const { observation, index } of supportingObservations) {
+      if (!valuesMatch(slot?.route_state || slot?.routeState, observation?.route_state)) {
+        issues.push({
+          code: 'observation_route_state_mismatch',
+          path: `observations[${index}].route_state`,
+          message: `Observed UI proof observation route/state does not match planned slot ${slotIdValue}.`,
+        });
+      }
+    }
+  }
+
+  const passedSupportingKinds = new Set(
+    supportingObservations
+      .filter(({ observation }) => observation?.result === 'passed')
+      .map(({ observation }) => observation?.evidence_kind)
+      .filter(Boolean)
+  );
+  const missingSupportingKinds = requiredKinds.filter((kind) => !passedSupportingKinds.has(kind));
+  if (missingSupportingKinds.length > 0) {
+    issues.push({
+      code: 'missing_supporting_observation_evidence_kind',
+      path: 'observations[].evidence_kind',
+      message: `Observed UI proof for slot ${slotIdValue} lacks passed supporting observation(s) for required evidence kind(s): ${missingSupportingKinds.join(', ')}.`,
+    });
+  }
+
+  for (const [index, step] of normalizeArray(bundle?.commands_or_manual_steps).entries()) {
+    if (step?.result !== 'passed') {
+      issues.push({
+        code: 'unsatisfied_proof_step',
+        path: `commands_or_manual_steps[${index}].result`,
+        message: `Observed UI proof command/manual step is ${step?.result || 'missing'} for slot ${slotIdValue}.`,
+      });
+    }
+  }
+
+  const manualAcceptanceRequired = slot?.manual_acceptance_required === true || slot?.manualAcceptanceRequired === true;
+  if (manualAcceptanceRequired) {
+    if (!observedKinds.includes('human')) {
+      issues.push({
+        code: 'missing_manual_acceptance_evidence',
+        path: 'evidence_inputs.kinds',
+        message: `Observed UI proof for slot ${slotIdValue} is missing required human evidence for manual acceptance.`,
+      });
+    }
+    if (!passedSupportingKinds.has('human')) {
+      issues.push({
+        code: 'missing_manual_acceptance_observation',
+        path: 'observations[].evidence_kind',
+        message: `Observed UI proof for slot ${slotIdValue} lacks a passed human observation for manual acceptance.`,
+      });
+    }
+  }
+
+  for (const { observation, index } of supportingObservations) {
+    if (observation?.result !== 'passed') {
+      issues.push({
+        code: 'unsatisfied_observation_result',
+        path: `observations[${index}].result`,
+        message: `Observed UI proof observation is ${observation?.result || 'missing'} for slot ${slotIdValue}.`,
+      });
+    }
+  }
+
+  for (const expected of normalizeArray(slot?.minimum_observations || slot?.minimumObservations)) {
+    if (!includesObservation(supportingObservations.map(({ observation }) => observation), expected)) {
+      issues.push({
+        code: 'missing_minimum_observation',
+        path: 'observations',
+        message: `Observed UI proof for slot ${slotIdValue} is missing a planned minimum observation.`,
+      });
+    }
+  }
+
+  if (hasValue(slot?.claim_limit || slot?.claimLimit)) {
+    const claimLimit = slot.claim_limit || slot.claimLimit;
+    if (!normalizeArray(bundle?.claim_limits).includes(claimLimit)) {
+      issues.push({
+        code: 'missing_claim_limit',
+        path: 'claim_limits',
+        message: `Observed UI proof for slot ${slotIdValue} does not preserve the planned claim limit.`,
+      });
+    }
+  }
+
+  const status = issues.length === 0 ? 'satisfied' : (bundleStatus === 'missing' ? 'missing' : 'partial');
+  return { status, issues, source: observed.source };
+}
+
+export function compareUiProofSlots(plannedSlots, observedBundles) {
+  const slots = normalizeArray(plannedSlots);
+  const bundles = normalizeArray(observedBundles).map(normalizeObservedBundle);
+  const results = [];
+  const errors = [];
+
+  for (const observed of bundles) {
+    if (!observed.validation.valid) {
+      errors.push({
+        code: 'invalid_observed_bundle',
+        path: observed.source,
+        message: `Observed UI proof bundle ${observed.source} failed metadata validation.`,
+        details: observed.validation.errors,
+      });
+    }
+  }
+
+  for (const [index, slot] of slots.entries()) {
+    const slotIdValue = slotId(slot, index);
+    const matchingBundles = bundles.filter((observed) => normalizeArray(observed.bundle?.scope?.slot_ids).includes(slotIdValue));
+    if (matchingBundles.length === 0) {
+      results.push({
+        slot_id: slotIdValue,
+        status: 'missing',
+        issues: [{
+          code: 'missing_observed_bundle',
+          path: 'scope.slot_ids',
+          message: `No observed UI proof bundle declares planned slot ${slotIdValue}.`,
+        }],
+      });
+      continue;
+    }
+
+    const candidates = matchingBundles.map((observed) => compareSlotToBundle(slot, slotIdValue, observed));
+    const satisfied = candidates.find((candidate) => candidate.status === 'satisfied');
+    if (satisfied) {
+      results.push({ slot_id: slotIdValue, status: 'satisfied', issues: [], source: satisfied.source });
+      continue;
+    }
+    const partial = candidates.find((candidate) => candidate.status === 'partial') || candidates[0];
+    results.push({ slot_id: slotIdValue, status: partial.status, issues: partial.issues, source: partial.source });
+  }
+
+  const statuses = results.map((result) => result.status);
+  const status = errors.length > 0
+    ? 'partial'
+    : statuses.length === 0
+    ? 'not_applicable'
+    : statuses.every((value) => value === 'satisfied')
+      ? 'satisfied'
+      : statuses.every((value) => value === 'missing')
+        ? 'missing'
+        : 'partial';
+
+  return { status, slots: results, errors };
+}
+
 export function validateUiProofBundle(bundle, options = {}) {
   const errors = [];
   const warnings = [];
@@ -332,10 +627,10 @@ export function validateUiProofBundle(bundle, options = {}) {
   return { valid: errors.length === 0, errors, warnings };
 }
 
-export function parseUiProofBundleContent(content, filePath = 'UI proof bundle') {
+function parseJsonOrFencedContent(content, filePath, label) {
   const trimmed = content.trim();
   if (!trimmed) {
-    return { bundle: null, errors: [{ code: 'empty_bundle_file', path: filePath, message: 'UI proof bundle file is empty.', fix: 'Write JSON UI proof metadata before validating.' }] };
+    return { value: null, errors: [{ code: 'empty_file', path: filePath, message: `${label} file is empty.`, fix: 'Write JSON metadata before validating.' }] };
   }
 
   const jsonCandidates = [trimmed];
@@ -344,18 +639,58 @@ export function parseUiProofBundleContent(content, filePath = 'UI proof bundle')
 
   for (const candidate of jsonCandidates) {
     try {
-      return { bundle: JSON.parse(candidate), errors: [] };
+      return { value: JSON.parse(candidate), errors: [] };
     } catch {
       // Try next candidate; final error is reported below.
     }
   }
 
   return {
-    bundle: null,
-    errors: [{ code: 'unparseable_bundle', path: filePath, message: 'UI proof bundle metadata is not valid JSON.', fix: 'Use a .json proof bundle or a markdown fenced JSON block; no YAML parser dependency is installed.' }],
+    value: null,
+    errors: [{ code: 'unparseable_json', path: filePath, message: `${label} metadata is not valid JSON.`, fix: 'Use a .json file or a markdown fenced JSON block; no YAML parser dependency is installed.' }],
   };
 }
 
+export function parseUiProofBundleContent(content, filePath = 'UI proof bundle') {
+  const parsed = parseJsonOrFencedContent(content, filePath, 'UI proof bundle');
+  return { bundle: parsed.value, errors: parsed.errors.map((error) => ({
+    ...error,
+    code: error.code === 'empty_file' ? 'empty_bundle_file' : error.code === 'unparseable_json' ? 'unparseable_bundle' : error.code,
+    message: error.code === 'empty_file'
+      ? 'UI proof bundle file is empty.'
+      : error.code === 'unparseable_json'
+        ? 'UI proof bundle metadata is not valid JSON.'
+        : error.message,
+    fix: error.code === 'empty_file'
+      ? 'Write JSON UI proof metadata before validating.'
+      : error.fix,
+  })) };
+}
+
+export function parseUiProofSlotsContent(content, filePath = 'UI proof slots') {
+  const parsed = parseJsonOrFencedContent(content, filePath, 'UI proof slots');
+  if (parsed.errors.length > 0) return { slots: [], errors: parsed.errors };
+
+  const value = parsed.value;
+  const slots = Array.isArray(value)
+    ? value
+    : normalizeArray(value?.ui_proof_slots || value?.uiProofSlots || value?.planned_slots || value?.plannedSlots);
+
+  if (slots.length === 0) {
+    return {
+      slots: [],
+      errors: [{
+        code: 'missing_planned_slots',
+        path: filePath,
+        message: 'Planned UI proof input must be an array or contain ui_proof_slots.',
+        fix: 'Provide JSON with an array of planned slots or an object with ui_proof_slots.',
+      }],
+    };
+  }
+
+  return { slots, errors: [] };
+}
+
 export function readUiProofBundleFile(filePath) {
   return parseUiProofBundleContent(readFileSync(filePath, 'utf-8'), filePath);
 }
@@ -434,6 +769,50 @@ function cmdValidate(cwd, args) {
   if (!validation.valid) process.exitCode = 1;
 }
 
+function cmdCompare(cwd, args) {
+  const [plannedArg, ...observedArgs] = args;
+  if (!plannedArg) fail('Usage: gsdd ui-proof compare <planned-slots-json> [observed-bundle-json ...]');
+
+  const plannedPath = resolveWorkspacePath(cwd, plannedArg);
+  if (!existsSync(plannedPath) || statSync(plannedPath).isDirectory()) fail(`Planned UI proof slots file does not exist: ${plannedArg}`);
+
+  const planned = parseUiProofSlotsContent(readFileSync(plannedPath, 'utf-8'), plannedArg);
+  const observedBundles = [];
+  const observedTargets = [];
+  const observedErrors = [];
+
+  for (const observedArg of observedArgs) {
+    const observedPath = resolveWorkspacePath(cwd, observedArg);
+    if (!existsSync(observedPath) || statSync(observedPath).isDirectory()) fail(`Observed UI proof bundle file does not exist: ${observedArg}`);
+    const parsed = readUiProofBundleFile(observedPath);
+    if (parsed.errors.length > 0) {
+      observedErrors.push(...parsed.errors.map((error) => ({ ...error, path: observedArg })));
+      observedBundles.push({
+        bundle: {},
+        validation: { valid: false, errors: parsed.errors, warnings: [] },
+        source: observedArg,
+      });
+    } else {
+      observedBundles.push({ bundle: parsed.bundle, source: observedArg });
+    }
+    observedTargets.push(observedArg);
+  }
+
+  const comparison = planned.errors.length > 0
+    ? { status: 'missing', slots: [], errors: planned.errors }
+    : compareUiProofSlots(planned.slots, observedBundles);
+
+  output({
+    operation: 'ui-proof compare',
+    planned: plannedArg,
+    observed: observedTargets,
+    status: comparison.status,
+    slots: comparison.slots,
+    errors: [...(comparison.errors || []), ...observedErrors],
+  });
+  if (!['satisfied', 'not_applicable'].includes(comparison.status)) process.exitCode = 1;
+}
+
 export function cmdUiProof(...args) {
   const { args: normalizedArgs, workspaceRoot, invalid, error } = resolveWorkspaceContext(args);
   if (invalid) {
@@ -447,8 +826,11 @@ export function cmdUiProof(...args) {
       case 'validate':
         cmdValidate(workspaceRoot, rest);
         return;
+      case 'compare':
+        cmdCompare(workspaceRoot, rest);
+        return;
       default:
-        fail('Usage: gsdd ui-proof validate <path> [--claim <public|publication|tracked|delivery|release>]');
+        fail('Usage: gsdd ui-proof <validate|compare> ...');
     }
   } catch (error) {
     if (error instanceof UiProofError) {

package/distilled/templates/ui-proof.md

@@ -152,7 +152,7 @@ Bundle rules:
 
 ## Deterministic Validation
 
-Use `gsdd ui-proof validate <path>` on JSON proof-bundle metadata or markdown fenced JSON before relying on a bundle for closure; add `--claim <public|publication|tracked|delivery|release>` only when validating that stronger proof use. Required observed-bundle top-level fields are `proof_bundle_version`, `scope`, `route_state`, `environment`, `viewport`, `evidence_inputs`, `commands_or_manual_steps`, `observations`, `artifacts`, `privacy`, `result`, and `claim_limits`. The validator checks required bundle and observation fields, structured command/manual-step entries, fixed evidence kinds, `result.claim_status`, observation `result`, comparison statuses, non-empty claim limits, locked artifact and observation privacy fields, observation-to-artifact references, workspace-relative/http(s) artifact references, and explicit public/tracked/delivery proof claims that rely on local-only, unsafe, unsanitized, or privacy-contradictory artifacts. `claim_status`, observation `result`, and command/manual-step `result` use `passed`, `failed`, `partial`, `waived`, `deferred`, or `not_applicable`. It is metadata-only and does not inspect raw screenshot, trace, video, DOM, or report contents.
+Use `gsdd ui-proof validate <path>` on JSON proof-bundle metadata or markdown fenced JSON before relying on a bundle for closure; add `--claim <public|publication|tracked|delivery|release>` only when validating that stronger proof use. Use `gsdd ui-proof compare <planned-slots-json> [observed-bundle-json ...]` when verifying planned proof slots against observed bundles through the deterministic product-facing path. Required observed-bundle top-level fields are `proof_bundle_version`, `scope`, `route_state`, `environment`, `viewport`, `evidence_inputs`, `commands_or_manual_steps`, `observations`, `artifacts`, `privacy`, `result`, and `claim_limits`. The validator checks required bundle and observation fields, structured command/manual-step entries, fixed evidence kinds, `result.claim_status`, observation `result`, comparison statuses, non-empty claim limits, locked artifact and observation privacy fields, observation-to-artifact references, workspace-relative/http(s) artifact references, and explicit public/tracked/delivery proof claims that rely on local-only, unsafe, unsanitized, or privacy-contradictory artifacts. `claim_status`, observation `result`, and command/manual-step `result` use `passed`, `failed`, `partial`, `waived`, `deferred`, or `not_applicable`. It is metadata-only and does not inspect raw screenshot, trace, video, DOM, or report contents.
 
 ## Comparison Statuses
 

package/distilled/workflows/plan-milestone-gaps.md

@@ -15,6 +15,18 @@ If no audit file exists: stop and direct the user to run `/gsdd-audit-milestone`
 If audit status is `passed`: stop and direct the user to run `/gsdd-complete-milestone` instead.
 </prerequisites>
 
+<repo_root_helper_contract>
+All `node .planning/bin/gsdd.mjs ...` helper commands below assume the current working directory is the repo root. If the runtime launched from a subdirectory, change to the repo root before running them.
+</repo_root_helper_contract>
+
+<lifecycle_preflight>
+Before writing ROADMAP gap-closure phases or phase directories, run:
+
+- `node .planning/bin/gsdd.mjs lifecycle-preflight plan-milestone-gaps`
+
+If the preflight result is `blocked`, STOP and report the blocker. This workflow intentionally mutates planning truth, so it must not proceed through pre-existing planning-state drift.
+</lifecycle_preflight>
+
 <load_context>
 Before starting, read these files:
 
@@ -144,6 +156,14 @@ Create a directory for each gap closure phase:
 
 No files inside — `/gsdd-plan` populates them.
 
+## 8. Rebaseline Planning Fingerprint
+
+After confirming the ROADMAP update and phase directories exist, run:
+
+- `node .planning/bin/gsdd.mjs session-fingerprint write --allow-changed ROADMAP.md`
+
+This records the user-confirmed ROADMAP mutation so the recommended `/gsdd-plan [N]` handoff does not immediately block on expected `planning_state_drift`. The `--allow-changed ROADMAP.md` guard must fail if `SPEC.md` or `config.json` also drifted after preflight; stop and reconcile that unexpected drift instead of rebaselining it. Do not run this if the ROADMAP write failed or the phase directories are missing.
+
 </process>
 
 <success_criteria>
@@ -155,6 +175,7 @@ No files inside — `/gsdd-plan` populates them.
 - [ ] User confirmed gap closure plan before ROADMAP.md was updated
 - [ ] ROADMAP.md updated with new gap closure phases
 - [ ] Phase directories created
+- [ ] `session-fingerprint write` ran after the reviewed ROADMAP update so `/gsdd-plan [N]` is not stranded by expected planning drift
 </success_criteria>
 
 **MANDATORY: `.planning/ROADMAP.md` must be updated on disk before this workflow is complete. If the write fails, STOP and report the failure. Without the updated ROADMAP, the phase cycle cannot begin.**

package/distilled/workflows/verify.md

@@ -129,7 +129,7 @@ Note: this step does NOT replace levels 1–3. An artifact can satisfy the evide
 </evidence_contract>
 
 <ui_proof_comparison>
-If the plan defines non-empty `ui_proof_slots`, compare planned UI proof against observed bundles before closure. If the plan records only `no_ui_proof_rationale`, verify the rationale instead of requiring a bundle. Each observed bundle must include top-level `proof_bundle_version`, `scope`, `route_state`, `environment`, `viewport`, `evidence_inputs`, `commands_or_manual_steps`, `observations`, `artifacts`, `privacy`, `result`, and `claim_limits`.
+If the plan defines non-empty `ui_proof_slots`, compare planned UI proof against observed bundles before closure. Prefer `gsdd ui-proof compare <planned-slots-json> [observed-bundle-json ...]` when planned slots are available as JSON or fenced JSON; otherwise perform the same field-by-field comparison and record reduced assurance if no deterministic command could run. If the plan records only `no_ui_proof_rationale`, verify the rationale instead of requiring a bundle. Each observed bundle must include top-level `proof_bundle_version`, `scope`, `route_state`, `environment`, `viewport`, `evidence_inputs`, `commands_or_manual_steps`, `observations`, `artifacts`, `privacy`, `result`, and `claim_limits`.
 Classify each slot as exactly one of: `satisfied`, `partial`, `missing`, `waived`, `deferred`, or `not_applicable`. Waiver/deferment narrows the claim; it is not proof. Screenshots, traces, videos, reports, accessibility scans, Gherkin, visual diffs, and manual notes are artifact types or activities mapped onto existing evidence kinds, not new evidence kinds. Artifact count is never proof; each artifact must tie to the slot claim, route/state, observation, artifact path/link, privacy metadata, and claim limit.
 Artifact privacy metadata must include `visibility`, `retention`, `sensitivity`, and `safe_to_publish`; raw screenshots, traces, videos, DOM snapshots, and reports default to local-only and unsafe unless sanitized. Run `gsdd ui-proof validate <path>` or treat `gsdd health` E10 as blocking; add `--claim <...>` when relying on the bundle for public, tracked, delivery, release, or publication proof. Visual taste, accessibility judgment, baseline acceptance, subjective polish/layout quality, and privacy publication require human evidence or explicit waiver; human approval does not replace required `code`, `test`, `runtime`, or `delivery` evidence. Source annotations, AST/cAST findings, semantic search, comments, and Semble-like retrieval are discovery hints only.
 </ui_proof_comparison>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsdd-cli",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Workspine — a repo-native delivery spine for long-horizon AI-assisted work, with directly validated support for Claude Code, Codex CLI, and OpenCode, published as gsdd-cli.",
   "type": "module",
   "bin": {