@really-knows-ai/foundry 1.0.0

package/scripts/sort.js

@@ -0,0 +1,410 @@
+#!/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 { parseArgs } from 'util';
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+import yaml from 'js-yaml';
+import { minimatch } from 'minimatch';
+import { validateTags, extractAllTags } from './lib/tags.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
+// ---------------------------------------------------------------------------
+
+function parseFrontmatter(text) {
+  const match = text.match(/^---\n(.+?)\n---/s);
+  if (!match) return {};
+  return yaml.load(match[1]) || {};
+}
+
+function parseFeedback(text, cycle, artefacts) {
+  const cycleFiles = new Set();
+  for (const art of artefacts) {
+    if (art.cycle === cycle) {
+      cycleFiles.add(art.file || '');
+    }
+  }
+
+  const items = [];
+  let currentFile = null;
+  let inFeedback = false;
+
+  for (const line of text.split('\n')) {
+    const stripped = line.trim();
+
+    if (stripped === '# Feedback') {
+      inFeedback = true;
+      continue;
+    }
+
+    if (inFeedback && stripped.startsWith('# ') && stripped !== '# Feedback') {
+      inFeedback = false;
+      continue;
+    }
+
+    if (!inFeedback) continue;
+
+    if (stripped.startsWith('## ')) {
+      currentFile = stripped.slice(3).trim();
+      continue;
+    }
+
+    if (cycleFiles.has(currentFile) && /^- \[/.test(stripped)) {
+      items.push(parseFeedbackItem(stripped));
+    }
+  }
+
+  return items;
+}
+
+function parseFeedbackItem(line) {
+  const item = { raw: line, state: 'unknown', tags: [], resolved: false };
+
+  if (line.startsWith('- [ ]')) {
+    item.state = 'open';
+  } else if (line.startsWith('- [x]')) {
+    item.state = 'actioned';
+  } else if (line.startsWith('- [~]')) {
+    item.state = 'wont-fix';
+  }
+
+  if (line.includes('| approved')) {
+    item.resolved = true;
+  } else if (line.includes('| rejected')) {
+    item.state = 'rejected';
+    item.resolved = false;
+  }
+
+  item.tags = extractAllTags(line);
+
+  return item;
+}
+
+function parseArtefactsTable(text) {
+  const artefacts = [];
+  let inTable = false;
+
+  for (const line of text.split('\n')) {
+    const stripped = line.trim();
+
+    if (stripped.startsWith('| File')) {
+      inTable = true;
+      continue;
+    }
+    if (inTable && stripped.startsWith('|---')) {
+      continue;
+    }
+    if (inTable && stripped.startsWith('|')) {
+      const cols = stripped.split('|').slice(1, -1).map(c => c.trim());
+      if (cols.length >= 4) {
+        artefacts.push({
+          file: cols[0],
+          type: cols[1],
+          cycle: cols[2],
+          status: cols[3],
+        });
+      }
+    } else if (inTable) {
+      inTable = false;
+    }
+  }
+
+  return artefacts;
+}
+
+function loadHistory(historyPath, cycle, io = defaultIO) {
+  if (!io.exists(historyPath)) return [];
+  const data = yaml.load(io.readFile(historyPath)) || [];
+  return data.filter(e => e.cycle === cycle);
+}
+
+// ---------------------------------------------------------------------------
+// Routing logic
+// ---------------------------------------------------------------------------
+
+function determineRoute(stages, history, feedback, maxIterations) {
+  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 === 'hitl') {
+    const next = nextInRoute(stages, lastEntry);
+    return next ?? 'done';
+  }
+
+  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, feedback, forgeCount, maxIterations);
+  }
+
+  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, 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';
+  }
+
+  const pendingApproval = feedback.some(
+    f => (f.state === 'actioned' || f.state === 'wont-fix') && !f.resolved
+  );
+  if (pendingApproval) {
+    return findFirst(stages, 'appraise') ?? 'blocked';
+  }
+
+  return '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 };
+}
+
+// ---------------------------------------------------------------------------
+// Exports (for testing) — keep main() private
+// ---------------------------------------------------------------------------
+
+export {
+  baseStage,
+  findFirst,
+  nextInRoute,
+  parseFrontmatter,
+  parseFeedback,
+  parseFeedbackItem,
+  parseArtefactsTable,
+  loadHistory,
+  determineRoute,
+  nextAfterQuench,
+  nextAfterAppraise,
+  globMatch,
+  getModifiedFiles,
+  getAllowedPatterns,
+  checkModifiedFiles,
+};
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const { values } = parseArgs({
+    options: {
+      work: { type: 'string', default: 'WORK.md' },
+      history: { type: 'string', default: 'WORK.history.yaml' },
+      'foundry-dir': { type: 'string', default: 'foundry' },
+      'cycle-def': { type: 'string' },
+    },
+  });
+
+  const workPath = values.work;
+  const historyPath = values.history;
+  const foundryDir = values['foundry-dir'];
+
+  if (!existsSync(workPath)) {
+    process.stderr.write('ERROR: WORK.md not found\n');
+    process.exit(1);
+  }
+
+  const workText = readFileSync(workPath, 'utf-8');
+  const frontmatter = parseFrontmatter(workText);
+
+  const cycle = frontmatter.cycle;
+  const stages = frontmatter.stages;
+  const maxIterations = frontmatter['max-iterations'] ?? 3;
+
+  if (!cycle) {
+    process.stderr.write('ERROR: No cycle in WORK.md frontmatter\n');
+    process.exit(1);
+  }
+
+  if (!stages || !Array.isArray(stages)) {
+    process.stderr.write('ERROR: No stages in WORK.md frontmatter\n');
+    process.exit(1);
+  }
+
+  if (!findFirst(stages, 'forge')) {
+    process.stderr.write('ERROR: stages must include at least one forge stage\n');
+    process.exit(1);
+  }
+
+  const artefacts = parseArtefactsTable(workText);
+  const history = loadHistory(historyPath, cycle);
+  const feedback = parseFeedback(workText, cycle, artefacts);
+
+  // --- 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 || '');
+
+    // Resolve cycle-def: CLI arg > WORK.md frontmatter field
+    const cycleDef = values['cycle-def']
+      || frontmatter['cycle-def']
+      || `${foundryDir}/cycles/${cycle}.md`;
+
+    const result = checkModifiedFiles(lastBase, foundryDir, cycleDef, cycle);
+    if (!result.ok) {
+      console.log('violation');
+      process.stderr.write(`File modification violation after ${lastBase} stage:\n`);
+      result.violations.forEach(f => process.stderr.write(`  ${f}\n`));
+      process.exit(0);
+    }
+  }
+
+  // --- Tag validation ---
+  const tagErrors = validateTags(workText, foundryDir);
+  if (tagErrors.length > 0) {
+    console.log('violation');
+    process.stderr.write(`Feedback tag validation failed (${tagErrors.length} issue${tagErrors.length > 1 ? 's' : ''}):\n`);
+    tagErrors.forEach(e => process.stderr.write(`  line ${e.line}: ${e.message}\n`));
+    process.exit(0);
+  }
+
+  const route = determineRoute(stages, history, feedback, maxIterations);
+  console.log(route);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main();
+}

