@really-knows-ai/foundry 3.3.9 → 3.5.1

package/dist/scripts/orchestrate.js

@@ -4,26 +4,37 @@
 
 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,
   readCycleTargets,
   readForgeFilePatterns,
   renderDispatchPrompt,
   synthesizeStages,
   violation,
   computeOpenFeedback,
+  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 { findCycleOutputArtefact, readCycleTargets, readForgeFilePatterns };
+export {
+  renderDispatchPrompt, synthesizeStages, computeOpenFeedback,
+  DISPATCH_MULTI_ACTION, validateDispatchMulti, buildDispatchMultiResponse,
+};
+export { gatherAppraiseContext, consolidateAppraise };
+export { readCycleTargets, readForgeFilePatterns };
 export { handleSortResult as __handleSortResultForTest };
 
 export function needsSetup(workMdContent) {
@@ -38,28 +49,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,61 +77,188 @@ 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,
-    defaultModel: args.defaultModel,
+    ulid: args.ulid ?? defaultUlid, defaultModel: args.defaultModel,
   };
 }
 
 function buildSortContext(cycleId, args, io) {
-  return { cycleId, cwd: args.cwd ?? process.cwd(), io };
+  return { cycleId, cwd: args.cwd ?? process.cwd(), io, foundryDir: args.foundryDir ?? 'foundry', baseBranch: args.baseBranch ?? 'main' };
 }
 
 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,
+    baseBranch: args.baseBranch ?? 'main',
+    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,
+    baseBranch: args.baseBranch ?? 'main',
+    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') {
+    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) {
@@ -143,8 +272,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) {
@@ -152,13 +280,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,162 @@
+/**
+ * Quench module — deterministic validation run entirely within the orchestrator.
+ *
+ * The module discovers artefact changes via branch-based artefact discovery,
+ * runs validators for each artefact change, posts feedback for each validation
+ * item, resolves prior quench feedback, and finalises the stage. No LLM
+ * involvement.
+ */
+
+import { readActiveStage } from './lib/state.js';
+import { getArtefactFiles } from './lib/artefacts.js';
+import { getCycleDefinition } from './lib/config.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 cycleDef = await getCycleDefinition(ctx.foundryDir, ctx.cycleId, ctx.io);
+  const outputType = cycleDef.frontmatter['output-type'];
+  if (!outputType) {
+    return { ok: false, error: `Cycle ${ctx.cycleId} has no output-type` };
+  }
+
+  const discovery = await discoverArtefacts(ctx, outputType);
+  if (!discovery.ok) return discovery;
+  const artefacts = discovery.artefacts;
+
+  if (artefacts.length === 0) {
+    return await handleNoArtefacts(ctx, activeStageRecord);
+  }
+
+  return await processArtefacts(ctx, artefacts, activeStageRecord, outputType);
+}
+
+async function discoverArtefacts(ctx, outputType) {
+  try {
+    const artefacts = await getArtefactFiles(ctx.foundryDir, outputType, ctx.io, { baseBranch: ctx.baseBranch ?? 'main' });
+    return { ok: true, artefacts };
+  } catch (err) {
+    return { ok: false, error: `Failed to discover artefacts: ${err.message}` };
+  }
+}
+
+/**
+ * Handle the case where no artefacts exist for this cycle.
+ */
+async function handleNoArtefacts(ctx, activeStageRecord) {
+  const summary = 'SKIP: no files';
+  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, outputType) {
+  const perArtefact = [];
+  const currentFeedback = [];
+  let allOk = true;
+
+  for (const artefact of artefacts) {
+    const result = await performValidation({
+      typeId: outputType,
+      io: ctx.io,
+      foundryDir: ctx.foundryDir,
+      artefacts: [artefact],
+    });
+
+    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) {
+    return { ok: false, text: `${artefact.file}: ${result.error}` };
+  }
+
+  if (isAllErrors(result)) {
+    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);
+  }
+}

package/dist/scripts/sort.js

