@really-knows-ai/foundry 3.5.8 → 3.6.0

package/dist/scripts/orchestrate-terminals.js

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

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

@@ -29,38 +29,6 @@ import {
   getDirtyToolManagedFiles,
 } from './lib/sort-fs-check.js';
 
-// ---------------------------------------------------------------------------
-// Top-level deadlock pass (spec §6.1)
-// ---------------------------------------------------------------------------
-
-/**
- * Walk the feedback store and write a `state=deadlocked` snapshot for every
- * non-resolved item whose history depth has reached the configured threshold.
- * One atomic batch write via `store.writeDeadlockedSnapshots(ids, ...)`.
- *
- * Sort is the only writer of `state=deadlocked` per spec §6.1.
- *
- * @returns {boolean} true iff at least one snapshot was written.
- */
-function runDeadlockPass(store, { threshold, enabled, cycle }) {
-  if (!enabled) return false;
-  const qualifying = store.list().filter(item => {
-    // history[0] is the most recent state per the feedback-store invariant
-    // (entries are prepended to keep newest at head).
-    const head = item.history[0];
-    if (head.state === 'resolved' || head.state === 'deadlocked') return false;
-    return item.history.length >= threshold;
-  });
-  if (qualifying.length === 0) return false;
-  store.writeDeadlockedSnapshots(
-    qualifying.map(it => it.id),
-    `depth >= threshold=${threshold}`,
-    'sort',
-    cycle,
-  );
-  return true;
-}
-
 // ---------------------------------------------------------------------------
 // runSort — structured result for programmatic use
 // ---------------------------------------------------------------------------
@@ -85,13 +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,
-    humanAppraiseEnabled: frontmatter['human-appraise'] === true,
-    deadlockAppraise: frontmatter['deadlock-appraise'] !== false,
-    deadlockIterations: frontmatter['deadlock-iterations'] ?? maxIt,
+    alwaysHumanAppraise: frontmatter['always-human-appraise'] === true,
+    deadlockHumanAppraise: frontmatter['deadlock-human-appraise'] === true,
   };
 }
 
@@ -105,17 +72,33 @@ function checkDirtyFiles(history, io) {
     + `Re-run foundry_orchestrate or commit the listed files manually before retrying.`;
 }
 
-function loadFeedbackAndRunDeadlock(cycle, deadlockIterations, deadlockAppraise, io) {
+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);
-  runDeadlockPass(store, { threshold: deadlockIterations, enabled: deadlockAppraise, cycle });
-  const feedback = store.list().map(item => ({
-    id: item.id,
-    file: item.file,
-    state: item.history[0].state,
-    depth: item.history.length,
-  }));
-  const anyDeadlocked = feedback.some(f => f.state === 'deadlocked');
-  return { feedback, anyDeadlocked };
+  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) {
@@ -138,15 +121,15 @@ function getCurrentNonSortStage(nonSortHistory) {
   return nonSortHistory.length > 0 ? nonSortHistory[nonSortHistory.length - 1].stage : null;
 }
 
-function resolveDeadlockRoute(stages, nonSortHistory, cycle) {
-  const currentNonSort = getCurrentNonSortStage(nonSortHistory);
-  if (currentNonSort && baseStage(currentNonSort) === 'human-appraise') return 'blocked';
-  return findFirst(stages, 'human-appraise') || `human-appraise:${cycle}`;
-}
-
 function resolveRoute(ctx) {
-  if (ctx.anyDeadlocked) return resolveDeadlockRoute(ctx.stages, ctx.nonSortHistory, ctx.cycle);
-  return determineRoute(ctx.stages, ctx.history, ctx.feedback, ctx.maxIterations);
+  return determineRoute(
+    ctx.stages, ctx.history, ctx.feedback, ctx.maxIterations,
+    {
+      alwaysHumanAppraise: ctx.alwaysHumanAppraise,
+      deadlockHumanAppraise: ctx.deadlockHumanAppraise,
+      cycle: ctx.cycle,
+    },
+  );
 }
 
 function firstModelValue(models) {
@@ -215,9 +198,7 @@ function preparePhases({ workPath, historyPath, foundryDir, cycleDef, io }) {
   const history = loadHistory(historyPath, cycle, io);
   const dirtyError = checkDirtyFiles(history, io);
   if (dirtyError) return { kind: 'violation', details: dirtyError };
-  const { feedback, anyDeadlocked } = loadFeedbackAndRunDeadlock(
-    cycle, defaults.deadlockIterations, defaults.deadlockAppraise, io,
-  );
+  const feedback = loadFeedback(io, cycle);
   const fileCheck = checkModifiedFilesAfterLastStage({
     history, foundryDir, cycleDef, cycle, frontmatter, io,
   });
@@ -225,7 +206,7 @@ function preparePhases({ workPath, historyPath, foundryDir, cycleDef, io }) {
   if (violation) return { kind: 'violation', details: violation };
   return {
     kind: 'ok',
-    frontmatter, cycle, stages, defaults, history, feedback, anyDeadlocked,
+    frontmatter, cycle, stages, defaults, history, feedback,
     nonSortHistory: fileCheck.nonSortHistory,
   };
 }
@@ -253,8 +234,9 @@ function buildRouteCtx(prep) {
     history: prep.history,
     feedback: prep.feedback,
     maxIterations: prep.defaults.maxIterations,
+    alwaysHumanAppraise: prep.defaults.alwaysHumanAppraise,
+    deadlockHumanAppraise: prep.defaults.deadlockHumanAppraise,
     cycle: prep.cycle,
-    anyDeadlocked: prep.anyDeadlocked,
     nonSortHistory: prep.nonSortHistory,
   };
 }
@@ -283,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/dist/skills/add-cycle/SKILL.md

@@ -38,7 +38,7 @@ Do not tell the user to call branch tools directly.
 
 When invoked with pre-filled fields matching the `foundry_config_create_cycle` tool args, skip questions for provided fields. Missing fields trigger clarifying questions.
 
-Context fields: `{id, name, outputType, description, inputs?, targets?, humanAppraise?, deadlockAppraise?, deadlockIterations?, maxIterations?, assay?, memory?, models?}`
+Context fields: `{id, name, outputType, description, inputs?, targets?, alwaysHumanAppraise?, deadlockHumanAppraise?, maxIterations?, assay?, memory?, models?}`
 
 `inputs` is optional. A source cycle that starts from the user's run goal and has no upstream artefact dependency omits `inputs` entirely. Empty input contracts are invalid: do not pass `inputs: {type: "any-of", artefacts: []}`.
 
@@ -85,12 +85,12 @@ If the parent flow or required artefact type is missing and the user's goal clea
 **Optional clusters** — After each cluster, ask whether the user wants to configure it; if not, skip:
 
 - **Routing**: `inputs` (input contract: `{type: "any-of"|"all-of", artefacts: string[]}`; omit for source cycles with no upstream artefact dependency), `targets` (cycle IDs to route to after completion), `maxIterations` (maximum iterations before forced progression)
-- **Human-appraise**: `humanAppraise` (boolean, default false) — human reviews every iteration; `deadlockAppraise` (boolean, default true) — human is pulled in when LLM appraisers deadlock; `deadlockIterations` (number, defaults to `max-iterations` value) — deadlock threshold. Only applies when either appraise is enabled.
+- **Human-appraise**: `alwaysHumanAppraise` (boolean, default false) — human reviews every iteration; when true, `max-iterations` is not enforced. `deadlockHumanAppraise` (boolean, default true) — route to human for review when the iteration cap is reached, instead of blocking the cycle. Only applies when `alwaysHumanAppraise` is false.
 - **Memory and models**: `assay` (assay configuration), `memory` (memory configuration), `models` (stage-specific model overrides, e.g. `{forge: "openai/gpt-4o", appraise: "openai/gpt-4o"}`). For models, offer each stage (forge, quench, appraise) individually. If the user has no preference, omit the `models` map and use the session defaults.
 
 ### 2. Plan
 
-Present a structured summary of the cycle definition: id, name, outputType, description, and any configured optional fields (inputs, targets, humanAppraise, deadlockAppraise, deadlockIterations, maxIterations, assay, memory, models). Include only fields that have values.
+Present a structured summary of the cycle definition: id, name, outputType, description, and any configured optional fields (inputs, targets, alwaysHumanAppraise, deadlockHumanAppraise, maxIterations, assay, memory, models). Include only fields that have values.
 
 Ask: "Does this capture the cycle correctly?" Iterate until the user is satisfied.
 
@@ -102,7 +102,7 @@ Ask: "Proceed with this plan?" — wait for user answer before building. If the
 
 1. **Validate**: Call `foundry_config_validate_cycle({ name: "<id>", body: "<assembled markdown>" })`. Assemble the body from the fields using the frontmatter format the tool produces internally. If the result is `{ ok: false, errors: [...] }`, address each error and re-run until `{ ok: true }`. Common issues: missing required frontmatter keys, references to artefact types or flows that do not exist yet.
 
-2. **Create**: Call `foundry_config_create_cycle({ id: "<id>", name: "<name>", outputType: "<type>", description: "<description>", targets: ..., humanAppraise: ..., deadlockAppraise: ..., deadlockIterations: ..., maxIterations: ..., assay: ..., memory: ..., models: ... })`. Include `inputs` only when the cycle reads upstream artefacts, and include `models` whenever the user selected stage-specific model overrides. The tool:
+2. **Create**: Call `foundry_config_create_cycle({ id: "<id>", name: "<name>", outputType: "<type>", description: "<description>", targets: ..., alwaysHumanAppraise: ..., deadlockHumanAppraise: ..., maxIterations: ..., assay: ..., memory: ..., models: ... })`. Include `inputs` only when the cycle reads upstream artefacts, and include `models` whenever the user selected stage-specific model overrides. The tool:
    - re-validates the body (TOCTOU);
    - writes `foundry/cycles/<id>.md`;
    - produces one git commit on the current `config/*` branch.

package/dist/skills/add-flow/SKILL.md

@@ -69,7 +69,7 @@ Create missing dependencies in validation order:
 
 3. **Appraisers** (may reference models): For each new appraiser, gather `id`, `name`, `description`, and optional `model` preference. Context object: `{id, name, description, model?}`.
 
-4. **Cycles** (reference artefact types, laws, appraisers): For each new cycle, gather `id`, `name`, `outputType`, `description`, and any optional settings (inputs, targets, appraise, assay, memory, models). Context object: `{id, name, outputType, description, inputs?, targets?, humanAppraise?, deadlockAppraise?, deadlockIterations?, maxIterations?, assay?, memory?, models?}`. For a source cycle that starts from the user's run goal and has no upstream artefact dependency, omit `inputs` entirely; never pass `inputs` with an empty `artefacts` array.
+4. **Cycles** (reference artefact types, laws, appraisers): For each new cycle, gather `id`, `name`, `outputType`, `description`, and any optional settings (inputs, targets, appraise, assay, memory, models). Context object: `{id, name, outputType, description, inputs?, targets?, alwaysHumanAppraise?, deadlockHumanAppraise?, maxIterations?, assay?, memory?, models?}`. For a source cycle that starts from the user's run goal and has no upstream artefact dependency, omit `inputs` entirely; never pass `inputs` with an empty `artefacts` array.
 
 For the haiku example, default to a `haiku` artefact type, `haikus/*.md` file pattern, laws for form, imagery, and mood, a deterministic syllable validator where project dependencies allow it, two or three distinct appraisers, one cycle, and one flow.
 

package/dist/skills/human-appraise/SKILL.md

@@ -6,7 +6,7 @@ description: Human quality gate. Presents the artefact to the human for review a
 
 # Human Appraise
 
-You are a human quality gate. Sort has routed to you either because the LLM appraisers have finished (normal flow) or because a deadlock was detected between forge and appraisers.
+You are a human quality gate. Sort has routed to you for the human to review the current artefact and provide feedback or approve.
 
 ## Prerequisites
 
@@ -31,7 +31,7 @@ When invoked from orchestrate, you receive `{cycle, token, context}`:
 - `cycle` — the current cycle id
 - `token` — single-use token for `foundry_stage_begin`
 - `context.artefact_file` — the target artefact
-- `context.recent_feedback` — recent deadlocked feedback items to present to the user
+- `context.recent_feedback` — recent unresolved feedback items to present to the user
 
 Your FIRST tool call must be `foundry_stage_begin({stage: 'human-appraise:<cycle>', cycle, token})`.
 
@@ -63,31 +63,24 @@ Your LAST tool call must be `foundry_stage_end({summary: '<one-sentence descript
 4. Present to the human:
    - The current artefact content (full file content or multi-file diff)
    - A summary of this iteration's feedback (resolved and open)
-   - If this is a deadlock escalation, clearly explain the deadlock:
-     - Which feedback item(s) are stuck
-     - The appraiser's reasoning
-     - Forge's wont-fix or revision justification
-     - Ask the human to resolve the disagreement
+   - Ask the human to review, provide feedback, or approve
 
 5. Wait for the human's response.
 
 6. Act on the response (tag MUST be `human` on any added feedback — the tool rejects other tags during human-appraise):
    - **Approve** — "looks good" / "continue" — no feedback added, sort will advance.
    - **Provide feedback** — `foundry_feedback_add({ file, text, tag: 'human' })`. Sort will route back to forge.
-   - **Resolve feedback** — `foundry_feedback_resolve({ id, resolution, reason? })` for items in `{actioned, wont-fix, deadlocked}`. See "Feedback handling" below for the legal transitions and authority rules.
+   - **Resolve feedback** — `foundry_feedback_resolve({ id, resolution, reason? })` for items in `{actioned, wont-fix}`. See "Feedback handling" below for the legal transitions and authority rules.
    - **Abort** — human-appraise cannot directly mark the artefact `blocked` (the repository no longer has a per-artefact status tool or table). To abort: end the stage with a summary explaining the abort, then either (a) instruct the user to call `foundry_workfile_delete({ confirm: true })` to discard the cycle, or (b) reject outstanding feedback so routing exhausts iterations and sort blocks the cycle on its own.
 
 7. `foundry_stage_end({summary})` — describe what the human decided so sort can log it.
 
 ## Feedback handling
 
-As a human-appraise stage, you can add human feedback and resolve feedback
-items (including deadlock overrides). **Human-appraise can resolve any
-non-resolved source-stage item regardless of source** — this is the
-universal override authority recorded in spec §5.1 rule 5. It is not
-limited to deadlocked items, though in practice most overrides today are
-on deadlocked items because default sort routing only surfaces deadlocked
-items to human-appraise (see §17 future-work note below).
+As a human-appraise stage, you can add human feedback and resolve
+feedback items. **Human-appraise can resolve any non-resolved
+source-stage item regardless of source** — this is the universal
+override authority recorded in spec §5.1 rule 5.
 
 What human-appraise can NOT do:
 
@@ -109,37 +102,16 @@ What human-appraise CAN do:
    found and no new snapshot was written, `deduped: false` indicates a new
    item was created.
 
-2. **Resolve any non-resolved source-stage item.** For items in
-   `{actioned, wont-fix}` (sourced from quench, appraise, or
-   human-appraise), call `foundry_feedback_resolve` with
+2. **Resolve any non-resolved item.** For items in
+   `{actioned, wont-fix}`, call `foundry_feedback_resolve` with
    `{ id, resolution: 'approved' | 'rejected', reason? }`. Human-appraise
    may resolve any such item regardless of source, including items from
    other stage ids.
 
-3. **Resolve deadlocked items.** When items reach `state: deadlocked`
-   (written by sort when an item's history depth hits
-   `deadlock-iterations`), human-appraise is the ONLY stage authorised
-   to resolve them. Call `foundry_feedback_resolve` with
-   `{ id, resolution: 'approved' | 'rejected', reason: '...' }`.
-   `reason` is always required on deadlock override — it documents why
-   the deadlock is being broken. After human-appraise resolves every
-   deadlocked item, the cycle resumes normal forge/appraise routing. If
-   deadlocks remain after human-appraise, the cycle blocks (per spec §5.2).
-
 **Reason rules.** `reason` is required when rejecting feedback
-(`resolution: 'rejected'`) and when overriding a deadlocked item.
-Non-deadlocked approved resolution via
+(`resolution: 'rejected'`). Approved resolution via
 `foundry_feedback_resolve({ id, resolution: 'approved', reason? })` may
-omit `reason`; deadlock override always requires `reason` to document why
-the deadlock is being broken.
-
-**Future work.** Spec §17 notes that a cycle-level mode flag letting
-human-appraise see all unresolved feedback (not just deadlocked items)
-before sort routes is planned for a future release. In v2.6.0 the
-authority is universal but reachability is limited — you typically only
-see deadlocked items on the route from sort. If you do see non-deadlocked
-items (e.g. you were invoked directly by the user), the same authority
-applies.
+omit `reason`.
 
 ## What you do NOT do
 

package/package.json

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