sdd-agent-platform 0.2.0 → 0.4.0

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

@@ -0,0 +1,40 @@
+import type { RuntimeRef, RuntimeScope, SddStage } from '../contracts.js';
+import { STAGE_RUN_CONTRACT_VERSION, WORKFLOW_HANDOFF_CONTRACT_VERSION } from '../contracts.js';
+
+export type StageRunStatus = 'pending' | 'active' | 'completed' | 'blocked' | 'skipped' | 'failed';
+export type WorkflowHandoffStatus = 'proposed' | 'accepted' | 'rejected' | 'blocked';
+
+export interface StageRun {
+  contract: typeof STAGE_RUN_CONTRACT_VERSION;
+  id: string;
+  scope: RuntimeScope;
+  stage: SddStage;
+  ownerAgent: string;
+  coMainAgents: string[];
+  status: StageRunStatus;
+  inputRefs: RuntimeRef[];
+  outputRefs: RuntimeRef[];
+  decisionRefs: RuntimeRef[];
+  blockingReasons: string[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface WorkflowHandoff {
+  contract: typeof WORKFLOW_HANDOFF_CONTRACT_VERSION;
+  id: string;
+  scope: RuntimeScope;
+  fromStage: SddStage;
+  toStage: SddStage;
+  fromAgent: string;
+  toAgent: string;
+  status: WorkflowHandoffStatus;
+  outputRefs: RuntimeRef[];
+  requiredInputRefs: RuntimeRef[];
+  riskDecisionRef: RuntimeRef;
+  evidenceRefs: RuntimeRef[];
+  openQuestions: string[];
+  blockingGaps: string[];
+  createdAt: string;
+  decidedAt?: string;
+}

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

@@ -0,0 +1,209 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { setTimeout } from 'node:timers/promises';
+import test from 'node:test';
+
+import { STAGE_RUN_CONTRACT_VERSION, WORKFLOW_HANDOFF_CONTRACT_VERSION, LIFECYCLE_RISK_DECISION_CONTRACT_VERSION, type RuntimeRef, type RuntimeScope } from '../contracts.js';
+import { initProject } from '../config/init-project.js';
+import type { LifecycleRiskDecision } from '../risk.js';
+import { recordRuntimeProjectionEnvelope } from '../storage/runtime-store.js';
+import type { StageRun, WorkflowHandoff } from './contracts.js';
+import { canTransitionStageRun, canTransitionWorkflowHandoff, inspectWorkflowStageHandoff, recordStageRunProjection, recordWorkflowHandoffProjection, readStageRunProjection, readWorkflowHandoffProjection, STAGE_RUNTIME_PRODUCER_VERSION, transitionStageRun, validateStageRun, validateWorkflowHandoff, WORKFLOW_HANDOFF_PROJECTION_TYPE, workflowHandoffScopeKey } from './runtime.js';
+
+const scope: RuntimeScope = { branch: 'master', taskId: 'PHASE8-6', runId: 'run-1' };
+const projectionRef: RuntimeRef = { kind: 'projection', ref: 'phase8_lifecycle_risk_decision:master:PHASE8-6:run-1:none' };
+const artifactRef: RuntimeRef = { kind: 'artifact', ref: 'artifacts/phase8-stage-handoff-review.md' };
+const evidenceRef: RuntimeRef = { kind: 'evidence', ref: 'artifacts/phase8-stage-handoff-validation.md#AC-7' };
+
+async function removeTempRoot(root: string): Promise<void> {
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    try {
+      await rm(root, { recursive: true, force: true });
+      return;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EBUSY' || attempt === 4) {
+        throw error;
+      }
+      await setTimeout(100);
+    }
+  }
+}
+
+test('stage run state machine allows legal transitions and rejects terminal reopen', () => {
+  const active = stageRun('active');
+  const completed = transitionStageRun(active, 'completed', { updatedAt: '2026-05-18T00:01:00.000Z', outputRefs: [artifactRef] });
+  const reopened = transitionStageRun(completed.stageRun, 'active');
+
+  assert.equal(canTransitionStageRun('active', 'completed'), true);
+  assert.equal(completed.valid, true);
+  assert.equal(completed.stageRun.status, 'completed');
+  assert.deepEqual(completed.stageRun.outputRefs, [artifactRef]);
+  assert.equal(canTransitionStageRun('completed', 'active'), false);
+  assert.equal(reopened.valid, false);
+  assert.match(reopened.issues[0], /Illegal stage transition/);
+});
+
+test('stage validation rejects subagent lifecycle owners', () => {
+  const result = validateStageRun({ ...stageRun('active'), ownerAgent: 'review-subagent' });
+
+  assert.equal(result.valid, false);
+  assert.match(result.issues[0], /subagents cannot own lifecycle stages/);
+});
+
+test('workflow handoff validation considers source stage risk refs evidence and blockers', () => {
+  const valid = validateWorkflowHandoff({
+    handoff: handoff('proposed'),
+    sourceStageRun: stageRun('completed'),
+    lifecycleRiskDecision: riskDecision('compact', 'review-required')
+  });
+  const blocked = validateWorkflowHandoff({
+    handoff: { ...handoff('proposed'), evidenceRefs: [], openQuestions: ['Need acceptance owner.'] },
+    sourceStageRun: stageRun('active'),
+    lifecycleRiskDecision: riskDecision('blocked', 'blocked')
+  });
+
+  assert.equal(valid.valid, true);
+  assert.equal(valid.recommendedStatus, 'proposed');
+  assert.equal(valid.considered.sourceStageStatus, 'completed');
+  assert.equal(blocked.valid, false);
+  assert.equal(blocked.recommendedStatus, 'blocked');
+  assert.equal(blocked.issues.some((issue) => /only completed or skipped/.test(issue)), true);
+  assert.equal(blocked.issues.some((issue) => /Lifecycle risk decision blocks/.test(issue)), true);
+  assert.equal(blocked.issues.some((issue) => /no evidence refs/.test(issue)), true);
+});
+
+test('workflow handoff state machine accepts proposed handoff and rejects terminal mutation', () => {
+  const accepted = canTransitionWorkflowHandoff('proposed', 'accepted');
+  const terminal = canTransitionWorkflowHandoff('accepted', 'blocked');
+
+  assert.equal(accepted, true);
+  assert.equal(terminal, false);
+});
+
+test('stage run and workflow handoff projections can be written read and inspected', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-stage-runtime-'));
+  try {
+    await initProject(root);
+    const stage = stageRun('completed');
+    const flow = handoff('accepted');
+
+    const stageWrite = await recordStageRunProjection(root, stage);
+    const handoffWrite = await recordWorkflowHandoffProjection(root, flow);
+    const restoredStage = await readStageRunProjection(root, scope, 'do');
+    const restoredHandoff = await readWorkflowHandoffProjection(root, scope, 'do', 'test');
+    const diagnostic = await inspectWorkflowStageHandoff(root, 'master');
+
+    assert.equal(stageWrite.status, 'created');
+    assert.equal(handoffWrite.status, 'created');
+    assert.equal(restoredStage?.payload.status, 'completed');
+    assert.equal(restoredHandoff?.payload.status, 'accepted');
+    assert.equal(diagnostic.status, 'fresh');
+    assert.equal(diagnostic.latestStageRun?.stage, 'do');
+    assert.equal(diagnostic.latestHandoff?.toStage, 'test');
+  } finally {
+    await removeTempRoot(root);
+  }
+});
+
+test('workflow handoff diagnostics report blocked rejected and stale projections', async () => {
+  const blockedRoot = await mkdtemp(path.join(tmpdir(), 'sdd-stage-runtime-blocked-'));
+  const rejectedRoot = await mkdtemp(path.join(tmpdir(), 'sdd-stage-runtime-rejected-'));
+  const staleRoot = await mkdtemp(path.join(tmpdir(), 'sdd-stage-runtime-stale-'));
+  try {
+    await initProject(blockedRoot);
+    await recordStageRunProjection(blockedRoot, stageRun('blocked'));
+    await recordWorkflowHandoffProjection(blockedRoot, { ...handoff('blocked'), blockingGaps: ['Acceptance evidence missing.'] });
+    const blocked = await inspectWorkflowStageHandoff(blockedRoot, 'master');
+
+    await initProject(rejectedRoot);
+    await recordStageRunProjection(rejectedRoot, stageRun('completed'));
+    await recordWorkflowHandoffProjection(rejectedRoot, handoff('rejected'));
+    const rejected = await inspectWorkflowStageHandoff(rejectedRoot, 'master');
+
+    await initProject(staleRoot);
+    const staleHandoff = handoff('accepted');
+    await recordRuntimeProjectionEnvelope(staleRoot, {
+      projectionType: WORKFLOW_HANDOFF_PROJECTION_TYPE,
+      scopeKey: workflowHandoffScopeKey(staleHandoff.scope, staleHandoff.fromStage, staleHandoff.toStage),
+      inputHash: 'old-handoff-input',
+      producer: 'phase8-stage-runtime',
+      producerVersion: STAGE_RUNTIME_PRODUCER_VERSION,
+      payload: staleHandoff,
+      generatedAt: staleHandoff.decidedAt
+    });
+    const stale = await inspectWorkflowStageHandoff(staleRoot, 'master');
+
+    assert.equal(blocked.status, 'blocked');
+    assert.equal(rejected.status, 'rejected');
+    assert.equal(stale.status, 'stale');
+  } finally {
+    await Promise.all([removeTempRoot(blockedRoot), removeTempRoot(rejectedRoot), removeTempRoot(staleRoot)]);
+  }
+});
+
+function stageRun(status: StageRun['status']): StageRun {
+  return {
+    contract: STAGE_RUN_CONTRACT_VERSION,
+    id: `stage-${status}`,
+    scope,
+    stage: 'do',
+    ownerAgent: 'implementer',
+    coMainAgents: ['reviewer'],
+    status,
+    inputRefs: [projectionRef],
+    outputRefs: status === 'completed' ? [artifactRef] : [],
+    decisionRefs: [projectionRef],
+    blockingReasons: status === 'blocked' ? ['Waiting on acceptance evidence.'] : [],
+    createdAt: '2026-05-18T00:00:00.000Z',
+    updatedAt: `2026-05-18T00:0${statusOrder(status)}:00.000Z`
+  };
+}
+
+function handoff(status: WorkflowHandoff['status']): WorkflowHandoff {
+  return {
+    contract: WORKFLOW_HANDOFF_CONTRACT_VERSION,
+    id: `handoff-${status}`,
+    scope,
+    fromStage: 'do',
+    toStage: 'test',
+    fromAgent: 'implementer',
+    toAgent: 'validator',
+    status,
+    outputRefs: [artifactRef],
+    requiredInputRefs: [projectionRef],
+    riskDecisionRef: projectionRef,
+    evidenceRefs: [evidenceRef],
+    openQuestions: [],
+    blockingGaps: status === 'blocked' ? ['Acceptance evidence missing.'] : [],
+    createdAt: '2026-05-18T00:10:00.000Z',
+    decidedAt: status === 'proposed' ? undefined : '2026-05-18T00:11:00.000Z'
+  };
+}
+
+function riskDecision(profile: LifecycleRiskDecision['profile'], approvalPolicy: LifecycleRiskDecision['approvalPolicy']): LifecycleRiskDecision {
+  return {
+    contract: LIFECYCLE_RISK_DECISION_CONTRACT_VERSION,
+    scope,
+    profile,
+    requiredStages: profile === 'blocked' ? [] : ['do', 'test'],
+    skippedStages: [],
+    blockedStages: profile === 'blocked' ? ['spec', 'plan', 'tasks', 'verifies', 'do', 'test', 'sync-back', 'ship'] : [],
+    requiredEvidence: [],
+    requiredReviews: [],
+    humanCheckpointRequired: approvalPolicy !== 'auto-allow',
+    approvalPolicy,
+    inputRefs: [projectionRef],
+    signalRefs: [],
+    policyVersion: 'phase8-risk-kernel-v1',
+    inputHash: 'risk-input',
+    confidence: profile === 'blocked' ? 'low' : 'high',
+    reasons: [],
+    generatedAt: '2026-05-18T00:00:00.000Z'
+  };
+}
+
+function statusOrder(status: StageRun['status']): number {
+  return ['pending', 'active', 'completed', 'blocked', 'skipped', 'failed'].indexOf(status) + 1;
+}

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

