sdd-agent-platform 0.3.0 → 0.4.0

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

@@ -0,0 +1,114 @@
+export const RUNTIME_VERSION = 'phase-1.2-runtime-skeleton';
+export const PROJECT_CONFIG_CONTRACT = 'phase-1.2-project-contract';
+export const RUN_STATE_CONTRACT = 'phase-1.2-run-state-contract';
+export const EVENT_LOG_CONTRACT = 'phase-1.2-event-log-contract';
+export const ARTIFACT_PATH_CONTRACT = 'phase-1.2-artifact-path-contract';
+export const LEGACY_LIFECYCLE_DECISION_CONTRACT = 'phase-1.2-lifecycle-decision-contract';
+export const LIFECYCLE_DECISION_CONTRACT = 'sdd-lifecycle-decision-v1';
+export const LIFECYCLE_DECISION_VERSION = '1.3.0';
+export const SDD_RESULT_CONTRACT = 'sdd-result-v1';
+export const SDD_RESULT_VERSION = '1.3.0';
+export const DELEGATION_LIVENESS_CONTRACT = 'sdd-delegation-liveness-v1';
+export const DELEGATION_LIVENESS_VERSION = '1.3.0';
+
+export const ARTIFACT_RESULT_INGESTION_CONTRACT_VERSION = 'phase-3.6-artifact-result-ingestion-v1';
+export const TASK_GRAPH_PLANNER_CONTRACT_VERSION = 'phase-3.9-task-graph-planner-v1';
+export const WAVE_PLANNER_CONTRACT_VERSION = 'phase-3.10-wave-planner-v1';
+export const BACKGROUND_EXECUTOR_CONTRACT_VERSION = 'phase-3.11-background-executor-v1';
+export const WAVE_EXECUTOR_CONTRACT_VERSION = 'phase-3.12-wave-executor-v1';
+export const LOCAL_RUN_INDEX_CONTRACT_VERSION = 'phase-3.13-local-run-index-v1';
+export const GOVERNANCE_POLICY_CONTRACT_VERSION = 'phase-3.14-governance-policy-v1';
+export const CONTEXT_RESOLVER_CONTRACT_VERSION = 'phase-5.1-context-resolver-v1';
+export const LIFECYCLE_RISK_GATE_CONTRACT_VERSION = 'phase-5.1-lifecycle-risk-gate-v1';
+export const OUTPUT_QUALITY_CONTRACT_VERSION = 'phase-5.1-output-quality-v1';
+export const WORKFLOW_GATE_CONTRACT_VERSION = 'phase-5.2-workflow-gate-v1';
+export const AGENT_REGISTRY_CONTRACT_VERSION = 'phase-5.2-agent-registry-v1';
+export const TASK_GRAPH_CONTRACT_VERSION = 'phase-5.3-task-graph-v1';
+export const TASK_RUN_EVIDENCE_CONTRACT_VERSION = 'phase-5.3-task-run-evidence-v1';
+export const QUERY_STATUS_CONTRACT_VERSION = 'phase-5.4-query-status-v1';
+export const SKILL_AGENT_EVAL_CONTRACT_VERSION = 'phase-5.5-skill-agent-eval-v1';
+export const HARNESS_LEARNING_CONTRACT_VERSION = 'phase-5.5-harness-learning-v1';
+export const PROJECT_CONTEXT_PACK_CONTRACT_VERSION = 'phase-5.5-project-context-pack-v1';
+export const AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION = 'phase-6.0-agent-skill-team-runtime-v1';
+export const CAPABILITY_SOURCE_CATALOG_VERSION = 'phase-6.0-capability-source-catalog-v1';
+export const EXTERNAL_AGENT_PACK_IMPORT_POLICY_VERSION = 'phase-6.0-external-agent-pack-import-policy-v1';
+export const TOOL_PERMISSION_SPEC_VERSION = 'phase-6.0-tool-permission-spec-v1';
+export const HOST_ADAPTER_CONTRACT_VERSION = 'phase-6.0-host-adapter-contract-v1';
+export const AGENT_ROUTER_CONTRACT_VERSION = 'phase-6.0-agent-router-v1';
+export const TEAM_MODE_POLICY_VERSION = 'phase-6.0-team-mode-policy-v1';
+export const EVIDENCE_INGESTION_CONTRACT_VERSION = 'phase-6.0-evidence-ingestion-v1';
+export const AGENT_EXECUTION_RECORD_CONTRACT_VERSION = 'phase-6.0-agent-execution-record-v1';
+export const TEAM_SESSION_RECORD_CONTRACT_VERSION = 'phase-6.0-team-session-record-v1';
+export const RESIDENT_WORKER_RUNTIME_CONTRACT_VERSION = 'phase-6.1-resident-worker-runtime-v1';
+export const SDD_EVIDENCE_CONTRACT = 'sdd-evidence-v1';
+export const SDD_EVIDENCE_VERSION = '1.0.0';
+export const ACCEPTANCE_POLICY_RULESET_VERSION = 'acceptance-policy-v1';
+export const INVOCATION_LEDGER_CONTRACT_VERSION = 'phase-6.9-invocation-ledger-v1';
+export const ROUTE_CACHE_CONTRACT_VERSION = 'phase-6.9-route-cache-v1';
+export const RUNTIME_PROFILE_CONTRACT_VERSION = 'phase-6.9-runtime-profile-v1';
+export const CONTEXT_BUDGET_CONTRACT_VERSION = 'phase-6.10-context-budget-v1';
+export const COMMAND_OUTPUT_SUMMARY_CONTRACT_VERSION = 'sdd-command-output-summary-v1';
+export const EVIDENCE_SUMMARY_CONTRACT_VERSION = 'sdd-evidence-summary-v1';
+export const CONTEXT_PACKAGE_CONTRACT_VERSION = 'sdd-context-package-v1';
+export const LOG_WORKER_SUMMARY_CONTRACT_VERSION = 'sdd-log-worker-summary-v1';
+export const RUNTIME_ANALYSIS_CONTRACT_VERSION = 'phase-7-runtime-analysis-v1';
+export const WORKFLOW_STATE_RESOLVER_CONTRACT_VERSION = 'phase-7.3-workflow-state-resolver-v1';
+export const VERIFY_DOCUMENT_CONTRACT_VERSION = 'sdd-verify-doc-v1';
+export const AGENT_CAPABILITY_CATALOG_CONTRACT_VERSION = 'phase-7.6-agent-capability-catalog-v1';
+export const COMMAND_TEAM_RUNTIME_CONTRACT_VERSION = 'phase-7.7-command-team-runtime-v1';
+export const RUNTIME_PROJECTION_ENVELOPE_CONTRACT_VERSION = 'sdd-runtime-projection-envelope-v1';
+export const CODING_FACT_SET_CONTRACT_VERSION = 'sdd-coding-fact-set-v1';
+export const CODING_RISK_PROFILE_CONTRACT_VERSION = 'sdd-coding-risk-profile-v1';
+export const LIFECYCLE_RISK_DECISION_CONTRACT_VERSION = 'sdd-lifecycle-risk-decision-v1';
+export const STAGE_RUN_CONTRACT_VERSION = 'sdd-stage-run-v1';
+export const WORKFLOW_HANDOFF_CONTRACT_VERSION = 'sdd-workflow-handoff-v1';
+export const WORK_UNIT_CONTRACT_VERSION = 'sdd-work-unit-v1';
+export const SUBAGENT_DEFINITION_CONTRACT_VERSION = 'sdd-subagent-definition-v1';
+export const SUBAGENT_DISPATCH_CONTRACT_VERSION = 'sdd-subagent-dispatch-v1';
+export const SUBAGENT_RESULT_CONTRACT_VERSION = 'sdd-subagent-result-v1';
+export const CONTEXT_LOAD_SIGNAL_CONTRACT_VERSION = 'sdd-context-load-signal-v1';
+export const CONTEXT_OFFLOAD_DECISION_CONTRACT_VERSION = 'sdd-context-offload-decision-v1';
+export const SCOPED_CONTEXT_HANDOFF_CONTRACT_VERSION = 'sdd-scoped-context-handoff-v1';
+export const TEST_EVIDENCE_RUN_CONTRACT_VERSION = 'sdd-test-evidence-run-v1';
+export const MODEL_PRODUCED_ARTIFACT_CONTRACT_VERSION = 'sdd-model-produced-artifact-v1';
+
+export type RuntimeConfidence = 'high' | 'medium' | 'low';
+export type RuntimeProjectionStaleness = 'fresh' | 'stale' | 'incompatible' | 'unknown';
+export type SddStage = 'spec' | 'plan' | 'tasks' | 'verifies' | 'do' | 'test' | 'goal-verify' | 'sync-back' | 'ship';
+export type RuntimeRefKind = 'document' | 'task' | 'run' | 'artifact' | 'projection' | 'evidence' | 'command' | 'external';
+
+export interface RuntimeScope {
+  branch: string;
+  taskId?: string;
+  runId?: string;
+  changeRef?: string;
+}
+
+export interface RuntimeRef {
+  kind: RuntimeRefKind;
+  ref: string;
+  hash?: string;
+}
+
+export interface RuntimeProjectionEnvelope<TPayload> {
+  contract: typeof RUNTIME_PROJECTION_ENVELOPE_CONTRACT_VERSION;
+  projectionType: string;
+  scopeKey: string;
+  id: string;
+  inputHash: string;
+  producer: string;
+  producerVersion: string;
+  generatedAt: string;
+  staleReason?: string;
+  payload: TPayload;
+}
+
+export interface ModelProducedArtifact {
+  contract: typeof MODEL_PRODUCED_ARTIFACT_CONTRACT_VERSION;
+  producer: 'main-agent' | 'co-main-agent' | 'subagent';
+  authority: 'stage-owned' | 'candidate' | 'non-authoritative';
+  allowedUse: Array<'summary' | 'diagnostic' | 'test-suggestion' | 'evidence-candidate'>;
+  forbiddenUse: Array<'final-risk-decision' | 'stage-completion' | 'ship-gate-pass'>;
+  artifactRefs: string[];
+  reviewedByRuntime: boolean;
+}

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

