@really-knows-ai/foundry 2.1.0 → 2.2.1

package/scripts/lib/feedback.js

@@ -3,6 +3,7 @@
  */
 
 import { extractAllTags } from './tags.js';
+import { validateTransition, hashText } from './feedback-transitions.js';
 
 // ---------------------------------------------------------------------------
 // Parsing
@@ -85,6 +86,16 @@ export function parseFeedback(text, cycle, artefacts) {
 // ---------------------------------------------------------------------------
 
 export function addFeedbackItem(text, file, itemText, tag) {
+  // Dedup by (file, tag, text hash): if any existing item under this file
+  // heading has the same tag and the same itemText, return without mutating.
+  const existing = collectItemsForFile(text, file);
+  const h = hashText(itemText);
+  for (const ex of existing) {
+    if (ex.tags.includes(`#${tag}`) && hashText(ex.coreText) === h) {
+      return { text, deduped: true };
+    }
+  }
+
   const newItem = `- [ ] ${itemText} #${tag}`;
   const lines = text.split('\n');
 
@@ -111,7 +122,7 @@ export function addFeedbackItem(text, file, itemText, tag) {
   if (feedbackIdx === -1) {
     // No Feedback section — append one
     lines.push('', '## Feedback', '', `### ${file}`, newItem);
-    return lines.join('\n');
+    return { text: lines.join('\n'), deduped: false };
   }
 
   // Find the file heading within the feedback section
@@ -135,7 +146,7 @@ export function addFeedbackItem(text, file, itemText, tag) {
   if (fileIdx === -1) {
     // File heading doesn't exist — add it before section end
     lines.splice(sectionEnd, 0, '', fileHeading, newItem);
-    return lines.join('\n');
+    return { text: lines.join('\n'), deduped: false };
   }
 
   // Find last item under this file heading
@@ -149,23 +160,23 @@ export function addFeedbackItem(text, file, itemText, tag) {
   }
 
   lines.splice(insertIdx, 0, newItem);
-  return lines.join('\n');
+  return { text: lines.join('\n'), deduped: false };
 }
 
-export function actionFeedbackItem(text, file, index) {
-  return transformFeedbackItem(text, file, index, (line) =>
+export function actionFeedbackItem(text, file, index, stageBase) {
+  return transformFeedbackItemWithValidation(text, file, index, 'actioned', stageBase, (line) =>
     line.replace('- [ ]', '- [x]')
   );
 }
 
-export function wontfixFeedbackItem(text, file, index, reason) {
-  return transformFeedbackItem(text, file, index, (line) =>
+export function wontfixFeedbackItem(text, file, index, reason, stageBase) {
+  return transformFeedbackItemWithValidation(text, file, index, 'wont-fix', stageBase, (line) =>
     line.replace('- [ ]', '- [~]') + ` | wont-fix: ${reason}`
   );
 }
 
-export function resolveFeedbackItem(text, file, index, resolution, reason) {
-  return transformFeedbackItem(text, file, index, (line) => {
+export function resolveFeedbackItem(text, file, index, resolution, reason, stageBase) {
+  return transformFeedbackItemWithValidation(text, file, index, resolution, stageBase, (line) => {
     if (resolution === 'approved') {
       return line + ' | approved';
     }
@@ -257,6 +268,132 @@ export function detectDeadlocks(feedback, history, threshold = 3) {
 // Internal helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Collect feedback items under a specific file heading, returning the parsed
+ * representation plus the "core text" (item body with tag and trailing resolution
+ * stripped) for dedup hashing.
+ */
+function collectItemsForFile(text, file) {
+  const items = [];
+  const lines = text.split('\n');
+  let inFeedback = false;
+  let feedbackLevel = 0;
+  let currentFile = null;
+
+  for (const line of lines) {
+    const stripped = line.trim();
+
+    if (stripped === '# Feedback' || stripped === '## Feedback') {
+      inFeedback = true;
+      feedbackLevel = stripped.startsWith('## ') ? 2 : 1;
+      continue;
+    }
+
+    if (inFeedback && /^#{1,2} /.test(stripped)) {
+      const level = stripped.startsWith('## ') ? 2 : 1;
+      if (level <= feedbackLevel && stripped !== '# Feedback' && stripped !== '## Feedback') {
+        inFeedback = false;
+        continue;
+      }
+    }
+
+    if (!inFeedback) continue;
+
+    const fileHeadingPrefix = feedbackLevel === 1 ? '## ' : '### ';
+    if (stripped.startsWith(fileHeadingPrefix)) {
+      currentFile = stripped.slice(fileHeadingPrefix.length).trim();
+      continue;
+    }
+
+    if (currentFile === file && /^- \[/.test(stripped)) {
+      const parsed = parseFeedbackItem(stripped);
+      // Strip checkbox, tags, and trailing `| approved` / `| rejected: ...` /
+      // `| wont-fix: ...` to get the core author-supplied text for dedup.
+      let core = stripped.replace(/^- \[[ x~]\]\s*/, '');
+      core = core.replace(/\s*\|\s*(approved|rejected[^|]*|wont-fix[^|]*)\s*$/, '');
+      for (const t of parsed.tags) {
+        core = core.replace(t, '');
+      }
+      core = core.trim();
+      items.push({ line: stripped, state: parsed.state, tags: parsed.tags, coreText: core });
+    }
+  }
+
+  return items;
+}
+
+/**
+ * Read the line at (file, index) and return its current feedback state
+ * (or null if not found).
+ */
+function readItemState(text, file, index) {
+  const lines = text.split('\n');
+  let inFeedback = false;
+  let feedbackLevel = 0;
+  let currentFile = null;
+  let fileIndex = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    const stripped = lines[i].trim();
+
+    if (stripped === '# Feedback' || stripped === '## Feedback') {
+      inFeedback = true;
+      feedbackLevel = stripped.startsWith('## ') ? 2 : 1;
+      continue;
+    }
+
+    if (inFeedback && /^#{1,2} /.test(stripped)) {
+      const level = stripped.startsWith('## ') ? 2 : 1;
+      if (level <= feedbackLevel && stripped !== '# Feedback' && stripped !== '## Feedback') {
+        inFeedback = false;
+        continue;
+      }
+    }
+
+    if (!inFeedback) continue;
+
+    const fileHeadingPrefix = feedbackLevel === 1 ? '## ' : '### ';
+    if (stripped.startsWith(fileHeadingPrefix)) {
+      currentFile = stripped.slice(fileHeadingPrefix.length).trim();
+      fileIndex = 0;
+      continue;
+    }
+
+    if (currentFile === file && /^- \[/.test(stripped)) {
+      if (fileIndex === index) {
+        const parsed = parseFeedbackItem(stripped);
+        // Map parseFeedbackItem's (state, resolved) pair onto state-machine states:
+        // - `| approved` → terminal "approved"
+        // - `| rejected` → "rejected" (parseFeedbackItem already sets this)
+        // - bare `[x]`   → "actioned"
+        // - bare `[~]`   → "wont-fix"
+        // - bare `[ ]`   → "open"
+        if (parsed.resolved) return 'approved';
+        return parsed.state;
+      }
+      fileIndex++;
+    }
+  }
+  return null;
+}
+
+function transformFeedbackItemWithValidation(text, file, index, target, stageBase, transform) {
+  if (stageBase !== undefined) {
+    const current = readItemState(text, file, index);
+    if (!current) {
+      return { ok: false, error: `feedback item not found: file=${file} index=${index}` };
+    }
+    const v = validateTransition(current, target, stageBase);
+    if (!v.ok) {
+      return { ok: false, error: v.reason };
+    }
+    const updated = transformFeedbackItem(text, file, index, transform);
+    return { ok: true, text: updated };
+  }
+  // Backward-compatible path: return plain string.
+  return transformFeedbackItem(text, file, index, transform);
+}
+
 function transformFeedbackItem(text, file, index, transform) {
   const lines = text.split('\n');
   let inFeedback = false;

package/scripts/lib/finalize.js

@@ -0,0 +1,41 @@
+// scripts/lib/finalize.js
+import { execSync } from 'node:child_process';
+import { minimatch } from 'minimatch';
+
+const TOOL_MANAGED = [
+  'WORK.md',
+  'WORK.history.yaml',
+];
+const TOOL_MANAGED_PREFIX = ['.foundry/'];
+
+function changedFiles(cwd, baseSha) {
+  const tracked = execSync(`git diff --name-only ${baseSha} HEAD`, { cwd }).toString().split('\n').filter(Boolean);
+  const diffUnstaged = execSync('git diff --name-only', { cwd }).toString().split('\n').filter(Boolean);
+  const untracked = execSync('git ls-files --others --exclude-standard', { cwd }).toString().split('\n').filter(Boolean);
+  return [...new Set([...tracked, ...diffUnstaged, ...untracked])];
+}
+
+function isToolManaged(f) {
+  if (TOOL_MANAGED.includes(f)) return true;
+  return TOOL_MANAGED_PREFIX.some(p => f.startsWith(p));
+}
+
+export function finalizeStage({ cwd, baseSha, stageBase, cycleDef, artefactTypes, registerArtefact }) {
+  const files = changedFiles(cwd, baseSha).filter(f => !isToolManaged(f));
+  const allowedPatterns = stageBase === 'forge'
+    ? (artefactTypes[cycleDef.outputArtefactType]?.filePatterns ?? [])
+    : [];
+  const unexpected = [];
+  const matched = [];
+  for (const f of files) {
+    const hit = allowedPatterns.find(p => minimatch(f, p));
+    if (hit) matched.push(f);
+    else unexpected.push(f);
+  }
+  if (unexpected.length) return { ok: false, error: 'unexpected_files', files: unexpected };
+  const artefacts = matched.map(file => {
+    registerArtefact({ file, type: cycleDef.outputArtefactType, status: 'draft' });
+    return { file, type: cycleDef.outputArtefactType, status: 'draft' };
+  });
+  return { ok: true, artefacts };
+}

package/scripts/lib/history.js

@@ -18,7 +18,7 @@ export function loadHistory(historyPath, cycle, io) {
 /**
  * Append a history entry with auto-generated ISO timestamp.
  */
-export function appendEntry(historyPath, { cycle, stage, iteration, comment }, io) {
+export function appendEntry(historyPath, { cycle, stage, iteration, comment, route }, io) {
   if (iteration == null) throw new Error('iteration is required');
   if (!comment) throw new Error('comment is required');
 
@@ -27,13 +27,15 @@ export function appendEntry(historyPath, { cycle, stage, iteration, comment }, i
     existing = yaml.load(io.readFile(historyPath)) || [];
   }
 
-  existing.push({
+  const entry = {
     cycle,
     stage,
     iteration,
     comment,
     timestamp: new Date().toISOString(),
-  });
+  };
+  if (route !== undefined) entry.route = route;
+  existing.push(entry);
 
   io.writeFile(historyPath, yaml.dump(existing));
 }
@@ -45,3 +47,13 @@ export function getIteration(historyPath, cycle, io) {
   const history = loadHistory(historyPath, cycle, io);
   return history.filter(e => (e.stage || '').split(':')[0] === 'forge').length;
 }
+
+/**
+ * Return the `route` field from the most recent `sort` history entry for a
+ * given cycle, or null if none exists.
+ */
+export function readLastSortRoute(historyPath, cycle, io) {
+  const entries = loadHistory(historyPath, cycle, io).filter(e => e.stage === 'sort');
+  if (!entries.length) return null;
+  return entries[entries.length - 1].route ?? null;
+}

package/scripts/lib/pending.js

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

package/scripts/lib/secret.js

@@ -0,0 +1,23 @@
+import { existsSync, readFileSync, mkdirSync, openSync, writeSync, closeSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+
+export function readOrCreateSecret(directory) {
+  const dir = join(directory, '.foundry');
+  const file = join(dir, '.secret');
+  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/lib/stage-guard.js

@@ -0,0 +1,25 @@
+// scripts/lib/stage-guard.js
+import { readActiveStage } from './state.js';
+
+export function stageBaseOf(stage) {
+  const i = stage.indexOf(':');
+  return i === -1 ? stage : stage.slice(0, i);
+}
+
+export function requireNoActiveStage(io) {
+  const a = readActiveStage(io);
+  if (!a) return { ok: true };
+  return { ok: false, error: `tool requires no active stage; current: ${a.stage}` };
+}
+
+export function requireActiveStage(io, { stageBase, cycle } = {}) {
+  const a = readActiveStage(io);
+  if (!a) return { ok: false, error: `tool requires active stage; current: none` };
+  if (stageBase && stageBaseOf(a.stage) !== stageBase) {
+    return { ok: false, error: `tool requires active ${stageBase} stage; current: ${a.stage}` };
+  }
+  if (cycle && a.cycle !== cycle) {
+    return { ok: false, error: `tool requires active stage in cycle ${cycle}; current cycle: ${a.cycle}` };
+  }
+  return { ok: true, active: a };
+}

package/scripts/lib/state.js

@@ -0,0 +1,31 @@
+const ACTIVE = '.foundry/active-stage.json';
+const LAST = '.foundry/last-stage.json';
+const DIR = '.foundry';
+
+export function ensureFoundryDir(io) {
+  if (!io.exists(DIR)) io.mkdir(DIR);
+}
+
+export function readActiveStage(io) {
+  if (!io.exists(ACTIVE)) return null;
+  return JSON.parse(io.readFile(ACTIVE));
+}
+
+export function writeActiveStage(io, payload) {
+  ensureFoundryDir(io);
+  io.writeFile(ACTIVE, JSON.stringify(payload, null, 2));
+}
+
+export function clearActiveStage(io) {
+  io.unlink(ACTIVE);
+}
+
+export function readLastStage(io) {
+  if (!io.exists(LAST)) return null;
+  return JSON.parse(io.readFile(LAST));
+}
+
+export function writeLastStage(io, payload) {
+  ensureFoundryDir(io);
+  io.writeFile(LAST, JSON.stringify(payload, null, 2));
+}

package/scripts/lib/token.js

@@ -0,0 +1,26 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+export function signToken(payload, secret) {
+  const body = Buffer.from(JSON.stringify(payload)).toString('base64url');
+  const mac = createHmac('sha256', secret).update(body).digest('base64url');
+  return `${body}.${mac}`;
+}
+
+export function verifyToken(token, secret) {
+  if (typeof token !== 'string' || !token.includes('.')) return { ok: false, reason: 'malformed' };
+  const [body, mac] = token.split('.');
+  if (!body || !mac) return { ok: false, reason: 'malformed' };
+  const expected = createHmac('sha256', secret).update(body).digest();
+  let given;
+  try { given = Buffer.from(mac, 'base64url'); } catch { return { ok: false, reason: 'malformed' }; }
+  if (given.length !== expected.length || !timingSafeEqual(given, expected)) {
+    return { ok: false, reason: 'bad_signature' };
+  }
+  let payload;
+  try { payload = JSON.parse(Buffer.from(body, 'base64url').toString()); }
+  catch { return { ok: false, reason: 'malformed' }; }
+  if (typeof payload.exp !== 'number' || payload.exp < Date.now()) {
+    return { ok: false, reason: 'expired' };
+  }
+  return { ok: true, payload };
+}

package/scripts/lib/workfile.js

@@ -11,7 +11,16 @@ import yaml from 'js-yaml';
 export function parseFrontmatter(text) {
   const match = text.match(/^---\n(.+?)\n---/s);
   if (!match) return {};
-  return yaml.load(match[1]) || {};
+  const fm = yaml.load(match[1]) || {};
+  // Normalize: on-disk canonical key is `max-iterations` (kebab).
+  // Tolerate legacy `maxIterations` (camel) by rewriting on read.
+  if (fm.maxIterations !== undefined) {
+    if (fm['max-iterations'] === undefined) {
+      fm['max-iterations'] = fm.maxIterations;
+    }
+    delete fm.maxIterations;
+  }
+  return fm;
 }
 
 export function writeFrontmatter(fields) {
@@ -25,6 +34,8 @@ export function getFrontmatterField(text, key) {
 }
 
 export function setFrontmatterField(text, key, value) {
+  // Coerce legacy camelCase key to canonical kebab form on write.
+  if (key === 'maxIterations') key = 'max-iterations';
   const fm = parseFrontmatter(text);
   fm[key] = value;
   const fmBlock = writeFrontmatter(fm);

package/scripts/sort.js

@@ -64,7 +64,7 @@ const defaultIO = {
 // Routing logic
 // ---------------------------------------------------------------------------
 
-function determineRoute(stages, history, feedback, maxIterations) {
+function determineRoute(stages, history, feedback, maxIterations, opts = {}) {
   const forgeCount = history.filter(e => baseStage(e.stage || '') === 'forge').length;
 
   const nonSortHistory = history.filter(e => baseStage(e.stage || '') !== 'sort');
@@ -83,11 +83,11 @@ function determineRoute(stages, history, feedback, maxIterations) {
   }
 
   if (lastBase === 'appraise') {
-    return nextAfterAppraise(stages, lastEntry, feedback, forgeCount, maxIterations, nonSortHistory);
+    return nextAfterAppraise(stages, lastEntry, feedback, forgeCount, maxIterations, nonSortHistory, opts);
   }
 
   if (lastBase === 'human-appraise') {
-    return nextAfterAppraise(stages, lastEntry, feedback, forgeCount, maxIterations, nonSortHistory);
+    return nextAfterAppraise(stages, lastEntry, feedback, forgeCount, maxIterations, nonSortHistory, opts);
   }
 
   return 'blocked';
@@ -103,16 +103,31 @@ function nextAfterQuench(stages, current, feedback, forgeCount, maxIterations) {
   return nextInRoute(stages, current) ?? 'done';
 }
 
-function nextAfterAppraise(stages, current, feedback, forgeCount, maxIterations, history = []) {
-  // Check for deadlock escalation
-  const deadlocked = detectDeadlocks(feedback, history);
+function nextAfterAppraise(stages, current, feedback, forgeCount, maxIterations, history = [], opts = {}) {
+  const {
+    humanAppraise: humanAppraiseEnabled = false,
+    deadlockAppraise = true,
+    deadlockIterations = 5,
+    cycle = null,
+  } = opts;
+
+  // Check for deadlock escalation using configured threshold
+  const deadlocked = detectDeadlocks(feedback, history, deadlockIterations);
   if (deadlocked.length > 0) {
-    const humanAppraise = findFirst(stages, 'human-appraise');
-    if (humanAppraise && baseStage(current) !== 'human-appraise') {
-      return humanAppraise;
+    const alreadyInHumanAppraise = baseStage(current) === 'human-appraise';
+    if (alreadyInHumanAppraise) {
+      // Human-appraise ran and deadlock still present — give up.
+      return 'blocked';
     }
-    // Human-appraise not available or we're already in it — blocked
-    if (forgeCount >= maxIterations) return 'blocked';
+    if (deadlockAppraise) {
+      // Route to human-appraise. Prefer one in `stages`; else synthesize via cycle id.
+      const inStages = findFirst(stages, 'human-appraise');
+      if (inStages) return inStages;
+      if (cycle) return `human-appraise:${cycle}`;
+      return 'blocked';
+    }
+    // deadlock-appraise disabled — block the cycle.
+    return 'blocked';
   }
 
   const needsForge = feedback.some(f => f.state === 'open' || f.state === 'rejected');
@@ -205,11 +220,43 @@ function checkModifiedFiles(lastBase, foundryDir, cycleDef, cycle, io = defaultI
   return { ok: violations.length === 0, violations };
 }
 
+// ---------------------------------------------------------------------------
+// Micro-commit enforcement
+// ---------------------------------------------------------------------------
+
+/**
+ * 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.history.yaml, and anything under
+ * .foundry/. The sort skill is the sole writer of these between stages,
+ * and every stage must end with `foundry_git_commit`. If this function
+ * returns a non-empty list at the start of a sort invocation, a prior
+ * stage skipped the commit step.
+ */
+function getDirtyToolManagedFiles(io = defaultIO) {
+  try {
+    const output = io.exec('git status --porcelain -- WORK.md WORK.history.yaml .foundry');
+    return output
+      .split('\n')
+      .map(line => line.trim())
+      .filter(Boolean)
+      .map(line => line.replace(/^[\sMADRCU?!]+/, '').trim())
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Exported runSort — structured result for programmatic use
 // ---------------------------------------------------------------------------
 
-export function runSort({ workPath = 'WORK.md', historyPath = 'WORK.history.yaml', foundryDir = 'foundry', cycleDef, agentsDir = '.opencode/agents' } = {}, io = defaultIO) {
+function isDispatchableRoute(route) {
+  return typeof route === 'string' && /^(forge|quench|appraise|human-appraise):/.test(route);
+}
+
+export function runSort({ workPath = 'WORK.md', historyPath = 'WORK.history.yaml', foundryDir = 'foundry', cycleDef, agentsDir = '.opencode/agents', mint, now = Date.now() } = {}, io = defaultIO) {
   if (!io.exists(workPath)) {
     return { route: 'blocked', details: 'WORK.md not found' };
   }
@@ -220,6 +267,9 @@ export function runSort({ workPath = 'WORK.md', historyPath = 'WORK.history.yaml
   const cycle = frontmatter.cycle;
   const stages = frontmatter.stages;
   const maxIterations = frontmatter['max-iterations'] ?? 3;
+  const humanAppraiseEnabled = frontmatter['human-appraise'] === true;
+  const deadlockAppraise = frontmatter['deadlock-appraise'] !== false; // default true
+  const deadlockIterations = frontmatter['deadlock-iterations'] ?? 5;
 
   if (!cycle) return { route: 'blocked', details: 'No cycle in WORK.md frontmatter' };
   if (!stages || !Array.isArray(stages)) return { route: 'blocked', details: 'No stages in WORK.md frontmatter' };
@@ -229,6 +279,20 @@ export function runSort({ workPath = 'WORK.md', historyPath = 'WORK.history.yaml
   const history = loadHistory(historyPath, cycle, io);
   const feedback = parseFeedback(workText, cycle, artefacts);
 
+  // Micro-commit enforcement: if any prior stage ran (history non-empty),
+  // all tool-managed files must be committed before the next sort call.
+  // The first sort of a cycle has empty history — WORK.md may be untracked
+  // or dirty at that point, which is fine.
+  if (history.length > 0) {
+    const dirty = getDirtyToolManagedFiles(io);
+    if (dirty.length > 0) {
+      return {
+        route: 'violation',
+        details: `Uncommitted tool-managed files since last sort: ${dirty.join(', ')}. Call foundry_git_commit for the prior stage before invoking sort again.`,
+      };
+    }
+  }
+
   // File modification enforcement
   const nonSortHistory = history.filter(e => baseStage(e.stage || '') !== 'sort');
   if (nonSortHistory.length > 0) {
@@ -248,7 +312,12 @@ export function runSort({ workPath = 'WORK.md', historyPath = 'WORK.history.yaml
     return { route: 'violation', details: `Feedback tag validation failed: ${details}` };
   }
 
-  const route = determineRoute(stages, history, feedback, maxIterations);
+  const route = determineRoute(stages, history, feedback, maxIterations, {
+    humanAppraise: humanAppraiseEnabled,
+    deadlockAppraise,
+    deadlockIterations,
+    cycle,
+  });
 
   // Model resolution
   let model = null;
@@ -267,7 +336,12 @@ export function runSort({ workPath = 'WORK.md', historyPath = 'WORK.history.yaml
     }
   }
 
-  return { route, ...(model ? { model } : {}) };
+  const result = { route, ...(model ? { model } : {}) };
+  if (mint && isDispatchableRoute(route)) {
+    const token = mint({ route, cycle, exp: now + 10 * 60 * 1000 });
+    if (token) result.token = token;
+  }
+  return result;
 }
 
 // ---------------------------------------------------------------------------
@@ -290,6 +364,7 @@ export {
   getModifiedFiles,
   getAllowedPatterns,
   checkModifiedFiles,
+  getDirtyToolManagedFiles,
 };
 
 

package/skills/add-cycle/SKILL.md

@@ -54,10 +54,15 @@ Only stages with an explicitly specified model are included in the `models` fron
 
 Ask the user:
 
-> Do you want a human quality gate on this cycle? If enabled, a human reviewer will check the artefact after LLM appraisers pass, and can break deadlocks between forge and appraisers.
+> Human-appraise has two independent knobs:
 >
-> - Enable human-appraise? (yes/no)
-> - If yes, deadlock threshold (default: 3 — number of forge/appraise iterations before escalating to human)
+> 1. `human-appraise` — should a human review the artefact every iteration? Default: no.
+> 2. `deadlock-appraise` — should a human be pulled in only when LLM appraisers deadlock? Default: yes.
+> 3. If either is enabled, `deadlock-iterations` sets the deadlock threshold (default: 5).
+>
+> - human-appraise: yes/no (default no)
+> - deadlock-appraise: yes/no (default yes)
+> - deadlock-iterations: number (default 5)
 
 ### 5. Validate artefact types
 
@@ -108,9 +113,9 @@ inputs:
     - <artefact-type-id>
 targets:
   - <cycle-id>
-human-appraise:
-  enabled: <true|false>
-  deadlock-threshold: <number>
+human-appraise: <true|false>
+deadlock-appraise: <true|false>
+deadlock-iterations: <number>
 models:
   appraise: <model-id>
 ---