@really-knows-ai/foundry 3.3.3 → 3.3.4

package/dist/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [3.3.4] - 2026-05-18
+
+### Fixed
+
+- **Corrected law/validator framing across all skills and agent.** Laws are
+  rules — they are never "deterministic" or "subjective." Validators are
+  optional scripts attached to laws that check script-checkable elements
+  during quench. Appraisers evaluate every law, de-prioritising elements
+  already covered by passed validators. Removed all `[deterministic|subjective]`
+  law labelling from add-flow's plan template and add-law's Understand phase.
+
 ## [3.3.3] - 2026-05-15
 
 ### Fixed

package/dist/agents/foundry.md

@@ -17,6 +17,17 @@ Foundry is a framework for governed AI artefact generation. Your role is to help
 - Only create configuration during the Build phase, after the user confirms the plan.
 - Report outcomes as Foundry concepts, files created or updated, validations run, and commits made.
 
+## Foundry Concepts
+
+- **Artefact type** — the kind of file a flow produces (e.g. a haiku poem, a blog post, a code review). Defined by file patterns and appraiser configuration.
+- **Law** — a single rule that artefacts of a given type must satisfy. Laws cover both objective criteria (line count, syllable count, forbidden words) and subjective criteria (imagery quality, emotional resonance, persuasiveness). Every law is appraised by appraisers — laws are not inherently deterministic.
+- **Validator** — an optional script attached to a law. Runs during quench to check script-checkable elements without an LLM. Outputs NDJSON with file/text per violation. Since quench always runs before appraise, validators that pass mean those elements are already verified. A law may have zero, one, or multiple validators. Appraisers are aware of which elements a validator covers so they can de-prioritise them, focusing their judgment on elements without deterministic checks.
+- **Appraiser** — a personality or perspective that reads all laws for an artefact type and judges artefacts against them. Appraisers evaluate every law — they note which elements were covered by validators (and thus passed deterministically) and focus their judgment on the remaining elements.
+- **Cycle** — a pipeline stage (assay → forge → quench → appraise → human-appraise) that produces artefacts of one type.
+- **Flow** — ties cycles together. Defines which cycles start the pipeline.
+
+When discussing laws with the user, say they are "rules" or "criteria." Present which elements can be script-checked (with validators) and which elements require the appraiser's judgment. Never label a law itself as "deterministic" or "subjective."
+
 ## Authoring Posture
 
 When the user asks to create or change a flow, load the relevant authoring skill first (`add-flow`, `add-artefact-type`, `add-appraiser`, `add-law`, `add-cycle`, or the memory authoring skills). Each skill follows a wizard protocol: Understand → Plan → Confirm → Build. Follow the skill's instructions — they guide you through asking questions, presenting a plan, waiting for confirmation, and only then building.

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

@@ -45,7 +45,7 @@ Extract or ask for the flow purpose, expected final artefact, output location, a
 
 **What the flow produces**: Ask about the artefact type the flow should produce. Determine whether it needs a new artefact type or whether an existing one fits.
 
-**Quality constraints**: Ask about the laws that govern quality. For each law: what it checks, whether it applies globally or to a specific artefact type, and the deterministic-vs-subjective split.
+**Quality constraints**: Ask about the laws that govern quality. For each law: what it checks, whether it applies globally or to a specific artefact type, and which elements can be checked with validators.
 
 **Appraisers**: Ask about the appraisers that evaluate quality. Determine how many are needed and whether existing appraisers fit or new ones are needed.
 
@@ -65,7 +65,7 @@ Create missing dependencies in validation order:
 
 1. **Artefact types** (no sub-dependencies): For each new artefact type, gather `id`, `name`, `filePatterns`, `description`, and whether it needs type-specific laws or appraiser configuration. Context object: `{id, name, filePatterns, description, appraisers?}`.
 
