@really-knows-ai/foundry 2.2.1 → 2.3.0

package/.opencode/plugins/foundry.js

@@ -12,13 +12,12 @@ 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, appendEntry, getIteration, readLastSortRoute } 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';
@@ -103,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
 
@@ -127,6 +126,12 @@ function makeIO(directory) {
     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'] }),
   };
 }
 
@@ -165,35 +170,6 @@ export const FoundryPlugin = async ({ directory }) => {
 
     tool: {
       // ── History tools ──
-      foundry_history_append: tool({
-        description: 'Append an entry to the cycle history (WORK.history.yaml)',
-        args: {
-          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, route: args.route }, io);
-          return JSON.stringify({ ok: true, iteration });
-        },
-      }),
-
       foundry_history_list: tool({
         description: 'List history entries for a cycle',
         args: {
@@ -269,57 +245,6 @@ export const FoundryPlugin = async ({ directory }) => {
         },
       }),
 
-      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',
@@ -371,137 +296,111 @@ 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 (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"}\')'),
+          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_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}` });
+          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');
-          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
-            }
+          const historyPath = path.join(context.worktree, 'WORK.history.yaml');
+          if (existsSync(workPath)) {
+            unlinkSync(workPath);
           }
-          // 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);
-            }
+          if (existsSync(historyPath)) {
+            unlinkSync(historyPath);
           }
-          const updated = setFrontmatterField(text, args.key, value);
-          writeFileSync(workPath, updated, 'utf-8');
           return JSON.stringify({ ok: true });
         },
       }),
 
-      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).',
+      // ── 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: {
-          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>)'),
+          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 guard = requireNoActiveStage(io);
-          if (!guard.ok) return JSON.stringify({ error: `foundry_workfile_configure_from_cycle ${guard.error}` });
+          const cwd = context.worktree;
 
-          const workPath = path.join(context.worktree, 'WORK.md');
-          if (!existsSync(workPath)) {
-            return JSON.stringify({ error: 'WORK.md not found' });
-          }
+          // 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);
+          };
 
-          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 } : {}),
+          // 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) };
+            },
+          };
 
-      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);
+          // 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: [] });
           }
-          return JSON.stringify({ ok: true });
         },
       }),
 
@@ -672,27 +571,6 @@ export const FoundryPlugin = async ({ directory }) => {
         },
       }),
 
-      // ── Sort tool ──
-      foundry_sort: tool({
-        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 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);
-        },
-      }),
-
       // ── Git tools ──
       foundry_git_branch: tool({
         description: 'Create and checkout a work branch for a flow',
@@ -712,25 +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) {
-          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' });
-          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: {
@@ -746,7 +605,7 @@ export const FoundryPlugin = async ({ directory }) => {
           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` });
           }
@@ -759,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 });
         },

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 2.3.0 — 2026-04-20
+
+### Breaking
+
+- **LLM orchestration replaced with deterministic `foundry_orchestrate` tool.** The `cycle` and `sort` skills are removed; replaced by a single thin `orchestrate` skill that drives a 3-line loop.
+- **Six tools deregistered** from the plugin (still exist as internal imports for tests): `foundry_sort`, `foundry_history_append`, `foundry_stage_finalize`, `foundry_git_commit`, `foundry_workfile_configure_from_cycle`, `foundry_workfile_set`.
+- Upgrade requires clean main + no in-flight workfile (see `upgrade-foundry` skill).
+
+### Added
+
+- `foundry_orchestrate` — single tool that owns the sort → history → dispatch → finalize → history → commit loop. Atomic stage completion.
+- `scripts/orchestrate.js` — deterministic orchestration logic, composes existing internal functions.
+- Orphaned-stage detection: if orchestrate is called without `lastResult` but an active stage exists, returns `violation`. Fixes the ses_256c failure mode where an LLM skipped the post-dispatch history append and wedged the cycle.
+
+### Fixed
+
+- Root cause of all deferred HARDEN.md bugs (B, C, D, E, G) and the ses_256c bug: LLM misfollowing a deterministic protocol. Protocol now lives inside the plugin tool.
+
+### Migration
+
+See `skills/upgrade-foundry/SKILL.md` for v2.3.0 pre-flight checks. No automated state migration — complete or discard in-flight cycles on v2.2.x before upgrading.
+
 ## 2.2.1 — 2026-04-20
 
 Follow-up patch addressing the five bugs deferred from v2.2.0 (see `HARDEN.md` §Deferred).

