@really-knows-ai/foundry 2.3.2 → 3.0.0

package/scripts/sort.js

@@ -1,370 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Sort — deterministic routing for a Foundry Cycle.
- *
- * Reads WORK.md (frontmatter + feedback) and WORK.history.yaml to determine
- * the next stage to execute, or signal completion/blocked.
- *
- * Usage:
- *     node scripts/sort.js [--work WORK.md] [--history WORK.history.yaml]
- *
- * Output (stdout): a full stage alias (e.g., forge:write-haiku), 'done', or 'blocked'
- * Exit code: 0 on success, 1 on error
- */
-
-import { readFileSync, existsSync } from 'fs';
-import { execSync } from 'child_process';
-import yaml from 'js-yaml';
-import { minimatch } from 'minimatch';
-import { validateTags } from './lib/tags.js';
-import { parseFrontmatter } from './lib/workfile.js';
-import { parseArtefactsTable } from './lib/artefacts.js';
-import { loadHistory } from './lib/history.js';
-import { parseFeedback, parseFeedbackItem, detectDeadlocks } from './lib/feedback.js';
-
-// ---------------------------------------------------------------------------
-// Stage helpers
-// ---------------------------------------------------------------------------
-
-function baseStage(stage) {
-  return stage.split(':')[0];
-}
-
-function findFirst(stages, base) {
-  for (const s of stages) {
-    if (baseStage(s) === base) return s;
-  }
-  return null;
-}
-
-function nextInRoute(stages, current) {
-  const idx = stages.indexOf(current);
-  if (idx !== -1 && idx + 1 < stages.length) {
-    return stages[idx + 1];
-  }
-  return null;
-}
-
-// ---------------------------------------------------------------------------
-// I/O boundary — injectable for testing
-// ---------------------------------------------------------------------------
-
-const defaultIO = {
-  readFile: (p) => readFileSync(p, 'utf-8'),
-  exists: (p) => existsSync(p),
-  exec: (cmd) => execSync(cmd, { encoding: 'utf8' }),
-};
-
-// ---------------------------------------------------------------------------
-// Parsing
-// ---------------------------------------------------------------------------
-
-// ---------------------------------------------------------------------------
-// Routing logic
-// ---------------------------------------------------------------------------
-
-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');
-  const lastEntry = nonSortHistory.length > 0 ? nonSortHistory[nonSortHistory.length - 1].stage : null;
-  const lastBase = lastEntry ? baseStage(lastEntry) : null;
-
-  if (lastBase === null) return stages[0];
-
-  if (lastBase === 'forge') {
-    const next = nextInRoute(stages, lastEntry);
-    return next ?? 'done';
-  }
-
-  if (lastBase === 'quench') {
-    return nextAfterQuench(stages, lastEntry, feedback, forgeCount, maxIterations);
-  }
-
-  if (lastBase === 'appraise') {
-    return nextAfterAppraise(stages, lastEntry, feedback, forgeCount, maxIterations, nonSortHistory, opts);
-  }
-
-  if (lastBase === 'human-appraise') {
-    return nextAfterAppraise(stages, lastEntry, feedback, forgeCount, maxIterations, nonSortHistory, opts);
-  }
-
-  return 'blocked';
-}
-
-function nextAfterQuench(stages, current, feedback, forgeCount, maxIterations) {
-  const needsForge = feedback.some(f => f.state === 'open' || f.state === 'rejected');
-  if (needsForge) {
-    if (forgeCount >= maxIterations) return 'blocked';
-    return findFirst(stages, 'forge') ?? 'blocked';
-  }
-
-  return nextInRoute(stages, current) ?? 'done';
-}
-
-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 alreadyInHumanAppraise = baseStage(current) === 'human-appraise';
-    if (alreadyInHumanAppraise) {
-      // Human-appraise ran and deadlock still present — give up.
-      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');
-  if (needsForge) {
-    if (forgeCount >= maxIterations) return 'blocked';
-    return findFirst(stages, 'forge') ?? 'blocked';
-  }
-
-  const pendingApproval = feedback.some(
-    f => (f.state === 'actioned' || f.state === 'wont-fix') && !f.resolved
-  );
-  if (pendingApproval) {
-    return findFirst(stages, 'appraise') ?? 'blocked';
-  }
-
-  return nextInRoute(stages, current) ?? 'done';
-}
-
-// ---------------------------------------------------------------------------
-// File modification enforcement
-// ---------------------------------------------------------------------------
-
-function getModifiedFiles(cycle, io = defaultIO) {
-  try {
-    // Find the last sort commit for this cycle to use as the base.
-    // This captures ALL files modified since the last sort invocation,
-    // even if the stage made multiple commits.
-    const log = io.exec('git log --oneline -20');
-    const sortPattern = `[${cycle}] sort:`;
-    let commitCount = 1;
-    let foundSortCommit = false;
-    for (const line of log.trim().split('\n')) {
-      commitCount++;
-      if (line.includes(sortPattern)) {
-        foundSortCommit = true;
-        break;
-      }
-    }
-    // If no sort commit found in recent history, fall back to HEAD~1
-    if (!foundSortCommit) commitCount = 1;
-    const output = io.exec(`git diff --name-only HEAD~${commitCount} HEAD`);
-    return output.trim().split('\n').filter(Boolean);
-  } catch {
-    return [];
-  }
-}
-
-function globMatch(filePath, pattern) {
-  return minimatch(filePath, pattern);
-}
-
-function getAllowedPatterns(lastBase, foundryDir, cycleDef, io = defaultIO) {
-  const always = ['WORK.md', 'WORK.history.yaml'];
-
-  if (lastBase !== 'forge') {
-    return always;
-  }
-
-  // For forge: also allow the output artefact's file-patterns
-  try {
-    const cycleText = io.readFile(cycleDef);
-    const cycleFm = parseFrontmatter(cycleText);
-    const outputType = cycleFm.output;
-    if (!outputType) return always;
-
-    const artDefPath = `${foundryDir}/artefacts/${outputType}/definition.md`;
-    if (!io.exists(artDefPath)) return always;
-
-    const artText = io.readFile(artDefPath);
-    const artFm = parseFrontmatter(artText);
-    const filePatterns = artFm['file-patterns'] || [];
-    return [...always, ...filePatterns];
-  } catch {
-    return always;
-  }
-}
-
-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 };
-}
-
-// ---------------------------------------------------------------------------
-// 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
-// ---------------------------------------------------------------------------
-
-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' };
-  }
-
-  const workText = io.readFile(workPath);
-  const frontmatter = parseFrontmatter(workText);
-
-  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' };
-  if (!findFirst(stages, 'forge')) return { route: 'blocked', details: 'stages must include at least one forge stage' };
-
-  const artefacts = parseArtefactsTable(workText);
-  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) {
-    const lastEntry = nonSortHistory[nonSortHistory.length - 1];
-    const lastBase = baseStage(lastEntry.stage || '');
-    const resolvedCycleDef = cycleDef || frontmatter['cycle-def'] || `${foundryDir}/cycles/${cycle}.md`;
-    const result = checkModifiedFiles(lastBase, foundryDir, resolvedCycleDef, cycle, io);
-    if (!result.ok) {
-      return { route: 'violation', details: `File modification violation after ${lastBase} stage: ${result.violations.join(', ')}` };
-    }
-  }
-
-  // Tag validation
-  const tagErrors = validateTags(workText, foundryDir);
-  if (tagErrors.length > 0) {
-    const details = tagErrors.map(e => `line ${e.line}: ${e.message}`).join('; ');
-    return { route: 'violation', details: `Feedback tag validation failed: ${details}` };
-  }
-
-  const route = determineRoute(stages, history, feedback, maxIterations, {
-    humanAppraise: humanAppraiseEnabled,
-    deadlockAppraise,
-    deadlockIterations,
-    cycle,
-  });
-
-  // Model resolution
-  let model = null;
-  const routeBase = baseStage(route);
-  if (frontmatter.models && frontmatter.models[routeBase]) {
-    const modelId = frontmatter.models[routeBase];
-    model = `foundry-${modelId.replace(/[/.]/g, '-')}`;
-
-    // Fail-fast: required subagent file must exist
-    const agentPath = `${agentsDir}/${model}.md`;
-    if (!io.exists(agentPath)) {
-      return {
-        route: 'violation',
-        details: `Missing required subagent: ${model}.md is not present in ${agentsDir}/. Run the refresh-agents skill to regenerate agent files, then restart.`,
-      };
-    }
-  }
-
-  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;
-}
-
-// ---------------------------------------------------------------------------
-// Exports (for testing) — keep main() private
-// ---------------------------------------------------------------------------
-
-export { parseArtefactsTable } from './lib/artefacts.js';
-export { loadHistory } from './lib/history.js';
-export { parseFeedback, parseFeedbackItem } from './lib/feedback.js';
-
-export {
-  baseStage,
-  findFirst,
-  nextInRoute,
-  parseFrontmatter,
-  determineRoute,
-  nextAfterQuench,
-  nextAfterAppraise,
-  globMatch,
-  getModifiedFiles,
-  getAllowedPatterns,
-  checkModifiedFiles,
-  getDirtyToolManagedFiles,
-};
-
-

