docs: replace spec-validation parser fact with a project-local directive

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.
This commit is contained in:
2026-06-15 10:13:15 +02:00
parent 2e8dfd8ff9
commit c4bee767da
+25 -14
View File
@@ -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`).