@really-knows-ai/foundry 3.7.0 → 3.7.3

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

@@ -318,7 +318,7 @@ function makeReadLawTool(tool) {
 function makeAddLawTool(tool) {
   return tool({
     description: 'Add a new law (config-tier; requires a config/* branch). ' +
-      'Fields: id, name, description, passing, failing, target ({kind, file|typeId}), validators ([{id, command, failureMeans?}]).',
+      'Args: id, name, description, passing, failing, target ({kind, file|typeId}), validators ([{id, command, failureMeans?}]). Every validator needs a companion test (TDD) before the law is created.',
     args: {
       id: tool.schema.string().describe('Law identifier. Becomes the ## <id> heading.'),
       name: tool.schema.string().describe('Human-readable name stored as prose after heading.'),
@@ -332,9 +332,9 @@ function makeAddLawTool(tool) {
       }).describe('Where to write the law'),
       validators: tool.schema.array(tool.schema.object({
         id: tool.schema.string().describe('Validator identifier'),
-        command: tool.schema.string().describe('CLI command with optional {pattern} / {files} placeholders. Prefer JavaScript (.mjs) scripts as separate files (e.g. "node foundry/artefacts/<type>/check.mjs {files}"). Stdout must be NDJSON: one JSON object per line with required fields "file" (relative path) and "text" (message). Optional: "location" (line:col), "severity" (error|warning). Exit code is ignored.'),
+        command: tool.schema.string().describe('CLI command with optional {pattern} / {files} placeholders. Prefer .mjs scripts (e.g. "node foundry/artefacts/<type>/check.mjs {files}") with a companion .test.js file (TDD). Stdout must be NDJSON: one JSON object per line with required fields "file" (relative path) and "text" (message). Optional: "location" (line:col), "severity" (error|warning). Exit code is ignored.'),
         failureMeans: tool.schema.string().optional().describe('Description of what failure means'),
-      })).optional().describe('Optional deterministic validators'),
+      })).optional().describe('Optional deterministic validators. Each requires a companion test file.'),
     },
     execute: guarded('foundry_config_add_law', CREATE_GUARDS, executeAddLaw, { branchIo: branchIoFactory, io: asyncIoFactory }),
   });

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

@@ -4,8 +4,7 @@ import { existsSync, unlinkSync, writeFileSync, readFileSync } from 'fs';
 import { slugify } from '../../../scripts/lib/slug.js';
 import { CONFIG_RE, DRY_RUN_RE } from '../../../scripts/lib/branch-guard.js';
 import { finishWorkBranchWithArchive } from '../../../scripts/lib/git-finish/work-finish.js';
-import { finishDryRun } from '../../../scripts/lib/snapshot/finish.js';
-import { asyncIoFactory } from './helpers.js';
+import { checkConfigBranchFiles } from '../../../scripts/lib/git-policy.js';
 
 const WORK_FILES = ['WORK.md', 'WORK.history.yaml', 'WORK.feedback.yaml'];
 
@@ -233,15 +232,35 @@ export function finishBranchCommon({ branchName, branchType, base, cwd, args })
   const opts = { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] };
   const planned = computeFinishPlan({ branchName, branchType, base, args, cwd });
   if (args.confirm !== true) return makeConfirmRefusal(planned);
-  const dirty = dirtyTrackedFiles(cwd);
-  if (dirty.length) return makeDirtyRefusal(dirty);
-  if (branchType === 'work') deleteWorkFilesAndCommit(planned.filesToDelete, cwd, branchName);
+  const guardErr = runPreMergeGuards({ branchName, branchType, base, cwd, opts, planned });
+  if (guardErr) return guardErr;
   const mergeErr = squashMergeIntoBase(base, branchName, branchType, opts);
   if (mergeErr) return mergeErr;
   const { hash } = commitAndDeleteBranch(args.message, branchName, opts);
   return JSON.stringify({ ok: true, hash, branch: base });
 }
 
