sdd-agent-platform 0.3.0 → 0.4.0

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

@@ -0,0 +1,296 @@
+import { RUNTIME_ANALYSIS_CONTRACT_VERSION } from '../contracts.js';
+import type {
+  RuntimeAnalysisEvidenceSummaryLike,
+  RuntimeAnalysisFinding,
+  RuntimeAnalysisReport,
+  RuntimeAnalysisReportInput,
+  RuntimeAnalysisRunInspectionLike,
+  RuntimeAnalysisStatus,
+  RuntimeAnalysisSyncBackLike
+} from './model.js';
+
+export function createRuntimeAnalysisReport(input: RuntimeAnalysisReportInput): RuntimeAnalysisReport {
+  const findings = buildRuntimeAnalysisFindings(input);
+  return {
+    contract: RUNTIME_ANALYSIS_CONTRACT_VERSION,
+    generatedAt: input.generatedAt,
+    profile: input.profile,
+    authoritative: false,
+    usableForPass: false,
+    status: summarizeRuntimeAnalysisStatus(findings),
+    branch: input.branch,
+    selectedRunId: input.selectedRunId,
+    selectedTaskId: input.selectedTaskId,
+    recommendedNextCommand: input.status.recommendedNextCommand,
+    workflow: input.status,
+    doctor: input.doctor,
+    runIndex: input.runIndex,
+    taskGraph: input.taskGraph,
+    wavePlan: input.wavePlan,
+    runInspection: input.runInspection,
+    evidenceSummary: input.evidenceSummary,
+    contextPackage: input.contextPackage,
+    syncBack: input.syncBack,
+    findings
+  };
+}
+
+export function buildRuntimeAnalysisFindings(input: RuntimeAnalysisReportInput): RuntimeAnalysisFinding[] {
+  const findings: RuntimeAnalysisFinding[] = [];
+  const add = (finding: RuntimeAnalysisFinding) => findings.push(finding);
+
+  if (input.status.workflowStatus === 'not_started') {
+    add({
+      severity: 'blocking',
+      category: 'workflow',
+      source: `specs/${input.branch}`,
+      message: `Workflow partition ${input.branch} has not started.`,
+      action: input.status.recommendedNextCommand
+    });
+  }
+
+  for (const gap of input.status.gaps) {
+    add({
+      severity: gap.severity === 'blocking' ? 'blocking' : 'warning',
+      category: 'workflow',
+      source: gap.field,
+      message: gap.taskId ? `${gap.taskId}: ${gap.message}` : gap.message,
+      action: gap.recommendation,
+      taskId: gap.taskId ?? undefined
+    });
+  }
+
+  if (input.status.tasks.pending > 0) {
+    add({
+      severity: 'info',
+      category: 'workflow',
+      source: `specs/${input.branch}/tasks.md`,
+      message: `${input.status.tasks.pending} pending task(s) remain.`,
+      action: input.status.recommendedNextCommand
+    });
+  }
+
+  for (const reason of input.status.latestRunStaleReasons) {
+    add({
+      severity: 'warning',
+      category: 'run',
+      source: input.status.latestRun?.runId ?? 'latest-run',
+      message: reason,
+      action: input.status.latestRun?.currentTask ? `sdd test task ${input.status.latestRun.currentTask} --branch ${input.branch}` : undefined,
+      runId: input.status.latestRun?.runId ?? undefined,
+      taskId: input.status.latestRun?.currentTask ?? undefined
+    });
+  }
+
+  for (const check of input.doctor.checks) {
+    if (check.level !== 'PASS') {
+      add({
+        severity: check.level === 'FAIL' ? 'blocking' : 'warning',
+        category: 'doctor',
+        source: check.check,
+        message: check.message,
+        action: check.action
+      });
+    }
+  }
+
+  if (!input.runIndex.exists) {
+    add({
+      severity: 'warning',
+      category: 'run_index',
+      source: input.runIndex.indexPath,
+      message: 'Local run index is missing.',
+      action: 'sdd run index rebuild'
+    });
+  } else if (!input.runIndex.valid) {
+    for (const issue of input.runIndex.issues) {
+      add({
+        severity: 'warning',
+        category: 'run_index',
+        source: input.runIndex.indexPath,
+        message: issue.message,
+        action: issue.recommendation
+      });
+    }
+  }
+
+  if (!input.taskGraph.valid) {
+    add({
+      severity: 'blocking',
+      category: 'task_graph',
+      source: `specs/${input.branch}/tasks.md`,
+      message: 'Task graph is not valid.',
+      action: `sdd tasks gaps --branch ${input.branch}`
+    });
+  }
+  for (const diagnostic of input.taskGraph.diagnostics) {
+    add({
+      severity: diagnostic.severity === 'blocking' ? 'blocking' : 'warning',
+      category: 'task_graph',
+      source: diagnostic.field,
+      message: diagnostic.taskId ? `${diagnostic.taskId}: ${diagnostic.message}` : diagnostic.message,
+      action: diagnostic.recommendation,
+      taskId: diagnostic.taskId ?? undefined
+    });
+  }
+
+  for (const gate of input.wavePlan.blockedTasks) {
+    add({
+      severity: 'blocking',
+      category: 'wave_plan',
+      source: `wave:${input.wavePlan.branch}`,
+      message: `${gate.taskId} is blocked: ${gate.reasons.join('; ')}`,
+      action: `sdd tasks inspect ${gate.taskId} --branch ${input.wavePlan.branch}`,
+      taskId: gate.taskId
+    });
+  }
+  for (const gate of input.wavePlan.manualGates) {
+    add({
+      severity: 'warning',
+      category: 'wave_plan',
+      source: `wave:${input.wavePlan.branch}`,
+      message: `${gate.taskId} requires manual gating: ${gate.reasons.join('; ')}`,
+      action: `sdd tasks inspect ${gate.taskId} --branch ${input.wavePlan.branch}`,
+      taskId: gate.taskId
+    });
+  }
+
+  if (input.runInspection) {
+    addRunInspectionFindings(input.runInspection, add);
+  }
+  if (input.evidenceSummary) {
+    addEvidenceSummaryFindings(input.evidenceSummary, add);
+  }
+  if (input.contextPackage) {
+    for (const warning of input.contextPackage.warnings) {
+      add({
+        severity: warning.includes('cannot satisfy PASS evidence') ? 'info' : 'warning',
+        category: 'context',
+        source: `context:${input.contextPackage.mode}`,
+        message: warning,
+        action: input.contextPackage.nextCommands[0],
+        taskId: input.contextPackage.taskId
+      });
+    }
+  }
+  if (input.syncBack) {
+    addSyncBackFindings(input.syncBack, add);
+  }
+  for (const issue of input.inputIssues) {
+    add({
+      severity: 'warning',
+      category: issue.source,
+      source: issue.source,
+      message: issue.message,
+      action: issue.action,
+      runId: issue.runId,
+      taskId: issue.taskId
+    });
+  }
+
+  return findings;
+}
+
+function addRunInspectionFindings(run: RuntimeAnalysisRunInspectionLike, add: (finding: RuntimeAnalysisFinding) => void): void {
+  if (run.state.status === 'failed' || run.state.status === 'blocked') {
+    add({
+      severity: 'blocking',
+      category: 'run',
+      source: run.summary.runId,
+      message: `Run status is ${run.state.status}.`,
+      action: run.summary.currentTask ? `sdd do task ${run.summary.currentTask} --branch ${run.summary.partition ?? run.summary.gitBranch ?? 'master'}` : undefined,
+      runId: run.summary.runId,
+      taskId: run.summary.currentTask ?? undefined
+    });
+  }
+  if (run.validation.status === 'fail' || run.validation.status === 'blocked') {
+    add({
+      severity: 'blocking',
+      category: 'run',
+      source: `${run.summary.runId}:validation`,
+      message: `Run validation status is ${run.validation.status}.`,
+      action: run.summary.currentTask ? `sdd test task ${run.summary.currentTask} --branch ${run.summary.partition ?? run.summary.gitBranch ?? 'master'}` : undefined,
+      runId: run.summary.runId,
+      taskId: run.summary.currentTask ?? undefined
+    });
+  }
+  if (run.syncBack.status === 'proposed') {
+    add({
+      severity: 'warning',
+      category: 'sync_back',
+      source: `${run.summary.runId}:sync_back`,
+      message: 'Run has an unapplied sync-back proposal.',
+      action: run.summary.currentTask ? `sdd sync-back inspect --branch ${run.summary.partition ?? run.summary.gitBranch ?? 'master'} --task ${run.summary.currentTask}` : undefined,
+      runId: run.summary.runId,
+      taskId: run.summary.currentTask ?? undefined
+    });
+  }
+}
+
+function addEvidenceSummaryFindings(summary: RuntimeAnalysisEvidenceSummaryLike, add: (finding: RuntimeAnalysisFinding) => void): void {
+  add({
+    severity: 'info',
+    category: 'evidence',
+    source: `evidence:${summary.runId}`,
+    message: 'Evidence summary is derived guidance only and cannot satisfy PASS evidence.',
+    action: summary.taskId ? `sdd test task ${summary.taskId}` : undefined,
+    runId: summary.runId,
+    taskId: summary.taskId ?? undefined
+  });
+  if (summary.failCount > 0 || summary.blockedCount > 0) {
+    add({
+      severity: summary.failCount > 0 ? 'blocking' : 'warning',
+      category: 'evidence',
+      source: `evidence:${summary.runId}`,
+      message: `Evidence projection has pass=${summary.passCount}, blocked=${summary.blockedCount}, fail=${summary.failCount}.`,
+      action: summary.taskId ? `sdd test task ${summary.taskId}` : undefined,
+      runId: summary.runId,
+      taskId: summary.taskId ?? undefined
+    });
+  }
+  if (summary.issueCodes.length > 0) {
+    add({
+      severity: 'warning',
+      category: 'evidence',
+      source: `evidence:${summary.runId}`,
+      message: `Evidence quality issues: ${summary.issueCodes.join(', ')}.`,
+      action: summary.taskId ? `sdd artifact validate ${summary.runId} <artifact> --task ${summary.taskId} --agent <agent>` : undefined,
+      runId: summary.runId,
+      taskId: summary.taskId ?? undefined
+    });
+  }
+}
+
+function addSyncBackFindings(syncBack: RuntimeAnalysisSyncBackLike, add: (finding: RuntimeAnalysisFinding) => void): void {
+  if (syncBack.status === 'ready') {
+    add({
+      severity: 'warning',
+      category: 'sync_back',
+      source: syncBack.targetTasksPath,
+      message: `Sync-back is ready for ${syncBack.taskId ?? 'unknown task'} but not applied.`,
+      action: `sdd sync-back apply ${syncBack.runId} --branch ${syncBack.branch} --task ${syncBack.taskId ?? '<task_id>'}${syncBack.applyPolicy.requiresApproval ? ' --approved' : ''}`,
+      runId: syncBack.runId,
+      taskId: syncBack.taskId ?? undefined
+    });
+  } else if (syncBack.status === 'blocked') {
+    add({
+      severity: 'blocking',
+      category: 'sync_back',
+      source: syncBack.targetTasksPath,
+      message: `Sync-back is blocked: ${syncBack.reasons.join('; ')}`,
+      action: `sdd sync-back inspect ${syncBack.runId} --branch ${syncBack.branch} --task ${syncBack.taskId ?? '<task_id>'}`,
+      runId: syncBack.runId,
+      taskId: syncBack.taskId ?? undefined
+    });
+  }
+}
+
+export function summarizeRuntimeAnalysisStatus(findings: RuntimeAnalysisFinding[]): RuntimeAnalysisStatus {
+  if (findings.some((finding) => finding.severity === 'blocking')) {
+    return 'BLOCKED';
+  }
+  if (findings.some((finding) => finding.severity === 'warning')) {
+    return 'WARN';
+  }
+  return 'PASS';
+}

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

