sdd-agent-platform 0.4.0 → 0.4.2

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

@@ -1,3 +1,5 @@
+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';
@@ -5,7 +7,15 @@ import { inspectGitRepository, inspectProjectConfig, inspectRunsDirectoryAccess,
 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 { 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';
@@ -58,6 +68,19 @@ export async function doctor(projectRoot: string, options: { allRuns?: boolean;
   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),
@@ -90,6 +113,191 @@ function unavailableRuntimeCheck(check: string, label: string, error: unknown):
   }];
 }
 
+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);
@@ -112,7 +320,7 @@ function inspectLifecycleRiskRuntime(snapshot: DoctorProjectStatusSnapshot): Doc
     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.`
+    action: risk.status === 'fresh' ? undefined : `sdd status --branch ${snapshot.status.branch} --compact-json`
   }];
 }
 
@@ -125,7 +333,7 @@ function inspectWorkflowHandoffRuntime(snapshot: DoctorProjectStatusSnapshot): D
     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.`
+    action: handoff.status === 'fresh' || handoff.status === 'missing' ? undefined : `sdd status --branch ${snapshot.status.branch} --compact-json`
   }];
 }
 
@@ -153,4 +361,94 @@ function inspectSubagentDispatchRuntime(snapshot: DoctorProjectStatusSnapshot):
     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
+  }];
 }

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

