docs: SPEC drift fix for v0.11.2 + load-bearing SKILL.md

[danieljohnmorris]

Summary

PRs #262 / #271 audited docs through v0.11.1. Since then #272 to #288 landed and SPEC.md fell behind. This PR catches the spec up to v0.11.2 and fixes the skill-surface drift trap that let SKILL.md fall behind every release.

Manifesto framing: when SPEC.md says one thing and the engine does another, every agent that hits the gap pays the retry tax. The skill surface is the cheapest place to fix this once and for everyone.

What's in the diff

Commit 1 - docs: refresh SPEC for v0.11.2 features

• slc / take / drop document negative indices counting from end with clamp-on-overflow semantics (negative indices on slc / take / drop (parity with at) #266).
• Map type section rewritten: keys are typed (t or n), Int(1) and Text("1") distinct, float keys floor to i64, jdmp stringifies numeric keys for JSON output (perf: typed MapKey enum removes routing-tsp str(j) tax on numeric maps #267).
• map, flt, fld added to the builtin reference table. New note: all HOFs work cross-engine on tree / VM / Cranelift JIT / AOT post vm + cranelift: FnRef NaN-tag plumbing (PR 1 of HOF dispatch chain) #274 vm + cranelift: native map HOF dispatch (PR 2 of 4) #277 vm + cranelift: native flt + fld + flatmap HOF dispatch (PR 3a of 4) #278 vm/cranelift: lift grp + uniqby + srt-2arg + partition via tree-bridge (HOF dispatch PR 3b) #279 vm + cranelift: closure-bind HOF ctx forms via tree-bridge #280 vm + cranelift: dispatch FnRef-variable calls dynamically (HOF dispatch PR 3d) #283.
• New ### Inline lambdas subsection: Phase 1 literal-only is cross-engine, Phase 2 closure capture is tree-only with ILO-R012 automatic fallthrough on VM and Cranelift (Phase 2 inline lambdas: closure capture #265 HOF dispatch PR 4: lift inline lambdas Phase 1 to cross-engine #284).
• Top-level program output section updated: AOT-compiled binaries from ilo compile now strip the ~/^ wrapper byte-for-byte the same as in-process runners (fix(aot): strip top-level ~/^ wrappers in compiled binaries #281). The previous follow-up disclaimer goes away.

Commit 2 - build: mirror ai.txt into skills/ilo/SKILL.md

SKILL.md is the file Claude Code agents actually load when they invoke the ilo skill. Until now it referenced ai.txt but never embedded it. That meant every SPEC update silently bypassed the skill surface unless the agent also cat'd ai.txt, which most don't. build.rs now injects ai.txt between <!-- BEGIN AI-SPEC --> markers so the skill stays in step with SPEC.md on every cargo build. The human-authored summary at the top of SKILL.md is also refreshed to mention !!, inline lambdas, numeric map keys, negative indices, the top-level Ok-on-stdout contract, and ilo compile.

Repro

Before this PR:

$ grep -c "negative indices" SPEC.md ai.txt skills/ilo/SKILL.md
SPEC.md:0
ai.txt:0
skills/ilo/SKILL.md:0

After:

$ grep -c "negative indices" SPEC.md ai.txt skills/ilo/SKILL.md
SPEC.md:2
ai.txt:2
skills/ilo/SKILL.md:2

Test plan

• cargo build --release --features cranelift clean - ai.txt regenerates from SPEC.md, SKILL.md mirrors ai.txt between markers
• cargo test --release --features cranelift - full suite green (2992 lib tests + every integration crate)
• cargo fmt --check clean
• Manual verification: SKILL.md now contains the canonical builtin table inline, so agents loading the skill see all 90+ builtins without needing to run ilo help ai
• All four shipped behaviours (negative indices, typed map keys, HOF cross-engine, AOT wrapper symmetry) are reflected in both SPEC.md and the regenerated ai.txt + SKILL.md

Skipped on purpose

• JIT helper nil-sweep batches 3-7 (Cranelift JIT nil-sweep batch 3: arithmetic, comparison, numeric-unary #282 route stats + linalg JIT helpers through JIT_RUNTIME_ERROR (batch 6) #285 Route collection JIT helpers through JIT_RUNTIME_ERROR (batch 5) #286 JIT nil-sweep batch 4: text + format helpers #287 route I/O JIT helpers through JIT_RUNTIME_ERROR (batch 7) #288) - implementation detail; user-visible behaviour was unchanged (silent-nil to runtime-error transition for invalid inputs that should never have worked).
• Cranelift errors carrying source spans (cranelift: thread source span through jit_hd/jit_at/jit_tl #270) - the existing "Parser, verifier, and runtime errors all show source spans" line in the Error Diagnostics section already covers this generically.
• OP_CALL_DYN / FnRef NaN-tag plumbing - internal opcodes, not user-facing.

Follow-ups

• ilo-site (the Astro repo at /Users/dan/code/ilo-lang/site) has its own user-facing copy that drifts on the same cadence. Auditing it is a separate PR in a separate repo.

[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!