# Iter form-a.0 — Prelude Pilot — Implementation Plan > **Parent spec:** `docs/specs/0025-form-a-default-authoring.md` > > **For agentic workers:** REQUIRED SUB-SKILL: use `skills/implement` > to run this plan. Steps use `- [ ]` checkboxes for tracking. **Goal:** Render `examples/prelude.ail.json` to its Form-A sibling `examples/prelude.ail` and prove that the existing roundtrip-CI gate (`every_ail_fixture_matches_its_json_counterpart`) plus the parallel idempotency test both pass on the new file, validating the migration mechanism on the hardest single file before iter 1 commits to the bulk test-infrastructure refactor. **Architecture:** One CLI invocation (`ail render`) produces the Form-A text from the canonical JSON-AST. The two relevant tests in `crates/ailang-surface/tests/round_trip.rs` auto-discover fixtures via `read_dir(examples/)`; the freshly added `.ail` lands in their corpus on the next `cargo test` run with no test- code changes. Iter 0 deliberately keeps `prelude.ail.json` on disk alongside the new `.ail` — the JSON counterpart is the byte-witness the gate uses, and that gate is the safety net that makes the pilot worth running. **Tech Stack:** `ail render` CLI subcommand (Form-A printer in `ailang-surface::print`), `crates/ailang-surface/tests/round_trip.rs` (auto-discovering gate + idempotency tests), `docs/journals/` append convention. **Files this plan creates or modifies:** - Create: `examples/prelude.ail` — Form-A rendering of `examples/prelude.ail.json`, ~6386 bytes / 116 lines, produced verbatim by `ail render`. - Create: `docs/journals/2026-05-13-iter-form-a.0.md` — per-iter journal entry. - Modify: `docs/journals/INDEX.md:53` (append-only, one new line at line 54). No source-code edits, no test edits, no CLAUDE.md / DESIGN.md edits. The two existing roundtrip tests pick up the new fixture automatically because both use `read_dir(examples/)` discovery. --- ### Task 1: Render `examples/prelude.ail` and verify both auto-discovering roundtrip tests pass **Files:** - Create: `examples/prelude.ail` - Test (existing, no edit): `crates/ailang-surface/tests/round_trip.rs:120-204` (`every_ail_fixture_matches_its_json_counterpart`) and `crates/ailang-surface/tests/round_trip.rs:216-277` (`parse_then_print_then_parse_is_idempotent_on_every_ail_fixture`). - [ ] **Step 1: Render the prelude via `ail render`** Run from the workspace root: ``` cargo run -q --bin ail -- render examples/prelude.ail.json > examples/prelude.ail ``` The CLI dispatch lives at `crates/ail/src/main.rs:424-427`: ```rust Cmd::Render { path } => { let m = ailang_surface::load_module(&path)?; print!("{}", ailang_surface::print(&m)); } ``` `render` takes a single positional path argument and writes Form-A text to stdout; shell redirection captures it to the target file. Expected: exit 0, no stderr output, `examples/prelude.ail` created. - [ ] **Step 2: Sanity-check the rendered file's shape** Run: ``` wc -lc examples/prelude.ail ``` Expected output (verified during recon): approximately `116 6386 examples/prelude.ail` — exactly 116 lines, 6386 bytes. A different count by more than ±1 line is a signal that the renderer drifted between recon and execution; investigate before continuing. Then verify the file begins with the expected `(module prelude` header by reading the first 5 lines: ``` head -n 5 examples/prelude.ail ``` Expected first line: `(module prelude`. Expected second line: ` (data Ordering`. If the file does not start this way, the render is wrong; do not continue. - [ ] **Step 3: Run the gate test in isolation** This is the spec's named witness for iter 0 (§A2). Run: ``` cargo test -p ailang-surface --test round_trip every_ail_fixture_matches_its_json_counterpart ``` Expected: PASS. The test (`crates/ailang-surface/tests/round_trip.rs:120-204`) walks every `.ail` file under `examples/`, looks up the same-stem `.ail.json` counterpart, and asserts that parsing the `.ail` produces canonical bytes byte-equal to loading the JSON. The freshly added `prelude.ail` (with its retained `prelude.ail.json` counterpart) is the new corpus element this iter introduces; the test must report at least one more fixture passing than the previous run (or the same count if the test summary doesn't print per-file). If the test FAILS on the new prelude: the failure mode is E1 from the spec (a fixture round-trips before migration but the migrated `.ail` fails to parse, or parses to different bytes). The bug is in `ail render` or `ailang_surface::parse`; this iter halts and the bug fix takes precedence. Do NOT delete or alter `prelude.ail` to make the test pass. - [ ] **Step 4: Run the parallel idempotency test** The recon flagged this test as the second one that auto-discovers `.ail` fixtures and would react to the new file. It checks a different property (idempotency under print) and must also pass. Run: ``` cargo test -p ailang-surface --test round_trip parse_then_print_then_parse_is_idempotent_on_every_ail_fixture ``` Expected: PASS. The test (`crates/ailang-surface/tests/round_trip.rs:216-277`) walks every `.ail` file and asserts `canonical(parse(t)) == canonical(parse(print(parse(t))))`. If this fails on the new prelude while the gate test passes, the Form-A printer is non-idempotent on some feature prelude uses — a deeper render bug that the gate test does not catch. Same halt rule: do not alter the rendered file. - [ ] **Step 5: Run the full workspace test suite for regression safety** Run: ``` cargo test --workspace ``` Expected: PASS, identical pass count to pre-iter baseline plus zero (no new tests are added in this iter). The recon explicitly verified that no `.ail.json`-walking test (`print_then_parse_round_trips_every_fixture`, `every_ast_variant_is_observed_in_the_fixture_corpus`, `cli_render_then_parse_preserves_canonical_bytes_on_every_fixture`) has its corpus changed by adding a sibling `.ail`, so the only tests that should react are the two run in Steps 3-4; the full suite is the sanity check that nothing unexpected fires. --- ### Task 2: Write the per-iter journal entry and append the INDEX line **Files:** - Create: `docs/journals/2026-05-13-iter-form-a.0.md` - Modify: `docs/journals/INDEX.md` (append one line at the end of file — current last line is 53). - [ ] **Step 1: Write the journal file** Create `docs/journals/2026-05-13-iter-form-a.0.md` with the following content. The `116 lines / 6386 bytes` figures are the recon-observed values; if Task 1 Step 2 observed different values (it should not, the renderer is byte-stable), use the actual `wc -lc` output and adjust the INDEX line in Step 2 to match. ```markdown # Iter form-a.0 — Prelude Pilot **Date:** 2026-05-13 **Parent spec:** `docs/specs/0025-form-a-default-authoring.md` **Parent plan:** `docs/plans/0059-iter-form-a.0.md` ## Outcome `examples/prelude.ail` rendered from `examples/prelude.ail.json` via `ail render` (116 lines / 6386 bytes). The two auto-discovering roundtrip tests in `crates/ailang-surface/tests/round_trip.rs` both pass on the new fixture without test-code changes: - `every_ail_fixture_matches_its_json_counterpart` — green; the `prelude.ail` parses to canonical bytes byte-equal to `prelude.ail.json`. - `parse_then_print_then_parse_is_idempotent_on_every_ail_fixture` — green; the Form-A printer is idempotent over prelude. `prelude.ail.json` is retained on disk per spec §A2; iter 1 deletes it alongside the bulk test-infrastructure refactor. This is the only iteration in the milestone where a fixture is dual-form. ## Why this iter is the pilot Spec §A2 names prelude as the pilot because it exercises the widest cross-section of language features in a single file: typeclasses with superclasses (`Ord extends Eq`), polymorphic free functions with constraints (`forall where Show a fn print`), IO-effect signatures, primitive ctor patterns, and the loader's auto-injection path. A green roundtrip on prelude is strong evidence the bulk migration in iter 1+ will not surface render or parse bugs. ## Verifications run - `cargo test -p ailang-surface --test round_trip every_ail_fixture_matches_its_json_counterpart` — PASS - `cargo test -p ailang-surface --test round_trip parse_then_print_then_parse_is_idempotent_on_every_ail_fixture` — PASS - `cargo test --workspace` — PASS, no regression ## Scope NOT touched Per spec §"Iteration scope": no test-infrastructure changes, no CLAUDE.md / DESIGN.md edits, no deletion of `prelude.ail.json`, no migration script yet. Those land in iter 1. ``` - [ ] **Step 2: Append the INDEX line** The last existing line in `docs/journals/INDEX.md` is line 53 (iter `24.tidy`). Append one new line at the end of file: ```markdown - 2026-05-13 — iter form-a.0: prelude pilot for Form-A-as-default-authoring milestone — examples/prelude.ail rendered (116 lines / 6386 bytes) via `ail render`; two auto-discovering roundtrip tests (every_ail_fixture_matches_its_json_counterpart + parse_then_print_then_parse_is_idempotent_on_every_ail_fixture) green on the new fixture without test-code changes; prelude.ail.json retained per spec §A2 (singular dual-form iter, deletion lands iter 1 with bulk test-infra refactor); cargo test --workspace green → 2026-05-13-iter-form-a.0.md ``` Adjust the byte/line counts in the line if Task 1 Step 2 observed different numbers. Convention (per INDEX.md header lines 1-7): append-only, one line per iter, newest at the bottom, em-dash between iter id and summary, arrow before the journal filename. No other files modify in this step; INDEX append is the terminal working-tree edit of this iter.