@unbrained/pm-cli 2026.8.4 → 2026.8.6

package/docs/EXTENSION_LIFECYCLE.md

@@ -0,0 +1,46 @@
+# Extension Lifecycle Contracts
+
+Tracked by [pm-ig5cfe](../.agents/pm/issues/pm-ig5cfe.toon),
+[pm-495lkc](../.agents/pm/issues/pm-495lkc.toon), and
+[pm-miy5k6](../.agents/pm/issues/pm-miy5k6.toon).
+
+## Explicit Install-Source Identity
+
+A bare target may name both a bundled alias and an already-installed npm
+package. pm preserves the bundled-first compatibility rule but never hides the
+choice. Install results include `source_resolution` with the selected source,
+an `ambiguous` indicator, every matching candidate, and an explicit command for
+each. Use `pm install npm:<package>` to force npm identity or the reported bare
+alias command to force the bundled package. Install-all results carry the same
+receipt on every package row.
+
+## Durable Extension Migrations
+
+Active packages register schema migrations through `api.registerMigration`.
+Runtime preflight applies runnable migrations, and operators can plan or apply
+the same registrations explicitly:
+
+```bash
+pm package migrate --project --dry-run --json
+pm package migrate --project --json
+pm health --check-only --json
+```
+
+`pm extension migrate` is the compatibility spelling. The SDK exposes
+`runExtensionMigrations`, `PmClient.packageMigrate`, and the one-shot
+`packageMigrate`/`extensionMigrate` helpers. Dry-run never invokes package code
+or writes state. Apply records deterministic per-migration receipts in
+`.agents/pm/extension-migrations.json` through workspace history. Successful
+migrations become idempotent `skipped` rows in later processes. Failures retain
+their error for health diagnostics and are retried on the next apply. Project
+scope includes active project and global packages because both affect that
+workspace; `--global` restricts execution to global registrations.
+
+## Scoped Preflight Ownership
+
+`definePreflightOverride` and `api.registerPreflight` accept
+`{ commands, run }`. Command paths are normalized, disjoint registrations
+compose without warnings, and runtime invokes only the matching owner. Empty or
+omitted command ownership retains the legacy global behavior and collides with
+every other override. Activation summaries and persisted contribution
+inventories expose `preflight_ownership` for static doctor and tooling output.

package/docs/MERGE_SAFETY.md

@@ -63,6 +63,8 @@ pm merge install --dry-run --json
 
 When both sides change the same scalar or JSON leaf differently, the driver writes a parseable preferred-side result but exits nonzero. Git keeps the path conflicted so a human or coordinating agent must review the losing value and explicitly `git add` the resolution. Use `--prefer theirs` only when that is the intended resolution policy.
 
+The driver result's `guidance` always points unresolved conflicts to `pm merge report`. When a clone-local receipt exists, guidance includes its privacy-safe receipt and item ids for exact correlation; discarded values remain confined to the local receipt and never appear in generic logs or tracker history. Tracked by [pm-fbrz7p](../.agents/pm/issues/pm-fbrz7p.toon).
+
 For item conflicts, the driver also writes a clone-local receipt below the Git
 directory. It contains retained and discarded values so recovery does not
 depend on a reflog. Raw values never enter public tracker history:

package/docs/PR_REVIEW_LOOP.md

@@ -1,6 +1,6 @@
 # Pull Request Review Loop
 
-Tracker: [pm-hq28](../.agents/pm/tasks/pm-hq28.toon)
+Trackers: [pm-hq28](../.agents/pm/tasks/pm-hq28.toon), [pm-cp5pbo](../.agents/pm/tasks/pm-cp5pbo.toon)
 
 Use `scripts/reviews/pr-review-loop.mjs` to inventory every GitHub pull-request
 conversation surface before deciding that review is complete. The inventory includes
@@ -11,6 +11,7 @@ reaction state, thread resolution, outdated markers, and the reviewed head SHA.
 node scripts/reviews/pr-review-loop.mjs inventory --pr 123 > /tmp/pr-123-review-inventory.json
 node scripts/reviews/pr-review-loop.mjs watch --pr 123 --interval 30 > /tmp/pr-123-review-inventory.json
 node scripts/reviews/pr-review-loop.mjs react --node-id IC_kw... --reaction THUMBS_UP
