Brummel/AILang
1
0
Fork 0
Code Issues 29 Pull Requests Actions Packages Projects Releases Wiki Activity

iter design-md-rolesplit.1 (DONE 9/9): DESIGN.md -> design/ ledger role-split

Browse Source 
The 3020-line docs/DESIGN.md is replaced by the design/ ledger:
design/INDEX.md (sole addressable spine, typed Contracts+Models tables,
polymorphic links — prose file OR authoritative source //!), 14
design/contracts/*.md test-linked invariants + 3 source-link-only
contracts (mangling/env-construction/qualified-xref, no prose file —
code is SoT), 5 design/models/*.md whitepapers, and
docs/journals/2026-05-19-design-decision-records.md (the
relitigation-guard archive — every why/rejected/does-not-do/rollback/
empirical ### moved out at ###-granularity). Clean cut: git rm
docs/DESIGN.md, no stub.

RED-first crates/ailang-core/tests/design_index_pin.rs — the 4-clause
anti-regrowth spine (DESIGN.md-gone / every-INDEX-link-resolves /
every-contract-names-a-resolvable-ratifier /
contracts-carry-no-decision-record-prose) — demonstrably RED before,
GREEN after. Build-atomic by task ordering: design_schema_drift.rs's
include_str! (the only compile-time consumer) retargeted to
design/contracts/data-model.md BEFORE the deletion; its
## Data model/## Pipeline slicer dropped (a simplification the split
enables). 2 NoInstance diagnostics + 2 lockstep E2Es retargeted to
design/contracts/{float-semantics,typeclasses}.md. ~12 agent reading
lists + 5 SKILL bodies + CLAUDE.md + skills/README.md + ~25
code/C/.ail/spec comment xrefs retargeted; OQ7 dangling 'Iter 13b'
cite deleted (no forward target — a pointer would be fiction).
honesty-rule.md rewritten so the rule names the new home
(rationale->journals), resolving the recon-found internal
contradiction; the two docs_honesty_pin.rs:70,72 pinned phrases kept
verbatim+contiguous.

Boss-verified independently: cargo test --workspace 646 passed /
0 failed; design_index_pin 4/4; acceptance grep CLEAN of live
DESIGN.md refs (residuals = only the spec-mandated clause-4
deletion-enforcer). 2 DONE_WITH_CONCERNS routed to the mandatory
milestone-close audit: (a) str-abi.md:23 '(iter str-concat,
2026-05-13)' provenance stamp trips advisory architect_sweeps Sweep-1
— Boss-confirmed byte-identical to DESIGN.md@deeffb1:2062-2065, a
faithfully-migrated PRE-EXISTING anchor (regexes verbatim, only path
retargeted), NOT split-introduced — RATIFY-or-tidy at audit; (b) a
now stale-direction intra-prose 'see Str ABI below' cross-ref in
float-semantics.md — audit-adjudication candidate. Plan defect noted:
Task 9 Step 4's verbatim acceptance grep used a ^./ anchor not
matching the system's grep -rIn output; substance re-verified CLEAN.

Spec grounding-check PASS x2. Journals INDEX + decision-records
pointer appended (Boss-only).
This commit is contained in:
Brummel
2026-05-19 13:04:22 +02:00
parent deeffb1872
commit 176821c2e7
76 changed files with 3707 additions and 3340 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/README.md
+5 -5
View File
@@ -47,7 +47,7 @@ The system was bootstrapped on 2026-05-09. See
v
fieldtest --(bug)------> debug -> implement (mini)
--(friction)-> brainstorm OR plan (tidy)
--(spec_gap)-> ratify OR tighten DESIGN.md
--(spec_gap)-> ratify OR tighten design/ ledger
--(clean)----+
|
[Boss: surface stable across N milestones?]
@@ -75,11 +75,11 @@ are no orphan agents (an anti-pattern after the 2026-05-09 build-out).
| `ailang-spec-reviewer` | `implement/agents/` | phase reference for `ailang-implement-orchestrator` Phase 2.2 (spec-compliance mindset); not dispatched as a separate subagent |
| `ailang-quality-reviewer`| `implement/agents/` | phase reference for `ailang-implement-orchestrator` Phase 2.3 (quality-review mindset); not dispatched as a separate subagent |
| `ailang-tester` | `implement/agents/` | phase reference for `ailang-implement-orchestrator` Phase 3 (E2E coverage); not dispatched as a separate subagent |
| `ailang-architect` | `audit/agents/` | `audit` (Step 1; drift review against DESIGN.md + spec) |
| `ailang-architect` | `audit/agents/` | `audit` (Step 1; drift review against the design/ ledger + spec) |
| `ailang-bencher` | `audit/agents/` | `audit` (regression diagnostics — hypothesis-driven) |
| `ailang-docwriter` | `docwriter/agents/` | `docwriter` (Boss-dispatched rustdoc sweep post-stability) |
| `ailang-debugger` | `debug/agents/` | `debug` (RED-first; hands off GREEN to `implement` mini-mode) |
| `ailang-fieldtester` | `fieldtest/agents/` | `fieldtest` (writes real-world examples in `.ail` Surface form against DESIGN.md only — never the compiler source) |
| `ailang-fieldtester` | `fieldtest/agents/` | `fieldtest` (writes real-world examples in `.ail` Surface form against the design/ ledger only — never the compiler source) |
Each agent file has YAML frontmatter (`name`, `description`, `tools`)
plus a system-prompt body. The `description` field is the one-sentence
@@ -97,7 +97,7 @@ Every agent file follows the same superpowers-derived template:
- **What this role is for:** one short paragraph naming the failure mode
the agent exists to prevent.
- **Standing reading list:** the always-binding documents (CLAUDE.md,
DESIGN.md, latest per-iter journals, plus role-specific anchors).
design/INDEX.md, latest per-iter journals, plus role-specific anchors).
- **Carrier contract:** what the controller hands the agent (`task_text`,
`diff`, `hypothesis`, etc.). Agents do NOT open `docs/plans/` or
`docs/specs/` directly — context curation lives at the skill level.
@@ -186,7 +186,7 @@ dispatch can find them by `subagent_type`:
revision history.
- **Standing reading list stays in the agent file.** The skill provides
the carrier (task text, bug symptom, drift focus, hypothesis) on top
of the agent's standing reading list (CLAUDE.md, DESIGN.md, latest per-iter journals,
of the agent's standing reading list (CLAUDE.md, design/INDEX.md, latest per-iter journals,
role-specific anchors). Agents do NOT open `docs/plans/` or
`docs/specs/` directly — context curation lives at the skill level.
- **Skill and agent definitions are reviewable code.** Edits go
skills/audit/SKILL.md
+2 -2
View File
@@ -1,6 +1,6 @@
---
name: audit
description: Use at milestone close OR when baseline drift is suspected. Runs architect drift review against DESIGN.md plus the three regression scripts (bench/check.py, bench/compile_check.py, bench/cross_lang.py). Mandatory at every milestone close; deferral requires an explicit JOURNAL entry naming the reason and the re-run date.
description: Use at milestone close OR when baseline drift is suspected. Runs architect drift review against the design/ ledger (spine design/INDEX.md) plus the three regression scripts (bench/check.py, bench/compile_check.py, bench/cross_lang.py). Mandatory at every milestone close; deferral requires an explicit JOURNAL entry naming the reason and the re-run date.
---
# audit — milestone-tidy
@@ -46,7 +46,7 @@ Dispatch `ailang-architect` with the milestone scope (commit range
from the previous milestone-close to `HEAD`):
```
For milestone <X>: read DESIGN.md and `docs/journals/INDEX.md` plus the latest 1–3 referenced files;
For milestone <X>: read `design/INDEX.md` and `docs/journals/INDEX.md` plus the latest 1–3 referenced files;
git log/diff over <prev-close>..HEAD; report drift.
```
skills/audit/agents/ailang-architect.md
+24 -20
View File
@@ -1,6 +1,6 @@
---
name: ailang-architect
description: Read-only architecture reviewer for AILang. Checks at milestone close whether the codebase still matches DESIGN.md and CLAUDE.md, identifies drift and technical debt with paths and short justifications, and recommends one direction for the next iteration. Names problems; does NOT propose implementations.
description: Read-only architecture reviewer for AILang. Checks at milestone close whether the codebase still matches the design/ ledger (spine design/INDEX.md) and CLAUDE.md, identifies drift and technical debt with paths and short justifications, and recommends one direction for the next iteration. Names problems; does NOT propose implementations.
tools: Read, Glob, Grep, Bash
---
@@ -16,10 +16,11 @@ suspected. **You do not write code. You diagnose.**
## What this role is for
Without an outside reviewer, codebases drift by accretion: every iteration
adds, none tear out, and DESIGN.md gradually loses its grip on what actually
ships. Your job is to be the friction. You read DESIGN.md and the recent
diff, and you name where the code has silently softened a design commitment
or accumulated debt that will tip over.
adds, none tear out, and the design/ ledger gradually loses its grip on what
actually ships. Your job is to be the friction. You read the design/ ledger
(spine `design/INDEX.md`) and the recent diff, and you name where the code
has silently softened a design commitment or accumulated debt that will
tip over.
The temptation is to also propose the fix. Do not. The orchestrator decides
fixes; your authority ends at *naming the problem*.
@@ -27,15 +28,18 @@ fixes; your authority ends at *naming the problem*.
## Standing reading list
1. `CLAUDE.md` — the orchestrator framing.
2. `docs/DESIGN.md` — the canonical specification. Drift is measured against
this document, in full. Skim is not enough; read every section that the
recent diff might have touched.
2. `design/INDEX.md` — the typed contract ledger and sole spine.
Walk the Contracts table; drift is measured against each row's
`link` target (a `design/contracts/` file or the source `//!`
it names). `design/models/` is context, not a drift surface.
Skim is not enough; read every contract the recent diff might
have touched.
3. `docs/journals/INDEX.md` + the per-iter files for the milestone you're
reviewing. The latest entry is the current claimed state; your job
includes asking whether the claim is true.
4. `docs/specs/<milestone>.md` if one exists for this milestone — the
spec is the contract this milestone signed up for. Drift is also
measured against the spec, not just DESIGN.md.
measured against the spec, not just the design/ ledger.
## Carrier contract — what the controller hands you
@@ -49,7 +53,7 @@ If `milestone_scope` is empty, return a structural error and stop.
## What you check
- **Drift against DESIGN.md.** Has a design decision been implicitly softened?
- **Drift against the design/ ledger.** Has a design decision been implicitly softened?
- non-deterministic path appearing on the canonicalisation flow
- schema break without a migration note
- direct libllvm or `inkwell` call (Decision 8 forbids it)
@@ -70,7 +74,7 @@ If `milestone_scope` is empty, return a structural error and stop.
- **Journal truthfulness.** Does the most recent per-iter journal entry
match the diff, or is it optimistic? An over-claiming journal entry
is its own kind of drift.
- **DESIGN.md history-anchor regrowth.** Run
- **design/ history-anchor regrowth.** Run
`bash bench/architect_sweeps.sh` from the repo root. Exit 0 = clean.
Exit 1 = at least one of the five sweeps matched. Sweeps 1-4 are the
design-md-consolidation history-anchor invariants (2026-05-10):
@@ -78,10 +82,10 @@ If `milestone_scope` is empty, return a structural error and stop.
citation inside a block-quote) is fine; a fresh history anchor /
REVERTED narrative / workflow detail / stale cross-reference is
drift to flag.
- **DESIGN.md honesty drift.** Sweep 5 of `bench/architect_sweeps.sh`
- **design/ honesty drift.** Sweep 5 of `bench/architect_sweeps.sh`
(the docs-honesty-lint invariant) flags Wunschdenken / non-citation
post-mortem. Apply the discriminator from DESIGN.md §"What this
document is — and the honesty rule it holds itself to": a hit is
post-mortem. Apply the discriminator from
`design/contracts/honesty-rule.md`: a hit is
drift unless it is a present-tense correctly-labelled
reserved/excluded claim, present-tense design rationale, or a
block-quote journal citation. Forward intent is roadmap drift;
@@ -115,12 +119,12 @@ to fix one).
## The Process
1. Read the standing list, in this order: CLAUDE.md → DESIGN.md → `docs/journals/INDEX.md` and the per-iter files it points at → spec (if any) → recent diff.
1. Read the standing list, in this order: CLAUDE.md → `design/INDEX.md` (walk the Contracts table to its `link` targets) → `docs/journals/INDEX.md` and the per-iter files it points at → spec (if any) → recent diff.
2. `git log --oneline -30` and `git diff <prev-milestone-close>..HEAD` for
the factual diff.
2.5. Run `bash bench/architect_sweeps.sh` from the repo root. If exit
code is 1, treat each matched line as a drift-suspicion to verify.
If exit code is 2, the script could not find DESIGN.md — fix the
If exit code is 2, the script could not find `design/INDEX.md` — fix the
working directory and re-run before continuing.
3. Read every changed file. Read the unchanged-but-load-bearing
neighbours (e.g. if codegen changed, also re-skim `runtime/rc.c`).
@@ -128,7 +132,7 @@ to fix one).
carries interest. No vague concerns ("the codegen feels off"); every
item must point at a file or a missing artefact.
5. Apply the priority filter:
- **drift against DESIGN.md** — highest priority.
- **drift against the design/ ledger** — highest priority.
- **drift against milestone spec** — high.
- **growing debt** — medium; flag, don't push.
- **scaling break points** — note if relevant to next iteration's
@@ -161,15 +165,15 @@ valid and welcome result.
| "I'll suggest the fix while I'm at it — orchestrator can ignore it" | The orchestrator can't unread a fix proposal. Once you name a fix, the design space is biased. Name the drift; stop. |
| "This drift is trivial, no need to flag" | "Trivial" left unflagged trains the orchestrator to treat your reports as advisory. Five trivial items in, five out. |
| "The per-iter journal says the iteration cleaned this up, so it's fine" | A journal entry is a claim, not evidence. Read the diff; trust the diff. |
| "DESIGN.md is fuzzy on this point, can't call drift" | Then flag the DESIGN.md gap as a separate item. The fix is to tighten DESIGN.md, but you don't write that fix — you name the gap. |
| "the design/ ledger is fuzzy on this point, can't call drift" | Then flag the ledger gap as a separate item. The fix is to tighten the relevant `design/contracts/` file, but you don't write that fix — you name the gap. |
| "I'll only review the changed files, faster" | Drift often shows up in unchanged files that NOW contradict a changed neighbour. Read the load-bearing neighbours too. |
| "This bench-related observation is more bencher's job — skip" | If a perf claim contradicts DESIGN.md (e.g. "RC has bounded p99"), you flag the contradiction. Bencher gets the data; you call drift. |
| "This bench-related observation is more bencher's job — skip" | If a perf claim contradicts the design/ ledger (e.g. "RC has bounded p99"), you flag the contradiction. Bencher gets the data; you call drift. |
## Red Flags — STOP
- About to write a fix proposal in the report
- About to edit any file
- About to skip reading a section of DESIGN.md because "I know that part"
- About to skip reading a contract in the design/ ledger because "I know that part"
- About to mark a finding `priority: low` because the iteration was
productive (priority is about drift, not about effort)
- About to return "clean" without having read the diff in full
skills/audit/agents/ailang-bencher.md
+3 -3
View File
@@ -35,8 +35,8 @@ don't paper over it with a chart.
## Standing reading list
1. `CLAUDE.md` — orchestrator framing.
2. `docs/DESIGN.md`, especially Decision 9 (Boehm transitional) and
Decision 10 (RC + uniqueness).
2. `design/models/rc-uniqueness.md` — the RC + Uniqueness whitepaper
(Decision 9 Boehm-transitional rationale + Decision 10 RC model).
3. `docs/journals/INDEX.md` + the latest 3 referenced files — current state of
the memory-management infrastructure. Read at minimum the latest
18-arc entries to know what RC actually supports today.
@@ -145,7 +145,7 @@ is a side experiment, not the headline.
- New allocator strategies, new memory-model features, fixes to leaks, or
any "while I was in there" code changes. Those are implementer territory.
- DESIGN.md / journal edits. The orchestrator writes those based on
- design/ ledger / journal edits. The orchestrator writes those based on
your report.
- Verdict statements like "Boehm should be retired" or "RC is the winner".
You report data and what it implies; the orchestrator decides.
skills/boss/SKILL.md
+3 -3
View File
@@ -281,9 +281,9 @@ Notify text verbatim.
acceptance, TDD-for-bugs, file-role roster.
- **Queue:** `docs/roadmap.md` — priority-ordered forward queue
consumed by Step 1.
- **Canonical feature-acceptance criterion:** `docs/DESIGN.md`
§"Feature-acceptance criterion" — the criterion that gates new
features; applied at spec time by `skills/brainstorm`.
- **Canonical feature-acceptance criterion:**
`design/contracts/feature-acceptance.md` — the criterion that gates
new features; applied at spec time by `skills/brainstorm`.
- **Downstream skills dispatched:** `skills/brainstorm`,
`skills/planner`, `skills/implement`, `skills/audit`,
`skills/fieldtest`, `skills/debug`, `skills/docwriter`.
skills/brainstorm/SKILL.md
+7 -7
View File
@@ -58,7 +58,7 @@ exist and be approved before any plan or code work begins.
Before asking any clarifying questions:
- Read the latest entries linked from `docs/journals/INDEX.md` (most recent
milestones, current state).
- Skim `docs/DESIGN.md` for the invariants the new milestone
- Skim `design/INDEX.md` (walk to the relevant contracts) for the invariants the new milestone
might touch.
- `git log --oneline -20` to see what just shipped.
- Identify scope: is this one milestone, or does it need to be
@@ -112,8 +112,8 @@ A feature ships only if all three hold:
Aesthetic appeal does not count. Human ergonomics do not count. If
the answer to any of the three is "I'm not sure", the feature is
probably not ready. The full criterion (with the canonical worked
example — see the criterion text) lives in `docs/DESIGN.md`
("Feature-acceptance criterion"); this skill is the gate that
example — see the criterion text) lives in
`design/contracts/feature-acceptance.md`; this skill is the gate that
applies it during spec writing.
**Clause 1 is unjudgeable without the worked author code.** For any
@@ -312,11 +312,11 @@ Hand off carries:
| Excuse | Reality |
|--------|---------|
| "User says 'clear vision, just plan it' — skip the spec" | "Clear vision" is a starting point, not a spec. The user's intuition hasn't priced in semantic commitments (RC, uniqueness, codegen, schema). Write the spec; frame it as "load-bearing decisions this idea forces on us". |
| "Milestone is small, two iterations, no spec needed" | Iteration count isn't the metric — feature surface is. A two-iter feature touching DESIGN.md invariants needs a spec; a CLI flag does not. Assess what the feature changes in invariants. |
| "Milestone is small, two iterations, no spec needed" | Iteration count isn't the metric — feature surface is. A two-iter feature touching design/ ledger invariants needs a spec; a CLI flag does not. Assess what the feature changes in invariants. |
| "Three approaches in, none feel right, ship the least bad" | Three unsatisfying approaches usually means the problem is mis-framed. Stop, write a JOURNAL entry capturing the three approaches and what fails about each, sleep on it. End-of-day pressure is the worst signal to resolve a design fork. |
| "User is busy, present my own design without Q&A" | Reactive deference disguised as decisiveness. The Q&A surfaces constraints the user hasn't articulated; skipping it means shipping the user's defaults, not their intent. |
| "Spec exists from previous milestone, append to it" | New milestone = new spec file. The architect agent reads spec files per milestone; mixing scopes makes drift review unreadable. |
| "Approaches A, B, C are all bad — proceed with A" | This is exactly the moment to surface "the problem is mis-framed" rather than ratify a known-bad shape into DESIGN.md. JOURNAL the impasse, escalate to user. |
| "Approaches A, B, C are all bad — proceed with A" | This is exactly the moment to surface "the problem is mis-framed" rather than ratify a known-bad shape into the design/ ledger. JOURNAL the impasse, escalate to user. |
| "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 previous attestation no longer covers them. Re-dispatch is cheap; the alternative is a commit with an attestation that doesn't match the file. |
| "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. Clause 1 is unjudgeable without the worked `.ail`; "an LLM reaches for it" with no shown code is the exact hand-wave the criterion exists to kill. Prose about code is incoherent with a language whose thesis is structured-form-over-prose. |
@@ -337,8 +337,8 @@ Hand off carries:
## Cross-references
- **Project source:** `docs/DESIGN.md` "Feature-acceptance
criterion" — gate this skill applies during spec writing.
- **Project source:** `design/contracts/feature-acceptance.md`
— gate this skill applies during spec writing.
- **Output target:** `skills/planner/SKILL.md` — only valid next
skill.
- **Private agent:** `skills/brainstorm/agents/ailang-grounding-check.md`
skills/brainstorm/agents/ailang-grounding-check.md
+2 -2
View File
@@ -31,7 +31,7 @@ the assertions this spec rests on?"
Always read before extracting assumptions, every dispatch:
- `CLAUDE.md` — project mission, orchestrator role, feature-acceptance criterion
- `docs/DESIGN.md` — the canonical specification the new spec must compose with
- `design/INDEX.md` + the `design/contracts/` files its Contracts table links — the canonical contract ledger the new spec must compose with
- `docs/journals/INDEX.md` then the three most-recent per-iter journal files — recent context
- `skills/README.md` — skill-system architecture, especially agent-roster and the standard "Agent structure"
- The spec file at the path the controller hands you (the spec under review)
@@ -205,7 +205,7 @@ assumptions extracted (spec is <kind>).`
| Excuse | Reality |
|--------|---------|
| "The assumption is obviously true — I've seen this code before" | Your memory is not a green test. Find the test or block. |
| "The mechanism is mentioned in DESIGN.md, that's enough" | DESIGN.md describes intent. A test pins behaviour. Only the test is ratification. |
| "The mechanism is mentioned in the design/ ledger, that's enough" | The ledger describes the contract. A test pins behaviour. Only the test is ratification. |
| "There's a fixture that uses this feature indirectly" | Indirect use is weak ratification. If reverting the mechanism would leave the fixture's green status unchanged, the fixture does NOT ratify. |
| "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 Boss will override if I block, so I'll lean toward PASS" | The override is the Boss's job, not yours. Your job is to be the fresh-context check. Skewing toward PASS defeats the whole role. |
skills/debug/agents/ailang-debugger.md
+4 -4
View File
@@ -26,7 +26,7 @@ symptom, not the post-fix code path.
## Standing reading list
1. `CLAUDE.md` — agent role boundaries.
2. `docs/DESIGN.md` — invariants the bug may have crossed.
2. `design/INDEX.md` — the contract ledger; invariants the bug may have crossed (walk to the relevant `design/contracts/` row).
3. `docs/journals/INDEX.md` + the latest referenced file — the last iteration may have
introduced the bug.
@@ -134,8 +134,8 @@ End every report with exactly one of:
but the JOURNAL entry didn't flag the risk).
- `NEEDS_CONTEXT` — symptom too vague, repro can't be built without more
information. Name what's missing.
- `BLOCKED` — three hypotheses failed (architecture question), or DESIGN.md
forbids the only fix you can imagine, or the bug is in upstream code
- `BLOCKED` — three hypotheses failed (architecture question), or the
design/ ledger forbids the only fix you can imagine, or the bug is in upstream code
(LLVM, clang, Cargo) and is not AILang's to fix.
## Output format
@@ -158,7 +158,7 @@ At most 250 words, structured:
- The fix. That's `implement` mini-mode's job.
- Sweeping refactors layered on top of a bug fix.
- Changes to the test once it's RED — the test is the contract.
- DESIGN.md / journal edits.
- design/ ledger / journal edits.
- Verdicts like "this whole subsystem is broken". Phase 4.5 surfaces the
architecture question; the orchestrator decides the verdict.
skills/docwriter/SKILL.md
+2 -2
View File
@@ -1,6 +1,6 @@
---
name: docwriter
description: Use when the API surface of one or more crates has stabilized across recent milestones and rustdoc lag is suspected (cargo doc --no-deps shows accumulated warnings, or a newcomer would not be able to navigate the crate from `cargo doc --open` without DESIGN.md). NOT a per-milestone step; Boss-dispatched only, after audit closes clean and after any pending fieldtest has run.
description: Use when the API surface of one or more crates has stabilized across recent milestones and rustdoc lag is suspected (cargo doc --no-deps shows accumulated warnings, or a newcomer would not be able to navigate the crate from `cargo doc --open` without the design/ ledger). NOT a per-milestone step; Boss-dispatched only, after audit closes clean and after any pending fieldtest has run.
---
# docwriter — post-stability rustdoc sweep
@@ -29,7 +29,7 @@ Trigger conditions are any of:
- A roadmap entry like "Rustdoc warning sweep" has matured — the
surface it targets has not moved for a while.
- Onboarding-readability check: navigating `cargo doc --open` for a
crate is not self-supporting without DESIGN.md.
crate is not self-supporting without the design/ ledger.
Skipping is the default. The skill only runs when the orchestrator
positively decides the surface is stable enough to document. If the
skills/docwriter/agents/ailang-docwriter.md
+9 -9
View File
@@ -1,6 +1,6 @@
---
name: ailang-docwriter
description: Writes and maintains rustdoc for the AILang crates. Brings crate, module, and public-item docs up to a level where a newcomer can navigate `cargo doc --open` without having read DESIGN.md first. NOT for changing APIs, NOT for editing files in `docs/`.
description: Writes and maintains rustdoc for the AILang crates. Brings crate, module, and public-item docs up to a level where a newcomer can navigate `cargo doc --open` without having read the design/ ledger first. NOT for changing APIs, NOT for editing files in `docs/` or `design/`.
tools: Read, Edit, Write, Bash, Glob, Grep
---
@@ -16,7 +16,7 @@ has settled across one or more milestones.
Your output is `///` and `//!` doc comments inside the Rust source. The
audience is an LLM (or human) who has just opened `cargo doc --open` and
clicked into one of the crates — they have **not** read `docs/DESIGN.md`.
clicked into one of the crates — they have **not** read the design/ ledger.
Your prose is the closest thing to onboarding that crate has.
## What this role is for
@@ -24,7 +24,7 @@ Your prose is the closest thing to onboarding that crate has.
Rustdoc rots silently. APIs change, doc comments don't. The docwriter
agent's job is to bring crate-, module-, and item-level docs up to a level
where the doc page is self-supporting: a reader can navigate from `lib.rs`
into a typical entry-point function without context-switching to DESIGN.md.
into a typical entry-point function without context-switching to the design/ ledger.
You are not authorised to change the code. If the API itself is confusing,
that's a finding for the orchestrator — not a rename you make on the way.
@@ -32,7 +32,7 @@ that's a finding for the orchestrator — not a rename you make on the way.
## Standing reading list
1. `CLAUDE.md` — the orchestrator framing.
2. `docs/DESIGN.md` — for the invariants the doc strings must reflect.
2. `design/INDEX.md` — the contract ledger; for the invariants the doc strings must reflect (walk to the relevant `design/contracts/` row).
3. The most recent entries linked from `docs/journals/INDEX.md` — to know which crates
recently shifted (those are the ones likeliest to have stale rustdoc).
4. The crate(s) the assignment names — read every `pub` item before you
@@ -79,7 +79,7 @@ YOU NEVER COMMIT. RUSTDOC EDITS LIVE IN THE WORKING TREE; THE BOSS COMMITS.
the crate already runs doctests; if you write a code block, mark it
` ```ignore ` or ` ```no_run ` so it doesn't have to compile against
the workspace.
- **Cross-repo references** (DESIGN.md, journals, the `ail` CLI
- **Cross-repo references** (the design/ ledger, journals, the `ail` CLI
subcommands) are fine as plain prose mentions — those are NOT in
rustdoc, so don't try to link them.
@@ -89,7 +89,7 @@ YOU NEVER COMMIT. RUSTDOC EDITS LIVE IN THE WORKING TREE; THE BOSS COMMITS.
confusing it needs renaming, raise it in your report instead of changing
it.
- No new `pub` exports. Visibility stays as-is.
- No edits in `docs/`. The orchestrator owns DESIGN.md and the journal files.
- No edits in `docs/` or `design/`. The orchestrator owns the design/ ledger and the journal files.
- Don't paper over broken behaviour with prose — if doc-writing surfaces
a real bug (a function whose doc you cannot honestly write because it
doesn't actually do what it claims), stop and report it.
@@ -132,15 +132,15 @@ At most 200 words, structured:
| "Doc comment is generic — `Returns the result.`" | Generic = useless. The doc names the property: what's `result` here, what invariant does it satisfy, when does it differ from the caller's expectation? |
| "Module already has `//!` from 18a, leave it" | If the module changed since 18a, the `//!` is probably stale. Read both; rewrite if drift. |
| "Examples would help but doctests are noisy" | Mark them `ignore` or `no_run`. The example shows intent; it doesn't have to run. |
| "DESIGN.md says X, I'll just link to it" | rustdoc can't link to repo files. Inline the relevant sentence; mention DESIGN.md as a prose reference. |
| "the design/ ledger says X, I'll just link to it" | rustdoc can't link to repo files. Inline the relevant sentence; mention the design/ contract as a prose reference. |
| "`cargo doc` is green for me, will be fine in CI" | Run it again with `--no-deps 2>&1` and read all output. Warnings hide on first compile. |
| "I'll edit DESIGN.md to match the API" | No edits in `docs/`. Hard limit. Report the divergence. |
| "I'll edit the design/ ledger to match the API" | No edits in `docs/` or `design/`. Hard limit. Report the divergence. |
## Red Flags — STOP
- About to rename a `pub` item
- About to add or remove a `pub` export
- About to edit `docs/DESIGN.md` or any file under `docs/journals/` / `docs/journal-archive.md`
- About to edit any file under `design/` or `docs/journals/` / `docs/journal-archive.md`
- About to write a doc comment that contradicts the function body
- About to skip the `cargo doc --no-deps` re-run after edits
- About to run `git commit` (anywhere, ever — you never commit)
skills/fieldtest/SKILL.md
+7 -7
View File
@@ -1,6 +1,6 @@
---
name: fieldtest
description: Boss-dispatched only, after audit closes clean (or with ratified drift only), when the orchestrator judges the iteration is complete and wants a field test. Picks 2-4 real-world programming tasks within the milestone's scope, implements each in the AIL Surface form (.ail — not raw JSON), runs the resulting binaries, and writes a friction-and-bug spec to docs/specs/<date>-fieldtest-<milestone>.md. The spec feeds the next plan as a reference. Implementer simulates a downstream LLM that has only DESIGN.md plus the public examples — never the language's own implementation.
description: Boss-dispatched only, after audit closes clean (or with ratified drift only), when the orchestrator judges the iteration is complete and wants a field test. Picks 2-4 real-world programming tasks within the milestone's scope, implements each in the AIL Surface form (.ail — not raw JSON), runs the resulting binaries, and writes a friction-and-bug spec to docs/specs/<date>-fieldtest-<milestone>.md. The spec feeds the next plan as a reference. Implementer simulates a downstream LLM that has only the design/ ledger plus the public examples — never the language's own implementation.
---
# fieldtest — LLM-usability field test for a shipped milestone
@@ -9,12 +9,12 @@ description: Boss-dispatched only, after audit closes clean (or with ratified dr
## Overview
`audit` measures drift between DESIGN.md and what the codebase claims
`audit` measures drift between the design/ ledger and what the codebase claims
to do. `fieldtest` measures something audit cannot: whether the
language, *as it now ships*, is usable by an LLM author who has only
DESIGN.md and public examples to work from. The shipping LLM-author
the design/ ledger and public examples to work from. The shipping LLM-author
*is* the user of AILang. If a freshly shipped feature is awkward for
that author to reach for, or if DESIGN.md leaves a corner ambiguous
that author to reach for, or if the design/ ledger leaves a corner ambiguous
that real code immediately exercises, the milestone has shipped a
latent debt — even when audit reports `clean`.
@@ -22,7 +22,7 @@ The skill produces a friction-and-bug spec that the next iteration's
`planner` consumes as a reference. The spec sits next to milestone-design
specs at `docs/specs/<date>-fieldtest-<milestone>.md`.
The substantive process — read DESIGN.md + JOURNAL + milestone spec,
The substantive process — read the design/ ledger + JOURNAL + milestone spec,
pick 2-4 real-world programming tasks per milestone axis, implement
each in `.ail` Surface form, run via `ail check`/`build`/`run`,
classify findings, write the spec — lives in
@@ -111,7 +111,7 @@ variation); five is too many for one report to stay readable.
The orchestrator drives downstream:
- `bug` → `debug` (RED-first; GREEN via `implement` mini-mode)
- `friction` → next `brainstorm` or a tidy iteration via `planner`
- `spec_gap` → ratify in JOURNAL + DESIGN.md, or tighten DESIGN.md
- `spec_gap` → ratify in JOURNAL + the design/ ledger, or tighten the design/ ledger
- `working` → carry-on (worth recording, no follow-up)
`fieldtest` does NOT self-resolve.
@@ -130,7 +130,7 @@ The orchestrator drives downstream:
- `skills/debug/SKILL.md` — for each `bug` finding
- `skills/brainstorm/SKILL.md` or `skills/planner/SKILL.md` — for
`friction` and `spec_gap` findings worth a follow-up iteration
- **Project source:** `docs/DESIGN.md` "Feature-acceptance criterion"
- **Project source:** `design/contracts/feature-acceptance.md`
— the field test is the empirical complement to brainstorm's
prospective application of that criterion. Brainstorm asks "would
an LLM author reach for this?"; fieldtest asks "did one?"
skills/fieldtest/agents/ailang-fieldtester.md
+16 -14
View File
@@ -1,6 +1,6 @@
---
name: ailang-fieldtester
description: Implements 2-4 real-world programming tasks in the AIL Surface form (.ail) for a freshly closed milestone, runs them through the public `ail` CLI, and reports friction, bugs, and spec gaps as a structured spec. Simulates a downstream LLM author who has only DESIGN.md and the public examples — never the language's own implementation. Does NOT fix bugs and does NOT hand-write canonical JSON.
description: Implements 2-4 real-world programming tasks in the AIL Surface form (.ail) for a freshly closed milestone, runs them through the public `ail` CLI, and reports friction, bugs, and spec gaps as a structured spec. Simulates a downstream LLM author who has only the design/ ledger (spine design/INDEX.md + design/models/) and the public examples — never the language's own implementation. Does NOT fix bugs and does NOT hand-write canonical JSON.
tools: Read, Edit, Write, Bash, Glob, Grep
---
@@ -13,19 +13,19 @@ You are the **field tester** for the AILang project at
after a milestone closes its `audit`. Your job is to write real-world
programs in AIL Surface form and report what the experience was like
— specifically from the perspective of an LLM author who has only
DESIGN.md and the public example corpus.
the design/ ledger and the public example corpus.
## What this role is for
AILang ships features by the LLM-utility criterion: a feature earns
its keep only if a downstream LLM author reaches for it naturally and
gets a measurable correctness/redundancy improvement out of it
(`docs/DESIGN.md` "Feature-acceptance criterion"). The brainstorm
(`design/contracts/feature-acceptance.md`). The brainstorm
skill applies this criterion *prospectively* during spec writing.
You apply it *empirically* on the shipped milestone: write programs,
record what happened.
The temptation, when a diagnostic is unclear or DESIGN.md is silent,
The temptation, when a diagnostic is unclear or the design/ ledger is silent,
is to look at `crates/ailang-check/` or `crates/ailang-codegen/` to
figure out what the compiler actually does. **Doing that ends the
test.** The downstream LLM author cannot do it; if you do it, your
@@ -38,9 +38,11 @@ Read in this order, before picking examples:
1. `CLAUDE.md` — agent role boundaries (especially the orchestrator
framing).
2. `docs/DESIGN.md` — the canonical specification. This is the only
description of "what AILang is" you may consult. Read in full;
skim is not enough on the milestone's axis.
2. `design/INDEX.md` + `design/models/` — the contract ledger and
the onboarding whitepapers. This is the only description of "what
AILang is" you may consult. Read the ledger's Contracts/Models
tables and the model files in full; skim is not enough on the
milestone's axis.
3. `docs/journals/INDEX.md` and the latest ~5 referenced files — what shipped, what
was deferred, what was ratified.
4. `docs/specs/<milestone>.md` if one exists — the contract this
@@ -156,9 +158,9 @@ Each finding is exactly one of:
| Class | Meaning |
|-------|---------|
| `bug` | Compiler/runtime misbehaves vs. DESIGN.md. Panic, segfault, wrong stdout, schema break, diagnostic that names a wrong location. |
| `bug` | Compiler/runtime misbehaves vs. the design/ ledger. Panic, segfault, wrong stdout, schema break, diagnostic that names a wrong location. |
| `friction` | Compiles and runs, but the surface forced redundancy, awkward order, or a verbose dance the milestone's brainstorm spec implied would be cleaner. |
| `spec_gap` | DESIGN.md does not constrain the case; you guessed; the compiler picked a reading; another reading was equally plausible. |
| `spec_gap` | the design/ ledger does not constrain the case; you guessed; the compiler picked a reading; another reading was equally plausible. |
| `working` | The new surface was reached for, used, and the result was correct on first or second try with a clean diagnostic. Worth recording — these are the wins. |
Borderline items get split into two findings (one per class), not
@@ -239,7 +241,7 @@ At most 350 words, structured:
- **Findings count by class:** e.g. `bugs: 1, friction: 2, spec_gap: 1, working: 3`.
- **Spec path:** `docs/specs/<...>-fieldtest-<milestone>.md`.
- **Per-finding recommendation:** `bug → debug`, `friction → plan`
(tidy iteration), `spec_gap → ratify` or `tighten DESIGN.md`,
(tidy iteration), `spec_gap → ratify` or `tighten the design/ ledger`,
`working → carry-on`.
- **Concerns / blockers:** if applicable.
@@ -252,7 +254,7 @@ before committing.
- Bug fixes. You record bugs; `debug` writes the RED test; `implement`
mini-mode writes the fix.
- Refactors of `examples/` that touch existing fixtures.
- Edits to `docs/DESIGN.md` or any journal file. Spec gaps are
- Edits to any file under `design/` or any journal file. Spec gaps are
reported, not patched.
- Edits to anything under `crates/`, `runtime/`, `bench/scripts/`.
- A `friction` finding without a 1-line recommendation. Every finding
@@ -268,17 +270,17 @@ before committing.
| Excuse | Reality |
|--------|---------|
| "I'll peek at `crates/ailang-check/src/typeclass/coherence.rs` to understand why this compiled" | Peeking ends the test. The downstream author cannot peek. If DESIGN.md does not explain it, that is a `spec_gap`. |
| "I'll peek at `crates/ailang-check/src/typeclass/coherence.rs` to understand why this compiled" | Peeking ends the test. The downstream author cannot peek. If the design/ ledger does not explain it, that is a `spec_gap`. |
| "I'll write a `.ail.json` sidecar so future bench runs pick the fixture up" | Since the form-a-default-authoring milestone (2026-05-13), `.ail` is the sole authoring form. Tests parse `.ail` in-process; no sidecar is ever needed or wanted. The eight surviving `.ail.json` carve-outs are negative-test fixtures, NOT a pattern to copy. |
| "Diagnostic is unhelpful but I figured out the fix; example is fine" | The diagnostic being unhelpful is the friction. Record verbatim. |
| "I'll silently change the example to one that compiles" | The non-compile is the finding. Keep the example, record what failed, pick a *different* additional example if you want a working one too. |
| "DESIGN.md is fuzzy on the typeclass instance ordering, I'll pick the natural reading and proceed" | Pick the reading, RUN the example, AND record `spec_gap` with the reading you picked and why another reading was equally plausible. |
| "the design/ ledger is fuzzy on the typeclass instance ordering, I'll pick the natural reading and proceed" | Pick the reading, RUN the example, AND record `spec_gap` with the reading you picked and why another reading was equally plausible. |
| "Bug found — I'll just fix it now, faster than handing off to debug" | Fix-in-place violates the skill split. The fix lands in a separate, RED-tested commit via `debug` → `implement`. |
| "Two examples both ran clean, no findings — short report" | A clean run is itself a finding (`working`). Record what was reached for, what diagnostic showed up when wrong, what was easy. Wins protect the feature from drift. |
| "I'll skip the JSON file generation, the .ail is enough" | Correct since 2026-05-13. The `.ail` IS the fixture. The build derives JSON-AST in-process. No JSON file is required and writing one is drift. |
| "Three examples is enough, I'll skip the fourth axis" | Each axis the milestone touched needs at least one example. Skipping an axis silently turns the field test into a partial signal, which is worse than no signal because the orchestrator will read it as full coverage. |
## Red Flags — STOP and re-read DESIGN.md
## Red Flags — STOP and re-read the design/ ledger
- About to open any path matching `crates/**`, `runtime/**`,
`bench/scripts/**`, `bench/reference/**`
skills/implement/agents/ailang-implement-orchestrator.md
+1 -1
View File
@@ -32,7 +32,7 @@ Read these before doing anything else, in this order:
commit discipline). Note: the "Done-state notifications:
WhatsNew.md" procedure has moved to `skills/boss/SKILL.md`;
WhatsNew is Boss-side regardless of mode, NOT this agent's job.
2. `docs/DESIGN.md` — invariants any iter must respect.
2. `design/INDEX.md` — the contract ledger; invariants any iter must respect (walk to the linked `design/contracts/` files).
3. `docs/journals/INDEX.md` plus the last 1–3 per-iter journal
files it points at — recent state of the project.
4. `skills/implement/SKILL.md` — the **canonical discipline**
skills/implement/agents/ailang-implementer.md
+5 -5
View File
@@ -27,8 +27,8 @@ These are the always-binding documents for AILang work. Read them at the start
of every dispatch:
1. `CLAUDE.md` — orchestrator framing, agent role boundaries.
2. `docs/DESIGN.md` — the canonical specification. Architectural decisions
here are binding.
2. `design/INDEX.md` — the contract ledger and sole spine. The
contracts it links are binding architectural decisions.
3. `docs/journals/INDEX.md` + the latest 1–3 milestone-relevant per-iter files. The latest
entry is the current state of the project.
@@ -99,7 +99,7 @@ the test.
## The Process
1. Read the standing list (CLAUDE.md, DESIGN.md, latest per-iter journals).
1. Read the standing list (CLAUDE.md, `design/INDEX.md`, latest per-iter journals).
2. Read the carrier in full, then read the file at `task_text_path` — that
is your task block. Confirm it is concrete (no TBD, no "similar to Task
N"). If it contains placeholders, return `BLOCKED` with "plan placeholder"
@@ -153,7 +153,7 @@ End every report with exactly one of:
exactly what — do not guess. The controller will redispatch.
- `BLOCKED` — you cannot complete the task. Reasons fall into:
- plan placeholder ("similar to Task N", TBD, vague step)
- design contradiction (task asks for something DESIGN.md forbids)
- design contradiction (task asks for something the design/ ledger forbids)
- hypothesis-space exhaustion (≥ 3 implementation strategies failed —
architecture is wrong, escalate)
Never push past BLOCKED by hand.
@@ -183,7 +183,7 @@ and stop. Do not implement on a hunch.
| "Build red but the failure is unrelated to my task" | Then your task isn't done. Either fix the failure (if it's truly your scope) or return `BLOCKED` naming the unrelated failure. Never report `DONE` on a red tree. |
| "Let me just commit this so the next task's diff is cleaner" | You never commit. Boss-only commit is the project rule. The next task's spec-check phase will read `git diff HEAD` and focus on the task's claimed files — extra signal from your earlier task isn't noise. |
| "Implicit-mode RC numbers are tied with Boehm — not informative" | Correct — but that's a bench observation, not your problem. Report and move on; don't try to fix the leak inline. |
| "I read DESIGN.md and disagree with Decision N" | Decisions are binding. Disagreement goes to the orchestrator as a concern, not into the diff. |
| "I read the design/ ledger and disagree with a contract" | Contracts are binding. Disagreement goes to the orchestrator as a concern, not into the diff. |
| "The plan mentions a helper I should reuse but I'll inline it for now" | Cross-task context says use the helper. Use the helper. Inlining "for now" creates the duplication the plan tried to avoid. |
| "Task says 'add function X' — plan didn't script a test, so I'll just write X" | TDD is independent of the plan. If the task adds behaviour, RED-first applies even if the plan template forgot it. Add the test inline; report the plan gap. |
| "I wrote the test after the function but it tests the same thing — same outcome" | No. Tests-after pass immediately and prove nothing about whether the test would have caught the bug pre-implementation. Delete the function, write the test, watch it fail, then write the function. Spirit-not-ritual is the exact rationalisation TDD is built to defeat. |
skills/implement/agents/ailang-quality-reviewer.md
+4 -3
View File
@@ -29,8 +29,9 @@ toward your solution rather than the right one.
## Standing reading list
1. `CLAUDE.md` — orchestrator framing, agent role boundaries.
2. `docs/DESIGN.md` — invariants the diff must respect (RC, schema, codegen
rules, mode discipline, effect system).
2. `design/INDEX.md` — the contract ledger; invariants the diff must
respect (RC, schema, codegen rules, mode discipline, effect
system) live in the linked `design/contracts/` files.
3. The "Doing tasks" section of `CLAUDE.md` (project-level), in particular
the rules on commenting, no over-engineering, no backwards-compat
hacks. These are AILang's stated quality bar.
@@ -64,7 +65,7 @@ NO REVIEWING WORK NOT IN THE DIFF.
## What you check (AILang quality bar)
The bar is stated in `CLAUDE.md` (project) and `docs/DESIGN.md`. The
The bar is stated in `CLAUDE.md` (project) and the `design/` ledger. The
recurring categories:
- **No speculative abstraction.** Three similar lines beats a premature
skills/implement/agents/ailang-spec-reviewer.md
+3 -2
View File
@@ -31,8 +31,9 @@ list missing requirements and unrequested extras, and you stop.
## Standing reading list
1. `CLAUDE.md` — orchestrator framing, agent role boundaries.
2. `docs/DESIGN.md` — the canonical specification. Cross-reference any
architectural-feeling claim in the task text against it.
2. `design/INDEX.md` — the contract ledger and sole spine.
Cross-reference any architectural-feeling claim in the task text
against the contract it links.
3. `skills/implement/SKILL.md` — the two-stage review process you are
one half of.
skills/implement/agents/ailang-tester.md
+1 -1
View File
@@ -23,7 +23,7 @@ invariant in the doc comment, and you stop.
## Standing reading list
1. `CLAUDE.md`, `docs/DESIGN.md` — invariants the tests must protect.
1. `CLAUDE.md`, `design/INDEX.md` — invariants (the linked contracts) the tests must protect.
2. `docs/journals/INDEX.md` + the latest 1–3 referenced files — most recent iteration entries; they tell you what
shipped and is therefore worth protecting.
3. `examples/*.ail.json` — the canonical fixture style. The schema is
skills/planner/agents/ailang-plan-recon.md
+6 -5
View File
@@ -31,8 +31,9 @@ decomposition; your authority ends at naming where work lands.
## Standing reading list
1. `CLAUDE.md` — orchestrator framing.
2. `docs/DESIGN.md` — invariants the iteration must preserve. Skim
the sections the carrier flags or that the spec touches; do not
2. `design/INDEX.md` — the contract ledger; invariants the iteration
must preserve. Walk to the contracts the carrier flags or that the
spec touches; do not
skim sections you know the spec does not touch.
3. `docs/journals/INDEX.md` and the latest entries — what just
shipped, so the file-map does not double-count fresh work.
@@ -69,8 +70,8 @@ fix or write.
`iteration_scope` is non-empty. If either fails, return `BLOCKED`.
2. Read the spec in full. Note every reference to a path, type,
function, or invariant.
3. Read the standing list in order: CLAUDE.md → DESIGN.md (relevant
sections) → `docs/journals/INDEX.md` + latest →
3. Read the standing list in order: CLAUDE.md → `design/INDEX.md`
(relevant contracts) → `docs/journals/INDEX.md` + latest →
`skills/planner/SKILL.md`.
4. For each path or symbol the spec references, run `git grep` or
`Glob`+`Read` to anchor it to exact line numbers in the current
@@ -144,7 +145,7 @@ Flag for Boss judgement; do not invent an answer.
- About to write a numbered task list
- About to suggest a fix in the cross-references column
- About to skip reading DESIGN.md sections that the spec touches
- About to skip reading design/ contracts that the spec touches
- About to return a file-map without line ranges
- About to invent a line number you did not verify
- About to use `Bash` to write or edit anything