#511 Preserve extension command contracts and recovery fidelity

Summary

• synthesize usable command contracts for importer/exporter registrations that omit optional metadata
• inherit canonical help/flag contracts for verified same-extension flattened aliases
• preserve nested extension failure recovery boundaries and honor extension flag arity in retry suggestions
• update SDK harness and activation-summary expectations; refresh pm-changelog to 2026.7.11

Verification

• pnpm lint
• pnpm typecheck
• node scripts/run-tests.mjs coverage — 5,533/5,533, 100/100/100/100
• fresh tarball install and TypeScript extension dogfood in /tmp/pm-extension-contract-proof
• pm validate --check-resolution --check-history-drift --json (history drift clean; known legacy resolution warnings)
• pm health --check-only --summary --json
• pnpm audit --audit-level moderate
• pnpm changelog:pm:check
• local Greptile review, feedback fixed, second review clean

Tracks pm-s9iu / GH-503, pm-0mjz / GH-504, pm-o71e / GH-505, and pm-9qcr / GH-507.

---

Summary by cubic

Preserves extension command contracts and recovery fidelity. Flattened aliases inherit canonical flags; importer/exporters get default contracts (even when options are omitted or {}); nested errors keep their recovery; and suggested retries use extension flag arity with path‑exact command matching (longest descriptor) and treat required untyped flags as value‑taking. Also syncs with main, keeps fixes under Unreleased, bumps pm-changelog to 2026.7.11, and removes stale tracker references from the README.

• Bug Fixes

  • GH-503 (pm-s9iu): Flattened aliases inherit help/flag contracts; unknown options now error; supports single‑token aliases.
  • GH-504 (pm-0mjz): Synthesizes default importer/exporter contracts, including optional [file]; visible in help/SDK; applies when options are omitted or {}.
  • GH-505 (pm-o71e): Preserves nested typed errors and recovery; no top‑level suggestions from nested calls.
  • GH-507 (pm-9qcr): Suggested retries honor extension arity; booleans render bare; value flags keep placeholders; treat required untyped flags as value‑taking; path‑exact command matching (longest descriptor) across repeated tokens; guards missing invocation tokens.

• Refactors

  • Move verified alias mapping and related helpers into the command‑contract module; behavior unchanged.
  • Remove obsolete tracker references from README.