@really-knows-ai/foundry 2.1.0 → 2.3.0

package/.opencode/plugins/foundry.js

@@ -9,17 +9,26 @@
 
 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 { parseFrontmatter, createWorkfile, setFrontmatterField, getFrontmatterField, enrichStages, parseStagesValue, parseModelsValue } from '../../scripts/lib/workfile.js';
+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 { 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, '../..');
@@ -93,7 +102,7 @@ new skills). It does NOT apply to running an existing, defined flow.
 
 ## Available skills
 
-- **Pipeline:** forge, quench, appraise, cycle, flow, sort, human-appraise
+- **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
 
@@ -115,11 +124,27 @@ 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)); },
+    // 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 }) => {
-  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 || [];
@@ -145,32 +170,78 @@ export const FoundryPlugin = async ({ directory }) => {
 
     tool: {
       // ── History tools ──
-      foundry_history_append: tool({
-        description: 'Append an entry to the cycle history (WORK.history.yaml)',
+      foundry_history_list: tool({
+        description: 'List history entries for a cycle',
         args: {
           cycle: tool.schema.string().describe('Cycle name'),
-          stage: tool.schema.string().describe('Stage name'),
-          comment: tool.schema.string().describe('Comment for this entry'),
         },
         async execute(args, context) {
           const io = makeIO(context.worktree);
           const historyPath = path.join(context.worktree, 'WORK.history.yaml');
-          const iteration = getIteration(historyPath, args.cycle, io);
-          appendEntry(historyPath, { cycle: args.cycle, stage: args.stage, iteration, comment: args.comment }, io);
-          return JSON.stringify({ ok: true, iteration });
+          const entries = loadHistory(historyPath, args.cycle, io);
+          return JSON.stringify(entries);
         },
       }),
 
-      foundry_history_list: tool({
-        description: 'List history entries for a cycle',
+      // ── 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);
-          const historyPath = path.join(context.worktree, 'WORK.history.yaml');
-          const entries = loadHistory(historyPath, args.cycle, io);
-          return JSON.stringify(entries);
+          // 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 });
         },
       }),
 
@@ -186,16 +257,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);
@@ -222,53 +296,18 @@ export const FoundryPlugin = async ({ directory }) => {
         },
       }),
 
-      foundry_workfile_set: tool({
-        description: 'Update a single frontmatter field in WORK.md',
+      foundry_workfile_delete: tool({
+        description: 'Delete WORK.md and WORK.history.yaml (requires confirm:true)',
         args: {
-          key: tool.schema.string().describe('Frontmatter key'),
-          value: tool.schema.string().describe('Value to set (use JSON for arrays/objects, e.g. \'["forge:a","quench:b"]\' or \'{"forge":"openai/gpt-4o"}\')'),
+          confirm: tool.schema.boolean().describe('Must be true to confirm deletion'),
         },
         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');
-          // Parse JSON values for arrays/objects, keep strings as-is
-          let value = args.value;
-          if (args.key === 'stages') {
-            // Always parse stages into an array (handles JSON arrays and comma-separated strings)
-            value = parseStagesValue(args.value);
-          } else if (args.key === 'models') {
-            // Always parse models into an object (handles JSON objects and "key: value" strings)
-            value = parseModelsValue(args.value);
-          } else {
-            try {
-              const parsed = JSON.parse(args.value);
-              if (typeof parsed === 'object' || Array.isArray(parsed) || typeof parsed === 'number') {
-                value = parsed;
-              }
-            } catch {
-              // Not JSON, use as plain string
-            }
-          }
-          // Auto-enrich bare stage names with cycle ID alias
-          if (args.key === 'stages' && Array.isArray(value)) {
-            const fm = parseFrontmatter(text);
-            if (fm.cycle) {
-              value = enrichStages(value, fm.cycle);
-            }
+          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 updated = setFrontmatterField(text, args.key, value);
-          writeFileSync(workPath, updated, 'utf-8');
-          return JSON.stringify({ ok: true });
-        },
-      }),
-
-      foundry_workfile_delete: tool({
-        description: 'Delete WORK.md and WORK.history.yaml',
-        args: {},
-        async execute(_args, context) {
           const workPath = path.join(context.worktree, 'WORK.md');
           const historyPath = path.join(context.worktree, 'WORK.history.yaml');
           if (existsSync(workPath)) {
@@ -281,49 +320,130 @@ export const FoundryPlugin = async ({ directory }) => {
         },
       }),
 
-      // ── Artefacts tools ──
-      foundry_artefacts_add: tool({
-        description: 'Add an artefact row to the WORK.md table',
+      // ── 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: {
-          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)'),
+          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 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 });
+          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',
+        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'),
+          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 = setArtefactStatus(text, args.file, args.status);
-          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_list: tool({
-        description: 'List all artefacts from the WORK.md table',
-        args: {},
-        async execute(_args, context) {
+        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');
-          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 +456,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 +488,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 +512,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 +537,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 });
         },
       }),
@@ -410,19 +571,6 @@ export const FoundryPlugin = async ({ directory }) => {
         },
       }),
 
