docs: reserved-namespaces forecast + 3+ char-first convention for new builtins

[danieljohnmorris]

Summary

Three consecutive releases broke carry-forward scripts via short-name builtin collisions: v0.11.3 reserved avg, v0.11.4 tightened +=, v0.11.6 reserved ct. Each time ILO-P011 fired cleanly at parse time with a good rename hint, but the persona had no way to see it coming. Marketing-analyst rerun7 (originating P2 in the assessment doc) called this the predictable-cadence tax: not the rename itself, but the ~6-turn investigation cycle of parse-error → read message → check ai.txt for new builtin → confirm version → apply rename.

This PR closes the forecast gap with combined option (a) + (c) from the originating entry:

• (a) Reserved namespaces section in SPEC.md — full enumeration of every 2-char and 3-char builtin currently reserved, plus the forward-compat rule. Agents now have a stable published surface to budget against once instead of once per release.
• (c) 3+ char-first convention in AGENTS.md — new builtins land under names of 4 characters or longer; a short alias is only added later when the long form is unambiguous and the short doesn't shadow a plausible user binding. Existing short builtins grandfather, so this is a forward-looking policy, no renames.
• Drift-guard test — asserts the SPEC enumeration matches Builtin::ALL at test time so the published forecast cannot silently fall out of sync with the registry.

Manifesto framing: every name-collision incident now turns into a single-character rename (the existing ILO-P011 hint already nails that), and every release ships with a forecast that lets agents avoid the collision in the first place. The published 2-char namespace becomes a forever-safe binding surface for user code.

Rejected option (b) loud→warn: demoting ILO-P011 to a warning would re-introduce the silent-mis-dispatch in call position that the existing error message specifically guards against — exactly the manifesto-violation we're guarding against.

What's in the diff (per commit)

• docs: add reserved-namespaces section to SPEC — new ### Reserved namespaces subsection after the existing reserved-words section. Enumerates every 2-char (at hd tl rd wr ct) and 3-char short-name builtin, plus the longer ones in prose. Publishes the safe-name strategy (2-char names not on the list are permanently safe, new builtins land 4+ chars). ai.txt and skills/ilo/SKILL.md regenerate through the existing build.rs mirror.
• docs: record 3+ char-first convention for new builtins in AGENTS.md — new ## Adding builtins section spelling out the rule for contributors, including the alias-only-when-safe guard for short aliases.
• tests: drift-guard SPEC reserved-names enumeration vs Builtin::ALL — tests/regression_reserved_names_doc.rs with two tests: one that parses the SPEC enumeration and diffs it against the registry, one that asserts the section + forecast string still exist. Failure messages point the maintainer at AGENTS.md.
• examples: reserved-names learning artefact — examples/reserved-names.ilo showing the would-error forms as commented reference + a working 4-char binding. Doubles as engine-harness regression coverage.

Repro before/after

Before: marketing-analyst rerun7, carry-forward script with ct=r.10, hits ILO-P011: 'ct' is a builtin and cannot be used as a binding name. Persona has to grep ai.txt for new builtin entries to figure out what changed. ~6 turn investigation overhead.

After: persona reads SPEC ### Reserved namespaces once, picks cty (unreserved 2-char name, permanently safe) and never collides again. New builtins land under 4+ chars per AGENTS.md so the 2-char surface stops accumulating reservations.

Test plan

• cargo test --release --features cranelift — full suite green
• cargo clippy --release --features cranelift --all-targets -- -D warnings — clean
• cargo fmt --check — clean
• Drift-guard tests pass with the current registry
• Drift-guard intentionally fails (verified during development) when the SPEC enumeration disagrees with Builtin::ALL — the message names the offending builtin and points at the AGENTS rule
• examples/reserved-names.ilo runs across every engine via the existing tests/examples_engines.rs harness, returns 3 as expected

Follow-ups

• None mandatory. The forecast is now public; any future builtin addition that needs a short alias goes through the AGENTS.md rule, the drift-guard catches the doc update at CI time, and the changelog entry surfaces it to agents on the next persona run.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!