@worca/app 1.0.0 → 1.2.0-rc.1

package/src/core/channels.mjs

@@ -1,302 +0,0 @@
-// src/core/channels.mjs
-// Typed channel vocabulary + the dispatch-time binder. Pure: the only IO is the
-// path STRINGS it computes via artifacts.mjs (no reads/writes). Replaces the
-// role-coupled _nodeIo/_afterNode switch with data-driven channel wiring.
-
-import { join } from 'node:path';
-import { planPath, reviewPath } from './artifacts.mjs';
-
-/** The closed set of channel ids (single source; imported by registry + validator).
- *  `workspace` (M3) is a read-only metadata channel carrying the frozen workspace
- *  description + member set; it is seeded once and never re-published (CONV-6). */
-export const CHANNEL_IDS = ['userPrompt', 'plan', 'review', 'checklist', 'code', 'workspace', 'clarify', 'decomposition'];
-
-/** Channels the dispatcher pre-seeds WITH VALUES on the bus at run start
- *  (orchestrator.mjs _dispatch bus literal): userPrompt IS the prompt,
- *  plan/checklist get default destinations, code is the standing worktree.
- *  The bus literal also carries workspace (metadata or null) and clarify/
- *  decomposition seeded as null — those are deliberately NOT listed here so the
- *  validator keeps warning when they are consumed with no upstream producer
- *  (current behavior). Single source for the validator's reachability pass —
- *  keep in sync with the _dispatch bus literal. */
-export const PRESEEDED_CHANNELS = ['userPrompt', 'plan', 'checklist', 'code'];
-
-/**
- * Mint the concrete OUTPUT handle for a channel the node produces. This is the
- * relocated output half of the old _nodeIo switch; paths are byte-identical so
- * history/state.json/MOCK markers do not move.
- * @param {string} channel
- * @param {{projectDir,pipelineDir,baseName,datePrefix,cycle,key?}} ctx
- */
-export function allocate(channel, ctx) {
-  const { projectDir, pipelineDir, baseName, datePrefix, cycle, key, workspaceKey } = ctx;
-  switch (channel) {
-    case 'plan': {
-      // The planner is cycle-aware so a plan-review -> planner loop writes a fresh
-      // -vN on each replan instead of clobbering v1 (cycle is 1 on the first pass,
-      // so v1 has NO -v suffix, matching today's seeded io.planPath). The refiner
-      // versions up to cycle+1 (a self-loop never produces v1). workspaceKey (when
-      // present) routes the unified plan to the workspace store; absent it is byte-
-      // identical to the single-project path.
-      const version = key === 'planner' ? cycle : cycle + 1;
-      return { kind: 'artifact', path: planPath(projectDir, baseName, version, datePrefix, workspaceKey) };
-    }
-    case 'review': {
-      // Review json basename differs by producing role (keeps existing filenames).
-      // A CUSTOM verifier key gets its own `<key>-review` basename so it can never
-      // clobber the built-in reviewer's impl-review files.
-      const k = key || 'reviewer';
-      const BESPOKE_BASE = {
-        reviewer: 'impl-review',
-        refiner: 'refine-review',
-        manualWebUiTesting: 'webui-review',
-        planReviewer: 'plan-review',
-        workspaceReviewer: 'ws-review',
-      };
-      let base = BESPOKE_BASE[k] || `${k}-review`;
-      // A custom key like "impl" would mint impl-review-* and clobber the built-in
-      // reviewer's files AND its DB verdict (reviewKind upsert); divert it.
-      if (!BESPOKE_BASE[k] && Object.values(BESPOKE_BASE).includes(base)) base = `${k}-agent-review`;
-      // ▲ C2: the refiner emits ONLY a json verdict (its md is null => private to its
-      // self-loop). Every other verifier carries a review md so publish() folds it
-      // onto the shared `review` channel its loop target consumes. workspaceKey routes
-      // the review md to the workspace store (the json stays per-cycle in the pipeline
-      // dir, store-root independent); absent it is byte-identical. Custom verifiers
-      // keep their md pipeline-dir-local (like webui-review).
-      const mdPath = k === 'refiner'
-        ? null
-        : k === 'manualWebUiTesting'
-          ? join(pipelineDir, `webui-review-cycle${cycle}.md`)
-          : k === 'planReviewer'
-            ? reviewPath(projectDir, baseName, datePrefix, 'plan-review', workspaceKey)
-            : k === 'workspaceReviewer'
-              ? reviewPath(projectDir, baseName, datePrefix, 'ws-review', workspaceKey)
-              : k === 'reviewer'
-                ? reviewPath(projectDir, baseName, datePrefix, 'impl-review', workspaceKey)
-                : join(pipelineDir, `${base}-cycle${cycle}.md`);
-      return { kind: 'review', mdPath, jsonPath: join(pipelineDir, `${base}-cycle${cycle}.json`), reviewKind: base };
-    }
-    case 'checklist':
-      return { kind: 'artifact', path: join(pipelineDir, 'manual-tests-checklist.md') };
-    case 'code':
-      return { kind: 'worktree' }; // standing channel; nothing to allocate
-    case 'workspace':
-      // Read-only metadata handle: the frozen workspace description snapshot. The
-      // member set + description are seeded onto the bus directly by the orchestrator
-      // (this just names the on-disk path of the frozen snapshot).
-      return { kind: 'metadata', path: join(pipelineDir, 'workspace-description.md') };
-    case 'decomposition':
-      // The decomposer writes decomposition.json (phase->task index) into the run dir,
-      // alongside a tasks/ subdir of self-contained task markdown files.
-      return { kind: 'artifact', path: join(pipelineDir, 'decomposition.json') };
-    case 'clarify':
-      // The clarify agent writes clarify.json into the pipeline dir as scratch; the
-      // DB clarify row is authoritative. Same path the legacy pre-step used.
-      return { kind: 'clarify', path: join(pipelineDir, 'clarify.json') };
-    default: {
-      // Open vocabulary: any custom channel allocates a generic pipeline-dir
-      // artifact. A registry channelDef (threaded via ctx.channelDefs) overrides
-      // kind (md|json) and filename; absent a def the channel defaults to
-      // markdown <id>.md. Loop re-runs suffix -cycle<N> so a rewind never
-      // clobbers an earlier cycle's output.
-      const def = (ctx.channelDefs && ctx.channelDefs[channel]) || null;
-      const ext = def?.kind === 'json' ? 'json' : 'md';
-      const stem = String(def?.filename || `${channel}.${ext}`).replace(/\.(md|json)$/i, '');
-      const name = Number(cycle) > 1 ? `${stem}-cycle${cycle}.${ext}` : `${stem}.${ext}`;
-      return { kind: 'artifact', path: join(pipelineDir, name), channel };
-    }
-  }
-}
-
-/**
- * Resolve a node's inputs from the bus (latest-writer-wins). Required channels that
- * are null still pass through (the agent/mock proceeds, e.g. a pre-seeded but
- * unwritten plan path). Optional channels that are null are omitted entirely.
- */
-export function bindInputs(consumes, optionalConsumes, bus) {
-  const optional = new Set(optionalConsumes || []);
-  const inputs = {};
-  for (const c of consumes || []) {
-    const v = bus[c];
-    if (v == null && optional.has(c)) continue; // omit absent optional channel
-    inputs[c] = v;
-  }
-  return inputs;
-}
-
-/**
- * Fold a node's result back onto the bus for each produced channel, in node order.
- * Clearing `review` on a `code` publish fixes the sticky fix-mode bug: a later
- * implementer no longer sees a stale review.
- */
-export function publish(produces, result, outputs, bus) {
-  if (!result) return;
-  for (const c of produces || []) {
-    if (c === 'plan') {
-      const path = result.outPlanPath || result.planPath || outputs.plan?.path;
-      if (path) bus.plan = { kind: 'artifact', path };
-    } else if (c === 'review') {
-      // ▲ C2: only a review carrying an md (reviewer / manualWebUiTesting) is shared.
-      // The refiner's md-less verdict stays private to its self-loop (read from the
-      // results array by _reviewOf, never the bus), so it can't flip a later
-      // implementer into `fix` mode.
-      const mdPath = result.reviewMdPath ?? outputs.review?.mdPath;
-      if (!mdPath) continue;
-      bus.review = { kind: 'review', mdPath, jsonPath: outputs.review?.jsonPath, verdict: result.review, reviewKind: outputs.review?.reviewKind };
-    } else if (c === 'checklist') {
-      const path = result.checklistPath || outputs.checklist?.path;
-      if (path) bus.checklist = { kind: 'artifact', path };
-    } else if (c === 'code') {
-      bus.review = null; // implementer superseded any pending review (fix-mode reset)
-    } else if (c === 'workspace') {
-      // Read-only metadata: seeded once by the orchestrator, NEVER re-published
-      // (CONV-6: the frozen per-step snapshot must not change mid-run). No-op.
-    } else if (c === 'clarify') {
-      // The clarify node carries questions (from the agent) + answers (from the
-      // interactive gate) in its result; fold both onto the bus so the planner reads
-      // inputs.clarify.answers.
-      bus.clarify = {
-        kind: 'clarify',
-        path: outputs.clarify?.path,
-        questions: result.questions || [],
-        answers: result.answers || [],
-      };
-    } else if (c === 'decomposition') {
-      // Fold the decomposer's parsed phases onto the bus so _runStep's implement
-      // step can fan out one implementer per task.
-      const path = result.decompositionPath || outputs.decomposition?.path;
-      bus.decomposition = {
-        kind: 'artifact',
-        path: path || null,
-        phases: Array.isArray(result.decomposition?.phases) ? result.decomposition.phases : [],
-      };
-    } else {
-      // Open vocabulary: a custom channel folds its allocated artifact handle onto
-      // the bus (latest-writer-wins), mirroring plan/checklist.
-      const path = outputs?.[c]?.path;
-      if (path) bus[c] = { kind: 'artifact', path };
-    }
-  }
-}
-
-/**
- * Adapter: flatten typed inputs/outputs into the EXACT field names the phases.mjs
- * runners already read (verified against runners.mjs), so runners.mjs/phases.mjs and
- * the runner/dispatcher tests need ZERO changes. This is one of two role switches
- * (the other is runners.mjs's producer/verifier); it names fields, it does not
- * compute data flow.
- */
-export function legacyFields(node, inputs, outputs, cycle, baseName) {
-  const fields = legacyRoleFields(node, inputs, outputs, cycle, baseName);
-  // Workspace runs: surface the read-only metadata channel (description + member
-  // set) onto the flattened ctx so phases.mjs runners read ctx.workspace. Absent
-  // the channel (every single-project node) the field is never added, so the ctx
-  // shape stays byte-identical.
-  if (inputs && inputs.workspace) fields.workspace = inputs.workspace;
-  return fields;
-}
-
-/** Per-role field naming (the original legacyFields body). */
-function legacyRoleFields(node, inputs, outputs, cycle, baseName) {
-  switch (node.key) {
-    case 'planner':
-      // reviewPath is set only when a review is bound (a plan-review -> planner
-      // rewind), which switches runPlannerPlan into its cold-replan branch.
-      return { planFilePath: outputs.plan?.path, baseName, answers: inputs.clarify?.answers || inputs.userPrompt?.answers || [], reviewPath: inputs.review?.mdPath };
-    case 'refiner':
-      return { inPlanPath: inputs.plan?.path, outPlanPath: outputs.plan?.path, reviewJsonPath: outputs.review?.jsonPath, cycle };
-    case 'decomposer':
-      return { planPath: inputs.plan?.path, decompositionPath: outputs.decomposition?.path };
-    case 'implementer':
-      // The implementer fixes CODE reviews (impl-review / webui-review). A plan-review
-      // left on the shared `review` bus by a planReviewer -> planner loop is NOT for the
-      // implementer (it bounces to the planner), so it must not flip a first-pass
-      // implementer into fix mode. Discriminate by review provenance (reviewKind), not
-      // cycle — a linear `... -> reviewer -> implementer` forward edge legitimately fixes
-      // a code review at cycle 1 (see saved-pipeline-parity).
-      return { planPath: inputs.plan?.path, reviewPath: inputs.review?.mdPath, mode: (inputs.review?.mdPath && inputs.review?.reviewKind !== 'plan-review') ? 'fix' : 'implement', cycle };
-    case 'planReviewer':
-      return { planPath: inputs.plan?.path, reviewMdPath: outputs.review?.mdPath, reviewJsonPath: outputs.review?.jsonPath, cycle };
-    case 'reviewer':
-      return { planPath: inputs.plan?.path, reviewMdPath: outputs.review?.mdPath, reviewJsonPath: outputs.review?.jsonPath, cycle };
-    case 'workspaceReviewer':
-      // Identical field shape to `reviewer` — the workspace synthesizer reads the
-      // same planPath/reviewMd/reviewJson/cycle and folds its merged verdict onto
-      // the shared `review` channel its implementer loop target consumes.
-      return { planPath: inputs.plan?.path, reviewMdPath: outputs.review?.mdPath, reviewJsonPath: outputs.review?.jsonPath, cycle };
-    case 'manualTestsChecklist':
-      return { planPath: inputs.plan?.path, checklistPath: outputs.checklist?.path };
-    case 'manualWebUiTesting':
-      return { checklistPath: inputs.checklist?.path, reviewMdPath: outputs.review?.mdPath, reviewJsonPath: outputs.review?.jsonPath, cycle };
-    default:
-      // Generic agents: no bespoke field names. The generic runners consume the
-      // typed inputs/outputs maps directly (same references _bindNodeIo spreads).
-      return { cycle, inputs, outputs };
-  }
-}
-
-/** Channels materializable from plain prompt text (markdown artifacts). userPrompt
- *  is already the prompt; code is the standing worktree; review is not pre-seeded and
- *  is optional for its only consumer — so none of those ever seed. */
-const SEEDABLE = new Set(['plan', 'checklist']);
-
-/**
- * Decide which materializable channels must be seeded from the user prompt because
- * the topology REQUIRES them before any step produces them (a pipeline that starts
- * mid-stream — implementer/refiner/... first). Mirrors the validator's step-ordered
- * reachability walk (workflow-validator.mjs:112-144) but returns the channels to fill
- * rather than warnings. Reads the channel spec carried on each resolved node, so no
- * registry argument is needed (resolveWorkflow already stamped consumes/produces).
- * @param {Array<Array<{key,consumes,optionalConsumes,produces}>>} steps
- * @returns {string[]} channel ids to seed (subset of SEEDABLE), in first-needed order
- */
-export function entrySeedChannels(steps) {
-  const seeded = new Set();
-  const produced = new Set();
-  for (const group of steps || []) {
-    for (const node of group || []) {
-      const optional = new Set(node?.optionalConsumes || []);
-      for (const c of node?.consumes || []) {
-        if (!SEEDABLE.has(c) || optional.has(c) || produced.has(c) || seeded.has(c)) continue;
-        seeded.add(c);
-      }
-    }
-    // Producers fold in AFTER the step (matches the validator's frozen-snapshot model),
-    // so a node that both consumes AND produces the same channel (the refiner) still
-    // triggers a seed at its own step.
-    for (const node of group || []) for (const c of node?.produces || []) produced.add(c);
-  }
-  return [...seeded];
-}
-
-/**
- * Render the `## Attached files` block listing each attachment by path + name.
- * Single source of truth shared by renderPromptArtifact (the seeded file body) and
- * phases.mjs taskHeader (the entry agent's inline header) so the two cannot drift.
- * Returns '' when there are no attachments.
- * @param {Array<{name:string,path:string}>} [extras]
- */
-export function renderAttachmentsBlock(extras = []) {
-  if (!Array.isArray(extras) || extras.length === 0) return '';
-  return (
-    `\n## Attached files\n\nThe user attached these files; read any that are relevant:\n\n` +
-    extras.map((e) => `- \`${e.path}\` (${e.name})`).join('\n') +
-    '\n'
-  );
-}
-
-/**
- * Render the markdown a seeded artifact channel holds: the user's request stands in
- * for the missing upstream artifact, with any attached files listed by path.
- * @param {string} promptText
- * @param {Array<{name:string,path:string}>} [extras]
- */
-export function renderPromptArtifact(promptText, extras = []) {
-  const body = (promptText || '').trim() || '(no prompt text)';
-  return (
-    `# Task (from the user prompt)\n\n` +
-    `No upstream agent produced this artifact, so the user's request below stands in for it.\n\n` +
-    `## Original request\n\n${body}\n` +
-    renderAttachmentsBlock(extras)
-  );
-}

