gsdd-cli 0.24.0 → 0.26.0

package/bin/adapters/claude.mjs

@@ -36,7 +36,20 @@ ${delegateContent.trim()}
 `;
 }
 
-function renderClaudePlanSkill() {
+function renderClaudePlanSkill({ portableContractPath = '.agents/skills/gsdd-plan/SKILL.md' } = {}) {
+  const contractSection = portableContractPath
+    ? `Portable contract:
+- Read \`${portableContractPath}\` first. That file remains the canonical vendor-agnostic plan contract.
+- Keep the portable contract honest: it defines the workflow, but it does not by itself prove fresh-context checker orchestration across runtimes.
+- If the portable skill says plan is still a stub, treat that as a portability-status warning for the generic surface, not as a stop signal for this Claude-native adapter path.`
+    : `Workflow contract:
+- This globally installed skill is the canonical Claude-native \`gsdd-plan\` workflow contract.
+- Keep the workflow portable: use repo-local \`.planning/\` artifacts for project state and do not require repo-local \`.agents/skills/\` files to exist.
+- Do not claim that other runtimes have the same behavior unless their own adapters explicitly implement and prove it.`;
+  const planningContract = portableContractPath
+    ? `\`${portableContractPath}\``
+    : 'this skill';
+
   return `---
 name: gsdd-plan
 description: Claude-native Phase planning with fresh-context plan checking for GSDD
@@ -45,10 +58,7 @@ argument-hint: [phase-number]
 
 You are the Claude-native \`/gsdd-plan\` skill for GSDD phase planning.
 
-Portable contract:
-- Read \`.agents/skills/gsdd-plan/SKILL.md\` first. That file remains the canonical vendor-agnostic plan contract.
-- Keep the portable contract honest: it defines the workflow, but it does not by itself prove fresh-context checker orchestration across runtimes.
-- If the portable skill says plan is still a stub, treat that as a portability-status warning for the generic surface, not as a stop signal for this Claude-native adapter path.
+${contractSection}
 
 Native Claude adapter rule:
 - This skill is the canonical Claude-native entry surface for \`/gsdd-plan\`.
@@ -66,7 +76,7 @@ Execution flow:
    d. The explorer runs a GSD-style interactive conversation with the user (gray areas, research, deep-dive questions, assumptions) and writes APPROACH.md.
    e. Before planning, confirm APPROACH.md records all canonical proof fields: \`alignment_status\`, \`alignment_method\`, \`user_confirmed_at\`, \`explicit_skip_approved\`, \`skip_scope\`, \`skip_rationale\`, and \`confirmed_decisions\`. For \`alignment_status: user_confirmed\`, \`confirmed_decisions\` must name the locked decisions and skip fields may be \`false\`/\`N/A\`; for \`alignment_status: approved_skip\`, \`explicit_skip_approved: true\`, \`skip_scope\`, and \`skip_rationale\` must be substantive. Agent-only "No questions needed" is not valid proof under \`workflow.discuss: true\`.
    f. Load APPROACH.md decisions as locked constraints alongside SPEC.md decisions.
-4. Produce the initial phase plan according to \`.agents/skills/gsdd-plan/SKILL.md\`. Pass APPROACH.md decisions (if any) as locked constraints to the planner.
+4. Produce the initial phase plan according to ${planningContract}. Pass APPROACH.md decisions (if any) as locked constraints to the planner.
 5. If \`.planning/config.json\` has \`workflow.planCheck: false\`, stop after planner self-check and explicitly report reduced assurance. This only skips the independent checker; it does not skip the step 3 alignment-proof gate when \`workflow.discuss: true\`.
 6. If \`workflow.planCheck: true\`, invoke the native \`gsdd-plan-checker\` subagent with fresh context.
 7. Pass only explicit inputs to the checker:
@@ -107,14 +117,14 @@ Never return raw checker JSON without summarizing it.
 `;
 }
 
