sdd-agent-platform 0.3.0 → 0.4.1

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

@@ -0,0 +1,176 @@
+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 getLegacyRunDir(projectRoot: string, runId: string): string {
+  assertSafePathSegment(runId, 'runId');
+  return path.join(getRunsDir(projectRoot), runId);
+}
+
+export function getRunDir(projectRoot: string, runId: string): string {
+  return getLegacyRunDir(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 getLegacyArtifactsDir(projectRoot: string, runId: string): string {
+  return path.join(getLegacyRunDir(projectRoot, runId), 'artifacts');
+}
+
+export function getArtifactsDir(projectRoot: string, runId: string): string {
+  return getLegacyArtifactsDir(projectRoot, runId);
+}
+
+export function getLegacyAgentExecutionsDir(projectRoot: string, runId: string): string {
+  return path.join(getLegacyRunDir(projectRoot, runId), 'agent-executions');
+}
+
+export function getAgentExecutionsDir(projectRoot: string, runId: string): string {
+  return getLegacyAgentExecutionsDir(projectRoot, runId);
+}
+
+export function getLegacyTeamSessionsDir(projectRoot: string, runId: string): string {
+  return path.join(getLegacyRunDir(projectRoot, runId), 'team-sessions');
+}
+
+export function getTeamSessionsDir(projectRoot: string, runId: string): string {
+  return getLegacyTeamSessionsDir(projectRoot, runId);
+}
+
+export function getLegacyWorkerRuntimesDir(projectRoot: string, runId: string): string {
+  return path.join(getLegacyRunDir(projectRoot, runId), 'worker-runtimes');
+}
+
+export function getWorkerRuntimesDir(projectRoot: string, runId: string): string {
+  return getLegacyWorkerRuntimesDir(projectRoot, runId);
+}
+
+export function getLegacyInvocationLedgerPath(projectRoot: string, runId: string): string {
+  return path.join(getLegacyRunDir(projectRoot, runId), 'invocations.jsonl');
+}
+
+export function getInvocationLedgerPath(projectRoot: string, runId: string): string {
+  return getLegacyInvocationLedgerPath(projectRoot, runId);
+}
+
+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 getLegacyWorkerRuntimeRecordPath(projectRoot: string, runId: string, runtimeId: string): string {
+  assertSafePathSegment(runtimeId, 'runtimeId');
+  return path.join(getLegacyWorkerRuntimesDir(projectRoot, runId), `${runtimeId}.json`);
+}
+
+export function getWorkerRuntimeRecordPath(projectRoot: string, runId: string, runtimeId: string): string {
+  return getLegacyWorkerRuntimeRecordPath(projectRoot, runId, runtimeId);
+}
+
+export function getLegacyAgentExecutionRecordPath(projectRoot: string, runId: string, executionId: string): string {
+  assertSafePathSegment(executionId, 'executionId');
+  return path.join(getLegacyAgentExecutionsDir(projectRoot, runId), `${executionId}.json`);
+}
+
+export function getAgentExecutionRecordPath(projectRoot: string, runId: string, executionId: string): string {
+  return getLegacyAgentExecutionRecordPath(projectRoot, runId, executionId);
+}
+
+export function getLegacyTeamSessionRecordPath(projectRoot: string, runId: string, teamId: string): string {
+  assertSafePathSegment(teamId, 'teamId');
+  return path.join(getLegacyTeamSessionsDir(projectRoot, runId), `${teamId}.json`);
+}
+
+export function getTeamSessionRecordPath(projectRoot: string, runId: string, teamId: string): string {
+  return getLegacyTeamSessionRecordPath(projectRoot, runId, teamId);
+}
+
+export function getLegacyArtifactPath(projectRoot: string, runId: string, relativeArtifactPath: string): string {
+  const artifactsDir = getLegacyArtifactsDir(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 getArtifactPath(projectRoot: string, runId: string, relativeArtifactPath: string): string {
+  return getLegacyArtifactPath(projectRoot, runId, relativeArtifactPath);
+}
+
+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;
+}

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

@@ -0,0 +1,111 @@
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { CONTEXT_RESOLVER_CONTRACT_VERSION } from '../contracts.js';
+import { branchToSafePartition, normalizePortablePath, safeBranchOrNull } from '../path-safety.js';
+import { getProjectConfigPath } from '../runtime-paths.js';
+import type { RunState } from '../run-state/model.js';
+import { parseProjectConfig } from '../config/project-config.js';
+
+const execFileAsync = promisify(execFile);
+
+export type ContextBranchSource = 'explicit_option' | 'cli_option' | 'project_config' | 'git_branch';
+
+export interface ContextResolverContract {
+  contract: typeof CONTEXT_RESOLVER_CONTRACT_VERSION;
+  branch: string;
+  partition: string;
+  rawBranch: string;
+  branchSource: ContextBranchSource;
+  currentGitBranch: string | null;
+  workingTreeMatched: boolean | null;
+  specDir: string;
+}
+
+export async function resolveSddContext(projectRoot: string, options: { branch?: string | null; branchSource?: ContextBranchSource } = {}): Promise<ContextResolverContract> {
+  const currentGitBranch = await getCurrentGitBranch(projectRoot);
+  const requestedBranch = options.branch?.trim();
+  if (requestedBranch) {
+    return resolvedContext(projectRoot, requestedBranch, options.branchSource ?? 'explicit_option', currentGitBranch);
+  }
+
+  if (currentGitBranch) {
+    return resolvedContext(projectRoot, currentGitBranch, 'git_branch', currentGitBranch);
+  }
+
+  const projectConfigBranch = await resolveProjectConfigBranch(projectRoot);
+  if (projectConfigBranch) {
+    return resolvedContext(projectRoot, projectConfigBranch, 'project_config', currentGitBranch);
+  }
+
+  throw new Error('Cannot resolve SDD branch. Run from a Git branch, pass --branch <branch>, or set sdd.default_branch in .sdd/project.yml. The spec stage is the workflow partition entry.');
+}
+
+export async function resolveRunStateContext(projectRoot: string, state: RunState): Promise<ContextResolverContract> {
+  if (!state.partition && !state.gitBranch) {
+    return resolveSddContext(projectRoot);
+  }
+
+  const currentGitBranch = await getCurrentGitBranch(projectRoot);
+  const partition = state.partition ?? branchToSafePartition(state.gitBranch ?? '');
+  const rawBranch = state.gitBranch ?? state.partition ?? partition;
+  return {
+    contract: CONTEXT_RESOLVER_CONTRACT_VERSION,
+    branch: partition,
+    partition,
+    rawBranch,
+    branchSource: 'explicit_option',
+    currentGitBranch,
+    workingTreeMatched: currentGitBranch ? currentGitBranch === rawBranch : null,
+    specDir: normalizePortablePath(path.relative(projectRoot, path.join(projectRoot, 'specs', partition)))
+  };
+}
+
+function resolvedContext(projectRoot: string, rawBranch: string, branchSource: ContextBranchSource, currentGitBranch: string | null): ContextResolverContract {
+  const partition = branchToSafePartition(rawBranch);
+  return {
+    contract: CONTEXT_RESOLVER_CONTRACT_VERSION,
+    branch: partition,
+    partition,
+    rawBranch,
+    branchSource,
+    currentGitBranch,
+    workingTreeMatched: currentGitBranch ? currentGitBranch === rawBranch : null,
+    specDir: normalizePortablePath(path.relative(projectRoot, path.join(projectRoot, 'specs', partition)))
+  };
+}
+
+async function resolveProjectConfigBranch(projectRoot: string): Promise<string | null> {
+  try {
+    const configPath = getProjectConfigPath(projectRoot);
+    const raw = await readFile(configPath, 'utf8');
+    const config = parseProjectConfig(raw, configPath);
+    const defaultBranch = safeBranchOrNull(config.sdd.default_branch ?? '');
+    if (defaultBranch) {
+      return defaultBranch;
+    }
+
+    const specDir = normalizePortablePath(config.sdd.spec_dir);
+    if (specDir.includes('<branch>')) {
+      return null;
+    }
+    const parts = specDir.split('/');
+    if (parts.length === 2 && parts[0] === 'specs') {
+      return safeBranchOrNull(parts[1]);
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+async function getCurrentGitBranch(projectRoot: string): Promise<string | null> {
+  try {
+    const result = await execFileAsync('git', ['-C', projectRoot, 'branch', '--show-current']);
+    const branch = result.stdout.trim();
+    return branch.length > 0 ? branch : null;
+  } catch {
+    return null;
+  }
+}

package/node_modules/@sdd-agent-platform/core/src/sdd-docs/document-hashes.ts

@@ -0,0 +1,207 @@
+import { createHash } from 'node:crypto';
+
+const TASK_CONTRACT_METADATA_KEYS = [
+  'id',
+  'wave',
+  'depends_on',
+  'acceptance_refs',
+  'plan_refs',
+  'affected_files',
+  'change_surface',
+  'implementation_wave',
+  'validation_batch',
+  'validation_timing',
+  'requires_verify_before_next',
+  'validation',
+  'risk',
+  'required_artifacts',
+  'allowed_agents',
+  'verification_availability',
+  'autonomy',
+  'validation_wave',
+  'review_gate'
+];
+
+const TASK_CONTRACT_SECTION_TITLES = [
+  'Boundary',
+  'Acceptance',
+  'Definition of Done',
+  'Evidence Expectations'
+];
+
+const TOP_LEVEL_CONTRACT_SECTION_TITLES = [
+  'Delivery Map',
+  'Wave Plan',
+  'Implementation Waves',
+  'Validation Waves',
+  'Review Gate',
+  'Review Gates',
+  'Review Gate Declarations',
+  'Phase Gate Checkpoint'
+];
+
+export function hashDocumentContent(raw: string): string {
+  return sha256(raw.replace(/\r\n/g, '\n'));
+}
+
+export function hashSemanticDocument(raw: string | null): string | null {
+  return raw === null ? null : sha256(normalizeSemanticMarkdown(raw));
+}
+
+export function hashTasksContract(raw: string | null): string | null {
+  if (raw === null) {
+    return null;
+  }
+  return sha256(stableJson({
+    tasks: parseTaskContracts(raw),
+    declarations: TOP_LEVEL_CONTRACT_SECTION_TITLES.map((title) => [title, normalizeSectionText(sectionText(raw, title))]).filter(([, value]) => value !== null)
+  }));
+}
+
+export function documentHashMatches(expected: string, actual: string): boolean {
+  return expected.replace(/^sha256:/, '') === actual;
+}
+
+function parseTaskContracts(raw: string): unknown[] {
+  const fencedBlocks = Array.from(raw.matchAll(/^\s*```sdd-task\s*\r?\n([\s\S]*?)\r?^\s*```\s*$/gm));
+  return fencedBlocks.map((blockMatch, index) => {
+    const block = blockMatch[1] ?? '';
+    const blockStart = blockMatch.index ?? 0;
+    const blockEnd = blockStart + blockMatch[0].length;
+    const nextBlockStart = fencedBlocks[index + 1]?.index ?? raw.length;
+    const section = raw.slice(blockEnd, nextTaskStart(raw, blockEnd, nextBlockStart));
+    const metadata = parseSimpleYamlBlock(block);
+    const heading = nearestTaskHeading(raw.slice(0, blockStart));
+    const id = scalarValue(metadata.id) ?? heading?.id ?? null;
+    return {
+      id,
+      title: heading?.title ?? null,
+      metadata: Object.fromEntries(TASK_CONTRACT_METADATA_KEYS.map((key) => [key, normalizedMetadataValue(metadata[key])])),
+      sections: Object.fromEntries(TASK_CONTRACT_SECTION_TITLES.map((title) => [title, normalizeSectionText(sectionText(section, title))]))
+    };
+  }).sort((left, right) => String((left as { id: string | null }).id ?? '').localeCompare(String((right as { id: string | null }).id ?? '')));
+}
+
+function normalizeSemanticMarkdown(raw: string): string {
+  return raw
+    .replace(/\r\n/g, '\n')
+    .split('\n')
+    .filter((line) => !/^\s*(created_at|updated_at|generatedAt|generated_at|run_id):/i.test(line))
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .join('\n');
+}
+
+function normalizeSectionText(value: string | null): string | null {
+  if (!value) {
+    return null;
+  }
+  return value.replace(/\r\n/g, '\n').split('\n').map((line) => line.trim()).filter((line) => line && !/^<!--.*-->$/.test(line)).join('\n');
+}
+
+function sectionText(raw: string, title: string): string | null {
+  const escaped = title.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const sectionPattern = `^\\s*#{2,4}\\s+${escaped}\\s*$([\\s\\S]*?)(?=^\\s*#{2,4}\\s+|$(?![\\s\\S]))`;
+  const match = raw.match(new RegExp(sectionPattern, 'im'));
+  const text = match?.[1]?.trim() ?? '';
+  return text.length > 0 ? text : null;
+}
+
+function parseSimpleYamlBlock(raw: string): Record<string, string | string[]> {
+  const result: Record<string, string | string[]> = {};
+  const lines = raw.split(/\r?\n/);
+  let currentListKey: string | null = null;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) {
+      continue;
+    }
+    if (currentListKey && /^-\s+/.test(trimmed)) {
+      const current = result[currentListKey];
+      const items = Array.isArray(current) ? current : [];
+      items.push(unquoteSimpleYamlValue(trimmed.slice(2).trim()));
+      result[currentListKey] = items;
+      continue;
+    }
+
+    const scalarMatch = trimmed.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!scalarMatch) {
+      currentListKey = null;
+      continue;
+    }
+    const key = scalarMatch[1];
+    const value = scalarMatch[2].trim();
+    if (value === '') {
+      result[key] = [];
+      currentListKey = key;
+    } else if (value === '[]') {
+      result[key] = [];
+      currentListKey = null;
+    } else if (value.startsWith('[') && value.endsWith(']')) {
+      result[key] = value.slice(1, -1).split(',').map((item) => unquoteSimpleYamlValue(item.trim())).filter(Boolean);
+      currentListKey = null;
+    } else {
+      result[key] = unquoteSimpleYamlValue(value);
+      currentListKey = null;
+    }
+  }
+
+  return result;
+}
+
+function normalizedMetadataValue(value: string | string[] | undefined): string | string[] | null {
+  if (Array.isArray(value)) {
+    return [...value].filter(Boolean).sort();
+  }
+  return value && value !== '[]' ? value : null;
+}
+
+function scalarValue(value: string | string[] | undefined): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+function unquoteSimpleYamlValue(value: string): string {
+  if (value.length >= 2) {
+    const first = value[0];
+    const last = value[value.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return value.slice(1, -1);
+    }
+  }
+  return value;
+}
+
+function nearestTaskHeading(prefix: string): { raw: string; id: string | null; title: string | null } | null {
+  const matches = Array.from(prefix.matchAll(/^\s*###\s+(.+)$/gm));
+  const last = matches.at(-1);
+  if (!last) {
+    return null;
+  }
+  const raw = last[1].trim();
+  const parsed = raw.match(/^([^:：\s]+)\s*[:：]\s*(.+)$/);
+  return {
+    raw,
+    id: parsed?.[1]?.trim() ?? null,
+    title: parsed?.[2]?.trim() ?? raw
+  };
+}
+
+function nextTaskStart(raw: string, offset: number, limit = raw.length): number {
+  const next = raw.slice(offset, limit).search(/^\s*###\s+/m);
+  return next < 0 ? limit : offset + next;
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableJson).join(',')}]`;
+  }
+  if (value && typeof value === 'object') {
+    return `{${Object.entries(value as Record<string, unknown>).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function sha256(value: string): string {
+  return createHash('sha256').update(value, 'utf8').digest('hex');
+}

package/node_modules/@sdd-agent-platform/core/src/sdd-docs/run-binding.ts

@@ -0,0 +1,95 @@
+import path from 'node:path';
+import { appendEvent } from '../run-state/events.js';
+import { readRunState, writeRunState } from '../run-state/run-state.js';
+import type { RunDocumentSnapshot, RunState } from '../run-state/model.js';
+import type { ContextResolverContract } from './context.js';
+import type { SddTask, SddTaskModel } from './task-parser.js';
+import { getEvidenceDir } from '../runtime-paths.js';
+
+export async function bindRunStateToTask(projectRoot: string, state: RunState, context: ContextResolverContract, model: SddTaskModel, task: SddTask | null, taskId: string): Promise<RunState> {
+  if (state.partition && state.partition !== context.partition) {
+    throw new Error(`Run ${state.runId} belongs to partition ${state.partition}, not ${context.partition}.`);
+  }
+  if (state.taskId && state.taskId !== taskId) {
+    throw new Error(`Run ${state.runId} belongs to task ${state.taskId}, not ${taskId}.`);
+  }
+  if (state.gitBranch && state.gitBranch !== context.rawBranch) {
+    throw new Error(`Run ${state.runId} belongs to Git branch ${state.gitBranch}, not ${context.rawBranch}.`);
+  }
+
+  const nextState: RunState = {
+    ...state,
+    currentTask: taskId,
+    partition: context.partition,
+    gitBranch: context.rawBranch,
+    taskId,
+    affectedFiles: task?.affectedFiles ?? state.affectedFiles,
+    documentSnapshot: documentSnapshotFromModel(model),
+    artifactRoot: path.relative(projectRoot, getEvidenceDir(projectRoot, context.partition))
+  };
+  await writeRunState(projectRoot, nextState);
+  await appendEvent(projectRoot, state.runId, {
+    event: 'run_context_bound',
+    runId: state.runId,
+    summary: `Run bound to ${context.partition}/${taskId}`,
+    data: {
+      partition: context.partition,
+      gitBranch: context.rawBranch,
+      task: taskId,
+      affectedFiles: nextState.affectedFiles,
+      documentSnapshot: nextState.documentSnapshot
+    }
+  });
+  return readRunState(projectRoot, state.runId);
+}
+
+export async function bindRunStateToTaskContext(projectRoot: string, state: RunState, context: ContextResolverContract, model: SddTaskModel, task: SddTask | null, taskId: string): Promise<RunState> {
+  if (!state.taskId || state.taskId === taskId) {
+    return bindRunStateToTask(projectRoot, state, context, model, task, taskId);
+  }
+  if (state.partition && state.partition !== context.partition) {
+    throw new Error(`Run ${state.runId} belongs to partition ${state.partition}, not ${context.partition}.`);
+  }
+  if (state.gitBranch && state.gitBranch !== context.rawBranch) {
+    throw new Error(`Run ${state.runId} belongs to Git branch ${state.gitBranch}, not ${context.rawBranch}.`);
+  }
+
+  const nextState: RunState = {
+    ...state,
+    currentTask: taskId,
+    partition: context.partition,
+    gitBranch: context.rawBranch,
+    affectedFiles: [...new Set([...state.affectedFiles, ...(task?.affectedFiles ?? [])])],
+    documentSnapshot: documentSnapshotFromModel(model),
+    artifactRoot: path.relative(projectRoot, getEvidenceDir(projectRoot, context.partition))
+  };
+  await writeRunState(projectRoot, nextState);
+  await appendEvent(projectRoot, state.runId, {
+    event: 'run_context_bound',
+    runId: state.runId,
+    summary: `Run context updated for ${context.partition}/${taskId}`,
+    data: {
+      partition: context.partition,
+      gitBranch: context.rawBranch,
+      task: taskId,
+      affectedFiles: nextState.affectedFiles,
+      documentSnapshot: nextState.documentSnapshot
+    }
+  });
+  return readRunState(projectRoot, state.runId);
+}
+
+export function documentSnapshotFromModel(model: SddTaskModel): RunDocumentSnapshot {
+  return {
+    specHash: model.documents.specHash ?? null,
+    planHash: model.documents.planHash ?? null,
+    tasksHash: model.documents.tasksHash ?? null,
+    specContractHash: model.documents.specContractHash ?? null,
+    planContractHash: model.documents.planContractHash ?? null,
+    tasksContractHash: model.documents.tasksContractHash ?? null,
+    planBasedOnSpecHash: model.documents.planBasedOnSpecHash ?? null,
+    tasksBasedOnPlanHash: model.documents.tasksBasedOnPlanHash ?? null,
+    planBasedOnSpecContractHash: model.documents.planBasedOnSpecContractHash ?? null,
+    tasksBasedOnPlanContractHash: model.documents.tasksBasedOnPlanContractHash ?? null
+  };
+}

package/node_modules/@sdd-agent-platform/core/src/sdd-docs/task-inspection.ts

@@ -0,0 +1,39 @@
+import type { SddTask, SddTaskGap, SddTaskModel } from './task-parser.js';
+
+export function inspectSddTask(model: SddTaskModel, taskId: string): { task: SddTask | null; gaps: SddTaskGap[] } {
+  const matchingTasks = model.tasks.filter((candidate) => candidate.id === taskId);
+  if (matchingTasks.length > 1) {
+    return {
+      task: null,
+      gaps: [
+        ...model.gaps.filter((gap) => gap.taskId === taskId),
+        taskGap(
+          taskId,
+          'id',
+          `Task id ${taskId} is ambiguous; ${matchingTasks.length} tasks share this id: ${matchingTasks.map(taskSourceEvidence).join('; ')}.`,
+          'Inspect by a unique task id, or rename duplicate task ids before implementation.'
+        )
+      ]
+    };
+  }
+  const task = matchingTasks[0] ?? null;
+  return {
+    task,
+    gaps: model.gaps.filter((gap) => gap.taskId === taskId || (task === null && gap.taskId === null))
+  };
+}
+
+export function taskGap(taskId: string, field: string, message: string, recommendation: string): SddTaskGap {
+  return {
+    type: 'Task Gap',
+    severity: 'blocking',
+    taskId,
+    field,
+    message,
+    recommendation
+  };
+}
+
+function taskSourceEvidence(task: Pick<SddTask, 'id' | 'source'>): string {
+  return `${task.id} at ${task.source.filePath}:${task.source.lineStart}-${task.source.lineEnd}`;
+}