package/scripts/validate-tags.js

@@ -0,0 +1,54 @@
+#!/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-appraiser/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: add-appraiser
+type: atomic
+description: Creates a new appraiser personality, checking for semantic overlap with existing appraisers.
+---
+
+# Add Appraiser
+
+You help the user create a new appraiser personality. You ensure it's genuinely distinct from existing appraisers and scaffold the definition file.
+
+## Protocol
+
+### 1. Gather basics
+
+From the user's prompt, establish:
+- `id` — lowercase, hyphenated identifier
+- `name` — a short character name (e.g., "The Pedant", "The Pragmatist")
+- `model` — (optional) a specific model ID to use for this appraiser (e.g., `openai/gpt-4o`). Overrides the cycle-level model for the appraise stage. If omitted, the appraiser uses whatever model the cycle's appraise stage is configured with.
+- A prose description of the personality: how they think, what they prioritize, how they evaluate
+
+If `id`, `name`, or the personality description are missing, ask. The `model` field is optional — only ask about it if the user mentions wanting a specific model for this appraiser.
+
+### 2. Check for id conflicts
+
+Read all existing appraiser definitions in `foundry/appraisers/*.md`.
+
+- Exact id match → hard conflict, must choose a different id
+
+### 3. Check for semantic overlap
+
+For each existing appraiser, compare the new personality against it:
+- What does this appraiser prioritize?
+- What lens do they evaluate through?
+- Would two artefacts get meaningfully different feedback from these appraisers?
+
+If significant overlap is found, present it to the user:
+
+> The new appraiser `<new-id>` seems to overlap with existing appraiser `<existing-id>`:
+> - New: <name> — <personality summary>
+> - Existing: <name> — <personality summary>
+> - Overlap: <what makes them similar>
+>
+> Appraiser diversity matters — similar personalities produce redundant feedback.
+>
+> Options:
+> 1. Proceed anyway (the distinction is meaningful enough)
+> 2. Adjust the new personality to be more distinct
+> 3. Replace the existing appraiser with a revised version
+> 4. Cancel
+
+Do not proceed until the user has decided.
+
+### 4. Draft the definition
+
+Present the definition to the user:
+
+```markdown
+---
+id: <id>
+name: <name>
+model: <model-id>            # only include if specified
+---
+
+# <Name>
+
+<personality description — 2-4 sentences describing how this appraiser thinks, what they care about, and how they approach evaluation>
+```
+
+Ask: does this capture the personality correctly?
+
+### 5. Refine with the user
+
+Iterate until the user is happy with the personality description. Key things to check:
+- Is the personality distinct enough from existing appraisers?
+- Does the description give the LLM enough direction to adopt a consistent voice?
+- Is it clear what this appraiser would flag vs let pass?
+
+### 6. Write the file
+
+Create `foundry/appraisers/<id>.md` with the agreed definition.
+
+### 7. Mention artefact type configuration
+
+After creating the appraiser, remind the user:
+
+> Appraiser `<id>` is now available. To use it for a specific artefact type, add it to the `appraisers.allowed` list in that type's `definition.md` frontmatter:
+>
+> ```yaml
+> appraisers:
+>   count: 3
+>   allowed: [<id>, ...]
+> ```
+>
+> If no `allowed` list is specified, all available appraisers (including this new one) are eligible.
+
+## What you do NOT do
+
+- You do not write files without showing the user first
+- You do not skip the semantic overlap check
+- You do not modify artefact type definitions — that is the user's choice
+- You do not create appraisers with duplicate ids

