gsdd-cli 0.24.0 → 0.25.0

package/bin/lib/health.mjs

@@ -14,21 +14,19 @@ import { findUiProofBundleFiles, readUiProofBundleFile, validateUiProofBundle }
 import { resolveWorkspaceContext } from './workspace-root.mjs';
 
 /**
- * Factory function returning the health command.
- * ctx should provide: { frameworkVersion, workflows }
+ * Build the structured health report without printing or mutating workspace
+ * state. ctx should provide: { frameworkVersion, workflows }.
  */
-export function createCmdHealth(ctx) {
-  return async function cmdHealth(...healthArgs) {
-    const jsonMode = healthArgs.includes('--json');
+export function buildHealthReport(ctx, healthArgs = []) {
     const { planningDir, workspaceRoot, invalid, error } = resolveWorkspaceContext(healthArgs);
     if (invalid) {
-      if (jsonMode) {
-        output({ status: 'broken', errors: [{ id: 'E1', severity: 'ERROR', message: error, fix: 'Pass --workspace-root with a real path or remove the flag.' }], warnings: [], info: [] });
-      } else {
-        console.log(error);
-      }
-      process.exitCode = 1;
-      return;
+      return {
+        status: 'broken',
+        errors: [{ id: 'E1', severity: 'ERROR', message: error, fix: 'Pass --workspace-root with a real path or remove the flag.' }],
+        warnings: [],
+        info: [],
+        humanMessage: error,
+      };
     }
     const cwd = workspaceRoot;
     const frameworkSourceMode = isFrameworkSourceRepo(cwd);
@@ -36,13 +34,13 @@ export function createCmdHealth(ctx) {
 
     // Pre-init guard
     if (!existsSync(join(planningDir, 'config.json'))) {
-      if (jsonMode) {
-        output({ status: 'broken', errors: [{ id: 'E1', severity: 'ERROR', message: '.planning/config.json missing', fix: 'Run `npx -y gsdd-cli init`' }], warnings: [], info: [] });
-      } else {
-        console.log('Not initialized. Run `npx -y gsdd-cli init`. If `gsdd` is installed globally, `gsdd init` is also fine.');
-      }
-      process.exitCode = 1;
-      return;
+      return {
+        status: 'broken',
+        errors: [{ id: 'E1', severity: 'ERROR', message: '.planning/config.json missing', fix: 'Run `npx -y gsdd-cli init`' }],
+        warnings: [],
+        info: [],
+        humanMessage: 'Not initialized. Run `npx -y gsdd-cli init`. If `gsdd` is installed globally, `gsdd init` is also fine.',
+      };
     }
 
     const errors = [];
@@ -272,22 +270,41 @@ export function createCmdHealth(ctx) {
     const hasWarnings = warnings.length > 0;
     const status = hasErrors ? 'broken' : hasWarnings ? 'degraded' : 'healthy';
 
-    if (hasErrors) process.exitCode = 1;
+    return { status, errors, warnings, info };
+}
+/**
+ * Factory function returning the health command.
+ * ctx should provide: { frameworkVersion, workflows }
+ */
+export function createCmdHealth(ctx) {
+  return async function cmdHealth(...healthArgs) {
+    const jsonMode = healthArgs.includes('--json');
+    const report = buildHealthReport(ctx, healthArgs);
+    const printableReport = {
+      status: report.status,
+      errors: report.errors,
+      warnings: report.warnings,
+      info: report.info,
+    };
+
+    if (report.status === 'broken') process.exitCode = 1;
 
     if (jsonMode) {
-      output({ status, errors, warnings, info });
+      output(printableReport);
+    } else if (report.humanMessage) {
+      console.log(report.humanMessage);
     } else {
-      console.log(`\ngsdd health — workspace integrity check\n`);
-      if (errors.length > 0) {
-        for (const e of errors) console.log(`  ERROR: [${e.id}] ${e.message}\n    Fix: ${e.fix}`);
+      console.log(`\ngsdd health - workspace integrity check\n`);
+      if (report.errors.length > 0) {
+        for (const e of report.errors) console.log(`  ERROR: [${e.id}] ${e.message}\n    Fix: ${e.fix}`);
       }
-      if (warnings.length > 0) {
-        for (const w of warnings) console.log(`  WARN:  [${w.id}] ${w.message}\n    Fix: ${w.fix}`);
+      if (report.warnings.length > 0) {
+        for (const w of report.warnings) console.log(`  WARN:  [${w.id}] ${w.message}\n    Fix: ${w.fix}`);
       }
-      if (info.length > 0) {
-        for (const i of info) console.log(`  INFO:  [${i.id}] ${i.message}${i.fix ? `\n    Fix: ${i.fix}` : ''}`);
+      if (report.info.length > 0) {
+        for (const i of report.info) console.log(`  INFO:  [${i.id}] ${i.message}${i.fix ? `\n    Fix: ${i.fix}` : ''}`);
       }
-      console.log(`\n  Verdict: ${status.toUpperCase()}\n`);
+      console.log(`\n  Verdict: ${report.status.toUpperCase()}\n`);
     }
   };
 }

package/bin/lib/init-runtime.mjs

@@ -194,6 +194,10 @@ Commands:
                               Compare planned UI proof slots against observed bundles
   control-map [--json] [--with-ignored] [--annotations <path>]
                               Report computed repo/worktree/planning state and local annotations
+  control-map annotate <set|clear>
+                              Maintain optional local intent annotations under .planning/.local/
+  closeout-report [--json] [--phase <N>]
+                              Replay read-only closeout status from control-map, health, preflight, verify, and UI-proof signals
   help                        Show this summary
 
 Platforms (for --tools):
@@ -237,6 +241,8 @@ Examples:
   npx -y gsdd-cli update
   npx -y gsdd-cli find-phase
   npx -y gsdd-cli verify 1
+  npx -y gsdd-cli control-map annotate set --id canonical --write-set src/app.ts
+  npx -y gsdd-cli control-map annotate clear --id canonical
   npx -y gsdd-cli scaffold phase 4 Payments
 
 Workflows (run via skills/adapters generated by init, not direct CLI):
@@ -265,7 +271,8 @@ Advanced/internal helpers (kept available, but not the primary first-run user st
   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 and compare planned slots to observed bundles
-  control-map               Report computed repo/worktree/planning state and local annotations
+  control-map               Report computed repo/worktree/planning state; annotate only records local intent
+  closeout-report           Read-only post-merge closure replay; reports blockers, warnings, and next safe action
   file-op                   Deterministic workspace-confined file copy/delete/text mutation
 `;
 }

package/bin/lib/lifecycle-preflight.mjs

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'fs';
-import { join } from 'path';
+import { join, resolve } from 'path';
 import { output } from './cli-utils.mjs';
+import { buildControlMap } from './control-map.mjs';
 import {
   DELIVERY_POSTURES,
   EVIDENCE_KINDS,
@@ -74,12 +75,14 @@ const RELEASE_CONTRADICTION_CHECKS = Object.freeze([
 ]);
 
 const RELEASE_CONTRADICTION_STATUSES = Object.freeze(['passed', 'failed', 'not_applicable']);
+const PREFLIGHT_CONTROL_MAP_SKIP_CODES = Object.freeze(['planning_state_drift']);
 
 export function evaluateLifecyclePreflight({
   planningDir,
   surface,
   phaseNumber = null,
   expectsMutation = 'none',
+  controlMapReport = null,
 } = {}) {
   if (!planningDir) {
     throw new Error('planningDir is required');
@@ -184,6 +187,17 @@ export function evaluateLifecyclePreflight({
     }
   }
 
+  const controlMap = buildPreflightControlMap({
+    planningDir,
+    policy,
+    existingBlockerCodes: new Set(blockers.map((entry) => entry.code)),
+    controlMapReport,
+  });
+  for (const notice of controlMap.notices) {
+    if (notice.severity === 'block') blockers.push(notice);
+    else warnings.push(notice);
+  }
+
   if (lifecycle.phaseStatusAlignment.mismatches.length > 0) {
     warnings.push({
       code: 'roadmap_phase_status_mismatch',
@@ -206,6 +220,7 @@ export function evaluateLifecyclePreflight({
     blockers,
     warnings,
     planningState,
+    controlMap: controlMap.summary,
     lifecycle: {
       currentMilestone: lifecycle.currentMilestone,
       currentPhase: lifecycle.currentPhase ? lifecycle.currentPhase.number : null,
@@ -215,6 +230,48 @@ export function evaluateLifecyclePreflight({
   };
 }
 
+function buildPreflightControlMap({ planningDir, policy, existingBlockerCodes, controlMapReport = null }) {
+  const empty = {
+    summary: null,
+    notices: [],
+  };
+  if (policy.classification !== 'owned_write' || !existsSync(planningDir)) return empty;
+
+  const map = controlMapReport || buildControlMap({
+    workspaceRoot: resolve(planningDir, '..'),
+    planningDir,
+  });
+  const risks = (map.risks || []).filter((risk) => (
+    !PREFLIGHT_CONTROL_MAP_SKIP_CODES.includes(risk.code)
+    && !(existingBlockerCodes.has(risk.code) && risk.severity !== 'block')
+  ));
+  const notices = risks.map((risk) => ({
+    ...controlMapNotice(risk),
+    severity: risk.severity || 'info',
+  }));
+
+  return {
+    summary: {
+      riskCount: map.risks.length,
+      noticeCount: notices.length,
+      blockerCount: notices.filter((notice) => notice.severity === 'block').length,
+      warningCount: notices.filter((notice) => notice.severity !== 'block').length,
+      interventions: map.interventions || [],
+    },
+    notices,
+  };
+}
+
+function controlMapNotice(risk) {
+  return {
+    code: risk.code,
+    source: 'control-map',
+    message: risk.message,
+    artifacts: ['gsdd control-map --json'],
+    risk,
+  };
+}
+
 function buildPhaseBlockers({ lifecycle, phaseToken, surface }) {
   const blockers = [];
   const phaseEntry = lifecycle.phases.find((phase) => phase.number === phaseToken);

package/bin/lib/phase.mjs

@@ -210,42 +210,118 @@ function normalizeUiProofIssue(issue) {
   };
 }
 
-function planDeclaresUiProofSlots(planContent) {
-  const match = String(planContent || '').match(/(^|\n)ui_proof_slots:[ \t]*([^\n]*)/);
-  if (!match) return false;
-  const inlineValue = match[2].replace(/\s+#.*$/, '').trim();
-  if (inlineValue) return !['[]', 'null', '~'].includes(inlineValue);
-  const after = String(planContent || '').slice(match.index + match[0].length).split(/\r?\n/);
-  for (const line of after) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith('#')) continue;
-    if (trimmed === '---' || trimmed === '...') break;
-    if (/^\s+-\s+/.test(line)) return true;
-    if (/^\S[^:\n]*:\s*/.test(line) || /^\S/.test(line)) break;
+function stripInlineComment(value) {
+  return String(value || '').replace(/\s+#.*$/, '').trim();
+}
+
+function stripOuterScalarQuotes(value) {
+  return String(value)
+    .trim()
+    .replace(/^(['"])([\s\S]*)\1$/g, '$2')
+    .trim();
+}
+
+function normalizeNullableFrontmatterValue(value) {
+  const stripped = stripOuterScalarQuotes(value);
+  if (!stripped) return '';
+  if (stripped === '~') return '';
+  if (/^null$/i.test(stripped)) return '';
+  return stripped;
+}
+
+function extractUiProofSlotIds(value) {
+  const ids = [];
+  const slotPattern = /['"]?slot_id['"]?\s*:\s*['"]?([^,'"\]\s}]+)['"]?/g;
+  for (const match of String(value || '').matchAll(slotPattern)) {
+    ids.push(match[1].replace(/^['"]|['"]$/g, ''));
   }
-  return false;
+  return ids;
 }
 
-function extractDeclaredUiProofSlotIds(planContent) {
-  const match = String(planContent || '').match(/(^|\n)ui_proof_slots:[ \t]*([^\n]*)/);
-  if (!match) return [];
-  const after = String(planContent || '').slice(match.index + match[0].length).split(/\r?\n/);
-  const slotIds = [];
-  for (const line of after) {
+function readPlanFrontmatter(planContent) {
+  const content = String(planContent || '');
+  if (!content.startsWith('---')) return '';
+  const lines = content.split(/\r?\n/);
+  const frontmatter = [];
+  for (let index = 1; index < lines.length; index += 1) {
+    if (lines[index].trim() === '---') return frontmatter.join('\n');
+    frontmatter.push(lines[index]);
+  }
+  return '';
+}
+
+function frontmatterKeyBlock(frontmatter, key) {
+  const lines = String(frontmatter || '').split(/\r?\n/);
+  const keyPattern = new RegExp(`^${key}:[ \\t]*(.*)$`);
+  for (let index = 0; index < lines.length; index += 1) {
+    const match = lines[index].match(keyPattern);
+    if (!match) continue;
+    const block = [];
+    for (let next = index + 1; next < lines.length; next += 1) {
+      const line = lines[next];
+      if (/^\S[^:\n]*:\s*/.test(line)) break;
+      block.push(line);
+    }
+    return { inline: stripInlineComment(match[1]), block };
+  }
+  return null;
+}
+
+function frontmatterScalar(frontmatter, key) {
+  const entry = frontmatterKeyBlock(frontmatter, key);
+  if (!entry) return null;
+  if (entry.inline && !['|', '>'].includes(entry.inline)) return entry.inline;
+  return entry.block
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .join(' ')
+    .trim();
+}
+
+function readPlanUiProofContract(planContent) {
+  const frontmatter = readPlanFrontmatter(planContent);
+  const slotsEntry = frontmatterKeyBlock(frontmatter, 'ui_proof_slots');
+  const rationale = normalizeNullableFrontmatterValue(frontmatterScalar(frontmatter, 'no_ui_proof_rationale') || '');
+  const result = {
+    hasUiProofKey: Boolean(slotsEntry),
+    declaresSlots: false,
+    explicitEmptySlots: false,
+    noUiProofRationale: rationale,
+    hasNoUiProofRationale: Boolean(rationale.trim()),
+    slotIds: [],
+  };
+
+  if (!slotsEntry) return result;
+
+  if (slotsEntry.inline) {
+    if (['[]', 'null', '~'].includes(slotsEntry.inline)) {
+      result.explicitEmptySlots = true;
+      return result;
+    }
+    result.declaresSlots = true;
+    result.slotIds.push(...extractUiProofSlotIds(slotsEntry.inline));
+    return result;
+  }
+
+  let sawMeaningfulLine = false;
+  for (const line of slotsEntry.block) {
     const trimmed = line.trim();
     if (!trimmed || trimmed.startsWith('#')) continue;
-    if (trimmed === '---' || trimmed === '...') break;
-    if (/^\S[^:\n]*:\s*/.test(line) || /^\S/.test(line)) break;
-    const slotMatch = trimmed.match(/(?:^-\s*)?slot_id:\s*([^#\s]+)/);
-    if (slotMatch) slotIds.push(slotMatch[1].replace(/^['"]|['"]$/g, ''));
+    sawMeaningfulLine = true;
+    if (/^\s+-\s+/.test(line)) result.declaresSlots = true;
+    result.slotIds.push(...extractUiProofSlotIds(trimmed));
   }
-  return slotIds;
+
+  result.explicitEmptySlots = !result.declaresSlots && !sawMeaningfulLine;
+  return result;
 }
 
 function findUiProofSlotPlansAndFiles(planningDir, planDisplayPaths) {
   const candidates = new Set();
   const declaredPlans = [];
   const declaredSlotIds = [];
+  const noUiPlans = [];
+  const contractErrors = [];
   const names = new Set([
     'ui-proof-slots.json',
     'ui-proof-slots.md',
@@ -259,21 +335,45 @@ function findUiProofSlotPlansAndFiles(planningDir, planDisplayPaths) {
     const fullPlanPath = join(planningDir, 'phases', planDisplayPath);
     if (!existsSync(fullPlanPath)) continue;
     const planContent = readFileSync(fullPlanPath, 'utf-8');
-    if (!planDeclaresUiProofSlots(planContent)) continue;
     const relPlanPath = relative(planningDir, fullPlanPath).replace(/\\/g, '/');
+    const contract = readPlanUiProofContract(planContent);
+    const planDir = dirname(fullPlanPath);
+    const sidecars = [];
+    if (existsSync(planDir)) {
+      for (const entry of readdirSync(planDir, { withFileTypes: true })) {
+        if (entry.isFile() && names.has(entry.name)) {
+          sidecars.push(join(planDir, entry.name));
+        }
+      }
+    }
+
+    if (contract.hasUiProofKey && !contract.declaresSlots && !contract.hasNoUiProofRationale) {
+      contractErrors.push(normalizeUiProofIssue({
+        code: 'missing_no_ui_proof_rationale',
+        path: `${relPlanPath}.no_ui_proof_rationale`,
+        message: 'Plan declares empty ui_proof_slots but does not provide a no_ui_proof_rationale.',
+        fix: 'Add a nonblank no_ui_proof_rationale for non-UI work, or declare required UI proof slots and add a planned slots artifact.',
+      }));
+    }
+
+    if (contract.hasNoUiProofRationale && !contract.declaresSlots) {
+      noUiPlans.push({ plan: relPlanPath, sidecars });
+      continue;
+    }
+
+    if (!contract.declaresSlots) continue;
+
     declaredPlans.push(relPlanPath);
-    for (const slotId of extractDeclaredUiProofSlotIds(planContent)) {
+    for (const slotId of contract.slotIds) {
       declaredSlotIds.push({ plan: relPlanPath, slot_id: slotId });
     }
-    const planDir = dirname(fullPlanPath);
-    if (!existsSync(planDir)) continue;
     for (const entry of readdirSync(planDir, { withFileTypes: true })) {
       if (entry.isFile() && names.has(entry.name)) {
         candidates.add(join(planDir, entry.name));
       }
     }
   }
-  return { declaredPlans, declaredSlotIds, files: [...candidates].sort() };
+  return { declaredPlans, declaredSlotIds, noUiPlans, contractErrors, files: [...candidates].sort() };
 }
 
 function comparePhaseUiProof({ planningDir, workspaceRoot, planDisplayPaths }) {
@@ -285,9 +385,23 @@ function comparePhaseUiProof({ planningDir, workspaceRoot, planDisplayPaths }) {
 
   const plannedSlots = [];
   const errors = [];
+  const warnings = [];
   const planned = [];
   const observed = [];
 
+  errors.push(...plannedDiscovery.contractErrors);
+  for (const noUiPlan of plannedDiscovery.noUiPlans) {
+    for (const filePath of noUiPlan.sidecars) {
+      warnings.push({
+        code: 'stale_ui_proof_sidecar_ignored',
+        severity: 'warn',
+        path: relative(workspaceRoot, filePath).replace(/\\/g, '/'),
+        message: `Plan ${noUiPlan.plan} records no_ui_proof_rationale, so the UI proof sidecar is ignored for closure.`,
+        fix_hint: 'Remove or classify the stale sidecar if it no longer belongs to this non-UI phase.',
+      });
+    }
+  }
+
   for (const filePath of plannedFiles) {
     const rel = relative(workspaceRoot, filePath).replace(/\\/g, '/');
     const parsed = parseUiProofSlotsContent(readFileSync(filePath, 'utf-8'), rel);
@@ -343,6 +457,7 @@ function comparePhaseUiProof({ planningDir, workspaceRoot, planDisplayPaths }) {
       status: 'missing',
       comparison: { status: 'missing', slots: [], errors: [missingError] },
       errors: [missingError],
+      warnings,
     };
   }
 
@@ -350,9 +465,10 @@ function comparePhaseUiProof({ planningDir, workspaceRoot, planDisplayPaths }) {
     return {
       planned,
       observed,
-      status: 'not_applicable',
+      status: errors.length > 0 ? 'partial' : 'not_applicable',
       comparison: null,
       errors,
+      warnings,
     };
   }
 
@@ -366,6 +482,7 @@ function comparePhaseUiProof({ planningDir, workspaceRoot, planDisplayPaths }) {
     status: comparison.status,
     comparison,
     errors: comparison.errors || errors,
+    warnings,
   };
 }
 
@@ -534,26 +651,41 @@ export function cmdFindPhase(...args) {
   });
 }
 
-export function cmdVerify(...args) {
+export function buildPhaseVerificationReport(...args) {
   const { args: normalizedArgs, workspaceRoot, planningDir, invalid, error } = resolveWorkspaceContext(args);
   if (invalid) {
-    console.error(error);
-    process.exitCode = 1;
-    return;
+    return { ok: false, error, exitCode: 1 };
   }
   const phaseNum = normalizedArgs[0];
   if (!phaseNum) {
-    console.error('Usage: gsdd verify <phase-number>');
-    process.exitCode = 1; return;
+    return { ok: false, error: 'Usage: gsdd verify <phase-number>', exitCode: 1 };
   }
 
   if (!existsSync(planningDir)) {
-    console.error('No .planning/ directory found.');
-    process.exitCode = 1; return;
+    return { ok: false, error: 'No .planning/ directory found.', exitCode: 1 };
   }
   const phasesDir = join(planningDir, 'phases');
   const matchingPlans = findFiles(phasesDir, `${padPhase(phaseNum)}-PLAN`);
   const matchingSummaries = findFiles(phasesDir, `${padPhase(phaseNum)}-SUMMARY`);
+  const prerequisiteBlockers = [];
+  if (matchingPlans.length === 0) {
+    prerequisiteBlockers.push({
+      code: 'missing_phase_plan',
+      severity: 'blocker',
+      path: `.planning/phases/${padPhase(phaseNum)}-*/${padPhase(phaseNum)}-PLAN.md`,
+      message: `No PLAN.md artifact was found for phase ${normalizePhaseToken(phaseNum)}.`,
+      fix_hint: `Run /gsdd-plan ${normalizePhaseToken(phaseNum)} before verifying this phase.`,
+    });
+  }
+  if (matchingPlans.length > 0 && matchingSummaries.length === 0) {
+    prerequisiteBlockers.push({
+      code: 'missing_phase_summary',
+      severity: 'blocker',
+      path: `.planning/phases/${padPhase(phaseNum)}-*/${padPhase(phaseNum)}-SUMMARY.md`,
+      message: `No SUMMARY.md artifact was found for phase ${normalizePhaseToken(phaseNum)}.`,
+      fix_hint: `Run /gsdd-execute ${normalizePhaseToken(phaseNum)} before verifying this phase.`,
+    });
+  }
   const artifacts = matchingPlans.flatMap((planPath) => {
     const fullPath = join(phasesDir, planPath);
     return existsSync(fullPath)
@@ -576,10 +708,11 @@ export function cmdVerify(...args) {
     required_block: uiProof.status !== 'not_applicable' && !uiProofSatisfied ? 'ui-proof-failed' : null,
   };
   const blockedOn = [
+    ...(prerequisiteBlockers.length > 0 ? ['prerequisites'] : []),
     ...(artifactStatus.satisfied ? [] : ['artifacts']),
     ...(uiProofGate.blocks_verification ? ['ui_proof'] : []),
   ];
-  const closureVerified = legacyVerified && artifactStatus.satisfied && uiProofSatisfied;
+  const closureVerified = legacyVerified && prerequisiteBlockers.length === 0 && artifactStatus.satisfied && uiProofSatisfied;
 
   const result = {
     phase: normalizePhaseToken(phaseNum),
@@ -593,12 +726,26 @@ export function cmdVerify(...args) {
     verified: closureVerified,
     legacy_verified: legacyVerified,
     phase_artifacts_present: legacyVerified,
+    prerequisite_status: {
+      satisfied: prerequisiteBlockers.length === 0,
+      blockers: prerequisiteBlockers,
+    },
     ui_proof: uiProofGate,
     blocked_on: blockedOn,
     blocks_verification: blockedOn.length > 0,
   };
-  output(result);
-  if (!closureVerified && legacyVerified) process.exitCode = 1;
+  return { ok: true, result, exitCode: closureVerified ? 0 : 1 };
+}
+
+export function cmdVerify(...args) {
+  const report = buildPhaseVerificationReport(...args);
+  if (!report.ok) {
+    console.error(report.error);
+    process.exitCode = report.exitCode;
+    return;
+  }
+  output(report.result);
+  if (report.exitCode !== 0) process.exitCode = report.exitCode;
 }
 
 export function cmdScaffold(...args) {

package/bin/lib/rendering.mjs

@@ -7,6 +7,7 @@ const __dirname = dirname(__filename);
 const DISTILLED_DIR = join(__dirname, '..', '..', 'distilled');
 const HELPER_LIB_FILES = Object.freeze([
   'cli-utils.mjs',
+  'closeout-report.mjs',
   'control-map.mjs',
   'evidence-contract.mjs',
   'file-ops.mjs',
@@ -47,19 +48,28 @@ function renderPlanningCliLauncher() {
 
 import { cmdFileOp } from './lib/file-ops.mjs';
 import { cmdLifecyclePreflight } from './lib/lifecycle-preflight.mjs';
-import { cmdPhaseStatus } from './lib/phase.mjs';
+import { cmdPhaseStatus, cmdVerify } from './lib/phase.mjs';
 import { cmdSessionFingerprint } from './lib/session-fingerprint.mjs';
 import { cmdUiProof } from './lib/ui-proof.mjs';
 import { cmdControlMap } from './lib/control-map.mjs';
+import { createCmdCloseoutReport } from './lib/closeout-report.mjs';
 import { bootstrapHelperWorkspace, consumeWorkspaceRootArg, resolveWorkspaceContext } from './lib/workspace-root.mjs';
 
+const HELPER_CONTEXT = {
+  workflows: [],
+  frameworkVersion: 'generated-helper',
+};
+const cmdCloseoutReport = createCmdCloseoutReport(HELPER_CONTEXT);
+
 const COMMANDS = {
   'file-op': cmdFileOp,
   'lifecycle-preflight': cmdLifecyclePreflight,
   'phase-status': cmdPhaseStatus,
+  verify: cmdVerify,
   'session-fingerprint': cmdSessionFingerprint,
   'ui-proof': cmdUiProof,
   'control-map': cmdControlMap,
+  'closeout-report': cmdCloseoutReport,
 };
 
 function printHelp() {
@@ -72,6 +82,8 @@ function printHelp() {
     '                               Example: node .planning/bin/gsdd.mjs file-op delete .planning/.continue-here.bak --missing ok',
     '  phase-status <N> <status>   Update ROADMAP.md phase status ([ ] / [-] / [x])',
     '                               Example: node .planning/bin/gsdd.mjs phase-status 1 done',
+    '  verify <N>                  Run direct phase artifact and UI-proof gate checks',
+    '                               Example: node .planning/bin/gsdd.mjs verify 1',
     '  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',
@@ -83,6 +95,8 @@ function printHelp() {
     '                               Compare planned UI proof slots against observed bundles',
     '  control-map [--json] [--with-ignored] [--annotations <path>]',
     '                               Report computed repo/worktree/planning state and local annotations',
+    '  closeout-report [--json] [--phase <N>]',
+    '                               Replay read-only closeout status from control-map, health, preflight, verify, and UI-proof signals',
     '',
     'Advanced option:',
     '  --workspace-root <path>     Override workspace root discovery before or after the subcommand',