package/src/core/runners.mjs

@@ -1,167 +0,0 @@
-// src/core/runners.mjs
-// Runner registry: maps an agent's runnerType -> a function the dispatcher calls.
-//
-// There are exactly two runner types (CONTRACT):
-//   - producer : generates artifacts/code (Plan, Refine, Implement, Manual Tests
-//                Checklist). Always returns status "ok"; may carry a review.
-//   - verifier : emits a protocol.mjs review verdict (Review, Manual web UI
-//                testing). status is "blocked" iff the review has blocking
-//                (critical/major) issues; eligible as a loopSource.
-//
-// Each runner receives the orchestrator's node ctx (see Orchestrator._nodeCtx):
-//   { projectDir, pipelineDir, taskPrompt, toolInstruction, agentPrompts,
-//     checkpointRef, signal, onEvent, claudeOpts:{model,effort,mock,...},
-//     node:{nodeId,key,runnerType,loopSource,...}, nodeId, stepIndex, cycle,
-//     ...per-call fields the dispatcher threads in (planPath, planFilePath,
-//        reviewMdPath, reviewJsonPath, outPlanPath, inPlanPath, baseName,
-//        answers, reviewPath, mode) }
-//
-// New agents pick an existing runnerType and need NO engine code; a genuinely new
-// behavior = add one branch (or one runner) here.
-
-import {
-  runPlannerPlan,
-  runRefiner,
-  runDecomposer,
-  runImplementer,
-  runReviewer,
-  runPlanReviewer,
-  runWorkspaceReviewer,
-  runManualTestsChecklist,
-  runManualWebUiTesting,
-  runGenericProducer,
-  runGenericVerifier,
-} from './phases.mjs';
-import { hasBlocking, blockingIssues } from './protocol.mjs';
-
-/** Normalize a protocol review into the RunnerResult verdict fields. */
-function verdict(review) {
-  return {
-    status: hasBlocking(review) ? 'blocked' : 'ok',
-    issues: blockingIssues(review),
-    review,
-    summary: review?.summary || '',
-  };
-}
-
-/**
- * producer — generates artifacts/code. Dispatches on the canonical agent key.
- * Always status "ok" (producers do not gate); the refiner additionally surfaces
- * its review so a workflow MAY hang a loop off it, but default routing does not.
- * @param {object} ctx node ctx from the orchestrator
- * @returns {Promise<{status:'ok', summary?:string, planPath?:string, outPlanPath?:string, review?:object}>}
- */
-async function producer(ctx) {
-  const key = ctx?.node?.key;
-  switch (key) {
-    case 'planner': {
-      const { planPath } = await runPlannerPlan(ctx, {
-        answers: ctx.answers || [],
-        planFilePath: ctx.planFilePath,
-        baseName: ctx.baseName,
-        reviewPath: ctx.reviewPath,
-      });
-      return { status: 'ok', planPath, summary: 'Plan written.' };
-    }
-    case 'refiner': {
-      const { outPlanPath, review } = await runRefiner(ctx, {
-        inPlanPath: ctx.inPlanPath,
-        outPlanPath: ctx.outPlanPath,
-        cycle: ctx.cycle,
-        reviewJsonPath: ctx.reviewJsonPath,
-      });
-      // A producer never blocks; expose the review (+ issues) for loop wiring.
-      return { status: 'ok', outPlanPath, review, issues: blockingIssues(review), summary: review?.summary || '' };
-    }
-    case 'decomposer': {
-      const { decompositionPath, decomposition } = await runDecomposer(ctx, {
-        planPath: ctx.planPath,
-        decompositionPath: ctx.decompositionPath,
-      });
-      return { status: 'ok', decompositionPath, decomposition, summary: 'Plan decomposed.' };
-    }
-    case 'implementer': {
-      const { summary } = await runImplementer(ctx, {
-        planPath: ctx.planPath,
-        reviewPath: ctx.reviewPath,
-        taskPath: ctx.node?.taskPath,
-        siblings: ctx.node?.siblings,
-        mode: ctx.mode || 'implement',
-      });
-      return { status: 'ok', summary };
-    }
-    case 'manualTestsChecklist': {
-      const { checklistPath, summary } = await runManualTestsChecklist(ctx, {
-        planPath: ctx.planPath,
-        checklistPath: ctx.checklistPath,
-      });
-      return { status: 'ok', checklistPath, summary };
-    }
-    default: {
-      // Generic branch: a metadata-declared agent runs with ZERO core edits.
-      const { summary } = await runGenericProducer(ctx);
-      return { status: 'ok', summary };
-    }
-  }
-}
-
-/**
- * verifier — emits a protocol review verdict. status "blocked" iff the review has
- * blocking issues. Eligible as a loopSource.
- * @param {object} ctx node ctx from the orchestrator
- * @returns {Promise<{status:'ok'|'blocked', issues:Array, review:object, summary:string}>}
- */
-async function verifier(ctx) {
-  const key = ctx?.node?.key;
-  switch (key) {
-    case 'reviewer': {
-      const { review } = await runReviewer(ctx, {
-        planPath: ctx.planPath,
-        reviewMdPath: ctx.reviewMdPath,
-        reviewJsonPath: ctx.reviewJsonPath,
-        cycle: ctx.cycle,
-      });
-      // CONV-5: thread the review markdown path so a loop rewind runs the implementer in `fix` mode.
-      return { ...verdict(review), reviewMdPath: ctx.reviewMdPath };
-    }
-    case 'planReviewer': {
-      const { review } = await runPlanReviewer(ctx, {
-        planPath: ctx.planPath,
-        reviewMdPath: ctx.reviewMdPath,
-        reviewJsonPath: ctx.reviewJsonPath,
-        cycle: ctx.cycle,
-      });
-      // Thread the review md path so a loop rewind to the planner reads the review.
-      return { ...verdict(review), reviewMdPath: ctx.reviewMdPath };
-    }
-    case 'workspaceReviewer': {
-      const { review } = await runWorkspaceReviewer(ctx, {
-        planPath: ctx.planPath,
-        reviewMdPath: ctx.reviewMdPath,
-        reviewJsonPath: ctx.reviewJsonPath,
-        cycle: ctx.cycle,
-      });
-      // CONV-5: thread the review markdown path so a loop rewind runs the implementer in `fix` mode.
-      return { ...verdict(review), reviewMdPath: ctx.reviewMdPath };
-    }
-    case 'manualWebUiTesting': {
-      const { review } = await runManualWebUiTesting(ctx, {
-        checklistPath: ctx.checklistPath,
-        reviewMdPath: ctx.reviewMdPath,
-        reviewJsonPath: ctx.reviewJsonPath,
-        cycle: ctx.cycle,
-      });
-      // CONV-5: thread the review markdown path (web-UI loop source → implementer fix mode).
-      return { ...verdict(review), reviewMdPath: ctx.reviewMdPath };
-    }
-    default: {
-      // Generic branch: a metadata-declared verifier emits the standard protocol
-      // verdict; thread the md path so a loop rewind reads the review (CONV-5).
-      const { review, reviewMdPath } = await runGenericVerifier(ctx);
-      return { ...verdict(review), reviewMdPath };
-    }
-  }
-}
-
-/** The runner registry: runnerType -> async (ctx) => RunnerResult. */
-export const runners = { producer, verifier };

