Maintain a pi extension against its pi dependencies

Adapt an extension to the latest published versions of the pi packages it imports by default, or to an explicit target=<version>. Two layers:

• Compatibility layer (steps 3–4): fix breaking changes with zero behavior change — the user's sign-off is required only when a behavior change is unavoidable.
• Adoption layer (step 6): survey APIs/features added since the installed version; present each as a candidate with benefit, scope, and risk; adopt only what the user picks, one item at a time.

Steps

1. Resolve the target versions, locate the packages, and read the changelogs

Resolve the target per pi package the extension imports (@earendil-works/... specifiers, gathered from the repo's package.json and import surface): explicit target=<version> pins the whole run → else the latest published version (npm view <pkg> dist-tags.latest, cross-check GitHub releases). Never infer targets from prior reports, prior syncs, GLOSSARY.md, ADRs, git history, or installed devDependencies — the report is write-only.

Record the resolved version per package. If it equals the installed version, skip the fix loop (steps 3–4) but still run step 2's import-surface check — the seam catches pre-existing repo debt, not just SDK drift — and run the adoption survey (step 6).

Locate the installed packages via the pi CLI (Get-Command pi / mise which pi, then walk up from the shim to the package) — never a hardcoded store layout. For a target other than installed, unpack the target to a temp dir (npm pack <pkg>@<target> or an isolated npm i in a scratch project).

Read each package's CHANGELOG.md over the installed → target range, not just the newest entry: note Breaking Changes and any Added/Changed/Removed/Fixed touching the extension surface. Also check the target version's official docs / API reference, not just the changelog.