@really-knows-ai/foundry 3.5.2 → 3.5.3

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

@@ -1,13 +1,16 @@
 import { getCycleDefinition, getArtefactType, getLaws, getAppraisers, getFlow } from '../../../scripts/lib/config.js';
 import { makeIO } from './helpers.js';
+import { writeCall } from '../../../scripts/lib/stage-calls.js';
 
-function makeConfigTool(tool, description, argSchema, invoke) {
+function makeConfigTool(tool, description, argSchema, invoke, logName) {
   return tool({
     description,
     args: argSchema,
     async execute(args, context) {
       const io = makeIO(context.worktree);
-      return JSON.stringify(await invoke(args, io));
+      const result = await invoke(args, io);
+      if (logName) writeCall(io, logName);
+      return JSON.stringify(result);
     },
   });
 }
@@ -18,16 +21,19 @@ export function createConfigTools({ tool }) {
       tool, 'Get a cycle definition from foundry config',
       { cycleId: tool.schema.string().describe('Cycle ID') },
       (args, io) => getCycleDefinition('foundry', args.cycleId, io),
+      'foundry_config_cycle',
     ),
     foundry_config_artefact_type: makeConfigTool(
       tool, 'Get an artefact type definition',
       { typeId: tool.schema.string().describe('Artefact type ID') },
       (args, io) => getArtefactType('foundry', args.typeId, io),
+      'foundry_config_artefact_type',
     ),
     foundry_config_laws: makeConfigTool(
       tool, 'Get laws, optionally filtered by artefact type',
       { typeId: tool.schema.string().optional().describe('Artefact type ID') },
       (args, io) => getLaws('foundry', io, { typeId: args.typeId }),
+      'foundry_config_laws',
     ),
     foundry_config_appraisers: makeConfigTool(
       tool, 'List all appraisers',

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

@@ -3,6 +3,7 @@ import { parseFrontmatter } from '../../../scripts/lib/workfile.js';
 import { requireActiveStage, stageBaseOf } from '../../../scripts/lib/stage-guard.js';
 import { guarded, notFailedGuard } from '../../../scripts/lib/guards.js';
 import { makeIO, branchIoFactory, asyncIoFactory, flowBranchGuard } from './helpers.js';
+import { writeCall } from '../../../scripts/lib/stage-calls.js';
 
 const gateNotFailed = notFailedGuard(makeIO);
 
@@ -170,6 +171,7 @@ async function executeFeedbackList(args, context) {
   }
   try {
     const store = openFeedbackStore('WORK.feedback.yaml', io);
+    writeCall(io, 'foundry_feedback_list');
     const items = store.list()
       .filter(it => !args.file || it.file === args.file)
       .map(it => {

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

@@ -8,10 +8,31 @@ import { syncStore } from '../../../scripts/lib/memory/store.js';
 import { makeIO, makeMemoryIO, branchIoFactory, asyncIoFactory, flowBranchGuard } from './helpers.js';
 import { markWorkfileFailed, readFailedStatus, clearWorkfileFailed } from '../../../scripts/lib/failed-flow.js';
 import { guarded, notFailedGuard } from '../../../scripts/lib/guards.js';
+import { initForgeCallLog, verifyAndClearForgeCallLog } from '../../../scripts/lib/stage-calls.js';
+import { openFeedbackStore } from '../../../scripts/lib/feedback-store.js';
+
+const FORGE_REQUIRED_TOOLS = [
+  'foundry_config_cycle',
+  'foundry_workfile_get',
+  'foundry_config_artefact_type',
+  'foundry_config_laws',
+  'foundry_feedback_list',
+];
+
+function stageBase(stage) { return stage.split(':')[0]; }
 
 const gateNotFailed = notFailedGuard(makeIO);
 
-// -- Helpers for foundry_stage_begin --
+// -- Helpers for forge tool call verification --
+
+function verifyAndManageForgeTools(io, active) {
+  const verified = verifyAndClearForgeCallLog(io, FORGE_REQUIRED_TOOLS);
+  if (!verified.ok) {
+    postMissingToolsFeedback(io, active, verified.missing);
+    return;
+  }
+  resolveSystemFeedback(io, active);
+}
 
 function resolveBaseSha(worktree) {
   try {
@@ -59,9 +80,14 @@ async function executeStageBegin(args, context, pending) {
     startedAt: new Date().toISOString(),
   };
   writeActiveStage(io, active);
+  initForgeIfApplicable(io, active.stage);
   return JSON.stringify({ ok: true, active });
 }
 
+function initForgeIfApplicable(io, stage) {
+  if (stageBase(stage) === 'forge') initForgeCallLog(io);
+}
+
 // -- Helpers for foundry_stage_end --
 
 function markWorkfileFailedSilently(io, msg) {
@@ -82,6 +108,11 @@ async function executeStageEnd(args, context) {
   if (!active) {
     return JSON.stringify({ error: 'foundry_stage_end requires active stage; current: none' });
   }
+
+  if (stageBase(active.stage) === 'forge') {
+    verifyAndManageForgeTools(io, active);
+  }
+
   writeLastStage(io, {
     cycle: active.cycle,
     stage: active.stage,
@@ -101,6 +132,26 @@ async function executeStageEnd(args, context) {
   return JSON.stringify({ ok: true, summary: args.summary });
 }
 
+function postMissingToolsFeedback(io, active, missing) {
+  try {
+    const store = openFeedbackStore('WORK.feedback.yaml', io);
+    store.add({
+      file: '(forge)',
+      tag: 'system:missing-tool-calls',
+      text: `Missing required forge tools: ${missing.join(', ')}`,
+      source: active.stage,
+      cycle: active.cycle,
+    });
+  } catch { /* feedback file not initialised yet; non-critical */ }
+}
+
+function resolveSystemFeedback(io, active) {
+  try {
+    const store = openFeedbackStore('WORK.feedback.yaml', io);
+    store.resolveSystemItems(active.stage, active.cycle);
+  } catch { /* non-critical */ }
+}
+
 // -- Helpers for foundry_stage_retry --
 
 function checkGitWorkingTreeClean(worktree) {

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

@@ -4,6 +4,7 @@ import { requireNoActiveStage } from '../../../scripts/lib/stage-guard.js';
 import { guarded, notFailedGuard } from '../../../scripts/lib/guards.js';
 import { parseFrontmatter, createWorkfile, enrichStages, parseModelsValue } from '../../../scripts/lib/workfile.js';
 import { makeIO, branchIoFactory, asyncIoFactory, flowBranchGuard } from './helpers.js';
+import { writeCall } from '../../../scripts/lib/stage-calls.js';
 
 const gateNotFailed = notFailedGuard(makeIO);
 
@@ -84,6 +85,7 @@ export function createWorkfileTools({ tool }) {
         const fm = parseFrontmatter(text);
         const goalMatch = text.match(/# Goal\n\n([\s\S]*?)(?=\n\||\n##|$)/);
         const goal = goalMatch ? goalMatch[1].trim() : '';
+        writeCall(makeIO(context.worktree), 'foundry_workfile_get');
         return JSON.stringify({ ...fm, goal });
       },
     }),

package/dist/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [3.5.3] - 2026-05-23
+
+### Added
+
+- Forge tool-call verification: `stage_end` checks that required tools were called and posts system feedback if not, with automatic retry via the existing feedback loop.
+
+### Fixed
+
+- Forge dispatch prompts now include explicit required-tool instructions with the actual output type filled in.
+
+### Changed
+
+- `readForgeFilePatterns` returns `{ patterns, outputType }` instead of a bare array.
+- Build quality gate now writes a seal; `prepublishOnly` verifies the seal instead of re-running lint and tests.
+
 ## [3.5.2] - 2026-05-23
 
 ### Fixed

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

@@ -60,14 +60,22 @@ function cloneItem(it) {
   return { ...it, history: it.history.map(h => ({ ...h })) };
 }
 
+function resolveSystemItemsImpl({ items, stage, cycle, timestamp, persist }) {
+  const snapshot = { state: 'resolved', stage, cycle, timestamp: timestamp() };
+  const next = items.map(it =>
+    it.tag === 'system:missing-tool-calls' && it.history[0].state !== 'resolved'
+      ? { ...it, history: [snapshot, ...it.history] }
+      : it
+  );
+  persist(next);
+}
+
 export function openFeedbackStore(path, io) {
   let items = loadItems(path, io);
-
   function persist(nextItems) {
     saveItems(path, nextItems, io);
     items = nextItems;
   }
-
   return {
     list() { return items.map(cloneItem); },
     get(id) {
@@ -89,14 +97,13 @@ export function openFeedbackStore(path, io) {
       });
     },
     writeDeadlockedSnapshotForTest(params) {
-      return storeWriteDeadlockedSnapshot(params, items, {
-        timestamp: nowIso, persist,
-      });
+      return storeWriteDeadlockedSnapshot(params, items, { timestamp: nowIso, persist });
     },
     writeDeadlockedSnapshots(ids, reason, stage, cycle) {
-      return storeWriteDeadlockedSnapshots({ ids, reason, stage, cycle }, items, {
-        timestamp: nowIso, persist,
-      });
+      return storeWriteDeadlockedSnapshots({ ids, reason, stage, cycle }, items, { timestamp: nowIso, persist });
+    },
+    resolveSystemItems(stage, cycle) {
+      resolveSystemItemsImpl({ items, stage, cycle, timestamp: nowIso, persist });
     },
   };
 }

package/dist/scripts/lib/stage-calls.js

@@ -0,0 +1,56 @@
+const LOG_PATH = '.foundry/.forge-tool-calls.jsonl';
+const RETRIES_PATH = '.foundry/.forge-tool-retries';
+
+export function initForgeCallLog(io) {
+  io.writeFile(LOG_PATH, '');
+}
+
+export function writeCall(io, toolName) {
+  if (!io.exists(LOG_PATH)) return;
+  const entry = JSON.stringify({ tool: toolName, ts: Date.now() }) + '\n';
+  const existing = io.readFile(LOG_PATH);
+  io.writeFile(LOG_PATH, existing + entry);
+}
+
+function addCallFromLine(line, called) {
+  try {
+    const rec = JSON.parse(line);
+    if (rec.tool) called.add(rec.tool);
+  } catch { /* skip malformed lines */ }
+}
+
+function readCallSet(io) {
+  const called = new Set();
+  if (!io.exists(LOG_PATH)) return called;
+  const content = io.readFile(LOG_PATH);
+  for (const line of content.split('\n')) {
+    if (line) addCallFromLine(line, called);
+  }
+  return called;
+}
+
+export function verifyAndClearForgeCallLog(io, expected) {
+  const called = readCallSet(io);
+  const missing = expected.filter(t => !called.has(t));
+  io.unlink(LOG_PATH);
+  return missing.length ? { ok: false, missing } : { ok: true, missing: [] };
+}
+
+export function readForgeRetryCount(io) {
+  if (!io.exists(RETRIES_PATH)) return 0;
+  try {
+    return parseInt(io.readFile(RETRIES_PATH).trim(), 10) || 0;
+  } catch {
+    return 0;
+  }
+}
+
+export function incrementForgeRetryCount(io) {
+  const count = readForgeRetryCount(io) + 1;
+  io.writeFile(RETRIES_PATH, String(count));
+  return count;
+}
+
+export function resetForgeRetryCount(io) {
+  io.unlink(RETRIES_PATH);
+}

package/dist/scripts/orchestrate-cycle.js

@@ -39,7 +39,8 @@ export async function readForgeFilePatterns(cycleId, io) {
   const output = extractOutputType(cd);
   if (!output) return null;
   try {
-    return await fetchFilePatterns(output, io);
+    const patterns = await fetchFilePatterns(output, io);
+    return patterns ? { patterns, outputType: output } : null;
   } catch {
     return null;
   }
@@ -228,9 +229,28 @@ export function buildDispatchMultiResponse(tasks, stage, cycle) {
 // Dispatch prompt rendering (pure utility, used by handleSortResult and exported publicly).
 // ---------------------------------------------------------------------------
 
-export function renderDispatchPrompt({ stage, cycle, token, cwd, filePatterns }) {
+function buildForgePromptLines({ cycle, outputType }) {
+  return [
+    ``,
+    `Before producing output you MUST call these tools to understand the context:`,
+    outputType
+      ? `  - foundry_config_cycle({ cycleId: "${cycle}" }) — to learn the cycle definition, including its output type "${outputType}"`
+      : `  - foundry_config_cycle({ cycleId: "${cycle}" }) — to learn the cycle definition`,
+    outputType
+      ? `  - foundry_config_artefact_type({ typeId: "${outputType}" }) — to learn the artefact type definition and file patterns`
+      : `  - foundry_config_artefact_type({ typeId: "<output type>" }) — to learn the artefact type definition and file patterns`,
+    outputType
+      ? `  - foundry_config_laws({ typeId: "${outputType}" }) — to learn all applicable quality laws`
+      : `  - foundry_config_laws({ typeId: "<output type>" }) — to learn all applicable quality laws`,
+    `  - foundry_workfile_get({}) — to learn the goal`,
+    `  - foundry_feedback_list({}) — to check for existing feedback from prior iterations`,
+  ];
+}
+
+export function renderDispatchPrompt({ stage, cycle, token, cwd, filePatterns, outputType }) {
+  const base = stage.split(':')[0];
   const lines = [
-    `You are a Foundry stage agent. Invoke the ${stage.split(':')[0]} skill and follow its instructions exactly.`,
+    `You are a Foundry stage agent. Invoke the ${base} skill and follow its instructions exactly.`,
     ``,
     `Stage: ${stage}`,
     `Cycle: ${cycle}`,
@@ -240,6 +260,9 @@ export function renderDispatchPrompt({ stage, cycle, token, cwd, filePatterns })
   if (filePatterns && filePatterns.length) {
     lines.push(`File patterns (forge only): ${JSON.stringify(filePatterns)}`);
   }
+  if (base === 'forge') {
+    lines.push(...buildForgePromptLines({ cycle, outputType }));
+  }
   lines.push(
     ``,
     `Your FIRST tool call MUST be foundry_stage_begin({stage, cycle, token}) using the values above.`,

package/dist/scripts/orchestrate-phases.js

@@ -2,8 +2,8 @@
 // Private phase functions used by runOrchestrate.
 
 import {
-  getCycleDefinition,
   getArtefactType,
+  getCycleDefinition,
   getLawsForQuench,
 } from './lib/config.js';
 import { parseFrontmatter, writeFrontmatter } from './lib/workfile.js';
@@ -13,73 +13,40 @@ import { stageBaseOf } from './lib/stage-guard.js';
 import { allowedPatternsForStage } from './lib/git-policy.js';
 import { loadExtractor } from './lib/assay/loader.js';
 import { checkExtractorAgainstCycle } from './lib/assay/permissions.js';
-import { getArtefactFiles } from './lib/artefacts.js';
 import {
-  readCycleTargets,
   readForgeFilePatterns,
-  readRecentFeedback,
   computeOpenFeedback,
   violation,
   tryCommit,
   synthesizeStages,
   renderDispatchPrompt,
 } from './orchestrate-cycle.js';
+import {
+  doneAction,
+  blockedAction,
+  humanAppraiseAction,
+  missingModelViolation,
+} from './orchestrate-terminals.js';
 
-async function findOutputArtefacts(cfm, io, foundryDir, baseBranch) {
-  const outputType = cfm ? cfm['output-type'] : undefined;
-  if (!outputType) return null;
-  const artefacts = await getArtefactFiles(foundryDir, outputType, io, { baseBranch });
-  return artefacts.find(a => a.state !== 'deleted') || null;
-}
-
-async function doneAction(cycleId, io, foundryDir, baseBranch) {
-  const fd = foundryDir || 'foundry';
-  const base = baseBranch || 'main';
-  const cfm = (await getCycleDefinition(fd, cycleId, io)).frontmatter;
-  const artefact = await findOutputArtefacts(cfm, io, fd, base);
-  const artefactFile = artefact ? artefact.file : null;
-  return { action: 'done', cycle: cycleId, artefact_file: artefactFile, next_cycles: await readCycleTargets(cycleId, io) };
-}
-
-async function blockedAction(cycleId, io, details, foundryDir, baseBranch) {
-  const fd = foundryDir || 'foundry';
-  const base = baseBranch || 'main';
-  const cfm = (await getCycleDefinition(fd, cycleId, io)).frontmatter;
-  const artefact = await findOutputArtefacts(cfm, io, fd, base);
-  const artefactFile = artefact ? artefact.file : null;
-  const reason = details || 'iteration limit reached with unresolved feedback';
-  return { action: 'blocked', cycle: cycleId, artefact_file: artefactFile, reason };
-}
-
-async function humanAppraiseAction(route, token, ctx) {
-  const { cycleId, io, baseBranch } = ctx;
-  const fd = ctx.foundryDir || 'foundry';
-  const base = baseBranch || 'main';
-  const cfm = (await getCycleDefinition(fd, cycleId, io)).frontmatter;
-  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) } };
-}
-
-async function missingModelViolation(cycleId, route, io, foundryDir, baseBranch) {
-  const fd = foundryDir || 'foundry';
-  const base = baseBranch || 'main';
-  const cfm = (await getCycleDefinition(fd, cycleId, io)).frontmatter;
-  const outputType = cfm ? cfm['output-type'] : undefined;
-  const artefacts = outputType ? await getArtefactFiles(fd, outputType, io, { baseBranch: base }) : [];
-  const affectedFiles = artefacts.filter(a => a.state !== 'deleted').map(a => a.file);
-  return violation(`cycle ${cycleId} stage ${route} has no model declared in cycle definition`, affectedFiles);
-}
-
-function makeDispatchPayload(route, cycleId, token, cwd, filePatterns) {
-  return { stage: route, cycle: cycleId, token, cwd, filePatterns };
+function makeDispatchPayload({ route, cycleId, token, cwd, filePatterns, outputType }) {
+  return { stage: route, cycle: cycleId, token, cwd, filePatterns, outputType };
 }
 
 async function buildDispatchAction(route, model, token, ctx) {
   if (!model) return missingModelViolation(ctx.cycleId, route, ctx.io, ctx.foundryDir, ctx.baseBranch ?? 'main');
   const base = route.split(':')[0];
-  const filePatterns = base === 'forge' ? await readForgeFilePatterns(ctx.cycleId, ctx.io) : null;
-  return { action: 'dispatch', stage: route, subagent_type: model, prompt: renderDispatchPrompt(makeDispatchPayload(route, ctx.cycleId, token, ctx.cwd, filePatterns)) };
+  let filePatterns = null;
+  let outputType = null;
+  if (base === 'forge') {
+    const result = await readForgeFilePatterns(ctx.cycleId, ctx.io);
+    if (result) {
+      filePatterns = result.patterns;
+      outputType = result.outputType;
+    }
+  }
+  const payload = { route, cycleId: ctx.cycleId, token, cwd: ctx.cwd, filePatterns, outputType };
+  return { action: 'dispatch', stage: route, subagent_type: model,
+    prompt: renderDispatchPrompt(makeDispatchPayload(payload)) };
 }
 
 export function routeDispatch(route) {
@@ -282,7 +249,11 @@ function writeHistoryEntries(ctx) {
 
 async function computeAllowedPatterns(lastStage, cycleId, io) {
   const stageBase = stageBaseOf(lastStage.stage);
-  const forgeFilePatterns = stageBase === 'forge' ? (await readForgeFilePatterns(cycleId, io)) ?? [] : [];
+  let forgeFilePatterns = [];
+  if (stageBase === 'forge') {
+    const result = await readForgeFilePatterns(cycleId, io);
+    forgeFilePatterns = result ? result.patterns : [];
+  }
   return allowedPatternsForStage({ stageBase, forgeFilePatterns });
 }
 

package/dist/scripts/orchestrate-terminals.js

@@ -0,0 +1,49 @@
+import { getCycleDefinition } from './lib/config.js';
+import { getArtefactFiles } from './lib/artefacts.js';
+import { readCycleTargets, readRecentFeedback, violation } from './orchestrate-cycle.js';
+
+async function findOutputArtefacts(cfm, io, foundryDir, baseBranch) {
+  const outputType = cfm ? cfm['output-type'] : undefined;
+  if (!outputType) return null;
+  const artefacts = await getArtefactFiles(foundryDir, outputType, io, { baseBranch });
+  return artefacts.find(a => a.state !== 'deleted') || null;
+}
+
+export async function doneAction(cycleId, io, foundryDir, baseBranch) {
+  const fd = foundryDir || 'foundry';
+  const base = baseBranch || 'main';
+  const cfm = (await getCycleDefinition(fd, cycleId, io)).frontmatter;
+  const artefact = await findOutputArtefacts(cfm, io, fd, base);
+  const artefactFile = artefact ? artefact.file : null;
+  return { action: 'done', cycle: cycleId, artefact_file: artefactFile, next_cycles: await readCycleTargets(cycleId, io) };
+}
+
+export async function blockedAction(cycleId, io, details, foundryDir, baseBranch) {
+  const fd = foundryDir || 'foundry';
+  const base = baseBranch || 'main';
+  const cfm = (await getCycleDefinition(fd, cycleId, io)).frontmatter;
+  const artefact = await findOutputArtefacts(cfm, io, fd, base);
+  const artefactFile = artefact ? artefact.file : null;
+  const reason = details || 'iteration limit reached with unresolved feedback';
+  return { action: 'blocked', cycle: cycleId, artefact_file: artefactFile, reason };
+}
+
+export async function humanAppraiseAction(route, token, ctx) {
+  const { cycleId, io, baseBranch } = ctx;
+  const fd = ctx.foundryDir || 'foundry';
+  const base = baseBranch || 'main';
+  const cfm = (await getCycleDefinition(fd, cycleId, io)).frontmatter;
+  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) } };
+}
+
+export async function missingModelViolation(cycleId, route, io, foundryDir, baseBranch) {
+  const fd = foundryDir || 'foundry';
+  const base = baseBranch || 'main';
+  const cfm = (await getCycleDefinition(fd, cycleId, io)).frontmatter;
+  const outputType = cfm ? cfm['output-type'] : undefined;
+  const artefacts = outputType ? await getArtefactFiles(fd, outputType, io, { baseBranch: base }) : [];
+  const affectedFiles = artefacts.filter(a => a.state !== 'deleted').map(a => a.file);
+  return violation(`cycle ${cycleId} stage ${route} has no model declared in cycle definition`, affectedFiles);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@really-knows-ai/foundry",
-  "version": "3.5.2",
+  "version": "3.5.3",
   "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",
@@ -58,7 +58,7 @@
     "test:all": "node --test --experimental-test-module-mocks --test-reporter=dot",
     "test:coverage": "node --test --experimental-test-coverage --test-reporter=dot",
     "lint": "eslint src/ tests/ scripts/",
-    "build:full": "pnpm run lint --fix && pnpm run test:all && pnpm run build",
-    "build:all": "pnpm run lint && pnpm run test:all && pnpm run build"
+    "build:full": "pnpm run lint --fix && pnpm run test:all && pnpm run build && node scripts/seal.js",
+    "build:all": "pnpm run lint && pnpm run test:all && pnpm run build && node scripts/seal.js"
   }
 }