@really-knows-ai/foundry 2.2.1 → 2.3.1

package/scripts/orchestrate.js

@@ -0,0 +1,418 @@
+// Foundry v2.3.0 orchestrate: deterministic cycle orchestration.
+// Composes internal functions (sort, finalize, history, commit, configure)
+// into a single entry point the LLM drives via a 3-line loop.
+
+import { runSort } from './sort.js';
+import {
+  getCycleDefinition,
+  getArtefactType,
+  getValidation,
+} from './lib/config.js';
+import { parseFrontmatter, writeFrontmatter } from './lib/workfile.js';
+import { parseArtefactsTable, addArtefactRow, setArtefactStatus } from './lib/artefacts.js';
+import { readActiveStage, readLastStage, clearActiveStage } from './lib/state.js';
+import { appendEntry, getIteration } from './lib/history.js';
+import { listFeedback } from './lib/feedback.js';
+
+export function renderDispatchPrompt({ stage, cycle, token, cwd, filePatterns }) {
+  const lines = [
+    `You are a Foundry stage agent. Invoke the ${stage.split(':')[0]} skill and follow its instructions exactly.`,
+    ``,
+    `Stage: ${stage}`,
+    `Cycle: ${cycle}`,
+    `Token: ${token}`,
+    `Working directory: ${cwd}`,
+  ];
+  if (filePatterns && filePatterns.length) {
+    lines.push(`File patterns (forge only): ${JSON.stringify(filePatterns)}`);
+  }
+  lines.push(
+    ``,
+    `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');
+}
+
+export function synthesizeStages({ cycleId, hasValidation, humanAppraise }) {
+  const stages = [`forge:${cycleId}`];
+  if (hasValidation) stages.push(`quench:${cycleId}`);
+  stages.push(`appraise:${cycleId}`);
+  if (humanAppraise) stages.push(`human-appraise:${cycleId}`);
+  return stages;
+}
+
+export function needsSetup(workMdContent) {
+  const match = workMdContent.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return true;
+  const fm = match[1];
+  return !/^stages:/m.test(fm);
+}
+
+// ---------------------------------------------------------------------------
+// Task-6 stub helpers (wired in later). readForgeFilePatterns is real now
+// because the first-call dispatch prompt needs it.
+// ---------------------------------------------------------------------------
+
+export function findCycleOutputArtefact(cycleId, io) {
+  if (!io.exists('WORK.md')) return null;
+  const content = io.readFile('WORK.md');
+  const rows = parseArtefactsTable(content);
+  const match = rows.find(r => r.cycle === cycleId);
+  return match ? { file: match.file, type: match.type, status: match.status } : null;
+}
+
+export async function readCycleTargets(cycleId, io) {
+  try {
+    const cd = await getCycleDefinition('foundry', cycleId, io);
+    return cd.frontmatter?.targets ?? [];
+  } catch {
+    return [];
+  }
+}
+
+export async function readForgeFilePatterns(cycleId, io) {
+  try {
+    const cd = await getCycleDefinition('foundry', cycleId, io);
+    const output = cd.frontmatter?.output;
+    if (!output) return null;
+    const at = await getArtefactType('foundry', output, io);
+    return at.frontmatter?.['file-patterns'] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function readRecentFeedback(cycleId, io, limit = 5) {
+  // Best-effort: surface recent deadlocked items (rejected or wont-fix) for
+  // the human-appraise checkpoint. Returns last `limit` matching entries.
+  // On any parse error, return [] rather than crashing the cycle.
+  try {
+    if (!io.exists('WORK.md')) return [];
+    const content = io.readFile('WORK.md');
+    const rows = parseArtefactsTable(content);
+    const items = listFeedback(content, cycleId, rows);
+    const deadlocked = items.filter(
+      it => it.state === 'wont-fix' || it.state === 'rejected'
+    );
+    return deadlocked.slice(-limit);
+  } catch {
+    return [];
+  }
+}
+
+function violation(details, affectedFiles = []) {
+  return {
+    action: 'violation',
+    details,
+    recoverable: false,
+    affected_files: affectedFiles,
+  };
+}
+
+function markArtefactBlocked(cycleId, io) {
+  if (!io.exists('WORK.md')) return { ok: true };
+  const content = io.readFile('WORK.md');
+  const rows = parseArtefactsTable(content);
+  const row = rows.find(r => r.cycle === cycleId);
+  if (!row) return { ok: true };
+  try {
+    io.writeFile('WORK.md', setArtefactStatus(content, row.file, 'blocked'));
+    return { ok: true };
+  } catch (e) {
+    // Surface to caller: setArtefactStatus is strict (e.g. row already
+    // blocked/done, invalid status). Don't crash; let caller annotate
+    // the violation.
+    return { ok: false, error: e?.message || String(e) };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Sort result -> action shape
+// ---------------------------------------------------------------------------
+
+async function handleSortResult(sortResult, { cycleId, cwd, io }) {
+  const { route, model, token, details } = sortResult;
+  const base = typeof route === 'string' ? route.split(':')[0] : '';
+
+  if (route === 'done') {
+    const art = findCycleOutputArtefact(cycleId, io);
+    return {
+      action: 'done',
+      cycle: cycleId,
+      artefact_file: art?.file ?? null,
+      next_cycles: await readCycleTargets(cycleId, io),
+    };
+  }
+
+  if (route === 'blocked') {
+    const art = findCycleOutputArtefact(cycleId, io);
+    return {
+      action: 'blocked',
+      cycle: cycleId,
+      artefact_file: art?.file ?? null,
+      reason: details ?? 'iteration limit reached with unresolved feedback',
+    };
+  }
+
+  if (route === 'violation') {
+    return violation(details ?? 'sort returned violation');
+  }
+
+  if (base === 'human-appraise') {
+    const art = findCycleOutputArtefact(cycleId, io);
+    return {
+      action: 'human_appraise',
+      stage: route,
+      token,
+      context: {
+        cycle: cycleId,
+        artefact_file: art?.file ?? null,
+        recent_feedback: readRecentFeedback(cycleId, io),
+      },
+    };
+  }
+
+  // forge | quench | appraise
+  if (!model) {
+    const art = findCycleOutputArtefact(cycleId, io);
+    return violation(
+      `cycle ${cycleId} stage ${route} has no model declared in cycle definition (\`models:\` field) and no default available`,
+      [art?.file].filter(Boolean)
+    );
+  }
+
+  const filePatterns = base === 'forge'
+    ? await readForgeFilePatterns(cycleId, io)
+    : null;
+
+  return {
+    action: 'dispatch',
+    stage: route,
+    subagent_type: model,
+    prompt: renderDispatchPrompt({
+      stage: route,
+      cycle: cycleId,
+      token,
+      cwd,
+      filePatterns,
+    }),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+export async function runOrchestrate(args = {}, io) {
+  const {
+    cwd = process.cwd(),
+    cycleDef: cycleDefOverride = null,
+    git,
+    mint,
+    now = Date.now,
+    lastResult = null,
+    finalize = null,
+  } = args;
+
+  if (!io.exists('WORK.md')) {
+    return violation('no WORK.md; flow skill must create it first');
+  }
+
+  let workContent = io.readFile('WORK.md');
+  const fm = parseFrontmatter(workContent);
+  const cycleId = fm.cycle;
+  if (!cycleId) {
+    return violation('WORK.md frontmatter missing cycle field', ['WORK.md']);
+  }
+
+  if (needsSetup(workContent)) {
+    if (lastResult) {
+      return violation(
+        'inconsistent state: lastResult provided but WORK.md still needs setup',
+        ['WORK.md']
+      );
+    }
+
+    const foundryDir = 'foundry';
+    let cycleDefDoc;
+    try {
+      cycleDefDoc = await getCycleDefinition(foundryDir, cycleId, io);
+    } catch {
+      return violation(`cycle definition not found for id: ${cycleId}`, ['WORK.md']);
+    }
+    const cfm = cycleDefDoc.frontmatter || {};
+
+    const outputType = cfm.output;
+    if (!outputType) {
+      return violation(`cycle ${cycleId} missing output field`, ['WORK.md']);
+    }
+
+    try {
+      await getArtefactType(foundryDir, outputType, io);
+    } catch {
+      return violation(`artefact type not found: ${outputType}`, ['WORK.md']);
+    }
+
+    const validation = await getValidation(foundryDir, outputType, io);
+
+    let stages;
+    if (Array.isArray(cfm.stages)) {
+      if (cfm.stages.length === 0) {
+        const art = findCycleOutputArtefact(cycleId, io);
+        return violation(
+          `cycle ${cycleId} has no stages declared in cycle definition`,
+          [art?.file, 'WORK.md'].filter(Boolean)
+        );
+      }
+      stages = cfm.stages.map(s =>
+        typeof s === 'string' && s.includes(':') ? s : `${s}:${cycleId}`
+      );
+    } else {
+      stages = synthesizeStages({
+        cycleId,
+        hasValidation: !!validation && validation.length > 0,
+        humanAppraise: cfm['human-appraise'] === true,
+      });
+    }
+
+    const newFm = { ...fm };
+    newFm.stages = stages;
+    newFm['max-iterations'] = cfm['max-iterations'] ?? 3;
+    newFm['human-appraise'] = cfm['human-appraise'] === true;
+    newFm['deadlock-appraise'] = cfm['deadlock-appraise'] !== false;
+    newFm['deadlock-iterations'] = cfm['deadlock-iterations'] ?? 5;
+    if (cfm.models) newFm.models = cfm.models;
+
+    const body = workContent.replace(/^---\n[\s\S]+?\n---\n?/, '');
+    const fmBlock = writeFrontmatter(newFm);
+    const newWork = body ? `${fmBlock}\n${body}` : fmBlock;
+    io.writeFile('WORK.md', newWork);
+
+    if (git && typeof git.commit === 'function') {
+      git.commit(`[${cycleId}] setup: configure stages and limits`);
+    }
+
+    workContent = io.readFile('WORK.md');
+  }
+
+  const activeStage = readActiveStage(io);
+  const lastStage = readLastStage(io);
+
+  if (activeStage && !lastResult) {
+    return violation(
+      `prior stage ${activeStage.stage} orphaned — no lastResult provided but active stage exists. ` +
+      `Likely cause: previous orchestrate call returned dispatch but caller did not follow up.`,
+      []
+    );
+  }
+
+  if (lastResult) {
+    // Subagent crash path: stage_end may NOT have been called, so activeStage
+    // can still exist and lastStage may be stale or absent. Prefer activeStage
+    // (current dispatch) over lastStage (could be from a prior cycle).
+    if (lastResult.ok === false) {
+      const failedStage = activeStage || lastStage;
+      if (!failedStage) {
+        return violation('lastResult.ok=false but no stage recorded — orphaned state');
+      }
+      const blockResult = markArtefactBlocked(cycleId, io);
+      if (activeStage) clearActiveStage(io);
+      const art = findCycleOutputArtefact(cycleId, io);
+      const blockNote = blockResult.ok ? '' : ` (also: failed to mark artefact blocked: ${blockResult.error})`;
+      return violation(
+        `subagent dispatch failed: ${lastResult.error || 'unknown error'}${blockNote}`,
+        [art?.file].filter(Boolean)
+      );
+    }
+
+    // Happy path: foundry_stage_end has run, which writes lastStage and clears
+    // activeStage. lastStage is the canonical source of stage identity & baseSha.
+    if (!lastStage) {
+      return violation('lastResult provided but no last stage recorded — orphaned state');
+    }
+
+    let finalizeResult;
+    if (typeof finalize !== 'function') {
+      return violation(
+        'orchestrate caller must inject a `finalize` function when providing lastResult; ' +
+        'the plugin wires lib/finalize.finalizeStage; tests must pass a stub.',
+        []
+      );
+    }
+    finalizeResult = await finalize({
+      cycleId,
+      stage: lastStage.stage,
+      baseSha: lastStage.baseSha,
+      io,
+    });
+
+    if (!finalizeResult.ok) {
+      const blockResult = markArtefactBlocked(cycleId, io);
+      if (activeStage) clearActiveStage(io);
+      const blockNote = blockResult.ok ? '' : ` (also: failed to mark artefact blocked: ${blockResult.error})`;
+      if (finalizeResult.error === 'unexpected_files') {
+        return violation(
+          `unexpected files written by subagent: ${(finalizeResult.files || []).join(', ')}${blockNote}`,
+          finalizeResult.files || []
+        );
+      }
+      return violation(`stage_finalize error: ${finalizeResult.error}${blockNote}`, []);
+    }
+
+    for (const a of finalizeResult.artefacts ?? []) {
+      let wm = io.readFile('WORK.md');
+      const rows = parseArtefactsTable(wm);
+      if (!rows.some(r => r.file === a.file)) {
+        wm = addArtefactRow(wm, {
+          file: a.file,
+          type: a.type,
+          cycle: cycleId,
+          status: a.status ?? 'draft',
+        });
+        io.writeFile('WORK.md', wm);
+      }
+    }
+
+    const summary = lastStage.summary || '(no summary)';
+    const historyPath = 'WORK.history.yaml';
+    const iteration = getIteration(historyPath, cycleId, io);
+
+    appendEntry(historyPath, {
+      cycle: cycleId,
+      stage: 'sort',
+      iteration,
+      route: lastStage.stage,
+      comment: `route ${lastStage.stage}`,
+    }, io);
+    appendEntry(historyPath, {
+      cycle: cycleId,
+      stage: lastStage.stage,
+      iteration,
+      comment: summary,
+    }, io);
+
+    if (git && typeof git.commit === 'function') {
+      git.commit(`[${cycleId}] ${lastStage.stage}: ${summary}`);
+    }
+    // Defensive: stage_end clears activeStage already; this is a no-op in the
+    // normal lifecycle but cleans up if the subagent skipped stage_end.
+    if (activeStage) clearActiveStage(io);
+  }
+
+  const sortResult = runSort(
+    {
+      cycleDef: cycleDefOverride,
+      mint,
+      now: typeof now === 'function' ? now() : now,
+    },
+    io
+  );
+
+  return handleSortResult(sortResult, { cycleId, cwd, io });
+}
+
+// Test-only export; keep underscored to discourage runtime use.
+export { handleSortResult as __handleSortResultForTest };

package/skills/flow/SKILL.md

@@ -2,7 +2,7 @@
 name: flow
 type: composite
 description: Runs a defined foundry flow to produce artefacts. Use this whenever the user references a flow by id, name, or paraphrase (e.g. "use the creative flow", "run creative-flow"). Do not brainstorm — the flow's cycles already define the work. The user's request is the goal to pass in.
-composes: [cycle]
+composes: [orchestrate]
 ---
 
 # Flow
@@ -20,9 +20,10 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 1. Call `foundry_config_flow` with the flow ID — get the flow definition
 2. Call `foundry_git_branch` with the flow ID and a short description — create the work branch
 3. Determine the starting cycle:
-   - If only one starting cycle, use it
-   - If multiple starting cycles, check whether the user's request makes the choice obvious (e.g., "write a haiku" clearly maps to `create-haiku`)
-   - If ambiguous, prompt the user to choose
+   - Any cycle listed in the flow can be the starting cycle. The flow's `starting-cycles` list is a hint for when the user's request is ambiguous.
+   - Map the user's goal to a cycle by matching the requested output (e.g. "write a short story from the tennis haiku" → `create-short-story`; "write a haiku" → `create-haiku`).
+   - If the goal is ambiguous, prompt the user to choose from the flow's cycles, defaulting the recommendation to entries in `starting-cycles`.
+   - A cycle whose `inputs` contract cannot be satisfied from files already on disk should not be chosen as the starting cycle. If no other cycle matches, inform the user which input types are missing and offer to run a cycle that produces them first.
 4. Pre-check for an existing workfile (prevents silent data loss from an aborted prior session):
    a. Call `foundry_workfile_get`.
    b. If it returns `{error: ...}` (no WORK.md), proceed to step 5.
@@ -30,8 +31,8 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
       - **Resume** — keep the existing workfile and skip to step 6. **Only offer resume if the existing `flow` AND `cycle` match what the user just asked for.** If either differs, do not offer resume — running the wrong cycle against stale state corrupts the workflow.
       - **Discard** — call `foundry_workfile_delete`, then proceed to step 5.
       - **Abort** — stop the skill without modifying anything.
-5. Call `foundry_workfile_create` with **only** the flow ID, chosen cycle ID, and goal — do **not** pass `stages` or `maxIterations`. The `cycle` skill will read the cycle definition and populate those via `foundry_workfile_set` in the next step.
-6. Execute the cycle by invoking the cycle skill
+5. Call `foundry_workfile_create` with **only** the flow ID, chosen cycle ID, and goal — do **not** pass `stages` or `maxIterations`. The `orchestrate` skill will read the cycle definition and handle setup on its first call.
+6. Execute the cycle by invoking the orchestrate skill
 
 ## Between cycles
 
@@ -49,9 +50,10 @@ When a cycle completes (sort returns `done`):
    - Check input contracts for each
    - The user chooses which target to pursue (or which to pursue first)
 5. Set up the next cycle:
-   - Call `foundry_workfile_set` with `key: "cycle"`, `value: <next-cycle-id>`
-   - Reset stages and iteration count for the new cycle
-   - Execute the cycle by invoking the cycle skill
+   - Call `foundry_workfile_delete` to clear the completed cycle's WORK.md.
+   - Call `foundry_workfile_create` with **only** the flow ID, the next cycle ID, and the goal — do **not** pass `stages` or `maxIterations`. The orchestrate skill will detect `needsSetup` on its first call and bootstrap the rest of the frontmatter from the cycle definition.
+   - Do **not** register the completed cycle's output as an input to the next cycle. The output file is on disk and the next cycle's forge discovers it through the input type's `file-patterns` — see the forge skill's input-discovery protocol.
+   - Execute the cycle by invoking the orchestrate skill.
 
 ## Completing a flow
 

package/skills/forge/SKILL.md

@@ -30,7 +30,11 @@ Forge runs inside an enforced stage. Your **first** and **last** tool calls are
 3. `foundry_config_cycle` — understand what to produce and what inputs are available.
 4. `foundry_config_artefact_type` with the output type ID — get the artefact type definition, especially its `file-patterns`.
 5. `foundry_config_laws` — get all applicable laws (global + type-specific).
-6. If the cycle has inputs, read the input artefacts (read-only context).
+6. If the cycle declares `inputs`, discover input files by filesystem scan:
+   - For each type listed in `inputs`, call `foundry_config_artefact_type` to get its `file-patterns`.
+   - Glob the working tree against those patterns to enumerate candidate input files.
+   - Read the goal (from `foundry_workfile_get`) and select the files that are relevant to this run. If the goal names specific files or slugs, use those; if it describes a category ("all the auth tests"), select the matching subset; if it's open-ended, you may consume all candidates or ask the user when the set is clearly ambiguous.
+   - 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})`.
@@ -40,16 +44,22 @@ Forge runs inside an enforced stage. Your **first** and **last** tool calls are
 1. `foundry_stage_begin(...)`.
 2. `foundry_feedback_list` — find unresolved feedback for the artefact.
 3. Read the artefact file.
-4. If the cycle has inputs, read the input artefacts (read-only context).
+4. 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).
 5. For each unresolved feedback item, either:
    - Address it and call `foundry_feedback_action` (marks item `actioned`), or
    - Call `foundry_feedback_wontfix` with a justification — available only for `law:` / `human` tags (validation feedback must be actioned).
 6. Update the artefact file.
 7. `foundry_stage_end({summary})`.
 
-## File-pattern hygiene
+## Write invariant
 
-Writes during forge must match the output artefact type's `file-patterns`. Writing to any other path causes `foundry_stage_finalize` to return `{error: 'unexpected_files'}` and the orchestrator will mark the cycle's target artefact `blocked`. You will not get a retry. Plus `WORK.md` and `WORK.history.yaml` (managed by tools). Nothing else.
+Forge may only write to:
+- Files matching the output artefact type's `file-patterns`.
+- `WORK.md` and `WORK.history.yaml` (tool-managed).
+
+Everything else on disk — including files of the cycle's input types, files of unrelated artefact types, and files outside any artefact type — is read-only for this stage. This is not an honor-system rule: `foundry_stage_finalize` returns `{error: 'unexpected_files'}` and `sort`'s `checkModifiedFiles` routes a violation on the next call. Either outcome marks the cycle's target artefact `blocked` and you do not get a retry.
+
+When a cycle's output type overlaps with one of its input types (e.g. a `refine-haiku` cycle with input `haiku` and output `haiku`), the overlap is intentional: the cycle's job is to modify existing files of that type. The write invariant still holds — you may only touch files matching the output type's patterns, which in this case includes the files you read as inputs.
 
 ## Unresolved feedback
 
@@ -75,4 +85,4 @@ Feedback tagged `human` (from the human-appraise stage) takes absolute priority:
 - You do not evaluate or score the artefact.
 - You do not mark feedback as actioned unless you actually changed the artefact to address it.
 - You do not wont-fix validation feedback.
-- You do not modify input artefacts — they are read-only.
+- You do not write to any file outside the output artefact type's `file-patterns` (plus `WORK.md` / `WORK.history.yaml`). Input files are read-only unless the output type's patterns happen to cover them.

package/skills/human-appraise/SKILL.md

@@ -23,6 +23,18 @@ Human-appraise runs inside an enforced stage. Your **first** and **last** tool c
 
 Human-appraise makes **no disk writes**. All output flows through `foundry_feedback_add` / `foundry_feedback_resolve` / `foundry_artefacts_set_status`. `foundry_stage_finalize` flags unexpected writes as a violation.
 
+## Input
+
+When invoked from orchestrate, you receive `{cycle, token, context}`:
+- `cycle` — the current cycle id
+- `token` — single-use token for `foundry_stage_begin`
+- `context.artefact_file` — the target artefact
+- `context.recent_feedback` — recent deadlocked feedback items to present to the user
+
+Your FIRST tool call must be `foundry_stage_begin({stage: 'human-appraise:<cycle>', cycle, token})`.
+
+Your LAST tool call must be `foundry_stage_end({summary: '<one-sentence description of the user verdict>'})` — orchestrate reads this summary for the commit message.
+
 ## Protocol
 
 1. `foundry_stage_begin(...)`.

package/skills/orchestrate/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: orchestrate
+description: Runs a foundry cycle by calling foundry_orchestrate in a loop and acting on the returned action.
+---
+
+# Orchestrate
+
+You drive a foundry cycle by calling `foundry_orchestrate` repeatedly and acting on each returned `action`. The tool owns all step-ordering, history, committing, and routing. Your job is to dispatch subagents, run human-appraise when asked, and report terminal states.
+
+## Prerequisites
+
+Before running this skill, verify that `foundry/` exists in the project root and `WORK.md` has been created by the flow skill (with `flow`, `cycle`, and `goal` fields). If not, stop and tell the user to run the flow skill first.
+
+## Protocol
+
+Loop until `foundry_orchestrate` returns a terminal action (`done`, `blocked`, or `violation`):
+
+1. Call `foundry_orchestrate({lastResult})`. Omit `lastResult` on the first iteration. On subsequent iterations, pass `{kind, ok}` reflecting the previous action's outcome.
+
+2. Switch on the returned `action`:
+
+### `dispatch`
+
+Payload: `{stage, subagent_type, prompt}`.
+
+Call the `task` tool:
+```
+task tool:
+  subagent_type: <subagent_type-from-payload>
+  description: "Run <stage> for <cycle>"
+  prompt: <prompt-from-payload — pass verbatim>
+```
+
+When the task returns, call `foundry_orchestrate({lastResult: {kind: 'dispatch', ok: true}})`. If the task tool itself errored or reported a subagent crash, pass `{kind: 'dispatch', ok: false, error: '<message>'}`.
+
+### `human_appraise`
+
+Payload: `{stage, token, context}`.
+
+Invoke the `human-appraise` skill inline, passing `{cycle, token, context}`. The skill will prompt the user, collect feedback, and call `foundry_stage_end({summary})`.
+
+When it returns, call `foundry_orchestrate({lastResult: {kind: 'human_appraise', ok: true}})`.
+
+### `done`
+
+Payload: `{cycle, artefact_file, next_cycles}`.
+
+1. Call `foundry_artefacts_set_status({file: artefact_file, status: 'done'})`.
+2. Report to the user: "Cycle `<cycle>` complete. Output: `<artefact_file>`. Next cycles available: `<next_cycles>`."
+3. Return control to the flow skill.
+
+### `blocked`
+
+Payload: `{cycle, artefact_file, reason}`.
+
+Report to the user: "Cycle `<cycle>` blocked on `<artefact_file>`: `<reason>`." Return control to the flow skill. The artefact has already been marked blocked.
+
+### `violation`
+
+Payload: `{details, affected_files}`.
+
+Report to the user: "Cycle halted (violation): `<details>`. Affected files: `<affected_files>`." Return control to the flow skill. Affected artefacts have already been marked blocked.
+
+## What you do NOT do
+
+- You do NOT inline forge / quench / appraise work. Always dispatch via `task`.
+- You do NOT mint, modify, or cache tokens. The `prompt` from orchestrate already contains the token verbatim.
+- You do NOT call `foundry_history_append`, `foundry_git_commit`, `foundry_stage_finalize`, or `foundry_sort`. These are not registered tools in v2.3+; orchestrate handles them internally.
+- You do NOT reorder the protocol. `foundry_orchestrate` returns, you act, you call back. Nothing else between.

package/skills/upgrade-foundry/SKILL.md

@@ -130,6 +130,37 @@ For each `foundry/cycles/*.md` whose frontmatter has the old nested form, migrat
 
 The old nested form is no longer read. After migration, verify by asking: "cycle `<id>`: human-appraise every iteration? deadlock-appraise on? deadlock-iterations = N?".
 
+### 4c. v2.2.x → v2.3.0
+
+v2.3.0 replaces the LLM-driven sort orchestrator with the `foundry_orchestrate` plugin tool. The `cycle` and `sort` skills are removed. Six tools are deregistered: `foundry_sort`, `foundry_history_append`, `foundry_stage_finalize`, `foundry_git_commit`, `foundry_workfile_configure_from_cycle`, `foundry_workfile_set`.
+
+#### Pre-flight checks
+
+Before upgrading, verify a clean base state. Abort the upgrade if any of these fail:
+
+1. **Branch**: must be on `main` (or the user's configured default base branch).
+   - Check: `git rev-parse --abbrev-ref HEAD` — must match expected default.
+   - If on `work/*`: abort with "You're on a work branch. Switch to main and complete or discard any in-flight flow before upgrading."
+
+2. **Working tree**: must be clean.
+   - Check: `git status --porcelain` — must be empty.
+   - If dirty: abort with "Uncommitted changes. Commit or stash before upgrading."
+
+3. **In-flight workfile**: `WORK.md` must not exist.
+   - Check: is `WORK.md` present in the repo root?
+   - If yes: abort with "In-flight workfile detected. Delete it (`foundry_workfile_delete`) or complete the cycle before upgrading."
+
+Only when all three pass, proceed with the plugin swap.
+
+#### Upgrade steps
+
+1. Install the new plugin package version: `npm install @really-knows-ai/foundry@2.3.0 --save-dev`.
+2. Swap `.opencode/plugins/foundry.js` with the new version from `node_modules/@really-knows-ai/foundry/.opencode/plugins/foundry.js`.
+3. Remove `skills/cycle/` and `skills/sort/` directories from the project if they exist locally (they shouldn't — skills live in the package).
+4. Commit the upgrade: `chore: upgrade foundry to 2.3.0`.
+
+No state migration is performed. In-flight cycles from v2.2.x must be completed or discarded before upgrading.
+
 ### 5. Migrate flows
 
 For each flow needing migration: