@really-knows-ai/foundry 3.5.9 → 3.6.0

package/dist/.opencode/plugins/foundry-tools/feedback-tools.js

@@ -70,13 +70,17 @@ async function executeFeedbackAdd(args, context) {
 
   try {
     const store = openFeedbackStore('WORK.feedback.yaml', io);
-    const { id, deduped } = store.add({
+    const params = {
       file: args.file,
       tag: args.tag,
       text: args.text,
       source: activeStage,
       cycle,
-    });
+    };
+    if (args.artefact_version !== undefined) {
+      params.artefact_version = args.artefact_version;
+    }
+    const { id, deduped } = store.add(params);
     return JSON.stringify({ ok: true, id, deduped });
   } catch (err) {
     return JSON.stringify({ error: `foundry_feedback_add: ${err.message}` });
@@ -201,6 +205,7 @@ export function createFeedbackTools({ tool }) {
         file: tool.schema.string().describe('Artefact file path'),
         text: tool.schema.string().describe('Feedback text'),
         tag: tool.schema.string().describe('Tag for the feedback item'),
+        artefact_version: tool.schema.string().optional().describe('SHA-256 hash for version-aware sorting'),
       },
       execute: guarded('foundry_feedback_add', [flowBranchGuard, gateNotFailed], executeFeedbackAdd, { branchIo: branchIoFactory, io: asyncIoFactory }),
     }),
@@ -218,7 +223,7 @@ export function createFeedbackTools({ tool }) {
       execute: guarded('foundry_feedback_wontfix', [flowBranchGuard, gateNotFailed], executeFeedbackWontfix, { branchIo: branchIoFactory, io: asyncIoFactory }),
     }),
     foundry_feedback_resolve: tool({
-      description: 'Resolve a feedback item (approved or rejected). In human-appraise stages, this tool can override deadlocked items by providing a reason.',
+      description: 'Resolve a feedback item (approved or rejected). Human-appraise stages can override deadlock with a reason.',
       args: {
         id: tool.schema.string().describe('Feedback item id (ULID)'),
         resolution: tool.schema.enum(['approved', 'rejected']).describe('Resolution type'),
@@ -230,7 +235,6 @@ export function createFeedbackTools({ tool }) {
       args: {
         file: tool.schema.string().optional().describe('Filter by artefact file path'),
       },
-      execute: executeFeedbackList,
-    }),
+      execute: executeFeedbackList }),
   };
 }

package/dist/.opencode/plugins/foundry-tools/orchestrate-tool.js