package/docs/work-spec.md

@@ -25,8 +25,8 @@ The `stages` list is the happy path. Sort follows it but loops back to `forge` w
 
 - `flow` — set by the foundry flow skill at foundry flow start, never changes
 - `cycle` — set by the foundry flow skill when starting each foundry cycle
-- `stages` — set by the foundry cycle skill when starting each foundry cycle (reads artefact type to determine if quench is needed)
-- `max-iterations` — set by the foundry cycle skill (default 3, could be overridden in foundry cycle definition)
+- `stages` — set by the orchestrate skill when starting each foundry cycle (reads artefact type to determine if quench is needed)
+- `max-iterations` — set by the orchestrate skill (default 3, could be overridden in foundry cycle definition)
 
 ## Sections
 
@@ -96,9 +96,9 @@ Grouped by artefact file path. Each item is a checklist entry with a tag indicat
 | Section | Written by | Updated by |
 |---------|-----------|------------|
 | Frontmatter (`flow`) | `foundry_workfile_create` (flow skill) | nobody |
-| Frontmatter (`cycle`, `stages`, `max-iterations`) | `foundry_workfile_set` (cycle skill) | `foundry_workfile_set` (reset on each new cycle) |
+| Frontmatter (`cycle`, `stages`, `max-iterations`) | `foundry_workfile_set` (orchestrate skill) | `foundry_workfile_set` (reset on each new cycle) |
 | Goal | `foundry_workfile_create` (flow skill) | nobody |
-| Artefacts | `foundry_artefacts_add` (forge skill) | `foundry_artefacts_set_status` (cycle skill) |
+| Artefacts | `foundry_artefacts_add` (forge skill) | `foundry_artefacts_set_status` (orchestrate skill) |
 | Feedback | `foundry_feedback_add` (quench/appraise/hitl) | `foundry_feedback_action`/`foundry_feedback_wontfix` (forge), `foundry_feedback_resolve` (quench/appraise/hitl) |
 
 ## WORK.history.yaml

package/package.json

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

package/scripts/orchestrate.js

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

package/skills/flow/SKILL.md

@@ -2,7 +2,7 @@
 name: flow
 type: composite
 description: Runs a defined foundry flow to produce artefacts. Use this whenever the user references a flow by id, name, or paraphrase (e.g. "use the creative flow", "run creative-flow"). Do not brainstorm — the flow's cycles already define the work. The user's request is the goal to pass in.
-composes: [cycle]
+composes: [orchestrate]
 ---
 
 # Flow
@@ -30,8 +30,8 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
       - **Resume** — keep the existing workfile and skip to step 6. **Only offer resume if the existing `flow` AND `cycle` match what the user just asked for.** If either differs, do not offer resume — running the wrong cycle against stale state corrupts the workflow.
       - **Discard** — call `foundry_workfile_delete`, then proceed to step 5.
       - **Abort** — stop the skill without modifying anything.
-5. Call `foundry_workfile_create` with **only** the flow ID, chosen cycle ID, and goal — do **not** pass `stages` or `maxIterations`. The `cycle` skill will read the cycle definition and populate those via `foundry_workfile_set` in the next step.
-6. Execute the cycle by invoking the cycle skill
+5. Call `foundry_workfile_create` with **only** the flow ID, chosen cycle ID, and goal — do **not** pass `stages` or `maxIterations`. The `orchestrate` skill will read the cycle definition and handle setup on its first call.
+6. Execute the cycle by invoking the orchestrate skill
 
 ## Between cycles
 
@@ -49,9 +49,9 @@ When a cycle completes (sort returns `done`):
    - Check input contracts for each
    - The user chooses which target to pursue (or which to pursue first)
 5. Set up the next cycle:
-   - Call `foundry_workfile_set` with `key: "cycle"`, `value: <next-cycle-id>`
-   - Reset stages and iteration count for the new cycle
-   - Execute the cycle by invoking the cycle skill
+   - Call `foundry_workfile_delete` to clear the completed cycle's WORK.md
+   - Call `foundry_workfile_create` with **only** the flow ID, the next cycle ID, and the goal — do **not** pass `stages` or `maxIterations`. The orchestrate skill will detect `needsSetup` on its first call and bootstrap the rest of the frontmatter from the cycle definition.
+   - Execute the cycle by invoking the orchestrate skill
 
 ## Completing a flow
 

