sdd-agent-platform 0.3.0 → 0.4.0

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

@@ -0,0 +1,156 @@
+import { inspectAiToolEntryEvidence } from './checks/ai-entries.js';
+import { inspectDocumentChainEvidence } from './checks/document-chain.js';
+import { inspectLocalRunIndexEvidence } from './checks/local-run-index.js';
+import { inspectGitRepository, inspectProjectConfig, inspectRunsDirectoryAccess, inspectSpecsDirectory } from './checks/project.js';
+import { inspectRunEvidence } from './checks/run-evidence.js';
+import { inspectAgentCapabilityCatalogDoctorContract, inspectAgentSkillTeamRuntimeDoctorContract, inspectCapabilityRegistry, inspectCommandTeamRuntimeDoctorContract, inspectGovernancePolicyContract, inspectHarnessLearningDoctorContract, inspectProjectContextPackDoctorContract, inspectQueryStatusBoundaryContract, inspectSkillAgentEvalDoctorContract, inspectToolPluginContracts } from './checks/registries.js';
+import { inspectBackgroundExecutorContract, inspectDelegationQueueContract, inspectDelegationStateMachineContract, inspectLocalRunIndexContract, inspectTaskGraphPlannerContract, inspectWaveExecutorContract, inspectWavePlannerContract, inspectWorkerAdapterContracts, inspectWorktreeIsolationContract, inspectWorktreeLifecycleContract } from './checks/runtime-contracts.js';
+import { inspectRuntimeStoreEvidence } from '../storage/runtime-store.js';
+import { getProjectStatus, statuslineProjectionFromStatus, type ProjectStatus } from '../status/project-status.js';
+import type { DoctorCheck, DoctorReport } from './model.js';
+import { summarizeDoctorStatus } from './summary.js';
+
+
+export async function doctor(projectRoot: string, options: { allRuns?: boolean; latestOnly?: boolean; branch?: string | null } = {}): Promise<DoctorReport> {
+  const checks: DoctorCheck[] = [];
+  checks.push(...await inspectGitRepository(projectRoot));
+
+  const projectConfigInspection = await inspectProjectConfig(projectRoot);
+  checks.push(...projectConfigInspection.checks);
+
+  checks.push(...await inspectRuntimeStoreEvidence(projectRoot));
+  const runsDirectoryInspection = await inspectRunsDirectoryAccess(projectRoot);
+  checks.push(...runsDirectoryInspection.checks);
+  if (runsDirectoryInspection.available) {
+    checks.push(...await inspectRunEvidence(projectRoot, options));
+    checks.push(...await inspectLocalRunIndexEvidence(projectRoot));
+  }
+
+  checks.push(...await inspectSpecsDirectory(projectRoot));
+
+  checks.push(...await inspectDocumentChainEvidence(projectRoot, options.branch ?? undefined));
+  if (projectConfigInspection.exists) {
+    checks.push(...await inspectAiToolEntryEvidence(projectRoot));
+  }
+  checks.push(...await inspectCapabilityRegistry(projectRoot));
+  checks.push(...await inspectToolPluginContracts(projectRoot));
+  checks.push(...await inspectDelegationQueueContract(projectRoot));
+  checks.push(...await inspectDelegationStateMachineContract(projectRoot));
+  checks.push(...await inspectWorkerAdapterContracts(projectRoot));
+  checks.push(...await inspectWorktreeIsolationContract(projectRoot));
+  checks.push(...await inspectWorktreeLifecycleContract(projectRoot));
+  checks.push(...await inspectTaskGraphPlannerContract(projectRoot));
+  checks.push(...await inspectWavePlannerContract(projectRoot));
+  checks.push(...await inspectBackgroundExecutorContract(projectRoot));
+  checks.push(...await inspectWaveExecutorContract(projectRoot));
+  checks.push(...await inspectLocalRunIndexContract(projectRoot));
+  checks.push(...await inspectGovernancePolicyContract(projectRoot));
+  checks.push(...await inspectQueryStatusBoundaryContract(projectRoot));
+  checks.push(...await inspectAgentSkillTeamRuntimeDoctorContract(projectRoot));
+  checks.push(...await inspectAgentCapabilityCatalogDoctorContract(projectRoot));
+  checks.push(...await inspectCommandTeamRuntimeDoctorContract(projectRoot));
+  checks.push(...await inspectSkillAgentEvalDoctorContract(projectRoot));
+  checks.push(...await inspectHarnessLearningDoctorContract(projectRoot));
+  checks.push(...await inspectProjectContextPackDoctorContract(projectRoot));
+  const statusSnapshot = await readDoctorProjectStatus(projectRoot, options.branch ?? undefined);
+  checks.push(...inspectContextTokenRuntime(statusSnapshot));
+  checks.push(...inspectLifecycleRiskRuntime(statusSnapshot));
+  checks.push(...inspectWorkflowHandoffRuntime(statusSnapshot));
+  checks.push(...inspectContextOffloadRuntime(statusSnapshot));
+  checks.push(...inspectSubagentDispatchRuntime(statusSnapshot));
+
+  return {
+    status: summarizeDoctorStatus(checks),
+    checks
+  };
+}
+
+interface DoctorProjectStatusSnapshot {
+  status: ProjectStatus | null;
+  error: unknown | null;
+}
+
+async function readDoctorProjectStatus(projectRoot: string, branch?: string | null): Promise<DoctorProjectStatusSnapshot> {
+  try {
+    return {
+      status: await getProjectStatus(projectRoot, { branch, branchSource: branch ? 'cli_option' : undefined }),
+      error: null
+    };
+  } catch (error) {
+    return { status: null, error };
+  }
+}
+
+function unavailableRuntimeCheck(check: string, label: string, error: unknown): DoctorCheck[] {
+  return [{
+    level: 'WARN',
+    check,
+    message: `${label} unavailable: ${error instanceof Error ? error.message : String(error)}`,
+    action: 'Resolve SDD branch context, then rerun sdd doctor.'
+  }];
+}
+
+function inspectContextTokenRuntime(snapshot: DoctorProjectStatusSnapshot): DoctorCheck[] {
+  if (!snapshot.status) {
+    return unavailableRuntimeCheck('context_token_runtime', 'token runtime projection', snapshot.error);
+  }
+  const statusline = statuslineProjectionFromStatus(snapshot.status);
+  return [{
+    level: statusline.tokenHealth === 'pressure' ? 'WARN' : 'PASS',
+    check: 'context_token_runtime',
+    message: `token_health=${statusline.tokenHealth} context_risk_tasks=${statusline.taskRisk.contextRiskTasks.length} token_risk_tasks=${statusline.taskRisk.tokenRiskTasks.length}`,
+    action: statusline.tokenHealth === 'pressure' ? `Run sdd context build --task <task_id> --branch ${statusline.branch} --mode doctor --profile brief and defer optional material.` : undefined
+  }];
+}
+
+function inspectLifecycleRiskRuntime(snapshot: DoctorProjectStatusSnapshot): DoctorCheck[] {
+  if (!snapshot.status) {
+    return unavailableRuntimeCheck('lifecycle_risk_decision', 'lifecycle risk decision', snapshot.error);
+  }
+  const risk = snapshot.status.lifecycleRisk;
+  return [{
+    level: risk.status === 'blocked' || risk.status === 'incompatible' || risk.approvalPolicy === 'blocked' ? 'FAIL' : risk.status === 'missing' || risk.status === 'stale' || risk.approvalPolicy === 'human-required' ? 'WARN' : 'PASS',
+    check: 'lifecycle_risk_decision',
+    message: `status=${risk.status} profile=${risk.profile ?? 'none'} approval=${risk.approvalPolicy ?? 'none'} input=${risk.inputHash ?? 'none'} expected=${risk.expectedInputHash}`,
+    action: risk.status === 'fresh' ? undefined : `Run lifecycle risk projection for ${risk.scopeKey}; workflow gates now consume this decision directly.`
+  }];
+}
+
+function inspectWorkflowHandoffRuntime(snapshot: DoctorProjectStatusSnapshot): DoctorCheck[] {
+  if (!snapshot.status) {
+    return unavailableRuntimeCheck('workflow_handoff_state', 'workflow handoff state', snapshot.error);
+  }
+  const handoff = snapshot.status.workflowHandoff;
+  return [{
+    level: handoff.status === 'blocked' || handoff.status === 'rejected' || handoff.status === 'incompatible' ? 'FAIL' : handoff.status === 'stale' ? 'WARN' : 'PASS',
+    check: 'workflow_handoff_state',
+    message: `status=${handoff.status} active_stage=${handoff.activeStage?.stage ?? 'none'} latest_stage=${handoff.latestStageRun?.stage ?? 'none'} latest_handoff=${handoff.latestHandoff ? `${handoff.latestHandoff.fromStage}->${handoff.latestHandoff.toStage}:${handoff.latestHandoff.status}` : 'none'} stage_projections=${handoff.projectionCounts.stageRuns} handoff_projections=${handoff.projectionCounts.handoffs}`,
+    action: handoff.status === 'fresh' || handoff.status === 'missing' ? undefined : `Resolve workflow handoff projection for ${snapshot.status.branch}; workflow gates now consume this state directly.`
+  }];
+}
+
+function inspectContextOffloadRuntime(snapshot: DoctorProjectStatusSnapshot): DoctorCheck[] {
+  if (!snapshot.status) {
+    return unavailableRuntimeCheck('context_offload_state', 'context offload state', snapshot.error);
+  }
+  const context = snapshot.status.contextRuntime;
+  return [{
+    level: context.action === 'block-for-curation' ? 'FAIL' : 'PASS',
+    check: 'context_offload_state',
+    message: `level=${context.level} action=${context.action} load_signals=${context.loadSignals} offload_decisions=${context.offloadDecisions} dispatch_refs=${context.dispatchRefs}`,
+    action: context.action === 'block-for-curation' ? `Curate scoped context before stage output for ${snapshot.status.branch}.` : undefined
+  }];
+}
+
+function inspectSubagentDispatchRuntime(snapshot: DoctorProjectStatusSnapshot): DoctorCheck[] {
+  if (!snapshot.status) {
+    return unavailableRuntimeCheck('subagent_dispatch_state', 'subagent dispatch state', snapshot.error);
+  }
+  const dispatches = snapshot.status.subagentDispatches;
+  return [{
+    level: dispatches.status === 'blocked' || dispatches.status === 'failed' || dispatches.status === 'stale' || dispatches.status === 'incompatible' ? 'FAIL' : 'PASS',
+    check: 'subagent_dispatch_state',
+    message: `status=${dispatches.status} dispatches=${dispatches.dispatches} blocking_open=${dispatches.blockingOpen} failed=${dispatches.failed} stale=${dispatches.stale} completed=${dispatches.completed} archived=${dispatches.archived} superseded=${dispatches.superseded}`,
+    action: dispatches.status === 'fresh' || dispatches.status === 'missing' ? undefined : dispatches.reasons.join(' ')
+  }];
+}

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

