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 agents under `~/dev/skills/<name>/agents/<agent>.md`. The
plugin reads the few project-specific facts it needs (code plugin reads the few project-specific facts it needs (code
roots, build/test commands, design-ledger paths, issue roots, build/test commands, design-ledger paths, issue
tracker, by-role standing reading, spec-validation parsers) tracker, by-role standing reading) from the "Skills plugin:
from the "Skills plugin: project facts" section at the bottom project facts" section at the bottom of this file. See `~/dev/skills/README.md` for the skill table
of this file. See `~/dev/skills/README.md` for the skill table
and `~/dev/skills/docs/conventions.md` for the fixed and `~/dev/skills/docs/conventions.md` for the fixed
conventions. Skills are sharper tools, not a replacement for conventions. Skills are sharper tools, not a replacement for
orchestrator judgement. 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 each file in the pair), open both files in the pair and confirm
the matching update is present. Flag any unpaired arm as drift. 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 ## Skills plugin: project facts
The few facts the `~/dev/skills/` plugin needs that genuinely vary per 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 (everything else, especially code roots and bench, is forbidden to
it): `README.md`, `design`, `docs`, `examples` it): `README.md`, `design`, `docs`, `examples`
- **Fieldtest examples** — `examples/fieldtest` - **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 - **By-role standing reading** — extra files/commands a specific agent
role reads on every dispatch, beyond the universal always-list role reads on every dispatch, beyond the universal always-list
(`CLAUDE.md` + `git log -10`). (`CLAUDE.md` + `git log -10`).