@really-knows-ai/foundry 3.0.0 → 3.0.2

package/dist/.opencode/plugins/foundry-tools/config-law-tools.js

@@ -38,73 +38,47 @@ function findLawEnd(lines, startIdx) {
   return lines.length;
 }
 
-// Extract full markdown for a single law from file content
 function extractLawMarkdown(content, lawId) {
   const lines = content.split('\n');
   const startIdx = findLawStart(lines, lawId);
-
   if (startIdx < 0) return null;
-
   const endIdx = findLawEnd(lines, startIdx);
   const lawLines = lines.slice(startIdx, endIdx);
-  
-  while (lawLines.length > 0 && lawLines[lawLines.length - 1] === '') {
-    lawLines.pop();
-  }
-  
+  while (lawLines.length > 0 && lawLines[lawLines.length - 1] === '') lawLines.pop();
   return lawLines.join('\n') + '\n';
 }
 
 async function searchGlobalLaws(io, foundryDir, lawId) {
   const globalLawsDir = join(foundryDir, 'laws');
-  if (!(await io.exists(globalLawsDir))) {
-    return null;
-  }
-
+  if (!(await io.exists(globalLawsDir))) return null;
   const files = await io.readDir(globalLawsDir);
   for (const file of files) {
     if (!file.endsWith('.md')) continue;
     const path = join(globalLawsDir, file);
     const content = await io.readFile(path);
-    if (contentContainsLaw(content, lawId)) {
-      return { path, fullMarkdown: content, source: 'global' };
-    }
+    if (contentContainsLaw(content, lawId)) return { path, fullMarkdown: content, source: 'global' };
   }
-
   return null;
 }
 
 async function searchTypeSpecificLaws(io, foundryDir, lawId) {
   const artefactsDir = join(foundryDir, 'artefacts');
-  if (!(await io.exists(artefactsDir))) {
-    return null;
-  }
-
+  if (!(await io.exists(artefactsDir))) return null;
   const types = await io.readDir(artefactsDir);
   for (const typeId of types) {
     const typeLawsPath = join(artefactsDir, typeId, 'laws.md');
     if (!(await io.exists(typeLawsPath))) continue;
-
     const content = await io.readFile(typeLawsPath);
-    if (contentContainsLaw(content, lawId)) {
-      return { path: typeLawsPath, fullMarkdown: content, source: `type:${typeId}` };
-    }
+    if (contentContainsLaw(content, lawId)) return { path: typeLawsPath, fullMarkdown: content, source: `type:${typeId}` };
   }
-
   return null;
 }
 
 async function findLawByID(io, foundryDir, lawId) {
-  let result = await searchGlobalLaws(io, foundryDir, lawId);
-  if (result) {
-    return { found: true, ...result };
-  }
-
-  result = await searchTypeSpecificLaws(io, foundryDir, lawId);
-  if (result) {
-    return { found: true, ...result };
-  }
-
+  const global = await searchGlobalLaws(io, foundryDir, lawId);
+  if (global) return { found: true, ...global };
+  const typeSpec = await searchTypeSpecificLaws(io, foundryDir, lawId);
+  if (typeSpec) return { found: true, ...typeSpec };
   return { found: false };
 }
 
