@really-knows-ai/foundry 2.3.2 → 3.0.1

package/.opencode/plugins/foundry.js

@@ -1,761 +0,0 @@
-/**
- * Foundry plugin for OpenCode.ai
- *
- * All skills are always registered. Individual skills check for foundry/ dir.
- * - If foundry/ exists: pipeline context injected into first message
- * - If foundry/ does not exist: minimal prompt guiding user to init-foundry
- * Multi-model agents are managed as .opencode/agents/foundry-*.md files via the refresh-agents skill.
- */
-
-import path from 'path';
-import fs from 'fs';
-import { readFileSync, writeFileSync, existsSync, readdirSync, unlinkSync, mkdirSync } from 'fs';
-import { fileURLToPath } from 'url';
-import { tool } from '@opencode-ai/plugin';
-import { loadHistory } from '../../scripts/lib/history.js';
-import { parseFrontmatter, createWorkfile, enrichStages, 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';
-import { getCycleDefinition, getArtefactType, getLaws, getValidation, getAppraisers, getFlow, selectAppraisers } from '../../scripts/lib/config.js';
-import { slugify } from '../../scripts/lib/slug.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, '../..');
-const allSkillsDir = path.join(packageRoot, 'skills');
-
-function listFlows(foundryDir) {
-  const flowsDir = path.join(foundryDir, 'flows');
-  if (!fs.existsSync(flowsDir)) return [];
-  const flows = [];
-  for (const entry of readdirSync(flowsDir)) {
-    if (!entry.endsWith('.md') || entry === '.gitkeep') continue;
-    try {
-      const text = readFileSync(path.join(flowsDir, entry), 'utf-8');
-      const fmMatch = text.match(/^---\n([\s\S]*?)\n---/);
-      if (!fmMatch) continue;
-      const fm = fmMatch[1];
-      const idMatch = fm.match(/^id:\s*(.+)$/m);
-      const nameMatch = fm.match(/^name:\s*(.+)$/m);
-      const startingMatch = fm.match(/^starting-cycles:\s*\n((?:\s*-\s*.+\n?)+)/m);
-      const id = idMatch ? idMatch[1].trim() : entry.replace(/\.md$/, '');
-      const name = nameMatch ? nameMatch[1].trim() : id;
-      const startingCycles = startingMatch
-        ? startingMatch[1].split('\n').map(l => l.replace(/^\s*-\s*/, '').trim()).filter(Boolean)
-        : [];
-      flows.push({ id, name, startingCycles });
-    } catch { /* skip bad files */ }
-  }
-  return flows;
-}
-
-function getBootstrapContent(directory) {
-  const foundryDir = path.join(directory, 'foundry');
-  const foundryExists = fs.existsSync(foundryDir) && fs.statSync(foundryDir).isDirectory();
-
-  if (!foundryExists) {
-    return `<FOUNDRY_CONTEXT>
-Foundry is installed but not initialized in this project. There is no foundry/ directory.
-
-To set up Foundry, use the \`init-foundry\` skill. This will create the foundry/ directory structure
-and guide you through defining artefact types, laws, appraisers, cycles, and flows.
-</FOUNDRY_CONTEXT>`;
-  }
-
-  const flows = listFlows(foundryDir);
-  const flowList = flows.length > 0
-    ? flows.map(f => {
-        const sc = f.startingCycles.length > 0 ? ` — starting cycles: ${f.startingCycles.join(', ')}` : '';
-        return `- \`${f.id}\` — ${f.name}${sc}`;
-      }).join('\n')
-    : '- (no flows defined yet — use the `add-flow` skill to create one)';
-
-  return `<FOUNDRY_CONTEXT>
-Foundry is active in this project. The foundry/ directory contains the project's artefact definitions,
-laws, appraisers, cycles, and flows.
-
-Foundry is a skill-driven framework for governed artefact generation and evaluation.
-The pipeline: forge (produce) → quench (deterministic checks) → appraise (subjective evaluation) → iterate.
-
-## Defined flows
-
-${flowList}
-
-**CRITICAL ROUTING RULE:** When the user references any flow above — by id (e.g. "creative-flow"),
-by name (e.g. "Creative Flow"), or by clear paraphrase (e.g. "the creative flow", "use the creative pipeline") —
-invoke the \`flow\` skill DIRECTLY with that flow's id. Do NOT invoke brainstorming, do NOT explore the
-codebase, do NOT ask clarifying questions about what to build. The flow's cycles already define the
-work. The user's request text (e.g. "make a haiku about X") is the goal to pass to the flow.
-
-Brainstorming applies to NEW features being added to foundry itself (new cycles, new artefact types,
-new skills). It does NOT apply to running an existing, defined flow.
-
-## Available skills
-
-- **Pipeline:** forge, quench, appraise, orchestrate, flow, human-appraise
-- **Authoring:** add-artefact-type, add-law, add-appraiser, add-cycle, add-flow, init-foundry
-- **Maintenance:** upgrade-foundry, refresh-agents, list-agents
-
-## Multi-model routing
-
-Foundry uses \`foundry-*\` sub-agents defined as markdown files in \`.opencode/agents/\`.
-Run the \`refresh-agents\` skill to regenerate them after adding or removing providers.
-Cycle definitions can specify per-stage models via the \`models\` frontmatter map. Appraisers can override with their own \`model\` field.
-
-All user content lives under foundry/.
-Scripts are located at: ${path.join(packageRoot, 'scripts')}
-</FOUNDRY_CONTEXT>`;
-}
-
-function makeIO(directory) {
-  const resolve = (p) => path.isAbsolute(p) ? p : path.join(directory, p);
-  return {
-    exists: (p) => existsSync(resolve(p)),
-    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)); },
-    // exec: run a shell command in the worktree and return stdout as a UTF-8 string.
-    // Used by sort.js (getDirtyToolManagedFiles, getModifiedFiles) for git enforcement.
-    // Call sites pass full shell strings (e.g. 'git status --porcelain ...'), so we
-    // must use execSync rather than execFileSync. Throws on non-zero exit; callers
-    // already wrap in try/catch.
-    exec: (cmd) => execSync(cmd, { cwd: directory, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }),
-  };
-}
-
-export const FoundryPlugin = async ({ directory }) => {
-  // 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 || [];
-
-      // Always register all skills — individual skills check for foundry/ dir
-      if (!config.skills.paths.includes(allSkillsDir)) {
-        config.skills.paths.push(allSkillsDir);
-      }
-    },
-
-    'experimental.chat.messages.transform': async (_input, output) => {
-      const bootstrap = getBootstrapContent(directory);
-      if (!bootstrap || !output.messages.length) return;
-
-      const firstUser = output.messages.find(m => m.info.role === 'user');
-      if (!firstUser || !firstUser.parts.length) return;
-
-      if (firstUser.parts.some(p => p.type === 'text' && p.text.includes('FOUNDRY_CONTEXT'))) return;
-
-      const ref = firstUser.parts[0];
-      firstUser.parts.unshift({ ...ref, type: 'text', text: bootstrap });
-    },
-
-    tool: {
-      // ── History tools ──
-      foundry_history_list: tool({
-        description: 'List history entries for a cycle',
-        args: {
-          cycle: tool.schema.string().describe('Cycle name'),
-        },
-        async execute(args, context) {
-          const io = makeIO(context.worktree);
-          const historyPath = path.join(context.worktree, 'WORK.history.yaml');
-          const entries = loadHistory(historyPath, args.cycle, io);
-          return JSON.stringify(entries);
-        },
-      }),
-
-      // ── 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 });
-        },
-      }),
-
-      // ── Workfile tools ──
-      foundry_workfile_create: tool({
-        description: 'Create WORK.md with frontmatter and goal',
-        args: {
-          flow: tool.schema.string().describe('Flow name'),
-          cycle: tool.schema.string().describe('Cycle name'),
-          stages: tool.schema.array(tool.schema.string()).optional().describe('Ordered stage names'),
-          maxIterations: tool.schema.number().optional().describe('Maximum iterations'),
-          goal: tool.schema.string().describe('Goal text'),
-          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: '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['max-iterations'] = args.maxIterations;
-          }
-          if (args.models) {
-            fm.models = parseModelsValue(args.models);
-          }
-          const content = createWorkfile(fm, args.goal);
-          writeFileSync(workPath, content, 'utf-8');
-          return JSON.stringify({ ok: true });
-        },
-      }),
-
-      foundry_workfile_get: tool({
-        description: 'Read WORK.md and return frontmatter + goal',
-        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');
-          const fm = parseFrontmatter(text);
-          const goalMatch = text.match(/# Goal\n\n([\s\S]*?)(?=\n\||\n##|$)/);
-          const goal = goalMatch ? goalMatch[1].trim() : '';
-          return JSON.stringify({ ...fm, goal });
-        },
-      }),
-
-      foundry_workfile_delete: tool({
-        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)) {
-            unlinkSync(workPath);
-          }
-          if (existsSync(historyPath)) {
-            unlinkSync(historyPath);
-          }
-          return JSON.stringify({ ok: true });
-        },
-      }),
-
-      // ── Orchestrate tool ──
-      foundry_orchestrate: tool({
-        description: 'Run the next step of the current cycle. Call with no args on first invocation; call with lastResult={ok,error?} after a dispatch/human_appraise completes. Returns {action, ...} describing what the caller should do next.',
-        args: {
-          lastResult: tool.schema.object({
-            ok: tool.schema.boolean(),
-            error: tool.schema.string().optional(),
-          }).optional(),
-          cycleDef: tool.schema.string().optional().describe('Test-mode cycle definition override (path to cycle file)'),
-        },
-        async execute(args, context) {
-          const { runOrchestrate } = await import('../../scripts/orchestrate.js');
-          const io = makeIO(context.worktree);
-          const cwd = context.worktree;
-
-          // Mint: same pattern as removed foundry_sort.
-          const mint = ({ route, cycle, exp }) => {
-            const nonce = randomUUID();
-            const payload = { route, cycle, nonce, exp };
-            pending.add(nonce, payload);
-            return signToken(payload, secret);
-          };
-
-          // Git bridge: commit staged changes with a cycle-prefixed message.
-          const git = {
-            commit: (msg) => {
-              execFileSync('git', ['add', '.'], { cwd, encoding: 'utf8' });
-              execFileSync('git', ['commit', '-m', msg], { cwd, encoding: 'utf8' });
-              return execFileSync('git', ['rev-parse', '--short', 'HEAD'], { cwd, encoding: 'utf8' }).trim();
-            },
-            status: () => {
-              const out = execFileSync('git', ['status', '--porcelain'], { cwd, encoding: 'utf8' }).trim();
-              return { clean: out === '', dirty: out.split('\n').filter(Boolean) };
-            },
-          };
-
-          // Finalize bridge: mimics the deleted foundry_stage_finalize body.
-          const finalize = async ({ cycleId, stage, baseSha }) => {
-            let cycleDoc;
-            try {
-              cycleDoc = await getCycleDefinition('foundry', cycleId, io);
-            } catch (e) {
-              return { ok: false, error: 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(cwd, 'WORK.md');
-            const result = finalizeStage({
-              cwd,
-              baseSha,
-              stageBase: stageBaseOf(stage),
-              cycleDef,
-              artefactTypes,
-              registerArtefact: ({ file, type, status }) => {
-                const text = readFileSync(workPath, 'utf-8');
-                const updated = addArtefactRow(text, { file, type, cycle: cycleId, status });
-                writeFileSync(workPath, updated, 'utf-8');
-              },
-            });
-            return result;
-          };
-
-          try {
-            const result = await runOrchestrate({
-              cwd, cycleDef: args.cycleDef, git, mint, finalize,
-              now: () => Date.now(),
-              lastResult: args.lastResult ?? null,
-            }, io);
-            return JSON.stringify(result);
-          } catch (e) {
-            return JSON.stringify({ action: 'violation', details: `orchestrate threw: ${e.message}`, recoverable: false, affected_files: [] });
-          }
-        },
-      }),
-
-      // ── Artefacts tools ──
-      // 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'),
-          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');
-          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_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: {
-          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');
-          if (!existsSync(workPath)) {
-            return JSON.stringify({ error: 'WORK.md not found' });
-          }
-          const text = readFileSync(workPath, 'utf-8');
-          const rows = parseArtefactsTable(text);
-          const filtered = args.cycle ? rows.filter(r => r.cycle === args.cycle) : rows;
-          return JSON.stringify(filtered);
-        },
-      }),
-
-      // ── Feedback tools ──
-      foundry_feedback_add: tool({
-        description: 'Add a feedback item to WORK.md under a file heading',
-        args: {
-          file: tool.schema.string().describe('Artefact file path'),
-          text: tool.schema.string().describe('Feedback text'),
-          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 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 });
-        },
-      }),
-
-      foundry_feedback_action: tool({
-        description: 'Mark a feedback item as actioned [x]',
-        args: {
-          file: tool.schema.string().describe('Artefact file path'),
-          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 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 });
-        },
-      }),
-
-      foundry_feedback_wontfix: tool({
-        description: 'Mark a feedback item as wont-fix [~] with reason',
-        args: {
-          file: tool.schema.string().describe('Artefact file path'),
-          index: tool.schema.number().describe('Zero-based index of the feedback item'),
-          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 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 });
-        },
-      }),
-
-      foundry_feedback_resolve: tool({
-        description: 'Resolve a feedback item (approved or rejected)',
-        args: {
-          file: tool.schema.string().describe('Artefact file path'),
-          index: tool.schema.number().describe('Zero-based index of the feedback item'),
-          resolution: tool.schema.enum(['approved', 'rejected']).describe('Resolution type'),
-          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 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 });
-        },
-      }),
-
-      foundry_feedback_list: tool({
-        description: 'List feedback items, optionally filtered by file',
-        args: {
-          file: tool.schema.string().optional().describe('Filter by artefact file path'),
-        },
-        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');
-          const fm = parseFrontmatter(text);
-          const artefacts = parseArtefactsTable(text);
-          const cycle = fm.cycle || '';
-          return JSON.stringify(listFeedback(text, cycle, artefacts, args.file));
-        },
-      }),
-
-      // ── Git tools ──
-      foundry_git_branch: tool({
-        description: 'Create and checkout a work branch for a flow',
-        args: {
-          flowId: tool.schema.string().describe('Flow ID'),
-          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}`;
-          execFileSync('git', ['checkout', '-b', branch], { cwd: context.worktree, encoding: 'utf8', stdio: 'pipe' });
-          return JSON.stringify({ ok: true, branch });
-        },
-      }),
-
-      foundry_git_finish: tool({
-        description: 'Clean up work files, squash merge to base branch, and delete the work branch',
-        args: {
-          message: tool.schema.string().describe('Squash merge commit message'),
-          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'] };
-
-          // Get current branch name
-          const workBranch = execFileSync('git', ['branch', '--show-current'], opts).trim();
-          if (workBranch === base) {
-            return JSON.stringify({ error: `Already on ${base} — nothing to merge` });
-          }
-
-          // Delete work files
-          const workPath = path.join(cwd, 'WORK.md');
-          const historyPath = path.join(cwd, 'WORK.history.yaml');
-          if (existsSync(workPath)) unlinkSync(workPath);
-          if (existsSync(historyPath)) unlinkSync(historyPath);
-
-          // Commit cleanup if there are changes
-          try {
-            execFileSync('git', ['add', '-A'], opts);
-            const status = execFileSync('git', ['status', '--porcelain'], opts).trim();
-            if (status) {
-              const cleanupMsg = `[${workBranch.replace('work/', '')}] cleanup: remove work files`;
-              execFileSync('git', ['commit', '-m', cleanupMsg], opts);
-            }
-          } catch { /* no changes to commit */ }
-
-          // Switch to base and squash merge
-          execFileSync('git', ['checkout', base], opts);
-          execFileSync('git', ['merge', '--squash', workBranch], opts);
-          execFileSync('git', ['commit', '-m', args.message], opts);
-          const hash = execFileSync('git', ['rev-parse', '--short', 'HEAD'], opts).trim();
-
-          // Force-delete work branch (required after squash)
-          execFileSync('git', ['branch', '-D', workBranch], opts);
-
-          return JSON.stringify({ ok: true, hash, branch: base });
-        },
-      }),
-
-      // ── Config tools ──
-      foundry_config_cycle: tool({
-        description: 'Get a cycle definition from foundry config',
-        args: {
-          cycleId: tool.schema.string().describe('Cycle ID'),
-        },
-        async execute(args, context) {
-          const io = makeIO(context.worktree);
-          const result = await getCycleDefinition('foundry', args.cycleId, io);
-          return JSON.stringify(result);
-        },
-      }),
-
-      foundry_config_artefact_type: tool({
-        description: 'Get an artefact type definition',
-        args: {
-          typeId: tool.schema.string().describe('Artefact type ID'),
-        },
-        async execute(args, context) {
-          const io = makeIO(context.worktree);
-          const result = await getArtefactType('foundry', args.typeId, io);
-          return JSON.stringify(result);
-        },
-      }),
-
-      foundry_config_laws: tool({
-        description: 'Get laws, optionally filtered by artefact type',
-        args: {
-          typeId: tool.schema.string().optional().describe('Artefact type ID'),
-        },
-        async execute(args, context) {
-          const io = makeIO(context.worktree);
-          const result = args.typeId
-            ? await getLaws('foundry', args.typeId, io)
-            : await getLaws('foundry', io);
-          return JSON.stringify(result);
-        },
-      }),
-
-      foundry_config_validation: tool({
-        description: 'Get validation commands for an artefact type',
-        args: {
-          typeId: tool.schema.string().describe('Artefact type ID'),
-        },
-        async execute(args, context) {
-          const io = makeIO(context.worktree);
-          const result = await getValidation('foundry', args.typeId, io);
-          return JSON.stringify(result);
-        },
-      }),
-
-      foundry_config_appraisers: tool({
-        description: 'List all appraisers',
-        args: {},
-        async execute(_args, context) {
-          const io = makeIO(context.worktree);
-          const result = await getAppraisers('foundry', io);
-          return JSON.stringify(result);
-        },
-      }),
-
-      foundry_config_flow: tool({
-        description: 'Get a flow definition',
-        args: {
-          flowId: tool.schema.string().describe('Flow ID'),
-        },
-        async execute(args, context) {
-          const io = makeIO(context.worktree);
-          const result = await getFlow('foundry', args.flowId, io);
-          return JSON.stringify(result);
-        },
-      }),
-
-      // ── Validate tool ──
-      foundry_validate_run: tool({
-        description: 'Run validation commands for an artefact type against a file',
-        args: {
-          typeId: tool.schema.string().describe('Artefact type ID'),
-          file: tool.schema.string().describe('File path to validate'),
-        },
-        async execute(args, context) {
-          const io = makeIO(context.worktree);
-          const commands = await getValidation('foundry', args.typeId, io);
-          if (!commands || commands.length === 0) return JSON.stringify({ error: 'No validation defined for type: ' + args.typeId });
-          const results = [];
-          for (const entry of commands) {
-            const expanded = entry.command.replace(/\{file\}/g, args.file);
-            try {
-              const output = execSync(expanded, { cwd: context.worktree, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
-              results.push({ id: entry.id, command: expanded, passed: true, output: output.trim() });
-            } catch (err) {
-              results.push({ id: entry.id, command: expanded, passed: false, output: (err.stderr || err.stdout || err.message || '').trim(), failureMeans: entry.failureMeans });
-            }
-          }
-          return JSON.stringify(results);
-        },
-      }),
-
-      // ── Appraiser selection tool ──
-      foundry_appraisers_select: tool({
-        description: 'Select appraisers for an artefact type',
-        args: {
-          typeId: tool.schema.string().describe('Artefact type ID'),
-          count: tool.schema.number().optional().describe('Number of appraisers to select'),
-        },
-        async execute(args, context) {
-          const io = makeIO(context.worktree);
-          const result = args.count
-            ? await selectAppraisers('foundry', args.typeId, args.count, io)
-            : await selectAppraisers('foundry', args.typeId, io);
-          return JSON.stringify(result);
-        },
-      }),
-    },
-  };
-
-  Object.defineProperty(plugin, Symbol.for('foundry.test.pending'), { value: pending });
-  Object.defineProperty(plugin, Symbol.for('foundry.test.secret'), { value: secret });
-  return plugin;
-};