AILang/docs/journals/2026-05-12-iter-ext-rename.md

# iter ext-rename — `.ailx` extension renamed to `.ail` across the live toolchain

**Date:** 2026-05-12
**Started from:** 17b370b (post-audit-ms close, working tree clean)
**Status:** DONE
**Tasks completed:** 1 of 1

## Summary

The surface-form file extension changes from `.ailx` to `.ail`.
AILang's authoring surface now uses the same `.ail` stem as its
canonical JSON form (`.ail.json`), giving the language a single
coherent extension family: `.ail` is the LLM-authored Form A;
`.ail.json` is the canonical JSON-AST Form B that
`ail check` / `build` / `run` actually loads today.

The earlier `.ailx` extension carried an unmotivated `x`. The
cross-model authoring-form test (cma + ms milestones, closed
earlier today) treated `.ailx` purely as a cohort identifier;
once the empirical case for keeping a separate authoring surface
had been ratified (DESIGN.md §Decision-6 addendum), the awkward
extension was the last asymmetry between Form A and Form B.
User-initiated rename.

## Scope

In scope (touched):

- 61 example files `examples/**/*.ailx → .ail` (57 top-level +
  4 `examples/fieldtest/`) renamed via `git mv`.
- `experiments/.../rendered/ailx.md → ail.md` rename.
- All live toolchain prose and code: `crates/ail/`,
  `crates/ailang-surface/`, `crates/ailang-core/specs/form_a.md`,
  `docs/DESIGN.md`, `docs/roadmap.md`, `docs/PROSE_ROUNDTRIP.md`,
  `bench/reference/*.c`, all of `skills/`, the Cross-Model
  Authoring experiment crates under
  `experiments/.../{render,harness,master,rendered,README.md}`.
- Cohort identifier `ailx → ail` in the experiment crate (Rust
  `Cohort::Ailx → Cohort::Ail`, `Form::Ailx → Form::Ail`,
  per-cohort path component, `{form-only: ailx}` marker,
  ```ailx codefence language tag).

Out of scope (untouched, by design):

- `docs/journal-archive.md` (content-frozen per CLAUDE.md).
- All `docs/journals/`, `docs/specs/`, `docs/plans/`,
  `bench/orchestrator-stats/` — historical records describing
  states as they were.
- `experiments/.../runs/` — frozen LLM-output artefacts; the
  models in those runs actually saw `.ailx`, and renaming the
  artefacts would falsify the experimental record.

The exclusion preserves the journals as honest history. Anyone
chasing why a 2026-05-11 fieldtest names `.ailx` files will find
that the renaming happened today and that the names were correct
at the time of writing.

## Why boss-direct edit (no planner / implement dispatch)

Same rationale as iter rt.2: the user fully specified the
transformation (rename `.ailx → .ail`, rename cohort
`ailx → ail`, historical records untouched), down to the three
open questions that were resolved up-front via AskUserQuestion
(cohort name; treatment of frozen runs; treatment of historical
docs). The execution was two `git mv` passes plus one
heavily-scoped `sed` over an explicit 41-file whitelist (plus
two follow-up files surfaced by the negative-grep). No design
judgement deferred to execution time.

## Files touched (working-tree counts)

- 61 renames under `examples/`.
- 1 rename `experiments/.../rendered/ailx.md → ail.md`.
- 35 content-edited files: the 41-file SCOPE whitelist minus
  the experiment-crate files that had no `ailx` content, plus
  two follow-up files surfaced by the negative-grep
  (`examples/bench_list_sum_explicit.ail`'s in-source comment;
  `experiments/.../rendered/json.md` for three `AILX` acronyms
  in prose).

## Verification

- `cargo build --workspace` clean.
- `cargo test --workspace` green; the renamed identifiers
  `every_ail_fixture_matches_its_json_counterpart` and
  `parse_then_print_then_parse_is_idempotent_on_every_ail_fixture`
  in `crates/ailang-surface/tests/round_trip.rs` were run
  explicitly and pass.
- Experiment crate `cargo test` (out-of-workspace) green.
- `bench/check.py`, `bench/compile_check.py`, `bench/cross_lang.py`:
  0 regressed across all three; 6 improved-beyond-tolerance on
  `latency.explicit_at_rc` (same cluster the previous two audits
  today already observed; decoupled from this rename — baseline
  left pristine).
- Negative grep: `git grep -nIi 'ailx|Ailx|AILX'` outside the
  out-of-scope paths returns no matches.

## Roadmap implications

The `.ail` extension is now canonical authoring surface but the
CLI does not yet accept it — `ail check foo.ail` still produces
the misleading JSON-parse error. The existing P2 todo
"`ail check`/`build`/`run` accept `.ail` extension" (roadmap.md
line 185) is the natural next iteration: it closes the loop
opened by today's rename and removes the largest first-command
friction for any LLM-author writing in Form A. Promoting that
todo to the immediate next dispatch.