@really-knows-ai/foundry 3.5.8 → 3.6.0

package/dist/scripts/lib/history.js

@@ -78,7 +78,7 @@ function validateAppendArgs({ iteration, comment, route, stage }) {
   }
 }
 
-function buildEntry({ cycle, stage, iteration, comment, route, openFeedback, changedFiles }, seq) {
+function buildEntry({ cycle, stage, iteration, comment, route, openFeedback, changedFiles, ...rest }, seq) {
   const entry = {
     cycle,
     stage,
@@ -87,6 +87,7 @@ function buildEntry({ cycle, stage, iteration, comment, route, openFeedback, cha
     timestamp: new Date().toISOString(),
     seq,
     open_feedback: openFeedback ?? 0,
+    ...rest,
   };
   if (route !== undefined) entry.route = route;
   if (changedFiles !== undefined) {

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

@@ -18,18 +18,19 @@ export function reasonForRoute(route, prep) {
 
 function buildReasonData(route, prep) {
   const base = baseStage(route);
-  const forgeCount = prep.history.filter(e => baseStage(e.stage || '') === 'forge').length;
+  const forgeCount = prep.history.filter(e =>
+    baseStage(e.stage || '') === 'forge' && e.contract_passed !== false,
+  ).length;
   const maxIt = prep.defaults.maxIterations;
   const feedback = prep.feedback || [];
-  const openCount = feedback.filter(
-    f => f.state !== 'resolved' && f.state !== 'deadlocked',
-  ).length;
-  const dlCount = feedback.filter(f => f.state === 'deadlocked').length;
+  const openCount = feedback.filter(f => f.state !== 'resolved').length;
   const needingForge = feedback.filter(
     f => f.state === 'open' || f.state === 'rejected',
   ).length;
+  const alwaysHumanAppraise = prep.defaults.alwaysHumanAppraise;
+  const deadlockHumanAppraise = prep.defaults.deadlockHumanAppraise;
 
-  return { base, route, forgeCount, maxIt, openCount, dlCount, needingForge, anyDeadlocked: prep.anyDeadlocked };
+  return { base, route, forgeCount, maxIt, openCount, needingForge, alwaysHumanAppraise, deadlockHumanAppraise };
 }
 
 function forgeReason(d) {
@@ -38,12 +39,14 @@ function forgeReason(d) {
 }
 
 function appraiseReason(d) {
-  if (d.anyDeadlocked) return `${d.dlCount} feedback item(s) deadlocked — routing to appraise for re-evaluation`;
   return `quench passed with ${d.openCount} open feedback item(s) — routing to appraise`;
 }
 
 function humanAppraiseReason(d) {
-  return `${d.dlCount} feedback item(s) deadlocked after ${d.forgeCount} forge iteration(s) — routing to human for override`;
+  if (d.alwaysHumanAppraise) {
+    return `always-human-appraise enabled — routing to human after ${d.forgeCount} forge iteration(s)`;
+  }
+  return `max iterations (${d.maxIt}) reached after ${d.forgeCount} forge iteration(s) — routing to human for review`;
 }
 
 function blockedReason(d) {

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.
  */
 
-// Spec §6.1: an item is "open" (still in flight) when its head state is
-// 'open', 'actioned', 'rejected', or 'wont-fix' — equivalently, when the
-// state is neither 'resolved' nor 'deadlocked'.
-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,72 +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 routeForgeIfNeeded(stages, forgeCount, maxIterations) {
-  if (forgeCount >= maxIterations) return 'blocked';
-  return findFirst(stages, 'forge') ?? 'blocked';
+/**
+ * Returns true when a stage with the given base exists in `stages`.
+ */
+export function hasStage(stages, base) {
+  return findFirst(stages, base) !== null;
 }
 
-function appraiseForgeOrApproval(stages, openItems, forgeCount, maxIterations) {
-  if (hasItemsNeedingForge(openItems)) {
-    return routeForgeIfNeeded(stages, forgeCount, maxIterations);
+/**
+ * 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';
   }
-  if (hasItemsPendingApproval(openItems)) {
-    return findFirst(stages, 'appraise') ?? 'blocked';
+  return next;
+}
+
+// ---------------------------------------------------------------------------
+// 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 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;
+}
+
+/**
+ * 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 };
+}
+
+/**
+ * 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 (!hasStage(stages, 'forge')) return 'blocked';
+  return firstFn('forge', stages);
+}
+
+/**
+ * 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;
 }
 
-export function nextAfterAppraise({ stages, current, feedback, forgeCount, maxIterations }) {
-  // Note: deadlock detection is handled by runDeadlockPass at the top of
-  // runSort (spec §6.1). This helper assumes routing has already been allowed
-  // to fall through (i.e., no item qualifies as deadlocked).
-  const openItems = feedback.filter(isOpenItem);
-  const decided = appraiseForgeOrApproval(stages, openItems, forgeCount, maxIterations);
-  if (decided !== null) return decided;
-  return nextInRoute(stages, current) ?? 'done';
+/**
+ * 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, forgeCount, maxIterations) {
-  const openItems = feedback.filter(isOpenItem);
-  const needsForge = openItems.some(f => f.state === 'open' || f.state === 'rejected');
-  if (needsForge) return routeForgeIfNeeded(stages, forgeCount, maxIterations);
-  return nextInRoute(stages, current) ?? 'done';
+/**
+ * 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 }) {
-  const appraiseRoute = () => nextAfterAppraise({
-    stages, current: lastEntry, feedback, forgeCount, maxIterations,
-  });
-  return {
-    'assay': () => findFirst(stages, 'forge') ?? 'blocked',
-    'forge': () => nextInRoute(stages, lastEntry) ?? 'done',
-    'quench': () => nextAfterQuench(stages, lastEntry, feedback, forgeCount, maxIterations),
-    'appraise': appraiseRoute,
-    'human-appraise': appraiseRoute,
-  };
-}
-
-export function determineRoute(stages, history, feedback, maxIterations) {
-  const forgeCount = history.filter(e => baseStage(e.stage || '') === 'forge').length;
-  const lastEntry = lastNonSortStage(history);
-  if (lastEntry === null) return stages[0];
-  const handlers = buildRouteHandlers({
-    stages, lastEntry, feedback, forgeCount, maxIterations,
-  });
-  const handler = handlers[baseStage(lastEntry)];
-  return handler ? handler() : 'blocked';
+/**
+ * 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 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-cycle.js

@@ -150,13 +150,13 @@ export function tryCommit(git, message, allowedPatterns, phase) {
 // Stage synthesis (pure utility, used by setupWorkfile and exported publicly).
 // ---------------------------------------------------------------------------
 
-export function synthesizeStages({ cycleId, hasValidation, humanAppraise, assay = false }) {
+export function synthesizeStages({ cycleId, hasValidation, alwaysHumanAppraise, assay = false }) {
   const stages = [];
   if (assay) stages.push(`assay:${cycleId}`);
   stages.push(`forge:${cycleId}`);
   if (hasValidation) stages.push(`quench:${cycleId}`);
   stages.push(`appraise:${cycleId}`);
-  if (humanAppraise) stages.push(`human-appraise:${cycleId}`);
+  if (alwaysHumanAppraise) stages.push(`human-appraise:${cycleId}`);
   return stages;
 }
 
@@ -273,14 +273,4 @@ export function renderDispatchPrompt({ stage, cycle, token, cwd, filePatterns, o
   return lines.join('\n');
 }
 
-export function checkIterationLimits(cfm, cycleId) {
-  const maxIt = cfm['max-iterations'];
-  const dlIt = cfm['deadlock-iterations'];
-  if (maxIt !== undefined && dlIt !== undefined && dlIt > maxIt) {
-    return violation(
-      `cycle ${cycleId}: deadlock-iterations (${dlIt}) cannot exceed max-iterations (${maxIt})`,
-      ['WORK.md'],
-    );
-  }
-  return null;
-}
+

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';
@@ -21,7 +22,6 @@ import {
   tryCommit,
   synthesizeStages,
   renderDispatchPrompt,
-  checkIterationLimits,
 } from './orchestrate-cycle.js';
 import {
   doneAction,
@@ -67,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;
@@ -86,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 };
@@ -104,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) {
@@ -116,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']) };
   }
@@ -125,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)) {
@@ -151,26 +135,21 @@ 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, humanAppraise: cfm['human-appraise'] === true, assay: !!assayExtractors });
+    return synthesizeStages({ cycleId, hasValidation, alwaysHumanAppraise: cfm['always-human-appraise'] === true, assay: !!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['human-appraise'] = cfm['human-appraise'] === true;
-  newFm['deadlock-appraise'] = cfm['deadlock-appraise'] !== false;
-  newFm['deadlock-iterations'] = cfm['deadlock-iterations'] ?? maxIt;
+  newFm['always-human-appraise'] = cfm['always-human-appraise'] === true;
+  newFm['deadlock-human-appraise'] = cfm['deadlock-human-appraise'] === true;
   if (cfm.models) newFm.models = cfm.models;
   if (assayExtractors) newFm.assay = { extractors: assayExtractors };
 }
@@ -186,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);
 }
 
@@ -205,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 });
@@ -226,8 +206,6 @@ async function completeSetup(ctx) {
   const hasValidation = ctx.lawsWithValidators && ctx.lawsWithValidators.length > 0;
   const stagesResult = resolveStages(ctx.cfm, ctx.cycleId, hasValidation, ctx.assayResult.extractors);
   if (stagesResult.error) return stagesResult.error;
-  const validityErr = checkIterationLimits(ctx.cfm, ctx.cycleId);
-  if (validityErr) return validityErr;
   const newWork = buildNewFrontmatter(ctx.workContent, stagesResult, ctx.cfm, ctx.assayResult.extractors);
   ctx.io.writeFile('WORK.md', newWork);
   return trySetupCommit(ctx);
@@ -242,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 || []);
@@ -253,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) {
@@ -290,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);
@@ -303,7 +306,10 @@ 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, iteration, openFeedback, io,
+    artefactVersion: postVersion, contractPassed,
+  });
   const commitErr = await tryStageCommit(git, lastStage, cycleId, io);
   if (commitErr) {
     rollbackState(io, original);