@really-knows-ai/foundry 3.5.4 → 3.5.5

package/dist/.opencode/plugins/foundry-tools/helpers.js

@@ -3,6 +3,7 @@
 import path from 'path';
 import { readFileSync, writeFileSync, existsSync, readdirSync, unlinkSync, mkdirSync, renameSync, rmSync, statSync } from 'fs';
 import { execFileSync } from 'child_process';
+import matter from 'gray-matter';
 import { getCycleDefinition } from '../../../scripts/lib/config.js';
 import { getOrOpenStore, getContext } from '../../../scripts/lib/memory/singleton.js';
 import { resolvePermissions } from '../../../scripts/lib/memory/permissions.js';
@@ -13,49 +14,27 @@ import { requireOnFlowBranch } from '../../../scripts/lib/branch-guard.js';
 // Track flow files we've already warned about to avoid spamming stderr
 const warnedFlowFiles = new Set();
 
-// -- Frontmatter parsing helpers --
-
-function isFieldSeparator(char) {
-  return char === ' ' || char === '\t';
-}
-
-function parseFrontmatterField(fm, fieldName) {
-  const prefix = `${fieldName}:`;
-  for (const line of fm.split('\n')) {
-    if (!line.startsWith(prefix)) continue;
-    const rest = line.slice(prefix.length);
-    if (rest === '' || isFieldSeparator(rest[0])) {
-      return rest.trim();
-    }
-  }
-  return null;
+function parseFlowFrontmatter(text, entry) {
+  const fm = extractFrontmatter(text);
+  if (!fm) return null;
+  const id = fm.id || entry.replace(/\.md$/, '');
+  return {
+    id,
+    name: fm.name || id,
+    startingCycles: resolveStartingCycles(fm),
+  };
 }
 
-function parseStartingCycles(fm) {
-  const lines = fm.split('\n');
-  const scIndex = lines.findIndex(line => line.trimEnd() === 'starting-cycles:');
-  if (scIndex < 0) return [];
-  const items = [];
-  for (let i = scIndex + 1; i < lines.length; i++) {
-    const trimmed = lines[i].trimStart();
-    if (trimmed.startsWith('-')) {
-      const content = trimmed.slice(1).trimStart();
-      if (content) items.push(content);
-    } else {
-      break;
-    }
-  }
-  return items;
+function extractFrontmatter(text) {
+  const parsed = matter(text);
+  return parsed.data && typeof parsed.data === 'object' && Object.keys(parsed.data).length > 0
+    ? parsed.data
+    : null;
 }
 
-function parseFlowFrontmatter(text, entry) {
-  const fmMatch = text.match(/^---\n([\s\S]*?)\n---/);
-  if (!fmMatch) return null;
-  const fm = fmMatch[1];
-  const id = parseFrontmatterField(fm, 'id') || entry.replace(/\.md$/, '');
-  const name = parseFrontmatterField(fm, 'name') || id;
-  const startingCycles = parseStartingCycles(fm);
-  return { id, name, startingCycles };
+function resolveStartingCycles(fm) {
+  const sc = fm['starting-cycles'];
+  return Array.isArray(sc) ? sc : [];
 }
 
 function parseFlowFile(entry, flowsDir) {

package/dist/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [3.5.5] - 2026-05-23
+
+### Fixed
+
+- `buildAppraiserPrompt` output format aligned with the YAML parser — indented continuation fields instead of dash-prefixed. Previously, an appraiser reporting an issue with the exact prompt format would have every field split into separate entries and silently discarded.
+- Hand-rolled appraiser output parsing (120 lines) replaced with `js-yaml` plus a line-scanning fallback for non-clean LLM output.
+
+### Changed
+
+- All hand-rolled YAML frontmatter regex extraction (5 patterns across 10 sites in 8 files) replaced with `gray-matter`.
+- Flow frontmatter parsing in `helpers.js` switched from line-scanning to `gray-matter`.
+
 ## [3.5.4] - 2026-05-23
 
 ### Fixed

package/dist/scripts/appraise-module.js

@@ -13,6 +13,7 @@
 
 import { getArtefactFiles } from './lib/artefacts.js';
 import { selectAppraisers, getLaws, getCycleDefinition } from './lib/config.js';
+import yaml from 'js-yaml';
 
 // ---------------------------------------------------------------------------
 // Public API — gather
@@ -296,9 +297,9 @@ function buildAppraiserPrompt({ appraiser, artefact, laws }) {
     '',
     'Return a list of issues. For each issue:',
     `- file: ${artefact.file}`,
-    '- law: <law-id>',
-    '- issue: <description>',
-    '- evidence: <quote from artefact>',
+    '  law: <law-id>',
+    '  issue: <description>',
+    '  evidence: <quote from artefact>',
     '',
     'If there are no issues, return an empty list.',
   ];
@@ -313,127 +314,87 @@ function buildAppraiserPrompt({ appraiser, artefact, laws }) {
 /**
  * Parse a structured issue list from an appraiser subagent output.
  *
- * Expected per-issue format (YAML list):
- *   - file: <path>
- *     law: <law-id>
- *     issue: <description>
- *     evidence: <quote>
+ * LLM output is free-form text that may contain a YAML list of issues.
+ * Tries js-yaml first; falls back to line-scanning when the output is
+ * not clean YAML (LLMs may include surrounding text, quotes in bare
+ * strings, or other quirks that trip up a strict YAML parser).
  *
- * Returns an array of { file, law, issue, evidence } objects. Entries that
- * lack a file, law, or issue field are silently skipped.
+ * Returns an array of { file, law, issue, evidence } objects.
  */
 function parseAppraiserOutput(output) {
-  // Split output into entries on boundaries where a new line starts a
-  // list entry ("- ").  Avoids regex to prevent sonarjs/slow-regex.
-  const entries = [];
-  let buffer = '';
-
-  for (const line of output.split('\n')) {
-    if (buffer && isListEntryStart(line)) {
-      entries.push(buffer);
-      buffer = line;
-      continue;
-    }
-
-    buffer = concatLine(buffer, line);
-  }
-
-  if (buffer) entries.push(buffer);
+  const text = output || '';
+  const yamlBlock = extractYamlBlock(text);
+  const issues = tryYamlParse(yamlBlock);
+  if (issues) return issues;
 
-  return entries
-    .map(parseRawEntry)
-    .filter(e => e !== null);
+  return parseFallback(text);
 }
 
-/**
- * Append a line to the current buffer string.
- */
-function concatLine(buffer, line) {
-  if (!buffer) return line;
-  return `${buffer}\n${line}`;
+function extractYamlBlock(text) {
+  if (text.startsWith('- file:')) return text;
+  const afterNewline = text.indexOf('\n- file:');
+  if (afterNewline >= 0) return text.slice(afterNewline + 1);
+  return text;
 }
 
-/**
- * True when a line marks the start of a new YAML list entry (starts with
- * "- " after optional whitespace).
- */
-function isListEntryStart(line) {
-  for (let i = 0; i < line.length; i++) {
-    const ch = line[i];
-    if (ch === ' ' || ch === '\t') continue;
-    return ch === '-' && line[i + 1] === ' ';
-  }
-  return false;
+function tryYamlParse(yamlBlock) {
+  try {
+    const parsed = yaml.load(yamlBlock);
+    if (Array.isArray(parsed)) {
+      return parsed
+        .filter(e => e && typeof e === 'object' && e.file && e.law && e.issue)
+        .map(e => ({ file: e.file, law: e.law, issue: e.issue, evidence: e.evidence || '' }));
+    }
+  } catch { /* fall through to fallback */ }
+  return null;
 }
 
-/**
- * Parse a single raw entry block into an issue object, or null when
- * required fields are missing.
- */
-function parseRawEntry(raw) {
-  const block = raw.trim();
-
-  const file = extractField(block, 'file');
-  const law = extractField(block, 'law');
-  const issue = extractField(block, 'issue');
-  const evidence = extractField(block, 'evidence');
+const FALLBACK_FIELDS = new Set(['law', 'issue', 'evidence']);
 
-  if (!file || !law || !issue) return null;
+function isCompleteIssue(obj) {
+  return obj && obj.file && obj.law && obj.issue;
+}
 
-  return { file, law, issue, evidence: evidence || '' };
+function applyFallbackField(kv, entry, issues) {
+  if (kv.key === 'file') {
+    const e = { file: kv.value, law: '', issue: '', evidence: '' };
+    issues.push(e);
+    return e;
+  }
+  if (entry && FALLBACK_FIELDS.has(kv.key)) {
+    entry[kv.key] = kv.value;
+  }
+  return entry;
 }
 
-/**
- * Extract a YAML list item field value.
- *
- * Matches lines like:
- *   - file: value
- *     law: value
- *
- * The field name may be preceded by optional whitespace and/or a "- " list
- * marker. Returns the value portion, trimmed.
- */
-function extractField(text, key) {
-  // Walk lines to find "key: value" preceded only by whitespace or a "- "
-  // list marker.  Avoids regex quantifiers that trigger sonarjs/slow-regex.
+function parseFallback(text) {
+  const issues = [];
+  let entry = null;
 
   for (const line of text.split('\n')) {
-    const trimmed = line.trim();
-    const value = tryExtractKey(trimmed, key);
-    if (value !== null) return value;
+    const kv = parseFallbackLine(line);
+    if (kv) entry = applyFallbackField(kv, entry, issues);
   }
 
-  return null;
+  return issues.filter(isCompleteIssue);
 }
 
-/**
- * Given a single trimmed line, try to extract the value for key.
- * Returns null if the pattern is not found.
- */
-function tryExtractKey(line, key) {
-  const needle = `${key}:`;
-  const idx = line.indexOf(needle);
-  if (idx < 0) return null;
+function parseFallbackLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return null;
 
-  const before = line.slice(0, idx);
-  if (before.length > 0 && !isLegalPrefix(before)) return null;
+  const colon = trimmed.indexOf(':');
+  if (colon < 1) return null;
 
-  const value = line.slice(idx + needle.length).trim();
-  return value || null;
+  const key = stripDash(trimmed.slice(0, colon));
+  return {
+    key: key.trim(),
+    value: trimmed.slice(colon + 1).trim(),
+  };
 }
 
-/**
- * True when the text before a key: on a line is either all whitespace or
- * the "- " list marker.
- */
-function isLegalPrefix(before) {
-  if (before === '- ') return true;
-
-  for (let i = 0; i < before.length; i++) {
-    if (before[i] !== ' ' && before[i] !== '\t') return false;
-  }
-
-  return true;
+function stripDash(s) {
+  return s.startsWith('- ') ? s.slice(2) : s;
 }
 
 // ---------------------------------------------------------------------------

package/dist/scripts/lib/config-validators/helpers.js

@@ -1,4 +1,5 @@
 import { parseFrontmatter } from '../workfile.js';
+import matter from 'gray-matter';
 
 /**
  * Shared helpers for config validators.
@@ -10,7 +11,8 @@ import { parseFrontmatter } from '../workfile.js';
  * @returns {{ok: true, fm: object} | {ok: false, errors: string[]}}
  */
 export function tryParseFrontmatter(body) {
-  if (!/^---\n[\s\S]*?\n---/.test(body)) {
+  const { data } = matter(body);
+  if (!data || typeof data !== 'object' || Object.keys(data).length === 0) {
     return { ok: false, errors: ['frontmatter is missing or unparseable'] };
   }
   try {
@@ -65,7 +67,7 @@ export function validateNameMatch(fm, name) {
  * @returns {string}
  */
 export function bodyAfterFrontmatter(body) {
-  return body.replace(/^---\n[\s\S]*?\n---\n?/, '').trim();
+  return matter(body).content.trim();
 }
 
 /**

package/dist/scripts/lib/config.js

@@ -4,10 +4,11 @@
 
 import { join } from 'path';
 import { parseFrontmatter } from './workfile.js';
+import matter from 'gray-matter';
 
 function parseDoc(text) {
   const frontmatter = parseFrontmatter(text);
-  const body = text.replace(/^---\n.+?\n---\n?/s, '').trim();
+  const body = matter(text).content.trim();
   return { frontmatter, body };
 }
 

package/dist/scripts/lib/failed-flow.js

@@ -28,6 +28,7 @@
  * is clean.
  */
 import { parseFrontmatter, setFrontmatterField, writeFrontmatter } from './workfile.js';
+import matter from 'gray-matter';
 
 const MAX_REASON_LEN = 500;
 
@@ -126,6 +127,6 @@ export function clearWorkfileFailed(io) {
   
   // Rebuild the file with cleaned frontmatter
   const fmBlock = writeFrontmatter(fm);
-  const body = text.replace(/^---\n.+?\n---\n?/s, '');
+  const body = matter(text).content;
   io.writeFile('WORK.md', body ? `${fmBlock}\n${body}` : fmBlock);
 }

package/dist/scripts/lib/memory/admin/rename-entity-type.js

@@ -5,10 +5,10 @@ import { parseEdgeRows, serialiseEdgeRows, parseEntityRows, serialiseEntityRows
 import { invalidateStore } from '../singleton.js';
 import { parseFrontmatter } from '../frontmatter.js';
 import { renderEdgeFrontmatter, composeMarkdown } from './helpers.js';
+import matter from 'gray-matter';
+import yaml from 'js-yaml';
 
 const IDENT = /^[a-z][a-z0-9_]*$/;
-const TYPE_LINE = /^type:\s*\S.*$/m;
-const FRONTMATTER_BLOCK = /^---\r?\n([\s\S]*?)\r?\n---/;
 
 function assertValidIdentifier(id) {
   if (!IDENT.test(id)) throw new Error(`invalid identifier: '${id}'`);
@@ -37,10 +37,10 @@ function validateRename(schema, from, to) {
 async function rewriteEntityTypeFile(from, to, p, io) {
   const oldFile = p.entityTypeFile(from);
   const text = await io.readFile(oldFile);
-  const newText = text.replace(FRONTMATTER_BLOCK, (_, fm) => {
-    const replaced = fm.replace(TYPE_LINE, `type: ${to}`);
-    return `---\n${replaced}\n---`;
-  });
+  const { data, content } = matter(text);
+  const fm = { ...data, type: to };
+  const fmBlock = `---\n${yaml.dump(fm, { lineWidth: -1, sortKeys: false }).trim()}\n---`;
+  const newText = content ? `${fmBlock}\n${content}` : fmBlock;
   await io.writeFile(p.entityTypeFile(to), newText);
   await io.unlink(oldFile);
 }

package/dist/scripts/lib/memory/frontmatter.js

@@ -1,31 +1,9 @@
+import matter from 'gray-matter';
 import yaml from 'js-yaml';
 
-/**
- * Safely parse a YAML string, rethrowing with a filename-prefixed message
- * on failure so errors are actionable.
- *
- * @param {string} yamlStr
- * @param {string} filename
- * @returns {unknown}
- */
-function safeYamlLoad(yamlStr, filename) {
-  try {
-    return yaml.load(yamlStr);
-  } catch (err) {
-    const msg = err?.message ?? String(err);
-    throw new Error(`${filename}: malformed YAML frontmatter: ${msg}`, { cause: err });
-  }
-}
-
-/**
- * Normalise a parsed YAML value into a frontmatter object.
- *
- * @param {unknown} parsed
- * @returns {object}
- */
 function normaliseFrontmatter(parsed) {
   if (parsed && typeof parsed === 'object') {
-    return /** @type {object} */ (parsed);
+    return { ...parsed };
   }
   return {};
 }
@@ -49,19 +27,39 @@ function normaliseFrontmatter(parsed) {
  * @param {{ filename?: string }} [opts]
  * @returns {{ frontmatter: object, body: string, hasFrontmatter: boolean }}
  */
-export function parseFrontmatter(text, { filename = '<unknown>' } = {}) {
-  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
-  if (!m) {
+function hasData(d) {
+  return d && (typeof d === 'object' ? Object.keys(d).length > 0 : true);
+}
+
+export function parseFrontmatter(text, { filename } = {}) {
+  const result = tryMatter(text, filename);
+  if (!result) {
+    return { frontmatter: {}, body: text, hasFrontmatter: false };
+  }
+
+  if (!hasData(result.data)) {
     return { frontmatter: {}, body: text, hasFrontmatter: false };
   }
-  const parsed = safeYamlLoad(m[1], filename);
+
   return {
-    frontmatter: normaliseFrontmatter(parsed),
-    body: m[2] ?? '',
+    frontmatter: normaliseFrontmatter(result.data),
+    body: result.content,
     hasFrontmatter: true,
   };
 }
 
+function tryMatter(text, filename) {
+  try {
+    return matter(text);
+  } catch (err) {
+    if (filename) {
+      const msg = err?.message ?? String(err);
+      console.warn(`${filename}: malformed YAML frontmatter: ${msg}`);
+    }
+    return null;
+  }
+}
+
 /**
  * Render a markdown document from a frontmatter object and a body string.
  * Uses `yaml.dump` — callers that need a specific key order (e.g. edge type

package/dist/scripts/lib/workfile.js

@@ -3,23 +3,15 @@
  */
 
 import yaml from 'js-yaml';
+import matter from 'gray-matter';
 
 // ---------------------------------------------------------------------------
 // Frontmatter parsing
 // ---------------------------------------------------------------------------
 
-/**
- * Parse YAML frontmatter from a markdown document.
- * NOTE: Intentionally duplicates logic from memory/frontmatter.js for
- * different use cases. See memory/frontmatter.js for the canonical version
- * with full error handling and line-ending normalisation.
- */
 export function parseFrontmatter(text) {
-  const match = text.match(/^---\r?\n(.+?)\r?\n---/s);
-  if (!match) return {};
-  const fm = yaml.load(match[1]) || {};
-  // Normalize: on-disk canonical key is `max-iterations` (kebab).
-  // Tolerate legacy `maxIterations` (camel) by rewriting on read.
+  const { data } = matter(text);
+  const fm = { ...data };
   if (fm.maxIterations !== undefined) {
     if (fm['max-iterations'] === undefined) {
       fm['max-iterations'] = fm.maxIterations;
@@ -53,7 +45,7 @@ export function setFrontmatterField(text, key, value) {
   const fmBlock = writeFrontmatter(fm);
 
   // Strip existing frontmatter (if any) and prepend new one
-  const body = text.replace(/^---\r?\n.+?\r?\n---\r?\n?/s, '');
+  const body = matter(text).content;
   return body ? `${fmBlock}\n${body}` : fmBlock;
 }
 

package/dist/scripts/orchestrate-phases.js

@@ -7,6 +7,7 @@ import {
   getLawsForQuench,
 } from './lib/config.js';
 import { parseFrontmatter, writeFrontmatter } from './lib/workfile.js';
+import matter from 'gray-matter';
 import { clearActiveStage, clearLastStage } from './lib/state.js';
 import { appendEntry, getIteration } from './lib/history.js';
 import { stageBaseOf } from './lib/stage-guard.js';
@@ -171,7 +172,7 @@ function buildNewFrontmatter(workContent, stages, cfm, assayExtractors) {
   const newFm = { ...fm };
   newFm.stages = stages;
   applyFmDefaults(newFm, cfm, assayExtractors);
-  const body = workContent.replace(/^---\n[\s\S]+?\n---\n?/, '');
+  const body = matter(workContent).content;
   const fmBlock = writeFrontmatter(newFm);
   return body ? `${fmBlock}\n${body}` : fmBlock;
 }

package/dist/scripts/orchestrate.js

@@ -4,6 +4,7 @@
 
 import { runSort } from './sort.js';
 import { parseFrontmatter } from './lib/workfile.js';
+import matter from 'gray-matter';
 import { readActiveStage, readLastStage, writeActiveStage, clearActiveStage } from './lib/state.js';
 import { stageBaseOf } from './lib/stage-guard.js';
 import { ulid as defaultUlid } from './lib/ulid.js';
@@ -38,10 +39,8 @@ export { readCycleTargets, readForgeFilePatterns };
 export { handleSortResult as __handleSortResultForTest };
 
 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);
+  const { data } = matter(workMdContent);
+  return !data || !data.stages;
 }
 
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@really-knows-ai/foundry",
-  "version": "3.5.4",
+  "version": "3.5.5",
   "description": "A skill-driven framework for governed artefact generation with AI coding tools. Define your own artefact types, laws, and flows — Foundry handles the forge → quench → appraise pipeline with deterministic routing, quality gates, and iterative refinement.",
   "type": "module",
   "main": "dist/.opencode/plugins/foundry.js",
@@ -26,6 +26,7 @@
   },
   "dependencies": {
     "@opencode-ai/plugin": "^1.4.0",
+    "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
     "minimatch": "^10.2.5"
   },