sdd-agent-platform 0.3.0 → 0.4.0

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

@@ -0,0 +1,241 @@
+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';
+
+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'];
+  };
+  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 checks = buildShipChecks(projectStatus, doctorReport);
+  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, 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: projectStatus.workflowStatus,
+      tasks: projectStatus.tasks,
+      taskRisk: projectStatus.taskRisk,
+      latestRun: projectStatus.latestRun,
+      latestRunEvidence: projectStatus.latestRunEvidence,
+      staleReasons: projectStatus.latestRunStaleReasons,
+      affectedFileConflicts: projectStatus.affectedFileConflicts.length,
+      dependencyBlockers: projectStatus.dependencyBlockers.length,
+      tokenProjection: projectStatus.tokenProjection,
+      lifecycleRisk: projectStatus.lifecycleRisk,
+    },
+    doctor: summarizeDoctor(doctorReport),
+    releaseDocument
+  };
+}
+
+function buildShipChecks(projectStatus: ProjectStatus, doctorReport: DoctorReport): 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: 'sdd init --branch <branch> --scaffold-docs'
+  });
+  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 === 'PASS' ? 'PASS' : 'BLOCKED',
+    message: `doctor_status=${doctorReport.status}`,
+    nextAction: `sdd doctor fast --branch ${projectStatus.branch}`
+  });
+  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} sync_back=${projectStatus.latestRun.syncBackStatus}`
+      : 'run=none',
+    nextAction: projectStatus.latestRun ? `sdd run inspect ${projectStatus.latestRun.runId}` : `sdd do task <task_id> --branch ${projectStatus.branch}`
+  });
+  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(' ')
+  });
+  return checks;
+}
+
+function latestRunReady(projectStatus: ProjectStatus): boolean {
+  if (!projectStatus.latestRun) {
+    return false;
+  }
+  return projectStatus.latestRun.status === 'completed'
+    && projectStatus.latestRun.validationStatus === 'pass'
+    && projectStatus.latestRun.syncBackStatus === 'applied';
+}
+
+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} sync_back=${latestRun.syncBackStatus}` : '- 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}`,
+    `- doctor_fast: status=${input.doctorReport.status} checks=${input.doctorReport.checks.length}`,
+    '',
+    '## Next actions',
+    '',
+    ...input.nextActions.map((action) => `- ${action}`),
+    ''
+  ].join('\n');
+}

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

@@ -0,0 +1,4 @@
+export * from './lifecycle/decision-gate.js';
+export * from './lifecycle/rendering.js';
+export * from './lifecycle/risk-signals.js';
+export * from './lifecycle/ship.js';

package/node_modules/@sdd-agent-platform/core/src/orchestration/contracts.ts

@@ -0,0 +1,50 @@
+import type { RuntimeRef, RuntimeScope, SddStage } from '../contracts.js';
+import type { ContextLoadSignal, ContextOffloadDecision } from '../context-offload/contracts.js';
+import type { LifecycleRiskDecision } from '../risk/contracts.js';
+import type { StageRun, WorkflowHandoff } from '../stage-runtime/contracts.js';
+import type { SubagentDispatch, SubagentResult } from '../subagents/contracts.js';
+import type { WorkUnit } from '../work-units/contracts.js';
+
+export type OrchestrationGateStatus = 'PASS' | 'WARN' | 'BLOCKED';
+export type OrchestrationGateTarget = 'route' | 'execution' | 'handoff' | 'sync-back' | 'ship' | 'test';
+
+export interface OrchestrationGate {
+  status: OrchestrationGateStatus;
+  target: OrchestrationGateTarget;
+  scope: RuntimeScope;
+  blockingReasons: string[];
+  warnings: string[];
+  nextAction: string | null;
+  riskDecision: LifecycleRiskDecision | null;
+  stageRun: StageRun | null;
+  handoff: WorkflowHandoff | null;
+  contextLoadSignal: ContextLoadSignal | null;
+  contextOffloadDecision: ContextOffloadDecision | null;
+  blockingWorkUnits: WorkUnit[];
+  blockingSubagentDispatches: SubagentDispatch[];
+  subagentResults: SubagentResult[];
+}
+
+export interface EnsureTaskOrchestrationInput {
+  branch: string;
+  taskId: string;
+  runId?: string;
+  agent?: string;
+  stage?: SddStage;
+  status?: StageRun['status'];
+  outputRefs?: RuntimeRef[];
+  evidenceRefs?: RuntimeRef[];
+}
+
+export interface EnsureExecutionOrchestrationInput extends EnsureTaskOrchestrationInput {
+  workerKind?: string | null;
+  delegationId?: string;
+  expectedArtifact?: string;
+  dispatchBlocking?: boolean;
+}
+
+export interface CompleteExecutionOrchestrationInput extends EnsureExecutionOrchestrationInput {
+  artifactPath: string | null;
+  resultStatus: string | null;
+  completed: boolean;
+}

