AILang/docs/specs/0013-brainstorm-grounding-check.md

Brainstorm Grounding-Check — Design Spec

Date: 2026-05-11 Status: Draft — awaiting user spec review Authors: Brummel (orchestrator) + Claude

Goal

Close the spec-defect loophole that surfaced on 2026-05-11, when iter 23.4 BLOCKED three times on architectural prerequisites the parent spec had not anticipated. The root cause was a load-bearing half-sentence in docs/specs/2026-05-10-23-eq-ord-prelude.md — "polymorphic helpers ... work the same way: the typeclass-elaboration in 22b.3 inserts the right monomorphised compare__T symbol per use site" — that was never verified against any existing green test.

Today the brainstorm skill verifies specs only linguistically (Step 7 self-review) and via user approval (Step 8). No step grounds the spec's assumptions against the actual codebase. This spec adds one: a new agent, dispatched between Step 7 and Step 8, that reads the spec with fresh context, extracts its load-bearing assumptions, and for each one searches for a currently-green test that ratifies it. On miss: hard-discard with a roadmap entry. On miss + Boss override: proceed. On pass: through to user approval.

The expected outcome is that future iter-loops do not start on unfounded spec assertions. The cost of the agent is one extra step per brainstorm session; the cost of the failure mode it prevents is calibrated against 2026-05-11, where a half-day was lost and four iter dispatches discarded.

Architecture

A new agent file at skills/brainstorm/agents/ailang-grounding-check.md, read-only (tools: Read, Glob, Grep, Bash). The agent is dispatched internally by skills/brainstorm/SKILL.md in a new Step 7.5; it is not standalone-callable in normal flow (Boss MAY dispatch it ad-hoc for retro reviews, but no skill other than brainstorm is wired to invoke it).

The pipeline becomes:

Step 6   — write the spec
Step 7   — linguistic self-review (existing)
Step 7.5 — Grounding-Check Agent (NEW; hard-gate, Boss-overridable)
Step 8   — user-approval gate (existing)
Step 9   — hand off to planner (existing)

On agent BLOCK: brainstorm deletes the spec file, appends a depends on: entry to docs/roadmap.md, and terminates the session. On agent PASS or on BLOCK + Boss override (free chat act): brainstorm proceeds to Step 8 unchanged.

Fresh-context discipline is the central design choice. The brainstorm-driven orchestrator has spent 30+ minutes building the spec and is biased toward shipping it; the agent has no such bias. This mirrors how ailang-architect reviews DESIGN.md drift at milestone close without loyalty to the implementation that produced the drift.

The agent does NOT run on its own spec (the spec you are reading). Bootstrap: the first real run is on the re-brainstormed Spec-23 (see "Application to in-flight Spec-23" below).

Components

What	Where	Action
Agent definition	skills/brainstorm/agents/ailang-grounding-check.md	Create
Skill body	skills/brainstorm/SKILL.md	Modify — insert Step 7.5, document failure-mode procedure
Skill roster	skills/README.md	Modify — extend the agent-roster table
Agent discovery	.claude/agents/brainstorm → skills/brainstorm/agents	Create symlink
Roadmap shape	docs/roadmap.md	Documentation note — depends on: line type stays; no schema change
In-flight Spec-23	docs/specs/2026-05-10-23-eq-ord-prelude.md	Delete (after the agent ships)
Re-brainstormed Spec-23	docs/specs/YYYY-MM-DD-23-eq-ord-prelude.md	Created by the first real run of the new pipeline

The agent file follows the standard agent template described in skills/README.md ("Agent structure"): frontmatter (name, description, tools), spirit-letter lead-in, role purpose, standing reading list, carrier contract, Iron Law, the Process, status protocol, output format, common rationalisations, red flags.

Data flow

Carrier from brainstorm to the agent (Step 7.5 dispatch):

Field	Content
spec_path	path to the just-drafted spec
iteration_scope	which sections of the spec are in scope for the imminent first iteration (so the agent prioritises load-bearing assumptions over speculative future-iter content)

The agent then:

