design/ + source rustdoc: replace opaque shorthand with content phrases + links

Reader-facing prose and rustdoc carried opaque shorthand like
"Decision 10", "clause-5", "mq.1", "ct.1", "eob.1", "rpe.1",
"post-mq.3", and "Iter 22b.1:" with no in-repo definition the reader
could follow. This commit replaces every such occurrence in the
durable tier the reader is most likely to land on (design/ ledger +
source //! module headers + the central /// public-item rustdoc) with
an inline content phrase plus, where applicable, a Markdown link to
the file that defines the referenced concept.

design/ ledger — 16 files:
  Definition-site headings demoted from "Decision N: <title>" to
  "<title>": authoring-surface, tail-calls, memory-model section in
  rc-uniqueness.md, dual-allocator section, typeclass design,
  effects "pure core + algebraic effects".
  Cross-reference sites: "Decision 1" -> canonical-schema principle
  (data-model); "Decision 3/4" -> effects + scope-boundaries; "Decision
  6" -> authoring-surface; "Decision 8" -> tail-calls; "Decision 9" ->
  rc-uniqueness (dual-allocator); "Decision 10" -> memory-model;
  "Decision 11" -> typeclasses (model). "clause-5" -> body-link
  durability gate. "clause-3" (in language-constraints) ->
  bug-class-reintroduction discriminator. "mq.1/2/3", "ct.1/4",
  "eob.1", "rpe.1" -> the canonical-form rule / the type-driven
  dispatch / the Str carve-out / etc. "post-mq.3" -> "type-driven".

design/contracts/feature-acceptance.md: file-local "clauses 1/2/3"
-> "criteria 1/2/3" (sprachliche Kohärenz mit der File-Überschrift
"Feature-acceptance criterion"); "the clause-3 mechanism" -> "the
bug-class-reintroduction discriminator".

Source //! module headers — 24 files:
  Stripped "Iter X.Y:" prefixes and "(Decision N)" / "(mq.X)" tags
  from spec_drift, uniqueness, reuse_shape, migrate_canonical_types,
  typeclass_22b{2,3,c}, suppress_filter, lift, mono, linearity,
  diagnostic, method_dispatch_pin, method_collision_pin,
  no_per_type_print_ops, mq3_multi_class_e2e, print_mono_body_shape,
  print_no_leak_pin, cli_diag_human_workspace_load_error,
  ct1_check_cli, prose snapshot, unbound_in_instance_method_pin,
  mono_xmod_ctor_pattern, desugar.

Central /// public-item rustdoc:
  ast.rs (full sweep — every "Iter X" + "Decision N" prefix
  reformulated; mode/Type::Fn rustdoc now points at memory-model.md;
  Constraint / SuperclassRef / InstanceDef / ClassDef rustdoc points
  at typeclasses contract).
  diagnostic.rs (all "(Iter X)" / "(mq.X)" tags on diagnostic codes
  removed).
  lib.rs (FORM_A_SPEC rustdoc points at authoring-surface.md
  instead of "Decision 6").
  canonical.rs (type_hash + Float-literal rustdoc).

Still outstanding (for a follow-up commit): ~500 inline `//`
code-body comments with `Iter X.Y` markers across the workspace, and
a handful of `///` rustdoc items in hash_pin / workspace_pin / lift /
mono / suppress_filter test-pin and internal-function bodies. Code
identifiers (test filenames like `mq3_multi_class_e2e.rs`, function
names like `iter18e_drop_iterative_default_preserves_hashes`) stay
verbatim per the user's "code identifiers stay verbatim" rule.

Tests: design_index_pin 5/5 + docs_honesty_pin 5/5; workspace builds
clean; full `cargo test --workspace` previously green (every
`test result: ok` line, no FAILED line).

crates/ail/tests/cli_diag_human_workspace_load_error.rs

@@ -1,4 +1,4 @@
-//! Iter cli-diag-human (2026-05-14): non-JSON `ail check` and
+//! Human-readable CLI diagnostics (2026-05-14): non-JSON `ail check` and
 //! sibling subcommands surface `WorkspaceLoadError` with the same
 //! bracketed `[code]` prefix that the JSON path emits.
 //!

crates/ail/tests/ct1_check_cli.rs

@@ -1,4 +1,4 @@
-//! ct.1: E2E coverage for the CLI surface of the canonical-type-names
+//! E2E coverage for the CLI surface of the canonical-type-names
 //! validator. The unit tests in `workspace.rs` already prove the
 //! validator fires; these tests prove the diagnostic survives the
 //! `WorkspaceLoadError -> Diagnostic` translation in

crates/ail/tests/migrate_canonical_types.rs

@@ -1,4 +1,5 @@
-//! ct.1: E2E test for `ail migrate-canonical-types <dir>`.
+//! E2E test for `ail migrate-canonical-types <dir>` (the
+//! canonical-form migration for `Type::Con.name`).
 //!
 //! Builds a synthetic workspace in a tempdir with one fixture that
 //! has a bare cross-module Type::Con ref, runs the migration, then

crates/ail/tests/mono_xmod_ctor_pattern.rs

@@ -4,7 +4,8 @@
 //! by `mono::build_workspace_env`, which delegates to `crate::build_check_env`
 //! and produces a workspace-flat `ctor_index` and `types` map.
 //!
-//! Post-ct.2, `Pattern::Ctor` lookup is type-driven — it consults the
+//! After the canonical-form / type-driven-ctor-lookup refactor,
+//! `Pattern::Ctor` lookup is type-driven — it consults the
 //! scrutinee's canonical `Type::Con.name` to find the TypeDef directly
 //! in `env.module_types`, then validates the ctor name within it. The
 //! mono pass's flat `ctor_index` is no longer consulted by this path;
@@ -14,14 +15,16 @@
 //!
 //! This test pins the cross-module pattern shape against a minimal
 //! 2-module fixture (`test_mono_ctor_main` + `test_mono_ctor_listmod`).
-//! Pre-ct.2 the bug surfaced as `PatternTypeMismatch { ctor: "Cons",
+//! Before the refactor the bug surfaced as
+//! `PatternTypeMismatch { ctor: "Cons",
 //! ty: "test_mono_ctor_listmod.List<Int>" }` because the mono env
-//! resolved `Cons` to bare `List` via the flat index. Post-ct.2 the
-//! lookup is type-driven and `expected.name == "test_mono_ctor_listmod.List"`
-//! directly indexes the right TypeDef.
+//! resolved `Cons` to bare `List` via the flat index. After the
+//! refactor the lookup is type-driven and
+//! `expected.name == "test_mono_ctor_listmod.List"` directly indexes
+//! the right TypeDef.
 //!
-//! Surfaced by iter 23.2 Task 3, which adds `class Eq a` + Eq Int/Bool/Str
-//! instances to `examples/prelude.ail.json`, flipping the
+//! Surfaced when `class Eq a` + Eq Int/Bool/Str instances were added
+//! to `examples/prelude.ail.json`, flipping the
 //! `workspace_has_typeclasses` gate so every workspace exercises the
 //! mono pass.
 

crates/ail/tests/mq3_multi_class_e2e.rs

@@ -1,4 +1,4 @@
-//! mq.3.6: end-to-end coverage of the post-`MethodNameCollision`-
+//! End-to-end coverage of the post-`MethodNameCollision`-
 //! retirement multi-candidate dispatch path. Three positive fixtures
 //! exercise the three trajectories from the milestone spec
 //! §"Data flow":

crates/ail/tests/print_mono_body_shape.rs

@@ -4,7 +4,8 @@
 //! structurally `Term::Let { name: "s", value: App(show__Int, [x]),
 //! body: Term::Do { op: "io/print_str", args: [s] } }`. The explicit
 //! let-binder around `show__Int x` is load-bearing for the heap-Str RC
-//! discipline (eob.1 Str carve-out at `drop_symbol_for_binder` requires
+//! discipline (the heap-Str Str carve-out at
+//! `drop_symbol_for_binder` requires
 //! a let-binder to attach the rc-dec to). If a future codegen / mono
 //! refactor inlines the let-binder away, this pin fires and surfaces
 //! the regression BEFORE the E2E runtime stats produce a confusing

crates/ail/tests/print_no_leak_pin.rs

@@ -1,4 +1,5 @@
-//! RED-pin for the 2026-05-14 rpe.1 Cat-A heap-Str leak in `print`.
+//! RED-pin for the 2026-05-14 Cat-A heap-Str leak in `print`
+//! (uncovered during the per-type-print-op retirement).
 //!
 //! Property protected: under `--alloc=rc`, evaluating the trivial
 //! program `(body (app print 42))` does NOT leak the heap-Str

crates/ail/tests/typeclass_22b2.rs

@@ -1,6 +1,7 @@
-//! Iter 22b.2 typeclass typecheck arms — integration tests.
+//! Typeclass typecheck arms — integration tests.
 //!
-//! This file is shared by 22b.2 tasks: it exists from Task 8
+//! This file holds the cluster of typeclass typecheck-arm integration
+//! tests; it exists from Task 8
 //! (class methods register into module globals) and is extended by
 //! Tasks 9 (`missing-constraint`) and 10 (`no-instance`).
 

crates/ail/tests/typeclass_22b3.rs

@@ -1,4 +1,4 @@
-//! Iter 22b.3: monomorphisation pass tests.
+//! Monomorphisation pass tests.
 //!
 //! Co-located with `typeclass_22b2.rs` so the typeclass-feature
 //! coverage is browsable in one directory. Tests use the same

crates/ail/tests/typeclass_22c.rs

@@ -1,6 +1,6 @@
-//! Iter 22c: milestone-22 acceptance — user-defined classes with
-//! instances over user-defined ADTs end-to-end (typecheck → mono →
-//! codegen → binary). The 22b.3 mono pass was tested only against
+//! Milestone-22 acceptance: user-defined classes with instances over
+//! user-defined ADTs end-to-end (typecheck → mono → codegen →
+//! binary). The mono pass was previously tested only against
 //! instances over primitive types; this file pins the user-ADT path.
 //!
 //! Co-located with `typeclass_22b3.rs` so the typeclass-feature

crates/ail/tests/unbound_in_instance_method_pin.rs

@@ -23,8 +23,9 @@
 //! Root cause (from debugger Phase 1-2):
 //! `crates/ailang-check/src/lib.rs::check_def` early-returns `Ok(())`
 //! for `Def::Class | Def::Instance` (the comment claims body
-//! typechecking landed in iter 22b.2, but the body-walk was never
-//! wired). Only the workspace-load coherence checks
+//! typechecking landed alongside the typeclass-typecheck arms, but
+//! the body-walk was never wired). Only the workspace-load coherence
+//! checks
 //! (Orphan/Duplicate/MissingMethod) in `workspace::build_registry`
 //! touch instance defs, and those only inspect the schema, not the
 //! method-body identifier graph.