@really-knows-ai/foundry 3.2.7 → 3.3.1

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

@@ -48,28 +48,37 @@ If the user names a type-specific law for an artefact type that does not exist,
 
 ### 2. Draft the law
 
-Write the law following the standard format:
+Write the law using these structured fields:
 
-```markdown
-## <law-id>
+- `id` (string) — lowercase, hyphenated law identifier, unique across all laws
+- `name` (string) — human-readable name
+- `description` (string) — one or two sentences describing what this law checks
+- `passing` (string) — description of what passing looks like
+- `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.
 
-<What this law checks — one or two sentences.>
+#### 2a. Identify deterministic vs subjective elements
 
-validators:
-  - id: validator-id
-    command: ./script.sh
-    failure-means: (optional description)
-```
+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:
 
-The `law-id` (heading) should be:
+> 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
 - Unique across all laws (global and type-specific)
 
-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
 
 Read all existing laws that would apply to the same artefact types:
@@ -111,7 +120,7 @@ Iterate until the user is happy.
 
 ### 5. Validate the draft
 
-Call `foundry_config_validate_law({ name: "<file-name-without-extension>", body: "<full markdown>" })`.
+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 (adjust the body) and re-run until you get `{ ok: true }`. Common issues: missing required frontmatter keys, references to artefact types that don't exist yet.
 
@@ -126,8 +135,11 @@ Then call:
 
 ```
 foundry_config_add_law({
-  name: "<file-name-without-extension>",
-  body: "<full markdown>",
+  id: "<id>",
+  name: "<name>",
+  description: "<description>",
+  passing: "<passing>",
+  failing: "<failing>",
   target: { kind: "global", file: "<file-name>.md" }   // OR
            { kind: "type-specific", typeId: "<artefact-type>" }
 })
@@ -140,9 +152,9 @@ The tool:
 - produces one git commit on the current `config/*` branch.
 
 The tool appends to an existing `laws.md` automatically when the
-new `## <law-id>` heading is not already present. It only errors when
+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>", body: "<updated-body>" })`
+`foundry_config_edit_law({ id: "<law-id>", description: "<updated>", passing: "<updated>", failing: "<updated>" })`
 to modify the existing law in place.
 
 Show the user the resulting commit hash from the response.
@@ -286,7 +298,7 @@ Then proceed with the update.
 
 #### 8e. Apply the update
 
-Call `foundry_config_edit_law({ id: "<law-id>", body: "<updated-markdown>" })` with the full updated body (prose and validators combined).
+Call `foundry_config_edit_law({ id: "<law-id>", description: "<updated>", passing: "<updated>", failing: "<updated>", validators: [...] })` with the full updated fields.
 
 Validate the result. If the tool returns `{ ok: true }`, show the user the commit hash. If it returns `{ ok: false, errors }`, address each error and retry.
 

package/package.json

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