@really-knows-ai/foundry 3.8.5 → 3.9.0

package/dist/scripts/lib/stage-output-schemas.js

@@ -0,0 +1,174 @@
+// src/scripts/lib/stage-output-schemas.js
+// Stage output validation schemas for forge, appraise, and human-appraise.
+// Each exported function validates a plain object against the stage's output
+// schema and returns { ok: true } or { ok: false, errors: [...] }.
+
+// ── JSON Schema definitions ──────────────────────────────────────────
+
+const FORGE_SCHEMA = {
+  type: 'object',
+  required: ['status'],
+  properties: {
+    status: { enum: ['done', 'actioned', 'wont-fix'] },
+    reason: { type: 'string' },
+  },
+  allOf: [
+    {
+      if: { properties: { status: { const: 'wont-fix' } } },
+      then: { required: ['reason'] },
+    },
+  ],
+};
+
+const APPRAISE_SCHEMA = {
+  type: 'object',
+  required: ['file', 'law', 'text'],
+  properties: {
+    file: { type: 'string', minLength: 1 },
+    law: { type: 'string', minLength: 1 },
+    text: { type: 'string', minLength: 1 },
+    evidence: { type: 'string' },
+    severity: { type: 'string' },
+    location: { type: 'string' },
+  },
+};
+
+const HUMAN_APPRAISE_SCHEMA = {
+  type: 'object',
+  required: ['verdict'],
+  properties: {
+    verdict: { const: 'approved' },
+  },
+};
+
+// ── Schema validator ─────────────────────────────────────────────────
+
+function checkObjectType(schema, data, path) {
+  if (schema.type !== 'object') return [];
+  if (isRecord(data)) return [];
+  return [`${path} — must be a plain object`];
+}
+
+function checkStringType(schema, data, path) {
+  if (schema.type !== 'string') return [];
+  if (typeof data !== 'string') {
+    return [`${path} — must be a string`];
+  }
+  if (schema.minLength !== undefined && data.length < schema.minLength) {
+    return [`${path} — must be a non-empty string`];
+  }
+  return [];
+}
+
+function checkType(schema, data, path) {
+  return [
+    ...checkObjectType(schema, data, path),
+    ...checkStringType(schema, data, path),
+  ];
+}
+
+function isRecord(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function checkRequired(schema, data, path) {
+  if (!schema.required || !isRecord(data)) return [];
+  return schema.required
+    .filter(key => !(key in data))
+    .map(key => `${path}: ${key} — is required`);
+}
+
+function checkProperties(schema, data, path) {
+  if (!schema.properties || !isRecord(data)) return [];
+  const errors = [];
+  for (const [key, propSchema] of Object.entries(schema.properties)) {
+    if (key in data) {
+      errors.push(...validateSchema(propSchema, data[key], `${path}: ${key}`));
+    }
+  }
+  return errors;
+}
+
+function checkAdditionalProperties(schema, data, path) {
+  if (schema.additionalProperties !== false || !schema.properties || !isRecord(data)) return [];
+  const allowed = new Set(Object.keys(schema.properties));
+  return Object.keys(data)
+    .filter(key => !allowed.has(key))
+    .map(key => `${path}: ${key} — unknown field`);
+}
+
+function checkEnum(schema, data, path) {
+  if (schema.enum === undefined) return [];
+  if (schema.enum.includes(data)) return [];
+  const allowed = schema.enum.map(v => JSON.stringify(v)).join(', ');
+  return [`${path} — must be one of ${allowed}`];
+}
+
+function checkConst(schema, data, path) {
+  if (schema.const === undefined) return [];
+  if (data === schema.const) return [];
+  return [`${path} — must be ${JSON.stringify(schema.const)}`];
+}
+
+function checkNot(schema, data, path) {
+  if (!schema.not || !schema.not.required || !isRecord(data)) return [];
+  return schema.not.required
+    .filter(key => key in data)
+    .map(key => `${path}: ${key} — must not be present`);
+}
+
+function skipAllOfItem(item, data) {
+  if (!item.if) return true;
+  if (!item.if.properties) return false;
+  return Object.keys(item.if.properties).some(key => !(key in data));
+}
+
+function checkAllOf(schema, data, path) {
+  if (!schema.allOf) return [];
+  const errors = [];
+  for (const item of schema.allOf) {
+    if (skipAllOfItem(item, data)) continue;
+    const ifErrors = validateSchema(item.if, data, path);
+    if (ifErrors.length === 0) {
+      errors.push(...validateSchema(item.then, data, path));
+    }
+  }
+  return errors;
+}
+
+function validateSchema(schema, data, path = '') {
+  const typeErrors = checkType(schema, data, path);
+  if (typeErrors.length > 0) return typeErrors;
+
+  return [
+    ...checkRequired(schema, data, path),
+    ...checkProperties(schema, data, path),
+    ...checkAdditionalProperties(schema, data, path),
+    ...checkEnum(schema, data, path),
+    ...checkConst(schema, data, path),
+    ...checkNot(schema, data, path),
+    ...checkAllOf(schema, data, path),
+  ];
+}
+// ── Exported validators ──────────────────────────────────────────────
+
+export function validateForgeOutput(data) {
+  const stage = 'forge';
+  const errors = validateSchema(FORGE_SCHEMA, data, stage);
+  if (errors.length) return { ok: false, errors };
+  return { ok: true };
+}
+
+export function validateAppraiseOutput(data) {
+  const stage = 'appraise';
+  const errors = validateSchema(APPRAISE_SCHEMA, data, stage);
+  if (errors.length) return { ok: false, errors };
+  return { ok: true };
+}
+
+export function validateHumanAppraiseOutput(data) {
+  const stage = 'human-appraise';
+  const errors = validateSchema(HUMAN_APPRAISE_SCHEMA, data, stage);
+  if (errors.length) return { ok: false, errors };
+  return { ok: true };
+}

package/dist/scripts/orchestrate-cycle.js

@@ -266,17 +266,17 @@ function buildForgePromptLines({ cycle, outputType, forgeItem }) {
       `File: ${forgeItem.file}`,
       `Issue: ${forgeItem.text}`,
       ``,
-      `Respond with EXACTLY one of:`,
-      `  - ACTIONED  — fix the issue by changing the artefact file`,
-      `  - WONT-FIX: <justification> — the issue is already resolved or does not apply`,
+      `Call foundry_stage_output with the correct status:`,
+      `  - foundry_stage_output({ status: "actioned" }) — fix the issue by changing the artefact file`,
+      `  - foundry_stage_output({ status: "wont-fix", reason: "<justification>" }) — the issue is already resolved or does not apply`,
       ``,
-      `Write NOTHING else in the stage_end summary — no descriptions, no explanations.`,
+      `Then call foundry_stage_end(). Write nothing else — format is validated by the tool.`,
     );
   } else {
     lines.push(
       ``,
       `First generation — no feedback to address yet.`,
-      `Produce the artefact and call foundry_stage_end({summary: "DONE"}).`,
+      `Produce the artefact, call foundry_stage_output({ status: "done" }), then foundry_stage_end().`,
     );
   }
   return lines;
