sdd-agent-platform 0.4.1 → 0.5.0

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

@@ -1,116 +1,122 @@
-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 STAGE_TEAM_RUNTIME_CONTRACT_VERSION = 'phase-8.15-stage-team-runtime-v1';
-export const WORKFLOW_GATE_RUNTIME_CONTRACT_VERSION = 'phase-8.16-workflow-gate-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;
+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 STAGE_TEAM_RUNTIME_CONTRACT_VERSION = 'phase-8.15-stage-team-runtime-v1';
+export const WORKFLOW_GATE_RUNTIME_CONTRACT_VERSION = 'phase-8.16-workflow-gate-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 const STAGE_COLLABORATION_RUNTIME_CONTRACT_VERSION = 'phase-9.1-stage-collaboration-runtime-v1';
+export const LIFECYCLE_GRAPH_INSTANCE_CONTRACT_VERSION = 'sdd-lifecycle-graph-instance-v1';
+export const LIFECYCLE_ROUTE_PROJECTION_CONTRACT_VERSION = 'sdd-lifecycle-route-projection-v1';
+export const STAGE_WORK_ORDER_PROJECTION_CONTRACT_VERSION = 'sdd-stage-work-order-projection-v1';
+export const EVIDENCE_SELECTION_PROJECTION_CONTRACT_VERSION = 'sdd-evidence-selection-projection-v1';
+export const DIAGNOSTIC_PROJECTION_CONTRACT_VERSION = 'sdd-diagnostic-projection-v1';
+
+export type RuntimeConfidence = 'high' | 'medium' | 'low';
+export type RuntimeProjectionStaleness = 'fresh' | 'stale' | 'incompatible' | 'unknown';
+export type SddStage = 'spec' | 'plan' | 'tasks' | 'execute' | '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

@@ -1,183 +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 });
-  }
-});
+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 });
+  }
+});