-2. **Laws** (may reference artefact types): For each new law, gather `id`, `name`, `description`, `passing`, `failing`, the target (global file or type-specific with `typeId`), and the deterministic-vs-subjective split. Determine whether validators are needed. Context object: `{id, name, description, passing, failing, target: {kind, file|typeId}, validators?}`.
+2. **Laws** (may reference artefact types): For each new law, gather `id`, `name`, `description`, `passing`, `failing`, the target (global file or type-specific with `typeId`), and which elements can be checked with validators. Determine whether validators are needed. Context object: `{id, name, description, passing, failing, target: {kind, file|typeId}, validators?}`.
 
 3. **Appraisers** (may reference models): For each new appraiser, gather `id`, `name`, `description`, and optional `model` preference. Context object: `{id, name, description, model?}`.
 
@@ -86,8 +86,8 @@ Flow: <id> — <name>
   Artefact Types:
     · <id> (<name>) — <filePatterns>
   Laws:
-    · <id> — <description> [deterministic|subjective]
-      validators: <validator-id> (if deterministic)
+    · <id> — <description>
+      validators: <validator-id> (if any)
   Appraisers:
     · <id> — <description>
   Cycles:

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

@@ -53,20 +53,20 @@ If global, ask for the `file` (the filename under `foundry/laws/`, e.g. `rules.m
 
 **Fields**: Ask for `id`, `name`, `description`, `passing` criteria, and `failing` criteria one at a time.
 
-**Deterministic vs subjective split**: For each law, explicitly split what it checks into two categories:
+**Validators**: For each law, identify which elements can be validated deterministically:
 
-- **Deterministic** — can be checked by a script without human or LLM judgment. Examples: line count, syllable count, word minimum, forbidden patterns, file existence, formatting rules. These become `validators:` entries in the law.
-- **Subjective** — requires judgment. Examples: imagery quality, emotional resonance, persuasiveness, aesthetic appeal, clarity of argument. The appraisers evaluate these during the appraise stage. No validator entry needed; the law's prose alone guides the appraiser.
+- **Script-checkable** — can be checked by a validator without human or LLM judgment. Examples: line count, syllable count, word minimum, forbidden patterns, file existence, formatting rules. These become `validators:` entries in the law. Since quench runs before appraise, validators that pass mean those elements are already verified — the appraiser is aware of this and can de-prioritise them, focusing judgment on elements without validators.
+- **Requires judgment** — needs the appraiser's evaluation. Examples: imagery quality, emotional resonance, persuasiveness, aesthetic appeal, clarity of argument. The law's prose alone guides the appraiser — no validator entry needed.
 
-Walk the user through this split for each law:
+Walk the user through which elements of the law can be validated deterministically:
 
-> This law covers [summary]. Here's what's deterministic vs subjective:
-> - Deterministic: [list elements that can be script-checked]
-> - Subjective: [list elements requiring judgment — appraisers handle these]
+> This law covers [summary]. Here's which parts can be checked with validators:
+> - Validatable: [list elements that can be script-checked]
+> - Requires judgment: [list elements the appraiser evaluates]
 >
-> Shall I add validators for the deterministic elements?
+> Shall I add validators for the script-checkable elements?
 
-For each deterministic 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. Prefer Node.js built-ins and libraries already in the project; hand-rolled heuristics are fragile — use available packages instead of writing custom validation logic from scratch.
+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. Prefer Node.js built-ins and libraries already in the project; hand-rolled heuristics are fragile — use available packages instead of writing custom validation logic from scratch.
 
 **Validators**: Ask about `validators` (optional) — offer to create one or skip.
 
@@ -85,7 +85,7 @@ For each deterministic element, write a standalone `.mjs` script next to the art
 
 ### 2. Plan
 
-Present a structured summary: law id, name, description, passing/failing criteria, target (global or type-specific with typeId), deterministic/subjective split, validators. 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), 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.
 
 ### 3. Confirm
 

package/dist/skills/appraise/SKILL.md

@@ -164,6 +164,6 @@ When reviewing an artefact, check the feedback history for `#human` tagged items
 
 - You do not write files — feedback output goes through `foundry_feedback_add` and `foundry_feedback_resolve`.
 - You do not revise the artefact.
-- You do not check deterministic rules — that is the quench skill's job.
+- You do not run deterministic validators — that is the quench skill's job.
 - You do not filter out feedback because only one appraiser raised it — one is enough.
 - You do not register artefacts — that happens automatically via the orchestrator's internal finalize step.

package/package.json

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