@really-knows-ai/foundry 2.3.2 → 3.0.1

package/dist/scripts/lib/memory/writes.js

@@ -0,0 +1,40 @@
+import { entRelName, edgeRelName, cozoStringLit } from './cozo.js';
+import { validateEntityWrite, validateEdgeWrite } from './validate.js';
+
+const lit = cozoStringLit;
+function vecLit(v) {
+  return `vec([${v.map((n) => Number(n).toString()).join(', ')}])`;
+}
+
+export async function putEntity(store, { type, name, value }, vocabulary, { embedder } = {}) {
+  validateEntityWrite({ type, name, value }, vocabulary);
+  const rel = entRelName(type);
+  if (embedder) {
+    const vectors = await embedder([value]);
+    const vec = vectors && vectors[0];
+    if (!Array.isArray(vec)) throw new Error('embedder did not return a vector');
+    await store.db.run(
+      `?[name, value, embedding] <- [[${lit(name)}, ${lit(value)}, ${vecLit(vec)}]]\n:put ${rel} { name => value, embedding }`,
+    );
+  } else {
+    await store.db.run(
+      `?[name, value] <- [[${lit(name)}, ${lit(value)}]]\n:put ${rel} { name => value }`,
+    );
+  }
+}
+
+export async function relate(store, { edge_type, from_type, from_name, to_type, to_name }, vocabulary) {
+  validateEdgeWrite({ edge_type, from_type, from_name, to_type, to_name }, vocabulary);
+  const rel = edgeRelName(edge_type);
+  await store.db.run(
+    `?[from_type, from_name, to_type, to_name] <- [[${lit(from_type)}, ${lit(from_name)}, ${lit(to_type)}, ${lit(to_name)}]]\n:put ${rel} { from_type, from_name, to_type, to_name }`,
+  );
+}
+
+export async function unrelate(store, { edge_type, from_type, from_name, to_type, to_name }, vocabulary) {
+  validateEdgeWrite({ edge_type, from_type, from_name, to_type, to_name }, vocabulary);
+  const rel = edgeRelName(edge_type);
+  await store.db.run(
+    `?[from_type, from_name, to_type, to_name] <- [[${lit(from_type)}, ${lit(from_name)}, ${lit(to_type)}, ${lit(to_name)}]]\n:rm ${rel} { from_type, from_name, to_type, to_name }`,
+  );
+}

package/{scripts → dist/scripts}/lib/pending.js

@@ -5,13 +5,18 @@ export function createPendingStore() {
     consume(nonce) {
       const meta = map.get(nonce);
       if (!meta) return null;
+      if (meta.exp < Date.now()) {
+        map.delete(nonce);
+        return null;
+      }
       map.delete(nonce);
-      if (meta.exp < Date.now()) return null;
       return meta;
     },
-    size() {
+    gc() {
       const now = Date.now();
       for (const [k, v] of map) if (v.exp < now) map.delete(k);
+    },
+    size() {
       return map.size;
     },
   };

package/dist/scripts/lib/secret.js

@@ -0,0 +1,59 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, openSync, writeSync, closeSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+
+// Lines that are considered equivalent to a `.foundry/` ignore rule.
+// Git treats `.foundry` and `.foundry/` slightly differently (the former matches
+// files too), but for our purpose any of these means the user is already
+// ignoring the runtime directory.
+const FOUNDRY_GITIGNORE_VARIANTS = new Set([
+  '.foundry',
+  '.foundry/',
+  '/.foundry',
+  '/.foundry/',
+]);
+
+/**
+ * Idempotently ensure `.foundry/` is listed in the project's `.gitignore`.
+ * Creates the file if absent. Comments (`#`-prefixed lines) are ignored when
+ * checking for an existing entry.
+ *
+ * @param {string} directory  Project root.
+ * @returns {boolean}  true if a line was appended, false if no change.
+ */
+export function ensureFoundryGitignored(directory) {
+  const path = join(directory, '.gitignore');
+  const exists = existsSync(path);
+  const current = exists ? readFileSync(path, 'utf-8') : '';
+  const present = current
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0 && !l.startsWith('#'));
+  if (present.some((l) => FOUNDRY_GITIGNORE_VARIANTS.has(l))) return false;
+  const tail = current.length === 0 || current.endsWith('\n') ? '' : '\n';
+  writeFileSync(path, current + tail + '.foundry/\n', 'utf-8');
+  return true;
+}
+
+export function readOrCreateSecret(directory) {
+  const dir = join(directory, '.foundry');
+  const file = join(dir, '.secret');
+  // Ensure `.gitignore` lists `.foundry/` *before* the secret hits disk so the
+  // stage-token key is never momentarily visible as an untracked file.
+  ensureFoundryGitignored(directory);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const bytes = randomBytes(32);
+  let fd;
+  try {
+    fd = openSync(file, 'wx', 0o600);
+  } catch (err) {
+    if (err.code === 'EEXIST') return readFileSync(file);
+    throw err;
+  }
+  try {
+    writeSync(fd, bytes);
+  } finally {
+    closeSync(fd);
+  }
+  return bytes;
+}

