@really-knows-ai/foundry 3.6.2 → 3.7.0

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

@@ -16,7 +16,6 @@ const FORGE_REQUIRED_TOOLS = [
   'foundry_workfile_get',
   'foundry_config_artefact_type',
   'foundry_config_laws',
-  'foundry_feedback_list',
 ];
 
 function stageBase(stage) { return stage.split(':')[0]; }

package/dist/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [3.7.0] - 2026-05-27
+
+### Added
+
+- Single-item forge dispatch: the forge stage dispatches one artefact at a time, producing focused, incremental edits instead of batch rewrites.
+
+- Single-item contract enforcement: forge contract checks validate per-item responses and artefact version consistency at the single-artefact level, matching the new dispatch model.
+
+### Fixed
+
+- Max-iterations cap now triggers `alwaysHumanAppraise` when the cycle exceeds its limit, and quench no longer files redundant duplicate feedback items for the same violation.
+
+- Forge dispatch review findings addressed: tightened guard logic and cleaned up stale inline comments from the initial single-item implementation.
+
+### Changed
+
+- Forge and orchestrate skill guidance aligned with the single-item dispatch model.
+
+## [3.6.3] - 2026-05-26
+
+### Fixed
+
+- Validator script crashes now surface a single clear error ("Validator produced no valid output — check the script for syntax errors") instead of 20+ individual "Invalid JSON" parse errors from the stack trace.
+
 ## [3.6.2] - 2026-05-25
 
 ### Fixed

package/dist/scripts/appraise-module.js

