tailored ILO-P001 hint + docs for glued-negative-literal misparse

[danieljohnmorris]

Summary

Closes pending.md #5ap (negative literal in operator chain).

When a user writes 0 -1.5 (no space before the dash, meaning "zero minus one point five") the lexer packs -1.5 into a single Number(-1.5) token because the previous token is an Ident/Number/RParen and not one of the keep-glued contexts where the lexer auto-splits -N back into Minus + Number. That's deliberate: the glued form is load-bearing for call-arg, list-element, and binop-operand shapes (mod n -2, +a -3, [1 -2 3], <r -0.05) - the existing regression_neg_literal_papercut.rs / regression_negative_literal_after_op.rs suites pin all of them. Splitting the glued token universally would break those.

So this isn't a parser bug to fix - it's a spacing convention that the docs and diagnostics never spelled out. The earlier session correctly stopped at the gate after discovering the lexer-rewrite path conflicts with load-bearing tests. This PR is the doc + diagnostic-only path: tell the user what shape they meant, in the moment they get it wrong.

Repro before / after

m > n
  0 -1.5
m

Before:

ILO-P001: expected declaration, got number `-1.5`

No hint. The user has no idea the issue is a missing space.

After:

ILO-P001: expected declaration, got number `-1.5`
hint: for subtraction, write `a - b` with spaces both sides (e.g. `0 - 1.5`).
      for a negative value as an expression, wrap in parens: `(-1.5)`.
      a glued `-N` (no space before) is only parsed as a negative literal
      when it's a call argument or inside a list.

The hint interpolates the offending value so the example is self-explanatory (works for ints too: 4 -1 suggests 0 - 1 and (-1)).

What's in the diff

Commit 1 (parser + tests + example): new Number(n) if *n < 0.0 arm in the parse_decl hint match in src/parser/mod.rs. No lexer changes. New cross-engine regression test tests/regression_negative_literal_diag.rs (4 tests) pinning the tailored hint text and the four idiomatic positive shapes. New examples/glued-negative-literal-spacing.ilo pinning the three shapes with -- run: / -- out: assertions, picked up by the existing examples harness.

Commit 2 (docs): SPEC.md arithmetic section, ai.txt neg-literal paragraph, skills/ilo/ilo-language.md operators line - all gain a "subtraction spacing" sentence pointing at the canonical form and the (-N) paren workaround. Site gotchas.md gets a new dedicated section (separate commit in the site repo, already pushed: ilo-lang/ilo-site@4be236d).

Test plan

• new regression suite: cargo test --release --features cranelift --test regression_negative_literal_diag -> 4 passed
• full neg-literal family unchanged: regression_neg_literal_papercut, regression_negative_literal_after_op, regression_minus_prefix_call, regression_minus_zero_decl_parse, regression_neg_literal_edge_pin all green cross-engine
• 319 parser unit tests pass
• cross-engine examples_engines test passes (includes the new example)
• cargo fmt --check clean
• cargo clippy --release --features cranelift --all-targets -- -D warnings clean
• manual repro: 0 -1.5 now shows the tailored hint; 0 - 1.5 -> -1.5; mod n -2, [1 -2 3], (-1.5) all still work
• CI green on push

Follow-ups

None - the alternative paths (lexer rewrite, comma-mode call args, context-sensitive Pratt) were ruled out by the earlier investigation as they'd break load-bearing tests. This is the right scope for a diagnostic papercut.

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