@really-knows-ai/foundry 1.3.1 → 1.4.0

package/.opencode/plugins/foundry.js

@@ -13,7 +13,7 @@ import { readFileSync, writeFileSync, existsSync, readdirSync, unlinkSync } from
 import { fileURLToPath } from 'url';
 import { tool } from '@opencode-ai/plugin';
 import { loadHistory, appendEntry, getIteration } from '../../scripts/lib/history.js';
-import { parseFrontmatter, createWorkfile, setFrontmatterField, getFrontmatterField } from '../../scripts/lib/workfile.js';
+import { parseFrontmatter, createWorkfile, setFrontmatterField, getFrontmatterField, enrichStages } from '../../scripts/lib/workfile.js';
 import { parseArtefactsTable, addArtefactRow, setArtefactStatus } from '../../scripts/lib/artefacts.js';
 import { addFeedbackItem, actionFeedbackItem, wontfixFeedbackItem, resolveFeedbackItem, listFeedback } from '../../scripts/lib/feedback.js';
 import { getCycleDefinition, getArtefactType, getLaws, getValidation, getAppraisers, getFlow, selectAppraisers } from '../../scripts/lib/config.js';
@@ -132,15 +132,17 @@ export const FoundryPlugin = async ({ directory }) => {
           stages: tool.schema.array(tool.schema.string()).describe('Ordered stage names'),
           maxIterations: tool.schema.number().describe('Maximum iterations'),
           goal: tool.schema.string().describe('Goal text'),
-          models: tool.schema.record(tool.schema.string()).optional().describe('Per-stage model overrides'),
+          models: tool.schema.string().optional().describe('Per-stage model overrides as JSON object, e.g. \'{"forge":"openai/gpt-4o"}\''),
         },
         async execute(args, context) {
           const workPath = path.join(context.worktree, 'WORK.md');
           if (existsSync(workPath)) {
             return JSON.stringify({ error: 'WORK.md already exists' });
           }
-          const fm = { flow: args.flow, cycle: args.cycle, stages: args.stages, maxIterations: args.maxIterations };
-          if (args.models) fm.models = args.models;
+          const fm = { flow: args.flow, cycle: args.cycle, stages: enrichStages(args.stages, args.cycle), maxIterations: args.maxIterations };
+          if (args.models) {
+            try { fm.models = JSON.parse(args.models); } catch { fm.models = {}; }
+          }
           const content = createWorkfile(fm, args.goal);
           writeFileSync(workPath, content, 'utf-8');
           return JSON.stringify({ ok: true });
@@ -167,7 +169,7 @@ export const FoundryPlugin = async ({ directory }) => {
         description: 'Update a single frontmatter field in WORK.md',
         args: {
           key: tool.schema.string().describe('Frontmatter key'),
-          value: tool.schema.any().describe('Value to set'),
+          value: tool.schema.string().describe('Value to set (use JSON for arrays/objects, e.g. \'["forge:a","quench:b"]\' or \'{"forge":"openai/gpt-4o"}\')'),
         },
         async execute(args, context) {
           const workPath = path.join(context.worktree, 'WORK.md');
@@ -175,7 +177,24 @@ export const FoundryPlugin = async ({ directory }) => {
             return JSON.stringify({ error: 'WORK.md not found' });
           }
           const text = readFileSync(workPath, 'utf-8');
-          const updated = setFrontmatterField(text, args.key, args.value);
+          // Parse JSON values for arrays/objects, keep strings as-is
+          let value = args.value;
+          try {
+            const parsed = JSON.parse(args.value);
+            if (typeof parsed === 'object' || Array.isArray(parsed) || typeof parsed === 'number') {
+              value = parsed;
+            }
+          } catch {
+            // Not JSON, use as plain string
+          }
+          // Auto-enrich bare stage names with cycle ID alias
+          if (args.key === 'stages' && Array.isArray(value)) {
+            const fm = parseFrontmatter(text);
+            if (fm.cycle) {
+              value = enrichStages(value, fm.cycle);
+            }
+          }
+          const updated = setFrontmatterField(text, args.key, value);
           writeFileSync(workPath, updated, 'utf-8');
           return JSON.stringify({ ok: true });
         },
@@ -448,15 +467,15 @@ export const FoundryPlugin = async ({ directory }) => {
         async execute(args, context) {
           const io = makeIO(context.worktree);
           const commands = await getValidation('foundry', args.typeId, io);
-          if (!commands) return JSON.stringify({ error: 'No validation defined for type: ' + args.typeId });
+          if (!commands || commands.length === 0) return JSON.stringify({ error: 'No validation defined for type: ' + args.typeId });
           const results = [];
-          for (const cmd of commands) {
-            const expanded = cmd.replace(/\{file\}/g, args.file);
+          for (const entry of commands) {
+            const expanded = entry.command.replace(/\{file\}/g, args.file);
             try {
               const output = execSync(expanded, { cwd: context.worktree, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
-              results.push({ command: expanded, passed: true, output: output.trim() });
+              results.push({ id: entry.id, command: expanded, passed: true, output: output.trim() });
             } catch (err) {
-              results.push({ command: expanded, passed: false, output: (err.stderr || err.stdout || err.message || '').trim() });
+              results.push({ id: entry.id, command: expanded, passed: false, output: (err.stderr || err.stdout || err.message || '').trim(), failureMeans: entry.failureMeans });
             }
           }
           return JSON.stringify(results);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@really-knows-ai/foundry",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "A structured framework for AI-driven artefact creation with deterministic routing, quality gates, and iterative refinement cycles.",
   "type": "module",
   "main": ".opencode/plugins/foundry.js",

package/scripts/lib/config.js

@@ -89,16 +89,37 @@ export async function getValidation(foundryDir, typeId, io) {
     return null;
   }
   const text = await io.readFile(path);
-  const commands = [];
-  const regex = /```(?:bash|sh)\n([\s\S]*?)```/g;
-  let match;
-  while ((match = regex.exec(text)) !== null) {
-    for (const line of match[1].trim().split('\n')) {
-      const trimmed = line.trim();
-      if (trimmed) commands.push(trimmed);
+  const entries = [];
+  const lines = text.split('\n');
+  let currentId = null;
+  let currentCommand = null;
+  let currentFailure = null;
+
+  function flush() {
+    if (currentId && currentCommand) {
+      const entry = { id: currentId, command: currentCommand };
+      if (currentFailure) entry.failureMeans = currentFailure;
+      entries.push(entry);
     }
+    currentId = null;
+    currentCommand = null;
+    currentFailure = null;
   }
-  return commands;
+
+  for (const line of lines) {
+    const heading = line.match(/^## (.+)/);
+    if (heading) {
+      flush();
+      currentId = heading[1].trim();
+    } else if (currentId) {
+      const cmdMatch = line.match(/^Command:\s*(.+)/);
+      const failMatch = line.match(/^Failure means:\s*(.+)/);
+      if (cmdMatch) currentCommand = cmdMatch[1].trim();
+      if (failMatch) currentFailure = failMatch[1].trim();
+    }
+  }
+  flush();
+  return entries;
 }
 
 export async function getAppraisers(foundryDir, io) {

package/scripts/lib/feedback.js

@@ -38,6 +38,7 @@ export function parseFeedback(text, cycle, artefacts) {
       cycleFiles.add(art.file || '');
     }
   }
+  const filterByFile = cycleFiles.size > 0;
 
   const items = [];
   let currentFile = null;
@@ -71,7 +72,7 @@ export function parseFeedback(text, cycle, artefacts) {
       continue;
     }
 
-    if (cycleFiles.has(currentFile) && /^- \[/.test(stripped)) {
+    if ((!filterByFile || cycleFiles.has(currentFile)) && /^- \[/.test(stripped)) {
       items.push(parseFeedbackItem(stripped));
     }
   }
@@ -183,6 +184,7 @@ export function listFeedback(text, cycle, artefacts, filterFile) {
       cycleFiles.add(art.file || '');
     }
   }
+  const filterByCycle = cycleFiles.size > 0;
 
   const results = [];
   let currentFile = null;
@@ -216,7 +218,7 @@ export function listFeedback(text, cycle, artefacts, filterFile) {
       continue;
     }
 
-    if (cycleFiles.has(currentFile) && /^- \[/.test(stripped)) {
+    if ((!filterByCycle || cycleFiles.has(currentFile)) && /^- \[/.test(stripped)) {
       if (!filterFile || filterFile === currentFile) {
         const item = parseFeedbackItem(stripped);
         results.push({

package/scripts/lib/workfile.js

@@ -34,6 +34,19 @@ export function setFrontmatterField(text, key, value) {
   return body ? `${fmBlock}\n${body}` : fmBlock;
 }
 
+// ---------------------------------------------------------------------------
+// Stage alias enrichment
+// ---------------------------------------------------------------------------
+
+/**
+ * Ensure each stage has a base:alias format.
+ * Bare names (e.g. "forge") become "forge:<cycleId>".
+ * Already-aliased names (e.g. "forge:write-haiku") pass through unchanged.
+ */
+export function enrichStages(stages, cycleId) {
+  return stages.map(s => s.includes(':') ? s : `${s}:${cycleId}`);
+}
+
 // ---------------------------------------------------------------------------
 // Workfile creation
 // ---------------------------------------------------------------------------
@@ -45,8 +58,8 @@ export function createWorkfile(frontmatter, goal) {
 
 ${goal}
 
-| Artefact | Status |
-|----------|--------|
+| File | Type | Cycle | Status |
+|------|------|-------|--------|
 
 ## Feedback
 `;

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

@@ -128,6 +128,11 @@ If yes, walk through each validation entry:
 - A `Command:` line with `{file}` placeholder
 - A `Failure means:` line explaining what a non-zero exit indicates
 
+If the user wants validation scripts (not just inline commands), create them as separate files in the artefact type directory. Check the project's `package.json` for `"type": "module"`:
+- If ESM (`"type": "module"`): use `import` syntax, or name scripts with `.mjs` extension
+- If CommonJS (no `"type"` field or `"type": "commonjs"`): `require()` is fine, or use `.cjs` extension
+- When in doubt, use `.mjs` or `.cjs` extensions to be explicit regardless of project settings
+
 ### 8. Scaffold
 
 Create the directory and files:

package/skills/cycle/SKILL.md

@@ -23,6 +23,7 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
    - Use the cycle definition's `stages` field if present
    - Otherwise generate defaults: always `forge`, add `quench` if `foundry_config_validation` returns non-null for the type, always `appraise`
    - Cycle definitions can include `hitl` entries for human-in-the-loop checkpoints
+   - Stages should use `base:alias` format (e.g. `forge:write-haiku`, `quench:check-syllables`). If you pass bare names, the tool will auto-append the cycle ID as the alias.
 4. Call `foundry_workfile_set` to configure the work file:
    - `key: "cycle"`, `value: <cycle-id>`
    - `key: "stages"`, `value: <determined stages list>`