@ijfw/memory-server 1.3.0 → 1.4.0

package/src/swarm/dispatch-prompt.js

@@ -0,0 +1,154 @@
+// Prompt scaffolding for prepared swarm tasks.
+//
+// This helper is intentionally pure and dependency-free. It renders the task
+// record already prepared on the blackboard; command integration lives in the
+// CLI layer.
+
+export function renderSwarmDispatchPrompt(task, options = {}) {
+  const normalized = normalizeTask(task);
+  const projectRoot = stringValue(options.projectRoot);
+  const lead = stringValue(options.lead) || 'main agent';
+  const codex = Boolean(options.codex);
+
+  const lines = [
+    `# IJFW Swarm Worker Prompt: ${normalized.id}`,
+    '',
+    'You are working inside an IJFW prepared swarm task. Stay inside the task scope, coordinate through the blackboard, and report blockers early.',
+    '',
+    '## Task',
+    field('Task id', normalized.id),
+    field('Title', normalized.title),
+    field('Owner', normalized.owner),
+    field('Status', normalized.status),
+    field('Wave', normalized.wave_id),
+    field('Wave mode', normalized.wave_mode),
+  ];
+
+  if (projectRoot) lines.push(field('Project root', projectRoot));
+
+  if (codex) {
+    lines.push(
+      '',
+      '## Codex Dispatch',
+      `- Preferred custom agent: ${codexAgentName(normalized.owner)}`,
+      '- If this Codex runtime cannot invoke named `.codex/agents/*.toml` agents, spawn a generic `worker` for implementation/review tasks or `explorer` for read-only discovery, then paste this prompt into it.',
+      '- Keep `fork_context` false unless the worker needs the full parent conversation; pass only the task scope and relevant files when possible.',
+    );
+  }
+
+  lines.push(
+    '',
+    '## Artifact Scope',
+    listBlock('Artifact ids', normalized.artifact_ids),
+    listBlock('Allowed paths', normalized.paths, 'No path scope was provided. Coordinate by artifact id, references, and the blackboard before editing project artifacts.'),
+    listBlock('Allowed refs', normalized.refs, 'No external or internal refs were provided.'),
+  );
+
+  lines.push(
+    '',
+    '## Dependencies',
+    listBlock('Depends on', normalized.depends_on, 'No prepared task dependencies.'),
+  );
+
+  if (normalized.blocked_by.length) {
+    lines.push(listBlock('Blocked by', normalized.blocked_by.map(formatBlocker)));
+  }
+
+  if (normalized.blocker) {
+    lines.push(listBlock('Current blocker', [normalized.blocker]));
+  }
+
+  lines.push(
+    '',
+    '## Verification',
+    listBlock('Required checks or review gates', normalized.verification, 'No verification was specified. Define an appropriate check for this artifact type and include the result in your completion note.'),
+  );
+
+  if (normalized.review_criteria.length) {
+    lines.push(
+      '',
+      '## Review Criteria',
+      listBlock('Criteria', normalized.review_criteria),
+    );
+  }
+
+  lines.push(
+    '',
+    '## Blackboard Commands',
+    `- Start when you begin: \`ijfw swarm start ${normalized.id}\``,
+    `- Complete when finished: \`ijfw swarm complete ${normalized.id} "<summary and verification result>"\``,
+    `- Block if stuck: \`ijfw swarm block ${normalized.id} "<blocker and requested help>"\``,
+  );
+
+  if (normalized.status === 'blocked') {
+    lines.push('', 'This task is currently blocked. Do not start implementation/review work until the blocker is resolved or the lead marks the task ready.');
+  } else if (normalized.status !== 'ready') {
+    lines.push('', `This task is currently \`${normalized.status}\`. Confirm with ${lead} before changing its lifecycle state.`);
+  }
+
+  lines.push(
+    '',
+    '## Operating Constraints',
+    '- Do not revert user changes or edits by other agents.',
+    '- Touch only the allowed artifact scope unless the lead expands it.',
+    '- Preserve project-agnostic output: this task may be code, design, writing, research, business, operations, or another artifact type.',
+    '- Keep handoff notes concise and include changed artifacts, verification performed, and any residual risk.',
+  );
+
+  return lines.filter((line) => line !== null && line !== undefined).join('\n').trimEnd();
+}
+
+function normalizeTask(task) {
+  const source = task && typeof task === 'object' ? task : {};
+  return {
+    id: stringValue(source.id) || 'unknown-task',
+    title: stringValue(source.title) || 'Untitled prepared swarm task',
+    owner: stringValue(source.owner) || 'unassigned',
+    status: stringValue(source.status) || 'unknown',
+    wave_id: stringValue(source.wave_id) || 'unknown',
+    wave_mode: stringValue(source.wave_mode) || 'unknown',
+    artifact_ids: stringArray(source.artifact_ids),
+    paths: stringArray(source.paths),
+    refs: stringArray(source.refs),
+    depends_on: stringArray(source.depends_on),
+    verification: stringArray(source.verification),
+    review_criteria: stringArray(source.review_criteria),
+    blocked_by: Array.isArray(source.blocked_by) ? source.blocked_by : [],
+    blocker: stringValue(source.blocker),
+  };
+}
+
+function field(label, value) {
+  return `- ${label}: ${value || 'none'}`;
+}
+
+function listBlock(label, values, empty = 'None.') {
+  const items = stringArray(values);
+  if (!items.length) return `- ${label}: ${empty}`;
+  return [`- ${label}:`, ...items.map((value) => `  - ${value}`)].join('\n');
+}
+
+function formatBlocker(blocker) {
+  if (!blocker || typeof blocker !== 'object') return stringValue(blocker) || 'unknown blocker';
+  const parts = [];
+  if (blocker.task_id) parts.push(`task ${blocker.task_id}`);
+  if (blocker.status) parts.push(`status ${blocker.status}`);
+  if (blocker.artifact_id) parts.push(`artifact ${blocker.artifact_id}`);
+  if (blocker.agent) parts.push(`agent ${blocker.agent}`);
+  if (Array.isArray(blocker.paths) && blocker.paths.length) parts.push(`paths ${blocker.paths.join(', ')}`);
+  return parts.join('; ') || JSON.stringify(blocker);
+}
+
+function stringArray(value) {
+  if (!Array.isArray(value)) return [];
+  return value.map((item) => stringValue(item)).filter(Boolean);
+}
+
+function stringValue(value) {
+  if (value === null || value === undefined) return '';
+  return String(value).trim();
+}
+
+function codexAgentName(value) {
+  return stringValue(value).toLowerCase().replace(/[^a-z0-9_]+/g, '_').replace(/^_+|_+$/g, '') || 'ijfw_agent';
+}