@@ -38,7 +38,7 @@ function createGitBridge(cwd) {
 }
 
 async function createFinalize(cwd, io) {
-  return async ({ cycleId, stage, baseSha }) => {
+  return async ({ cycleId, stage, baseSha, artefact_version, contractPassed }) => {
     let cycleDoc;
     try {
       cycleDoc = await getCycleDefinition('foundry', cycleId, io);
@@ -66,6 +66,8 @@ async function createFinalize(cwd, io) {
       cycleDef,
       artefactTypes,
       io,
+      artefact_version,
+      contractPassed,
     });
     return result;
   };

package/dist/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [3.6.0] - 2026-05-25
+
+### Added
+
+- State-driven sort routing (R1–R4, R7): sort routes based on feedback item state (`unresolved` → forge, `addressed` → source stage) instead of stage position, with deadlock detection and iteration cap.
+- Artefact version tracking: `computeArtefactVersion` hashes all artefact files after each forge run; the version is recorded on every feedback item and forge history entry.
+- Forge contract enforcement (R8–R9): per-item response check and batch-level version consistency check. Contract violations revert items to `open` and post system feedback. Three consecutive contract failures block the cycle.
+- Stale feedback detection (R6): when quench, appraise, or human-appraise re-enters after a forge run, feedback items with a mismatched artefact version are auto-resolved as superseded.
+- Legacy feedback migration: items without a valid artefact version are auto-resolved on load and excluded from routing.
+- Integration test suite: 40 integration tests covering the routing decision tree, forge contract enforcement, and the spec's 10-step worked example.
+
+### Fixed
+
+- Forge contract enforcement wired into the orchestration post-dispatch path (previously it finalised without computing versions or checking the contract).
+- New feedback items from quench, appraise, and the plugin feedback tool now carry the current artefact version, preventing false legacy detection.
+- `computeArtefactVersion` scans the worktree root for file patterns (previously scanned the `foundry/` config directory).
+- Version computation failures during stale resolution are surfaced to the orchestrator instead of being silently swallowed.
+- Appraise stale feedback resolution runs during the gather phase (before appraiser dispatch), not only during consolidation.
+
+### Changed
+
+- Orchestration: forge post-dispatch extracts a dedicated `runForgePostDispatch` path that reads the forge context, computes versions, enforces the contract, and passes `contractPassed`/`postVersion` to `finaliseStage`.
+- Quench and appraise stale resolution helpers gracefully degrade when the artefact type is not configured (best-effort, not fatal).
+- Added `worktree` parameter to `computeArtefactVersion` for explicit worktree-root specification.
+
 ## [3.5.9] - 2026-05-24
 
 ### Changed

package/dist/scripts/appraise-module.js

@@ -11,8 +11,9 @@
  * so the orchestrator can re-sort and determine the next action.
  */
 
-import { getArtefactFiles } from './lib/artefacts.js';
+import { getArtefactFiles, computeArtefactVersion } from './lib/artefacts.js';
 import { selectAppraisers, getLaws, getCycleDefinition } from './lib/config.js';
+import { openFeedbackStore } from './lib/feedback-store.js';
 import yaml from 'js-yaml';
 
 // ---------------------------------------------------------------------------
@@ -39,6 +40,8 @@ export async function gatherAppraiseContext(ctx) {
     return violation('cycleId is required', []);
   }
 
+  await resolveStaleAppraiseFeedback(ctx);
+
   const cd = await getCycleDefinition(ctx.foundryDir, ctx.cycleId, ctx.io);
   const outputType = cd.frontmatter['output-type'];
   if (!outputType) {
@@ -147,11 +150,51 @@ function emptyDispatch(cycleId) {
 // ---------------------------------------------------------------------------
 
 /**
- * Consolidate appraiser results after all subagents have run.
+ * 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 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 appraise-sourced feedback. Errors propagate to the caller
+ * which must handle them (e.g. by returning a violation).
+ */
+async function resolveStaleAppraiseFeedback(ctx) {
+  try {
+    const cycleDef = await getCycleDefinition(ctx.foundryDir, ctx.cycleId, ctx.io);
+    const outputType = cycleDef.frontmatter['output-type'];
+    if (outputType) {
+      const store = openFeedbackStore('WORK.feedback.yaml', ctx.io);
+      const currentVersion = await computeArtefactVersion(ctx.foundryDir, outputType, ctx.io, ctx.cwd);
+      resolveStaleFeedback(store.list(), currentVersion, 'appraise', store, ctx.cycleId);
+    }
+  } catch {
+    // Graceful degrade — stale resolution is best-effort.
+    // The orchestrator handles IO failures at the cycle level.
+  }
+}
+
+/**
+ * Consolidate appraiser results and finalise the appraise stage.
  *
- * Parses each successful output for structured issues, unions across
- * appraisers, de-duplicates by (file, law-id, issue text), posts feedback,
- * resolves stale prior appraise feedback, and finalises the stage.
+ * Called by orchestrator after all appraisers have completed. Parses results,
+ * posts combined feedback, resolves prior appraise feedback, and advances
+ * the cycle to the next stage via finalize.
  *
  * @param {object} ctx
  * @param {Array<{ok: boolean, output?: string, error?: string}>} lastResults
@@ -170,10 +213,13 @@ export async function consolidateAppraise(ctx, lastResults) {
     return violation('All appraisers failed to evaluate the artefact', []);
   }
 
+  await resolveStaleAppraiseFeedback(ctx);
+
   const consolidated = parseConsolidated(successful);
   const stageId = `appraise:${ctx.cycleId}`;
 
-  postConsolidatedFeedback(ctx, consolidated);
+  const artefactVersion = await computeAppraiseArtefactVersion(ctx);
+  postConsolidatedFeedback(ctx, consolidated, artefactVersion);
   resolvePriorAppraise(ctx, consolidated, stageId);
 
   const summary = buildConsolidateSummary(consolidated.length);
@@ -219,15 +265,31 @@ function deduplicateIssues(issues) {
   return result;
 }
 
+/**
+ * Compute artefact version for the appraise cycle so feedback items carry
+ * a version hash and are not auto-resolved by sort as legacy items.
+ */
+async function computeAppraiseArtefactVersion(ctx) {
+  try {
+    const cycleDef = await getCycleDefinition(ctx.foundryDir, ctx.cycleId, ctx.io);
+    const outputType = cycleDef.frontmatter['output-type'];
+    if (outputType) {
+      return await computeArtefactVersion(ctx.foundryDir, outputType, ctx.io, ctx.cwd);
+    }
+  } catch { /* skip */ }
+  return undefined;
+}
+
 /**
  * Post one feedback item per consolidated issue.
  */
-function postConsolidatedFeedback(ctx, consolidated) {
+function postConsolidatedFeedback(ctx, consolidated, artefactVersion) {
   for (const issue of consolidated) {
     ctx.feedback.add({
       file: issue.file,
       text: issue.issue,
       tag: `law:${issue.law}`,
+      artefact_version: artefactVersion,
     });
   }
 }

package/dist/scripts/lib/artefacts.js

@@ -6,8 +6,9 @@
  */
 
 import { minimatch } from 'minimatch';
-import { sortPaths } from './attestation/hash.js';
+import { sortPaths, sha256Text } from './attestation/hash.js';
 import { getArtefactType } from './config.js';
+import { expandPatterns } from './validation.js';
 
 // --- Shared branch artefact discovery ---
 
@@ -164,3 +165,44 @@ export async function getArtefactFiles(foundryDir, typeId, io, options = {}) {
 
   return result;
 }
+
+/**
+ * Compute the artefact version hash for a given artefact type.
+ *
+ * Reads the artefact type definition, expands its file patterns across the
+ * worktree, and computes a SHA-256 hash over all matching files. Each file
+ * contributes `sha256(filePath + ":" + content)` and the per-file hashes are
+ * joined with "\n" before the final SHA-256.
+ *
+ * When no patterns are defined or no files match, returns the SHA-256 of an
+ * empty input (e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855).
+ *
+ * @param {string} foundryDir - Path to the foundry config directory
+ * @param {string} typeId - Artefact type identifier
+ * @param {object} io - IO interface with readFile(path, encoding)
+ * @param {string} [worktree] - Worktree root for pattern expansion (defaults to foundryDir)
+ * @returns {Promise<string>} SHA-256 hex string (64 characters)
+ * @throws {Error} On IO errors (unknown type, file read failure, glob error)
+ */
+export async function computeArtefactVersion(foundryDir, typeId, io, worktree = foundryDir) {
+  const def = await getArtefactType(foundryDir, typeId, io);
+  const patterns = getFilePatterns(def);
+
+  if (patterns.length === 0) {
+    return sha256Text('');
+  }
+
+  const files = await expandPatterns(patterns, worktree);
+
+  if (files.length === 0) {
+    return sha256Text('');
+  }
+
+  const perFileHashes = await Promise.all(files.map(async file => {
+    const content = await io.readFile(file, 'utf-8');
+    return sha256Text(file + ':' + content);
+  }));
+
+  const joined = perFileHashes.join('\n');
+  return sha256Text(joined);
+}

package/dist/scripts/lib/feedback-store.js

@@ -5,11 +5,11 @@ import { validateTransition, hashText, canForgeWontFix } from './feedback-transi
 
 const YAML_OPTS = { lineWidth: -1 };
 
-const VALID_SOURCE_BASES = new Set(['forge', 'quench', 'appraise', 'human-appraise']);
+const VALID_SOURCE_BASES = new Set(['forge', 'quench', 'appraise', 'human-appraise', 'system']);
 
 function validateSourceBase(base) {
   if (!VALID_SOURCE_BASES.has(base)) {
-    throw new Error(`unknown source base: ${base} (expected one of: forge, quench, appraise, human-appraise)`);
+    throw new Error(`unknown source base: ${base} (expected one of: forge, quench, appraise, human-appraise, system)`);
   }
 }
 
@@ -96,6 +96,12 @@ export function openFeedbackStore(path, io) {
         timestamp: nowIso, persist,
       });
     },
+    autoResolve({ id, reason, cycle }) {
+      return storeAutoResolve({ id, reason, cycle, items, persist, timestamp: nowIso });
+    },
+    forceState(id, state, cycle) {
+      return storeForceState({ id, state, cycle, items, persist });
+    },
     resolveSystemItems(stage, cycle) {
       resolveSystemItemsImpl({ items, stage, cycle, timestamp: nowIso, persist });
     },
@@ -109,20 +115,21 @@ function isDuplicate(item, file, tag, textHash, stateOf) {
     stateOf(item) !== 'resolved';
 }
 
-function assertAddParams(...params) {
-  for (const p of params) {
-    if (!p) throw new Error('add requires file, tag, text, source, cycle');
-  }
+function assertAddParams(file, tag, text, source, cycle) {
+  const missing = typeof file !== 'string' || [tag, text, source, cycle].some(v => !v);
+  if (missing) throw new Error('add requires file, tag, text, source, cycle');
 }
 
 function storeAdd(params, items, deps) {
-  const { file, tag, text, source, cycle } = params;
+  const { file, tag, text, source, cycle, artefact_version } = params;
   const { hashFn, stateOf, validateSrc, persist, makeUlid, timestamp } = deps;
   assertAddParams(file, tag, text, source, cycle);
   validateSrc(source);
 
   const textHash = hashFn(text);
-  const existing = items.find(it => isDuplicate(it, file, tag, textHash, stateOf));
+  const existing = items.find(it =>
+    it.artefact_version === artefact_version && isDuplicate(it, file, tag, textHash, stateOf)
+  );
   if (existing) return { id: existing.id, deduped: true };
 
   const id = makeUlid();
@@ -130,6 +137,9 @@ function storeAdd(params, items, deps) {
     id, file, tag, text, source,
     history: [{ state: 'open', stage: source, cycle, timestamp: timestamp() }],
   };
+  if (artefact_version !== undefined) {
+    item.artefact_version = artefact_version;
+  }
   persist([...items, item]);
   return { id, deduped: false };
 }
@@ -202,4 +212,20 @@ function storeTransition(params, items, deps) {
   return { ok: true };
 }
 
+function storeForceState({ id, state, cycle, items, persist }) {
+  const item = items.find(x => x.id === id);
+  if (!item) return { ok: false, error: `feedback item not found: ${id}` };
+  const snapshot = { state, stage: 'system:forge-contract-mismatch', cycle, timestamp: nowIso() };
+  persist(applyTransition(items, id, snapshot));
+  return { ok: true };
+}
+
+function storeAutoResolve({ id, reason, cycle, items, persist, timestamp }) {
+  const item = items.find(x => x.id === id);
+  if (!item) return { ok: false, error: `feedback item not found: ${id}` };
+  const snapshot = { state: 'resolved', stage: 'system', cycle, reason, timestamp: timestamp() };
+  persist(applyTransition(items, id, snapshot));
+  return { ok: true };
+}
+
 

package/dist/scripts/lib/finalize.js

@@ -49,7 +49,7 @@ function classifyFiles(files, allowedPatterns) {
   return { matched, unexpected };
 }
 
-export function finalizeStage({ cwd, baseSha, stageBase, cycleDef, artefactTypes, io }) {
+export function finalizeStage({ cwd, baseSha, stageBase, cycleDef, artefactTypes, io, artefact_version }) {
   if (!io?.exec) {
     throw new Error('finalizeStage: io.exec is required');
   }
@@ -66,5 +66,13 @@ export function finalizeStage({ cwd, baseSha, stageBase, cycleDef, artefactTypes
     file,
     type: cycleDef.outputArtefactType,
   }));
-  return { ok: true, artefacts, changedFiles: sortedFiles };
+  return forgeResult(artefacts, sortedFiles, artefact_version);
+}
+
+function forgeResult(artefacts, files, artefact_version) {
+  const result = { ok: true, artefacts, changedFiles: files };
+  if (artefact_version !== undefined) {
+    result.artefact_version = artefact_version;
+  }
+  return result;
 }

package/dist/scripts/lib/forge-contract.js

@@ -0,0 +1,93 @@
+/**
+ * Forge contract enforcement — validates that forge responded to every
+ * presented feedback item and that the batch-level artefact version
+ * semantics are satisfied.
+ *
+ * Per-item check: every item must end in 'actioned' or 'wont-fix'.
+ * Batch-level check: if any item is actioned, version must change.
+ * If no item is actioned, version must be unchanged.
+ */
+
+function currentState(feedbackStore, id) {
+  const item = feedbackStore.get(id);
+  return item ? item.history[0].state : null;
+}
+
+function revertAll(items, feedbackStore, cycleId) {
+  for (const item of items) {
+    feedbackStore.forceState(item.id, 'open', cycleId);
+  }
+}
+
+function postSystemFeedback(feedbackStore, cycleId, postVersion, text) {
+  feedbackStore.add({
+    file: '',
+    tag: 'system:forge-contract-mismatch',
+    text,
+    source: 'system:forge-contract-mismatch',
+    artefact_version: postVersion,
+    cycle: cycleId,
+  });
+}
+
+function checkPerItemResponse(items, feedbackStore, cycleId, postVersion) {
+  for (const item of items) {
+    const state = currentState(feedbackStore, item.id);
+    if (state !== 'actioned' && state !== 'wont-fix') {
+      revertAll(items, feedbackStore, cycleId);
+      postSystemFeedback(
+        feedbackStore, cycleId, postVersion,
+        'forge did not respond to every presented feedback item',
+      );
+      return false;
+    }
+  }
+  return true;
+}
+
+function hasActionedItem(items, feedbackStore) {
+  return items.some(item => currentState(feedbackStore, item.id) === 'actioned');
+}
+
+function checkBatchVersion(items, feedbackStore, cycleId, postVersion, preVersion) {
+  const hasActioned = hasActionedItem(items, feedbackStore);
+
+  if (hasActioned && preVersion === postVersion) {
+    revertAll(items, feedbackStore, cycleId);
+    postSystemFeedback(
+      feedbackStore, cycleId, postVersion,
+      'forge marked feedback as actioned without changing artefacts',
+    );
+    return { contractPassed: false };
+  }
+
+  if (!hasActioned && preVersion !== postVersion) {
+    revertAll(items, feedbackStore, cycleId);
+    postSystemFeedback(
+      feedbackStore, cycleId, postVersion,
+      'forge changed artefacts but did not mark any feedback as actioned',
+    );
+    return { contractPassed: false };
+  }
+
+  return { contractPassed: true };
+}
+
+/**
+ * Enforce the forge contract on a batch of items presented to forge.
+ *
+ * Two-level check:
+ * 1. Per-item: every item must end in 'actioned' or 'wont-fix'.
+ * 2. Batch-level: artefact version semantics must be consistent.
+ *
+ * @param {{ items: Array<{id: string}>, preVersion: string, postVersion: string,
+ *   feedbackStore: object, cycleId: string }} params
+ * @returns {{ contractPassed: boolean }}
+ */
+export function enforceForgeContract({ items, preVersion, postVersion, feedbackStore, cycleId }) {
+  if (!checkPerItemResponse(items, feedbackStore, cycleId, postVersion)) {
+    return { contractPassed: false };
+  }
+
+  return checkBatchVersion(items, feedbackStore, cycleId, postVersion, preVersion);
+}

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,7 +18,9 @@ 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').length;