package/scripts/validate-tags.js

@@ -1,54 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Validate feedback tags in WORK.md.
- *
- * Checks that every feedback item tag:
- *   1. Matches allowed syntax: #validation, #law:<id>, or #hitl
- *   2. For #law:<id>, the law id exists in foundry/laws/*.md or the
- *      relevant artefact type's laws.md
- *
- * Usage:
- *     node scripts/validate-tags.js [--work WORK.md] [--foundry-dir foundry]
- *
- * Exit 0 and prints "OK" if all tags are valid.
- * Exit 1 and prints invalid items to stderr otherwise.
- */
-
-import { readFileSync, existsSync } from 'fs';
-import { parseArgs } from 'util';
-import { validateTags } from './lib/tags.js';
-
-function main() {
-  const { values } = parseArgs({
-    options: {
-      work: { type: 'string', default: 'WORK.md' },
-      'foundry-dir': { type: 'string', default: 'foundry' },
-    },
-  });
-
-  const workPath = values.work;
-  const foundryDir = values['foundry-dir'];
-
-  if (!existsSync(workPath)) {
-    process.stderr.write('ERROR: WORK.md not found\n');
-    process.exit(2);
-  }
-
-  const workText = readFileSync(workPath, 'utf-8');
-  const errors = validateTags(workText, foundryDir);
-
-  if (errors.length === 0) {
-    console.log('OK');
-    process.exit(0);
-  }
-
-  process.stderr.write(`Tag validation failed (${errors.length} issue${errors.length > 1 ? 's' : ''}):\n`);
-  for (const err of errors) {
-    process.stderr.write(`  line ${err.line}: ${err.message}\n`);
-    process.stderr.write(`    ${err.raw}\n`);
-  }
-  process.exit(1);
-}
-
-main();