package/src/swarm/planner.js

@@ -0,0 +1,399 @@
+// Artifact-aware swarm planner.
+//
+// Reads Team Assembly 2.0 charter/workflow plus blackboard claims and returns
+// an execution plan. This module is intentionally read-only: it explains what
+// can run, what is blocked, and why. Execution/worktrees come later.
+
+import { readTeamAssembly } from '../team/generator.js';
+import {
+  addBlackboardNote,
+  appendBlackboardEvent,
+  blackboardStatus,
+  claimArtifact,
+  listBlackboardTasks,
+  releaseClaim,
+  updateBlackboardTask,
+  writeBlackboardTasks,
+} from '../blackboard.js';
+import { deriveReviewTasks } from './review.js';
+
+export function buildSwarmPlan(projectRoot = process.cwd(), options = {}) {
+  const team = options.team || readTeamAssembly(projectRoot);
+  if (!team.ok) {
+    return {
+      ok: false,
+      error: 'missing-team-assembly',
+      message: 'No complete team assembly found. Run: ijfw team init',
+      validation: team.validation,
+    };
+  }
+
+  const blackboard = options.blackboard || blackboardStatus(projectRoot);
+  const workflow = team.workflow;
+  const charter = team.charter;
+  const artifactsById = new Map(workflow.artifacts.map((artifact) => [artifact.id, artifact]));
+  const rolesByName = new Map(charter.roles.map((role) => [role.name, role]));
+  const activeClaims = blackboard.claims.active_items || [];
+
+  const waves = workflow.waves.map((wave) => {
+    const tasks = wave.artifact_ids.map((artifactId) => {
+      const artifact = artifactsById.get(artifactId);
+      return buildTask(artifactId, artifact, rolesByName, activeClaims);
+    });
+    const blocked = tasks.filter((task) => task.blocked);
+    const mode = normalizeMode(wave.mode, tasks);
+    return {
+      id: wave.id,
+      requested_mode: wave.mode,
+      mode,
+      artifact_ids: wave.artifact_ids.slice(),
+      tasks,
+      blocked: blocked.length > 0,
+      reason: explainWave(wave, tasks, mode),
+    };
+  });
+
+  return {
+    ok: true,
+    team_name: charter.team_name,
+    project_archetypes: workflow.project_archetypes,
+    waves,
+    summary: summarizePlan(waves),
+  };
+}
+
+export function swarmPlanSummary(plan) {
+  if (!plan.ok) return plan.message || plan.error;
+  const lines = [
+    `Swarm plan for ${plan.team_name}`,
+    `Archetypes: ${plan.project_archetypes.join(', ')}`,
+    plan.summary,
+  ];
+  for (const wave of plan.waves) {
+    lines.push(`Wave ${wave.id}: ${wave.mode}${wave.blocked ? ' (blocked)' : ''} -- ${wave.reason}`);
+    for (const task of wave.tasks) {
+      const state = task.blocked ? `blocked by ${task.blocked_by.map((c) => `${c.artifact_id}:${c.agent}`).join(', ')}` : 'ready';
+      lines.push(`  ${task.artifact_id} -> ${task.owner} [${state}]`);
+      if (task.verification.length) lines.push(`    verify: ${task.verification.join(' | ')}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+export function prepareSwarmTasks(projectRoot = process.cwd(), options = {}) {
+  const plan = options.plan || buildSwarmPlan(projectRoot, options);
+  if (!plan.ok) return { ok: false, error: plan.error, message: plan.message, plan };
+
+  const tasks = [];
+  for (const wave of plan.waves) {
+    for (const task of wave.tasks) {
+      tasks.push({
+        id: `swarm:${wave.id}:${task.artifact_id}`,
+        title: `${task.owner}: ${task.artifact_id}`,
+        status: task.blocked ? 'blocked' : 'ready',
+        wave_id: wave.id,
+        wave_mode: wave.mode,
+        artifact_ids: [task.artifact_id],
+        owner: task.owner,
+        reviewers: task.reviewers,
+        paths: task.paths,
+        refs: task.refs,
+        depends_on: task.depends_on.map((id) => `swarm:${findWaveForArtifact(plan, id) || wave.id}:${id}`),
+        verification: task.verification,
+        blocked_by: task.blocked_by.map((claim) => ({
+          artifact_id: claim.artifact_id,
+          agent: claim.agent,
+          paths: claim.paths || [],
+        })),
+      });
+    }
+  }
+
+  if (options.includeReviews) {
+    tasks.push(...deriveReviewTasks({
+      plan,
+      tasks,
+      charter: (options.team || readTeamAssembly(projectRoot)).charter,
+    }));
+  }
+
+  const write = writeBlackboardTasks(projectRoot, tasks, { replace: options.replace !== false });
+  appendBlackboardEvent(projectRoot, {
+    type: 'swarm.prepared',
+    actor: 'ijfw',
+    message: `Prepared ${tasks.length} swarm task(s)`,
+    data: { includeReviews: Boolean(options.includeReviews), replace: options.replace !== false },
+  });
+  return {
+    ok: write.ok,
+    written: write.written || 0,
+    total: write.total || 0,
+    tasks,
+    plan,
+    error: write.error,
+  };
+}
+
+export function listSwarmTasks(projectRoot = process.cwd()) {
+  const listed = listBlackboardTasks(projectRoot);
+  const tasks = (listed.tasks || []).filter((task) => String(task.id || '').startsWith('swarm:') || String(task.id || '').startsWith('review:'));
+  return { ok: listed.ok, tasks, error: listed.error };
+}
+
+export function startSwarmTask(projectRoot, taskId, options = {}) {
+  const task = findTask(projectRoot, taskId);
+  if (!task.ok) return task;
+  if (task.task.status !== 'ready') return { ok: false, error: 'task-not-ready', task: task.task };
+  const blockedDependency = firstBlockedDependency(projectRoot, task.task);
+  if (blockedDependency) return { ok: false, error: 'dependency-not-done', dependency: blockedDependency, task: task.task };
+
+  const owner = options.owner || task.task.owner;
+  const claimResults = [];
+  for (const artifactId of task.task.artifact_ids || []) {
+    const result = claimArtifact(projectRoot, {
+      artifact: artifactId,
+      owner,
+      paths: task.task.paths || [],
+      note: `swarm task ${taskId}`,
+    });
+    if (!result.ok) return { ok: false, error: 'claim-failed', claim: result, task: task.task };
+    claimResults.push(result.claim);
+  }
+
+  const updated = updateBlackboardTask(projectRoot, taskId, {
+    status: 'in_progress',
+    started_at: new Date().toISOString(),
+    active_owner: owner,
+  });
+  if (updated.ok) {
+    appendBlackboardEvent(projectRoot, {
+      type: 'task.started',
+      actor: owner,
+      task_id: taskId,
+      artifact_ids: task.task.artifact_ids || [],
+      message: `Started ${taskId}`,
+    });
+  }
+  return { ok: updated.ok, task: updated.task, claims: claimResults, error: updated.error };
+}
+
+export function completeSwarmTask(projectRoot, taskId, options = {}) {
+  const task = findTask(projectRoot, taskId);
+  if (!task.ok) return task;
+  if (!['in_progress', 'review'].includes(task.task.status)) {
+    return { ok: false, error: 'task-not-in-progress', task: task.task };
+  }
+  const owner = options.owner || task.task.active_owner || task.task.owner;
+  const releases = [];
+  for (const artifactId of task.task.artifact_ids || []) {
+    releases.push(releaseClaim(projectRoot, { artifact: artifactId, owner }));
+  }
+  const updated = updateBlackboardTask(projectRoot, taskId, {
+    status: 'done',
+    completed_at: new Date().toISOString(),
+    completion_note: options.message || undefined,
+  });
+  if (updated.ok) {
+    appendBlackboardEvent(projectRoot, {
+      type: 'task.completed',
+      actor: owner,
+      task_id: taskId,
+      artifact_ids: task.task.artifact_ids || [],
+      message: options.message || `Completed ${taskId}`,
+    });
+  }
+  return { ok: updated.ok, task: updated.task, releases, error: updated.error };
+}
+
+export function blockSwarmTask(projectRoot, taskId, options = {}) {
+  const task = findTask(projectRoot, taskId);
+  if (!task.ok) return task;
+  const message = String(options.message || '').trim();
+  if (!message) return { ok: false, error: 'message-required', task: task.task };
+  const updated = updateBlackboardTask(projectRoot, taskId, {
+    status: 'blocked',
+    blocked_at: new Date().toISOString(),
+    blocker: message,
+  });
+  if (updated.ok) {
+    appendBlackboardEvent(projectRoot, {
+      type: 'task.blocked',
+      actor: options.owner || task.task.owner || 'swarm',
+      task_id: taskId,
+      artifact_ids: task.task.artifact_ids || [],
+      message,
+    });
+  }
+  addBlackboardNote(projectRoot, {
+    kind: 'blocker',
+    author: options.owner || task.task.owner || 'swarm',
+    artifact: (task.task.artifact_ids || []).join(','),
+    message: `${taskId}: ${message}`,
+  });
+  return { ok: updated.ok, task: updated.task, error: updated.error };
+}
+
+export function readySwarmTask(projectRoot, taskId) {
+  const task = findTask(projectRoot, taskId);
+  if (!task.ok) return task;
+  if (task.task.status !== 'blocked') return { ok: false, error: 'task-not-blocked', task: task.task };
+  const updated = updateBlackboardTask(projectRoot, taskId, {
+    status: 'ready',
+    blocker: null,
+    unblocked_at: new Date().toISOString(),
+  });
+  if (updated.ok) {
+    appendBlackboardEvent(projectRoot, {
+      type: 'task.ready',
+      actor: 'ijfw',
+      task_id: taskId,
+      artifact_ids: task.task.artifact_ids || [],
+      message: `Ready ${taskId}`,
+    });
+  }
+  return { ok: updated.ok, task: updated.task, error: updated.error };
+}
+
+function buildTask(artifactId, artifact, rolesByName, activeClaims) {
+  if (!artifact) {
+    return {
+      artifact_id: artifactId,
+      owner: null,
+      reviewers: [],
+      paths: [],
+      refs: [],
+      verification: [],
+      blocked: true,
+      blocked_by: [],
+      reason: 'unknown-artifact',
+    };
+  }
+  const owner = rolesByName.get(artifact.owner);
+  const claimConflicts = activeClaims.filter((claim) => claimBlocksArtifact(claim, artifact));
+  const allowed_paths = artifact.paths || [];
+  const refs = artifact.refs || [];
+  return {
+    artifact_id: artifact.id,
+    artifact_type: artifact.type,
+    owner: artifact.owner,
+    owner_role_type: owner?.role_type || null,
+    reviewers: artifact.reviewers || [],
+    paths: allowed_paths,
+    refs,
+    verification: artifact.verification || [],
+    depends_on: artifact.depends_on || [],
+    claim_required: owner?.coordination?.claim_required !== false,
+    blocked: claimConflicts.length > 0,
+    blocked_by: claimConflicts,
+    reason: claimConflicts.length ? 'active-claim-conflict' : 'ready',
+  };
+}
+
+function normalizeMode(requested, tasks) {
+  if (tasks.some((task) => task.blocked)) return 'blocked';
+  if (requested === 'review') return 'review';
+  if (requested === 'parallel' && tasks.length > 1 && !tasksOverlap(tasks)) return 'parallel';
+  if (requested === 'parallel' && tasks.length <= 1) return 'parallel';
+  return 'sequential';
+}
+
+function explainWave(wave, tasks, mode) {
+  if (mode === 'blocked') return 'one or more artifacts already have active blackboard claims';
+  if (mode === 'review') return 'review wave from workflow manifest';
+  if (mode === 'parallel') return 'artifacts have no dependency or path overlap inside this wave';
+  if (wave.mode === 'parallel' && tasksOverlap(tasks)) return 'requested parallel, but artifact paths overlap';
+  return 'workflow requested sequential execution or contains dependent artifacts';
+}
+
+function summarizePlan(waves) {
+  const total = waves.reduce((n, wave) => n + wave.tasks.length, 0);
+  const blocked = waves.reduce((n, wave) => n + wave.tasks.filter((task) => task.blocked).length, 0);
+  const parallel = waves.filter((wave) => wave.mode === 'parallel').length;
+  const review = waves.filter((wave) => wave.mode === 'review').length;
+  return `${waves.length} wave(s), ${total} artifact task(s), ${parallel} parallel wave(s), ${review} review wave(s), ${blocked} blocked task(s).`;
+}
+
+function findWaveForArtifact(plan, artifactId) {
+  for (const wave of plan.waves) {
+    if (wave.artifact_ids.includes(artifactId)) return wave.id;
+  }
+  return null;
+}
+
+function findTask(projectRoot, taskId) {
+  const listed = listSwarmTasks(projectRoot);
+  const task = (listed.tasks || []).find((item) => item.id === taskId);
+  if (!task) return { ok: false, error: 'task-not-found' };
+  return { ok: true, task };
+}
+
+function firstBlockedDependency(projectRoot, task) {
+  const listed = listSwarmTasks(projectRoot);
+  const byId = new Map((listed.tasks || []).map((item) => [item.id, item]));
+  for (const depId of task.depends_on || []) {
+    const dep = byId.get(depId);
+    if (dep && dep.status !== 'done') return dep;
+  }
+  return null;
+}
+
+function tasksOverlap(tasks) {
+  for (let i = 0; i < tasks.length; i++) {
+    for (let j = i + 1; j < tasks.length; j++) {
+      if (pathsOverlap(tasks[i].paths, tasks[j].paths)) return true;
+      if ((tasks[i].depends_on || []).includes(tasks[j].artifact_id)) return true;
+      if ((tasks[j].depends_on || []).includes(tasks[i].artifact_id)) return true;
+    }
+  }
+  return false;
+}
+
+function claimBlocksArtifact(claim, artifact) {
+  if (claim.agent === artifact.owner) return false;
+  if (claim.artifact_id === artifact.id) return true;
+  return pathsOverlap(claim.paths || [], artifact.paths || []);
+}
+
+function pathsOverlap(a, b) {
+  if (!a?.length || !b?.length) return false;
+  for (const left of a) {
+    for (const right of b) {
+      if (left === right) return true;
+      const lp = prefixBeforeGlob(left);
+      const rp = prefixBeforeGlob(right);
+      if (lp && right.startsWith(lp)) return true;
+      if (rp && left.startsWith(rp)) return true;
+      if (globCouldMatch(left, right) || globCouldMatch(right, left)) return true;
+    }
+  }
+  return false;
+}
+
+function prefixBeforeGlob(pattern) {
+  const idx = pattern.search(/[*?[\]{}]/);
+  return idx === -1 ? pattern : pattern.slice(0, idx);
+}
+
+function globCouldMatch(glob, literal) {
+  if (!/[*?]/.test(glob)) return false;
+  const re = new RegExp(`^${globToRegex(glob)}$`);
+  return re.test(literal);
+}
+
+function globToRegex(glob) {
+  let out = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') { out += '.*'; i++; }
+      else out += '[^/]*';
+    } else if (c === '?') {
+      out += '[^/]';
+    } else if ('.+^$|()[]{}\\'.includes(c)) {
+      out += `\\${c}`;
+    } else {
+      out += c;
+    }
+  }
+  return out;
+}

package/src/swarm/review.js

@@ -0,0 +1,136 @@
+// Review task materialization for swarm lifecycle.
+//
+// This sidecar is dependency-free and intentionally does not write to the
+// blackboard. CLI integration can decide when to persist these task records.
+
+const DONE_STATUSES = new Set(['done']);
+
+export function deriveReviewTasks(source = {}, options = {}) {
+  const normalized = normalizeSource(source, options);
+  const tasks = [];
+
+  for (const wave of normalized.waves) {
+    for (const artifactId of wave.artifact_ids || []) {
+      const artifact = normalized.artifactsById.get(artifactId);
+      if (!artifact) continue;
+
+      const reviewers = Array.isArray(artifact.reviewers) ? artifact.reviewers : [];
+      for (const reviewer of reviewers) {
+        const implementationTaskId = swarmTaskId(wave.id, artifact.id);
+        const implementationTask = normalized.implementationTasksById.get(implementationTaskId);
+        const dependencyKnown = implementationTask != null;
+        const dependencyDone = !dependencyKnown || DONE_STATUSES.has(implementationTask.status);
+        const reviewCriteria = criteriaForReviewer(normalized.rolesByName.get(reviewer), artifact);
+
+        tasks.push({
+          id: `review:${wave.id}:${artifact.id}:${reviewer}`,
+          title: `${reviewer}: review ${artifact.id}`,
+          status: dependencyDone ? 'ready' : 'blocked',
+          wave_id: wave.id,
+          wave_mode: 'review',
+          artifact_ids: [artifact.id],
+          owner: reviewer,
+          reviewers: [],
+          paths: artifact.paths || [],
+          refs: artifact.refs || [],
+          depends_on: [implementationTaskId],
+          verification: artifact.verification || [],
+          review_criteria: reviewCriteria,
+          blocked_by: dependencyDone ? [] : [{
+            task_id: implementationTaskId,
+            status: implementationTask.status,
+          }],
+        });
+      }
+    }
+  }
+
+  return tasks;
+}
+
+function normalizeSource(source, options) {
+  const sourceTasks = Array.isArray(source) ? source : source.tasks;
+  const plan = source.plan || options.plan || (Array.isArray(source.waves) ? source : null);
+  const implementationTasks = sourceTasks || options.tasks || [];
+  const workflow = source.workflow || options.workflow || planToWorkflow(plan) || tasksToWorkflow(implementationTasks);
+  const charter = source.charter || options.charter || null;
+
+  return {
+    waves: workflow?.waves || [],
+    artifactsById: new Map((workflow?.artifacts || []).map((artifact) => [artifact.id, artifact])),
+    rolesByName: new Map((charter?.roles || []).map((role) => [role.name, role])),
+    implementationTasksById: new Map(implementationTasks.map((task) => [task.id, task])),
+  };
+}
+
+function planToWorkflow(plan) {
+  if (!plan?.ok || !Array.isArray(plan.waves)) return null;
+
+  const artifacts = [];
+  const waves = plan.waves.map((wave) => {
+    for (const task of wave.tasks || []) {
+      artifacts.push({
+        id: task.artifact_id,
+        type: task.artifact_type,
+        paths: task.paths || [],
+        refs: task.refs || [],
+        owner: task.owner,
+        reviewers: task.reviewers || [],
+        depends_on: task.depends_on || [],
+        verification: task.verification || [],
+      });
+    }
+    return {
+      id: wave.id,
+      mode: wave.mode,
+      artifact_ids: wave.artifact_ids || [],
+    };
+  });
+
+  return { artifacts, waves };
+}
+
+function tasksToWorkflow(tasks) {
+  if (!Array.isArray(tasks) || tasks.length === 0) return null;
+
+  const artifacts = [];
+  const wavesById = new Map();
+  for (const task of tasks) {
+    const waveId = task.wave_id;
+    if (!waveId || !Array.isArray(task.artifact_ids)) continue;
+    if (!wavesById.has(waveId)) {
+      wavesById.set(waveId, {
+        id: waveId,
+        mode: task.wave_mode || 'parallel',
+        artifact_ids: [],
+      });
+    }
+
+    const wave = wavesById.get(waveId);
+    for (const artifactId of task.artifact_ids) {
+      if (!wave.artifact_ids.includes(artifactId)) wave.artifact_ids.push(artifactId);
+      artifacts.push({
+        id: artifactId,
+        type: task.artifact_type,
+        paths: task.paths || [],
+        refs: task.refs || [],
+        owner: task.owner,
+        reviewers: task.reviewers || [],
+        depends_on: task.depends_on || [],
+        verification: task.verification || [],
+      });
+    }
+  }
+
+  return { artifacts, waves: Array.from(wavesById.values()) };
+}
+
+function criteriaForReviewer(role, artifact) {
+  if (!role || !Array.isArray(role.reviews)) return [];
+  const match = role.reviews.find((review) => review.artifact_type === artifact.type);
+  return match?.criteria || [];
+}
+
+function swarmTaskId(waveId, artifactId) {
+  return `swarm:${waveId}:${artifactId}`;
+}