@really-knows-ai/foundry 3.8.1 → 3.8.3

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,33 @@
 # Changelog
 
+## [3.8.3] - 2026-05-27
+
+### Changed
+
+- Appraise subagents no longer receive artefact content or laws in their prompt. The dispatch prompt contains only the appraiser's personality and the artefact type ID. The subagent discovers artefact files, laws, and file-patterns via tool calls (`foundry_config_artefact_type`, `foundry_config_laws`, `foundry_artefacts_list`) and reads files from the worktree.
+
+- Appraise subagent output format changed from YAML to JSONL (one JSON object per line), matching the quench validator protocol. Required fields: `file`, `text`. Recommended: `law`, `evidence`. Optional: `severity`, `location`. The consolidate phase parses JSONL and posts feedback with tag `law:<slug>`.
+
+- Gather phase now creates one task per appraiser (not per artefact × appraiser). Each appraiser covers all artefacts of the given type via tool-based discovery.
+
+### Fixed
+
+- Removed `js-yaml` dependency from appraise-module.js. All YAML parsing and fallback line-parsing code replaced with JSONL parsing.
+
+## [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/appraise-module.js

@@ -2,28 +2,33 @@
  * Appraise module — gathers context for parallel appraiser dispatch and
  * consolidates results after all appraisers have run.
  *
- * Gather phase: reads artefacts, laws, and appraiser personalities, builds
- * subagent prompts, and returns a dispatch_multi action so the orchestrator's
- * LLM dispatches appraisers in parallel.
+ * Gather phase: reads artefacts, selects appraisers, builds subagent prompts
+ * with only personality + type ID (no artefact content or laws inlined), and
+ * returns a dispatch_multi action so the orchestrator's LLM dispatches
+ * appraisers in parallel.
  *
- * Consolidate phase: receives lastResults from the orchestrator, unions and
- * de-duplicates appraiser issues, posts feedback, and finalises the stage
- * so the orchestrator can re-sort and determine the next action.
+ * Each appraiser subagent discovers artefacts, laws, and file-patterns via
+ * tool calls and returns JSONL — one JSON object per line.
+ *
+ * Consolidate phase: receives lastResults from the orchestrator, parses JSONL
+ * from each appraiser, unions and de-duplicates issues, posts feedback, and
+ * finalises the stage so the orchestrator can re-sort and determine the next
+ * action.
  */
 
 import { getArtefactFiles, computeArtefactVersion } from './lib/artefacts.js';
-import { selectAppraisers, getLaws, getCycleDefinition } from './lib/config.js';
+import { selectAppraisers, getCycleDefinition } from './lib/config.js';
 import { openFeedbackStore } from './lib/feedback-store.js';
-import yaml from 'js-yaml';
 
 // ---------------------------------------------------------------------------
 // Public API — gather
 // ---------------------------------------------------------------------------
 
 /**
- * Gather appraise context: read draft artefacts, select appraisers, read laws
- * and artefact content, then build a dispatch_multi action with one task per
- * (artefact, appraiser) pair.
+ * Gather appraise context: read draft artefacts, select appraisers, build a
+ * dispatch_multi action with one task per appraiser. The subagent prompt
+ * contains only the appraiser personality and artefact type ID — the subagent
+ * discovers artefact files, laws, and file-patterns via tool calls.
  *
  * @param {object} ctx
  * @param {string} ctx.cycleId
@@ -36,91 +41,54 @@ import yaml from 'js-yaml';
  * @returns {Promise<{action: string, tasks: Array, stage: string, cycle: string}>}
  */
 export async function gatherAppraiseContext(ctx) {
-  if (!ctx.cycleId) {
-    return violation('cycleId is required', []);
-  }
+  const guarded = guardAppraiseGather(ctx);
+  if (guarded) return guarded;
 
   await resolveStaleAppraiseFeedback(ctx);
 
   const cd = await getCycleDefinition(ctx.foundryDir, ctx.cycleId, ctx.io);
-  const outputType = cd.frontmatter['output-type'];
-  if (!outputType) {
-    return violation(`cycle ${ctx.cycleId} missing output-type field`, []);
-  }
-  const baseBranch = ctx.baseBranch || 'main';
-  const artefacts = await getArtefactFiles(ctx.foundryDir, outputType, ctx.io, { baseBranch });
-  if (artefacts.length === 0) {
-    return emptyDispatch(ctx.cycleId);
-  }
-
-  const typedArtefacts = artefacts.map(artefact => ({ ...artefact, type: outputType }));
-  const tasks = await collectTasks(typedArtefacts, ctx);
-
-  return {
-    action: 'dispatch_multi',
-    tasks,
-    stage: `appraise:${ctx.cycleId}`,
-    cycle: ctx.cycleId,
-  };
-}
+  const outputType = validateOutputType(cd, ctx.cycleId);
+  if (typeof outputType !== 'string') return outputType;
 
