Unify same-file and cross-file forward-reference enrichment in diagnostics provider

[jbearak]

Context

Follow-up to the out-of-scope diagnostic cleanup spec (2026-04-22). That spec takes approach B: a shared message helper used by both the analyzer and the diagnostics provider, so same-file and cross-file forward-reference messages stay in sync. This issue tracks the larger restructuring we considered but deferred (approach C).

The idea

Today the analyzer produces the `Undefined local macro: `x'` / `Undefined global macro: $x` diagnostic directly, including the case where `x` is defined later in the same file. The cross-file diagnostic provider then (separately) rewrites the message when the symbol is out of scope through a `do`/`run`/`include` chain.

Approach C would instead:

• Have the analyzer emit only the generic undefined diagnostic.
• Attach structured side-band information (e.g., `defined_later_in_same_file_line: N`) to the diagnostic or to the document state.
• Move all position-aware message enrichment (both same-file and cross-file) into `src/providers/diagnostics.ts`, so there is a single pipeline that turns "undefined" into a specific reason.

Why defer

• Requires new plumbing: a place to attach/consume the analyzer's forward-ref data. The analyzer currently uses it internally via the preorder-traversal index.
• The sibling spec already makes the messages consistent via a shared helper, which captures most of the UX benefit.
• Risk of cascade changes through tests that assume the analyzer emits specific wording.

When to revisit

• When we add other cross-cutting enrichment (e.g., "did you mean X?" suggestions) that would also benefit from a central pipeline.
• When analyzer-side wording becomes a recurring source of drift.

Links

• Sibling spec: `docs/superpowers/specs/2026-04-22-out-of-scope-diagnostic-cleanup-design.md` (to be written)
• Related follow-up: Position-aware forward-reference analysis for variables #147 (position-aware variable forward references)