@really-knows-ai/foundry 3.4.0 → 3.5.2

package/dist/.opencode/plugins/foundry-tools/artefact-tools.js

@@ -1,58 +1,47 @@
 import path from 'path';
-import { readFileSync, writeFileSync, existsSync } from 'fs';
-import { requireNoActiveStage } from '../../../scripts/lib/stage-guard.js';
-import { guarded, notFailedGuard } from '../../../scripts/lib/guards.js';
-import { parseArtefactsTable, setArtefactStatus } from '../../../scripts/lib/artefacts.js';
-import { makeIO, branchIoFactory, asyncIoFactory, flowBranchGuard } from './helpers.js';
+import { readFileSync, existsSync } from 'fs';
+import { getArtefactFiles } from '../../../scripts/lib/artefacts.js';
+import { getCycleDefinition } from '../../../scripts/lib/config.js';
+import { parseFrontmatter } from '../../../scripts/lib/workfile.js';
+import { makeIO } from './helpers.js';
 
-const gateNotFailed = notFailedGuard(makeIO);
+function readWorkCycleId(worktree) {
+  const workPath = path.join(worktree, 'WORK.md');
+  if (!existsSync(workPath)) throw new Error('WORK.md not found');
+  const frontmatter = parseFrontmatter(readFileSync(workPath, 'utf-8'));
+  if (!frontmatter.cycle) throw new Error('current cycle not found in WORK.md frontmatter');
+  return frontmatter.cycle;
+}
+
+async function readOutputType(foundryDir, cycleId, io) {
+  let cd;
+  try {
+    cd = await getCycleDefinition(foundryDir, cycleId, io);
+  } catch { return null; }
+  return cd.frontmatter && cd.frontmatter['output-type'];
+}
 
 function makeListTool(tool) {
   return tool({
-    description: 'List artefacts from the WORK.md table. Optionally filter by cycle — callers should always pass the current cycle to avoid picking up stale rows from prior sessions.',
-    args: {
-      cycle: tool.schema.string().optional().describe('Only return rows whose Cycle column matches this value'),
-    },
-    async execute(args, context) {
-      const workPath = path.join(context.worktree, 'WORK.md');
-      if (!existsSync(workPath)) {
-        return JSON.stringify({ error: 'WORK.md not found' });
+    description: 'List artefact changes on the current work branch for the current cycle. Returns [{ file, state }] entries.',
+    args: {},
+    async execute(_args, context) {
+      try {
+        const cycleId = readWorkCycleId(context.worktree);
+        const io = makeIO(context.worktree);
+        const outputType = await readOutputType('foundry', cycleId, io);
+        if (!outputType) return JSON.stringify([]);
+        const artefacts = await getArtefactFiles('foundry', outputType, io, { baseBranch: 'main' });
+        return JSON.stringify(artefacts);
+      } catch (err) {
+        return JSON.stringify({ error: err.message });
       }
-      const text = readFileSync(workPath, 'utf-8');
-      const rows = parseArtefactsTable(text);
-      const filtered = args.cycle ? rows.filter(r => r.cycle === args.cycle) : rows;
-      return JSON.stringify(filtered);
     },
   });
 }
 
 export function createArtefactTools({ tool }) {
   return {
-    // NOTE: `foundry_artefacts_add` was removed in v2.2.0. Artefacts are now
-    // registered automatically by the orchestrator's internal finalize step as drafts,
-    // then promoted to done|blocked via `foundry_artefacts_set_status`.
-    foundry_artefacts_set_status: tool({
-      description: 'Update the status of an artefact in WORK.md (done|blocked only)',
-      args: {
-        file: tool.schema.string().describe('Artefact file path'),
-        status: tool.schema.string().describe('New status (done|blocked)'),
-      },
-      execute: guarded('foundry_artefacts_set_status', [flowBranchGuard, gateNotFailed], async (args, context) => {
-        const io = makeIO(context.worktree);
-        const guard = requireNoActiveStage(io);
-        if (!guard.ok) return JSON.stringify({ error: `foundry_artefacts_set_status ${guard.error}` });
-        const workPath = path.join(context.worktree, 'WORK.md');
-        const text = readFileSync(workPath, 'utf-8');
-        try {
-          const updated = setArtefactStatus(text, args.file, args.status);
-          writeFileSync(workPath, updated, 'utf-8');
-          return JSON.stringify({ ok: true });
-        } catch (e) {
-          return JSON.stringify({ error: e.message });
-        }
-      }, { branchIo: branchIoFactory, io: asyncIoFactory }),
-    }),
-
     foundry_artefacts_list: makeListTool(tool),
   };
 }

package/dist/.opencode/plugins/foundry-tools/attestation-tools.js

@@ -131,11 +131,18 @@ function commitAttestation(cwd, cycle, content, opts) {
 function buildAttestationInputs(opts) {
   return {
     cwd: opts.cwd,
+    foundryDir: 'foundry',
     baseBranch: opts.baseBranch,
+    branchBaseSha: opts.branchBaseSha,
     goalText: opts.goalText,
     archiveBranch: opts.archiveBranch,
     archiveTipSha: opts.archiveTipSha,
-    io: { readFile: (p) => readFileSync(p, 'utf8'), fileExists: (p) => existsSync(p) },
+    io: {
+      readFile: (p) => readFileSync(p, 'utf8'),
+      fileExists: (p) => existsSync(p),
+      exists: (p) => existsSync(p),
+      exec: (args) => execFileSync(args[0], args.slice(1), { cwd: opts.cwd, encoding: 'utf8' }),
+    },
     execGit: opts.execGit,
   };
 }
@@ -151,7 +158,7 @@ function createAttestTool(tool) {
   return tool({
     description:
       'Verify the current work cycle is complete (all required stages ran, no unresolved ' +
-      'feedback, no blocked artefacts) and commit an ATTEST.md attestation file to the work branch. ' +
+      'feedback) and commit an ATTEST.md attestation file to the work branch. ' +
       'foundry_git_finish will not merge without this commit at HEAD.',
     args: {
       baseBranch: tool.schema.string().optional()

package/dist/.opencode/plugins/foundry-tools/config-create-tools.js

@@ -160,7 +160,7 @@ function cycleArgs(s) { return {
   inputs: s.object({
     type: s.enum(['any-of', 'all-of']).describe('Contract type: any-of (at least one) or all-of (all must exist)'),
     artefacts: s.array(s.string()).describe('Artefact type IDs this cycle reads'),
-  }).optional().describe('Input contract for this cycle'),
+  }).optional().describe('Input contract for this cycle. Omit for source cycles that start from the user goal; empty artefacts arrays are invalid.'),
   targets: s.array(s.string()).optional().describe('Downstream cycle IDs this cycle can route to'),
   humanAppraise: s.boolean().optional().describe('Include human-appraise in every iteration'),
   deadlockAppraise: s.boolean().optional().describe('Route to human-appraise on LLM appraiser deadlock'),
@@ -173,7 +173,7 @@ function cycleArgs(s) { return {
     read: s.array(s.string()).describe('Memory store keys this cycle can read'),
     write: s.array(s.string()).describe('Memory store keys this cycle can write'),
   }).optional().describe('Flow memory permissions'),
-  models: s.object({}).optional().describe('Per-stage model overrides (e.g. { forge: "openai/gpt-4o" })'),
+  models: s.object({}).optional().describe('Per-stage model overrides (e.g. { forge: "opencode-go/deepseek-v4-flash", appraise: "opencode-go/qwen3.6-plus" }). Preserve user-selected stage models.'),
   description: s.string().optional().describe('Prose description placed after frontmatter'),
 }; }
 

package/dist/.opencode/plugins/foundry-tools/orchestrate-tool.js

@@ -1,11 +1,8 @@
-import path from 'path';
 import { execFileSync } from 'child_process';
 import { randomUUID } from 'node:crypto';
-import { readFileSync, writeFileSync } from 'fs';
 import { signToken } from '../../../scripts/lib/token.js';
 import { readOrCreateSecret } from '../../../scripts/lib/secret.js';
 import { getCycleDefinition, getArtefactType } from '../../../scripts/lib/config.js';
-import { addArtefactRow } from '../../../scripts/lib/artefacts.js';
 import { stageBaseOf } from '../../../scripts/lib/stage-guard.js';
 import { finalizeStage } from '../../../scripts/lib/finalize.js';
 import { commitWithPolicy } from '../../../scripts/lib/git-bridge.js';
@@ -40,15 +37,6 @@ function createGitBridge(cwd) {
   };
 }
 
-function makeRegisterArtefact(cwd, cycleId) {
-  const workPath = path.join(cwd, 'WORK.md');
-  return ({ file, type, status }) => {
-    const text = readFileSync(workPath, 'utf-8');
-    const updated = addArtefactRow(text, { file, type, cycle: cycleId, status });
-    writeFileSync(workPath, updated, 'utf-8');
-  };
-}
-
 async function createFinalize(cwd, io) {
   return async ({ cycleId, stage, baseSha }) => {
     let cycleDoc;
@@ -78,7 +66,6 @@ async function createFinalize(cwd, io) {
       cycleDef,
       artefactTypes,
       io,
-      registerArtefact: makeRegisterArtefact(cwd, cycleId),
     });
     return result;
   };

package/dist/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [3.5.2] - 2026-05-23
+
+### Fixed
+
+- Guide agents to omit empty `inputs` for source cycles and preserve stage-specific model overrides when creating cycles.
+
+## [3.5.1] - 2026-05-22
+
+### Fixed
+
+- Run CI against the active Node release lines: 22.x, 24.x, 25.x, and 26.x.
+- Use Node 22-compatible `mock.module({ namedExports })` test mocks.
+
+## [3.5.0] - 2026-05-22
+
+### Changed
+
+- Add branch-based artefact discovery with `getArtefactFiles` and git change-state tracking.
+- Remove the `WORK.md` artefact table, artefact registration side effects, and per-artefact status updates.
+- Update quench, appraise, orchestration, plugin tools, and attestation to use branch artefact discovery.
+- Remove `foundry_artefacts_set_status` and update `foundry_artefacts_list` to return `{file, state}` entries.
+- Remove artefact table generation from new `WORK.md` files.
+- Update tests and docs for branch artefact discovery.
+
+### Fixed
+
+- Include all non-deleted artefact files in missing-model violation payloads.
+- Thread base-branch selection through artefact discovery contexts.
+
 ## [3.4.0] - 2026-05-20
 
 ### Changed

package/dist/docs/architecture.md

@@ -238,7 +238,7 @@ Input artefacts (files matching an input type's `file-patterns`) are read-only.
 When an unrecoverable error occurs (e.g. assay extractor abort, invalid JSONL, or memory-sync failure), the orchestrator marks `WORK.md` frontmatter with `status: failed` and a `reason`. The flow is then locked:
 
 - **Blocked tools.** All mutation tools refuse to run and return an error referencing the failure reason:
-  - **Lifecycle:** `foundry_stage_begin`, `foundry_orchestrate`, `foundry_workfile_create`, `foundry_artefacts_set_status`
+  - **Lifecycle:** `foundry_stage_begin`, `foundry_orchestrate`, `foundry_workfile_create`
   - **Stage work:** `foundry_assay_run`, `foundry_validate_run`
   - **Feedback writes:** `foundry_feedback_add`, `foundry_feedback_action`, `foundry_feedback_wontfix`, `foundry_feedback_resolve` (`foundry_feedback_list` remains callable)
   - **Appraiser selection:** `foundry_appraisers_select`

package/dist/docs/tools.md

@@ -59,7 +59,6 @@ state machine, see [`docs/concepts.md`](./concepts.md) and
 
 **Artefacts**
 - [`foundry_artefacts_list`](#foundry_artefacts_list)
-- [`foundry_artefacts_set_status`](#foundry_artefacts_set_status)
 
 **Feedback**
 - [`foundry_feedback_add`](#foundry_feedback_add)
@@ -326,41 +325,19 @@ flow** (escape hatch).
 
 ### `foundry_artefacts_list`
 
-> List artefacts from the WORK.md table. Optional `cycle` filter —
-> callers should always pass the current cycle to avoid stale rows.
+> List artefact changes on the current work branch for the current cycle.
 
 **Args:**
-- `cycle` (string, optional).
+- none.
 
-**Returns:** array of `{file, type, cycle, status, ...}` rows. `{error:
-"WORK.md not found"}` if missing.
+**Returns:** array of `{file, state}` entries. `{error: "WORK.md not found"}`
+if `WORK.md` is missing, or `{error: "current cycle not found in WORK.md frontmatter"}`
+if `WORK.md` has no current cycle.
 
 **Stage requirements:** none.
 
 **Side effects:** none.
 
-### `foundry_artefacts_set_status`
-
-> Update the status of an artefact in `WORK.md` (`done` | `blocked`
-> only).
-
-**Args:**
-- `file` (string, required): Artefact file path.
-- `status` (string, required): New status (`done` | `blocked`).
-
-**Returns:** `{ ok: true }`. On invalid input: `{ error: <message> }`.
-
-**Stage requirements:** requires no active stage. Refuses on failed
-flow.
-
-**Failure modes:**
-- Invalid status, unknown file, malformed table → error from
-  `setArtefactStatus`.
-
-**Side effects:** rewrites `WORK.md`.
-
----
-
 ## Feedback
 
 All feedback tools (except `foundry_feedback_list`) require an active

package/dist/docs/work-spec.md

@@ -168,11 +168,11 @@ A crash between the two steps leaves the live file untouched.
 | Frontmatter (`flow`, `cycle`) | `foundry_workfile_create` (flow skill) | updated in place as the flow advances between cycles |
 | Frontmatter (`stages`, `max-iterations`, `human-appraise`, `deadlock-appraise`, `deadlock-iterations`, `models`) | `foundry_orchestrate` (first call of each cycle, internally) | reset on each new cycle |
 | Goal | `foundry_workfile_create` (flow skill) | nobody |
-| Artefacts | the orchestrator's internal finalize step (after forge closes) | `foundry_artefacts_set_status` (orchestrator → `done`/`blocked`) |
+| Artefact files | forge stage writes files on disk | git tracks file changes; cycle-level state records completion or failure |
 | `WORK.feedback.yaml` | `foundry_feedback_add` (`quench` / `appraise` / `human-appraise`) | `foundry_feedback_action` / `foundry_feedback_wontfix` (forge), `foundry_feedback_resolve` (source stage / human-appraise override); sort writes only deadlocked snapshots |
 | `WORK.history.yaml` | `foundry_orchestrate` | `foundry_orchestrate` |
 
-Note: `foundry_artefacts_add` no longer exists as a public tool — artefact registration is automatic via the orchestrator's internal finalize step, which scans the git diff and registers files matching the output type's `file-patterns` as `draft`.
+Artefact files are discovered from branch changes matching the cycle output type's `file-patterns`.
 
 ## WORK.history.yaml
 

package/dist/scripts/appraise-module.js

@@ -11,8 +11,8 @@
  * so the orchestrator can re-sort and determine the next action.
  */
 
-import { getArtefactsForCycle } from './lib/artefacts.js';
-import { selectAppraisers, getLaws } from './lib/config.js';
+import { getArtefactFiles } from './lib/artefacts.js';
+import { selectAppraisers, getLaws, getCycleDefinition } from './lib/config.js';
 
 // ---------------------------------------------------------------------------
 // Public API — gather
@@ -27,6 +27,8 @@ import { selectAppraisers, getLaws } from './lib/config.js';
  * @param {string} ctx.cycleId
  * @param {object} ctx.io
  * @param {string} ctx.foundryDir
+ * @param {string} [ctx.baseBranch] - Git base branch for diff comparison,
+ *   defaults to 'main'.
  * @param {string} [ctx.defaultModel] - Fallback model when an appraiser has no
  *   explicit model.
  * @returns {Promise<{action: string, tasks: Array, stage: string, cycle: string}>}
@@ -36,12 +38,19 @@ export async function gatherAppraiseContext(ctx) {
     return violation('cycleId is required', []);
   }
 
-  const artefacts = getArtefactsForCycle(ctx.cycleId, ctx.io);
+  const cd = await getCycleDefinition(ctx.foundryDir, ctx.cycleId, ctx.io);
+  const outputType = cd.frontmatter['output-type'];
+  if (!outputType) {
+    return violation(`cycle ${ctx.cycleId} missing output-type field`, []);
+  }
+  const baseBranch = ctx.baseBranch || 'main';
+  const artefacts = await getArtefactFiles(ctx.foundryDir, outputType, ctx.io, { baseBranch });
   if (artefacts.length === 0) {
     return emptyDispatch(ctx.cycleId);
   }
 
-  const tasks = await collectTasks(artefacts, ctx);
+  const typedArtefacts = artefacts.map(artefact => ({ ...artefact, type: outputType }));
+  const tasks = await collectTasks(typedArtefacts, ctx);
 
   return {
     action: 'dispatch_multi',
@@ -91,7 +100,10 @@ async function resolveTypeEntry(typeId, cache, ctx) {
  * Build and append appraiser tasks for a single artefact.
  */
 function addTasksForArtefact(tasks, artefact, entry, ctx) {
-  const content = ctx.io.readFile(artefact.file);
+  let content = '';
+  if (artefact.state !== 'deleted') {
+    content = ctx.io.readFile(artefact.file);
+  }
 
   for (const appraiser of entry.appraisers) {
     const prompt = buildAppraiserPrompt({

package/dist/scripts/lib/artefacts.js

@@ -1,163 +1,166 @@
 /**
- * Artefacts table utilities for WORK.md.
+ * Artefact discovery and branch change utilities.
  *
- * Parses, adds rows to, and updates status in the markdown artefacts table.
+ * Resolves the branch base SHA, collects changed files on the flow branch,
+ * filters by artefact type file-patterns, and returns the artefact change set.
  */
 
-// --- Table line classifiers ---
+import { minimatch } from 'minimatch';
+import { sortPaths } from './attestation/hash.js';
+import { getArtefactType } from './config.js';
+
+// --- Shared branch artefact discovery ---
+
+const STATUS_HANDLERS = {
+  A: (parts) => [{ file: parts[1], state: 'new' }],
+  M: (parts) => [{ file: parts[1], state: 'modified' }],
+  T: (parts) => [{ file: parts[1], state: 'modified' }],
+  U: (parts) => [{ file: parts[1], state: 'modified' }],
+  D: (parts) => [{ file: parts[1], state: 'deleted' }],
+  R: (parts) => [
+    { file: parts[1], state: 'deleted' },
+    { file: parts[2], state: 'new' },
+  ],
+  C: (parts) => [{ file: parts[2], state: 'new' }],
+};
 
-function isTableHeader(line) {
-  return line.startsWith('| File');
-}
-
-function isTableSeparator(line) {
-  return line.startsWith('|---');
-}
-
-function isTableRow(line) {
-  return line.startsWith('|');
-}
-
-function parseTableRow(line) {
-  const cols = line.split('|').slice(1, -1).map(c => c.trim());
-  return cols.length >= 4 ? cols : null;
-}
-
-// --- Status validation ---
-
-function validateStatus(newStatus) {
-  if (newStatus === 'draft') {
-    throw new Error('status draft not permitted; artefacts are registered automatically during orchestration');
-  }
-  if (!['done', 'blocked'].includes(newStatus)) {
-    throw new Error(`invalid status: ${newStatus}`);
-  }
-}
-
-// --- Table boundary detection ---
-
-function findTableHeader(lines) {
-  for (let i = 0; i < lines.length; i++) {
-    if (isTableHeader(lines[i].trim())) return i;
-  }
-  return -1;
-}
-
-function findTableSeparator(lines, afterIdx) {
-  for (let i = afterIdx + 1; i < lines.length; i++) {
-    if (isTableSeparator(lines[i].trim())) return i;
-  }
-  return -1;
-}
-
-function getTableBounds(lines) {
-  const headerIdx = findTableHeader(lines);
-  if (headerIdx < 0) return null;
-  const sepIdx = findTableSeparator(lines, headerIdx);
-  if (sepIdx < 0) return null;
-  return { headerIdx, sepIdx };
+/**
+ * Parse a single git diff --name-status line into one or more { file, state } entries.
+ * Uses a lookup table to map status codes to handlers.
+ * @param {string} line - A line from git diff --name-status output
+ * @returns {Array<{file: string, state: string}>}
+ */
+function parseDiffStatusLine(line) {
+  const parts = line.split('\t');
+  const handler = STATUS_HANDLERS[parts[0][0]];
+  return handler ? handler(parts) : [];
 }
 
-function findTableEnd(lines, startIdx) {
-  for (let i = startIdx; i < lines.length; i++) {
-    const stripped = lines[i].trim();
-    if (!isTableRow(stripped)) return i;
+/**
+ * Parse git diff --name-status output into an array of { file, state } entries.
+ * @param {string} output - Raw output from git diff --name-status
+ * @returns {Array<{file: string, state: string}>}
+ */
+function parseDiffOutput(output) {
+  const entries = [];
+  if (!output) return entries;
+  for (const line of output.trim().split('\n')) {
+    if (!line) continue;
+    for (const entry of parseDiffStatusLine(line)) {
+      entries.push(entry);
+    }
   }
-  return lines.length;
-}
-
-function formatTableRow(cols) {
-  return '| ' + cols.join(' | ') + ' |';
+  return entries;
 }
 
 /**
- * Parse the artefacts markdown table from text.
- * @param {string} text
- * @returns {Array<{file: string, type: string, cycle: string, status: string}>}
+ * Collect changed files from the branch since a given base SHA.
+ * Combines committed, unstaged, staged, and untracked changes.
+ *
+ * Sources are ordered by increasing priority: committed, unstaged, staged, untracked.
+ * This function does not deduplicate per-file entries; call dedupeArtefactChanges for that.
+ *
+ * @param {string} branchBaseSha - The merge-base SHA for the branch
+ * @param {object} io - IO interface with exec
+ * @returns {Array<{file: string, state: string}>}
  */
-export function parseArtefactsTable(text) {
-  const lines = text.split('\n');
-  const bounds = getTableBounds(lines);
-  if (!bounds) return [];
-
-  const artefacts = [];
-  const endIdx = findTableEnd(lines, bounds.sepIdx + 1);
-
-  for (let i = bounds.sepIdx + 1; i < endIdx; i++) {
-    const cols = parseTableRow(lines[i].trim());
-    if (cols) {
-      artefacts.push({
-        file: cols[0],
-        type: cols[1],
-        cycle: cols[2],
-        status: cols[3],
-      });
+function getBranchChangedFiles(branchBaseSha, io) {
+  const changes = [];
+
+  // Diff-based sources: committed, unstaged, staged
+  changes.push(...parseDiffOutput(io.exec(['git', 'diff', '--name-status', `${branchBaseSha}..HEAD`])));
+  changes.push(...parseDiffOutput(io.exec(['git', 'diff', '--name-status'])));
+  changes.push(...parseDiffOutput(io.exec(['git', 'diff', '--cached', '--name-status'])));
+
+  // Untracked files (not in git)
+  const untracked = io.exec(['git', 'ls-files', '--others', '--exclude-standard']);
+  if (untracked) {
+    for (const file of untracked.trim().split('\n')) {
+      if (!file) continue;
+      changes.push({ file, state: 'new' });
     }
   }
 
-  return artefacts;
+  return changes;
 }
 
 /**
- * Add a row to the artefacts table.
- * @param {string} text - Full WORK.md text
- * @param {{file: string, type: string, cycle: string, status: string}} row
- * @returns {string} Updated text
+ * Deduplicate artefact changes, keeping the most recent state for each file.
+ * Because later git sources (staged, untracked) take precedence over earlier
+ * ones (committed), the last occurrence of a file wins.
+ *
+ * @param {Array<{file: string, state: string}>} changes
+ * @returns {Array<{file: string, state: string}>}
  */
-export function addArtefactRow(text, { file, type, cycle, status }) {
-  const lines = text.split('\n');
-  const bounds = getTableBounds(lines);
-
-  if (!bounds) {
-    throw new Error('Artefacts table not found');
+function dedupeArtefactChanges(changes) {
+  const seen = new Map();
+  for (const { file, state } of changes) {
+    seen.set(file, state);
   }
-
-  const endIdx = findTableEnd(lines, bounds.sepIdx + 1);
-  const insertAt = endIdx > bounds.sepIdx + 1 ? endIdx - 1 : bounds.sepIdx;
-  const newRow = `| ${file} | ${type} | ${cycle} | ${status} |`;
-  lines.splice(insertAt + 1, 0, newRow);
-  return lines.join('\n');
+  return Array.from(seen.entries()).map(([file, state]) => ({ file, state }));
 }
 
 /**
- * Update the status column for a specific file in the artefacts table.
- * @param {string} text - Full WORK.md text
- * @param {string} file - File name to match
- * @param {string} newStatus - New status value
- * @returns {string} Updated text
+ * Resolve the merge-base SHA between HEAD and a base branch.
+ * @param {object} io - IO interface with exec
+ * @param {string} [baseBranch='main'] - Base branch name
+ * @returns {string} The merge-base commit SHA
  */
-export function setArtefactStatus(text, file, newStatus) {
-  validateStatus(newStatus);
-
-  const lines = text.split('\n');
-  const bounds = getTableBounds(lines);
-
-  if (!bounds) {
-    throw new Error(`File not found in artefacts table: ${file}`);
+export function resolveBranchBaseSha(io, baseBranch = 'main') {
+  if (!io.exec) {
+    throw new Error('io.exec is required for resolveBranchBaseSha');
   }
-
-  const endIdx = findTableEnd(lines, bounds.sepIdx + 1);
-
-  for (let i = bounds.sepIdx + 1; i < endIdx; i++) {
-    const cols = parseTableRow(lines[i].trim());
-    if (cols && cols[0] === file) {
-      cols[3] = newStatus;
-      lines[i] = formatTableRow(cols);
-      return lines.join('\n');
-    }
+  const sha = io.exec(['git', 'merge-base', 'HEAD', baseBranch]).trim();
+  if (!sha) {
+    throw new Error(`Failed to resolve merge-base for HEAD and ${baseBranch}`);
   }
+  return sha;
+}
 
-  throw new Error(`File not found in artefacts table: ${file}`);
+/**
+ * Extract file-patterns from an artefact type definition frontmatter.
+ * Returns an empty array when frontmatter is absent or contains no patterns.
+ * @param {object} def - Artefact type definition with frontmatter
+ * @returns {Array<string>}
+ */
+function getFilePatterns(def) {
+  const fm = def.frontmatter;
+  return Array.isArray(fm && fm['file-patterns']) ? fm['file-patterns'] : [];
 }
 
 /**
- * Get draft artefacts for a specific cycle from the artefacts table.
- * @param {string} cycleId - Cycle ID to filter by
- * @param {object} io - IO interface
- * @returns {Array<{file: string, type: string, cycle: string, status: string}>}
+ * Get artefact files for a given artefact type using shared branch discovery.
+ *
+ * Reads the artefact type definition, resolves the branch base, collects changed
+ * files on the flow branch, filters by the type's file-patterns, and returns a
+ * deterministically sorted list of { file, state } entries.
+ *
+ * @param {string} foundryDir - Path to the foundry directory
+ * @param {string} typeId - Artefact type identifier
+ * @param {object} io - IO interface with exec, readFile, exists
+ * @param {object} [options={}] - Optional parameters
+ * @param {string} [options.baseBranch='main'] - Base branch for merge-base resolution
+ * @param {string} [options.branchBaseSha] - Pre-resolved merge-base SHA (takes precedence)
+ * @returns {Promise<Array<{file: string, state: string}>>}
  */
-export function getArtefactsForCycle(cycleId, io) {
-  const text = io.readFile('WORK.md');
-  const artefacts = parseArtefactsTable(text);
-  return artefacts.filter(a => a.cycle === cycleId && a.status === 'draft');
+export async function getArtefactFiles(foundryDir, typeId, io, options = {}) {
+  const def = await getArtefactType(foundryDir, typeId, io);
+  const patterns = getFilePatterns(def);
+
+  if (patterns.length === 0) return [];
+
+  const baseBranch = options.baseBranch || 'main';
+  const branchBaseSha = options.branchBaseSha || resolveBranchBaseSha(io, baseBranch);
+  const changedFiles = getBranchChangedFiles(branchBaseSha, io);
+  const changes = dedupeArtefactChanges(changedFiles);
+  const matching = changes.filter(({ file }) =>
+    patterns.some(pattern => minimatch(file, pattern))
+  );
+
+  // Sort deterministically by file path
+  const sorted = sortPaths(matching.map(({ file }) => file));
+  const order = new Map(sorted.map((file, idx) => [file, idx]));
+  const result = [...matching].sort((a, b) => order.get(a.file) - order.get(b.file));
+
+  return result;
 }