sdd-agent-platform 0.4.2 → 0.5.1

package/node_modules/@sdd-agent-platform/core/src/lifecycle/ship.ts

@@ -1,280 +1,255 @@
-import { mkdir, writeFile } from 'node:fs/promises';
-import path from 'node:path';
-import { doctor } from '../doctor/doctor.js';
-import type { DoctorLevel, DoctorReport } from '../doctor/model.js';
-import { getProjectStatus, type ProjectStatus } from '../status/project-status.js';
-import { evaluateAndRecordWorkflowGateDecision } from '../workflow-gate/evidence-packet.js';
-import { listRuntimeRepairs, type RuntimeRepairRecord } from '../storage/runtime-store.js';
-
-export interface ShipReadinessCheck {
-  name: string;
-  status: 'PASS' | 'BLOCKED';
-  message: string;
-  nextAction?: string;
-}
-
-export interface ShipResult {
-  contract: 'sdd-ship-readiness-v1';
-  branch: string;
-  status: 'PASS' | 'BLOCKED';
-  dryRun: boolean;
-  releasePath: string;
-  wroteRelease: boolean;
-  checkedAt: string;
-  checks: ShipReadinessCheck[];
-  nextActions: string[];
-  projectStatus: {
-    workflowStatus: ProjectStatus['workflowStatus'];
-    tasks: ProjectStatus['tasks'];
-    taskRisk: ProjectStatus['taskRisk'];
-    latestRun: ProjectStatus['latestRun'];
-    latestRunEvidence: ProjectStatus['latestRunEvidence'];
-    staleReasons: string[];
-    affectedFileConflicts: number;
-    dependencyBlockers: number;
-    tokenProjection: ProjectStatus['tokenProjection'];
-    lifecycleRisk: ProjectStatus['lifecycleRisk'];
-    capabilityHealth: ProjectStatus['capabilityHealth'];
-    workflowGateHealth: ProjectStatus['workflowGateHealth'];
-    truthReconciliation: ProjectStatus['truthReconciliation'];
-  };
-  doctor: {
-    status: DoctorLevel;
-    pass: number;
-    warn: number;
-    fail: number;
-  };
-  releaseDocument: string;
-}
-
-export async function runShip(projectRoot: string, options: { branch?: string | null; dryRun?: boolean } = {}): Promise<ShipResult> {
-  const checkedAt = new Date().toISOString();
-  const projectStatus = await getProjectStatus(projectRoot, { branch: options.branch ?? undefined, branchSource: options.branch ? 'cli_option' : undefined });
-  const doctorReport = await doctor(projectRoot, { latestOnly: true, branch: projectStatus.branch });
-  const gateDecision = projectStatus.latestRun?.taskId
-    ? (await evaluateAndRecordWorkflowGateDecision(projectRoot, { branch: projectStatus.branch, taskId: projectStatus.latestRun.taskId, runId: projectStatus.latestRun.runId, decisionKind: 'ship' })).decision
-    : null;
-  const projectStatusWithGate = gateDecision ? await getProjectStatus(projectRoot, { branch: options.branch ?? undefined, branchSource: options.branch ? 'cli_option' : undefined }) : projectStatus;
-  const openRepairs = await listRuntimeRepairs(projectRoot, { branchSlug: projectStatus.branch, status: 'open' });
-  const checks = buildShipChecks(projectStatusWithGate, doctorReport, gateDecision, openRepairs);
-  const blocked = checks.some((check) => check.status === 'BLOCKED');
-  const status = blocked ? 'BLOCKED' : 'PASS';
-  const releasePath = path.join(projectStatus.context.specDir, 'release.md');
-  const nextActions = shipNextActions(projectStatus.branch, checks);
-  const releaseDocument = renderReleaseDocument({ checkedAt, projectStatus: projectStatusWithGate, doctorReport, checks, nextActions, status });
-  const dryRun = options.dryRun === true;
-  if (!dryRun) {
-    const absoluteReleasePath = path.join(projectRoot, releasePath);
-    await mkdir(path.dirname(absoluteReleasePath), { recursive: true });
-    await writeFile(absoluteReleasePath, releaseDocument, 'utf8');
-  }
-  return {
-    contract: 'sdd-ship-readiness-v1',
-    branch: projectStatus.branch,
-    status,
-    dryRun,
-    releasePath,
-    wroteRelease: !dryRun,
-    checkedAt,
-    checks,
-    nextActions,
-    projectStatus: {
-      workflowStatus: projectStatusWithGate.workflowStatus,
-      tasks: projectStatusWithGate.tasks,
-      taskRisk: projectStatusWithGate.taskRisk,
-      latestRun: projectStatusWithGate.latestRun,
-      latestRunEvidence: projectStatusWithGate.latestRunEvidence,
-      staleReasons: projectStatusWithGate.latestRunStaleReasons,
-      affectedFileConflicts: projectStatusWithGate.affectedFileConflicts.length,
-      dependencyBlockers: projectStatusWithGate.dependencyBlockers.length,
-      tokenProjection: projectStatusWithGate.tokenProjection,
-      lifecycleRisk: projectStatusWithGate.lifecycleRisk,
-      capabilityHealth: projectStatusWithGate.capabilityHealth,
-      workflowGateHealth: projectStatusWithGate.workflowGateHealth,
-      truthReconciliation: projectStatusWithGate.truthReconciliation
-    },
-    doctor: summarizeDoctor(doctorReport),
-    releaseDocument
-  };
-}
-
-function buildShipChecks(projectStatus: ProjectStatus, doctorReport: DoctorReport, gateDecision: ProjectStatus['workflowGateHealth']['latestDecision'], openRepairs: RuntimeRepairRecord[]): ShipReadinessCheck[] {
-  const checks: ShipReadinessCheck[] = [];
-  checks.push({
-    name: 'documents',
-    status: projectStatus.documents.specExists && projectStatus.documents.planExists && projectStatus.documents.tasksExists && projectStatus.documents.verifyExists ? 'PASS' : 'BLOCKED',
-    message: `spec=${projectStatus.documents.specExists} plan=${projectStatus.documents.planExists} tasks=${projectStatus.documents.tasksExists} verify=${projectStatus.documents.verifyExists}`,
-    nextAction: `Run missing document stages for ${projectStatus.branch}: sdd spec, sdd plan, then sdd tasks so verify.md is regenerated from the frozen tasks contract.`
-  });
-  checks.push({
-    name: 'workflow_gaps',
-    status: projectStatus.gaps.some((gap) => gap.severity === 'blocking') ? 'BLOCKED' : 'PASS',
-    message: `blocking_gaps=${projectStatus.gaps.filter((gap) => gap.severity === 'blocking').length} total_gaps=${projectStatus.gaps.length}`,
-    nextAction: `sdd tasks list --branch ${projectStatus.branch}`
-  });
-  checks.push({
-    name: 'dependency_blockers',
-    status: projectStatus.dependencyBlockers.length === 0 ? 'PASS' : 'BLOCKED',
-    message: `dependency_blockers=${projectStatus.dependencyBlockers.length}`,
-    nextAction: projectStatus.dependencyBlockers[0] ? `sdd tasks inspect ${projectStatus.dependencyBlockers[0].dependencyId} --branch ${projectStatus.branch}` : undefined
-  });
-  checks.push({
-    name: 'doctor_fast',
-    status: doctorReport.status === 'FAIL' ? 'BLOCKED' : 'PASS',
-    message: `doctor_status=${doctorReport.status}`,
-    nextAction: `sdd doctor fast --branch ${projectStatus.branch}`
-  });
-  checks.push({
-    name: 'open_repairs',
-    status: openRepairs.length === 0 ? 'PASS' : 'BLOCKED',
-    message: `open=${openRepairs.length} types=${[...new Set(openRepairs.map((repair) => repair.repairType))].join(',') || 'none'}`,
-    nextAction: openRepairs[0]?.recommendedCommands[0] ?? `sdd doctor --branch ${projectStatus.branch} --latest-only`
-  });
-  checks.push({
-    name: 'latest_run',
-    status: latestRunReady(projectStatus) ? 'PASS' : 'BLOCKED',
-    message: projectStatus.latestRun
-      ? `run=${projectStatus.latestRun.runId} status=${projectStatus.latestRun.status} validation=${projectStatus.latestRun.validationStatus}`
-      : 'run=none',
-    nextAction: projectStatus.latestRun ? `sdd run inspect ${projectStatus.latestRun.runId}` : `sdd do task <task_id> --branch ${projectStatus.branch}`
-  });
-  checks.push({
-    name: 'truth_reconciliation',
-    status: projectStatus.truthReconciliation ? 'BLOCKED' : 'PASS',
-    message: projectStatus.truthReconciliation ? `change=${projectStatus.truthReconciliation.changeKind} impact=${projectStatus.truthReconciliation.semanticImpact} owner=${projectStatus.truthReconciliation.ownerStage}-manager frontier=${projectStatus.truthReconciliation.minimalFrontier.join('>') || 'none'}` : 'none',
-    nextAction: projectStatus.truthReconciliation?.nextIntent.canonicalCommand
-  });
-  checks.push({
-    name: 'evidence_health',
-    status: projectStatus.latestRunStaleReasons.length === 0 && projectStatus.affectedFileConflicts.length === 0 ? 'PASS' : 'BLOCKED',
-    message: `stale_reasons=${projectStatus.latestRunStaleReasons.length} affected_file_conflicts=${projectStatus.affectedFileConflicts.length}`,
-    nextAction: `sdd status --branch ${projectStatus.branch}`
-  });
-  checks.push({
-    name: 'token_health',
-    status: 'PASS',
-    message: `token_health=${projectStatus.tokenProjection.health} estimated_tokens=${projectStatus.tokenProjection.estimatedTokens ?? 'unknown'} context_packages=${projectStatus.tokenProjection.contextPackages} team_runtime_decisions=${projectStatus.tokenProjection.teamRuntimeDecisions}`,
-    nextAction: `sdd statusline --branch ${projectStatus.branch} --json`
-  });
-  checks.push({
-    name: 'lifecycle_risk_decision',
-    status: lifecycleRiskReady(projectStatus) ? 'PASS' : 'BLOCKED',
-    message: `enforced status=${projectStatus.lifecycleRisk.status} profile=${projectStatus.lifecycleRisk.profile ?? 'none'} approval=${projectStatus.lifecycleRisk.approvalPolicy ?? 'none'}`,
-    nextAction: lifecycleRiskReady(projectStatus) ? undefined : `Resolve lifecycle risk gate for ${projectStatus.lifecycleRisk.scopeKey} before ship.`
-  });
-  checks.push({
-    name: 'workflow_handoff',
-    status: workflowHandoffReady(projectStatus) ? 'PASS' : 'BLOCKED',
-    message: `status=${projectStatus.workflowHandoff.status} latest=${projectStatus.workflowHandoff.latestHandoff ? `${projectStatus.workflowHandoff.latestHandoff.fromStage}->${projectStatus.workflowHandoff.latestHandoff.toStage}:${projectStatus.workflowHandoff.latestHandoff.status}` : 'none'}`,
-    nextAction: workflowHandoffReady(projectStatus) ? undefined : `Resolve workflow handoff state before ship for ${projectStatus.branch}.`
-  });
-  checks.push({
-    name: 'context_offload',
-    status: projectStatus.contextRuntime.action === 'block-for-curation' ? 'BLOCKED' : 'PASS',
-    message: `level=${projectStatus.contextRuntime.level} action=${projectStatus.contextRuntime.action}`,
-    nextAction: projectStatus.contextRuntime.action === 'block-for-curation' ? `Curate context before ship for ${projectStatus.branch}.` : undefined
-  });
-  checks.push({
-    name: 'subagent_dispatches',
-    status: subagentDispatchesReady(projectStatus) ? 'PASS' : 'BLOCKED',
-    message: `status=${projectStatus.subagentDispatches.status} blocking_open=${projectStatus.subagentDispatches.blockingOpen} failed=${projectStatus.subagentDispatches.failed} archived=${projectStatus.subagentDispatches.archived} superseded=${projectStatus.subagentDispatches.superseded}`,
-    nextAction: subagentDispatchesReady(projectStatus) ? undefined : projectStatus.subagentDispatches.reasons.join(' ')
-  });
-  checks.push({
-    name: 'capability_health',
-    status: projectStatus.capabilityHealth.status === 'blocked' ? 'BLOCKED' : 'PASS',
-    message: `status=${projectStatus.capabilityHealth.status} baseline=${projectStatus.capabilityHealth.baselineDomains.length}/${projectStatus.capabilityHealth.requiredProfessionalDomains.length} release_critical_gaps=${projectStatus.capabilityHealth.releaseCriticalGaps.join(',') || 'none'} adoption_closures=${projectStatus.capabilityHealth.adoptions.releaseCriticalClosures.join(',') || 'none'} evidence_candidate=${projectStatus.capabilityHealth.evidence.candidate} evidence_quarantined=${projectStatus.capabilityHealth.evidence.quarantined} evidence_blocked=${projectStatus.capabilityHealth.evidence.blocked}` ,
-    nextAction: projectStatus.capabilityHealth.status === 'blocked' ? `Run sdd test <validation_unit_id-or-validation_text> for ${projectStatus.branch} to record accepted runtime evidence; capability output remains advisory.` : undefined
-  });
-  checks.push({
-    name: 'workflow_gate',
-    status: gateDecision && gateDecision.status !== 'PASS' ? 'BLOCKED' : 'PASS',
-    message: gateDecision ? `decision=${gateDecision.decisionId} status=${gateDecision.status} hard_blocks=${gateDecision.hardBlocks.length} warnings=${gateDecision.warnings.length} human_required=${gateDecision.humanRequired}` : 'decision=none',
-    nextAction: gateDecision && gateDecision.status !== 'PASS' ? gateDecision.allowedNextActions.join(', ') : undefined
-  });
-  return checks;
-}
-
-function latestRunReady(projectStatus: ProjectStatus): boolean {
-  if (!projectStatus.latestRun) {
-    return false;
-  }
-  return projectStatus.latestRun.status === 'completed'
-    && projectStatus.latestRun.validationStatus === 'pass';
-}
-
-function lifecycleRiskReady(projectStatus: ProjectStatus): boolean {
-  return projectStatus.lifecycleRisk.status === 'fresh'
-    && projectStatus.lifecycleRisk.approvalPolicy !== 'blocked'
-    && projectStatus.lifecycleRisk.approvalPolicy !== 'human-required';
-}
-
-function workflowHandoffReady(projectStatus: ProjectStatus): boolean {
-  return projectStatus.workflowHandoff.status === 'fresh' || projectStatus.workflowHandoff.status === 'missing';
-}
-
-function subagentDispatchesReady(projectStatus: ProjectStatus): boolean {
-  return projectStatus.subagentDispatches.status === 'fresh' || projectStatus.subagentDispatches.status === 'missing';
-}
-
-function summarizeDoctor(report: DoctorReport): ShipResult['doctor'] {
-  return {
-    status: report.status,
-    pass: report.checks.filter((check) => check.level === 'PASS').length,
-    warn: report.checks.filter((check) => check.level === 'WARN').length,
-    fail: report.checks.filter((check) => check.level === 'FAIL').length
-  };
-}
-
-function shipNextActions(branch: string, checks: ShipReadinessCheck[]): string[] {
-  const blocked = checks.filter((check) => check.status === 'BLOCKED');
-  if (blocked.length === 0) {
-    return [`Review specs/${branch}/release.md`, 'Do not publish, push, tag, or deploy without explicit separate approval.'];
-  }
-  return blocked.map((check) => check.nextAction ?? `Resolve ${check.name}`).filter((item, index, items) => items.indexOf(item) === index);
-}
-
-function renderReleaseDocument(input: {
-  checkedAt: string;
-  projectStatus: ProjectStatus;
-  doctorReport: DoctorReport;
-  checks: ShipReadinessCheck[];
-  nextActions: string[];
-  status: ShipResult['status'];
-}): string {
-  const latestRun = input.projectStatus.latestRun;
-  const evidence = input.projectStatus.latestRunEvidence;
-  return [
-    `# Release — ${input.projectStatus.branch}`,
-    '',
-    '## Readiness',
-    '',
-    `- status: ${input.status}`,
-    `- checked_at: ${input.checkedAt}`,
-    '- boundary: local readiness and release summary only; no publish, push, tag, deploy, or external release state is performed.',
-    '',
-    '## Checks',
-    '',
-    ...input.checks.map((check) => `- ${check.status} ${check.name}: ${check.message}`),
-    '',
-    '## Workflow summary',
-    '',
-    `- workflow_status: ${input.projectStatus.workflowStatus}`,
-    `- tasks: total=${input.projectStatus.tasks.total} pending=${input.projectStatus.tasks.pending} in_progress=${input.projectStatus.tasks.inProgress} completed=${input.projectStatus.tasks.completed} blocked=${input.projectStatus.tasks.blocked} gaps=${input.projectStatus.tasks.gaps}`,
-    `- dependency_blockers: ${input.projectStatus.dependencyBlockers.map((blocker) => `${blocker.taskId}->${blocker.dependencyId}`).join(',') || 'none'}`,
-    `- task_risk: high=${input.projectStatus.taskRisk.highRiskTasks.join(',') || 'none'} medium=${input.projectStatus.taskRisk.mediumRiskTasks.join(',') || 'none'} source_boundary=${input.projectStatus.taskRisk.sourceBoundaryTasks.join(',') || 'none'} context=${input.projectStatus.taskRisk.contextRiskTasks.join(',') || 'none'} token=${input.projectStatus.taskRisk.tokenRiskTasks.join(',') || 'none'} performance=${input.projectStatus.taskRisk.performanceRiskTasks.join(',') || 'none'}`,
-    latestRun ? `- latest_run: ${latestRun.runId} status=${latestRun.status} validation=${latestRun.validationStatus}` : '- latest_run: none',
-    evidence ? `- latest_run_evidence: route_preflight=${evidence.routePreflight} agent_executions=${evidence.agentExecutions} team_sessions=${evidence.teamSessions} worker_runtimes=${evidence.workerRuntimes} stale_worker_runtimes=${evidence.staleWorkerRuntimes} artifact_ingestions=${evidence.artifactIngestions}` : '- latest_run_evidence: none',
-    `- token_health: ${input.projectStatus.tokenProjection.health} estimated_tokens=${input.projectStatus.tokenProjection.estimatedTokens ?? 'unknown'} context_packages=${input.projectStatus.tokenProjection.contextPackages} team_runtime_decisions=${input.projectStatus.tokenProjection.teamRuntimeDecisions}`,
-    `- lifecycle_risk: status=${input.projectStatus.lifecycleRisk.status} profile=${input.projectStatus.lifecycleRisk.profile ?? 'none'} approval=${input.projectStatus.lifecycleRisk.approvalPolicy ?? 'none'} input=${input.projectStatus.lifecycleRisk.inputHash ?? 'none'} expected=${input.projectStatus.lifecycleRisk.expectedInputHash}`,
-    `- capability_health: status=${input.projectStatus.capabilityHealth.status} baseline=${input.projectStatus.capabilityHealth.baselineDomains.length}/${input.projectStatus.capabilityHealth.requiredProfessionalDomains.length} active=${input.projectStatus.capabilityHealth.activeDomains.join(',') || 'none'} release_critical_gaps=${input.projectStatus.capabilityHealth.releaseCriticalGaps.join(',') || 'none'} adoption_closures=${input.projectStatus.capabilityHealth.adoptions.releaseCriticalClosures.join(',') || 'none'} evidence_candidate=${input.projectStatus.capabilityHealth.evidence.candidate} evidence_quarantined=${input.projectStatus.capabilityHealth.evidence.quarantined} evidence_blocked=${input.projectStatus.capabilityHealth.evidence.blocked}`, 
-    `- workflow_gate: decisions=${input.projectStatus.workflowGateHealth.decisions} latest=${input.projectStatus.workflowGateHealth.latestDecision ? `${input.projectStatus.workflowGateHealth.latestDecision.decisionKind}:${input.projectStatus.workflowGateHealth.latestDecision.status}:${input.projectStatus.workflowGateHealth.latestDecision.decisionId}` : 'none'}`,
-    input.projectStatus.truthReconciliation ? `- truth_reconciliation: change=${input.projectStatus.truthReconciliation.changeKind} impact=${input.projectStatus.truthReconciliation.semanticImpact} owner=${input.projectStatus.truthReconciliation.ownerStage}-manager frontier=${input.projectStatus.truthReconciliation.minimalFrontier.join('>') || 'none'} next=${input.projectStatus.truthReconciliation.nextIntent.canonicalCommand}` : '- truth_reconciliation: none',
-    `- doctor_fast: status=${input.doctorReport.status} checks=${input.doctorReport.checks.length}`,
-    '',
-    '## Next actions',
-    '',
-    ...input.nextActions.map((action) => `- ${action}`),
-    ''
-  ].join('\n');
-}
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { doctor } from '../doctor/doctor.js';
+import type { DoctorLevel, DoctorReport } from '../doctor/model.js';
+import { getProjectStatus, type ProjectStatus } from '../status/project-status.js';
+import { evaluateAndRecordWorkflowGateDecision } from '../workflow-gate/evidence-packet.js';
+import { readTruthAlignmentProjection } from '../stage-collaboration.js';
+
+export interface ShipReadinessCheck {
+  name: string;
+  status: 'PASS' | 'BLOCKED';
+  message: string;
+  nextAction?: string;
+}
+
+export interface ShipResult {
+  contract: 'sdd-ship-readiness-v1';
+  branch: string;
+  status: 'PASS' | 'BLOCKED';
+  dryRun: boolean;
+  releasePath: string;
+  wroteRelease: boolean;
+  checkedAt: string;
+  checks: ShipReadinessCheck[];
+  nextActions: string[];
+  projectStatus: {
+    workflowStatus: ProjectStatus['workflowStatus'];
+    tasks: ProjectStatus['tasks'];
+    taskRisk: ProjectStatus['taskRisk'];
+    latestRun: ProjectStatus['latestRun'];
+    latestRunEvidence: ProjectStatus['latestRunEvidence'];
+    staleReasons: string[];
+    affectedFileConflicts: number;
+    dependencyBlockers: number;
+    tokenProjection: ProjectStatus['tokenProjection'];
+    lifecycleRisk: ProjectStatus['lifecycleRisk'];
+    capabilityHealth: ProjectStatus['capabilityHealth'];
+    workflowGateHealth: ProjectStatus['workflowGateHealth'];
+  };
+  doctor: {
+    status: DoctorLevel;
+    pass: number;
+    warn: number;
+    fail: number;
+  };
+  releaseDocument: string;
+}
+
+interface ShipRuntimeReadiness {
+  executeClosureReady: boolean;
+}
+
+export async function runShip(projectRoot: string, options: { branch?: string | null; dryRun?: boolean } = {}): Promise<ShipResult> {
+  const checkedAt = new Date().toISOString();
+  const projectStatus = await getProjectStatus(projectRoot, { branch: options.branch ?? undefined, branchSource: options.branch ? 'cli_option' : undefined });
+  const doctorReport = await doctor(projectRoot, { latestOnly: true, branch: projectStatus.branch });
+  const gateDecision = projectStatus.latestRun?.taskId
+    ? (await evaluateAndRecordWorkflowGateDecision(projectRoot, { branch: projectStatus.branch, taskId: projectStatus.latestRun.taskId, runId: projectStatus.latestRun.runId, decisionKind: 'ship' })).decision
+    : null;
+  const projectStatusWithGate = gateDecision ? await getProjectStatus(projectRoot, { branch: options.branch ?? undefined, branchSource: options.branch ? 'cli_option' : undefined }) : projectStatus;
+  const truthAlignmentEnvelope = await readTruthAlignmentProjection(projectRoot, { branch: projectStatusWithGate.branch });
+  const runtimeReadiness: ShipRuntimeReadiness = {
+    executeClosureReady: Boolean(truthAlignmentEnvelope?.payload.status === 'aligned' && truthAlignmentEnvelope.payload.staleRefs.length === 0 && truthAlignmentEnvelope.payload.acceptedRealityRefs.some((ref) => Boolean(ref.hash)))
+  };
+  const checks = buildShipChecks(projectStatusWithGate, doctorReport, gateDecision, runtimeReadiness);
+  const blocked = checks.some((check) => check.status === 'BLOCKED');
+  const status = blocked ? 'BLOCKED' : 'PASS';
+  const releasePath = path.join(projectStatus.context.specDir, 'release.md');
+  const nextActions = shipNextActions(projectStatus.branch, checks);
+  const releaseDocument = renderReleaseDocument({ checkedAt, projectStatus: projectStatusWithGate, doctorReport, checks, nextActions, status });
+  const dryRun = options.dryRun === true;
+  if (!dryRun) {
+    const absoluteReleasePath = path.join(projectRoot, releasePath);
+    await mkdir(path.dirname(absoluteReleasePath), { recursive: true });
+    await writeFile(absoluteReleasePath, releaseDocument, 'utf8');
+  }
+  return {
+    contract: 'sdd-ship-readiness-v1',
+    branch: projectStatus.branch,
+    status,
+    dryRun,
+    releasePath,
+    wroteRelease: !dryRun,
+    checkedAt,
+    checks,
+    nextActions,
+    projectStatus: {
+      workflowStatus: projectStatusWithGate.workflowStatus,
+      tasks: projectStatusWithGate.tasks,
+      taskRisk: projectStatusWithGate.taskRisk,
+      latestRun: projectStatusWithGate.latestRun,
+      latestRunEvidence: projectStatusWithGate.latestRunEvidence,
+      staleReasons: projectStatusWithGate.latestRunStaleReasons,
+      affectedFileConflicts: projectStatusWithGate.affectedFileConflicts.length,
+      dependencyBlockers: projectStatusWithGate.dependencyBlockers.length,
+      tokenProjection: projectStatusWithGate.tokenProjection,
+      lifecycleRisk: projectStatusWithGate.lifecycleRisk,
+      capabilityHealth: projectStatusWithGate.capabilityHealth,
+      workflowGateHealth: projectStatusWithGate.workflowGateHealth
+    },
+    doctor: summarizeDoctor(doctorReport),
+    releaseDocument
+  };
+}
+
+function buildShipChecks(projectStatus: ProjectStatus, doctorReport: DoctorReport, gateDecision: ProjectStatus['workflowGateHealth']['latestDecision'], runtimeReadiness: ShipRuntimeReadiness): ShipReadinessCheck[] {
+  const checks: ShipReadinessCheck[] = [];
+  checks.push({
+    name: 'accepted_documents',
+    status: projectStatus.documents.specExists && projectStatus.documents.planExists && projectStatus.documents.tasksExists ? 'PASS' : 'BLOCKED',
+    message: `spec=${projectStatus.documents.specExists} plan=${projectStatus.documents.planExists} tasks=${projectStatus.documents.tasksExists}`,
+    nextAction: `Run missing document stages for ${projectStatus.branch}: sdd spec, sdd plan, then sdd tasks.`
+  });
+  checks.push({
+    name: 'workflow_gaps',
+    status: projectStatus.gaps.some((gap) => gap.severity === 'blocking') ? 'BLOCKED' : 'PASS',
+    message: `blocking_gaps=${projectStatus.gaps.filter((gap) => gap.severity === 'blocking').length} total_gaps=${projectStatus.gaps.length}`,
+    nextAction: `sdd tasks list --branch ${projectStatus.branch}`
+  });
+  checks.push({
+    name: 'dependency_blockers',
+    status: projectStatus.dependencyBlockers.length === 0 ? 'PASS' : 'BLOCKED',
+    message: `dependency_blockers=${projectStatus.dependencyBlockers.length}`,
+    nextAction: projectStatus.dependencyBlockers[0] ? `sdd tasks inspect ${projectStatus.dependencyBlockers[0].dependencyId} --branch ${projectStatus.branch}` : undefined
+  });
+  checks.push({
+    name: 'execute_evidence',
+    status: latestRunReady(projectStatus, runtimeReadiness) ? 'PASS' : 'BLOCKED',
+    message: runtimeReadiness.executeClosureReady
+      ? 'execute_close=accepted'
+      : projectStatus.latestRun
+        ? `run=${projectStatus.latestRun.runId} status=${projectStatus.latestRun.status} validation=${projectStatus.latestRun.validationStatus}`
+        : 'run=none',
+    nextAction: latestRunReady(projectStatus, runtimeReadiness) ? undefined : projectStatus.latestRun ? `sdd run inspect ${projectStatus.latestRun.runId}` : `sdd execute --branch ${projectStatus.branch} --json`
+  });
+  checks.push({
+    name: 'evidence_freshness',
+    status: projectStatus.latestRunStaleReasons.length === 0 && projectStatus.affectedFileConflicts.length === 0 ? 'PASS' : 'BLOCKED',
+    message: `stale_reasons=${projectStatus.latestRunStaleReasons.length} affected_file_conflicts=${projectStatus.affectedFileConflicts.length}`,
+    nextAction: `sdd status --branch ${projectStatus.branch}`
+  });
+  checks.push({
+    name: 'lifecycle_risk_decision',
+    status: lifecycleRiskReady(projectStatus, runtimeReadiness) ? 'PASS' : 'BLOCKED',
+    message: `status=${projectStatus.lifecycleRisk.status} profile=${projectStatus.lifecycleRisk.profile ?? 'none'} approval=${projectStatus.lifecycleRisk.approvalPolicy ?? 'none'}`,
+    nextAction: lifecycleRiskReady(projectStatus, runtimeReadiness) ? undefined : `Resolve lifecycle risk gate for ${projectStatus.lifecycleRisk.scopeKey} before ship.`
+  });
+  checks.push({
+    name: 'workflow_handoff',
+    status: workflowHandoffReady(projectStatus) ? 'PASS' : 'BLOCKED',
+    message: `status=${projectStatus.workflowHandoff.status} latest=${projectStatus.workflowHandoff.latestHandoff ? `${projectStatus.workflowHandoff.latestHandoff.fromStage}->${projectStatus.workflowHandoff.latestHandoff.toStage}:${projectStatus.workflowHandoff.latestHandoff.status}` : 'none'}`,
+    nextAction: workflowHandoffReady(projectStatus) ? undefined : `Resolve workflow handoff state before ship for ${projectStatus.branch}.`
+  });
+  checks.push({
+    name: 'workflow_gate',
+    status: gateDecision && gateDecision.status !== 'PASS' ? 'BLOCKED' : 'PASS',
+    message: gateDecision ? `decision=${gateDecision.decisionId} status=${gateDecision.status} hard_blocks=${gateDecision.hardBlocks.length} warnings=${gateDecision.warnings.length} human_required=${gateDecision.humanRequired}` : 'decision=none',
+    nextAction: gateDecision && gateDecision.status !== 'PASS' ? gateDecision.allowedNextActions.join(', ') : undefined
+  });
+  if (doctorReport.status === 'FAIL' && !runtimeReadiness.executeClosureReady) {
+    checks.push({
+      name: 'doctor_fast',
+      status: 'BLOCKED',
+      message: `doctor_status=${doctorReport.status}`,
+      nextAction: `sdd doctor fast --branch ${projectStatus.branch}`
+    });
+  }
+  return checks;
+}
+
+function latestRunReady(projectStatus: ProjectStatus, runtimeReadiness: ShipRuntimeReadiness): boolean {
+  if (runtimeReadiness.executeClosureReady) return true;
+  if (!projectStatus.latestRun) {
+    return false;
+  }
+  return projectStatus.latestRun.status === 'completed'
+    && projectStatus.latestRun.validationStatus === 'pass';
+}
+
+function lifecycleRiskReady(projectStatus: ProjectStatus, runtimeReadiness: ShipRuntimeReadiness): boolean {
+  if (runtimeReadiness.executeClosureReady) return true;
+  return projectStatus.lifecycleRisk.status === 'fresh'
+    && projectStatus.lifecycleRisk.approvalPolicy !== 'blocked'
+    && projectStatus.lifecycleRisk.approvalPolicy !== 'human-required';
+}
+
+function workflowHandoffReady(projectStatus: ProjectStatus): boolean {
+  return projectStatus.workflowHandoff.status === 'fresh' || projectStatus.workflowHandoff.status === 'missing';
+}
+
+function subagentDispatchesReady(projectStatus: ProjectStatus): boolean {
+  return projectStatus.subagentDispatches.status === 'fresh' || projectStatus.subagentDispatches.status === 'missing';
+}
+
+function summarizeDoctor(report: DoctorReport): ShipResult['doctor'] {
+  return {
+    status: report.status,
+    pass: report.checks.filter((check) => check.level === 'PASS').length,
+    warn: report.checks.filter((check) => check.level === 'WARN').length,
+    fail: report.checks.filter((check) => check.level === 'FAIL').length
+  };
+}
+
+function shipNextActions(branch: string, checks: ShipReadinessCheck[]): string[] {
+  const blocked = checks.filter((check) => check.status === 'BLOCKED');
+  if (blocked.length === 0) {
+    return [`Review specs/${branch}/release.md`, 'Do not publish, push, tag, or deploy without explicit separate approval.'];
+  }
+  return blocked.map((check) => check.nextAction ?? `Resolve ${check.name}`).filter((item, index, items) => items.indexOf(item) === index);
+}
+
+function renderReleaseDocument(input: {
+  checkedAt: string;
+  projectStatus: ProjectStatus;
+  doctorReport: DoctorReport;
+  checks: ShipReadinessCheck[];
+  nextActions: string[];
+  status: ShipResult['status'];
+}): string {
+  const latestRun = input.projectStatus.latestRun;
+  const evidence = input.projectStatus.latestRunEvidence;
+  const checklistMark = input.status === 'PASS' ? 'x' : ' ';
+  const blockingChecks = input.checks.filter((check) => check.status === 'BLOCKED');
+  return [
+    `# Release — ${input.projectStatus.branch}`,
+    '',
+    '## 核心变更',
+    '',
+    `- 工作流状态：${input.projectStatus.workflowStatus}` ,
+    `- 任务状态：total=${input.projectStatus.tasks.total} completed=${input.projectStatus.tasks.completed} pending=${input.projectStatus.tasks.pending} blocked=${input.projectStatus.tasks.blocked}` ,
+    latestRun ? `- Execute 结果：run=${latestRun.runId} status=${latestRun.status} validation=${latestRun.validationStatus}` : '- Execute 结果：未找到完成记录',
+    blockingChecks.length > 0 ? `- 当前阻塞：${blockingChecks.map((check) => check.name).join(', ')}` : '- 当前阻塞：无',
+    '',
+    '## 发布计划清单',
+    '',
+    `- [${checklistMark}] 代码变更已完成`,
+    `- [${checklistMark}] 必要验证已通过`,
+    `- [${blockingChecks.length === 0 ? 'x' : ' '}] 关键风险已确认`,
+    `- [${checklistMark}] 回滚/恢复方式已明确`,
+    '- [ ] 发布负责人确认',
+    '',
+    '## 验证摘要',
+    '',
+    latestRun ? `- 已运行：${latestRun.runId}` : '- 已运行：未找到',
+    latestRun ? `- 结果：${latestRun.validationStatus}` : '- 结果：blocked',
+    evidence ? `- 证据：agent_executions=${evidence.agentExecutions} worker_runtimes=${evidence.workerRuntimes} artifact_ingestions=${evidence.artifactIngestions}` : '- 证据：缺失，需回到 execute',
+    '',
+    '## 风险与回滚',
+    '',
+    blockingChecks.length > 0 ? `- 已知风险：${blockingChecks.map((check) => `${check.name}: ${check.message}`).join('; ')}` : '- 已知风险：未发现阻塞项',
+    '- 回滚方式：按本次变更的代码/配置提交边界回滚；如无法安全回滚，停止发布并回到 execute 修复。',
+    `- 失败后下一步：${input.nextActions[0] ?? '停止发布，回到 execute 检查证据。'}`,
+    ''
+  ].join('\n');
+}