A new utility skill that grades a finished session on three axes —
cost & efficiency, toolchain health, agent effectiveness — from the
session's own Claude Code flight recorder (the JSONL transcript plus
one sidechain log per dispatched subagent).
The heavy lifting lives in scripts/postmortem.py, a stdlib-only,
read-only aggregator. It handles the two accounting traps the raw log
sets: usage is repeated per streamed assistant line under a shared
requestId (deduped max-per-field, then summed across requests), and
the transcript carries no costUSD/durationMs (both null) — so cost is
derived from tokens x an overridable list-price table and labelled an
estimate, wall-clock from timestamp deltas. Subagent spend is billed
separately from its own usage objects and graded by terminal status.
Single-session by design: defaults to the newest transcript in the
project's log dir (flagged active if still live), or --session <id>
for a finished run. Secret files are out of bounds in both the Iron
Law and the Red Flags.
Verified end-to-end against a real 15-subagent session.
Step 3 framed `tdd` as a conditional add-on ("if the profile enables
the tdd phase, dispatch tdd") while `brainstorm` read as the default
spine. The orchestrator inherited that tilt and routed feature work to
`brainstorm` by reflex.
Replace it with an explicit Entry-path reflection run before every
feature dispatch: the two are co-equal, the choice is made per item by
the design line, and the one-line verdict is recorded in the loop. The
autonomy asymmetry (tdd proceeds, a fresh brainstorm cycle bounces
back) is reframed as a context-budget consequence, not a ranking, with
a guard against hardening it into an "im Zweifel brainstorm" reflex.
The one principled tilt now lives inside the test: genuine doubt that
one assertion can pin the behaviour is itself the design-fork signal.
Add two rationalisation rows and a red flag naming the default-to-
brainstorm bias.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The tdd skill referenced its neighbours (implement, brainstorm,
debug) but none referenced it back. Close the loop so the new
executable-spec-first entry path is reachable and consistent from
every skill that describes a relationship it now belongs to:
- implement: mini-mode trigger + dispatch example now cover a
RED-first handoff from `debug` OR `tdd` (was debug-only); the
orchestrator's task template and Phase-3 skip note generalised.
This was real drift — mini-mode is no longer debug-exclusive.
- planner: skip rule gains the `tdd` case (it skips brainstorm
AND planner — the RED executable-spec is the plan).
- brainstorm: `tdd` added to the permitted-skip list as the
profile-gated alternative entry path, plus a cross-ref marking
brainstorm as the bounce-back target when behaviour stops being
test-specifiable.
- boss: pipeline diagram, Step-3 routing prose, and cross-refs.
A test-specifiable feature issue is dispatched to `tdd`
autonomously, the same way a bug issue goes to `debug`; this is
NOT a new-cycle bounce-back (the test is the spec). The
bounce-back fires only reactively, when tdd surfaces a genuine
design fork.
- debug: reciprocal sibling note + cross-ref (new behaviour is
tdd's job; debug is for regressions of existing behaviour).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rule 2 (validated-or-flagged) now suggests dropping in a fenced code
snippet where it sharpens the point — the input that triggers the
failure or the call as it should behave — preferred over a prose
paraphrase.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A new opt-in alternative to the brainstorm -> planner design entry,
for work whose desired behaviour is test-specifiable. Instead of a
prose spec the user approves, `tdd` produces one minimal RED
executable-spec ("how it should work") and treats it like a bug to
be fixed: the GREEN side hands off to `implement` mini-mode, the
same two-stage RED-first handoff `debug` uses.
Skill + agent split mirrors debug/debugger: a thin SKILL.md owns
trigger, dispatch, the orchestrator-side loop, and handoff; the
agent (tdd-author) carries the authoring discipline. The agent
guards two failure modes specifically — guessing a design into a
test (a genuine design fork bounces back to `brainstorm` rather
than ratifying an un-chosen design), and pushing harder on a
headline test that won't go green (one iteration that can't reach
GREEN triggers a reactive decompose into a ladder of BLOCKER
sub-tests; two failed rounds bounce to `brainstorm`).
The boundary is the design line: `tdd` owns the work iff one honest
minimal assertion pins it; otherwise `brainstorm` reclaims it. This
is distinct from the per-task TDD the implementer already practices
inside `implement` — `tdd` authors the one headline spec above it.
Wires the phase into the docs it references:
- docs/profile-schema.md: opt-in `tdd` pipeline slot
- README.md: skill table row
- docs/pipeline.md: entry-path in the graph, phase description, skip rule
- templates/project-profile.yml: commented-out slot
install.sh picks up tdd/ automatically (top-level dir with SKILL.md).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Align the design_ledger profile-slot default and its illustrative
references with the docs/ layout used by the other path slots.
Historical specs/plans are left untouched as cycle records.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Cycle-close tidy for the glossary-skill cycle (59c2f4b..4fd5408).
Architect drift review (sole gate — repo ships no
.claude/dev-cycle-profile.yml, so commands.regression is empty and the
regression step is a documented no-op):
- [medium] FIXED. docs/agent-template.md said the Iron Law is rendered
'as a numbered list' (the schematic placeholder at l.37 and the prose
at the § Iron Law section), but all 13 existing agents render it as a
code-fenced block of short imperative lines — and the cycle's new
glossary-extractor.md correctly followed that universal convention. So
the drift was the template wording, stale relative to every one of its
instances, not the new file. Resolution: align the template to reality
(both spots now say 'a code-fenced block of short imperative lines').
The new agent file was carry-on — 'fixing' it to a numbered list would
have made it the lone deviant among 14 agents, i.e. introducing drift,
not removing it.
- [low] CARRY-ON. README now classes issue/glossary as 'utility skills'
but that taxonomy is not mirrored in issue/SKILL.md's or
glossary/SKILL.md's own frontmatter. Accepted as low-severity: the
invocation-class label is a README-level descriptor; mandating every
skill self-declare its class in frontmatter is gold-plating with no
consumer. Revisit only if a tool starts keying off a per-skill class.
What holds: single-sourcing preserved (the new skill cites
glossary-convention.md and restates no rule; paths.glossary semantics
defer to profile-schema.md); authority consistent across the boss
sentence, the convention, and the skill's Authority section; the
utility-vs-phase distinction held (no claim that glossary is a pipeline
phase); glossary-extractor.md conforms to agent-template.md.
Cycle is drift-clean. Not a milestone close (no milestone fieldtest run;
see docs/pipeline.md § Milestone-close gate).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Gives the plugin an executable procedure over a project's glossary,
closing the two gaps the glossary-convention infrastructure left open:
no on-ramp to build a glossary for an existing project, and no
conformance check around hand-maintenance.
New `glossary` utility skill (invoked on demand like `issue`, not a
pipeline phase) with a mode dispatch:
- maintain: guided add / change / remove of one entry under a local
conformance check (three-field shape, <=2-sentence definition,
collision scan against existing entries) plus a stale-usage sweep on
change/rename. A non-conforming entry is rejected with the named rule,
not written. The sweep reports drift; it does not block (guidance, not
enforcement).
- bootstrap (user-only): fans out one read-only glossary-extractor agent
per prose slice, merges and clusters their observed variants, auto-
includes clear winners, surfaces contested clusters to the user for the
canonical choice, and leaves unresolved clusters out (never coined).
New `glossary-extractor` agent (read-only, template-conforming): sweeps
one prose slice, reports recurring concept terms + competing variants
with frequencies and locations, coins nothing.
Single-sourcing held throughout: the skill applies the rules in
docs/glossary-convention.md and restates none of them. Authority is
unchanged — maintain keeps the user-any-time / boss-record-reality rule;
bootstrap is user-only, with boss allowed to recommend it via bounce-back
(one wired sentence in boss/SKILL.md). docs/glossary-convention.md gains
a one-line tooling pointer to the skill; README.md lists `glossary` and
`issue` as utility skills and drops the stale 'Eight skills' count the
fresh-context grounding-check flagged (it had silently omitted `issue`).
install.sh links the new skill + agent with no installer change (its glob
covers any top-level dir with a SKILL.md + agents/ subdir; verified).
Docs/prose-only repo, no test runner: all 13 grep presence-gates green
against verified zero baselines; final sweep ALL_PRESENT, install.sh
still parses (bash -n). Implements
docs/specs/2026-05-31-glossary-skill-design.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Task-by-task plan for the glossary-skill spec. Two create tasks
(glossary/SKILL.md mode-dispatch utility skill, glossary/agents/
glossary-extractor.md read-only per-slice prose extractor) carrying full
verbatim file bodies, plus three single-sentence wiring edits
(boss/SKILL.md bootstrap bounce-back, docs/glossary-convention.md tooling
pointer, README.md utility-skill listing + count-free framing) and a
final sweep.
Docs/prose-only repo, no test runner: every task closes on a grep
presence-assertion against the touched file. All edit-task gates use
single-token patterns or code-fence lines calibrated against verified
zero baselines (bootstrap/glossary/SKILL.md path / glossary all 0 today),
sidestepping the line-wrap pitfall recorded at c7a56c2.
Implements docs/specs/2026-05-31-glossary-skill-design.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Adds a new utility skill `glossary` (invoked on demand like `issue`,
not a pipeline phase) carrying two procedures over a project's glossary:
- maintain: guided add / change / remove of one entry with a local
conformance check (three-field shape, <=2-sentence definition,
collision scan against existing entries) plus a stale-usage sweep on
change/rename. A non-conforming entry is rejected with the named rule,
not written.
- bootstrap (user-only): a fan-out of read-only glossary-extractor
agents over the project's prose surface, merged and clustered into
conforming entries; clear winners auto-included, contested clusters
surfaced to the user, unresolved clusters left out (never coined).
Single-sources against docs/glossary-convention.md (the skill executes
the rules, restates none). Authority unchanged: maintain keeps the
existing user-any-time / boss-record-reality rule; bootstrap is
user-only with boss allowed to recommend it via bounce-back.
Grounding-check PASS (9/9 assumptions ratified against live repo bytes;
parse-gate a documented no-op, no spec_validation configured). The
fresh-context pass also surfaced that README's "Eight skills" framing
is already stale (omits the existing `issue` utility skill); the spec's
README edit reconciles that rather than assuming a non-existent
agent-roster note.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Cycle-close tidy for the glossary-integration cycle (fc0e1d0..HEAD).
Architect drift review (sole gate — repo ships no
.claude/dev-cycle-profile.yml, so commands.regression is empty and the
regression step is a documented no-op):
- [medium] FIXED. docs/glossary.md Avoid-lists `release`/`epic` while
profile-schema.md § vocabulary offered the same words as example
slot renamings — opposite verdicts on the same words in two in-repo
docs, with neither stating its scope, reading as contradiction.
Resolution (per the user's steer: the glossary is the new source of
truth for nomenclature): state that authority once, where the
glossary's role is owned. glossary-convention.md now declares the
set glossary the SoT for a project's nomenclature and that its
canonical entry + Avoid list win over any colliding vocabulary
example; profile-schema.md's vocabulary note defers to it with a
pointer rather than restating the rule, keeping the single-sourcing
the architect flagged as clean. The glossary itself is unchanged —
it is the SoT and was already correct.
- [low] CARRY-ON. glossary-convention.md mandates an `**Avoid:** —`
line for synonym-free terms, but no dogfood entry in glossary.md
exercises that arm (all five terms have real synonyms). Accepted as
low-severity documented debt: the rule is unambiguous prose, and
coining a synonym-free term solely to exercise a formatting arm
would be gold-plating. Revisit if a genuinely synonym-free canonical
term enters the dogfood.
What holds: wiring semantics single-sourced at the paths.glossary row;
convention/instance split clean; boss named as the only autonomous
glossary writer; all six spec acceptance criteria landed.
Cycle is drift-clean. Not a milestone close (no milestone fieldtest
run; see docs/pipeline.md § Milestone-close gate).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Pins canonical nomenclature per project so terminology does not drift
and LLM-driven work reuses the established term instead of coining a
synonym each session. The glossary rides the existing standing-reading
mechanism — one optional path slot, no new delivery path.
Single-sourcing, to avoid cross-doc drift:
- `paths.glossary` row in profile-schema.md owns the "set => standing
reading for every role; unset => no-op" semantics; agent-template.md
and pipeline.md each carry one referencing sentence, not a restatement.
- glossary-convention.md owns the format (flat per-term blocks: canonical
heading + Avoid line + <=2-sentence definition) and the boss
record-reality-never-invent write-rule; boss/SKILL.md only points to it.
- glossary.md dogfoods the format on the plugin's own vocabulary
(cycle, milestone, iteration, drift, hard-gate).
Write authority: user any time; boss autonomously but only to record
terms already in consistent use or to settle a drift it just resolved —
never to coin. All other roles are read-only consumers.
No executable surface; this repo has no test runner, so each task closed
on a grep presence-assertion against the file it touched. All eight gates
green (T1 3>=3, T2 5, T3 2, T4 1, T5 1, T6 1, T7 2, final sweep present).
Implements docs/specs/2026-05-31-glossary-integration-design.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Task 1's Step-2 verification grepped for `record reality`, but in the
verbatim convention-doc content those two words straddle a line break
(`...**record` / `reality, never...`), so `grep -c` matched 0 lines and
the gate returned 2 against its own >= 3 expectation — a false BLOCKED on
byte-faithful content. Swap the pattern to `reality, never to invent`,
which matches the unwrapped line and yields 3. Content is unchanged; only
the proxy assertion was wrong.
Surfaced by the implement-orchestrator on first dispatch, which correctly
refused to reflow spec-dictated prose to satisfy the proxy and instead
escalated the plan defect.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Task-by-task plan for the glossary-integration spec. Seven tasks
plus a final sweep: create docs/glossary-convention.md and the
dogfooded docs/glossary.md, document the paths.glossary slot in
profile-schema.md, add the commented slot to the project-profile
template, wire one standing-reading sentence each into
agent-template.md and pipeline.md, and point boss/SKILL.md at the
convention's write-rule.
Docs-only cycle: no test runner, so each task closes on a grep
presence assertion calibrated against verified zero baselines.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Optional paths.glossary slot: when set, the file is standing reading
for every role (no separate standing_reading.always entry). Adds a
docs/glossary-convention.md single-sourcing the three-field format,
the standing-reading obligation, and the boss record-reality
write-rule; plus a dogfooded docs/glossary.md over the plugin's own
vocabulary. Guidance, not enforcement — no synonym check.
Grounding-check PASS: the one new semantic (paths.glossary auto-
promotion into standing reading) is carried as deliverable wiring,
not assumed to pre-exist.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Per-skill prose tightening from the same audit swarm; each finding
passed an adversarial second reviewer. No behavioural change.
- audit: drop garbled "Conventions require deferred audits to
compound" sentence (says the opposite of intent; the preceding
line already closes the loophole).
- brainstorm: drop forward-pointing meta-comment about the
Rationalisations table.
- debug: drop third restatement that debugger.md is the single
source for the carrier/handoff fields.
- docwriter: drop motivational opener; Overview starts at the
waste argument.
- fieldtest: fold the 2-4-examples rationale into the dispatch
sentence instead of restating the count a fourth time.
- implement: drop "known platform constraint at the time" aside.
- planner: cut the verbose anti-drift paragraph (which restated
the very table it claimed not to) down to a cross-reference.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Two consistency fixes across the skill suite, both found by a
prose-audit agent swarm.
Trivial-mechanical-edit carve-out: brainstorm and planner each
invented their own bound (≤30 LOC, single file) that contradicts
the canonical definition in the project's CLAUDE.md (which allows
a rename across N files and sets no LOC ceiling) and disagreed
with implement. Both now reference that carve-out instead of
restating a divergent shape.
Parse-block gate: brainstorm Step 7 and planner Step 5 spelled out
the parser-invocation protocol near-verbatim. Both now defer to
docs/profile-schema.md, which owns the protocol, and keep only
their skill-specific parts (target artefacts, failure semantics,
where the parse-trace goes) — matching the single-sourcing the
carrier contracts already use.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Correct the cycle vocabulary description, add the milestone container
slot, fix the minimal-profile example, and document the
milestone_fieldtest phase that gates the milestone close.
Correct the cycle comment (a cycle is a pipeline round, not the
top-level container); add the milestone tracker-container slot and a
commented milestone_fieldtest phase that gates the milestone close.
Reword the green-exit row, annotate the carry-on commit body, and add a
red flag: an audit-clean never licenses closing a milestone — that needs
a green milestone fieldtest (gate in pipeline.md).
Authoritative carrier contract for the milestone fieldtest: scoped to
milestone_promise, scenarios derived top-down rather than as a union of
per-cycle axes.
Define the cycle/milestone distinction and the complete-and-functional
close gate once in pipeline.md; rename audit's cycle-close edge to
drift-clean so it no longer reads as a milestone close.
Nine bite-sized tasks across eight files; pipeline.md as the single
source, fieldtester.md for the milestone carrier, then the referencing
skills and the vocabulary/profile layer, closing with a cross-file
verification sweep.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Separate `cycle` (a pipeline-graph round) from `milestone` (a
Gitea tracker container that closes only when complete AND
functional). `audit` proves drift-clean, never functional, so no
audit signal — and no `/boss` done-state — may close a milestone.
Introduces a milestone-close gate (complete ∧ functional) defined
once in docs/pipeline.md, and a milestone-wide fieldtest as a
carrier-scope variant of the existing fieldtest skill. The
milestone fieldtest runs curated end-to-end scenarios derived
top-down from the milestone's promise — proving the shipped
implementation delivers what the milestone as a whole promised,
not a mechanical union of per-cycle axes. The actual tracker
close stays a manual act; this spec only defines when a milestone
is closeable.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A field test that runs a stale pre-built binary inverts its own
purpose — it reports the previously-shipped state as current, producing
false positives on already-fixed bugs and masking newly-introduced
ones. This bit an AILang raw-buf field test: the agent ran a
target/release binary built before a fix landed, reported a fixed bug as
still-broken, and masked a real check-clean/build-crash defect until
orchestrator re-verification against a fresh build.
Phase 2 now opens with a mandatory build-from-HEAD step (run
commands.build, or invoke the tool through the build system rather than
a path to a pre-existing artefact; build the release profile if the
examples invoke a release binary), and the agent records which build the
run exercised.
Unifies four issue-writing rules — impersonal voice, every claim
validated-with-evidence or flagged as a claim, imperative concise
title (checkboxes allowed for sub-points), and self-containment
(every reference directly resolvable, no unresolvable tags) — and
records the tea-CLI mechanics for create/edit/comment/close.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Apply the debug-skill pattern (commits 6410732..de42974) to the
remaining skills: the agent file is the single source for each
interface field's semantics; the SKILL.md copy is reduced to field
names plus a pointer, marking the agent's contract table
authoritative. Because SKILL.md loads into orchestrator context and
agents/*.md into the subagent's fresh system prompt with no
transclusion, duplicated field tables drift apart over time.
- brainstorm: carrier (spec_path/iteration_scope) -> grounding-check;
the absolute-path requirement now lives only in the agent.
- planner: carrier (spec_path/iteration_scope/focus_hint) ->
plan-recon, including the mandatory/optional markers and the
BLOCKED-on-missing rule SKILL.md had omitted.
- fieldtest: carrier + produced fields -> fieldtester; the skill-level
`status` roll-up (clean/friction_found/bugs_found/infra_blocked),
which is not part of the agent's run-status protocol, stays defined
in SKILL.md only.
- docwriter: carrier + produced fields -> docwriter agent.
- implement: carrier (iter_id scratch-dir/stats/not-a-branch
semantics) -> implement-orchestrator; per-task sub-status vocabulary
moved into the orchestrator-agent (it runs the loop in a fresh
context and could not read SKILL.md at runtime, yet referenced "the
sub-status table" by name); task_text_path single-sourced in
implementer with spec-reviewer cross-referencing.
audit was already the reference implementation (pointers, no restated
contracts) and is unchanged.
closes#2
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The carrier (symptom/repro_known/recent_iter) and handoff
(red_test_path/cause_summary/constraint) field definitions were
tabled in full in both SKILL.md and debugger.md — the exact
duplication that let the `constraint` wording drift earlier.
Since the debugger agent runs in a fresh context, it must carry
both contracts inline regardless; that makes debugger.md the
natural single source. Mark its Carrier-contract and Output-format
tables authoritative, fold in the richer field descriptions that
only SKILL.md had, and reduce SKILL.md to naming the fields plus a
pointer — no field semantics restated. Drift-prone prose now lives
in exactly one place. Consistent with SKILL.md's own stated split
(debugger.md = source of truth; skill = trigger/dispatch/handoff).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The `constraint` handoff field was worded two ways: SKILL.md
omitted the "no opportunistic refactor" clause that debugger.md
carried. Same contract, two strings — exactly the interface drift
the two-file split risks. Align SKILL.md to the fuller wording.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Phase 3 previously said only "smallest possible reproducer" — a
passive property an agent can satisfy by name while still asserting
against the full reproducing fixture. Sharpen it into an explicit
two-step discipline: minimize the trigger (delta-reduce until one
more cut makes the symptom vanish) and make the fixture autonomous
(inline input, no shared fixtures/DB seeds/clocks/server boots
unless the bug is genuinely at that integration boundary).
- Iron Law gains: an un-minimized repro is not a RED test
- Phase 3 rewritten with explicit Minimize + Autonomous steps
- 3 rationalization rows + 4 red flags for the "full fixture
reproduces deterministically, ship it" failure mode
- SKILL.md overview/handoff mirrored at orchestrator altitude
Baseline (writing-skills RED-first): 6 subagent runs showed the old
wording usually steered right but relied on agent instinct; GREEN:
2 runs under the targeted full-fixture pressure now reduce to the
minimal trigger and cite the contract verbatim.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The nested-subagent-dispatch constraint is unchanged in Opus 4.8.
Workflows added a top-level fan-out mechanism alongside it, but a
workflow's spawned agents still cannot spawn further agents. Record
this in both the design rationale and the README capability list so a
future reader does not read the plugin as unaware of Workflows.
Documents that profile slots are versioned with the plugin, not the
project: optional slots degrade to documented no-ops when absent, so
an out-of-date profile silently skips the gates a new slot powers.
Tells maintainers to skim the template's commented blocks and the
schema after a plugin update, and gives a concrete retrofit recipe
for `spec_validation` (the slot the compound-hallucination hardening
added) and the three gates it powers.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Brings the spec_validation profile slot and the five defense-in-depth
fixes onto main: brainstorm + planner parse gates, grounding-check
code-block pass, plan-recon content-pin blast radius, and the
aspirational-source marker convention.
closes#1
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Documents a recommended (not plugin-enforced) frontmatter marker for
files under `design_models` / RFCs / proposals:
`status: aspirational` + `validated-against: <sha|"no validation">`,
plus a recommendation that the design ledger distinguish model rows
from contract rows mechanically.
Wires the brainstorm skill to consume the signal: Step 1 notes the
marker when reading model files, Step 4 flags code lifted from an
aspirational source as the spec's most suspect bytes that must clear
the Step-7 parse gate. This is the upstream signal whose downstream
catch is the Fix-1 parse-every-block gate. Adds a Common
Rationalisation and a Red Flag. Missing marker -> signal absent,
graceful degradation, never a hard fail.
Closes the issue #1 hardening set (P0 + Fixes 1-5).
refs #1
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
plan-recon already had a Non-compile-checked sweep, but it was gated
behind signature/variant/removal scopes (omittable otherwise). The
raw-buf.2 failure was a module addition that shifted a workspace-listing
hash pinned in two test files — no signature change — so the sweep was
legitimately skipped and the twin pin was missed.
Adds "Content-pin-perturbing scopes" to Step 5: when the iteration
shifts a content-addressed/hashed/snapshot value a test pins, the
Non-compile-checked sweep is MANDATORY and must enumerate EVERY test
file that grep-matches the perturbed constant — not just the first.
Updates the omission clause accordingly, leans on the CLAUDE.md
lockstep-invariant pairs (no new profile slot), and adds a Common
Rationalisation plus two Red Flags. Embedded in the agent's own file
so the discipline does not depend on orchestrator memory.
refs #1
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Adds a third pass to the grounding-check agent: when the profile
declares `spec_validation.parsers`, every fenced spec block whose
fence label has an entry is run through its parser (temp file + `ext`,
`cmd` with {file}); a non-zero exit marks the block unparseable and
the aggregate status becomes BLOCK. Complementary to the existing
test-ratification search (checks the spec's own bytes, not codebase
behaviour) and independent of the orchestrator's Step-7 gate (Fix 1) —
a fresh-context second line of the same defense.
Amends the Iron Law to permit per-block parser runs (same read-only
spirit as test-list/type-check), adds an "Unparseable code blocks"
report section, a Common Rationalisation, a Red Flag, and the agent
description.
refs #1
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Adds self-review check #9 to planner Step 5, symmetric to Fix 1: when
the profile declares `spec_validation.parsers`, every verbatim code
body the plan inlines into a task step whose fence label has an entry
must parse clean against the live tool before hand-off. Non-zero exit
is a plan failure — the last defensive line before implementer
dispatch. Trace goes into the planner session.
Targets the surface-language snippets the plan lifts verbatim from the
spec (the compound-hallucination bytes); source-language test/impl
bodies are out of scope — the implement compile gate catches those.
Also adds a Common Rationalisation ("came straight from the spec") and
a Red Flag (configured parser, no trace in session).
refs #1
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Adds self-review check #6 to brainstorm Step 7: when the profile
declares `spec_validation.parsers`, every fenced spec block whose
fence label has an entry is written to a temp file (entry `ext`) and
run through the entry `cmd` ({file} substituted); non-zero exit is a
self-review failure that must be fixed before the spec proceeds. The
parse-trace goes into the brainstorm chat as the attestation the gate
fired. Labels with no entry are skipped-and-documented; a malformed
entry surfaces as a profile error; no `spec_validation` -> no-op.
Placed in Step 7 (not Step 4 as the issue's prose suggested) because
the spec file — and thus its code blocks — exists only after Step 6;
Step 7 also already re-runs on post-PASS edits, so a changed block
re-triggers the gate for free.
Also adds a Common Rationalisation ("it obviously parses") and a Red
Flag (configured parser, no trace in chat).
refs #1
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Defines an optional top-level `spec_validation` profile section: a
registry mapping each markdown fence label to the tool that validates
a spec code block of that kind (`ext` + `cmd`, with a `{file}`
placeholder; exit 0 = clean parse, non-zero = BLOCK). Labels without an
entry are skipped-and-documented; a malformed entry fails closed.
This is P0 of issue #1 — the shared prerequisite for the brainstorm
Step-4 parse gate (Fix 1) and the grounding-check code-block pass
(Fix 2). Contract only; no consumer reads the slot yet.
refs #1
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Three minor-issues + three optional follow-ups identified by
the three parallel reviewers of debug/docwriter/audit,
fieldtest/planner/brainstorm, and implement. None blocking;
all close calibrated gaps the bulk migration left.
Minor-issues:
- audit/SKILL.md: handoff field `regression_results` now
explicitly carries "raw output verbatim (no rounding, no
summarisation)" — restores the verbatim-numbers emphasis
the original `bench_numbers` field name implied.
- audit/agents/bencher.md: hypothesis examples grouped by
axis (Tail-latency / Count reduction / Scalability /
Overhead vs floor) with concrete numerical anchors (2× of
median, ≥80%, 10-million-element, ±15%). Subjects stay
domain-neutral but the calibrated bite returns. The
preamble enumerates plausible subjects (allocators, query
plans, request handlers, parsing strategies, codecs,
caches) so the reader has concrete domains to anchor on.
- implement/agents/implementer.md: "Architecture rules"
section gains a 5-bullet kind-list (determinism contracts;
backend / FFI constraints; schema versions; memory /
resource models; effect / capability discipline) so the
implementer has scaffolding to look for even when the
project's CLAUDE.md is sparse. The "BLOCKED on
contradiction" mechanism stays the load-bearing rule.
Optional follow-ups:
- brainstorm/SKILL.md Step 7.5: failure-mode procedure
restores the structured backlog-issue fields (Title /
Label / Body with `depends on:` and `context:` lines)
and the milestone-container option for big deferred work
(Gitea milestones, GitHub milestones, Linear projects).
- templates/CLAUDE.md.fragment: adds an optional
"Lockstep-invariant pairs" section so projects that have
cross-file pairings can declare them in a way the
architect agent and plan-recon agent already know to
consult. Projects without such pairings omit the section;
both agents handle absence gracefully.
No discipline regressions; no Iron Law / Common Rationalisations
/ Red Flags edits. Pure scaffold-and-anchor improvements.
Seventh skill via the boss pattern. brainstorm is the
spec-generation hard-gate; grounding-check is its Step-7.5
read-only assumption-ratification reviewer.
Vocabulary substitutions:
- AILang → "this project"
- milestone → cycle
- Boss → orchestrator
- ailang-grounding-check → grounding-check
- "the AILang program" / ".ail Form-A" → "the user-facing
program in the project's canonical authoring/consumer form"
- "Brummel (orchestrator) + Claude" → "orchestrator + Claude"
AILang-specific bits dropped or generalized:
- `docs/specs/<milestone>.md` / `docs/plans/` → `paths.spec_dir`
/ `paths.plan_dir`
- AILang feature-acceptance criterion's three specific clauses
(LLM-author-reaches-for-it, measurable correctness/redundancy
improvement, no-reintroduction-of-core-constraint-bug) →
"the criterion declared in the project's CLAUDE.md", with the
three typical-shape clauses retained as illustrative
- `design/contracts/0004-feature-acceptance.md` cross-ref →
pointer to project CLAUDE.md
- "AILang's own thesis is structured concrete form over prose
description" → "concrete code first, prose second" (the
discipline survives without the project-thesis hook)
- The 2026-05-11 incident date → generic "recurring failure
mode" framing (the discipline survives without the date)
- `tea issues create --repo Brummel/AILang` → "the project's
issue-tracker create command (typically tea/gh)" with both
examples shown
- `cargo test --list -p <crate>` / `cargo check` → "the
project's test-list / type-check command" with Rust example
- `crates/*/tests/`, `crates/*/src/**/tests.rs`, `examples/`
→ derived from `paths.code_roots` and the project's examples
/ fixtures convention
- The `Spec-23 / prelude free-fn ne / typeclass elaboration`
worked example → generic "spec section that proposes
adding to a table or extending a pass without stating that
the existing entries / passes cover the new shape"
- AILang skill-system index reference (`skills/README.md`)
→ `../../README.md` (plugin's top-level)
- "Form-A / .ail / monomorphised compare__T symbol" examples
→ generic "function names, type names, schema fields, pass
names" example
Universal substance preserved verbatim:
- The hard-gate (3 lines) — NO IMPLEMENTATION UNTIL SPEC
APPROVED
- Nine-step process (explore context → clarify Q&A →
propose 2-3 approaches → apply feature-acceptance → present
in sections → write spec → self-review → grounding-check →
user-review-gate → hand off)
- "Concrete code first, prose second" discipline
(the universally-applicable form of what was the
AILang-thesis hook)
- "The criterion is unjudgeable without concrete code" rule
(universal good practice; project's CLAUDE.md picks the
specific criterion)
- Spec structure (Goal / Architecture / Concrete code shapes
/ Components / Data flow / Error handling / Testing strategy
/ Acceptance criteria)
- Step-7 self-review checklist (5 items)
- Step-7.5 grounding-check dispatch + PASS/BLOCK/INFRA_ERROR
three-way classification + failure-mode procedure + re-
dispatch on post-PASS edit rule
- All 8 Common Rationalisations rows
- All 9 Red Flags bullets
- grounding-check's six-step process incl. assumption
extraction, search design, ratification classification,
aggregate status computation
- grounding-check's Iron Law (5 lines), output format (exact
layout preserved), 6 Common Rationalisations rows, 8 Red
Flags bullets
The brainstorm is the largest skill in the migration (366 →
355 lines after substitutions). Calibrated discipline kept
intact per memory feedback_dont_strip_repeated_discipline.md:
"concrete code first" + grounding-check hard-gate + "re-
dispatch on post-PASS edit" are the load-bearing rules; all
survive verbatim except for project-specific identifiers.
Sixth skill via the boss pattern. planner is the spec→executable-
plan transformation; plan-recon is its read-only file-mapper.
Vocabulary substitutions:
- AILang → "this project"
- milestone → cycle
- Boss → orchestrator
- ailang-plan-recon → plan-recon
- "the architect's Lockstep invariants table" → "the project's
CLAUDE.md lockstep-invariant pairs" (the lockstep pairs are
project-specific; the plugin only carries the pattern that
the orchestrator may declare them)
AILang-specific bits dropped or generalized:
- `docs/specs/<milestone>.md` / `docs/plans/NNNN-<iteration>.md`
→ `paths.spec_dir` / `paths.plan_dir`
- `cargo test --workspace -p <crate>` → "the project's test
command from commands.test, scoped to this test" + generic
template
- `cargo check`, `cargo expand` → "the project's type-checker
/ compiler" and "the project's macro-expansion tool" with
Rust/TypeScript examples in parentheses
- Rust code-snippet template in Step 3 → language-neutral
placeholder with `(exact source code here)` annotations
- Specific past-iter references (loop-recur.1, loop-recur.2,
loop-recur.tidy, remove-mut-var-assign.1, form_a.md,
iter-revert Concern 2, iter effect-doc-honesty Task 2, iter
loop-recur.3 Concern) → generic "recurring defect family
in this project's history" (the discipline survives; the
AILang iter codes that wouldn't parse for a plugin reader
go away)
- `error[E0061]` Rust-specific compiler error code → "hard
compile error" (universal)
Universal substance preserved verbatim:
- Iron Law (3 lines)
- Six-step process (read spec → map structure → write tasks
→ header → self-review → hand off)
- Step 5 self-review checklist — all 8 calibrated checks
(spec coverage, placeholder scan, type consistency, step
granularity, no commit steps, pin/replacement substring
contiguity, compile-gate vs deferred-caller ordering,
verification-command filter strings must resolve)
- All 6 Common Rationalisations rows
- All 6 Red Flags bullets
- plan-recon's nine-step process incl. compile-driven
enumeration (Step 5) and spec-named-path existence table
(Step 6)
- plan-recon's output format including all five sections
(Files, Compile-driven site set, Non-compile-checked
sites, Spec-named-path existence table, Anchors not yet
present)
- plan-recon's 8 Common Rationalisations rows and 9 Red
Flags bullets
Calibrated discipline kept (per memory feedback_dont_strip_
repeated_discipline.md): the three plan-defect families flagged
by user memory (pin/replacement soft-wrap, compile-gate vs
deferred caller, verification filter must resolve) all stay
verbatim — they are project-history scaffolding, just
de-AILang'd in the references.
Fifth skill via the boss pattern. fieldtest empirically tests
whether a shipped cycle is usable by a downstream consumer
who has only the public interface.
Profile gains two slots:
- `paths.public_interface` — list of dirs/files the fieldtester
may read (the project's outward-facing surface: README, design
ledger, docs, examples)
- `paths.fieldtest_examples` — where the fieldtester writes its
fixtures
The forbidden zone is derived: everything not in
`paths.public_interface` (especially `paths.code_roots` and
`paths.bench_dir`) is closed to the fieldtester. This is the
load-bearing source-isolation discipline.
Vocabulary substitutions:
- AILang → "this project"
- milestone → cycle
- Boss → orchestrator
- ailang-fieldtester → fieldtester
- "AIL Surface form / .ail" → "the project's canonical
authoring or consumer form"
- "design/INDEX.md + design/models/" → `paths.public_interface`
- "crates/, runtime/, bench/" → `paths.code_roots`,
`paths.bench_dir`
AILang-specific bits dropped:
- The form-a-default-authoring milestone history (2026-05-13)
and the eight `.ail.json` carve-outs — AILang-specific
schema-migration detail; the universal rule is just
"canonical authoring form only"
- The ail check / ail build / ail emit-ir CLI commands — the
fieldtester now uses "the project's user-facing entry point"
- Per-iter journals reference — replaced with recent iter
commit bodies (universal)
- Example ideas calibrated to AILang (FizzBuzz, Newton's method
on Float, JSON-tree depth, ADT functors) — generalised to
"realistic tasks an end-user might be asked to do"
- `design/contracts/0004-feature-acceptance.md` cross-ref —
dropped (AILang-specific contract); the empirical-vs-
prospective brainstorm symmetry survives in prose
Universal substance preserved verbatim:
- All three Iron Law clauses (public-interface-only,
canonical-form-only, record-don't-fix)
- Five-phase process structure
- Four-class finding taxonomy (bug / friction / spec_gap /
working)
- Spec template
- Status protocol (DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT /
BLOCKED)
- All 8 Common Rationalisations rows (vocabulary-substituted)
- All 10 Red Flags bullets (vocabulary-substituted, with the
AILang-specific .ail.json hand-write bullet generalised to
"intermediate representations")
The source-isolation contract (Iron Law clause 1) is the
load-bearing discipline. Profile slot
`paths.public_interface` makes it machine-checkable; the
agent's hard limit on opening paths outside that list is the
discipline.
Fourth skill via the boss pattern. audit is the cycle-close
cleanup gate; architect does read-only drift review against
the design ledger; bencher does hypothesis-driven performance
diagnostics.
Profile gains one slot:
- `commands.architect_sweeps` — optional list of project-
specific architect sweep commands. The architect agent runs
these in addition to its universal checks; non-zero exit =
drift suspicions. AILang uses this for the
bench/architect_sweeps.sh design-honesty / history-anchor
/ lockstep-invariant detector.
The existing `commands.regression` slot now does double duty:
the audit skill walks it in Step 2; the bencher agent reads
the failing script for diagnostics.
Vocabulary substitutions:
- AILang → "this project"
- milestone → cycle
- Boss → orchestrator
- ailang-architect, ailang-bencher → architect, bencher
AILang-specific bits replaced or removed:
- `bench/check.py && bench/compile_check.py && bench/cross_lang.py`
→ `commands.regression` list
- `bench/architect_sweeps.sh` → `commands.architect_sweeps`
- design/INDEX.md / design/contracts/ / design/models/
→ `paths.design_ledger` / `paths.design_contracts` /
`paths.design_models`
- `bench/run.sh`, `bench/orchestrator-stats/`, `runtime/rc.c`,
`runtime/bump.c` (in bencher) → generic harness / production-
path references
- RC + uniqueness + bump + implicit-mode/explicit-mode
framework (the entire AILang allocator-comparison
calibration) → generic "cost-paying variant vs control"
framing; the hypothesis examples generalised to abstract
perf claims
- The two specific lockstep invariants in architect
(Pattern::Lit::* ↔ pre_desugar_validation; lower_app ↔
is_static_callee) → "the project's CLAUDE.md enumerates
the known pairings; walk each one against the cycle diff"
(the concrete pairings stay AILang-only, in AILang's
CLAUDE.md, not in the plugin)
- The Floats fieldtest "B1 canonical example" reference →
dropped (AILang-specific anchor)
- `design/contracts/0007-honesty-rule.md` cross-ref → dropped
(AILang-specific contract); the honesty principle survives
in the architect's commit-body-truthfulness check
Universal substance preserved verbatim:
- All three Iron Law clauses for audit, architect, bencher
- audit's four-step process; architect's eight-step process;
bencher's hypothesis-first methodology + fixture-pairing
rule + honesty rules
- audit + architect + bencher exit code 0/1/2 semantics
- All Common Rationalisations (5/6/8) and all Red Flags
(5/6/7) rows across the three files, vocabulary-substituted
- bencher's "tie is not a result" doctrine intact
Bencher is the most language-coupled of the seven (was
AILang-allocator-specific). Generalised to a performance-
benchmarker; the discipline (hypothesis-first, design-against
not around, ties-are-bench-info) survives intact. AILang's
RC+bump examples kept in spirit via the generic "cost-paying
vs control" framing.
Brummel