@@ -301,7 +301,7 @@ export function renderDispatchPrompt({ stage, cycle, token, cwd, filePatterns, o
   lines.push(
     ``,
     `Your FIRST tool call MUST be foundry_stage_begin({stage, cycle, token}) using the values above.`,
-    `Your LAST tool call MUST be foundry_stage_end({summary}).`,
+    `Your LAST tool call MUST be foundry_stage_end().`,
   );
   return lines.join('\n');
 }

package/dist/scripts/orchestrate-dispatch.js

@@ -0,0 +1,240 @@
+// Foundry v3.x orchestrate: post-dispatch handlers for structured output
+// reading from .foundry/stage-outputs/ files.
+
+import path from 'node:path';
+import { computeArtefactVersion } from './lib/artefacts.js';
+import { enforceForgeContract } from './lib/forge-contract.js';
+import { loadHistory } from './lib/history.js';
+import { stageBaseOf } from './lib/stage-guard.js';
+import { readForgeFilePatterns, violation } from './orchestrate-cycle.js';
+import { openFeedbackStore } from './lib/feedback-store.js';
+import { finaliseStage } from './orchestrate-phases.js';
+
+const FORGE_CTX = '.foundry/forge-context.json';
+
+export function safeUnlink(io, filePath) {
+  try { io.unlink(filePath); } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+    console.warn(`ENOENT: file already removed: ${filePath}`);
+  }
+}
+
+export async function readStageOutput(filePath, io) {
+  try {
+    const content = await io.readFile(filePath);
+    const lines = content.trim().split('\n').filter(Boolean);
+    if (lines.length === 0) return [];
+    return lines.map(line => JSON.parse(line));
+  } catch {
+    return [];
+  }
+}
+
+async function readForgeStageOutput(io) {
+  let entries;
+  try { entries = await io.readDir('.foundry/stage-outputs'); } catch { entries = []; }
+  return parseForgeOutput(entries, io);
+}
+
+async function parseForgeOutput(entries, io) {
+  const files = (Array.isArray(entries) ? entries : []).filter(f => f.endsWith('.jsonl'));
+  if (files.length === 0) return { ok: false, error: 'forge: no stage output found' };
+
+  const allOutputs = [];
+  for (const f of files) {
+    const filePath = path.join('.foundry/stage-outputs', f);
+    const outputs = await readStageOutput(filePath, io);
+    allOutputs.push(...outputs);
+    safeUnlink(io, filePath);
+  }
+
+  if (allOutputs.length === 0) return { ok: false, error: 'forge: malformed stage output' };
+  return { ok: true, outputs: allOutputs };
+}
+
+export async function enforceForgeStage(forgeCtx, fgResult, cycleId, io, cwd) {
+  const postVersion = await computeArtefactVersion('foundry', fgResult.outputType, io, cwd);
+  const feedbackStore = openFeedbackStore('WORK.feedback.yaml', io);
+
+  const stageResult = await readForgeStageOutput(io);
+  if (!stageResult.ok) return stageResult;
+
+  const outputs = stageResult.outputs;
+  if (outputs.length !== 1) {
+    return { ok: false, error: `forge stage_end: expected exactly 1 output object, got ${outputs.length}` };
+  }
+  const output = outputs[0];
+  const item = forgeCtx.forgeItem || null;
+
+  const { contractPassed } = enforceForgeContract({
+    item, preVersion: forgeCtx.forgePreVersion, postVersion, output, feedbackStore, cycleId,
+  });
+
+  if (checkConsecutiveFailures(contractPassed, io, cycleId)) {
+    return { violation: 'forge contract failed 3 consecutive times — unable to satisfy feedback requirements' };
+  }
+  return { postVersion, contractPassed, output };
+}
+
+function countConsecutiveForgeFailures(io, cycleId) {
+  if (!io.exists('WORK.history.yaml')) return 0;
+  const entries = loadHistory('WORK.history.yaml', cycleId, io);
+  let count = 0;
+  for (let i = entries.length - 1; i >= 0; i--) {
+    if (stageBaseOf(entries[i].stage) !== 'forge') break;
+    if (entries[i].contract_passed === false) count++;
+    else break;
+  }
+  return count;
+}
+
+export function checkConsecutiveFailures(contractPassed, io, cycleId) {
+  if (!contractPassed) {
+    return countConsecutiveForgeFailures(io, cycleId) + 1 >= 3;
+  }
+  return false;
+}
+
+export async function captureForgeContext(sortResult, args, preCheck, io) {
+  const fgResult = await readForgeFilePatterns(preCheck.cycleId, io);
+  if (!fgResult) return;
+  const preVersion = await computeArtefactVersion('foundry', fgResult.outputType, io, args.cwd);
+  const allItems = openFeedbackStore('WORK.feedback.yaml', io).list();
+  // Only capture unresolved items (open/rejected) — resolved items are terminal
+  // and presenting them to forge causes the contract to fail and revert them.
+  const unresolvedItems = allItems.filter(item => {
+    const state = item.history?.[0]?.state ?? 'open';
+    return state === 'open' || state === 'rejected';
+  });
+  if (!io.exists('.foundry')) io.mkdir('.foundry');
+  const forgeItem = unresolvedItems.length > 0
+    ? ({
+      id: unresolvedItems[0].id,
+      file: unresolvedItems[0].file,
+      tag: unresolvedItems[0].tag,
+      text: unresolvedItems[0].text,
+      source: (typeof unresolvedItems[0].source === 'string'
+        ? unresolvedItems[0].source.split(':')[0]
+        : unresolvedItems[0].source),
+      sourceAlias: unresolvedItems[0].source,
+    })
+    : null;
+  const ctx = { forgePreVersion: preVersion, forgeItem };
+  io.writeFile(FORGE_CTX, JSON.stringify(ctx));
+}
+
+export async function runForgePostDispatch(args, activeStage, lastStage, cycleId, io) {
+  const fgResult = await readForgeFilePatterns(cycleId, io);
+  const base = { lastStage, activeStage, cycleId, io, finalize: args.finalize, git: args.git };
+  if (!fgResult) return finaliseStage(base);
+  if (!io.exists(FORGE_CTX)) return finaliseStage(base);
+  const forgeCtx = JSON.parse(io.readFile(FORGE_CTX));
+  io.unlink(FORGE_CTX);
+  const result = await enforceForgeStage(forgeCtx, fgResult, cycleId, io, args.cwd);
+  if (result.violation) return violation(result.violation, []);
+  if (result.error) return violation(result.error, []);
+  return finaliseStage({
+    ...base,
+    postVersion: result.postVersion,
+    contractPassed: result.contractPassed,
+    structuredSummary: JSON.stringify(result.output),
+  });
+}
+
+function isVerdictApproved(output) {
+  return output && output.verdict === 'approved';
+}
+
+async function readStageOutputFiles(io) {
+  const dir = '.foundry/stage-outputs';
+  let entries;
+  try { entries = await io.readDir(dir); } catch { entries = []; }
+  return (entries || []).filter(f => f.endsWith('.jsonl'));
+}
+
+function resolveHumanAppraiseVerdict(output) {
+  return isVerdictApproved(output) ? 'approved' : '';
+}
+
+function cleanupHumanAppraiseFiles(io, files) {
+  for (const f of files) {
+    safeUnlink(io, path.join('.foundry/stage-outputs', f));
+  }
+}
+
+export async function runHumanAppraisePostDispatch(args, activeStage, lastStage, cycleId, io) {
+  const files = await readStageOutputFiles(io);
+
+  if (files.length === 0) {
+    return finaliseStage({
+      lastStage, activeStage, cycleId, io,
+      finalize: args.finalize, git: args.git,
+      structuredSummary: '',
+    });
+  }
+
+  if (files.length > 1) {
+    cleanupHumanAppraiseFiles(io, files);
+    return finaliseStage({
+      lastStage, activeStage, cycleId, io,
+      finalize: args.finalize, git: args.git,
+      structuredSummary: '',
+    });
+  }
+
+  const outputs = await readStageOutput(path.join('.foundry/stage-outputs', files[0]), io);
+  cleanupHumanAppraiseFiles(io, files);
+
+  // Any approved verdict in the outputs means approved
+  const approved = outputs.some(o => o && o.verdict === 'approved');
+  const structuredSummary = approved ? 'approved' : '';
+
+  return finaliseStage({
+    lastStage, activeStage, cycleId, io,
+    finalize: args.finalize, git: args.git,
+    structuredSummary,
+  });
+}
+
+export async function runAppraisePostDispatch(args, activeStage, lastStage, cycleId, io) {
+  const files = await readStageOutputFiles(io);
+
+  if (files.length === 0) {
+    return finaliseStage({
+      lastStage, activeStage, cycleId, io,
+      finalize: args.finalize, git: args.git,
+      structuredSummary: undefined,
+    });
+  }
+
+  let totalCount = 0;
+  for (const f of files) {
+    const filePath = path.join('.foundry/stage-outputs', f);
+    const outputs = await readStageOutput(filePath, io);
+    totalCount += outputs.length;
+  }
+
+  // Do NOT clean up files — consolidateAppraise handles cleanup later
+
+  const structuredSummary = totalCount > 0 ? `found:${totalCount}` : undefined;
+
+  return finaliseStage({
+    lastStage, activeStage, cycleId, io,
+    finalize: args.finalize, git: args.git,
+    structuredSummary,
+  });
+}
+
+export function routePostDispatchStage(baseStageName, opts) {
+  if (baseStageName === 'forge') return runForgePostDispatch(opts.args, opts.activeStage, opts.lastStage, opts.cycleId, opts.io);
+  if (baseStageName === 'human-appraise') return runHumanAppraisePostDispatch(opts.args, opts.activeStage, opts.lastStage, opts.cycleId, opts.io);
+  if (baseStageName === 'appraise') return runAppraisePostDispatch(opts.args, opts.activeStage, opts.lastStage, opts.cycleId, opts.io);
+  return finaliseStage({
+    lastStage: opts.lastStage,
+    activeStage: opts.activeStage,
+    cycleId: opts.cycleId,
+    io: opts.io,
+    finalize: opts.args.finalize,
+    git: opts.args.git,
+  });
+}