@@ -0,0 +1,13 @@
+export type DoctorLevel = 'PASS' | 'WARN' | 'FAIL';
+
+export interface DoctorCheck {
+  level: DoctorLevel;
+  check: string;
+  message: string;
+  action?: string;
+}
+
+export interface DoctorReport {
+  status: DoctorLevel;
+  checks: DoctorCheck[];
+}

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

@@ -0,0 +1,11 @@
+import type { DoctorCheck, DoctorLevel } from './model.js';
+
+export function summarizeDoctorStatus(checks: DoctorCheck[]): DoctorLevel {
+  if (checks.some((check) => check.level === 'FAIL')) {
+    return 'FAIL';
+  }
+  if (checks.some((check) => check.level === 'WARN')) {
+    return 'WARN';
+  }
+  return 'PASS';
+}

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

@@ -0,0 +1,2 @@
+export * from './doctor/model.js';
+export * from './doctor/doctor.js';

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

@@ -0,0 +1,37 @@
+import type { RuntimeRef, RuntimeScope } from '../contracts.js';
+import { TEST_EVIDENCE_RUN_CONTRACT_VERSION } from '../contracts.js';
+
+export type TestEvidenceStatus = 'PASS' | 'FAIL' | 'BLOCKED';
+export type EvidenceCoverageStatus = 'complete' | 'partial' | 'missing' | 'stale';
+
+export interface TestCommandEvidence {
+  command: string;
+  status: TestEvidenceStatus;
+  outputRef?: RuntimeRef;
+  evidenceRefs: RuntimeRef[];
+  acceptanceRefs: string[];
+  startedAt: string;
+  completedAt?: string;
+}
+
+export interface AcceptanceEvidenceCoverage {
+  acceptanceRef: string;
+  status: EvidenceCoverageStatus;
+  evidenceRefs: RuntimeRef[];
+  gaps: string[];
+}
+
+export interface UnifiedTestEvidenceRun {
+  contract: typeof TEST_EVIDENCE_RUN_CONTRACT_VERSION;
+  id: string;
+  scope: RuntimeScope;
+  commandStatus: TestEvidenceStatus;
+  evidenceCoverage: EvidenceCoverageStatus;
+  policyJudgment: TestEvidenceStatus;
+  commands: TestCommandEvidence[];
+  acceptanceCoverage: AcceptanceEvidenceCoverage[];
+  syncBackReady: boolean;
+  gaps: string[];
+  next: string;
+  generatedAt: string;
+}

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

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

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