@@ -0,0 +1,88 @@
+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 truth-alignment authority must use runtime evidence gates.',
+    filters,
+    payloads: filtered,
+    resolvedPayloads,
+    counts: countByStatus(filtered)
+  };
+}
+
+function countByStatus(payloads: RuntimeArtifactPayloadRecord[]): Record<RuntimeArtifactPayloadStatus, number> {
+  return {
+    active: payloads.filter((payload) => payload.status === 'active').length,
+    candidate: payloads.filter((payload) => payload.status === 'candidate').length,
+    partial: payloads.filter((payload) => payload.status === 'partial').length,
+    active_attempt: payloads.filter((payload) => payload.status === 'active_attempt').length,
+    rejected: payloads.filter((payload) => payload.status === 'rejected').length,
+    superseded: payloads.filter((payload) => payload.status === 'superseded').length,
+    quarantined: payloads.filter((payload) => payload.status === 'quarantined').length,
+    stale: payloads.filter((payload) => payload.status === 'stale').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

@@ -3,6 +3,7 @@ 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;
@@ -21,6 +22,16 @@ export interface AcceptanceEvidenceCoverage {
   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;
@@ -30,7 +41,7 @@ export interface UnifiedTestEvidenceRun {
   policyJudgment: TestEvidenceStatus;
   commands: TestCommandEvidence[];
   acceptanceCoverage: AcceptanceEvidenceCoverage[];
-  syncBackReady: boolean;
+  capabilityEvidence: CapabilityEvidenceClassification[];
   gaps: string[];
   next: string;
   generatedAt: string;

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

@@ -1,17 +1,16 @@
 import { createHash } from 'node:crypto';
-import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import {
   AGENT_EXECUTION_RECORD_CONTRACT_VERSION,
   TEAM_SESSION_RECORD_CONTRACT_VERSION
 } from '../contracts.js';
 import {
-  getAgentExecutionRecordPath,
-  getAgentExecutionsDir,
-  getTeamSessionRecordPath,
-  getTeamSessionsDir
+  getLegacyAgentExecutionsDir,
+  getLegacyTeamSessionsDir
 } from '../runtime-paths.js';
 import { exists } from '../storage/json-io.js';
+import { listRuntimeAgentExecutions, listRuntimeTeamSessions, recordRuntimeAgentExecution, recordRuntimeTeamSession } from '../storage/runtime-store.js';
 import { BUILT_IN_SKILL_CAPABILITIES } from '../registries/skill-capabilities.js';
 import type { ArtifactResultIngestionRecord } from '../artifacts/ingestion.js';
 import type {
@@ -24,19 +23,21 @@ import type {
 } from '../router/agent-runtime.js';
 
 export async function writeAgentExecutionRecord(projectRoot: string, record: AgentExecutionRecord): Promise<AgentExecutionRecord> {
-  await mkdir(getAgentExecutionsDir(projectRoot, record.runId), { recursive: true });
-  await writeFile(getAgentExecutionRecordPath(projectRoot, record.runId, record.executionId), `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+  await recordRuntimeAgentExecution(projectRoot, record);
   return record;
 }
 
 export async function writeTeamSessionRecord(projectRoot: string, record: TeamSessionRecord): Promise<TeamSessionRecord> {
-  await mkdir(getTeamSessionsDir(projectRoot, record.runId), { recursive: true });
-  await writeFile(getTeamSessionRecordPath(projectRoot, record.runId, record.teamId), `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+  await recordRuntimeTeamSession(projectRoot, record);
   return record;
 }
 
 export async function listAgentExecutionRecords(projectRoot: string, runId: string): Promise<AgentExecutionRecord[]> {
-  const recordsDir = getAgentExecutionsDir(projectRoot, runId);
+  const runtimeRecords = await listRuntimeAgentExecutions(projectRoot, runId);
+  if (runtimeRecords.length > 0) {
+    return runtimeRecords;
+  }
+  const recordsDir = getLegacyAgentExecutionsDir(projectRoot, runId);
   if (!await exists(recordsDir)) {
     return [];
   }
@@ -54,7 +55,11 @@ export async function listAgentExecutionRecords(projectRoot: string, runId: stri
 }
 
 export async function listTeamSessionRecords(projectRoot: string, runId: string): Promise<TeamSessionRecord[]> {
-  const recordsDir = getTeamSessionsDir(projectRoot, runId);
+  const runtimeRecords = await listRuntimeTeamSessions(projectRoot, runId);
+  if (runtimeRecords.length > 0) {
+    return runtimeRecords;
+  }
+  const recordsDir = getLegacyTeamSessionsDir(projectRoot, runId);
   if (!await exists(recordsDir)) {
     return [];
   }

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

@@ -9,13 +9,23 @@ import { doctor } from '../doctor/doctor.js';
 import { writeArtifact } from '../run-state/artifacts.js';
 import { readRunState } from '../run-state/run-state.js';
 import { validResultArtifact, validTaskMarkdown, writeBranchDocs } from '../test-support/fixtures.js';
+import { writeVerifyContract } from '../verification/verify-contract.js';
+import { evaluateLifecycleRiskDecisionForModel, recordLifecycleRiskDecisionProjection } from '../risk.js';
+import { parseSddBranch } from '../sdd-docs/task-parser.js';
 import { inspectBackgroundExecutor, runBackgroundExecutor } from './background-executor.js';
 
+async function seedLifecycleRiskDecision(root: string, branch: string): Promise<void> {
+  const model = await parseSddBranch(root, branch);
+  await recordLifecycleRiskDecisionProjection(root, evaluateLifecycleRiskDecisionForModel(branch, model));
+}
+
 test('background executor claims one delegation and persists background run state', async () => {
   const root = await mkdtemp(path.join(tmpdir(), 'sdd-background-claim-'));
   try {
     await initProject(root);
     await writeBranchDocs(root, 'master', validTaskMarkdown('B1', []));
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+    await seedLifecycleRiskDecision(root, 'master');
 
     const result = await runBackgroundExecutor(root, { taskId: 'B1' });
     const state = await readRunState(root, result.runId);
@@ -39,6 +49,8 @@ test('background executor ingests supplied artifact and reaches terminal state',
   try {
     await initProject(root);
     await writeBranchDocs(root, 'master', validTaskMarkdown('B1', []));
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+    await seedLifecycleRiskDecision(root, 'master');
 
     const claimed = await runBackgroundExecutor(root, { taskId: 'B1' });
     await writeArtifact(root, claimed.runId, 'implementer-B1.md', validResultArtifact('implementer', 'B1', 'PASS', 'artifacts/implementer-B1.md'));
@@ -63,16 +75,53 @@ test('background executor ingests supplied artifact and reaches terminal state',
   }
 });
 
+test('background executor replays changed terminal artifact into a new attempt', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-background-replay-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', validTaskMarkdown('B1', []));
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+    await seedLifecycleRiskDecision(root, 'master');
+
+    const claimed = await runBackgroundExecutor(root, { taskId: 'B1' });
+    await writeArtifact(root, claimed.runId, 'implementer-B1.md', validResultArtifact('implementer', 'B1', 'PASS', 'artifacts/implementer-B1.md'));
+    const completed = await runBackgroundExecutor(root, {
+      runId: claimed.runId,
+      taskId: 'B1',
+      artifactPath: 'artifacts/implementer-B1.md'
+    });
+    await writeArtifact(root, claimed.runId, 'implementer-B1.md', `${validResultArtifact('implementer', 'B1', 'PASS', 'artifacts/implementer-B1.md')}\nReplay evidence.\n`);
+    const replayed = await runBackgroundExecutor(root, {
+      runId: claimed.runId,
+      taskId: 'B1',
+      artifactPath: 'artifacts/implementer-B1.md'
+    });
+    const state = await readRunState(root, claimed.runId);
+
+    assert.equal(completed.status, 'completed');
+    assert.equal(replayed.status, 'completed');
+    assert.equal(replayed.delegationId, 'B-B1-implementer-001');
+    assert.equal(replayed.ingestion?.delegationId, 'B-B1-implementer-002');
+    assert.equal(replayed.ingestion?.retryOf, 'B-B1-implementer-001');
+    assert.equal(state.delegations['B-B1-implementer-001']?.status, 'COMPLETED');
+    assert.equal(state.delegations['B-B1-implementer-002']?.status, 'COMPLETED');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
 test('claude code subagent worker spawns host process and ingests stdout artifact', async () => {
   const root = await mkdtemp(path.join(tmpdir(), 'sdd-background-claude-host-'));
   try {
     await initProject(root);
     await writeBranchDocs(root, 'master', validTaskMarkdown('B1', []));
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+    await seedLifecycleRiskDecision(root, 'master');
     const hostScript = path.join(root, 'fake-claude-host.mjs');
     await writeFile(hostScript, [
       "const prompt = process.argv[2] ?? '';",
       "if (!prompt.includes('Queue item id:')) process.exit(2);",
-      "process.stdout.write('# implementer result\\n\\n```sdd-result\\ncontract: sdd-result-v1\\nversion: 1.3.0\\nagent: implementer\\ntask: B1\\nstatus: PASS\\nartifacts:\\n  - artifacts/implementer-B1.md\\n```\\n');"
+      "process.stdout.write('# implementer result\\n\\n```sdd-result\\ncontract: sdd-result-v1\\nversion: 1.3.0\\nagent: implementer\\ntask: B1\\nstatus: PASS\\nartifacts:\\n  - .sdd/runs/master/do/implementer-B1.md\\n```\\n');"
     ].join('\n'), 'utf8');
 
     const completed = await runBackgroundExecutor(root, {
@@ -86,7 +135,7 @@ test('claude code subagent worker spawns host process and ingests stdout artifac
 
     assert.equal(completed.status, 'completed');
     assert.equal(completed.hostInvocation?.exitCode, 0);
-    assert.equal(completed.hostInvocation?.artifactPath, 'artifacts/implementer-B1.md');
+    assert.equal(completed.hostInvocation?.artifactPath, '.sdd/runs/master/do/implementer-B1.md');
     assert.equal(completed.ingestion?.delegationStatus, 'COMPLETED');
     assert.equal(state.delegations['B-B1-implementer-001']?.status, 'COMPLETED');
     assert.equal(inspection.terminalDelegations, 1);
@@ -101,6 +150,8 @@ test('background executor blocks invalid artifact evidence instead of completing
   try {
     await initProject(root);
     await writeBranchDocs(root, 'master', validTaskMarkdown('B1', []));
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+    await seedLifecycleRiskDecision(root, 'master');
 
     const claimed = await runBackgroundExecutor(root, { taskId: 'B1' });
     await writeArtifact(root, claimed.runId, 'implementer-B1.md', '# Missing contract\n');
@@ -125,6 +176,8 @@ test('background executor requires approval for database manual gate and accepts
   try {
     await initProject(root);
     await writeBranchDocs(root, 'master', validTaskMarkdown('B1', []).replace('risk: []', 'risk:\n  - database'));
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+    await seedLifecycleRiskDecision(root, 'master');
 
     const blocked = await runBackgroundExecutor(root, { taskId: 'B1' });
     assert.equal(blocked.status, 'blocked');
@@ -153,6 +206,8 @@ test('background executor blocks manual handoff worker adapters', async () => {
   try {
     await initProject(root);
     await writeBranchDocs(root, 'master', validTaskMarkdown('B1', []));
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+    await seedLifecycleRiskDecision(root, 'master');
 
     const result = await runBackgroundExecutor(root, { taskId: 'B1', workerAdapterId: 'manual-handoff-worker' });