-/**
- * Build all appraiser tasks across artefacts, caching per type.
- */
-async function collectTasks(artefacts, ctx) {
-  const tasks = [];
-  const typeCache = new Map();
-
-  for (const artefact of artefacts) {
-    const entry = await resolveTypeEntry(artefact.type, typeCache, ctx);
-    if (!entry) continue;
+  const artefacts = await fetchAppraiseArtefacts(ctx, outputType);
+  if (!Array.isArray(artefacts)) return artefacts;
 
-    addTasksForArtefact(tasks, artefact, entry, ctx);
+  const appraisers = await selectAppraisers(ctx.foundryDir, outputType, { io: ctx.io });
+  if (appraisers.length === 0) {
+    return emptyDispatch(ctx.cycleId);
   }
 
-  return tasks;
+  return buildGatherResponse(appraisers, outputType, ctx);
 }
 
-/**
- * Get or create a cached (appraisers, laws) entry for an artefact type.
- * Returns null when no appraisers are available for the type.
- */
-async function resolveTypeEntry(typeId, cache, ctx) {
-  if (cache.has(typeId)) {
-    return cache.get(typeId);
-  }
-
-  const [appraisers, laws] = await Promise.all([
-    selectAppraisers(ctx.foundryDir, typeId, { io: ctx.io }),
-    getLaws(ctx.foundryDir, ctx.io, { typeId }),
-  ]);
+function guardAppraiseGather(ctx) {
+  return ctx.cycleId ? null : violation('cycleId is required', []);
+}
 
-  const entry = appraisers.length === 0 ? null : { appraisers, laws };
-  cache.set(typeId, entry);
-  return entry;
+function validateOutputType(cd, cycleId) {
+  const outputType = cd.frontmatter['output-type'];
+  return outputType ?? violation(`cycle ${cycleId} missing output-type field`, []);
 }
 
-/**
- * Build and append appraiser tasks for a single artefact.
- */
-function addTasksForArtefact(tasks, artefact, entry, ctx) {
-  let content = '';
-  if (artefact.state !== 'deleted') {
-    content = ctx.io.readFile(artefact.file);
-  }
+async function fetchAppraiseArtefacts(ctx, outputType) {
+  const baseBranch = ctx.baseBranch || 'main';
+  const artefacts = await getArtefactFiles(ctx.foundryDir, outputType, ctx.io, { baseBranch });
+  if (artefacts.length === 0) return emptyDispatch(ctx.cycleId);
+  return artefacts;
+}
 
-  for (const appraiser of entry.appraisers) {
-    const prompt = buildAppraiserPrompt({
-      appraiser,
-      artefact: { file: artefact.file, content },
-      laws: entry.laws,
-    });
+function buildGatherResponse(appraisers, outputType, ctx) {
+  const tasks = appraisers.map(appraiser => ({
+    subagent_type: resolveSubagentType(appraiser, ctx),
+    prompt: buildAppraiserPrompt({ appraiser, typeId: outputType }),
+  }));
 
-    tasks.push({
-      subagent_type: resolveSubagentType(appraiser, ctx),
-      prompt,
-    });
-  }
+  return {
+    action: 'dispatch_multi',
+    tasks,
+    stage: `appraise:${ctx.cycleId}`,
+    cycle: ctx.cycleId,
+  };
 }
 
 /**
@@ -197,9 +165,9 @@ async function resolveStaleAppraiseFeedback(ctx) {
 /**
  * Consolidate appraiser results and finalise the appraise stage.
  *
- * Called by orchestrator after all appraisers have completed. Parses results,
- * posts combined feedback, resolves prior appraise feedback, and advances
- * the cycle to the next stage via finalize.
+ * Called by orchestrator after all appraisers have completed. Parses JSONL
+ * from each appraiser's output, posts combined feedback, resolves prior
+ * appraise feedback, and advances the cycle to the next stage via finalize.
  *
  * @param {object} ctx
  * @param {Array<{ok: boolean, output?: string, error?: string}>} lastResults
@@ -238,20 +206,73 @@ export async function consolidateAppraise(ctx, lastResults) {
 }
 
 /**
- * Parse all successful appraiser outputs and de-duplicate the combined issue
- * list by (file, law-id, issue text).
+ * Parse JSONL from all successful appraiser outputs and de-duplicate the
+ * combined issue list by (file, law-id, issue text).
  */
 function parseConsolidated(successful) {
   const all = [];
 
   for (const result of successful) {
-    const issues = parseAppraiserOutput(result.output || '');
+    const issues = parseAppraiserJsonl(result.output || '');
     all.push(...issues);
   }
 
   return deduplicateIssues(all);
 }
 
+/**
+ * Parse appraiser JSONL output.
+ *
+ * Each line must be a JSON object with at least `file` and `text` fields.
+ * Extra fields (`law`, `evidence`, `severity`, `location`) are preserved.
+ * The `text` field maps to the issue description used for feedback text.
+ */
+function parseAppraiserJsonl(output) {
+  const issues = [];
+  const lines = output.trim().split('\n');
+
+  for (const line of lines) {
+    const issue = parseAppraiserLine(line);
+    if (issue) issues.push(issue);
+  }
+
+  return issues;
+}
+
+function parseAppraiserLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return null;
+
+  const obj = tryJsonParseLine(trimmed);
+  if (!obj) return null;
+
+  return validateJsonlIssue(obj);
+}
+
+function tryJsonParseLine(line) {
+  try { return JSON.parse(line); } catch { return null; }
+}
+
+function validateJsonlIssue(obj) {
+  if (!hasStringField(obj, 'file')) return null;
+  if (!hasStringField(obj, 'text')) return null;
+
+  return {
+    file: obj.file,
+    law: strOrEmpty(obj.law),
+    issue: obj.text,
+    evidence: strOrEmpty(obj.evidence),
+  };
+}
+
+function hasStringField(obj, key) {
+  return typeof obj[key] === 'string' && obj[key].length > 0;
+}
+
+function strOrEmpty(value) {
+  return typeof value === 'string' ? value : '';
+}
+
 /**
  * De-duplicate an issue array by (file, law, issue text).
  */
@@ -332,138 +353,41 @@ function buildConsolidateSummary(count) {
 // ---------------------------------------------------------------------------
 
 /**
- * Build a subagent prompt for a single (appraiser, artefact) pair.
+ * Build a subagent prompt for an appraiser.
  *
- * Follows the template from the appraise skill (src/skills/appraise/SKILL.md)
- * extended to include the file path for deterministic result parsing.
+ * The prompt contains only the appraiser's personality and the artefact type
+ * ID. The subagent discovers artefact files, laws, and file-patterns via tool
+ * calls and returns JSONL — one JSON object per line.
  */
-function buildAppraiserPrompt({ appraiser, artefact, laws }) {
-  const lawSections = laws
-    .map(law => `## ${law.id}\n\n${law.text}`)
-    .join('\n\n');
-
+function buildAppraiserPrompt({ appraiser, typeId }) {
   const lines = [
     'You are an appraiser. Your personality:',
     '',
     appraiser.personality,
     '',
-    'Evaluate the following artefact against each law below. For each law,',
-    'either:',
-    '- Note no issues (pass)',
-    '- Describe the issue, quoting evidence from the artefact',
+    `Evaluate artefacts of type "${typeId}" against applicable laws.`,
     '',
-    '## Artefact',
+    'Use tools to discover context:',
+    `- foundry_config_artefact_type with typeId "${typeId}" for file-patterns`,
+    `- foundry_config_laws with typeId "${typeId}" for applicable laws (prose only)`,
+    '- foundry_artefacts_list for changed files',
+    '- Read matching files from the worktree',
     '',
-    artefact.content,
+    'For each law, evaluate each relevant file. If a violation is found,',
+    'output a JSONL line:',
     '',
-    '## Laws',
+    '{"file": "<path>", "law": "<law-slug>", "text": "<issue description>", "evidence": "<quote>"}',
     '',
-    lawSections,
+    '`file` and `text` are required. `law` and `evidence` are recommended.',
+    'Optional fields `severity` and `location` are passed through unchanged.',
     '',
-    '## Output',
-    '',
-    'Return a list of issues. For each issue:',
-    `- file: ${artefact.file}`,
-    '  law: <law-id>',
-    '  issue: <description>',
-    '  evidence: <quote from artefact>',
-    '',
-    'If there are no issues, return an empty list.',
+    'Output ONLY JSONL — one JSON object per line. No markdown, no commentary.',
+    'If no issues are found, output nothing.',
   ];
 
   return lines.join('\n');
 }
 
-// ---------------------------------------------------------------------------
-// Output parsing
-// ---------------------------------------------------------------------------
-
-/**
- * Parse a structured issue list from an appraiser subagent output.
- *
- * 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.
- */
-function parseAppraiserOutput(output) {
-  const text = output || '';
-  const yamlBlock = extractYamlBlock(text);
-  const issues = tryYamlParse(yamlBlock);
-  if (issues) return issues;
-
-  return parseFallback(text);
-}
-
-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;
-}
-
-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;
-}
-
-const FALLBACK_FIELDS = new Set(['law', 'issue', 'evidence']);
-
-function isCompleteIssue(obj) {
-  return obj && obj.file && obj.law && obj.issue;
-}
-
-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;
-}
-
-function parseFallback(text) {
-  const issues = [];
-  let entry = null;
-
-  for (const line of text.split('\n')) {
-    const kv = parseFallbackLine(line);
-    if (kv) entry = applyFallbackField(kv, entry, issues);
-  }
-
-  return issues.filter(isCompleteIssue);
-}
-
-function parseFallbackLine(line) {
-  const trimmed = line.trim();
-  if (!trimmed) return null;
-
-  const colon = trimmed.indexOf(':');
-  if (colon < 1) return null;
-
-  const key = stripDash(trimmed.slice(0, colon));
-  return {
-    key: key.trim(),
-    value: trimmed.slice(colon + 1).trim(),
-  };
-}
-
-function stripDash(s) {
-  return s.startsWith('- ') ? s.slice(2) : s;
-}
-
 // ---------------------------------------------------------------------------
 // Shared helpers
 // ---------------------------------------------------------------------------

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/appraise/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: appraise
 type: atomic
-description: Subjective evaluation of an artefact against laws via multiple independent appraisers.
+description: Subjective evaluation of an artefact against laws via independent appraiser subagents.
 ---
 
 # Appraise
 
-You orchestrate subjective appraisal of an artefact by dispatching independent sub-agent appraisers, then consolidating their feedback.
+**This skill is subagent-only.** It describes the protocol an appraiser subagent follows when dispatched via `task()` from the orchestrate loop. Do NOT load this skill and run appraise inline — the orchestrate skill returns a `dispatch_multi` action with pre-built prompts; call `task()` with each.
+
+You evaluate artefacts against laws. Your dispatch prompt contains your personality and the artefact type ID. You discover artefact files, laws, and file-patterns via tool calls.
 
 ## Prerequisites
 
@@ -18,152 +20,58 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 
 Appraise runs inside an enforced stage. Your **first** and **last** tool calls are fixed:
 
-1. **First:** `foundry_stage_begin({stage, cycle, token})` — copy the token verbatim from the dispatch prompt.
+1. **First:** `foundry_stage_begin({stage, cycle, token})` — copy the token verbatim from the dispatch prompt. No other tool call is permitted before this one.
 2. **Last:** `foundry_stage_end({summary})`.
 
-Appraise makes **no disk writes**. Feedback output flows through `foundry_feedback_add` and `foundry_feedback_resolve`. The orchestrator's internal finalize step flags any unexpected writes as a violation.
+Appraise makes **no disk writes**. Feedback output flows through JSONL returned in your response text. The orchestrator's internal consolidate step parses the JSONL, posts feedback, and resolves prior items.
 
 ## Protocol
 
-1. `foundry_stage_begin(...)`.
-2. Gather context:
-   - `foundry_workfile_get` — read the `cycle` from frontmatter
-
-     **Check for failed flow state.** If `foundry_workfile_get` returns `{status: "failed", reason: ...}`, STOP. Do not call any other tool. Tell the user:
-
-     > The flow is in a failed state. Reason: `<reason>`.
-     >
-     > No further work is permitted. To recover:
-     >
-     >   1. `foundry_workfile_delete({confirm: true})` to abandon the cycle.
-     >   2. Back out to main (`git checkout main`) and delete the work branch.
-     >   3. Investigate and fix the root cause of the failure before restarting.
-
-     Then return control to the user and stop.
-   - `foundry_artefacts_list({})` — enumerate the current cycle's branch artefact changes as `[{ file, state }]` entries.
-   - For each artefact change, gather its type-specific context:
-     - `foundry_config_laws` with the cycle's output type — applicable laws (global + type-specific)
-     - `foundry_config_artefact_type` with the type ID — the artefact type definition
-     - `foundry_appraisers_select` with the type ID — selected appraiser personalities with their raw model IDs
-
-3. Dispatch each appraiser as an independent sub-agent (see Dispatch below). If this cycle produced multiple artefacts, appraisers evaluate each.
-
-4. Collect results from all appraisers
-
-5. Consolidate (this is judgment):
-   - Union of all issues — if any one appraiser flags it, it's feedback
-   - De-duplicate: merge overlapping observations into a single feedback item
-   - Preserve which appraiser(s) raised each issue (for traceability)
-
-6. For each consolidated issue: `foundry_feedback_add` with `{ file, text, tag: 'law:<slug>' }`. Tags must match `law:<slug>`, and dedup uses the non-resolved `(file, tag, hash(text))` semantics described in Feedback handling.
-
-7. If no appraiser found any issues, the artefact clears appraisal.
-
-8. `foundry_stage_end({summary})`.
-
-## Feedback handling
-
-As an appraise stage, you have two feedback responsibilities:
-
-1. **Adding new law-violation feedback.** For each unmet law, call
-   `foundry_feedback_add` with `{ file, text, tag: 'law:<slug>' }`.
-   The `source` is automatically your stage id (e.g. `appraise:write-check`).
-   The tool rejects any tag not matching `law:<slug>` during an appraise
-   stage; do not attempt bare `'appraise'` or `'review'` tags.
-
-   The tool returns `{ ok: true, id, deduped }` on success. `deduped: true`
-   means an existing non-resolved item with the same `(file, tag,
-   hash(text))` was found (no new snapshot written); `deduped: false`
-   means a new item was created. Resolved items are NOT considered for
-   dedup — a re-added item after a resolution is a legitimate new item
-   (regression feedback).
+1. `foundry_stage_begin(...)` with the token from the dispatch prompt.
+2. `foundry_config_artefact_type` with the type ID — get the artefact type definition and `file-patterns`.
+3. `foundry_config_laws` with the type ID — get all applicable laws (prose only).
+4. `foundry_artefacts_list` — enumerate the current cycle's branch artefact changes.
+5. For each artefact file that matches the type's `file-patterns`, read the file from the worktree.
+6. Evaluate each file against each law. For each law, either:
+   - Note no issues (pass)
+   - Describe the violation, quoting evidence from the artefact
+7. Output JSONL. Each line is one JSON object:
 
-2. **Resolving items you sourced.** Call `foundry_feedback_list` and look
-   at items whose `source` exactly matches your stage id. For items whose
-   current state is `actioned` or `wont-fix`:
-   - Approve: `foundry_feedback_resolve` with `{ id, resolution: 'approved' }`.
-     `reason` is optional.
-   - Reject: `foundry_feedback_resolve` with `{ id, resolution: 'rejected', reason: '...' }`.
-     `reason` is required. A rejection sends the item back to forge for
-     another attempt (the `rejected` state is a legal forge input per
-     §5.1 rule 2).
+   ```json
+   {"file": "<path>", "law": "<law-slug>", "text": "<issue description>", "evidence": "<quote from artefact>"}
+   ```
 
-**Reason rules.** `reason` is required on `resolution: 'rejected'` and on
-any deadlock-override transition. On `resolution: 'approved'` for a
-non-deadlocked item, `reason` is optional.
+   `file` and `text` are required. `law` and `evidence` are recommended — `law` tells the orchestrator which law tag to use, `evidence` quotes the offending passage. Optional extra fields (`severity`, `location`) are passed through unchanged.
 
-**Source-authorship rule.** You can only resolve/reject items whose `source`
-matches your own stage id — not every appraise stage in the cycle, just yours.
-This prevents a second appraise stage from rubber-stamping work it didn't
-request. For deadlocked items, only human-appraise has the override authority.
+   If there are no issues, output nothing (empty response).
 
-**Future work.** Spec §17 notes a planned cycle-level mode that would let
-human-appraise see non-deadlocked unresolved feedback before the orchestrator routes.
-Not available in v2.6.0; appraise stages today are the sole resolver of
-their own non-deadlocked items.
+   Your response text is ONLY JSONL — one JSON object per line. No markdown headings, no code blocks, no commentary, no YAML.
 
-## Dispatch
+8. `foundry_stage_end({summary})`. The summary describes how many issues were found (e.g. "3 issues found" or "No issues found").
 
-Each appraiser is dispatched as an independent sub-agent. The sub-agent receives a prompt containing:
-- The appraiser's personality (from their definition)
-- The artefact content
-- All applicable laws (global + type-specific)
-- Instructions to evaluate the artefact against each law and return issues as a structured list
+## Output examples
 
-### Model resolution
-
-`foundry_appraisers_select` returns raw model IDs for each appraiser. Convert each to an agent name: `foundry-<model.replace(/[/.]/g, '-')>` — both `/` and `.` are replaced with `-`. Examples:
-- `openai/gpt-4o` → `foundry-openai-gpt-4o`
-- `github-copilot/claude-sonnet-4.6` → `foundry-github-copilot-claude-sonnet-4-6`
-
-- If a model is specified: dispatch with `subagent_type: "foundry-<converted-name>"`. If no agent with that name exists, **hard fail**.
-- If no model is specified: dispatch with `subagent_type: "general"` (inherits session model).
-
-Note: per-appraiser `model` overrides are applied here at dispatch time. The cycle-level `models.appraise` value (if set) is used for routing-time agent-file validation only; this skill does not consult it when iterating appraisers.
-
-Dispatch all appraisers in parallel (multiple Task calls in a single response).
-
-### Sub-agent prompt template
+Good (issues found):
 
 ```
-You are an appraiser. Your personality:
-
-<contents of appraiser personality>
-
-Evaluate the following artefact against each law below. For each law, either:
-- Note no issues (pass)
-- Describe the issue, quoting evidence from the artefact
-
-## Artefact
-
-<artefact content>
-
-## Laws
-
-<all applicable laws>
-
-## Output
-
-Return a list of issues. For each issue:
-- law: <law-id>
-- issue: <description>
-- evidence: <quote from artefact>
-
-If there are no issues, return an empty list.
+{"file": "haikus/mountain.md", "law": "syllable-count", "text": "Line 2 has 8 syllables, expected 7", "evidence": "A frog jumps into the pond", "location": "2:1"}
+{"file": "haikus/mountain.md", "law": "nature-imagery", "text": "Contains industrial imagery violating nature-only requirement", "evidence": "The rusty old machine"}
 ```
 
-## History
+Good (no issues found — empty response, then stage_end):
 
-Do NOT call `foundry_history_append` or `foundry_git_commit` — `foundry_orchestrate` handles those (the tools are not registered publicly). Return a summary via `foundry_stage_end` (e.g., "3 issues found across 2 appraisers" or "No issues found").
+(no output text)
 
-### Human override awareness
+## Feedback handling
 
-When reviewing an artefact, check the feedback history for `#human` tagged items. If a human has already ruled on a topic in a prior iteration, do not re-raise the same issue — the human's decision is final.
+You do NOT call `foundry_feedback_add` or `foundry_feedback_resolve`. The orchestrator's consolidate step reads your JSONL output, de-duplicates across all appraisers, posts feedback items with tag `law:<slug>`, and resolves prior appraise-sourced feedback.
 
 ## What you do NOT do
 
-- You do not write files — feedback output goes through `foundry_feedback_add` and `foundry_feedback_resolve`.
-- You do not revise the artefact.
+- You do not write files — feedback output goes through JSONL, not `foundry_feedback_add`.
+- You do not revise the artefact — that is the forge skill's job.
 - You do not run deterministic validators — that is the quench skill's job.
-- You do not filter out feedback because only one appraiser raised it — one is enough.
-- You do not register artefacts — that happens automatically via the orchestrator's internal finalize step.
+- You do not call `foundry_feedback_add`, `foundry_feedback_action`, `foundry_feedback_wontfix`, or `foundry_feedback_resolve`.
+- You do not call `foundry_history_append` or `foundry_git_commit` — `foundry_orchestrate` handles those.
+- You do not register artefacts — that happens automatically.
+- You do not output YAML, markdown, or prose — only JSONL.

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.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",