@really-knows-ai/foundry 3.5.4 → 3.5.6

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

@@ -3,6 +3,7 @@
 import path from 'path';
 import { readFileSync, writeFileSync, existsSync, readdirSync, unlinkSync, mkdirSync, renameSync, rmSync, statSync } from 'fs';
 import { execFileSync } from 'child_process';
+import matter from 'gray-matter';
 import { getCycleDefinition } from '../../../scripts/lib/config.js';
 import { getOrOpenStore, getContext } from '../../../scripts/lib/memory/singleton.js';
 import { resolvePermissions } from '../../../scripts/lib/memory/permissions.js';
@@ -13,49 +14,27 @@ import { requireOnFlowBranch } from '../../../scripts/lib/branch-guard.js';
 // Track flow files we've already warned about to avoid spamming stderr
 const warnedFlowFiles = new Set();
 
-// -- Frontmatter parsing helpers --
-
-function isFieldSeparator(char) {
-  return char === ' ' || char === '\t';
-}
-
-function parseFrontmatterField(fm, fieldName) {
-  const prefix = `${fieldName}:`;
-  for (const line of fm.split('\n')) {
-    if (!line.startsWith(prefix)) continue;
-    const rest = line.slice(prefix.length);
-    if (rest === '' || isFieldSeparator(rest[0])) {
-      return rest.trim();
-    }
-  }
-  return null;
+function parseFlowFrontmatter(text, entry) {
+  const fm = extractFrontmatter(text);
+  if (!fm) return null;
+  const id = fm.id || entry.replace(/\.md$/, '');
+  return {
+    id,
+    name: fm.name || id,
+    startingCycles: resolveStartingCycles(fm),
+  };
 }
 
-function parseStartingCycles(fm) {
-  const lines = fm.split('\n');
-  const scIndex = lines.findIndex(line => line.trimEnd() === 'starting-cycles:');
-  if (scIndex < 0) return [];
-  const items = [];
-  for (let i = scIndex + 1; i < lines.length; i++) {
-    const trimmed = lines[i].trimStart();
-    if (trimmed.startsWith('-')) {
-      const content = trimmed.slice(1).trimStart();
-      if (content) items.push(content);
-    } else {
-      break;
-    }
-  }
-  return items;
+function extractFrontmatter(text) {
+  const parsed = matter(text);
+  return parsed.data && typeof parsed.data === 'object' && Object.keys(parsed.data).length > 0
+    ? parsed.data
+    : null;
 }
 
-function parseFlowFrontmatter(text, entry) {
-  const fmMatch = text.match(/^---\n([\s\S]*?)\n---/);
-  if (!fmMatch) return null;
-  const fm = fmMatch[1];
-  const id = parseFrontmatterField(fm, 'id') || entry.replace(/\.md$/, '');
-  const name = parseFrontmatterField(fm, 'name') || id;
-  const startingCycles = parseStartingCycles(fm);
-  return { id, name, startingCycles };
+function resolveStartingCycles(fm) {
+  const sc = fm['starting-cycles'];
+  return Array.isArray(sc) ? sc : [];
 }
 
 function parseFlowFile(entry, flowsDir) {

package/dist/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [3.5.6] - 2026-05-23
+
+### Fixed
+
+- `deadlock-iterations` default changed from hardcoded 5 to the resolved `max-iterations` value, and defaults are clamped so deadlock is never unreachable. Deadlock validation rejects cycles where `deadlock-iterations > max-iterations` at setup time and cycle creation time.
+
+### Added
+
+- Orchestrator routing responses now include a `reason` field explaining why sort chose the returned action (e.g. "found 1 unresolved feedback item(s) — routing to forge for revision (iteration 2 of 3)").
+
+## [3.5.5] - 2026-05-23
+
+### Fixed
+
+- `buildAppraiserPrompt` output format aligned with the YAML parser — indented continuation fields instead of dash-prefixed. Previously, an appraiser reporting an issue with the exact prompt format would have every field split into separate entries and silently discarded.
+- Hand-rolled appraiser output parsing (120 lines) replaced with `js-yaml` plus a line-scanning fallback for non-clean LLM output.
+
+### Changed
+
+- All hand-rolled YAML frontmatter regex extraction (5 patterns across 10 sites in 8 files) replaced with `gray-matter`.
+- Flow frontmatter parsing in `helpers.js` switched from line-scanning to `gray-matter`.
+
 ## [3.5.4] - 2026-05-23
 
 ### Fixed

package/dist/scripts/appraise-module.js

@@ -13,6 +13,7 @@
 
 import { getArtefactFiles } from './lib/artefacts.js';
 import { selectAppraisers, getLaws, getCycleDefinition } from './lib/config.js';
+import yaml from 'js-yaml';
 
 // ---------------------------------------------------------------------------
 // Public API — gather
@@ -296,9 +297,9 @@ function buildAppraiserPrompt({ appraiser, artefact, laws }) {
     '',
     'Return a list of issues. For each issue:',
     `- file: ${artefact.file}`,
-    '- law: <law-id>',
-    '- issue: <description>',
-    '- evidence: <quote from artefact>',
+    '  law: <law-id>',
+    '  issue: <description>',
+    '  evidence: <quote from artefact>',
     '',
     'If there are no issues, return an empty list.',
   ];
@@ -313,127 +314,87 @@ function buildAppraiserPrompt({ appraiser, artefact, laws }) {
 /**
  * Parse a structured issue list from an appraiser subagent output.
  *
- * Expected per-issue format (YAML list):
- *   - file: <path>
- *     law: <law-id>
- *     issue: <description>
- *     evidence: <quote>
+ * LLM output is free-form text that may contain a YAML list of issues.
+ * Tries js-yaml first; falls back to line-scanning when the output is
+ * not clean YAML (LLMs may include surrounding text, quotes in bare
+ * strings, or other quirks that trip up a strict YAML parser).
  *
- * Returns an array of { file, law, issue, evidence } objects. Entries that
- * lack a file, law, or issue field are silently skipped.
+ * Returns an array of { file, law, issue, evidence } objects.
  */
 function parseAppraiserOutput(output) {
-  // Split output into entries on boundaries where a new line starts a
-  // list entry ("- ").  Avoids regex to prevent sonarjs/slow-regex.
-  const entries = [];
-  let buffer = '';
-
-  for (const line of output.split('\n')) {
-    if (buffer && isListEntryStart(line)) {
-      entries.push(buffer);
-      buffer = line;
-      continue;
-    }
-
-    buffer = concatLine(buffer, line);
-  }
-
-  if (buffer) entries.push(buffer);
+  const text = output || '';
+  const yamlBlock = extractYamlBlock(text);
+  const issues = tryYamlParse(yamlBlock);
+  if (issues) return issues;
 
-  return entries
-    .map(parseRawEntry)
-    .filter(e => e !== null);
+  return parseFallback(text);
 }
 
-/**
- * Append a line to the current buffer string.
- */
-function concatLine(buffer, line) {
-  if (!buffer) return line;
-  return `${buffer}\n${line}`;
+function extractYamlBlock(text) {
+  if (text.startsWith('- file:')) return text;
+  const afterNewline = text.indexOf('\n- file:');
+  if (afterNewline >= 0) return text.slice(afterNewline + 1);
+  return text;
 }
 
-/**
- * True when a line marks the start of a new YAML list entry (starts with
- * "- " after optional whitespace).
- */
-function isListEntryStart(line) {
-  for (let i = 0; i < line.length; i++) {
-    const ch = line[i];
-    if (ch === ' ' || ch === '\t') continue;
-    return ch === '-' && line[i + 1] === ' ';
-  }
-  return false;
+function tryYamlParse(yamlBlock) {
+  try {
+    const parsed = yaml.load(yamlBlock);
+    if (Array.isArray(parsed)) {
+      return parsed
+        .filter(e => e && typeof e === 'object' && e.file && e.law && e.issue)
+        .map(e => ({ file: e.file, law: e.law, issue: e.issue, evidence: e.evidence || '' }));
+    }
+  } catch { /* fall through to fallback */ }
+  return null;
 }
 
-/**
- * Parse a single raw entry block into an issue object, or null when
- * required fields are missing.
- */
-function parseRawEntry(raw) {
-  const block = raw.trim();
-
-  const file = extractField(block, 'file');
-  const law = extractField(block, 'law');
-  const issue = extractField(block, 'issue');
-  const evidence = extractField(block, 'evidence');
+const FALLBACK_FIELDS = new Set(['law', 'issue', 'evidence']);
 
-  if (!file || !law || !issue) return null;
+function isCompleteIssue(obj) {
+  return obj && obj.file && obj.law && obj.issue;
+}
 
-  return { file, law, issue, evidence: evidence || '' };
+function applyFallbackField(kv, entry, issues) {
+  if (kv.key === 'file') {
+    const e = { file: kv.value, law: '', issue: '', evidence: '' };
+    issues.push(e);
+    return e;
+  }
+  if (entry && FALLBACK_FIELDS.has(kv.key)) {
+    entry[kv.key] = kv.value;
+  }
+  return entry;
 }
 
-/**
- * Extract a YAML list item field value.
- *
- * Matches lines like:
- *   - file: value
- *     law: value
- *
- * The field name may be preceded by optional whitespace and/or a "- " list
- * marker. Returns the value portion, trimmed.
- */
-function extractField(text, key) {
-  // Walk lines to find "key: value" preceded only by whitespace or a "- "
-  // list marker.  Avoids regex quantifiers that trigger sonarjs/slow-regex.
+function parseFallback(text) {
+  const issues = [];
+  let entry = null;
 
   for (const line of text.split('\n')) {
-    const trimmed = line.trim();
-    const value = tryExtractKey(trimmed, key);
-    if (value !== null) return value;
+    const kv = parseFallbackLine(line);
+    if (kv) entry = applyFallbackField(kv, entry, issues);
   }
 
-  return null;
+  return issues.filter(isCompleteIssue);
 }
 
-/**
- * Given a single trimmed line, try to extract the value for key.
- * Returns null if the pattern is not found.
- */
-function tryExtractKey(line, key) {
-  const needle = `${key}:`;
-  const idx = line.indexOf(needle);
-  if (idx < 0) return null;
+function parseFallbackLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return null;
 
-  const before = line.slice(0, idx);
-  if (before.length > 0 && !isLegalPrefix(before)) return null;
+  const colon = trimmed.indexOf(':');
+  if (colon < 1) return null;
 
-  const value = line.slice(idx + needle.length).trim();
-  return value || null;
+  const key = stripDash(trimmed.slice(0, colon));
+  return {
+    key: key.trim(),
+    value: trimmed.slice(colon + 1).trim(),
+  };
 }
 
-/**
- * True when the text before a key: on a line is either all whitespace or
- * the "- " list marker.
- */
-function isLegalPrefix(before) {
-  if (before === '- ') return true;
-
-  for (let i = 0; i < before.length; i++) {
-    if (before[i] !== ' ' && before[i] !== '\t') return false;
-  }
-
-  return true;
+function stripDash(s) {
+  return s.startsWith('- ') ? s.slice(2) : s;
 }
 
 // ---------------------------------------------------------------------------

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

@@ -29,6 +29,7 @@ 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 };
@@ -129,3 +130,12 @@ 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/config-validators/helpers.js

@@ -1,4 +1,5 @@
 import { parseFrontmatter } from '../workfile.js';
+import matter from 'gray-matter';
 
 /**
  * Shared helpers for config validators.
@@ -10,7 +11,8 @@ import { parseFrontmatter } from '../workfile.js';
  * @returns {{ok: true, fm: object} | {ok: false, errors: string[]}}
  */
 export function tryParseFrontmatter(body) {
-  if (!/^---\n[\s\S]*?\n---/.test(body)) {
+  const { data } = matter(body);
+  if (!data || typeof data !== 'object' || Object.keys(data).length === 0) {
     return { ok: false, errors: ['frontmatter is missing or unparseable'] };
   }
   try {
@@ -65,7 +67,7 @@ export function validateNameMatch(fm, name) {
  * @returns {string}
  */
 export function bodyAfterFrontmatter(body) {
-  return body.replace(/^---\n[\s\S]*?\n---\n?/, '').trim();
+  return matter(body).content.trim();
 }
 
 /**

package/dist/scripts/lib/config.js

@@ -4,10 +4,11 @@
 
 import { join } from 'path';
 import { parseFrontmatter } from './workfile.js';
+import matter from 'gray-matter';
 
 function parseDoc(text) {
   const frontmatter = parseFrontmatter(text);
-  const body = text.replace(/^---\n.+?\n---\n?/s, '').trim();
+  const body = matter(text).content.trim();
   return { frontmatter, body };
 }
 

package/dist/scripts/lib/failed-flow.js

@@ -28,6 +28,7 @@
  * is clean.
  */
 import { parseFrontmatter, setFrontmatterField, writeFrontmatter } from './workfile.js';
+import matter from 'gray-matter';
 
 const MAX_REASON_LEN = 500;
 
@@ -126,6 +127,6 @@ export function clearWorkfileFailed(io) {
   
   // Rebuild the file with cleaned frontmatter
   const fmBlock = writeFrontmatter(fm);
-  const body = text.replace(/^---\n.+?\n---\n?/s, '');
+  const body = matter(text).content;
   io.writeFile('WORK.md', body ? `${fmBlock}\n${body}` : fmBlock);
 }

package/dist/scripts/lib/memory/admin/rename-entity-type.js

@@ -5,10 +5,10 @@ import { parseEdgeRows, serialiseEdgeRows, parseEntityRows, serialiseEntityRows
 import { invalidateStore } from '../singleton.js';
 import { parseFrontmatter } from '../frontmatter.js';
 import { renderEdgeFrontmatter, composeMarkdown } from './helpers.js';
+import matter from 'gray-matter';
+import yaml from 'js-yaml';
 
 const IDENT = /^[a-z][a-z0-9_]*$/;
-const TYPE_LINE = /^type:\s*\S.*$/m;
-const FRONTMATTER_BLOCK = /^---\r?\n([\s\S]*?)\r?\n---/;
 
 function assertValidIdentifier(id) {
   if (!IDENT.test(id)) throw new Error(`invalid identifier: '${id}'`);
@@ -37,10 +37,10 @@ function validateRename(schema, from, to) {
 async function rewriteEntityTypeFile(from, to, p, io) {
   const oldFile = p.entityTypeFile(from);
   const text = await io.readFile(oldFile);
-  const newText = text.replace(FRONTMATTER_BLOCK, (_, fm) => {
-    const replaced = fm.replace(TYPE_LINE, `type: ${to}`);
-    return `---\n${replaced}\n---`;
-  });
+  const { data, content } = matter(text);
+  const fm = { ...data, type: to };
+  const fmBlock = `---\n${yaml.dump(fm, { lineWidth: -1, sortKeys: false }).trim()}\n---`;
+  const newText = content ? `${fmBlock}\n${content}` : fmBlock;
   await io.writeFile(p.entityTypeFile(to), newText);
   await io.unlink(oldFile);
 }

package/dist/scripts/lib/memory/frontmatter.js

@@ -1,31 +1,9 @@
+import matter from 'gray-matter';
 import yaml from 'js-yaml';
 
-/**
- * Safely parse a YAML string, rethrowing with a filename-prefixed message
- * on failure so errors are actionable.
- *
- * @param {string} yamlStr
- * @param {string} filename
- * @returns {unknown}
- */
-function safeYamlLoad(yamlStr, filename) {
-  try {
-    return yaml.load(yamlStr);
-  } catch (err) {
-    const msg = err?.message ?? String(err);
-    throw new Error(`${filename}: malformed YAML frontmatter: ${msg}`, { cause: err });
-  }
-}
-
-/**
- * Normalise a parsed YAML value into a frontmatter object.
- *
- * @param {unknown} parsed
- * @returns {object}
- */
 function normaliseFrontmatter(parsed) {
   if (parsed && typeof parsed === 'object') {
-    return /** @type {object} */ (parsed);
+    return { ...parsed };
   }
   return {};
 }
@@ -49,19 +27,39 @@ function normaliseFrontmatter(parsed) {
  * @param {{ filename?: string }} [opts]
  * @returns {{ frontmatter: object, body: string, hasFrontmatter: boolean }}
  */
-export function parseFrontmatter(text, { filename = '<unknown>' } = {}) {
-  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
-  if (!m) {
+function hasData(d) {
+  return d && (typeof d === 'object' ? Object.keys(d).length > 0 : true);
+}
+
+export function parseFrontmatter(text, { filename } = {}) {
+  const result = tryMatter(text, filename);
+  if (!result) {
+    return { frontmatter: {}, body: text, hasFrontmatter: false };
+  }
+
+  if (!hasData(result.data)) {
     return { frontmatter: {}, body: text, hasFrontmatter: false };
   }
-  const parsed = safeYamlLoad(m[1], filename);
+
   return {
-    frontmatter: normaliseFrontmatter(parsed),
-    body: m[2] ?? '',
+    frontmatter: normaliseFrontmatter(result.data),
+    body: result.content,
     hasFrontmatter: true,
   };
 }
 
+function tryMatter(text, filename) {
+  try {
+    return matter(text);
+  } catch (err) {
+    if (filename) {
+      const msg = err?.message ?? String(err);
+      console.warn(`${filename}: malformed YAML frontmatter: ${msg}`);
+    }
+    return null;
+  }
+}
+
 /**
  * Render a markdown document from a frontmatter object and a body string.
  * Uses `yaml.dump` — callers that need a specific key order (e.g. edge type

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

@@ -0,0 +1,55 @@
+import { baseStage } from './sort-routing.js';
+
+const REASON_HANDLERS = {
+  forge: forgeReason,
+  assay: (d) => `starting cycle — routing to assay`,
+  quench: () => 'routing to quench for deterministic validation',
+  appraise: appraiseReason,
+  'human-appraise': humanAppraiseReason,
+  done: () => 'all stages complete — no unresolved feedback',
+  blocked: blockedReason,
+};
+
+export function reasonForRoute(route, prep) {
+  const data = buildReasonData(route, prep);
+  const handler = REASON_HANDLERS[data.base] || defaultReason;
+  return handler(data);
+}
+
+function buildReasonData(route, prep) {
+  const base = baseStage(route);
+  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 needingForge = feedback.filter(
+    f => f.state === 'open' || f.state === 'rejected',
+  ).length;
+
+  return { base, route, forgeCount, maxIt, openCount, dlCount, needingForge, anyDeadlocked: prep.anyDeadlocked };
+}
+
+function forgeReason(d) {
+  if (d.forgeCount === 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})`;
+}
+
+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`;
+}
+
+function blockedReason(d) {
+  return `max iterations (${d.maxIt}) reached after ${d.forgeCount} forge iteration(s) with ${d.openCount} unresolved feedback item(s)`;
+}
+
+function defaultReason(d) {
+  return `routing to ${d.route}`;
+}

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

@@ -11,6 +11,8 @@
 // state is neither 'resolved' nor 'deadlocked'.
 const isOpenItem = (f) => f.state !== 'resolved' && f.state !== 'deadlocked';
 
+export { isOpenItem };
+
 export function baseStage(stage) {
   return stage.split(':')[0];
 }

package/dist/scripts/lib/workfile.js

@@ -3,23 +3,15 @@
  */
 
 import yaml from 'js-yaml';
+import matter from 'gray-matter';
 
 // ---------------------------------------------------------------------------
 // Frontmatter parsing
 // ---------------------------------------------------------------------------
 
-/**
- * Parse YAML frontmatter from a markdown document.
- * NOTE: Intentionally duplicates logic from memory/frontmatter.js for
- * different use cases. See memory/frontmatter.js for the canonical version
- * with full error handling and line-ending normalisation.
- */
 export function parseFrontmatter(text) {
-  const match = text.match(/^---\r?\n(.+?)\r?\n---/s);
-  if (!match) return {};
-  const fm = yaml.load(match[1]) || {};
-  // Normalize: on-disk canonical key is `max-iterations` (kebab).
-  // Tolerate legacy `maxIterations` (camel) by rewriting on read.
+  const { data } = matter(text);
+  const fm = { ...data };
   if (fm.maxIterations !== undefined) {
     if (fm['max-iterations'] === undefined) {
       fm['max-iterations'] = fm.maxIterations;
@@ -53,7 +45,7 @@ export function setFrontmatterField(text, key, value) {
   const fmBlock = writeFrontmatter(fm);
 
   // Strip existing frontmatter (if any) and prepend new one
-  const body = text.replace(/^---\r?\n.+?\r?\n---\r?\n?/s, '');
+  const body = matter(text).content;
   return body ? `${fmBlock}\n${body}` : fmBlock;
 }
 

package/dist/scripts/orchestrate-cycle.js

@@ -272,3 +272,15 @@ 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

@@ -7,6 +7,7 @@ import {
   getLawsForQuench,
 } from './lib/config.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';
@@ -20,6 +21,7 @@ import {
   tryCommit,
   synthesizeStages,
   renderDispatchPrompt,
+  checkIterationLimits,
 } from './orchestrate-cycle.js';
 import {
   doneAction,
@@ -70,9 +72,15 @@ function getRouteBase(route) {
 }
 
 export async function handleSortResult(sortResult, ctx) {
-  const { route, model, token } = sortResult;
+  const { route, model, token, reason } = sortResult;
   const routeBase = getRouteBase(route);
-  if (isTerminalRoute(route)) return handleTerminalRoute(route, sortResult, ctx);
+  const result = await resolveRouteResult({ route, routeBase, model, token, ctx });
+  if (reason !== undefined) result.reason = reason;
+  return result;
+}
+
+async function resolveRouteResult({ route, routeBase, model, token, ctx }) {
+  if (isTerminalRoute(route)) return handleTerminalRoute(route, { route }, ctx);
   if (routeBase === 'quench' || routeBase === 'appraise') return violation(routeBase + ' route reached handleSortResult');
   if (routeBase === 'human-appraise') return humanAppraiseAction(route, token, ctx);
   return buildDispatchAction(route, model, token, ctx);
@@ -158,10 +166,11 @@ function resolveStages(cfm, cycleId, hasValidation, assayExtractors) {
 }
 
 function applyFmDefaults(newFm, cfm, assayExtractors) {
-  newFm['max-iterations'] = cfm['max-iterations'] ?? 3;
+  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'] ?? 5;
+  newFm['deadlock-iterations'] = cfm['deadlock-iterations'] ?? maxIt;
   if (cfm.models) newFm.models = cfm.models;
   if (assayExtractors) newFm.assay = { extractors: assayExtractors };
 }
@@ -171,7 +180,7 @@ function buildNewFrontmatter(workContent, stages, cfm, assayExtractors) {
   const newFm = { ...fm };
   newFm.stages = stages;
   applyFmDefaults(newFm, cfm, assayExtractors);
-  const body = workContent.replace(/^---\n[\s\S]+?\n---\n?/, '');
+  const body = matter(workContent).content;
   const fmBlock = writeFrontmatter(newFm);
   return body ? `${fmBlock}\n${body}` : fmBlock;
 }
@@ -217,6 +226,8 @@ 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);

package/dist/scripts/orchestrate.js

@@ -4,6 +4,7 @@
 
 import { runSort } from './sort.js';
 import { parseFrontmatter } from './lib/workfile.js';
+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';
@@ -38,10 +39,8 @@ export { readCycleTargets, readForgeFilePatterns };
 export { handleSortResult as __handleSortResultForTest };
 
 export function needsSetup(workMdContent) {
-  const match = workMdContent.match(/^---\n([\s\S]*?)\n---/);
-  if (!match) return true;
-  const fm = match[1];
-  return !/^stages:/m.test(fm);
+  const { data } = matter(workMdContent);
+  return !data || !data.stages;
 }
 
 // ---------------------------------------------------------------------------
@@ -194,19 +193,23 @@ async function handleQuenchRoute(sortResult, preCheck, args, io) {
   return dispatchByRoute(nextSort, args, preCheck, io);
 }
 
-async function handleAppraiseGatherRoute(sortResult, preCheck, args, io) {
-  writeStageRecord(io, preCheck.cycleId, sortResult.route);
-  const result = await gatherAppraiseContext(buildAppraiseCtx(preCheck.cycleId, args, io));
-  if (result.action === 'violation') { clearActiveStage(io); return result; }
+async function dispatchAppraiseOrConsolidate(sortResult, preCheck, args, io, result) {
   if (!result.tasks || result.tasks.length === 0) {
-    // No appraisers/artefacts — consolidate with empty results to advance
     return handleAppraiseConsolidateRoute(sortResult, preCheck, { ...args, lastResults: [] }, io);
   }
   const validationErr = validateDispatchMulti(result);
   if (validationErr) return validationErr;
+  if (sortResult.reason !== undefined) result.reason = sortResult.reason;
   return result;
 }
 
+async function handleAppraiseGatherRoute(sortResult, preCheck, args, io) {
+  writeStageRecord(io, preCheck.cycleId, sortResult.route);
+  const result = await gatherAppraiseContext(buildAppraiseCtx(preCheck.cycleId, args, io));
+  if (result.action === 'violation') { clearActiveStage(io); return result; }
+  return dispatchAppraiseOrConsolidate(sortResult, preCheck, args, io, result);
+}
+
 async function handleAppraiseConsolidateRoute(sortResult, preCheck, args, io) {
   const ctx = buildAppraiseCtx(preCheck.cycleId, args, io);
   const result = await consolidateAppraise(ctx, args.lastResults);

package/dist/scripts/sort.js

@@ -22,6 +22,7 @@ import {
   findFirst,
   determineRoute,
 } from './lib/sort-routing.js';
+import { reasonForRoute } from './lib/sort-reason.js';
 import {
   defaultIO,
   checkModifiedFiles,
@@ -85,11 +86,12 @@ function validateWorkMd(workPath, io) {
 }
 
 function extractFrontmatterDefaults(frontmatter) {
+  const maxIt = frontmatter['max-iterations'] ?? 3;
   return {
-    maxIterations: frontmatter['max-iterations'] ?? 3,
+    maxIterations: maxIt,
     humanAppraiseEnabled: frontmatter['human-appraise'] === true,
     deadlockAppraise: frontmatter['deadlock-appraise'] !== false,
-    deadlockIterations: frontmatter['deadlock-iterations'] ?? 5,
+    deadlockIterations: frontmatter['deadlock-iterations'] ?? maxIt,
   };
 }
 
@@ -184,8 +186,8 @@ function checkModel(route, frontmatter, agentsDir, io, defaultModel) {
   return { model: typeof modelResult === 'string' ? modelResult : null };
 }
 
-function mintToken({ route, model, mint, cycle, now, ulid }) {
-  const result = { route, ...(model ? { model } : {}) };
+function mintToken({ route, model, mint, cycle, now, ulid, reason }) {
+  const result = { route, ...(model ? { model } : {}), reason };
   if (mint && isDispatchableRoute(route)) {
     const token = mint({ route, cycle, exp: now + 10 * 60 * 1000, nonce: ulid(now) });
     if (token) result.token = token;
@@ -268,6 +270,7 @@ export function runSort(args = {}, io = defaultIO) {
 
   return mintToken({
     route, model: modelCheck.model, mint: opts.mint, cycle: prep.cycle, now: opts.now, ulid: opts.ulid,
+    reason: reasonForRoute(route, prep),
   });
 }
 

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

@@ -85,7 +85,7 @@ 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, default 5) — deadlock threshold. Only applies when either appraise is enabled.
+- **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.
 - **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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@really-knows-ai/foundry",
-  "version": "3.5.4",
+  "version": "3.5.6",
   "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",
@@ -26,6 +26,7 @@
   },
   "dependencies": {
     "@opencode-ai/plugin": "^1.4.0",
+    "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
     "minimatch": "^10.2.5"
   },