convention: counter-prefix file naming across docs/specs/, docs/plans/, design/contracts/, design/models/

All 176 files in the four accumulating directories now use a
zero-padded 4-digit counter prefix that reflects creation order
(`NNNN-slug.md`). The counter is assigned per directory in strict
git-log creation order; ties broken alphabetically by original name.
The old `YYYY-MM-DD-` prefix on docs/specs/ and docs/plans/ files is
dropped — the date is recoverable from git log and the counter
carries the ordering.

A file's counter is stable for the life of the file: never reassigned,
never reused, never compacted. Deleted files retire their counter;
subsequent files do not fill the gap. This is the property that lets
cross-references stay literal — refs use the full filename including
the counter (`design/contracts/0007-honesty-rule.md`) so they grep
cleanly and resolve directly without a glob step.

313 cross-references updated across .md/.rs/.toml/.c/.json files
(test pins, include_str! paths, design-INDEX entries, baseline notes,
runtime C comments, inter-contract markdown links incl. bare basename
and `../models/foo.md` forms).

CLAUDE.md gets a new "File-naming convention" section spelling out
the rule and rationale. skills/brainstorm/SKILL.md and
skills/planner/SKILL.md updated so new spec/plan creation produces
counter-prefixed names from the start.

The full test suite (cargo test --workspace) passes.
This commit is contained in:
2026-05-28 13:31:31 +02:00
parent 7b8596cef0
commit 832375f2ac
227 changed files with 785 additions and 751 deletions
+2 -2
View File
@@ -85,7 +85,7 @@ impl<'a> Emitter<'a> {
out.push_str(" %is_null = icmp eq ptr %p, null\n");
out.push_str(" br i1 %is_null, label %ret, label %live\n");
out.push_str("live:\n");
// FROZEN ABI (embedding boundary) — see design/contracts/embedding-abi.md.
// FROZEN ABI (embedding boundary) — see design/contracts/0003-embedding-abi.md.
out.push_str(" %tag = load i64, ptr %p, align 8\n");
let n_ctors = td.ctors.len();
@@ -111,7 +111,7 @@ impl<'a> Emitter<'a> {
if lty != "ptr" {
continue;
}
// FROZEN ABI (embedding boundary) — see design/contracts/embedding-abi.md.
// FROZEN ABI (embedding boundary) — see design/contracts/0003-embedding-abi.md.
let off = 8 + (j as i64) * 8;
let addr_id = local;
local += 1;
+3 -3
View File
@@ -174,7 +174,7 @@ pub enum Target {
/// published via `@__ail_tls_ctx` around the unchanged internal
/// call. The ctx-threaded C signature is the M2 shape; the
/// value/record layout is frozen as of M3
/// (design/contracts/frozen-value-layout.md).
/// (design/contracts/0006-frozen-value-layout.md).
StaticLib,
}
@@ -687,7 +687,7 @@ fn llvm_scalar(t: &Type) -> &'static str {
// M3: any other Type::Con reaching an (export) signature is,
// by the Task-2 export gate, a single-ctor scalar record;
// it crosses the C ABI as a bare `ptr`
// (design/contracts/frozen-value-layout.md — payload pointer).
// (design/contracts/0006-frozen-value-layout.md — payload pointer).
Type::Con { .. } => "ptr",
_ => "i64",
}
@@ -2813,7 +2813,7 @@ impl<'a> Emitter<'a> {
/// allocates an `Ordering` ctor per call via the
/// `compare__Int` → `match` path, which surfaces as a
/// `bench_closure_chain` regression. See
/// `design/contracts/prelude-classes.md` for the full surface
/// `design/contracts/0017-prelude-classes.md` for the full surface
/// and the Int-only asymmetry rationale.
fn try_emit_primitive_instance_body(
&mut self,
+1 -1
View File
@@ -105,7 +105,7 @@ impl<'a> Emitter<'a> {
compiled.push((v, vty));
}
// FROZEN ABI (embedding boundary) —
// design/contracts/frozen-value-layout.md. size = 8 + n*8, tag@0, fields@8+i*8.
// design/contracts/0006-frozen-value-layout.md. size = 8 + n*8, tag@0, fields@8+i*8.
let size_bytes = 8 + (compiled.len() * 8) as i64;
let p = self.fresh_ssa();
// pick allocator based on escape analysis. `alloca`
@@ -1,4 +1,4 @@
//! FROZEN ABI byte-pin — see design/contracts/frozen-value-layout.md.
//! FROZEN ABI byte-pin — see design/contracts/0006-frozen-value-layout.md.
//! Pins the heap (@ailang_rc_alloc) box layout a boundary-crossing
//! single-ctor scalar record takes: size = 8 + n*8, tag i64 @ offset
//! 0, fields i64-strided from offset 8. Goes RED if codegen moves an
@@ -45,7 +45,7 @@ fn staticlib_emits_forwarder_no_main() {
/// M3: a single-ctor scalar record param/ret crosses the embedding
/// C boundary as a bare `ptr` (the frozen payload pointer —
/// design/contracts/frozen-value-layout.md). The M2 forwarder body
/// design/contracts/0006-frozen-value-layout.md). The M2 forwarder body
/// is byte-unchanged: leading `ptr %ctx`, TLS save/store/restore, the
/// internal `@ail_<module>_<fn>` call carrying no ctx arg and no
/// aggregate calling convention (no `sret`/`byval` — a record is a