-      // ── Sort tool ──
-      foundry_sort: tool({
-        description: 'Run sort routing to determine the next stage',
-        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);
-          return JSON.stringify(result);
-        },
-      }),
-
       // ── Git tools ──
       foundry_git_branch: tool({
         description: 'Create and checkout a work branch for a flow',
@@ -431,6 +579,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}`;
@@ -439,22 +590,6 @@ export const FoundryPlugin = async ({ directory }) => {
         },
       }),
 
-      foundry_git_commit: tool({
-        description: 'Stage all changes and commit with a cycle-prefixed message',
-        args: {
-          cycle: tool.schema.string().describe('Cycle name'),
-          stage: tool.schema.string().describe('Stage name'),
-          description: tool.schema.string().describe('Commit description'),
-        },
-        async execute(args, context) {
-          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' });
-          const hash = execSync('git rev-parse --short HEAD', { cwd: context.worktree, encoding: 'utf8' }).trim();
-          return JSON.stringify({ ok: true, hash });
-        },
-      }),
-
       foundry_git_finish: tool({
         description: 'Clean up work files, squash merge to base branch, and delete the work branch',
         args: {
@@ -462,12 +597,15 @@ 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'] };
 
           // Get current branch name
-          const workBranch = execSync('git branch --show-current', opts).trim();
+          const workBranch = execFileSync('git', ['branch', '--show-current'], opts).trim();
           if (workBranch === base) {
             return JSON.stringify({ error: `Already on ${base} — nothing to merge` });
           }
@@ -480,23 +618,22 @@ export const FoundryPlugin = async ({ directory }) => {
 
           // Commit cleanup if there are changes
           try {
-            execSync('git add -A', opts);
-            const status = execSync('git status --porcelain', opts).trim();
+            execFileSync('git', ['add', '-A'], opts);
+            const status = execFileSync('git', ['status', '--porcelain'], opts).trim();
             if (status) {
               const cleanupMsg = `[${workBranch.replace('work/', '')}] cleanup: remove work files`;
-              execSync(`git commit -m "${cleanupMsg.replace(/"/g, '\\"')}"`, opts);
+              execFileSync('git', ['commit', '-m', cleanupMsg], opts);
             }
           } catch { /* no changes to commit */ }
 
           // Switch to base and squash merge
-          execSync(`git checkout ${base}`, opts);
-          execSync(`git merge --squash ${workBranch}`, opts);
-          const msg = args.message.replace(/"/g, '\\"');
-          execSync(`git commit -m "${msg}"`, opts);
-          const hash = execSync('git rev-parse --short HEAD', opts).trim();
+          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)
-          execSync(`git branch -D ${workBranch}`, opts);
+          execFileSync('git', ['branch', '-D', workBranch], opts);
 
           return JSON.stringify({ ok: true, hash, branch: base });
         },
@@ -617,4 +754,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;
 };