sdd-agent-platform 0.4.0 → 0.4.1

package/node_modules/@sdd-agent-platform/core/src/run-state/task-evidence.ts

@@ -0,0 +1,206 @@
+import { branchToSafePartition } from '../path-safety.js';
+import { listRuntimeAcceptanceEvidenceMaps, listRuntimeAgentExecutions, listRuntimeArtifactPayloads, listRuntimeDurableGaps, listRuntimeFanInEvidenceSets, listRuntimeLlmAdvisorAssessments, listRuntimeStageRoleResults, listRuntimeStageTeamSessions, listRuntimeSyncBackDecisions, listRuntimeTeamSessions, listRuntimeTestRuns, listRuntimeValidationEnvironmentSessions, listRuntimeValidationWaveRuns, listRuntimeWorkflowGateDecisions, listRuntimeWorkerRuntimes } from '../storage/runtime-store.js';
+import type { RuntimeAcceptanceEvidenceMapRecord, RuntimeArtifactPayloadRecord, RuntimeDurableGapRecord, RuntimeSyncBackDecisionRecord, RuntimeTestRunRecord, RuntimeValidationEnvironmentSessionRecord, RuntimeValidationWaveRunRecord } from '../storage/runtime-store.js';
+import type { AgentExecutionRecord, TeamSessionRecord } from '../router/agent-runtime.js';
+import type { ResidentWorkerRuntimeRecord } from '../execution/resident-worker.js';
+import type { FanInEvidenceSetRecord, LlmAdvisorAssessmentRecord, StageRoleResultRecord, StageTeamSessionRecord } from '../execution/stage-team-runtime.js';
+import type { WorkflowGateDecision } from '../workflow-gate/types.js';
+import type { RunState } from './model.js';
+import { resolveWorkflowState } from '../workflow-state/resolve.js';
+import type { LatestEligibleRunCandidate, LatestEligibleRunSelection } from '../workflow-state/latest-eligible-run.js';
+import type { SddTaskGap } from '../sdd-docs/task-parser.js';
+
+export const TASK_EVIDENCE_VIEW_CONTRACT_VERSION = 'phase-8.12-task-evidence-view-v1';
+
+export interface TaskEvidencePayloadGroups {
+  active: RuntimeArtifactPayloadRecord[];
+  candidate: RuntimeArtifactPayloadRecord[];
+  rejected: RuntimeArtifactPayloadRecord[];
+  superseded: RuntimeArtifactPayloadRecord[];
+  all: RuntimeArtifactPayloadRecord[];
+}
+
+export interface TaskEvidenceRuntimeActivity {
+  agentExecutions: AgentExecutionRecord[];
+  teamSessions: TeamSessionRecord[];
+  workerRuntimes: ResidentWorkerRuntimeRecord[];
+}
+
+export interface TaskEvidenceValidationView {
+  runValidation: RunState['validation'] | null;
+  testRuns: RuntimeTestRunRecord[];
+  validationWaves: RuntimeValidationWaveRunRecord[];
+  environmentSessions: RuntimeValidationEnvironmentSessionRecord[];
+  acceptanceEvidenceMaps: RuntimeAcceptanceEvidenceMapRecord[];
+}
+
+export interface TaskEvidenceStageTeamView {
+  sessions: StageTeamSessionRecord[];
+  roleResults: StageRoleResultRecord[];
+  advisorAssessments: LlmAdvisorAssessmentRecord[];
+  fanInEvidenceSets: FanInEvidenceSetRecord[];
+}
+
+export interface TaskEvidenceWorkflowGateView {
+  latestDecision: WorkflowGateDecision | null;
+  decisions: WorkflowGateDecision[];
+}
+
+export interface TaskEvidenceView {
+  contract: typeof TASK_EVIDENCE_VIEW_CONTRACT_VERSION;
+  generatedAt: string;
+  retrievalMemoryOnly: false;
+  source: 'runtime.sqlite+branch-evidence-payloads';
+  branch: string;
+  taskId: string;
+  latestEligibleRun: LatestEligibleRunCandidate | null;
+  candidates: LatestEligibleRunCandidate[];
+  rejected: LatestEligibleRunCandidate[];
+  compatibility: LatestEligibleRunCandidate['compatibility'] | null;
+  payloads: TaskEvidencePayloadGroups;
+  validation: TaskEvidenceValidationView;
+  syncBackDecision: RuntimeSyncBackDecisionRecord | null;
+  runtimeActivity: TaskEvidenceRuntimeActivity;
+  gaps: SddTaskGap[];
+  durableGaps: RuntimeDurableGapRecord[];
+  stageTeam: TaskEvidenceStageTeamView;
+  workflowGate: TaskEvidenceWorkflowGateView;
+}
+
+export async function readTaskEvidenceView(projectRoot: string, input: { branch?: string | null; taskId: string }): Promise<TaskEvidenceView> {
+  const workflow = await resolveWorkflowState(projectRoot, { branch: input.branch, branchSource: input.branch ? 'cli_option' : undefined, taskId: input.taskId });
+  const selection = workflow.latestEligibleRunsByTask.find((entry) => entry.taskId === input.taskId) ?? emptySelection(workflow.branch, input.taskId);
+  const selectedRunState = selection.selected?.runId === workflow.latestRunState?.runId ? workflow.latestRunState : null;
+  const runIds = uniqueRunIds(selection);
+  const payloads = await readTaskPayloads(projectRoot, workflow.branch, input.taskId, runIds);
+  const [testRuns, validationWaveEvidence, syncBackDecision, runtimeActivity, durableGaps, stageTeam, workflowGate] = selection.selected
+    ? await Promise.all([
+      listRuntimeTestRuns(projectRoot, selection.selected.runId),
+      readValidationWaveEvidence(projectRoot, workflow.branch, input.taskId, selection.selected.runId),
+      latestSyncBackDecision(projectRoot, selection.selected.runId),
+      readRuntimeActivity(projectRoot, selection.selected.runId),
+      listRuntimeDurableGaps(projectRoot, { partition: workflow.branch, taskId: input.taskId, status: 'open_terminal' }),
+      readStageTeamEvidence(projectRoot, workflow.branch, input.taskId, selection.selected.runId),
+      readWorkflowGateEvidence(projectRoot, workflow.branch, input.taskId, selection.selected.runId)
+    ])
+    : await Promise.all([
+      Promise.resolve([]),
+      readValidationWaveEvidence(projectRoot, workflow.branch, input.taskId, null),
+      Promise.resolve(null),
+      Promise.resolve(emptyRuntimeActivity()),
+      listRuntimeDurableGaps(projectRoot, { partition: workflow.branch, taskId: input.taskId, status: 'open_terminal' }),
+      readStageTeamEvidence(projectRoot, workflow.branch, input.taskId, null),
+      readWorkflowGateEvidence(projectRoot, workflow.branch, input.taskId, null)
+    ]);
+
+  const [validationWaves, environmentSessions, acceptanceEvidenceMaps] = validationWaveEvidence;
+  return {
+    contract: TASK_EVIDENCE_VIEW_CONTRACT_VERSION,
+    generatedAt: new Date().toISOString(),
+    retrievalMemoryOnly: false,
+    source: 'runtime.sqlite+branch-evidence-payloads',
+    branch: workflow.branch,
+    taskId: input.taskId,
+    latestEligibleRun: selection.selected,
+    candidates: selection.candidates,
+    rejected: selection.rejected,
+    compatibility: selection.selected?.compatibility ?? null,
+    payloads,
+    validation: {
+      runValidation: selectedRunState?.validation ?? null,
+      testRuns: testRuns.filter((run) => run.taskId === input.taskId),
+      validationWaves,
+      environmentSessions,
+      acceptanceEvidenceMaps
+    },
+    syncBackDecision,
+    runtimeActivity,
+    gaps: [...workflow.visibleGaps.filter((gap) => gap.taskId === input.taskId || gap.taskId === null), ...runtimeTaskGaps(selectedRunState?.tasks[input.taskId])],
+    durableGaps,
+    stageTeam,
+    workflowGate
+  };
+}
+
+function emptySelection(partition: string, taskId: string): LatestEligibleRunSelection {
+  return { partition, taskId, selected: null, candidates: [], rejected: [] };
+}
+
+function uniqueRunIds(selection: LatestEligibleRunSelection): string[] {
+  return Array.from(new Set([...selection.candidates, ...selection.rejected].map((candidate) => candidate.runId)));
+}
+
+async function readTaskPayloads(projectRoot: string, branch: string, taskId: string, runIds: string[]): Promise<TaskEvidencePayloadGroups> {
+  const payloads = runIds.length > 0
+    ? (await Promise.all(runIds.map((runId) => listRuntimeArtifactPayloads(projectRoot, { runId, taskId })))).flat()
+    : await listRuntimeArtifactPayloads(projectRoot, { branchSlug: branchToSafePartition(branch), taskId });
+  return {
+    active: payloads.filter((payload) => payload.status === 'active'),
+    candidate: payloads.filter((payload) => payload.status === 'candidate'),
+    rejected: payloads.filter((payload) => payload.status === 'rejected'),
+    superseded: payloads.filter((payload) => payload.status === 'superseded'),
+    all: payloads
+  };
+}
+
+async function readValidationWaveEvidence(projectRoot: string, partition: string, taskId: string, runId: string | null): Promise<[RuntimeValidationWaveRunRecord[], RuntimeValidationEnvironmentSessionRecord[], RuntimeAcceptanceEvidenceMapRecord[]]> {
+  const query = runId ? { partition, runId, taskId } : { partition, taskId };
+  const validationWaves = await listRuntimeValidationWaveRuns(projectRoot, query);
+  const waveRunIds = validationWaves.map((wave) => wave.waveRunId);
+  const [environmentSessions, acceptanceEvidenceMaps] = await Promise.all([
+    Promise.all(waveRunIds.map((waveRunId) => listRuntimeValidationEnvironmentSessions(projectRoot, { partition, waveRunId }))).then((items) => items.flat()),
+    Promise.all(waveRunIds.map((waveRunId) => listRuntimeAcceptanceEvidenceMaps(projectRoot, { partition, taskId, waveRunId }))).then((items) => items.flat())
+  ]);
+  return [validationWaves, environmentSessions, acceptanceEvidenceMaps];
+}
+
+async function latestSyncBackDecision(projectRoot: string, runId: string): Promise<RuntimeSyncBackDecisionRecord | null> {
+  const decisions = await listRuntimeSyncBackDecisions(projectRoot, runId);
+  return decisions[0] ?? null;
+}
+
+async function readRuntimeActivity(projectRoot: string, runId: string): Promise<TaskEvidenceRuntimeActivity> {
+  const [agentExecutions, teamSessions, workerRuntimes] = await Promise.all([
+    listRuntimeAgentExecutions(projectRoot, runId),
+    listRuntimeTeamSessions(projectRoot, runId),
+    listRuntimeWorkerRuntimes(projectRoot, runId)
+  ]);
+  return { agentExecutions, teamSessions, workerRuntimes };
+}
+
+async function readStageTeamEvidence(projectRoot: string, partition: string, taskId: string, runId: string | null): Promise<TaskEvidenceStageTeamView> {
+  const query = runId ? { partition, taskId, runId } : { partition, taskId };
+  const [sessions, roleResults, advisorAssessments, fanInEvidenceSets] = await Promise.all([
+    listRuntimeStageTeamSessions(projectRoot, query),
+    listRuntimeStageRoleResults(projectRoot, query),
+    listRuntimeLlmAdvisorAssessments(projectRoot, query),
+    listRuntimeFanInEvidenceSets(projectRoot, query)
+  ]);
+  return { sessions, roleResults, advisorAssessments, fanInEvidenceSets };
+}
+
+async function readWorkflowGateEvidence(projectRoot: string, partition: string, taskId: string, runId: string | null): Promise<TaskEvidenceWorkflowGateView> {
+  const query = runId ? { partition, taskId, runId } : { partition, taskId };
+  const decisions = await listRuntimeWorkflowGateDecisions(projectRoot, query);
+  return { latestDecision: decisions[0] ?? null, decisions };
+}
+
+function emptyRuntimeActivity(): TaskEvidenceRuntimeActivity {
+  return { agentExecutions: [], teamSessions: [], workerRuntimes: [] };
+}
+
+function runtimeTaskGaps(taskState: unknown): SddTaskGap[] {
+  if (!taskState || typeof taskState !== 'object' || !('gaps' in taskState)) {
+    return [];
+  }
+  const gaps = (taskState as { gaps?: unknown }).gaps;
+  return Array.isArray(gaps) ? gaps.filter(isTaskGap) : [];
+}
+
+function isTaskGap(value: unknown): value is SddTaskGap {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+  const gap = value as Partial<SddTaskGap>;
+  return typeof gap.type === 'string' && typeof gap.severity === 'string' && typeof gap.field === 'string' && typeof gap.message === 'string' && typeof gap.recommendation === 'string';
+}

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

