Files

T

Brummel 14a91f0ae5 iter boehm-retirement.1 (DONE 10/10): retire the transitional Boehm GC backend

Closes Gitea #4. Removes the Boehm-Demers-Weiser conservative GC
backend wholesale across six layers in one atomic iteration. After
this iter, `AllocStrategy` has two variants (`Rc`, `Bump`),
`--alloc=gc` is rejected at CLI parse with `unknown --alloc value`,
the libgc link arm is gone, and the design ledger describes RC
(canonical) + bump (raw-alloc bench-floor) as the only allocators.

Layer-by-layer summary:

  CLI surface — `crates/ail/src/main.rs`:
    `parse_alloc_strategy` arm `"gc" => Ok(AllocStrategy::Gc)`
    removed; error wording updated to `(expected `rc` or `bump`)`;
    clap-derive `value_parser = ["gc","bump","rc"]` allowlist on
    BOTH `Build` and `Run` subcommands DROPPED so that
    `parse_alloc_strategy` remains the sole gatekeeper for the
    unknown-value diagnostic (otherwise clap shadows the runtime
    diagnostic with `invalid value 'gc' for '--alloc'`, which would
    miss the milestone-pin's stderr substring check). The
    `default_value = "rc"` stays.

  Codegen — `crates/ailang-codegen/src/lib.rs`:
    `AllocStrategy::Gc` variant + `Default` derive removed (no
    caller of `AllocStrategy::default()` existed in the workspace,
    so the trait derivation was dead). `fn_name` (spec called it
    `runtime_alloc_fn` loosely; actual identifier is `fn_name`)
    drops the `Gc => "GC_malloc"` arm. `lower_workspace` and
    `lower_workspace_staticlib` defaults flip from `Gc` to `Rc`.
    In-source negative-complement codegen test (mod tests, lib.rs:3571ff)
    retargets from `AllocStrategy::Gc` to `AllocStrategy::Bump`
    (bump also doesn't emit per-type drop fns; the test's semantic
    "no drop fns under non-RC" is preserved).

  Link branch — `crates/ail/src/main.rs:2389ff`:
    The `match strategy { AllocStrategy::Gc => { ... cmd.arg("-lgc"); ... } }`
    arm and its libgc-link block are entirely gone. The surviving
    match exhausts on `Bump` and `Rc` (Rust's exhaustiveness check
    confirms; no `error[E0004]`). Staticlib-guard diagnostic
    rewritten to drop the "shared Boehm collector" phrasing while
    preserving the prefix `staticlib (swarm) artefact is RC-only`
    verbatim (the surviving `staticlib_bump_is_rejected` test
    depends on that substring).

  Test suite — 3 pure-differential e2e tests deleted
    (`gc_handles_recursive_list_construction`,
    `alloc_rc_produces_same_stdout_as_gc`,
    `alloc_rc_matches_gc_on_std_list_demo`); 9 RC-feature tests
    stripped of their `stdout_gc` build call and differential
    `assert_eq!(stdout_gc, stdout_rc, ...)` (absolute
    `assert_eq!(stdout_rc.trim(), "<n>")` pin retained as
    correctness oracle); `staticlib_gc_is_rejected` deleted; new
    milestone-pin `crates/ail/tests/boehm_retirement_pin.rs`
    asserts `ail build --alloc=gc` exits ≠ 0 with stderr containing
    `unknown --alloc value` and `\`gc\``; `examples/gc_stress.ail`
    fixture deleted (no remaining references).

    Implementer expansion (not in plan): `iter17a_local_box_alloca`
    (in `e2e.rs`) carried an IR-shape assertion against
    `@GC_malloc`-absence as the witness for non-escaping
    allocation. After the Task-2 codegen default flip, the witness
    shifts to `@ailang_rc_alloc`-absence in escape-targeted
    positions; assertion + doc-comment updated. Property
    protected ("no heap allocation in non-escaping contexts") is
    unchanged; only the named allocator shifts.

  Bench harness — `bench/run.sh` 9→6 column compaction
    (workload + bump(s) + rc(s) + rc/bump + bump RSS + rc RSS);
    gc-arm `bench_latency_implicit_gc` build call + harness
    invocation dropped from latency block; header comment reframed
    from "GC-overhead bench harness" to "RC-overhead bench
    harness"; "Decision 10's Boehm-retirement target (1.3x)"
    rewording to "RC-overhead-vs-bump bench-health regression gate".

    `bench/check.py:62` header-sentinel changes from
    `"gc(s)" in line` to `"bump(s)" in line`; column-count check
    at `:72` flips from `!= 9` to `!= 6`; per-workload field set
    drops `gc_s`/`gc_over_bump`/`gc_rss_kb`; `ARM_LABEL_TO_KEY`
    drops the `"implicit @ gc": "implicit_at_gc"` entry.
    `bench/baseline.json` regenerated via `--update-baseline`.

    Implementer note (planner-defect): `write_new_baseline`
    iterated over the *existing* baseline's metric list when
    emitting the regenerated file, so even after parser-level
    `gc_*` removal, the fallback emitted them back into the JSON.
    Scrubbed post-update; the cleaner fix (have
    `write_new_baseline` emit only keys present in
    `parsed_throughput[workload]`) is a follow-up if the script
    becomes load-bearing for further allocator changes.

  Design ledger — `design/models/rc-uniqueness.md` excises the
    `## Dual allocator — RC canonical, Boehm parity oracle`
    section and the `Boehm-Demers-Weiser conservative GC` choice
    block + rationale + trade-offs; the per-fn-alloca section
    generalises Boehm-specific language to allocator-agnostic;
    the memory-model section's `## Choice.` paragraph reframes the
    1.3× target from "Boehm-retirement gate" to "bench-health
    regression gate".

    `design/models/pipeline.md` drops the `--alloc=gc → links libgc`
    arm of the pipeline diagram and replaces it with
    `--alloc=bump → links bump-floor`; the accompanying prose
    rewrites accordingly.

    `design/contracts/scope-boundaries.md` rewrites the
    "Memory management via Boehm conservative GC" bullet to
    describe RC + per-fn-arena present-tense; the dead reference
    to `examples/gc_stress.ail.json` (file never existed; the
    fixture only ever had a `.ail` form, deleted by this iter) is
    dropped along with the `examples/std_list_stress.ail.json`
    reference whose purpose was Boehm-only soak testing.
    `:67`'s `@printf` / `@GC_malloc` parenthetical updated.

    `design/contracts/memory-model.md:232` drops the
    "leaks like the pre-Boehm era" phrase; the RC inc/dec
    instrumentation is wired up, so the "until then" conditional
    that referenced pre-Boehm is closed.

    `design/contracts/embedding-abi.md:42-44` rewrites the
    staticlib-guard prose to drop the `--alloc=gc` clause (gc is
    now a CLI-parser-level unknown-value, not a staticlib-guard
    rejection) and reframe the swarm-safety justification around
    `--alloc=bump` (leak-only bench instrument) rather than the
    historical Boehm collector.

  Honesty pin — `crates/ailang-core/tests/docs_honesty_pin.rs`
    inverts the polarity: the present-tense Boehm-anchor assertion
    on `pipeline.md` (`:116-117`) is deleted, and four
    absence-pins are added to `design_md_has_no_wunschdenken`
    against the Boehm-zombie strings `transitional Boehm`,
    `parity oracle`, `GC_malloc`, `libgc`. The
    `design_corpus()` already includes `rc-uniqueness.md` so no
    path-list change was needed for the new pins to scan.

    `crates/ailang-core/tests/design_index_pin.rs:166` drops the
    `"pre-Boehm"` token from the protected-exception comment list
    (the phrase no longer appears in `memory-model.md` after this
    iter, so the exception is dead).

  Runtime docs — `runtime/bump.c`, `runtime/rc.c`, `runtime/str.c`
    header comments scrubbed of Boehm/`GC_malloc`/`libgc`
    references. `bump.c`'s function signature description still
    documents `void *bump_malloc(size_t)` as the bench-floor
    allocator interface, but no longer cross-references libgc.

  Example fixtures — `examples/bench_latency_implicit.ail`,
    `bench_latency_explicit.ail`, `escape_local_demo.ail`,
    `reuse_as_demo.ail`, `rc_pin_recurse_implicit.ail` doc-comment
    headers scrubbed of `--alloc=gc` / Boehm references. The
    `.ail` surface (AST) is untouched in every case; round-trip
    invariant holds (`cargo test -p ailang-surface --test round_trip`
    green).

  Skill / agent prompts — `skills/audit/agents/ailang-bencher.md`
    rewritten to use an RC-vs-bump worked example pattern for the
    hypothesis-driven bench tutorial, replacing the recurring
    "RC vs Boehm under heap pressure" example.
    `skills/implement/agents/ailang-implementer.md` Decision-10 /
    Boehm references replaced with present-tense RC-commitment
    framing.

  IR snapshots — the 5 checked-in snapshots
    (`crates/ail/tests/snapshots/{hello,list,max3,sum,ws_main}.ll`)
    regenerated via `UPDATE_SNAPSHOTS=1 cargo test -p ail --test
    ir_snapshot`. Each previously contained
    `declare ptr @GC_malloc(i64)` and (for `list.ll`) a `call ptr
    @GC_malloc(...)` invocation; post-flip the snapshots contain
    `declare ptr @ailang_rc_alloc(i64)` plus the rc inc/dec runtime
    declarations.

Spec-vs-acceptance addendum (caught at orchestrator end-report,
absorbed here rather than in a follow-up spec edit): spec §6
acceptance criteria said "Boehm-grep returns matches ONLY in
docs_honesty_pin.rs". The plan itself prescribed historical Boehm
references in 3 additional files: (a) the new milestone-pin
`boehm_retirement_pin.rs` (must literally invoke `--alloc=gc` to
assert its rejection), (b) `embed_staticlib_alloc_guard.rs` file
doc-comment historical note ("`--alloc=gc` no longer exists as a
CLI value"), (c) `embedding-abi.md:44-45` contract historical
clause ("see the Boehm-retirement iter"). All three are
prescribed; the spec's grep wording was too narrow. The four
absence-pins in `docs_honesty_pin.rs` catch the actual zombies
(Boehm-narrative re-emerging in the design ledger), which is the
substantive intent the spec was aiming at — the four extra
documented-by-design exceptions are the cost of having an
explicit milestone-pin and contract-level historical anchors.

Net delta:
  - 32 files modified, 2 new (boehm_retirement_pin.rs + stats),
    1 deleted (gc_stress.ail);
  - workspace tests: every binary `0 failed`. Pass-count delta:
    -3 net (4 e2e tests deleted, 1 new milestone-pin test added);
  - boehm-grep state: hits only in the four by-design exceptions
    documented above;
  - `bench/check.py` exit 0 against regenerated baseline;
  - CLI must-fail fixture: `ail build --alloc=gc examples/hello.ail`
    exits non-zero with stderr containing `unknown --alloc value`
    and `\`gc\``;
  - design ledger present-tense honest (Boehm-narrative gone from
    `rc-uniqueness.md` + `pipeline.md`; the few historical
    references in `embedding-abi.md` / `boehm_retirement_pin.rs` /
    `embed_staticlib_alloc_guard.rs` are explicit milestone-pins
    or contract anchors, not silent ledger residue).

Bench measurement variance noted: closure-chain and hof-pipeline
are ±1-5% jittery between runs; one regeneration flagged 2
metrics as `regressed` before a second run returned 0. The
captured baseline is within self-comparison range. Existing
per-metric tolerances absorb the jitter.

Stats file:
`bench/orchestrator-stats/2026-05-20-iter-boehm-retirement.1.json`.

closes #4

2026-05-20 20:51:53 +02:00

audit

iter boehm-retirement.1 (DONE 10/10): retire the transitional Boehm GC backend

2026-05-20 20:51:53 +02:00

boss

Update SKILL.md

2026-05-20 16:47:09 +02:00

brainstorm

workflow: add BLOCKER Gitea label — preempts everything in /boss

2026-05-20 15:33:40 +02:00

debug

workflow: replace per-iter journal system with git log + BLOCKED.md

2026-05-20 11:21:37 +02:00

docwriter

workflow: replace docs/roadmap.md with Gitea issue backlog

2026-05-20 14:48:27 +02:00

fieldtest

workflow: replace docs/roadmap.md with Gitea issue backlog

2026-05-20 14:48:27 +02:00

implement

iter boehm-retirement.1 (DONE 10/10): retire the transitional Boehm GC backend

2026-05-20 20:51:53 +02:00

planner

workflow(plan-recon): require compile-driven enumeration + existence table

2026-05-20 18:26:54 +02:00

README.md

workflow: delete docs/journals/ and docs/journal-archive.md

2026-05-20 11:25:15 +02:00

README.md

AILang Skill System

This directory holds the project-local development skills. A skill is a SKILL.md plus the agents that skill primarily dispatches. Skills formalise the AILang development cycle into named, trigger-bound discipline so the orchestrator (me) cannot accidentally diverge from established practice without explicitly violating a named rule.

The system was bootstrapped on 2026-05-09. See docs/specs/2026-05-09-skill-system.md for the design; the bootstrap rationale lives in the commits from that week.

The eight skills

Skill	Trigger	Output	Mandatory?
`brainstorm`	New milestone starting	`docs/specs/<milestone>.md`	Hard-gate before plan
`planner`	New iteration within an open milestone	`docs/plans/<iteration>.md`	Hard-gate before implement
`implement`	Plan exists	Code + tests (and `BLOCKED.md` on PARTIAL/BLOCKED), all uncommitted in the working tree	Standard iteration path
`audit`	Milestone closing OR baseline drift suspected	Drift report + bench-regression report	Mandatory at milestone close
`docwriter`	API surface stabilized; rustdoc lag suspected	rustdoc updates in `///` and `//!`, uncommitted in the working tree	No — Boss-dispatched only
`fieldtest`	Boss-dispatched post-audit field test on a milestone that touched user-visible surface	2-4 `.ail` example fixtures + `docs/specs/<date>-fieldtest-<milestone>.md`, all uncommitted in the working tree	No — Boss-dispatched only
`debug`	Bug encountered (failing test, segfault, wrong stdout)	RED-test in the working tree (uncommitted) + cause analysis	Mandatory RED-first for any bug
`boss`	User-invoked only (`/boss`)	Autonomous orchestration session — dispatches existing skills until done-state or bounce-back	No — user-gated

Pipeline

Inside a /boss session the orchestrator walks this pipeline autonomously. Outside /boss, the pipeline runs only when the user explicitly invokes a skill.

[new milestone]                                  [bug observed]
       |                                                |
       v                                                v
 brainstorm  ->  plan  ->  implement                  debug -> implement (mini)
       (per iteration loop)
                  |
       [milestone close]
                  |
                  v
                audit  --(drift)--> plan + implement (tidy iteration)
                       --(ratify)-> --update-baseline + ratify paragraph in audit commit body
                       --(clean)-+
                                 |
                       [Boss: iter complete? if surface-touch:]
                                 v
                            fieldtest --(bug)------> debug -> implement (mini)
                                      --(friction)-> brainstorm OR plan (tidy)
                                      --(spec_gap)-> ratify OR tighten design/ ledger
                                      --(clean)----+
                                                   |
                                       [Boss: surface stable across N milestones?]
                                                   v
                                              docwriter (rustdoc sweep)
                                                   |
                                                   v
                                            next milestone

Skipping rules are codified in each SKILL.md. Ad-hoc skipping is forbidden by design.

Agent roster

Agents live next to the skill that primarily dispatches them. There are no orphan agents (an anti-pattern after the 2026-05-09 build-out).

Agent	Path	Dispatched by skill
`ailang-grounding-check`	`brainstorm/agents/`	`brainstorm` (Step 7.5; spec grounding hard-gate)
`ailang-plan-recon`	`planner/agents/`	`planner` (Step 2; read-only file-structure mapping); `brainstorm` (ad-hoc Step 1 in unfamiliar territory)
`ailang-implement-orchestrator`	`implement/agents/`	`implement` (the dispatched agent; runs the entire per-task loop inline in its own context)
`ailang-implementer`	`implement/agents/`	phase reference for `ailang-implement-orchestrator` Phase 2.1 (implementer mindset, carries TDD as an independent layer); not dispatched as a separate subagent
`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 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 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 summary the orchestrator (or a skill) reads to decide whether to dispatch.

Agent structure

Every agent file follows the same superpowers-derived template:

Frontmatter: name, description (third-person, "Use when…" or description of role), tools.
Spirit-letter lead-in: > Violating the letter of these rules is violating the spirit.
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/INDEX.md, git log --format=full for recent state, 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.
Iron Law: the non-negotiable rules of the role.
The Process: numbered steps.
Status protocol: structured terminal status the controller acts on. For implementer / tester / debugger / bencher / docwriter: DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED. For reviewers: role-specific (compliant / non_compliant / unclear / infra_blocked for spec; approved / changes_requested / infra_blocked for quality).
Output format: word-budgeted, structured.
Common Rationalisations: excuse → reality table, calibrated to past failure modes.
Red Flags — STOP: bullet list of "if you're about to do this, stop" signals.

TDD as an independent layer

Note that ailang-implementer carries Test-Driven Development as an independent discipline, not just as plan-template fallout. Even if the plan task forgot to script a RED-first step, the implementer adds it inline before writing production code. This mirrors the superpowers split: subagent-driven-development (orchestration, outer loop) is in skills/implement/SKILL.md; test-driven-development (per- task, inner loop) is in skills/implement/agents/ailang-implementer.md. The two skills exist at different layers and stack.

Discovery

Two symlink sets, both tracked in git, no setup needed after clone:

Skills are reachable under .claude/skills/ so Claude Code's Skill tool can invoke them:

.claude/skills/brainstorm -> skills/brainstorm
.claude/skills/planner    -> skills/planner
.claude/skills/implement  -> skills/implement
.claude/skills/audit      -> skills/audit
.claude/skills/docwriter  -> skills/docwriter
.claude/skills/fieldtest  -> skills/fieldtest
.claude/skills/debug      -> skills/debug

Agents are reachable under .claude/agents/ so subagent dispatch can find them by subagent_type:

.claude/agents/brainstorm  -> skills/brainstorm/agents
.claude/agents/planner    -> skills/planner/agents
.claude/agents/implement  -> skills/implement/agents
.claude/agents/audit      -> skills/audit/agents
.claude/agents/docwriter  -> skills/docwriter/agents
.claude/agents/fieldtest  -> skills/fieldtest/agents
.claude/agents/debug      -> skills/debug/agents

Conventions

Only the Boss commits. No skill agent — implementer, brainstormer, planner, debugger, fieldtester, docwriter, architect, bencher — performs git commit. Agents write their artefacts (spec, plan, code, tests, fixtures, rustdoc edits, RED tests, stats files, updated baselines, BLOCKED.md on PARTIAL/ BLOCKED) to the working tree as unstaged changes. The Boss inspects with git status / git diff and commits when there is something consistent to commit. Per-task or per-phase commits are not a goal; the iter (or the cohesive change) is the unit of commit. BLOCKED.md is never committed by convention.
main HEAD is sacrosanct. No actor (Boss or agent) runs git reset or git revert on main. main moves forward only via Boss commits; bad work stays in the working tree where it is still discardable via git checkout -- <path> (Boss-side, not on main HEAD).
No orphan agents. Every agent lives under the skill that dispatches it. If a recurring need does not fit any skill, raise it with the user (or in a /boss session, surface the question via notify) before adding the agent.
Agents do not call other agents. The dispatching skill composes (e.g. audit dispatches architect, then bencher). No agent receives the Agent tool in its frontmatter — Claude Code does not permit a subagent to spawn other subagents. The ailang-implement-orchestrator, which historically was framed as a named exception, runs its per-task phases as sequential role-switches inside its own context (implementer phase → spec check → quality check); see skills/implement/SKILL.md for the mechanism.
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/INDEX.md, git log --format=full for recent state, 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 through git. Commit messages name why the role shifted.

Adding a new skill

Decide what triggers it and what it produces.
Write skills/<name>/SKILL.md with frontmatter (name, description starting "Use when…"). Keep the description trigger-focused; never a workflow summary.
If the skill dispatches subagents, add them under skills/<name>/agents/ and create .claude/agents/<name> as a symlink to that directory.
Update this file (skill table + agent roster).
If the skill replaces or supersedes a CLAUDE.md section, migrate that section: leave a one-line pointer in CLAUDE.md.

Adding a new agent

Decide which skill primarily dispatches it.
Add the .md file under that skill's agents/ directory.
Update the agent roster above and the dispatching skill's "Cross-references" section.
If the agent is genuinely standalone (no skill dispatches it), raise the question with the user first.