@@ -204,82 +178,92 @@ function computeTargetPath(target) {
 
 // --- add law executor --------------------------------------------------------
 
+function extractLawId(body) {
+  const match = body.match(/^## ([^\s]+)/m);
+  return match ? match[1] : null;
+}
+
+async function checkExistingLaw(io, path, lawId) {
+  if (!(await io.exists(path))) return { existedBefore: false, priorContent: null };
+  const priorContent = await io.readFile(path);
+  if (contentContainsLaw(priorContent, lawId)) {
+    return { error: `law id "${lawId}" already exists in ${path}; use foundry_config_edit_law to update it` };
+  }
+  return { existedBefore: true, priorContent };
+}
+
 async function validateAddLawPrerequisites(io, args) {
   const targetError = validateAddLawTarget(args.target);
-  if (targetError) {
-    return { error: targetError };
-  }
+  if (targetError) return { error: targetError };
 
   const path = computeTargetPath(args.target);
   const validation = await validateLaw({ body: args.body, io });
-  if (!validation.ok) {
-    return validation;
-  }
+  if (!validation.ok) return validation;
 
-  if (await io.exists(path)) {
-    return {
-      ok: false,
-      errors: [`${path} already exists; use foundry_config_edit_law to update an existing law in place`],
-    };
-  }
+  const lawId = extractLawId(args.body);
+  if (!lawId) return { error: 'could not determine law id from body (expected "## <law-id>" heading)' };
+
+  const existing = await checkExistingLaw(io, path, lawId);
+  if (existing.error) return { error: existing.error };
+  return { ok: true, path, lawId, ...existing };
+}
+
+function formatAddLawError(err) {
+  return err instanceof UnexpectedFilesError
+    ? JSON.stringify({ error: err.message, affected_files: err.files })
+    : errorJson(err);
+}
 
-  return { ok: true, path };
+function buildNextContent(existedBefore, priorContent, body) {
+  return existedBefore ? priorContent.trimEnd() + '\n\n' + body.trimStart() : body;
+}
+
+async function rollbackAddLaw(io, path, existedBefore, priorContent) {
+  if (existedBefore) await io.writeFile(path, priorContent);
+  else await io.rm(path);
 }
 
 async function executeAddLaw(args, context) {
   const io = makeAsyncIO(context.worktree);
   const execFile = makeExecFile(context.worktree);
+  let path, existedBefore, priorContent;
 
   try {
     const prereq = await validateAddLawPrerequisites(io, args);
-    if (prereq.error) {
-      return JSON.stringify({ ok: false, errors: [prereq.error] });
-    }
-    if (!prereq.ok) {
-      return JSON.stringify(prereq);
-    }
+    if (prereq.error) return JSON.stringify({ ok: false, errors: [prereq.error] });
+    if (!prereq.ok) return JSON.stringify(prereq);
 
-    const path = prereq.path;
+    ({ path, existedBefore, priorContent } = prereq);
+    const nextContent = buildNextContent(existedBefore, priorContent, args.body);
 
     await io.mkdirp(dirname(path));
-    await io.writeFile(path, args.body);
+    await io.writeFile(path, nextContent);
 
     const sha = commitWithPolicy({
       message: `config: add law ${args.name}\n\nvia foundry_config_add_law`,
       allowedPatterns: ['foundry/**'],
       execFile,
     });
-
     return JSON.stringify({ ok: true, path, sha });
   } catch (err) {
-    if (err instanceof UnexpectedFilesError) {
-      return JSON.stringify({ error: err.message, affected_files: err.files });
-    }
-    return errorJson(err);
+    if (path) await rollbackAddLaw(io, path, existedBefore, priorContent);
+    return formatAddLawError(err);
   }
 }
 
 // --- helper for preserving sibling laws -------------------------------------------------------
 
-// Replace a law in file content while preserving other laws
 function replaceLawInContent(content, lawId, newLawMarkdown) {
   const lines = content.split('\n');
   const startIdx = findLawStart(lines, lawId);
   if (startIdx < 0) return content.trimEnd() + '\n\n' + newLawMarkdown;
-  
   const endIdx = findLawEnd(lines, startIdx);
   const before = lines.slice(0, startIdx);
   const after = lines.slice(endIdx);
-  
-  // Trim trailing empty lines from before
   const beforeEnd = before.findLastIndex(l => l !== '') + 1;
   before.length = beforeEnd;
-  
-  // Trim leading empty lines from after  
   const afterStart = after.findIndex(l => l !== '');
   if (afterStart > 0) after.splice(0, afterStart);
-  
-  // newLawMarkdown includes trailing newline; split and rejoin without final empty string
   const newLines = newLawMarkdown.trimEnd().split('\n');
   return before.concat(newLines, after).join('\n') + '\n';
 }

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

@@ -52,7 +52,7 @@ async function executeValidator(expanded, worktree, patterns) {
  *   JSON or missing required fields, `pattern-mismatch` for files that
  *   didn't match the artefact type's `file-patterns`.
  */
-async function runValidators(laws, patterns, patternSubstitution, worktree) {
+async function runValidators(laws, patterns, substitutions, worktree) {
   const results = {
     validatorsRun: 0,
     items: [],
@@ -61,7 +61,7 @@ async function runValidators(laws, patterns, patternSubstitution, worktree) {
 
   for (const law of laws) {
     if (!law.validators || law.validators.length === 0) continue;
-    await runLawValidators(law, patterns, patternSubstitution, worktree, results);
+    await runLawValidators(law, patterns, substitutions, worktree, results);
   }
 
   return results;
@@ -70,15 +70,15 @@ async function runValidators(laws, patterns, patternSubstitution, worktree) {
 /**
  * Run validators for a single law.
  */
-async function runLawValidators(law, patterns, patternSubstitution, worktree, results) {
+async function runLawValidators(law, patterns, substitutions, worktree, results) {
   for (const validator of law.validators) {
-    // Skip validators if pattern substitution is empty (no matching files)
-    // Self-resolving validators (npm test, tsc) omit {pattern}, so they still run
-    if (patternSubstitution === '' && validator.command.includes('{pattern}')) {
+    // Skip iff command uses {files} and there are no matching files.
+    // {pattern}-only and verbatim commands always run.
+    if (substitutions.files === '' && /(?:^|\s)\{files\}(?=\s|$)/.test(validator.command)) {
       continue;
     }
     results.validatorsRun++;
-    const expanded = expandValidatorCommand(validator.command, patternSubstitution);
+    const expanded = expandValidatorCommand(validator.command, substitutions);
     const parseResult = await executeValidator(expanded, worktree, patterns);
     collectValidatorResult(parseResult, law.id, validator.id, results);
   }
@@ -160,8 +160,11 @@ async function performValidation(args, context) {
  */
 async function runValidatorsAndReport(laws, patterns, worktree) {
   const expandedFiles = await expandPatterns(patterns, worktree);
-  const patternSubstitution = expandedFiles.map(shellQuote).join(' ');
-  const results = await runValidators(laws, patterns, patternSubstitution, worktree);
+  const substitutions = {
+    pattern: patterns.map(shellQuote).join(' '),
+    files: expandedFiles.map(shellQuote).join(' '),
+  };
+  const results = await runValidators(laws, patterns, substitutions, worktree);
 
   return JSON.stringify({
     ok: results.errors.length === 0,
@@ -235,29 +238,34 @@ async function expandPatterns(patterns, worktree) {
 }
 
 /**
- * Expand validator command by replacing {pattern} placeholder.
+ * Expand validator command by replacing {pattern} and {files} placeholders.
+ *
+ * - {pattern} → space-separated, shell-quoted globs from the artefact
+ *   type's `file-patterns:` array (e.g. "'haikus/*.md' 'drafts/*.md'").
+ * - {files}   → space-separated, shell-quoted matching file paths in the
+ *   worktree (e.g. "'haikus/one.md' 'haikus/two.md'").
  *
- * Only replaces {pattern} when it appears as a standalone token bounded by
- * whitespace or string start/end. This allows self-resolving validators
- * (e.g., npm test, tsc --noEmit) to omit the placeholder without risk of
- * accidental substitution if they contain the literal text "{pattern}" as part
- * of another string.
+ * Both placeholders are recognised only as standalone tokens, bounded
+ * by whitespace or start/end of string. Surrounding single or double
+ * quotes around the placeholder are stripped first so authors can
+ * write `rg "{pattern}"` for readability.
  *
- * @param {string} command - The validator command
- * @param {string} patternSubstitution - Shell-quoted file paths, space-separated
- * @returns {string} The expanded command
+ * @param {string} command
+ * @param {{ pattern: string, files: string }} substitutions
+ * @returns {string}
  */
-export function expandValidatorCommand(command, patternSubstitution) {
-  // First strip surrounding quotes around {pattern} to handle cases like
-  // rg "{pattern}" where authors add quotes for readability
-  const cmd = command
+export function expandValidatorCommand(command, { pattern, files }) {
+  let cmd = command
     .replace(/"\{pattern\}"/g, '{pattern}')
-    .replace(/'\{pattern\}'/g, '{pattern}');
+    .replace(/'\{pattern\}'/g, '{pattern}')
+    .replace(/"\{files\}"/g, '{files}')
+    .replace(/'\{files\}'/g, '{files}');
 
-  // Only substitute {pattern} when it appears as a standalone token
-  // (bounded by whitespace or start/end of string)
-  return cmd.replace(/(?:^|\s)\{pattern\}(?=\s|$)/g, (match) => {
-    const leadingSpace = match.startsWith('{') ? '' : ' ';
-    return leadingSpace + patternSubstitution;
-  });
+  cmd = cmd.replace(/(?:^|\s)\{pattern\}(?=\s|$)/g, (match) =>
+    match.startsWith('{') ? pattern : ' ' + pattern);
+
+  cmd = cmd.replace(/(?:^|\s)\{files\}(?=\s|$)/g, (match) =>
+    match.startsWith('{') ? files : ' ' + files);
+
+  return cmd;
 }

package/dist/CHANGELOG.md

@@ -1,5 +1,117 @@
 # Changelog
 
+## [3.0.2] - 2026-05-11
+
+A documentation and tool-correctness patch driven by a failing
+haiku-flow setup session. Closes the loop on the laws-with-validators
+migration: the validator contract is now fully documented in
+`add-law`; the `add_law` tool appends additional laws to an existing
+file and rolls back its file write when the commit fails;
+`init-foundry` seeds a `node_modules/` ignore so npm-installed
+validator dependencies never collide with the config-tier write
+guard.
+
+### Validator contract is canonical in `add-law`
+
+- `add-law` SKILL.md gains a **§7a. Validator contract** that covers
+  the JSONL output shape (`file`, `text` required; `location`,
+  `severity` optional), command placeholders, working directory, skip
+  rule, and a worked Node example. Authors no longer need to read
+  plugin source to write a validator.
+- `add-artefact-type` step 5 drops its half-duplicate contract and
+  cross-references `add-law` §7a. Step 1 and step 4 now make clear
+  that the frontmatter `name:` field equals the artefact type's id
+  (lowercase, hyphenated); human-readable labels go in the
+  `## Definition` prose. Step 9 reflects the new append-aware
+  `add_law`.
+
+### Validator command placeholders split
+
+- `{pattern}` now renders the artefact type's `file-patterns:` as
+  space-separated, shell-quoted globs (e.g.
+  `'haikus/*.md' 'drafts/*.md'`). Use it when a validator does its
+  own globbing or accepts globs directly (e.g. `rg --glob`).
+- `{files}` renders the matching files in the worktree as
+  space-separated, shell-quoted paths. Use it when the validator
+  takes an explicit list of file paths.
+- A validator is skipped iff its command contains `{files}` and there
+  are no matching files. `{pattern}`-only and verbatim commands
+  always run.
+- **Migration:** any existing validator authored against the prior
+  semantics (where `{pattern}` substituted expanded paths) must be
+  updated to use `{files}` instead. Foundry was tagged 3.0.1 only
+  12 hours before this release; no migration helper is provided.
+
+### `foundry_config_add_law` correctness
+
+- The tool now appends a new law to an existing `laws.md` instead of
+  erroring on file-exists. It only errors when a law with the same
+  id is already present in the file — in that case the caller
+  switches to `foundry_config_edit_law`.
+- File writes are atomic with the commit. If the commit fails (most
+  commonly `unexpected_files`), the tool restores `laws.md` to its
+  prior content (or deletes it if it didn't exist before the call).
+  This eliminates the orphaned-file state that previously broke the
+  next call with "already exists".
+
+### `init-foundry` seeds `node_modules/`
+
+- `.gitignore` now starts with `.snapshots/`, `node_modules/`, and
+  `.DS_Store`. The new entry stops `npm install` from immediately
+  blocking every config-tier tool with `unexpected_files`.
+
+### Migration
+
+- Update any validator commands that used `{pattern}` for file
+  expansion to use `{files}` instead.
+- No action needed for projects already on 3.0.1 that have not yet
+  authored validators using `{pattern}`.
+- Existing projects can add `node_modules/` to `.gitignore` by hand;
+  the `init-foundry` change only affects newly-initialised projects.
+
+## [3.0.1] - 2026-05-11
+
+A documentation and cleanup patch. No runtime behaviour change. `quench`
+already read deterministic checks via `getLawsForQuench`; this release
+aligns the authoring skills, end-user docs, and source tree with that
+reality and removes the deprecated `validation.md` reader path.
+
+### Authoring skills now teach laws-with-validators
+
+- `add-artefact-type` folds deterministic checks into laws via the
+  optional `validators:` block. The skill walks the user through laws
+  and their validators in a single step; the previously separate
+  "Validation" step is gone.
+- `upgrade-foundry` describes type-specific laws (with validators where
+  applicable) instead of standalone "validation commands".
+- The `validators:` YAML shape in `add-artefact-type` is now identical
+  to the canonical shape in `add-law`.
+
+### Documentation
+
+- `docs/architecture.md`, `docs/concepts.md`, `docs/getting-started.md`,
+  and `docs/work-spec.md` drop every reference to `validation.md` and
+  describe `quench` as running validators declared inside laws.
+- The `quench` stage is now correctly documented as included iff any
+  applicable law declares validators.
+
+### Internal cleanup
+
+- Remove the deprecated `getValidation` and `parseValidationLines`
+  exports from `src/scripts/lib/config.js`, plus their six private
+  helpers. Nothing in production called them; `quench` reads via
+  `getLawsForQuench`.
+- Remove the `describe('getValidation', …)` test block and three inert
+  `validation.md` fixtures from the orchestrate integration tests.
+
+### Migration
+
+No action required for projects that already use laws-with-validators.
+Projects still carrying a `foundry/artefacts/<type>/validation.md` file
+have been carrying dead weight since the move to `getLawsForQuench`;
+the file is now safe to delete by hand, or `upgrade-foundry` will
+rebuild the configuration through the current tools.
+
 ## [3.0.0] - 2026-05-10
 
 A consolidation release covering every change since v2.4.2. Foundry 3.0.0

package/dist/docs/architecture.md

@@ -399,8 +399,7 @@ your-project/
 │   ├── artefacts/              # artefact type definitions
 │   │   └── <type>/
 │   │       ├── definition.md
-│   │       ├── laws.md         # optional
-│   │       └── validation.md   # optional
+│   │       └── laws.md         # optional
 │   ├── laws/                   # global laws
 │   ├── appraisers/             # appraiser personalities
 │   └── memory/                 # optional flow memory config (init-memory)

package/dist/docs/concepts.md

@@ -35,7 +35,7 @@ The stage names come from the foundry metaphor because the system treats AI outp
 
 - **assay** — opt-in pre-forge stage that populates flow memory by running project-authored extractor scripts (iteration 0 only). No artefact, no feedback, no output beyond memory writes. See the [Assay](#assay) and [Extractor](#extractor) entries below.
 - **forge** — produce or revise the artefact.
-- **quench** — run deterministic CLI checks (skipped if the artefact type has no `validation.md`).
+- **quench** — run deterministic CLI checks declared in laws (via their optional `validators:` blocks).
 - **appraise** — subjective evaluation by multiple appraiser sub-agents.
 - **human-appraise** — human quality gate. Can run every iteration, only on deadlock, or both.
 
@@ -63,8 +63,7 @@ See also: [Extractor](#extractor).
 A definition of what is being produced. Lives in `foundry/artefacts/<type>/`:
 
 - `definition.md` — identity, file patterns, output directory, appraiser config, prose description.
-- `laws.md` *(optional)* — type-specific subjective criteria.
-- `validation.md` *(optional)* — CLI commands for deterministic quench checks.
+- `laws.md` *(optional)* — type-specific subjective criteria, with optional validators for deterministic checks.
 
 File patterns must not overlap with any other artefact type's patterns — the write-invariant enforcer needs to know which type owns a given file.
 

package/dist/docs/getting-started.md

@@ -72,10 +72,9 @@ Run `add-artefact-type`. It walks you through:
 - `id` (lowercase, hyphenated), `name`, prose description.
 - `file-patterns` — glob patterns describing which files this type owns. Forge's write scope is exactly these patterns; anything written outside them violates the cycle. The skill refuses patterns that overlap with existing types.
 - Appraiser config — how many appraisers evaluate this type and which personalities are allowed.
-- Optional `laws.md` — type-specific criteria.
-- Optional `validation.md` — CLI commands for quench (non-zero exit = failure).
+- Optional `laws.md` — type-specific criteria, with optional validators for deterministic checks.
 
-Produces `foundry/artefacts/<id>/definition.md` (+ optional `laws.md`, `validation.md`).
+Produces `foundry/artefacts/<id>/definition.md` (+ optional `laws.md`).
 
 ### 2. Write laws
 

package/dist/docs/work-spec.md

@@ -46,7 +46,7 @@ assay:
 Fields:
 - `flow` — the foundry flow being executed.
 - `cycle` — the current cycle id.
-- `stages` — the ordered route for this cycle. Each entry uses `base:alias` format where `base` is the stage type (`forge`, `quench`, `appraise`, `human-appraise`, or `assay`) and `alias` is a human-readable name for what that stage does in this cycle. The list is derived from the cycle and artefact type: `forge` and `appraise` are always included; `quench` is included iff the artefact type has `validation.md`; `human-appraise` is included iff the cycle sets `human-appraise: true`; and `assay` is included iff the cycle declares an `assay.extractors` block.
+- `stages` — the ordered route for this cycle. Each entry uses `base:alias` format where `base` is the stage type (`forge`, `quench`, `appraise`, `human-appraise`, or `assay`) and `alias` is a human-readable name for what that stage does in this cycle. The list is derived from the cycle and artefact type: `forge` and `appraise` are always included; `quench` is included iff any applicable law declares validators; `human-appraise` is included iff the cycle sets `human-appraise: true`; and `assay` is included iff the cycle declares an `assay.extractors` block.
 - `max-iterations` — how many forge passes before the cycle is blocked (default: 3).
 - `human-appraise` — run human-appraise every iteration (default: `false`).
 - `deadlock-appraise` — route to human-appraise when LLM appraisers deadlock (default: `true`).

package/dist/scripts/lib/config.js

@@ -269,71 +269,6 @@ export async function getLawsForQuench(foundryDir, io, { typeId } = {}) {
   return laws.filter(law => law.validators && law.validators.length > 0);
 }
 
-function parseValidationEntry(line) {
-  const cmdMatch = line.match(/^Command:\s*(.+)/);
-  if (cmdMatch) return { type: 'command', value: cmdMatch[1].trim().replace(/^`|`$/g, '') };
-  const failMatch = line.match(/^Failure means:\s*(.+)/);
-  if (failMatch) return { type: 'failure', value: failMatch[1].trim() };
-  return null;
-}
-
-function buildValidationEntry(currentId, currentCommand, currentFailure) {
-  if (!currentId || !currentCommand) return null;
-  const entry = { id: currentId, command: currentCommand };
-  if (currentFailure) entry.failureMeans = currentFailure;
-  return entry;
-}
-
-function flushValidationEntry(entries, id, command, failure) {
-  const entry = buildValidationEntry(id, command, failure);
-  if (entry) entries.push(entry);
-}
-
-function applyParsedEntry(state, parsed) {
-  if (parsed?.type === 'command') state.command = parsed.value;
-  if (parsed?.type === 'failure') state.failure = parsed.value;
-}
-
-function handleValidationLine(line, state) {
-  const heading = line.match(/^## (.+)/);
-  if (heading) {
-    flushValidationEntry(state.entries, state.id, state.command, state.failure);
-    state.id = heading[1].trim();
-    state.command = null;
-    state.failure = null;
-    return;
-  }
-  if (state.id) {
-    applyParsedEntry(state, parseValidationEntry(line));
-  }
-}
-
-function internalParseValidationLines(lines) {
-  const state = { entries: [], id: null, command: null, failure: null };
-  for (const line of lines) {
-    handleValidationLine(line, state);
-  }
-  flushValidationEntry(state.entries, state.id, state.command, state.failure);
-  return state.entries;
-}
-
-/**
- * @deprecated Use getLawsForQuench instead. Phase 2 migration of validation.md files will remove this.
- */
-export async function getValidation(foundryDir, typeId, io) {
-  const path = join(foundryDir, 'artefacts', typeId, 'validation.md');
-  if (!(await io.exists(path))) return null;
-  const text = await io.readFile(path);
-  return internalParseValidationLines(text.split('\n'));
-}
-
-/**
- * @deprecated Use getLawsForQuench instead. Phase 2 migration of validation.md files will remove this.
- */
-export async function parseValidationLines(lines) {
-  return internalParseValidationLines(lines);
-}
-
 export async function getAppraisers(foundryDir, io) {
   const dir = join(foundryDir, 'appraisers');
   if (!(await io.exists(dir))) return [];

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

@@ -6,7 +6,7 @@ description: Creates a new artefact type, checking for conflicts with existing t
 
 # 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.
+You help the user create a new artefact type. You ensure it avoids conflicts with existing types, scaffold the directory structure, and walk the user through defining laws and their optional validators.
 
 ## Prerequisites
 
@@ -42,10 +42,12 @@ Before running this skill, verify all three of the following:
 ### 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 (forge's write scope is exactly these patterns)
-- A prose description of what this artefact type is
+- `id` — lowercase, hyphenated identifier (e.g. `haiku`). The
+  frontmatter `name:` field must equal this id; any human-readable
+  label goes in the `## Definition` prose, not in frontmatter.
+- `file-patterns` — glob patterns for files this type produces
+  (forge's write scope is exactly these patterns).
+- A prose description of what this artefact type is.
 
 If any of these are missing, ask.
 
@@ -87,7 +89,7 @@ Present the definition to the user:
 
 ```markdown
 ---
-name: <name>
+name: <id>
 file-patterns:
   - "<pattern>"
 ---
@@ -97,6 +99,10 @@ file-patterns:
 <description>
 ```
 
+The `name:` value must exactly match the artefact type's `id`
+(lowercase, hyphenated). If you want a human-readable label, put it
+in the `## Definition` prose.
+
 Ask: does this capture the artefact type correctly?
 
 ### 5. Laws (optional)
@@ -106,10 +112,28 @@ 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
+- Draft each law, adding validators where a deterministic check applies
 - Check for conflicts with global laws and any existing type-specific laws
 - Confirm with the user
 
+Each law may declare an optional `validators:` block; the YAML shape,
+JSONL output contract, `{pattern}` / `{files}` placeholders, skip
+rule, working directory, and a worked example are documented once in
+the `add-law` skill under **§7a. Validator contract**. Authors of
+type-specific laws must follow that contract — do not invent a
+different one here.
+
+**Use existing libraries:** Before writing custom validation logic,
+search npm for well-tested libraries that solve the problem (e.g.
+`syllable` for syllable counting, `natural` for NLP tasks).
+Hand-rolled heuristics are fragile — prefer battle-tested packages.
+Install them as project dependencies.
+
+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
+
 ### 6. Appraisers (optional)
 
 Ask:
@@ -135,33 +159,13 @@ appraisers:
 
 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
-
-If the user wants validation scripts (not just inline commands), create them as separate files in the artefact type directory.
-
-**Use existing libraries:** Before writing custom validation logic, search npm for well-tested libraries that solve the problem (e.g., `syllable` for syllable counting, `natural` for NLP tasks). Hand-rolled heuristics are fragile — prefer battle-tested packages. Install them as project dependencies.
-
-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. Validate the draft
+### 7. Validate the draft
 
 Call `foundry_config_validate_artefact_type({ name: "<id>", body: "<full markdown>" })`.
 
 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.
 
-### 9. Create the file
+### 8. Create the file
 
 Call `foundry_config_create_artefact_type({ name: "<id>", body: "<full markdown>" })`. The tool:
 
@@ -173,13 +177,16 @@ If the tool returns `{ ok: false, errors }` because the target file already exis
 
 Show the user the resulting commit hash from the response.
 
-### 10. Add laws and validation files (if defined)
-
-The create tool writes only `definition.md`. If you drafted any type-specific laws in step 5, append them to `foundry/artefacts/<id>/laws.md` by hand on this same `config/*` branch (use the `Edit` tool to create the file) and commit that as a separate microcommit.
+### 9. Add laws file (if defined)
 
-If you drafted validation commands in step 7, write `foundry/artefacts/<id>/validation.md` (and any companion validation script files) by hand and commit as a separate microcommit.
+If you drafted any type-specific laws in step 5, add them via
+`foundry_config_add_law` (one call per law) with
+`target: { kind: "type-specific", typeId: "<id>" }`. The first call
+creates `foundry/artefacts/<id>/laws.md`; subsequent calls append to
+that same file. Each call produces its own microcommit. See the
+`add-law` skill for the full protocol.
 
-### 11. Confirm
+### 10. Confirm
 
 Show the user the complete file listing and the commit hashes.
 

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

@@ -71,7 +71,9 @@ The `law-id` (heading) should be:
 - Short but descriptive
 - Unique across all laws (global and type-specific)
 
-The `validators:` block is optional. Include it only if you want to add validation commands for this law.
+The `validators:` block is optional. Include it only when a
+deterministic check can decide pass/fail. See **Validator contract**
+below for the exact shape a validator command must satisfy.
 
 ### 3. Check for conflicts
 
@@ -142,7 +144,11 @@ The tool:
 - writes the law file at the path determined by `target`;
 - produces one git commit on the current `config/*` branch.
 
-If the tool returns `{ ok: false, errors }` because the target file already exists, use `foundry_config_edit_law({ id: "<law-id>", body: "<updated-body>" })` to modify the law.
+The tool appends to an existing `laws.md` automatically when the
+new `## <law-id>` heading is not already present. It only errors when
+a law with the same id is already in the file — in that case use
+`foundry_config_edit_law({ id: "<law-id>", body: "<updated-body>" })`
+to modify the existing law in place.
 
 Show the user the resulting commit hash from the response.
 
@@ -150,6 +156,111 @@ Show the user the resulting commit hash from the response.
 
 After the file is created, confirm the law id is unique across all law files. If a collision exists, ask the user to rename and edit by hand on this branch.
 
+### 7a. Validator contract
+
+A law's `validators:` entries declare CLI commands that `quench` runs
+during a cycle. The plugin parses each command's stdout as **JSONL**
+(one JSON object per line). Authors must follow this contract exactly;
+nothing in plugin source needs to be read.
+
+#### Output format (stdout, parsed as JSONL)
+
+One JSON object per line. Empty lines are ignored. Required fields:
+
+- `file` *(string)* — path of the offending file, relative to the
+  worktree root. Must match at least one of the artefact type's
+  `file-patterns:`; otherwise the line becomes a validator-level
+  error, not feedback.
+- `text` *(string)* — the feedback message.
+
+Optional fields:
+
+- `location` *(string, e.g. `"3:1"`)* — line:column reference,
+  prepended to `text` as `file:location — text`.
+- `severity` *(string, e.g. `"error"` or `"warning"`)* — prepended to
+  `text` as `[severity] file:location — text` (or `[severity] file —
+  text` when no `location`).
+
+Anything else on the line is preserved verbatim on the parsed item.
+The validator's exit code is **ignored** — the parser reads stdout
+either way, and falls back to stderr when stdout is empty (so tools
+like `rg` that exit non-zero on hits still work).
+
+#### Command placeholders
+
+Inside `command:`, two placeholders may appear, alone, together, or
+not at all. They are recognised only as standalone tokens (bounded by
+whitespace or string start/end). Authors may wrap a placeholder in
+single or double quotes for readability — surrounding quotes are
+stripped before substitution.
+
+- `{pattern}` → the artefact type's `file-patterns:` rendered as
+  space-separated, shell-quoted globs (e.g.
+  `'haikus/*.md' 'drafts/*.md'`). Use this when the validator does
+  its own globbing or accepts globs directly (e.g. `rg --glob`).
+- `{files}` → the matching files in the worktree, rendered as
+  space-separated, shell-quoted paths (e.g.
+  `'haikus/one.md' 'haikus/two.md'`). Use this when the validator
+  takes an explicit list of file paths.
+
+A command with neither placeholder runs verbatim — useful for
+self-resolving validators such as `npm test`, `tsc --noEmit`, or
+`pnpm run lint`.
+
+#### Skip rule
+
+A validator is skipped iff its command contains `{files}` and there
+are no matching files in the worktree. Commands using `{pattern}` only,
+or no placeholders at all, always run.
+
+#### Working directory
+
+Validators run with `cwd` set to the worktree root, so root-level
+`node_modules/`, `package.json`, and project tooling all resolve
+normally. Do not assume the validator runs from inside the artefact
+type's directory.
+
+#### Worked example
+
+A validator that checks each `.md` file in `haikus/` has exactly three
+non-empty lines, attached to a haiku artefact type
+(`file-patterns: ["haikus/*.md"]`):
+
+`foundry/artefacts/haiku/check-line-count.mjs`:
+
+~~~js
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+
+for (const file of process.argv.slice(2)) {
+  const content = await readFile(file, 'utf8');
+  const lines = content
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0);
+  if (lines.length !== 3) {
+    process.stdout.write(JSON.stringify({
+      file,
+      text: `Expected 3 non-empty lines, got ${lines.length}.`,
+      severity: 'error',
+    }) + '\n');
+  }
+}
+~~~
+
+Declared in the law:
+
+~~~markdown
+## three-lines
+
+A haiku must consist of exactly three non-empty lines.
+
+validators:
+  - id: line-count
+    command: node foundry/artefacts/haiku/check-line-count.mjs {files}
+    failure-means: The artefact file does not contain exactly three non-empty lines.
+~~~
+
 ### 8. Editing existing laws (prose or validators)
 
 When the user wants to modify an existing law — whether updating the prose description or adding/changing validators — use this flow:

package/dist/skills/init-foundry/SKILL.md

@@ -31,9 +31,24 @@ Set up the `foundry/` directory structure in the current project.
 
 3. **Update `.gitignore`**
 
-   Append `.snapshots/` to the project's `.gitignore` (creating the file if absent). This directory is where dry-run snapshots are written and must never be committed.
+   Append the following lines to the project's `.gitignore` (creating
+   the file if absent), skipping any that are already present:
 
-   The plugin will idempotently append `.foundry/` itself on first boot, so you do not need to add that line.
+   ```
+   .snapshots/
+   node_modules/
+   .DS_Store
+   ```
+
+   - `.snapshots/` keeps dry-run snapshots out of git.
+   - `node_modules/` keeps any npm dependencies (e.g. validator
+     packages) out of git. Without it, foundry's `config/*` tools
+     reject calls with `unexpected_files` as soon as the user runs
+     `npm install`.
+   - `.DS_Store` keeps macOS metadata out of git.
+
+   The plugin will idempotently append `.foundry/` itself on first
+   boot, so you do not need to add that line.
 
 4. **Generate foundry agent files**
 

package/dist/skills/upgrade-foundry/SKILL.md

@@ -64,8 +64,7 @@ Read source material from the preserved directory:
 - Flow definitions.
 - Cycle definitions.
 - Artefact type definitions.
-- Type-specific laws.
-- Type-specific validation commands.
+- Type-specific laws (with validators where applicable).
 - Global laws.
 - Appraisers.
 - Memory schema, relations, and extractors when present.
@@ -93,7 +92,7 @@ Common clarification points:
 - Starting cycles when the old flow has no explicit current-version equivalent.
 - Input contracts when old inputs do not state `any-of` or `all-of` intent.
 - Artefact ownership when file patterns overlap or are missing.
-- Validation commands whose purpose or failure meaning is unclear.
+- Validators whose purpose or failure meaning is unclear.
 - Appraiser selection when old config lacks counts, allowed appraisers, or personality detail.
 - Human appraisal and deadlock settings that map to current fields with changed semantics.
 - Memory permissions, extractor outputs, relation files, or schema details whose current contract is ambiguous.
@@ -107,7 +106,7 @@ Recreate concepts in dependency order:
 
 1. Global laws.
 2. Appraisers.
-3. Artefact types, including type laws and validation commands.
+3. Artefact types, including type laws and validators.
 4. Memory schema and extractors when safely inferable.
 5. Cycles.
 6. Flows.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@really-knows-ai/foundry",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "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",