@really-knows-ai/foundry 3.5.8 → 3.5.9

package/dist/docs/work-spec.md

@@ -32,9 +32,8 @@ flow: <flow-id>
 cycle: <current-cycle-id>
 stages: [forge:write-haiku, quench:check-syllables, appraise:evaluate-quality]
 max-iterations: 3
-human-appraise: false
-deadlock-appraise: true
-deadlock-iterations: 5
+always-human-appraise: false
+deadlock-human-appraise: true
 models:
   forge: anthropic/claude-opus-4.7
   appraise: openai/gpt-5
@@ -46,21 +45,21 @@ assay:
 Fields:
 - `flow` — the foundry flow being executed.
 - `cycle` — the current cycle id.
-- `stages` — the ordered route for this cycle. Each entry uses `base:alias` format where `base` is the stage type (`forge`, `quench`, `appraise`, `human-appraise`, or `assay`) and `alias` is a human-readable name for what that stage does in this cycle. The list is derived from the cycle and artefact type: `forge` and `appraise` are always included; `quench` is included iff any applicable law declares validators; `human-appraise` is included iff the cycle sets `human-appraise: true`; and `assay` is included iff the cycle declares an `assay.extractors` block.
+- `stages` — the ordered route for this cycle. Each entry uses `base:alias` format where `base` is the stage type (`forge`, `quench`, `appraise`, `human-appraise`, or `assay`) and `alias` is a human-readable name for what that stage does in this cycle. The list is derived from the cycle and artefact type: `forge` and `appraise` are always included; `quench` is included iff any applicable law declares validators; `human-appraise` is included iff the cycle sets `always-human-appraise: true`; and `assay` is included iff the cycle declares an `assay.extractors` block.
 - `max-iterations` — how many forge passes before the cycle is blocked (default: 3).
-- `human-appraise` — run human-appraise every iteration (default: `false`).
-- `deadlock-appraise` — route to human-appraise when LLM appraisers deadlock (default: `true`).
-- `deadlock-iterations` — deadlock threshold (default: 5).
+- `always-human-appraise` — run human-appraise every iteration (default: `false`).
+- `deadlock-human-appraise` — route to human-appraise when the iteration count reaches `max-iterations` (default: `true`).
 - `models` — optional per-stage model overrides; individual appraisers may further override via their own `model` field.
 - `assay.extractors` — optional list of extractor names (defined under `foundry/memory/extractors/`) to run at iteration 0 before the first forge. Requires `foundry/memory/` to be initialized; cycle fails to load otherwise.
 
-The `stages` list is the happy path. Sort follows it, loops back to `forge` when unresolved feedback demands it, and may insert `human-appraise` on deadlock. If `assay` is configured, it runs once at iteration 0 before the route begins.
+The `stages` list is the happy path. Sort follows it, loops back to `forge` when unresolved feedback demands it, and routes to `human-appraise` when the iteration count reaches `max-iterations` (provided `deadlock-human-appraise` is `true`). If `assay` is configured, it runs once at iteration 0 before the route begins.
 
 ### Who sets what
 
 - `flow`, `cycle` — set by the `flow` skill via `foundry_workfile_create` at flow start and updated as the flow advances between cycles.
 - `goal` — written once by the `flow` skill when `WORK.md` is created.
-- `stages`, `max-iterations`, `human-appraise`, `deadlock-appraise`, `deadlock-iterations`, `models`, `assay` — set by `foundry_orchestrate` on the first call of each cycle (via internal `workfile_configure_from_cycle`, reading the cycle definition).
+- `stages`, `max-iterations`, `always-human-appraise`, `deadlock-human-appraise`, `models`, `assay` — set by `foundry_orchestrate` on the first call of each cycle (via internal `workfile_configure_from_cycle`, reading the cycle definition).
+- The frontmatter may also contain `status: failed` with a `reason` when the flow enters a failed state, locking all mutation tools.
 
 ## Sections
 
