iter design-ledger-formal-links.1 (DONE 5/5): clause-5 hard gate + 7 prose-ref conversions + 2 disposition-(b) homeless removals + honesty-rule positive-half (whole milestone in one iter)

Positive-half completion of the DESIGN.md -> design/ split: design/ body cross-references are now formal, file-relative Markdown links into the durable tier (design/ or source), and a new in-tree hard gate (design_index_pin.rs clause-5, design_body_links_are_durable_and_resolve) walks every design/contracts/*.md + design/models/*.md, strips fenced code (strip_fences toggles on ```/~~~ lines so a ]( inside a fence is not treated as a link), extracts every ](path), and asserts the target resolves file-relative to a real file under design/-or-crates/-or- runtime/; never docs/, never an in-file #anchor. RED-first via identity-stubbed strip_fences (four embedded synthetic vectors -- first one FAILS); replacing the stub with the real toggle-on-fence impl turns the test GREEN. clause-5 composes with clause-3 into the complete invariant the milestone establishes: every contract cross-reference is EITHER a resolving durable file-link OR clause-3-forbidden decision-record prose. Conversions (recon-and-corpus-verified closed set): Task 2 (7 prose refs, 8 link tokens): float-semantics.md:69 Prelude classes -> [..](typeclasses.md) float-semantics.md:100 bare-path -> [Str ABI](str-abi.md) embedding-abi.md:45 "Frozen value layout" -> [..](frozen-value-layout.md) (drop stale "below") memory-model.md:44 Data model -> [..](data-model.md) memory-model.md:105-106 Method dispatch -> [..](typeclasses.md) (drop stale "below"; the target heading lives in typeclasses.md:227, not in this file) scope-boundaries.md:48 Str ABI -> [..](str-abi.md) scope-boundaries.md:88 mixed split: ailang-core::desugar -> source link + Pipeline -> ../models/pipeline.md (drop stale "above") Task 3 (2 disposition-(b) homeless removals): pipeline.md:60-61 (see docs/PROSE_ROUNDTRIP.md) pointer removed, CLI prose preserved authoring-surface.md:178-181 cross-tier pointer clause removed, ail merge-prose sentence preserved Task 4: honesty-rule.md positive-half paragraph inserted between L14 and the existing L15-blank-L16; both docs_honesty_pin.rs-pinned phrases byte-identical at L14/L19 (now shifted to L19 -> L25 by the +6 lines). Out of scope, preserved (asserted independently): every intra-file "above/below"; embedding-abi.md:51 "frozen value layout below specifies" (no quoted title, no (see) form); data-model.md 38/66/79/206/226 (in-fence ```jsonc schema annotations -- the inline analog of the nominal-mention carve-out). INDEX.md and the decision-records journal byte-unchanged; clauses 1-4 of design_index_pin.rs source byte-unchanged (the only `-` lines in the diff are the two-line //! header rewrite Task 1 Step 5 itself delivers). Boss-verified independently (not on agent report alone): cargo test --workspace 647 passed / 0 failed (+1 vs pre-milestone 646: the new clause-5) cargo test --test design_index_pin 5 / 5 passed cargo test --test docs_honesty_pin 5 / 5 passed (additive paragraph is pin-safe) grep ](.../docs/.../) under design/ zero grep ](#) under design/ zero ](-link count under design/ 8 (closed convert-set) git diff --quiet design/INDEX.md ok git diff --quiet decision-records ok embedding-abi.md:48 pinned phrase byte-identical One Concerns item: Task-5 Step-7's plan-predicted "`-` line count = 1" was actually 2 because Task 1 Step 5 rewrote the //! header 5 -> 8 lines (removing the original L4 + L5, not just L5). Planner self- review-item-8 miss on my part -- a verification-arithmetic error in the plan, NOT an implementation defect. The substantive assertion (clauses 1-4 source byte-unchanged) is fully satisfied; the implementer correctly flagged it and proceeded. The plan stands as written; the assertion's `1` should have been `2`. Lesson noted for future header-rewrite tasks. Spec: docs/specs/2026-05-19-design-ledger-formal-links.md (grounding-check PASS x3 across two corpus-grounded amendments -- clause-6 + cross-ref definition; clause-5 fence-skip + closed convert-set enumeration). Next: mandatory milestone-close audit (no fieldtest -- zero authoring-surface change, reasoned exclusion).
2026-05-19 23:31:30 +02:00
parent 36599bedd9
commit 8ad91e7f24
11 changed files with 258 additions and 13 deletions
@@ -42,7 +42,7 @@ exact. The swarm artefact is data-race-free, sanitiser-verified.
 The staticlib swarm artefact is **RC-only**:
 `ail build --emit=staticlib` rejects `--alloc=gc`/`--alloc=bump`
 (the shared Boehm collector is not swarm-safe). The value/record
-layout is **frozen as of M3** (see "Frozen value layout" below); the
+layout is **frozen as of M3** (see [Frozen value layout](frozen-value-layout.md)); the
 ctx-threaded C signature is the M2 shape.

 Export parameters are written **bare**: a scalar type carries no
@@ -66,7 +66,7 @@ no `f32` variant. The runtime / codegen contract:

 The same libc-`%g` rendering applies to `show 1.5` / `show nan` /
 `show inf` via `instance Show Float` (which calls `float_to_str`
-internally — see §"Prelude (built-in) classes" for the Show ship).
+internally — see [Prelude (built-in) classes](typeclasses.md) for the Show ship).
 The NaN-spelling caveat above is observable via `do print x` for
 Float-typed `x`; the rendering is libc-version-dependent and
 target-libc-specific. AILang does NOT canonicalise Float textual
@@ -97,7 +97,7 @@ LLM-author wants. Use ordering operators (`<`, `>`, ...) and

 `float_to_str` (Float → Str) and `int_to_str` (Int → Str) are
 fully wired through checker, codegen, and runtime. Both allocate
-a fresh heap-Str slab at the call site (see design/contracts/str-abi.md
+a fresh heap-Str slab at the call site (see [Str ABI](str-abi.md)
 for the dual realisation) and carry `ret_mode: Own` so the let-binder
 for the call result is RC-tracked and the slab is freed at scope
 close.
@@ -13,6 +13,12 @@ Two things never belong in a contract or model file:
  Decision-records are journal content, not ledger content; this is
  the honesty rule it holds itself to.

+A cross-reference that does belong stays: it is a formal,
+file-relative Markdown link into the durable tier (`design/` or
+source), enforced by `design_index_pin.rs` clause-5. A reference
+that cannot be expressed as such a link is, by that fact, the
+history-or-rationale prose the rule above removes.
+
 The single legitimate exception is a present-tense reserved or
 deliberately-excluded claim that is explicitly and correctly
 labelled. The discriminator is not whether a sentence mentions past
@@ -41,7 +41,7 @@ The form-A surface for fn signatures gains mode wrappers:

 Internally, this is *not* a new `Type` variant. Modes are
 metadata on `Type::Fn` — `paramModes` and `retMode` fields run
-parallel to `params` and `ret` (see §"Data model" for the JSON
+parallel to `params` and `ret` (see [Data model](data-model.md) for the JSON
 schema). The substantive reasons for per-position metadata over a
 `Type::Borrow` / `Type::Own` variant approach:

@@ -102,8 +102,8 @@ Three schema fields carry class references in this form:
 `ClassDef.name` itself stays bare (defining-site context, like
 `TypeDef.name`).

-Method dispatch is type-driven post-mq.3 (see §"Method dispatch"
-below): synth resolves a `Term::Var { name: "show" }` by consulting
+Method dispatch is type-driven post-mq.3 (see [Method dispatch](typeclasses.md)):
+synth resolves a `Term::Var { name: "show" }` by consulting
 the workspace's method-to-candidate-class index, filtering by
 argument type (concrete) or by declared constraint (rigid-var), and
 routing the residual through the registry at fn-body-end discharge.
@@ -45,7 +45,7 @@ What **is** supported (and used as the smoke test for the pipeline):
  `float_to_int_truncate : (Float) -> Int` (saturating, NaN → 0),
  `float_to_str : (Float) -> Str`,
  `int_to_str : (Int) -> Str` (both allocate a heap-Str slab at
-  call time and return it with `ret_mode: Own`; see "Str ABI" for
+  call time and return it with `ret_mode: Own`; see [Str ABI](str-abi.md) for
  the dual heap-/static-Str realisation); inspection
  `is_nan : (Float) -> Bool` (LLVM
  `fcmp uno`); Float bit-pattern constants `nan : Float`,
@@ -85,7 +85,7 @@ What **is** supported (and used as the smoke test for the pipeline):
  another `Ctor`, or a literal. The desugar pass flattens
  nested Ctor patterns into a chain of let + match and rewrites every
  `Pattern::Lit` (top-level or sub-) to a `Term::If` on `==` before
-  typecheck/codegen — see `ailang-core::desugar` and Pipeline above.
+  typecheck/codegen — see [desugar](../../crates/ailang-core/src/desugar.rs) and [Pipeline](../models/pipeline.md).
 - Literal patterns at top level and inside Ctor sub-patterns (via desugar).
  `(pat-lit 0)` and `(pat-ctor Cons (pat-lit 0) _)` both
  parse and lower; the rewrite is to `Term::If { cond = (== sv lit) }`,
@@ -177,8 +177,8 @@ human readers. Form (B) inverts the trade-offs:
 Critically, **form (B) has no parser**. Form (A) is round-trippable
 by construction (Decision 6 constraint 2); form (B) deliberately is
 not. Re-integrating prose edits requires an external LLM mediator,
-not a compiler pass — see `docs/PROSE_ROUNDTRIP.md` for the
-six-step cycle and the prompt template `ail merge-prose` composes.
+not a compiler pass — the prompt template `ail merge-prose`
+composes the six-step cycle.

 Form (B) does not weaken any Decision 6 invariant:

@@ -58,7 +58,6 @@ ail parse     <module.ail>              — form-A text → canonical JSON-AST
 ail prose     <module.ail.json>          — JSON-AST  → form-B (lossy human prose, no parser)
 ail merge-prose <m.ail.json> <m.prose.txt>
                                         — compose the LLM-mediator prompt for the prose round-trip
-                                           (see docs/PROSE_ROUNDTRIP.md)
 ail deps      <module.ail.json>          — list cross-module references
 ail diff      <a.ail.json> <b.ail.json>  — content-addressed def-level diff
 ail workspace <entry.ail.json>           — list all modules transitively reachable from entry