From c4bee767daa8a1057667a0c2577677e4a8f5cf77 Mon Sep 17 00:00:00 2001
From: Brummel <mould@mycelium.de>
Date: Mon, 15 Jun 2026 10:13:15 +0200
Subject: [PATCH] docs: replace spec-validation parser fact with a
 project-local directive
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The skills plugin no longer carries generic spec-validation machinery.
Move the ail/ail-json/ll code-block validation rules into a standalone
'Spec & plan code-block validation' section that instructs specify,
grounding-check, and planner directly — same effect, project-local.
---
 CLAUDE.md | 39 +++++++++++++++++++++++++--------------
 1 file changed, 25 insertions(+), 14 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index be5f717..b876bd3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -99,9 +99,8 @@ generic SKILL.md files at `~/dev/skills/<name>/SKILL.md`,
 agents under `~/dev/skills/<name>/agents/<agent>.md`. The
 plugin reads the few project-specific facts it needs (code
 roots, build/test commands, design-ledger paths, issue
-tracker, by-role standing reading, spec-validation parsers)
-from the "Skills plugin: project facts" section at the bottom
-of this file. See `~/dev/skills/README.md` for the skill table
+tracker, by-role standing reading) from the "Skills plugin:
+project facts" section at the bottom of this file. See `~/dev/skills/README.md` for the skill table
 and `~/dev/skills/docs/conventions.md` for the fixed
 conventions. Skills are sharper tools, not a replacement for
 orchestrator judgement.
@@ -321,6 +320,29 @@ landed in these files (use `git diff <prev-close>..HEAD --` on
 each file in the pair), open both files in the pair and confirm
 the matching update is present. Flag any unpaired arm as drift.
 
+## Spec & plan code-block validation
+
+A spec or plan's fenced code blocks are hypotheses, not verified bytes.
+When `specify`, `grounding-check`, or `planner` writes or reviews a
+spec/plan for this project, validate every fenced block it carries
+against the real tool before it ships:
+
+| Fence label | Validate with                            |
+|-------------|------------------------------------------|
+| `ail`       | `ail check <file>` (temp file `.ail`)     |
+| `ail-json`  | `ail check <file>` (temp file `.ail.json`)|
+| `ll`        | `llvm-as <file> -o /dev/null` (`.ll`)     |
+
+Write the block to a temp file with the matching extension and require
+exit 0; a non-zero exit is a defect — fix the spec/plan, do not pass
+the bytes downstream. A block whose fence label is not in this table
+is a documented skip, never a silent pass. Paste the parse-trace into
+the session as the attestation the check fired.
+
+This is deliberately project-local: the skills plugin carries no
+generic spec-validation machinery, so this section is the whole of it
+for AILang.
+
 ## Skills plugin: project facts
 
 The few facts the `~/dev/skills/` plugin needs that genuinely vary per
@@ -343,17 +365,6 @@ project. Everything else is a fixed convention (see
   (everything else, especially code roots and bench, is forbidden to
   it): `README.md`, `design`, `docs`, `examples`
 - **Fieldtest examples** — `examples/fieldtest`
-- **Spec-validation parsers** — fence-label → parser table the `specify`
-  parse-gate and `grounding-check` use to validate spec code blocks. A
-  block whose label has no entry is a documented skip, never a silent
-  pass.
-
-  | Fence label | Temp ext    | Command |
-  |-------------|-------------|---------|
-  | `ail`       | `.ail`      | `ail check {file}` |
-  | `ail-json`  | `.ail.json` | `ail check {file}` |
-  | `ll`        | `.ll`       | `llvm-as {file} -o /dev/null` |
-
 - **By-role standing reading** — extra files/commands a specific agent
   role reads on every dispatch, beyond the universal always-list
   (`CLAUDE.md` + `git log -10`).