sdd-agent-platform 0.4.2 → 0.5.0

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

@@ -1,454 +1,302 @@
-import { readFile } from 'node:fs/promises';
-
-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, listRuntimeRepairs, listRuntimeTestRuns, listRuntimeTestSteps, listRuntimeValidationCacheEntries, listRuntimeValidationCacheUses, recordRuntimeRepair, type RuntimeRepairRecord } from '../storage/runtime-store.js';
-
-import { branchToSafePartition } from '../path-safety.js';
-import { readAllRunStates } from '../run-state/run-state.js';
-import { readRunEvents } from '../run-state/events.js';
-import { buildRunDurationBreakdown } from '../run-state/timing.js';
-import { parseSddBranch } from '../sdd-docs/task-parser.js';
-import { buildMixedVersionRecoveryPlan } from '../workflow-state/migration-recovery.js';
-import { buildOpenRepairRecord } from '../workflow-state/repair-contract.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));
-  checks.push(...inspectCapabilityHealthRuntime(statusSnapshot));
-  checks.push(...inspectLatestEligibleRunSelector(statusSnapshot));
-  checks.push(...inspectDurableGapRuntime(statusSnapshot));
-  checks.push(...inspectStageTeamRuntime(statusSnapshot));
-  checks.push(...inspectWorkflowGateRuntime(statusSnapshot));
-  checks.push(...inspectSpecCollaborationRuntime(statusSnapshot));
-  checks.push(...await inspectRuntimePerformanceObservability(projectRoot, options));
-  checks.push(...await inspectValidationCacheVisibility(projectRoot, options));
-  checks.push(...await inspectMixedVersionRecovery(projectRoot, statusSnapshot, options));
-  
-
-  checks.push(...await inspectRepairRecords(projectRoot, options));
-  await recordDoctorRepairs(projectRoot, checks, options.branch ?? null);
-
-  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.'
-  }];
-}
-
-const STALE_OPEN_RUN_MS = 30 * 60 * 1000;
-const WAITING_DOMINATED_MIN_MS = 10_000;
-const SLOW_VALIDATION_STEP_MS = 30_000;
-
-async function inspectRuntimePerformanceObservability(projectRoot: string, options: { allRuns?: boolean; branch?: string | null } = {}): Promise<DoctorCheck[]> {
-  try {
-    const branchPartition = options.branch ? branchToSafePartition(options.branch) : null;
-    const states = (await readAllRunStates(projectRoot))
-      .filter((state) => options.allRuns || state.status !== 'archived')
-      .filter((state) => !branchPartition || state.partition === branchPartition || state.gitBranch === options.branch || (state.gitBranch ? branchToSafePartition(state.gitBranch) === branchPartition : false));
-    const staleOpenRuns: string[] = [];
-    const missingTestSteps: string[] = [];
-    const waitingDominatedRuns: string[] = [];
-    const slowValidationSteps: string[] = [];
-    const hostNoOutputRuns: string[] = [];
-
-    for (const state of states) {
-      const ageMs = Date.now() - Date.parse(state.updatedAt);
-      if (!isTerminalRunStatus(state.status) && Number.isFinite(ageMs) && ageMs >= STALE_OPEN_RUN_MS) {
-        staleOpenRuns.push(state.runId);
-      }
-
-      const [events, testRuns, testSteps] = await Promise.all([
-        readRunEvents(projectRoot, state.runId),
-        listRuntimeTestRuns(projectRoot, state.runId),
-        listRuntimeTestSteps(projectRoot, { runId: state.runId })
-      ]);
-      if (testRuns.length > 0 && testSteps.length === 0) {
-        missingTestSteps.push(state.runId);
-      }
-
-      const breakdown = buildRunDurationBreakdown(state, { events, testRuns, testSteps });
-      if (breakdown.waitingDurationMs >= WAITING_DOMINATED_MIN_MS && breakdown.waitingDurationMs > breakdown.activeRuntimeDurationMs) {
-        waitingDominatedRuns.push(`${state.runId}:${breakdown.waitingDurationMs}ms`);
-      }
-      if (breakdown.hostWaitingDurationMs >= WAITING_DOMINATED_MIN_MS && testSteps.length === 0) {
-        hostNoOutputRuns.push(`${state.runId}:${breakdown.hostWaitingDurationMs}ms`);
-      }
-      for (const step of testSteps) {
-        if (step.durationMs >= SLOW_VALIDATION_STEP_MS) {
-          slowValidationSteps.push(`${step.runId}:${step.stepId}:${step.durationMs}ms`);
-        }
-      }
-    }
-
-    const warnings = staleOpenRuns.length + missingTestSteps.length + waitingDominatedRuns.length + slowValidationSteps.length + hostNoOutputRuns.length;
-    return [{
-      level: warnings > 0 ? 'WARN' : 'PASS',
-      check: 'runtime_performance_observability',
-      message: `runs=${states.length} stale_open=${staleOpenRuns.join(',') || 'none'} missing_test_steps=${missingTestSteps.join(',') || 'none'} waiting_dominated=${waitingDominatedRuns.join(',') || 'none'} slow_validation=${slowValidationSteps.join(',') || 'none'} host_no_output=${hostNoOutputRuns.join(',') || 'none'}`,
-      action: warnings > 0 ? 'Inspect run duration breakdowns with sdd run inspect; persist test_steps for validation commands and investigate long waiting or host-no-output gaps.' : undefined
-    }];
-  } catch (error) {
-    return unavailableRuntimeCheck('runtime_performance_observability', 'runtime performance observability', error);
-  }
-}
-
-async function inspectValidationCacheVisibility(projectRoot: string, options: { branch?: string | null } = {}): Promise<DoctorCheck[]> {
-  try {
-    const branchPartition = options.branch ? branchToSafePartition(options.branch) : null;
-    const entries = await listRuntimeValidationCacheEntries(projectRoot, { branchSlug: branchPartition, status: 'valid' });
-    const uses = await listRuntimeValidationCacheUses(projectRoot, { branchSlug: branchPartition });
-    const staleEntries = entries.filter((entry) => !entry.payload || typeof entry.payload !== 'object' || !('cachePlan' in entry.payload));
-    return [{
-      level: staleEntries.length > 0 ? 'WARN' : 'PASS',
-      check: 'validation_cache_visibility',
-      message: `entries=${entries.length} uses=${uses.length} stale_entries=${staleEntries.map((entry) => entry.cacheKey).join(',') || 'none'} hit_sources=${[...new Set(uses.map((use) => use.sourceTestRunId))].join(',') || 'none'}`,
-      action: staleEntries.length > 0 ? 'Replay stale validation cache entries; cache hits must remain tied to current cachePlan payload and accepted evidence mapping.' : undefined
-    }];
-  } catch (error) {
-    return unavailableRuntimeCheck('validation_cache_visibility', 'validation cache visibility', error);
-  }
-}
-
-async function inspectRepairRecords(projectRoot: string, options: { branch?: string | null } = {}): Promise<DoctorCheck[]> {
-  try {
-    const branchPartition = options.branch ? branchToSafePartition(options.branch) : null;
-    const repairs = await listRuntimeRepairs(projectRoot, { branchSlug: branchPartition, status: 'open' });
-    return [{
-      level: repairs.length > 0 ? 'WARN' : 'PASS',
-      check: 'repair_records',
-      message: `open=${repairs.length} types=${[...new Set(repairs.map((repair) => repair.repairType))].join(',') || 'none'} next=${repairs.flatMap((repair) => repair.recommendedCommands).slice(0, 3).join(' | ') || 'none'}`,
-      action: repairs.length > 0 ? 'Resolve open repair records with new accepted evidence or a fresh gate PASS; diagnostic text alone does not close repairs.' : undefined
-    }];
-  } catch (error) {
-    return unavailableRuntimeCheck('repair_records', 'repair records', error);
-  }
-}
-
-async function recordDoctorRepairs(projectRoot: string, checks: DoctorCheck[], branch: string | null): Promise<void> {
-  const branchSlug = branch ? branchToSafePartition(branch) : 'master';
-  const repairable = checks.filter((check) => doctorCheckCreatesRepair(check));
-  const repairableCheckNames = new Set(repairable.map((check) => check.check));
-  try {
-    const openRepairs = await listRuntimeRepairs(projectRoot, { branchSlug, status: 'open' });
-    for (const repair of openRepairs) {
-      const checkName = doctorRepairCheckName(repair);
-      if (checkName && (!repairableCheckNames.has(checkName) || repair.recommendedCommands.some((command) => !doctorRepairCommandLooksExecutable(command)))) {
-        await recordRuntimeRepair(projectRoot, {
-          ...repair,
-          status: 'superseded',
-          resolvedAt: new Date().toISOString(),
-          payload: { ...doctorRepairPayload(repair.payload), supersededBy: 'doctor_fail_check_cleared' }
-        });
-      }
-    }
-  } catch {
-    return;
-  }
-  for (const check of repairable) {
-    try {
-      await recordRuntimeRepair(projectRoot, buildOpenRepairRecord({
-        branchSlug,
-        message: `${check.check}: ${check.message}`,
-        recommendedCommands: doctorRepairCommands(branchSlug, check),
-        requiredEvidence: ['new accepted evidence or fresh gate PASS']
-      }));
-    } catch {
-      return;
-    }
-  }
-}
-
-function doctorCheckCreatesRepair(check: DoctorCheck): boolean {
-  return check.check !== 'repair_records' && check.check !== 'capability_health' && check.level === 'FAIL';
-}
-
-function doctorRepairCheckName(repair: RuntimeRepairRecord): string | null {
-  const blocker = repair.blockers[0] ?? '';
-  const separator = blocker.indexOf(':');
-  return separator > 0 ? blocker.slice(0, separator) : null;
-}
-
-function doctorRepairPayload(payload: unknown): Record<string, unknown> {
-  return payload && typeof payload === 'object' && !Array.isArray(payload) ? payload as Record<string, unknown> : { previousPayload: payload };
-}
-
-function doctorRepairCommands(branchSlug: string, check: DoctorCheck): string[] {
-  if (check.check === 'ai_entry_projection') {
-    return ['sdd update'];
-  }
-  if (check.check === 'capability_health') {
-    return [`sdd status --branch ${branchSlug} --compact-json`];
-  }
-  if (check.check === 'document_chain' || check.check === 'verify_contract' || check.message.includes('verify.md')) {
-    return [`sdd verifies write --branch ${branchSlug} --force`];
-  }
-  return [`sdd doctor --branch ${branchSlug} --latest-only`];
-}
-
-function doctorRepairCommandLooksExecutable(command: string): boolean {
-  const normalized = command.trim().toLowerCase();
-  return normalized.startsWith('sdd ') || normalized.startsWith('npm ') || normalized.startsWith('node ') || normalized.startsWith('npx ');
-}
-
-function isTerminalRunStatus(status: string): boolean {
-  return status === 'completed' || status === 'failed' || status === 'blocked' || status === 'archived';
-}
-
-
-async function inspectMixedVersionRecovery(projectRoot: string, snapshot: DoctorProjectStatusSnapshot, options: { branch?: string | null } = {}): Promise<DoctorCheck[]> {
-  if (!snapshot.status) {
-    return unavailableRuntimeCheck('mixed_version_recovery', 'mixed-version recovery plan', snapshot.error);
-  }
-  try {
-    const model = await parseSddBranch(projectRoot, snapshot.status.branch);
-    const verifyText = model.documents.verifyExists ? await readFile(model.verifyPath, 'utf8') : null;
-    const plan = buildMixedVersionRecoveryPlan({ model, latestEligibleRunsByTask: snapshot.status.latestEligibleRunsByTask, verifyText });
-    const blocking = plan.detectedIssues.filter((issue) => issue.severity === 'blocking').length;
-    const warnings = plan.detectedIssues.filter((issue) => issue.severity === 'warn').length;
-    const legacyArtifacts = plan.detectedIssues.filter((issue) => issue.kind === 'legacy_artifact_ref').map((issue) => `${issue.taskId}:${issue.current}->${issue.expected}`);
-    const strictStale = plan.staleRunImpact.map((impact) => `${impact.taskId}:${impact.runId}`);
-    return [{
-      level: blocking > 0 ? 'FAIL' : warnings > 0 || plan.staleRunImpact.length > 0 ? 'WARN' : 'PASS',
-      check: 'mixed_version_recovery',
-      message: `issues=${plan.detectedIssues.length} safe_fixes=${plan.safeMechanicalUpdates.length} behavior_changes=${plan.behaviorChangingUpdates.length} legacy_artifacts=${legacyArtifacts.join(',') || 'none'} stale_runs=${strictStale.join(',') || 'none'} replay=${plan.evidenceReplayNeeded.join(',') || 'none'} next=${plan.nextCommands.join(' | ')}`,
-      action: plan.detectedIssues.length > 0 ? 'Apply only safe mechanical fixes in dry-run/preview first, then replay validation evidence; do not promote legacy stale runs as accepted truth.' : undefined
-    }];
-  } catch (error) {
-    return unavailableRuntimeCheck('mixed_version_recovery', 'mixed-version recovery plan', error);
-  }
-}
-
-
-
-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 : `sdd status --branch ${snapshot.status.branch} --compact-json`
-  }];
-}
-
-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 : `sdd status --branch ${snapshot.status.branch} --compact-json`
-  }];
-}
-
-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(' ')
-  }];
-}
-
-function inspectCapabilityHealthRuntime(snapshot: DoctorProjectStatusSnapshot): DoctorCheck[] {
-  if (!snapshot.status) {
-    return unavailableRuntimeCheck('capability_health', 'capability health', snapshot.error);
-  }
-  const health = snapshot.status.capabilityHealth;
-  return [{
-    level: health.status === 'blocked' ? 'FAIL' : health.status === 'warn' ? 'WARN' : 'PASS',
-    check: 'capability_health',
-    message: `status=${health.status} baseline=${health.baselineDomains.length}/${health.requiredProfessionalDomains.length} packs=${health.materialPacks} active=${health.activeDomains.join(',') || 'none'} sources_quarantined=${health.sources.quarantined} sources_denied=${health.sources.denied} evidence_candidate=${health.evidence.candidate} adoptions=${health.adoptions.adopted}/${health.adoptions.rejected}/${health.adoptions.unresolved} adoption_closures=${health.adoptions.releaseCriticalClosures.join(',') || 'none'} release_critical_gaps=${health.releaseCriticalGaps.join(',') || 'none'}`, 
-    action: health.status === 'pass' ? undefined : `sdd status --branch ${snapshot.status.branch} --compact-json`
-  }];
-}
-
-function inspectWorkflowGateRuntime(snapshot: DoctorProjectStatusSnapshot): DoctorCheck[] {
-  if (!snapshot.status) {
-    return unavailableRuntimeCheck('workflow_gate_runtime', 'workflow gate runtime', snapshot.error);
-  }
-  const health = snapshot.status.workflowGateHealth;
-  const latest = health.latestDecision;
-  const level = health.blocked > 0 || health.humanRequired > 0 || health.warnings > 0 ? 'WARN' : 'PASS';
-  return [{
-    level,
-    check: 'workflow_gate_runtime',
-    message: `decisions=${health.decisions} blocked=${health.blocked} warn=${health.warnings} human_required=${health.humanRequired} latest=${latest ? `${latest.decisionKind}:${latest.status}:${latest.decisionId}` : 'none'}`,
-    action: level === 'PASS' ? undefined : `Workflow gate decisions are audit evidence; rerun the relevant gate command for current enforcement on ${snapshot.status.branch}.`
-  }];
-}
-
-function inspectStageTeamRuntime(snapshot: DoctorProjectStatusSnapshot): DoctorCheck[] {
-  if (!snapshot.status) {
-    return unavailableRuntimeCheck('stage_team_runtime', 'stage team runtime', snapshot.error);
-  }
-  const health = snapshot.status.stageTeamHealth;
-  const level = health.highConcernAdvisors > 0 || !health.directProfileRequiresNoTeam ? 'WARN' : 'PASS';
-  return [{
-    level,
-    check: 'stage_team_runtime',
-    message: `sessions=${health.sessions} role_results=${health.roleResults} advisors=${health.advisorAssessments} high_concern=${health.highConcernAdvisors} fan_in=${health.fanInEvidenceSets} profiles=${health.lifecycleProfiles.join(',') || 'none'} direct_required_team=${!health.directProfileRequiresNoTeam}`,
-    action: level === 'PASS' ? undefined : `Inspect task evidence for ${snapshot.status.branch}; agent-team and advisor outputs are gate inputs, not final lifecycle authority.`
-  }];
-}
-
-function inspectSpecCollaborationRuntime(snapshot: DoctorProjectStatusSnapshot): DoctorCheck[] {
-  if (!snapshot.status) {
-    return unavailableRuntimeCheck('spec_collaboration_runtime', 'spec collaboration runtime', snapshot.error);
-  }
-  const health = snapshot.status.specCollaborationHealth;
-  const level = health.status === 'blocked' || health.status === 'rejected' || health.status === 'incompatible' ? 'FAIL' : health.status === 'needs_clarification' ? 'WARN' : 'PASS';
-  return [{
-    level,
-    check: 'spec_collaboration_runtime',
-    message: `status=${health.status} projections=${health.projectionCount} clarification=${health.latestClarificationGateId ?? 'none'} handoff=${health.latestHandoffId ?? 'none'} rejection=${health.latestRejectionReason ?? 'none'}`,
-    action: level === 'PASS' ? undefined : health.reasons.join(' ')
-  }];
-}
-
-
-function inspectDurableGapRuntime(snapshot: DoctorProjectStatusSnapshot): DoctorCheck[] {
-  if (!snapshot.status) {
-    return unavailableRuntimeCheck('durable_gap_runtime', 'durable gap runtime', snapshot.error);
-  }
-  const gaps = snapshot.status.durableGaps;
-  const blocking = gaps.filter((gap) => gap.severity === 'blocking').length;
-  const warnings = gaps.filter((gap) => gap.severity === 'warning').length;
-  const tasks = [...new Set(gaps.map((gap) => gap.taskId).filter((taskId): taskId is string => typeof taskId === 'string'))].sort();
-  return [{
-    level: blocking > 0 ? 'FAIL' : warnings > 0 ? 'WARN' : 'PASS',
-    check: 'durable_gap_runtime',
-    message: `open=${gaps.length} blocking=${blocking} warning=${warnings} tasks=${tasks.join(',') || 'none'}`,
-    action: gaps.length > 0 ? `Inspect task evidence or status for ${snapshot.status.branch}; terminal durable gap closure is runtime/gate-policy controlled.` : undefined
-  }];
-}
-
-function inspectLatestEligibleRunSelector(snapshot: DoctorProjectStatusSnapshot): DoctorCheck[] {
-  if (!snapshot.status) {
-    return unavailableRuntimeCheck('latest_eligible_run_selector', 'latest eligible run selector', snapshot.error);
-  }
-  const selections = snapshot.status.latestEligibleRunsByTask;
-  const selected = selections.filter((selection) => selection.selected).length;
-  const candidates = selections.reduce((sum, selection) => sum + selection.candidates.length, 0);
-  const rejected = selections.reduce((sum, selection) => sum + selection.rejected.length, 0);
-  const blockedTasks = selections.filter((selection) => !selection.selected && selection.candidates.length > 0).map((selection) => selection.taskId);
-  return [{
-    level: blockedTasks.length > 0 ? 'WARN' : 'PASS',
-    check: 'latest_eligible_run_selector',
-    message: `tasks=${selections.length} selected=${selected} candidates=${candidates} rejected=${rejected} blocked_tasks=${blockedTasks.join(',') || 'none'}`,
-    action: blockedTasks.length > 0 ? `Inspect rejected candidates with sdd status --branch ${snapshot.status.branch}; default apply only uses compatible eligible runs.` : undefined
-  }];
+import { readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+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 { getLegacyAgentExecutionsDir, getLegacyRunDir, getLegacyTeamSessionsDir, getLegacyWorkerRuntimesDir } from '../runtime-paths.js';
+import { branchToSafePartition } from '../path-safety.js';
+import { readAllRunStates } from '../run-state/run-state.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));
+  checks.push(...inspectCapabilityHealthRuntime(statusSnapshot));
+  checks.push(...inspectLatestEligibleRunSelector(statusSnapshot));
+  checks.push(...inspectDurableGapRuntime(statusSnapshot));
+  checks.push(...inspectStageTeamRuntime(statusSnapshot));
+  checks.push(...inspectWorkflowGateRuntime(statusSnapshot));
+  checks.push(...await inspectPhase818Compatibility(projectRoot, options));
+
+  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.'
+  }];
+}
+
+async function inspectPhase818Compatibility(projectRoot: string, options: { allRuns?: boolean; branch?: string | null } = {}): Promise<DoctorCheck[]> {
+  try {
+    const branchPartition = options.branch ? branchToSafePartition(options.branch) : null;
+    const states = (await readAllRunStates(projectRoot))
+      .filter((state) => options.allRuns || state.status !== 'archived')
+      .filter((state) => !branchPartition || state.partition === branchPartition || state.gitBranch === options.branch || (state.gitBranch ? branchToSafePartition(state.gitBranch) === branchPartition : false));
+    const legacyRunFiles: string[] = [];
+    const legacySidecars: string[] = [];
+
+    for (const state of states) {
+      const legacyRunDir = getLegacyRunDir(projectRoot, state.runId);
+      const runLocalFiles = ['state.json', 'events.jsonl', 'invocations.jsonl'];
+      for (const fileName of runLocalFiles) {
+        if (await fileExists(path.join(legacyRunDir, fileName))) {
+          legacyRunFiles.push(`${state.runId}:${fileName}`);
+        }
+      }
+
+      const sidecarDirs = [
+        getLegacyAgentExecutionsDir(projectRoot, state.runId),
+        getLegacyTeamSessionsDir(projectRoot, state.runId),
+        getLegacyWorkerRuntimesDir(projectRoot, state.runId)
+      ];
+      if ((await Promise.all(sidecarDirs.map(directoryHasEntries))).some(Boolean)) {
+        legacySidecars.push(state.runId);
+      }
+
+    }
+
+    return [
+      legacyRunFiles.length > 0
+        ? { level: 'WARN', check: 'phase8_18_legacy_run_files', message: `legacy_run_files=${legacyRunFiles.join(',')}`, action: 'Runtime authority is runtime.sqlite; keep legacy run-local state/events/invocation files as import fallback only.' }
+        : { level: 'PASS', check: 'phase8_18_legacy_run_files', message: 'No legacy run-local state, event, or invocation files found in inspected runs.' },
+      legacySidecars.length > 0
+        ? { level: 'WARN', check: 'phase8_18_legacy_sidecars', message: `legacy_sidecar_runs=${legacySidecars.join(',')}`, action: 'Runtime authority is runtime.sqlite; keep old sidecars as import fallback and avoid writing new per-run structured sidecars.' }
+        : { level: 'PASS', check: 'phase8_18_legacy_sidecars', message: 'No legacy per-run agent/team/worker sidecar directories found in inspected runs.' },
+      { level: 'PASS', check: 'phase9_readiness', message: 'code_graph_signals=optional_advisory_only authority=phase8_runtime_policy', action: 'Phase 9 graph providers may feed risk/context/test-impact/status/doctor signals but cannot replace Phase 8 gate truth.' }
+    ];
+  } catch (error) {
+    return unavailableRuntimeCheck('phase8_18_compatibility', 'Phase 8.18 compatibility diagnostics', error);
+  }
+}
+
+async function directoryHasEntries(directory: string): Promise<boolean> {
+  try {
+    return (await readdir(directory)).length > 0;
+  } catch {
+    return false;
+  }
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await stat(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+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(' ')
+  }];
+}
+
+function inspectCapabilityHealthRuntime(snapshot: DoctorProjectStatusSnapshot): DoctorCheck[] {
+  if (!snapshot.status) {
+    return unavailableRuntimeCheck('capability_health', 'capability health', snapshot.error);
+  }
+  const health = snapshot.status.capabilityHealth;
+  return [{
+    level: health.status === 'blocked' ? 'FAIL' : health.status === 'warn' ? 'WARN' : 'PASS',
+    check: 'capability_health',
+    message: `status=${health.status} baseline=${health.baselineDomains.length}/${health.requiredProfessionalDomains.length} packs=${health.materialPacks} active=${health.activeDomains.join(',') || 'none'} sources_quarantined=${health.sources.quarantined} sources_denied=${health.sources.denied} evidence_candidate=${health.evidence.candidate} release_critical_gaps=${health.releaseCriticalGaps.join(',') || 'none'}`,
+    action: health.status === 'pass' ? undefined : health.reasons.join(' ')
+  }];
+}
+
+function inspectWorkflowGateRuntime(snapshot: DoctorProjectStatusSnapshot): DoctorCheck[] {
+  if (!snapshot.status) {
+    return unavailableRuntimeCheck('workflow_gate_runtime', 'workflow gate runtime', snapshot.error);
+  }
+  const health = snapshot.status.workflowGateHealth;
+  const latest = health.latestDecision;
+  const level = health.blocked > 0 || health.humanRequired > 0 || health.warnings > 0 ? 'WARN' : 'PASS';
+  return [{
+    level,
+    check: 'workflow_gate_runtime',
+    message: `decisions=${health.decisions} blocked=${health.blocked} warn=${health.warnings} human_required=${health.humanRequired} latest=${latest ? `${latest.decisionKind}:${latest.status}:${latest.decisionId}` : 'none'}`,
+    action: level === 'PASS' ? undefined : `Workflow gate decisions are audit evidence; rerun the relevant gate command for current enforcement on ${snapshot.status.branch}.`
+  }];
+}
+
+function inspectStageTeamRuntime(snapshot: DoctorProjectStatusSnapshot): DoctorCheck[] {
+  if (!snapshot.status) {
+    return unavailableRuntimeCheck('stage_team_runtime', 'stage team runtime', snapshot.error);
+  }
+  const health = snapshot.status.stageTeamHealth;
+  const level = health.highConcernAdvisors > 0 || !health.directProfileRequiresNoTeam ? 'WARN' : 'PASS';
+  return [{
+    level,
+    check: 'stage_team_runtime',
+    message: `sessions=${health.sessions} role_results=${health.roleResults} advisors=${health.advisorAssessments} high_concern=${health.highConcernAdvisors} fan_in=${health.fanInEvidenceSets} profiles=${health.lifecycleProfiles.join(',') || 'none'} direct_required_team=${!health.directProfileRequiresNoTeam}`,
+    action: level === 'PASS' ? undefined : `Inspect task evidence for ${snapshot.status.branch}; agent-team and advisor outputs are gate inputs, not final lifecycle authority.`
+  }];
+}
+
+function inspectDurableGapRuntime(snapshot: DoctorProjectStatusSnapshot): DoctorCheck[] {
+  if (!snapshot.status) {
+    return unavailableRuntimeCheck('durable_gap_runtime', 'durable gap runtime', snapshot.error);
+  }
+  const gaps = snapshot.status.durableGaps;
+  const blocking = gaps.filter((gap) => gap.severity === 'blocking').length;
+  const warnings = gaps.filter((gap) => gap.severity === 'warning').length;
+  const tasks = [...new Set(gaps.map((gap) => gap.taskId).filter((taskId): taskId is string => typeof taskId === 'string'))].sort();
+  return [{
+    level: blocking > 0 ? 'FAIL' : warnings > 0 ? 'WARN' : 'PASS',
+    check: 'durable_gap_runtime',
+    message: `open=${gaps.length} blocking=${blocking} warning=${warnings} tasks=${tasks.join(',') || 'none'}`,
+    action: gaps.length > 0 ? `Inspect task evidence or status for ${snapshot.status.branch}; terminal durable gap closure is runtime/gate-policy controlled.` : undefined
+  }];
+}
+
+function inspectLatestEligibleRunSelector(snapshot: DoctorProjectStatusSnapshot): DoctorCheck[] {
+  if (!snapshot.status) {
+    return unavailableRuntimeCheck('latest_eligible_run_selector', 'latest eligible run selector', snapshot.error);
+  }
+  const selections = snapshot.status.latestEligibleRunsByTask;
+  const selected = selections.filter((selection) => selection.selected).length;
+  const candidates = selections.reduce((sum, selection) => sum + selection.candidates.length, 0);
+  const rejected = selections.reduce((sum, selection) => sum + selection.rejected.length, 0);
+  const blockedTasks = selections.filter((selection) => !selection.selected && selection.candidates.length > 0).map((selection) => selection.taskId);
+  return [{
+    level: blockedTasks.length > 0 ? 'WARN' : 'PASS',
+    check: 'latest_eligible_run_selector',
+    message: `tasks=${selections.length} selected=${selected} candidates=${candidates} rejected=${rejected} blocked_tasks=${blockedTasks.join(',') || 'none'}`,
+    action: blockedTasks.length > 0 ? `Inspect rejected candidates with sdd status --branch ${snapshot.status.branch}; default apply only uses compatible eligible runs.` : undefined
+  }];
 }