+function runPreMergeGuards({ branchName, branchType, base, cwd, opts, planned }) {
+  const dirty = dirtyTrackedFiles(cwd);
+  if (dirty.length) return makeDirtyRefusal(dirty);
+  if (branchType === 'work') {
+    deleteWorkFilesAndCommit(planned.filesToDelete, cwd, branchName);
+    return null;
+  }
+  if (branchType !== 'config') return null;
+  const diff = execFileSync('git', ['diff', '--name-only', `${base}..${branchName}`],
+    { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+  const result = checkConfigBranchFiles(diff);
+  if (result) {
+    return JSON.stringify({
+      ok: false,
+      error: 'Config branches may only change files inside foundry/. Outside files detected:',
+      outside: result.files,
+    });
+  }
+  return null;
+}
+
 // -- finishWorkBranch helpers --
 
 function makeExecGit(cwd, opts) {
@@ -321,34 +340,3 @@ export function finishConfigBranch({ configBranch, base, cwd, args }) {
   });
 }
 
-// -- finishDryRunBranch --
-
-export async function finishDryRunBranch({ branch, args, cwd }) {
-  const io = asyncIoFactory({ worktree: cwd });
-  const exec = (argv) => execFileSync('git', argv,
-    { cwd, encoding: 'utf8', stdio: 'pipe' });
-
-  if (args.confirm !== true) {
-    return JSON.stringify({
-      ok: false,
-      error: 'foundry_git_finish requires {confirm: true} to perform destructive operations. Re-invoke with confirm:true to apply the plan.',
-      planned: {
-        branch,
-        action: 'snapshot + discard (dry-run finish)',
-        snapshotPath: '.snapshots/<runId> (computed at apply time)',
-      },
-    });
-  }
-
-  try {
-    const out = await finishDryRun({
-      message: args.message, branch, io, execFile: exec,
-    });
-    return JSON.stringify(out);
-  } catch (err) {
-    return JSON.stringify({
-      ok: false,
-      error: `foundry_git_finish: dry-run finish failed: ${err.message ?? String(err)}`,
-    });
-  }
-}

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

@@ -6,7 +6,6 @@ import {
   classifyBranch,
   finishWorkBranch,
   finishConfigBranch,
-  finishDryRunBranch,
   KIND_DRY_RUN,
   KINDS,
 } from './git-helpers.js';
@@ -14,6 +13,7 @@ import { makeIO, makeExec, asyncIoFactory } from './helpers.js';
 import { requireNoActiveStage } from '../../../scripts/lib/stage-guard.js';
 import { currentBranch } from '../../../scripts/lib/branch-guard.js';
 import { truncateTrace } from '../../../scripts/lib/tracing.js';
+import { finishDryRun } from '../../../scripts/lib/snapshot/finish.js';
 
 function refuse(error) { return JSON.stringify({ error }); }
 
@@ -107,6 +107,36 @@ function refuseUnknownFinishBranch(branch) {
     `(expected work/<x>, config/<x>, or dry-run/<x>/<y>).`);
 }
 
