@really-knows-ai/foundry 2.3.1 → 3.0.0

package/scripts/lib/history.js

@@ -1,59 +0,0 @@
-import yaml from 'js-yaml';
-
-/**
- * Load history entries for a cycle, sorted by timestamp ascending.
- */
-export function loadHistory(historyPath, cycle, io) {
-  if (!io.exists(historyPath)) return [];
-  const data = yaml.load(io.readFile(historyPath)) || [];
-  const filtered = data.filter(e => e.cycle === cycle);
-  filtered.sort((a, b) => {
-    const ta = a.timestamp ? new Date(a.timestamp).getTime() : 0;
-    const tb = b.timestamp ? new Date(b.timestamp).getTime() : 0;
-    return ta - tb;
-  });
-  return filtered;
-}
-
-/**
- * Append a history entry with auto-generated ISO timestamp.
- */
-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');
-
-  let existing = [];
-  if (io.exists(historyPath)) {
-    existing = yaml.load(io.readFile(historyPath)) || [];
-  }
-
-  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));
-}
-
-/**
- * Count forge entries for a cycle.
- */
-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/secret.js

@@ -1,23 +0,0 @@
-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/tags.js

@@ -1,108 +0,0 @@
-/**
- * Shared tag validation utilities used by sort.js and validate-tags.js.
- */
-
-import { readFileSync, existsSync, readdirSync } from 'fs';
-import { join } from 'path';
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-export const VALID_TAG_RE = /^(#validation|#hitl|#law:[\w-]+)$/;
-
-// ---------------------------------------------------------------------------
-// Law collection
-// ---------------------------------------------------------------------------
-
-export function collectLawIds(foundryDir) {
-  const ids = new Set();
-
-  const lawsDir = join(foundryDir, 'laws');
-  if (existsSync(lawsDir)) {
-    for (const file of readdirSync(lawsDir)) {
-      if (!file.endsWith('.md')) continue;
-      const text = readFileSync(join(lawsDir, file), 'utf-8');
-      for (const id of extractLawHeadings(text)) ids.add(id);
-    }
-  }
-
-  const artefactsDir = join(foundryDir, 'artefacts');
-  if (existsSync(artefactsDir)) {
-    for (const typeDir of readdirSync(artefactsDir)) {
-      const lawsPath = join(artefactsDir, typeDir, 'laws.md');
-      if (!existsSync(lawsPath)) continue;
-      const text = readFileSync(lawsPath, 'utf-8');
-      for (const id of extractLawHeadings(text)) ids.add(id);
-    }
-  }
-
-  return ids;
-}
-
-export function extractLawHeadings(text) {
-  const ids = [];
-  for (const line of text.split('\n')) {
-    const match = line.match(/^## (.+)$/);
-    if (match) ids.push(match[1].trim());
-  }
-  return ids;
-}
-
-// ---------------------------------------------------------------------------
-// Tag extraction
-// ---------------------------------------------------------------------------
-
-/**
- * Extract all hash-tags from a feedback line.
- * Returns an array of strings like ['#validation', '#law:brevity'].
- */
-export function extractAllTags(line) {
-  return (line.match(/#[\w][\w:-]*/g) || []);
-}
-
-// ---------------------------------------------------------------------------
-// Validation
-// ---------------------------------------------------------------------------
-
-/**
- * Validate all feedback tags in the Feedback section of WORK.md text.
- *
- * Returns an array of error strings. Empty array = all valid.
- */
-export function validateTags(workText, foundryDir) {
-  const lawIds = collectLawIds(foundryDir);
-  const errors = [];
-  let inFeedback = false;
-  let lineNum = 0;
-
-  for (const line of workText.split('\n')) {
-    lineNum++;
-    const stripped = line.trim();
-
-    if (stripped === '# Feedback') { inFeedback = true; continue; }
-    if (inFeedback && stripped.startsWith('# ') && stripped !== '# Feedback') {
-      inFeedback = false; continue;
-    }
-    if (!inFeedback || !(/^- \[/.test(stripped))) continue;
-
-    const tags = extractAllTags(stripped);
-    if (tags.length === 0) {
-      errors.push({ line: lineNum, message: 'Feedback item has no tag', raw: stripped });
-      continue;
-    }
-
-    for (const tag of tags) {
-      if (!VALID_TAG_RE.test(tag)) {
-        errors.push({ line: lineNum, message: `Unknown tag: ${tag}`, raw: stripped });
-      } else if (tag.startsWith('#law:')) {
-        const lawId = tag.slice(5);
-        if (!lawIds.has(lawId)) {
-          errors.push({ line: lineNum, message: `Law not found: ${lawId}`, raw: stripped });
-        }
-      }
-    }
-  }
-
-  return errors;
-}

package/scripts/lib/token.js

@@ -1,26 +0,0 @@
-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/orchestrate.js

@@ -1,418 +0,0 @@
-// 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 };