@@ -0,0 +1,183 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { initProject } from '../config/init-project.js';
+import { doctor } from '../doctor/doctor.js';
+import { writeArtifact } from '../run-state/artifacts.js';
+import { appendEvent } from '../run-state/events.js';
+import { createRun, writeRunState } from '../run-state/run-state.js';
+import { inspectDelegationQueueItem, listDelegationQueueItems } from './queue.js';
+import { getDelegationStateMachine, validateDelegationStateTransition } from './state-machine.js';
+import { createDelegationRecord, isDelegationStale, isDelegationTerminal, validateDelegationRecord } from './validation.js';
+
+test('delegation queue contract derives stable items from run-state delegations', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-queue-api-'));
+  try {
+    await initProject(root);
+    const state = await createRun(root, { runId: 'queue-run-001' });
+    const delegation = createDelegationRecord({
+      delegationId: 'D-T001-implementer-001',
+      task: 'T001',
+      agent: 'implementer',
+      expectedArtifact: 'artifacts/implement-T001.md',
+      runMode: 'background'
+    });
+    await writeRunState(root, {
+      ...state,
+      currentTask: 'T001',
+      delegations: { [delegation.delegationId]: delegation }
+    });
+
+    const snapshot = await listDelegationQueueItems(root);
+    const scopedSnapshot = await listDelegationQueueItems(root, { runId: 'queue-run-001' });
+    const item = await inspectDelegationQueueItem(root, 'queue-run-001:D-T001-implementer-001');
+    const missing = await inspectDelegationQueueItem(root, 'missing:item');
+
+    assert.equal(snapshot.version, 'phase-3.3-delegation-queue-contract-v1');
+    assert.equal(snapshot.items.length, 1);
+    assert.equal(scopedSnapshot.items.length, 1);
+    assert.equal(item?.id, 'queue-run-001:D-T001-implementer-001');
+    assert.equal(item?.taskId, 'T001');
+    assert.equal(item?.requestedCapabilityId, 'sdd-cli');
+    assert.equal(item?.dedupeKey, 'queue-run-001:T001:implementer');
+    assert.equal(item?.statusSource, 'run_state_delegation');
+    assert.equal(item?.requiredEvidence.includes('artifacts/implement-T001.md'), true);
+    assert.equal(missing, null);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('doctor reports delegation queue contract visibility', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-queue-doctor-'));
+  try {
+    await initProject(root);
+    const report = await doctor(root, { latestOnly: true });
+    const check = report.checks.find((item) => item.check === 'delegation_queue_contract');
+
+    assert.equal(check?.level, 'PASS');
+    assert.match(check?.message ?? '', /phase-3\.3-delegation-queue-contract-v1/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('delegation state machine exposes allowed transitions and blocks terminal reopen', () => {
+  const machine = getDelegationStateMachine();
+  const allowed = validateDelegationStateTransition('RUNNING', 'COMPLETED', 'delegation_completed');
+  const retry = validateDelegationStateTransition('RECOVERABLE', 'RUNNING', 'delegation_retry_started');
+  const terminalReopen = validateDelegationStateTransition('COMPLETED', 'RUNNING', 'delegation_retry_started');
+  const wrongEvent = validateDelegationStateTransition('RUNNING', 'COMPLETED', 'delegation_failed');
+
+  assert.equal(machine.version, 'phase-3.4-delegation-state-machine-v1');
+  assert.equal(machine.statuses.includes('RECOVERABLE'), true);
+  assert.equal(machine.terminalStatuses.includes('COMPLETED'), true);
+  assert.equal(machine.transitions.some((transition) => transition.from === 'STALE' && transition.to === 'TIMED_OUT' && transition.event === 'delegation_timeout'), true);
+  assert.equal(allowed.valid, true);
+  assert.equal(retry.valid, true);
+  assert.equal(terminalReopen.valid, false);
+  assert.match(terminalReopen.issues.map((issue) => issue.message).join('\n'), /Terminal delegation status COMPLETED cannot transition to RUNNING/);
+  assert.equal(wrongEvent.valid, false);
+});
+
+test('doctor reports delegation state machine visibility', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-state-machine-doctor-'));
+  try {
+    await initProject(root);
+    const report = await doctor(root, { latestOnly: true });
+    const check = report.checks.find((item) => item.check === 'delegation_state_machine');
+
+    assert.equal(check?.level, 'PASS');
+    assert.match(check?.message ?? '', /phase-3\.4-delegation-state-machine-v1/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('doctor reports illegal delegation event transitions', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-state-machine-events-'));
+  try {
+    await initProject(root);
+    const state = await createRun(root, { runId: 'state-machine-run-001' });
+    const delegation = createDelegationRecord({
+      delegationId: 'D-T003-implementer-001',
+      task: 'T003',
+      agent: 'implementer',
+      expectedArtifact: 'artifacts/implement-T003.md'
+    });
+    await writeRunState(root, {
+      ...state,
+      delegations: {
+        [delegation.delegationId]: { ...delegation, status: 'COMPLETED', terminalEventAt: new Date().toISOString() }
+      }
+    });
+    await appendEvent(root, 'state-machine-run-001', {
+      event: 'delegation_started',
+      runId: 'state-machine-run-001',
+      data: { delegationId: delegation.delegationId }
+    });
+    await appendEvent(root, 'state-machine-run-001', {
+      event: 'delegation_completed',
+      runId: 'state-machine-run-001',
+      data: { delegationId: delegation.delegationId }
+    });
+    await appendEvent(root, 'state-machine-run-001', {
+      event: 'delegation_started',
+      runId: 'state-machine-run-001',
+      data: { delegationId: delegation.delegationId }
+    });
+
+    const report = await doctor(root, { allRuns: true });
+    const check = report.checks.find((item) => item.check === 'delegation_state_transition');
+
+    assert.equal(check?.level, 'FAIL');
+    assert.match(check?.message ?? '', /cannot transition COMPLETED -> RUNNING on delegation_started/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('delegation terminal and stale contract checks are explicit', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-delegation-'));
+  try {
+    await initProject(root);
+    const state = await createRun(root, { runId: 'run-1' });
+    const running = createDelegationRecord({
+      delegationId: 'D-T1-reviewer-001',
+      task: 'T1',
+      agent: 'reviewer',
+      expectedArtifact: 'artifacts/review-T1.md',
+      startedAt: '2026-05-01T00:00:00.000Z',
+      timeoutSeconds: 60
+    });
+
+    assert.equal(isDelegationTerminal(running.status), false);
+    assert.equal(isDelegationStale(running, new Date('2026-05-01T00:02:00.000Z')), true);
+    const stale = await validateDelegationRecord(root, state.runId, running, new Date('2026-05-01T00:02:00.000Z'));
+    assert.equal(stale.valid, false);
+    assert.equal(stale.stale, true);
+    assert.equal(stale.issues.some((issue) => issue.field === 'status' && /stale/.test(issue.message)), true);
+
+    const completed = { ...running, status: 'COMPLETED' as const, terminalEventAt: '2026-05-01T00:00:30.000Z' };
+    await writeArtifact(root, state.runId, 'review-T1.md', `# Review
+
+\`\`\`sdd-result
+contract: sdd-result-v1
+version: 1.3.0
+agent: reviewer
+task: T1
+status: PASS
+artifacts:
+  - artifacts/review-T1.md
+\`\`\`
+`);
+    const terminal = await validateDelegationRecord(root, state.runId, completed, new Date('2026-05-01T00:02:00.000Z'));
+    assert.equal(isDelegationTerminal(completed.status), true);
+    assert.equal(terminal.valid, true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

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

@@ -0,0 +1,23 @@
+import { DELEGATION_LIVENESS_CONTRACT, DELEGATION_LIVENESS_VERSION } from '../contracts.js';
+import type { DelegationStatus } from './state-machine.js';
+
+export type { DelegationStatus } from './state-machine.js';
+export type DelegationRunMode = 'foreground' | 'background';
+
+export interface DelegationRecord {
+  contract: typeof DELEGATION_LIVENESS_CONTRACT;
+  version: typeof DELEGATION_LIVENESS_VERSION;
+  delegationId: string;
+  task: string;
+  agent: string;
+  runMode: DelegationRunMode;
+  blocking: boolean;
+  requiredForPhaseExit: boolean;
+  status: DelegationStatus;
+  startedAt: string;
+  lastHeartbeatAt: string | null;
+  timeoutSeconds: number;
+  expectedArtifact: string;
+  terminalEventRequired: boolean;
+  terminalEventAt?: string | null;
+}

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

@@ -0,0 +1,58 @@
+import { readFile } from 'node:fs/promises';
+import { parseProjectConfig } from '../config/project-config.js';
+import { getProjectConfigPath } from '../runtime-paths.js';
+import { readAllRunStates, readRunState } from '../run-state/run-state.js';
+import type { DelegationQueueItem } from '../run-state/run-index.js';
+import type { RunState, RunStateDelegationRecord } from '../run-state/model.js';
+
+export const DELEGATION_QUEUE_CONTRACT_VERSION = 'phase-3.3-delegation-queue-contract-v1';
+
+export interface DelegationQueueSnapshot {
+  version: string;
+  items: DelegationQueueItem[];
+}
+
+export async function listDelegationQueueItems(projectRoot: string, options: { runId?: string } = {}): Promise<DelegationQueueSnapshot> {
+  await assertProjectConfigReadable(projectRoot);
+  const states = options.runId
+    ? [await readRunState(projectRoot, options.runId)]
+    : await readAllRunStates(projectRoot);
+  const items = states
+    .filter((state) => state.status !== 'archived')
+    .flatMap((state) => Object.values(state.delegations).map((delegation) => delegationQueueItemFromRunState(state, delegation)))
+    .sort((left, right) => left.id.localeCompare(right.id));
+  return {
+    version: DELEGATION_QUEUE_CONTRACT_VERSION,
+    items
+  };
+}
+
+export async function inspectDelegationQueueItem(projectRoot: string, queueItemId: string): Promise<DelegationQueueItem | null> {
+  const snapshot = await listDelegationQueueItems(projectRoot);
+  return snapshot.items.find((item) => item.id === queueItemId) ?? null;
+}
+
+function delegationQueueItemFromRunState(state: RunState, delegation: RunStateDelegationRecord): DelegationQueueItem {
+  return {
+    id: `${state.runId}:${delegation.delegationId}`,
+    runId: state.runId,
+    delegationId: delegation.delegationId,
+    taskId: delegation.task,
+    agent: delegation.agent,
+    requestedCapabilityId: 'sdd-cli',
+    dedupeKey: `${state.runId}:${delegation.task}:${delegation.agent}`,
+    status: delegation.status,
+    statusSource: 'run_state_delegation',
+    runMode: delegation.runMode,
+    expectedArtifact: delegation.expectedArtifact,
+    requiredEvidence: [delegation.expectedArtifact, state.eventLogPath],
+    createdAt: delegation.startedAt,
+    updatedAt: delegation.terminalEventAt ?? delegation.lastHeartbeatAt ?? state.updatedAt
+  };
+}
+
+async function assertProjectConfigReadable(projectRoot: string): Promise<void> {
+  const configPath = getProjectConfigPath(projectRoot);
+  const raw = await readFile(configPath, 'utf8');
+  parseProjectConfig(raw, configPath);
+}

package/node_modules/@sdd-agent-platform/core/src/delegation/run-state.ts

@@ -0,0 +1,14 @@
+import { readRunState, writeRunState } from '../run-state/run-state.js';
+import type { DelegationRecord } from './model.js';
+
+export async function persistDelegation(projectRoot: string, runId: string, delegation: DelegationRecord): Promise<void> {
+  const state = await readRunState(projectRoot, runId);
+  await writeRunState(projectRoot, {
+    ...state,
+    status: delegation.status === 'RUNNING' ? 'running' : state.status,
+    delegations: {
+      ...state.delegations,
+      [delegation.delegationId]: delegation
+    }
+  });
+}

package/node_modules/@sdd-agent-platform/core/src/delegation/state-machine.ts

@@ -0,0 +1,90 @@
+export const DELEGATION_STATE_MACHINE_VERSION = 'phase-3.4-delegation-state-machine-v1';
+
+export type DelegationStatus = 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'TIMED_OUT' | 'CANCELLED' | 'RECOVERABLE' | 'STALE';
+
+export interface ContractValidationIssue {
+  field: string;
+  message: string;
+  recommendation: string;
+}
+
+export interface DelegationStateTransition {
+  from: DelegationStatus;
+  to: DelegationStatus;
+  event: string;
+  terminal: boolean;
+}
+
+export interface DelegationStateMachine {
+  version: string;
+  statuses: DelegationStatus[];
+  terminalStatuses: DelegationStatus[];
+  transitions: DelegationStateTransition[];
+}
+
+export interface DelegationStateTransitionValidation {
+  valid: boolean;
+  from: DelegationStatus;
+  to: DelegationStatus;
+  event: string | null;
+  issues: ContractValidationIssue[];
+}
+
+export const DELEGATION_STATUSES: DelegationStatus[] = ['PENDING', 'RUNNING', 'COMPLETED', 'FAILED', 'TIMED_OUT', 'CANCELLED', 'RECOVERABLE', 'STALE'];
+export const TERMINAL_DELEGATION_STATUSES: DelegationStatus[] = ['COMPLETED', 'FAILED', 'TIMED_OUT', 'CANCELLED'];
+
+const DELEGATION_STATE_TRANSITIONS: DelegationStateTransition[] = [
+  { from: 'PENDING', to: 'RUNNING', event: 'delegation_started', terminal: false },
+  { from: 'PENDING', to: 'CANCELLED', event: 'delegation_cancelled', terminal: true },
+  { from: 'RUNNING', to: 'COMPLETED', event: 'delegation_completed', terminal: true },
+  { from: 'RUNNING', to: 'FAILED', event: 'delegation_failed', terminal: true },
+  { from: 'RUNNING', to: 'TIMED_OUT', event: 'delegation_timeout', terminal: true },
+  { from: 'RUNNING', to: 'CANCELLED', event: 'delegation_cancelled', terminal: true },
+  { from: 'RUNNING', to: 'RECOVERABLE', event: 'artifact_invalid', terminal: false },
+  { from: 'RUNNING', to: 'STALE', event: 'delegation_stale', terminal: false },
+  { from: 'RECOVERABLE', to: 'RUNNING', event: 'delegation_retry_started', terminal: false },
+  { from: 'RECOVERABLE', to: 'FAILED', event: 'delegation_failed', terminal: true },
+  { from: 'RECOVERABLE', to: 'CANCELLED', event: 'delegation_cancelled', terminal: true },
+  { from: 'STALE', to: 'RUNNING', event: 'delegation_heartbeat', terminal: false },
+  { from: 'STALE', to: 'TIMED_OUT', event: 'delegation_timeout', terminal: true },
+  { from: 'STALE', to: 'FAILED', event: 'delegation_failed', terminal: true },
+  { from: 'STALE', to: 'CANCELLED', event: 'delegation_cancelled', terminal: true }
+];
+
+export function getDelegationStateMachine(): DelegationStateMachine {
+  return {
+    version: DELEGATION_STATE_MACHINE_VERSION,
+    statuses: [...DELEGATION_STATUSES],
+    terminalStatuses: [...TERMINAL_DELEGATION_STATUSES],
+    transitions: DELEGATION_STATE_TRANSITIONS.map((transition) => ({ ...transition }))
+  };
+}
+
+export function validateDelegationStateTransition(from: DelegationStatus, to: DelegationStatus, event: string | null = null): DelegationStateTransitionValidation {
+  const issues: ContractValidationIssue[] = [];
+  if (!DELEGATION_STATUSES.includes(from)) {
+    issues.push(contractIssue('from', `Unsupported delegation status ${from}.`, 'Use a status declared by the Phase 3.4 delegation state machine.'));
+  }
+  if (!DELEGATION_STATUSES.includes(to)) {
+    issues.push(contractIssue('to', `Unsupported delegation status ${to}.`, 'Use a status declared by the Phase 3.4 delegation state machine.'));
+  }
+  if (TERMINAL_DELEGATION_STATUSES.includes(from)) {
+    issues.push(contractIssue('from', `Terminal delegation status ${from} cannot transition to ${to}.`, 'Create a new delegation id for retry instead of reopening a terminal delegation.'));
+  }
+  const transition = DELEGATION_STATE_TRANSITIONS.find((candidate) => candidate.from === from && candidate.to === to && (event === null || candidate.event === event));
+  if (!transition) {
+    const eventText = event === null ? '' : ` on ${event}`;
+    issues.push(contractIssue('transition', `Transition ${from} -> ${to}${eventText} is not allowed.`, 'Use one of the declared Phase 3.4 delegation state machine transitions.'));
+  }
+  return {
+    valid: issues.length === 0,
+    from,
+    to,
+    event,
+    issues
+  };
+}
+
+function contractIssue(field: string, message: string, recommendation: string): ContractValidationIssue {
+  return { field, message, recommendation };
+}

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

@@ -0,0 +1,124 @@
+import { DELEGATION_LIVENESS_CONTRACT, DELEGATION_LIVENESS_VERSION } from '../contracts.js';
+import { toArtifactRootRelativePath } from '../runtime-paths.js';
+import { validateSddResultArtifact } from '../artifacts/sdd-result.js';
+import type { DelegationRecord, DelegationStatus } from './model.js';
+
+export interface ContractValidationIssue {
+  field: string;
+  message: string;
+  recommendation: string;
+}
+
+export interface DelegationValidationReport {
+  valid: boolean;
+  delegation: DelegationRecord;
+  terminal: boolean;
+  stale: boolean;
+  issues: ContractValidationIssue[];
+}
+
+export function createDelegationRecord(input: { delegationId: string; task: string; agent: string; expectedArtifact: string; runMode?: DelegationRecord['runMode']; blocking?: boolean; requiredForPhaseExit?: boolean; startedAt?: string; timeoutSeconds?: number; status?: DelegationStatus }): DelegationRecord {
+  return {
+    contract: DELEGATION_LIVENESS_CONTRACT,
+    version: DELEGATION_LIVENESS_VERSION,
+    delegationId: input.delegationId,
+    task: input.task,
+    agent: input.agent,
+    runMode: input.runMode ?? 'foreground',
+    blocking: input.blocking ?? true,
+    requiredForPhaseExit: input.requiredForPhaseExit ?? true,
+    status: input.status ?? 'RUNNING',
+    startedAt: input.startedAt ?? new Date().toISOString(),
+    lastHeartbeatAt: null,
+    timeoutSeconds: input.timeoutSeconds ?? 900,
+    expectedArtifact: input.expectedArtifact,
+    terminalEventRequired: true,
+    terminalEventAt: null
+  };
+}
+
+export function isDelegationTerminal(status: DelegationStatus): boolean {
+  return status === 'COMPLETED' || status === 'FAILED' || status === 'TIMED_OUT' || status === 'CANCELLED';
+}
+
+export function isDelegationStale(delegation: DelegationRecord, now = new Date()): boolean {
+  if (delegation.status !== 'RUNNING') {
+    return false;
+  }
+  const heartbeatOrStart = delegation.lastHeartbeatAt ?? delegation.startedAt;
+  const timestamp = Date.parse(heartbeatOrStart);
+  if (Number.isNaN(timestamp) || delegation.timeoutSeconds <= 0) {
+    return true;
+  }
+  return now.getTime() - timestamp > delegation.timeoutSeconds * 1000;
+}
+
+export async function validateDelegationRecord(projectRoot: string, runId: string, delegation: DelegationRecord, now = new Date()): Promise<DelegationValidationReport> {
+  const issues: ContractValidationIssue[] = [];
+  const terminal = isDelegationTerminal(delegation.status);
+  const stale = isDelegationStale(delegation, now);
+  issues.push(...validateDelegationShape(delegation));
+
+  if (stale) {
+    issues.push(contractIssue('status', `Delegation ${delegation.delegationId} is RUNNING but stale.`, 'Record TIMED_OUT/FAILED/CANCELLED or heartbeat before phase exit.'));
+  }
+  if (delegation.requiredForPhaseExit && delegation.terminalEventRequired && terminal && !delegation.terminalEventAt) {
+    issues.push(contractIssue('terminalEventAt', `Delegation ${delegation.delegationId} is terminal without a terminal event timestamp.`, 'Append and persist the terminal delegation event timestamp.'));
+  }
+  if (delegation.status === 'COMPLETED') {
+    const resultReport = await validateSddResultArtifact(projectRoot, runId, delegation.expectedArtifact, { expectedTask: delegation.task, expectedAgent: delegation.agent });
+    issues.push(...resultReport.issues);
+  }
+
+  return { valid: issues.length === 0, delegation, terminal, stale, issues };
+}
+
+function validateDelegationShape(delegation: DelegationRecord): ContractValidationIssue[] {
+  const issues: ContractValidationIssue[] = [];
+  if (delegation.contract !== DELEGATION_LIVENESS_CONTRACT) {
+    issues.push(contractIssue('contract', `Expected ${DELEGATION_LIVENESS_CONTRACT}, got ${delegation.contract}.`, 'Use the delegation liveness contract id.'));
+  }
+  if (delegation.version !== DELEGATION_LIVENESS_VERSION) {
+    issues.push(contractIssue('version', `Expected ${DELEGATION_LIVENESS_VERSION}, got ${delegation.version}.`, 'Use version: 1.3.0 until a new contract version is introduced.'));
+  }
+  if (!delegation.delegationId) {
+    issues.push(contractIssue('delegationId', 'delegationId is required.', 'Persist a stable delegation id.'));
+  }
+  if (!delegation.task) {
+    issues.push(contractIssue('task', 'delegation task is required.', 'Persist the delegated task id.'));
+  }
+  if (!delegation.agent) {
+    issues.push(contractIssue('agent', 'delegation agent is required.', 'Persist the delegated agent name.'));
+  }
+  if (delegation.runMode !== 'foreground' && delegation.runMode !== 'background') {
+    issues.push(contractIssue('runMode', `Unsupported runMode ${delegation.runMode}.`, 'Use foreground or background.'));
+  }
+  if (!isDelegationStatus(delegation.status)) {
+    issues.push(contractIssue('status', `Unsupported delegation status ${delegation.status}.`, 'Use a status from the delegation liveness contract.'));
+  }
+  if (!Number.isInteger(delegation.timeoutSeconds) || delegation.timeoutSeconds <= 0) {
+    issues.push(contractIssue('timeoutSeconds', 'timeoutSeconds must be a positive integer.', 'Set an explicit positive timeout.'));
+  }
+  validateRunRelativeArtifactReference(delegation.expectedArtifact, issues, 'expectedArtifact');
+  return issues;
+}
+
+function validateRunRelativeArtifactReference(value: string, issues: ContractValidationIssue[], field = 'artifacts'): void {
+  try {
+    toArtifactRootRelativePath(value);
+  } catch (error) {
+    issues.push(contractIssue(field, messageFromError(error), 'Use run-relative artifacts/<file> paths that stay under the run artifact directory.'));
+  }
+}
+
+function isDelegationStatus(value: string): value is DelegationStatus {
+  return value === 'PENDING' || value === 'RUNNING' || value === 'COMPLETED' || value === 'FAILED' || value === 'TIMED_OUT' || value === 'CANCELLED' || value === 'RECOVERABLE' || value === 'STALE';
+}
+
+function contractIssue(field: string, message: string, recommendation: string): ContractValidationIssue {
+  return { field, message, recommendation };
+}
+
+function messageFromError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

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

@@ -0,0 +1,26 @@
+export * from './delegation/model.js';
+export * from './delegation/queue.js';
+export { persistDelegation } from './delegation/run-state.js';
+export {
+  DELEGATION_STATE_MACHINE_VERSION,
+  DELEGATION_STATUSES,
+  TERMINAL_DELEGATION_STATUSES,
+  getDelegationStateMachine,
+  validateDelegationStateTransition
+} from './delegation/state-machine.js';
+export type {
+  ContractValidationIssue as DelegationStateContractValidationIssue,
+  DelegationStateMachine,
+  DelegationStateTransition,
+  DelegationStateTransitionValidation
+} from './delegation/state-machine.js';
+export {
+  createDelegationRecord,
+  isDelegationStale,
+  isDelegationTerminal,
+  validateDelegationRecord
+} from './delegation/validation.js';
+export type {
+  ContractValidationIssue as DelegationRecordContractValidationIssue,
+  DelegationValidationReport
+} from './delegation/validation.js';

package/node_modules/@sdd-agent-platform/core/src/doctor/checks/ai-entries.ts

@@ -0,0 +1,28 @@
+import { checkAiToolEntryDrift } from '../../ai-tools.js';
+import type { DoctorCheck } from '../model.js';
+
+export async function inspectAiToolEntryEvidence(projectRoot: string): Promise<DoctorCheck[]> {
+  const results = await checkAiToolEntryDrift(projectRoot);
+  const checks = results.flatMap((result) => result.entries.map((entry): DoctorCheck => {
+    const check = `ai_entry_${entry.id}`;
+    const message = `${entry.relativePath}: ${entry.message}`;
+    if (entry.status === 'unchanged') {
+      return { level: 'PASS', check, message };
+    }
+    if (entry.status === 'missing' || entry.status === 'drifted') {
+      return { level: 'FAIL', check, message, action: entry.action ?? 'Run sdd update.' };
+    }
+    if (entry.status === 'user-modified') {
+      return { level: 'FAIL', check, message, action: entry.action ?? 'Review manually; sdd update will not overwrite user-modified entries by default.' };
+    }
+    if (entry.status === 'foreign' || entry.status === 'conflict') {
+      return { level: 'FAIL', check, message, action: entry.action ?? 'Review the target file before running sdd update.' };
+    }
+    return { level: 'WARN', check, message, action: entry.action };
+  }));
+
+  if (checks.length === 0) {
+    checks.push({ level: 'WARN', check: 'ai_entries', message: 'No AI tool adapters selected for drift inspection.', action: 'Run sdd init --ai claude-code if Claude Code entries are required.' });
+  }
+  return checks;
+}