@@ -0,0 +1,152 @@
+import type { RUNTIME_ANALYSIS_CONTRACT_VERSION } from '../contracts.js';
+
+export type RuntimeAnalysisProfile = 'brief' | 'normal' | 'forensic';
+
+export interface RuntimeAnalysisGapLike {
+  severity: 'blocking' | 'warning';
+  taskId: string | null;
+  field: string;
+  message: string;
+  recommendation: string;
+}
+
+export interface RuntimeAnalysisWorkflowLike {
+  workflowStatus: 'active' | 'not_started';
+  recommendedNextCommand: string;
+  gaps: RuntimeAnalysisGapLike[];
+  tasks: { pending: number };
+  latestRun: { runId: string; currentTask: string | null } | null;
+  latestRunStaleReasons: string[];
+  latestRunsByTask: Array<{ taskId: string; runId: string }>;
+}
+
+export interface RuntimeAnalysisDoctorLike {
+  checks: Array<{ level: 'PASS' | 'WARN' | 'FAIL'; check: string; message: string; action?: string }>;
+}
+
+export interface RuntimeAnalysisRunIndexLike {
+  valid: boolean;
+  exists: boolean;
+  indexPath: string;
+  issues: Array<{ message: string; recommendation: string }>;
+}
+
+export interface RuntimeAnalysisTaskGraphLike {
+  valid: boolean;
+  nodes: Array<{ taskId: string; status: string }>;
+  diagnostics: RuntimeAnalysisGapLike[];
+}
+
+export interface RuntimeAnalysisWavePlanLike {
+  branch: string;
+  blockedTasks: Array<{ taskId: string; reasons: string[] }>;
+  manualGates: Array<{ taskId: string; reasons: string[] }>;
+  summary: { tasks: number };
+}
+
+export interface RuntimeAnalysisRunInspectionLike {
+  summary: { runId: string; currentTask: string | null; partition: string | null; gitBranch: string | null };
+  state: { status: string };
+  validation: { status: string };
+  syncBack: { status: string };
+}
+
+export interface RuntimeAnalysisEvidenceSummaryLike {
+  authoritative: false;
+  usableForPass: false;
+  runId: string;
+  taskId: string | null;
+  passCount: number;
+  blockedCount: number;
+  failCount: number;
+  issueCodes: string[];
+}
+
+export interface RuntimeAnalysisContextPackageLike {
+  authoritative: false;
+  usableForPass: false;
+  mode: string;
+  taskId: string;
+  warnings: string[];
+  nextCommands: string[];
+}
+
+export interface RuntimeAnalysisSyncBackLike {
+  runId: string;
+  branch: string;
+  taskId: string | null;
+  status: 'ready' | 'blocked' | 'applied';
+  reasons: string[];
+  targetTasksPath: string;
+  applyPolicy: { requiresApproval: boolean };
+}
+
+export type RuntimeAnalysisStatus = 'PASS' | 'WARN' | 'BLOCKED';
+export type RuntimeAnalysisFindingSeverity = 'info' | 'warning' | 'blocking';
+export type RuntimeAnalysisFindingCategory = 'workflow' | 'doctor' | 'run_index' | 'run' | 'evidence' | 'sync_back' | 'task_graph' | 'wave_plan' | 'context';
+
+export interface RuntimeAnalysisOptions {
+  branch?: string | null;
+  runId?: string;
+  taskId?: string;
+  profile?: RuntimeAnalysisProfile;
+}
+
+export interface RuntimeAnalysisFinding {
+  severity: RuntimeAnalysisFindingSeverity;
+  category: RuntimeAnalysisFindingCategory;
+  source: string;
+  message: string;
+  action?: string;
+  runId?: string;
+  taskId?: string;
+}
+
+export interface RuntimeAnalysisInputIssue {
+  source: RuntimeAnalysisFindingCategory;
+  message: string;
+  action?: string;
+  runId?: string;
+  taskId?: string;
+}
+
+export interface RuntimeAnalysisReportInput {
+  generatedAt: string;
+  profile: RuntimeAnalysisProfile;
+  branch: string;
+  selectedRunId: string | null;
+  selectedTaskId: string | null;
+  status: RuntimeAnalysisWorkflowLike;
+  doctor: RuntimeAnalysisDoctorLike;
+  runIndex: RuntimeAnalysisRunIndexLike;
+  taskGraph: RuntimeAnalysisTaskGraphLike;
+  wavePlan: RuntimeAnalysisWavePlanLike;
+  runInspection: RuntimeAnalysisRunInspectionLike | null;
+  evidenceSummary: RuntimeAnalysisEvidenceSummaryLike | null;
+  contextPackage: RuntimeAnalysisContextPackageLike | null;
+  syncBack: RuntimeAnalysisSyncBackLike | null;
+  inputIssues: RuntimeAnalysisInputIssue[];
+}
+
+export interface RuntimeAnalysisReport {
+  contract: typeof RUNTIME_ANALYSIS_CONTRACT_VERSION;
+  generatedAt: string;
+  profile: RuntimeAnalysisProfile;
+  authoritative: false;
+  usableForPass: false;
+  status: RuntimeAnalysisStatus;
+  branch: string;
+  selectedRunId: string | null;
+  selectedTaskId: string | null;
+  recommendedNextCommand: string;
+  workflow: RuntimeAnalysisWorkflowLike;
+  doctor: RuntimeAnalysisDoctorLike;
+  runIndex: RuntimeAnalysisRunIndexLike;
+  taskGraph: RuntimeAnalysisTaskGraphLike;
+  wavePlan: RuntimeAnalysisWavePlanLike;
+  runInspection: RuntimeAnalysisRunInspectionLike | null;
+  evidenceSummary: RuntimeAnalysisEvidenceSummaryLike | null;
+  contextPackage: RuntimeAnalysisContextPackageLike | null;
+  syncBack: RuntimeAnalysisSyncBackLike | null;
+  findings: RuntimeAnalysisFinding[];
+}

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