+node scripts/reviews/pr-review-loop.mjs acknowledge --pr 123 --node-id PRR_kw... --reaction THUMBS_UP --body "CodeRabbit feedback implemented: https://github.com/owner/repo/pull/123#pullrequestreview-456. The suggested edge case is covered by test X."
 node scripts/reviews/pr-review-loop.mjs reply-inline --pr 123 --comment-id 456 --body "Addressed in abc123."
 node scripts/reviews/pr-review-loop.mjs acknowledge-inline --pr 123 --comment-id 456 --node-id PRRC_kw... --reaction THUMBS_UP --body "Addressed in abc123."
 ```
@@ -18,9 +19,14 @@ node scripts/reviews/pr-review-loop.mjs acknowledge-inline --pr 123 --comment-id
 Choose `THUMBS_UP` when feedback is useful or correct and `THUMBS_DOWN` when a
 finding is materially incorrect. Use `acknowledge-inline` so the reaction and
 explanation land on the actual review comment and its thread. GitHub does not expose
-a reply thread for top-level PR conversation comments or submitted review summaries;
-react to those surfaces, but do not create a generic PR comment that pretends to be
-a direct reply. The complete inventory keeps those non-threadable surfaces visible.
+a reply thread for top-level PR conversation comments or submitted review summaries.
+Use `acknowledge` for those surfaces: its PR comment must identify the bot, link the
+exact GitHub artifact, and explain whether the feedback was implemented or declined.
+That keeps the response auditable without pretending GitHub created a direct thread.
+The command adds a hidden artifact marker and reuses an existing marked comment on
+retry, so a lost response cannot create duplicate acknowledgements. It reports a
+partial result and exits unsuccessfully when either the comment or reaction write
+fails, allowing the missing write to be retried safely.
 
 After every push or reviewer retrigger, run `watch`. It delegates waiting to
 `gh pr checks --watch`, because reviewer agents report completion through GitHub

package/docs/README.md

@@ -17,17 +17,17 @@ pm guide release --json
 
 ## Read Path
 
-| Reader | First page | Then read |
-|--------|------------|-----------|
-| New user | [Quickstart](QUICKSTART.md) | [Command Reference](COMMANDS.md) |
-| New maintainer | [Onboarding](ONBOARDING.md) | [Agent Guide](AGENT_GUIDE.md), [Testing](TESTING.md), [Releasing](RELEASING.md) |
-| Coding agent | [Agent Guide](AGENT_GUIDE.md) | [Configuration](CONFIGURATION.md), then command help |
-| Maintainer | [Contributing](../CONTRIBUTING.md) | [Testing](TESTING.md), [Releasing](RELEASING.md), [Architecture](ARCHITECTURE.md) |
-| Package author | [Packages and Extensions](EXTENSIONS.md) | [SDK](SDK.md), [starter extension](examples/starter-extension/README.md) |
-| Codex or ChatGPT plugin implementer | [Codex Plugin](CODEX_PLUGIN.md) | [Native ChatGPT and Codex Plugin Implementation Plan](CHATGPT_CODEX_PLUGIN_IMPLEMENTATION.md) |
-| Codex user | [Codex Plugin](CODEX_PLUGIN.md) | [Agent Guide](AGENT_GUIDE.md), then [Command Reference](COMMANDS.md) |
-| Claude Code user | [Claude Code Plugin](CLAUDE_CODE_PLUGIN.md) | [Agent Guide](AGENT_GUIDE.md), then [Command Reference](COMMANDS.md) |
-| Machine client | `pm contracts --json` | [CLI Scripting Contract](SCRIPTING.md), [Command Reference](COMMANDS.md#machine-contracts), optionally `pm install guide-shell --project && pm guide commands` |
+| Reader                              | First page                                  | Then read                                                                                                                                                      |
+| ----------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| New user                            | [Quickstart](QUICKSTART.md)                 | [Command Reference](COMMANDS.md)                                                                                                                               |
+| New maintainer                      | [Onboarding](ONBOARDING.md)                 | [Agent Guide](AGENT_GUIDE.md), [Testing](TESTING.md), [Releasing](RELEASING.md)                                                                                |
+| Coding agent                        | [Agent Guide](AGENT_GUIDE.md)               | [Configuration](CONFIGURATION.md), then command help                                                                                                           |
+| Maintainer                          | [Contributing](../CONTRIBUTING.md)          | [Testing](TESTING.md), [Releasing](RELEASING.md), [Architecture](ARCHITECTURE.md)                                                                              |
+| Package author                      | [Packages and Extensions](EXTENSIONS.md)    | [SDK](SDK.md), [starter extension](examples/starter-extension/README.md)                                                                                       |
+| Codex or ChatGPT plugin implementer | [Codex Plugin](CODEX_PLUGIN.md)             | [Native ChatGPT and Codex Plugin Implementation Plan](CHATGPT_CODEX_PLUGIN_IMPLEMENTATION.md)                                                                  |
+| Codex user                          | [Codex Plugin](CODEX_PLUGIN.md)             | [Agent Guide](AGENT_GUIDE.md), then [Command Reference](COMMANDS.md)                                                                                           |
+| Claude Code user                    | [Claude Code Plugin](CLAUDE_CODE_PLUGIN.md) | [Agent Guide](AGENT_GUIDE.md), then [Command Reference](COMMANDS.md)                                                                                           |
+| Machine client                      | `pm contracts --json`                       | [CLI Scripting Contract](SCRIPTING.md), [Command Reference](COMMANDS.md#machine-contracts), optionally `pm install guide-shell --project && pm guide commands` |
 
 ## Documentation Map
 
@@ -35,7 +35,7 @@ pm guide release --json
 - [Onboarding](ONBOARDING.md) - first-two-hours maintainer and contributor setup.
 - [Agent Guide](AGENT_GUIDE.md) - canonical agent loop, tracker linking, and token-minimal command choices.
 - [Command Reference](COMMANDS.md) - command families with examples and when to use each family.
-- [CLI Scripting Contract](SCRIPTING.md) - exit codes, stdout/stderr boundaries, stable JSON fields, uniform OR filters, and shell composition recipes.
+- [CLI Scripting Contract](SCRIPTING.md) - exit codes, flat mutation receipts versus read envelopes, stdout/stderr boundaries, stable JSON fields, uniform OR filters, and shell composition recipes.
 - [Configuration](CONFIGURATION.md) - settings, storage formats, output, search, validation, and environment variables.
 - [Testing](TESTING.md) - sandbox-safe local tests and linked-test orchestration.
 - [Security Governance](SECURITY_GOVERNANCE.md) - vulnerability reporting, review discipline, property fuzzing, and OpenSSF limitations.
@@ -59,6 +59,7 @@ pm guide release --json
 - [Portable Corpus Shapes](CORPUS_SHAPES.md) - versioned SDK populations for realistic benchmarks, evaluations, and package tests.
 - [Agent UX Contracts](AGENT_UX_CONTRACTS.md) - ordering-cycle advisories, graph count units, collision safety, compact context, ownership wording, and recovery behavior.
 - [Packages and Extensions](EXTENSIONS.md) - package install workflows, runtime extension lifecycle, and API reference.
+- [Extension Lifecycle Contracts](EXTENSION_LIFECYCLE.md) - source identity, durable migrations, and scoped preflight ownership.
 - [Extension Author Contracts](EXTENSION_AUTHOR_CONTRACTS.md) - the stability guarantees and contract surface package authors build against.
 - [SDK](SDK.md) - public import surfaces and typed authoring examples.
 - [Multi-Branch Merge Safety](MERGE_SAFETY.md) - semantic tracker merge drivers, post-merge integrity gates, delete/modify policy, and recovery-receipt retention.
@@ -72,16 +73,16 @@ pm guide release --json
 
 ## Guide Topic Map
 
-| Optional `pm guide` topic | Primary docs |
-|-----------------------------|--------------|
-| `quickstart` | [Quickstart](QUICKSTART.md), [Command Reference](COMMANDS.md) |
-| `commands` | [Command Reference](COMMANDS.md), [Configuration](CONFIGURATION.md) |
-| `workflows` | [Agent Guide](AGENT_GUIDE.md), [Testing](TESTING.md) |
-| `sdk` | [SDK](SDK.md), [Architecture](ARCHITECTURE.md) |
-| `extensions`, `packages` | [Packages and Extensions](EXTENSIONS.md), [starter extension](examples/starter-extension/README.md) |
-| `skills` | [Agent Guide](AGENT_GUIDE.md) plus `.agents/skills/*` |
-| `harnesses` | [Agent Guide](AGENT_GUIDE.md) plus `.agents/skills/HARNESS_COMPATIBILITY.md` |
-| `release` | [Releasing](RELEASING.md), [CHANGELOG](../CHANGELOG.md) |
+| Optional `pm guide` topic | Primary docs                                                                                        |
+| ------------------------- | --------------------------------------------------------------------------------------------------- |
+| `quickstart`              | [Quickstart](QUICKSTART.md), [Command Reference](COMMANDS.md)                                       |
+| `commands`                | [Command Reference](COMMANDS.md), [Configuration](CONFIGURATION.md)                                 |
+| `workflows`               | [Agent Guide](AGENT_GUIDE.md), [Testing](TESTING.md)                                                |
+| `sdk`                     | [SDK](SDK.md), [Architecture](ARCHITECTURE.md)                                                      |
+| `extensions`, `packages`  | [Packages and Extensions](EXTENSIONS.md), [starter extension](examples/starter-extension/README.md) |
+| `skills`                  | [Agent Guide](AGENT_GUIDE.md) plus `.agents/skills/*`                                               |
+| `harnesses`               | [Agent Guide](AGENT_GUIDE.md) plus `.agents/skills/HARNESS_COMPATIBILITY.md`                        |
+| `release`                 | [Releasing](RELEASING.md), [CHANGELOG](../CHANGELOG.md)                                             |
 
 Community files:
 

package/docs/RELEASING.md

@@ -20,7 +20,8 @@ Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon),
 [pm-4s24d2](../.agents/pm/issues/pm-4s24d2.toon),
 [pm-39cqqx](../.agents/pm/tasks/pm-39cqqx.toon), stable peer compatibility
 [pm-csuce0](../.agents/pm/issues/pm-csuce0.toon), and artifact budgets
-[pm-998juj](../.agents/pm/tasks/pm-998juj.toon).
+[pm-998juj](../.agents/pm/tasks/pm-998juj.toon), plus exact-tag recovery
+[pm-lwnifd](../.agents/pm/issues/pm-lwnifd.toon).
 
 ## Version Policy
 
@@ -66,7 +67,7 @@ pnpm version:check
 Policy:
 
 - release only when commits exist after the latest release tag
-- ignore `.agents/pm`-only tracker commits for publish eligibility so post-release evidence and closure updates do not create a package release by themselves
+- ignore tracker-governance-only commits for publish eligibility: `.agents/pm/**` and the mechanically generated `CHANGELOG.md` projection do not create a package release by themselves, while any product, test, documentation, workflow, or other changed path remains release-relevant
 - create at most one production tag and npm version per UTC day; if no tag was
   created, a non-`github-actions[bot]` closure of the exact bot-created
   `Auto Release blocked` issue on the same UTC day triggers one preparation
@@ -103,7 +104,7 @@ The pipeline performs:
 2. a single `YYYY.M.D` version bump; ordinal targets and the removed
    `--allow-same-day-release` override fail closed
 3. latest `pm-changelog` install and main changelog refresh through package-owned full-history generation; the release pipeline passes `--release-version` with `--all-release-tags` so the pending release section matches post-tag CI checks
-4. strict gates (build, typecheck, docs/skills freshness, coverage, static quality, compatibility, security, smoke checks, reliability gate)
+4. build, clone-local merge-driver installation, then the remaining strict gates (typecheck, docs/skills freshness, coverage, static quality, compatibility, security, smoke checks, reliability gate); this ordering makes the checkout-owned CLI available before bootstrap, matches CI, and prevents fresh-clone tracker measurements from observing undeclared merge-driver repairs
 5. release note generation from changelog + pm evidence
 6. commit and tag creation (plus optional push)
 
@@ -232,11 +233,14 @@ git push origin v<version>
 `.github/workflows/release.yml` runs on `v*.*.*` tags and handles:
 
 - full-history checkout
-- manual `workflow_dispatch` by tag for recovery when an immutable npm version already exists; the reviewed current `main` source runs the gates so a historical tag cannot be blocked by an expired external fixture
+- manual `workflow_dispatch` by tag for recovery. An authenticated exact-version probe keeps already-published access recovery on the reviewed dispatch-time `main` source; when the immutable tag exists but npm publication never completed, recovery checks out that exact tagged source and retains the original version guard
 - pnpm install with frozen lockfile
 - version policy and tag guard
 - secret scan
-- build, typecheck, test, and coverage
+- build, clone-local merge-driver installation, typecheck, test, and coverage
+- generated changelog verification and `pm-changelog` installation before the
+  tracker-bearing static gate, so a clean checkout does not misclassify the
+  managed extension's linked files as missing
 - static quality gate (shared complexity, duplication, dead/orphan module, file/folder hygiene, source/exported docstring coverage profile)
 - temporary-project compatibility gate against latest published tracker data
 - reliability threshold gate (Sentry severity threshold, bounded to a recent-activity window via `--sentry-window-days` (default `14`, `0` = unbounded) so a stale benign unresolved issue cannot block every scheduled release; `--telemetry-mode` gate policy: `off` | `best-effort` | `required`). Scheduled `auto-release.yml` failures open/update an `Auto Release blocked` GitHub issue so blocked daily releases are never silently skipped.
@@ -248,7 +252,10 @@ git push origin v<version>
 - `npm publish --access public --provenance --tag latest`, skipped on retry
   only when the exact version is anonymously visible from a fresh npm cache.
   If the package is public but the target version is absent, the workflow
-  publishes immediately without attempting a package-access mutation. Only
+  publishes immediately without attempting a package-access mutation. A
+  dispatch may do so only when its source-selection preflight pinned the
+  checkout to the requested immutable tag; reviewed-main recovery continues
+  to refuse publication of a missing target. Only
   when neither the target nor package metadata is anonymously visible does the
   same-tag recovery path attempt to restore public package access, because a
   hidden version can also return 404 to authenticated metadata reads. After a
@@ -272,7 +279,7 @@ git push origin v<version>
   `scripts/release/verify-installed-agent-session.mjs`. Separate npm and Bun
   install roots must contain the resolved executable, then each drives the
   cold-start `init -> context -> create -> claim -> annotate -> files -> close
-  -> validate -> get -> context` loop. The structured report identifies the
+-> validate -> get -> context` loop. The structured report identifies the
   failing step and records per-step output ceilings and estimated token cost.
 - GitHub Release creation
 - GitHub Release metadata verification through the same local verification script
@@ -312,32 +319,38 @@ Use the npm registry package for maintainer global updates. Do not use `npm inst
   ordinal recovery version. Rerun `.github/workflows/release.yml` with
   `workflow_dispatch` and `tag=v<version>` (or close the current bot-created
   blocker once to trigger the guarded exact-run recovery). The workflow skips
-  duplicate npm publication for an anonymously visible version and attempts
-  protected access recovery before anonymous probes. A dispatch refuses to
-  publish when that immutable version is absent; first publication remains owned
-  by the original tag-push run.
-  Authenticated metadata is not used as the existence oracle because a hidden
-  immutable version can return 404 there as well.
+  duplicate npm publication for an anonymously visible version. Before
+  installing or running gates, dispatch performs an authenticated exact-version
+  probe. An
+  existing version keeps the reviewed dispatch-time `main` source and cannot
+  be republished. A definitive missing-version response pins the checkout to
+  the existing immutable tag, reapplies the version guard, installs the managed
+  changelog extension before tracker measurement, and permits first publication
+  only from that exact tagged source. Other registry failures stop before
+  source selection or publication.
 - If an immutable published package contains a defect that cannot be repaired
   by rerunning the same tag workflow, document the incident and ship the code
   fix in the next UTC day's release.
-- A manual exact-tag `workflow_dispatch` recovery reasserts public npm package
-  access before consulting anonymous registry metadata. This prevents a stale
-  public cache hit from bypassing access repair; an already-visible immutable
-  version is still verified and never republished. Recovery checks out the
+- A manual exact-tag `workflow_dispatch` recovery uses isolated anonymous
+  registry probes before any account-level access mutation. A visible package
+  with a missing target version proceeds directly to exact-tag publication, so
+  a publish-capable automation token is not required to change package access.
+  Access recovery is reserved for the ambiguous case where neither the package
+  nor target version is anonymously visible. An already-visible immutable
+  version is still verified and never republished. Recovery starts from the
   dispatch-time commit SHA and fails unless the dispatch ref is the repository
-  default branch (`main`), while `RELEASE_TAG` keeps the requested immutable
-  version as the verification target. Historical recovery validates
-  the tag shape but intentionally does not require current `package.json` to
-  equal that older version; dispatch cannot publish, so this does not weaken the
-  original tag-push version guard.
+  default branch (`main`). It remains on that reviewed source when the exact
+  npm version exists. When the version is definitively absent, it switches to
+  the resolved commit behind `RELEASE_TAG`, requires `package.json` to match the
+  tag, installs the clone-local merge driver and managed changelog extension,
+  and may publish that exact source after every gate passes.
 - Record failure evidence and remediation in the release `pm` item.
 
 ### Silent skip debugging
 
 When auto-release exits green but does not cut a version, inspect the pipeline's JSON skip `reason` from `scripts/release/run-release-pipeline.mjs` (or rerun locally with `pnpm release:pipeline:dry-run -- --json`):
 
-- tracker-only skip family: `tracker_only_changes_since_last_tag` (all changed paths are `.agents/pm` only)
+- tracker-only skip family: `tracker_only_changes_since_last_tag` (all changed paths are `.agents/pm/**` and/or the generated `CHANGELOG.md` projection; a product-visible path is the required negative control)
 - changelog-empty skip family: `empty_generated_changelog_section_for_target_version` (generated release section exists but has no non-empty entries)
 
 `pm-changelog` is maintained in a separate repository/package. Classifier or release-window bugs must be fixed and released there first, then consumed here via the latest npm package (`pm install npm:pm-changelog --project`) before rerunning release generation.

package/docs/SCRIPTING.md

@@ -1,19 +1,19 @@
 # CLI Scripting Contract
 
-Tracked by [pm-psy1](../.agents/pm/tasks/pm-psy1.toon), [pm-gknu](../.agents/pm/issues/pm-gknu.toon), and [pm-999jh7](../.agents/pm/issues/pm-999jh7.toon).
+Tracked by [pm-psy1](../.agents/pm/tasks/pm-psy1.toon), [pm-gknu](../.agents/pm/issues/pm-gknu.toon), [pm-999jh7](../.agents/pm/issues/pm-999jh7.toon), and [pm-srns](../.agents/pm/issues/pm-srns.toon).
 
 Use this contract when composing `pm` with shells, CI runners, `jq`, or another process. Exact flags remain discoverable from `pm <command> --help --json` and `pm contracts --command <command> --flags-only --json`.
 
 ## Process Contract
 
-| Exit | Meaning | Script response |
-|------|---------|-----------------|
-| `0` | The requested operation completed. A successful read may still return zero rows. | Parse stdout. |
-| `1` | Runtime or unexpected failure. | Preserve stderr and stop. |
-| `2` | Invalid flags, values, or command composition. | Correct the invocation; do not retry unchanged. |
-| `3` | Requested tracker or resource was not found. | Correct the path or ID. |
-| `4` | State or concurrency conflict. | Refresh live state before deciding whether to retry. |
-| `5` | A required dependency operation failed. | Inspect the dependency evidence before retrying. |
+| Exit | Meaning                                                                          | Script response                                      |
+| ---- | -------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| `0`  | The requested operation completed. A successful read may still return zero rows. | Parse stdout.                                        |
+| `1`  | Runtime or unexpected failure.                                                   | Preserve stderr and stop.                            |
+| `2`  | Invalid flags, values, or command composition.                                   | Correct the invocation; do not retry unchanged.      |
+| `3`  | Requested tracker or resource was not found.                                     | Correct the path or ID.                              |
+| `4`  | State or concurrency conflict.                                                   | Refresh live state before deciding whether to retry. |
+| `5`  | A required dependency operation failed.                                          | Inspect the dependency evidence before retrying.     |
 
 Successful structured results are written to stdout. Diagnostics, warnings, profiles, and errors are written to stderr so `--json`, `--format ndjson`, CSV, and table stdout remain pipe-safe. Never merge stderr into stdout before parsing structured output.
 
@@ -29,6 +29,29 @@ fi
 
 ## Stable Structured Fields
 
+Mutation and read envelopes are intentionally different. Single-item mutation
+commands emit a flat receipt whose `id`, `status`, and `changed_field_count`
+are top-level fields. Reads wrap their primary entity or rows under documented
+keys such as `item` or `items`. Bulk mutations such as `close-many` and
+`update-many` use collection envelopes under `rows`; consult
+`command_output_contracts` for the exact command path. Never infer one shape
+from another.
+
+TypeScript package consumers should parse mutation stdout with the SDK boundary
+helper so a wrapped or malformed result fails loudly:
+
+```ts
+import { parseMutationReceipt } from "@unbrained/pm-cli/sdk/contracts";
+
+const { id, status, changedFieldCount } = parseMutationReceipt(stdout);
+```
+
+`pm contracts --summary --json` keeps bootstrap discovery compact while
+declaring every command's default token ceiling. Use `pm contracts --full
+--json` for `command_output_contracts`, which pairs the envelope declaration
+with TOON- and JSON-specific token ceilings for every active core or package
+command.
+
 JSON object field order is not an API. Consume fields by name. Read envelopes keep the stable pagination vocabulary `items`, `count`, `total`, `has_more`, and, when another page exists, `next_cursor`. The `filters` object echoes the effective query scope. Plain `pm list` and `pm search` are all-status reads and disclose `filters.status: "all"`; lifecycle-specific commands such as `pm list-open` remain explicit shortcuts.
 
 Projection flags intentionally change row shape. Use `--fields` when a script requires an exact subset, `--brief` or `--compact` only when the documented sparse shape is sufficient, and `--full` when linked metadata is required. Check `row_contract` on generic read surfaces that expose one; do not infer omitted fields as empty values.

package/docs/SDK.md

@@ -30,6 +30,11 @@ content-addressed snapshots are tracked by
 [pm-dkrmzv](../.agents/pm/features/pm-dkrmzv.toon); see
 [Reproducible Workspaces and Snapshots](REPRODUCIBLE_WORKSPACES.md).
 
+Extension migration receipts, install-source identity, and scoped preflight
+ownership are tracked by [pm-ig5cfe](../.agents/pm/issues/pm-ig5cfe.toon),
+[pm-495lkc](../.agents/pm/issues/pm-495lkc.toon), and
+[pm-miy5k6](../.agents/pm/issues/pm-miy5k6.toon).
+
 Use it for extension authoring, package authoring, command/action contract discovery, and deterministic app or CI automation. Do not import private `src/core/...` modules from external integrations or packages.
 
 ## Install
@@ -290,7 +295,8 @@ Command/action contract exports:
 - Relationship graph primitives: `RelationshipKindRegistry`, `createRelationshipKindRegistry`, `assertRelationshipEdgeAllowed`, `RelationshipGraph`, `RelationshipEventLog`, `RelationshipEventStore`, `planRelationshipEventBackfill`, `buildRelationshipContext`, `buildDepsRelationshipContext`, `hierarchyAncestors`, `hierarchyDescendants`, `orderingPredecessors`, `orderingSuccessors`, `enumerateRelationshipPaths`, `auditWorkspaceRelationshipGraph`, `isOrderingRelationshipKind`, and `dependencyToRelationship` provide application-defined edge semantics, durable replay, deterministic legacy migration, bounded semantic traversal, policy-aware governance, and explainable context queries. Mutation adapters should call `assertRelationshipEdgeAllowed` with the active registry before persistence; it resolves aliases and honors custom `allowSelf` definitions while built-in self edges fail before item or history writes. `RelationshipEventLog.stream/project` and their durable-store equivalents page immutable prefixes and fold them into deterministic application state with exact version, processed-count, and as-of metadata. `RelationshipEventStore.appendBatch` validates a complete import under one cross-process lock and atomically publishes it; `skip_identical` resume mode rejects same-id semantic collisions. `RelationshipGraphAdapter`, `createRelationshipGraphSnapshot`, `syncRelationshipGraphAdapter`, `loadRelationshipGraphAdapter`, and `federateRelationshipGraphSnapshots` form the backend-neutral content-addressed projection boundary for database or remote graph packages. `MemoryRelationshipGraphAdapter`, `assertRelationshipGraphAdapterConformance`, and `createRelationshipGraphScaleFixture` give package authors a reference implementation, reusable compatibility contract, and lazy deterministic fixtures through one million nodes. See [Relationship graph semantics](RELATIONSHIP_GRAPH.md).
 - Atomic application transactions: `commitWorkspaceTransaction` coordinates ordered, idempotent item and relationship mutations under one workspace writer lock and a durable replay journal. Interrupted work resumes from step inspection; ordinary failures append reverse-order compensations without rewriting immutable histories.
 - Multi-branch merge primitives: `mergeItemDocuments`, `mergeHistoryStreams`, `mergeRelationshipEventStreams`, `mergeJsonDocuments`, `runMergeDriver`, `runMergeInstall`, and `runMergeReconcile` provide the same field-aware item, hash-chain-preserving history, sequence-renumbering relationship-event, key-level configuration, and audited post-merge repair-and-verify semantics as `pm merge`; `installMergeFence` and `findGitWorkspaceRoot` let custom init hosts install the same contract with explicit roots, while `buildMergeAttributePatterns`, `refreshMergeAttributeFenceIfInstalled`, and `auditMergeAttributeFence` expose fence coverage, refresh, and validation. See [Multi-Branch Merge Safety](MERGE_SAFETY.md).
-- Dependency provenance primitives: `EXTERNAL_DEPENDENCY_SOURCE_KIND`, `isExternalDependencySourceKind`, and `normalizeDependencySeedId` let custom importers preserve cross-workspace dependency ids explicitly while retaining local prefix normalization for ordinary seeds. Newly created dependency rows also carry the effective `author`, `author_source` (`asserted` or `detected`), and a mutation `source_kind`; legacy rows remain readable without invented provenance.
+- Dependency provenance primitives: `EXTERNAL_DEPENDENCY_SOURCE_KIND`, `EXTERNAL_DEPENDENCY_SOURCE_KIND_ALIAS`, `isExternalDependencySourceKind`, and `normalizeDependencySeedId` let custom importers preserve cross-workspace dependency ids explicitly while retaining local prefix normalization for ordinary seeds. `source_kind: "external"` is the human-facing alias and persists canonically as `global`; a `blocked_by` row with that provenance is a real external predecessor, so graph governance does not require a fabricated local item or misreport `stale_lifecycle_block`. Newly created dependency rows also carry the effective `author`, `author_source` (`asserted` or `detected`), and a mutation `source_kind`; legacy rows remain readable without invented provenance. Tracked by [pm-6sc8jq](../.agents/pm/issues/pm-6sc8jq.toon).
+- Terminal-create primitive: `CreateCommandOptions.closeReason` and `completedAt` allow importers to create an already-terminal item in the same atomic item/history transaction while preserving the source completion time separately from the local `closed_at` mutation time. The equivalent CLI flags are `--close-reason` and `--completed-at`; direct JSON documents map `close_reason` and `completed_at` to the same SDK operation. A missing governed reason returns `close_reason_required` with same-command `pm create` recovery examples. Tracked by [pm-ykdt4m](../.agents/pm/issues/pm-ykdt4m.toon) and [pm-5uclvd](../.agents/pm/issues/pm-5uclvd.toon).
 - Compile-cache lifecycle primitive: `pruneCompileCacheGenerations` bounds pm-owned Node bytecode caches to the current package generation; embedded hosts can apply the same upgrade cleanup without importing the executable entrypoint.
 - Typed mutation inputs (pm-x29o / GH-601): `PmCreateActionOptions`, `PmUpdateActionOptions`, and `PmCloseActionOptions` (`PmClientCloseActionOptions` on the client method) strip the permissive custom-field index signature from the executable command-option contracts, retaining their exact public keys and value types without a second hand-written shape; the free `create`/`update`/`close` functions and `PmClient` methods share those types. `PmUpdateManyActionOptions`, `PmCloseManyActionOptions`, and `OptionsFromContracts` cover flat action-contract composition. Field typos, object values, invalid scalar kinds, and MCP-only aliases on a `PmClient` command-option bag fail `tsc` under strict. Runtime-schema custom fields use the repeatable `field` option and `PmClient.run` remains the wide escape hatch. Projected list rows expose the typed `ListProjectedItemCore` fields (`row.id` is `string | undefined`, never `unknown`).
 - Typed customization primitives on `PmClient`: `init`, `config`, `schema`, `schemaList`, `schemaShow`, `schemaAddType`, `schemaRemoveType`, `schemaAddStatus`, `schemaRemoveStatus`, `schemaAddField`, `schemaRemoveField`, `schemaListFields`, `schemaShowField`, `schemaApplyPreset`, `schemaInferTypes`, `schemaShowStatus`, `profile`, `profileList`, `profileShow`, `profileApply`, and `profileLint`
@@ -305,7 +311,7 @@ Command/action contract exports:
 - Linked-test authoring primitives: `parseLinkedTestJsonEntries`, the `parseLinkedTest*` field parsers, `LINKED_TEST_PM_CONTEXT_MODE_VALUES`, `LINKED_TEST_PROTECTED_ENV_KEYS`, `classifyLinkedTestFailure`, `countFailureCategories`, and `summarizeContextPreflight` let custom hosts validate, execute, classify, and report linked tests without duplicating CLI policy.
 - Typed plan workflow primitives on `PmClient`: `plan`, `planCreate`, `planShow`, `planAddStep`, `planUpdateStep`, `planCompleteStep`, `planBlockStep`, `planReorderStep`, `planRemoveStep`, `planLink`, `planUnlink`, `planDecision`, `planDiscovery`, `planValidation`, `planResume`, `planApprove`, and `planMaterialize`
 - Plan contracts: `PlanSubcommand`, `PlanCommandOptions`, `PlanCommandResult`, `PlanResultPlan`, `PlanStepSummary`, `PlanShowDepth`, and `PlanTemplateName`
-- Typed package and extension lifecycle primitives on `PmClient`: `extension`, `extensionList`, `extensionActivate`, `extensionDeactivate`, `package`, `packageList`, `packageInstall`, `packageUninstall`, `packageDoctor`, `packageManage`, `packageDescribe`, `packageReload`, `packageCatalog`, `packageActivate`, `packageDeactivate`, and `upgrade`
+- Typed package and extension lifecycle primitives on `PmClient`: `extension`, `extensionList`, `extensionActivate`, `extensionDeactivate`, `package`, `packageList`, `packageInstall`, `packageUninstall`, `packageDoctor`, `packageManage`, `packageDescribe`, `packageReload`, `packageCatalog`, `packageActivate`, `packageDeactivate`, `packageMigrate`, and `upgrade`; one-shot `extensionMigrate` and `packageMigrate` helpers mirror those lifecycle actions.
 - Lifecycle primitive option/result contracts: `ExtensionCommandOptions` / `ExtensionCommandResult`, `PackageCommandOptions` / `PackageCommandResult`, `UpgradeCommandOptions` / `UpgradeResult`
 - `PM_CORE_COMMAND_NAMES`
 - `PM_TOOL_ACTIONS`
@@ -567,18 +573,20 @@ Tracked by [pm-5t33or](../.agents/pm/features/pm-5t33or.toon),
 [pm-gmdzaa](../.agents/pm/issues/pm-gmdzaa.toon), and
 [pm-dpqa3h](../.agents/pm/chores/pm-dpqa3h.toon).
 
-`PM_COMMAND_OUTPUT_BUDGET_CONTRACTS` declares one default estimated-token
-ceiling for every built-in command. Each row also carries its workload class,
+`PM_COMMAND_OUTPUT_BUDGET_CONTRACTS` declares generated TOON and JSON
+estimated-token ceilings for every built-in command. Each row also carries its workload class,
 the stable `ceil(UTF-8 bytes / 4)` estimate, whether an explicit unbounded
 request is allowed, and the shared deterministic degradation ladder:
 `full → compact → brief → summary → counts`. These contracts are policy data,
 not renderer-specific code, so package authors can reuse
-`definePmCommandOutputBudget`, `resolvePmCommandOutputBudget`, and
+`createPmCommandOutputBudget`, `definePmCommandOutputBudget`,
+`resolvePmCommandOutputBudget`, and
 `estimatePmOutputTokens` in custom transports.
 
 ```ts
 import {
   definePmCommandOutputBudget,
+  parseMutationReceipt,
   estimatePmOutputTokens,
   resolvePmCommandOutputBudget,
 } from "@unbraind/pm-cli/sdk/contracts";
@@ -587,6 +595,7 @@ const compactRead = definePmCommandOutputBudget({
   command: "get",
   budget_class: "read",
   default_max_estimated_tokens: 800,
+  default_max_estimated_tokens_by_format: { toon: 800, json: 1200 },
   degradation_ladder: ["compact", "summary"],
   allows_unbounded_opt_out: false,
   token_estimate: "ceil(utf8_bytes / 4)",
@@ -596,8 +605,21 @@ const builtIn = resolvePmCommandOutputBudget("contracts --summary");
 const measured = estimatePmOutputTokens(
   new TextEncoder().encode(JSON.stringify(result)).byteLength,
 );
+
+const receipt = parseMutationReceipt(mutationStdout);
+// receipt.id and receipt.changedFieldCount are typed; wrapped read envelopes
+// throw instead of silently producing an undefined id.
 ```
 
+`PM_COMMAND_OUTPUT_ENVELOPE_CONTRACTS` and
+`resolvePmCommandOutputEnvelope` declare whether the default structured result
+is a flat mutation receipt, wrapped entity, collection, diagnostic, or stream.
+The contracts command keeps summary bootstrap output compact and publishes
+complete budget/envelope pairs under `command_output_contracts` only in the
+explicit full projection. Active package commands receive deterministic
+fallback contracts, so extension authors can discover a bounded surface before
+they invoke it.
+
 `pm activity` applies a compact 20-row default bound; direct SDK calls default
 to five full rows. Results disclose `total_count`, `omitted_count`, `has_more`,
 and `applied_bound`. An explicit `limit` remains authoritative, while
@@ -816,7 +838,8 @@ lifecycle order to mirror `hook_counts`) of every registered surface's
 identifiers — command paths, hook kinds, item-type /
 field names, migration ids, importer / exporter / provider / adapter names,
 overridden service names and renderer formats, flag target-commands, and the
-preflight-override count — plus scoped `renderer_ownership` rows (format,
+preflight-override count — plus scoped `preflight_ownership` command rows and
+`renderer_ownership` rows (format,
 normalized commands, and whether a result discriminator exists) and the
 `capabilities` those surfaces exercise. Two
 uses:
@@ -1053,7 +1076,10 @@ tools that need to own item state without spawning `pm`.
 Tracked by [pm-4e12](../.agents/pm/features/pm-4e12.toon), with the VCS
 acceptance story [pm-8ngt](../.agents/pm/stories/pm-8ngt.toon) and the structured
 SDK adapters tracked by [pm-xm7c](../.agents/pm/features/pm-xm7c.toon) and
-[pm-kipd](../.agents/pm/features/pm-kipd.toon).
+[pm-kipd](../.agents/pm/features/pm-kipd.toon), versioned batch-local
+references tracked by [pm-o8z748](../.agents/pm/issues/pm-o8z748.toon), and
+atomic evidence-backed completion tracked by
+[pm-cyn0y6](../.agents/pm/issues/pm-cyn0y6.toon).
 
 `commitWorkspaceTransaction` is the public unit-of-work primitive for domain
 commands that must coordinate several SDK mutations. A plan supplies a stable
@@ -1193,12 +1219,15 @@ previously compensated retry without package-private file access.
 For the ubiquitous "commit N item mutations atomically" case (bulk import,
 bulk sync), `commitItemMutations` wraps the coordinator so callers describe
 the mutations instead of hand-writing a step array. The helper wires the
-crash-consistency contract for you: creates use their explicit stable `id` as
+crash-consistency contract for you: creates use their resolved stable `id` as
 the idempotency key (exists-by-id inspection) and are compensated by closing
 the item (or deleting it with `createCompensation: "delete"`); updates stamp a
 durable history marker for applied-detection and are compensated by restoring
 the captured pre-mutation version; closes treat an already-terminal target as
-applied and are likewise compensated by version restore. A stable
+applied and are likewise compensated by version restore; releases restore the
+prior claim when a later step fails. The journal step identity includes a
+canonical mutation fingerprint, so reusing a transaction id with changed
+payload fails before new work. A stable
 `transactionId` makes interrupted batches resumable across processes and
 agents.
 
@@ -1249,7 +1278,7 @@ each `addAc`/`removeAc` entry must be semicolon-free; unmatched removals are
 reported as `remove_ac_unmatched:<text>` warnings rather than disappearing as
 silent no-ops.
 
-`parseItemMutationBatch` is the strict JSON boundary for that primitive. It
+`parseItemMutationBatch` is the strict legacy JSON boundary for that primitive. It
 accepts either a non-empty mutation array or `{ "mutations": [...] }`, derives
 allowed option names from the exported create/update/close command contracts,
 and rejects unknown row or option keys with a did-you-mean diagnostic before a
@@ -1271,6 +1300,61 @@ await commitItemMutations({
 });
 ```
 
+For coherent heterogeneous specifications, use
+`resolveItemMutationDocument`. It accepts the legacy array or a versioned
+`{ schema_version: 1, mutations }` document. Create rows may declare a unique
+`ref`, omit `id`, and use exact `@ref` values in target ids, `parent`,
+`blockedBy`, and dependency `id` fields. Omitted ids are derived from the
+transaction id, alias, and workspace prefix; explicit ids are normalized.
+Malformed, duplicate, unknown, and cyclic references fail before tracker
+mutation. Commit the returned mutations and retain its alias-to-id receipt:
+
+```ts
+import {
+  commitItemMutations,
+  resolveItemMutationDocument,
+} from "@unbrained/pm-cli/sdk";
+import path from "node:path";
+
+const pmRoot = path.join(process.cwd(), ".agents", "pm");
+const specificationJson = JSON.stringify({
+  schema_version: 1,
+  mutations: [
+    {
+      op: "create",
+      ref: "initiative",
+      options: { title: "Initiative", type: "Epic" },
+    },
+    {
+      op: "create",
+      ref: "delivery",
+      options: {
+        title: "Delivery",
+        type: "Feature",
+        parent: "@initiative",
+      },
+    },
+  ],
+});
+
+const resolved = resolveItemMutationDocument(specificationJson, {
+  transactionId: "specification-2026-08-05-001",
+  idPrefix: "pm-",
+});
+await commitItemMutations({
+  pmRoot,
+  author: "specification-agent",
+  transactionId: "specification-2026-08-05-001",
+  mutations: resolved.mutations,
+});
+```
+
+`buildItemCompletionMutations` creates the ordered evidence/update, close, and
+release plan for inspection. `commitItemCompletion` executes that plan through
+the same durable coordinator, restoring annotations, linked artifacts,
+lifecycle fields, and claim ownership on failure. It is the SDK primitive
+behind `pm item complete`.
+
 `itemDocumentToMutationOptions` is the companion full-document adapter. It
 accepts either a direct `ItemDocument` or the envelope returned by
 `pm get <id> --json`, strips read-only metadata, maps canonical snake-case item
@@ -1281,9 +1365,11 @@ through the public `field` escape hatch.
 
 The built-in adapters stay deliberately thin:
 
-- `pm item mutate --transaction-id <stable-id> --stdin-json` validates and
-  commits a batch with `commitItemMutations`; `--dry-run` performs validation
-  only, and reusing the transaction id resumes or replays the durable journal.
+- `pm item mutate --transaction-id <stable-id> --stdin-json` resolves aliases,
+  validates, and commits a versioned batch; `--dry-run` returns the concrete
+  graph and alias receipt without writes.
+- `pm item complete <id> <reason> --transaction-id <stable-id>` records linked
+  evidence, closes, and releases a claim as one compensating transaction.
 - `pm create --stdin-json` and `pm update <id> --stdin-json` accept a whole item
   document. This supports the lossless `get → edit → update` agent workflow
   without translating every field into argv.
@@ -1779,7 +1865,29 @@ For provider-safe schemas, use `PM_PROVIDER_TOOL_PARAMETERS_SCHEMA`. It is flat
 | `registerSearchProvider`     | `search`            |
 | `registerVectorStoreAdapter` | `search`            |
 
-Some override surfaces are single-winner: command overrides, parser overrides, preflight overrides, and output renderers. Keep those handlers narrowly scoped and verify package combinations with:
+Some override surfaces are single-winner: command overrides, parser overrides,
+preflight overrides, and output renderers. Preflight overrides can declare
+static command ownership, allowing disjoint packages to compose without false
+collisions or unrelated callback invocations:
+
+```ts
+const preflight = definePreflightOverride({
+  commands: ["incident triage", "incident close"],
+  run: (context) => ({
+    enforce_mandatory_migration_gate:
+      context.decision.enforce_mandatory_migration_gate,
+  }),
+});
+
+api.registerPreflight(preflight);
+```
+
+Command paths are normalized. Two scoped overrides collide only when their
+ownership overlaps; an empty or omitted `commands` list retains legacy global
+behavior and collides with every other override. Activation summaries and
+persisted contribution inventories expose `preflight_ownership`, so doctor and
+static tooling can explain the decision. Keep handlers narrowly scoped and
+verify package combinations with:
 
 ```bash
 pm package doctor --project --detail deep --trace