@really-knows-ai/foundry 3.3.9 → 3.5.1

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/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/.opencode/plugins/foundry-tools/validate-tools.js

@@ -1,109 +1,10 @@
-import { execSync } from 'child_process';
-import { readdir } from 'fs/promises';
-import { join, relative, sep } from 'path';
-import { minimatch } from 'minimatch';
-import { getLawsForQuench, getArtefactType } from '../../../scripts/lib/config.js';
-import { parseValidatorJsonl } from '../../../scripts/lib/validator-jsonl.js';
+import { join } from 'path';
 import { makeIO, branchIoFactory, asyncIoFactory, flowBranchGuard } from './helpers.js';
 import { guarded, notFailedGuard } from '../../../scripts/lib/guards.js';
+import { performValidation } from '../../../scripts/lib/validation.js';
 
 const gateNotFailed = notFailedGuard(makeIO);
 
-/**
- * Shell-quote a string for POSIX `/bin/sh` so it is treated as a single literal
- * argument. Wraps the value in single quotes and escapes any embedded single
- * quotes via the `'\''` idiom. Safe for arbitrary file paths including ones
- * containing spaces, semicolons, `$()`, backticks, quotes, and newlines.
- */
-function shellQuote(value) {
-  return "'" + String(value).replace(/'/g, "'\\''") + "'";
-}
-
-/**
- * Execute a validator command and parse its output.
- */
-async function executeValidator(expanded, worktree, patterns) {
-  try {
-    const output = execSync(expanded, {
-      cwd: worktree,
-      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-    const { Readable } = await import('stream');
-    const stream = Readable.from([output]);
-    return await parseValidatorJsonl(stream, patterns);
-  } catch (err) {
-    // Validator command failed - prefer stdout for JSONL (tools like rg exit 1 with results on stdout)
-    const output = (err.stdout || err.stderr || err.message || '').trim();
-    const { Readable } = await import('stream');
-    const stream = Readable.from([output]);
-    return await parseValidatorJsonl(stream, patterns);
-  }
-}
-
-/**
- * Run all validators for laws and collect results.
- *
- * Aggregates per-validator parse results into a single structured payload:
- * - `items`: each successfully parsed feedback item, annotated with the
- *   `lawId` and `validatorId` it came from. The quench skill consumes this
- *   to call `foundry_feedback_add` with tag `law:<lawId>:<validatorId>`.
- * - `errors`: validator-level errors split by type. `parse` for malformed
- *   JSON or missing required fields, `pattern-mismatch` for files that
- *   didn't match the artefact type's `file-patterns`.
- */
-async function runValidators(laws, patterns, substitutions, worktree) {
-  const results = {
-    validatorsRun: 0,
-    items: [],
-    errors: [],
-  };
-
-  for (const law of laws) {
-    if (!law.validators || law.validators.length === 0) continue;
-    await runLawValidators(law, patterns, substitutions, worktree, results);
-  }
-
-  return results;
-}
-
-/**
- * Run validators for a single law.
- */
-async function runLawValidators(law, patterns, substitutions, worktree, results) {
-  for (const validator of law.validators) {
-    // Skip iff command uses {files} and there are no matching files.
-    // {pattern}-only and verbatim commands always run.
-    if (substitutions.files === '' && /(?:^|\s)\{files\}(?=\s|$)/.test(validator.command)) {
-      continue;
-    }
-    results.validatorsRun++;
-    const expanded = expandValidatorCommand(validator.command, substitutions);
-    const parseResult = await executeValidator(expanded, worktree, patterns);
-    collectValidatorResult(parseResult, law.id, validator.id, results);
-  }
-}
-
-/**
- * Fold a single validator's parse result into the aggregate results.
- *
- * Items always flow through annotated with their `lawId` and `validatorId`,
- * so the caller can construct `law:<lawId>:<validatorId>` feedback tags.
- * Errors are surfaced with their type so the caller can distinguish parse
- * failures from file-pattern mismatches.
- */
-function collectValidatorResult(parseResult, lawId, validatorId, results) {
-  for (const item of parseResult.items) {
-    results.items.push({ lawId, validatorId, ...item });
-  }
-  for (const message of parseResult.parseErrors) {
-    results.errors.push({ lawId, validatorId, type: 'parse', message });
-  }
-  for (const message of parseResult.patternErrors) {
-    results.errors.push({ lawId, validatorId, type: 'pattern-mismatch', message });
-  }
-}
-
 export function createValidateTools({ tool }) {
   return {
     foundry_validate_run: tool({
@@ -120,152 +21,14 @@ export function createValidateTools({ tool }) {
 
 async function executeValidateRun(args, context) {
   try {
-    return await performValidation(args, context);
+    const io = makeIO(context.worktree);
+    const foundryDir = join(context.worktree, 'foundry');
+    const result = await performValidation({ typeId: args.typeId, io, foundryDir });
+    return JSON.stringify(result);
   } catch (err) {
     return JSON.stringify({ ok: false, error: `foundry_validate_run: ${err.message}` });
   }
 }
 
-/**
- * Perform actual validation work.
- */
-async function getValidationPatterns(foundryDir, typeId, io) {
-  const artType = await getArtefactType(foundryDir, typeId, io);
-  return artType.frontmatter['file-patterns'] || [];
-}
-
-async function performValidation(args, context) {
-  const io = makeIO(context.worktree);
-  const foundryDir = join(context.worktree, 'foundry');
-
-  let patterns;
-  try {
-    patterns = await getValidationPatterns(foundryDir, args.typeId, io);
-  } catch (err) {
-    return JSON.stringify({ ok: false, error: err.message });
-  }
-
-  const validationErr = validatePatterns(patterns, args.typeId);
-  if (validationErr) return JSON.stringify(validationErr);
-
-  const laws = await getLawsForQuench(foundryDir, io, { typeId: args.typeId });
-  if (!laws?.length) {
-    return JSON.stringify({ ok: true, validatorsRun: 0, items: [], errors: [] });
-  }
-  return runValidatorsAndReport(laws, patterns, context.worktree);
-}
-
-/**
- * Run validators and report results.
- */
-async function runValidatorsAndReport(laws, patterns, worktree) {
-  const expandedFiles = await expandPatterns(patterns, worktree);
-  const substitutions = {
-    pattern: patterns.map(shellQuote).join(' '),
-    files: expandedFiles.map(shellQuote).join(' '),
-  };
-  const results = await runValidators(laws, patterns, substitutions, worktree);
-
-  return JSON.stringify({
-    ok: results.errors.length === 0,
-    validatorsRun: results.validatorsRun,
-    items: results.items,
-    errors: results.errors,
-  });
-}
-
-/**
- * Validate file patterns.
- */
-function validatePatterns(patterns, typeId) {
-  if (!Array.isArray(patterns) || patterns.length === 0) {
-    return { ok: false, error: `Artefact type ${typeId} has no file-patterns` };
-  }
-  return null;
-}
-
-const SKIP_DIRS = new Set(['node_modules', '.git']);
-
-function toPosix(p) {
-  return sep === '/' ? p : p.split(sep).join('/');
-}
-
-async function readdirSafe(dir) {
-  try {
-    return await readdir(dir, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-}
-
-/**
- * Recursively walk `dir` and yield POSIX-style paths relative to `root`.
- * Skips `node_modules` and `.git` for speed; the artefacts we validate live
- * elsewhere.
- */
-async function* walkFiles(root, dir) {
-  for (const entry of await readdirSafe(dir)) {
-    const full = join(dir, entry.name);
-    if (entry.isDirectory() && !SKIP_DIRS.has(entry.name)) {
-      yield* walkFiles(root, full);
-    } else if (entry.isFile()) {
-      yield toPosix(relative(root, full));
-    }
-  }
-}
-
-function fileMatchesAnyPattern(rel, patterns) {
-  for (const pattern of patterns) {
-    if (minimatch(rel, pattern)) return true;
-  }
-  return false;
-}
-
-/**
- * Expand glob patterns to actual files in the worktree.
- *
- * Implemented over `readdir` + `minimatch` so we work on Node 20, which lacks
- * `fs/promises.glob` (added in Node 22).
- */
-async function expandPatterns(patterns, worktree) {
-  const files = new Set();
-  for await (const rel of walkFiles(worktree, worktree)) {
-    if (fileMatchesAnyPattern(rel, patterns)) {
-      files.add(rel);
-    }
-  }
-  return Array.from(files).sort();
-}
-
-/**
- * Expand validator command by replacing {pattern} and {files} placeholders.
- *
- * - {pattern} → space-separated, shell-quoted globs from the artefact
- *   type's `file-patterns:` array (e.g. "'haikus/*.md' 'drafts/*.md'").
- * - {files}   → space-separated, shell-quoted matching file paths in the
- *   worktree (e.g. "'haikus/one.md' 'haikus/two.md'").
- *
- * Both placeholders are recognised only as standalone tokens, bounded
- * by whitespace or start/end of string. Surrounding single or double
- * quotes around the placeholder are stripped first so authors can
- * write `rg "{pattern}"` for readability.
- *
- * @param {string} command
- * @param {{ pattern: string, files: string }} substitutions
- * @returns {string}
- */
-export function expandValidatorCommand(command, { pattern, files }) {
-  let cmd = command
-    .replace(/"\{pattern\}"/g, '{pattern}')
-    .replace(/'\{pattern\}'/g, '{pattern}')
-    .replace(/"\{files\}"/g, '{files}')
-    .replace(/'\{files\}'/g, '{files}');
-
-  cmd = cmd.replace(/(?:^|\s)\{pattern\}(?=\s|$)/g, (match) =>
-    match.startsWith('{') ? pattern : ' ' + pattern);
-
-  cmd = cmd.replace(/(?:^|\s)\{files\}(?=\s|$)/g, (match) =>
-    match.startsWith('{') ? files : ' ' + files);
-
-  return cmd;
-}
+// Re-export for existing tests (validator-command-expansion.test.js)
+export { expandValidatorCommand } from '../../../scripts/lib/validation.js';

package/dist/CHANGELOG.md

@@ -1,5 +1,72 @@
 # Changelog
 
+## [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
+
+- **Quench runs as an internal orchestrator module.** Quench no longer
+  dispatches an LLM subagent — it runs validators directly within the
+  orchestrator, posting feedback and resolving prior items without any
+  model involvement. A single `foundry_orchestrate` call handles the
+  full quench stage inline.
+- **Appraise dispatch moves into the orchestrator.** Instead of
+  dispatching a single appraise subagent that can't use `task`, the
+  orchestrator gathers context internally, returns a `dispatch_multi`
+  action with pre-built prompts, and the LLM dispatches individual
+  appraiser subagents in parallel. After dispatch, the orchestrator
+  consolidates results internally — unioning, de-duplicating, and
+  posting feedback — all within the `foundry_orchestrate` loop.
+- **New `dispatch_multi` action and `lastResults` input.** The
+  `foundry_orchestrate` tool now returns `action: "dispatch_multi"`
+  with `tasks: [{subagent_type, prompt}, ...]` and accepts
+  `lastResults: [{ok, output?, error?}, ...]` for consolidating
+  multi-dispatch results. Mutual exclusivity with `lastResult` is
+  enforced.
+- **Stage model fallback.** When a cycle's `models:` map omits a stage,
+  the orchestrator falls back to the caller's `defaultModel`, then
+  `models.default`, then any available model in the map.
+
+### Added
+
+- `src/scripts/quench-module.js` — `runQuench(ctx)` runs validators
+  deterministically with no LLM.
+- `src/scripts/appraise-module.js` — `gatherAppraiseContext(ctx)` and
+  `consolidateAppraise(ctx, lastResults)` for multi-appraiser dispatch.
+- `src/scripts/lib/validation.js` — extracted `performValidation` and
+  related functions from `validate-tools.js`.
+- `getArtefactsForCycle()` on `src/scripts/lib/artefacts.js`.
+- `DISPATCH_MULTI_ACTION`, `validateDispatchMulti`, and
+  `buildDispatchMultiResponse` on `orchestrate-cycle.js`.
+- `guardLastResults()` and `dispatchByRoute()` in `orchestrate.js`.
+- Defensive guards in `handleSortResult` for quench and appraise routes.
+- Integration tests: `tests/orchestrate-quench.integration.test.js`,
+  `tests/orchestrate-appraise.integration.test.js`,
+  `tests/orchestrate-contract.test.js`.
+- Unit tests: `tests/quench-module.test.js`, `tests/appraise-module.test.js`.
+
 ## [3.3.9] - 2026-05-19
 
 ### Fixed

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