From 82cd9eafb2f519289d914191fb860a223bb10638 Mon Sep 17 00:00:00 2001 From: Brummel Date: Mon, 15 Jun 2026 10:13:13 +0200 Subject: [PATCH] refactor: drop cross-project spec-validation parser machinery The fence-label -> parser fact, the specify/grounding-check/planner parse gates, the parse-trace attestation, and all their cross-references served a single real user (ailang). Convention over configuration: the generic machinery is removed plugin-wide; the one consumer carries an equivalent project-local directive in its own CLAUDE.md. Archive under docs/plans and docs/specs left intact as time documents. --- README.md | 7 ++--- docs/conventions.md | 5 ++-- docs/design.md | 4 +-- docs/pipeline.md | 5 ++-- planner/SKILL.md | 21 --------------- specify/SKILL.md | 34 +++++++---------------- specify/agents/grounding-check.md | 45 +++++-------------------------- specify/agents/spec-skeptic.md | 4 +-- templates/CLAUDE.md.fragment | 11 -------- 9 files changed, 26 insertions(+), 110 deletions(-) diff --git a/README.md b/README.md index a4730a4..068893b 100644 --- a/README.md +++ b/README.md @@ -92,9 +92,6 @@ project's own `CLAUDE.md` under `## Skills plugin: project facts`: - Regression scripts; architect sweeps - Design ledger / glossary / contracts / models / bench / public interface / fieldtest-examples paths -- Spec-validation parsers (fence label → `{ext, cmd}`, `cmd` carrying - the `{file}` placeholder; a label with no entry is a documented - skip, never a silent pass) - Per-role standing reading - Issue-tracker repo slug + list / show commands - Spec auto-sign (off by default) @@ -115,8 +112,8 @@ auto-sign in its CLAUDE.md project facts. With it on, the orchestrator may sign a spec in the user's place, but never on its own confidence. Signing requires two stages to clear: -- **Objective gates** — the precondition gate, the parse-every-block - gate, and a `grounding-check` `PASS` with no human override. +- **Objective gates** — the precondition gate and a `grounding-check` + `PASS` with no human override. - **A unanimous adversarial panel** — the `spec-skeptic` agent dispatched five times in parallel, one per lens (`criterion`, `grounding`, `scope-fork`, `ambiguity`, `plan-readiness`), each diff --git a/docs/conventions.md b/docs/conventions.md index e68d399..fbe4876 100644 --- a/docs/conventions.md +++ b/docs/conventions.md @@ -112,7 +112,6 @@ Under `## Skills plugin: project facts`, where applicable: | **doc-build command** | docwriter | Optional; prints warnings on stderr. | | **regression scripts** | audit (bencher) | Optional list; non-zero exit = regress. | | **architect sweeps** | audit (architect) | Optional list; non-zero exit = drift suspicion. | -| **spec-validation parsers** | specify, grounding-check | Optional; fence-label → `{ext, cmd}` table. `cmd` MUST contain `{file}`. Absent label → documented skip, never silent pass. | | **design ledger** | architect, most agents | Optional path (e.g. `design/INDEX.md`). | | **glossary** | every role | Optional path; implicitly standing reading. | | **design contracts / models** | docwriter, specify | Optional dirs. Aspirational-source frontmatter marker recommended (see below). | @@ -140,5 +139,5 @@ validated-against: When the marker is absent the signal is simply absent — `specify` degrades to treating the content as unmarked, never hard-failing. -Content lifted from an aspirational source is flagged and must clear -the parse-every-block gate before it ships in a spec. +Content lifted from an aspirational source is flagged as a target, +not verified fact, before it ships in a spec. diff --git a/docs/design.md b/docs/design.md index 0997988..18ce69e 100644 --- a/docs/design.md +++ b/docs/design.md @@ -80,8 +80,8 @@ project's `CLAUDE.md` under `## Skills plugin: project facts`: code roots, build / test / lint / doc-build commands, regression scripts, architect sweeps, design-ledger / glossary / contracts / models / bench / public-interface / fieldtest-examples paths, -spec-validation parsers, by-role standing reading, the issue-tracker -repo slug and commands, and spec auto-sign. The template is in +by-role standing reading, the issue-tracker repo slug and commands, +and spec auto-sign. The template is in `../templates/CLAUDE.md.fragment`; the per-fact reference is the table in `conventions.md`. diff --git a/docs/pipeline.md b/docs/pipeline.md index 6972d0b..7e95a9e 100644 --- a/docs/pipeline.md +++ b/docs/pipeline.md @@ -98,9 +98,8 @@ Hard-gate before plan — the spec-production core and the carrier of the "no plan without an approved spec" invariant. Takes a settled design (directly from sources, or a ratified design handed over by `brainstorm`), applies the feature-acceptance criterion, writes the -spec to `docs/specs`, runs the parse-every-block and -`grounding-check` gates, and takes user sign-off — with review but no -interview. Bounces to `brainstorm` the moment the sources do not +spec to `docs/specs`, runs the `grounding-check` gate, and takes user +sign-off — with review but no interview. Bounces to `brainstorm` the moment the sources do not resolve a load-bearing design decision. A core node — the spec-production gate before `planner` on every design path. diff --git a/planner/SKILL.md b/planner/SKILL.md index 0d53b59..f4795b2 100644 --- a/planner/SKILL.md +++ b/planner/SKILL.md @@ -221,22 +221,6 @@ Before handing the plan off, run this checklist inline: so "nothing ran" cannot masquerade as "nothing regressed". This is a recurring defect family — scrub every Run step whose assertion lives in a filter string. -9. **Parse-the-bytes-you-inline gate.** Every verbatim code body - the plan inlines into a task step must be run through the - spec-validation parsers the project declares in its CLAUDE.md - project facts, following the parser-invocation protocol in - `docs/conventions.md` (which owns the no-parser skip, the - malformed-entry failure, and the no-op when the project - declares no spec-validation parsers) before - hand-off. The target is the surface-language snippets the plan - lifts verbatim (example programs, fixtures); the project's - source-language test / implementation bodies are NOT the - target — the `implement` compile gate catches those. A parse - failure is a plan failure — the plan would hand the - implementer bytes that do not parse, the last defensive line - before dispatch — fix the plan, do not hand off. The - parse-trace goes into the planner's self-review activity (the - session) as the attestation the gate fired. Fix issues inline. @@ -268,7 +252,6 @@ The planner skill does not perform the commit itself. | "Step 5 'implement the parser' is fine, I'll detail it at execution time" | Then it's not a step, it's a wish. Steps are bite-sized OR the plan isn't done. | | "Task 7 is similar to Task 4, just say so" | The executor may read tasks out of order. Repeat the code. | | "The spec has a TBD too, I can pass it through" | Bounce back to `specify`. Plans inherit spec gaps; spec gaps are not plan placeholders. | -| "The example program came straight from the spec, it must be valid" | The spec's code blocks are hypotheses, not verified bytes — specify's parse gate can be skipped and a post-spec edit can break them. Re-parse every surface-language body you inline against the spec-validation parsers the project declares in its CLAUDE.md project facts; this is the last line before the implementer hits it (issue #1 Fix 4). | ## Red Flags — STOP @@ -279,10 +262,6 @@ The planner skill does not perform the commit itself. - Step descriptions longer than the code they describe - Header missing parent spec reference - Self-review skipped because "the plan looks fine" -- A task step inlining a surface-language code body whose fence - label has a project-declared spec-validation parser (its - CLAUDE.md project facts), handed off without a parse-trace in - the planner session ## Cross-references diff --git a/specify/SKILL.md b/specify/SKILL.md index a88ee85..6330f8b 100644 --- a/specify/SKILL.md +++ b/specify/SKILL.md @@ -17,8 +17,7 @@ planner consumes: with review, but **without an interview**. It is the **sole home of the spec-production gates**: the feature-acceptance criterion, the write-spec step, the -parse-every-block self-review, the `grounding-check` hard-gate, and -the user-review gate. Whichever way design work enters — fresh +`grounding-check` hard-gate, and the user-review gate. Whichever way design work enters — fresh through `brainstorm`'s discovery, or directly from sources that already resolve the design — it passes through `specify` to become a spec. `specify` carries the universal invariant **no plan without an @@ -62,7 +61,7 @@ Triggers: **Skipping a gate is never permitted.** The interview is `brainstorm`'s, and its absence here is the whole point — but the *production gates* -(criterion, parse-every-block, grounding-check, user-review) are +(criterion, grounding-check, user-review) are non-negotiable regardless of how the work entered. "The issue looks exhaustive, skip the grounding-check" is the reactive-deference failure this skill must not reintroduce. @@ -73,7 +72,7 @@ this skill must not reintroduce. THE SOURCES MUST RESOLVE EVERY LOAD-BEARING DESIGN DECISION BEFORE THE SPEC IS WRITTEN. IF WRITING THE SPEC FORCES A CHOICE BETWEEN PLAUSIBLE DESIGNS THE SOURCES DO NOT RESOLVE, STOP AND BOUNCE TO brainstorm. DO NOT SILENTLY PICK ONE. -THE PRODUCTION GATES — ACCEPTANCE CRITERION, PARSE-EVERY-BLOCK, GROUNDING-CHECK, USER-REVIEW — +THE PRODUCTION GATES — ACCEPTANCE CRITERION, GROUNDING-CHECK, USER-REVIEW — ARE NON-NEGOTIABLE REGARDLESS OF ENTRY PATH. NO PLAN, SCAFFOLDING, OR DOWNSTREAM SKILL UNTIL THE SPEC IS APPROVED — BY THE USER, OR (ONLY UNDER /boss WITH spec_auto_sign ENABLED) BY THE AUTO-SIGN GATE: ALL OBJECTIVE GATES GREEN @@ -100,8 +99,7 @@ Before producing anything, establish what the sources actually say: files the design touches — rather than re-deriving it. - If the project has a design ledger (its CLAUDE.md project facts), walk to the contracts the work touches. Note any `status: - aspirational` source: its code is a target, not verified fact — - track it for the Step-4 parse gate. + aspirational` source: its code is a target, not verified fact. ### Step 1.5 — Precondition gate (bounce-back) @@ -203,8 +201,8 @@ surface so no code to show" is the rationalisation to refuse. **Code lifted from an aspirational source is a hypothesis, not evidence.** If the concrete code here is lifted from a design-models file (or any `status: aspirational` source, per Step 1), it carries no -validation by default. Treat it as the spec's most suspect bytes: it -must clear the Step-4 parse-every-block gate before PASS. +validation by default. Treat it as the spec's most suspect bytes: flag +it as a target, not verified fact. ### Step 3 — Write the spec @@ -258,15 +256,6 @@ Inline checklist (not a subagent dispatch): carry before → after code for every load-bearing change (plus the worked user-facing example for a surface cycle)? A load-bearing change described only in prose is a self-review failure to fix. -6. **Parse-every-block gate.** Extract every fenced code block and run - it through the spec-validation parsers the project declares in its - CLAUDE.md project facts (a fence label with no parser is a documented - skip, never a silent pass; a malformed entry fails closed; the whole - gate is a no-op when the project declares no parsers). A parse - failure is a self-review failure — fix the spec; do not pass - unparsed bytes downstream. Paste the parse-trace into the chat: a - visible trace attests the gate fired; its absence means it was - skipped. Fix issues inline. @@ -363,8 +352,7 @@ CLAUDE.md project facts): fork was silently picked (if one had been, `specify` would have bounced, so reaching here is the evidence; do not re-decide it). - Step 4 self-review clean, **including the placeholder scan** (no - `TBD` / `TODO` / incomplete section) and a pasted parse-trace - for every configured-label block. + `TBD` / `TODO` / incomplete section). - Step 5 `grounding-check` returned **`PASS`** — *not* an overridden `BLOCK`. An override needs a human; with no human in the loop a `BLOCK` can never be overridden, so any non-`PASS` @@ -480,9 +468,8 @@ discipline `tdd` applies when behaviour is not test-specifiable. | "There's a small open fork but the sources mostly decide it — I'll pick the rest" | "Mostly decided" with one real fork left is an unresolved design, and a guessed design baked into a spec is harder to dislodge than an open question. That is the bounce-back trigger — stop and go to `brainstorm`. | | "Genuine doubt whether the sources resolve this — but bouncing feels like overkill" | Doubt about whether the sources resolve a decision *is* the fork signal. It resolves to a bounce, not a guess. The bounce is cheap (nothing is written yet); a wrong guess in a ratified spec is not. | | "The shape is clear from the prose, I don't need to paste the code" | If it's clear, pasting it is free; if pasting it is hard, it wasn't clear. The acceptance criterion is unjudgeable without the worked code. | -| "The block obviously parses — I wrote it carefully" | Careful authoring is not a parse. A spec's code blocks are hypotheses until the live tool accepts them. If a parser is configured for the fence label, run it and paste the trace. | | "Just polishing a wording after PASS, no need to re-dispatch" | The grounding-check report attests to specific bytes. A polish edit changes the bytes; the attestation no longer covers them. Re-dispatch is cheap. | -| "It's in a model doc / the design ledger, so it's canonical" | A `models` / RFC / proposal doc holds aspirational code — a target, not verified fact. Code lifted from a `status: aspirational` source must clear the Step-4 parse gate like any other block. | +| "It's in a model doc / the design ledger, so it's canonical" | A `models` / RFC / proposal doc holds aspirational code — a target, not verified fact. Flag code lifted from a `status: aspirational` source as such; it is not ratified contract. | | "In `/boss` with auto-sign on, this spec looks solid — I'll sign and move on" | Your sense that it looks solid is the exact signal the auto-sign gate refuses to trust. Signing requires all objective gates green AND a unanimous `spec-skeptic` panel. If you find yourself wanting to sign on confidence, that is the cue to run the gate, not to skip it. | | "One lens blocked on something minor — I'll sign anyway since the rest passed" | The panel is unanimous-or-nothing by design. You never *sign over* a `BLOCK`. An editorial `BLOCK` you may *repair* (within the ≤ 2-round budget, with a full re-panel after); a design `BLOCK` routes to the human. Neither is overruling a juror — that is the whole point of replacing your eye with five independent ones. | @@ -492,11 +479,8 @@ discipline `tdd` applies when behaviour is not test-specifiable. - "The sources are thorough, skip a gate" thoughts (any flavour) - A load-bearing change described in prose with no before → after code block; a surface cycle with no worked user-facing example -- A spec carrying a code block whose fence label has a spec-validation - parser (the project's CLAUDE.md project facts), committed without a - parse-trace in the chat - Lifting code verbatim from a `status: aspirational` source without - flagging it for the Step-4 parse gate + flagging it as a target, not verified fact - Editing the spec file after a Step 5 PASS without re-dispatching - (auto-sign) About to sign a spec in the user's place on confidence — without all objective gates green AND a unanimous `spec-skeptic` diff --git a/specify/agents/grounding-check.md b/specify/agents/grounding-check.md index b2206f2..8151732 100644 --- a/specify/agents/grounding-check.md +++ b/specify/agents/grounding-check.md @@ -1,6 +1,6 @@ --- name: grounding-check -description: Read-only grounding-check reviewer for spec drafts. Dispatched by the specify skill in Step 5, between linguistic self-review and user-approval. Reads the draft with fresh context, extracts its load-bearing assumptions about current codebase behaviour, and for each one searches the workspace for a currently-green test that ratifies it; also validates the spec's own fenced code blocks against the spec-validation parsers the project declares in its CLAUDE.md project facts. Reports PASS or BLOCK. Does NOT propose fixes, does NOT edit files. +description: Read-only grounding-check reviewer for spec drafts. Dispatched by the specify skill in Step 5, between linguistic self-review and user-approval. Reads the draft with fresh context, extracts its load-bearing assumptions about current codebase behaviour, and for each one searches the workspace for a currently-green test that ratifies it. Reports PASS or BLOCK. Does NOT propose fixes, does NOT edit files. tools: Read, Glob, Grep, Bash --- @@ -138,9 +138,8 @@ mechanism strongly. EXTRACT ASSUMPTIONS FROM THE SPEC, NOT FROM YOUR MEMORY. RATIFICATION REQUIRES A NAMED, CURRENTLY-GREEN TEST. NOT CODE PRESENCE. NOT RECALL. ONE UNRATIFIED LOAD-BEARING ASSUMPTION = BLOCK. NO PARTIAL CREDIT. -ONE SPEC CODE BLOCK THAT FAILS ITS PROJECT-DECLARED PARSER = BLOCK. YOU DO NOT EDIT FILES. YOU DO NOT PROPOSE FIXES. -YOU DO NOT RUN THE FULL TEST SUITE. (TEST LIST, TYPE-CHECK, AND PER-BLOCK PARSER RUNS ARE OK.) +YOU DO NOT RUN THE FULL TEST SUITE. (TEST LIST AND TYPE-CHECK ARE OK.) ``` ## The Process @@ -167,30 +166,12 @@ YOU DO NOT RUN THE FULL TEST SUITE. (TEST LIST, TYPE-CHECK, AND PER-BLOCK PARSER 4. Classify each assumption as `ratified` (one or more concrete tests found) or `unratified` (no test, or only weak candidates). -5. **Code-block parse pass.** If the project declares - spec-validation parsers (its CLAUDE.md project facts), - extract every fenced code block - from the spec. For each block whose fence label has a - declared parser: write it to a temp file with the parser's - `ext`, run the parser's `cmd` with `{file}` substituted, and - require exit 0. A non-zero exit marks the block unparseable. - A block whose fence label has no parser is skipped and noted - ("no parser for fence label X"); never a silent pass. If the - project declares no spec-validation parsers, this pass is a - documented no-op. This pass is complementary to the - assumption search: it checks the spec's own bytes against the - live tool, not the codebase's behaviour — and it is - independent of the orchestrator's own Step-7 parse gate, the - fresh-context second line of the same defense. -6. Compute aggregate status: - - All assumptions ratified AND every block whose fence label - has a declared parser parsed clean → `PASS`. - - One or more unratified assumptions, OR one or more - unparseable code blocks → `BLOCK`. +5. Compute aggregate status: + - All assumptions ratified → `PASS`. + - One or more unratified assumptions → `BLOCK`. - Any infra error (cannot read spec, type-check fails, - workspace does not build, a declared parser command is - missing from PATH) → `INFRA_ERROR`. -7. Emit the report in the format below. + workspace does not build) → `INFRA_ERROR`. +6. Emit the report in the format below. The process is bounded by your dispatch context. If extraction yields more than ~20 candidate assumptions, stop @@ -237,15 +218,6 @@ Unratified assumptions: would have> (Repeat per unratified assumption. Omit this block entirely on PASS.) - -Unparseable code blocks: -- Block: - Parser: - Failure: - -(Repeat per unparseable block. Omit this block entirely when none -failed. A "no parser for fence label X" skip is noted here as a -single line, not a failure.) ``` On `INFRA_ERROR`, only the first two lines are required, @@ -266,7 +238,6 @@ the assumption-extraction step yields an empty list, emit | "I extracted too many assumptions, let me trim the report" | Don't trim. If a spec has too many assumptions to check, that is the finding — report it as BLOCK with reason "spec too broad". | | "The orchestrator will override if I block, so I'll lean toward PASS" | The override is the orchestrator's job, not yours. Your job is to be the fresh-context check. Skewing toward PASS defeats the whole role. | | "I'll run the full test suite to see which tests are actually green" | You may NOT run the full test suite. Use the project's test-list command to enumerate, then read test bodies. Running tests would mutate workspace state and is out of scope for a read-only review. | -| "The code block is just illustrative, not a claim about behaviour" | A spec code block whose fence label has a project-declared parser is a hypothesis the downstream plan will lift verbatim. Illustrative or not, if it does not parse it is a defect. Run the parser and report the failure. | ## Red Flags — STOP @@ -278,8 +249,6 @@ the assumption-extraction step yields an empty list, emit it - About to mark an assumption ratified based on code presence rather than test presence -- About to PASS a spec carrying a code block whose fence label - has a project-declared parser without having run that parser - About to skip an assumption because "it would always be true" - Report exceeding ~500 tokens diff --git a/specify/agents/spec-skeptic.md b/specify/agents/spec-skeptic.md index 921ad71..18c3647 100644 --- a/specify/agents/spec-skeptic.md +++ b/specify/agents/spec-skeptic.md @@ -118,7 +118,7 @@ YOUR DEFAULT POSTURE IS REFUTATION, NOT APPROVAL. WHEN YOU CANNOT DECIDE AFTER A HONEST SEARCH, BLOCK. THERE IS NO PARTIAL CREDIT. `grounding` RATIFICATION REQUIRES A NAMED, CURRENTLY-GREEN TEST. NOT CODE PRESENCE. NOT RECALL. YOU DO NOT EDIT FILES. YOU DO NOT PROPOSE FIXES. -YOU DO NOT RUN THE FULL TEST SUITE. (TEST LIST, TYPE-CHECK, PER-BLOCK PARSER RUNS ARE OK.) +YOU DO NOT RUN THE FULL TEST SUITE. (TEST LIST, TYPE-CHECK ARE OK.) ``` ## The Process @@ -209,5 +209,5 @@ On `INFRA_ERROR`, the first three lines plus a brief `Detail:` line. - About to lean toward `SOUND` because the orchestrator seems confident or the spec reads smoothly - About to run the project's full test suite (test-list / type-check - / per-block parser only) + only) - Report exceeding ~300 tokens diff --git a/templates/CLAUDE.md.fragment b/templates/CLAUDE.md.fragment index 9cc3a20..3a04930 100644 --- a/templates/CLAUDE.md.fragment +++ b/templates/CLAUDE.md.fragment @@ -129,17 +129,6 @@ that does not apply. bench, is forbidden to it). Example: `README.md, docs, examples`. - **Fieldtest examples** — optional path where the `fieldtester` writes fixtures. Example: `examples/fieldtest`. -- **Spec-validation parsers** — optional. A 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. `cmd` MUST contain the `{file}` placeholder. - Example: - - | Fence label | Temp ext | Command | - |-------------|----------|---------| - | `ail` | `.ail` | `ail check {file}` | - | `ail-json` | `.ail.json`| `ail check {file}` | - - **By-role standing reading** — optional. Extra files/commands a specific agent role reads on every dispatch, beyond the universal `CLAUDE.md` + `git log -10`. Role names match agent slugs (`architect`,