package/skills/add-law/SKILL.md

@@ -1,111 +0,0 @@
----
-name: add-law
-type: atomic
-description: Creates a new law, checking for conflicts with existing laws.
----
-
-# Add Law
-
-You help the user create a new law. You ensure it's well-scoped, doesn't conflict with existing laws, and ends up in the right file.
-
-## Prerequisites
-
-Before running this skill, verify both of the following:
-
-1. The `foundry/` directory exists in the project root. If it does not exist, stop and tell the user:
-
-   > Foundry is not initialized in this project. Run the `init-foundry` skill first to create the foundry/ directory structure.
-
-2. The current git branch is not a work branch. Run `git rev-parse --abbrev-ref HEAD` — if it starts with `work/`, stop and tell the user:
-
-   > You're on a work branch (`<branch>`). Foundry configuration changes must be made on the base branch (usually `main`). Complete or discard the in-flight flow (`foundry_git_finish`, or switch branches and delete it), then re-run this skill from the base branch.
-
-## Protocol
-
-### 1. Determine scope
-
-If the user specifies where the law applies:
-- "global law" → goes in `foundry/laws/` (ask which file, or create a new one)
-- "law for X artefacts" → goes in `foundry/artefacts/<type>/laws.md`
-
-If the user doesn't specify, ask:
-
-> Should this law apply globally to all artefact types, or to a specific type?
-
-If they name a type, verify it exists in `foundry/artefacts/`. If it doesn't, tell them and ask if they want to create the artefact type first.
-
-### 2. Draft the law
-
-Write the law following the standard format:
-
-```markdown
-## <law-id>
-
-<What this law checks — one or two sentences.>
-
-Passing: <What a passing artefact looks like.>
-Failing: <What a failing artefact looks like.>
-```
-
-The `law-id` (heading) should be:
-- Lowercase, hyphenated
-- Short but descriptive
-- Unique across all laws (global and type-specific)
-
-### 3. Check for conflicts
-
-Read all existing laws that would apply to the same artefact types:
-- All files in `foundry/laws/` (global)
-- `foundry/artefacts/<type>/laws.md` if the law is type-specific
-- If the law is global, also read all `foundry/artefacts/*/laws.md` since a global law applies everywhere
-
-For each existing law, check:
-- Does the new law contradict an existing law? (e.g., "must be formal" vs "must be conversational")
-- Does the new law duplicate an existing law? (same criterion, different wording)
-- Does the new law overlap with an existing law? (partially covers the same ground)
-
-If any conflict is found, present it to the user:
-
-> The new law `<new-id>` may conflict with existing law `<existing-id>`:
-> - New: <summary of new law>
-> - Existing: <summary of existing law>
-> - Conflict: <what the conflict is>
->
-> Options:
-> 1. Proceed anyway (both laws will apply)
-> 2. Replace the existing law with the new one
-> 3. Rephrase the new law to avoid the conflict
-> 4. Cancel
-
-### 4. Refine with the user
-
-Present the drafted law to the user before writing it. Ask:
-
-> Here's the draft law:
->
-> ## <law-id>
->
-> <law content>
->
-> Does this capture what you want, or should we adjust the wording?
-
-Iterate until the user is happy.
-
-### 5. Write the law
-
-Append the law to the appropriate file:
-- Global: the specified file in `foundry/laws/`, or a new file
-- Type-specific: `foundry/artefacts/<type>/laws.md`
-
-If the target file doesn't exist yet, create it with a top-level heading.
-
-### 6. Verify uniqueness
-
-After writing, confirm the law id is unique. If there's a collision, ask the user to rename.
-
-## What you do NOT do
-
-- You do not write the law without showing the user first
-- You do not skip the conflict check
-- You do not silently overwrite existing laws
-- You do not create artefact types — that is a separate skill