@@ -5,3 +5,4 @@ export * from './run-state/invocation-ledger.js';
 export * from './run-state/model.js';
 export * from './run-state/run-index.js';
 export * from './run-state/run-state.js';
+export * from './run-state/task-evidence.js';

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

@@ -25,11 +25,15 @@ export function getRuntimeStorePath(projectRoot: string): string {
   return path.join(getSddDir(projectRoot), 'runtime.sqlite');
 }
 
-export function getRunDir(projectRoot: string, runId: string): string {
+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));
 }
@@ -48,24 +52,44 @@ export function getEvidenceAttachmentPath(projectRoot: string, branchSlug: strin
   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 path.join(getRunDir(projectRoot, runId), 'artifacts');
+  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 path.join(getRunDir(projectRoot, runId), 'agent-executions');
+  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 path.join(getRunDir(projectRoot, runId), 'team-sessions');
+  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 path.join(getRunDir(projectRoot, runId), 'worker-runtimes');
+  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 path.join(getRunDir(projectRoot, runId), 'invocations.jsonl');
+  return getLegacyInvocationLedgerPath(projectRoot, runId);
 }
 
 export function getRouteCacheDir(projectRoot: string): string {
@@ -77,23 +101,35 @@ export function getRouteCachePath(projectRoot: string, key: string): string {
   return path.join(getRouteCacheDir(projectRoot), `${key}.json`);
 }
 
-export function getWorkerRuntimeRecordPath(projectRoot: string, runId: string, runtimeId: string): string {
+export function getLegacyWorkerRuntimeRecordPath(projectRoot: string, runId: string, runtimeId: string): string {
   assertSafePathSegment(runtimeId, 'runtimeId');
-  return path.join(getWorkerRuntimesDir(projectRoot, runId), `${runtimeId}.json`);
+  return path.join(getLegacyWorkerRuntimesDir(projectRoot, runId), `${runtimeId}.json`);
 }
 
-export function getAgentExecutionRecordPath(projectRoot: string, runId: string, executionId: string): string {
+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(getAgentExecutionsDir(projectRoot, runId), `${executionId}.json`);
+  return path.join(getLegacyAgentExecutionsDir(projectRoot, runId), `${executionId}.json`);
 }
 
-export function getTeamSessionRecordPath(projectRoot: string, runId: string, teamId: string): string {
+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(getTeamSessionsDir(projectRoot, runId), `${teamId}.json`);
+  return path.join(getLegacyTeamSessionsDir(projectRoot, runId), `${teamId}.json`);
 }
 
-export function getArtifactPath(projectRoot: string, runId: string, relativeArtifactPath: string): string {
-  const artifactsDir = getArtifactsDir(projectRoot, runId);
+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}`);
@@ -101,6 +137,10 @@ export function getArtifactPath(projectRoot: string, runId: string, relativeArti
   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)}`;
 }

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

@@ -39,7 +39,7 @@ export async function resolveSddContext(projectRoot: string, options: { branch?:
     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. /sdd:spec is the workflow partition entry.');
+  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> {

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

@@ -1,8 +1,10 @@
+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) {
@@ -22,7 +24,8 @@ export async function bindRunStateToTask(projectRoot: string, state: RunState, c
     gitBranch: context.rawBranch,
     taskId,
     affectedFiles: task?.affectedFiles ?? state.affectedFiles,
-    documentSnapshot: documentSnapshotFromModel(model)
+    documentSnapshot: documentSnapshotFromModel(model),
+    artifactRoot: path.relative(projectRoot, getEvidenceDir(projectRoot, context.partition))
   };
   await writeRunState(projectRoot, nextState);
   await appendEvent(projectRoot, state.runId, {
@@ -57,7 +60,8 @@ export async function bindRunStateToTaskContext(projectRoot: string, state: RunS
     partition: context.partition,
     gitBranch: context.rawBranch,
     affectedFiles: [...new Set([...state.affectedFiles, ...(task?.affectedFiles ?? [])])],
-    documentSnapshot: documentSnapshotFromModel(model)
+    documentSnapshot: documentSnapshotFromModel(model),
+    artifactRoot: path.relative(projectRoot, getEvidenceDir(projectRoot, context.partition))
   };
   await writeRunState(projectRoot, nextState);
   await appendEvent(projectRoot, state.runId, {
@@ -80,7 +84,12 @@ export function documentSnapshotFromModel(model: SddTaskModel): RunDocumentSnaps
     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
+    tasksBasedOnPlanHash: model.documents.tasksBasedOnPlanHash ?? null,
+    planBasedOnSpecContractHash: model.documents.planBasedOnSpecContractHash ?? null,
+    tasksBasedOnPlanContractHash: model.documents.tasksBasedOnPlanContractHash ?? null
   };
 }