sdd-agent-platform 0.4.2 → 0.5.0

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

@@ -0,0 +1,522 @@
+import { createHash } from 'node:crypto';
+
+import type { RuntimeProjectionEnvelope, RuntimeRef, RuntimeScope, SddStage } from '../contracts.js';
+import { lifecycleRiskDecisionScopeKey, LIFECYCLE_RISK_DECISION_PROJECTION_TYPE, readLifecycleRiskDecisionProjection } from '../risk/kernel.js';
+import type { LifecycleRiskDecision } from '../risk/contracts.js';
+import { readRuntimeProjectionEnvelope, recordRuntimeProjectionEnvelope } from '../storage/runtime-store.js';
+import {
+  buildExecuteStageWorkOrder,
+  buildPlanStageWorkOrder,
+  buildShipStageWorkOrder,
+  buildSpecStageWorkOrder,
+  buildTasksStageWorkOrder,
+  deriveSpecCollaborationProfile
+} from '../stage-collaboration.js';
+import type {
+  DiagnosticProjection,
+  EvidenceSelectionProjection,
+  LifecycleGraphAuthority,
+  LifecycleActionAuthority,
+  LifecycleGraphBundleWriteResult,
+  LifecycleGraphEdge,
+  LifecycleGraphInstance,
+  LifecycleGraphNode,
+  LifecycleRouteProjection,
+  StageWorkOrder,
+  StageWorkOrderProjection
+} from './contracts.js';
+import {
+  DIAGNOSTIC_PROJECTION_TYPE,
+  EVIDENCE_SELECTION_PROJECTION_TYPE,
+  LIFECYCLE_GRAPH_INSTANCE_PROJECTION_TYPE,
+  LIFECYCLE_GRAPH_POLICY_VERSION,
+  LIFECYCLE_ROUTE_PROJECTION_TYPE,
+  STAGE_WORK_ORDER_PROJECTION_TYPE
+} from './contracts.js';
+
+const ALL_STAGES: SddStage[] = ['spec', 'plan', 'tasks', 'execute', 'ship'];
+
+export function lifecycleGraphScopeKey(scope: RuntimeScope): string {
+  return lifecycleRiskDecisionScopeKey(scope);
+}
+
+export function lifecycleRouteScopeKey(scope: RuntimeScope): string {
+  return lifecycleRiskDecisionScopeKey(scope);
+}
+
+export function stageWorkOrderScopeKey(scope: RuntimeScope, stage: SddStage): string {
+  return `${lifecycleRiskDecisionScopeKey(scope)}:${stage}`;
+}
+
+export function evidenceSelectionScopeKey(scope: RuntimeScope, stage: SddStage): string {
+  return `${lifecycleRiskDecisionScopeKey(scope)}:${stage}`;
+}
+
+export function diagnosticScopeKey(scope: RuntimeScope, diagnosticId: string): string {
+  return `${lifecycleRiskDecisionScopeKey(scope)}:${diagnosticId}`;
+}
+
+export async function recordLifecycleGraphBundle(projectRoot: string, decision: LifecycleRiskDecision, options: { generatedAt?: string; activeStage?: SddStage | null } = {}): Promise<LifecycleGraphBundleWriteResult> {
+  const generatedAt = options.generatedAt ?? decision.generatedAt;
+  const graph = buildLifecycleGraphInstance(decision, generatedAt, options.activeStage);
+  const graphWrite = await recordRuntimeProjectionEnvelope(projectRoot, {
+    projectionType: LIFECYCLE_GRAPH_INSTANCE_PROJECTION_TYPE,
+    scopeKey: lifecycleGraphScopeKey(decision.scope),
+    inputHash: graph.inputHash,
+    producer: 'phase9-lifecycle-graph',
+    producerVersion: LIFECYCLE_GRAPH_POLICY_VERSION,
+    generatedAt,
+    payload: graph
+  });
+  const graphRef = projectionRef(LIFECYCLE_GRAPH_INSTANCE_PROJECTION_TYPE, lifecycleGraphScopeKey(decision.scope));
+  const route = buildLifecycleRouteProjection(decision, graph, graphRef, generatedAt);
+  const routeWrite = await recordRuntimeProjectionEnvelope(projectRoot, {
+    projectionType: LIFECYCLE_ROUTE_PROJECTION_TYPE,
+    scopeKey: lifecycleRouteScopeKey(decision.scope),
+    inputHash: route.inputHash,
+    producer: 'phase9-lifecycle-graph',
+    producerVersion: LIFECYCLE_GRAPH_POLICY_VERSION,
+    generatedAt,
+    payload: route
+  });
+  const workOrders = buildStageWorkOrderProjections(decision, graphRef, generatedAt);
+  const workOrderWrites = [];
+  for (const workOrder of workOrders) {
+    workOrderWrites.push(await recordRuntimeProjectionEnvelope(projectRoot, {
+      projectionType: STAGE_WORK_ORDER_PROJECTION_TYPE,
+      scopeKey: stageWorkOrderScopeKey(decision.scope, workOrder.stage),
+      inputHash: workOrder.inputHash,
+      producer: 'phase9-lifecycle-graph',
+      producerVersion: LIFECYCLE_GRAPH_POLICY_VERSION,
+      generatedAt,
+      payload: workOrder
+    }));
+  }
+  const evidenceSelections = buildEvidenceSelectionProjections(decision, graphRef, workOrders, generatedAt);
+  const evidenceWrites = [];
+  for (const evidenceSelection of evidenceSelections) {
+    evidenceWrites.push(await recordRuntimeProjectionEnvelope(projectRoot, {
+      projectionType: EVIDENCE_SELECTION_PROJECTION_TYPE,
+      scopeKey: evidenceSelectionScopeKey(decision.scope, evidenceSelection.stage),
+      inputHash: evidenceSelection.inputHash,
+      producer: 'phase9-lifecycle-graph',
+      producerVersion: LIFECYCLE_GRAPH_POLICY_VERSION,
+      generatedAt,
+      payload: evidenceSelection
+    }));
+  }
+  const diagnostics = buildDiagnosticProjections(decision, graphRef, route, generatedAt);
+  const diagnosticWrites = [];
+  for (const diagnostic of diagnostics) {
+    diagnosticWrites.push(await recordRuntimeProjectionEnvelope(projectRoot, {
+      projectionType: DIAGNOSTIC_PROJECTION_TYPE,
+      scopeKey: diagnosticScopeKey(decision.scope, diagnostic.diagnosticId),
+      inputHash: diagnostic.inputHash,
+      producer: 'phase9-lifecycle-graph',
+      producerVersion: LIFECYCLE_GRAPH_POLICY_VERSION,
+      generatedAt,
+      payload: diagnostic
+    }));
+  }
+  return {
+    graph: graphWrite.envelope,
+    route: routeWrite.envelope,
+    workOrders: workOrderWrites.map((write) => write.envelope),
+    evidenceSelections: evidenceWrites.map((write) => write.envelope),
+    diagnostics: diagnosticWrites.map((write) => write.envelope)
+  };
+}
+
+export async function readLifecycleGraphAuthority(projectRoot: string, scope: RuntimeScope): Promise<LifecycleGraphAuthority> {
+  const decision = await readLifecycleRiskDecisionProjection(projectRoot, scope);
+  const graph = await readRuntimeProjectionEnvelope<LifecycleGraphInstance>(projectRoot, LIFECYCLE_GRAPH_INSTANCE_PROJECTION_TYPE, lifecycleGraphScopeKey(scope));
+  const route = await readRuntimeProjectionEnvelope<LifecycleRouteProjection>(projectRoot, LIFECYCLE_ROUTE_PROJECTION_TYPE, lifecycleRouteScopeKey(scope));
+  const requiredStages = graph?.payload.requiredStages ?? decision?.payload.requiredStages ?? [];
+  const workOrders: RuntimeProjectionEnvelope<StageWorkOrderProjection>[] = [];
+  const evidenceSelections: RuntimeProjectionEnvelope<EvidenceSelectionProjection>[] = [];
+  for (const stage of requiredStages) {
+    const workOrder = await readRuntimeProjectionEnvelope<StageWorkOrderProjection>(projectRoot, STAGE_WORK_ORDER_PROJECTION_TYPE, stageWorkOrderScopeKey(scope, stage));
+    if (workOrder) {
+      workOrders.push(workOrder);
+    }
+    const evidenceSelection = await readRuntimeProjectionEnvelope<EvidenceSelectionProjection>(projectRoot, EVIDENCE_SELECTION_PROJECTION_TYPE, evidenceSelectionScopeKey(scope, stage));
+    if (evidenceSelection) {
+      evidenceSelections.push(evidenceSelection);
+    }
+  }
+  const diagnostics: RuntimeProjectionEnvelope<DiagnosticProjection>[] = [];
+  const blockedDiagnostic = await readRuntimeProjectionEnvelope<DiagnosticProjection>(projectRoot, DIAGNOSTIC_PROJECTION_TYPE, diagnosticScopeKey(scope, 'lifecycle-blocked'));
+  if (blockedDiagnostic) {
+    diagnostics.push(blockedDiagnostic);
+  }
+  const reasons = authorityReasons(scope, decision, graph, route, requiredStages, workOrders, evidenceSelections);
+  return {
+    scope,
+    decision,
+    graph,
+    route,
+    workOrders,
+    evidenceSelections,
+    diagnostics,
+    status: reasons.length === 0 ? 'fresh' : !decision || !graph || !route ? 'missing' : 'incomplete',
+    reasons
+  };
+}
+
+export async function readLifecycleActionAuthority(projectRoot: string, scope: RuntimeScope, requestedStage: SddStage | null): Promise<LifecycleActionAuthority> {
+  const authority = await readLifecycleGraphAuthority(projectRoot, scope);
+  const route = authority.route;
+  const nextStage = route?.payload.nextStage ?? null;
+  const canonicalCommand = route?.payload.canonicalCommand ?? null;
+  const workOrder = nextStage ? authority.workOrders.find((item) => item.payload.stage === nextStage) ?? null : null;
+  if (authority.status !== 'fresh') {
+    return {
+      action: 'repair',
+      scope,
+      requestedStage,
+      status: authority.status,
+      decision: authority.decision,
+      route,
+      workOrder,
+      nextStage,
+      canonicalCommand: lifecycleRefreshCommand(scope.branch),
+      reasons: ['Stage-local entry requires active lifecycle authority created by sdd spec.', ...authority.reasons],
+      safeToWriteRuntimeArtifacts: false
+    };
+  }
+  if (route?.payload.status === 'blocked' || authority.decision?.payload.profile === 'blocked') {
+    return {
+      action: 'blocked',
+      scope,
+      requestedStage,
+      status: authority.status,
+      decision: authority.decision,
+      route,
+      workOrder,
+      nextStage,
+      canonicalCommand,
+      reasons: route?.payload.routeReason ? [route.payload.routeReason] : authority.reasons,
+      safeToWriteRuntimeArtifacts: false
+    };
+  }
+  if (!nextStage) {
+    return {
+      action: 'complete',
+      scope,
+      requestedStage,
+      status: authority.status,
+      decision: authority.decision,
+      route,
+      workOrder,
+      nextStage,
+      canonicalCommand,
+      reasons: route?.payload.routeReason ? [route.payload.routeReason] : ['Active lifecycle graph is complete.'],
+      safeToWriteRuntimeArtifacts: false
+    };
+  }
+  if (requestedStage && requestedStage !== nextStage) {
+    return {
+      action: 'redirect',
+      scope,
+      requestedStage,
+      status: authority.status,
+      decision: authority.decision,
+      route,
+      workOrder,
+      nextStage,
+      canonicalCommand,
+      reasons: [`Active lifecycle graph routes to ${nextStage}; ${requestedStage} is not the current legal stage.`],
+      safeToWriteRuntimeArtifacts: false
+    };
+  }
+  if (!workOrder) {
+    return {
+      action: 'repair',
+      scope,
+      requestedStage,
+      status: authority.status,
+      decision: authority.decision,
+      route,
+      workOrder,
+      nextStage,
+      canonicalCommand: lifecycleRefreshCommand(scope.branch),
+      reasons: [`Stage work order projection is missing for ${nextStage}.`],
+      safeToWriteRuntimeArtifacts: false
+    };
+  }
+  return {
+    action: 'proceed',
+    scope,
+    requestedStage,
+    status: authority.status,
+    decision: authority.decision,
+    route,
+    workOrder,
+    nextStage,
+    canonicalCommand,
+    reasons: route?.payload.routeReason ? [route.payload.routeReason] : [],
+    safeToWriteRuntimeArtifacts: true
+  };
+}
+
+export function buildLifecycleGraphInstance(decision: LifecycleRiskDecision, generatedAt = decision.generatedAt, activeStage?: SddStage | null): LifecycleGraphInstance {
+  const graphScopeKey = lifecycleGraphScopeKey(decision.scope);
+  const decisionRef = projectionRef(LIFECYCLE_RISK_DECISION_PROJECTION_TYPE, lifecycleRiskDecisionScopeKey(decision.scope));
+  const requiredStages = [...decision.requiredStages];
+  const skippedStages = [...decision.skippedStages];
+  const blockedStages = [...decision.blockedStages];
+  const requestedActiveStage = activeStage === null ? null : activeStage;
+  const nextStage = requestedActiveStage && requiredStages.includes(requestedActiveStage) ? requestedActiveStage : requiredStages[0] ?? null;
+  const terminalState = decision.profile === 'blocked' || blockedStages.length > 0 ? 'blocked' : nextStage ? 'pending' : 'complete';
+  const nodes: LifecycleGraphNode[] = ALL_STAGES.map((stage) => ({
+    stage,
+    state: blockedStages.includes(stage) ? 'blocked' : requiredStages.includes(stage) ? 'required' : 'skipped',
+    requiredBefore: nextRequiredAfter(requiredStages, stage),
+    blockerRefs: blockedStages.includes(stage) ? [decisionRef] : [],
+    workOrderRef: requiredStages.includes(stage) ? projectionRef(STAGE_WORK_ORDER_PROJECTION_TYPE, stageWorkOrderScopeKey(decision.scope, stage)) : null,
+    evidenceSelectionRef: requiredStages.includes(stage) ? projectionRef(EVIDENCE_SELECTION_PROJECTION_TYPE, evidenceSelectionScopeKey(decision.scope, stage)) : null
+  }));
+  const edges: LifecycleGraphEdge[] = requiredStages.slice(0, -1).map((stage, index) => ({
+    fromStage: stage,
+    toStage: requiredStages[index + 1],
+    kind: 'requires_handoff'
+  }));
+  const inputHash = stableHash(JSON.stringify({ policyVersion: LIFECYCLE_GRAPH_POLICY_VERSION, decisionHash: decision.inputHash, requiredStages, skippedStages, blockedStages, nextStage }));
+  return {
+    contract: 'sdd-lifecycle-graph-instance-v1',
+    scope: decision.scope,
+    templateId: decision.profile,
+    graphId: `lifecycle-graph:${graphScopeKey}:${inputHash}`,
+    decisionRef,
+    decisionInputHash: decision.inputHash,
+    policyVersion: LIFECYCLE_GRAPH_POLICY_VERSION,
+    profile: decision.profile,
+    nodes,
+    edges,
+    requiredStages,
+    skippedStages,
+    blockedStages,
+    activeStage: nextStage,
+    nextStage,
+    terminalState,
+    inputRefs: decision.inputRefs,
+    inputHash,
+    generatedAt,
+    reasons: decision.reasons
+  };
+}
+
+export function buildLifecycleRouteProjection(decision: LifecycleRiskDecision, graph: LifecycleGraphInstance, graphRef: RuntimeRef, generatedAt = graph.generatedAt): LifecycleRouteProjection {
+  const blocked = graph.terminalState === 'blocked';
+  const command = blocked ? lifecycleRefreshCommand(decision.scope.branch) : graph.nextStage ? commandForStage(graph.nextStage, decision.scope) : `sdd status --branch ${decision.scope.branch} --json`;
+  const inputHash = stableHash(JSON.stringify({ graphHash: graph.inputHash, nextStage: graph.nextStage, command, blocked }));
+  return {
+    contract: 'sdd-lifecycle-route-projection-v1',
+    scope: decision.scope,
+    graphRef,
+    decisionRef: graph.decisionRef,
+    status: blocked ? 'blocked' : graph.nextStage ? 'ready' : 'complete',
+    currentStage: graph.activeStage,
+    nextStage: graph.nextStage,
+    canonicalCommand: command,
+    displayCommand: command,
+    targetRuntimeStage: graph.nextStage,
+    routeReason: blocked ? 'Active lifecycle decision blocks stage-local workflow movement.' : graph.nextStage ? `Active lifecycle graph routes to ${graph.nextStage}.` : 'Active lifecycle graph is complete.',
+    blockerRefs: blocked ? [graph.decisionRef] : [],
+    requiredInputRefs: decision.inputRefs,
+    evidenceSurface: graph.nextStage ? evidenceSurfaceForStage(graph.nextStage, decision.scope.branch) : [],
+    authority: 'lifecycle_graph',
+    fallbackUsed: false,
+    inputHash,
+    generatedAt
+  };
+}
+
+function buildStageWorkOrderProjections(decision: LifecycleRiskDecision, graphRef: RuntimeRef, generatedAt: string): StageWorkOrderProjection[] {
+  const decisionRef = projectionRef(LIFECYCLE_RISK_DECISION_PROJECTION_TYPE, lifecycleRiskDecisionScopeKey(decision.scope));
+  return decision.requiredStages.map((stage) => {
+    const workOrder = buildStageWorkOrder(stage, decision, decisionRef, generatedAt);
+    return {
+      contract: 'sdd-stage-work-order-projection-v1' as const,
+      scope: decision.scope,
+      stage,
+      graphRef,
+      decisionRef,
+      workOrderId: workOrder.workOrderId,
+      workOrder,
+      targetRef: stageTargetRef(stage, decision.scope),
+      targetHash: null,
+      closureCommand: closureCommandForStage(stage, decision.scope),
+      requiredInputRefs: workOrder.inputRefs,
+      requiredOutputKinds: workOrder.requiredOutputKinds,
+      artifactSchemas: workOrder.requiredOutputKinds.map((kind) => ({ kind, requiredFields: ['contract', 'stage', 'scope', 'evidence_hash'] })),
+      inputHash: stableHash(JSON.stringify({ decisionHash: decision.inputHash, stage, workOrder })),
+      generatedAt
+    };
+  });
+}
+
+function buildEvidenceSelectionProjections(decision: LifecycleRiskDecision, graphRef: RuntimeRef, workOrders: StageWorkOrderProjection[], generatedAt: string): EvidenceSelectionProjection[] {
+  const decisionRef = projectionRef(LIFECYCLE_RISK_DECISION_PROJECTION_TYPE, lifecycleRiskDecisionScopeKey(decision.scope));
+  return workOrders.map((workOrder) => ({
+    contract: 'sdd-evidence-selection-projection-v1',
+    scope: decision.scope,
+    stage: workOrder.stage,
+    graphRef,
+    decisionRef,
+    requiredEvidence: decision.requiredEvidence,
+    requiredOutputKinds: workOrder.requiredOutputKinds,
+    requiredInputRefs: workOrder.requiredInputRefs,
+    acceptedEvidenceRefs: [],
+    missingEvidence: workOrder.requiredOutputKinds,
+    evidenceSurface: evidenceSurfaceForStage(workOrder.stage, decision.scope.branch),
+    status: decision.blockedStages.includes(workOrder.stage) ? 'blocked' : workOrder.requiredOutputKinds.length > 0 ? 'missing' : 'ready',
+    inputHash: stableHash(JSON.stringify({ decisionHash: decision.inputHash, stage: workOrder.stage, requiredOutputKinds: workOrder.requiredOutputKinds })),
+    generatedAt
+  }));
+}
+
+function buildDiagnosticProjections(decision: LifecycleRiskDecision, graphRef: RuntimeRef, route: LifecycleRouteProjection, generatedAt: string): DiagnosticProjection[] {
+  if (route.status !== 'blocked') {
+    return [];
+  }
+  const diagnosticId = 'lifecycle-blocked';
+  return [{
+    contract: 'sdd-diagnostic-projection-v1',
+    scope: decision.scope,
+    graphRef,
+    stage: null,
+    diagnosticId,
+    severity: 'blocking',
+    kind: 'lifecycle_blocked',
+    message: route.routeReason,
+    ownerStage: 'lifecycle',
+    expected: 'A non-blocked lifecycle graph with at least one legal next action.',
+    actual: `Lifecycle profile is ${decision.profile} with approval policy ${decision.approvalPolicy}.`,
+    reasonRefs: [route.decisionRef],
+    blockerRefs: route.blockerRefs,
+    recommendedCommand: lifecycleRefreshCommand(decision.scope.branch),
+    recoveryCommands: [lifecycleRefreshCommand(decision.scope.branch), `sdd status --branch ${decision.scope.branch} --json`],
+    authority: 'lifecycle_graph',
+    inputHash: stableHash(JSON.stringify({ decisionHash: decision.inputHash, diagnosticId, reasons: decision.reasons })),
+    generatedAt
+  }];
+}
+
+function buildStageWorkOrder(stage: SddStage, decision: LifecycleRiskDecision, decisionRef: RuntimeRef, generatedAt: string): StageWorkOrder {
+  if (stage === 'spec') {
+    return buildSpecStageWorkOrder(deriveSpecCollaborationProfile(decision, generatedAt), decisionRef, generatedAt);
+  }
+  if (stage === 'plan') {
+    return buildPlanStageWorkOrder(decision.scope, decisionRef, decision.inputRefs, generatedAt);
+  }
+  if (stage === 'tasks') {
+    return buildTasksStageWorkOrder(decision.scope, decisionRef, decision.inputRefs, generatedAt);
+  }
+  if (stage === 'execute') {
+    return buildExecuteStageWorkOrder(decision.scope, decisionRef, decision.inputRefs, generatedAt);
+  }
+  return buildShipStageWorkOrder(decision.scope, decisionRef, decision.inputRefs, generatedAt);
+}
+
+function authorityReasons(
+  scope: RuntimeScope,
+  decision: RuntimeProjectionEnvelope<LifecycleRiskDecision> | null,
+  graph: RuntimeProjectionEnvelope<LifecycleGraphInstance> | null,
+  route: RuntimeProjectionEnvelope<LifecycleRouteProjection> | null,
+  requiredStages: SddStage[],
+  workOrders: RuntimeProjectionEnvelope<StageWorkOrderProjection>[],
+  evidenceSelections: RuntimeProjectionEnvelope<EvidenceSelectionProjection>[]
+): string[] {
+  const reasons = [];
+  if (!decision) {
+    reasons.push('Lifecycle risk decision projection is missing.');
+  }
+  if (!graph) {
+    reasons.push('Lifecycle graph instance projection is missing.');
+  }
+  if (!route) {
+    reasons.push('Lifecycle route projection is missing.');
+  }
+  if (decision && graph && graph.payload.decisionInputHash !== decision.payload.inputHash) {
+    reasons.push(`Lifecycle graph instance is stale for lifecycle risk decision input ${decision.payload.inputHash}.`);
+  }
+  if (decision && graph && route) {
+    const expectedRoute = buildLifecycleRouteProjection(decision.payload, graph.payload, projectionRef(LIFECYCLE_GRAPH_INSTANCE_PROJECTION_TYPE, lifecycleGraphScopeKey(scope)), route.payload.generatedAt);
+    if (route.payload.inputHash !== expectedRoute.inputHash) {
+      reasons.push('Lifecycle route projection is stale for lifecycle graph instance.');
+    }
+  }
+  const expectedGraphRef = projectionRef(LIFECYCLE_GRAPH_INSTANCE_PROJECTION_TYPE, lifecycleGraphScopeKey(scope)).ref;
+  const expectedDecisionRef = projectionRef(LIFECYCLE_RISK_DECISION_PROJECTION_TYPE, lifecycleRiskDecisionScopeKey(scope)).ref;
+  const staleWorkOrders = workOrders.filter((workOrder) => workOrder.payload.graphRef.ref !== expectedGraphRef || workOrder.payload.decisionRef.ref !== expectedDecisionRef).map((workOrder) => workOrder.payload.stage);
+  if (staleWorkOrders.length > 0) {
+    reasons.push(`Stage work order projection is stale for ${staleWorkOrders.join(', ')}.`);
+  }
+  const staleEvidenceSelections = evidenceSelections.filter((selection) => selection.payload.graphRef.ref !== expectedGraphRef || selection.payload.decisionRef.ref !== expectedDecisionRef).map((selection) => selection.payload.stage);
+  if (staleEvidenceSelections.length > 0) {
+    reasons.push(`Evidence selection projection is stale for ${staleEvidenceSelections.join(', ')}.`);
+  }
+  const missingWorkOrders = requiredStages.filter((stage) => !workOrders.some((workOrder) => workOrder.payload.stage === stage));
+  if (missingWorkOrders.length > 0) {
+    reasons.push(`Stage work order projection is missing for ${missingWorkOrders.join(', ')}.`);
+  }
+  const missingEvidenceSelections = requiredStages.filter((stage) => !evidenceSelections.some((selection) => selection.payload.stage === stage));
+  if (missingEvidenceSelections.length > 0) {
+    reasons.push(`Evidence selection projection is missing for ${missingEvidenceSelections.join(', ')}.`);
+  }
+  return reasons;
+}
+
+function nextRequiredAfter(requiredStages: SddStage[], stage: SddStage): SddStage | null {
+  const index = requiredStages.indexOf(stage);
+  return index >= 0 ? requiredStages[index + 1] ?? null : null;
+}
+
+function projectionRef(projectionType: string, scopeKey: string): RuntimeRef {
+  return { kind: 'projection', ref: `${projectionType}:${scopeKey}` };
+}
+
+function commandForStage(stage: SddStage, scope: RuntimeScope): string {
+  const branchArg = `--branch ${scope.branch}`;
+  if (stage === 'spec') {
+    return `sdd spec ${branchArg} --json`;
+  }
+  if (stage === 'plan') {
+    return `sdd plan ${branchArg} --json`;
+  }
+  if (stage === 'tasks') {
+    return `sdd instructions tasks ${branchArg} --json`;
+  }
+  if (stage === 'execute') {
+    return `sdd execute ${branchArg} --json`;
+  }
+  return `sdd ship close ${branchArg} --compact-json`;
+}
+
+function closureCommandForStage(stage: SddStage, scope: RuntimeScope): string {
+  const branchArg = `--branch ${scope.branch}`;
+  return `sdd ${stage} close ${branchArg} --compact-json`;
+}
+
+function lifecycleRefreshCommand(branch: string): string {
+  return `sdd spec --branch ${branch} --json`;
+}
+
+function evidenceSurfaceForStage(stage: SddStage, branch: string): string[] {
+  if (stage === 'spec' || stage === 'plan' || stage === 'tasks') {
+    return [`specs/${branch}/${stage}.md`, `.sdd/runs/${branch}/${stage}/*.md`];
+  }
+  return [`.sdd/runs/${branch}/${stage}/*.md`];
+}
+
+function stageTargetRef(stage: SddStage, scope: RuntimeScope): RuntimeRef | null {
+  if (stage === 'spec' || stage === 'plan' || stage === 'tasks') {
+    return { kind: 'document', ref: `specs/${scope.branch}/${stage}.md` };
+  }
+  return null;
+}
+
+function stableHash(value: string): string {
+  return createHash('sha256').update(value).digest('hex');
+}

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

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

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

@@ -1,4 +1,4 @@
-export * from './lifecycle/decision-gate.js';
-export * from './lifecycle/rendering.js';
-export * from './lifecycle/risk-signals.js';
-export * from './lifecycle/ship.js';
+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

@@ -1,50 +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' | '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;
-}
+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' | 'ship';
+
+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

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