@really-knows-ai/foundry 3.5.9 → 3.6.1

package/dist/scripts/lib/sort-routing.js

@@ -2,17 +2,10 @@
  * Sort routing helpers — pure functions that decide the next stage given
  * the current stage list, history, feedback, and iteration counters.
  *
- * Extracted from `src/scripts/sort.js` to keep that file under the
- * configured `max-lines` limit and to lower per-function complexity.
+ * Replaced the handler-dispatch pattern with a state-driven decision tree
+ * that routes based on feedback item state, history, and the stage list.
  */
 
-// An item is "open" (still in flight) when its head state is not
-// 'resolved' or 'deadlocked'. The deadlocked check is retained for
-// backward compatibility with existing feedback files.
-const isOpenItem = (f) => f.state !== 'resolved' && f.state !== 'deadlocked';
-
-export { isOpenItem };
-
 export function baseStage(stage) {
   return stage.split(':')[0];
 }
@@ -24,7 +17,10 @@ export function findFirst(stages, base) {
   return null;
 }
 
-export function nextInRoute(stages, current) {
+/**
+ * Returns the next stage in `stages` after `current`, or null if at the end.
+ */
+export function nextStageInChain(stages, current) {
   const idx = stages.indexOf(current);
   if (idx !== -1 && idx + 1 < stages.length) {
     return stages[idx + 1];
@@ -32,150 +28,198 @@ export function nextInRoute(stages, current) {
   return null;
 }
 
-function hasItemsNeedingForge(openItems) {
-  return openItems.some(f => f.state === 'open' || f.state === 'rejected');
+/**
+ * Returns the first stage in `stages` whose base matches `base`, with
+ * a fallback for `human-appraise`. For `human-appraise`, if no exact
+ * match is found, falls back to `human-appraise:<cycle>`.
+ */
+export function first(base, stages, cycle) {
+  if (base === 'human-appraise') {
+    const stage = findFirst(stages, 'human-appraise');
+    return stage !== null ? stage : `human-appraise:${cycle}`;
+  }
+  return findFirst(stages, base);
 }
 
-function hasItemsPendingApproval(openItems) {
-  return openItems.some(f => f.state === 'actioned' || f.state === 'wont-fix');
+/**
+ * Returns the first stage in `stages` whose base appears after `base`
+ * in the canonical chain order [forge, quench, appraise, human-appraise].
+ * Returns null if base is not in the canonical order or no subsequent
+ * stage is configured.
+ */
+export function firstAfter(stages, base) {
+  const canon = ['forge', 'quench', 'appraise', 'human-appraise'];
+  const baseIdx = canon.indexOf(base);
+  if (baseIdx === -1) return null;
+  for (let i = baseIdx + 1; i < canon.length; i++) {
+    const found = findFirst(stages, canon[i]);
+    if (found !== null) return found;
+  }
+  return null;
 }
 
-function firstForgeOrBlocked(stages) {
-  const stage = findFirst(stages, 'forge');
-  return stage !== null ? stage : 'blocked';
+/**
+ * Returns true when a stage with the given base exists in `stages`.
+ */
+export function hasStage(stages, base) {
+  return findFirst(stages, base) !== null;
 }
 
-function nextRouteOrDone(stages, current) {
-  const nextStage = nextInRoute(stages, current);
-  return nextStage !== null ? nextStage : 'done';
+/**
+ * Called after all unresolved and addressed items have been exhausted.
+ * Finds the next stage after `lastStage` via `nextStageInChain`.
+ * Returns 'done' if no next stage exists.
+ * Returns 'done' if the next stage is human-appraise and
+ * opts.alwaysHumanAppraise is false.
+ * Otherwise returns the next stage.
+ */
+export function forwardClean(stages, lastStage, opts = {}) {
+  const next = nextStageInChain(stages, lastStage);
+  if (next === null) return 'done';
+  if (baseStage(next) === 'human-appraise' && !opts.alwaysHumanAppraise) {
+    return 'done';
+  }
+  return next;
 }
 
-function firstHumanOrSuffixed(stages, cycle) {
-  const stage = findFirst(stages, 'human-appraise');
-  return stage !== null ? stage : `human-appraise:${cycle}`;
+// ---------------------------------------------------------------------------
+// Helpers extracted to keep determineRoute within complexity limits
+// ---------------------------------------------------------------------------
+
+/**
+ * Validates maxIterations, stages list, and history emptiness.
+ * Returns a route value when the input is terminal, or null to continue.
+ */
+function isValidMaxIterations(maxIterations) {
+  return typeof maxIterations === 'number' && Number.isInteger(maxIterations) && maxIterations >= 1;
 }
 
-function isBelowIterationCap(forgeCount, maxIterations, alwaysHumanAppraise) {
-  return alwaysHumanAppraise || forgeCount < maxIterations;
+function validateRoute(maxIterations, stages, history) {
+  if (!isValidMaxIterations(maxIterations)) return 'blocked';
+  if (!stages || stages.length === 0) return 'blocked';
+  if (history.length === 0) return stages[0];
+  return null;
 }
 
-function callHandlerOrBlocked(handler) {
-  return handler ? handler() : 'blocked';
+/**
+ * Extracts routing state from history and feedback: the last non-sort
+ * stage entry (full alias), its base stage name, forge iteration count,
+ * and categorised feedback items.
+ */
+function computeRoutingState(history, feedback) {
+  const nonSort = history.filter(e => baseStage(e.stage || '') !== 'sort');
+  const lastEntry = nonSort.length > 0 ? nonSort[nonSort.length - 1].stage : null;
+  const lastStage = lastEntry !== null ? baseStage(lastEntry) : null;
+  const forgeCount = history.filter(e =>
+    baseStage(e.stage || '') === 'forge' && e.contract_passed !== false,
+  ).length;
+  const unresolvedItems = feedback.filter(f => f.state === 'open' || f.state === 'rejected');
+  const addressedItems = feedback.filter(f => f.state === 'actioned' || f.state === 'wont-fix');
+  return { lastEntry, lastStage, forgeCount, unresolvedItems, addressedItems };
 }
 
-function routeForgeIfNeeded(stages, forgeCount, maxIterations, opts = {}) {
-  const { alwaysHumanAppraise, deadlockHumanAppraise, cycle } = opts;
-  if (isBelowIterationCap(forgeCount, maxIterations, alwaysHumanAppraise)) {
-    return firstForgeOrBlocked(stages);
+/**
+ * Checks whether the iteration cap has been reached.
+ * When the cap is reached and not bypassed by alwaysHumanAppraise,
+ * routes to human-appraise (if deadlockHumanAppraise) or 'blocked'.
+ * Otherwise routes to forge via first('forge', stages).
+ */
+function checkIterationAndRoute(firstFn, stages, forgeCount, maxIterations, opts) {
+  if (forgeCount >= maxIterations && !opts.alwaysHumanAppraise) {
+    if (opts.deadlockHumanAppraise) {
+      return firstFn('human-appraise', stages, opts.cycle);
+    }
+    return 'blocked';
   }
-  if (!deadlockHumanAppraise) return 'blocked';
-  if (!findFirst(stages, 'human-appraise')) return 'blocked';
-  return `human-appraise:${cycle}`;
+  if (!hasStage(stages, 'forge')) return 'blocked';
+  return firstFn('forge', stages);
 }
 
-function appraiseForgeOrApproval(stages, openItems, forgeCount, maxIterations, opts = {}) {
-  if (hasItemsNeedingForge(openItems)) {
-    return routeForgeIfNeeded(stages, forgeCount, maxIterations, opts);
-  }
-  if (hasItemsPendingApproval(openItems)) {
-    const stage = findFirst(stages, 'appraise');
-    return stage !== null ? stage : 'blocked';
+/**
+ * Collects unique source bases from addressed items and finds the
+ * earliest stage in the canonical chain that has a matching configured
+ * stage. Returns the resolved stage alias when found, or null to
+ * fall through to forwardClean.
+ */
+function routeAddressedItems(addressedItems, stages, opts) {
+  const sourceBases = [...new Set(addressedItems.map(i => baseStage(i.source)))];
+  const chain = ['quench', 'appraise', 'human-appraise'];
+  for (const base of chain) {
+    if (sourceBases.includes(base) && hasStage(stages, base)) {
+      return first(base, stages, opts.cycle);
+    }
   }
   return null;
 }
 
-function routeAlwaysHumanAppraise(stages, current, openItems, cycle) {
-  if (openItems.length > 0) {
-    return firstHumanOrSuffixed(stages, cycle);
-  }
-  return nextRouteOrDone(stages, current);
-}
-
-function decideAppraiseRoute(opts) {
-  const {
-    stages, current, openItems, forgeCount, maxIterations,
-    alwaysHumanAppraise, deadlockHumanAppraise, cycle,
-  } = opts;
-  const decided = appraiseForgeOrApproval(
-    stages, openItems, forgeCount, maxIterations,
-    { alwaysHumanAppraise, deadlockHumanAppraise, cycle },
-  );
-  if (decided !== null) return decided;
-  return nextRouteOrDone(stages, current);
-}
-
-export function nextAfterAppraise({
-  stages, current, feedback, forgeCount, maxIterations,
-  alwaysHumanAppraise = false, deadlockHumanAppraise = false, cycle = 'default',
-}) {
-  const openItems = feedback.filter(isOpenItem);
-  if (alwaysHumanAppraise) {
-    return routeAlwaysHumanAppraise(stages, current, openItems, cycle);
-  }
-  return decideAppraiseRoute({
-    stages, current, openItems, forgeCount, maxIterations,
-    alwaysHumanAppraise, deadlockHumanAppraise, cycle,
-  });
+/**
+ * Routes addressed items to their earliest source stage, falling through
+ * to forwardClean when no source matches or no addressed items exist.
+ */
+function routeAddressedOrForward(addressedItems, stages, lastEntry, opts) {
+  const routed = routeAddressedItems(addressedItems, stages, opts);
+  if (routed !== null) return routed;
+  return forwardClean(stages, lastEntry, opts);
 }
 
-export function nextAfterQuench(stages, current, feedback, opts = {}) {
-  const { forgeCount = 0, maxIterations = 100 } = opts;
-  const openItems = feedback.filter(isOpenItem);
-  const needsForge = hasItemsNeedingForge(openItems);
-  if (needsForge) return routeForgeIfNeeded(stages, forgeCount, maxIterations, opts);
-  return nextRouteOrDone(stages, current);
+/**
+ * Handles the R7 case when the last non-sort history entry is forge.
+ * If unresolved items exist, delegates to checkIterationAndRoute.
+ * If clean, routes via firstAfter to the first evaluation stage,
+ * or 'done' if no stage follows forge.
+ */
+function handleForgeJustRan(stages, unresolvedItems, forgeCount, maxIterations, opts) {
+  if (unresolvedItems.length > 0) {
+    return checkIterationAndRoute(first, stages, forgeCount, maxIterations, opts);
+  }
+  const next = firstAfter(stages, 'forge');
+  return next !== null ? next : 'done';
 }
 
-function lastNonSortStage(history) {
-  const nonSort = history.filter(e => baseStage(e.stage || '') !== 'sort');
-  if (nonSort.length === 0) return null;
-  return nonSort[nonSort.length - 1].stage;
-}
-
-function buildRouteHandlers({
-  stages, lastEntry, feedback, forgeCount, maxIterations,
-  alwaysHumanAppraise, deadlockHumanAppraise, cycle,
-}) {
-  const appraiseRoute = () => nextAfterAppraise({
-    stages, current: lastEntry, feedback, forgeCount, maxIterations,
-    alwaysHumanAppraise, deadlockHumanAppraise, cycle,
-  });
-  return {
-    'assay': () => firstForgeOrBlocked(stages),
-    'forge': () => nextRouteOrDone(stages, lastEntry),
-    'quench': () => nextAfterQuench(
-      stages, lastEntry, feedback,
-      { forgeCount, maxIterations, alwaysHumanAppraise, deadlockHumanAppraise, cycle },
-    ),
-    'appraise': appraiseRoute,
-    'human-appraise': appraiseRoute,
-  };
-}
-
-function countForgeIterations(history) {
-  return history.filter(e => baseStage(e.stage || '') === 'forge').length;
-}
-
-function routeFromLastEntry(opts) {
-  const {
-    stages, lastEntry, feedback, forgeCount, maxIterations,
-    alwaysHumanAppraise, deadlockHumanAppraise, cycle,
-  } = opts;
-  if (lastEntry === null) return stages[0];
-  const handlers = buildRouteHandlers({
-    stages, lastEntry, feedback, forgeCount, maxIterations,
-    alwaysHumanAppraise, deadlockHumanAppraise, cycle,
-  });
-  const handler = handlers[baseStage(lastEntry)];
-  return callHandlerOrBlocked(handler);
+/**
+ * Handles R1 (unresolved, addressed) and R2 (forward) routing paths.
+ * Extracted to keep determineRoute within the complexity limit.
+ */
+function routeFeedbackState(state, stages, maxIterations, opts) {
+  if (state.unresolvedItems.length > 0) {
+    return checkIterationAndRoute(first, stages, state.forgeCount, maxIterations, opts);
+  }
+  if (state.addressedItems.length > 0) {
+    return routeAddressedOrForward(state.addressedItems, stages, state.lastEntry, opts);
+  }
+  return forwardClean(stages, state.lastEntry, opts);
 }
 
+// ---------------------------------------------------------------------------
+// determineRoute — state-driven decision tree
+// ---------------------------------------------------------------------------
+
+/**
+ * Determines the next route given the current cycle state.
+ *
+ * The decision tree reads feedback item state, history, and the stage
+ * list to route to forge, an evaluation stage, human-appraise, 'done',
+ * or 'blocked'. It never calls computeArtefactVersion and does not
+ * read item.artefact_version.
+ *
+ * @param {string[]} stages - Configured stage aliases in chain order
+ * @param {object[]} history - Cycle history entries
+ * @param {object[]} feedback - Feedback items with state, source, etc.
+ * @param {number} maxIterations - Maximum forge iterations
+ * @param {object} [opts] - Options object
+ * @param {boolean} [opts.alwaysHumanAppraise=false]
+ * @param {boolean} [opts.deadlockHumanAppraise=false]
+ * @param {string} [opts.cycle='default']
+ * @returns {string} Next route: stage alias, 'done', or 'blocked'
+ */
 export function determineRoute(stages, history, feedback, maxIterations, opts = {}) {
-  const { alwaysHumanAppraise = false, deadlockHumanAppraise = false, cycle = 'default' } = opts;
-  const forgeCount = countForgeIterations(history);
-  const lastEntry = lastNonSortStage(history);
-  return routeFromLastEntry({
-    stages, lastEntry, feedback, forgeCount, maxIterations,
-    alwaysHumanAppraise, deadlockHumanAppraise, cycle,
-  });
+  const validation = validateRoute(maxIterations, stages, history);
+  if (validation !== null) return validation;
+
+  const state = computeRoutingState(history, feedback);
+
+  if (state.lastStage === null) return stages[0];
+  if (state.lastStage === 'forge') return handleForgeJustRan(stages, state.unresolvedItems, state.forgeCount, maxIterations, opts);
+
+  return routeFeedbackState(state, stages, maxIterations, opts);
 }

package/dist/scripts/lib/workfile.js

@@ -121,3 +121,31 @@ export function createWorkfile(frontmatter, goal) {
 ${goal}
 `;
 }
+
+/**
+ * Build a forge history entry options object for appendEntry.
+ *
+ * The returned object includes changedFiles (camelCase), artefact_version,
+ * and contract_passed. appendEntry/buildEntry handle sorting changedFiles,
+ * converting to changed_files in YAML, and setting timestamp/seq.
+ *
+ * @param {{ cycle: string, stage: string, iteration: number, comment: string,
+ *   artefactVersion: string, contractPassed: boolean,
+ *   changedFiles: string[] }} params
+ * @returns {{ cycle: string, stage: string, iteration: number,
+ *   comment: string, changedFiles: string[], artefact_version: string,
+ *   contract_passed: boolean }}
+ */
+export function buildForgeHistoryEntry(
+  { cycle, stage, iteration, comment, artefactVersion, contractPassed, changedFiles },
+) {
+  return {
+    cycle,
+    stage,
+    iteration,
+    comment,
+    changedFiles,
+    artefact_version: artefactVersion,
+    contract_passed: contractPassed,
+  };
+}

package/dist/scripts/orchestrate-phases.js

@@ -6,11 +6,12 @@ import {
   getCycleDefinition,
   getLawsForQuench,
 } from './lib/config.js';
-import { parseFrontmatter, writeFrontmatter } from './lib/workfile.js';
+import { parseFrontmatter, writeFrontmatter, buildForgeHistoryEntry } from './lib/workfile.js';
 import matter from 'gray-matter';
 import { clearActiveStage, clearLastStage } from './lib/state.js';
 import { appendEntry, getIteration } from './lib/history.js';
 import { stageBaseOf } from './lib/stage-guard.js';
+import { baseStage } from './lib/sort-routing.js';
 import { allowedPatternsForStage } from './lib/git-policy.js';
 import { loadExtractor } from './lib/assay/loader.js';
 import { checkExtractorAgainstCycle } from './lib/assay/permissions.js';
@@ -66,13 +67,9 @@ function isTerminalRoute(route) {
   return route === 'done' || route === 'blocked' || route === 'violation';
 }
 
-function getRouteBase(route) {
-  return routeDispatch(route);
-}
-
 export async function handleSortResult(sortResult, ctx) {
   const { route, model, token, reason } = sortResult;
-  const routeBase = getRouteBase(route);
+  const routeBase = routeDispatch(route);
   const result = await resolveRouteResult({ route, routeBase, model, token, ctx });
   if (reason !== undefined) result.reason = reason;
   return result;
@@ -85,10 +82,6 @@ async function resolveRouteResult({ route, routeBase, model, token, ctx }) {
   return buildDispatchAction(route, model, token, ctx);
 }
 
-async function fetchCycleDefinition(foundryDir, cycleId, io) {
-  try { return await getCycleDefinition(foundryDir, cycleId, io); } catch { return null; }
-}
-
 function checkOutputType(cfm, cycleId) {
   const outputType = cfm['output-type'];
   if (outputType) return { outputType };
@@ -103,7 +96,6 @@ async function checkArtefactType(foundryDir, outputType, io) {
   catch { return { error: violation(`artefact type not found: ${outputType}`, ['WORK.md']) }; }
 }
 
-function isAssayAbsent(assayBlock) { return assayBlock === undefined || assayBlock === null; }
 function isAssayInvalid(assayBlock) { return typeof assayBlock !== 'object' || Array.isArray(assayBlock); }
 
 function checkAssayExtractors(list, cycleId) {
@@ -115,7 +107,7 @@ function checkAssayExtractors(list, cycleId) {
 
 function checkAssayShape(cfm, cycleId) {
   const assayBlock = cfm.assay;
-  if (isAssayAbsent(assayBlock)) return { ok: true, extractors: null };
+  if (assayBlock === undefined || assayBlock === null) return { ok: true, extractors: null };
   if (isAssayInvalid(assayBlock)) {
     return { error: violation(`cycle ${cycleId}: 'assay' must be a mapping`, ['WORK.md']) };
   }
@@ -124,13 +116,6 @@ function checkAssayShape(cfm, cycleId) {
   return { ok: true, extractors: assayBlock.extractors };
 }
 
-function checkMemoryEnabled(io, cycleId) {
-  if (!io.exists('foundry/memory/config.md')) {
-    return violation(`cycle ${cycleId}: 'assay:' requires memory to be enabled (run the init-memory skill first)`, ['WORK.md']);
-  }
-  return null;
-}
-
 function checkCycleWriteDecl(cfm, cycleId) {
   const cycleWrite = cfm.memory?.write;
   if (!Array.isArray(cycleWrite)) {
@@ -150,10 +135,6 @@ async function checkExtractors(foundryDir, cycleId, list, cycleWriteSet, io) {
   return null;
 }
 
-function stageTag(s, cycleId) {
-  return typeof s === 'string' && s.includes(':') ? s : `${s}:${cycleId}`;
-}
-
 function resolveStages(cfm, cycleId, hasValidation, assayExtractors) {
   if (!Array.isArray(cfm.stages)) {
     return synthesizeStages({ cycleId, hasValidation, alwaysHumanAppraise: cfm['always-human-appraise'] === true, assay: !!assayExtractors });
@@ -161,14 +142,14 @@ function resolveStages(cfm, cycleId, hasValidation, assayExtractors) {
   if (cfm.stages.length === 0) {
     return { error: violation(`cycle ${cycleId} has no stages declared in cycle definition`, ['WORK.md']) };
   }
-  return cfm.stages.map(s => stageTag(s, cycleId));
+  return cfm.stages.map(s => typeof s === 'string' && s.includes(':') ? s : `${s}:${cycleId}`);
 }
 
-function applyFmDefaults(newFm, cfm, assayExtractors) {
+export function applyFmDefaults(newFm, cfm, assayExtractors) {
   const maxIt = cfm['max-iterations'] ?? 3;
   newFm['max-iterations'] = maxIt;
   newFm['always-human-appraise'] = cfm['always-human-appraise'] === true;
-  newFm['deadlock-human-appraise'] = cfm['deadlock-human-appraise'] !== false;
+  newFm['deadlock-human-appraise'] = cfm['deadlock-human-appraise'] === true;
   if (cfm.models) newFm.models = cfm.models;
   if (assayExtractors) newFm.assay = { extractors: assayExtractors };
 }
@@ -184,8 +165,9 @@ function buildNewFrontmatter(workContent, stages, cfm, assayExtractors) {
 }
 
 async function checkAssayPrereqs(cfm, cycleId, io) {
-  const memErr = checkMemoryEnabled(io, cycleId);
-  if (memErr) return memErr;
+  if (!io.exists('foundry/memory/config.md')) {
+    return violation(`cycle ${cycleId}: 'assay:' requires memory to be enabled (run the init-memory skill first)`, ['WORK.md']);
+  }
   return checkCycleWriteDecl(cfm, cycleId);
 }
 
@@ -203,7 +185,7 @@ async function runAssayValidation(cfm, cycleId, io, foundryDir) {
 
 export async function setupWorkfile(args) {
   const { cycleId, workContent, io, git, foundryDir } = args;
-  const cycleDefDoc = await fetchCycleDefinition(foundryDir, cycleId, io);
+  const cycleDefDoc = await getCycleDefinition(foundryDir, cycleId, io).catch(() => null);
   if (!cycleDefDoc) return violation(`cycle definition not found for id: ${cycleId}`, ['WORK.md']);
   const cfm = cycleDefDoc.frontmatter || {};
   return runSetupPipeline({ cfm, cycleId, workContent, io, git, foundryDir });
@@ -238,10 +220,6 @@ async function trySetupCommit(ctx) {
   return { ok: true, workContent: ctx.io.readFile('WORK.md') };
 }
 
-function readOriginalState(io) {
-  return { workMd: io.readFile('WORK.md'), history: io.exists('WORK.history.yaml') ? io.readFile('WORK.history.yaml') : null };
-}
-
 function buildFinalizeViolation(finalizeResult) {
   if (finalizeResult.error === 'unexpected_files') {
     return violation(`unexpected files written by subagent: ${(finalizeResult.files || []).join(', ')}`, finalizeResult.files || []);
@@ -249,9 +227,32 @@ function buildFinalizeViolation(finalizeResult) {
   return violation(`stage_finalize error: ${finalizeResult.error}`, []);
 }
 
+function buildStageEntryBase(ctx) {
+  const summary = ctx.lastStage.summary || '(no summary)';
+  const changed = ctx.lastStage.changedFiles ?? [];
+  return { 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,
+      })
+      : {}),
+  };
+}
+
 function writeHistoryEntries(ctx) {
-  appendEntry(ctx.historyPath, { cycle: ctx.cycleId, stage: 'sort', iteration: ctx.iteration, route: ctx.lastStage.stage, comment: `route ${ctx.lastStage.stage}`, openFeedback: ctx.openFeedback }, ctx.io);
-  appendEntry(ctx.historyPath, { cycle: ctx.cycleId, stage: ctx.lastStage.stage, iteration: ctx.iteration, comment: ctx.lastStage.summary || '(no summary)', openFeedback: ctx.openFeedback, changedFiles: ctx.lastStage.changedFiles ?? [] }, ctx.io);
+  appendEntry(ctx.historyPath, {
+    cycle: ctx.cycleId, stage: 'sort', iteration: ctx.iteration,
+    route: ctx.lastStage.stage,
+    comment: `route ${ctx.lastStage.stage}`,
+    openFeedback: ctx.openFeedback,
+  }, ctx.io);
+  appendEntry(ctx.historyPath, buildStageEntryBase(ctx), ctx.io);
 }
 
 async function computeAllowedPatterns(lastStage, cycleId, io) {
@@ -286,12 +287,18 @@ function clearStageState(activeStage, lastStage, io) {
 }
 
 export async function finaliseStage(args) {
-  const { lastStage, activeStage, cycleId, io, finalize, git } = args;
-  const original = readOriginalState(io);
+  const { lastStage, activeStage, cycleId, io, finalize, git, postVersion, contractPassed } = args;
+  const original = {
+    workMd: io.readFile('WORK.md'),
+    history: io.exists('WORK.history.yaml') ? io.readFile('WORK.history.yaml') : null,
+  };
   if (typeof finalize !== 'function') {
     return violation('orchestrate caller must inject a `finalize` function when providing lastResult; the plugin wires lib/finalize.finalizeStage; tests must pass a stub.', []);
   }
-  const finalizeResult = await finalize({ cycleId, stage: lastStage.stage, baseSha: lastStage.baseSha, io });
+  const finalizeResult = await finalize({
+    cycleId, stage: lastStage.stage, baseSha: lastStage.baseSha, io,
+    artefact_version: postVersion, contractPassed,
+  });
   if (!finalizeResult.ok) {
     clearStageState(activeStage, null, io);
     return buildFinalizeViolation(finalizeResult);
@@ -299,7 +306,12 @@ export async function finaliseStage(args) {
   const historyPath = 'WORK.history.yaml';
   const iteration = getIteration(historyPath, cycleId, io);
   const openFeedback = computeOpenFeedback(io);
-  writeHistoryEntries({ historyPath, cycleId, lastStage, iteration, openFeedback, io });
+  writeHistoryEntries({
+    historyPath, cycleId,
+    lastStage: { ...lastStage, changedFiles: finalizeResult.changedFiles },
+    iteration, openFeedback, io,
+    artefactVersion: postVersion, contractPassed,
+  });
   const commitErr = await tryStageCommit(git, lastStage, cycleId, io);
   if (commitErr) {
     rollbackState(io, original);

package/dist/scripts/orchestrate-terminals.js

@@ -1,6 +1,8 @@
 import { getCycleDefinition } from './lib/config.js';
-import { getArtefactFiles } from './lib/artefacts.js';
+import { getArtefactFiles, computeArtefactVersion } from './lib/artefacts.js';
 import { readCycleTargets, readRecentFeedback, violation } from './orchestrate-cycle.js';
+import { openFeedbackStore } from './lib/feedback-store.js';
+import { baseStage } from './lib/sort-routing.js';
 
 async function findOutputArtefacts(cfm, io, foundryDir, baseBranch) {
   const outputType = cfm ? cfm['output-type'] : undefined;
@@ -29,15 +31,48 @@ export async function blockedAction(cycleId, io, details, foundryDir, baseBranch
 }
 
 export async function humanAppraiseAction(route, token, ctx) {
-  const { cycleId, io, baseBranch } = ctx;
+  const { cycleId, io, baseBranch, cwd } = ctx;
   const fd = ctx.foundryDir || 'foundry';
   const base = baseBranch || 'main';
   const cfm = (await getCycleDefinition(fd, cycleId, io)).frontmatter;
+
+  try {
+    await resolveStaleHumanAppraiseFeedback(cfm, fd, io, cycleId, cwd);
+  } catch (err) {
+    return { action: 'violation', details: `version check failed: ${err.message}`, recoverable: false, affected_files: [] };
+  }
+
   const artefact = await findOutputArtefacts(cfm, io, fd, base);
   const artefactFile = artefact ? artefact.file : null;
   return { action: 'human_appraise', stage: route, token, context: { cycle: cycleId, artefact_file: artefactFile, recent_feedback: readRecentFeedback(io) } };
 }
 
+/**
+ * Resolve stale human-appraise feedback. Errors propagate to the caller
+ * (humanAppraiseAction) which surfaces them as a violation.
+ */
+async function resolveStaleHumanAppraiseFeedback(cfm, fd, io, cycleId, cwd) {
+  const outputType = cfm['output-type'];
+  if (!outputType) return;
+  const store = openFeedbackStore('WORK.feedback.yaml', io);
+  const currentVersion = await computeArtefactVersion(fd, outputType, io, cwd);
+  for (const item of store.list()) {
+    if (shouldSkipHumanAppraiseResolve(item, currentVersion)) continue;
+    store.autoResolve({
+      id: item.id,
+      reason: `superseded by forge revision ${currentVersion}`,
+      cycle: cycleId,
+    });
+  }
+}
+
+function shouldSkipHumanAppraiseResolve(item, currentVersion) {
+  if (item.history[0].state === 'resolved') return true;
+  if (baseStage(item.source) !== 'human-appraise') return true;
+  if (item.artefact_version === currentVersion) return true;
+  return false;
+}
+
 export async function missingModelViolation(cycleId, route, io, foundryDir, baseBranch) {
   const fd = foundryDir || 'foundry';
   const base = baseBranch || 'main';