@really-knows-ai/foundry 3.8.1 → 3.8.2

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

@@ -8,7 +8,7 @@ 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 { initForgeCallLog, readForgeCallSet } from '../../../scripts/lib/stage-calls.js';
 import { openFeedbackStore } from '../../../scripts/lib/feedback-store.js';
 
 const FORGE_REQUIRED_TOOLS = [
@@ -18,6 +18,12 @@ const FORGE_REQUIRED_TOOLS = [
   'foundry_config_laws',
 ];
 
+const FORGE_FORBIDDEN_TOOLS = [
+  'foundry_feedback_action',
+  'foundry_feedback_wontfix',
+  'foundry_feedback_resolve',
+];
+
 function stageBase(stage) { return stage.split(':')[0]; }
 
 const gateNotFailed = notFailedGuard(makeIO);
@@ -25,9 +31,16 @@ const gateNotFailed = notFailedGuard(makeIO);
 // -- 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);
+  const callSet = readForgeCallSet(io);
+  const forbidden = FORGE_FORBIDDEN_TOOLS.filter(t => callSet.has(t));
+  const missing = FORGE_REQUIRED_TOOLS.filter(t => !callSet.has(t));
+  io.unlink('.foundry/.forge-tool-calls.jsonl');
+  if (forbidden.length) {
+    postForbiddenToolsFeedback(io, active, forbidden);
+    return;
+  }
+  if (missing.length) {
+    postMissingToolsFeedback(io, active, missing);
     return;
   }
   resolveSystemFeedback(io, active);
@@ -144,6 +157,19 @@ async function executeStageEnd(args, context) {
   return JSON.stringify({ ok: true, summary: args.summary });
 }
 
+function postForbiddenToolsFeedback(io, active, forbidden) {
+  try {
+    const store = openFeedbackStore('WORK.feedback.yaml', io);
+    store.add({
+      file: '(forge)',
+      tag: 'system:forbidden-tool-calls',
+      text: `Forbidden forge tool calls: ${forbidden.join(', ')}. Forge subagents do not manage feedback — the orchestrator handles transitions.`,
+      source: active.stage,
+      cycle: active.cycle,
+    });
+  } catch { /* feedback file not initialised yet; non-critical */ }
+}
+
 function postMissingToolsFeedback(io, active, missing) {
   try {
     const store = openFeedbackStore('WORK.feedback.yaml', io);

package/dist/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [3.8.2] - 2026-05-27
+
+### Changed
+
+- Forge subagent protocol simplified to three keywords: `DONE` (first generation), `ACTIONED` (file changed), `WONT-FIX: <justification>` (no changes needed). The `foundry_stage_end` summary must be exactly one of these — no descriptions, no explanations. The forge contract recognises `ACTIONED` even without a version change.
+
+- WONT-FIX is now allowed for all feedback source types (quench, appraise, human-appraise), not just appraise. The `WONT-FIX:` keyword in the summary transitions the item regardless of source.
+
+### Fixed
+
+- Forge subagents are blocked from calling `foundry_feedback_action`, `foundry_feedback_wontfix`, or `foundry_feedback_resolve` — `foundry_stage_end` checks the call log and posts `system:forbidden-tool-calls` feedback if any were called.
+
+- Single-item dispatch prompts clarified: the orchestrator dispatches one feedback item per forge call. The orchestrate skill instructs the LLM to pass the prompt verbatim without injecting extra items from quench output.
+
 ## [3.8.1] - 2026-05-27
 
 ### Fixed

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

@@ -99,7 +99,5 @@ export function hashText(text) {
  */
 export function canForgeWontFix(item, callerStageBase) {
   if (callerStageBase !== 'forge') return false;
-  if (!item || typeof item.source !== 'string' || !item.source) return false;
-  const sourceBase = item.source.split(':')[0];
-  return sourceBase === 'appraise';
+  return !!(item && typeof item.source === 'string' && item.source);
 }

package/dist/scripts/lib/forge-contract.js

@@ -45,28 +45,18 @@ function handleVersionChanged(item, feedbackStore, cycleId, postVersion) {
 }
 
 function handleWontFixWithReason(item, feedbackStore, cycleId, postVersion, reason) {
-  const sourceBase = typeof item.source === 'string' ? item.source.split(':')[0] : '';
-  if (sourceBase === 'appraise') {
-    const result = feedbackStore.transition({
-      id: item.id,
-      target: 'wont-fix',
-      stage: 'forge:' + cycleId,
-      cycle: cycleId,
-      reason,
-    });
-    if (!result.ok) {
-      postSystemFeedback(feedbackStore, cycleId, postVersion, result.error || 'store transition failed');
-      feedbackStore.forceState(item.id, 'open', cycleId, `forge:${cycleId}`);
-    }
-    return { contractPassed: result.ok };
+  const result = feedbackStore.transition({
+    id: item.id,
+    target: 'wont-fix',
+    stage: 'forge:' + cycleId,
+    cycle: cycleId,
+    reason,
+  });
+  if (!result.ok) {
+    postSystemFeedback(feedbackStore, cycleId, postVersion, result.error || 'store transition failed');
+    feedbackStore.forceState(item.id, 'open', cycleId, `forge:${cycleId}`);
   }
-  // quench or human-appraise — wont-fix not allowed
-  postSystemFeedback(
-    feedbackStore, cycleId, postVersion,
-    `wont-fix not allowed on ${sourceBase}-sourced item; wont-fix is only allowed for appraise-sourced items`,
-  );
-  feedbackStore.forceState(item.id, 'open', cycleId, `forge:${cycleId}`);
-  return { contractPassed: false };
+  return { contractPassed: result.ok };
 }
 
 /**
@@ -81,24 +71,23 @@ function handleWontFixWithReason(item, feedbackStore, cycleId, postVersion, reas
  * @returns {{ contractPassed: boolean }}
  */
 export function enforceForgeContract({ item, preVersion, postVersion, summary, feedbackStore, cycleId }) {
-  // No item means forge had no prior feedback to respond to.
   if (!item) return { contractPassed: true };
 
-  // Version changed → forge fixed the issue
-  if (preVersion !== postVersion) {
-    return handleVersionChanged(item, feedbackStore, cycleId, postVersion);
-  }
-
-  // Version unchanged — check for WONT-FIX justification
   const wontFixMatch = summary.match(/WONT-FIX:\s*(.+)/);
+  const versionChanged = preVersion !== postVersion;
+  const actioned = summary.trim() === 'ACTIONED';
+
   if (wontFixMatch) {
     return handleWontFixWithReason(item, feedbackStore, cycleId, postVersion, wontFixMatch[1]);
   }
 
-  // Version unchanged with no WONT-FIX — neither fix nor justification
+  if (versionChanged || actioned) {
+    return handleVersionChanged(item, feedbackStore, cycleId, postVersion);
+  }
+
   postSystemFeedback(
     feedbackStore, cycleId, postVersion,
-    'forge did not change artefacts and did not provide WONT-FIX justification',
+    'forge did not change artefacts and did not provide ACTIONED or WONT-FIX justification',
   );
   feedbackStore.forceState(item.id, 'open', cycleId, `forge:${cycleId}`);
   return { contractPassed: false };

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

@@ -35,7 +35,7 @@ function forgeReason(d) {
   if (d.forgeCount === 0 && d.needingForge === 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})`;
+  return `found ${d.needingForge} unresolved feedback item(s) — dispatching one item at a time to forge (revision ${d.forgeCount + 1} of ${d.maxIt})`;
 }
 
 function appraiseReason(d) {

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

@@ -29,6 +29,10 @@ function readCallSet(io) {
   return called;
 }
 
+export function readForgeCallSet(io) {
+  return readCallSet(io);
+}
+
 export function verifyAndClearForgeCallLog(io, expected) {
   const called = readCallSet(io);
   const missing = expected.filter(t => !called.has(t));

package/dist/scripts/orchestrate-cycle.js

@@ -266,15 +266,17 @@ function buildForgePromptLines({ cycle, outputType, forgeItem }) {
       `File: ${forgeItem.file}`,
       `Issue: ${forgeItem.text}`,
       ``,
-      `You MUST either:`,
-      `  a) Fix the issue by changing the artefact file. The orchestrator`,
-      `     will record this as ACTIONED.`,
-      `  b) If this is an appraise-sourced item (subjective quality`,
-      `     feedback), you may respond with:`,
-      `     WONT-FIX: <justification for why you disagree>`,
+      `Respond with EXACTLY one of:`,
+      `  - ACTIONED  — fix the issue by changing the artefact file`,
+      `  - WONT-FIX: <justification> — the issue is already resolved or does not apply`,
       ``,
-      `Quench-sourced items are deterministic validation failures —`,
-      `you MUST fix them. There is no wont-fix option.`,
+      `Write NOTHING else in the stage_end summary — no descriptions, no explanations.`,
+    );
+  } else {
+    lines.push(
+      ``,
+      `First generation — no feedback to address yet.`,
+      `Produce the artefact and call foundry_stage_end({summary: "DONE"}).`,
     );
   }
   return lines;
@@ -300,8 +302,6 @@ export function renderDispatchPrompt({ stage, cycle, token, cwd, filePatterns, o
     ``,
     `Your FIRST tool call MUST be foundry_stage_begin({stage, cycle, token}) using the values above.`,
     `Your LAST tool call MUST be foundry_stage_end({summary}).`,
-    ``,
-    `When done, report back a brief summary. Do NOT call foundry_history_append, foundry_git_commit, or foundry_artefacts_add — the orchestrator handles all of those.`
   );
   return lines.join('\n');
 }

package/dist/skills/forge/SKILL.md

@@ -51,43 +51,38 @@ Forge runs inside an enforced stage. Your **first** and **last** tool calls are
    - Read the selected files for context.
 7. Produce the artefact, respecting all applicable laws from the start.
 8. Write the artefact file to a location that matches the artefact type's `file-patterns`.
-9. `foundry_stage_end({summary})`.
+9. `foundry_stage_end({summary: "DONE"})`.
 
 ### Revision (feedback exists)
 
 1. `foundry_stage_begin(...)`.
 2. Read the artefact file.
 3. If the cycle declares `inputs`, discover them via filesystem scan against each input type's `file-patterns` (same protocol as first-generation step 6). Re-read the relevant files — they may have changed on disk since the previous iteration (nothing in this cycle wrote to them, but the user may have modified them between iterations).
-4. Address the single feedback item from the dispatch prompt following the feedback handling rules below — either fix the artefact, or for appraise-sourced items write a WONT-FIX justification in the summary.
-5. Update the artefact file.
-6. `foundry_stage_end({summary})`.
+4. Address the single feedback item from the dispatch prompt following the feedback handling rules below.
+5. Update the artefact file (if fixing), or skip (if WONT-FIX).
+6. `foundry_stage_end({summary})`. The summary must be EXACTLY one of:
+   - `"ACTIONED"` — file was changed to address the feedback
+   - `"WONT-FIX: <justification>"` — item already resolved or does not apply
+   Write NOTHING else in the summary.
 
 ## Feedback handling
 
-The dispatch prompt already contains the single feedback item for this
-iteration. Each item has the shape `{ id, file, tag, text, source, state,
-depth, reason? }`.
+The dispatch prompt contains one feedback item to address.
 
-Fix the issue by changing the artefact — the orchestrator records the item
-as actioned when it detects your changes on disk.
+**To fix the issue** — change the artefact file and call
+`foundry_stage_end({summary: "ACTIONED"})`.
 
-For items whose `source` stage base is `appraise` only, you may instead
-respond with `WONT-FIX: <justification>` in the `foundry_stage_end`
-summary. The orchestrator records the item as wont-fix.
+**If the issue is already resolved** — call
+`foundry_stage_end({summary: "WONT-FIX: <justification>"})`.
+Do NOT change the file.
 
-Items whose source base is `quench` (objective validation failure) or
-`human-appraise` (direct user instruction) are deterministic failures that
-**must** be fixed. There is no wont-fix option for these.
+**If the issue does not apply** (appraise judgement you disagree with) — same
+`WONT-FIX:` flow.
 
-`foundry_feedback_add` (if you ever call it — forge normally does not)
-returns `{ ok, id, deduped }`. `deduped: true` means an existing
-non-resolved item with the same `(file, tag, hash(text))` was found and no
-new item was written; the returned `id` is the existing item's id.
-`deduped: false` means a new item was created.
+The summary is ONLY one of these keywords. No descriptions, no explanations.
 
-You cannot resolve or reject items — only the stage that created the item
-(the `source` on each list entry) can do that, with the exception that
-human-appraise can override any non-resolved item.
+Do NOT call `foundry_feedback_action`, `foundry_feedback_wontfix`, or
+`foundry_feedback_resolve`. The orchestrator handles transitions automatically.
 
 ## Write invariant
 

package/dist/skills/orchestrate/SKILL.md

@@ -45,11 +45,8 @@ task tool:
   description: "Run <stage> for <cycle>"
   prompt: <prompt-from-payload — pass verbatim>
 ```
-task tool:
-  subagent_type: <subagent_type-from-payload>
-  description: "Run <stage> for <cycle>"
-  prompt: <prompt-from-payload — pass verbatim>
-```
+
+**Critical for forge dispatch:** The orchestrator dispatches one feedback item per forge subagent call. The `prompt` already contains exactly one `FEEDBACK ITEM TO ADDRESS`. Pass the prompt verbatim — do NOT read quench output, do NOT add additional feedback items, do NOT inject validator results. The orchestrator will dispatch a separate `task()` call for each unresolved item.
 
 When the task returns, call `foundry_orchestrate({lastResult: {ok: true}})`. If the task tool itself errored or reported a subagent crash, pass `{ok: false, error: '<message>'}`.
 
@@ -114,6 +111,7 @@ Report to the user: "Cycle halted (violation): `<details>`. Affected files: `<af
 - You do NOT mint, modify, or cache tokens. The `prompt` from orchestrate already contains the token verbatim.
 - `foundry_history_append`, `foundry_git_commit`, `foundry_stage_finalize`, and `foundry_sort` are not registered tools; orchestrate handles them internally via the loop.
 - You do NOT reorder the protocol. `foundry_orchestrate` returns, you act, you call back. Nothing else between.
+- You do NOT add extra feedback items to the forge dispatch prompt. The orchestrator dispatches one item at a time. Each prompt already contains exactly one `FEEDBACK ITEM TO ADDRESS`. Do not read quench output and inject additional items.
 
 ## Feedback visibility
 

package/package.json

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