AILang/docs/journals/2026-05-11-iter-gc.1.md

iter gc.1 — Grounding-Check Agent, brainstorm Step 7.5 hard-gate

Date: 2026-05-11 Branch: iter/gc.1 Status: DONE Tasks completed: 5 of 5

Summary

This iter ships ailang-grounding-check, a read-only spec reviewer dispatched between brainstorm Step 7 (self-review) and Step 8 (user-approval). The agent reads a freshly-written spec with no sunk-cost bias, extracts the spec's load-bearing assumptions about current compiler / checker / codegen / schema behaviour, and for each one searches the workspace for a currently-green test that ratifies it. PASS or BLOCK; no PARTIAL credit. The output is the hybrid format the agent template prescribes: a ratified-assumptions table for fast Boss scanning plus a per-assumption prose block for the unratified set.

Wiring is markdown-only. skills/brainstorm/SKILL.md gets a new Step 7.5 hard-gate section, two new Handoff-Contract rows (brainstorm → grounding-check, brainstorm → roadmap on no-override BLOCK), and a Cross-references rewrite that splits the old "No private agents" bullet into "Private agent" (the new grounding-check dispatch) plus "Ad-hoc dispatch" (the existing plan-recon opt-in). skills/README.md gets one new agent-roster row and one new symlink-discovery line. .claude/agents/brainstorm is the matching symlink. Spec-23 (Eq/Ord prelude) is retired because the session that produced gc.1's spec is the same session that discovered Spec-23's polymorphic-free-fn-monomorphisation assumption was unratified — a fact gc.1's whole machinery exists to catch from now on. The roadmap P1 Post-22 Prelude entry is amended to record the retirement, name the unratified mechanism, and point forward to the re-brainstorm.

The bootstrap irony stands: the spec for ailang-grounding-check did not itself run through ailang-grounding-check. The agent did not exist when its own spec was written, so per Spec §Architecture's bootstrap-exclusion the gc.1 plan was implemented without the gating mechanism it introduces. The first real run of the new pipeline is the re-brainstormed Spec-23 in a separate session, not this iter.

Per-task subjects

• iter gc.1.1: agent — ailang-grounding-check definition
• iter gc.1.2: brainstorm SKILL — insert Step 7.5 (grounding-check hard-gate)
• iter gc.1.3: skills README — roster + symlink for ailang-grounding-check
• iter gc.1.4: symlink .claude/agents/brainstorm -> skills/brainstorm/agents
• iter gc.1.5: retire Spec-23, roadmap forward-pointer to re-brainstorm

Concerns

• Plan §Step 2.4 and §F.2 expect grep -c "^### Step " == 9 after the 7.5 splice, but the brainstorm SKILL has nine original step headings (Step 1 through Step 9), so adding 7.5 lands at 10. The plan's parenthetical comment in §F.2 enumerates ten labels (1, 2, 3, 4, 5, 6, 7, 7.5, 8, 9) while asserting wc -l = 9 — internally inconsistent. Substantive intent (Step 7.5 between 7 and 8, leave Step 9 in place) is unambiguous and honored; the off-by-one is a plan-template miscount, not an implementation bug. Surfaced as a cadence-flow signal to the Boss in the end-report.

Cadence-flow notes (for skillsystem postmortem)

Two observations from the orchestrator's end-report, surfaced here for the Boss's future skillsystem-postmortem entry — NOT in scope for gc.1 itself:

1. Planner verify-step counts derived from offsets become stale at plan-freeze time. The §Step 2.4 and §F.2 miscount above is one instance. The orchestrator suggested two fixes: (a) planner re-runs grep counts against the current file state at plan-freeze time, or (b) planner expresses such counts as ≥ N inequalities rather than exact-match equalities. The latter is cheaper and survives subsequent edits to the same file.

2. Markdown-only verbatim-content iters bottom out cleanly in the spec-check + quality-check phases. Zero review-loop fixups landed this iter; all five tasks went DONE on first pass through both phases. The spec-check phase effectively reduced to "is the verbatim text from the plan in the diff?" and the quality-check phase had little to flag beyond whitespace hygiene. Both passes still ran (discipline preserved), but the value they added was low. This is expected for verbatim-content tasks and not a concern about the discipline itself — captured here so it is not misread, in retrospect, as evidence that the phases are too lenient.

3. First real run of grounding-check (2026-05-11 same-day, on the revised Spec-23): PASS, 15 assumptions ratified. The agent's output format leaked an internal-thinking preamble before the structured GROUNDING-CHECK REPORT block — the Iron Law should be tightened to forbid any preamble before the structured report. Substantively unproblematic (the judgement and test pins were clear) but a real prompt-discipline gap.

4. Behaviour change requested for impending-BLOCK paths. On a miss (assumption with no green test), the agent should attempt to write the missing GREEN test itself — strictly test code, never src/-side app code — and only BLOCK if test creation fails. This is two changes: (a) tools — add Write (or Edit) to the agent frontmatter, today Read, Glob, Grep, Bash only; (b) discipline — Iron Law gains "you may write tests under crates/*/tests/ or #[cfg(test)] mod tests; you may NOT touch any file outside test scope." The first real PASS run did not exercise this path, so the constraint surfaces here as a future tightening rather than as a tested behaviour.

Known debt

None.

Blocked detail

N/A — DONE.

Commits

606a2eb..HEAD (5 task commits, no review-loop fixups).

Stats

bench/orchestrator-stats/2026-05-11-iter-gc.1.json