sdd-agent-platform 0.3.0 → 0.4.1

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

@@ -0,0 +1,319 @@
+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
+  }];
+}

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/lookup.ts

@@ -0,0 +1,80 @@
+import { branchToSafePartition } from '../path-safety.js';
+import { listRuntimeArtifactPayloads } from '../storage/runtime-store.js';
+import type { RuntimeArtifactPayloadRecord, RuntimeArtifactPayloadStatus } from '../storage/runtime-store.js';
+
+export const EVIDENCE_LOOKUP_CONTRACT_VERSION = 'phase-8.12-evidence-lookup-v1';
+
+export interface EvidenceLookupFilters {
+  branch?: string | null;
+  runId?: string | null;
+  taskId?: string | null;
+  logicalRef?: string | null;
+  status?: RuntimeArtifactPayloadStatus | 'any' | null;
+  role?: string | null;
+  kind?: string | null;
+}
+
+export interface EvidenceLookupResult {
+  contract: typeof EVIDENCE_LOOKUP_CONTRACT_VERSION;
+  generatedAt: string;
+  retrievalMemoryOnly: true;
+  gateTruthAuthority: false;
+  reason: string;
+  filters: EvidenceLookupFilters;
+  payloads: RuntimeArtifactPayloadRecord[];
+  resolvedPayloads: RuntimeArtifactPayloadRecord[];
+  counts: Record<RuntimeArtifactPayloadStatus, number>;
+}
+
+export async function lookupEvidence(projectRoot: string, filters: EvidenceLookupFilters = {}): Promise<EvidenceLookupResult> {
+  const payloads = await listRuntimeArtifactPayloads(projectRoot, {
+    runId: filters.runId ?? null,
+    branchSlug: filters.branch ? branchToSafePartition(filters.branch) : null,
+    taskId: filters.taskId ?? null,
+    logicalRef: filters.logicalRef ?? null,
+    status: filters.status && filters.status !== 'any' ? filters.status : null
+  });
+  const filtered = payloads.filter((payload) => matchesMetadata(payload, filters));
+  const resolvedPayloads = resolveActivePayloads(filtered);
+  return {
+    contract: EVIDENCE_LOOKUP_CONTRACT_VERSION,
+    generatedAt: new Date().toISOString(),
+    retrievalMemoryOnly: true,
+    gateTruthAuthority: false,
+    reason: 'Evidence Lookup is retrieval memory over SQLite metadata and payload refs; PASS, verify, and sync-back authority must use runtime evidence gates.',
+    filters,
+    payloads: filtered,
+    resolvedPayloads,
+    counts: {
+      active: filtered.filter((payload) => payload.status === 'active').length,
+      candidate: filtered.filter((payload) => payload.status === 'candidate').length,
+      rejected: filtered.filter((payload) => payload.status === 'rejected').length,
+      superseded: filtered.filter((payload) => payload.status === 'superseded').length
+    }
+  };
+}
+
+function matchesMetadata(payload: RuntimeArtifactPayloadRecord, filters: EvidenceLookupFilters): boolean {
+  if (filters.role && payload.artifactRole !== filters.role) {
+    return false;
+  }
+  if (filters.kind && payload.artifactRole !== filters.kind) {
+    return false;
+  }
+  return true;
+}
+
+function resolveActivePayloads(payloads: RuntimeArtifactPayloadRecord[]): RuntimeArtifactPayloadRecord[] {
+  const byLogicalRef = new Map<string, RuntimeArtifactPayloadRecord>();
+  for (const payload of payloads) {
+    if (payload.status !== 'active') {
+      continue;
+    }
+    const key = `${payload.branchSlug}\\0${payload.taskId ?? ''}\\0${payload.logicalRef}`;
+    const current = byLogicalRef.get(key);
+    if (!current || payload.sequence > current.sequence || (payload.sequence === current.sequence && payload.createdAt > current.createdAt)) {
+      byLogicalRef.set(key, payload);
+    }
+  }
+  return Array.from(byLogicalRef.values()).sort((left, right) => right.createdAt.localeCompare(left.createdAt) || right.sequence - left.sequence);
+}

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

@@ -0,0 +1,49 @@
+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 type CapabilityEvidenceClass = 'accepted' | 'candidate' | 'quarantined' | 'diagnostic' | 'blocked';
+
+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 CapabilityEvidenceClassification {
+  class: CapabilityEvidenceClass;
+  source: 'professional_capability' | 'external_source' | 'runtime_diagnostic';
+  domainOrSourceId: string;
+  evidenceRefs: RuntimeRef[];
+  acceptanceRefs: string[];
+  provenanceRefs: RuntimeRef[];
+  reason: 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[];
+  capabilityEvidence: CapabilityEvidenceClassification[];
+  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';