@really-knows-ai/foundry 2.2.1 → 2.3.1

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,40 @@
 # Changelog
 
+## 2.3.1 — 2026-04-20
+
+### Changed
+
+- `flow` skill: any cycle in a flow may now be the starting cycle (previously limited to `starting-cycles`). The list becomes a hint for ambiguous requests. A cycle whose `inputs` contract cannot be satisfied from files on disk is not eligible to start.
+- `flow` skill: between-cycles logic no longer implies any carry-over ceremony. The next cycle's forge discovers the previous cycle's output via filesystem scan against its input types' `file-patterns`.
+- `forge` skill: input discovery now explicitly uses filesystem scan against each input type's `file-patterns`, with the goal guiding which candidates are relevant.
+- `forge` skill: the write invariant is restated accurately — forge may only write to files matching the output artefact type's `file-patterns` (plus the tool-managed files). All other files on disk are read-only. The previous "inputs are read-only" framing was a special case of this rule.
+
+### Notes
+
+- No tool, schema, or enforcement changes. Existing flows continue to work. `sort.js`'s `checkModifiedFiles` already enforces the write invariant.
+
+## 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.1",
   "description": "A structured framework for AI-driven artefact creation with deterministic routing, quality gates, and iterative refinement cycles.",
   "type": "module",
   "main": ".opencode/plugins/foundry.js",