@really-knows-ai/foundry 2.1.0 → 2.2.1

package/.opencode/plugins/foundry.js

@@ -9,10 +9,10 @@
 
 import path from 'path';
 import fs from 'fs';
-import { readFileSync, writeFileSync, existsSync, readdirSync, unlinkSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, readdirSync, unlinkSync, mkdirSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { tool } from '@opencode-ai/plugin';
-import { loadHistory, appendEntry, getIteration } from '../../scripts/lib/history.js';
+import { loadHistory, appendEntry, getIteration, readLastSortRoute } from '../../scripts/lib/history.js';
 import { parseFrontmatter, createWorkfile, setFrontmatterField, getFrontmatterField, enrichStages, parseStagesValue, parseModelsValue } from '../../scripts/lib/workfile.js';
 import { parseArtefactsTable, addArtefactRow, setArtefactStatus } from '../../scripts/lib/artefacts.js';
 import { addFeedbackItem, actionFeedbackItem, wontfixFeedbackItem, resolveFeedbackItem, listFeedback } from '../../scripts/lib/feedback.js';
@@ -20,6 +20,16 @@ import { getCycleDefinition, getArtefactType, getLaws, getValidation, getApprais
 import { slugify } from '../../scripts/lib/slug.js';
 import { runSort } from '../../scripts/sort.js';
 import { execSync, execFileSync } from 'child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { readOrCreateSecret } from '../../scripts/lib/secret.js';
+import { createPendingStore } from '../../scripts/lib/pending.js';
+import { signToken, verifyToken } from '../../scripts/lib/token.js';
+import {
+  ensureFoundryDir, readActiveStage, writeActiveStage, clearActiveStage,
+  readLastStage, writeLastStage,
+} from '../../scripts/lib/state.js';
+import { requireNoActiveStage, requireActiveStage, stageBaseOf } from '../../scripts/lib/stage-guard.js';
+import { finalizeStage } from '../../scripts/lib/finalize.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(__dirname, '../..');
@@ -115,11 +125,21 @@ function makeIO(directory) {
     readFile: (p) => readFileSync(resolve(p), 'utf-8'),
     writeFile: (p, content) => writeFileSync(resolve(p), content, 'utf-8'),
     readDir: (p) => readdirSync(resolve(p)),
+    mkdir: (p) => mkdirSync(resolve(p), { recursive: true }),
+    unlink: (p) => { if (existsSync(resolve(p))) unlinkSync(resolve(p)); },
   };
 }
 
 export const FoundryPlugin = async ({ directory }) => {
-  return {
+  // Bootstrap per-worktree HMAC secret (created on first boot, persisted to .foundry/secret).
+  // Note: `directory` is the worktree root at plugin-boot time. Per-invocation `context.worktree`
+  // may differ in multi-worktree setups — we still use `context.worktree` inside tool `execute`
+  // bodies to locate `.foundry/` on disk, and use the plugin-boot `secret` only for
+  // signing/verifying. A worktree change mid-session would mismatch; deferred out of v2.2.0 scope.
+  const secret = readOrCreateSecret(directory);
+  const pending = createPendingStore();
+
+  const plugin = {
     config: async (config) => {
       config.skills = config.skills || {};
       config.skills.paths = config.skills.paths || [];
@@ -151,12 +171,25 @@ export const FoundryPlugin = async ({ directory }) => {
           cycle: tool.schema.string().describe('Cycle name'),
           stage: tool.schema.string().describe('Stage name'),
           comment: tool.schema.string().describe('Comment for this entry'),
+          route: tool.schema.string().optional().describe('When stage=sort, the stage alias the sort routed to'),
         },
         async execute(args, context) {
           const io = makeIO(context.worktree);
+          const guard = requireNoActiveStage(io);
+          if (!guard.ok) return JSON.stringify({ error: `foundry_history_append ${guard.error}` });
           const historyPath = path.join(context.worktree, 'WORK.history.yaml');
+          // Sort-route alias check: if this entry is NOT a sort, it must match
+          // the most recent sort's `route` for this cycle.
+          if (args.stage !== 'sort') {
+            const expected = readLastSortRoute(historyPath, args.cycle, io);
+            if (args.stage !== expected) {
+              return JSON.stringify({
+                error: `foundry_history_append: stage ${args.stage} does not match last sort route ${expected ?? 'none'}`,
+              });
+            }
+          }
           const iteration = getIteration(historyPath, args.cycle, io);
-          appendEntry(historyPath, { cycle: args.cycle, stage: args.stage, iteration, comment: args.comment }, io);
+          appendEntry(historyPath, { cycle: args.cycle, stage: args.stage, iteration, comment: args.comment, route: args.route }, io);
           return JSON.stringify({ ok: true, iteration });
         },
       }),
@@ -174,6 +207,119 @@ export const FoundryPlugin = async ({ directory }) => {
         },
       }),
 
+      // ── Stage lifecycle tools ──
+      foundry_stage_begin: tool({
+        description: 'Open a subagent work stage; consumes a dispatch token from foundry_sort.',
+        args: {
+          stage: tool.schema.string().describe('Stage alias, e.g. "forge:create-haiku"'),
+          cycle: tool.schema.string().describe('Cycle name'),
+          token: tool.schema.string().describe('Token received from foundry_sort via the dispatch prompt'),
+        },
+        async execute(args, context) {
+          const io = makeIO(context.worktree);
+          // Precondition: no active stage.
+          const current = readActiveStage(io);
+          if (current) {
+            return JSON.stringify({ error: `foundry_stage_begin requires no active stage; current: ${current.stage}` });
+          }
+          // Verify token signature + expiry.
+          const v = verifyToken(args.token, secret);
+          if (!v.ok) return JSON.stringify({ error: `foundry_stage_begin: token ${v.reason}` });
+          // Payload must match args.
+          if (v.payload.route !== args.stage || v.payload.cycle !== args.cycle) {
+            return JSON.stringify({ error: `foundry_stage_begin: token payload mismatch (route=${v.payload.route}, cycle=${v.payload.cycle})` });
+          }
+          // Single-use nonce check.
+          const meta = pending.consume(v.payload.nonce);
+          if (!meta) return JSON.stringify({ error: `foundry_stage_begin: nonce not pending or already consumed` });
+
+          // Resolve base SHA from git.
+          let baseSha;
+          try {
+            baseSha = execSync('git rev-parse HEAD', { cwd: context.worktree }).toString().trim();
+          } catch {
+            return JSON.stringify({ error: `foundry_stage_begin: git rev-parse HEAD failed (no commits?)` });
+          }
+
+          const tokenHash = createHash('sha256').update(args.token).digest('hex');
+          const active = {
+            cycle: args.cycle,
+            stage: args.stage,
+            tokenHash,
+            baseSha,
+            startedAt: new Date().toISOString(),
+          };
+          writeActiveStage(io, active);
+          return JSON.stringify({ ok: true, active });
+        },
+      }),
+
+      foundry_stage_end: tool({
+        description: 'Close the active subagent work stage; preserves baseSha for finalize.',
+        args: {
+          summary: tool.schema.string().describe('Short summary of the work done'),
+        },
+        async execute(args, context) {
+          const io = makeIO(context.worktree);
+          const active = readActiveStage(io);
+          if (!active) return JSON.stringify({ error: 'foundry_stage_end requires active stage; current: none' });
+          writeLastStage(io, { cycle: active.cycle, stage: active.stage, baseSha: active.baseSha, summary: args.summary });
+          clearActiveStage(io);
+          return JSON.stringify({ ok: true, summary: args.summary });
+        },
+      }),
+
+      foundry_stage_finalize: tool({
+        description: 'Verify stage output matches allowed file patterns; register artefacts as drafts.',
+        args: {
+          cycle: tool.schema.string().describe('Cycle name'),
+        },
+        async execute(args, context) {
+          const io = makeIO(context.worktree);
+          const guard = requireNoActiveStage(io);
+          if (!guard.ok) return JSON.stringify({ error: guard.error });
+          const last = readLastStage(io);
+          if (!last) return JSON.stringify({ error: 'foundry_stage_finalize: no last stage recorded; call stage_end first' });
+          if (last.cycle !== args.cycle) {
+            return JSON.stringify({ error: `foundry_stage_finalize: cycle mismatch (last=${last.cycle}, got=${args.cycle})` });
+          }
+
+          // Load on-disk definitions and translate to finalizeStage's camelCase contract.
+          let cycleDoc;
+          try {
+            cycleDoc = await getCycleDefinition('foundry', args.cycle, io);
+          } catch (e) {
+            return JSON.stringify({ error: `foundry_stage_finalize: ${e.message}` });
+          }
+          const outputType = cycleDoc.frontmatter.output;
+          const cycleDef = { outputArtefactType: outputType };
+          const artefactTypes = {};
+          if (outputType) {
+            try {
+              const artDoc = await getArtefactType('foundry', outputType, io);
+              artefactTypes[outputType] = { filePatterns: artDoc.frontmatter['file-patterns'] || [] };
+            } catch {
+              artefactTypes[outputType] = { filePatterns: [] };
+            }
+          }
+
+          const workPath = path.join(context.worktree, 'WORK.md');
+          const result = finalizeStage({
+            cwd: context.worktree,
+            baseSha: last.baseSha,
+            stageBase: stageBaseOf(last.stage),
+            cycleDef,
+            artefactTypes,
+            registerArtefact: ({ file, type, status }) => {
+              const text = readFileSync(workPath, 'utf-8');
+              const updated = addArtefactRow(text, { file, type, cycle: args.cycle, status });
+              writeFileSync(workPath, updated, 'utf-8');
+            },
+          });
+          return JSON.stringify(result);
+        },
+      }),
+
       // ── Workfile tools ──
       foundry_workfile_create: tool({
         description: 'Create WORK.md with frontmatter and goal',
@@ -186,16 +332,19 @@ export const FoundryPlugin = async ({ directory }) => {
           models: tool.schema.string().optional().describe('Per-stage model overrides as JSON object, e.g. \'{"forge":"openai/gpt-4o"}\''),
         },
         async execute(args, context) {
+          const io = makeIO(context.worktree);
+          const guard = requireNoActiveStage(io);
+          if (!guard.ok) return JSON.stringify({ error: `foundry_workfile_create ${guard.error}` });
           const workPath = path.join(context.worktree, 'WORK.md');
           if (existsSync(workPath)) {
-            return JSON.stringify({ error: 'WORK.md already exists' });
+            return JSON.stringify({ error: 'foundry_workfile_create requires no WORK.md; current: exists' });
           }
           const fm = { flow: args.flow, cycle: args.cycle };
           if (args.stages) {
             fm.stages = enrichStages(args.stages, args.cycle);
           }
           if (args.maxIterations !== undefined) {
-            fm.maxIterations = args.maxIterations;
+            fm['max-iterations'] = args.maxIterations;
           }
           if (args.models) {
             fm.models = parseModelsValue(args.models);
@@ -225,10 +374,17 @@ export const FoundryPlugin = async ({ directory }) => {
       foundry_workfile_set: tool({
         description: 'Update a single frontmatter field in WORK.md',
         args: {
-          key: tool.schema.string().describe('Frontmatter key'),
+          key: tool.schema.string().describe('Frontmatter key (cycle|stages|max-iterations|models)'),
           value: tool.schema.string().describe('Value to set (use JSON for arrays/objects, e.g. \'["forge:a","quench:b"]\' or \'{"forge":"openai/gpt-4o"}\')'),
         },
         async execute(args, context) {
+          const io = makeIO(context.worktree);
+          const guard = requireNoActiveStage(io);
+          if (!guard.ok) return JSON.stringify({ error: `foundry_workfile_set ${guard.error}` });
+          const ALLOWED_KEYS = new Set(['cycle', 'stages', 'max-iterations', 'maxIterations', 'models', 'human-appraise', 'deadlock-appraise', 'deadlock-iterations']);
+          if (!ALLOWED_KEYS.has(args.key)) {
+            return JSON.stringify({ error: `foundry_workfile_set: key must be one of cycle|stages|max-iterations|models; got ${args.key}` });
+          }
           const workPath = path.join(context.worktree, 'WORK.md');
           if (!existsSync(workPath)) {
             return JSON.stringify({ error: 'WORK.md not found' });
@@ -265,10 +421,78 @@ export const FoundryPlugin = async ({ directory }) => {
         },
       }),
 
+      foundry_workfile_configure_from_cycle: tool({
+        description: 'Populate WORK.md frontmatter from a cycle definition in one pass. Reads the cycle def for max-iterations, human-appraise, deadlock-appraise, deadlock-iterations, and models; applies defaults for anything missing. Caller must supply the synthesized stages list (the skill owns stage synthesis).',
+        args: {
+          cycleId: tool.schema.string().describe('Cycle ID — used to locate foundry/cycles/<cycleId>.md'),
+          stages: tool.schema.array(tool.schema.string()).describe('Ordered stage aliases (bare names will be enriched with :<cycleId>)'),
+        },
+        async execute(args, context) {
+          const io = makeIO(context.worktree);
+          const guard = requireNoActiveStage(io);
+          if (!guard.ok) return JSON.stringify({ error: `foundry_workfile_configure_from_cycle ${guard.error}` });
+
+          const workPath = path.join(context.worktree, 'WORK.md');
+          if (!existsSync(workPath)) {
+            return JSON.stringify({ error: 'WORK.md not found' });
+          }
+
+          let cycleDoc;
+          try {
+            cycleDoc = await getCycleDefinition('foundry', args.cycleId, io);
+          } catch (e) {
+            return JSON.stringify({ error: `foundry_workfile_configure_from_cycle: ${e.message}` });
+          }
+          const fm = cycleDoc.frontmatter || {};
+
+          const stages = enrichStages(args.stages, args.cycleId);
+
+          // Apply defaults for each cycle-def-backed field.
+          const maxIterations = fm['max-iterations'] ?? 3;
+          const humanAppraise = fm['human-appraise'] === true;
+          const deadlockAppraise = fm['deadlock-appraise'] !== false; // default true
+          const deadlockIterations = fm['deadlock-iterations'] ?? 5;
+          const models = fm.models ?? null;
+
+          let text = readFileSync(workPath, 'utf-8');
+          text = setFrontmatterField(text, 'cycle', args.cycleId);
+          text = setFrontmatterField(text, 'stages', stages);
+          text = setFrontmatterField(text, 'max-iterations', maxIterations);
+          text = setFrontmatterField(text, 'human-appraise', humanAppraise);
+          text = setFrontmatterField(text, 'deadlock-appraise', deadlockAppraise);
+          text = setFrontmatterField(text, 'deadlock-iterations', deadlockIterations);
+          if (models && typeof models === 'object' && Object.keys(models).length > 0) {
+            text = setFrontmatterField(text, 'models', models);
+          }
+          writeFileSync(workPath, text, 'utf-8');
+
+          return JSON.stringify({
+            ok: true,
+            applied: {
+              cycle: args.cycleId,
+              stages,
+              'max-iterations': maxIterations,
+              'human-appraise': humanAppraise,
+              'deadlock-appraise': deadlockAppraise,
+              'deadlock-iterations': deadlockIterations,
+              ...(models ? { models } : {}),
+            },
+          });
+        },
+      }),
+
       foundry_workfile_delete: tool({
-        description: 'Delete WORK.md and WORK.history.yaml',
-        args: {},
-        async execute(_args, context) {
+        description: 'Delete WORK.md and WORK.history.yaml (requires confirm:true)',
+        args: {
+          confirm: tool.schema.boolean().describe('Must be true to confirm deletion'),
+        },
+        async execute(args, context) {
+          const io = makeIO(context.worktree);
+          const guard = requireNoActiveStage(io);
+          if (!guard.ok) return JSON.stringify({ error: `foundry_workfile_delete ${guard.error}` });
+          if (args.confirm !== true) {
+            return JSON.stringify({ error: 'foundry_workfile_delete requires {confirm: true}' });
+          }
           const workPath = path.join(context.worktree, 'WORK.md');
           const historyPath = path.join(context.worktree, 'WORK.history.yaml');
           if (existsSync(workPath)) {
@@ -282,48 +506,45 @@ export const FoundryPlugin = async ({ directory }) => {
       }),
 
       // ── Artefacts tools ──
-      foundry_artefacts_add: tool({
-        description: 'Add an artefact row to the WORK.md table',
+      // NOTE: `foundry_artefacts_add` was removed in v2.2.0. Artefacts are now
+      // registered automatically by `foundry_stage_finalize` as drafts, then
+      // promoted to done|blocked via `foundry_artefacts_set_status`.
+      foundry_artefacts_set_status: tool({
+        description: 'Update the status of an artefact in WORK.md (done|blocked only)',
         args: {
           file: tool.schema.string().describe('Artefact file path'),
-          type: tool.schema.string().describe('Artefact type'),
-          cycle: tool.schema.string().describe('Cycle name'),
-          status: tool.schema.string().optional().describe('Status (default: draft)'),
+          status: tool.schema.string().describe('New status (done|blocked)'),
         },
         async execute(args, context) {
+          const io = makeIO(context.worktree);
+          const guard = requireNoActiveStage(io);
+          if (!guard.ok) return JSON.stringify({ error: `foundry_artefacts_set_status ${guard.error}` });
           const workPath = path.join(context.worktree, 'WORK.md');
           const text = readFileSync(workPath, 'utf-8');
-          const updated = addArtefactRow(text, { file: args.file, type: args.type, cycle: args.cycle, status: args.status || 'draft' });
-          writeFileSync(workPath, updated, 'utf-8');
-          return JSON.stringify({ ok: true });
+          try {
+            const updated = setArtefactStatus(text, args.file, args.status);
+            writeFileSync(workPath, updated, 'utf-8');
+            return JSON.stringify({ ok: true });
+          } catch (e) {
+            return JSON.stringify({ error: e.message });
+          }
         },
       }),
 
-      foundry_artefacts_set_status: tool({
-        description: 'Update the status of an artefact in WORK.md',
+      foundry_artefacts_list: tool({
+        description: 'List artefacts from the WORK.md table. Optionally filter by cycle — callers should always pass the current cycle to avoid picking up stale rows from prior sessions.',
         args: {
-          file: tool.schema.string().describe('Artefact file path'),
-          status: tool.schema.string().describe('New status'),
+          cycle: tool.schema.string().optional().describe('Only return rows whose Cycle column matches this value'),
         },
         async execute(args, context) {
-          const workPath = path.join(context.worktree, 'WORK.md');
-          const text = readFileSync(workPath, 'utf-8');
-          const updated = setArtefactStatus(text, args.file, args.status);
-          writeFileSync(workPath, updated, 'utf-8');
-          return JSON.stringify({ ok: true });
-        },
-      }),
-
-      foundry_artefacts_list: tool({
-        description: 'List all artefacts from the WORK.md table',
-        args: {},
-        async execute(_args, context) {
           const workPath = path.join(context.worktree, 'WORK.md');
           if (!existsSync(workPath)) {
             return JSON.stringify({ error: 'WORK.md not found' });
           }
           const text = readFileSync(workPath, 'utf-8');
-          return JSON.stringify(parseArtefactsTable(text));
+          const rows = parseArtefactsTable(text);
+          const filtered = args.cycle ? rows.filter(r => r.cycle === args.cycle) : rows;
+          return JSON.stringify(filtered);
         },
       }),
 
@@ -336,11 +557,28 @@ export const FoundryPlugin = async ({ directory }) => {
           tag: tool.schema.string().describe('Tag for the feedback item'),
         },
         async execute(args, context) {
+          const io = makeIO(context.worktree);
+          const guard = requireActiveStage(io);
+          if (!guard.ok) return JSON.stringify({ error: `foundry_feedback_add requires active stage; ${guard.error}` });
+          const stageBase = stageBaseOf(guard.active.stage);
+          // Per-stage tag allow-list.
+          if (stageBase === 'forge') {
+            return JSON.stringify({ error: 'foundry_feedback_add: forge stages do not add feedback' });
+          }
+          if (stageBase === 'quench' && args.tag !== 'validation') {
+            return JSON.stringify({ error: `foundry_feedback_add: quench may only add tag "validation"; got "${args.tag}"` });
+          }
+          if (stageBase === 'appraise' && !args.tag.startsWith('law:')) {
+            return JSON.stringify({ error: `foundry_feedback_add: appraise tag must start with "law:"; got "${args.tag}"` });
+          }
+          if (stageBase === 'human-appraise' && args.tag !== 'human') {
+            return JSON.stringify({ error: `foundry_feedback_add: human-appraise may only add tag "human"; got "${args.tag}"` });
+          }
           const workPath = path.join(context.worktree, 'WORK.md');
           const content = readFileSync(workPath, 'utf-8');
-          const updated = addFeedbackItem(content, args.file, args.text, args.tag);
-          writeFileSync(workPath, updated, 'utf-8');
-          return JSON.stringify({ ok: true });
+          const r = addFeedbackItem(content, args.file, args.text, args.tag);
+          if (!r.deduped) writeFileSync(workPath, r.text, 'utf-8');
+          return JSON.stringify({ ok: true, deduped: r.deduped });
         },
       }),
 
@@ -351,10 +589,18 @@ export const FoundryPlugin = async ({ directory }) => {
           index: tool.schema.number().describe('Zero-based index of the feedback item'),
         },
         async execute(args, context) {
+          const io = makeIO(context.worktree);
+          const guard = requireActiveStage(io);
+          if (!guard.ok) return JSON.stringify({ error: `foundry_feedback_action requires active stage; ${guard.error}` });
+          const stageBase = stageBaseOf(guard.active.stage);
+          if (stageBase !== 'forge') {
+            return JSON.stringify({ error: `foundry_feedback_action requires active forge stage; current: ${guard.active.stage}` });
+          }
           const workPath = path.join(context.worktree, 'WORK.md');
           const content = readFileSync(workPath, 'utf-8');
-          const updated = actionFeedbackItem(content, args.file, args.index);
-          writeFileSync(workPath, updated, 'utf-8');
+          const r = actionFeedbackItem(content, args.file, args.index, stageBase);
+          if (!r.ok) return JSON.stringify({ error: r.error });
+          writeFileSync(workPath, r.text, 'utf-8');
           return JSON.stringify({ ok: true });
         },
       }),
@@ -367,10 +613,18 @@ export const FoundryPlugin = async ({ directory }) => {
           reason: tool.schema.string().describe('Reason for wont-fix'),
         },
         async execute(args, context) {
+          const io = makeIO(context.worktree);
+          const guard = requireActiveStage(io);
+          if (!guard.ok) return JSON.stringify({ error: `foundry_feedback_wontfix requires active stage; ${guard.error}` });
+          const stageBase = stageBaseOf(guard.active.stage);
+          if (stageBase !== 'forge') {
+            return JSON.stringify({ error: `foundry_feedback_wontfix requires active forge stage; current: ${guard.active.stage}` });
+          }
           const workPath = path.join(context.worktree, 'WORK.md');
           const content = readFileSync(workPath, 'utf-8');
-          const updated = wontfixFeedbackItem(content, args.file, args.index, args.reason);
-          writeFileSync(workPath, updated, 'utf-8');
+          const r = wontfixFeedbackItem(content, args.file, args.index, args.reason, stageBase);
+          if (!r.ok) return JSON.stringify({ error: r.error });
+          writeFileSync(workPath, r.text, 'utf-8');
           return JSON.stringify({ ok: true });
         },
       }),
@@ -384,10 +638,18 @@ export const FoundryPlugin = async ({ directory }) => {
           reason: tool.schema.string().optional().describe('Reason (required if rejected)'),
         },
         async execute(args, context) {
+          const io = makeIO(context.worktree);
+          const guard = requireActiveStage(io);
+          if (!guard.ok) return JSON.stringify({ error: `foundry_feedback_resolve requires active stage; ${guard.error}` });
+          const stageBase = stageBaseOf(guard.active.stage);
+          if (!['quench', 'appraise', 'human-appraise'].includes(stageBase)) {
+            return JSON.stringify({ error: `foundry_feedback_resolve requires active quench|appraise|human-appraise stage; current: ${guard.active.stage}` });
+          }
           const workPath = path.join(context.worktree, 'WORK.md');
           const content = readFileSync(workPath, 'utf-8');
-          const updated = resolveFeedbackItem(content, args.file, args.index, args.resolution, args.reason);
-          writeFileSync(workPath, updated, 'utf-8');
+          const r = resolveFeedbackItem(content, args.file, args.index, args.resolution, args.reason, stageBase);
+          if (!r.ok) return JSON.stringify({ error: r.error });
+          writeFileSync(workPath, r.text, 'utf-8');
           return JSON.stringify({ ok: true });
         },
       }),
@@ -412,13 +674,21 @@ export const FoundryPlugin = async ({ directory }) => {
 
       // ── Sort tool ──
       foundry_sort: tool({
-        description: 'Run sort routing to determine the next stage',
+        description: 'Determine the next stage for the current cycle and (if dispatchable) mint a single-use token.',
         args: {
           cycleDef: tool.schema.string().optional().describe('Path to cycle definition file'),
         },
         async execute(args, context) {
           const io = makeIO(context.worktree);
-          const result = runSort({ cycleDef: args.cycleDef }, io);
+          const guard = requireNoActiveStage(io);
+          if (!guard.ok) return JSON.stringify({ error: `foundry_sort ${guard.error}` });
+          const mint = ({ route, cycle, exp }) => {
+            const nonce = randomUUID();
+            const payload = { route, cycle, nonce, exp };
+            pending.add(nonce, payload);
+            return signToken(payload, secret);
+          };
+          const result = runSort({ cycleDef: args.cycleDef, mint }, io);
           return JSON.stringify(result);
         },
       }),
@@ -431,6 +701,9 @@ export const FoundryPlugin = async ({ directory }) => {
           description: tool.schema.string().describe('Branch description suffix'),
         },
         async execute(args, context) {
+          const io = makeIO(context.worktree);
+          const guard = requireNoActiveStage(io);
+          if (!guard.ok) return JSON.stringify({ error: `foundry_git_branch ${guard.error}` });
           const flowSlug = slugify(args.flowId);
           const descSlug = slugify(args.description);
           const branch = `work/${flowSlug}-${descSlug}`;
@@ -447,6 +720,9 @@ export const FoundryPlugin = async ({ directory }) => {
           description: tool.schema.string().describe('Commit description'),
         },
         async execute(args, context) {
+          const io = makeIO(context.worktree);
+          const guard = requireNoActiveStage(io);
+          if (!guard.ok) return JSON.stringify({ error: `foundry_git_commit ${guard.error}` });
           execSync('git add .', { cwd: context.worktree, encoding: 'utf8' });
           const msg = `[${args.cycle}] ${args.stage}: ${args.description}`;
           execSync(`git commit -m "${msg.replace(/"/g, '\\"')}"`, { cwd: context.worktree, encoding: 'utf8' });
@@ -462,6 +738,9 @@ export const FoundryPlugin = async ({ directory }) => {
           baseBranch: tool.schema.string().optional().describe('Target branch (default: main)'),
         },
         async execute(args, context) {
+          const io = makeIO(context.worktree);
+          const guard = requireNoActiveStage(io);
+          if (!guard.ok) return JSON.stringify({ error: `foundry_git_finish ${guard.error}` });
           const base = args.baseBranch || 'main';
           const cwd = context.worktree;
           const opts = { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] };
@@ -617,4 +896,8 @@ export const FoundryPlugin = async ({ directory }) => {
       }),
     },
   };
+
+  Object.defineProperty(plugin, Symbol.for('foundry.test.pending'), { value: pending });
+  Object.defineProperty(plugin, Symbol.for('foundry.test.secret'), { value: secret });
+  return plugin;
 };

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+## 2.2.1 — 2026-04-20
+
+Follow-up patch addressing the five bugs deferred from v2.2.0 (see `HARDEN.md` §Deferred).
+
+### Breaking changes
+
+- **Cycle-definition deadlock config flattened.** The nested `human-appraise: {enabled, deadlock-threshold}` block is replaced by three flat keys:
+  - `human-appraise: <bool>` (default `false`) — include `human-appraise` in the stage loop every iteration
+  - `deadlock-appraise: <bool>` (default `true`) — route to `human-appraise` when LLM appraisers deadlock
+  - `deadlock-iterations: <number>` (default `5`) — deadlock threshold
+  Run the `upgrade-foundry` skill to migrate existing cycle defs — the old nested form is no longer read.
+
+### New
+
+- **`foundry_workfile_configure_from_cycle({cycleId, stages})`** — populates WORK.md frontmatter from a cycle definition in one call. Replaces the prior 6–7 sequential `foundry_workfile_set` calls at cycle start. Defaults for `max-iterations`, `human-appraise`, `deadlock-appraise`, `deadlock-iterations`, and `models` now live in plugin code rather than skill prose.
+- **`foundry_artefacts_list({cycle})`** — optional cycle filter. Callers should always pass the current cycle to avoid picking up stale rows from prior aborted sessions.
+
+### Fixed
+
+- **Bug B — deadlock routing.** Sort now reads the flat deadlock keys from WORK.md frontmatter and routes to `human-appraise` on deadlock (either an existing `human-appraise:<cycle>` stage in `stages`, or a synthesized one). When `deadlock-appraise: false`, deadlock marks the cycle `blocked`.
+- **Bug C — stale artefact validation.** `quench`, `appraise`, and `human-appraise` skills now pass the current cycle to `foundry_artefacts_list`, scoping validation to artefacts produced by the current cycle instead of every row that has ever landed in WORK.md.
+- **Bug D — overwriting WORK.md.** The `flow` skill now calls `foundry_workfile_get` before `foundry_workfile_create` and prompts the user to resume, discard, or abort when an existing workfile is detected. Silent overwrite is not offered; resume requires matching `flow` and `cycle`.
+- **Bug E — missing micro-commits.** `foundry_sort` now returns `{route: 'violation'}` when `WORK.md`, `WORK.history.yaml`, or anything under `.foundry/` has uncommitted changes at the start of a sort call and history is non-empty. Structurally enforces the one-commit-per-stage contract that previously lived only in skill prose. First sort of a cycle is exempt (empty history).
+- **Bug G — workfile setup boilerplate.** See `foundry_workfile_configure_from_cycle` above.
+
+### Migration
+
+Run the `upgrade-foundry` skill to migrate cycle definitions to the flat deadlock keys (Bug B). No other migration required — WORK.md, `.foundry/`, and feedback state are forward-compatible.
+
+## 2.2.0 — 2026-04-19
+
+### Breaking changes
+
+- **`foundry_artefacts_add` removed.** Artefact registration now happens exclusively via `foundry_stage_finalize` after a forge stage closes.
+- **`foundry_artefacts_set_status` no longer accepts `draft`.** Only `done` and `blocked` are valid. New artefacts are registered as `draft` automatically by `stage_finalize`.
+- **Feedback / artefact / workfile mutation tools now enforce stage-lock preconditions.** Tools callable by subagents require an active stage matching their role; tools callable by the orchestrator require no active stage. Out-of-band calls return a structured error instead of mutating state.
+- **Feedback state machine strictly enforced.** `approved` is terminal. `quench` cannot approve/reject `wont-fix` items. See `HARDEN.md` §4 for the full matrix.
+- **`foundry_sort` dispatchable routes now return a `token` field.** Subagents must redeem the token via `foundry_stage_begin`; forged or replayed tokens are rejected.
+
+### New
+
+- **`foundry_stage_begin(stage, cycle, token)`** — subagents open a work stage by consuming a single-use HMAC-signed token.
+- **`foundry_stage_end(summary)`** — subagents close a stage; preserves `baseSha` for finalize.
+- **`foundry_stage_finalize(cycle)`** — orchestrator verifies stage output against allowed file patterns, registers matching files as draft artefacts, rejects stray writes with `{error: "unexpected_files", files: [...]}`.
+- **`.foundry/` state directory** (gitignored) — holds `.secret` (per-worktree HMAC key, mode 0600), `active-stage.json` (present only during an active stage), `last-stage.json` (for finalize lookup).
+
+### Fixed
+
+- Normalized `maxIterations` → `max-iterations` across workfile read/write paths (previously inconsistent between flow and cycle skills, causing latent deadlock-detection issues).
+
+### Migration
+
+Upgrade with the `upgrade-foundry` skill. `.foundry/` is created automatically on first plugin boot; `.secret` is generated idempotently. No data migration required — existing `WORK.md` and `foundry/*` configs are compatible.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@really-knows-ai/foundry",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "A structured framework for AI-driven artefact creation with deterministic routing, quality gates, and iterative refinement cycles.",
   "type": "module",
   "main": ".opencode/plugins/foundry.js",
@@ -40,6 +40,7 @@
     "docs/concepts.md",
     "docs/getting-started.md",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ]
 }

package/scripts/lib/artefacts.js

@@ -86,6 +86,12 @@ export function addArtefactRow(text, { file, type, cycle, status }) {
  * @returns {string} Updated text
  */
 export function setArtefactStatus(text, file, newStatus) {
+  if (newStatus === 'draft') {
+    throw new Error('status draft not permitted; use stage_finalize for registration');
+  }
+  if (!['done', 'blocked'].includes(newStatus)) {
+    throw new Error(`invalid status: ${newStatus}`);
+  }
   const lines = text.split('\n');
   let inTable = false;
   let found = false;

package/scripts/lib/feedback-transitions.js

@@ -0,0 +1,25 @@
+import { createHash } from 'node:crypto';
+
+// Matrix: [current][target] => set of allowed stageBases
+const MATRIX = {
+  open:       { actioned: ['forge'], 'wont-fix': ['forge'] },
+  actioned:   { approved: ['quench', 'appraise', 'human-appraise'], rejected: ['quench', 'appraise', 'human-appraise'] },
+  'wont-fix': { approved: ['appraise', 'human-appraise'], rejected: ['appraise', 'human-appraise'] },
+  rejected:   { actioned: ['forge'], 'wont-fix': ['forge'] },
+  approved:   {}, // terminal
+};
+
+export function validateTransition(current, target, stageBase) {
+  const row = MATRIX[current];
+  if (!row) return { ok: false, reason: `unknown state: ${current}` };
+  const allowedStages = row[target];
+  if (!allowedStages) return { ok: false, reason: `invalid transition ${current} → ${target}` };
+  if (!allowedStages.includes(stageBase)) {
+    return { ok: false, reason: `stage ${stageBase} cannot transition ${current} → ${target}` };
+  }
+  return { ok: true };
+}
+
+export function hashText(text) {
+  return createHash('sha256').update(text).digest('hex').slice(0, 16);
+}