@@ -68,22 +67,6 @@ The `stages` list is the happy path. Sort follows it, loops back to `forge` when
 
 Free text describing what the foundry flow is producing and any context the human provided. Written once at foundry flow start, not modified after.
 
-### Artefacts
-
-A table tracking every artefact produced by the foundry flow. The generator (`createWorkfile` in `src/scripts/lib/workfile.js`) writes the table immediately after the `# Goal` body — there is no `# Artefacts` heading. The orchestrator's internal finalise step appends rows for matching output files; authoring tools should not edit the artefacts table directly.
-
-```markdown
-| File | Type | Cycle | Status |
-|------|------|-------|--------|
-| petitions/login-change.md | petition | write-petition | draft |
-| features/login-change.feature | gherkin | petition-to-gherkin | draft |
-```
-
-Statuses:
-- `draft` — artefact exists but has not cleared all stages
-- `done` — artefact has cleared all stages
-- `blocked` — artefact hit iteration limit or a violation
-
 ## WORK.feedback.yaml
 
 The flow run owns one `WORK.feedback.yaml` file alongside `WORK.md` and
@@ -113,40 +96,48 @@ Each history snapshot:
 
 | Field | Type | Required | Notes |
 |-------|------|----------|-------|
-| `state` | enum | yes | `open \| actioned \| wont-fix \| rejected \| deadlocked \| resolved` |
+| `state` | enum | yes | `open \| actioned \| wont-fix \| rejected \| resolved` |
 | `stage` | string (`base:alias`) or literal `sort` | yes | Who performed the transition |
 | `cycle` | string | yes | Cycle id at the time of the transition |
 | `timestamp` | ISO-8601 UTC with ms | yes | |
-| `reason` | string | conditional | Required on `rejected`, `wont-fix`, `deadlocked`, `resolved`; forbidden on `open`; optional on `actioned` |
+| `reason` | string | conditional | Required on `rejected`, `wont-fix`; forbidden on `open`; optional on `actioned`, `resolved` |
 
 `history[0]` is always the current state; new snapshots are prepended.
 `resolved` is terminal.
 
 ### State machine
 
