@really-knows-ai/foundry 3.5.9 → 3.6.0

package/dist/scripts/orchestrate.js

@@ -8,6 +8,9 @@ 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 {
   readCycleTargets,
   readForgeFilePatterns,
@@ -138,7 +141,10 @@ 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 });
+      return store.add({
+        file: item.file, tag: item.tag, text: item.text, source: stageId, cycle: cycleId,
+        artefact_version: item.artefact_version,
+      });
     },
     list: (query) => {
       const store = openFeedbackStore('WORK.feedback.yaml', io);
@@ -159,7 +165,7 @@ 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',
+    baseBranch: args.baseBranch ?? 'main', cwd: args.cwd ?? process.cwd(),
     feedback: buildFeedback(cycleId, stageId, io) };
 }
 
@@ -167,7 +173,7 @@ 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',
+    baseBranch: args.baseBranch ?? 'main', cwd: args.cwd ?? process.cwd(),
     activeStage: readActiveStage(io), lastStage: readLastStage(io),
     feedback: buildFeedback(cycleId, stageId, io) };
 }
@@ -184,6 +190,42 @@ 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 items = openFeedbackStore('WORK.feedback.yaml', io).list();
+  if (!io.exists('.foundry')) io.mkdir('.foundry');
+  io.writeFile(FORGE_CTX, JSON.stringify({ forgePreVersion: preVersion, forgeItems: items.map(i => ({ id: i.id })) }));
+}
+
+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;
+}
+
+async function enforceForgeStage(activeStage, fgResult, cycleId, io, cwd) {
+  const postVersion = await computeArtefactVersion('foundry', fgResult.outputType, io, cwd);
+  const feedbackStore = openFeedbackStore('WORK.feedback.yaml', io);
+  const { contractPassed } = enforceForgeContract({
+    items: activeStage.forgeItems, preVersion: activeStage.forgePreVersion,
+    postVersion, feedbackStore, cycleId,
+  });
+  if (!contractPassed && countConsecutiveForgeFailures(io, cycleId) + 1 >= 3) {
+    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);
@@ -230,6 +272,7 @@ async function dispatchByRoute(sortResult, args, preCheck, io) {
       ? handleAppraiseConsolidateRoute(sortResult, preCheck, args, io)
       : handleAppraiseGatherRoute(sortResult, preCheck, args, io);
   }
+  if (base === 'forge') await captureForgeContext(sortResult, args, preCheck, io);
   return handleSortResult(sortResult, buildSortContext(preCheck.cycleId, args, io));
 }
 
@@ -278,12 +321,26 @@ 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);
+  if (!forgeCtx.forgePreVersion) return finaliseStage(base);
+  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);
-  const finaliseArgs = { lastStage, activeStage, cycleId, io, finalize: args.finalize ?? null, git: args.git };
-  return stageErr || finaliseStage(finaliseArgs);
+  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 });
 }

package/dist/scripts/quench-module.js

@@ -8,9 +8,46 @@
  */
 
 import { readActiveStage } from './lib/state.js';
-import { getArtefactFiles } from './lib/artefacts.js';
+import { getArtefactFiles, computeArtefactVersion } from './lib/artefacts.js';
 import { getCycleDefinition } from './lib/config.js';
 import { performValidation } from './lib/validation.js';
+import { openFeedbackStore } from './lib/feedback-store.js';
+
+/**
+ * Resolve stale feedback items whose artefact version does not match the
+ * current on-disk version. Items from this stage's source base with a
+ * mismatched artefact_version are auto-resolved as superseded.
+ */
+export async function resolveStaleFeedback(items, currentVersion, stageBase, feedback, cycle) {
+  for (const item of items) {
+    if (shouldSkipStaleResolve(item, currentVersion, stageBase)) continue;
+    const reason = `superseded by forge revision ${currentVersion}`;
+    feedback.autoResolve({ id: item.id, reason, cycle });
+  }
+}
+
+function shouldSkipStaleResolve(item, currentVersion, stageBase) {
+  if (item.history[0].state === 'resolved') return true;
+  const itemBase = typeof item.source === 'string' ? item.source.split(':')[0] : '';
+  if (itemBase !== stageBase) return true;
+  if (item.artefact_version === currentVersion) return true;
+  return false;
+}
+
+/**
+ * Resolve stale quench-sourced feedback. Errors propagate to the caller
+ * (runQuench) which surfaces them as a failure.
+ */
+async function resolveStaleQuenchFeedback(ctx, outputType) {
+  try {
+    const store = openFeedbackStore('WORK.feedback.yaml', ctx.io);
+    const currentVersion = await computeArtefactVersion(ctx.foundryDir, outputType, ctx.io, ctx.cwd);
+    resolveStaleFeedback(store.list(), currentVersion, 'quench', store, ctx.cycleId);
+  } catch {
+    // Graceful degrade — stale resolution is best-effort.
+    // The orchestrator handles IO failures at the cycle level.
+  }
+}
 
 /**
  * Run quench (deterministic validation) for a cycle.
@@ -30,15 +67,20 @@ export async function runQuench(ctx) {
     return { ok: false, error: `Cycle ${ctx.cycleId} has no output-type` };
   }
 
+  return await runQuenchWithStale(ctx, activeStageRecord, outputType);
+}
+
+async function runQuenchWithStale(ctx, activeStageRecord, outputType) {
+  await resolveStaleQuenchFeedback(ctx, outputType);
+  const artefactVersion = await computeArtefactVersion(
+    ctx.foundryDir, outputType, ctx.io, ctx.cwd,
+  ).catch(() => undefined);
   const discovery = await discoverArtefacts(ctx, outputType);
   if (!discovery.ok) return discovery;
-  const artefacts = discovery.artefacts;
-
-  if (artefacts.length === 0) {
+  if (discovery.artefacts.length === 0) {
     return await handleNoArtefacts(ctx, activeStageRecord);
   }
-
-  return await processArtefacts(ctx, artefacts, activeStageRecord, outputType);
+  return await processArtefacts(ctx, discovery.artefacts, activeStageRecord, outputType, artefactVersion);
 }
 
 async function discoverArtefacts(ctx, outputType) {
@@ -65,7 +107,7 @@ async function handleNoArtefacts(ctx, activeStageRecord) {
 /**
  * Process each artefact: run validation, post feedback, handle errors.
  */