package/src/core/workflow-validator.mjs

@@ -1,185 +0,0 @@
-// src/core/workflow-validator.mjs
-// Pure validator (imports only the channel constants from channels.mjs) for a
-// WorkflowTemplate against an agent registry. Collects ALL violations (does not
-// short-circuit) so the UI/API can show every problem at once. Returns
-// { ok, errors:string[], warnings:string[] } (warnings are soft: reachability/
-// governance/multi-producer hints that never set ok=false, so saved
-// topology-only pipelines stay valid).
-//
-// Rules (CONTRACT §workflow-validator):
-//   1. template is a non-null object with a non-empty steps array;
-//   2. no empty steps (every step has >= 1 node);
-//   3. every node has a non-blank string id, and ids are unique workflow-wide;
-//   4. every node.key exists in the registry;
-//   5. feedback from/to reference existing node ids;
-//   6. a feedback's target step index < its source step index
-//      (a same-node self-loop, from===to, is allowed; the forward graph is
-//       otherwise acyclic so only back-edges are legal feedbacks);
-//   7. feedback ids are unique.
-
-import { CHANNEL_IDS, PRESEEDED_CHANNELS } from './channels.mjs';
-
-/**
- * @param {object} tpl  WorkflowTemplate { steps:[[{id,key}]], feedbacks:[{id,from,to}] }
- * @param {Record<string,{key:string}>} registry  loadAgentRegistry() output
- * @returns {{ok:boolean, errors:string[], warnings:string[]}}
- */
-export function validateWorkflow(tpl, registry) {
-  const errors = [];
-  const reg = registry && typeof registry === 'object' ? registry : {};
-
-  if (!tpl || typeof tpl !== 'object' || !Array.isArray(tpl.steps)) {
-    return { ok: false, errors: ['workflow must be an object with a steps array'], warnings: [] };
-  }
-  if (tpl.steps.length === 0) {
-    errors.push('workflow must have at least one step');
-  }
-
-  // Pass 1: nodes — shape, unique ids, known keys. Build id -> stepIndex map.
-  const stepOfNode = new Map(); // nodeId -> step index
-  const seenIds = new Set();
-  for (let i = 0; i < tpl.steps.length; i++) {
-    const group = tpl.steps[i];
-    if (!Array.isArray(group) || group.length === 0) {
-      errors.push(`step ${i} is empty (a step must contain at least one node)`);
-      continue;
-    }
-    for (const node of group) {
-      if (!node || typeof node !== 'object') {
-        errors.push(`step ${i} contains a non-object node`);
-        continue;
-      }
-      const id = typeof node.id === 'string' ? node.id.trim() : '';
-      if (!id) {
-        errors.push(`step ${i} has a node with a missing or blank id`);
-        continue;
-      }
-      if (seenIds.has(id)) {
-        errors.push(`duplicate node id "${id}"`);
-      } else {
-        seenIds.add(id);
-        stepOfNode.set(id, i);
-      }
-      const key = typeof node.key === 'string' ? node.key.trim() : '';
-      if (!key) {
-        errors.push(`node "${id}" has a missing or blank key`);
-      } else if (!Object.prototype.hasOwnProperty.call(reg, key)) {
-        errors.push(`node "${id}" has key "${key}" which is not in the agent registry`);
-      }
-    }
-  }
-
-  // Pass 2: feedbacks — unique ids, endpoints exist, target precedes source.
-  const feedbacks = Array.isArray(tpl.feedbacks) ? tpl.feedbacks : [];
-  const seenFb = new Set();
-  for (const fb of feedbacks) {
-    if (!fb || typeof fb !== 'object') {
-      errors.push('feedbacks contains a non-object entry');
-      continue;
-    }
-    const fid = typeof fb.id === 'string' ? fb.id.trim() : '';
-    if (!fid) {
-      errors.push('a feedback has a missing or blank id');
-    } else if (seenFb.has(fid)) {
-      errors.push(`duplicate feedback id "${fid}"`);
-    } else {
-      seenFb.add(fid);
-    }
-    const from = typeof fb.from === 'string' ? fb.from.trim() : '';
-    const to = typeof fb.to === 'string' ? fb.to.trim() : '';
-    const hasFrom = stepOfNode.has(from);
-    const hasTo = stepOfNode.has(to);
-    if (!hasFrom) errors.push(`feedback "${fid || '?'}" from "${from}" does not exist`);
-    if (!hasTo) errors.push(`feedback "${fid || '?'}" to "${to}" does not exist`);
-    if (hasFrom && hasTo) {
-      const sFrom = stepOfNode.get(from);
-      const sTo = stepOfNode.get(to);
-      // A same-node self-loop (from === to) is legal (the refine loop). Otherwise
-      // the target step must strictly precede the source step (a back-edge).
-      if (from !== to && sTo >= sFrom) {
-        errors.push(
-          `feedback "${fid || '?'}" target step (${sTo}) must precede its source step (${sFrom})`,
-        );
-      }
-    }
-  }
-
-  // Pass 3: WARNINGS (never block saves, so existing topology-only pipelines stay
-  // valid). Forward order = step order.
-  const warnings = [];
-  // Pre-seeded channels (derived from channels.mjs — the dispatcher's bus literal)
-  // are always reachable and never warn.
-  const PRESEEDED = new Set(PRESEEDED_CHANNELS);
-  const NON_MULTIPLEXABLE = new Set(['code', 'plan']); // one producer per step
-  const produced = new Set();
-  for (let i = 0; i < tpl.steps.length; i++) {
-    const group = Array.isArray(tpl.steps[i]) ? tpl.steps[i] : [];
-    // (a) reachability: a required, non-pre-seeded channel must be produced earlier
-    for (const node of group) {
-      const meta = reg[node?.key] || {};
-      const optional = new Set(meta.optionalConsumes || []);
-      for (const c of meta.consumes || []) {
-        if (optional.has(c) || PRESEEDED.has(c) || produced.has(c)) continue;
-        warnings.push(`node "${node.id}" consumes "${c}" but no upstream step produces it`);
-      }
-    }
-    // (b) multi-producer (D2) + stale-sibling (D3): scan within the step
-    const stepProducers = new Map(); // channel -> count
-    for (const node of group) for (const c of (reg[node?.key]?.produces || [])) {
-      stepProducers.set(c, (stepProducers.get(c) || 0) + 1);
-    }
-    for (const [c, n] of stepProducers) {
-      if (n > 1 && NON_MULTIPLEXABLE.has(c)) {
-        warnings.push(`step ${i} has ${n} producers of "${c}" (only one producer per step is well-defined)`);
-      }
-    }
-    for (const node of group) {
-      const meta = reg[node?.key] || {};
-      const optional = new Set(meta.optionalConsumes || []);
-      for (const c of meta.consumes || []) {
-        // a channel produced ONLY by a same-step sibling is read stale (pre-step snapshot)
-        if (!optional.has(c) && !produced.has(c) && !PRESEEDED.has(c) && stepProducers.has(c)) {
-          warnings.push(`node "${node.id}" consumes "${c}" produced only by a same-step sibling; it reads the pre-step value`);
-        }
-      }
-    }
-    // commit this step's production AFTER the step (matches the frozen-snapshot model)
-    for (const [c] of stepProducers) produced.add(c);
-  }
-  // (d) custom-channel hygiene: a PRODUCED channel that is neither built-in nor
-  // declared by any registry channelDef silently defaults to a generic markdown
-  // artifact — surface that once per channel so a wizard/meta typo is visible.
-  const builtinChannels = new Set(CHANNEL_IDS);
-  const definedCustom = new Set();
-  for (const m of Object.values(reg)) {
-    for (const d of m?.channelDefs || []) if (d?.id) definedCustom.add(d.id);
-  }
-  const flaggedDefless = new Set();
-  for (const group of tpl.steps) {
-    for (const node of Array.isArray(group) ? group : []) {
-      for (const c of reg[node?.key]?.produces || []) {
-        if (builtinChannels.has(c) || definedCustom.has(c) || flaggedDefless.has(c)) continue;
-        flaggedDefless.add(c);
-        warnings.push(`custom channel "${c}" (produced by "${node.id}") has no channelDef; it defaults to markdown "${c}.md"`);
-      }
-    }
-  }
-  // (c) governance: every adjacent forward edge + every feedback edge must be allowed
-  const keyOf = new Map();
-  tpl.steps.forEach((g) => (Array.isArray(g) ? g : []).forEach((n) => keyOf.set(n.id, n.key)));
-  const allows = (fromKey, toKey) => {
-    const ct = reg[fromKey]?.connectsTo;
-    return ct === '*' || ct === undefined || !Array.isArray(ct) || ct.includes(toKey);
-  };
-  for (let i = 0; i < tpl.steps.length - 1; i++) {
-    for (const a of tpl.steps[i] || []) for (const b of tpl.steps[i + 1] || []) {
-      if (!allows(a.key, b.key)) warnings.push(`"${a.key}" is not allowed to connect to "${b.key}" (connectsTo)`);
-    }
-  }
-  for (const fb of Array.isArray(tpl.feedbacks) ? tpl.feedbacks : []) {
-    const fk = keyOf.get(fb?.from), tk = keyOf.get(fb?.to);
-    if (fk && tk && !allows(fk, tk)) warnings.push(`feedback "${fb.id || '?'}": "${fk}" is not allowed to connect to "${tk}" (connectsTo)`);
-  }
-
-  return { ok: errors.length === 0, errors, warnings };
-}