@really-knows-ai/foundry 3.5.5 → 3.5.7

package/dist/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [3.5.7] - 2026-05-23
+
+### Added
+
+- Artefact types can include an `example.md` alongside `definition.md`. When present, the forge skill treats its structure as normative — the forge agent follows the same format, preventing common formatting mistakes like unwanted title headings on haikus.
+
+## [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

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.js

@@ -22,12 +22,20 @@ export async function getCycleDefinition(foundryDir, cycleId, io) {
 }
 
 export async function getArtefactType(foundryDir, typeId, io) {
-  const path = join(foundryDir, 'artefacts', typeId, 'definition.md');
-  if (!(await io.exists(path))) {
+  const dir = join(foundryDir, 'artefacts', typeId);
+  const defPath = join(dir, 'definition.md');
+  if (!(await io.exists(defPath))) {
     throw new Error(`Artefact type not found: ${typeId}`);
   }
-  const text = await io.readFile(path);
-  return parseDoc(text);
+  const text = await io.readFile(defPath);
+  const result = parseDoc(text);
+
+  const examplePath = join(dir, 'example.md');
+  if (await io.exists(examplePath)) {
+    result.example = (await io.readFile(examplePath)).trim();
+  }
+
+  return result;
 }
 
 /**

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/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

@@ -21,6 +21,7 @@ import {
   tryCommit,
   synthesizeStages,
   renderDispatchPrompt,
+  checkIterationLimits,
 } from './orchestrate-cycle.js';
 import {
   doneAction,
@@ -71,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);
@@ -159,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 };
 }
@@ -218,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

@@ -193,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/dist/skills/forge/SKILL.md

@@ -40,7 +40,7 @@ Forge runs inside an enforced stage. Your **first** and **last** tool calls are
 
    Then return control to the user and stop.
 3. `foundry_config_cycle` — understand what to produce and what inputs are available.
-4. `foundry_config_artefact_type` with the output type ID — get the artefact type definition, especially its `file-patterns`.
+4. `foundry_config_artefact_type` with the output type ID — get the artefact type definition, `file-patterns`, and any example. When the response includes an `example` field, its structure is normative — your output must follow the same format (no extra headings, metadata blocks, or free-form prose that the example does not include).
 5. `foundry_config_laws` — get all applicable laws (global + type-specific).
 6. If the cycle declares `inputs`, discover input files by filesystem scan:
    - For each type listed in `inputs`, call `foundry_config_artefact_type` to get its `file-patterns`.

package/package.json

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