@@ -275,7 +275,6 @@ export function runSort(args = {}, io = defaultIO) {
 // Exports (for testing) — keep main() private
 // ---------------------------------------------------------------------------
 
-export { parseArtefactsTable } from './lib/artefacts.js';
 export { loadHistory } from './lib/history.js';
 export { parseFrontmatter } from './lib/workfile.js';
 export {

package/dist/skills/appraise/SKILL.md

@@ -40,9 +40,9 @@ Appraise makes **no disk writes**. Feedback output flows through `foundry_feedba
      >   3. Investigate and fix the root cause of the failure before restarting.
 
      Then return control to the user and stop.
-   - `foundry_artefacts_list({cycle: <current-cycle>})` — enumerate this cycle's artefacts. Always pass the `cycle` filter; omitting it returns stale rows from prior sessions. Skip rows whose status is `done` or `blocked`.
-   - For each remaining row, gather its type-specific context:
-     - `foundry_config_laws` with the row's type — applicable laws (global + type-specific)
+   - `foundry_artefacts_list({})` — enumerate the current cycle's branch artefact changes as `[{ file, state }]` entries.
+   - For each artefact change, gather its type-specific context:
+     - `foundry_config_laws` with the cycle's output type — applicable laws (global + type-specific)
      - `foundry_config_artefact_type` with the type ID — the artefact type definition
      - `foundry_appraisers_select` with the type ID — selected appraiser personalities with their raw model IDs
 

package/dist/skills/human-appraise/SKILL.md

@@ -23,7 +23,7 @@ Human-appraise runs inside an enforced stage. Your **first** and **last** tool c
 
 Human-appraise makes **no disk writes**. All output flows through `foundry_feedback_add` and `foundry_feedback_resolve`. `foundry_stage_end` flags unexpected writes as a violation.
 
-Human-appraise **cannot** call `foundry_feedback_action`, `foundry_feedback_wontfix`, or `foundry_artefacts_set_status` — the tools reject those calls during a human-appraise stage (action/wontfix are forge-only forward transitions; set-status requires no active stage). See "Feedback handling" below for the legal transitions available to human-appraise.
+Human-appraise **cannot** call `foundry_feedback_action` or `foundry_feedback_wontfix` — the tools reject those calls during a human-appraise stage (action/wontfix are forge-only forward transitions). See "Feedback handling" below for the legal transitions available to human-appraise.
 
 ## Input
 
@@ -54,7 +54,7 @@ Your LAST tool call must be `foundry_stage_end({summary: '<one-sentence descript
      >   3. Investigate and fix the root cause of the failure before restarting.
 
      Then call `foundry_stage_end({summary: 'Flow is failed; no human appraisal performed'})`, return control to the user, and stop.
-   - `foundry_artefacts_list({cycle: <current-cycle>})` — this cycle's artefact files and status (always pass the `cycle` filter; omitting it returns stale rows from prior sessions)
+   - `foundry_artefacts_list({})` — this cycle's branch artefact changes as `[{ file, state }]` entries
    - `foundry_feedback_list` — all existing feedback
    - `foundry_history_list({cycle: <current-cycle>})` — what has happened so far
 
@@ -75,7 +75,7 @@ Your LAST tool call must be `foundry_stage_end({summary: '<one-sentence descript
    - **Approve** — "looks good" / "continue" — no feedback added, sort will advance.
    - **Provide feedback** — `foundry_feedback_add({ file, text, tag: 'human' })`. Sort will route back to forge.
    - **Resolve feedback** — `foundry_feedback_resolve({ id, resolution, reason? })` for items in `{actioned, wont-fix, deadlocked}`. See "Feedback handling" below for the legal transitions and authority rules.
-   - **Abort** — human-appraise cannot directly mark the artefact `blocked` (the `foundry_artefacts_set_status` tool refuses calls during an active stage). To abort: end the stage with a summary explaining the abort, then either (a) instruct the user to call `foundry_workfile_delete({ confirm: true })` to discard the cycle, or (b) reject outstanding feedback so routing exhausts iterations and sort marks the artefact blocked on its own.
+   - **Abort** — human-appraise cannot directly mark the artefact `blocked` (the repository no longer has a per-artefact status tool or table). To abort: end the stage with a summary explaining the abort, then either (a) instruct the user to call `foundry_workfile_delete({ confirm: true })` to discard the cycle, or (b) reject outstanding feedback so routing exhausts iterations and sort blocks the cycle on its own.
 
 7. `foundry_stage_end({summary})` — describe what the human decided so sort can log it.
 
@@ -96,10 +96,9 @@ What human-appraise can NOT do:
   `{actioned, wont-fix}` — that is forge's lane (spec §5.1 rule 1) and
   the tools reject calls from any non-forge stage. If an open or rejected
   item needs work, sort will route to forge after this stage ends.
-- **No artefact status writes.** `foundry_artefacts_set_status` requires
-  no active stage; it refuses calls while human-appraise is open. Status
-  promotion to `done`/`blocked` is owned by sort/orchestrate based on
-  routing.
+- **No artefact status writes.** The repository no longer has a per-artefact
+  status tool or table. Status is owned by the cycle state machine through
+  sort and orchestrate routing.
 
 What human-appraise CAN do:
 

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}`.
@@ -59,25 +87,24 @@ When it returns, call `foundry_orchestrate({lastResult: {ok: true}})`.
 
 Payload: `{cycle, artefact_file, next_cycles}`.
 
-1. Call `foundry_artefacts_set_status({file: artefact_file, status: 'done'})`.
-2. Report to the user: "Cycle `<cycle>` complete. Output: `<artefact_file>`. Next cycles available: `<next_cycles>`."
-3. Return control to the flow skill.
+1. Report to the user: "Cycle `<cycle>` complete. Output: `<artefact_file>`. Next cycles available: `<next_cycles>`."
+2. Return control to the flow skill.
 
 ### `blocked`
 
 Payload: `{cycle, artefact_file, reason}`.
 
-Report to the user: "Cycle `<cycle>` blocked on `<artefact_file>`: `<reason>`." Return control to the flow skill. The artefact has already been marked blocked.
+Report to the user: "Cycle `<cycle>` blocked on `<artefact_file>`: `<reason>`." Return control to the flow skill. The cycle is blocked.
 
 ### `violation`
 
 Payload: `{details, affected_files}`.
 
-Report to the user: "Cycle halted (violation): `<details>`. Affected files: `<affected_files>`." Return control to the flow skill. Affected artefacts have already been marked blocked.
+Report to the user: "Cycle halted (violation): `<details>`. Affected files: `<affected_files>`." Return control to the flow skill. The cycle is halted by the violation; no per-artefact status is written.
 
 ## 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/dist/skills/quench/SKILL.md

@@ -39,14 +39,14 @@ Quench makes **no disk writes**. You produce feedback via `foundry_feedback_add`
    >   3. Investigate and fix the root cause of the failure before restarting.
 
    Then return control to the user and stop.
-3. `foundry_artefacts_list({cycle: <current-cycle>})` — enumerate the artefacts produced by **this** cycle. Always pass the `cycle` filter; omitting it returns rows from prior sessions and validates stale files. Skip rows whose status is `done` or `blocked`.
-4. For each remaining row:
+3. `foundry_artefacts_list({})` — enumerate the current cycle's branch artefact changes as `[{ file, state }]` entries.
+4. For each artefact change:
     a. `foundry_validate_run({ typeId: '<type-id>' })` — executes all law-based validators for the artefact type. The tool returns `{ ok, validatorsRun, items, errors }`. `items` is the array of parsed feedback items; each entry carries `lawId`, `validatorId`, `file`, and `text` (plus optional `location` and `severity`). `errors` carries validator-level failures with `lawId`, `validatorId`, `type` (`parse` or `pattern-mismatch`), and `message`.
    b. For each entry in `items`: call `foundry_feedback_add` with `{ file: item.file, text: item.text, tag: 'law:' + item.lawId + ':' + item.validatorId }`. The tag uses the law ID and validator ID returned by the tool so operators reading `WORK.feedback.yaml` can identify exactly which validator produced each item.
    c. If `errors` is non-empty, the validators themselves misbehaved (malformed JSONL or files outside the artefact type's `file-patterns`). Report these to the user via `foundry_stage_end` summary; do not convert them to law-tagged feedback.
 5. Call `foundry_feedback_list`. For items whose `source` matches your stage id and whose state is `actioned` or `wont-fix`, use the validation results from step 4 to resolve them by id: approve when the relevant validation now passes or the deterministic issue is gone; reject with a reason when it still fails.
-6. If every command passes for every row, add no new feedback.
-7. If the artefact table has no rows for this cycle, `foundry_stage_end({summary: 'SKIP: no artefacts registered for this cycle'})` and stop.
+6. If every command passes for every artefact change, add no new feedback.
+7. If the artefact list is empty, `foundry_stage_end({summary: 'SKIP: no files'})` and stop.
 8. `foundry_stage_end({summary})`.
 
 ## Feedback handling

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@really-knows-ai/foundry",
-  "version": "3.3.9",
+  "version": "3.5.1",
   "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",