Add pkg/suggest: advisory safer-form rewrites with typed caveats

[Kiran01bm]

Summary

Adds the advisory suggest surface — the last piece of P2.5
(PLAT-38440): map DDL that is risky as
written to the safer native form the engine would run instead, offline, never executing.

What

• pkg/suggest: versioned report (format_version: 1) with one Suggestion per
  constructed rewrite — original, operation, typed reason, recommended sequence,
  and typed caveats (non-transactional, separate-transactions,
  invalid-index-on-failure, detach-finalize-on-failure, validation-scan).
• pg-sprite suggest [file] CLI (stdin when omitted, --json): advisory only — always
  exits zero on a valid script; lint remains the gate.
• Caveats derive from the parsed operation kind; a rewrite with no caveat mapping fails
  closed instead of emitting caveat-less advice, so a new planner rewrite cannot ship
  un-annotated.

Why

The classifier already constructs safer sequences (planner.Decision.SaferSQL), but they
were only visible inside diff/migrate --dry-run output. The SchemaBot adapter's plan
verb and the standalone CLI front door both need the advisory contract as a standalone,
machine-readable surface: what would run instead, why, and under which caveats — because a
safer form is not a semantic equivalent (different transactionality, locking, and failure
modes).

                 ┌───────────────────────┐
 DDL script ────▶│ statement.Split       │
                 │ planner.Classify      │  zero live facts,
                 │ (per statement)       │  nothing executes
                 └──────────┬────────────┘
                            │ safer-idiom decisions with a
                            │ constructed rewrite only
                            ▼
                 ┌───────────────────────┐
                 │ suggest.Report         │
                 │  original → recommended│──▶ text / --json
                 │  reason + caveats      │
                 └───────────────────────┘

References

• PLAT-38440 — P2.5 dry-run plan + advisory suggest surface + linter
• Stacks on Add pkg/lint: offline typed findings replacing the CLI lint stub #9 (pkg/lint) and the safer-form wording follow-up
• Advisory-mode design: docs/high-level-design.md § advisory mode

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.