sdd-agent-platform 0.3.0 → 0.4.1

package/node_modules/@sdd-agent-platform/core/src/verification/verify-contract.test.ts

@@ -0,0 +1,204 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { validTaskMarkdown, writeBranchDocs } from '../test-support/fixtures.js';
+import { inspectVerifyContract, writeVerifyContract } from './verify-contract.js';
+
+
+test('inspectVerifyContract blocks when verify document is missing', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-verify-contract-missing-'));
+  try {
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+
+    const inspection = await inspectVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+
+    assert.equal(inspection.status, 'BLOCKED');
+    assert.equal(inspection.exists, false);
+    assert.equal(inspection.taskCount, 1);
+    assert.equal(inspection.issues.some((issue) => issue.field === 'verify.md' && issue.level === 'FAIL'), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('writeVerifyContract creates task-derived verify contract', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-verify-contract-write-'));
+  try {
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+
+    const written = await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+    const inspection = await inspectVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+
+    assert.equal(written.status, 'created');
+    assert.match(written.content, /contract: sdd-verify-doc-v1/);
+    assert.match(written.content, /verification_batches:/);
+    assert.match(written.content, /id: \"task-T1\"/);
+    assert.match(written.content, /failure_policy:\n      repair_flow: deferred/);
+    assert.match(written.content, /\| T1 \|/);
+    assert.match(written.content, /author_role: verification-designer/);
+    assert.match(written.content, /independent_from_roles:\n  - task-planner\n  - implementer/);
+    assert.equal(inspection.status, 'PASS');
+    assert.equal(inspection.exists, true);
+    assert.equal(inspection.issues.length, 0);
+    assert.equal(inspection.authorRole, 'verification-designer');
+    assert.deepEqual(inspection.independentFromRoles, ['task-planner', 'implementer']);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('writeVerifyContract groups tasks by validation_batch', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-verify-contract-batch-'));
+  try {
+    await writeBranchDocs(root, 'feature', `# Tasks
+
+### T1: UI copy
+
+\`\`\`sdd-task
+id: T1
+status: pending
+wave: 1
+depends_on: []
+acceptance_refs:
+  - AC-T1-copy
+affected_files:
+  - app/src/main/webapp/index.jsp
+change_surface: frontend_only
+implementation_wave: ui-wave-1
+validation_batch: ui-render-wave-1
+validation_timing: batch_end
+requires_verify_before_next: false
+validation:
+  - browser/manual check copy => AC-T1-copy
+required_artifacts:
+  - artifacts/ui-render-wave-1.md
+risk: []
+\`\`\`
+
+#### Boundary
+
+Only UI copy.
+
+#### Acceptance
+
+- Copy renders.
+
+### T2: UI image
+
+\`\`\`sdd-task
+id: T2
+status: pending
+wave: 1
+depends_on: []
+acceptance_refs:
+  - AC-T2-image
+affected_files:
+  - app/src/main/webapp/assets/banner.svg
+change_surface: frontend_only
+implementation_wave: ui-wave-1
+validation_batch: ui-render-wave-1
+validation_timing: batch_end
+requires_verify_before_next: false
+validation:
+  - browser/manual check image => AC-T2-image
+required_artifacts:
+  - artifacts/ui-render-wave-1.md
+risk: []
+\`\`\`
+
+#### Boundary
+
+Only UI image.
+
+#### Acceptance
+
+- Image renders.
+`);
+
+    const written = await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+
+    assert.match(written.content, /id: \"ui-render-wave-1\"/);
+    assert.match(written.content, /timing: batch_end/);
+    assert.match(written.content, /change_surface: frontend_only/);
+    assert.match(written.content, /forbidden_validation:\n      - \"maven_compile\"\n      - \"gradle_build\"/);
+    assert.match(written.content, /T1:\n        - \"AC-T1-copy\"/);
+    assert.match(written.content, /T2:\n        - \"AC-T2-image\"/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('inspectVerifyContract warns when verify document is stale', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-verify-contract-stale-'));
+  try {
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+    await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+    await writeFile(path.join(root, 'specs', 'feature', 'tasks.md'), validTaskMarkdown('T2', []), 'utf8');
+
+    const inspection = await inspectVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+
+    assert.equal(inspection.status, 'WARN');
+    assert.equal(inspection.issues.some((issue) => issue.field === 'based_on_tasks_contract_hash'), true);
+    assert.equal(inspection.issues.some((issue) => issue.field === 'tasks' && /T2/.test(issue.message)), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('inspectVerifyContract blocks legacy verify documents without tasks contract hash', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-verify-contract-legacy-'));
+  try {
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+    const written = await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+    await writeFile(path.join(root, 'specs', 'feature', 'verify.md'), written.content.replace(/^based_on_tasks_contract_hash: .+\n/m, ''), 'utf8');
+
+    const inspection = await inspectVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+
+    assert.equal(inspection.status, 'BLOCKED');
+    assert.equal(inspection.issues.some((issue) => issue.field === 'based_on_tasks_contract_hash' && issue.level === 'FAIL'), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('writeVerifyContract upgrades legacy verify documents without force', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-verify-contract-upgrade-'));
+  try {
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+    const written = await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+    await writeFile(path.join(root, 'specs', 'feature', 'verify.md'), written.content.replace(/^based_on_tasks_contract_hash: .+\n/m, ''), 'utf8');
+
+    const upgraded = await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+    const inspection = await inspectVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+
+    assert.equal(upgraded.status, 'updated');
+    assert.match(upgraded.content, /based_on_tasks_contract_hash: /);
+    assert.equal(inspection.status, 'PASS');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('writeVerifyContract preserves stale bound verify documents without force', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-verify-contract-preserve-stale-'));
+  try {
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+    const written = await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+    const verifyPath = path.join(root, 'specs', 'feature', 'verify.md');
+    const initial = await readFile(verifyPath, 'utf8');
+    await writeFile(path.join(root, 'specs', 'feature', 'tasks.md'), validTaskMarkdown('T2', []), 'utf8');
+
+    const preserved = await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+    const inspection = await inspectVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+
+    assert.equal(written.status, 'created');
+    assert.equal(preserved.status, 'unchanged');
+    assert.equal(preserved.content, initial);
+    assert.equal(inspection.status, 'WARN');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/node_modules/@sdd-agent-platform/core/src/verification/verify-contract.ts

@@ -0,0 +1,358 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { VERIFY_DOCUMENT_CONTRACT_VERSION } from '../contracts.js';
+import { resolveSddContext, type ContextBranchSource } from '../sdd-docs/context.js';
+import { parseSddBranch, type SddTask, type SddTaskModel } from '../sdd-docs/task-parser.js';
+import { exists } from '../storage/json-io.js';
+
+export type VerifyContractStatus = 'PASS' | 'WARN' | 'BLOCKED';
+export type VerifyContractIssueLevel = 'WARN' | 'FAIL';
+export type VerifyContractAuthorRole = 'verification-designer';
+
+const VERIFY_CONTRACT_AUTHOR_ROLE: VerifyContractAuthorRole = 'verification-designer';
+const REQUIRED_INDEPENDENT_FROM_ROLES = ['task-planner', 'implementer'] as const;
+
+export interface VerifyContractIssue {
+  level: VerifyContractIssueLevel;
+  field: string;
+  message: string;
+  action: string;
+}
+
+export interface VerifyContractInspection {
+  contract: typeof VERIFY_DOCUMENT_CONTRACT_VERSION;
+  branch: string;
+  verifyPath: string;
+  exists: boolean;
+  status: VerifyContractStatus;
+  basedOnTasksHash: string | null;
+  currentTasksHash: string | null;
+  basedOnTasksContractHash: string | null;
+  currentTasksContractHash: string | null;
+  issues: VerifyContractIssue[];
+  taskCount: number;
+  authorRole: VerifyContractAuthorRole | null;
+  independentFromRoles: string[];
+}
+
+export interface WriteVerifyContractResult {
+  branch: string;
+  verifyPath: string;
+  relativePath: string;
+  status: 'created' | 'updated' | 'unchanged';
+  content: string;
+}
+
+export async function inspectVerifyContract(projectRoot: string, options: { branch?: string | null; branchSource?: ContextBranchSource } = {}): Promise<VerifyContractInspection> {
+  const context = await resolveSddContext(projectRoot, options);
+  const model = await parseSddBranch(projectRoot, context.partition);
+  const raw = model.documents.verifyExists ? await readFile(model.verifyPath, 'utf8') : null;
+  const issues: VerifyContractIssue[] = [];
+
+  if (!model.documents.tasksExists) {
+    issues.push({
+      level: 'FAIL',
+      field: 'tasks.md',
+      message: 'Cannot inspect verify.md because tasks.md is missing.',
+      action: 'Create specs/<branch>/tasks.md before generating verify.md.'
+    });
+  }
+
+  if (!model.documents.verifyExists || raw === null) {
+    issues.push({
+      level: 'FAIL',
+      field: 'verify.md',
+      message: 'Verification contract document is missing.',
+      action: `Run /sdd:tasks or sdd verifies write --branch ${context.partition} to create specs/${context.partition}/verify.md before /sdd:test.`
+    });
+  } else {
+    if (!raw.includes(`contract: ${VERIFY_DOCUMENT_CONTRACT_VERSION}`)) {
+      issues.push({
+        level: 'FAIL',
+        field: 'contract',
+        message: `verify.md does not declare contract ${VERIFY_DOCUMENT_CONTRACT_VERSION}.`,
+        action: 'Regenerate verify.md with sdd verifies write or update the frontmatter contract.'
+      });
+    }
+    if (!model.documents.verifyBasedOnTasksContractHash) {
+      issues.push({
+        level: 'FAIL',
+        field: 'based_on_tasks_contract_hash',
+        message: 'verify.md does not bind to the frozen tasks contract hash.',
+        action: `Run /sdd:tasks or sdd verifies write --branch ${context.partition} --force to regenerate verify.md from the current tasks contract.`
+      });
+    }
+
+    if (model.documents.verifyStale) {
+      issues.push({
+        level: model.documents.verifyBasedOnTasksContractHash ? 'WARN' : 'FAIL',
+        field: 'based_on_tasks_contract_hash',
+        message: model.documents.verifyBasedOnTasksContractHash
+          ? `verify.md is stale for current tasks contract hash ${model.documents.tasksContractHash}.`
+          : 'verify.md cannot be proven current because based_on_tasks_contract_hash is missing.',
+        action: `Run /sdd:tasks or sdd verifies write --branch ${context.partition} --force after reviewing task contract changes.`
+      });
+    }
+    const authorRole = readDocumentScalar(raw, 'author_role');
+    if (authorRole !== VERIFY_CONTRACT_AUTHOR_ROLE) {
+      issues.push({
+        level: 'WARN',
+        field: 'author_role',
+        message: `verify.md must be owned by ${VERIFY_CONTRACT_AUTHOR_ROLE}, not ${authorRole ?? 'missing'}.`,
+        action: 'Regenerate verify.md with a verification-designer role before running sdd test task.'
+      });
+    }
+    const independentFromRoles = readDocumentList(raw, 'independent_from_roles');
+    for (const role of REQUIRED_INDEPENDENT_FROM_ROLES) {
+      if (!independentFromRoles.includes(role)) {
+        issues.push({
+          level: 'WARN',
+          field: 'independent_from_roles',
+          message: `verify.md must declare independence from ${role}.`,
+          action: 'Regenerate verify.md so task planning, verification design, and implementation are separated.'
+        });
+      }
+    }
+    if (!/^verification_batches:\s*$/m.test(raw)) {
+      issues.push({
+        level: 'FAIL',
+        field: 'verification_batches',
+        message: 'verify.md does not declare verification_batches from the frozen tasks contract.',
+        action: `Run /sdd:tasks or sdd verifies write --branch ${context.partition} --force to regenerate verify.md as a batch/wave validation plan.`
+      });
+    }
+    for (const task of model.tasks) {
+      if (!new RegExp(`\\b${escapeRegex(task.id)}\\b`).test(raw)) {
+        issues.push({
+          level: 'WARN',
+          field: 'tasks',
+          message: `verify.md does not mention task ${task.id}.`,
+          action: 'Refresh verify.md so every executable task has verification expectations.'
+        });
+      }
+    }
+  }
+
+  return {
+    contract: VERIFY_DOCUMENT_CONTRACT_VERSION,
+    branch: context.partition,
+    verifyPath: model.verifyPath,
+    exists: model.documents.verifyExists,
+    status: issues.some((issue) => issue.level === 'FAIL') ? 'BLOCKED' : issues.length > 0 ? 'WARN' : 'PASS',
+    basedOnTasksHash: model.documents.verifyBasedOnTasksHash ?? null,
+    currentTasksHash: model.documents.tasksHash ?? null,
+    basedOnTasksContractHash: model.documents.verifyBasedOnTasksContractHash ?? null,
+    currentTasksContractHash: model.documents.tasksContractHash ?? null,
+    issues,
+    taskCount: model.tasks.length,
+    authorRole: raw ? readDocumentScalar(raw, 'author_role') as VerifyContractAuthorRole | null : null,
+    independentFromRoles: raw ? readDocumentList(raw, 'independent_from_roles') : []
+  };
+}
+
+export async function writeVerifyContract(projectRoot: string, options: { branch?: string | null; branchSource?: ContextBranchSource; force?: boolean } = {}): Promise<WriteVerifyContractResult> {
+  const context = await resolveSddContext(projectRoot, options);
+  const model = await parseSddBranch(projectRoot, context.partition);
+  const content = renderVerifyContractDocument(model, new Date().toISOString());
+  const existed = await exists(model.verifyPath);
+  if (existed && !options.force) {
+    const current = await readFile(model.verifyPath, 'utf8');
+    const currentTasksContractHash = readDocumentScalar(current, 'based_on_tasks_contract_hash');
+    const hasCurrentBatchPlan = /^verification_batches:\s*$/m.test(current);
+    const hasContractBinding = Boolean(currentTasksContractHash && currentTasksContractHash !== 'missing');
+    if (current === content || (hasContractBinding && hasCurrentBatchPlan)) {
+      return {
+        branch: context.partition,
+        verifyPath: model.verifyPath,
+        relativePath: `specs/${context.partition}/verify.md`,
+        status: 'unchanged',
+        content: current
+      };
+    }
+  }
+  await mkdir(path.dirname(model.verifyPath), { recursive: true });
+  await writeFile(model.verifyPath, content, 'utf8');
+  return {
+    branch: context.partition,
+    verifyPath: model.verifyPath,
+    relativePath: `specs/${context.partition}/verify.md`,
+    status: existed ? 'updated' : 'created',
+    content
+  };
+}
+
+export function renderVerifyContractDocument(model: SddTaskModel, timestamp: string): string {
+  return `---
+contract: ${VERIFY_DOCUMENT_CONTRACT_VERSION}
+version: 1.0.0
+branch: ${model.branch}
+based_on_tasks_contract_hash: ${model.documents.tasksContractHash ?? 'missing'}
+based_on_tasks_hash: ${model.documents.tasksHash ?? 'missing'}
+author_role: ${VERIFY_CONTRACT_AUTHOR_ROLE}
+independent_from_roles:
+${REQUIRED_INDEPENDENT_FROM_ROLES.map((role) => `  - ${role}`).join('\n')}
+created_at: ${timestamp}
+updated_at: ${timestamp}
+---
+
+# Verify Contract: ${model.branch}
+
+## 1. Purpose
+
+This document maps executable SDD tasks to verification expectations. It is derived from specs/${model.branch}/tasks.md and is not runtime evidence. It is owned by the verification-designer role and must remain independent from task planning and implementation authority.
+
+## 2. Verification Batches
+
+verification_batches:
+${model.tasks.length > 0 ? renderVerificationBatches(model.tasks) : '  []'}
+
+## 3. Task Verification Matrix
+
+| Task | Acceptance refs | Validation commands | Required artifacts | Verification availability |
+|---|---|---|---|---|
+${model.tasks.length > 0 ? model.tasks.map(renderTaskMatrixRow).join('\n') : '| none | none | none | none | none |'}
+
+## 4. Verification Rules
+
+- The agent that creates tasks.md must not be the same authority that owns verify.md.
+- The implementer must not own verify.md or perform authoritative goal verification.
+- Reviewer and validator evidence must use run-relative artifacts/<file> paths.
+- Physical evidence files live under branch evidence .sdd/runs/<branchSlug>/evidence/artifacts/.
+- Goal-level verify must resolve the latest eligible run by branch and task unless --run is explicitly supplied for replay.
+- PASS requires policy-backed acceptance evidence, not mention-only acceptance text.
+- \`/sdd:test\` consumes this contract and must not create or refresh it.
+- Low-level sync-back may inspect or replay the generated proposal for diagnostic/recovery use, but normal workflow completion proceeds through test judgment and ship readiness.
+
+## 5. Out of Scope
+
+- This document does not replace runtime.sqlite, branch evidence artifacts, validator reports, or sync-back proposals.
+- This document does not authorize publish, push, tag, release, or source changes outside the selected task boundary.
+`;
+}
+
+interface VerificationBatch {
+  id: string;
+  tasks: SddTask[];
+}
+
+function renderVerificationBatches(tasks: SddTask[]): string {
+  const batches = new Map<string, VerificationBatch>();
+  for (const task of tasks) {
+    const id = task.validationBatch ?? `task-${task.id}`;
+    const existing = batches.get(id);
+    if (existing) {
+      existing.tasks.push(task);
+    } else {
+      batches.set(id, { id, tasks: [task] });
+    }
+  }
+  return Array.from(batches.values()).map(renderVerificationBatch).join('\n');
+}
+
+function renderVerificationBatch(batch: VerificationBatch): string {
+  const timing = batch.tasks.some((task) => task.validationTiming === 'wave_end') ? 'wave_end' : batch.tasks.some((task) => task.validationTiming === 'batch_end') ? 'batch_end' : 'task_end';
+  const changeSurface = unique(batch.tasks.map((task) => task.changeSurface)).length === 1 ? batch.tasks[0].changeSurface : 'mixed';
+  const requiredArtifacts = unique(batch.tasks.flatMap((task) => task.requiredArtifacts));
+  const forbiddenValidation = changeSurface === 'frontend_only' ? ['maven_compile', 'gradle_build'] : [];
+  return [
+    `  - id: ${quoteYaml(batch.id)}`,
+    `    timing: ${timing}`,
+    `    tasks:`,
+    ...batch.tasks.map((task) => `      - ${quoteYaml(task.id)}`),
+    `    change_surface: ${changeSurface}`,
+    `    checks:`,
+    ...renderBatchChecks(batch.tasks),
+    `    forbidden_validation:${renderInlineOrNestedList(forbiddenValidation, 6)}`,
+    `    required_artifacts:${renderInlineOrNestedList(requiredArtifacts, 6)}`,
+    `    acceptance_mapping:`,
+    ...renderAcceptanceMapping(batch.tasks),
+    `    failure_policy:`,
+    `      repair_flow: deferred`,
+    `      rerun_scope: pending_design`
+  ].join('\n');
+}
+
+function renderBatchChecks(tasks: SddTask[]): string[] {
+  const checks = unique(tasks.flatMap((task) => task.validation));
+  return checks.length > 0 ? checks.map((check) => `      - ${quoteYaml(check)}`) : ['      []'];
+}
+
+function renderAcceptanceMapping(tasks: SddTask[]): string[] {
+  const lines: string[] = [];
+  for (const task of tasks) {
+    lines.push(`      ${task.id}:`);
+    if (task.acceptanceRefs.length > 0) {
+      lines.push(...task.acceptanceRefs.map((ref) => `        - ${quoteYaml(ref)}`));
+    } else {
+      lines.push('        []');
+    }
+  }
+  return lines;
+}
+
+function renderInlineOrNestedList(values: string[], indent: number): string {
+  if (values.length === 0) {
+    return ' []';
+  }
+  const spaces = ' '.repeat(indent);
+  return `\n${values.map((value) => `${spaces}- ${quoteYaml(value)}`).join('\n')}`;
+}
+
+function unique(values: string[]): string[] {
+  return Array.from(new Set(values.filter(Boolean)));
+}
+
+function quoteYaml(value: string): string {
+  return JSON.stringify(value);
+}
+
+function renderTaskMatrixRow(task: SddTask): string {
+  return `| ${task.id} | ${cell(task.acceptanceRefs)} | ${cell(task.validation)} | ${cell(task.requiredArtifacts)} | ${cell(task.verificationAvailability)} |`;
+}
+
+function cell(values: string[]): string {
+  return values.length > 0 ? values.join('<br>') : 'none';
+}
+
+function readDocumentScalar(raw: string, key: string): string | null {
+  const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = raw.match(new RegExp(`^[^\\S\\r\\n]*(?:-[^\\S\\r\\n]*)?${escapedKey}:[^\\S\\r\\n]*(.+?)[^\\S\\r\\n]*$`, 'm'));
+  return match ? cleanDocumentValue(match[1]) : null;
+}
+
+function readDocumentList(raw: string, key: string): string[] {
+  const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const scalar = readDocumentScalar(raw, key);
+  if (scalar && scalar !== '[]') {
+    if (scalar.startsWith('[') && scalar.endsWith(']')) {
+      return scalar.slice(1, -1).split(',').map(cleanDocumentValue).filter(Boolean);
+    }
+    return [scalar];
+  }
+
+  const lines = raw.split(/\r?\n/);
+  const start = lines.findIndex((line) => new RegExp(`^\\s*${escapedKey}:\\s*$`).test(line));
+  if (start === -1) {
+    return [];
+  }
+
+  const values: string[] = [];
+  for (const line of lines.slice(start + 1)) {
+    if (/^\S/.test(line) || /^---\s*$/.test(line)) {
+      break;
+    }
+    const item = line.trim().match(/^-\s+(.+)$/)?.[1];
+    if (item) {
+      values.push(cleanDocumentValue(item));
+    }
+  }
+  return values;
+}
+
+function cleanDocumentValue(value: string): string {
+  return value.trim().replace(/^["'`]|["'`]$/g, '');
+}
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

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

@@ -0,0 +1,8 @@
+export * from './verification/goal-verify.js';
+export { renderGoalVerifyResult, renderSingleTaskLoopResult } from './verification/rendering.js';
+export type { GoalVerifyResultLike, SingleTaskLoopResultLike } from './verification/rendering.js';
+export * from './verification/single-task-loop.js';
+export * from './verification/verify-contract.js';
+export * from './verification/test-runtime.js';
+export * from './verification/validation-wave.js';
+export * from './verification/review-gate.js';

package/node_modules/@sdd-agent-platform/core/src/work-units/contracts.ts

@@ -0,0 +1,26 @@
+import type { RuntimeRef, RuntimeScope } from '../contracts.js';
+import { WORK_UNIT_CONTRACT_VERSION } from '../contracts.js';
+
+export type WorkUnitType = 'main-agent' | 'co-main-agent' | 'subagent';
+export type WorkUnitStatus = 'pending' | 'running' | 'completed' | 'blocked' | 'failed' | 'cancelled';
+export type WorkUnitAuthority = 'stage-owner' | 'stage-contributor' | 'non-authoritative';
+export type WorkUnitRequiredBefore = 'stage-output' | 'handoff' | 'sync-back' | 'ship' | 'never';
+
+export interface WorkUnit {
+  contract: typeof WORK_UNIT_CONTRACT_VERSION;
+  id: string;
+  scope: RuntimeScope;
+  stageRunId: string;
+  type: WorkUnitType;
+  name: string;
+  purpose: string;
+  status: WorkUnitStatus;
+  blocking: boolean;
+  authority: WorkUnitAuthority;
+  requiredBefore: WorkUnitRequiredBefore;
+  contextRef: RuntimeRef;
+  outputRefs: RuntimeRef[];
+  evidenceRefs: RuntimeRef[];
+  createdAt: string;
+  completedAt?: string;
+}