+async function finishDryRunBranch({ branch, args, cwd }) {
+  const io = asyncIoFactory({ worktree: cwd });
+  const exec = (argv) => execFileSync('git', argv,
+    { cwd, encoding: 'utf8', stdio: 'pipe' });
+
+  if (args.confirm !== true) {
+    return JSON.stringify({
+      ok: false,
+      error: 'foundry_git_finish requires {confirm: true} to perform destructive operations. Re-invoke with confirm:true to apply the plan.',
+      planned: {
+        branch,
+        action: 'snapshot + discard (dry-run finish)',
+        snapshotPath: '.snapshots/<runId> (computed at apply time)',
+      },
+    });
+  }
+
+  try {
+    const out = await finishDryRun({
+      message: args.message, branch, io, execFile: exec,
+    });
+    return JSON.stringify(out);
+  } catch (err) {
+    return JSON.stringify({
+      ok: false,
+      error: `foundry_git_finish: dry-run finish failed: ${err.message ?? String(err)}`,
+    });
+  }
+}
+
 function routeDryRunFinish(branch, args, cwd) {
   if (args.baseBranch !== undefined)
     return refuseBaseBranchForDryRun();

package/dist/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [3.7.3] - 2026-05-27
+
+### Added
+
+- Config branch file enforcement: `foundry_git_finish` on a `config/*` branch now validates that every changed file lives inside `foundry/` or is tool-managed. Files outside `foundry/` are rejected with a clear list of offending paths. This prevents test fixtures, artefact output, or other non-config files from accidentally landing on config branches.
+
+### Changed
+
+- The `add-law` skill clarifies that all flow artefacts — validator scripts, tests, and test fixtures — must live inside `foundry/`. Test fixtures colocate under `foundry/artefacts/<type>/test/fixtures/`. The worked example and "what you do NOT do" list updated accordingly.
+
+## [3.7.2] - 2026-05-27
+
+### Changed
+
+- Every validator now requires a companion test file written with TDD. The `add-law` skill walks through TDD (test first, confirm failure, implement, verify pass), produces a `.test.js` file alongside each validator, and refuses to create validators without passing tests. The `foundry_config_add_law` tool description surfaces the requirement.
+
+## [3.7.1] - 2026-05-27
+
+### Fixed
+
+- `mock.module` calls in `quench-module.test.js` use the canonical `namedExports` key instead of the deprecated `exports` alias. Node 22 does not recognise the old key, causing tests to fail with "does not provide an export named `computeArtefactVersion`".
+
 ## [3.7.0] - 2026-05-27
 
 ### Added

package/dist/scripts/lib/git-policy.js

@@ -99,3 +99,21 @@ export function allowedPatternsForStage({ stageBase, forgeFilePatterns = [] } =
   if (stageBase === 'assay') return ['foundry-memory/**'];
   return [];
 }
+
+/**
+ * Check that every file changed on a config branch lives inside foundry/ or
+ * is tool-managed. Returns null when clean, or { files: [...] } when outside
+ * files are detected.
+ *
+ * @param {string} diffOut - Raw `git diff --name-only base..branch` output
+ * @returns {null|{files: string[]}}
+ */
+export function checkConfigBranchFiles(diffOut) {
+  if (!diffOut) return null;
+  const toolManaged = new Set(TOOL_MANAGED);
+  const outside = diffOut.split('\n')
+    .map(f => f.trim())
+    .filter(f => f.length > 0 && !toolManaged.has(f) && !f.startsWith('foundry/'))
+    .filter(f => !TOOL_MANAGED_PREFIX.some(p => f.startsWith(p)));
+  return outside.length ? { files: outside } : null;
+}

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

@@ -68,6 +68,10 @@ Walk the user through which elements of the law can be validated deterministical
 
 For each script-checkable element, write a standalone `.mjs` script next to the artefacts it validates (e.g. `foundry/artefacts/<type>/check-line-count.mjs`) and reference it in the command (e.g. `node foundry/artefacts/<type>/check-line-count.mjs {files}`). Place validators alongside the artefacts so they colocate with what they validate. Use existing project dependencies and Node.js built‑ins. Hand‑rolled heuristics (custom syllable counters, regex parsers, manual character walks) are a last resort — they produce false positives, waste tokens on debugging, and break on edge cases. Install a library instead. Only write validation logic from scratch when no npm package exists for the task and the heuristic is trivially correct.
 
+All flow artefacts — validator scripts, tests, test fixtures — live inside `foundry/`. Never place artefacts outside `foundry/`. Test fixtures colocate with the validator's test file under `foundry/artefacts/<type>/test/fixtures/`. When test fixtures match an artefact type's `file-patterns:`, they trigger false-positive quench feedback during flow runs. Keeping them inside `foundry/` prevents this.
+
+Every validator carries a companion test file alongside it (e.g. `check-line-count.test.js`). The test uses Node's built‑in test runner — `node --test check-line-count.test.js`. Follow TDD: write the test, confirm it fails against a current artefact, implement the validator, verify the test passes. The test feeds sample inputs to the validator script and asserts the correct JSONL output on stdout — it validates the JSONL contract, not just that the script runs.
+
 **Validators**: Ask about `validators` (optional) — offer to create one or skip.
 
 **Conflict check**: Read all existing laws that would apply to the same artefact types. Check for contradiction, duplication, or overlap. If any conflict is found, present it to the user:
@@ -85,7 +89,7 @@ For each script-checkable element, write a standalone `.mjs` script next to the
 
 ### 2. Plan
 
-Present a structured summary: law id, name, description, passing/failing criteria, target (global or type-specific with typeId), and validators (which elements are checked deterministically). Ask: "Does this capture what you want, or should we adjust the wording?" Iterate until the user is satisfied.
+Present a structured summary: law id, name, description, passing/failing criteria, target (global or type-specific with typeId), validators (which elements are checked deterministically), and the companion test file for each validator. Ask: "Does this capture what you want, or should we adjust the wording?" Iterate until the user is satisfied.
 
 ### 3. Confirm
 
@@ -93,9 +97,15 @@ Ask: "Proceed with this plan?" — wait for user answer before building. If the
 
 ### 4. Build
 
-1. **Validate**: Call `foundry_config_validate_law({ name: "<id>", body: "<assembled markdown>" })`. Assemble the body from the fields using the `## <id>` heading format the tool produces internally. If the result is `{ ok: false, errors: [...] }`, address each error and re-run until `{ ok: true }`. Common issues: missing required frontmatter keys, references to artefact types that do not exist yet.
+1. **Write validators with TDD**: For each validator declared in the plan:
+
+   a. **Write the test first** — create a companion test file alongside the validator (e.g. `foundry/artefacts/<type>/check-line-count.test.js`). The test imports or spawns the validator script with sample inputs and asserts the correct JSONL output on stdout. Run `node --test` to confirm it fails.
 
-2. **Create**: Translate the scope into the `target` argument:
+   b. **Implement the validator** — write the `.mjs` script. Run the test again to confirm it passes. Do not commit the validator without its passing test.
+
+2. **Validate**: Call `foundry_config_validate_law({ name: "<id>", body: "<assembled markdown>" })`. Assemble the body from the fields using the `## <id>` heading format the tool produces internally. If the result is `{ ok: false, errors: [...] }`, address each error and re-run until `{ ok: true }`. Common issues: missing required frontmatter keys, references to artefact types that do not exist yet.
+
+3. **Create**: Translate the scope into the `target` argument:
    - Global → `target: { kind: "global", file: "<file-name>.md" }`
    - Type-specific → `target: { kind: "type-specific", typeId: "<artefact-type>" }`
 
@@ -117,7 +127,7 @@ Ask: "Proceed with this plan?" — wait for user answer before building. If the
 
    The tool appends to an existing `laws.md` automatically when the new law id 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>", description: "<updated>", passing: "<updated>", failing: "<updated>" })` to modify the existing law in place.
 
-3. **Verify uniqueness**: After the file is created, confirm the law id is unique across all law files. If a collision exists, read the colliding law, present the conflict to the user, propose a rename or merge, ask one focused question about the user's preference, then write and commit the resolution.
+4. **Verify uniqueness**: After the file is created, confirm the law id is unique across all law files. If a collision exists, read the colliding law, present the conflict to the user, propose a rename or merge, ask one focused question about the user's preference, then write and commit the resolution.
 
 ### 5. Editing existing laws (prose or validators)
 
@@ -145,7 +155,7 @@ Then proceed with the update.
 
 > 🔍 **Drift check:** Verify that the changed validator still aligns with the law's prose. If the validator has narrowed or broadened, the prose may need a corresponding update.
 
-Then proceed with the update.
+After the validator implementation changes, update the companion test file. Run the tests to confirm they pass against the updated validator before committing.
 
 #### 5e. Apply the update
 
@@ -258,8 +268,47 @@ validators:
     failure-means: The artefact file does not contain exactly three non-empty lines.
 ~~~
 
+#### Companion test
+
+`foundry/artefacts/haiku/check-line-count.test.js`:
+
+~~~js
+import { describe, it } from 'node:test';
+import { execSync } from 'node:child_process';
+import assert from 'node:assert/strict';
+
+describe('check-line-count', () => {
+  it('passes for exactly three non-empty lines', () => {
+    const result = execSync(
+      `node foundry/artefacts/haiku/check-line-count.mjs foundry/artefacts/haiku/test/fixtures/haiku-valid.md`,
+      { encoding: 'utf8' },
+    );
+    assert.strictEqual(result.trim(), '');
+  });
+
+  it('reports an error for fewer than three lines', () => {
+    const result = execSync(
+      `node foundry/artefacts/haiku/check-line-count.mjs foundry/artefacts/haiku/test/fixtures/haiku-short.md`,
+      { encoding: 'utf8' },
+    );
+    assert.match(result, /Expected 3 non-empty lines/);
+  });
+
+  it('reports an error for more than three lines', () => {
+    const result = execSync(
+      `node foundry/artefacts/haiku/check-line-count.mjs foundry/artefacts/haiku/test/fixtures/haiku-long.md`,
+      { encoding: 'utf8' },
+    );
+    assert.match(result, /Expected 3 non-empty lines/);
+  });
+});
+~~~
+
 ## What you do NOT do
 
 - You do not skip the conflict check
 - You do not silently overwrite existing laws
 - You do not create artefact types unless the user's stated goal clearly requires it; ask one focused question when multiple designs are plausible
+- You do not write validators without companion tests
+- You do not place flow artefacts or test fixtures outside `foundry/`
+- You do not accept test failures — fix the validator and retry until every test passes

package/package.json

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