@really-knows-ai/foundry 3.0.0 → 3.0.1

package/dist/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## [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
 
@@ -106,10 +106,32 @@ 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. Include validators only when a deterministic check is needed. The format matches `add-law`:
+
+```markdown
+## <law-id>
+
+<What this law checks — one or two sentences.>
+
+validators:
+  - id: validator-id
+    command: ./script.sh
+    failure-means: (optional description)
+```
+
+The `validators` block is optional. When present, `quench` runs each validator for this law. Validator scripts live within the artefact type directory (e.g., `foundry/artefacts/<type>/check-foo.mjs`).
+
+**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 +157,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 +175,11 @@ 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)
+### 9. Add laws file (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.
 
-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.
-
-### 11. Confirm
+### 10. Confirm
 
 Show the user the complete file listing and the commit hashes.
 

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.1",
   "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",