sdd-agent-platform 0.3.0 → 0.4.1

package/node_modules/@sdd-agent-platform/core/src/execution/stage-team-runtime.ts

@@ -0,0 +1,271 @@
+import { STAGE_TEAM_RUNTIME_CONTRACT_VERSION } from '../contracts.js';
+
+export type StageTeamLifecycleProfile = 'direct' | 'compact' | 'full' | 'research' | 'recover';
+export type StageTeamStage = 'spec' | 'plan' | 'tasks' | 'verifies' | 'do' | 'test' | 'review' | 'ship' | 'recover';
+export type StageTeamSessionStatus = 'planned' | 'running' | 'completed' | 'blocked' | 'cancelled';
+export type StageRoleAssignmentStatus = 'assigned' | 'running' | 'completed' | 'blocked' | 'skipped';
+export type StageRoleResultStatus = 'accepted' | 'candidate' | 'rejected' | 'superseded';
+export type StageRoleResultKind = 'evidence' | 'review' | 'gap' | 'proposal' | 'diagnostic' | 'gate_assessment';
+export type StageRoleAuthorityCeiling = 'advisory_only' | 'evidence_input' | 'proposal_input' | 'gate_input';
+export type LlmAdvisorAssessmentKind = 'evidence_sufficiency' | 'gap_classification' | 'semantic_drift' | 'writeback_classification' | 'risk_escalation' | 'recovery_suggestion';
+export type LlmAdvisorConcern = 'none' | 'low' | 'medium' | 'high';
+export type LlmAdvisorValidity = 'valid' | 'invalid';
+export type LlmAdvisorConfidence = 'low' | 'medium' | 'high';
+
+export interface StageRoleProfileActivation {
+  roleId: string;
+  required: boolean;
+  advisory: boolean;
+  reason: string;
+}
+
+export interface StageTeamActivationProfile {
+  contract: typeof STAGE_TEAM_RUNTIME_CONTRACT_VERSION;
+  profile: StageTeamLifecycleProfile;
+  requiredTeam: boolean;
+  roles: StageRoleProfileActivation[];
+  reason: string;
+}
+
+export interface StageTeamSessionRecord {
+  contract: typeof STAGE_TEAM_RUNTIME_CONTRACT_VERSION;
+  sessionId: string;
+  partition: string;
+  runId: string | null;
+  taskId: string | null;
+  stage: StageTeamStage;
+  lifecycleProfile: StageTeamLifecycleProfile;
+  status: StageTeamSessionStatus;
+  createdAt: string;
+  updatedAt: string;
+  assignments: StageRoleAssignment[];
+  payload: unknown;
+}
+
+export interface StageRoleAssignment {
+  assignmentId: string;
+  roleId: string;
+  agentId: string | null;
+  status: StageRoleAssignmentStatus;
+  required: boolean;
+  authorityCeiling: StageRoleAuthorityCeiling;
+  materialRefs: string[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface StageRoleResultRecord {
+  contract: typeof STAGE_TEAM_RUNTIME_CONTRACT_VERSION;
+  resultId: string;
+  sessionId: string;
+  assignmentId: string;
+  partition: string;
+  runId: string | null;
+  taskId: string | null;
+  roleId: string;
+  agentId: string | null;
+  outputKind: StageRoleResultKind;
+  authorityCeiling: StageRoleAuthorityCeiling;
+  status: StageRoleResultStatus;
+  summary: string;
+  evidenceRefs: string[];
+  durableGapIds: string[];
+  proposalRefs: string[];
+  advisorAssessmentIds: string[];
+  createdAt: string;
+  payload: unknown;
+}
+
+export interface LlmAdvisorAssessmentRecord {
+  contract: typeof STAGE_TEAM_RUNTIME_CONTRACT_VERSION;
+  assessmentId: string;
+  sessionId: string | null;
+  partition: string;
+  runId: string | null;
+  taskId: string | null;
+  kind: LlmAdvisorAssessmentKind;
+  concern: LlmAdvisorConcern;
+  validity: LlmAdvisorValidity;
+  confidence: LlmAdvisorConfidence;
+  advisoryOnly: true;
+  summary: string;
+  evidenceRefs: string[];
+  durableGapIds: string[];
+  proposalRefs: string[];
+  createdAt: string;
+  payload: unknown;
+}
+
+export interface FanInEvidenceSetRecord {
+  contract: typeof STAGE_TEAM_RUNTIME_CONTRACT_VERSION;
+  fanInId: string;
+  partition: string;
+  runId: string | null;
+  taskId: string | null;
+  stage: StageTeamStage;
+  roleResultIds: string[];
+  durableGapIds: string[];
+  proposalRefs: string[];
+  advisorAssessmentIds: string[];
+  evidenceRefs: string[];
+  canonicalEvidenceRefs: string[];
+  gateInputOnly: true;
+  createdAt: string;
+  payload: unknown;
+}
+
+const FORBIDDEN_LIFECYCLE_FIELDS = new Set([
+  'stage_passed',
+  'stagePassed',
+  'task_completed',
+  'taskCompleted',
+  'sync_back_approved',
+  'syncBackApproved',
+  'ship_ready',
+  'shipReady',
+  'final_pass',
+  'finalPass'
+]);
+
+export function assertValidStageRoleResult(value: StageRoleResultRecord | Record<string, unknown>): asserts value is StageRoleResultRecord {
+  const forbidden = firstForbiddenLifecycleField(value);
+  if (forbidden) {
+    throw new Error(`RoleResult cannot carry lifecycle transition field ${forbidden}.`);
+  }
+  const outputKind = (value as { outputKind?: unknown }).outputKind;
+  if (!isStageRoleResultKind(outputKind)) {
+    throw new Error(`RoleResult outputKind must be one of evidence, review, gap, proposal, diagnostic, gate_assessment.`);
+  }
+  const authorityCeiling = (value as { authorityCeiling?: unknown }).authorityCeiling;
+  if (!isStageRoleAuthorityCeiling(authorityCeiling)) {
+    throw new Error(`RoleResult authorityCeiling is invalid.`);
+  }
+}
+
+export function assertAdvisoryAssessment(value: LlmAdvisorAssessmentRecord | Record<string, unknown>): asserts value is LlmAdvisorAssessmentRecord {
+  const forbidden = firstForbiddenLifecycleField(value);
+  if (forbidden) {
+    throw new Error(`LLM advisor assessment cannot carry lifecycle transition field ${forbidden}.`);
+  }
+  if ((value as { advisoryOnly?: unknown }).advisoryOnly !== true) {
+    throw new Error('LLM advisor assessment must be advisoryOnly=true.');
+  }
+  const validity = (value as { validity?: unknown }).validity;
+  if (validity !== 'valid' && validity !== 'invalid') {
+    throw new Error('LLM advisor assessment validity must be valid or invalid.');
+  }
+  const confidence = (value as { confidence?: unknown }).confidence;
+  if (confidence !== 'low' && confidence !== 'medium' && confidence !== 'high') {
+    throw new Error('LLM advisor assessment confidence must be low, medium, or high.');
+  }
+}
+
+export function assertValidFanInEvidenceSet(value: FanInEvidenceSetRecord | Record<string, unknown>): asserts value is FanInEvidenceSetRecord {
+  const forbidden = firstForbiddenLifecycleField(value);
+  if (forbidden) {
+    throw new Error(`FanInEvidenceSet cannot carry lifecycle transition field ${forbidden}.`);
+  }
+  if ((value as { gateInputOnly?: unknown }).gateInputOnly !== true) {
+    throw new Error('FanInEvidenceSet must be gateInputOnly=true.');
+  }
+}
+
+export function buildFanInEvidenceSet(input: Omit<FanInEvidenceSetRecord, 'contract' | 'gateInputOnly'>): FanInEvidenceSetRecord {
+  assertValidFanInEvidenceSet({ ...input, gateInputOnly: true });
+  return {
+    contract: STAGE_TEAM_RUNTIME_CONTRACT_VERSION,
+    ...input,
+    roleResultIds: sortedUnique(input.roleResultIds),
+    durableGapIds: sortedUnique(input.durableGapIds),
+    proposalRefs: sortedUnique(input.proposalRefs),
+    advisorAssessmentIds: sortedUnique(input.advisorAssessmentIds),
+    evidenceRefs: sortedUnique(input.evidenceRefs),
+    canonicalEvidenceRefs: sortedUnique(input.canonicalEvidenceRefs),
+    gateInputOnly: true
+  };
+}
+
+export function describeStageTeamActivation(profile: StageTeamLifecycleProfile): StageTeamActivationProfile {
+  const roles = activationRoles(profile);
+  return {
+    contract: STAGE_TEAM_RUNTIME_CONTRACT_VERSION,
+    profile,
+    requiredTeam: profile !== 'direct',
+    roles,
+    reason: activationReason(profile)
+  };
+}
+
+function activationRoles(profile: StageTeamLifecycleProfile): StageRoleProfileActivation[] {
+  switch (profile) {
+    case 'direct':
+      return [];
+    case 'compact':
+      return [activationRole('role.implementation-reviewer', true, false, 'Compact profile adds one independent reviewer for bounded risk.')];
+    case 'full':
+      return [
+        activationRole('role.norm-scout', true, true, 'Full profile checks project norms before stage output.'),
+        activationRole('role.implementation-reviewer', true, false, 'Full profile requires implementation or contract review.'),
+        activationRole('role.evidence-runner', true, false, 'Full profile requires evidence collection as gate input.')
+      ];
+    case 'research':
+      return [
+        activationRole('role.norm-scout', true, true, 'Research profile gathers external and project norm context.'),
+        activationRole('role.uncertainty-reviewer', true, true, 'Research profile records unresolved ambiguity as advisory input.'),
+        activationRole('role.performance-planner', false, true, 'Research profile can add performance/token planning when relevant.')
+      ];
+    case 'recover':
+      return [
+        activationRole('role.context-curator', true, true, 'Recover profile reconstructs trusted context.'),
+        activationRole('role.sync-risk-reviewer', true, false, 'Recover profile reviews shared-state/writeback risk.'),
+        activationRole('role.verification-designer', true, false, 'Recover profile rebuilds validation needs before retry.')
+      ];
+  }
+}
+
+function activationRole(roleId: string, required: boolean, advisory: boolean, reason: string): StageRoleProfileActivation {
+  return { roleId, required, advisory, reason };
+}
+
+function activationReason(profile: StageTeamLifecycleProfile): string {
+  switch (profile) {
+    case 'direct':
+      return 'Direct profile does not require team activation; deterministic checks and explicit artifacts remain sufficient.';
+    case 'compact':
+      return 'Compact profile activates a minimal independent role for moderate risk without slowing simple flows.';
+    case 'full':
+      return 'Full profile activates norm, review, and evidence roles for high-risk implementation paths.';
+    case 'research':
+      return 'Research profile activates context and uncertainty roles for decisions that need broader evidence.';
+    case 'recover':
+      return 'Recover profile activates context, sync-risk, and verification roles because prior workflow evidence is blocked or stale.';
+  }
+}
+
+function isStageRoleResultKind(value: unknown): value is StageRoleResultKind {
+  return value === 'evidence' || value === 'review' || value === 'gap' || value === 'proposal' || value === 'diagnostic' || value === 'gate_assessment';
+}
+
+function isStageRoleAuthorityCeiling(value: unknown): value is StageRoleAuthorityCeiling {
+  return value === 'advisory_only' || value === 'evidence_input' || value === 'proposal_input' || value === 'gate_input';
+}
+
+function firstForbiddenLifecycleField(value: unknown): string | null {
+  if (!value || typeof value !== 'object') {
+    return null;
+  }
+  for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+    if (FORBIDDEN_LIFECYCLE_FIELDS.has(key)) {
+      return key;
+    }
+    const nested = firstForbiddenLifecycleField(child);
+    if (nested) {
+      return nested;
+    }
+  }
+  return null;
+}
+
+function sortedUnique(values: string[]): string[] {
+  return [...new Set(values.filter(Boolean))].sort();
+}

package/node_modules/@sdd-agent-platform/core/src/execution/wave-executor.test.ts

@@ -0,0 +1,111 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { initProject } from '../config/init-project.js';
+import { doctor } from '../doctor/doctor.js';
+import { writeArtifact } from '../run-state/artifacts.js';
+import { createRun, readRunState } from '../run-state/run-state.js';
+import { graphTaskMarkdown, validResultArtifact, writeBranchDocs } from '../test-support/fixtures.js';
+import { writeVerifyContract } from '../verification/verify-contract.js';
+import { bindTestRunState } from '../test-support/run-state.js';
+import { inspectWaveExecutor, runWaveExecutor } from './wave-executor.js';
+
+test('wave executor completes planner-safe waves from supplied artifacts', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-wave-executor-complete-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', `# Tasks\n\n${graphTaskMarkdown('WX1', [], ['src/a.ts'], [])}\n${graphTaskMarkdown('WX2', [], ['src/b.ts'], [])}`);
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+    const run = await createRun(root, { runId: 'run-1' });
+    await bindTestRunState(root, run.runId, 'master', 'WX1');
+    await writeArtifact(root, run.runId, 'implementer-WX1.md', validResultArtifact('implementer', 'WX1', 'PASS', 'artifacts/implementer-WX1.md'));
+    await writeArtifact(root, run.runId, 'implementer-WX2.md', validResultArtifact('implementer', 'WX2', 'PASS', 'artifacts/implementer-WX2.md'));
+
+    const result = await runWaveExecutor(root, {
+      runId: run.runId,
+      artifactPaths: {
+        WX1: 'artifacts/implementer-WX1.md',
+        WX2: 'artifacts/implementer-WX2.md'
+      }
+    });
+    const state = await readRunState(root, run.runId);
+    const inspection = await inspectWaveExecutor(root, run.runId);
+
+    assert.equal(result.version, 'phase-3.12-wave-executor-v1');
+    assert.equal(result.status, 'completed');
+    assert.equal(result.executedWaves, 1);
+    assert.deepEqual(result.taskResults.map((task) => task.taskId).sort(), ['WX1', 'WX2']);
+    assert.equal(state.status, 'completed');
+    assert.equal(state.phase, 'wave');
+    assert.equal(inspection.valid, true);
+    assert.equal(inspection.background.terminalDelegations, 2);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('wave executor blocks manual and blocked planner gates before execution', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-wave-executor-gates-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', `# Tasks\n\n${graphTaskMarkdown('DB1', [], ['db/schema.sql'], ['database'])}\n${graphTaskMarkdown('APP1', ['DB1'], ['src/app.ts'], [])}`);
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+
+    const result = await runWaveExecutor(root);
+
+    assert.equal(result.status, 'blocked');
+    assert.equal(result.executedWaves, 0);
+    assert.deepEqual(result.manualGates.map((gate) => gate.taskId), ['DB1']);
+    assert.deepEqual(result.blockedTasks.map((gate) => gate.taskId), ['APP1']);
+    assert.equal(result.taskResults.length, 0);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('wave executor safe-continue finishes current safe wave but does not cross dependency boundary', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-wave-executor-safe-continue-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', `# Tasks\n\n${graphTaskMarkdown('WX1', [], ['src/a.ts'], [])}\n${graphTaskMarkdown('WX2', [], ['src/b.ts'], [])}\n${graphTaskMarkdown('WX3', ['WX1'], ['src/c.ts'], [])}`);
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+    const run = await createRun(root, { runId: 'run-1' });
+    await bindTestRunState(root, run.runId, 'master', 'WX1');
+    await writeArtifact(root, run.runId, 'implementer-WX2.md', validResultArtifact('implementer', 'WX2', 'PASS', 'artifacts/implementer-WX2.md'));
+    await writeArtifact(root, run.runId, 'implementer-WX3.md', validResultArtifact('implementer', 'WX3', 'PASS', 'artifacts/implementer-WX3.md'));
+
+    const result = await runWaveExecutor(root, {
+      runId: run.runId,
+      strategy: 'safe-continue',
+      artifactPaths: {
+        WX2: 'artifacts/implementer-WX2.md',
+        WX3: 'artifacts/implementer-WX3.md'
+      }
+    });
+
+    assert.equal(result.status, 'claimed');
+    assert.equal(result.executedWaves, 1);
+    assert.deepEqual(result.taskResults.map((task) => `${task.taskId}:${task.result.status}`).sort(), ['WX1:claimed', 'WX2:completed']);
+    assert.equal(result.taskResults.some((task) => task.taskId === 'WX3'), false);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('doctor reports wave executor contract visibility', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-wave-executor-doctor-'));
+  try {
+    await initProject(root);
+
+    const report = await doctor(root, { latestOnly: true });
+    const check = report.checks.find((item) => item.check === 'wave_executor_contract');
+
+    assert.equal(check?.level, 'PASS');
+    assert.match(check?.message ?? '', /phase-3\.12-wave-executor-v1/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/node_modules/@sdd-agent-platform/core/src/execution/wave-executor.ts

@@ -0,0 +1,231 @@
+import { WAVE_EXECUTOR_CONTRACT_VERSION } from '../contracts.js';
+import { contractIssue, type ContractValidationIssue } from '../contracts/issues.js';
+import { evaluateGovernancePolicy } from '../governance/policy.js';
+import { inspectWavePlan } from '../planning/wave-plan.js';
+import { appendEvent, readRunEvents } from '../run-state/events.js';
+import type { RuntimeEvent } from '../run-state/model.js';
+import { createRun, readRunState, writeRunState } from '../run-state/run-state.js';
+import { resolveSddContext } from '../sdd-docs/context.js';
+import type { WavePlanGate } from '../planning/wave-plan.js';
+import { inspectBackgroundExecutor, runBackgroundExecutor } from './background-executor.js';
+import type { BackgroundExecutorInspection, BackgroundExecutorResult } from './background-executor.js';
+
+export type WaveExecutorStrategy = 'fast-stop' | 'safe-continue';
+export type WaveExecutorStatus = 'claimed' | 'completed' | 'failed' | 'blocked';
+
+export interface WaveExecutorRunOptions {
+  branch?: string;
+  runId?: string;
+  capabilityId?: string;
+  agent?: string;
+  workerAdapterId?: string;
+  strategy?: WaveExecutorStrategy;
+  artifactPaths?: Record<string, string>;
+}
+
+export interface WaveExecutorTaskResult {
+  waveIndex: number;
+  taskId: string;
+  result: BackgroundExecutorResult;
+}
+
+export interface WaveExecutorResult {
+  version: typeof WAVE_EXECUTOR_CONTRACT_VERSION;
+  runId: string;
+  branch: string;
+  strategy: WaveExecutorStrategy;
+  status: WaveExecutorStatus;
+  plannedWaves: number;
+  executedWaves: number;
+  taskResults: WaveExecutorTaskResult[];
+  manualGates: WavePlanGate[];
+  blockedTasks: WavePlanGate[];
+  issues: ContractValidationIssue[];
+  message: string;
+}
+
+export interface WaveExecutorInspection {
+  version: typeof WAVE_EXECUTOR_CONTRACT_VERSION;
+  runId: string;
+  background: BackgroundExecutorInspection;
+  waveEvents: RuntimeEvent[];
+  valid: boolean;
+  issues: ContractValidationIssue[];
+}
+
+export async function inspectWaveExecutor(projectRoot: string, runId: string): Promise<WaveExecutorInspection> {
+  const [background, events] = await Promise.all([
+    inspectBackgroundExecutor(projectRoot, runId),
+    readRunEvents(projectRoot, runId)
+  ]);
+  const waveEvents = events.filter((event) => event.event.startsWith('wave_executor_'));
+  const issues = [...background.issues];
+  if (waveEvents.length === 0) {
+    issues.push(contractIssue('wave_executor', `Run ${runId} has no wave executor events.`, 'Run sdd wave run before inspecting wave executor evidence.'));
+  }
+  return {
+    version: WAVE_EXECUTOR_CONTRACT_VERSION,
+    runId,
+    background,
+    waveEvents,
+    valid: issues.length === 0,
+    issues
+  };
+}
+
+export async function runWaveExecutor(projectRoot: string, options: WaveExecutorRunOptions = {}): Promise<WaveExecutorResult> {
+  const branch = options.branch ?? (await resolveSddContext(projectRoot)).branch;
+  const strategy = options.strategy ?? 'fast-stop';
+  const agent = options.agent ?? 'implementer';
+  const workerAdapterId = options.workerAdapterId ?? 'sdd-cli-task-worker';
+  const runState = options.runId ? await readRunState(projectRoot, options.runId) : await createRun(projectRoot);
+  const runId = runState.runId;
+  const plan = await inspectWavePlan(projectRoot, { branch, capabilityId: options.capabilityId ?? 'native-file-edit' });
+  const issues: ContractValidationIssue[] = [];
+  const taskResults: WaveExecutorTaskResult[] = [];
+
+  const governance = await evaluateGovernancePolicy(projectRoot, {
+    operation: 'wave_executor',
+    runId,
+    workerAdapterId,
+    riskTags: plan.manualGates.flatMap((gate) => gate.reasons)
+  });
+  if (!governance.allowed) {
+    await appendEvent(projectRoot, runId, { event: 'governance_policy_blocked', runId, summary: `Governance policy blocked wave executor for ${branch}`, data: { branch, strategy, decision: governance } });
+    await writeRunState(projectRoot, { ...runState, status: 'blocked', phase: 'wave', currentTask: null });
+    return {
+      version: WAVE_EXECUTOR_CONTRACT_VERSION,
+      runId,
+      branch,
+      strategy,
+      status: 'blocked',
+      plannedWaves: plan.waves.length,
+      executedWaves: 0,
+      taskResults,
+      manualGates: plan.manualGates,
+      blockedTasks: plan.blockedTasks,
+      issues: governance.issues,
+      message: 'Wave executor blocked by governance policy.'
+    };
+  }
+
+  await writeRunState(projectRoot, {
+    ...runState,
+    status: 'running',
+    phase: 'wave',
+    currentTask: null
+  });
+  await appendEvent(projectRoot, runId, {
+    event: 'wave_executor_started',
+    runId,
+    summary: `Wave executor started for ${branch}`,
+    data: { branch, strategy, plannedWaves: plan.waves.length }
+  });
+
+  if (!plan.valid || plan.manualGates.length > 0 || plan.blockedTasks.length > 0) {
+    for (const gate of [...plan.manualGates, ...plan.blockedTasks]) {
+      issues.push(contractIssue(`task:${gate.taskId}`, gate.reasons.join(' | '), 'Resolve manual or blocked wave gates before running the wave executor.'));
+    }
+    await appendEvent(projectRoot, runId, {
+      event: 'wave_executor_blocked',
+      runId,
+      summary: `Wave executor blocked for ${branch}`,
+      data: { branch, manualGates: plan.manualGates, blockedTasks: plan.blockedTasks, issues }
+    });
+    const blockedState = await readRunState(projectRoot, runId);
+    await writeRunState(projectRoot, { ...blockedState, status: 'blocked', phase: 'wave', currentTask: null });
+    return {
+      version: WAVE_EXECUTOR_CONTRACT_VERSION,
+      runId,
+      branch,
+      strategy,
+      status: 'blocked',
+      plannedWaves: plan.waves.length,
+      executedWaves: 0,
+      taskResults,
+      manualGates: plan.manualGates,
+      blockedTasks: plan.blockedTasks,
+      issues,
+      message: 'Wave executor blocked before executing planned tasks.'
+    };
+  }
+
+  let executedWaves = 0;
+  let stopAfterWave = false;
+  for (const wave of plan.waves) {
+    executedWaves += 1;
+    await appendEvent(projectRoot, runId, {
+      event: 'wave_executor_wave_started',
+      runId,
+      summary: `Wave ${wave.index} started`,
+      data: { branch, waveIndex: wave.index, taskIds: wave.tasks.map((task) => task.taskId) }
+    });
+    let waveTerminalCompleted = true;
+    for (const task of wave.tasks) {
+      const result = await runBackgroundExecutor(projectRoot, {
+        branch,
+        runId,
+        taskId: task.taskId,
+        agent,
+        workerAdapterId,
+        artifactPath: options.artifactPaths?.[task.taskId],
+        delegationId: `W${wave.index}-${task.taskId}-${agent}-001`
+      });
+      taskResults.push({ waveIndex: wave.index, taskId: task.taskId, result });
+      issues.push(...result.issues);
+      if (result.status !== 'completed') {
+        waveTerminalCompleted = false;
+        stopAfterWave = true;
+        if (strategy === 'fast-stop') {
+          break;
+        }
+      }
+    }
+    await appendEvent(projectRoot, runId, {
+      event: 'wave_executor_wave_completed',
+      runId,
+      summary: `Wave ${wave.index} ${waveTerminalCompleted ? 'completed' : 'stopped'}`,
+      data: { branch, waveIndex: wave.index, completed: waveTerminalCompleted }
+    });
+    if (stopAfterWave) {
+      break;
+    }
+  }
+
+  const statuses = taskResults.map((task) => task.result.status);
+  const status: WaveExecutorStatus = statuses.includes('blocked')
+    ? 'blocked'
+    : statuses.includes('failed')
+      ? 'failed'
+      : statuses.includes('claimed') || taskResults.length < plan.summary.plannedTasks
+        ? 'claimed'
+        : 'completed';
+  const completedState = await readRunState(projectRoot, runId);
+  await writeRunState(projectRoot, {
+    ...completedState,
+    status: status === 'completed' ? 'completed' : status === 'failed' ? 'failed' : status === 'blocked' ? 'blocked' : 'running',
+    phase: 'wave',
+    currentTask: null
+  });
+  await appendEvent(projectRoot, runId, {
+    event: status === 'completed' ? 'wave_executor_completed' : 'wave_executor_stopped',
+    runId,
+    summary: `Wave executor ${status} for ${branch}`,
+    data: { branch, strategy, status, executedWaves, taskResults: taskResults.map((task) => ({ waveIndex: task.waveIndex, taskId: task.taskId, status: task.result.status })) }
+  });
+
+  return {
+    version: WAVE_EXECUTOR_CONTRACT_VERSION,
+    runId,
+    branch,
+    strategy,
+    status,
+    plannedWaves: plan.waves.length,
+    executedWaves,
+    taskResults,
+    manualGates: [],
+    blockedTasks: [],
+    issues,
+    message: `Wave executor ${status} after ${executedWaves} wave(s).`
+  };
+}

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

@@ -0,0 +1,5 @@
+export * from './execution/agent-execution-records.js';
+export * from './execution/background-executor.js';
+export * from './execution/foreground-subagents.js';
+export * from './execution/resident-worker.js';
+export * from './execution/wave-executor.js';

package/node_modules/@sdd-agent-platform/core/src/governance/policy.test.ts

@@ -0,0 +1,57 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { initProject } from '../config/init-project.js';
+import { doctor } from '../doctor/doctor.js';
+import { runBackgroundExecutor } from '../execution/background-executor.js';
+import { readRunEvents } from '../run-state/events.js';
+import { validTaskMarkdown, writeBranchDocs } from '../test-support/fixtures.js';
+import { writeVerifyContract } from '../verification/verify-contract.js';
+import { evaluateGovernancePolicy, inspectGovernancePolicy } from './policy.js';
+
+test('governance policy explains confirmation and concurrency gates', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-governance-policy-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', `# Tasks\n\n${validTaskMarkdown('G1', [])}\n${validTaskMarkdown('G2', [])}\n${validTaskMarkdown('G3', [])}\n${validTaskMarkdown('G4', [])}\n${validTaskMarkdown('G5', [])}`);
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+    const policy = await inspectGovernancePolicy(root);
+    const risky = await evaluateGovernancePolicy(root, { operation: 'destructive_git' });
+
+    assert.equal(policy.version, 'phase-3.14-governance-policy-v1');
+    assert.equal(risky.status, 'confirm');
+    assert.equal(risky.allowed, false);
+    assert.equal(risky.issues.some((issue) => issue.field === 'governance.confirmation'), true);
+
+    await runBackgroundExecutor(root, { taskId: 'G1' });
+    await runBackgroundExecutor(root, { taskId: 'G2' });
+    await runBackgroundExecutor(root, { taskId: 'G3' });
+    await runBackgroundExecutor(root, { taskId: 'G4' });
+    const blocked = await runBackgroundExecutor(root, { taskId: 'G5' });
+    const events = await readRunEvents(root, blocked.runId);
+
+    assert.equal(blocked.status, 'blocked');
+    assert.equal(blocked.issues.some((issue) => issue.field === 'governance.concurrency'), true);
+    assert.equal(events.some((event) => event.event === 'governance_policy_blocked'), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('doctor reports governance policy contract visibility', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-governance-doctor-'));
+  try {
+    await initProject(root);
+
+    const report = await doctor(root, { latestOnly: true });
+    const check = report.checks.find((item) => item.check === 'governance_policy_contract');
+
+    assert.equal(check?.level, 'PASS');
+    assert.match(check?.message ?? '', /phase-3\.14-governance-policy-v1/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});