@really-knows-ai/foundry 3.2.7 → 3.3.0

package/dist/scripts/lib/config-creators/cycle.js

@@ -4,8 +4,118 @@ import { makeCreator } from './factory.js';
 
 const KIND = 'cycle';
 
-export const create = makeCreator({
+/** Render a YAML list block: `key:\n  - item1\n  - item2` */
+function yamlList(key, items) {
+  if (!items || items.length === 0) return '';
+  const prefix = key.match(/^(\s*)/)[1];
+  let block = `${key}:\n`;
+  for (const item of items) {
+    block += `${prefix}  - ${item}\n`;
+  }
+  return block;
+}
+
+/** Render the inputs mapping. */
+function renderInputs(inputs) {
+  if (!inputs) return '';
+  let block = 'inputs:\n';
+  block += `  type: ${inputs.type}\n`;
+  block += yamlList('  artefacts', inputs.artefacts);
+  return block;
+}
+
+/** Render the assay mapping. */
+function renderAssay(assay) {
+  if (!assay) return '';
+  return 'assay:\n' + yamlList('  extractors', assay.extractors);
+}
+
+/** Render the memory mapping. */
+function renderMemory(memory) {
+  if (!memory) return '';
+  let block = 'memory:\n';
+  block += yamlList('  read', memory.read);
+  block += yamlList('  write', memory.write);
+  return block;
+}
+
+/** Render models mapping (flat string key → string value). */
+function renderModels(models) {
+  if (!models) return '';
+  let block = 'models:\n';
+  for (const [key, value] of Object.entries(models)) {
+    block += `  ${key}: ${value}\n`;
+  }
+  return block;
+}
+
+/** Render boolean and numeric flags (camelCase to kebab-case). */
+function renderFlags(args) {
+  let fm = '';
+  if (args.humanAppraise !== undefined) {
+    fm += `human-appraise: ${args.humanAppraise}\n`;
+  }
+  if (args.deadlockAppraise !== undefined) {
+    fm += `deadlock-appraise: ${args.deadlockAppraise}\n`;
+  }
+  if (args.deadlockIterations !== undefined) {
+    fm += `deadlock-iterations: ${args.deadlockIterations}\n`;
+  }
+  if (args.maxIterations !== undefined) {
+    fm += `max-iterations: ${args.maxIterations}\n`;
+  }
+  return fm;
+}
+
+/**
+ * Assemble the markdown body for a cycle definition from structured arguments.
+ *
+ * @param {object} args
+ * @param {string} args.id               Slugged identifier; becomes frontmatter.id.
+ * @param {string} args.name             Human-readable display name; becomes frontmatter.name.
+ * @param {string} args.outputType       Artefact type ID this cycle produces.
+ * @param {{ type: 'any-of'|'all-of', artefacts: string[] }} [args.inputs]  Input contract.
+ * @param {string[]} [args.targets]      Downstream cycle IDs.
+ * @param {boolean} [args.humanAppraise] Include human-appraise in every iteration.
+ * @param {boolean} [args.deadlockAppraise] Route to human-appraise on deadlock.
+ * @param {number} [args.deadlockIterations] Iteration threshold for deadlock detection.
+ * @param {number} [args.maxIterations]  Maximum forge iterations.
+ * @param {{ extractors: string[] }} [args.assay]  Assay stage config.
+ * @param {{ read: string[], write: string[] }} [args.memory]  Flow memory permissions.
+ * @param {object} [args.models]         Per-stage model overrides.
+ * @param {string} [args.description]    Prose placed after frontmatter under ## Cycle.
+ * @returns {string} Assembled markdown body.
+ */
+export function assembleCycleMarkdown(args) {
+  const { id, name, outputType } = args;
+
+  let fm = `---\nid: ${id}\nname: ${name}\noutput-type: ${outputType}\n`;
+
+  fm += renderInputs(args.inputs);
+  fm += yamlList('targets', args.targets);
+  fm += renderFlags(args);
+  fm += renderAssay(args.assay);
+  fm += renderMemory(args.memory);
+  fm += renderModels(args.models);
+
+  fm += '---';
+
+  if (args.description) {
+    fm += `\n\n## Cycle\n\n${args.description}\n`;
+  } else {
+    fm += '\n';
+  }
+
+  return fm;
+}
+
+const _create = makeCreator({
   kind: KIND,
-  pathFor: (args) => join('foundry', 'cycles', `${args.name}.md`),
+  pathFor: (args) => join('foundry', 'cycles', `${args.id}.md`),
   validator: validate,
 });
+
+export async function create(args) {
+  const body = assembleCycleMarkdown(args);
+  return _create({ ...args, name: args.id, body });
+}

package/dist/scripts/lib/config-creators/flow.js

@@ -4,8 +4,33 @@ import { makeCreator } from './factory.js';
 
 const KIND = 'flow';
 
-export const create = makeCreator({
+/**
+ * Assemble the markdown body for a flow definition from structured arguments.
+ *
+ * @param {object} args
+ * @param {string} args.id              Slugged identifier; becomes frontmatter.id.
+ * @param {string} args.name            Human-readable display name; becomes frontmatter.name.
+ * @param {string[]} args.startingCycles  Cycle IDs that can start this flow.
+ * @param {string} args.description     Prose placed under ## Cycles.
+ * @returns {string} Assembled markdown body.
+ */
+export function assembleFlowMarkdown(args) {
+  const { id, name, startingCycles, description } = args;
+  let body = `---\nid: ${id}\nname: ${name}\nstarting-cycles:\n`;
+  for (const c of startingCycles) {
+    body += `  - ${c}\n`;
+  }
+  body += `---\n\n## Cycles\n\n${description}\n`;
+  return body;
+}
+
+const _create = makeCreator({
   kind: KIND,
-  pathFor: (args) => join('foundry', 'flows', `${args.name}.md`),
+  pathFor: (args) => join('foundry', 'flows', `${args.id}.md`),
   validator: validate,
 });
+
+export async function create(args) {
+  const body = assembleFlowMarkdown(args);
+  return _create({ ...args, name: args.id, body });
+}

package/dist/scripts/lib/config-creators/law.js

@@ -0,0 +1,269 @@
+/**
+ * @file Law markdown assembly helpers for add_law and edit_law tools.
+ *
+ * Laws have no YAML frontmatter — each law is a `## <id>` block within a
+ * markdown file. The block contains a combined name–description line,
+ * passing criteria, failing criteria, and an optional validators block.
+ */
+
+/**
+ * Build a validators block string from an array of validator objects.
+ *
+ * @param {{ id: string, command: string, failureMeans?: string }[]} validators
+ * @returns {string}  Validators block (empty string if none).
+ */
+function buildValidatorsBlock(validators) {
+  if (!validators || validators.length === 0) return '';
+
+  let block = 'validators:\n';
+  for (const v of validators) {
+    block += `  - id: ${v.id}\n    command: ${v.command}`;
+    if (v.failureMeans) {
+      block += `\n    failure-means: ${v.failureMeans}`;
+    }
+    block += '\n';
+  }
+  return block.trimEnd();
+}
+
+/**
+ * Assemble a law markdown block from structured arguments.
+ *
+ * @param {object} args
+ * @param {string} args.id           Law identifier; becomes `## <id>` heading.
+ * @param {string} args.name         Human-readable name.
+ * @param {string} args.description  Prose describing what the law covers.
+ * @param {string} args.passing      Criteria defining a passing artefact.
+ * @param {string} args.failing      Criteria defining a failing artefact.
+ * @param {{ id: string, command: string, failureMeans?: string }[]} [args.validators]
+ * @returns {string} Assembled law block (no trailing newline).
+ */
+export function assembleLawMarkdown(args) {
+  const { id, name, description, passing, failing } = args;
+  let block = `## ${id}\n\n${name} — ${description}\n\n${passing}\n\n${failing}`;
+
+  if (args.validators && args.validators.length > 0) {
+    block += '\n\n' + buildValidatorsBlock(args.validators);
+  }
+
+  return block;
+}
+
+/**
+ * Parse a single law block from a body that contains one or more `## <id>`
+ * headings. Returns data for the first block found.
+ *
+ * @param {string} body  Full file body.
+ * @returns {{ heading: string, headingIndex: number, blockEndIndex: number,
+ *             proseContent: string, validatorsContent: string } | null}
+ */
+function parseLawBlock(body) {
+  const headingMatch = body.match(/^(## .+)/m);
+  if (!headingMatch) return null;
+
+  const heading = headingMatch[1];
+  const headingIndex = headingMatch.index;
+
+  // Find the end of this block — next ## at same level or EOF
+  const afterHeading = body.slice(headingIndex);
+  const nextHeadingRe = /\n(?=## )/;
+  const nextMatch = afterHeading.match(nextHeadingRe);
+  const blockText = nextMatch
+    ? afterHeading.slice(0, nextMatch.index)
+    : afterHeading;
+  const blockEndIndex = nextMatch
+    ? headingIndex + nextMatch.index
+    : body.length;
+
+  // Locate the validators: block within this law block
+  const validatorsRe = /^validators:\n((?:[ \t]+\S.*(?:\n|$))*)/m;
+  const vMatch = blockText.match(validatorsRe);
+
+  let proseContent;
+  let validatorsContent;
+
+  if (vMatch) {
+    proseContent = blockText.slice(0, vMatch.index);
+    validatorsContent = blockText.slice(vMatch.index);
+  } else {
+    proseContent = blockText;
+    validatorsContent = '';
+  }
+
+  return {
+    heading, headingIndex, blockEndIndex, proseContent, validatorsContent,
+  };
+}
+
+/**
+ * Parse the name–description pair from a single line.
+ *
+ * Expected format: `<name> — <description>`
+ *
+ * @param {string} line
+ * @returns {{ name: string, description: string }}
+ */
+function parseNameDescription(line) {
+  const sep = ' — ';
+  const sepIndex = line.indexOf(sep);
+  if (sepIndex !== -1) {
+    return {
+      name: line.slice(0, sepIndex).trim(),
+      description: line.slice(sepIndex + sep.length).trim(),
+    };
+  }
+  return { name: line.trim(), description: '' };
+}
+
+/**
+ * Advance index past consecutive blank lines.
+ *
+ * @param {string[]} lines
+ * @param {number} start
+ * @returns {number} Index of first non-blank line (or lines.length).
+ */
+function skipBlankLines(lines, start) {
+  let i = start;
+  while (i < lines.length && lines[i].trim() === '') i++;
+  return i;
+}
+
+/**
+ * Collect consecutive non-blank lines starting at `start`.
+ *
+ * @param {string[]} lines
+ * @param {number} start
+ * @returns {{ lines: string[], nextIndex: number }}
+ */
+function collectNonBlank(lines, start) {
+  const collected = [];
+  let i = start;
+  while (i < lines.length && lines[i].trim() !== '') {
+    collected.push(lines[i]);
+    i++;
+  }
+  return { lines: collected, nextIndex: i };
+}
+
+/**
+ * Parse the prose section of a law block into its constituent fields.
+ *
+ * Expected prose structure:
+ *
+ *   <name> — <description>
+ *   (blank line)
+ *   <passing>
+ *   (blank line)
+ *   <failing>
+ *
+ * Each of passing/failing may be multi-line prose.
+ *
+ * @param {string} proseContent  Block content from heading to validators.
+ * @returns {{ name: string, description: string, passing: string, failing: string }}
+ */
+function parseLawProse(proseContent) {
+  const lines = proseContent.split('\n');
+  let i = 0;
+
+  // Skip heading line
+  if (lines[i] && lines[i].startsWith('## ')) i++;
+
+  // Skip blank lines after heading
+  i = skipBlankLines(lines, i);
+
+  // Name — description line
+  const nd = parseNameDescription(lines[i] || '');
+  i++;
+
+  // Skip blank lines, collect passing, skip blank lines again
+  i = skipBlankLines(lines, i);
+  const passing = collectNonBlank(lines, i);
+  i = passing.nextIndex;
+
+  i = skipBlankLines(lines, i);
+
+  // Remaining lines form failing
+  const failingLines = lines.slice(i);
+
+  return {
+    name: nd.name,
+    description: nd.description,
+    passing: passing.lines.join('\n'),
+    failing: failingLines.join('\n').trimEnd(),
+  };
+}
+
+/**
+ * Build the result block for an edit operation by appending validators.
+ *
+ * @param {string} newProse  Rebuilt prose section.
+ * @param {{ validators?: object[] | null }} updates
+ * @param {string} existingValidatorsContent  Original validators block text.
+ * @returns {string}  Full new block content.
+ */
+function appendValidators(newProse, updates, existingValidatorsContent) {
+  if (updates.validators !== undefined) {
+    if (updates.validators !== null) {
+      return newProse + '\n\n' + buildValidatorsBlock(updates.validators);
+    }
+    return newProse;
+  }
+
+  const trimmed = existingValidatorsContent.trim();
+  if (trimmed) {
+    return newProse + '\n\n' + trimmed;
+  }
+  return newProse;
+}
+
+/**
+ * Pick a field value from updates, falling back to the existing value.
+ *
+ * @param {object} updates
+ * @param {object} existing
+ * @param {string} field
+ * @returns {*}
+ */
+function pickField(updates, existing, field) {
+  return updates[field] !== undefined ? updates[field] : existing[field];
+}
+
+/**
+ * Update a law block in an existing body with new field values.
+ *
+ * Only the fields present in `updates` are replaced. Fields not in `updates`
+ * retain their original values. Pass `validators: null` to remove the
+ * validators block.
+ *
+ * @param {string} existingBody  Full file content (may contain multiple law blocks).
+ * @param {{ name?: string, description?: string, passing?: string,
+ *          failing?: string, validators?: object[] | null }} updates
+ * @returns {string}  Updated full body with the first law block modified.
+ */
+export function assembleEditLawMarkdown(existingBody, updates) {
+  const parsed = parseLawBlock(existingBody);
+  if (!parsed) {
+    throw new Error('Body must contain at least one ## law heading');
+  }
+
+  const { heading, headingIndex, blockEndIndex, proseContent } = parsed;
+  const existing = parseLawProse(proseContent);
+
+  const name = pickField(updates, existing, 'name');
+  const description = pickField(updates, existing, 'description');
+  const passing = pickField(updates, existing, 'passing');
+  const failing = pickField(updates, existing, 'failing');
+
+  const newProse = `${heading}\n\n${name} — ${description}\n\n${passing}\n\n${failing}`;
+  const result = appendValidators(newProse, updates, parsed.validatorsContent);
+
+  // If there are subsequent blocks, insert a newline separator so the gap
+  // between blocks remains `\n\n` (end of result + `\n` + leading `\n` of
+  // the remaining body).
+  if (blockEndIndex < existingBody.length) {
+    return existingBody.slice(0, headingIndex) + result + '\n'
+      + existingBody.slice(blockEndIndex);
+  }
+  return existingBody.slice(0, headingIndex) + result
+    + existingBody.slice(blockEndIndex);
+}

package/dist/skills/add-appraiser/SKILL.md

@@ -76,19 +76,12 @@ Do not proceed until the user has decided.
 
 ### 4. Draft the definition
 
-Present the definition to the user:
+Present the definition to the user with these structured fields:
 
-```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>
-```
+- `id` (string) — lowercase, hyphenated identifier
+- `name` (string) — a short character name (e.g., "The Pedant", "The Pragmatist")
+- `description` (string) — 2-4 sentences describing how this appraiser thinks, what they care about, and how they approach evaluation
+- `model` (string, optional) — a specific model ID to use for this appraiser (e.g., `openai/gpt-4o`). Overrides the cycle-level model for the appraise stage. Omit this field to use the cycle's default model.
 
 Ask: does this capture the personality correctly?
 
@@ -101,13 +94,13 @@ Iterate until the user is happy with the personality description. Key things to
 
 ### 6. Validate the draft
 
-Call `foundry_config_validate_appraiser({ name: "<id>", body: "<full markdown>" })`.
+Call `foundry_config_validate_appraiser({ name: "<id>", body: "<assembled markdown>" })`. Assemble the body from the fields using the frontmatter format the tool produces internally.
 
 If the result is `{ ok: false, errors: [...] }`, address each error (adjust the body) and re-run until you get `{ ok: true }`. Common issues: missing required frontmatter keys, references to artefact types or flows that don't exist yet.
 
 ### 7. Create the file
 
-Call `foundry_config_create_appraiser({ name: "<id>", body: "<full markdown>" })`. The tool:
+Call `foundry_config_create_appraiser({ id: "<id>", name: "<name>", description: "<description>" })`. The tool:
 
 - re-validates the body (TOCTOU);
 - writes `foundry/appraisers/<id>.md`;

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

@@ -80,23 +80,17 @@ Do not proceed until the patterns are non-overlapping.
 
 ### 4. Draft the definition
 
-Present the definition to the user:
+Present the definition to the user with these structured fields:
 
-```markdown
----
-name: <id>
-file-patterns:
-  - "<pattern>"
----
-
-## Definition
+- `id` (string) — lowercase, hyphenated identifier (e.g. `haiku`). Must be unique across artefact types.
+- `name` (string) — human-readable label
+- `filePatterns` (string[]) — glob patterns for files this type produces (forge's write scope is exactly these patterns)
+- `description` (string) — prose description of what this artefact type is
+- `appraisers` ({ count?: number, allowed?: string[] }, optional) — appraiser configuration
 
-<description>
-```
-
-The `name:` value must exactly match the artefact type's `id`
+The `id` value must exactly match the artefact type's identifier
 (lowercase, hyphenated). If you want a human-readable label, put it
-in the `## Definition` prose.
+in the `name` field.
 
 Ask: does this capture the artefact type correctly?
 
@@ -139,32 +133,24 @@ Ask:
 > - 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 specifies preferences, include these fields:
 
-If the user is happy with the defaults (3 appraisers, any personality), add just:
+- `appraisers.count` (number, optional, default: 3) — how many appraisers per foundry cycle
+- `appraisers.allowed` (string[], optional, default: all available) — whitelist of appraiser personality IDs
 
-```yaml
-appraisers:
-  count: 3
-```
+If the user is happy with the defaults (3 appraisers, any personality), omit the appraisers configuration entirely.
 
 List the available appraisers from `foundry/appraisers/*.md` so the user can see their options.
 
 ### 7. Validate the draft
 
-Call `foundry_config_validate_artefact_type({ name: "<id>", body: "<full markdown>" })`.
+Call `foundry_config_validate_artefact_type({ name: "<id>", body: "<assembled markdown>" })`. Assemble the body from the fields using the frontmatter format the tool produces internally.
 
 If the result is `{ ok: false, errors: [...] }`, address each error (adjust the body) and re-run until you get `{ ok: true }`. Common issues: missing required frontmatter keys, references to artefact types or flows that don't exist yet.
 
 ### 8. Create the file
 
-Call `foundry_config_create_artefact_type({ name: "<id>", body: "<full markdown>" })`. The tool:
+Call `foundry_config_create_artefact_type({ id: "<id>", name: "<name>", filePatterns: ["<pattern>"], description: "<description>" })`. The tool:
 
 - re-validates the body (TOCTOU);
 - writes `foundry/artefacts/<id>/definition.md`;

package/dist/skills/add-cycle/SKILL.md

@@ -120,30 +120,21 @@ If overlap is found, present it and ask the user to confirm the distinction is r
 
 ### 9. Draft the definition
 
-Present the foundry cycle definition to the user:
-
-```markdown
----
-id: <id>
-name: <name>
-output-type: <artefact-type-id>
-inputs:
-  type: <any-of|all-of>
-  artefacts:
-    - <artefact-type-id>
-targets:
-  - <cycle-id>
-human-appraise: <true|false>
-deadlock-appraise: <true|false>
-deadlock-iterations: <number>
-models:
-  appraise: <model-id>
----
-
-# <Name>
-
-<description>
-```
+Present the foundry cycle definition to the user with these structured fields:
+
+- `id` (string) — lowercase, hyphenated identifier
+- `name` (string) — human-readable name
+- `outputType` (string) — the artefact type this cycle produces (must exist in `foundry/artefacts/`)
+- `description` (string) — prose description of what this cycle does
+- `inputs` (object, optional) — input contract. Shape: `{ type: "any-of" | "all-of", artefacts: string[] }`. May be omitted for starting cycles.
+- `targets` (string[], optional) — cycle IDs to route to after completion. May be omitted for terminal cycles.
+- `humanAppraise` (boolean, optional, default: false) — whether a human reviews the artefact every iteration
+- `deadlockAppraise` (boolean, optional, default: true) — whether a human is pulled in when LLM appraisers deadlock
+- `deadlockIterations` (number, optional, default: 5) — deadlock threshold
+- `maxIterations` (number, optional) — maximum iterations before forced progression
+- `assay` (object, optional) — assay configuration
+- `memory` (object, optional) — memory configuration
+- `models` (object, optional) — stage-specific model overrides, e.g. `{ appraise: "openai/gpt-4o" }`
 
 Ask: does this capture the foundry cycle correctly?
 
@@ -160,13 +151,13 @@ For input validation:
 
 ### 11. Validate the draft
 
-Call `foundry_config_validate_cycle({ name: "<id>", body: "<full markdown>" })`.
+Call `foundry_config_validate_cycle({ name: "<id>", body: "<assembled markdown>" })`. Assemble the body from the fields using the frontmatter format the tool produces internally.
 
 If the result is `{ ok: false, errors: [...] }`, address each error (adjust the body) and re-run until you get `{ ok: true }`. Common issues: missing required frontmatter keys, references to artefact types or flows that don't exist yet.
 
 ### 12. Create the cycle file
 
-Call `foundry_config_create_cycle({ name: "<id>", body: "<full markdown>" })`. The tool:
+Call `foundry_config_create_cycle({ id: "<id>", name: "<name>", outputType: "<type>", description: "<description>", inputs: ..., targets: ..., humanAppraise: ..., deadlockAppraise: ..., deadlockIterations: ..., maxIterations: ..., assay: ..., memory: ..., models: ... })`. The tool:
 
 - re-validates the body (TOCTOU);
 - writes `foundry/cycles/<id>.md`;

package/dist/skills/add-flow/SKILL.md

@@ -67,6 +67,15 @@ Ask only for choices that affect the user's goal or safety. Reuse compatible exi
 
 For each definition, use the `foundry_config_validate_*` tool family to validate it first. Resolve any validation errors, then use the corresponding `foundry_config_create_*` tool to create it. Summarise each created file and commit hash in Foundry terms.
 
+For the flow definition itself, use these structured fields:
+
+- `id` (string) — lowercase, hyphenated identifier
+- `name` (string) — human-readable name
+- `description` (string) — prose description of the flow purpose
+- `startingCycles` (string[]) — cycle IDs that begin the flow
+
+Call `foundry_config_create_flow({ id: "<id>", name: "<name>", startingCycles: ["<id>"], description: "<description>" })` to create the flow file.
+
 ### 6. Final summary
 
 Report the flow, starting cycles, artefact type, laws, validators, appraisers, and files created. Tell the user they can now ask the Foundry agent to run the flow.