package/skills/human-appraise/SKILL.md

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

package/skills/orchestrate/SKILL.md

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

package/skills/upgrade-foundry/SKILL.md

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

package/skills/cycle/SKILL.md

@@ -1,87 +0,0 @@
----
-name: cycle
-type: composite
-description: Runs a foundry cycle by delegating all routing to the sort skill.
-composes: [sort, forge, quench, appraise, human-appraise]
----
-
-# Cycle
-
-A foundry cycle reads its definition, sets up the work file for routing, then hands control to the sort skill which drives the forge/quench/appraise/human-appraise loop.
-
-## Prerequisites
-
-Before running this skill, verify that the `foundry/` directory exists in the project root. If it does not exist, stop and tell the user:
-
-> Foundry is not initialized in this project. Run the `init-foundry` skill first to create the foundry/ directory structure.
-
-## Starting a foundry cycle
-
-1. Call `foundry_config_cycle` with the cycle ID — get the cycle definition
-2. Call `foundry_config_artefact_type` with the output type ID — get the artefact type definition
-3. Determine the stage route:
-   - Use the cycle definition's `stages` field if present
-   - Otherwise generate defaults: always `forge`, add `quench` if `foundry_config_validation` returns non-null for the type, always `appraise`
-   - If the cycle definition has `human-appraise: true`, append `human-appraise` as the final stage (runs every iteration). If `human-appraise: false` (default), do NOT include it in `stages` — sort will synthesize `human-appraise:<cycle>` on deadlock when needed.
-   - Stages should use `base:alias` format (e.g. `forge:write-haiku`, `quench:check-syllables`). If you pass bare names, the tool will auto-append the cycle ID as the alias.
-4. Call `foundry_workfile_configure_from_cycle({cycleId, stages})` with the cycle ID and the stages list from step 3. The tool reads the cycle definition and writes `cycle`, `stages`, `max-iterations`, `human-appraise`, `deadlock-appraise`, `deadlock-iterations`, and (if present) `models` into WORK.md in a single call, applying defaults for anything the cycle def omits. Do **not** use `foundry_workfile_set` for this — the configure tool is the authoritative cycle-def → WORK.md translator.
-5. Invoke the sort skill
-
-## Sort drives everything
-
-Once sort is invoked, it calls `foundry_sort` to determine the next stage, dispatches the corresponding skill to a fresh subagent with a single-use token, calls `foundry_stage_finalize` to register outputs (or detect file-pattern violations), writes history, and commits. This repeats until sort returns `done`, `blocked`, or `violation`.
-
-The cycle skill does not contain routing, finalization, history, or commit logic — sort owns all of that. The cycle skill only sets up the work file and reacts to sort's terminal result.
-
-## Completing a foundry cycle
-
-When sort returns `done`:
-- Call `foundry_artefacts_set_status(file, 'done')` for the cycle's output artefact.
-- Return control to the flow skill.
-
-When sort returns `blocked`:
-- The target artefact is usually already marked `blocked` by sort (on violations) or by human-appraise (on explicit abort). If not, call `foundry_artefacts_set_status(file, 'blocked')`.
-- Return control to the flow skill — the flow decides how to handle it.
-
-When sort returns `violation` (e.g., `stage_finalize` `unexpected_files`, missing subagent, or file-pattern violation):
-- Sort has already marked affected artefacts blocked and returned. Treat as the blocked path.
-- Return control to the flow skill.
-
-## Human Appraise
-
-Human-appraise is controlled by two flat cycle-def keys:
-
-- `human-appraise: true` — human-appraise runs every iteration as part of the normal stage flow (appended to `stages`).
-- `deadlock-appraise: true` (default) — if LLM appraisers deadlock on the same feedback for `deadlock-iterations` rounds (default 5), sort routes to human-appraise to resolve it, even when it isn't in `stages`.
-- `deadlock-appraise: false` — no human intervention; deadlock → `blocked`.
-
-## Micro commits
-
-Every stage ends with a micro commit, written by sort (not cycle, not subagents). The message format is `[<cycle-id>] <base>:<alias>: <brief description>`.
-
-Examples:
-- `[haiku-creation] forge:write-haiku: initial draft`
-- `[haiku-creation] quench:check-syllables: checked syllable pattern`
-- `[haiku-creation] forge:write-haiku: addressed validation feedback`
-
-## Feedback states
-
-```
-open         - needs generator action
-actioned     - needs approval
-wont-fix     - needs approval (appraisal only)
-approved     - resolved
-rejected     - re-opened
-```
-
-Tag types: `validation` (from quench), `law:<law-id>` (from appraise), `human` (from human-appraise) — indicates the source and category of feedback.
-
-## What you do NOT do
-
-- You do not make routing decisions — sort does that.
-- You do not register artefacts — `foundry_stage_finalize` does that (invoked by sort).
-- You do not write history or commits — sort does that.
-- You do not change the laws mid-cycle.
-- You do not decide the artefact is "close enough" — it passes or it doesn't.
-- You do not proceed past a file modification violation — honor sort's `violation`/`blocked` return.
-- You do not modify input artefacts — they are read-only.