package/skills/add-artefact-type/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: add-artefact-type
+type: atomic
+description: Creates a new artefact type, checking for conflicts with existing types.
+---
+
+# Add Artefact Type
+
+You help the user create a new artefact type. You ensure it doesn't conflict with existing types, scaffold the directory structure, and walk the user through defining laws and validation.
+
+## Protocol
+
+### 1. Gather basics
+
+From the user's prompt, establish:
+- `id` — lowercase, hyphenated identifier
+- `name` — human-readable name
+- `file-patterns` — glob patterns for files this type produces
+- `output` — output directory
+- A prose description of what this artefact type is
+
+If any of these are missing, ask.
+
+### 2. Check for naming conflicts
+
+Read all existing artefact type definitions in `foundry/artefacts/*/definition.md`.
+
+- Exact id match → hard conflict, must choose a different id
+- Semantically similar name or description → warn the user. Ask:
+
+> An artefact type `<existing-id>` already exists that seems similar:
+> - Existing: <name> — <description summary>
+> - New: <name> — <description summary>
+>
+> Is the new type genuinely distinct, or should you extend the existing one?
+
+### 3. Check for glob intersection
+
+For each existing artefact type, check whether the new type's `file-patterns` could match the same files as any existing type's `file-patterns`.
+
+Examples of intersections:
+- `features/*.feature` vs `features/*.feature` — exact overlap
+- `features/**` vs `features/*.feature` — subset overlap
+- `output/*.md` vs `output/reports/*.md` — potential overlap if nested
+
+If any intersection is found, this is a hard block:
+
+> The file pattern `<new-pattern>` intersects with artefact type `<existing-id>` which uses `<existing-pattern>`.
+>
+> Overlapping file patterns break file modification enforcement — the foundry cycle cannot determine which artefact type owns a file change.
+>
+> Please choose a different file pattern that does not overlap with any existing type.
+
+Do not proceed until the patterns are non-overlapping.
+
+### 4. Draft the definition
+
+Present the definition to the user:
+
+```markdown
+---
+id: <id>
+name: <name>
+file-patterns:
+  - "<pattern>"
+output: <output-dir>
+appraisers:
+  count: 3
+---
+
+# <Name>
+
+<description>
+```
+
+Ask: does this capture the artefact type correctly?
+
+### 5. Laws (optional)
+
+Ask:
+
+> Do you want to define any type-specific laws for this artefact type? (Global laws in `foundry/laws/` will apply automatically.)
+
+If yes, walk through each law using the same format as `add-law`:
+- Draft each law
+- Check for conflicts with global laws and any existing type-specific laws
+- Confirm with the user
+
+### 6. Appraisers (optional)
+
+Ask:
+
+> How should appraisers be configured for this artefact type?
+> - How many appraisers per foundry cycle? (default: 3)
+> - Restrict to specific appraiser personalities? (default: all available)
+
+If the user specifies preferences, add an `appraisers` section to the definition frontmatter:
+
+```yaml
+appraisers:
+  count: 3                              # how many appraisers (default: 3)
+  allowed: [pedantic, pragmatic]        # which personalities (default: all available)
+```
+
+If the user is happy with the defaults (3 appraisers, any personality), add just:
+
+```yaml
+appraisers:
+  count: 3
+```
+
+List the available appraisers from `foundry/appraisers/*.md` so the user can see their options.
+
+### 7. Validation (optional)
+
+Ask:
+
+> Do you want to define any deterministic validation commands for this artefact type?
+
+If yes, walk through each validation entry:
+- A `## heading` (identifier)
+- A `Command:` line with `{file}` placeholder
+- A `Failure means:` line explaining what a non-zero exit indicates
+
+### 8. Scaffold
+
+Create the directory and files:
+
+```
+foundry/artefacts/<id>/
+  definition.md      # always created
+  laws.md            # created if laws were defined
+  validation.md      # created if validation commands were defined
+```
+
+If laws or validation were skipped, do not create empty files.
+
+### 9. Confirm
+
+Show the user the complete file listing and contents. Confirm before writing.
+
+## What you do NOT do
+
+- You do not create artefact types with overlapping file patterns — this is a hard block
+- You do not write files without showing the user first
+- You do not skip the naming or glob checks
+- You do not create laws without checking for conflicts (delegate to add-law pattern)