@@ -0,0 +1,352 @@
+import { createHash } from 'node:crypto';
+
+import type { RuntimeProjectionEnvelope, RuntimeRef, RuntimeScope, RuntimeProjectionStaleness, SddStage } from '../contracts.js';
+import { readRuntimeProjectionEnvelope, recordRuntimeProjectionEnvelope, runtimeProjectionStaleness, listRuntimeProjections, type RuntimeProjectionEnvelopeWriteResult } from '../storage/runtime-store.js';
+import type { LifecycleRiskDecision } from '../risk/contracts.js';
+import type { StageRun, StageRunStatus, WorkflowHandoff, WorkflowHandoffStatus } from './contracts.js';
+
+export const STAGE_RUNTIME_PRODUCER_VERSION = 'phase8-stage-runtime-v1';
+export const STAGE_RUN_PROJECTION_TYPE = 'phase8_stage_run';
+export const WORKFLOW_HANDOFF_PROJECTION_TYPE = 'phase8_workflow_handoff';
+
+const STAGE_RUN_TRANSITIONS: Record<StageRunStatus, readonly StageRunStatus[]> = {
+  pending: ['active', 'blocked', 'skipped'],
+  active: ['completed', 'blocked', 'failed'],
+  blocked: ['active', 'skipped', 'failed'],
+  completed: [],
+  skipped: [],
+  failed: []
+};
+
+const WORKFLOW_HANDOFF_TRANSITIONS: Record<WorkflowHandoffStatus, readonly WorkflowHandoffStatus[]> = {
+  proposed: ['accepted', 'rejected', 'blocked'],
+  blocked: ['proposed', 'rejected'],
+  accepted: [],
+  rejected: []
+};
+
+export interface StageRuntimeValidationResult {
+  valid: boolean;
+  issues: string[];
+}
+
+export interface StageRunTransitionResult extends StageRuntimeValidationResult {
+  stageRun: StageRun;
+}
+
+export interface WorkflowHandoffTransitionResult extends StageRuntimeValidationResult {
+  handoff: WorkflowHandoff;
+}
+
+export interface WorkflowHandoffValidationInput {
+  handoff: WorkflowHandoff;
+  sourceStageRun?: StageRun | null;
+  lifecycleRiskDecision?: LifecycleRiskDecision | null;
+}
+
+export interface WorkflowHandoffValidationResult extends StageRuntimeValidationResult {
+  recommendedStatus: WorkflowHandoffStatus;
+  considered: {
+    sourceStageStatus: StageRunStatus | null;
+    lifecycleRiskProfile: LifecycleRiskDecision['profile'] | null;
+    lifecycleApprovalPolicy: LifecycleRiskDecision['approvalPolicy'] | null;
+    requiredInputRefs: number;
+    outputRefs: number;
+    evidenceRefs: number;
+    openQuestions: number;
+    blockingGaps: number;
+  };
+}
+
+export type WorkflowStageHandoffDiagnosticStatus = 'missing' | 'fresh' | 'stale' | 'blocked' | 'rejected' | 'incompatible';
+
+export interface WorkflowStageHandoffDiagnostic {
+  status: WorkflowStageHandoffDiagnosticStatus;
+  branch: string;
+  activeStage: StageRun | null;
+  latestStageRun: StageRun | null;
+  latestHandoff: WorkflowHandoff | null;
+  latestStageStaleness: RuntimeProjectionStaleness;
+  latestHandoffStaleness: RuntimeProjectionStaleness;
+  projectionCounts: {
+    stageRuns: number;
+    handoffs: number;
+  };
+  reasons: string[];
+}
+
+export function canTransitionStageRun(from: StageRunStatus, to: StageRunStatus): boolean {
+  return STAGE_RUN_TRANSITIONS[from].includes(to);
+}
+
+export function transitionStageRun(stageRun: StageRun, status: StageRunStatus, options: { updatedAt?: string; outputRefs?: RuntimeRef[]; blockingReasons?: string[] } = {}): StageRunTransitionResult {
+  if (!canTransitionStageRun(stageRun.status, status)) {
+    return {
+      valid: false,
+      issues: [`Illegal stage transition ${stageRun.status} -> ${status} for ${stageRun.stage}.`],
+      stageRun
+    };
+  }
+  const next: StageRun = {
+    ...stageRun,
+    status,
+    outputRefs: options.outputRefs ?? stageRun.outputRefs,
+    blockingReasons: options.blockingReasons ?? stageRun.blockingReasons,
+    updatedAt: options.updatedAt ?? new Date().toISOString()
+  };
+  return { valid: true, issues: validateStageRun(next).issues, stageRun: next };
+}
+
+export function canTransitionWorkflowHandoff(from: WorkflowHandoffStatus, to: WorkflowHandoffStatus): boolean {
+  return WORKFLOW_HANDOFF_TRANSITIONS[from].includes(to);
+}
+
+export function transitionWorkflowHandoff(handoff: WorkflowHandoff, status: WorkflowHandoffStatus, options: { decidedAt?: string; blockingGaps?: string[]; openQuestions?: string[] } = {}): WorkflowHandoffTransitionResult {
+  if (!canTransitionWorkflowHandoff(handoff.status, status)) {
+    return {
+      valid: false,
+      issues: [`Illegal handoff transition ${handoff.status} -> ${status} for ${handoff.fromStage} -> ${handoff.toStage}.`],
+      handoff
+    };
+  }
+  const next: WorkflowHandoff = {
+    ...handoff,
+    status,
+    blockingGaps: options.blockingGaps ?? handoff.blockingGaps,
+    openQuestions: options.openQuestions ?? handoff.openQuestions,
+    decidedAt: options.decidedAt ?? new Date().toISOString()
+  };
+  return { valid: true, issues: [], handoff: next };
+}
+
+export function validateStageRun(stageRun: StageRun): StageRuntimeValidationResult {
+  const issues: string[] = [];
+  if (isSubagentRole(stageRun.ownerAgent)) {
+    issues.push(`Stage owner ${stageRun.ownerAgent} is a subagent; subagents cannot own lifecycle stages.`);
+  }
+  if ((stageRun.status === 'blocked' || stageRun.status === 'failed') && stageRun.blockingReasons.length === 0) {
+    issues.push(`Stage ${stageRun.stage} is ${stageRun.status} but has no blocking reason.`);
+  }
+  return { valid: issues.length === 0, issues };
+}
+
+export function validateWorkflowHandoff(input: WorkflowHandoffValidationInput): WorkflowHandoffValidationResult {
+  const issues: string[] = [];
+  const { handoff, sourceStageRun, lifecycleRiskDecision } = input;
+  if (!sourceStageRun) {
+    issues.push('Handoff source stage run is missing.');
+  } else if (sourceStageRun.stage !== handoff.fromStage) {
+    issues.push(`Handoff source stage ${handoff.fromStage} does not match stage run ${sourceStageRun.stage}.`);
+  } else if (!['completed', 'skipped'].includes(sourceStageRun.status)) {
+    issues.push(`Handoff source stage ${handoff.fromStage} is ${sourceStageRun.status}; only completed or skipped stages can hand off control.`);
+  }
+  if (!lifecycleRiskDecision) {
+    issues.push('Lifecycle risk decision is missing for handoff validation.');
+  } else if (lifecycleRiskDecision.profile === 'blocked' || lifecycleRiskDecision.approvalPolicy === 'blocked') {
+    issues.push('Lifecycle risk decision blocks workflow handoff.');
+  }
+  if (handoff.requiredInputRefs.length === 0) {
+    issues.push('Handoff has no required input refs.');
+  }
+  if (handoff.outputRefs.length === 0) {
+    issues.push('Handoff has no source output refs.');
+  }
+  if (requiresEvidenceForHandoff(handoff.toStage) && handoff.evidenceRefs.length === 0) {
+    issues.push(`Handoff to ${handoff.toStage} has no evidence refs.`);
+  }
+  if (handoff.openQuestions.length > 0) {
+    issues.push(`Handoff has open questions: ${handoff.openQuestions.join(' ')}`);
+  }
+  if (handoff.blockingGaps.length > 0) {
+    issues.push(`Handoff has blocking gaps: ${handoff.blockingGaps.join(' ')}`);
+  }
+
+  return {
+    valid: issues.length === 0,
+    issues,
+    recommendedStatus: issues.length === 0 ? 'proposed' : 'blocked',
+    considered: {
+      sourceStageStatus: sourceStageRun?.status ?? null,
+      lifecycleRiskProfile: lifecycleRiskDecision?.profile ?? null,
+      lifecycleApprovalPolicy: lifecycleRiskDecision?.approvalPolicy ?? null,
+      requiredInputRefs: handoff.requiredInputRefs.length,
+      outputRefs: handoff.outputRefs.length,
+      evidenceRefs: handoff.evidenceRefs.length,
+      openQuestions: handoff.openQuestions.length,
+      blockingGaps: handoff.blockingGaps.length
+    }
+  };
+}
+
+export function stageRunScopeKey(scope: RuntimeScope, stage: SddStage): string {
+  return [scope.branch, scope.taskId ?? 'all', scope.runId ?? 'none', scope.changeRef ?? 'none', stage].join(':');
+}
+
+export function workflowHandoffScopeKey(scope: RuntimeScope, fromStage: SddStage, toStage: SddStage): string {
+  return [scope.branch, scope.taskId ?? 'all', scope.runId ?? 'none', scope.changeRef ?? 'none', fromStage, toStage].join(':');
+}
+
+export async function recordStageRunProjection(projectRoot: string, stageRun: StageRun): Promise<RuntimeProjectionEnvelopeWriteResult<StageRun>> {
+  return recordRuntimeProjectionEnvelope(projectRoot, {
+    projectionType: STAGE_RUN_PROJECTION_TYPE,
+    scopeKey: stageRunScopeKey(stageRun.scope, stageRun.stage),
+    inputHash: stageRunInputHash(stageRun),
+    producer: 'phase8-stage-runtime',
+    producerVersion: STAGE_RUNTIME_PRODUCER_VERSION,
+    generatedAt: stageRun.updatedAt,
+    payload: stageRun
+  });
+}
+
+export async function readStageRunProjection(projectRoot: string, scope: RuntimeScope, stage: SddStage): Promise<RuntimeProjectionEnvelope<StageRun> | null> {
+  return readRuntimeProjectionEnvelope(projectRoot, STAGE_RUN_PROJECTION_TYPE, stageRunScopeKey(scope, stage));
+}
+
+export async function recordWorkflowHandoffProjection(projectRoot: string, handoff: WorkflowHandoff): Promise<RuntimeProjectionEnvelopeWriteResult<WorkflowHandoff>> {
+  return recordRuntimeProjectionEnvelope(projectRoot, {
+    projectionType: WORKFLOW_HANDOFF_PROJECTION_TYPE,
+    scopeKey: workflowHandoffScopeKey(handoff.scope, handoff.fromStage, handoff.toStage),
+    inputHash: workflowHandoffInputHash(handoff),
+    producer: 'phase8-stage-runtime',
+    producerVersion: STAGE_RUNTIME_PRODUCER_VERSION,
+    generatedAt: handoff.decidedAt ?? handoff.createdAt,
+    payload: handoff
+  });
+}
+
+export async function readWorkflowHandoffProjection(projectRoot: string, scope: RuntimeScope, fromStage: SddStage, toStage: SddStage): Promise<RuntimeProjectionEnvelope<WorkflowHandoff> | null> {
+  return readRuntimeProjectionEnvelope(projectRoot, WORKFLOW_HANDOFF_PROJECTION_TYPE, workflowHandoffScopeKey(scope, fromStage, toStage));
+}
+
+export async function inspectWorkflowStageHandoff(projectRoot: string, branch: string): Promise<WorkflowStageHandoffDiagnostic> {
+  const projections = await listRuntimeProjections(projectRoot, [STAGE_RUN_PROJECTION_TYPE, WORKFLOW_HANDOFF_PROJECTION_TYPE]);
+  const stageEnvelopes = projections
+    .filter((projection) => projection.projectionType === STAGE_RUN_PROJECTION_TYPE)
+    .map((projection) => projection.payload as RuntimeProjectionEnvelope<StageRun>)
+    .filter((envelope) => envelope?.payload?.scope?.branch === branch);
+  const handoffEnvelopes = projections
+    .filter((projection) => projection.projectionType === WORKFLOW_HANDOFF_PROJECTION_TYPE)
+    .map((projection) => projection.payload as RuntimeProjectionEnvelope<WorkflowHandoff>)
+    .filter((envelope) => envelope?.payload?.scope?.branch === branch);
+  const latestStageEnvelope = latestEnvelope(stageEnvelopes);
+  const latestHandoffEnvelope = latestEnvelope(handoffEnvelopes);
+  const activeStage = latestEnvelope(stageEnvelopes.filter((envelope) => envelope.payload.status === 'active'))?.payload ?? null;
+  const latestStageStaleness = stageEnvelopeStaleness(latestStageEnvelope);
+  const latestHandoffStaleness = handoffEnvelopeStaleness(latestHandoffEnvelope);
+  const latestHandoff = latestHandoffEnvelope?.payload ?? null;
+  const status: WorkflowStageHandoffDiagnosticStatus = !latestHandoffEnvelope
+    ? 'missing'
+    : latestStageStaleness === 'incompatible' || latestHandoffStaleness === 'incompatible'
+      ? 'incompatible'
+      : latestStageStaleness === 'stale' || latestHandoffStaleness === 'stale'
+        ? 'stale'
+        : latestHandoff?.status === 'blocked'
+          ? 'blocked'
+          : latestHandoff?.status === 'rejected'
+            ? 'rejected'
+            : 'fresh';
+
+  return {
+    status,
+    branch,
+    activeStage,
+    latestStageRun: latestStageEnvelope?.payload ?? null,
+    latestHandoff,
+    latestStageStaleness,
+    latestHandoffStaleness,
+    projectionCounts: {
+      stageRuns: stageEnvelopes.length,
+      handoffs: handoffEnvelopes.length
+    },
+    reasons: workflowStageHandoffReasons(status, latestStageEnvelope?.payload ?? null, latestHandoff)
+  };
+}
+
+function stageEnvelopeStaleness(envelope: RuntimeProjectionEnvelope<StageRun> | null): RuntimeProjectionStaleness {
+  return runtimeProjectionStaleness(envelope, {
+    inputHash: envelope ? stageRunInputHash(envelope.payload) : 'missing',
+    producerVersion: STAGE_RUNTIME_PRODUCER_VERSION
+  });
+}
+
+function handoffEnvelopeStaleness(envelope: RuntimeProjectionEnvelope<WorkflowHandoff> | null): RuntimeProjectionStaleness {
+  return runtimeProjectionStaleness(envelope, {
+    inputHash: envelope ? workflowHandoffInputHash(envelope.payload) : 'missing',
+    producerVersion: STAGE_RUNTIME_PRODUCER_VERSION
+  });
+}
+
+function workflowStageHandoffReasons(status: WorkflowStageHandoffDiagnosticStatus, latestStageRun: StageRun | null, latestHandoff: WorkflowHandoff | null): string[] {
+  if (status === 'missing') {
+    return ['Workflow handoff projection is missing; legacy next-command behavior remains authoritative.'];
+  }
+  if (status === 'stale') {
+    return ['Workflow handoff projection is stale against its current payload.'];
+  }
+  if (status === 'incompatible') {
+    return [`Workflow handoff projection producer is incompatible with ${STAGE_RUNTIME_PRODUCER_VERSION}.`];
+  }
+  if (status === 'blocked') {
+    return [`Workflow handoff is blocked: ${latestHandoff?.blockingGaps.join(' ') || latestStageRun?.blockingReasons.join(' ') || 'no blocking detail recorded'}.`];
+  }
+  if (status === 'rejected') {
+    return [`Workflow handoff ${latestHandoff?.fromStage ?? 'unknown'} -> ${latestHandoff?.toStage ?? 'unknown'} was rejected.`];
+  }
+  return [`Workflow handoff is fresh: ${latestHandoff?.fromStage ?? 'unknown'} -> ${latestHandoff?.toStage ?? 'unknown'} status=${latestHandoff?.status ?? 'none'}.`];
+}
+
+function latestEnvelope<TPayload>(envelopes: Array<RuntimeProjectionEnvelope<TPayload>>): RuntimeProjectionEnvelope<TPayload> | null {
+  return [...envelopes].sort((left, right) => right.generatedAt.localeCompare(left.generatedAt))[0] ?? null;
+}
+
+function stageRunInputHash(stageRun: StageRun): string {
+  return stableHash(JSON.stringify({
+    contract: stageRun.contract,
+    id: stageRun.id,
+    scope: stageRun.scope,
+    stage: stageRun.stage,
+    ownerAgent: stageRun.ownerAgent,
+    coMainAgents: stageRun.coMainAgents,
+    status: stageRun.status,
+    inputRefs: stageRun.inputRefs,
+    outputRefs: stageRun.outputRefs,
+    decisionRefs: stageRun.decisionRefs,
+    blockingReasons: stageRun.blockingReasons,
+    createdAt: stageRun.createdAt,
+    updatedAt: stageRun.updatedAt
+  }));
+}
+
+function workflowHandoffInputHash(handoff: WorkflowHandoff): string {
+  return stableHash(JSON.stringify({
+    contract: handoff.contract,
+    id: handoff.id,
+    scope: handoff.scope,
+    fromStage: handoff.fromStage,
+    toStage: handoff.toStage,
+    fromAgent: handoff.fromAgent,
+    toAgent: handoff.toAgent,
+    status: handoff.status,
+    outputRefs: handoff.outputRefs,
+    requiredInputRefs: handoff.requiredInputRefs,
+    riskDecisionRef: handoff.riskDecisionRef,
+    evidenceRefs: handoff.evidenceRefs,
+    openQuestions: handoff.openQuestions,
+    blockingGaps: handoff.blockingGaps,
+    createdAt: handoff.createdAt,
+    decidedAt: handoff.decidedAt ?? null
+  }));
+}
+
+function requiresEvidenceForHandoff(toStage: SddStage): boolean {
+  return toStage === 'test' || toStage === 'goal-verify' || toStage === 'sync-back' || toStage === 'ship';
+}
+
+function isSubagentRole(role: string): boolean {
+  const normalized = role.toLowerCase();
+  return normalized === 'subagent' || normalized.startsWith('subagent:') || normalized.endsWith('-subagent');
+}
+
+function stableHash(value: string): string {
+  return createHash('sha256').update(value, 'utf8').digest('hex');
+}

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

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