gsdd-cli 0.23.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

@@ -4,10 +4,16 @@
 // evaluate once, so CWD must be computed inside function bodies.
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'fs';
-import { join, basename } from 'path';
+import { dirname, join, relative } from 'path';
 import { output } from './cli-utils.mjs';
 import { writeFingerprint } from './session-fingerprint.mjs';
 import { resolveWorkspaceContext } from './workspace-root.mjs';
+import {
+  compareUiProofSlots,
+  findUiProofBundleFiles,
+  parseUiProofSlotsContent,
+  readUiProofBundleFile,
+} from './ui-proof.mjs';
 
 const PHASE_STATUS_MARKERS = {
   not_started: '[ ]',
@@ -169,6 +175,317 @@ function extractPlanFileArtifacts(planContent, workspaceRoot) {
   return artifacts;
 }
 
+function isPlanArtifactSatisfied(artifact) {
+  if (artifact.operation === 'delete') return !artifact.exists;
+  return artifact.exists;
+}
+
+function planArtifactFixHint(artifact) {
+  if (artifact.operation === 'delete') {
+    return `Complete the planned DELETE for ${artifact.file}, or revise the plan if the file should remain.`;
+  }
+  return `Create or update ${artifact.file} so the planned ${artifact.operation.toUpperCase()} artifact exists, or revise the plan if it is no longer in scope.`;
+}
+
+function evaluatePlanArtifacts(artifacts) {
+  const unsatisfied = artifacts
+    .filter((artifact) => !isPlanArtifactSatisfied(artifact))
+    .map((artifact) => ({
+      ...artifact,
+      severity: 'blocker',
+      expected: artifact.operation === 'delete' ? 'absent' : 'present',
+      fix_hint: planArtifactFixHint(artifact),
+    }));
+  return {
+    satisfied: unsatisfied.length === 0,
+    unsatisfied,
+  };
+}
+
+function normalizeUiProofIssue(issue) {
+  return {
+    ...issue,
+    severity: issue.severity || 'blocker',
+    fix_hint: issue.fix_hint || issue.fix || 'Fix the UI proof issue before claiming verification is complete.',
+  };
+}
+
+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 ids;
+}
+
+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;
+    sawMeaningfulLine = true;
+    if (/^\s+-\s+/.test(line)) result.declaresSlots = true;
+    result.slotIds.push(...extractUiProofSlotIds(trimmed));
+  }
+
+  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',
+    'UI-PROOF-SLOTS.json',
+    'UI-PROOF-SLOTS.md',
+    'planned-ui-proof.json',
+    'planned-ui-proof.md',
+  ]);
+
+  for (const planDisplayPath of planDisplayPaths) {
+    const fullPlanPath = join(planningDir, 'phases', planDisplayPath);
+    if (!existsSync(fullPlanPath)) continue;
+    const planContent = readFileSync(fullPlanPath, 'utf-8');
+    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 contract.slotIds) {
+      declaredSlotIds.push({ plan: relPlanPath, slot_id: slotId });
+    }
+    for (const entry of readdirSync(planDir, { withFileTypes: true })) {
+      if (entry.isFile() && names.has(entry.name)) {
+        candidates.add(join(planDir, entry.name));
+      }
+    }
+  }
+  return { declaredPlans, declaredSlotIds, noUiPlans, contractErrors, files: [...candidates].sort() };
+}
+
+function comparePhaseUiProof({ planningDir, workspaceRoot, planDisplayPaths }) {
+  const plannedDiscovery = findUiProofSlotPlansAndFiles(planningDir, planDisplayPaths);
+  const plannedFiles = plannedDiscovery.files;
+  const phaseDirs = new Set(planDisplayPaths.map((planDisplayPath) => dirname(join(planningDir, 'phases', planDisplayPath))));
+  const observedFiles = findUiProofBundleFiles(planningDir)
+    .filter((filePath) => phaseDirs.has(dirname(filePath)));
+
+  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);
+    planned.push(rel);
+    plannedSlots.push(...parsed.slots);
+    errors.push(...parsed.errors.map(normalizeUiProofIssue));
+  }
+
+  if (plannedSlots.length > 0 && plannedDiscovery.declaredSlotIds.length > 0) {
+    const plannedSlotIds = new Set(plannedSlots.map((slot) => String(slot?.slot_id || '')));
+    for (const declaredSlot of plannedDiscovery.declaredSlotIds) {
+      if (plannedSlotIds.has(String(declaredSlot.slot_id))) continue;
+      errors.push(normalizeUiProofIssue({
+        code: 'planned_ui_proof_slots_drift',
+        path: `${declaredSlot.plan}.ui_proof_slots`,
+        message: `Plan declares UI proof slot ${declaredSlot.slot_id}, but no matching slot exists in the planned UI proof artifact.`,
+        fix: 'Update ui-proof-slots.json or ui-proof-slots.md beside the plan so it matches the plan-declared slot IDs, or update the plan declaration.',
+      }));
+    }
+  }
+
+  const observedBundles = [];
+  for (const filePath of observedFiles) {
+    const rel = relative(workspaceRoot, filePath).replace(/\\/g, '/');
+    const parsed = readUiProofBundleFile(filePath);
+    observed.push(rel);
+    if (parsed.errors.length > 0) {
+      errors.push(...parsed.errors.map((error) => normalizeUiProofIssue({ ...error, path: error.path || rel })));
+      continue;
+    }
+    observedBundles.push({
+      source: rel,
+      bundle: parsed.bundle,
+      options: {
+        requireLocalArtifactExists: true,
+        workspaceRoot,
+        bundleDir: dirname(filePath),
+      },
+    });
+  }
+
+  if (plannedFiles.length === 0 && plannedDiscovery.declaredPlans.length > 0) {
+    const missingError = {
+      code: 'missing_planned_ui_proof_slots_file',
+      severity: 'blocker',
+      path: plannedDiscovery.declaredPlans[0],
+      message: 'Plan declares ui_proof_slots but no ui-proof-slots artifact was found beside the plan.',
+      fix_hint: 'Create ui-proof-slots.json or ui-proof-slots.md beside the plan, or set ui_proof_slots: [] with a no_ui_proof_rationale if the phase is not UI-sensitive.',
+    };
+    return {
+      planned,
+      observed,
+      status: 'missing',
+      comparison: { status: 'missing', slots: [], errors: [missingError] },
+      errors: [missingError],
+      warnings,
+    };
+  }
+
+  if (plannedFiles.length === 0) {
+    return {
+      planned,
+      observed,
+      status: errors.length > 0 ? 'partial' : 'not_applicable',
+      comparison: null,
+      errors,
+      warnings,
+    };
+  }
+
+  const comparison = errors.length > 0
+    ? { status: 'partial', slots: [], errors: errors.map(normalizeUiProofIssue) }
+    : compareUiProofSlots(plannedSlots, observedBundles);
+
+  return {
+    planned,
+    observed,
+    status: comparison.status,
+    comparison,
+    errors: comparison.errors || errors,
+    warnings,
+  };
+}
+
 export function updateRoadmapPhaseStatus(roadmap, phaseNumber, status) {
   const marker = PHASE_STATUS_MARKERS[status];
   if (!marker) {
@@ -334,32 +651,68 @@ 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)
       ? extractPlanFileArtifacts(readFileSync(fullPath, 'utf-8'), workspaceRoot)
       : [];
   });
+  const artifactStatus = evaluatePlanArtifacts(artifacts);
+  const uiProof = comparePhaseUiProof({
+    planningDir,
+    workspaceRoot,
+    planDisplayPaths: matchingPlans,
+  });
+  const uiProofSatisfied = ['satisfied', 'not_applicable'].includes(uiProof.status);
+  const legacyVerified = matchingPlans.length > 0 && matchingSummaries.length > 0;
+  const uiProofGate = {
+    status: uiProof.status,
+    required: uiProof.status !== 'not_applicable',
+    satisfied: uiProofSatisfied,
+    blocks_verification: uiProof.status !== 'not_applicable' && !uiProofSatisfied,
+    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 && prerequisiteBlockers.length === 0 && artifactStatus.satisfied && uiProofSatisfied;
 
   const result = {
     phase: normalizePhaseToken(phaseNum),
@@ -368,9 +721,31 @@ export function cmdVerify(...args) {
     summaries: matchingSummaries,
     artifacts,
     allExist: artifacts.every((artifact) => artifact.exists),
-    verified: matchingPlans.length > 0 && matchingSummaries.length > 0,
+    artifact_status: artifactStatus,
+    uiProof,
+    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);
+  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) {