-function renderClaudePlanCommand() {
+function renderClaudePlanCommand({ skillPath = '.claude/skills/gsdd-plan/SKILL.md' } = {}) {
   return `---
 description: Compatibility alias for the Claude-native \`/gsdd-plan\` skill
 argument-hint: [phase-number]
 allowed-tools: Read
 ---
 
-Read \`.claude/skills/gsdd-plan/SKILL.md\` and execute that skill as the canonical Claude-native \`/gsdd-plan\` entry.
+Read \`${skillPath}\` and execute that skill as the canonical Claude-native \`/gsdd-plan\` entry.
 
 Rules:
 - Do NOT duplicate orchestration logic here.

package/bin/adapters/opencode.mjs

@@ -145,7 +145,7 @@ ${delegateContent.trim()}
 `;
 }
 
-function renderOpenCodePlanCommand() {
+function renderOpenCodePlanCommand({ skillPath = '.agents/skills/gsdd-plan/SKILL.md' } = {}) {
   return `---
 description: OpenCode-native phase planning with fresh-context plan checking for GSDD
 subtask: false
@@ -154,7 +154,7 @@ subtask: false
 You are the OpenCode-native \`/gsdd-plan\` command for GSDD phase planning.
 
 Portable contract:
-- Read \`.agents/skills/gsdd-plan/SKILL.md\` first. That file remains the canonical vendor-agnostic plan contract.
+- Read \`${skillPath}\` first. That file remains the canonical vendor-agnostic plan contract.
 - Keep the portable contract honest: it defines the workflow, but it does not by itself prove fresh-context checker orchestration across runtimes.
 - If the portable skill says plan is still a stub, treat that as a portability-status warning for the generic surface, not as a stop signal for this OpenCode-native adapter path.
 
@@ -174,7 +174,7 @@ Execution flow:
    d. The explorer runs a GSD-style interactive conversation with the user (gray areas, research, deep-dive questions, assumptions) and writes APPROACH.md.
    e. Before planning, confirm APPROACH.md records all canonical proof fields: \`alignment_status\`, \`alignment_method\`, \`user_confirmed_at\`, \`explicit_skip_approved\`, \`skip_scope\`, \`skip_rationale\`, and \`confirmed_decisions\`. For \`alignment_status: user_confirmed\`, \`confirmed_decisions\` must name the locked decisions and skip fields may be \`false\`/\`N/A\`; for \`alignment_status: approved_skip\`, \`explicit_skip_approved: true\`, \`skip_scope\`, and \`skip_rationale\` must be substantive. Agent-only "No questions needed" is not valid proof under \`workflow.discuss: true\`.
    f. Load APPROACH.md decisions as locked constraints alongside SPEC.md decisions.
-4. Produce the initial phase plan according to \`.agents/skills/gsdd-plan/SKILL.md\`. Pass APPROACH.md decisions (if any) as locked constraints to the planner.
+4. Produce the initial phase plan according to \`${skillPath}\`. Pass APPROACH.md decisions (if any) as locked constraints to the planner.
 5. If \`.planning/config.json\` has \`workflow.planCheck: false\`, stop after planner self-check and explicitly report reduced assurance. This only skips the independent checker; it does not skip the step 3 alignment-proof gate when \`workflow.discuss: true\`.
 6. If \`workflow.planCheck: true\`, invoke the hidden \`gsdd-plan-checker\` subagent with fresh context.
 7. Pass only explicit inputs to the checker:

package/bin/gsdd.mjs

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-
 import { realpathSync, readFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
@@ -12,8 +11,9 @@ import {
   upsertBoundedBlock,
   getDelegateContent,
 } from './lib/rendering.mjs';
-import { loadProjectModelConfig, getRuntimeModelOverride, resolveRuntimeAgentModel, cmdModels } from './lib/models.mjs';
+import { loadProjectModelConfig, getRuntimeModelOverride, resolveRuntimeAgentModel, cmdModels, cmdRigor } from './lib/models.mjs';
 import { createCmdInit, createCmdUpdate, cmdHelp } from './lib/init.mjs';
+import { createCmdInstall } from './lib/global-install.mjs';
 import { cmdFindPhase, cmdVerify, cmdScaffold, cmdPhaseStatus } from './lib/phase.mjs';
 import { cmdFileOp } from './lib/file-ops.mjs';
 import { createCmdHealth } from './lib/health.mjs';
@@ -21,8 +21,10 @@ import { cmdLifecyclePreflight } from './lib/lifecycle-preflight.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 { createCmdNext } from './lib/next.mjs';
 import { resolveWorkspaceContext } from './lib/workspace-root.mjs';
-
+import { FRAMEWORK_VERSION, WORKFLOWS } from './lib/workflows.mjs';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const DISTILLED_DIR = join(__dirname, '..', 'distilled');
@@ -32,34 +34,6 @@ const IS_MAIN = process.argv[1] ? realpathSync(process.argv[1]) === realpathSync
 
 const [,, command, ...args] = process.argv;
 
-function defineWorkflow({ mutatesArtifacts = true, ...workflow }) {
-  return {
-    ...workflow,
-    mutatesArtifacts,
-    agent: mutatesArtifacts ? 'Code' : 'Plan',
-    opencodeType: mutatesArtifacts ? 'edit' : 'plan',
-  };
-}
-
-const WORKFLOWS = [
-  defineWorkflow({ name: 'gsdd-new-project', workflow: 'new-project.md', description: 'New project - questioning, codebase audit, research, spec, roadmap' }),
-  defineWorkflow({ name: 'gsdd-map-codebase', workflow: 'map-codebase.md', description: 'Map or refresh codebase - 4 parallel mappers, staleness check, secrets scan' }),
-  defineWorkflow({ name: 'gsdd-plan', workflow: 'plan.md', description: 'Plan a phase - research check, backward planning, task creation' }),
-  defineWorkflow({ name: 'gsdd-execute', workflow: 'execute.md', description: 'Execute a phase plan - implement tasks, verify changes, follow repo git conventions' }),
-  defineWorkflow({ name: 'gsdd-verify', workflow: 'verify.md', description: 'Verify a completed phase - 3-level checks, anti-pattern scan' }),
-  defineWorkflow({ name: 'gsdd-verify-work', workflow: 'verify-work.md', description: 'Conversational UAT testing - validate user-facing behavior with structured gap tracking' }),
-  defineWorkflow({ name: 'gsdd-audit-milestone', workflow: 'audit-milestone.md', description: 'Audit a completed milestone - cross-phase integration, requirements coverage, E2E flows' }),
-  defineWorkflow({ name: 'gsdd-complete-milestone', workflow: 'complete-milestone.md', description: 'Complete milestone - archive, evolve spec, collapse roadmap' }),
-  defineWorkflow({ name: 'gsdd-new-milestone', workflow: 'new-milestone.md', description: 'New milestone - gather goals, define requirements, create roadmap phases' }),
-  defineWorkflow({ name: 'gsdd-plan-milestone-gaps', workflow: 'plan-milestone-gaps.md', description: 'Plan gap closure phases from audit results' }),
-  defineWorkflow({ name: 'gsdd-quick', workflow: 'quick.md', description: 'Quick task - plan and execute a sub-hour task outside the phase cycle' }),
-  defineWorkflow({ name: 'gsdd-pause', workflow: 'pause.md', description: 'Pause work - save session context for seamless resumption' }),
-  defineWorkflow({ name: 'gsdd-resume', workflow: 'resume.md', description: 'Resume work - restore context and route to next action' }),
-  defineWorkflow({ name: 'gsdd-progress', workflow: 'progress.md', description: 'Check progress - show project status and route to next action', mutatesArtifacts: false }),
-];
-
-const FRAMEWORK_VERSION = 'v1.4';
-
 function createCliContext(cwd = process.cwd()) {
   return {
     cwd,
@@ -70,6 +44,9 @@ function createCliContext(cwd = process.cwd()) {
     packageVersion: PACKAGE_JSON.version,
     workflows: WORKFLOWS,
     frameworkVersion: FRAMEWORK_VERSION,
+    loadProjectModelConfig,
+    getRuntimeModelOverride,
+    resolveRuntimeAgentModel,
     adapters: createAdapterRegistry({
       cwd,
       workflows: WORKFLOWS,
@@ -88,7 +65,10 @@ function createCliContext(cwd = process.cwd()) {
 
 const INIT_CONTEXT = createCliContext(process.cwd());
 const cmdInit = createCmdInit(INIT_CONTEXT);
+const cmdInstall = createCmdInstall(INIT_CONTEXT);
 const cmdHealth = createCmdHealth(INIT_CONTEXT);
+const cmdCloseoutReport = createCmdCloseoutReport(INIT_CONTEXT);
+const cmdNext = createCmdNext(INIT_CONTEXT);
 
 const cmdUpdate = (...updateArgs) => {
   const { args: normalizedArgs, workspaceRoot, invalid, error } = resolveWorkspaceContext(updateArgs, { cwd: INIT_CONTEXT.cwd });
@@ -99,17 +79,20 @@ const cmdUpdate = (...updateArgs) => {
   }
   return createCmdUpdate(createCliContext(workspaceRoot))(...normalizedArgs);
 };
-
 const COMMANDS = {
   init: cmdInit,
+  install: cmdInstall,
   update: cmdUpdate,
   models: cmdModels,
+  rigor: cmdRigor,
   health: cmdHealth,
+  next: cmdNext,
   'file-op': cmdFileOp,
   'lifecycle-preflight': cmdLifecyclePreflight,
   'session-fingerprint': cmdSessionFingerprint,
   'ui-proof': cmdUiProof,
   'control-map': cmdControlMap,
+  'closeout-report': cmdCloseoutReport,
   'find-phase': cmdFindPhase,
   'phase-status': cmdPhaseStatus,
   verify: cmdVerify,
@@ -136,4 +119,4 @@ async function runCli(cliCommand = command, ...cliArgs) {
 }
 
 if (IS_MAIN) await runCli();
-export { cmdHelp, cmdInit, cmdUpdate, cmdModels, cmdHealth, cmdFileOp, cmdLifecyclePreflight, cmdSessionFingerprint, cmdUiProof, cmdControlMap, cmdFindPhase, cmdPhaseStatus, cmdVerify, cmdScaffold, runCli, FRAMEWORK_VERSION, createCliContext };
+export { cmdHelp, cmdInit, cmdInstall, cmdUpdate, cmdModels, cmdRigor, cmdHealth, cmdNext, cmdFileOp, cmdLifecyclePreflight, cmdSessionFingerprint, cmdUiProof, cmdControlMap, cmdCloseoutReport, cmdFindPhase, cmdPhaseStatus, cmdVerify, cmdScaffold, runCli, FRAMEWORK_VERSION, createCliContext };

package/bin/lib/closeout-report.mjs

@@ -0,0 +1,318 @@
+// closeout-report.mjs - read-only post-merge closure replay report
+
+import { output, parseFlagValue } from './cli-utils.mjs';
+import { buildControlMap } from './control-map.mjs';
+import { evaluateLifecyclePreflight } from './lifecycle-preflight.mjs';
+import { evaluateLifecycleState, normalizePhaseToken } from './lifecycle-state.mjs';
+import { buildPhaseVerificationReport } from './phase.mjs';
+import { resolveWorkspaceContext } from './workspace-root.mjs';
+
+const USAGE = 'Usage: gsdd closeout-report [--json] [--phase <N>]';
+
+function severityFromRisk(risk) {
+  if (risk.severity === 'block') return 'blocker';
+  if (risk.severity === 'warn') return 'warn';
+  return risk.severity || 'info';
+}
+
+function notice(source, severity, entry) {
+  return {
+    source,
+    severity,
+    code: entry.code || entry.id || 'unknown',
+    message: entry.message,
+    fix: entry.fix_hint || entry.fix || null,
+    path: entry.path || null,
+  };
+}
+
+function latestCompletedPhase(lifecycle) {
+  const completed = lifecycle.phases.filter((phase) => phase.status === 'done');
+  return completed.length > 0 ? completed[completed.length - 1] : null;
+}
+
+async function buildHealthReportSafe(ctx, args) {
+  try {
+    const health = await import('./health.mjs');
+    return health.buildHealthReport(ctx, args);
+  } catch (error) {
+    return {
+      status: 'degraded',
+      errors: [],
+      warnings: [{
+        id: 'W_CLOSEOUT_HEALTH_UNAVAILABLE',
+        severity: 'WARN',
+        message: `Health report builder unavailable in this helper runtime: ${error.message}`,
+        fix: 'Run the source CLI `gsdd health --json` for full health diagnostics, or refresh generated helper support.',
+      }],
+      info: [],
+    };
+  }
+}
+
+function summarizeControlMap(map) {
+  return {
+    status: map.risks.some((risk) => risk.severity === 'block')
+      ? 'blocked'
+      : map.risks.some((risk) => risk.severity === 'warn')
+        ? 'warnings'
+        : 'clear',
+    authority: map.authority,
+    canonical_worktree: {
+      branch: map.canonical_worktree.branch,
+      head: map.canonical_worktree.head,
+      dirty: map.canonical_worktree.dirty,
+      ahead_behind: map.canonical_worktree.ahead_behind,
+    },
+    worktree_count: map.worktrees.length,
+    risks: map.risks,
+    interventions: map.interventions,
+  };
+}
+
+function summarizePreflight(preflight) {
+  return {
+    status: preflight.status,
+    allowed: preflight.allowed,
+    reason: preflight.reason,
+    blockers: preflight.blockers,
+    warnings: preflight.warnings,
+  };
+}
+
+function summarizePhaseVerification(report) {
+  if (!report.ok) {
+    return {
+      status: 'blocked',
+      verified: false,
+      error: report.error,
+      blocked_on: ['verification'],
+    };
+  }
+  return {
+    status: report.result.verified ? 'passed' : 'blocked',
+    verified: report.result.verified,
+    phase_artifacts_present: report.result.phase_artifacts_present,
+    prerequisite_status: report.result.prerequisite_status,
+    artifact_status: report.result.artifact_status,
+    blocked_on: report.result.blocked_on,
+    blocks_verification: report.result.blocks_verification,
+  };
+}
+
+function collectBlockers({ health, preflight, phaseReport }) {
+  const blockers = [];
+  const uiProofErrors = phaseReport.result?.uiProof?.errors || [];
+  const uiProofGate = phaseReport.result?.ui_proof || {};
+
+  blockers.push(...health.errors.map((entry) => notice('health', 'blocker', entry)));
+  blockers.push(...preflight.blockers.map((entry) => notice('preflight', 'blocker', entry)));
+
+  if (!phaseReport.ok) {
+    blockers.push(notice('phase_verification', 'blocker', {
+      code: 'phase_verification_error',
+      message: phaseReport.error,
+      fix_hint: 'Run the direct verify command for the selected phase and repair the reported prerequisite.',
+    }));
+  } else {
+    for (const blockerEntry of phaseReport.result.prerequisite_status.blockers || []) {
+      blockers.push(notice('phase_verification', 'blocker', blockerEntry));
+    }
+    for (const artifact of phaseReport.result.artifact_status.unsatisfied || []) {
+      blockers.push(notice('phase_verification', 'blocker', {
+        code: 'unsatisfied_plan_artifact',
+        message: `${artifact.file} is not ${artifact.expected}.`,
+        fix_hint: artifact.fix_hint,
+        path: artifact.file,
+      }));
+    }
+    for (const entry of uiProofErrors) {
+      blockers.push(notice('ui_proof', entry.severity === 'warn' ? 'warn' : 'blocker', entry));
+    }
+    if (uiProofErrors.length === 0 && uiProofGate.blocks_verification) {
+      blockers.push(notice('ui_proof', 'blocker', {
+        code: uiProofGate.required_block || 'ui_proof_verification_failed',
+        message: `UI proof verification is required for phase ${phaseReport.result.phase} but reported status ${uiProofGate.status}.`,
+        fix_hint: 'Run the phase-specific UI proof checks and supply a passing observed proof bundle for each declared slot.',
+      }));
+    }
+  }
+
+  return blockers.filter((entry) => entry.severity === 'blocker');
+}
+
+function collectWarnings({ controlMap, health, preflight, phaseReport }) {
+  const warnings = [];
+  warnings.push(...controlMap.risks
+    .filter((risk) => risk.severity !== 'block')
+    .map((risk) => notice('control_map', severityFromRisk(risk), risk)));
+  warnings.push(...health.warnings.map((entry) => notice('health', 'warn', entry)));
+  warnings.push(...preflight.warnings
+    .filter((entry) => entry.source !== 'control-map')
+    .map((entry) => notice('preflight', entry.severity === 'info' ? 'info' : 'warn', entry)));
+  if (phaseReport.ok) {
+    warnings.push(...(phaseReport.result.uiProof?.warnings || []).map((entry) => notice('ui_proof', 'warn', entry)));
+  }
+  return warnings;
+}
+
+function nextSafeAction({ blockers, warnings, phaseNumber }) {
+  if (blockers.length > 0) {
+    return {
+      command: `gsdd verify ${phaseNumber}`,
+      reason: 'Fix blockers first, then re-run closeout replay.',
+    };
+  }
+  const hasWarn = warnings.some((entry) => entry.severity === 'warn');
+  if (warnings.length > 0 && hasWarn) {
+    const sources = new Set(warnings.filter((entry) => entry.severity === 'warn').map((entry) => entry.source));
+    if (sources.has('health')) {
+      return {
+        command: 'gsdd health --json',
+        reason: 'Resolve workspace health warnings before claiming the environment is clean.',
+      };
+    }
+    if (sources.has('ui_proof') || sources.has('phase_verification')) {
+      return {
+        command: `gsdd verify ${phaseNumber}`,
+        reason: 'Resolve phase verification warnings before claiming closeout is replay-clean.',
+      };
+    }
+    return {
+      command: 'gsdd control-map --json',
+      reason: 'Resolve local state warnings before claiming the environment is clean.',
+    };
+  }
+  if (warnings.length > 0) {
+    return {
+      command: 'gsdd control-map --json',
+      reason: 'Review the informational notices before claiming the local environment is clean.',
+    };
+  }
+  return {
+    command: `gsdd verify ${phaseNumber}`,
+    reason: 'Closeout replay is clean; run formal verification for closure if it has not already been recorded.',
+  };
+}
+
+export async function buildCloseoutReport(ctx = {}, args = []) {
+  const context = resolveWorkspaceContext(args, { cwd: ctx.cwd || process.cwd() });
+  if (context.invalid) {
+    return {
+      ok: false,
+      error: context.error,
+      exitCode: 1,
+    };
+  }
+
+  const phaseArg = parseFlagValue(context.args, '--phase');
+  if (phaseArg.invalid) {
+    return { ok: false, error: USAGE, exitCode: 1 };
+  }
+
+  const filteredArgs = context.args.filter((arg, index) => {
+    if (arg === '--json') return false;
+    if (arg === '--phase') return false;
+    if (index > 0 && context.args[index - 1] === '--phase') return false;
+    return true;
+  });
+  if (filteredArgs.length > 0) {
+    return { ok: false, error: USAGE, exitCode: 1 };
+  }
+
+  const lifecycle = evaluateLifecycleState({ planningDir: context.planningDir });
+  const selectedPhase = phaseArg.present
+    ? normalizePhaseToken(phaseArg.value)
+    : latestCompletedPhase(lifecycle)?.number || null;
+  if (!selectedPhase) {
+    return {
+      ok: false,
+      error: 'No completed phase found. Pass --phase <N> to replay a specific phase.',
+      exitCode: 1,
+    };
+  }
+
+  const controlMap = buildControlMap({
+    workspaceRoot: context.workspaceRoot,
+    planningDir: context.planningDir,
+  });
+  const health = await buildHealthReportSafe(ctx, ['--workspace-root', context.workspaceRoot]);
+  const preflight = evaluateLifecyclePreflight({
+    planningDir: context.planningDir,
+    surface: 'verify',
+    phaseNumber: selectedPhase,
+    expectsMutation: 'phase-status',
+    controlMapReport: controlMap,
+  });
+  const phaseReport = buildPhaseVerificationReport('--workspace-root', context.workspaceRoot, selectedPhase);
+  const blockers = collectBlockers({ health, preflight, phaseReport });
+  const warnings = collectWarnings({ controlMap, health, preflight, phaseReport });
+  const status = blockers.length > 0 ? 'blocked' : warnings.length > 0 ? 'warnings' : 'clear';
+
+  return {
+    ok: true,
+    exitCode: blockers.length > 0 ? 1 : 0,
+    result: {
+      schema_version: 1,
+      operation: 'closeout-report',
+      generated_at: new Date().toISOString(),
+      workspace_root: context.workspaceRoot.replace(/\\/g, '/'),
+      phase: selectedPhase,
+      scope: {
+        defaulted_to_latest_completed: !phaseArg.present,
+        latest_completed_phase: latestCompletedPhase(lifecycle)?.number || null,
+      },
+      status,
+      blockers,
+      warnings,
+      next_safe_action: nextSafeAction({ blockers, warnings, phaseNumber: selectedPhase }),
+      control_map: summarizeControlMap(controlMap),
+      health: {
+        status: health.status,
+        errors: health.errors,
+        warnings: health.warnings,
+        info: health.info,
+      },
+      preflight: summarizePreflight(preflight),
+      phase_verification: summarizePhaseVerification(phaseReport),
+      ui_proof: phaseReport.ok ? phaseReport.result.ui_proof : null,
+    },
+  };
+}
+
+function printHuman(report) {
+  console.log('gsdd closeout-report - read-only closure replay\n');
+  console.log(`Phase: ${report.phase}`);
+  console.log(`Status: ${report.status}`);
+  if (report.blockers.length > 0) {
+    console.log('\nBlockers:');
+    for (const blocker of report.blockers) {
+      console.log(`  - [${blocker.source}] ${blocker.code}: ${blocker.message}`);
+      if (blocker.fix) console.log(`    Fix: ${blocker.fix}`);
+    }
+  }
+  if (report.warnings.length > 0) {
+    console.log('\nWarnings:');
+    for (const warning of report.warnings) {
+      console.log(`  - [${warning.source}] ${warning.code}: ${warning.message}`);
+      if (warning.fix) console.log(`    Fix: ${warning.fix}`);
+    }
+  }
+  console.log(`\nNext safe action: ${report.next_safe_action.command}`);
+  console.log(`Reason: ${report.next_safe_action.reason}`);
+}
+
+export function createCmdCloseoutReport(ctx = {}) {
+  return async function cmdCloseoutReport(...args) {
+    const jsonMode = args.includes('--json');
+    const report = await buildCloseoutReport(ctx, args);
+    if (!report.ok) {
+      console.error(report.error);
+      process.exitCode = report.exitCode;
+      return;
+    }
+    if (jsonMode) output(report.result);
+    else printHuman(report.result);
+    if (report.exitCode !== 0) process.exitCode = report.exitCode;
+  };
+}