@@ -153,6 +153,12 @@ function emptyDispatch(cycleId) {
  * 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.
+ *
+ * @param {object[]} items - Feedback items to check
+ * @param {string} currentVersion - Current on-disk artefact version
+ * @param {string} stageBase - Stage base name (e.g. 'appraise') to filter by source
+ * @param {object} feedback - Feedback store instance with autoResolve method
+ * @param {string} cycle - Current cycle identifier
  */
 export function resolveStaleFeedback(items, currentVersion, stageBase, feedback, cycle) {
   for (const item of items) {

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

@@ -99,8 +99,8 @@ export function openFeedbackStore(path, io) {
     autoResolve({ id, reason, cycle }) {
       return storeAutoResolve({ id, reason, cycle, items, persist, timestamp: nowIso });
     },
-    forceState(id, state, cycle) {
-      return storeForceState({ id, state, cycle, items, persist });
+    forceState(id, state, cycle, stage) {
+      return storeForceState({ id, state, cycle, items, persist, stage });
     },
     resolveSystemItems(stage, cycle) {
       resolveSystemItemsImpl({ items, stage, cycle, timestamp: nowIso, persist });
@@ -212,10 +212,10 @@ function storeTransition(params, items, deps) {
   return { ok: true };
 }
 
-function storeForceState({ id, state, cycle, items, persist }) {
+function storeForceState({ id, state, cycle, items, persist, stage }) {
   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() };
+  const snapshot = { state, stage: stage || 'system:forge-contract-mismatch', cycle, timestamp: nowIso() };
   persist(applyTransition(items, id, snapshot));
   return { ok: true };
 }

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

@@ -1,11 +1,16 @@
 /**
- * Forge contract enforcement — validates that forge responded to every
- * presented feedback item and that the batch-level artefact version
- * semantics are satisfied.
+ * Forge contract enforcement — validates that forge addressed the single
+ * presented feedback item according to the single-item dispatch contract.
  *
- * 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.
+ * Rules (per spec R4):
+ *   - Version changed → transition item to `actioned`.
+ *   - Version unchanged + summary contains `WONT-FIX:` + source base is
+ *     `appraise` → transition item to `wont-fix` with the justification
+ *     as the reason.
+ *   - Version unchanged + summary contains `WONT-FIX:` + source base is
+ *     NOT `appraise` → contract violation.
+ *   - Version unchanged + no `WONT-FIX:` in summary → contract violation.
+ *   - No item (null/undefined) → no-op, contract passes.
  */
 
 function currentState(feedbackStore, id) {
@@ -13,12 +18,6 @@ function currentState(feedbackStore, 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: '',
@@ -30,73 +29,77 @@ function postSystemFeedback(feedbackStore, cycleId, postVersion, text) {
   });
 }
 
-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',
-    );
+function handleVersionChanged(item, feedbackStore, cycleId, postVersion) {
+  const result = feedbackStore.transition({
+    id: item.id,
+    target: 'actioned',
+    stage: 'forge:' + cycleId,
+    cycle: cycleId,
+  });
+  if (!result.ok) {
+    postSystemFeedback(feedbackStore, cycleId, postVersion, result.error || 'store transition failed');
+    feedbackStore.forceState(item.id, 'open', cycleId, `forge:${cycleId}`);
     return { contractPassed: false };
   }
+  return { contractPassed: true };
+}
 
-  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 };
+function handleWontFixWithReason(item, feedbackStore, cycleId, postVersion, reason) {
+  const sourceBase = typeof item.source === 'string' ? item.source.split(':')[0] : '';
+  if (sourceBase === 'appraise') {
+    const result = feedbackStore.transition({
+      id: item.id,
+      target: 'wont-fix',
+      stage: 'forge:' + cycleId,
+      cycle: cycleId,
+      reason,
+    });
+    if (!result.ok) {
+      postSystemFeedback(feedbackStore, cycleId, postVersion, result.error || 'store transition failed');
+      feedbackStore.forceState(item.id, 'open', cycleId, `forge:${cycleId}`);
+    }
+    return { contractPassed: result.ok };
   }
-
-  return { contractPassed: true };
+  // quench or human-appraise — wont-fix not allowed
+  postSystemFeedback(
+    feedbackStore, cycleId, postVersion,
+    `wont-fix not allowed on ${sourceBase}-sourced item; wont-fix is only allowed for appraise-sourced items`,
+  );
+  feedbackStore.forceState(item.id, 'open', cycleId, `forge:${cycleId}`);
+  return { contractPassed: false };
 }
 
 /**
- * Enforce the forge contract on a batch of items presented to forge.
- *
- * When `items` is not a non-empty array (null, undefined, or []), the
- * contract passes immediately without side-effects. This covers the
- * initial forge run where no feedback exists yet.
+ * Enforce the forge contract on a single feedback item.
  *
- * Two-level check when items are present:
- * 1. Per-item: every item must end in 'actioned' or 'wont-fix'.
- * 2. Batch-level: artefact version semantics must be consistent.
+ * When no item is provided (null/undefined), the contract passes without
+ * side-effects. This covers the initial forge run where no feedback
+ * exists yet and subsequent runs where all items were already resolved.
  *
- * @param {{ items?: Array<{id: string}> | null, preVersion: string,
- *          postVersion: string, feedbackStore: object, cycleId: string }} params
+ * @param {{ item: object|null, preVersion: string, postVersion: string,
+ *           summary: string, feedbackStore: object, cycleId: string }} params
  * @returns {{ contractPassed: boolean }}
  */
-export function enforceForgeContract({ items, preVersion, postVersion, feedbackStore, cycleId }) {
-  if (!Array.isArray(items) || items.length === 0) {
-    // Empty batch means forge had no prior feedback to respond to.
-    // This is the first forge run or all items were already resolved.
-    return { contractPassed: true };
+export function enforceForgeContract({ item, preVersion, postVersion, summary, feedbackStore, cycleId }) {
+  // No item means forge had no prior feedback to respond to.
+  if (!item) return { contractPassed: true };
+
+  // Version changed → forge fixed the issue
+  if (preVersion !== postVersion) {
+    return handleVersionChanged(item, feedbackStore, cycleId, postVersion);
   }
-  if (!checkPerItemResponse(items, feedbackStore, cycleId, postVersion)) {
-    return { contractPassed: false };
+
+  // Version unchanged — check for WONT-FIX justification
+  const wontFixMatch = summary.match(/WONT-FIX:\s*(.+)/);
+  if (wontFixMatch) {
+    return handleWontFixWithReason(item, feedbackStore, cycleId, postVersion, wontFixMatch[1]);
   }
 
-  return checkBatchVersion(items, feedbackStore, cycleId, postVersion, preVersion);
+  // Version unchanged with no WONT-FIX — neither fix nor justification
+  postSystemFeedback(
+    feedbackStore, cycleId, postVersion,
+    'forge did not change artefacts and did not provide WONT-FIX justification',
+  );
+  feedbackStore.forceState(item.id, 'open', cycleId, `forge:${cycleId}`);
+  return { contractPassed: false };
 }

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

@@ -18,15 +18,13 @@ export function reasonForRoute(route, prep) {
 
 function buildReasonData(route, prep) {
   const base = baseStage(route);
-  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 needingForgeItems = feedback.filter(f => f.state === 'open' || f.state === 'rejected');
+  // Per-item forge count: use the maximum count across all unresolved items
+  const forgeCount = needingForgeItems.length > 0 ? Math.max(...needingForgeItems.map(i => i.forge_count || 0)) : 0;
+  const needingForge = needingForgeItems.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;
 
@@ -34,7 +32,9 @@ function buildReasonData(route, prep) {
 }
 
 function forgeReason(d) {
-  if (d.forgeCount === 0) return `starting cycle — routing to forge (iteration 1 of ${d.maxIt})`;
+  if (d.forgeCount === 0 && d.needingForge === 0) {
+    return `starting cycle — routing to forge (iteration 1 of ${d.maxIt})`;
+  }
   return `found ${d.needingForge} unresolved feedback item(s) — routing to forge for revision (iteration ${d.forgeCount + 1} of ${d.maxIt})`;
 }
 

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

@@ -103,18 +103,28 @@ function validateRoute(maxIterations, stages, history) {
 
 /**
  * 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.
+ * stage entry (full alias), its base stage name, forge iteration count
+ * per the first unresolved item, and categorised feedback items.
+ *
+ * The forge count tracks attempts against the current (first) unresolved
+ * item only. Each feedback item carries its own `forge_count` (set by
+ * `loadFeedback` in sort.js) that records how many forge runs it has
+ * actually consumed. This satisfies SPEC R7: each item gets at most
+ * `max-iterations` attempts before the cycle deadlocks.
  */
 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');
+  // Per-item forge count: use the maximum forge_count across all unresolved
+  // items. This ensures that if any item has exhausted its iteration budget,
+  // the route blocks — no single item with remaining budget can mask an
+  // item that has hit the cap.
+  const forgeCount = unresolvedItems.length > 0
+    ? Math.max(...unresolvedItems.map(i => i.forge_count || 0))
+    : 0;
   return { lastEntry, lastStage, forgeCount, unresolvedItems, addressedItems };
 }
 
@@ -124,12 +134,16 @@ function computeRoutingState(history, feedback) {
  * routes to human-appraise (if deadlockHumanAppraise) or 'blocked'.
  * Otherwise routes to forge via first('forge', stages).
  */
+function routeToHumanOrBlock(firstFn, stages, opts) {
+  if ((opts.deadlockHumanAppraise || opts.alwaysHumanAppraise) && hasStage(stages, 'human-appraise')) {
+    return firstFn('human-appraise', stages, opts.cycle);
+  }
+  return 'blocked';
+}
+
 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 (forgeCount >= maxIterations) {
+    return routeToHumanOrBlock(firstFn, stages, opts);
   }
   if (!hasStage(stages, 'forge')) return 'blocked';
   return firstFn('forge', stages);
@@ -142,7 +156,7 @@ function checkIterationAndRoute(firstFn, stages, forgeCount, maxIterations, opts
  * fall through to forwardClean.
  */
 function routeAddressedItems(addressedItems, stages, opts) {
-  const sourceBases = [...new Set(addressedItems.map(i => baseStage(i.source)))];
+  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)) {

package/dist/scripts/lib/validation.js

@@ -197,6 +197,23 @@ export function collectValidatorResult(parseResult, lawId, validatorId, results)
   }
 }
 
+/**
+ * If every line of output was unparseable, the validator script itself is
+ * broken (syntax error, runtime crash, etc.). Replace the noise of 20+
+ * individual "Invalid JSON" errors with a single actionable message.
+ */
+export function checkForValidatorCrash(result) {
+  if (result.items.length === 0 && result.parseErrors.length > 0) {
+    return {
+      ...result,
+      parseErrors: [
+        `Validator produced no valid output (${result.parseErrors.length} unparseable lines). Check the validator script for syntax errors.`,
+      ],
+    };
+  }
+  return result;
+}
+
 /**
  * Execute a validator command and parse its JSONL output.
  */
@@ -209,14 +226,18 @@ export async function executeValidator(expanded, worktree, patterns) {
     });
     const { Readable } = await import('stream');
     const stream = Readable.from([output]);
-    return await parseValidatorJsonl(stream, patterns);
+    return checkForValidatorCrash(
+      await parseValidatorJsonl(stream, patterns),
+    );
   } catch (err) {
     // Validator command failed — prefer stdout for JSONL
     // (tools like rg exit 1 with results on stdout)
     const output = (err.stdout || err.stderr || err.message || '').trim();
     const { Readable } = await import('stream');
     const stream = Readable.from([output]);
-    return await parseValidatorJsonl(stream, patterns);
+    return checkForValidatorCrash(
+      await parseValidatorJsonl(stream, patterns),
+    );
   }
 }
 

package/dist/scripts/orchestrate-cycle.js

@@ -6,6 +6,7 @@ import {
   getArtefactType,
 } from './lib/config.js';
 import { openFeedbackStore } from './lib/feedback-store.js';
+import { baseStage } from './lib/sort-routing.js';
 
 // ---------------------------------------------------------------------------
 // Public helpers (re-exported by orchestrate.js for tests).
@@ -229,8 +230,20 @@ export function buildDispatchMultiResponse(tasks, stage, cycle) {
 // Dispatch prompt rendering (pure utility, used by handleSortResult and exported publicly).
 // ---------------------------------------------------------------------------
 
-function buildForgePromptLines({ cycle, outputType }) {
-  return [
+/**
+ * Extract the base part of a source alias string (everything before the
+ * first colon). Returns an empty string when the source is not a string.
+ * Example: 'quench:abc123' -> 'quench'
+ *
+ * Reuses the exported `baseStage` from sort-routing.js to avoid
+ * duplicating the split logic.
+ */
+function sourceBase(source) {
+  return typeof source === 'string' ? baseStage(source) : '';
+}
+
+function buildForgePromptLines({ cycle, outputType, forgeItem }) {
+  const lines = [
     ``,
     `Before producing output you MUST call these tools to understand the context:`,
     outputType
@@ -243,11 +256,31 @@ function buildForgePromptLines({ cycle, outputType }) {
       ? `  - foundry_config_laws({ typeId: "${outputType}" }) — to learn all applicable quality laws`
       : `  - foundry_config_laws({ typeId: "<output type>" }) — to learn all applicable quality laws`,
     `  - foundry_workfile_get({}) — to learn the goal`,
-    `  - foundry_feedback_list({}) — to check for existing feedback from prior iterations`,
   ];
+  if (forgeItem) {
+    lines.push(
+      ``,
+      `FEEDBACK ITEM TO ADDRESS:`,
+      ``,
+      `Source: ${sourceBase(forgeItem.source)}`,
+      `File: ${forgeItem.file}`,
+      `Issue: ${forgeItem.text}`,
+      ``,
+      `You MUST either:`,
+      `  a) Fix the issue by changing the artefact file. The orchestrator`,
+      `     will record this as ACTIONED.`,
+      `  b) If this is an appraise-sourced item (subjective quality`,
+      `     feedback), you may respond with:`,
+      `     WONT-FIX: <justification for why you disagree>`,
+      ``,
+      `Quench-sourced items are deterministic validation failures —`,
+      `you MUST fix them. There is no wont-fix option.`,
+    );
+  }
+  return lines;
 }
 
-export function renderDispatchPrompt({ stage, cycle, token, cwd, filePatterns, outputType }) {
+export function renderDispatchPrompt({ stage, cycle, token, cwd, filePatterns, outputType, forgeItem }) {
   const base = stage.split(':')[0];
   const lines = [
     `You are a Foundry stage agent. Invoke the ${base} skill and follow its instructions exactly.`,
@@ -261,7 +294,7 @@ export function renderDispatchPrompt({ stage, cycle, token, cwd, filePatterns, o
     lines.push(`File patterns (forge only): ${JSON.stringify(filePatterns)}`);
   }
   if (base === 'forge') {
-    lines.push(...buildForgePromptLines({ cycle, outputType }));
+    lines.push(...buildForgePromptLines({ cycle, outputType, forgeItem }));
   }
   lines.push(
     ``,

package/dist/scripts/orchestrate-finalise.js

@@ -0,0 +1,127 @@
+// Foundry v3.x orchestrate: finalise stage and violation handlers.
+
+import { buildForgeHistoryEntry } from './lib/workfile.js';
+import { baseStage } from './lib/sort-routing.js';
+import { clearActiveStage, clearLastStage } from './lib/state.js';
+import { allowedPatternsForStage } from './lib/git-policy.js';
+import { stageBaseOf } from './lib/stage-guard.js';
+import { appendEntry, getIteration } from './lib/history.js';
+import {
+  tryCommit,
+  violation,
+  computeOpenFeedback,
+  readForgeFilePatterns,
+} from './orchestrate-cycle.js';
+
+function buildFinalizeViolation(finalizeResult) {
+  if (finalizeResult.error === 'unexpected_files') {
+    return violation(`unexpected files written by subagent: ${(finalizeResult.files || []).join(', ')}`, finalizeResult.files || []);
+  }
+  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, buildStageEntryBase(ctx), ctx.io);
+}
+
+async function computeAllowedPatterns(lastStage, cycleId, io) {
+  const stageB = stageBaseOf(lastStage.stage);
+  let forgeFilePatterns = [];
+  if (stageB === 'forge') {
+    const result = await readForgeFilePatterns(cycleId, io);
+    forgeFilePatterns = result ? result.patterns : [];
+  }
+  return allowedPatternsForStage({ stageBase: stageB, forgeFilePatterns });
+}
+
+function buildCommitMessage(cycleId, lastStage) {
+  return `[${cycleId}] ${lastStage.stage}: ${lastStage.summary || '(no summary)'}`;
+}
+
+function rollbackState(io, original) {
+  io.writeFile('WORK.md', original.workMd);
+  if (original.history !== null) { io.writeFile('WORK.history.yaml', original.history); }
+  else if (io.exists('WORK.history.yaml')) { io.unlink('WORK.history.yaml'); }
+}
+
+async function tryStageCommit(git, lastStage, cycleId, io) {
+  if (!git || typeof git.commit !== 'function') return null;
+  const allowedPatterns = await computeAllowedPatterns(lastStage, cycleId, io);
+  return tryCommit(git, buildCommitMessage(cycleId, lastStage), allowedPatterns, lastStage.stage);
+}
+
+function clearStageState(activeStage, lastStage, io) {
+  if (activeStage) clearActiveStage(io);
+  if (lastStage) clearLastStage(io);
+}
+
+export async function finaliseStage(args) {
+  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,
+    artefact_version: postVersion, contractPassed,
+  });
+  if (!finalizeResult.ok) {
+    clearStageState(activeStage, null, io);
+    return buildFinalizeViolation(finalizeResult);
+  }
+  const historyPath = 'WORK.history.yaml';
+  const iteration = getIteration(historyPath, cycleId, io);
+  const openFeedback = computeOpenFeedback(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);
+    clearStageState(activeStage, null, io);
+    return commitErr;
+  }
+  clearStageState(activeStage, lastStage, io);
+  return null;
+}
+
+export function handleViolation(args) {
+  const { lastResult, activeStage, lastStage } = args;
+  const failedStage = activeStage || lastStage;
+  if (!failedStage) { return violation('lastResult.ok=false but no stage recorded — orphaned state'); }
+  clearStageState(activeStage, lastStage, args.io);
+  return violation(
+    `subagent dispatch failed: ${lastResult.error || 'unknown error'}`,
+    lastResult.affected_files || [],
+  );
+}

package/dist/scripts/orchestrate-phases.js

@@ -6,18 +6,12 @@ import {
   getCycleDefinition,
   getLawsForQuench,
 } from './lib/config.js';
-import { parseFrontmatter, writeFrontmatter, buildForgeHistoryEntry } from './lib/workfile.js';
+import { parseFrontmatter, writeFrontmatter } 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';
 import {
   readForgeFilePatterns,
-  computeOpenFeedback,
   violation,
   tryCommit,
   synthesizeStages,
@@ -29,24 +23,35 @@ import {
   humanAppraiseAction,
   missingModelViolation,
 } from './orchestrate-terminals.js';
+import { finaliseStage, handleViolation } from './orchestrate-finalise.js';
+export { finaliseStage, handleViolation };
 
-function makeDispatchPayload({ route, cycleId, token, cwd, filePatterns, outputType }) {
-  return { stage: route, cycle: cycleId, token, cwd, filePatterns, outputType };
+function makeDispatchPayload({ route, cycleId, token, cwd, filePatterns, outputType, forgeItem }) {
+  return { stage: route, cycle: cycleId, token, cwd, filePatterns, outputType, forgeItem };
+}
+
+async function prepareForgePayload(cycleId, io) {
+  const payload = { filePatterns: null, outputType: null, forgeItem: null };
+  const result = await readForgeFilePatterns(cycleId, io);
+  if (result) {
+    payload.filePatterns = result.patterns;
+    payload.outputType = result.outputType;
+  }
+  const forgeCtxPath = '.foundry/forge-context.json';
+  if (io.exists(forgeCtxPath)) {
+    try {
+      const parsed = JSON.parse(io.readFile(forgeCtxPath));
+      payload.forgeItem = parsed.forgeItem ?? null;
+    } catch { /* malformed or missing — defaults to null */ }
+  }
+  return payload;
 }
 
 async function buildDispatchAction(route, model, token, ctx) {
   if (!model) return missingModelViolation(ctx.cycleId, route, ctx.io, ctx.foundryDir, ctx.baseBranch ?? 'main');
   const base = route.split(':')[0];
-  let filePatterns = null;
-  let outputType = null;
-  if (base === 'forge') {
-    const result = await readForgeFilePatterns(ctx.cycleId, ctx.io);
-    if (result) {
-      filePatterns = result.patterns;
-      outputType = result.outputType;
-    }
-  }
-  const payload = { route, cycleId: ctx.cycleId, token, cwd: ctx.cwd, filePatterns, outputType };
+  const forgePayload = base === 'forge' ? await prepareForgePayload(ctx.cycleId, ctx.io) : { filePatterns: null, outputType: null, forgeItem: null };
+  const payload = { route, cycleId: ctx.cycleId, token, cwd: ctx.cwd, ...forgePayload };
   return { action: 'dispatch', stage: route, subagent_type: model,
     prompt: renderDispatchPrompt(makeDispatchPayload(payload)) };
 }
@@ -220,115 +225,4 @@ async function trySetupCommit(ctx) {
   return { ok: true, workContent: ctx.io.readFile('WORK.md') };
 }
 
-function buildFinalizeViolation(finalizeResult) {
-  if (finalizeResult.error === 'unexpected_files') {
-    return violation(`unexpected files written by subagent: ${(finalizeResult.files || []).join(', ')}`, finalizeResult.files || []);
-  }
-  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, buildStageEntryBase(ctx), ctx.io);
-}
-
-async function computeAllowedPatterns(lastStage, cycleId, io) {
-  const stageBase = stageBaseOf(lastStage.stage);
-  let forgeFilePatterns = [];
-  if (stageBase === 'forge') {
-    const result = await readForgeFilePatterns(cycleId, io);
-    forgeFilePatterns = result ? result.patterns : [];
-  }
-  return allowedPatternsForStage({ stageBase, forgeFilePatterns });
-}
-
-function buildCommitMessage(cycleId, lastStage) {
-  return `[${cycleId}] ${lastStage.stage}: ${lastStage.summary || '(no summary)'}`;
-}
-
-function rollbackState(io, original) {
-  io.writeFile('WORK.md', original.workMd);
-  if (original.history !== null) { io.writeFile('WORK.history.yaml', original.history); }
-  else if (io.exists('WORK.history.yaml')) { io.unlink('WORK.history.yaml'); }
-}
-
-async function tryStageCommit(git, lastStage, cycleId, io) {
-  if (!git || typeof git.commit !== 'function') return null;
-  const allowedPatterns = await computeAllowedPatterns(lastStage, cycleId, io);
-  return tryCommit(git, buildCommitMessage(cycleId, lastStage), allowedPatterns, lastStage.stage);
-}
-
-function clearStageState(activeStage, lastStage, io) {
-  if (activeStage) clearActiveStage(io);
-  if (lastStage) clearLastStage(io);
-}
-
-export async function finaliseStage(args) {
-  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,
-    artefact_version: postVersion, contractPassed,
-  });
-  if (!finalizeResult.ok) {
-    clearStageState(activeStage, null, io);
-    return buildFinalizeViolation(finalizeResult);
-  }
-  const historyPath = 'WORK.history.yaml';
-  const iteration = getIteration(historyPath, cycleId, io);
-  const openFeedback = computeOpenFeedback(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);
-    clearStageState(activeStage, null, io);
-    return commitErr;
-  }
-  clearStageState(activeStage, lastStage, io);
-  return null;
-}
-
-export function handleViolation(args) {
-  const { lastResult, activeStage, lastStage } = args;
-  const failedStage = activeStage || lastStage;
-  if (!failedStage) { return violation('lastResult.ok=false but no stage recorded — orphaned state'); }
-  clearStageState(activeStage, lastStage, args.io);
-  return violation(
-    `subagent dispatch failed: ${lastResult.error || 'unknown error'}`,
-    lastResult.affected_files || [],
-  );
-}

package/dist/scripts/orchestrate-terminals.js

@@ -68,7 +68,7 @@ async function resolveStaleHumanAppraiseFeedback(cfm, fd, io, cycleId, cwd) {
 
 function shouldSkipHumanAppraiseResolve(item, currentVersion) {
   if (item.history[0].state === 'resolved') return true;
-  if (baseStage(item.source) !== 'human-appraise') return true;
+  if (typeof item.source !== 'string' || baseStage(item.source) !== 'human-appraise') return true;
   if (item.artefact_version === currentVersion) return true;
   return false;
 }

package/dist/scripts/orchestrate.js

@@ -40,6 +40,8 @@ export {
 export { gatherAppraiseContext, consolidateAppraise };
 export { readCycleTargets, readForgeFilePatterns };
 export { handleSortResult as __handleSortResultForTest };
+export { captureForgeContext as __captureForgeContextForTest };
+export { enforceForgeStage as __enforceForgeStageForTest };
 
 export function needsSetup(workMdContent) {
   const { data } = matter(workMdContent);
@@ -142,7 +144,19 @@ async function captureForgeContext(sortResult, args, preCheck, io) {
     return state === 'open' || state === 'rejected';
   });
   if (!io.exists('.foundry')) io.mkdir('.foundry');
-  const ctx = { forgePreVersion: preVersion, forgeItems: unresolvedItems.map(i => ({ id: i.id })) };
+  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));
 }
 
@@ -158,14 +172,30 @@ function countConsecutiveForgeFailures(io, cycleId) {
   return count;
 }
 
-async function enforceForgeStage(activeStage, fgResult, cycleId, io, cwd) {
+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({
-    items: activeStage.forgeItems, preVersion: activeStage.forgePreVersion,
-    postVersion, feedbackStore, cycleId,
+    item,
+    preVersion: forgeCtx.forgePreVersion,
+    postVersion,
+    summary,
+    feedbackStore,
+    cycleId,
   });
-  if (!contractPassed && countConsecutiveForgeFailures(io, cycleId) + 1 >= 3) {
+
+  if (checkConsecutiveFailures(contractPassed, io, cycleId)) {
     return { violation: 'forge contract failed 3 consecutive times — unable to satisfy feedback requirements' };
   }
   return { postVersion, contractPassed };
@@ -273,7 +303,6 @@ async function runForgePostDispatch(args, activeStage, lastStage, cycleId, io) {
   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 });

package/dist/scripts/quench-module.js

@@ -12,17 +12,24 @@ 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';
+import { hashText } from './lib/feedback-transitions.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.
+ *
+ * @param {object[]} items - Feedback items to check
+ * @param {string} currentVersion - Current on-disk artefact version
+ * @param {string} stageBase - Stage base name (e.g. 'quench') to filter by source
+ * @param {object} store - Feedback store instance with autoResolve method
+ * @param {string} cycle - Current cycle identifier
  */
-export async function resolveStaleFeedback(items, currentVersion, stageBase, feedback, cycle) {
+export async function resolveStaleFeedback(items, currentVersion, stageBase, store, 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 });
+    store.autoResolve({ id: item.id, reason, cycle });
   }
 }
 
@@ -35,14 +42,17 @@ function shouldSkipStaleResolve(item, currentVersion, stageBase) {
 }
 
 /**
- * Resolve stale quench-sourced feedback. Errors propagate to the caller
- * (runQuench) which surfaces them as a failure.
+ * Resolve stale quench-sourced feedback using the given store.
+ * Errors are silently caught — stale resolution is best-effort.
+ *
+ * @param {object} ctx - Orchestration context
+ * @param {string|undefined} currentVersion - Current artefact version, or undefined
+ * @param {object} store - Feedback store instance
  */
-async function resolveStaleQuenchFeedback(ctx, outputType) {
+async function resolveStaleQuenchFeedback(ctx, currentVersion, store) {
   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);
+    if (currentVersion === undefined || currentVersion === null) return;
+    await 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.
@@ -71,7 +81,6 @@ export async function runQuench(ctx) {
 }
 
 async function runQuenchWithStale(ctx, activeStageRecord, outputType) {
-  await resolveStaleQuenchFeedback(ctx, outputType);
   const artefactVersion = await computeArtefactVersion(
     ctx.foundryDir, outputType, ctx.io, ctx.cwd,
   ).catch(() => undefined);
@@ -111,6 +120,8 @@ async function processArtefacts(ctx, artefacts, activeStageRecord, outputType, a
   const perArtefact = [];
   const currentFeedback = [];
   let allOk = true;
+  ctx.store = openFeedbackStore('WORK.feedback.yaml', ctx.io);
+  await resolveStaleQuenchFeedback(ctx, artefactVersion, ctx.store);
 
   for (const artefact of artefacts) {
     const result = await performValidation({
@@ -177,12 +188,57 @@ function isAllErrors(result) {
   return result.items.length === 0 && result.errors.length > 0;
 }
 
+/**
+ * True when the candidate feedback item is a duplicate of an existing item
+ * that has already been addressed in the current or prior cycle iteration.
+ *
+ * actioned and wont-fix items are always treated as duplicates. resolved
+ * items are duplicates only when their artefact version matches the current
+ * version — a resolved item from a prior version should generate fresh
+ * feedback.
+ *
+ * NOTE: Uses `history[0]` as the most recent state. The feedback store
+ * must prepend new entries (not append) so that index 0 always holds the
+ * latest state. If the store implementation changes to append, this check
+ * and all consumers of `history[0]` will break.
+ */
+function isDuplicateFeedback(existing, artefactVersion) {
+  const state = existing.history[0].state;
+  if (state === 'actioned' || state === 'wont-fix') return true;
+  if (state === 'resolved' && existing.artefact_version === artefactVersion) return true;
+  return false;
+}
+
 /**
  * Post feedback items for validation results and track for resolution.
+ *
+ * Skips items whose file:tag:text already exists in actioned, wont-fix,
+ * or resolved state (with matching artefact version). This covers both
+ * the direct case (items the user has actioned or wont-fixed) and the
+ * stale-resolution case where items were advanced to resolved before
+ * validation runs. Prevents the quench → forge feedback accumulation
+ * loop when validators produce the same message across forge revisions.
  */
 function postFeedbackItems(ctx, artefact, result, currentFeedback, artefactVersion) {
+  const store = ctx.store;
+  const allItems = store.list();
+
   for (const item of result.items) {
     const tag = `law:${item.lawId}:${item.validatorId}`;
+    const textHash = hashText(item.text);
+
+    const existing = allItems.find(it =>
+      it.file === artefact.file &&
+      it.tag === tag &&
+      hashText(it.text) === textHash &&
+      isDuplicateFeedback(it, artefactVersion)
+    );
+
+    if (existing) {
+      currentFeedback.push({ file: artefact.file, tag });
+      continue;
+    }
+
     ctx.feedback.add({ file: artefact.file, text: item.text, tag, artefact_version: artefactVersion });
     currentFeedback.push({ file: artefact.file, tag });
   }

package/dist/scripts/sort.js

@@ -78,6 +78,25 @@ function isLegacyItem(item) {
   return !item.artefact_version || !SHA256_RE.test(item.artefact_version);
 }
 
+/**
+ * Counts how many forge runs this feedback item has actually consumed
+ * by scanning its history for forge-stage entries.
+ *
+ * Only entries whose stage base is 'forge' are counted — this covers
+ * successful forge transitions (actioned/wont-fix) as well as contract
+ * failures, which are now recorded with a `forge:<cycle>` stage.
+ *
+ * History entries that lack a `stage` field are silently ignored. Such
+ * entries originate from a different tracking subsystem and do not
+ * represent forge attempts against this item.
+ */
+function countForgeAttempts(item) {
+  return item.history.filter(e => {
+    const entryStage = e.stage || '';
+    return baseStage(entryStage) === 'forge';
+  }).length;
+}
+
 function loadFeedback(io, cycle) {
   const store = openFeedbackStore('WORK.feedback.yaml', io);
   const allItems = store.list();
@@ -95,6 +114,9 @@ function loadFeedback(io, cycle) {
       depth: item.history.length,
       source: item.source,
       artefact_version: item.artefact_version,
+      /** Number of forge runs this item has already consumed. Used by the
+       *  routing decision to enforce the max-iterations cap per item (SPEC R7). */
+      forge_count: countForgeAttempts(item),
     });
   }
 

package/dist/skills/forge/SKILL.md

@@ -6,7 +6,7 @@ description: Produces or revises an artefact, guided by WORK.md and the foundry
 
 # Forge
 
-You produce or revise artefacts. You read the work file to understand the goal, call `foundry_feedback_list` to understand feedback, and read the foundry cycle definition to understand what you're producing and what inputs you can read.
+You produce or revise artefacts. You read the work file to understand the goal and follow the feedback item in the dispatch prompt, and read the foundry cycle definition to understand what you're producing and what inputs you can read.
 
 ## Prerequisites
 
@@ -19,7 +19,7 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 Forge runs inside an enforced stage. Your **first** and **last** tool calls are fixed:
 
 1. **First:** `foundry_stage_begin({stage, cycle, token})` — the orchestrator hands you `stage`, `cycle`, and an opaque `token` string in the dispatch prompt. Copy the token verbatim; never invent, edit, or re-sign it. No other tool call is permitted before this one. Any writes before `stage_begin` will be blocked by preconditions.
-2. **Last:** `foundry_stage_end({summary})` — return control to the orchestrator. After `stage_end`, the orchestrator's internal finalize step scans the disk and registers your output artefact. **You do not register artefacts yourself.**
+2. **Last:** `foundry_stage_end({summary})` — return control to the orchestrator. After `stage_end`, the orchestrator's internal finalise step scans the disk and registers your output artefact. **You do not register artefacts yourself.**
 
 ## Protocol
 
@@ -54,31 +54,28 @@ Forge runs inside an enforced stage. Your **first** and **last** tool calls are
 ### Revision (feedback exists)
 
 1. `foundry_stage_begin(...)`.
-2. `foundry_feedback_list` — find feedback whose state is `open` or `rejected` for the current cycle.
-3. Read the artefact file.
-4. If the cycle declares `inputs`, discover them via filesystem scan against each input type's `file-patterns` (same protocol as first-generation step 6). Re-read the relevant files — they may have changed on disk since the previous iteration (nothing in this cycle wrote to them, but the user may have modified them between iterations).
-5. For each item whose state is `open` or `rejected`, follow the feedback handling rules below.
-6. Update the artefact file.
-7. `foundry_stage_end({summary})`.
+2. Read the artefact file.
+3. If the cycle declares `inputs`, discover them via filesystem scan against each input type's `file-patterns` (same protocol as first-generation step 6). Re-read the relevant files — they may have changed on disk since the previous iteration (nothing in this cycle wrote to them, but the user may have modified them between iterations).
+4. Address the single feedback item from the dispatch prompt following the feedback handling rules below — either fix the artefact, or for appraise-sourced items write a WONT-FIX justification in the summary.
+5. Update the artefact file.
+6. `foundry_stage_end({summary})`.
 
 ## Feedback handling
 
-Call `foundry_feedback_list` to see feedback items for the current cycle.
-Each entry has shape `{ id, file, tag, text, source, state, depth, reason? }`.
-Action every item whose `state` is `open` or `rejected`:
-
-- If you address the feedback in the artefact: call `foundry_feedback_action`
-  with `{ id }`. This marks the item `actioned`. The tool returns
-  `{ ok: true }` on success; keep using the original list entry's `id` for
-  any follow-up.
-- If you decide not to address the feedback: call `foundry_feedback_wontfix`
-  with `{ id, reason }`. The reason is required. **You may only mark
-  `wont-fix` on items whose `source` stage base is `appraise`.** If the
-  item's source base is `quench` (objective validation failure) or
-  `human-appraise` (direct user instruction), you must action it — the
-  tool will return an error if you attempt `wont-fix`. This replaces the
-  old tag-based restriction (`#validation`/`#human` tag check); tags are
-  now categorical/display-only and not consulted by the state machine.
+The dispatch prompt already contains the single feedback item for this
+iteration. Each item has the shape `{ id, file, tag, text, source, state,
+depth, reason? }`.
+
+Fix the issue by changing the artefact — the orchestrator records the item
+as actioned when it detects your changes on disk.
+
+For items whose `source` stage base is `appraise` only, you may instead
+respond with `WONT-FIX: <justification>` in the `foundry_stage_end`
+summary. The orchestrator records the item as wont-fix.
+
+Items whose source base is `quench` (objective validation failure) or
+`human-appraise` (direct user instruction) are deterministic failures that
+**must** be fixed. There is no wont-fix option for these.
 
 `foundry_feedback_add` (if you ever call it — forge normally does not)
 returns `{ ok, id, deduped }`. `deduped: true` means an existing
@@ -88,8 +85,7 @@ new item was written; the returned `id` is the existing item's id.
 
 You cannot resolve or reject items — only the stage that created the item
 (the `source` on each list entry) can do that, with the exception that
-human-appraise can override any non-resolved item. You also cannot action
-items whose state is `actioned`, `wont-fix`, `deadlocked`, or `resolved`.
+human-appraise can override any non-resolved item.
 
 ## Write invariant
 
@@ -97,7 +93,7 @@ Forge may only write to:
 - Files matching the output artefact type's `file-patterns`.
 - `WORK.md`, `WORK.feedback.yaml`, and `WORK.history.yaml` (tool-managed).
 
-Everything else on disk — including files of the cycle's input types, files of unrelated artefact types, and files outside any artefact type — is read-only for this stage. This rule is tool-enforced: the orchestrator's internal finalize step returns `{error: 'unexpected_files'}` and the orchestrator's modified-file check routes a violation on the next call. Either outcome marks the cycle's target artefact `blocked` and you do not get a retry.
+Everything else on disk — including files of the cycle's input types, files of unrelated artefact types, and files outside any artefact type — is read-only for this stage. This rule is tool-enforced: the orchestrator's internal finalise step returns `{error: 'unexpected_files'}` and the orchestrator's modified-file check routes a violation on the next call. Either outcome marks the cycle's target artefact `blocked` and you do not get a retry.
 
 When a cycle's output type overlaps with one of its input types (e.g. a `refine-haiku` cycle with input `haiku` and output `haiku`), the overlap is intentional: the cycle's job is to modify existing files of that type. The write invariant still holds — you may only touch files matching the output type's patterns, which in this case includes the files you read as inputs.
 
@@ -113,9 +109,8 @@ items in the list output.
 
 - You normally do not add feedback — that is the quench and appraise skills' job.
 - You do not `foundry_feedback_resolve` — that belongs to quench/appraise/human-appraise.
-- You do not register artefacts — the orchestrator's internal finalize step handles that automatically.
+- You do not register artefacts — the orchestrator's internal finalise step handles that automatically.
 - You do not call `foundry_history_append` or `foundry_git_commit` — `foundry_orchestrate` does (those tools are not registered publicly).
 - You do not evaluate or score the artefact.
-- You do not mark feedback as actioned unless you actually changed the artefact to address it.
-- You do not wont-fix items whose `source` stage base is `quench` or `human-appraise`.
+- You do not mark feedback as actioned or wont-fix via tool calls — the orchestrator handles feedback transitions based on your artefact changes and `stage_end` summary.
 - You do not write to any file outside the output artefact type's `file-patterns` (plus `WORK.md` / `WORK.feedback.yaml` / `WORK.history.yaml`). Input files are read-only unless the output type's patterns happen to cover them.

package/dist/skills/orchestrate/SKILL.md

@@ -111,12 +111,12 @@ Report to the user: "Cycle halted (violation): `<details>`. Affected files: `<af
 
 ## Feedback visibility
 
-Orchestrate's loop does not read, parse, or write feedback directly.
-Subagents invoked via `dispatch` use the `foundry_feedback_list` /
-`foundry_feedback_add` / `foundry_feedback_action` / `foundry_feedback_wontfix`
-/ `foundry_feedback_resolve` tools themselves; orchestrate does not stage
-feedback state between iterations. If you want to inspect feedback state
-between iterations for diagnostic purposes, call `foundry_feedback_list` —
-the response shape is `[{ id, file, tag, text, source, state, depth,
-reason? }]`. This is read-only and does not affect the loop's dispatch
-decisions.
+The orchestrator manages forge feedback transitions directly. After each
+forge subagent completes, `enforceForgeStage` inspects the outcome — a
+version change or a WONT-FIX in the stage-end summary — and transitions the
+feedback item to `actioned` or `wont-fix`. Forge subagents do not call
+`foundry_feedback_action` or `foundry_feedback_wontfix`; those are the
+orchestrator's responsibility. If you want to inspect feedback state for
+diagnostic purposes, call `foundry_feedback_list` — the response shape is
+`[{ id, file, tag, text, source, state, depth, reason? }]`. This is
+read-only and does not affect the loop's dispatch decisions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@really-knows-ai/foundry",
-  "version": "3.6.2",
+  "version": "3.7.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",