package/node_modules/@sdd-agent-platform/core/src/orchestration/index.ts

@@ -0,0 +1,2 @@
+export * from './contracts.js';
+export * from './runtime.js';

package/node_modules/@sdd-agent-platform/core/src/orchestration/runtime.ts

@@ -0,0 +1,342 @@
+import { STAGE_RUN_CONTRACT_VERSION, SUBAGENT_DISPATCH_CONTRACT_VERSION, SUBAGENT_RESULT_CONTRACT_VERSION, WORKFLOW_HANDOFF_CONTRACT_VERSION, WORK_UNIT_CONTRACT_VERSION, type RuntimeRef, type RuntimeScope, type SddStage } from '../contracts.js';
+import { evaluateContextLoadSignal, decideContextOffload, recordContextLoadSignalProjection, recordContextOffloadDecisionProjection } from '../context-offload/runtime.js';
+import type { ContextLoadSignal, ContextOffloadDecision } from '../context-offload/contracts.js';
+import type { ArtifactResultIngestionRecord } from '../artifacts/ingestion.js';
+import { evaluateLifecycleRiskDecisionForModel } from '../risk/consumer-diagnostics.js';
+import { lifecycleRiskDecisionScopeKey, recordLifecycleRiskDecisionProjection } from '../risk/kernel.js';
+import type { LifecycleRiskDecision } from '../risk/contracts.js';
+import type { SddTask, SddTaskModel } from '../sdd-docs/task-parser.js';
+import { recordStageRunProjection, recordWorkflowHandoffProjection, validateWorkflowHandoff } from '../stage-runtime/runtime.js';
+import type { StageRun, WorkflowHandoff } from '../stage-runtime/contracts.js';
+import { listRuntimeProjections } from '../storage/runtime-store.js';
+import { recordSubagentDispatchProjection, recordSubagentResultProjection, subagentDispatchBlocksGate, SUBAGENT_DISPATCH_PROJECTION_TYPE, SUBAGENT_RESULT_PROJECTION_TYPE } from '../subagents/runtime.js';
+import type { SubagentDispatch, SubagentResult } from '../subagents/contracts.js';
+import { recordWorkUnitProjection, workUnitBlocksGate, WORK_UNIT_PROJECTION_TYPE } from '../work-units/runtime.js';
+import type { WorkUnit, WorkUnitStatus } from '../work-units/contracts.js';
+import type { CompleteExecutionOrchestrationInput, EnsureExecutionOrchestrationInput, EnsureTaskOrchestrationInput, OrchestrationGate, OrchestrationGateTarget } from './contracts.js';
+
+export async function ensureLifecycleRiskDecision(projectRoot: string, model: SddTaskModel, input: { branch: string; task?: SddTask | null; runId?: string }): Promise<LifecycleRiskDecision> {
+  const scope = runtimeScope(input.branch, input.task?.id, input.runId);
+  const decision = input.task
+    ? taskLifecycleRiskDecision(input.branch, input.task, model)
+    : evaluateLifecycleRiskDecisionForModel(input.branch, model);
+  const scopedDecision: LifecycleRiskDecision = { ...decision, scope };
+  await recordLifecycleRiskDecisionProjection(projectRoot, scopedDecision);
+  return scopedDecision;
+}
+
+export async function ensureTaskOrchestration(projectRoot: string, model: SddTaskModel, task: SddTask | null, input: EnsureTaskOrchestrationInput): Promise<{ riskDecision: LifecycleRiskDecision; stageRun: StageRun; contextLoadSignal: ContextLoadSignal; contextOffloadDecision: ContextOffloadDecision }> {
+  await ensureLifecycleRiskDecision(projectRoot, model, { branch: input.branch });
+  const riskDecision = await ensureLifecycleRiskDecision(projectRoot, model, { branch: input.branch, task, runId: input.runId });
+  const scope = runtimeScope(input.branch, input.taskId, input.runId);
+  const now = new Date().toISOString();
+  const stage = input.stage ?? 'do';
+  const stageRun = buildStageRun(scope, stage, input.agent ?? 'implementer', input.status ?? 'active', riskDecision, input.outputRefs ?? [], now);
+  await recordStageRunProjection(projectRoot, stageRun);
+  const contextLoadSignal = evaluateContextLoadSignal({
+    scope,
+    refs: task ? [{ kind: 'task', ref: task.id }] : [],
+    fileCount: task?.affectedFiles.length ?? 0,
+    dependencyFanout: task?.dependsOn.length ?? 0,
+    staleEvidenceRefs: staleDocumentCount(model),
+    unknownImpact: task ? task.risk.some((risk) => /unknown|external/i.test(risk)) : true,
+    logBytes: task?.risk.some((risk) => /context|token/i.test(risk)) ? 300_000 : 0,
+    generatedAt: now
+  });
+  await recordContextLoadSignalProjection(projectRoot, contextLoadSignal);
+  const contextOffloadDecision = decideContextOffload(contextLoadSignal, { dispatchRefs: task ? [{ kind: 'task', ref: task.id }] : [] });
+  await recordContextOffloadDecisionProjection(projectRoot, contextOffloadDecision);
+  return { riskDecision, stageRun, contextLoadSignal, contextOffloadDecision };
+}
+
+export async function ensureExecutionOrchestration(projectRoot: string, model: SddTaskModel, task: SddTask | null, input: EnsureExecutionOrchestrationInput): Promise<{ riskDecision: LifecycleRiskDecision; stageRun: StageRun; workUnit: WorkUnit; dispatch: SubagentDispatch | null; contextLoadSignal: ContextLoadSignal; contextOffloadDecision: ContextOffloadDecision }> {
+  const ensured = await ensureTaskOrchestration(projectRoot, model, task, input);
+  const scope = runtimeScope(input.branch, input.taskId, input.runId);
+  const now = new Date().toISOString();
+  const isSubagent = input.workerKind === 'claude_code_subagent';
+  const workUnit = buildWorkUnit(scope, ensured.stageRun.id, input.agent ?? 'implementer', isSubagent, input.dispatchBlocking ?? isSubagent, 'running', input.expectedArtifact, now);
+  await recordWorkUnitProjection(projectRoot, workUnit);
+  const dispatch = isSubagent
+    ? buildSubagentDispatch(scope, workUnit, input.agent ?? 'implementer', input.delegationId ?? `${input.taskId}-${input.agent ?? 'implementer'}`, input.dispatchBlocking ?? true, 'running', ensured.contextOffloadDecision, now)
+    : null;
+  if (dispatch) {
+    await recordSubagentDispatchProjection(projectRoot, dispatch);
+  }
+  return { ...ensured, workUnit, dispatch };
+}
+
+export async function completeExecutionOrchestration(projectRoot: string, model: SddTaskModel, task: SddTask | null, input: CompleteExecutionOrchestrationInput): Promise<{ riskDecision: LifecycleRiskDecision; stageRun: StageRun; workUnit: WorkUnit; dispatch: SubagentDispatch | null; result: SubagentResult | null; handoff: WorkflowHandoff }> {
+  const scope = runtimeScope(input.branch, input.taskId, input.runId);
+  const now = new Date().toISOString();
+  const status = input.completed ? 'completed' : 'failed';
+  const ensured = await ensureTaskOrchestration(projectRoot, model, task, { ...input, status, outputRefs: input.artifactPath ? [{ kind: 'artifact', ref: input.artifactPath }] : [] });
+  const isSubagent = input.workerKind === 'claude_code_subagent';
+  const workUnit = buildWorkUnit(scope, ensured.stageRun.id, input.agent ?? 'implementer', isSubagent, input.dispatchBlocking ?? isSubagent, status, input.artifactPath ?? input.expectedArtifact, now);
+  await recordWorkUnitProjection(projectRoot, workUnit);
+  const dispatch = isSubagent
+    ? buildSubagentDispatch(scope, workUnit, input.agent ?? 'implementer', input.delegationId ?? `${input.taskId}-${input.agent ?? 'implementer'}`, input.dispatchBlocking ?? true, input.completed ? 'completed' : 'failed', ensured.contextOffloadDecision, now)
+    : null;
+  let result: SubagentResult | null = null;
+  if (dispatch) {
+    await recordSubagentDispatchProjection(projectRoot, dispatch);
+    result = buildSubagentResult(dispatch, input, now);
+    await recordSubagentResultProjection(projectRoot, result);
+  }
+  const handoff = buildWorkflowHandoff(scope, ensured.stageRun, ensured.riskDecision, input.agent ?? 'implementer', input.artifactPath, input.completed, now);
+  const validation = validateWorkflowHandoff({ handoff, sourceStageRun: ensured.stageRun, lifecycleRiskDecision: ensured.riskDecision });
+  await recordWorkflowHandoffProjection(projectRoot, validation.valid ? handoff : { ...handoff, status: 'blocked', blockingGaps: validation.issues, decidedAt: now });
+  return { riskDecision: ensured.riskDecision, stageRun: ensured.stageRun, workUnit, dispatch, result, handoff };
+}
+
+export async function projectSubagentResultFromBackgroundExecution(projectRoot: string, input: { branch: string; taskId: string; runId: string; agent: string; delegationId: string; ingestion: ArtifactResultIngestionRecord }): Promise<SubagentResult> {
+  const scope = runtimeScope(input.branch, input.taskId, input.runId);
+  const workUnit = buildWorkUnit(scope, stageRunId(scope, 'do'), input.agent, true, true, input.ingestion.delegationStatus === 'COMPLETED' ? 'completed' : 'failed', input.ingestion.artifactPath, input.ingestion.ingestedAt);
+  await recordWorkUnitProjection(projectRoot, workUnit);
+  const dispatch = buildSubagentDispatch(scope, workUnit, input.agent, input.delegationId, true, input.ingestion.delegationStatus === 'COMPLETED' ? 'completed' : 'failed', null, input.ingestion.ingestedAt);
+  await recordSubagentDispatchProjection(projectRoot, dispatch);
+  const result = buildSubagentResult(dispatch, { ...input, artifactPath: input.ingestion.artifactPath, resultStatus: input.ingestion.resultStatus, completed: input.ingestion.delegationStatus === 'COMPLETED' }, input.ingestion.ingestedAt);
+  await recordSubagentResultProjection(projectRoot, result);
+  return result;
+}
+
+export async function inspectOrchestrationGate(projectRoot: string, input: { branch: string; taskId?: string; runId?: string; target?: OrchestrationGateTarget; riskDecision?: LifecycleRiskDecision | null; contextOffloadDecision?: ContextOffloadDecision | null; contextLoadSignal?: ContextLoadSignal | null; stageRun?: StageRun | null; handoff?: WorkflowHandoff | null } ): Promise<OrchestrationGate> {
+  const scope = runtimeScope(input.branch, input.taskId, input.runId);
+  const target = input.target ?? 'execution';
+  const projections = await listRuntimeProjections(projectRoot, [WORK_UNIT_PROJECTION_TYPE, SUBAGENT_DISPATCH_PROJECTION_TYPE, SUBAGENT_RESULT_PROJECTION_TYPE]);
+  const workUnits = projections
+    .filter((projection) => projection.projectionType === WORK_UNIT_PROJECTION_TYPE)
+    .map((projection) => projection.payload as { payload: WorkUnit })
+    .map((envelope) => envelope.payload)
+    .filter((workUnit) => sameScope(workUnit.scope, scope));
+  const dispatches = projections
+    .filter((projection) => projection.projectionType === SUBAGENT_DISPATCH_PROJECTION_TYPE)
+    .map((projection) => projection.payload as { payload: SubagentDispatch })
+    .map((envelope) => envelope.payload)
+    .filter((dispatch) => sameScope(dispatch.scope, scope));
+  const results = projections
+    .filter((projection) => projection.projectionType === SUBAGENT_RESULT_PROJECTION_TYPE)
+    .map((projection) => projection.payload as { payload: SubagentResult })
+    .map((envelope) => envelope.payload);
+  const resultByDispatch = new Map(results.map((result) => [result.dispatchId, result]));
+  const blockingReasons: string[] = [];
+  const warnings: string[] = [];
+  const riskDecision = input.riskDecision ?? null;
+  const contextOffloadDecision = input.contextOffloadDecision ?? null;
+  const contextLoadSignal = input.contextLoadSignal ?? null;
+  const stageRun = input.stageRun ?? null;
+  const handoff = input.handoff ?? null;
+
+  if (!riskDecision && target !== 'route') {
+    warnings.push('Lifecycle risk decision is missing from orchestration gate input.');
+  }
+  if (riskDecision?.approvalPolicy === 'blocked' || riskDecision?.profile === 'blocked') {
+    blockingReasons.push(`Lifecycle risk blocks workflow: ${riskDecision.reasons.join(' ')}`);
+  } else if (riskDecision?.approvalPolicy === 'human-required' && target !== 'test') {
+    blockingReasons.push('Lifecycle risk requires human approval before automated workflow continuation.');
+  } else if (riskDecision?.approvalPolicy === 'review-required' && ['sync-back', 'ship'].includes(target)) {
+    warnings.push('Lifecycle risk requires review evidence before final workflow closure.');
+  }
+  if (contextOffloadDecision?.action === 'block-for-curation') {
+    blockingReasons.push(...contextOffloadDecision.blockingReasons.map((reason) => `Context curation required: ${reason}`));
+  }
+  const gateName = gateNameForTarget(target);
+  const blockingWorkUnits = workUnits.filter((workUnit) => workUnitBlocksGate(workUnit, gateName));
+  const blockingSubagentDispatches = dispatches.filter((dispatch) => subagentDispatchBlocksGate(dispatch, resultByDispatch.get(dispatch.id) ?? null) && dispatch.requiredBefore === gateName);
+  blockingReasons.push(...blockingWorkUnits.map((workUnit) => `Work unit ${workUnit.id} blocks ${gateName}: status=${workUnit.status}.`));
+  blockingReasons.push(...blockingSubagentDispatches.map((dispatch) => `Subagent dispatch ${dispatch.id} blocks ${dispatch.requiredBefore}: status=${dispatch.status}.`));
+  if (['sync-back', 'ship'].includes(target) && handoff && handoff.status !== 'accepted' && handoff.status !== 'proposed') {
+    blockingReasons.push(`Workflow handoff ${handoff.fromStage}->${handoff.toStage} is ${handoff.status}.`);
+  }
+  const status = blockingReasons.length > 0 ? 'BLOCKED' : warnings.length > 0 ? 'WARN' : 'PASS';
+  return {
+    status,
+    target,
+    scope,
+    blockingReasons: uniqueStrings(blockingReasons),
+    warnings: uniqueStrings(warnings),
+    nextAction: status === 'BLOCKED' ? 'Resolve orchestration blockers before continuing the workflow.' : status === 'WARN' ? 'Review orchestration warnings before final workflow closure.' : null,
+    riskDecision,
+    stageRun,
+    handoff,
+    contextLoadSignal,
+    contextOffloadDecision,
+    blockingWorkUnits,
+    blockingSubagentDispatches,
+    subagentResults: results.filter((result) => dispatches.some((dispatch) => dispatch.id === result.dispatchId))
+  };
+}
+
+export function lifecycleAutonomyCeilingFromDecision(decision: LifecycleRiskDecision): 'direct_execution_allowed' | 'compact_boundary_only' | 'full_sdd_with_checkpoint' | 'research_before_implementation' {
+  if (decision.profile === 'direct') {
+    return 'direct_execution_allowed';
+  }
+  if (decision.profile === 'compact') {
+    return 'compact_boundary_only';
+  }
+  if (decision.profile === 'full') {
+    return 'full_sdd_with_checkpoint';
+  }
+  return 'research_before_implementation';
+}
+
+function taskLifecycleRiskDecision(branch: string, task: SddTask, model: SddTaskModel): LifecycleRiskDecision {
+  return evaluateLifecycleRiskDecisionForModel(branch, { ...model, tasks: [task], gaps: model.gaps.filter((gap) => !gap.taskId || gap.taskId === task.id || gap.severity === 'blocking') });
+}
+
+function buildStageRun(scope: RuntimeScope, stage: SddStage, agent: string, status: StageRun['status'], riskDecision: LifecycleRiskDecision, outputRefs: RuntimeRef[], now: string): StageRun {
+  return {
+    contract: STAGE_RUN_CONTRACT_VERSION,
+    id: stageRunId(scope, stage),
+    scope,
+    stage,
+    ownerAgent: agent,
+    coMainAgents: [],
+    status,
+    inputRefs: riskDecision.inputRefs,
+    outputRefs,
+    decisionRefs: [{ kind: 'projection', ref: `${lifecycleRiskDecisionScopeKey(riskDecision.scope)}` }],
+    blockingReasons: status === 'blocked' || status === 'failed' ? riskDecision.reasons : [],
+    createdAt: now,
+    updatedAt: now
+  };
+}
+
+function buildWorkflowHandoff(scope: RuntimeScope, stageRun: StageRun, decision: LifecycleRiskDecision, agent: string, artifactPath: string | null, completed: boolean, now: string): WorkflowHandoff {
+  const handoff: WorkflowHandoff = {
+    contract: WORKFLOW_HANDOFF_CONTRACT_VERSION,
+    id: `${stageRun.id}:handoff:test`,
+    scope,
+    fromStage: stageRun.stage,
+    toStage: nextStage(stageRun.stage),
+    fromAgent: agent,
+    toAgent: 'validator',
+    status: completed ? 'proposed' : 'blocked',
+    outputRefs: artifactPath ? [{ kind: 'artifact', ref: artifactPath }] : [],
+    requiredInputRefs: decision.inputRefs.length > 0 ? decision.inputRefs : [{ kind: 'task', ref: scope.taskId ?? 'unknown' }],
+    riskDecisionRef: { kind: 'projection', ref: `${lifecycleRiskDecisionScopeKey(decision.scope)}` },
+    evidenceRefs: artifactPath ? [{ kind: 'artifact', ref: artifactPath }] : [],
+    openQuestions: [],
+    blockingGaps: completed ? [] : ['Execution did not complete successfully.'],
+    createdAt: now,
+    decidedAt: now
+  };
+  return handoff;
+}
+
+function buildWorkUnit(scope: RuntimeScope, stageRunIdValue: string, agent: string, isSubagent: boolean, blocking: boolean, status: WorkUnitStatus, artifactPath: string | null | undefined, now: string): WorkUnit {
+  return {
+    contract: WORK_UNIT_CONTRACT_VERSION,
+    id: workUnitId(scope, agent, isSubagent),
+    scope,
+    stageRunId: stageRunIdValue,
+    type: isSubagent ? 'subagent' : 'main-agent',
+    name: agent,
+    purpose: isSubagent ? 'Non-authoritative background evidence collection.' : 'Lifecycle stage execution.',
+    status,
+    blocking,
+    authority: isSubagent ? 'non-authoritative' : 'stage-owner',
+    requiredBefore: blocking ? 'handoff' : 'never',
+    contextRef: { kind: 'task', ref: scope.taskId ?? 'unknown' },
+    outputRefs: artifactPath ? [{ kind: 'artifact', ref: artifactPath }] : [],
+    evidenceRefs: artifactPath ? [{ kind: 'artifact', ref: artifactPath }] : [],
+    createdAt: now,
+    completedAt: ['completed', 'failed', 'cancelled'].includes(status) ? now : undefined
+  };
+}
+
+function buildSubagentDispatch(scope: RuntimeScope, workUnit: WorkUnit, agent: string, delegationId: string, blocking: boolean, status: SubagentDispatch['status'], decision: ContextOffloadDecision | null, now: string): SubagentDispatch {
+  return {
+    contract: SUBAGENT_DISPATCH_CONTRACT_VERSION,
+    id: subagentDispatchId(scope, delegationId),
+    scope,
+    workUnitId: workUnit.id,
+    definitionName: agent,
+    mode: 'background',
+    status,
+    blocking,
+    requiredBefore: blocking ? 'handoff' : 'never',
+    contextRef: decision?.loadSignalRef ?? { kind: 'task', ref: scope.taskId ?? 'unknown' },
+    createdAt: now,
+    updatedAt: now
+  };
+}
+
+function buildSubagentResult(dispatch: SubagentDispatch, input: { artifactPath: string | null; resultStatus: string | null; completed: boolean }, now: string): SubagentResult {
+  const artifactRefs = input.artifactPath ? [{ kind: 'artifact' as const, ref: input.artifactPath }] : [];
+  return {
+    contract: SUBAGENT_RESULT_CONTRACT_VERSION,
+    dispatchId: dispatch.id,
+    status: input.completed ? 'completed' : 'failed',
+    authority: 'evidence-candidate',
+    summary: `Subagent dispatch ${dispatch.id} finished with result ${input.resultStatus ?? 'unknown'}.`,
+    artifactRefs,
+    evidenceRefs: artifactRefs,
+    modelArtifacts: artifactRefs.length > 0 ? [{
+      contract: 'sdd-model-produced-artifact-v1',
+      producer: 'subagent',
+      authority: 'candidate',
+      allowedUse: ['summary', 'diagnostic', 'evidence-candidate'],
+      forbiddenUse: ['final-risk-decision', 'stage-completion', 'ship-gate-pass'],
+      artifactRefs: artifactRefs.map((ref) => ref.ref),
+      reviewedByRuntime: true
+    }] : [],
+    completedAt: now
+  };
+}
+
+function runtimeScope(branch: string, taskId?: string, runId?: string): RuntimeScope {
+  return { branch, taskId, runId };
+}
+
+function stageRunId(scope: RuntimeScope, stage: SddStage): string {
+  return `stage:${scope.branch}:${scope.taskId ?? 'all'}:${scope.runId ?? 'none'}:${stage}`;
+}
+
+function workUnitId(scope: RuntimeScope, agent: string, isSubagent: boolean): string {
+  return `work-unit:${scope.branch}:${scope.taskId ?? 'all'}:${scope.runId ?? 'none'}:${isSubagent ? 'subagent' : 'main'}:${agent}`;
+}
+
+function subagentDispatchId(scope: RuntimeScope, delegationId: string): string {
+  return `dispatch:${scope.branch}:${scope.taskId ?? 'all'}:${scope.runId ?? 'none'}:${delegationId}`;
+}
+
+function nextStage(stage: SddStage): SddStage {
+  if (stage === 'do') {
+    return 'test';
+  }
+  if (stage === 'test') {
+    return 'goal-verify';
+  }
+  if (stage === 'goal-verify') {
+    return 'sync-back';
+  }
+  if (stage === 'sync-back') {
+    return 'ship';
+  }
+  return 'do';
+}
+
+function gateNameForTarget(target: OrchestrationGateTarget): WorkUnit['requiredBefore'] {
+  if (target === 'ship') {
+    return 'ship';
+  }
+  if (target === 'sync-back' || target === 'test') {
+    return 'sync-back';
+  }
+  if (target === 'execution') {
+    return 'stage-output';
+  }
+  return 'handoff';
+}
+
+function sameScope(left: RuntimeScope, right: RuntimeScope): boolean {
+  return left.branch === right.branch && (!right.taskId || left.taskId === right.taskId) && (!right.runId || left.runId === right.runId);
+}
+
+function staleDocumentCount(model: SddTaskModel): number {
+  return [model.documents.planStale, model.documents.tasksStale, model.documents.verifyStale].filter(Boolean).length;
+}
+
+function uniqueStrings(values: string[]): string[] {
+  return Array.from(new Set(values.filter((value) => value.length > 0)));
+}