-Feedback items flow through a six-state lifecycle: `open` (newly raised), `actioned` (forge has addressed it), `wont-fix` (forge declined subjective feedback with justification), `rejected` (appraiser or human overruled the wont-fix), `deadlocked` (sort detected repeated forge/appraise iterations on the same item), and `resolved` (approved by the item's originating stage or human override). Transitions are source-based: the legal moves depend on what stage created the item and who is trying to transition it. The feedback state machine is the engine that routes work between cycles.
+Feedback items flow through a five-state lifecycle: `open` (newly raised), `actioned` (forge has addressed it), `wont-fix` (forge declined subjective feedback with justification), `rejected` (appraiser or human overruled the wont-fix), and `resolved` (approved by the item's originating stage or human override). Transitions are source-based: the legal moves depend on what stage created the item and who is trying to transition it. The feedback state machine is the engine that routes work between cycles.
 
-The six states and the legal transitions are:
+The five states and the legal transitions are:
 
-| From \ Caller | forge (any source) | source-stage (quench / appraise / human-appraise where stageId === item.source) | sort | human-appraise (override authority, any source) |
-|---|---|---|---|---|
-| `open` | -> `actioned` always; -> `wont-fix` only if `item.source` base is `appraise` | — | -> `deadlocked` (if depth >= threshold) | — |
-| `rejected` | -> `actioned` always; -> `wont-fix` only if `item.source` base is `appraise` | — | -> `deadlocked` (if depth >= threshold) | — |
-| `actioned` | — | -> `{resolved, rejected}` | -> `deadlocked` (if depth >= threshold) | -> `{resolved, rejected}` |
-| `wont-fix` | — | -> `{resolved, rejected}` | -> `deadlocked` (if depth >= threshold) | -> `{resolved, rejected}` |
-| `deadlocked` | — | — | — | -> `{resolved, rejected}` |
-| `resolved` | — | — | — | — (terminal) |
+| From \ Caller | forge (any source) | source-stage (quench / appraise / human-appraise where stageId === item.source) | human-appraise (override authority, any source) |
+|---|---|---|---|
+| `open` | -> `actioned` always; -> `wont-fix` only if `item.source` base is `appraise` | — | — |
+| `actioned` | — | -> `{resolved, rejected}` | -> `{resolved, rejected}` |
+| `wont-fix` | — | -> `{resolved, rejected}` | -> `{resolved, rejected}` |
+| `rejected` | -> `actioned` always; -> `wont-fix` only if `item.source` base is `appraise` | — | — |
+| `resolved` | — | — | — (terminal) |
 
 Notes:
 
-- `source-stage` column applies when the caller's stage id exactly matches `item.source` (e.g. `appraise:write-check` resolving an item it created). `human-appraise` override authority (last column) applies regardless of `item.source` and is the only path that can transition out of `deadlocked`.
+- `source-stage` column applies when the caller's stage id exactly matches `item.source` (e.g. `appraise:write-check` resolving an item it created). `human-appraise` override authority (last column) applies regardless of `item.source` and operates only on items in `actioned` or `wont-fix` state (or `deadlocked` for backward compatibility with existing feedback files).
 - **Forge `wont-fix` scope.** When `item.source` base is `quench` (objective validation failure) or `human-appraise` (direct user instruction), forge may not `wont-fix` — it must `actioned`. Only `appraise`-sourced items are wont-fix-able by forge. This replaces the earlier tag-based restriction on `validation` / `human` tags.
-- `tag` is categorical and display-only. The state machine consults `source`, not tags; `validation` / `human` tag-based restrictions are legacy and do not apply.
-- **Reason required on** `rejected`, `wont-fix`, `deadlocked`, `resolved`. **Forbidden on** `open`. **Optional on** `actioned` (the code change is the reason).
-- Sort is the only writer of `state: deadlocked`; it writes these via its internal pass, not through the plugin API.
+- `tag` is categorical and display-only. The state machine consults `source`, not tags.
+- **Reason required on** `rejected`, `wont-fix`. **Forbidden on** `open`. **Optional on** `actioned`, `resolved`.
+- Sort does not write `state: deadlocked`. Deadlock detection in sort uses iteration count comparison against `max-iterations` and `deadlock-human-appraise` to decide whether to route to human-appraise, not per-item deadlock state. The feedback-transition validator still recognises `deadlocked` state for backward compatibility with existing feedback files.
 
 This section is the authoritative specification of the feedback state machine.
 
+### Feedback tag gates
+
+`foundry_feedback_add` enforces per-stage tag rules:
+
+- **forge** and **assay** stages cannot add feedback; the tool returns an error.
+- **quench** and **appraise** stages require tags starting with `law:`.
+- **human-appraise** requires the tag `human`.
+- Quench validator feedback uses the tag format `law:<law-id>:<validator-id>`.
+
 ### Transitions are made via the plugin API
 
 No direct yaml editing. Every state change goes through one of:
@@ -166,10 +157,10 @@ A crash between the two steps leaves the live file untouched.
 | Section | Written by | Updated by |
 |---------|-----------|------------|
 | Frontmatter (`flow`, `cycle`) | `foundry_workfile_create` (flow skill) | updated in place as the flow advances between cycles |
-| Frontmatter (`stages`, `max-iterations`, `human-appraise`, `deadlock-appraise`, `deadlock-iterations`, `models`) | `foundry_orchestrate` (first call of each cycle, internally) | reset on each new cycle |
+| Frontmatter (`stages`, `max-iterations`, `always-human-appraise`, `deadlock-human-appraise`, `models`, `assay`) | `foundry_orchestrate` (first call of each cycle, internally) | reset on each new cycle |
 | Goal | `foundry_workfile_create` (flow skill) | nobody |
 | Artefact files | forge stage writes files on disk | git tracks file changes; cycle-level state records completion or failure |
-| `WORK.feedback.yaml` | `foundry_feedback_add` (`quench` / `appraise` / `human-appraise`) | `foundry_feedback_action` / `foundry_feedback_wontfix` (forge), `foundry_feedback_resolve` (source stage / human-appraise override); sort writes only deadlocked snapshots |
+| `WORK.feedback.yaml` | `foundry_feedback_add` (`quench` / `appraise` / `human-appraise`) | `foundry_feedback_action` / `foundry_feedback_wontfix` (forge), `foundry_feedback_resolve` (source stage / human-appraise override) |
 | `WORK.history.yaml` | `foundry_orchestrate` | `foundry_orchestrate` |
 
 Artefact files are discovered from branch changes matching the cycle output type's `file-patterns`.
@@ -231,7 +222,8 @@ A separate file (`WORK.history.yaml`) alongside WORK.md. Append-only log of ever
 | `timestamp` | ISO-8601 UTC with ms | yes | |
 | `seq` | integer | yes on write | Monotonic per file; sort tiebreaker for same-ms entries |
 | `route` | string | conditional | Only on `stage: sort` entries; records the route decision. Throws if set on a non-sort entry |
-| `open_feedback` | integer | yes on write | Count of non-resolved items in `WORK.feedback.yaml` at the time of write; deadlocked items are counted |
+| `open_feedback` | integer | yes on write | Count of non-resolved items in `WORK.feedback.yaml` at the time of write |
+| `changed_files` | array of strings | conditional | Only on stage entries; records the list of files detected as changed by the finalise step for that stage |
 
 ### Rules
 
@@ -265,9 +257,8 @@ flow: make-haiku
 cycle: haiku-creation
 stages: [forge:write-haiku, quench:check-syllables, appraise:evaluate-quality]
 max-iterations: 3
-human-appraise: false
-deadlock-appraise: true
-deadlock-iterations: 5
+always-human-appraise: false
+deadlock-human-appraise: true
 ---
 
 # Goal
@@ -275,9 +266,4 @@ deadlock-iterations: 5
 Write a haiku about autumn rain. Should evoke loneliness
 and the sound of rain on leaves.
 
-| File | Type | Cycle | Status |
-|------|------|-------|--------|
-| petitions/autumn-rain-haiku.md | petition | haiku-ideation | done |
-| haiku/autumn-rain.md | haiku | haiku-creation | draft |
-
 ```

package/dist/scripts/lib/config-creators/cycle.js

@@ -52,14 +52,11 @@ function renderModels(models) {
 /** Render boolean and numeric flags (camelCase to kebab-case). */
 function renderFlags(args) {
   let fm = '';
-  if (args.humanAppraise !== undefined) {
-    fm += `human-appraise: ${args.humanAppraise}\n`;
+  if (args.alwaysHumanAppraise !== undefined) {
+    fm += `always-human-appraise: ${args.alwaysHumanAppraise}\n`;
   }
-  if (args.deadlockAppraise !== undefined) {
-    fm += `deadlock-appraise: ${args.deadlockAppraise}\n`;
-  }
-  if (args.deadlockIterations !== undefined) {
-    fm += `deadlock-iterations: ${args.deadlockIterations}\n`;
+  if (args.deadlockHumanAppraise !== undefined) {
+    fm += `deadlock-human-appraise: ${args.deadlockHumanAppraise}\n`;
   }
   if (args.maxIterations !== undefined) {
     fm += `max-iterations: ${args.maxIterations}\n`;
@@ -76,9 +73,8 @@ function renderFlags(args) {
  * @param {string} args.outputType       Artefact type ID this cycle produces.
  * @param {{ type: 'any-of'|'all-of', artefacts: string[] }} [args.inputs]  Input contract.
  * @param {string[]} [args.targets]      Downstream cycle IDs.
- * @param {boolean} [args.humanAppraise] Include human-appraise in every iteration.
- * @param {boolean} [args.deadlockAppraise] Route to human-appraise on deadlock.
- * @param {number} [args.deadlockIterations] Iteration threshold for deadlock detection.
+ * @param {boolean} [args.alwaysHumanAppraise] Include human-appraise in every iteration.
+ * @param {boolean} [args.deadlockHumanAppraise] Route to human-appraise when max-iterations is reached.
  * @param {number} [args.maxIterations]  Maximum forge iterations.
  * @param {{ extractors: string[] }} [args.assay]  Assay stage config.
  * @param {{ read: string[], write: string[] }} [args.memory]  Flow memory permissions.

package/dist/scripts/lib/config-validators/cycle.js

@@ -29,7 +29,6 @@ export async function validate({ name, body, io }) {
     await checkOutputType(fm, io),
     ...await checkInputs(fm, io),
     ...await checkTargets(fm, io),
-    checkIterationLimits(fm),
   ].filter(Boolean);
 
   return errors.length ? { ok: false, errors } : { ok: true };
@@ -131,11 +130,4 @@ async function validateCycleRefs(targets, io) {
   return errors;
 }
 
-function checkIterationLimits(fm) {
-  const maxIt = fm['max-iterations'];
-  const dlIt = fm['deadlock-iterations'];
-  if (maxIt !== undefined && dlIt !== undefined && dlIt > maxIt) {
-    return `deadlock-iterations (${dlIt}) must be <= max-iterations (${maxIt}); deadlock would never trigger before the cycle blocks`;
-  }
-  return null;
-}
+

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

@@ -96,12 +96,6 @@ export function openFeedbackStore(path, io) {
         timestamp: nowIso, persist,
       });
     },
-    writeDeadlockedSnapshotForTest(params) {
-      return storeWriteDeadlockedSnapshot(params, items, { timestamp: nowIso, persist });
-    },
-    writeDeadlockedSnapshots(ids, reason, stage, cycle) {
-      return storeWriteDeadlockedSnapshots({ ids, reason, stage, cycle }, items, { timestamp: nowIso, persist });
-    },
     resolveSystemItems(stage, cycle) {
       resolveSystemItemsImpl({ items, stage, cycle, timestamp: nowIso, persist });
     },
@@ -153,7 +147,7 @@ function forgeWontFixError(item) {
 
 function reasonRequiredForTransition(target, current, reason) {
   const REASON_REQUIRED_TARGETS = new Set(['rejected', 'wont-fix']);
-  return (REASON_REQUIRED_TARGETS.has(target) || current === 'deadlocked')
+  return REASON_REQUIRED_TARGETS.has(target)
     && (!reason || !reason.trim());
 }
 
@@ -208,49 +202,4 @@ function storeTransition(params, items, deps) {
   return { ok: true };
 }
 
-function storeWriteDeadlockedSnapshot(params, items, deps) {
-  const { id, cycle, reason } = params;
-  const { timestamp, persist } = deps;
-
-  const item = items.find(x => x.id === id);
-  if (!item) return { ok: false, error: `feedback item not found: ${id}` };
-  if (!reason || !reason.trim()) {
-    return { ok: false, error: 'reason is required for deadlocked snapshot' };
-  }
-
-  const snapshot = { state: 'deadlocked', stage: 'sort', cycle, timestamp: timestamp(), reason };
-  persist(items.map(it =>
-    it.id === id ? { ...it, history: [snapshot, ...it.history] } : it
-  ));
-  return { ok: true };
-}
-
-function assertDeadlockedSnapshotArgs(ids, reason) {
-  if (!Array.isArray(ids)) return { ok: false, error: 'ids must be an array' };
-  if (ids.length === 0) return { ok: true };
-  if (!reason) return { ok: false, error: 'reason is required for deadlocked snapshot' };
-  return null;
-}
-
-function storeWriteDeadlockedSnapshots(params, items, deps) {
-  const { ids, reason, stage, cycle } = params;
-  const { timestamp, persist } = deps;
-
-  const precheck = assertDeadlockedSnapshotArgs(ids, reason);
-  if (precheck) return precheck;
 
-  const ts = timestamp();
-  const idSet = new Set(ids);
-  const nextItems = items.map(it => {
-    if (!idSet.has(it.id)) return it;
-    return { ...it, history: [{ state: 'deadlocked', stage, cycle, timestamp: ts, reason }, ...it.history] };
-  });
-  for (const id of ids) {
-    if (!items.some(it => it.id === id)) {
-      return { ok: false, error: `feedback item(s) not found: ${id}` };
-    }
-  }
-
-  persist(nextItems);
-  return { ok: true };
-}

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

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

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

@@ -6,9 +6,9 @@
  * configured `max-lines` limit and to lower per-function complexity.
  */
 
-// Spec §6.1: an item is "open" (still in flight) when its head state is
-// 'open', 'actioned', 'rejected', or 'wont-fix' — equivalently, when the
-// state is neither 'resolved' nor 'deadlocked'.
+// An item is "open" (still in flight) when its head state is not
+// 'resolved' or 'deadlocked'. The deadlocked check is retained for
+// backward compatibility with existing feedback files.
 const isOpenItem = (f) => f.state !== 'resolved' && f.state !== 'deadlocked';
 
 export { isOpenItem };
@@ -40,36 +40,90 @@ function hasItemsPendingApproval(openItems) {
   return openItems.some(f => f.state === 'actioned' || f.state === 'wont-fix');
 }
 
-function routeForgeIfNeeded(stages, forgeCount, maxIterations) {
-  if (forgeCount >= maxIterations) return 'blocked';
-  return findFirst(stages, 'forge') ?? 'blocked';
+function firstForgeOrBlocked(stages) {
+  const stage = findFirst(stages, 'forge');
+  return stage !== null ? stage : 'blocked';
 }
 
-function appraiseForgeOrApproval(stages, openItems, forgeCount, maxIterations) {
+function nextRouteOrDone(stages, current) {
+  const nextStage = nextInRoute(stages, current);
+  return nextStage !== null ? nextStage : 'done';
+}
+
+function firstHumanOrSuffixed(stages, cycle) {
+  const stage = findFirst(stages, 'human-appraise');
+  return stage !== null ? stage : `human-appraise:${cycle}`;
+}
+
+function isBelowIterationCap(forgeCount, maxIterations, alwaysHumanAppraise) {
+  return alwaysHumanAppraise || forgeCount < maxIterations;
+}
+
+function callHandlerOrBlocked(handler) {
+  return handler ? handler() : 'blocked';
+}
+
+function routeForgeIfNeeded(stages, forgeCount, maxIterations, opts = {}) {
+  const { alwaysHumanAppraise, deadlockHumanAppraise, cycle } = opts;
+  if (isBelowIterationCap(forgeCount, maxIterations, alwaysHumanAppraise)) {
+    return firstForgeOrBlocked(stages);
+  }
+  if (!deadlockHumanAppraise) return 'blocked';
+  if (!findFirst(stages, 'human-appraise')) return 'blocked';
+  return `human-appraise:${cycle}`;
+}
+
+function appraiseForgeOrApproval(stages, openItems, forgeCount, maxIterations, opts = {}) {
   if (hasItemsNeedingForge(openItems)) {
-    return routeForgeIfNeeded(stages, forgeCount, maxIterations);
+    return routeForgeIfNeeded(stages, forgeCount, maxIterations, opts);
   }
   if (hasItemsPendingApproval(openItems)) {
-    return findFirst(stages, 'appraise') ?? 'blocked';
+    const stage = findFirst(stages, 'appraise');
+    return stage !== null ? stage : 'blocked';
   }
   return null;
 }
 
-export function nextAfterAppraise({ stages, current, feedback, forgeCount, maxIterations }) {
-  // Note: deadlock detection is handled by runDeadlockPass at the top of
-  // runSort (spec §6.1). This helper assumes routing has already been allowed
-  // to fall through (i.e., no item qualifies as deadlocked).
-  const openItems = feedback.filter(isOpenItem);
-  const decided = appraiseForgeOrApproval(stages, openItems, forgeCount, maxIterations);
+function routeAlwaysHumanAppraise(stages, current, openItems, cycle) {
+  if (openItems.length > 0) {
+    return firstHumanOrSuffixed(stages, cycle);
+  }
+  return nextRouteOrDone(stages, current);
+}
+
+function decideAppraiseRoute(opts) {
+  const {
+    stages, current, openItems, forgeCount, maxIterations,
+    alwaysHumanAppraise, deadlockHumanAppraise, cycle,
+  } = opts;
+  const decided = appraiseForgeOrApproval(
+    stages, openItems, forgeCount, maxIterations,
+    { alwaysHumanAppraise, deadlockHumanAppraise, cycle },
+  );
   if (decided !== null) return decided;
-  return nextInRoute(stages, current) ?? 'done';
+  return nextRouteOrDone(stages, current);
 }
 
-export function nextAfterQuench(stages, current, feedback, forgeCount, maxIterations) {
+export function nextAfterAppraise({
+  stages, current, feedback, forgeCount, maxIterations,
+  alwaysHumanAppraise = false, deadlockHumanAppraise = false, cycle = 'default',
+}) {
   const openItems = feedback.filter(isOpenItem);
-  const needsForge = openItems.some(f => f.state === 'open' || f.state === 'rejected');
-  if (needsForge) return routeForgeIfNeeded(stages, forgeCount, maxIterations);
-  return nextInRoute(stages, current) ?? 'done';
+  if (alwaysHumanAppraise) {
+    return routeAlwaysHumanAppraise(stages, current, openItems, cycle);
+  }
+  return decideAppraiseRoute({
+    stages, current, openItems, forgeCount, maxIterations,
+    alwaysHumanAppraise, deadlockHumanAppraise, cycle,
+  });
+}
+
+export function nextAfterQuench(stages, current, feedback, opts = {}) {
+  const { forgeCount = 0, maxIterations = 100 } = opts;
+  const openItems = feedback.filter(isOpenItem);
+  const needsForge = hasItemsNeedingForge(openItems);
+  if (needsForge) return routeForgeIfNeeded(stages, forgeCount, maxIterations, opts);
+  return nextRouteOrDone(stages, current);
 }
 
 function lastNonSortStage(history) {
@@ -78,26 +132,50 @@ function lastNonSortStage(history) {
   return nonSort[nonSort.length - 1].stage;
 }
 
-function buildRouteHandlers({ stages, lastEntry, feedback, forgeCount, maxIterations }) {
+function buildRouteHandlers({
+  stages, lastEntry, feedback, forgeCount, maxIterations,
+  alwaysHumanAppraise, deadlockHumanAppraise, cycle,
+}) {
   const appraiseRoute = () => nextAfterAppraise({
     stages, current: lastEntry, feedback, forgeCount, maxIterations,
+    alwaysHumanAppraise, deadlockHumanAppraise, cycle,
   });
   return {
-    'assay': () => findFirst(stages, 'forge') ?? 'blocked',
-    'forge': () => nextInRoute(stages, lastEntry) ?? 'done',
-    'quench': () => nextAfterQuench(stages, lastEntry, feedback, forgeCount, maxIterations),
+    'assay': () => firstForgeOrBlocked(stages),
+    'forge': () => nextRouteOrDone(stages, lastEntry),
+    'quench': () => nextAfterQuench(
+      stages, lastEntry, feedback,
+      { forgeCount, maxIterations, alwaysHumanAppraise, deadlockHumanAppraise, cycle },
+    ),
     'appraise': appraiseRoute,
     'human-appraise': appraiseRoute,
   };
 }
 
-export function determineRoute(stages, history, feedback, maxIterations) {
-  const forgeCount = history.filter(e => baseStage(e.stage || '') === 'forge').length;
-  const lastEntry = lastNonSortStage(history);
+function countForgeIterations(history) {
+  return history.filter(e => baseStage(e.stage || '') === 'forge').length;
+}
+
+function routeFromLastEntry(opts) {
+  const {
+    stages, lastEntry, feedback, forgeCount, maxIterations,
+    alwaysHumanAppraise, deadlockHumanAppraise, cycle,
+  } = opts;
   if (lastEntry === null) return stages[0];
   const handlers = buildRouteHandlers({
     stages, lastEntry, feedback, forgeCount, maxIterations,
+    alwaysHumanAppraise, deadlockHumanAppraise, cycle,
   });
   const handler = handlers[baseStage(lastEntry)];
-  return handler ? handler() : 'blocked';
+  return callHandlerOrBlocked(handler);
+}
+
+export function determineRoute(stages, history, feedback, maxIterations, opts = {}) {
+  const { alwaysHumanAppraise = false, deadlockHumanAppraise = false, cycle = 'default' } = opts;
+  const forgeCount = countForgeIterations(history);
+  const lastEntry = lastNonSortStage(history);
+  return routeFromLastEntry({
+    stages, lastEntry, feedback, forgeCount, maxIterations,
+    alwaysHumanAppraise, deadlockHumanAppraise, cycle,
+  });
 }

package/dist/scripts/orchestrate-cycle.js

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

package/dist/scripts/orchestrate-phases.js

@@ -21,7 +21,6 @@ import {
   tryCommit,
   synthesizeStages,
   renderDispatchPrompt,
-  checkIterationLimits,
 } from './orchestrate-cycle.js';
 import {
   doneAction,
@@ -157,7 +156,7 @@ function stageTag(s, cycleId) {
 
 function resolveStages(cfm, cycleId, hasValidation, assayExtractors) {
   if (!Array.isArray(cfm.stages)) {
-    return synthesizeStages({ cycleId, hasValidation, humanAppraise: cfm['human-appraise'] === true, assay: !!assayExtractors });
+    return synthesizeStages({ cycleId, hasValidation, alwaysHumanAppraise: cfm['always-human-appraise'] === true, assay: !!assayExtractors });
   }
   if (cfm.stages.length === 0) {
     return { error: violation(`cycle ${cycleId} has no stages declared in cycle definition`, ['WORK.md']) };
@@ -168,9 +167,8 @@ function resolveStages(cfm, cycleId, hasValidation, assayExtractors) {
 function applyFmDefaults(newFm, cfm, assayExtractors) {
   const maxIt = cfm['max-iterations'] ?? 3;
   newFm['max-iterations'] = maxIt;
-  newFm['human-appraise'] = cfm['human-appraise'] === true;
-  newFm['deadlock-appraise'] = cfm['deadlock-appraise'] !== false;
-  newFm['deadlock-iterations'] = cfm['deadlock-iterations'] ?? maxIt;
+  newFm['always-human-appraise'] = cfm['always-human-appraise'] === true;
+  newFm['deadlock-human-appraise'] = cfm['deadlock-human-appraise'] !== false;
   if (cfm.models) newFm.models = cfm.models;
   if (assayExtractors) newFm.assay = { extractors: assayExtractors };
 }
@@ -226,8 +224,6 @@ async function completeSetup(ctx) {
   const hasValidation = ctx.lawsWithValidators && ctx.lawsWithValidators.length > 0;
   const stagesResult = resolveStages(ctx.cfm, ctx.cycleId, hasValidation, ctx.assayResult.extractors);
   if (stagesResult.error) return stagesResult.error;
-  const validityErr = checkIterationLimits(ctx.cfm, ctx.cycleId);
-  if (validityErr) return validityErr;
   const newWork = buildNewFrontmatter(ctx.workContent, stagesResult, ctx.cfm, ctx.assayResult.extractors);
   ctx.io.writeFile('WORK.md', newWork);
   return trySetupCommit(ctx);