-async function processArtefacts(ctx, artefacts, activeStageRecord, outputType) {
+async function processArtefacts(ctx, artefacts, activeStageRecord, outputType, artefactVersion) {
   const perArtefact = [];
   const currentFeedback = [];
   let allOk = true;
@@ -78,7 +120,7 @@ async function processArtefacts(ctx, artefacts, activeStageRecord, outputType) {
       artefacts: [artefact],
     });
 
-    const outcome = handleArtefactResult(ctx, artefact, result, currentFeedback);
+    const outcome = handleArtefactResult(ctx, artefact, result, currentFeedback, artefactVersion);
     perArtefact.push(outcome.text);
     if (!outcome.ok) allOk = false;
   }
@@ -103,7 +145,7 @@ async function processArtefacts(ctx, artefacts, activeStageRecord, outputType) {
  * 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) {
+function handleArtefactResult(ctx, artefact, result, currentFeedback, artefactVersion) {
   if (isNoValidators(result)) {
     return { ok: true, text: `${artefact.file}: OK: no validators` };
   }
@@ -117,7 +159,7 @@ function handleArtefactResult(ctx, artefact, result, currentFeedback) {
     return { ok: false, text: `${artefact.file}: ${messages}` };
   }
 
-  postFeedbackItems(ctx, artefact, result, currentFeedback);
+  postFeedbackItems(ctx, artefact, result, currentFeedback, artefactVersion);
   return { ok: true, text: `${artefact.file}: ${result.items.length} issues found` };
 }
 
@@ -138,10 +180,10 @@ function isAllErrors(result) {
 /**
  * Post feedback items for validation results and track for resolution.
  */
-function postFeedbackItems(ctx, artefact, result, currentFeedback) {
+function postFeedbackItems(ctx, artefact, result, currentFeedback, artefactVersion) {
   for (const item of result.items) {
     const tag = `law:${item.lawId}:${item.validatorId}`;
-    ctx.feedback.add({ file: artefact.file, text: item.text, tag });
+    ctx.feedback.add({ file: artefact.file, text: item.text, tag, artefact_version: artefactVersion });
     currentFeedback.push({ file: artefact.file, tag });
   }
 }

package/dist/scripts/sort.js

@@ -53,12 +53,12 @@ function validateWorkMd(workPath, io) {
   return { frontmatter, cycle: frontmatter.cycle, stages: frontmatter.stages };
 }
 
-function extractFrontmatterDefaults(frontmatter) {
+export function extractFrontmatterDefaults(frontmatter) {
   const maxIt = frontmatter['max-iterations'] ?? 3;
   return {
     maxIterations: maxIt,
     alwaysHumanAppraise: frontmatter['always-human-appraise'] === true,
-    deadlockHumanAppraise: frontmatter['deadlock-human-appraise'] !== false,
+    deadlockHumanAppraise: frontmatter['deadlock-human-appraise'] === true,
   };
 }
 
@@ -72,14 +72,33 @@ function checkDirtyFiles(history, io) {
     + `Re-run foundry_orchestrate or commit the listed files manually before retrying.`;
 }
 
+const SHA256_RE = /^[0-9a-f]{64}$/;
+
+function isLegacyItem(item) {
+  return !item.artefact_version || !SHA256_RE.test(item.artefact_version);
+}
+
 function loadFeedback(io, cycle) {
   const store = openFeedbackStore('WORK.feedback.yaml', io);
-  return store.list().map(item => ({
-    id: item.id,
-    file: item.file,
-    state: item.history[0].state,
-    depth: item.history.length,
-  }));
+  const allItems = store.list();
+  const routed = [];
+
+  for (const item of allItems) {
+    if (isLegacyItem(item)) {
+      store.autoResolve({ id: item.id, reason: 'superseded (legacy, no artefact version)', cycle });
+      continue;
+    }
+    routed.push({
+      id: item.id,
+      file: item.file,
+      state: item.history[0].state,
+      depth: item.history.length,
+      source: item.source,
+      artefact_version: item.artefact_version,
+    });
+  }
+
+  return routed;
 }
 
 function resolveCycleDef(cycleDef, frontmatter, foundryDir, cycle) {
@@ -246,10 +265,8 @@ export { parseFrontmatter } from './lib/workfile.js';
 export {
   baseStage,
   findFirst,
-  nextInRoute,
+  nextStageInChain,
   determineRoute,
-  nextAfterQuench,
-  nextAfterAppraise,
 } from './lib/sort-routing.js';
 export {
   globMatch,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@really-knows-ai/foundry",
-  "version": "3.5.9",
+  "version": "3.6.0",
   "description": "A skill-driven framework for governed artefact generation with AI coding tools. Define your own artefact types, laws, and flows — Foundry handles the forge → quench → appraise pipeline with deterministic routing, quality gates, and iterative refinement.",
   "type": "module",
   "main": "dist/.opencode/plugins/foundry.js",