1. Reads spec_path with no prior context from the brainstorm chat.
2. Reads the standing reading list (CLAUDE.md, DESIGN.md, latest journals, skills/README.md).
3. Extracts assumptions. Heuristic: an assumption is any spec assertion that the compiler, checker, codegen, or schema currently does X. The agent flags both explicit ("the typeclass-elaboration in 22b.3 inserts ...") and implicit ones (e.g. a spec section that proposes adding to a table without saying the table's existing entries cover the new shape).
4. For each assumption, searches the codebase for a green test that ratifies it. Search is free-form: grep on test bodies, cargo test --list, reading fixture files. The agent makes a judgement call about what "ratifies" means.
5. Emits a report (see "Output format" below). Aggregate-status is PASS (all assumptions ratified) or BLOCK (at least one unratified).

Boss interpretation:

Agent status	brainstorm behaviour
PASS	Proceed to Step 8. Report goes into the brainstorm chat for the record.
BLOCK	Present the report to the user. User either: (a) accepts discard → brainstorm deletes the spec, appends roadmap entry, terminates; or (b) overrides in free chat ("Test <path>::<name> ratifies that") → brainstorm logs the override note and proceeds to Step 8.
Infra error (cargo test --list fails, spec file missing, etc.)	brainstorm aborts; Boss debugs out-of-band.

Output format

The agent's report is plain-text, ≤500 tokens, hybrid layout:

GROUNDING-CHECK REPORT
Status: PASS|BLOCK
Spec: <path>
Iteration scope: <verbatim from carrier>

Ratified assumptions:
| # | Assumption | Test path | Test name |
| 1 | <one-line summary> | crates/.../foo.rs | test_bar_baz |
| 2 | <one-line summary> | examples/qux.ail.json | (fixture: build+run green) |
...

Unratified assumptions:
- Assumption: <verbatim or close paraphrase from spec, with section/line ref>
  Searched: <queries / files / test-name patterns checked>
  Why no ratification: <one paragraph — what's missing, where the
                       gap is, what shape a ratifying test would
                       have>

(Repeat the unratified block per assumption.)

Ratified entries are scannable; unratified entries carry the information the Boss needs to decide whether to override.

Error handling

Failure	Agent action	brainstorm action
No assumptions extracted (spec is trivial / pure rename / cosmetic)	Report empty ratified list, PASS with a note	brainstorm proceeds; the note is logged in the chat
Cannot read spec file	Status INFRA_ERROR, raw path	brainstorm aborts; Boss investigates
cargo test --list or cargo invocation fails (build broken in workspace)	Status INFRA_ERROR, raw stderr	brainstorm aborts; the spec is held — fix the workspace first
Ambiguous assumption (cannot decide whether it's a load-bearing claim)	Include in unratified block with note "ambiguous: judgement call deferred to Boss"	Treated as BLOCK by default; Boss overrides if the ambiguity is benign
Re-running the agent on the same spec	Allowed; idempotent (agent has no state)	Boss may re-dispatch after a clarifying spec edit; no special handling

The agent is read-only. No file writes, no test runs (cargo test --list only enumerates). Compile errors in the workspace are treated as infra, not as agent results.

Application to in-flight Spec-23

Spec docs/specs/2026-05-10-23-eq-ord-prelude.md is currently mid-flight (iters 23.1-23.3 shipped, 23.4 BLOCKED). Iter 23.1-23.3 are kept (they shipped working code). The spec itself is deleted once the new agent exists. A new spec for the remaining Eq/Ord prelude scope (free fns + the polymorphic mono-extension surfaced on 2026-05-11) is re-brainstormed from scratch and is the first real run of the new Step 7.5.

The bootstrap irony: the spec you are reading does NOT run through the new agent (the agent does not exist yet). The first real check happens on the re-brainstormed Spec-23, not on this spec.

Testing strategy

The agent is prompt-driven and read-only; it has no Rust unit tests. The validation strategy has three layers:

1. First real run is the re-brainstormed Spec-23. The agent must catch the assumption that polymorphic free fns are mono-specialised in the same way as class methods (the failure mode of 2026-05-11). If it catches that, the agent is doing its job; if it misses it, the prompt iterates.

2. Dry-run on past specs is optional but useful for prompt tuning. The agent can be invoked manually on docs/specs/0001-skill-system.md and other past specs to surface false-positive and false-negative rates before relying on it in the live pipeline. Not a hard acceptance criterion.

3. Long-term feedback loop. Future per-iter journals are the real testbed. If a spec passes the agent and an iter BLOCKS anyway on an unanticipated prerequisite, the journal entry surfaces it and the agent prompt is revised. Failure modes are captured in feedback_spec_over_plan_patches.md-style memory entries.

There is no formal "test suite" for the agent. The discipline is: when the agent misses a real assumption, that miss is treated as a prompt-defect to fix, not as an acceptable false negative.

Acceptance criteria

The iteration that implements this spec is complete when:

1. skills/brainstorm/agents/ailang-grounding-check.md exists, follows the standard agent template, and has been committed.
2. skills/brainstorm/SKILL.md has a new Step 7.5 documenting the dispatch + Boss-interpretation flow, AND a failure-mode procedure (delete spec, append roadmap entry, terminate) for the no-override BLOCK path.
3. skills/README.md skill table and agent roster reflect the new agent.
4. .claude/agents/brainstorm symlink exists and resolves to skills/brainstorm/agents.
5. docs/specs/2026-05-10-23-eq-ord-prelude.md is removed and a roadmap entry exists pointing forward to the re-brainstormed replacement (the re-brainstorm itself is a separate session and NOT part of this iteration's acceptance — only the deletion + roadmap pointer is).
6. A docs/journals/2026-05-11-iter-<id>.md records the iteration and is linked from docs/journals/INDEX.md.

The acceptance criteria deliberately exclude "the agent has been run successfully on a real spec." The first real run is the re-brainstormed Spec-23, in a separate brainstorm session, after this spec ships. Conflating the two is the same trap that broke Spec-23 in the first place: shipping infrastructure and the test case for that infrastructure as one undifferentiated batch.

Out of scope

• A test-naming convention or ratification-marker syntax. Today's free-form grep + judgement search is the agreed mechanism; no test annotation is introduced.
• A separate examples/grounding/ ratification corpus. Same rationale.
• A retroactive grounding-check pass over all existing specs (2026-05-09-skill-system.md, etc.). Only Spec-23 is touched, and not via this iteration — via a separate re-brainstorm afterwards.
• A "discarded drafts" archive (docs/specs/discarded/). Discarded drafts are deleted; the roadmap entry is the only persistent trace.
• An override-documentation mechanism (Pre-flight Ratifications section in the spec format). Overrides stay as free chat acts; the brainstorm chat history is the only record.

These exclusions are explicit so future agents do not re-derive them.