sdd-agent-platform 0.2.0 → 0.4.0

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

@@ -0,0 +1,65 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, 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 warns 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, 'WARN');
+    assert.equal(inspection.exists, false);
+    assert.equal(inspection.taskCount, 1);
+    assert.equal(inspection.issues.some((issue) => issue.field === 'verify.md' && issue.level === 'WARN'), 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, /\| 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('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_hash'), true);
+    assert.equal(inspection.issues.some((issue) => issue.field === 'tasks' && /T2/.test(issue.message)), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

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

@@ -0,0 +1,247 @@
+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;
+  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: 'WARN',
+      field: 'verify.md',
+      message: 'Verification contract document is missing.',
+      action: `Run sdd verifies write --branch ${context.partition} to create specs/${context.partition}/verify.md.`
+    });
+  } 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.verifyStale) {
+      issues.push({
+        level: 'WARN',
+        field: 'based_on_tasks_hash',
+        message: `verify.md is stale for current tasks hash ${model.documents.tasksHash}.`,
+        action: `Run 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.'
+      });
+    }
+    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.'
+        });
+      }
+    }
+    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,
+    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');
+    return {
+      branch: context.partition,
+      verifyPath: model.verifyPath,
+      relativePath: `specs/${context.partition}/verify.md`,
+      status: current === content ? 'unchanged' : '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_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. 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 |'}
+
+## 3. 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.
+- Sync-back must inspect the generated proposal before applying task status changes.
+
+## 4. 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.
+`;
+}
+
+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,6 @@
+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';

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;
+}

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

@@ -0,0 +1,88 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { WORK_UNIT_CONTRACT_VERSION, type RuntimeRef, type RuntimeScope } from '../contracts.js';
+import { initProject } from '../config/init-project.js';
+import type { WorkUnit } from './contracts.js';
+import { canTransitionWorkUnit, recordWorkUnitProjection, readWorkUnitProjection, transitionWorkUnit, validateWorkUnit, workUnitBlocksGate } from './runtime.js';
+
+const scope: RuntimeScope = { branch: 'master', taskId: 'PHASE8-8', runId: 'run-1' };
+const contextRef: RuntimeRef = { kind: 'projection', ref: 'sdd-context-package:PHASE8-8' };
+const evidenceRef: RuntimeRef = { kind: 'evidence', ref: 'artifacts/phase8-work-unit-validation.md#AC-1' };
+
+test('work unit state machine accepts legal transitions and rejects terminal mutation', () => {
+  const running = transitionWorkUnit(workUnit({ status: 'pending' }), 'running');
+  const completed = transitionWorkUnit(running.workUnit, 'completed', { completedAt: '2026-05-18T00:01:00.000Z' });
+  const reopened = transitionWorkUnit(completed.workUnit, 'running');
+
+  assert.equal(canTransitionWorkUnit('pending', 'running'), true);
+  assert.equal(running.valid, true);
+  assert.equal(completed.valid, true);
+  assert.equal(completed.workUnit.status, 'completed');
+  assert.equal(completed.workUnit.completedAt, '2026-05-18T00:01:00.000Z');
+  assert.equal(canTransitionWorkUnit('completed', 'running'), false);
+  assert.equal(reopened.valid, false);
+  assert.match(reopened.issues[0], /Illegal work unit transition/);
+});
+
+test('work unit validation enforces lifecycle authority and blocking gates', () => {
+  const subagentOwner = validateWorkUnit(workUnit({ type: 'subagent', authority: 'stage-owner', blocking: true, requiredBefore: 'handoff' }));
+  const coMainOwner = validateWorkUnit(workUnit({ type: 'co-main-agent', authority: 'stage-owner', blocking: true, requiredBefore: 'handoff' }));
+  const nonBlockingGate = validateWorkUnit(workUnit({ blocking: false, requiredBefore: 'handoff' }));
+  const blockingWithoutGate = validateWorkUnit(workUnit({ blocking: true, requiredBefore: 'never' }));
+
+  assert.equal(subagentOwner.valid, false);
+  assert.equal(subagentOwner.issues.some((issue) => /Subagent work units must be non-authoritative/.test(issue)), true);
+  assert.equal(coMainOwner.valid, false);
+  assert.equal(coMainOwner.issues.some((issue) => /Only main-agent work units/.test(issue)), true);
+  assert.equal(nonBlockingGate.valid, false);
+  assert.equal(blockingWithoutGate.valid, false);
+});
+
+test('work unit blocking gate semantics distinguish blocking and non-blocking work', () => {
+  assert.equal(workUnitBlocksGate(workUnit({ blocking: true, requiredBefore: 'handoff', status: 'running' }), 'handoff'), true);
+  assert.equal(workUnitBlocksGate(workUnit({ blocking: true, requiredBefore: 'handoff', status: 'completed' }), 'handoff'), false);
+  assert.equal(workUnitBlocksGate(workUnit({ blocking: false, requiredBefore: 'never', status: 'running' }), 'handoff'), false);
+});
+
+test('work unit projections can be written and read', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-work-unit-runtime-'));
+  try {
+    await initProject(root);
+    const unit = workUnit({ status: 'running', blocking: true, requiredBefore: 'handoff' });
+
+    const write = await recordWorkUnitProjection(root, unit);
+    const restored = await readWorkUnitProjection(root, scope, unit.id);
+
+    assert.equal(write.status, 'created');
+    assert.equal(restored?.payload.id, unit.id);
+    assert.equal(restored?.payload.status, 'running');
+    assert.equal(restored?.payload.requiredBefore, 'handoff');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+function workUnit(overrides: Partial<WorkUnit> = {}): WorkUnit {
+  return {
+    contract: WORK_UNIT_CONTRACT_VERSION,
+    id: 'wu-phase8-8',
+    scope,
+    stageRunId: 'stage-do',
+    type: 'main-agent',
+    name: 'implement phase8 runtime',
+    purpose: 'Record bounded runtime work without transferring lifecycle ownership.',
+    status: 'pending',
+    blocking: true,
+    authority: 'stage-owner',
+    requiredBefore: 'stage-output',
+    contextRef,
+    outputRefs: [],
+    evidenceRefs: [evidenceRef],
+    createdAt: '2026-05-18T00:00:00.000Z',
+    ...overrides
+  };
+}

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

@@ -0,0 +1,112 @@
+import { createHash } from 'node:crypto';
+
+import type { RuntimeProjectionEnvelope, RuntimeScope } from '../contracts.js';
+import { readRuntimeProjectionEnvelope, recordRuntimeProjectionEnvelope, type RuntimeProjectionEnvelopeWriteResult } from '../storage/runtime-store.js';
+import type { WorkUnit, WorkUnitStatus } from './contracts.js';
+
+export const WORK_UNIT_RUNTIME_PRODUCER_VERSION = 'phase8-work-unit-runtime-v1';
+export const WORK_UNIT_PROJECTION_TYPE = 'phase8_work_unit';
+
+const WORK_UNIT_TRANSITIONS: Record<WorkUnitStatus, readonly WorkUnitStatus[]> = {
+  pending: ['running', 'blocked', 'cancelled'],
+  running: ['completed', 'blocked', 'failed', 'cancelled'],
+  blocked: ['running', 'cancelled'],
+  completed: [],
+  failed: [],
+  cancelled: []
+};
+
+export interface WorkUnitValidationResult {
+  valid: boolean;
+  issues: string[];
+}
+
+export interface WorkUnitTransitionResult extends WorkUnitValidationResult {
+  workUnit: WorkUnit;
+}
+
+export function canTransitionWorkUnit(from: WorkUnitStatus, to: WorkUnitStatus): boolean {
+  return WORK_UNIT_TRANSITIONS[from].includes(to);
+}
+
+export function transitionWorkUnit(workUnit: WorkUnit, status: WorkUnitStatus, options: { completedAt?: string } = {}): WorkUnitTransitionResult {
+  if (!canTransitionWorkUnit(workUnit.status, status)) {
+    return {
+      valid: false,
+      issues: [`Illegal work unit transition ${workUnit.status} -> ${status} for ${workUnit.id}.`],
+      workUnit
+    };
+  }
+  const next: WorkUnit = {
+    ...workUnit,
+    status,
+    completedAt: status === 'completed' || status === 'failed' || status === 'cancelled' ? options.completedAt ?? new Date().toISOString() : workUnit.completedAt
+  };
+  return { valid: validateWorkUnit(next).valid, issues: validateWorkUnit(next).issues, workUnit: next };
+}
+
+export function validateWorkUnit(workUnit: WorkUnit): WorkUnitValidationResult {
+  const issues: string[] = [];
+  if (workUnit.type === 'subagent' && workUnit.authority !== 'non-authoritative') {
+    issues.push('Subagent work units must be non-authoritative.');
+  }
+  if (workUnit.authority === 'stage-owner' && workUnit.type !== 'main-agent') {
+    issues.push('Only main-agent work units can own a lifecycle stage.');
+  }
+  if (!workUnit.blocking && workUnit.requiredBefore !== 'never') {
+    issues.push('Non-blocking work units cannot declare a required-before gate.');
+  }
+  if (workUnit.blocking && workUnit.requiredBefore === 'never') {
+    issues.push('Blocking work units must declare the gate they block.');
+  }
+  return { valid: issues.length === 0, issues };
+}
+
+export function workUnitBlocksGate(workUnit: WorkUnit, gate: WorkUnit['requiredBefore']): boolean {
+  return workUnit.blocking && workUnit.requiredBefore === gate && workUnit.status !== 'completed';
+}
+
+export function workUnitScopeKey(scope: RuntimeScope, workUnitId: string): string {
+  return [scope.branch, scope.taskId ?? 'all', scope.runId ?? 'none', scope.changeRef ?? 'none', workUnitId].join(':');
+}
+
+export async function recordWorkUnitProjection(projectRoot: string, workUnit: WorkUnit): Promise<RuntimeProjectionEnvelopeWriteResult<WorkUnit>> {
+  return recordRuntimeProjectionEnvelope(projectRoot, {
+    projectionType: WORK_UNIT_PROJECTION_TYPE,
+    scopeKey: workUnitScopeKey(workUnit.scope, workUnit.id),
+    inputHash: workUnitInputHash(workUnit),
+    producer: 'phase8-work-unit-runtime',
+    producerVersion: WORK_UNIT_RUNTIME_PRODUCER_VERSION,
+    generatedAt: workUnit.completedAt ?? workUnit.createdAt,
+    payload: workUnit
+  });
+}
+
+export async function readWorkUnitProjection(projectRoot: string, scope: RuntimeScope, workUnitId: string): Promise<RuntimeProjectionEnvelope<WorkUnit> | null> {
+  return readRuntimeProjectionEnvelope(projectRoot, WORK_UNIT_PROJECTION_TYPE, workUnitScopeKey(scope, workUnitId));
+}
+
+function workUnitInputHash(workUnit: WorkUnit): string {
+  return stableHash(JSON.stringify({
+    contract: workUnit.contract,
+    id: workUnit.id,
+    scope: workUnit.scope,
+    stageRunId: workUnit.stageRunId,
+    type: workUnit.type,
+    name: workUnit.name,
+    purpose: workUnit.purpose,
+    status: workUnit.status,
+    blocking: workUnit.blocking,
+    authority: workUnit.authority,
+    requiredBefore: workUnit.requiredBefore,
+    contextRef: workUnit.contextRef,
+    outputRefs: workUnit.outputRefs,
+    evidenceRefs: workUnit.evidenceRefs,
+    createdAt: workUnit.createdAt,
+    completedAt: workUnit.completedAt ?? null
+  }));
+}
+
+function stableHash(value: string): string {
+  return createHash('sha256').update(value, 'utf8').digest('hex');
+}

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

@@ -0,0 +1,2 @@
+export * from './work-units/contracts.js';
+export * from './work-units/runtime.js';

package/node_modules/@sdd-agent-platform/core/src/workflow-state/affected-file-conflicts.ts

@@ -0,0 +1,79 @@
+import type { RunState } from '../run-state/model.js';
+
+export interface WorkflowAffectedFileConflict {
+  file: string;
+  partition: string;
+  gitBranch: string | null;
+  taskId: string;
+  runId: string;
+  runStatus: RunState['status'];
+  syncBackStatus: RunState['syncBack']['status'];
+  updatedAt: string;
+}
+
+export function affectedFileConflictsForSelectedRun(states: RunState[], selected: RunState): WorkflowAffectedFileConflict[] {
+  if (!selected.partition || !selected.taskId || selected.affectedFiles.length === 0) {
+    return [];
+  }
+
+  const selectedFiles = new Set(selected.affectedFiles);
+  const conflicts: WorkflowAffectedFileConflict[] = [];
+  for (const state of states) {
+    if (!isAffectedFileConflictCandidate(state, selected)) {
+      continue;
+    }
+    for (const file of state.affectedFiles) {
+      if (selectedFiles.has(file)) {
+        conflicts.push({
+          file,
+          partition: state.partition,
+          gitBranch: state.gitBranch,
+          taskId: state.taskId,
+          runId: state.runId,
+          runStatus: state.status,
+          syncBackStatus: state.syncBack.status,
+          updatedAt: state.updatedAt
+        });
+      }
+    }
+  }
+  return conflicts.sort((left, right) => left.file.localeCompare(right.file) || left.partition.localeCompare(right.partition) || left.taskId.localeCompare(right.taskId) || left.runId.localeCompare(right.runId));
+}
+
+function isAffectedFileConflictCandidate(candidate: RunState, selected: RunState): candidate is RunState & { partition: string; taskId: string } {
+  if (candidate.runId === selected.runId || candidate.status === 'archived' || !candidate.partition || !candidate.taskId) {
+    return false;
+  }
+  if (isNonAuthoritativeForegroundRun(candidate)) {
+    return false;
+  }
+  if (selectedSupersedesCandidate(selected, candidate)) {
+    return false;
+  }
+  return isActiveAffectedFileRun(candidate);
+}
+
+function isActiveAffectedFileRun(state: RunState): boolean {
+  return state.status === 'created' || state.status === 'running' || state.syncBack.status === 'proposed';
+}
+
+function selectedSupersedesCandidate(selected: RunState, candidate: RunState): boolean {
+  return Boolean(
+    selected.partition &&
+    selected.taskId &&
+    selected.partition === candidate.partition &&
+    selected.taskId === candidate.taskId &&
+    selected.status === 'completed' &&
+    selected.validation.status === 'pass' &&
+    Date.parse(selected.updatedAt) > Date.parse(candidate.updatedAt) &&
+    (candidate.status === 'failed' || candidate.status === 'blocked' || candidate.validation.status === 'fail' || candidate.validation.status === 'blocked' || candidate.syncBack.status === 'proposed')
+  );
+}
+
+function isNonAuthoritativeForegroundRun(state: RunState): boolean {
+  if (state.phase === 'foreground-subagents') {
+    return true;
+  }
+  const delegations = Object.values(state.delegations);
+  return delegations.length > 0 && delegations.every((delegation) => delegation.runMode === 'foreground' && !delegation.blocking && !delegation.requiredForPhaseExit);
+}

package/node_modules/@sdd-agent-platform/core/src/workflow-state/dependencies.test.ts

@@ -0,0 +1,32 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { parseSddTasksMarkdown } from '../sdd-docs/task-parser.js';
+import { resolveTaskDependencyReadiness, workflowDependencyBlockers } from './dependencies.js';
+
+function taskBlock(id: string, status: string, dependsOn: string[]): string {
+  const dependsOnBlock = dependsOn.length === 0 ? 'depends_on: []' : `depends_on:\n${dependsOn.map((dependency) => `  - ${dependency}`).join('\n')}`;
+  return `### ${id}: Dependency fixture\n\n\`\`\`sdd-task\nid: ${id}\nstatus: ${status}\nwave: 1\n${dependsOnBlock}\nacceptance_refs:\n  - AC-${id}\nplan_refs:\n  - Plan\naffected_files:\n  - docs/${id}.md\nvalidation:\n  - npm test\nrisk: []\n\`\`\`\n`;
+}
+
+test('dependency readiness blocks tasks until dependencies are completed', () => {
+  const model = parseSddTasksMarkdown(`# Tasks\n\n${taskBlock('DEP1', 'pending', [])}\n${taskBlock('DEP2', 'pending', ['DEP1'])}`, { tasksPath: 'tasks.md' });
+
+  const readiness = resolveTaskDependencyReadiness(model, 'DEP2');
+
+  assert.equal(readiness.ready, false);
+  assert.deepEqual(readiness.dependencies.map((dependency) => `${dependency.taskId}:${dependency.status}:${dependency.ready}`), ['DEP1:pending:false']);
+  assert.match(readiness.blockingReasons[0], /DEP2 depends on DEP1, but DEP1 status is pending/);
+  assert.deepEqual(workflowDependencyBlockers(model).map((blocker) => `${blocker.taskId}->${blocker.dependencyId}:${blocker.dependencyStatus}`), ['DEP2->DEP1:pending']);
+});
+
+test('dependency readiness accepts completed dependencies and reports missing dependencies', () => {
+  const readyModel = parseSddTasksMarkdown(`# Tasks\n\n${taskBlock('DEP1', 'completed', [])}\n${taskBlock('DEP2', 'pending', ['DEP1'])}`, { tasksPath: 'tasks.md' });
+  const missingModel = parseSddTasksMarkdown(`# Tasks\n\n${taskBlock('DEP2', 'pending', ['MISSING'])}`, { tasksPath: 'tasks.md' });
+
+  assert.equal(resolveTaskDependencyReadiness(readyModel, 'DEP2').ready, true);
+  const missing = resolveTaskDependencyReadiness(missingModel, 'DEP2');
+  assert.equal(missing.ready, false);
+  assert.equal(missing.dependencies[0].status, 'missing');
+  assert.match(missing.blockingReasons[0], /MISSING was not found/);
+});