@really-knows-ai/foundry 3.8.2 → 3.8.4

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

@@ -133,6 +133,7 @@ function artefactTypeArgs(s) { return {
   name: s.string().describe('Human-readable display name (accepted at boundary, not persisted — id becomes frontmatter.name)'),
   filePatterns: s.array(s.string()).describe('Glob patterns defining forge write scope (written to frontmatter.file-patterns)'),
   description: s.string().describe('Prose description placed under ## Definition'),
+  example: s.string().optional().describe('Example artefact structure (markdown with code blocks). Written to example.md alongside definition.md. Guides forge agents on the expected output format.'),
   appraisers: s.object({
     count: s.number().optional().describe('Number of appraisers per cycle'),
     allowed: s.array(s.string()).optional().describe('Restrict to specific appraiser IDs'),

package/dist/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [3.8.4] - 2026-05-27
+
+### Added
+
+- `foundry_config_create_artefact_type` now accepts an optional `example` arg. When provided, it writes `foundry/artefacts/<id>/example.md` alongside `definition.md`. The example file is a structure document — markdown with code blocks showing the expected output format, plus documentation for the forge agent.
+
+- The `add-artefact-type` skill now prompts users to provide an example artefact during the Understand phase, includes it in the Plan, and passes it to the create tool in Build.
+
+### Fixed
+
+- Human-appraise stage tokens no longer carry a subagent model scope. Previously, `sort.js` resolved a model for human-appraise routes (falling through to `defaultModel`), which got embedded in the token. `foundry_stage_begin` then rejected the token because the main Foundry agent is not the scoped subagent, causing the human-appraise stage to fail to start and user feedback to be lost. Human-appraise always runs inline by the Foundry agent.
+
+## [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

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/config-creators/artefact-type.js

@@ -50,7 +50,30 @@ const _create = makeCreator({
   validator: validate,
 });
 
+/**
+ * Assemble the markdown body for example.md from structured arguments.
+ *
+ * The example file is a structure document: markdown with code blocks showing
+ * the expected output format, plus documentation for the forge agent.
+ *
+ * @param {string} exampleContent - Raw markdown for example.md
+ * @returns {string} Trimmed content with trailing newline.
+ */
+export function assembleExampleMarkdown(exampleContent) {
+  return `${exampleContent.trim()}\n`;
+}
+
 export async function create(args) {
   const body = assembleArtefactTypeMarkdown(args);
+
+  if (args.example) {
+    const exampleDir = join('foundry', 'artefacts', args.id);
+    await args.io.mkdirp(exampleDir);
+    await args.io.writeFile(
+      join(exampleDir, 'example.md'),
+      assembleExampleMarkdown(args.example),
+    );
+  }
+
   return _create({ ...args, name: args.id, body });
 }

package/dist/scripts/sort.js

@@ -166,6 +166,7 @@ function resolveModelId(routeBase, models, defaultModel) {
 
 function pickModelId(route, frontmatter, defaultModel) {
   const routeBase = baseStage(route);
+  if (routeBase === 'human-appraise') return null;
   const resolved = frontmatter.models ? resolveModelId(routeBase, frontmatter.models, defaultModel) : null;
   return resolved || defaultModel || defaultForStage(routeBase);
 }

package/dist/skills/add-artefact-type/SKILL.md

@@ -38,7 +38,7 @@ Do not tell the user to call branch tools directly.
 
 When invoked with pre-filled fields matching the `foundry_config_create_artefact_type` tool args, skip questions for provided fields. Missing fields trigger clarifying questions.
 
-Context fields: `{id, name, filePatterns, description, appraisers?}`
+Context fields: `{id, name, filePatterns, description, example?, appraisers?}`
 
 When invoked with a context:
 - If all required fields are present, skip the Understand phase and proceed to Plan → Confirm → Build.
@@ -48,6 +48,12 @@ When invoked with a context:
 
 Ask for each field one question at a time. Prefer multiple choice for `filePatterns`, deriving options from the artefact type name and common conventions (e.g. `haikus/*.md`, `haiku.md`, `output/haiku/*.md`). Ask about `appraisers` (optional) — either provide an existing appraiser ID or skip.
 
+After the core fields, ask about the example:
+
+> Would you like to provide an example artefact? An example shows forge agents the expected output structure — markdown with code blocks, plus any conventions, constraints, or required sections. Give a short example file that demonstrates what a valid output looks like.
+
+If the user provides an example, capture it verbatim. If the artefact type has no structured output (e.g. free-form prose with no required format), the user may skip this step.
+
 **Naming conflict check**: Read all existing artefact type definitions in `foundry/artefacts/*/definition.md`. Exact id match means a hard conflict — choose a different id. A semantically similar name or description triggers a warning:
 
 > An artefact type `<existing-id>` already exists that seems similar:
@@ -74,6 +80,7 @@ Present the definition to the user with these structured fields:
 - `name` (string) — human-readable label.
 - `filePatterns` (string[]) — glob patterns for files this type produces.
 - `description` (string) — prose description of what this artefact type is.
+- `example` (string, optional) — example artefact to guide forge agents on the expected output structure.
 - `appraisers` ({ count?: number, allowed?: string[] }, optional) — appraiser configuration.
 
 Ask: does this capture the artefact type correctly? Iterate until the user is satisfied.
@@ -86,7 +93,7 @@ Ask: "Proceed with this plan?" — wait for user answer before building. If the
 
 1. **Validate**: Call `foundry_config_validate_artefact_type({ name: "<id>", body: "<assembled markdown>" })`. Assemble the body from the fields using the frontmatter format the tool produces internally. If the result is `{ ok: false, errors: [...] }`, address each error and re-run until `{ ok: true }`. Common issues: missing required frontmatter keys, references to artefact types or flows that do not exist yet.
 
-2. **Create**: Call `foundry_config_create_artefact_type({ id: "<id>", name: "<name>", filePatterns: ["<pattern>"], description: "<description>" })`. The tool re-validates the body (TOCTOU), writes `foundry/artefacts/<id>/definition.md`, and produces one git commit on the current `config/*` branch. Show the user the resulting commit hash.
+2. **Create**: Call `foundry_config_create_artefact_type({ id: "<id>", name: "<name>", filePatterns: ["<pattern>"], description: "<description>", example: "<example>" })`. Include `example` only when the user provided one. The tool re-validates the body (TOCTOU), writes `foundry/artefacts/<id>/definition.md` (and `example.md` if provided), and produces one git commit on the current `config/*` branch. Show the user the resulting commit hash.
 
    If the tool returns `{ ok: false, errors }` because the target file already exists, read the existing file, incorporate the user's requested changes into the current body, propose the merged result for review, then write and commit the updated file.
 

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/package.json

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