package/{scripts → dist/scripts}/lib/slug.js

@@ -22,8 +22,9 @@ export function slugify(input) {
     .normalize('NFD')
     .replace(/\p{Diacritic}/gu, '')
     .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '');
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean)
+    .join('-');
 
   if (slug.length === 0) {
     throw new Error(`slugify: input produced empty slug (input: ${JSON.stringify(input)})`);

package/dist/scripts/lib/snapshot/finish.js

@@ -0,0 +1,103 @@
+/**
+ * finishDryRun — captures a dry-run branch as an on-disk snapshot under
+ * `.snapshots/<runId>/` on the parent config branch, then deletes the
+ * dry-run branch. Implements §11.3 of the config-branch design.
+ *
+ * Recovery: If snapshot write fails (line 73), the function returns early
+ * with {ok: false, ...} whilst still on the dry-run branch. The dry-run
+ * branch and partial `.snapshots/<runId>/` directory (if any) remain.
+ * Manual cleanup: delete the dry-run branch with `git branch -D <branch>`
+ * and remove the incomplete snapshot directory under `.snapshots/` if present.
+ */
+
+import { ulid } from '../ulid.js';
+import { branchSlug } from '../tracing.js';
+import { renderReadme } from './render.js';
+
+const WORK_FILES = ['WORK.md', 'WORK.history.yaml', 'WORK.feedback.yaml'];
+
+async function checkCleanTree(execFile) {
+  const status = await execFile(['status', '--porcelain', '--untracked-files=no']);
+  const trimmed = status.trim();
+  if (trimmed.length > 0) {
+    const dirty = trimmed.split('\n').map(l => l.slice(3).trim()).filter(Boolean);
+    return { ok: false, error: 'dirty worktree: cannot finish dry-run with uncommitted tracked changes', dirty };
+  }
+  return { ok: true };
+}
+
+function deriveParent(branch) {
+  const m = branch.match(/^dry-run\/([^/]+)\/[^/]+$/);
+  if (!m) return { ok: false, error: `cannot derive parent config branch from '${branch}'` };
+  return { ok: true, parent: `config/${m[1]}` };
+}
+
+async function captureWorkFiles(io) {
+  const workCapture = {};
+  for (const f of WORK_FILES) {
+    if (await io.exists(f)) {
+      workCapture[f] = await io.readFile(f);
+    }
+  }
+  return workCapture;
+}
+
+async function captureTrace(io, branch) {
+  const traceFile = `.foundry/trace/${branchSlug(branch)}.jsonl`;
+  if (await io.exists(traceFile)) return { traceFile, traceText: await io.readFile(traceFile) };
+  return { traceFile, traceText: '' };
+}
+
+async function writeSnapshot({ io, snapDir, readme, workCapture, diffPatch, traceText }) {
+  await io.mkdirp(`${snapDir}/work`);
+  await io.writeFile(`${snapDir}/README.md`, readme);
+  for (const [name, body] of Object.entries(workCapture)) {
+    await io.writeFile(`${snapDir}/work/${name}`, body);
+  }
+  await io.writeFile(`${snapDir}/diff.patch`, diffPatch);
+  await io.writeFile(`${snapDir}/trace.jsonl`, traceText);
+}
+
+async function truncateTraceIfExists(io, traceFile) {
+  if (await io.exists(traceFile)) await io.writeFile(traceFile, '');
+}
+
+async function cleanupDryRunBranch(execFile, parent, branch) {
+  await execFile(['checkout', parent]);
+  await execFile(['branch', '-D', branch]);
+}
+
+export async function finishDryRun({ message, branch, io, execFile }) {
+  // 1. Verify clean tracked tree.
+  const cleanCheck = await checkCleanTree(execFile);
+  if (!cleanCheck.ok) return cleanCheck;
+
+  // 2. Compute parent.
+  const parentResult = deriveParent(branch);
+  if (!parentResult.ok) return parentResult;
+  const parent = parentResult.parent;
+
+  // 3-5. Capture diff, WORK files, and trace.
+  const diffPatch = await execFile(['diff', `${parent}...HEAD`]);
+  const workCapture = await captureWorkFiles(io);
+  const { traceFile, traceText } = await captureTrace(io, branch);
+
+  // 6-7. Build runId, snapshot dir, and render README.
+  const runId = `${branchSlug(branch)}-${ulid()}`;
+  const snapDir = `.snapshots/${runId}`;
+  const readme = renderReadme({ branch, parent, message, workfile: workCapture['WORK.md'] ?? '', traceText });
+
+  // 8. Materialise snapshot directory. If any write fails, preserve dry-run branch.
+  try {
+    await writeSnapshot({ io, snapDir, readme, workCapture, diffPatch, traceText });
+  } catch (err) {
+    return { ok: false, error: `snapshot write failed: ${err.message}` };
+  }
+
+  // 9-11. Checkout parent, delete dry-run branch, truncate trace.
+  await cleanupDryRunBranch(execFile, parent, branch);
+  await truncateTraceIfExists(io, traceFile);
+
+  // 12.
+  return { ok: true, runId, snapshotPath: snapDir, branch: parent };
+}

package/dist/scripts/lib/snapshot/inspect.js

@@ -0,0 +1,253 @@
+/**
+ * Snapshot inspection library: list, show, delete, prune.
+ *
+ * Operates on `.snapshots/<runId>/` directories produced by finishDryRun.
+ * IO contract: an injected `io` object exposing async `exists`, `readFile`,
+ * `readdir`, and `rm`. Pure logic; no direct fs imports.
+ */
+
+import { parseFrontmatter } from '../workfile.js';
+import { decodeUlidTime } from '../ulid.js';
+
+const REQUIRED = ['README.md', 'work/WORK.md', 'diff.patch', 'trace.jsonl'];
+
+const META_FIELDS = ['branch', 'parent', 'flow', 'goal', 'startedAt', 'finishedAt', 'exitReason'];
+
+// Fields that should be normalised to ISO strings if YAML parsed them as Date.
+const DATE_FIELDS = new Set(['startedAt', 'finishedAt']);
+
+function normaliseFieldValue(k, raw) {
+  if (raw === undefined) return null;
+  let v = raw;
+  if (v instanceof Date) v = v.toISOString();
+  if (DATE_FIELDS.has(k) && v === 'null') v = null;
+  return v;
+}
+
+function normaliseMeta(fm) {
+  const out = {};
+  for (const k of META_FIELDS) {
+    out[k] = normaliseFieldValue(k, fm[k]);
+  }
+  return out;
+}
+
+/**
+ * Compute the list of REQUIRED files missing from a snapshot directory.
+ */
+async function missingFiles(io, dir) {
+  const missing = [];
+  for (const rel of REQUIRED) {
+    if (!(await io.exists(`${dir}/${rel}`))) missing.push(rel);
+  }
+  return missing;
+}
+
+async function readSnapshotMeta(io, runId) {
+  const dir = `.snapshots/${runId}`;
+  const missing = await missingFiles(io, dir);
+
+  if (missing.includes('README.md')) {
+    return { runId, error: 'incomplete', missing };
+  }
+
+  const readmeText = await io.readFile(`${dir}/README.md`);
+  const fm = parseFrontmatter(readmeText) || {};
+
+  const entry = { runId, ...normaliseMeta(fm) };
+
+  if (missing.length > 0) {
+    entry.error = 'incomplete';
+    entry.missing = missing;
+  }
+  return entry;
+}
+
+function compareStartedAtDesc(a, b) {
+  const av = a.startedAt;
+  const bv = b.startedAt;
+  if (!av && !bv) return 0;
+  if (!av) return 1;
+  if (!bv) return -1;
+  return compareTimestamps(av, bv);
+}
+
+function compareTimestamps(av, bv) {
+  if (av < bv) return 1;
+  if (av > bv) return -1;
+  return 0;
+}
+
+/**
+ * List all snapshots under `.snapshots/`, sorted by startedAt desc.
+ * Returns [] if `.snapshots/` does not exist.
+ */
+export async function listSnapshots({ io }) {
+  if (!(await io.exists('.snapshots'))) return [];
+  const entries = await io.readdir('.snapshots');
+  const out = [];
+  for (const runId of entries) {
+    out.push(await readSnapshotMeta(io, runId));
+  }
+  // Sort by startedAt desc; missing/null sort last.
+  out.sort(compareStartedAtDesc);
+  return out;
+}
+
+function classifyPlusLine(line) {
+  return line[1] === '+' ? null : 'insertion';
+}
+
+function classifyMinusLine(line) {
+  return line[1] === '-' ? null : 'deletion';
+}
+
+function classifyDiffLine(line) {
+  if (line.startsWith('diff --git ')) return 'file';
+  if (line.startsWith('+')) return classifyPlusLine(line);
+  if (line.startsWith('-')) return classifyMinusLine(line);
+  return null;
+}
+
+function parseDiffStats(text) {
+  let files = 0;
+  let insertions = 0;
+  let deletions = 0;
+  for (const line of text.split('\n')) {
+    const kind = classifyDiffLine(line);
+    if (kind === 'file') files++;
+    else if (kind === 'insertion') insertions++;
+    else if (kind === 'deletion') deletions++;
+  }
+  return { files, insertions, deletions };
+}
+
+function parseTraceStats(text) {
+  const lines = text.split('\n').filter(l => l.length > 0);
+  if (lines.length === 0) return { lineCount: 0, firstTs: null, lastTs: null };
+  const parseTs = (line) => {
+    try {
+      return JSON.parse(line)?.ts ?? null;
+    } catch {
+      return null;
+    }
+  };
+  return {
+    lineCount: lines.length,
+    firstTs: parseTs(lines[0]),
+    lastTs: parseTs(lines[lines.length - 1]),
+  };
+}
+
+async function readReadmeRaw(io, dir) {
+  return await io.readFile(`${dir}/README.md`);
+}
+
+async function readDiffStats(io, dir) {
+  return parseDiffStats(await io.readFile(`${dir}/diff.patch`));
+}
+
+async function readTraceStats(io, dir) {
+  return parseTraceStats(await io.readFile(`${dir}/trace.jsonl`));
+}
+
+async function readMetadata(io, dir, missing) {
+  if (missing.includes('README.md')) return {};
+  const readmeText = await readReadmeRaw(io, dir);
+  return parseFrontmatter(readmeText) || {};
+}
+
+async function buildSnapshotParts(io, dir, missing) {
+  const fm = await readMetadata(io, dir, missing);
+  const metadata = normaliseMeta(fm);
+
+  const diff = missing.includes('diff.patch')
+    ? { files: 0, insertions: 0, deletions: 0 }
+    : await readDiffStats(io, dir);
+
+  const trace = missing.includes('trace.jsonl')
+    ? { lineCount: 0, firstTs: null, lastTs: null }
+    : await readTraceStats(io, dir);
+
+  const readmeText = missing.includes('README.md') ? null : await readReadmeRaw(io, dir);
+  return { readmeText, metadata, diff, trace };
+}
+
+/**
+ * Return a structured summary of a single snapshot.
+ */
+export async function showSnapshot({ runId, io }) {
+  const dir = `.snapshots/${runId}`;
+  if (!(await io.exists(dir))) {
+    return { runId, error: 'unknown_runId', missing: [...REQUIRED] };
+  }
+
+  const missing = await missingFiles(io, dir);
+  const parts = await buildSnapshotParts(io, dir, missing);
+  return { runId, readme: parts.readmeText, metadata: parts.metadata, diff: parts.diff, trace: parts.trace, missing };
+}
+
+/**
+ * Delete a snapshot directory. Requires {confirm: true}.
+ */
+export async function deleteSnapshot({ runId, io, confirm }) {
+  const dir = `.snapshots/${runId}`;
+  if (!(await io.exists(dir))) {
+    return { ok: false, error: `unknown runId '${runId}'` };
+  }
+  if (confirm !== true) {
+    return {
+      ok: false,
+      error: 'foundry_snapshot_delete requires {confirm: true}',
+      planned: { runId, path: dir },
+    };
+  }
+  await io.rm(dir, { recursive: true });
+  return { ok: true, runId, removed: dir };
+}
+
+function isExpiredCandidate(runId, cutoff) {
+  if (runId.length < 26) return false;
+  const ulidPart = runId.slice(-26);
+  try {
+    return decodeUlidTime(ulidPart) < cutoff;
+  } catch {
+    return false;
+  }
+}
+
+async function findExpiredCandidates(io, cutoff) {
+  if (!(await io.exists('.snapshots'))) return [];
+  const entries = await io.readdir('.snapshots');
+  return entries.filter(id => isExpiredCandidate(id, cutoff));
+}
+
+async function deleteSnapshots(io, candidates) {
+  for (const runId of candidates) {
+    await io.rm(`.snapshots/${runId}`, { recursive: true });
+  }
+}
+
+/**
+ * Prune snapshots older than `olderThanDays`. Time is decoded from the
+ * trailing 26-char ULID of each runId. Entries with malformed ULIDs are
+ * skipped. Requires {confirm: true} to actually delete.
+ */
+export async function pruneSnapshots({ olderThanDays, io, confirm, now = Date.now() }) {
+  const cutoff = now - olderThanDays * 86400000;
+  const cutoffIso = new Date(cutoff).toISOString();
+
+  const candidates = await findExpiredCandidates(io, cutoff);
+
+  if (confirm !== true) {
+    return {
+      ok: false,
+      error: 'foundry_snapshot_prune requires {confirm: true}',
+      candidates,
+      cutoff: cutoffIso,
+    };
+  }
+
+  await deleteSnapshots(io, candidates);
+  return { ok: true, removed: candidates };
+}

package/dist/scripts/lib/snapshot/render.js

@@ -0,0 +1,55 @@
+/**
+ * Render a dry-run snapshot README.md from branch metadata, workfile, and trace.
+ */
+
+import { parseFrontmatter } from '../workfile.js';
+
+function extractTimestamps(traceText) {
+  const lines = traceText.split('\n').filter(l => l.length > 0);
+  if (lines.length === 0) return { startedAt: null, finishedAt: null };
+
+  const parseTs = (line) => {
+    try {
+      const obj = JSON.parse(line);
+      return obj?.ts ?? null;
+    } catch {
+      return null;
+    }
+  };
+
+  return {
+    startedAt: parseTs(lines[0]),
+    finishedAt: parseTs(lines[lines.length - 1]),
+  };
+}
+
+function formatValue(v) {
+  if (v === null || v === undefined) return 'null';
+  return String(v);
+}
+
+export function renderReadme({ branch, parent, message, workfile, traceText }) {
+  const fm = parseFrontmatter(workfile) || {};
+  const { startedAt, finishedAt } = extractTimestamps(traceText);
+
+  // JSON.stringify the goal string to produce YAML-safe quoted output.
+  // Goals often contain colons, which would break YAML parsing without quotes.
+  const goalRaw = fm.goal;
+  const goalRendered = typeof goalRaw === 'string'
+    ? JSON.stringify(goalRaw)
+    : 'null';
+
+  const lines = [
+    '---',
+    `branch: ${branch}`,
+    `parent: ${parent}`,
+    `flow: ${formatValue(fm.flow)}`,
+    `goal: ${goalRendered}`,
+    `startedAt: ${formatValue(startedAt)}`,
+    `finishedAt: ${formatValue(finishedAt)}`,
+    `exitReason: ${fm.status ?? 'unknown'}`,
+    '---',
+  ];
+
+  return `${lines.join('\n')}\n\n# Dry-run snapshot\n\n${message}\n`;
+}

package/dist/scripts/lib/sort-fs-check.js

@@ -0,0 +1,121 @@
+/**
+ * Sort filesystem-check helpers — git-backed routines that verify which
+ * files were modified during a stage and that prior stage commits are clean.
+ *
+ * Extracted from `src/scripts/sort.js` to keep that file under the
+ * configured `max-lines` limit and to lower per-function complexity.
+ */
+
+import { readFileSync, writeFileSync, existsSync, renameSync } from 'fs';
+import { execFileSync } from 'child_process';
+
+import { minimatch } from 'minimatch';
+import { parseFrontmatter } from './workfile.js';
+
+export const defaultIO = {
+  readFile: (p) => readFileSync(p, 'utf-8'),
+  writeFile: (p, c) => writeFileSync(p, c),
+  rename: (from, to) => renameSync(from, to),
+  exists: (p) => existsSync(p),
+  exec: (argv) => execFileSync(argv[0], argv.slice(1), { encoding: 'utf8' }),
+};
+
+function findSortCommitSha(log, cycle) {
+  const sortPattern = `[${cycle}] sort:`;
+  for (const line of log.trim().split('\n')) {
+    if (line.includes(sortPattern)) {
+      return line.split(' ', 1)[0];
+    }
+  }
+  return null;
+}
+
+export function getModifiedFiles(cycle, io = defaultIO) {
+  try {
+    const log = io.exec(['git', 'log', '--oneline', '-20']);
+    const sortSha = findSortCommitSha(log, cycle);
+    if (!sortSha) return [];
+    const output = io.exec(['git', 'diff', '--name-only', '--no-renames', '-z', sortSha, 'HEAD']);
+    return output.split('\0').filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+export function globMatch(filePath, pattern) {
+  return minimatch(filePath, pattern);
+}
+
+function resolveForgePatterns(foundryDir, cycleDef, io) {
+  const cycleText = io.readFile(cycleDef);
+  const cycleFm = parseFrontmatter(cycleText);
+  const outputType = cycleFm['output-type'];
+  if (!outputType) return null;
+
+  const artDefPath = `${foundryDir}/artefacts/${outputType}/definition.md`;
+  if (!io.exists(artDefPath)) return null;
+
+  const artText = io.readFile(artDefPath);
+  const artFm = parseFrontmatter(artText);
+  return artFm['file-patterns'] || [];
+}
+
+function tryResolveForgePatterns(foundryDir, cycleDef, io) {
+  try {
+    return resolveForgePatterns(foundryDir, cycleDef, io);
+  } catch {
+    return null;
+  }
+}
+
+export function getAllowedPatterns(lastBase, foundryDir, cycleDef, io = defaultIO) {
+  const always = ['WORK.md', 'WORK.feedback.yaml', 'WORK.history.yaml'];
+  if (lastBase === 'assay') return [...always, '.foundry/**', 'foundry-memory/**'];
+  if (lastBase !== 'forge') return always;
+  const filePatterns = tryResolveForgePatterns(foundryDir, cycleDef, io);
+  return filePatterns ? [...always, ...filePatterns] : always;
+}
+
+export function checkModifiedFiles(lastBase, foundryDir, cycleDef, cycle, io = defaultIO) {
+  const allowedPatterns = getAllowedPatterns(lastBase, foundryDir, cycleDef, io);
+  const modified = getModifiedFiles(cycle, io);
+
+  if (modified.length === 0) {
+    return { ok: true, violations: [] };
+  }
+
+  const violations = modified.filter(f =>
+    !allowedPatterns.some(pattern => globMatch(f, pattern))
+  );
+
+  return { ok: violations.length === 0, violations };
+}
+
+/**
+ * Return a list of tool-managed files that have uncommitted changes
+ * (modified, staged, or untracked) in the working tree.
+ *
+ * Tool-managed files are WORK.md, WORK.feedback.yaml, WORK.history.yaml,
+ * and anything under .foundry/. `foundry_orchestrate` is the sole writer
+ * of these between stages, and every stage commit is performed internally
+ * by the orchestrator's git bridge (the previously-public
+ * `foundry_git_commit` tool was deregistered in v2.3.0). If this function
+ * returns a non-empty list at the start of a sort invocation, a prior
+ * stage's commit was skipped or aborted.
+ */
+export function getDirtyToolManagedFiles(io = defaultIO) {
+  try {
+    const output = io.exec([
+      'git', 'status', '--porcelain', '-z', '--',
+      'WORK.md', 'WORK.feedback.yaml', 'WORK.history.yaml', '.foundry',
+    ]);
+    return output
+      .split('\0')
+      .map(line => line.trim())
+      .filter(Boolean)
+      .map(line => line.replace(/^[\sMADRCU?!]+/, '').trim())
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}