@@ -0,0 +1,68 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { execFile } from 'node:child_process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+import { initProject } from './config/init-project.js';
+import { writeArtifact } from './run-state/artifacts.js';
+import { createRun } from './run-state/run-state.js';
+import { rebuildLocalRunIndex } from './run-state/run-index.js';
+import { validResultArtifact, validTaskMarkdown, validTrustEvidence, writeBranchDocs } from './test-support/fixtures.js';
+import { bindTestRunState } from './test-support/run-state.js';
+import { runGoalVerify } from './verification/goal-verify.js';
+import { writeVerifyContract } from './verification/verify-contract.js';
+import { buildRuntimeAnalysisReport } from './runtime-analysis.js';
+
+const execFileAsync = promisify(execFile);
+
+test('runtime analysis report composes workflow runtime evidence and non-authoritative projections', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-runtime-analysis-'));
+  try {
+    await initProject(root);
+    await execFileAsync('git', ['init'], { cwd: root });
+    await execFileAsync('git', ['checkout', '-b', 'feature'], { cwd: root });
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+    await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+    const state = await createRun(root, { runId: 'run-1' });
+    await bindTestRunState(root, state.runId, 'feature', 'T1');
+    await writeArtifact(root, state.runId, 'review-T1.md', validResultArtifact('reviewer', 'T1', 'PASS', 'artifacts/review-T1.md'));
+    await writeArtifact(root, state.runId, 'validation-T1.md', `${validResultArtifact('validator', 'T1', 'PASS', 'artifacts/validation-T1.md')}${validTrustEvidence('T1', 'AC-1', 'artifacts/validation-T1.md')}`);
+    await runGoalVerify(root, {
+      runId: state.runId,
+      branch: 'feature',
+      taskId: 'T1',
+      reviewArtifact: 'artifacts/review-T1.md',
+      validationArtifact: 'artifacts/validation-T1.md'
+    });
+    await rebuildLocalRunIndex(root);
+
+    const report = await buildRuntimeAnalysisReport(root, { branch: 'feature', runId: state.runId, taskId: 'T1', profile: 'brief' });
+
+    assert.equal(report.contract, 'phase-7-runtime-analysis-v1');
+    assert.equal(report.authoritative, false);
+    assert.equal(report.usableForPass, false);
+    assert.equal(report.status !== 'PASS', true);
+    assert.equal(report.branch, 'feature');
+    assert.equal(report.selectedRunId, state.runId);
+    assert.equal(report.selectedTaskId, 'T1');
+    assert.equal(report.workflow.latestRun?.runId, state.runId);
+    assert.equal(report.runIndex.exists, true);
+    assert.equal(report.taskGraph.nodes.some((node) => node.taskId === 'T1'), true);
+    assert.equal(report.wavePlan.summary.tasks, 1);
+    assert.equal(report.runInspection?.summary.runId, state.runId);
+    assert.equal(report.evidenceSummary?.runId, state.runId);
+    assert.equal(report.evidenceSummary?.authoritative, false);
+    assert.equal(report.evidenceSummary?.usableForPass, false);
+    assert.equal(report.contextPackage?.taskId, 'T1');
+    assert.equal(report.contextPackage?.authoritative, false);
+    assert.equal(report.contextPackage?.usableForPass, false);
+    assert.equal(report.syncBack?.status, 'ready');
+    assert.equal(report.findings.some((finding) => finding.category === 'sync_back' && finding.action?.includes('sdd sync-back apply run-1 --branch feature --task T1')), true);
+    assert.equal(report.findings.some((finding) => finding.category === 'evidence' && finding.message.includes('cannot satisfy PASS evidence')), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

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

@@ -0,0 +1,3 @@
+export * from './runtime-analysis/model.js';
+export * from './runtime-analysis/findings.js';
+export * from './runtime-analysis/build.js';

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

@@ -0,0 +1,136 @@
+import path from 'node:path';
+import { assertSafePathSegment, branchToSafePartition, normalizePortablePath } from './path-safety.js';
+
+export function getWorktreesDir(projectRoot: string): string {
+  return path.join(getSddDir(projectRoot), 'worktrees');
+}
+
+export function getSddDir(projectRoot: string): string {
+  return path.join(projectRoot, '.sdd');
+}
+
+export function getProjectConfigPath(projectRoot: string): string {
+  return path.join(getSddDir(projectRoot), 'project.yml');
+}
+
+export function getRunsDir(projectRoot: string): string {
+  return path.join(getSddDir(projectRoot), 'runs');
+}
+
+export function getLocalRunIndexPath(projectRoot: string): string {
+  return path.join(getSddDir(projectRoot), 'run-index.json');
+}
+
+export function getRuntimeStorePath(projectRoot: string): string {
+  return path.join(getSddDir(projectRoot), 'runtime.sqlite');
+}
+
+export function getRunDir(projectRoot: string, runId: string): string {
+  assertSafePathSegment(runId, 'runId');
+  return path.join(getRunsDir(projectRoot), runId);
+}
+
+export function getBranchRunRoot(projectRoot: string, branchSlug: string): string {
+  return path.join(getRunsDir(projectRoot), branchToSafePartition(branchSlug));
+}
+
+export function getEvidenceDir(projectRoot: string, branchSlug: string): string {
+  return path.join(getBranchRunRoot(projectRoot, branchSlug), 'evidence');
+}
+
+export function getEvidenceAttachmentPath(projectRoot: string, branchSlug: string, relativeEvidencePath: string): string {
+  const evidenceDir = getEvidenceDir(projectRoot, branchSlug);
+  const normalized = normalizeEvidenceRootRelativePath(relativeEvidencePath);
+  const resolved = path.resolve(evidenceDir, normalized);
+  if (!resolved.startsWith(path.resolve(evidenceDir) + path.sep) && resolved !== path.resolve(evidenceDir)) {
+    throw new Error(`Evidence path escapes evidence directory: ${relativeEvidencePath}`);
+  }
+  return resolved;
+}
+
+export function getArtifactsDir(projectRoot: string, runId: string): string {
+  return path.join(getRunDir(projectRoot, runId), 'artifacts');
+}
+
+export function getAgentExecutionsDir(projectRoot: string, runId: string): string {
+  return path.join(getRunDir(projectRoot, runId), 'agent-executions');
+}
+
+export function getTeamSessionsDir(projectRoot: string, runId: string): string {
+  return path.join(getRunDir(projectRoot, runId), 'team-sessions');
+}
+
+export function getWorkerRuntimesDir(projectRoot: string, runId: string): string {
+  return path.join(getRunDir(projectRoot, runId), 'worker-runtimes');
+}
+
+export function getInvocationLedgerPath(projectRoot: string, runId: string): string {
+  return path.join(getRunDir(projectRoot, runId), 'invocations.jsonl');
+}
+
+export function getRouteCacheDir(projectRoot: string): string {
+  return path.join(getSddDir(projectRoot), 'cache', 'routes');
+}
+
+export function getRouteCachePath(projectRoot: string, key: string): string {
+  assertSafePathSegment(key, 'routeCacheKey');
+  return path.join(getRouteCacheDir(projectRoot), `${key}.json`);
+}
+
+export function getWorkerRuntimeRecordPath(projectRoot: string, runId: string, runtimeId: string): string {
+  assertSafePathSegment(runtimeId, 'runtimeId');
+  return path.join(getWorkerRuntimesDir(projectRoot, runId), `${runtimeId}.json`);
+}
+
+export function getAgentExecutionRecordPath(projectRoot: string, runId: string, executionId: string): string {
+  assertSafePathSegment(executionId, 'executionId');
+  return path.join(getAgentExecutionsDir(projectRoot, runId), `${executionId}.json`);
+}
+
+export function getTeamSessionRecordPath(projectRoot: string, runId: string, teamId: string): string {
+  assertSafePathSegment(teamId, 'teamId');
+  return path.join(getTeamSessionsDir(projectRoot, runId), `${teamId}.json`);
+}
+
+export function getArtifactPath(projectRoot: string, runId: string, relativeArtifactPath: string): string {
+  const artifactsDir = getArtifactsDir(projectRoot, runId);
+  const resolved = path.resolve(artifactsDir, relativeArtifactPath);
+  if (!resolved.startsWith(path.resolve(artifactsDir) + path.sep) && resolved !== path.resolve(artifactsDir)) {
+    throw new Error(`Artifact path escapes artifacts directory: ${relativeArtifactPath}`);
+  }
+  return resolved;
+}
+
+export function getRunRelativeArtifactPath(artifactRootRelativePath: string): string {
+  return `artifacts/${normalizeArtifactRootRelativePath(artifactRootRelativePath)}`;
+}
+
+export function toArtifactRootRelativePath(runRelativeArtifactPath: string): string {
+  const portablePath = runRelativeArtifactPath.replace(/\\/g, '/');
+  if (!portablePath.startsWith('artifacts/')) {
+    throw new Error(`Run-relative artifact path must start with artifacts/: ${runRelativeArtifactPath}`);
+  }
+  return normalizeArtifactRootRelativePath(portablePath.slice('artifacts/'.length));
+}
+
+export function normalizeArtifactRootRelativePath(value: string): string {
+  const normalized = normalizePortablePath(value);
+  if (!normalized || normalized === '.' || normalized.startsWith('../') || normalized === '..' || path.isAbsolute(value)) {
+    throw new Error(`Artifact path must be relative and stay under artifacts/: ${value}`);
+  }
+  if (normalized.startsWith('artifacts/')) {
+    throw new Error(`Artifact helper paths must be artifact-root-relative, not run-relative: ${value}`);
+  }
+  return normalized;
+}
+
+export function normalizeEvidenceRootRelativePath(value: string): string {
+  const normalized = normalizePortablePath(value);
+  if (!normalized || normalized === '.' || normalized.startsWith('../') || normalized === '..' || path.isAbsolute(value)) {
+    throw new Error(`Evidence path must be relative and stay under evidence/: ${value}`);
+  }
+  if (normalized.startsWith('evidence/')) {
+    throw new Error(`Evidence helper paths must be evidence-root-relative, not branch-run-relative: ${value}`);
+  }
+  return normalized;
+}