@@ -0,0 +1,190 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import {
+  AGENT_EXECUTION_RECORD_CONTRACT_VERSION,
+  TEAM_SESSION_RECORD_CONTRACT_VERSION
+} from '../contracts.js';
+import {
+  getAgentExecutionRecordPath,
+  getAgentExecutionsDir,
+  getTeamSessionRecordPath,
+  getTeamSessionsDir
+} from '../runtime-paths.js';
+import { exists } from '../storage/json-io.js';
+import { BUILT_IN_SKILL_CAPABILITIES } from '../registries/skill-capabilities.js';
+import type { ArtifactResultIngestionRecord } from '../artifacts/ingestion.js';
+import type {
+  AgentExecutionRecord,
+  AgentExecutionRecordStatus,
+  AgentProfileId,
+  AgentRouterDecision,
+  TeamSessionRecord,
+  TeamSessionRecordStatus
+} from '../router/agent-runtime.js';
+
+export async function writeAgentExecutionRecord(projectRoot: string, record: AgentExecutionRecord): Promise<AgentExecutionRecord> {
+  await mkdir(getAgentExecutionsDir(projectRoot, record.runId), { recursive: true });
+  await writeFile(getAgentExecutionRecordPath(projectRoot, record.runId, record.executionId), `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+  return record;
+}
+
+export async function writeTeamSessionRecord(projectRoot: string, record: TeamSessionRecord): Promise<TeamSessionRecord> {
+  await mkdir(getTeamSessionsDir(projectRoot, record.runId), { recursive: true });
+  await writeFile(getTeamSessionRecordPath(projectRoot, record.runId, record.teamId), `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+  return record;
+}
+
+export async function listAgentExecutionRecords(projectRoot: string, runId: string): Promise<AgentExecutionRecord[]> {
+  const recordsDir = getAgentExecutionsDir(projectRoot, runId);
+  if (!await exists(recordsDir)) {
+    return [];
+  }
+  const entries = await readdir(recordsDir, { withFileTypes: true });
+  const records: AgentExecutionRecord[] = [];
+  for (const entry of entries.filter((candidate) => candidate.isFile() && candidate.name.endsWith('.json'))) {
+    try {
+      const raw = await readFile(path.join(recordsDir, entry.name), 'utf8');
+      records.push(JSON.parse(raw) as AgentExecutionRecord);
+    } catch {
+      continue;
+    }
+  }
+  return records.sort((left, right) => left.createdAt.localeCompare(right.createdAt) || left.executionId.localeCompare(right.executionId));
+}
+
+export async function listTeamSessionRecords(projectRoot: string, runId: string): Promise<TeamSessionRecord[]> {
+  const recordsDir = getTeamSessionsDir(projectRoot, runId);
+  if (!await exists(recordsDir)) {
+    return [];
+  }
+  const entries = await readdir(recordsDir, { withFileTypes: true });
+  const records: TeamSessionRecord[] = [];
+  for (const entry of entries.filter((candidate) => candidate.isFile() && candidate.name.endsWith('.json'))) {
+    try {
+      const raw = await readFile(path.join(recordsDir, entry.name), 'utf8');
+      records.push(JSON.parse(raw) as TeamSessionRecord);
+    } catch {
+      continue;
+    }
+  }
+  return records.sort((left, right) => left.createdAt.localeCompare(right.createdAt) || left.teamId.localeCompare(right.teamId));
+}
+
+export function routeRecordSnapshot(route: AgentRouterDecision): AgentExecutionRecord['routeDecision'] {
+  return {
+    version: route.version,
+    category: route.category,
+    recommendedProfile: route.recommendedProfile,
+    autonomyCeiling: route.autonomyCeiling,
+    requiredCapabilities: route.requiredCapabilities,
+    blockedReason: route.blockedReason
+  };
+}
+
+export function routeRecordId(route: AgentRouterDecision, profile: AgentProfileId): string {
+  const content = JSON.stringify({
+    version: route.version,
+    taskId: route.taskId,
+    branch: route.branch,
+    category: route.category,
+    profile,
+    recommendedProfile: route.recommendedProfile,
+    autonomyCeiling: route.autonomyCeiling,
+    requiredCapabilities: route.requiredCapabilities,
+    toolPermissionProfile: route.toolPermission?.profile ?? null,
+    toolPermissionPolicy: route.toolPermission?.policy ?? null,
+    blockedReason: route.blockedReason
+  });
+  return createHash('sha256').update(content).digest('hex').slice(0, 16);
+}
+
+export function sourceAttributionForCapabilities(capabilityIds: string[], route?: AgentRouterDecision): string[] {
+  return capabilityIds.map((capabilityId) => {
+    const routeSource = route?.registrySources?.find((source) => source.kind === 'skill_capability' && source.id === capabilityId);
+    if (routeSource) {
+      return `${capabilityId}:${routeSource.sourceId ?? routeSource.origin}`;
+    }
+    const capability = BUILT_IN_SKILL_CAPABILITIES.find((candidate) => candidate.id === capabilityId);
+    return capability ? `${capability.id}:${capability.sourceRef}` : capabilityId;
+  });
+}
+
+export function executionProfile(agent: string, route: AgentRouterDecision): AgentProfileId {
+  const normalized = normalizeAgentToken(agent);
+  return route.allowedProfiles.find((profile) => normalizeAgentToken(profile) === normalized) ?? toAgentProfileId(agent) ?? route.recommendedProfile ?? 'implementer';
+}
+
+export function buildAgentExecutionRecord(input: { runId: string; taskId: string; agent: string; route: AgentRouterDecision; status: AgentExecutionRecordStatus; delegationId?: string | null; queueItemId?: string | null; artifactPath?: string | null; ingestion?: ArtifactResultIngestionRecord | null; evidenceSummary: string }): AgentExecutionRecord {
+  const now = new Date().toISOString();
+  const profile = executionProfile(input.agent, input.route);
+  return {
+    version: AGENT_EXECUTION_RECORD_CONTRACT_VERSION,
+    executionId: toSafeRecordId(input.delegationId ?? `${input.taskId}-${input.agent}`),
+    runId: input.runId,
+    taskId: input.taskId,
+    profile,
+    category: input.route.category,
+    host: 'sdd-cli',
+    hostSessionId: input.runId,
+    hostTaskId: input.delegationId ?? null,
+    modelPolicy: input.route.modelPolicy,
+    toolPermission: input.route.toolPermission,
+    capabilitiesUsed: input.route.requiredCapabilities,
+    sourceAttribution: sourceAttributionForCapabilities(input.route.requiredCapabilities, input.route),
+    artifacts: input.artifactPath ? [input.artifactPath] : input.ingestion?.artifactPath ? [input.ingestion.artifactPath] : [],
+    status: input.status,
+    delegationId: input.delegationId ?? null,
+    queueItemId: input.queueItemId ?? null,
+    ingestionStatus: input.ingestion?.status ?? null,
+    resultStatus: input.ingestion?.resultStatus ?? null,
+    routeId: routeRecordId(input.route, profile),
+    routeDecision: routeRecordSnapshot(input.route),
+    evidenceSummary: input.evidenceSummary,
+    createdAt: now,
+    updatedAt: now
+  };
+}
+
+export function buildTeamSessionRecord(input: { runId: string; taskId: string | null; route: AgentRouterDecision; status: TeamSessionRecordStatus; artifacts: string[]; evidenceSummary: string }): TeamSessionRecord {
+  const now = new Date().toISOString();
+  return {
+    version: TEAM_SESSION_RECORD_CONTRACT_VERSION,
+    teamId: toSafeRecordId(`team-${input.runId}-${input.taskId ?? 'branch'}`),
+    runId: input.runId,
+    taskId: input.taskId,
+    status: input.status,
+    chiefProfile: input.route.teamMode.chiefProfile,
+    memberProfiles: input.route.teamMode.memberProfiles,
+    hostLayout: null,
+    teamMode: input.route.teamMode,
+    waves: input.route.teamMode.allowedWaves,
+    messages: [{
+      sender: 'runtime',
+      receiver: 'team',
+      taskRef: input.taskId,
+      artifactRefs: input.artifacts,
+      blocker: input.route.teamMode.blockedReason,
+      evidenceSummary: input.evidenceSummary,
+      createdAt: now
+    }],
+    artifacts: input.artifacts,
+    evidenceSummary: input.evidenceSummary,
+    createdAt: now,
+    updatedAt: now
+  };
+}
+
+export function toSafeRecordId(value: string): string {
+  const sanitized = value.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+  return sanitized || 'record';
+}
+
+function normalizeAgentToken(value: string): string {
+  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+}
+
+function toAgentProfileId(agent: string): AgentProfileId | null {
+  const normalized = normalizeAgentToken(agent);
+  return normalized.length > 0 ? normalized : null;
+}

package/node_modules/@sdd-agent-platform/core/src/execution/background-executor.test.ts

@@ -0,0 +1,180 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, rm, writeFile } 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 { readRunState } from '../run-state/run-state.js';
+import { validResultArtifact, validTaskMarkdown, writeBranchDocs } from '../test-support/fixtures.js';
+import { inspectBackgroundExecutor, runBackgroundExecutor } from './background-executor.js';
+
+test('background executor claims one delegation and persists background run state', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-background-claim-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', validTaskMarkdown('B1', []));
+
+    const result = await runBackgroundExecutor(root, { taskId: 'B1' });
+    const state = await readRunState(root, result.runId);
+    const inspection = await inspectBackgroundExecutor(root, result.runId);
+
+    assert.equal(result.version, 'phase-3.11-background-executor-v1');
+    assert.equal(result.status, 'claimed');
+    assert.equal(result.delegationId, 'B-B1-implementer-001');
+    assert.equal(state.status, 'running');
+    assert.equal(state.phase, 'background');
+    assert.equal(state.currentTask, 'B1');
+    assert.equal(inspection.runningDelegations, 1);
+    assert.equal(inspection.terminalDelegations, 0);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('background executor ingests supplied artifact and reaches terminal state', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-background-ingest-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', validTaskMarkdown('B1', []));
+
+    const claimed = await runBackgroundExecutor(root, { taskId: 'B1' });
+    await writeArtifact(root, claimed.runId, 'implementer-B1.md', validResultArtifact('implementer', 'B1', 'PASS', 'artifacts/implementer-B1.md'));
+
+    const completed = await runBackgroundExecutor(root, {
+      runId: claimed.runId,
+      taskId: 'B1',
+      artifactPath: 'artifacts/implementer-B1.md'
+    });
+    const state = await readRunState(root, claimed.runId);
+    const inspection = await inspectBackgroundExecutor(root, claimed.runId);
+
+    assert.equal(completed.status, 'completed');
+    assert.equal(completed.ingestion?.delegationStatus, 'COMPLETED');
+    assert.equal(state.status, 'completed');
+    assert.equal(state.phase, 'background');
+    assert.equal(inspection.runningDelegations, 0);
+    assert.equal(inspection.terminalDelegations, 1);
+    assert.equal(inspection.artifactIngestions.length, 1);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('claude code subagent worker spawns host process and ingests stdout artifact', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-background-claude-host-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', validTaskMarkdown('B1', []));
+    const hostScript = path.join(root, 'fake-claude-host.mjs');
+    await writeFile(hostScript, [
+      "const prompt = process.argv[2] ?? '';",
+      "if (!prompt.includes('Queue item id:')) process.exit(2);",
+      "process.stdout.write('# implementer result\\n\\n```sdd-result\\ncontract: sdd-result-v1\\nversion: 1.3.0\\nagent: implementer\\ntask: B1\\nstatus: PASS\\nartifacts:\\n  - artifacts/implementer-B1.md\\n```\\n');"
+    ].join('\n'), 'utf8');
+
+    const completed = await runBackgroundExecutor(root, {
+      taskId: 'B1',
+      workerAdapterId: 'claude-code-subagent-worker',
+      timeoutSeconds: 10,
+      hostInvocation: { command: process.execPath, args: [hostScript, '{prompt}'] }
+    });
+    const state = await readRunState(root, completed.runId);
+    const inspection = await inspectBackgroundExecutor(root, completed.runId);
+
+    assert.equal(completed.status, 'completed');
+    assert.equal(completed.hostInvocation?.exitCode, 0);
+    assert.equal(completed.hostInvocation?.artifactPath, 'artifacts/implementer-B1.md');
+    assert.equal(completed.ingestion?.delegationStatus, 'COMPLETED');
+    assert.equal(state.delegations['B-B1-implementer-001']?.status, 'COMPLETED');
+    assert.equal(inspection.terminalDelegations, 1);
+    assert.equal(inspection.artifactIngestions.length, 1);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('background executor blocks invalid artifact evidence instead of completing silently', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-background-invalid-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', validTaskMarkdown('B1', []));
+
+    const claimed = await runBackgroundExecutor(root, { taskId: 'B1' });
+    await writeArtifact(root, claimed.runId, 'implementer-B1.md', '# Missing contract\n');
+
+    const blocked = await runBackgroundExecutor(root, {
+      runId: claimed.runId,
+      taskId: 'B1',
+      artifactPath: 'artifacts/implementer-B1.md'
+    });
+    const state = await readRunState(root, claimed.runId);
+
+    assert.equal(blocked.status, 'blocked');
+    assert.equal(blocked.issues.length > 0, true);
+    assert.equal(state.status, 'blocked');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('background executor requires approval for database manual gate and accepts approved artifact ingestion', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-background-approved-manual-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', validTaskMarkdown('B1', []).replace('risk: []', 'risk:\n  - database'));
+
+    const blocked = await runBackgroundExecutor(root, { taskId: 'B1' });
+    assert.equal(blocked.status, 'blocked');
+    assert.equal(blocked.issues.some((issue) => issue.field === 'isolation' && /manual isolation gate/.test(issue.message)), true);
+    assert.equal(blocked.issues.some((issue) => issue.field === 'governance.confirmation' && /database/.test(issue.message)), true);
+
+    const claimed = await runBackgroundExecutor(root, { taskId: 'B1', approved: true });
+    await writeArtifact(root, claimed.runId, 'implementer-B1.md', validResultArtifact('implementer', 'B1', 'PASS', 'artifacts/implementer-B1.md'));
+    const completed = await runBackgroundExecutor(root, {
+      runId: claimed.runId,
+      taskId: 'B1',
+      artifactPath: 'artifacts/implementer-B1.md',
+      approved: true
+    });
+
+    assert.equal(claimed.status, 'claimed');
+    assert.equal(completed.status, 'completed');
+    assert.equal(completed.ingestion?.delegationStatus, 'COMPLETED');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('background executor blocks manual handoff worker adapters', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-background-manual-worker-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', validTaskMarkdown('B1', []));
+
+    const result = await runBackgroundExecutor(root, { taskId: 'B1', workerAdapterId: 'manual-handoff-worker' });
+
+    assert.equal(result.status, 'blocked');
+    assert.equal(result.delegationId, null);
+    assert.equal(result.issues.some((issue) => issue.field === 'workerAdapterId' && /manual handoff/.test(issue.message)), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('doctor reports background executor contract visibility', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-background-doctor-'));
+  try {
+    await initProject(root);
+
+    const report = await doctor(root, { latestOnly: true });
+    const check = report.checks.find((item) => item.check === 'background_executor_contract');
+
+    assert.equal(check?.level, 'PASS');
+    assert.match(check?.message ?? '', /phase-3\.11-background-executor-v1/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});