@really-knows-ai/foundry 1.3.2 → 1.5.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, parseStagesValue, parseModelsValue } 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';
@@ -139,9 +139,9 @@ export const FoundryPlugin = async ({ directory }) => {
           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 };
+          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 = {}; }
+            fm.models = parseModelsValue(args.models);
           }
           const content = createWorkfile(fm, args.goal);
           writeFileSync(workPath, content, 'utf-8');
@@ -179,13 +179,28 @@ export const FoundryPlugin = async ({ directory }) => {
           const text = readFileSync(workPath, 'utf-8');
           // 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;
+          if (args.key === 'stages') {
+            // Always parse stages into an array (handles JSON arrays and comma-separated strings)
+            value = parseStagesValue(args.value);
+          } else if (args.key === 'models') {
+            // Always parse models into an object (handles JSON objects and "key: value" strings)
+            value = parseModelsValue(args.value);
+          } else {
+            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);
             }
-          } catch {
-            // Not JSON, use as plain string
           }
           const updated = setFrontmatterField(text, args.key, value);
           writeFileSync(workPath, updated, 'utf-8');
@@ -460,15 +475,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.2",
+  "version": "1.5.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().replace(/^`|`$/g, '');
+      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,58 @@ 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}`);
+}
+
+/**
+ * Parse a stages value from tool input.
+ * Accepts JSON array string or comma-separated string.
+ * Always returns an array of trimmed, non-empty strings.
+ */
+export function parseStagesValue(raw) {
+  // Try JSON first
+  try {
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed)) return parsed;
+  } catch { /* not JSON */ }
+  // Fall back to comma-separated
+  return raw.split(',').map(s => s.trim()).filter(Boolean);
+}
+
+/**
+ * Parse a models value from tool input.
+ * Accepts JSON object string or "key: value, key: value" string.
+ * Always returns an object mapping stage base names to model IDs.
+ */
+export function parseModelsValue(raw) {
+  if (!raw || !raw.trim()) return {};
+  // Try JSON first
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed === 'object' && !Array.isArray(parsed)) return parsed;
+  } catch { /* not JSON */ }
+  // Fall back to "key: value, key: value" format
+  const result = {};
+  for (const part of raw.split(',')) {
+    const colonIdx = part.indexOf(':');
+    if (colonIdx === -1) continue;
+    const key = part.slice(0, colonIdx).trim();
+    const val = part.slice(colonIdx + 1).trim();
+    if (key && val) result[key] = val;
+  }
+  return result;
+}
+
 // ---------------------------------------------------------------------------
 // Workfile creation
 // ---------------------------------------------------------------------------
@@ -45,8 +97,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/appraise/SKILL.md

@@ -91,7 +91,7 @@ If there are no issues, return an empty list.
 
 ## History
 
-After completing the appraisal consolidation, call `foundry_history_append` with the current cycle, stage alias, and a brief summary (e.g., "3 issues found across 2 appraisers" or "No issues found").
+Do NOT call `foundry_history_append` — the sort skill (your caller) is responsible for writing history. Instead, return a clear summary of what you found (e.g., "3 issues found across 2 appraisers" or "No issues found") so sort can log it.
 
 ## What you do NOT do
 

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

package/skills/forge/SKILL.md

@@ -40,7 +40,7 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 
 ### After (both paths)
 
-Call `foundry_history_append` with the current cycle, the full stage alias (e.g., `forge:write-haiku`), and a brief description of what you did.
+Do NOT call `foundry_history_append` — the sort skill (your caller) is responsible for writing history. Instead, return a clear summary of what you did so sort can log it.
 
 ## Unresolved feedback
 

package/skills/hitl/SKILL.md

@@ -36,7 +36,7 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
    - **Provide context** — note in the history comment for future stages to reference
    - **Abort** — call `foundry_artefacts_set_status` with status `"blocked"`, cycle ends
 
-5. Call `foundry_history_append` with the current cycle, stage alias, and a comment capturing the substance of what the human said or decided.
+5. Do NOT call `foundry_history_append` — the sort skill (your caller) is responsible for writing history. Instead, return a clear summary of what the human said or decided so sort can log it.
 
 6. Return control to the sort skill.
 

package/skills/quench/SKILL.md

@@ -35,7 +35,7 @@ There is no wont-fix for validation feedback. Deterministic rules are not negoti
 
 ## History
 
-After completing validation, call `foundry_history_append` with the current cycle, stage alias, and a brief summary (e.g., "2 validation issues found" or "Validation passed").
+Do NOT call `foundry_history_append` — the sort skill (your caller) is responsible for writing history. Instead, return a clear summary of what you found (e.g., "2 validation issues found" or "Validation passed") so sort can log it.
 
 ## What you do NOT do
 

package/skills/sort/SKILL.md

@@ -29,22 +29,13 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
    - `blocked` — foundry cycle is blocked (iteration limit hit with unresolved feedback), return to the cycle skill
    - `violation` — file modification or tag validation violation detected (see `details`). The cycle halts — call `foundry_artefacts_set_status` with status `"blocked"`, and return to the cycle skill
 
-### Model dispatch
+4. After the subagent completes, call `foundry_history_append` with the current cycle, the **dispatched stage alias** (e.g., `forge:write-haiku`), and a comment summarizing what the subagent reported doing. This is critical — sort is the only reliable writer of stage history. Subagents must NOT write their own history entries.
 
-Use the `model` field from the `foundry_sort` result to determine sub-agent routing:
-
-- If `model` is set (e.g., `openai/gpt-4o`):
-  - Convert to agent name: `foundry-openai-gpt-4o`
-  - Dispatch with `subagent_type: "foundry-openai-gpt-4o"`
-  - If no agent with that name exists, **hard fail**: "Cycle specifies model `<model>` for stage `<base>` but no matching agent `foundry-<name>` is registered. Check your OpenCode provider config."
-- If `model` is null:
-  - Dispatch with `subagent_type: "general"` (inherits session model)
-
-4. After the invoked skill completes, call `foundry_sort` again. Repeat until it returns `done`, `blocked`, or `violation`.
+5. After logging the stage history, call `foundry_sort` again. Repeat from step 1 until it returns `done`, `blocked`, or `violation`.
 
 ## What you do NOT do
 
 - You do not make routing decisions yourself — the tool decides
 - You do not skip calling `foundry_sort`
 - You do not override the tool's output
-- You do not skip the history entry — every sort invocation must be logged via `foundry_history_append`
+- You do not skip the history entry — every sort invocation gets a `sort` entry, and every completed stage gets a stage entry (e.g., `forge:write-haiku`). You are the sole writer of history.