@really-knows-ai/foundry 3.3.8 → 3.4.0

package/dist/scripts/orchestrate-cycle.js

@@ -188,6 +188,71 @@ export function synthesizeStages({ cycleId, hasValidation, humanAppraise, assay
   return stages;
 }
 
+// ---------------------------------------------------------------------------
+// Dispatch-multi action constants and validators.
+// ---------------------------------------------------------------------------
+
+export const DISPATCH_MULTI_ACTION = 'dispatch_multi';
+
+/**
+ * Validate a dispatch_multi action object.
+ *
+ * Checks action type, tasks array shape, and each task's required fields.
+ * Returns undefined on success, a violation object on failure.
+ */
+function validString(value) {
+  return typeof value === 'string' && value.length > 0;
+}
+
+function checkActionType(action) {
+  if (!action || action.action !== DISPATCH_MULTI_ACTION) {
+    return violation(`action must be "${DISPATCH_MULTI_ACTION}"`, []);
+  }
+  return undefined;
+}
+
+function validateAllTasks(tasks) {
+  for (let i = 0; i < tasks.length; i++) {
+    const err = checkDispatchTask(tasks[i], i);
+    if (err) return err;
+  }
+  return undefined;
+}
+
+export function validateDispatchMulti(action) {
+  const typeErr = checkActionType(action);
+  if (typeErr) return typeErr;
+  if (!Array.isArray(action.tasks)) {
+    return violation('dispatch_multi tasks must be an array', []);
+  }
+  return validateAllTasks(action.tasks);
+}
+
+function checkDispatchTask(task, index) {
+  if (!validString(task.subagent_type)) {
+    return violation(`dispatch_multi tasks[${index}]: subagent_type must be a non-empty string`, []);
+  }
+  if (!validString(task.prompt)) {
+    return violation(`dispatch_multi tasks[${index}]: prompt must be a non-empty string`, []);
+  }
+  return undefined;
+}
+
+/**
+ * Build a dispatch_multi response object.
+ *
+ * Pure utility for constructing the action envelope expected by the
+ * orchestrate skill's LLM loop.
+ */
+export function buildDispatchMultiResponse(tasks, stage, cycle) {
+  return {
+    action: DISPATCH_MULTI_ACTION,
+    tasks,
+    stage,
+    cycle,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Dispatch prompt rendering (pure utility, used by handleSortResult and exported publicly).
 // ---------------------------------------------------------------------------

package/dist/scripts/orchestrate-phases.js

@@ -58,7 +58,7 @@ async function buildDispatchAction(route, model, token, ctx) {
   return { action: 'dispatch', stage: route, subagent_type: model, prompt: renderDispatchPrompt(makeDispatchPayload(route, ctx.cycleId, token, ctx.cwd, filePatterns)) };
 }
 
-function routeDispatch(route) {
+export function routeDispatch(route) {
   return typeof route === 'string' ? route.split(':')[0] : '';
 }
 
@@ -68,11 +68,18 @@ async function handleTerminalRoute(route, sortResult, ctx) {
   return violation(sortResult.details ?? 'sort returned violation');
 }
 
+function isTerminalRoute(route) {
+  return route === 'done' || route === 'blocked' || route === 'violation';
+}
+
 export async function handleSortResult(sortResult, ctx) {
   const { route, model, token } = sortResult;
-  if (route === 'done' || route === 'blocked' || route === 'violation') {
+  if (isTerminalRoute(route)) {
     return handleTerminalRoute(route, sortResult, ctx);
   }
+  if (routeDispatch(route) === 'quench' || routeDispatch(route) === 'appraise') {
+    return violation(`${routeDispatch(route)} route reached handleSortResult — should have been handled upstream in orchestrate.js`);
+  }
   if (routeDispatch(route) === 'human-appraise') {
     return humanAppraiseAction(route, token, ctx.cycleId, ctx.io);
   }

package/dist/scripts/orchestrate.js

@@ -4,7 +4,8 @@
 
 import { runSort } from './sort.js';
 import { parseFrontmatter } from './lib/workfile.js';
-import { readActiveStage, readLastStage } from './lib/state.js';
+import { readActiveStage, readLastStage, writeActiveStage, clearActiveStage } from './lib/state.js';
+import { stageBaseOf } from './lib/stage-guard.js';
 import { ulid as defaultUlid } from './lib/ulid.js';
 import {
   findCycleOutputArtefact,
@@ -14,15 +15,27 @@ import {
   synthesizeStages,
   violation,
   computeOpenFeedback,
+  markArtefactBlocked,
+  DISPATCH_MULTI_ACTION,
+  validateDispatchMulti,
+  buildDispatchMultiResponse,
 } from './orchestrate-cycle.js';
 import {
   handleSortResult,
   setupWorkfile,
   finaliseStage,
   handleViolation,
+  routeDispatch,
 } from './orchestrate-phases.js';
+import { runQuench } from './quench-module.js';
+import { gatherAppraiseContext, consolidateAppraise } from './appraise-module.js';
+import { openFeedbackStore } from './lib/feedback-store.js';
 
-export { renderDispatchPrompt, synthesizeStages, computeOpenFeedback };
+export {
+  renderDispatchPrompt, synthesizeStages, computeOpenFeedback,
+  DISPATCH_MULTI_ACTION, validateDispatchMulti, buildDispatchMultiResponse,
+};
+export { gatherAppraiseContext, consolidateAppraise };
 export { findCycleOutputArtefact, readCycleTargets, readForgeFilePatterns };
 export { handleSortResult as __handleSortResultForTest };
 
@@ -38,28 +51,19 @@ export function needsSetup(workMdContent) {
 // ---------------------------------------------------------------------------
 
 function guardNoWorkMd(io) {
-  if (!io.exists('WORK.md')) {
-    return violation('no WORK.md; flow skill must create it first');
-  }
+  if (!io.exists('WORK.md')) return violation('no WORK.md; flow skill must create it first');
   return null;
 }
 
 function guardMissingCycleId(io) {
   const workContent = io.readFile('WORK.md');
   const fm = parseFrontmatter(workContent);
-  if (!fm.cycle) {
-    return violation('WORK.md frontmatter missing cycle field', ['WORK.md']);
-  }
+  if (!fm.cycle) return violation('WORK.md frontmatter missing cycle field', ['WORK.md']);
   return { cycleId: fm.cycle, workContent };
 }
 
 function guardSetupInconsistent(lastResult) {
-  if (lastResult) {
-    return violation(
-      'inconsistent state: lastResult provided but WORK.md still needs setup',
-      ['WORK.md'],
-    );
-  }
+  if (lastResult) return violation('inconsistent state: lastResult provided but WORK.md still needs setup', ['WORK.md']);
   return null;
 }
 
@@ -75,18 +79,44 @@ function guardOrphanedStage(activeStage, lastResult) {
 }
 
 function guardMissingLastStage(lastStage) {
-  if (!lastStage) {
-    return violation('lastResult provided but no last stage recorded — orphaned state');
-  }
+  if (!lastStage) return violation('lastResult provided but no last stage recorded — orphaned state');
   return null;
 }
 
+function checkLastResultsConflict(args) {
+  if (args.lastResult !== undefined && args.lastResults !== undefined) return violation('lastResult and lastResults are mutually exclusive');
+  return null;
+}
+
+function checkLastResultsShape(args) {
+  if (args.lastResults === undefined) return null;
+  if (!Array.isArray(args.lastResults)) return violation('lastResults must be an array');
+  return null;
+}
+
+function isDuplicateConsolidation(lastStage, activeStage) {
+  return lastStage && lastStage.stage === activeStage.stage;
+}
+
+function checkLastResultsStageContext(args, activeStage, lastStage) {
+  if (args.lastResults === undefined) return null;
+  if (!activeStage) return violation('lastResults provided but no active stage exists');
+  if (stageBaseOf(activeStage.stage) !== 'appraise') return violation(`lastResults provided but active stage "${activeStage.stage}" is not an appraise stage`);
+  if (isDuplicateConsolidation(lastStage, activeStage)) return violation(`duplicate lastResults: consolidation already completed for this appraise stage "${activeStage.stage}"`);
+  return null;
+}
+
+function guardLastResults(args, activeStage, lastStage) {
+  return checkLastResultsConflict(args)
+    ?? checkLastResultsShape(args)
+    ?? checkLastResultsStageContext(args, activeStage, lastStage);
+}
+
 function buildSortArgs(args, now) {
   return {
-    cycleDef: args.cycleDef ?? null,
-    mint: args.mint,
+    cycleDef: args.cycleDef ?? null, mint: args.mint,
     now: typeof now === 'function' ? now() : now,
-    ulid: args.ulid ?? defaultUlid,
+    ulid: args.ulid ?? defaultUlid, defaultModel: args.defaultModel,
   };
 }
 
@@ -95,40 +125,141 @@ function buildSortContext(cycleId, args, io) {
 }
 
 function buildSetupArgs(cycleResult, args, io) {
-  return {
-    cycleId: cycleResult.cycleId,
-    workContent: cycleResult.workContent,
-    io,
-    git: args.git,
-    foundryDir: 'foundry',
-  };
+  return { cycleId: cycleResult.cycleId, workContent: cycleResult.workContent, io, git: args.git, foundryDir: 'foundry' };
 }
 
 function isViolation(result) {
   return result && result.action === 'violation';
 }
 
+function buildFinalizeWrapper(cycleId, args, io) {
+  return ({ lastStage, activeStage }) =>
+    finaliseStage({ lastStage, activeStage, cycleId, io, finalize: args.finalize, git: args.git });
+}
+
+function buildFeedback(cycleId, stageId, io) {
+  return {
+    add: (item) => {
+      const store = openFeedbackStore('WORK.feedback.yaml', io);
+      return store.add({ file: item.file, tag: item.tag, text: item.text, source: stageId, cycle: cycleId });
+    },
+    list: (query) => {
+      const store = openFeedbackStore('WORK.feedback.yaml', io);
+      let items = store.list();
+      if (query?.file) items = items.filter(it => it.file === query.file);
+      if (query?.source) items = items.filter(it => it.source === query.source);
+      return items;
+    },
+    resolve: (id, decision, reason) => {
+      const store = openFeedbackStore('WORK.feedback.yaml', io);
+      const target = decision === 'approved' ? 'resolved' : 'rejected';
+      return store.transition({ id, target, stage: stageId, cycle: cycleId });
+    },
+  };
+}
+
+function buildQuenchContext(cycleId, args, io) {
+  const stageId = `quench:${cycleId}`;
+  return { cycleId, stageId, io, git: args.git, finalize: buildFinalizeWrapper(cycleId, args, io),
+    now: args.now, ulid: args.ulid, mint: args.mint, foundryDir: 'foundry', defaultModel: args.defaultModel,
+    feedback: buildFeedback(cycleId, stageId, io) };
+}
+
+function buildAppraiseCtx(cycleId, args, io) {
+  const stageId = `appraise:${cycleId}`;
+  return { cycleId, io, git: args.git, finalize: buildFinalizeWrapper(cycleId, args, io),
+    foundryDir: 'foundry', defaultModel: args.defaultModel,
+    activeStage: readActiveStage(io), lastStage: readLastStage(io),
+    feedback: buildFeedback(cycleId, stageId, io) };
+}
+
+function resolveBaseSha(io) {
+  try {
+    const sha = io.exec(['git', 'rev-parse', 'HEAD']);
+    if (sha && typeof sha === 'string' && sha.trim()) return sha.trim();
+  } catch { /* use default */ }
+  return '0000000';
+}
+
+function writeStageRecord(io, cycleId, route) {
+  writeActiveStage(io, { cycle: cycleId, stage: `${route}`, token: null, baseSha: resolveBaseSha(io) });
+}
+
+async function handleQuenchRoute(sortResult, preCheck, args, io) {
+  writeStageRecord(io, preCheck.cycleId, sortResult.route);
+  const quenchCtx = buildQuenchContext(preCheck.cycleId, args, io);
+  const quenchResult = await runQuench(quenchCtx);
+  if (quenchResult.ok === false) return violation(quenchResult.error || 'quench failed');
+  const nextSort = runSort(buildSortArgs(args, args.now ?? Date.now), io);
+  return dispatchByRoute(nextSort, args, preCheck, io);
+}
+
+async function handleAppraiseGatherRoute(sortResult, preCheck, args, io) {
+  writeStageRecord(io, preCheck.cycleId, sortResult.route);
+  const result = await gatherAppraiseContext(buildAppraiseCtx(preCheck.cycleId, args, io));
+  if (result.action === 'violation') { clearActiveStage(io); return result; }
+  if (!result.tasks || result.tasks.length === 0) {
+    // No appraisers/artefacts — consolidate with empty results to advance
+    return handleAppraiseConsolidateRoute(sortResult, preCheck, { ...args, lastResults: [] }, io);
+  }
+  const validationErr = validateDispatchMulti(result);
+  if (validationErr) return validationErr;
+  return result;
+}
+
+async function handleAppraiseConsolidateRoute(sortResult, preCheck, args, io) {
+  const ctx = buildAppraiseCtx(preCheck.cycleId, args, io);
+  const result = await consolidateAppraise(ctx, args.lastResults);
+  if (result.action === 'violation') {
+    markArtefactBlocked(preCheck.cycleId, io);
+    clearActiveStage(io);
+    return result;
+  }
+  if (!result.ok) return violation(result.error || 'appraise consolidation failed');
+  const nextSort = runSort(buildSortArgs(args, args.now ?? Date.now), io);
+  return dispatchByRoute(nextSort, args, preCheck, io);
+}
+
+async function dispatchByRoute(sortResult, args, preCheck, io) {
+  const base = routeDispatch(sortResult.route);
+  if (base === 'quench') return handleQuenchRoute(sortResult, preCheck, args, io);
+  if (base === 'appraise') {
+    return args.lastResults
+      ? handleAppraiseConsolidateRoute(sortResult, preCheck, args, io)
+      : handleAppraiseGatherRoute(sortResult, preCheck, args, io);
+  }
+  return handleSortResult(sortResult, buildSortContext(preCheck.cycleId, args, io));
+}
+
 export async function runOrchestrate(args, io) {
   const preCheck = runPreChecks(io);
   if (preCheck.error) return preCheck.error;
   return runOrchestrateFlow(preCheck, args, io);
 }
 
+function checkFlowGuards(args, activeStage, lastStage) {
+  const lastResultsErr = guardLastResults(args, activeStage, lastStage);
+  if (lastResultsErr) return lastResultsErr;
+  // Only flag orphaned stage when not on consolidation path (lastResults path has activeStage but no lastResult)
+  if (args.lastResults === undefined) return guardOrphanedStage(activeStage, args.lastResult);
+  return null;
+}
+
 async function runOrchestrateFlow(preCheck, args, io) {
   const setupResult = await runSetupIfNeeded(preCheck, args, io);
   if (isViolation(setupResult)) return setupResult;
-
   const activeStage = readActiveStage(io);
   const lastStage = readLastStage(io);
-
-  const orphanErr = guardOrphanedStage(activeStage, args.lastResult);
-  if (orphanErr) return orphanErr;
-
+  const guardErr = checkFlowGuards(args, activeStage, lastStage);
+  if (guardErr) return guardErr;
   const postDispatchResult = await runPostDispatch(args, activeStage, lastStage, preCheck.cycleId, io);
   if (isViolation(postDispatchResult)) return postDispatchResult;
+  return runSortAndDispatch(args, preCheck, io);
+}
 
+async function runSortAndDispatch(args, preCheck, io) {
   const sortResult = runSort(buildSortArgs(args, args.now ?? Date.now), io);
-  return handleSortResult(sortResult, buildSortContext(preCheck.cycleId, args, io));
+  return dispatchByRoute(sortResult, args, preCheck, io);
 }
 
 function runPreChecks(io) {
@@ -142,8 +273,7 @@ function runPreChecks(io) {
 async function runSetupIfNeeded(preCheck, args, io) {
   if (!needsSetup(preCheck.workContent)) return null;
   const err = guardSetupInconsistent(args.lastResult);
-  if (err) return err;
-  return setupWorkfile(buildSetupArgs(preCheck, args, io));
+  return err || setupWorkfile(buildSetupArgs(preCheck, args, io));
 }
 
 async function runPostDispatch(args, activeStage, lastStage, cycleId, io) {
@@ -151,13 +281,7 @@ async function runPostDispatch(args, activeStage, lastStage, cycleId, io) {
   if (args.lastResult.ok === false) {
     return handleViolation({ lastResult: args.lastResult, activeStage, lastStage, cycleId, io });
   }
-
   const stageErr = guardMissingLastStage(lastStage);
-  if (stageErr) return stageErr;
-
-  return finaliseStage({
-    lastStage, activeStage, cycleId, io,
-    finalize: args.finalize ?? null,
-    git: args.git,
-  });
+  const finaliseArgs = { lastStage, activeStage, cycleId, io, finalize: args.finalize ?? null, git: args.git };
+  return stageErr || finaliseStage(finaliseArgs);
 }

package/dist/scripts/quench-module.js

@@ -0,0 +1,153 @@
+/**
+ * Quench module — deterministic validation run entirely within the orchestrator.
+ *
+ * The module runs validators for each draft artefact in the current cycle,
+ * posts feedback for each validation item, resolves prior quench feedback,
+ * and finalises the stage. No LLM involvement.
+ */
+
+import { readActiveStage } from './lib/state.js';
+import { getArtefactsForCycle, setArtefactStatus } from './lib/artefacts.js';
+import { performValidation } from './lib/validation.js';
+
+/**
+ * Run quench (deterministic validation) for a cycle.
+ *
+ * @param {object} ctx - Context object with io, feedback, finalize, etc.
+ * @returns {Promise<{ok: boolean, summary?: string, error?: string}>}
+ */
+export async function runQuench(ctx) {
+  const activeStageRecord = readActiveStage(ctx.io);
+  if (!activeStageRecord) {
+    return { ok: false, error: 'No active stage found' };
+  }
+
+  const artefacts = getArtefactsForCycle(ctx.cycleId, ctx.io);
+
+  if (artefacts.length === 0) {
+    return await handleNoArtefacts(ctx, activeStageRecord);
+  }
+
+  return await processArtefacts(ctx, artefacts, activeStageRecord);
+}
+
+/**
+ * Handle the case where no artefacts exist for this cycle.
+ */
+async function handleNoArtefacts(ctx, activeStageRecord) {
+  const summary = 'SKIP: no artefacts';
+  await ctx.finalize({
+    lastStage: { stage: ctx.stageId, summary, baseSha: activeStageRecord.baseSha },
+    activeStage: activeStageRecord,
+  });
+  return { ok: true, summary };
+}
+
+/**
+ * Process each artefact: run validation, post feedback, handle errors.
+ */
+async function processArtefacts(ctx, artefacts, activeStageRecord) {
+  const perArtefact = [];
+  const currentFeedback = [];
+  let allOk = true;
+
+  for (const artefact of artefacts) {
+    const result = await performValidation({
+      typeId: artefact.type,
+      io: ctx.io,
+      foundryDir: ctx.foundryDir,
+    });
+
+    const outcome = handleArtefactResult(ctx, artefact, result, currentFeedback);
+    perArtefact.push(outcome.text);
+    if (!outcome.ok) allOk = false;
+  }
+
+  const summary = perArtefact.join('; ');
+  resolvePriorFeedback(ctx, currentFeedback);
+
+  await ctx.finalize({
+    lastStage: { stage: ctx.stageId, summary, baseSha: activeStageRecord.baseSha },
+    activeStage: activeStageRecord,
+  });
+
+  if (!allOk) {
+    return { ok: false, summary, error: 'One or more artefacts failed validation' };
+  }
+  return { ok: true, summary };
+}
+
+/**
+ * Handle validation result for a single artefact.
+ *
+ * Returns { ok, text } where `ok` indicates whether the artefact passed
+ * validation and `text` is the per-artefact summary line.
+ */
+function handleArtefactResult(ctx, artefact, result, currentFeedback) {
+  if (isNoValidators(result)) {
+    return { ok: true, text: `${artefact.file}: OK: no validators` };
+  }
+
+  if (result.error) {
+    markArtefactBlocked(ctx.io, artefact.file);
+    return { ok: false, text: `${artefact.file}: ${result.error}` };
+  }
+
+  if (isAllErrors(result)) {
+    markArtefactBlocked(ctx.io, artefact.file);
+    const messages = result.errors.map(e => e.message).join('; ');
+    return { ok: false, text: `${artefact.file}: ${messages}` };
+  }
+
+  postFeedbackItems(ctx, artefact, result, currentFeedback);
+  return { ok: true, text: `${artefact.file}: ${result.items.length} issues found` };
+}
+
+/**
+ * True when no validators are configured for this artefact type.
+ */
+function isNoValidators(result) {
+  return result.ok && result.validatorsRun === 0 && result.items.length === 0 && result.errors.length === 0;
+}
+
+/**
+ * True when validators ran but produced only errors with no valid items.
+ */
+function isAllErrors(result) {
+  return result.items.length === 0 && result.errors.length > 0;
+}
+
+/**
+ * Post feedback items for validation results and track for resolution.
+ */
+function postFeedbackItems(ctx, artefact, result, currentFeedback) {
+  for (const item of result.items) {
+    const tag = `law:${item.lawId}:${item.validatorId}`;
+    ctx.feedback.add({ file: artefact.file, text: item.text, tag });
+    currentFeedback.push({ file: artefact.file, tag });
+  }
+}
+
+/**
+ * Resolve prior quench feedback items against current results.
+ */
+function resolvePriorFeedback(ctx, currentFeedback) {
+  const currentSigs = new Set(currentFeedback.map(fb => `${fb.file}:${fb.tag}`));
+  const priorItems = ctx.feedback.list({ source: ctx.stageId });
+
+  for (const prior of priorItems) {
+    if (prior.state === 'resolved') continue;
+    const sig = `${prior.file}:${prior.tag}`;
+    const decision = currentSigs.has(sig) ? 'rejected' : 'approved';
+    ctx.feedback.resolve(prior.id, decision);
+  }
+}
+
+/**
+ * Mark an artefact as blocked in the artefacts table.
+ */
+function markArtefactBlocked(io, file) {
+  const workText = io.readFile('WORK.md');
+  const updated = setArtefactStatus(workText, file, 'blocked');
+  io.writeFile('WORK.md', updated);
+}

package/dist/scripts/sort.js

@@ -147,10 +147,26 @@ function resolveRoute(ctx) {
   return determineRoute(ctx.stages, ctx.history, ctx.feedback, ctx.maxIterations);
 }
 
-function resolveModel(route, frontmatter, agentsDir, io) {
-  const routeBase = baseStage(route);
-  if (!frontmatter.models || !frontmatter.models[routeBase]) return null;
-  const modelId = frontmatter.models[routeBase];
+function firstModelValue(models) {
+  if (!models) return undefined;
+  const keys = Object.keys(models);
+  return keys.length > 0 ? models[keys[0]] : undefined;
+}
+
+function resolveModelId(routeBase, models, defaultModel) {
+  return models[routeBase] || defaultModel || models.default || firstModelValue(models);
+}
+
+function pickModelId(route, frontmatter, defaultModel) {
+  const models = frontmatter.models;
+  if (!models) return defaultModel || null;
+  return resolveModelId(baseStage(route), models, defaultModel) || null;
+}
+
+function resolveModel(route, frontmatter, agentsDir, io, defaultModel) {
+  const modelId = pickModelId(route, frontmatter, defaultModel);
+  if (!modelId) return null;
+
   const model = `foundry-${modelId.replace(/[/.]/g, '-')}`;
   const agentPath = `${agentsDir}/${model}.md`;
   if (!io.exists(agentPath)) {
@@ -162,8 +178,8 @@ function resolveModel(route, frontmatter, agentsDir, io) {
   return model;
 }
 
-function checkModel(route, frontmatter, agentsDir, io) {
-  const modelResult = resolveModel(route, frontmatter, agentsDir, io);
+function checkModel(route, frontmatter, agentsDir, io, defaultModel) {
+  const modelResult = resolveModel(route, frontmatter, agentsDir, io, defaultModel);
   if (modelResult && modelResult.error) return { error: modelResult.error };
   return { model: typeof modelResult === 'string' ? modelResult : null };
 }
@@ -217,6 +233,7 @@ const RUN_SORT_DEFAULTS = Object.freeze({
   historyPath: 'WORK.history.yaml',
   foundryDir: 'foundry',
   cycleDef: undefined,
+  defaultModel: undefined,
   agentsDir: '.opencode/agents',
   mint: undefined,
 });
@@ -246,7 +263,7 @@ export function runSort(args = {}, io = defaultIO) {
   if (prep.kind !== 'ok') return { route: prep.kind, details: prep.details };
 
   const route = resolveRoute(buildRouteCtx(prep));
-  const modelCheck = checkModel(route, prep.frontmatter, opts.agentsDir, io);
+  const modelCheck = checkModel(route, prep.frontmatter, opts.agentsDir, io, opts.defaultModel);
   if (modelCheck.error) return { route: 'violation', details: modelCheck.error };
 
   return mintToken({

package/dist/skills/orchestrate/SKILL.md

@@ -47,6 +47,34 @@ task tool:
 
 When the task returns, call `foundry_orchestrate({lastResult: {ok: true}})`. If the task tool itself errored or reported a subagent crash, pass `{ok: false, error: '<message>'}`.
 
+### `dispatch_multi`
+
+Payload: `{stage, cycle, tasks}`.
+
+Fire all tasks in parallel by making multiple `task` tool calls in a single response:
+
+```
+task tool:
+  subagent_type: <task.subagent_type>
+  description: "Appraise <artefact> for <cycle>"
+  prompt: <task.prompt — pass verbatim>
+```
+
+Repeat for every entry in the `tasks` array. If `tasks` is empty, call
+`foundry_orchestrate({lastResults: []})` directly — no dispatch needed.
+
+When all tasks complete, collect their outputs into a `lastResults` array:
+
+- Task succeeded: `{ok: true, output: "<subagent output text>"}`
+- Task failed: `{ok: false, error: "<error message>"}`
+
+Then call `foundry_orchestrate({lastResults})`.
+
+Each appraiser sub-agent prompt already contains the appraiser personality,
+artefact content, and applicable laws. Do NOT inject additional instructions.
+Do NOT call `foundry_stage_begin` or `foundry_stage_end` — the appraise
+module handles lifecycle internally.
+
 ### `human_appraise`
 
 Payload: `{stage, token, context}`.
@@ -77,7 +105,7 @@ Report to the user: "Cycle halted (violation): `<details>`. Affected files: `<af
 
 ## What you do NOT do
 
-- You do NOT inline forge / quench / appraise work. Always dispatch via `task`.
+- You do NOT inline forge work. Always dispatch forge via `task`. Quench runs internally in the orchestrator. Appraise uses `dispatch_multi` for parallel subagent dispatch followed by internal consolidation.
 - You do NOT mint, modify, or cache tokens. The `prompt` from orchestrate already contains the token verbatim.
 - `foundry_history_append`, `foundry_git_commit`, `foundry_stage_finalize`, and `foundry_sort` are not registered tools; orchestrate handles them internally via the loop.
 - You do NOT reorder the protocol. `foundry_orchestrate` returns, you act, you call back. Nothing else between.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@really-knows-ai/foundry",
-  "version": "3.3.8",
+  "version": "3.4.0",
   "description": "A skill-driven framework for governed artefact generation with AI coding tools. Define your own artefact types, laws, and flows — Foundry handles the forge → quench → appraise pipeline with deterministic routing, quality gates, and iterative refinement.",
   "type": "module",
   "main": "dist/.opencode/plugins/foundry.js",
@@ -51,11 +51,11 @@
   },
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "find tests -name '*.test.js' ! -name '*.integration.test.js' ! -name '*.e2e.test.js' -print0 | xargs -0 node --test --test-reporter=dot",
+    "test": "find tests -name '*.test.js' ! -name '*.integration.test.js' ! -name '*.e2e.test.js' -print0 | xargs -0 node --test --experimental-test-module-mocks --test-reporter=dot",
     "test:unit": "pnpm run test",
-    "test:integration": "find tests -name '*.integration.test.js' -print0 | xargs -0 node --test --test-reporter=dot",
-    "test:e2e": "find tests -name '*.e2e.test.js' -print0 | xargs -0 node --test --test-reporter=dot",
-    "test:all": "node --test --test-reporter=dot",
+    "test:integration": "find tests -name '*.integration.test.js' -print0 | xargs -0 node --test --experimental-test-module-mocks --test-reporter=dot",
+    "test:e2e": "find tests -name '*.e2e.test.js' -print0 | xargs -0 node --test --experimental-test-module-mocks --test-reporter=dot",
+    "test:all": "node --test --experimental-test-module-mocks --test-reporter=dot",
     "test:coverage": "node --test --experimental-test-coverage --test-reporter=dot",
     "lint": "eslint src/ tests/ scripts/",
     "build:full": "pnpm run lint --fix && pnpm run test:all && pnpm run build",