package/skills/sort/SKILL.md

@@ -1,111 +0,0 @@
----
-name: sort
-type: atomic
-description: Deterministic routing for a foundry cycle. Runs the foundry_sort tool and returns the next stage.
----
-
-# Sort
-
-You are the central dispatcher for a foundry cycle. You call `foundry_sort` to determine what stage to execute next, dispatch that stage to a fresh subagent, finalize the stage's disk output, and log history. You are the sole writer of history and git commits.
-
-## Prerequisites
-
-Before running this skill, verify that the `foundry/` directory exists in the project root. If it does not exist, stop and tell the user:
-
-> Foundry is not initialized in this project. Run the `init-foundry` skill first to create the foundry/ directory structure.
-
-## Protocol
-
-1. Call `foundry_sort` (optionally passing `cycleDef`). It returns `{route, model?, token?, details?}`. For dispatchable routes (`forge|quench|appraise|human-appraise:*`) the tool mints a single-use, time-limited `token`.
-
-2. Call `foundry_history_append({cycle, stage: 'sort', comment, route})` — the `route` field records what sort decided, and **subsequent** `history_append` calls for non-sort stages are enforced to match this route. This is your audit trail.
-
-3. Act on the route:
-   - `forge:*` / `quench:*` / `appraise:*` — **dispatch** (see §Dispatch).
-   - `human-appraise:*` — invoke the human-appraise skill inline (human stage, no subagent) but still pass the `token`; the skill must call `foundry_stage_begin` with it.
-   - `done` — cycle is complete, return to the cycle skill.
-   - `blocked` — iteration limit hit with unresolved feedback, return to the cycle skill.
-   - `violation` — a validation, file-modification, or missing-subagent violation was detected (see `details`). Halt the cycle: call `foundry_artefacts_set_status(file, 'blocked')` for each affected artefact, and return to the cycle skill. If `details` mentions a missing subagent, tell the user to run `refresh-agents` and restart.
-
-4. **After** the dispatched subagent returns, call `foundry_stage_finalize({cycle})`. Handle three outcomes:
-   - `{ok: true, artefacts: [...]}` — the tool has already registered output artefact rows in WORK.md. Proceed to step 5.
-   - `{error: 'unexpected_files', files: [...]}` — the subagent wrote outside the artefact type's `file-patterns`. Mark the cycle's target artefact `blocked` via `foundry_artefacts_set_status` and do **not** re-run the stage. Add a `violation` feedback item describing the offending files, then return to the cycle skill.
-   - Any other error — surface it to the user and halt.
-
-5. Call `foundry_history_append({cycle, stage: <dispatched-stage-alias>, comment})` summarizing what the subagent reported. The tool enforces that the stage alias matches the most recent sort's `route` — this is why step 2's `route` field matters.
-
-6. Call `foundry_git_commit({cycle, stage, description})` to record the stage's disk changes. **This is mandatory.** The next `foundry_sort` call will return `{route: 'violation', details: 'Uncommitted tool-managed files...'}` if WORK.md, WORK.history.yaml, or anything under `.foundry/` is dirty — the tool enforces one commit per stage.
-
-7. Return to step 1. Repeat until `done`, `blocked`, or `violation`.
-
-## Dispatch
-
-Every forge, quench, and appraise stage runs in a **fresh subagent**. Never inline the stage work in the orchestrator conversation — even if the chosen model matches the orchestrator's. The orchestrator's job is to route, dispatch, finalize, and log. Nothing else.
-
-### Choosing the subagent
-
-- If `foundry_sort` returned a `model` field, use it verbatim as `subagent_type`. It is already in `foundry-<slug>` form.
-- If no `model` field, dispatch to `general`.
-
-### Token handling
-
-The `token` returned by `foundry_sort` is an opaque signed string. Pass it through the dispatch prompt verbatim. **Never** invent, edit, or re-sign tokens. The subagent's first tool call must be `foundry_stage_begin({stage, cycle, token})` using this exact string; `stage_begin` verifies the signature, expiry, and single-use nonce.
-
-### Dispatch call shape
-
-Use the `task` tool:
-
-```
-task tool:
-  subagent_type: <model-slug-from-foundry_sort, or "general">
-  description: "Run <stage-alias> for <cycle-id>"
-  prompt: |
-    You are a Foundry stage agent. Invoke the <stage-base> skill and follow its instructions exactly.
-
-    Stage: <stage-alias>
-    Cycle: <cycle-id>
-    Token: <token-verbatim>
-    Working directory: <worktree>
-    File patterns (forge only): <file-patterns-list>
-
-    Your FIRST tool call MUST be foundry_stage_begin({stage, cycle, token}) using the values above.
-    Your LAST tool call MUST be foundry_stage_end({summary}).
-
-    When done, report back a brief summary. Do NOT call foundry_history_append, foundry_git_commit, or foundry_artefacts_add — the orchestrator handles all of those.
-```
-
-Substitute:
-- `<stage-alias>` — the full route string from `foundry_sort` (e.g., `forge:write-haiku`)
-- `<stage-base>` — the base of the alias
-- `<cycle-id>` — current cycle ID from WORK.md frontmatter
-- `<token-verbatim>` — exactly the `token` string from `foundry_sort` — no quoting transforms, no re-encoding
-- `<file-patterns-list>` — for forge stages, read via `foundry_config_artefact_type` and include so the subagent can avoid violations
-- `<worktree>` — current working directory
-
-### Missing subagent (fail-fast)
-
-`foundry_sort` verifies that `.opencode/agents/foundry-<slug>.md` exists before returning a `model`. If it doesn't, sort returns `{route: 'violation', details: 'Missing required subagent: ...'}`. Handle as in step 3 above.
-
-## Violation handling
-
-If `foundry_stage_finalize` returns `{error: 'unexpected_files', files}`:
-
-- The stage wrote outside its permitted `file-patterns`. This is unrecoverable within the current cycle.
-- Mark the target artefact `blocked`: `foundry_artefacts_set_status(file, 'blocked')`.
-- Add a feedback item describing the offense: `foundry_feedback_add(file, text: 'unexpected files: …', tag: 'violation')` (if permitted by your stage), or log in the history comment.
-- Do NOT attempt to re-run the stage — the subagent already consumed the stage slot.
-- Return to the cycle skill so the operator can intervene.
-
-If `foundry_sort` returns `{route: 'violation', details: 'Uncommitted tool-managed files...'}`:
-
-- A prior stage skipped step 6 (the micro-commit). The work is not lost — it's still in the working tree.
-- Call `foundry_git_commit({cycle, stage: <the-stage-that-just-ran>, description})` to record it.
-- Then call `foundry_sort` again. It should route normally.
-- If you genuinely don't know which stage produced the dirty files, read `WORK.history.yaml` — the most recent non-sort entry is the culprit.
-
-## What you do NOT do
-
-- You do not inline forge/quench/appraise work — always dispatch.
-- You do not mint, modify, or cache tokens — they come from `foundry_sort` and go straight to `foundry_stage_begin`.
-- You do not skip `foundry_stage_finalize` — it is the only mechanism that registers artefacts and detects file-pattern violations.
-- You do not let subagents call `foundry_history_append`, `foundry_git_commit`, or `foundry_artefacts_add` (the last has been removed anyway).