package/skills/forge/SKILL.md

@@ -1,88 +0,0 @@
----
-name: forge
-type: atomic
-description: Produces or revises an artefact, guided by WORK.md and the foundry cycle definition.
----
-
-# Forge
-
-You produce or revise artefacts. You read the work file to understand the goal and feedback, and the foundry cycle definition to understand what you're producing and what inputs you can read.
-
-## Prerequisites
-
-Before running this skill, verify that the `foundry/` directory exists in the project root. If it does not exist, stop and tell the user:
-
-> Foundry is not initialized in this project. Run the `init-foundry` skill first to create the foundry/ directory structure.
-
-## Stage lifecycle (mandatory)
-
-Forge runs inside an enforced stage. Your **first** and **last** tool calls are fixed:
-
-1. **First:** `foundry_stage_begin({stage, cycle, token})` — the orchestrator hands you `stage`, `cycle`, and an opaque `token` string in the dispatch prompt. Copy the token verbatim; never invent, edit, or re-sign it. No other tool call is permitted before this one. Any writes before `stage_begin` will be blocked by preconditions.
-2. **Last:** `foundry_stage_end({summary})` — return control to the orchestrator. After `stage_end`, the orchestrator calls `foundry_stage_finalize` which scans the disk and registers your output artefact. **You do not register artefacts yourself.**
-
-## Protocol
-
-### First generation (no artefact registered yet)
-
-1. `foundry_stage_begin(...)` with the token from the dispatch prompt.
-2. `foundry_workfile_get` — understand the goal.
-3. `foundry_config_cycle` — understand what to produce and what inputs are available.
-4. `foundry_config_artefact_type` with the output type ID — get the artefact type definition, especially its `file-patterns`.
-5. `foundry_config_laws` — get all applicable laws (global + type-specific).
-6. If the cycle declares `inputs`, discover input files by filesystem scan:
-   - For each type listed in `inputs`, call `foundry_config_artefact_type` to get its `file-patterns`.
-   - Glob the working tree against those patterns to enumerate candidate input files.
-   - Read the goal (from `foundry_workfile_get`) and select the files that are relevant to this run. If the goal names specific files or slugs, use those; if it describes a category ("all the auth tests"), select the matching subset; if it's open-ended, you may consume all candidates or ask the user when the set is clearly ambiguous.
-   - Read the selected files for context.
-7. Produce the artefact, respecting all applicable laws from the start.
-8. Write the artefact file to a location that matches the artefact type's `file-patterns`.
-9. `foundry_stage_end({summary})`.
-
-### Revision (feedback exists)
-
-1. `foundry_stage_begin(...)`.
-2. `foundry_feedback_list` — find unresolved feedback for the artefact.
-3. Read the artefact file.
-4. If the cycle declares `inputs`, discover them via filesystem scan against each input type's `file-patterns` (same protocol as first-generation step 6). Re-read the relevant files — they may have changed on disk since the previous iteration (nothing in this cycle wrote to them, but the user may have modified them between iterations).
-5. For each unresolved feedback item, either:
-   - Address it and call `foundry_feedback_action` (marks item `actioned`), or
-   - Call `foundry_feedback_wontfix` with a justification — available only for `law:` / `human` tags (validation feedback must be actioned).
-6. Update the artefact file.
-7. `foundry_stage_end({summary})`.
-
-## Write invariant
-
-Forge may only write to:
-- Files matching the output artefact type's `file-patterns`.
-- `WORK.md` and `WORK.history.yaml` (tool-managed).
-
-Everything else on disk — including files of the cycle's input types, files of unrelated artefact types, and files outside any artefact type — is read-only for this stage. This is not an honor-system rule: `foundry_stage_finalize` returns `{error: 'unexpected_files'}` and `sort`'s `checkModifiedFiles` routes a violation on the next call. Either outcome marks the cycle's target artefact `blocked` and you do not get a retry.
-
-When a cycle's output type overlaps with one of its input types (e.g. a `refine-haiku` cycle with input `haiku` and output `haiku`), the overlap is intentional: the cycle's job is to modify existing files of that type. The write invariant still holds — you may only touch files matching the output type's patterns, which in this case includes the files you read as inputs.
-
-## Unresolved feedback
-
-An item is unresolved if it is:
-- `open` — not yet addressed
-- `rejected` — actioned or wont-fixed but rejected by appraiser, effectively re-opened
-
-An item is resolved if it is `approved`.
-
-## #human feedback
-
-Feedback tagged `human` (from the human-appraise stage) takes absolute priority:
-- You MUST address it — you cannot wont-fix `#human` feedback.
-- When `#human` feedback contradicts LLM appraiser feedback on the same topic, follow the human's direction.
-- Acknowledge the human's input in your revision.
-
-## What you do NOT do
-
-- You do not add feedback — that is the quench and appraise skills' job. (`foundry_feedback_add` is blocked for you at the tool layer.)
-- You do not `foundry_feedback_resolve` — that belongs to quench/appraise/human-appraise.
-- You do not register artefacts — `foundry_stage_finalize` handles that automatically.
-- You do not call `foundry_history_append` or `foundry_git_commit` — the sort skill does.
-- You do not evaluate or score the artefact.
-- You do not mark feedback as actioned unless you actually changed the artefact to address it.
-- You do not wont-fix validation feedback.
-- You do not write to any file outside the output artefact type's `file-patterns` (plus `WORK.md` / `WORK.history.yaml`). Input files are read-only unless the output type's patterns happen to cover them.