fix: persona-diagnostic batch 2 (cross-language slips)

[danieljohnmorris]

Summary

Six diagnostic-only improvements addressing persona-friction patterns from rerun3 logs. Each is a cross-language slip that previously surfaced as a bare or misleading parse error; each now emits a friendly hint pointing at the canonical ilo form, so the agent's first retry should be the right one.

Manifesto framing: every friendly hint shaves the cost of one wrong follow-up message. The cumulative savings across these six shapes is meaningful because they're concentrated in early-program-writing turns where retries are expensive.

What's in the diff

Five commits, one logical change each:

• lexer: friendly hint for AND/OR/NOT from other languages — forward-scan of consecutive uppercase letters at fresh-expression position; emits ILO-L001 with a suggestion pointing at & / | / !. Type position (f x:OR n n>n → O R n n) is left untouched via a prev-token guard.
• parser: friendly hints for cross-language syntax slips — four hints bundled because they live across the same file and helper site:
  • =<a b / =>a b compound-prefix → suggest <= / >= single token (ILO-P003).
  • fn p:t>r;body at expression position → suggest parenthesised inline lambda (p:t>r;body) (ILO-P009).
  • main:>n;body no-param signature → suggest main>n;body (no : before >) (ILO-P003).
  • expected LBrace, got Semi multi-line-body confusion → hint about ilo's single-line ;-separated body rule.
• main: AST-aware hint for discarded-result braced conditional — cond{^\"err\"} runs and discards the body value silently. Added a post-parse AST walker to collect_hints_with_program that detects guard bodies whose tail expression is Expr::Err(_) / Expr::Ok(_), recursing through nested ForEach / Match-arm / While bodies. Hint points at the braceless cond ^\"err\" early-return form. Also fixes a pre-existing false positive in warn_cross_language_syntax: comments mentioning -> / && / || / // illustratively no longer trigger the warning.
• example: persona-diagnostic-batch-2 covers canonical forms — five run/out pairs pinning the corrected forms across tree, VM, and Cranelift via the examples_engines harness.
• docs: cross-language gotchas section + SKILL common-mistakes — new SPEC.md subsection with a six-row table mapping each slip to canonical form and error code. Regenerated into ai.txt via build.rs. Six new entries in skills/ilo/SKILL.md Common Mistakes. Site docs deliberately untouched to avoid collision with the in-flight doc-audit PR docs: SPEC drift fix for v0.11.2 + load-bearing SKILL.md #290.

Items dropped and deferred

• Item 1 (sin=42 builtin shadow) dropped: already covered by the in-flight fix/builtin-shadow-flat-freq worktree (extends Builtin::is_builtin gating to parse_let and parse_decl). The fix there is broader and more correct (gates against ALL builtin names, not just trig/log/exp).
• Item 8 (prefix - parse-error column off-by-one) parked: no clean repro from the original persona log entry. Filed in ilo_assessment_feedback.md Parked section for revisit when a concrete failing snippet shows up.

Repro before/after

Item 2 — AND a b:

before:  ILO-L001 unexpected token 'A'  Unexpected character(s): 'A'
after:   ILO-L001 unexpected token 'AND'  `AND` is not an ilo keyword. ilo uses `&` (single `&` for logical and)

Item 5 — =<d 0{...}:

before:  ILO-P009 expected expression, got LBrace
after:   ILO-P003 `=<` is not an ilo operator; compound prefix forms don't compose
         hint: use `<=` (single token) instead, e.g. `<=a b` for the comparison

Item 6 — f=fn x:n>n;+x 1:

before:  ILO-P009 expected expression, got KwFn
after:   ILO-P009 `fn` is a reserved word and cannot start an expression
         hint: ilo's inline lambda syntax is `(p:t>r;body)`, e.g. `map (x:n>n;+x 1) xs`. For a named function use `name params>return;body` at the top level.

Item 7 — main:>n;42:

before:  ILO-P003 expected Greater, got Colon
after:   ILO-P003 unexpected `:>` after `main` — ilo signatures don't put a colon before the return-type separator
         hint: write `main>return;body` for a no-param function, or `main p:t>return;body` if params were intended

Item 9 — @k xs;+k 1:

before:  ILO-P003 expected LBrace, got Semi  (no hint)
after:   ILO-P003 expected LBrace, got Semi
         hint: ilo bodies are single-line, `;`-separated. If you broke the body across lines, collapse it onto one line or wrap with `{ ... }`. For example `@k kws{body};...` not `@k kws;body`.

Item 4 — <x 0{^\"err\"};~x (runs cleanly, silently discards ^\"err\"):

before:  (no diagnostic; agent thinks early-return happened, downstream logic breaks)
after:   hint: `cond{^\"err\"}` and `cond{~v}` discard the body expression. For early-return use the braceless form `cond ^\"err\"` or wrap the body in `{ret ^\"err\"}`.

Test plan

• 7 new lexer tests (AND/OR/NOT positive, post-dot OR, mid-ident OR, OR-as-type position negative cases)
• 7 new parser tests (compound prefix Eq+Less, Eq+Greater, Bang+Less is-negated-guard, fn/def lambda hint, fn-decl colon-before-greater, params-present no-hint, LBrace-got-Semi, LBrace-got-other-token)
• 6 new collect_hints tests (discarded Err/Ok, braceless-guard no-hint, explicit-ret no-hint, foreach-body, match-arm-body)
• 5 example run/out pairs exercising the canonical forms end-to-end across tree/VM/Cranelift via examples_engines harness
• cargo test --release --features cranelift — all 3013 lib + 199 example + integration tests pass, 0 failures
• cargo fmt --check clean
• cargo clippy --release --features cranelift --all-targets clean

Follow-ups

• Item 8 (prefix - parse-error column) needs a concrete repro; logged in Parked.
• Site docs (reference/error-codes.md) refresh deferred to PR docs: SPEC drift fix for v0.11.2 + load-bearing SKILL.md #290's audit.

[codecov]

Codecov Report

❌ Patch coverage is 99.19786% with 3 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/main.rs	98.29%	2 Missing ⚠️
src/lexer/mod.rs	99.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!