package/dist/scripts/orchestrate-finalise.js

@@ -20,22 +20,25 @@ function buildFinalizeViolation(finalizeResult) {
   return violation(`stage_finalize error: ${finalizeResult.error}`, []);
 }
 
+function resolveStageSummary(ctx) {
+  return ctx.structuredSummary || ctx.lastStage.summary || '(no summary)';
+}
+
 function buildStageEntryBase(ctx) {
-  const summary = ctx.lastStage.summary || '(no summary)';
+  const summary = resolveStageSummary(ctx);
   const changed = ctx.lastStage.changedFiles ?? [];
-  return { cycle: ctx.cycleId, stage: ctx.lastStage.stage,
+  const base = { cycle: ctx.cycleId, stage: ctx.lastStage.stage,
     iteration: ctx.iteration, comment: summary,
     openFeedback: ctx.openFeedback, changedFiles: changed,
-    ...(baseStage(ctx.lastStage.stage || '') === 'forge'
-      ? buildForgeHistoryEntry({
-        cycle: ctx.cycleId, stage: ctx.lastStage.stage,
-        iteration: ctx.iteration, comment: summary,
-        artefactVersion: ctx.artefactVersion,
-        contractPassed: ctx.contractPassed,
-        changedFiles: changed,
-      })
-      : {}),
   };
+  if (baseStage(ctx.lastStage.stage || '') !== 'forge') return base;
+  return { ...base, ...buildForgeHistoryEntry({
+    cycle: ctx.cycleId, stage: ctx.lastStage.stage,
+    iteration: ctx.iteration, comment: summary,
+    artefactVersion: ctx.artefactVersion,
+    contractPassed: ctx.contractPassed,
+    changedFiles: changed,
+  }) };
 }
 
 function writeHistoryEntries(ctx) {
@@ -58,8 +61,8 @@ async function computeAllowedPatterns(lastStage, cycleId, io) {
   return allowedPatternsForStage({ stageBase: stageB, forgeFilePatterns });
 }
 
-function buildCommitMessage(cycleId, lastStage) {
-  return `[${cycleId}] ${lastStage.stage}: ${lastStage.summary || '(no summary)'}`;
+function buildCommitMessage(cycleId, lastStage, structuredSummary) {
+  return `[${cycleId}] ${lastStage.stage}: ${structuredSummary || lastStage.summary || '(no summary)'}`;
 }
 
 function rollbackState(io, original) {
@@ -68,10 +71,10 @@ function rollbackState(io, original) {
   else if (io.exists('WORK.history.yaml')) { io.unlink('WORK.history.yaml'); }
 }
 
-async function tryStageCommit(git, lastStage, cycleId, io) {
+async function tryStageCommit(git, lastStage, cycleId, io, structuredSummary) {
   if (!git || typeof git.commit !== 'function') return null;
   const allowedPatterns = await computeAllowedPatterns(lastStage, cycleId, io);
-  return tryCommit(git, buildCommitMessage(cycleId, lastStage), allowedPatterns, lastStage.stage);
+  return tryCommit(git, buildCommitMessage(cycleId, lastStage, structuredSummary), allowedPatterns, lastStage.stage);
 }
 
 function clearStageState(activeStage, lastStage, io) {
@@ -80,7 +83,7 @@ function clearStageState(activeStage, lastStage, io) {
 }
 
 export async function finaliseStage(args) {
-  const { lastStage, activeStage, cycleId, io, finalize, git, postVersion, contractPassed } = args;
+  const { lastStage, activeStage, cycleId, io, finalize, git, postVersion, contractPassed, structuredSummary } = args;
   const original = {
     workMd: io.readFile('WORK.md'),
     history: io.exists('WORK.history.yaml') ? io.readFile('WORK.history.yaml') : null,
@@ -104,8 +107,9 @@ export async function finaliseStage(args) {
     lastStage: { ...lastStage, changedFiles: finalizeResult.changedFiles },
     iteration, openFeedback, io,
     artefactVersion: postVersion, contractPassed,
+    structuredSummary,
   });
-  const commitErr = await tryStageCommit(git, lastStage, cycleId, io);
+  const commitErr = await tryStageCommit(git, lastStage, cycleId, io, structuredSummary);
   if (commitErr) {
     rollbackState(io, original);
     clearStageState(activeStage, null, io);

package/dist/scripts/orchestrate.js

@@ -7,9 +7,6 @@ import matter from 'gray-matter';
 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 { computeArtefactVersion } from './lib/artefacts.js';
-import { enforceForgeContract } from './lib/forge-contract.js';
-import { loadHistory } from './lib/history.js';
 import { getCycleDefinition } from './lib/config.js';
 import {
   readCycleTargets,
@@ -33,6 +30,11 @@ import { runQuench } from './quench-module.js';
 import { gatherAppraiseContext, consolidateAppraise } from './appraise-module.js';
 import { openFeedbackStore } from './lib/feedback-store.js';
 import { guardNoWorkMd, guardMissingCycleId, guardSetupInconsistent, guardOrphanedStage, guardMissingLastStage, guardLastResults } from './lib/orchestrate-guards.js';
+import {
+  captureForgeContext,
+  enforceForgeStage,
+  routePostDispatchStage,
+} from './orchestrate-dispatch.js';
 
 export {
   renderDispatchPrompt, synthesizeStages, computeOpenFeedback,
@@ -112,7 +114,8 @@ function buildQuenchContext(cycleId, args, io) {
 
 async function buildAppraiseCtx(cycleId, args, io) {
   const stageId = `appraise:${cycleId}`;
-  const defaultModel = args.defaultModel ?? await readAppraiseModel(cycleId, io);
+  const cycleModel = await readAppraiseModel(cycleId, io);
+  const defaultModel = cycleModel || args.defaultModel;
   return { cycleId, io, git: args.git, finalize: buildFinalizeWrapper(cycleId, args, io),
     foundryDir: 'foundry', defaultModel,
     baseBranch: args.baseBranch ?? 'main', cwd: args.cwd ?? process.cwd(),
@@ -139,77 +142,6 @@ function writeStageRecord(io, cycleId, route) {
   writeActiveStage(io, { cycle: cycleId, stage: `${route}`, token: null, baseSha: resolveBaseSha(io) });
 }
 
-const FORGE_CTX = '.foundry/forge-context.json';
-
-async function captureForgeContext(sortResult, args, preCheck, io) {
-  const fgResult = await readForgeFilePatterns(preCheck.cycleId, io);
-  if (!fgResult) return;
-  const preVersion = await computeArtefactVersion('foundry', fgResult.outputType, io, args.cwd);
-  const allItems = openFeedbackStore('WORK.feedback.yaml', io).list();
-  // Only capture unresolved items (open/rejected) — resolved items are terminal
-  // and presenting them to forge causes the contract to fail and revert them.
-  const unresolvedItems = allItems.filter(item => {
-    const state = item.history?.[0]?.state ?? 'open';
-    return state === 'open' || state === 'rejected';
-  });
-  if (!io.exists('.foundry')) io.mkdir('.foundry');
-  const forgeItem = unresolvedItems.length > 0
-    ? ({
-      id: unresolvedItems[0].id,
-      file: unresolvedItems[0].file,
-      tag: unresolvedItems[0].tag,
-      text: unresolvedItems[0].text,
-      source: (typeof unresolvedItems[0].source === 'string'
-        ? unresolvedItems[0].source.split(':')[0]
-        : unresolvedItems[0].source),
-      sourceAlias: unresolvedItems[0].source,
-    })
-    : null;
-  const ctx = { forgePreVersion: preVersion, forgeItem };
-  io.writeFile(FORGE_CTX, JSON.stringify(ctx));
-}
-
-function countConsecutiveForgeFailures(io, cycleId) {
-  if (!io.exists('WORK.history.yaml')) return 0;
-  const entries = loadHistory('WORK.history.yaml', cycleId, io);
-  let count = 0;
-  for (let i = entries.length - 1; i >= 0; i--) {
-    if (stageBaseOf(entries[i].stage) !== 'forge') break;
-    if (entries[i].contract_passed === false) count++;
-    else break;
-  }
-  return count;
-}
-
-function checkConsecutiveFailures(contractPassed, io, cycleId) {
-  if (!contractPassed) {
-    return countConsecutiveForgeFailures(io, cycleId) + 1 >= 3;
-  }
-  return false;
-}
-
-async function enforceForgeStage(forgeCtx, fgResult, cycleId, io, cwd) {
-  const postVersion = await computeArtefactVersion('foundry', fgResult.outputType, io, cwd);
-  const feedbackStore = openFeedbackStore('WORK.feedback.yaml', io);
-  const lastStage = readLastStage(io);
-  const summary = (lastStage && lastStage.summary) || '';
-  const item = forgeCtx.forgeItem || null;
-
-  const { contractPassed } = enforceForgeContract({
-    item,
-    preVersion: forgeCtx.forgePreVersion,
-    postVersion,
-    summary,
-    feedbackStore,
-    cycleId,
-  });
-
-  if (checkConsecutiveFailures(contractPassed, io, cycleId)) {
-    return { violation: 'forge contract failed 3 consecutive times — unable to satisfy feedback requirements' };
-  }
-  return { postVersion, contractPassed };
-}
-
 async function handleQuenchRoute(sortResult, preCheck, args, io) {
   writeStageRecord(io, preCheck.cycleId, sortResult.route);
   const quenchCtx = buildQuenchContext(preCheck.cycleId, args, io);
@@ -269,7 +201,7 @@ export async function runOrchestrate(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)
+  // Only flag orphaned stage when not on consolidation path
   if (args.lastResults === undefined) return guardOrphanedStage(activeStage, args.lastResult);
   return null;
 }
@@ -305,25 +237,11 @@ async function runSetupIfNeeded(preCheck, args, io) {
   return err || setupWorkfile(buildSetupArgs(preCheck, args, io));
 }
 
-async function runForgePostDispatch(args, activeStage, lastStage, cycleId, io) {
-  const fgResult = await readForgeFilePatterns(cycleId, io);
-  const base = { lastStage, activeStage, cycleId, io, finalize: args.finalize, git: args.git };
-  if (!fgResult) return finaliseStage(base);
-  if (!io.exists(FORGE_CTX)) return finaliseStage(base);
-  const forgeCtx = JSON.parse(io.readFile(FORGE_CTX));
-  io.unlink(FORGE_CTX);
-  const result = await enforceForgeStage(forgeCtx, fgResult, cycleId, io, args.cwd);
-  if (result.violation) return violation(result.violation, []);
-  return finaliseStage({ ...base, postVersion: result.postVersion, contractPassed: result.contractPassed });
-}
-
 async function runPostDispatch(args, activeStage, lastStage, cycleId, io) {
   if (!args.lastResult) return null;
   if (args.lastResult.ok === false) {
     return handleViolation({ lastResult: args.lastResult, activeStage, lastStage, cycleId, io });
   }
-  const stageErr = guardMissingLastStage(lastStage);
-  if (stageErr) return stageErr;
-  if (stageBaseOf(lastStage.stage) === 'forge') return runForgePostDispatch(args, activeStage, lastStage, cycleId, io);
-  return finaliseStage({ lastStage, activeStage, cycleId, io, finalize: args.finalize, git: args.git });
+  if (guardMissingLastStage(lastStage)) return guardMissingLastStage(lastStage);
+  return routePostDispatchStage(stageBaseOf(lastStage.stage), { args, activeStage, lastStage, cycleId, io });
 }