@really-knows-ai/foundry 3.3.0 → 3.3.1

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

@@ -142,7 +142,7 @@ function artefactTypeArgs(s) { return {
 function appraiserArgs(s) { return {
   id: s.string().describe('Slugged identifier matching the filename under foundry/appraisers/'),
   name: s.string().describe('Human-readable display name written to frontmatter.name'),
-  description: s.string().describe('Prose personality description placed after frontmatter'),
+  description: s.string().describe('Personality or perspective (2-4 sentences: how they think, what they care about, how they evaluate). Appraisers read laws to learn what to check — laws define boundaries and constraints, this field defines the evaluator character and lens only. Do not enumerate criteria here; put those in laws.'),
   model: s.string().optional().describe('Optional model override for this appraiser (e.g. openai/gpt-4o)'),
 }; }
 

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

@@ -332,7 +332,7 @@ 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'),
+        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.'),
         failureMeans: tool.schema.string().optional().describe('Description of what failure means'),
       })).optional().describe('Optional deterministic validators'),
     },

package/dist/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [3.3.1] - 2026-05-14
+
+### Fixed
+
+- **Appraiser tool description** now explicitly states that appraisers are
+  personalities only — boundaries and constraints belong in laws. Prevents
+  the AI from embedding criteria in appraiser descriptions that should be
+  encoded as laws.
+- **Validator command description** now mandates `.mjs` scripts and NDJSON
+  stdout format (`file`, `text`, optional `location`/`severity`, exit code
+  ignored). Prevents the AI from using inline bash/Python validators that
+  don't produce machine-parseable output.
+- **add-law skill** gains §2a: a deterministic-vs-subjective split step
+  that walks the user through which law elements can be script-checked and
+  which are left to appraisers. Includes guidance to prefer existing
+  libraries over hand-rolled validation logic.
+- **add-artefact-type skill** no longer carries validator guidance
+  (validators are exclusively law-related, not artefact-type-related).
+
 ## [3.3.0] - 2026-05-14
 
 ### Added

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

@@ -94,8 +94,6 @@ in the `name` field.
 
 Ask: does this capture the artefact type correctly?
 
-When laws or validators are clearly part of the requested artefact type, draft them during artefact-type creation. Use the validator contract from `add-law` and prefer established packages installed with the project package manager.
-
 ### 5. Laws (optional)
 
 Ask:
@@ -114,17 +112,6 @@ 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:

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

@@ -57,6 +57,23 @@ Write the law using these structured fields:
 - `failing` (string) — description of what failing looks like
 - `validators` (array, optional) — validator entries. Include only when a deterministic check can decide pass/fail. See **Validator contract** below for the exact shape a validator command must satisfy.
 
+#### 2a. Identify deterministic vs subjective elements
+
+For each law, explicitly split what it checks into two categories:
+
+- **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.
+
+Walk the user through this split for each law:
+
+> 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]
+>
+> Shall I add validators for the deterministic 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.
+
 The `id` value should be:
 - Lowercase, hyphenated
 - Short but descriptive

package/package.json

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