@really-knows-ai/foundry 2.1.0 → 2.3.0

package/scripts/orchestrate.js

@@ -0,0 +1,418 @@
+// Foundry v2.3.0 orchestrate: deterministic cycle orchestration.
+// Composes internal functions (sort, finalize, history, commit, configure)
+// into a single entry point the LLM drives via a 3-line loop.
+
+import { runSort } from './sort.js';
+import {
+  getCycleDefinition,
+  getArtefactType,
+  getValidation,
+} from './lib/config.js';
+import { parseFrontmatter, writeFrontmatter } from './lib/workfile.js';
+import { parseArtefactsTable, addArtefactRow, setArtefactStatus } from './lib/artefacts.js';
+import { readActiveStage, readLastStage, clearActiveStage } from './lib/state.js';
+import { appendEntry, getIteration } from './lib/history.js';
+import { listFeedback } from './lib/feedback.js';
+
+export function renderDispatchPrompt({ stage, cycle, token, cwd, filePatterns }) {
+  const lines = [
+    `You are a Foundry stage agent. Invoke the ${stage.split(':')[0]} skill and follow its instructions exactly.`,
+    ``,
+    `Stage: ${stage}`,
+    `Cycle: ${cycle}`,
+    `Token: ${token}`,
+    `Working directory: ${cwd}`,
+  ];
+  if (filePatterns && filePatterns.length) {
+    lines.push(`File patterns (forge only): ${JSON.stringify(filePatterns)}`);
+  }
+  lines.push(
+    ``,
+    `Your FIRST tool call MUST be foundry_stage_begin({stage, cycle, token}) using the values above.`,
+    `Your LAST tool call MUST be foundry_stage_end({summary}).`,
+    ``,
+    `When done, report back a brief summary. Do NOT call foundry_history_append, foundry_git_commit, or foundry_artefacts_add — the orchestrator handles all of those.`
+  );
+  return lines.join('\n');
+}
+
+export function synthesizeStages({ cycleId, hasValidation, humanAppraise }) {
+  const stages = [`forge:${cycleId}`];
+  if (hasValidation) stages.push(`quench:${cycleId}`);
+  stages.push(`appraise:${cycleId}`);
+  if (humanAppraise) stages.push(`human-appraise:${cycleId}`);
+  return stages;
+}
+
+export function needsSetup(workMdContent) {
+  const match = workMdContent.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return true;
+  const fm = match[1];
+  return !/^stages:/m.test(fm);
+}
+
+// ---------------------------------------------------------------------------
+// Task-6 stub helpers (wired in later). readForgeFilePatterns is real now
+// because the first-call dispatch prompt needs it.
+// ---------------------------------------------------------------------------
+
+export function findCycleOutputArtefact(cycleId, io) {
+  if (!io.exists('WORK.md')) return null;
+  const content = io.readFile('WORK.md');
+  const rows = parseArtefactsTable(content);
+  const match = rows.find(r => r.cycle === cycleId);
+  return match ? { file: match.file, type: match.type, status: match.status } : null;
+}
+
+export async function readCycleTargets(cycleId, io) {
+  try {
+    const cd = await getCycleDefinition('foundry', cycleId, io);
+    return cd.frontmatter?.targets ?? [];
+  } catch {
+    return [];
+  }
+}
+
+export async function readForgeFilePatterns(cycleId, io) {
+  try {
+    const cd = await getCycleDefinition('foundry', cycleId, io);
+    const output = cd.frontmatter?.output;
+    if (!output) return null;
+    const at = await getArtefactType('foundry', output, io);
+    return at.frontmatter?.['file-patterns'] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function readRecentFeedback(cycleId, io, limit = 5) {
+  // Best-effort: surface recent deadlocked items (rejected or wont-fix) for
+  // the human-appraise checkpoint. Returns last `limit` matching entries.
+  // On any parse error, return [] rather than crashing the cycle.
+  try {
+    if (!io.exists('WORK.md')) return [];
+    const content = io.readFile('WORK.md');
+    const rows = parseArtefactsTable(content);
+    const items = listFeedback(content, cycleId, rows);
+    const deadlocked = items.filter(
+      it => it.state === 'wont-fix' || it.state === 'rejected'
+    );
+    return deadlocked.slice(-limit);
+  } catch {
+    return [];
+  }
+}
+
+function violation(details, affectedFiles = []) {
+  return {
+    action: 'violation',
+    details,
+    recoverable: false,
+    affected_files: affectedFiles,
+  };
+}
+
+function markArtefactBlocked(cycleId, io) {
+  if (!io.exists('WORK.md')) return { ok: true };
+  const content = io.readFile('WORK.md');
+  const rows = parseArtefactsTable(content);
+  const row = rows.find(r => r.cycle === cycleId);
+  if (!row) return { ok: true };
+  try {
+    io.writeFile('WORK.md', setArtefactStatus(content, row.file, 'blocked'));
+    return { ok: true };
+  } catch (e) {
+    // Surface to caller: setArtefactStatus is strict (e.g. row already
+    // blocked/done, invalid status). Don't crash; let caller annotate
+    // the violation.
+    return { ok: false, error: e?.message || String(e) };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Sort result -> action shape
+// ---------------------------------------------------------------------------
+
+async function handleSortResult(sortResult, { cycleId, cwd, io }) {
+  const { route, model, token, details } = sortResult;
+  const base = typeof route === 'string' ? route.split(':')[0] : '';
+
+  if (route === 'done') {
+    const art = findCycleOutputArtefact(cycleId, io);
+    return {
+      action: 'done',
+      cycle: cycleId,
+      artefact_file: art?.file ?? null,
+      next_cycles: await readCycleTargets(cycleId, io),
+    };
+  }
+
+  if (route === 'blocked') {
+    const art = findCycleOutputArtefact(cycleId, io);
+    return {
+      action: 'blocked',
+      cycle: cycleId,
+      artefact_file: art?.file ?? null,
+      reason: details ?? 'iteration limit reached with unresolved feedback',
+    };
+  }
+
+  if (route === 'violation') {
+    return violation(details ?? 'sort returned violation');
+  }
+
+  if (base === 'human-appraise') {
+    const art = findCycleOutputArtefact(cycleId, io);
+    return {
+      action: 'human_appraise',
+      stage: route,
+      token,
+      context: {
+        cycle: cycleId,
+        artefact_file: art?.file ?? null,
+        recent_feedback: readRecentFeedback(cycleId, io),
+      },
+    };
+  }
+
+  // forge | quench | appraise
+  if (!model) {
+    const art = findCycleOutputArtefact(cycleId, io);
+    return violation(
+      `cycle ${cycleId} stage ${route} has no model declared in cycle definition (\`models:\` field) and no default available`,
+      [art?.file].filter(Boolean)
+    );
+  }
+
+  const filePatterns = base === 'forge'
+    ? await readForgeFilePatterns(cycleId, io)
+    : null;
+
+  return {
+    action: 'dispatch',
+    stage: route,
+    subagent_type: model,
+    prompt: renderDispatchPrompt({
+      stage: route,
+      cycle: cycleId,
+      token,
+      cwd,
+      filePatterns,
+    }),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+export async function runOrchestrate(args = {}, io) {
+  const {
+    cwd = process.cwd(),
+    cycleDef: cycleDefOverride = null,
+    git,
+    mint,
+    now = Date.now,
+    lastResult = null,
+    finalize = null,
+  } = args;
+
+  if (!io.exists('WORK.md')) {
+    return violation('no WORK.md; flow skill must create it first');
+  }
+
+  let workContent = io.readFile('WORK.md');
+  const fm = parseFrontmatter(workContent);
+  const cycleId = fm.cycle;
+  if (!cycleId) {
+    return violation('WORK.md frontmatter missing cycle field', ['WORK.md']);
+  }
+
+  if (needsSetup(workContent)) {
+    if (lastResult) {
+      return violation(
+        'inconsistent state: lastResult provided but WORK.md still needs setup',
+        ['WORK.md']
+      );
+    }
+
+    const foundryDir = 'foundry';
+    let cycleDefDoc;
+    try {
+      cycleDefDoc = await getCycleDefinition(foundryDir, cycleId, io);
+    } catch {
+      return violation(`cycle definition not found for id: ${cycleId}`, ['WORK.md']);
+    }
+    const cfm = cycleDefDoc.frontmatter || {};
+
+    const outputType = cfm.output;
+    if (!outputType) {
+      return violation(`cycle ${cycleId} missing output field`, ['WORK.md']);
+    }
+
+    try {
+      await getArtefactType(foundryDir, outputType, io);
+    } catch {
+      return violation(`artefact type not found: ${outputType}`, ['WORK.md']);
+    }
+
+    const validation = await getValidation(foundryDir, outputType, io);
+
+    let stages;
+    if (Array.isArray(cfm.stages)) {
+      if (cfm.stages.length === 0) {
+        const art = findCycleOutputArtefact(cycleId, io);
+        return violation(
+          `cycle ${cycleId} has no stages declared in cycle definition`,
+          [art?.file, 'WORK.md'].filter(Boolean)
+        );
+      }
+      stages = cfm.stages.map(s =>
+        typeof s === 'string' && s.includes(':') ? s : `${s}:${cycleId}`
+      );
+    } else {
+      stages = synthesizeStages({
+        cycleId,
+        hasValidation: !!validation && validation.length > 0,
+        humanAppraise: cfm['human-appraise'] === true,
+      });
+    }
+
+    const newFm = { ...fm };
+    newFm.stages = stages;
+    newFm['max-iterations'] = cfm['max-iterations'] ?? 3;
+    newFm['human-appraise'] = cfm['human-appraise'] === true;
+    newFm['deadlock-appraise'] = cfm['deadlock-appraise'] !== false;
+    newFm['deadlock-iterations'] = cfm['deadlock-iterations'] ?? 5;
+    if (cfm.models) newFm.models = cfm.models;
+
+    const body = workContent.replace(/^---\n[\s\S]+?\n---\n?/, '');
+    const fmBlock = writeFrontmatter(newFm);
+    const newWork = body ? `${fmBlock}\n${body}` : fmBlock;
+    io.writeFile('WORK.md', newWork);
+
+    if (git && typeof git.commit === 'function') {
+      git.commit(`[${cycleId}] setup: configure stages and limits`);
+    }
+
+    workContent = io.readFile('WORK.md');
+  }
+
+  const activeStage = readActiveStage(io);
+  const lastStage = readLastStage(io);
+
+  if (activeStage && !lastResult) {
+    return violation(
+      `prior stage ${activeStage.stage} orphaned — no lastResult provided but active stage exists. ` +
+      `Likely cause: previous orchestrate call returned dispatch but caller did not follow up.`,
+      []
+    );
+  }
+
+  if (lastResult) {
+    // Subagent crash path: stage_end may NOT have been called, so activeStage
+    // can still exist and lastStage may be stale or absent. Prefer activeStage
+    // (current dispatch) over lastStage (could be from a prior cycle).
+    if (lastResult.ok === false) {
+      const failedStage = activeStage || lastStage;
+      if (!failedStage) {
+        return violation('lastResult.ok=false but no stage recorded — orphaned state');
+      }
+      const blockResult = markArtefactBlocked(cycleId, io);
+      if (activeStage) clearActiveStage(io);
+      const art = findCycleOutputArtefact(cycleId, io);
+      const blockNote = blockResult.ok ? '' : ` (also: failed to mark artefact blocked: ${blockResult.error})`;
+      return violation(
+        `subagent dispatch failed: ${lastResult.error || 'unknown error'}${blockNote}`,
+        [art?.file].filter(Boolean)
+      );
+    }
+
+    // Happy path: foundry_stage_end has run, which writes lastStage and clears
+    // activeStage. lastStage is the canonical source of stage identity & baseSha.
+    if (!lastStage) {
+      return violation('lastResult provided but no last stage recorded — orphaned state');
+    }
+
+    let finalizeResult;
+    if (typeof finalize !== 'function') {
+      return violation(
+        'orchestrate caller must inject a `finalize` function when providing lastResult; ' +
+        'the plugin wires lib/finalize.finalizeStage; tests must pass a stub.',
+        []
+      );
+    }
+    finalizeResult = await finalize({
+      cycleId,
+      stage: lastStage.stage,
+      baseSha: lastStage.baseSha,
+      io,
+    });
+
+    if (!finalizeResult.ok) {
+      const blockResult = markArtefactBlocked(cycleId, io);
+      if (activeStage) clearActiveStage(io);
+      const blockNote = blockResult.ok ? '' : ` (also: failed to mark artefact blocked: ${blockResult.error})`;
+      if (finalizeResult.error === 'unexpected_files') {
+        return violation(
+          `unexpected files written by subagent: ${(finalizeResult.files || []).join(', ')}${blockNote}`,
+          finalizeResult.files || []
+        );
+      }
+      return violation(`stage_finalize error: ${finalizeResult.error}${blockNote}`, []);
+    }
+
+    for (const a of finalizeResult.artefacts ?? []) {
+      let wm = io.readFile('WORK.md');
+      const rows = parseArtefactsTable(wm);
+      if (!rows.some(r => r.file === a.file)) {
+        wm = addArtefactRow(wm, {
+          file: a.file,
+          type: a.type,
+          cycle: cycleId,
+          status: a.status ?? 'draft',
+        });
+        io.writeFile('WORK.md', wm);
+      }
+    }
+
+    const summary = lastStage.summary || '(no summary)';
+    const historyPath = 'WORK.history.yaml';
+    const iteration = getIteration(historyPath, cycleId, io);
+
+    appendEntry(historyPath, {
+      cycle: cycleId,
+      stage: 'sort',
+      iteration,
+      route: lastStage.stage,
+      comment: `route ${lastStage.stage}`,
+    }, io);
+    appendEntry(historyPath, {
+      cycle: cycleId,
+      stage: lastStage.stage,
+      iteration,
+      comment: summary,
+    }, io);
+
+    if (git && typeof git.commit === 'function') {
+      git.commit(`[${cycleId}] ${lastStage.stage}: ${summary}`);
+    }
+    // Defensive: stage_end clears activeStage already; this is a no-op in the
+    // normal lifecycle but cleans up if the subagent skipped stage_end.
+    if (activeStage) clearActiveStage(io);
+  }
+
+  const sortResult = runSort(
+    {
+      cycleDef: cycleDefOverride,
+      mint,
+      now: typeof now === 'function' ? now() : now,
+    },
+    io
+  );
+
+  return handleSortResult(sortResult, { cycleId, cwd, io });
+}
+
+// Test-only export; keep underscored to discourage runtime use.
+export { handleSortResult as __handleSortResultForTest };

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>
 ---