sdd-agent-platform 0.4.1 → 0.5.0

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

@@ -1,319 +1,302 @@
-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, listRuntimeSyncBackDecisions } 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[] = [];
-    const syncBackJsonOnly: string[] = [];
-    const syncBackDivergence: 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);
-      }
-
-      const decisions = await listRuntimeSyncBackDecisions(projectRoot, state.runId);
-      const latestDecision = decisions[0] ?? null;
-      if (state.syncBack.status !== 'not_created' && !latestDecision) {
-        syncBackJsonOnly.push(state.runId);
-      }
-      if (latestDecision && latestDecision.status !== state.syncBack.status) {
-        syncBackDivergence.push(`${state.runId}:${state.syncBack.status}->${latestDecision.status}`);
-      }
-    }
-
-    const oldSyncBackProjection = await fileExists(path.join(projectRoot, '.claude', 'commands', 'sdd', 'syncback.md'));
-    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.' },
-      syncBackJsonOnly.length > 0 || syncBackDivergence.length > 0
-        ? { level: 'WARN', check: 'phase8_18_sync_back_compat', message: `state_json_only=${syncBackJsonOnly.join(',') || 'none'} divergence=${syncBackDivergence.join(',') || 'none'}`, action: 'Use sdd sync-back inspect only for explicit diagnostic/recovery/replay, then reconcile canonical sync_back_decisions before relying on write-back state.' }
-        : { level: 'PASS', check: 'phase8_18_sync_back_compat', message: 'Canonical sync_back_decisions are consistent with inspected run compatibility summaries.' },
-      oldSyncBackProjection
-        ? { level: 'WARN', check: 'phase8_18_ai_projection_compat', message: 'Found legacy /sdd:syncback projection at .claude/commands/sdd/syncback.md.', action: 'Run sdd update to remove obsolete managed syncback projection; use diagnostic sync-back only when explicitly requested.' }
-        : { level: 'PASS', check: 'phase8_18_ai_projection_compat', message: 'No legacy /sdd:syncback projection found.' },
-      { 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
-  }];
+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
+  }];
 }