@unbrained/pm-cli 2026.9.4 → 2026.9.6

package/docs/EXTENSIONS.md

@@ -91,11 +91,15 @@ Package roots declare resources in `package.json` under `pm`:
 ```
 
 Installation activates `pm.extensions`. `pm.docs`, `pm.examples`, `pm.assets`, and `pm.prompts` are catalog metadata (metadata-only — they are discovered and surfaced in the catalog but not executed). Declare agent-facing prompt/slash-command markdown under `pm.prompts` and non-code assets (images, skills, fixtures) under `pm.assets`; their conventional roots are `prompts/` (also `.agents/pm/prompts/`) and `assets/` (also `.agents/pm/assets/`).
-`pm package init` and its compatibility spelling `pm extension init` emit the same publishable root-extension artifact (`"extensions": ["."]`): package metadata, a typed `index.ts`, a colocated `node:test` suite, a strict type-check-only `tsconfig.json`, and `typecheck`/`test` scripts. Both results report the canonical `package_name` and exact `invocation_command`; an already prefixed target such as `pm-my-workflow` stays `pm-my-workflow` instead of becoming `pm-pm-my-workflow`. The manifest `entry` points at `./index.ts` itself (ADR [pm-2c28](../.agents/pm/decisions/pm-2c28.toon) / [pm-m1uz](../.agents/pm/decisions/pm-m1uz.toon)). pm loads that `.ts` entry directly via Node's native type stripping (Node >=22.18), so there is no build step — run `npm install` (for the peer SDK and type-checking) before `pm package install`. The generated README shows how to author exported command/hook definitions with the SDK [define\* builders](../.agents/pm/decisions/pm-3mph.toon). `--capability` selects one of ten scaffold starters (`commands`, `hooks`, `search`, `importers`, `schema`, `profile`, `renderers`, `parser`, `preflight`, `services`), each keeping a runnable starter command and adding the selected registration pattern plus a colocated `node:test` suite built on the matching SDK `assertRegistered*`/`runRegistered*ForTest` helpers. These are authoring selectors, not a one-to-one manifest-capability vocabulary: the `profile` starter registers a profile but declares the supported `schema` manifest capability because `api.registerProfile` is schema-governed. The option is repeatable for shell and config composition: repeating the same capability is idempotent, while combining distinct starter shapes fails with a usage error that asks the author to select one explicit scaffold capability. The full per-capability matrix (what each starter registers, which starters also declare `schema` because flag metadata is schema-governed, and why `schema`/`profile` omit `activation.commands` so their global contributions activate conservatively for every command) lives in [SDK.md — Minimal Command Extension](./SDK.md#minimal-command-extension). Starter manifests use the same least-privilege policy metadata as pure first-party command packages: `trusted: true`, `sandbox_profile: "strict"`, and explicit `false` permissions for `fs_read`, `fs_write`, `network`, `env_read`, `env_write`, and `process_spawn`. Declarative starters import `manifest.json` in their generated test and call `assertExtensionManifestMatchesBlueprint`, so capability drift fails locally before publication. Larger packages may point at nested extension directories after declaring runtime dependencies, relaxing only the permissions they actually need, and validating with `pm package doctor`, which additionally emits the advisory `extension_schema_narrow_activation` warning when a package registers custom item types/fields yet declares narrow `activation.commands` (the schema footgun above), recommending the field be dropped so the type stays globally available.
-Package tests can pair `readPmPackageManifest(packageRoot)` with
-`assertPackageManifest(manifest, { resources: ... })` from
-`@unbrained/pm-cli/sdk` to prove aliases and resource paths without duplicating
-pm's manifest normalization logic.
+`pm package init` (and compatible `pm extension init`) creates a publishable root extension (`"extensions": ["."]`):
+
+- The artifact includes package metadata, typed `index.ts`, a colocated `node:test` suite, strict type-check-only `tsconfig.json`, and `typecheck`/`test` scripts. Results report canonical `package_name` and exact `invocation_command`; an existing `pm-` prefix is retained once.
+- The manifest points to `./index.ts`, loaded by native TypeScript stripping on Node >=22.18 ([pm-2c28](../.agents/pm/decisions/pm-2c28.toon), [pm-m1uz](../.agents/pm/decisions/pm-m1uz.toon)). Run `npm install` for the peer SDK and type checking before package installation; no build step is required. The README demonstrates the SDK [define* builders](../.agents/pm/decisions/pm-3mph.toon).
+- `--capability` selects `commands`, `hooks`, `search`, `importers`, `schema`, `profile`, `renderers`, `parser`, `preflight`, or `services`. Every starter keeps a runnable command and adds matching SDK `assertRegistered*`/`runRegistered*ForTest` tests. Repeating one selection is idempotent; distinct selections fail with an actionable usage error.
+- Scaffold selectors and manifest capabilities differ: `profile` registers a profile under `schema`. The [capability matrix](SDK.md#minimal-command-extension) explains each registration, schema-governed flags, and why `schema`/`profile` omit narrow `activation.commands` so their contributions stay globally available.
+- Starter manifests declare `trusted: true`, `sandbox_profile: "strict"`, and explicit false permissions for filesystem, network, environment, and subprocess access. Declarative tests import `manifest.json` and call `assertExtensionManifestMatchesBlueprint`, detecting capability drift before publication.
+- Larger packages may use nested extension directories and declare required runtime dependencies and permissions. Validate with `pm package doctor`; its advisory `extension_schema_narrow_activation` finding recommends removing narrow activation when custom item types or fields need global availability.
+Package tests can pair `readPmPackageManifest(packageRoot)` with `assertPackageManifest(manifest, { resources: ... })` from `@unbrained/pm-cli/sdk` to prove aliases and resource paths without duplicating pm's manifest normalization logic.
 
 When no package manifest is present, `pm` discovers conventional extension directories:
 
@@ -115,7 +119,11 @@ Runtime path overrides:
 - `PM_PATH`: project tracker root
 - `PM_GLOBAL_PATH`: global profile root
 
-Extensions are authored **and loaded** as TypeScript (ADR [pm-2c28](../.agents/pm/decisions/pm-2c28.toon) / [pm-m1uz](../.agents/pm/decisions/pm-m1uz.toon)): a minimal standalone extension has a `manifest.json` and a TypeScript `index.ts` entrypoint the loader imports directly by file URL via Node's native type stripping (Node >=22.18) — there is no compile step and no `./index.js`. Author against the SDK types with `import type { ExtensionApi }` — the type-only import is erased on load, so the `.ts` entry carries **no runtime import** of `@unbrained/pm-cli` (standalone entries are loaded outside any `node_modules`, so a runtime SDK import would fail). Type-check with `npx tsc --noEmit` after installing `typescript` and `@unbrained/pm-cli` for the type resolution.
+Extensions are authored and loaded as TypeScript ([pm-2c28](../.agents/pm/decisions/pm-2c28.toon), [pm-m1uz](../.agents/pm/decisions/pm-m1uz.toon)):
+
+- A minimal standalone extension has `manifest.json` and `index.ts`. Node >=22.18 loads that entry directly with native type stripping; no compilation or `index.js` is required.
+- Use `import type { ExtensionApi }` for erased SDK types. Standalone entries outside `node_modules` need the host SDK link described below before using runtime SDK imports.
+- Install `typescript` and `@unbrained/pm-cli`, then run `npx tsc --noEmit` to check authoring types.
 
 ```json
 {
@@ -279,7 +287,7 @@ Surface tokens include command handlers/overrides, parser/preflight/services/ren
 
 Some extension surfaces are intentionally single-winner: command handlers and overrides, parser overrides, preflight overrides, and format renderers. Activation is deterministic: lower manifest `priority` values load first, omitted priority defaults to `100`, equal priorities sort by package identity/path, and the last registration wins. If multiple packages register the same single-winner surface, `pm package doctor` / `pm health` report deterministic `extension_*_collision` warnings whose suffix names the winning layer/package before the displaced layer/package. `pm package describe --json` also exposes `command_ownership`: every claimant in activation order, the effective winner, collision state, and the explicit `last_activated_wins` policy. SDK hosts can build the identical table with `buildExtensionDescribeResult` and the exported `ExtensionCommandOwnership` contracts. Renderer ownership is evaluated per command: same-format renderers with disjoint `commands` lists safely coexist, while an unscoped or overlapping claim still warns; runtime `resultDiscriminator` predicates alone cannot prove static disjointness. Tracked by [pm-6mjxgq](../.agents/pm/issues/pm-6mjxgq.toon).
 
-For definition-based commands, validation is isolated per command: a malformed definition is recorded as `extension_command_quarantined:*` with a registration trace while valid siblings continue to activate. Unknown-command recovery reports that failure without recommending reinstallation.
+For definition-based commands, a malformed definition is recorded as `extension_command_quarantined:*` with a registration trace. Activation then rolls back all registrations from that extension, preserving atomic package activation. Fix the failed definition before expecting sibling commands to load. Other valid extensions retain their registrations.
 Use the warning details to resolve the overlap:
 
 ```bash
@@ -294,12 +302,6 @@ Doctor JSON also includes `triage.collision_plan` with grouped surfaces, ranked
 
 Use the public SDK barrel. Do not deep-import from `src/core` or `dist/core`.
 
-```ts
-import { defineExtension } from "@unbrained/pm-cli/sdk";
-```
-
-Common APIs:
-
 - `api.extension` is a read-only identity (`name`, `layer`, `version`, `capabilities`, `pm_min_version?`, `pm_max_version?`, `source_package?`) for self-identifying logs and version gating without re-reading the manifest.
 - `api.registerCommand(definition)` adds package-owned commands.
 - `api.registerFlags(command, flags)` adds runtime command flags. A flag may declare `value_type` (canonical; the legacy `type` alias is honored only when `value_type` is absent), `list: true` to accumulate repeated/comma-joined values like core `--tags`, and a `default` applied when the flag is omitted.
@@ -331,6 +333,8 @@ pm contracts --runtime-only --schema-only --json
 pm contracts --command <command> --flags-only --json
 ```
 
+`CliFlagContract.reservation_scope` tells package authors which host flags are reserved: `inherited` flags (including their aliases) cannot be redeclared by extensions; `root_only` flags belong only to the root command. The public `GLOBAL_FLAG_CONTRACTS` table from `@unbrained/pm-cli/sdk/contracts` exposes the same classification used by runtime validation. For example, an extension may define its own boolean `--explain`; root `pm --explain` keeps its host meaning. Redeclaring inherited `--json` fails validation and rolls back that package's activation. See [pm-2h8t6y](../.agents/pm/issues/pm-2h8t6y.toon).
+
 List-valued inline flags and `registerFlags` entries share one ordered
 accumulator across their long and short aliases. For a variadic positional that
 must receive values such as `-h` or `--json`, put the end-of-options separator
@@ -381,8 +385,6 @@ pm package reload --project
 pm package reload --project --watch
 ```
 
-Compatibility equivalents remain available through `pm extension ...` for existing automation.
-
 ## Upgrade Workflow
 
 `pm package upgrade` is the package-first update entrypoint:
@@ -443,7 +445,4 @@ Prefer `createExtensionTestHarness(module, { capabilities })` in package unit te
 
 ## Runnable Examples
 
-- `docs/examples/starter-extension/`
-- `docs/examples/policy-restricted-extension/`
-- `docs/examples/sdk-contract-consumer/`
-- `docs/examples/sdk-app-embedding/`
+See the [starter](examples/starter-extension/README.md), [policy-restricted](examples/policy-restricted-extension/README.md), [SDK contract consumer](examples/sdk-contract-consumer/README.md), and [SDK application](examples/sdk-app-embedding/README.md) examples.

package/docs/HISTORY_RECOVERY.md

@@ -0,0 +1,146 @@
+# History durability and recovery
+
+Tracked by [pm-96fsma](../.agents/pm/issues/pm-96fsma.toon),
+[pm-m0yjtg](../.agents/pm/issues/pm-m0yjtg.toon),
+[pm-qw1uw6](../.agents/pm/issues/pm-qw1uw6.toon),
+[pm-e3gn0z](../.agents/pm/issues/pm-e3gn0z.toon), and
+[pm-wlqxg3](../.agents/pm/tasks/pm-wlqxg3.toon).
+
+Project management depends on trustworthy context. History is not just an
+activity feed: it is the reconstructable source for prior item states, including
+their evidence, relationships, and lifecycle transitions. Recovery must not
+manufacture missing context or silently change an item's identity.
+
+## Stable addresses after compaction
+
+`pm get <id> --at <version>` and `pm restore <id> <version>` use durable,
+one-based version addresses. Compaction checkpoints the last compacted state
+at its original version. Retained entries keep their addresses, including after
+repeated compactions. Versions before the checkpoint fail with
+`history_version_pruned`; they never select a different retained entry.
+
+The checkpoint records `history_compaction.version_offset`. Add that offset to
+a physical one-based stream position to obtain its durable version. `pm history`
+reports `version_addressing`, and compact rows include their `version` alongside
+the physical `index`. Verification error ordinals and diff indices remain
+physical positions in the current stream. The checkpoint timestamp is the last
+compacted entry's timestamp; the maintenance audit event records compaction time.
+
+Legacy checkpoints without a recorded offset cannot prove their original
+numeric addresses. Numeric reads fail with `history_version_mapping_unavailable`.
+Use a retained timestamp instead; the SDK then returns `as_of_version: null`.
+SDK consumers must handle this nullable value. `target.historyIndex` is always
+the resolved physical zero-based position, not an original version number.
+Default and timestamp-based compaction remain available for these legacy
+streams. They preserve an unknown offset as `null`, including no-op results;
+compaction never manufactures a numeric mapping from physical positions.
+
+## Recover an unreadable item file
+
+```bash
+pm history <id> --full
+pm restore <id> <version>
+pm history <id> --verify --strict-exit
+```
+
+Restore accepts an absent file or an unparsable item document when intact
+history can reconstruct it. It verifies the history before using the recovered
+state, preserves the original unreadable bytes for rollback, and uses the normal
+ownership and lock checks. Successful recovery reports
+`restore_unreadable_item_recovered`. Permission errors and unresolved merge
+conflicts are not treated as missing files. A missing initial baseline returns
+`history_baseline_unavailable` with recovery guidance rather than inventing
+metadata from a partial patch.
+
+CLI shape errors name the item ID, file path, and zero-length files. The SDK
+error context also includes byte length and an explicit empty-file flag.
+`pm health --check-only` names malformed item paths and invalid
+history lines without mutating either file; use those diagnostics to select the
+specific recovery operation above.
+
+Invalid UTF-8 is a separate refusal (`item_document_encoding_invalid`), not a
+recoverable text parse failure. Preserve a binary backup before recovering such
+a file; text decoding must never silently replace original bytes.
+Its SDK error context identifies the item ID, path, byte length, and nonempty
+state just as text-shape diagnostics do.
+
+## Recover an invalid history tail
+
+Keep a local backup before applying destructive history maintenance. Preview
+exactly one stream, inspect the receipt, then explicitly apply:
+
+```bash
+pm history-repair <id> --salvage-tail --dry-run --json
+pm history-repair <id> --salvage-tail --json
+pm history <id> --verify --strict-exit
+```
+
+Salvage requires a nonempty, hash-verified prefix and retains its bytes unchanged.
+The receipt records the first invalid physical line, discarded UTF-8 byte count,
+discarded-suffix SHA-256, and retained record count. An appended `history_salvage`
+event records that receipt without copying potentially private damaged contents.
+Salvage does not rehash prior entries, reconcile item state, or normalize
+provenance. It refuses bulk selection, conflicting repair modes, merge conflict
+markers, parseable records after corruption, and potentially complete records
+with attached corruption. Recover those cases from version control or a backup.
+Non-UTF-8 streams are also refused, so receipt hashes and rollback snapshots
+always describe the original bytes rather than a lossy decoded approximation.
+
+The public SDK uses the same operation:
+
+```ts
+import { PmClient } from "@unbrained/pm-cli";
+
+const client = new PmClient({ pmRoot: "/project/.agents/pm" });
+const preview = await client.historyRepair("pm-example", {
+  salvageTail: true,
+  dryRun: true,
+});
+console.log(preview.salvage);
+```
+
+The CLI and MCP expose this SDK-owned contract; package authors do not need a
+separate recovery implementation.
+
+## Permanent item identities
+
+Deleting an item retains its identity reservation through its history file.
+Generated IDs skip those reservations, even under reproducible execution.
+Explicit recreation fails with `item_identity_reserved`; use restore to recover
+the original subject, or create a new ID for unrelated work.
+The first `create` append exclusively creates its effective history file, so
+concurrent SDK callers and extension redirects cannot both reserve it. A failed
+partial first write keeps the reservation for diagnosis; it is never deleted
+to make the identity reusable. Subsequent large-record appenders still need the
+normal item lock or an equivalent caller-owned serialization boundary.
+
+Verification refuses a second `create` event, including one imported through
+branch union, and names both physical ordinals. Point-in-time reads cannot cross
+that discontinuity silently. Recover the original streams rather than rehashing
+two unrelated subjects into a single supposedly valid item.
+
+`pm validate --check-history-drift` reports this as an error, with item ID,
+original and repeated genesis ordinals, and the observed sequence. The public
+`findHistoryIdentityDiscontinuities` SDK primitive provides the same evidence
+for importers. A delete followed by create is distinguished from multiple creates
+or a checkpoint followed by create; these observations do not prove which
+writer or branch introduced the records. Old drift caches are invalidated, and
+known-invalid streams are reread even in metadata-cache mode.
+
+## Regression verification
+
+```bash
+node scripts/run-tests.mjs test -- tests/integration/history-durability.integration.spec.ts
+node scripts/run-tests.mjs test -- tests/integration/history-maintenance-replay.integration.spec.ts
+```
+
+The fixture drives real CLI lifecycle mutations, independently captures each
+serialized state, removes the live item file, and compares every addressable
+version against those captures. Companion cases exercise repeated compaction,
+legacy mapping refusal, seeded identity reuse, invalid-tail preservation,
+unreadable-file recovery, and missing baselines. Maintenance fixtures additionally
+perform redaction and a real divergent Git merge, compare every version with an
+independent strict patch fold, and compare the final state with a separately
+read item. Concurrent writes and binary corruption are negative controls, not
+mocked successful outcomes. All fixtures use temporary trackers, never repository
+tracker data.

package/docs/MERGE_SAFETY.md

@@ -186,6 +186,53 @@ receipt file that the older writer never created. Incomplete, contradictory, or
 modern summaries still fail closed. `runMergeReceiptReport` remains the
 compatible valid-only report.
 
+## Historical receipt reader compatibility
+
+Tracked by [pm-2xtv84](../.agents/pm/issues/pm-2xtv84.toon) and
+[pm-v66zir](../.agents/pm/issues/pm-v66zir.toon). Version-1 preferred-era and
+identified `requested_preference`/`clone_local` receipts may omit `base`, `ours`,
+or `theirs` when the original value was undefined. Readers normalize those slots to the explicit missing-value marker
+in memory. They still require retained/discarded evidence and valid collections;
+reading never rewrites the original file. Collection failures expose a bounded
+`validation_path`, such as `union_fields` or `decisions[0]`. The diagnostic
+category `collections` is not a property that should be added to a receipt.
+The writer now encodes all five scalar slots itself, including undefined
+retained/discarded values supplied directly through the SDK, before JSON storage.
+
+Paired clone-local and historical hash-only copies accept the original scalar
+hash encoding throughout inspection and settlement. Compatibility does not
+apply to durable copies declaring the modern value policy. Changed values or
+immutable coordinates remain copy-provenance failures. Hash-only evidence
+does not recover the original private value.
+
+## Receipts from an aborted rebase
+
+Tracked by [pm-466m0j](../.agents/pm/issues/pm-466m0j.toon). New receipts
+created during a rebase capture only its original commit and item blob in the
+typed `MergeReceiptOperation` contract. After aborting, run:
+
+```bash
+pm merge reconcile --dry-run --json
+pm merge reconcile --message "Record restored original rebase state" --json
+```
+
+Settlement requires Git to have left every active merge/rebase/cherry-pick/revert
+operation, HEAD to match the original commit, and the item in HEAD, index, and
+working tree to match the original blob. The item history must already be clean.
+The history transaction rechecks the proof against its exact protected item
+snapshot. Apply appends an explicit `merge_reconcile` event with
+`abandoned_receipts` and the reason `original_git_state_restored`; it then marks
+both copies reconciled with that settlement reason. The result counts these in
+`receipts.abandoned`, separately from applied merge decisions. Preview performs
+the same eligibility checks and leaves both history and receipts untouched.
+If receipt persistence fails after the audit commits, retry reuses the identical
+verified disposition and finishes the receipt writes without appending another
+audit event. An unrelated earlier audit does not satisfy this check.
+
+Old receipts without operation coordinates remain pending for ordinary review.
+Tracked `merge-receipts/` sidecars are durable provenance and must remain tracked.
+Deleting or ignoring them would lose the evidence needed by other clones.
+
 ## Cross-branch id collision safety
 
 Item ids are `<prefix>` plus random base36 characters, and uniqueness is only probed against the local working tree — two agents branching from the same commit can mint the same id for different items (GH-600 / pm-pibw). Two controls bound that risk:
@@ -210,6 +257,9 @@ pm merge reconcile --force --message "Accept reviewed merge decisions" --json
 ```
 
 The preview reports every drifted stream and pending receipt without mutation.
+It applies the same exact-snapshot proof requirement as apply: stale or
+unprovable receipts appear as failed streams in both modes, tracked by
+[pm-ao0bu9](../.agents/pm/issues/pm-ao0bu9.toon).
 Lossless receipts do not become discarded-value decisions and reconcile without
 `--force`, but `pm health` reports `merge_receipts_pending:<n>` and remains
 non-green until the apply pass settles them. `pm history-repair` cannot clear

package/docs/OUTPUT_PROJECTION_CONTRACTS.md

@@ -265,11 +265,77 @@ These are corpus-generated figures, not live tracker payloads. The generated
 corpus contains 2,243 items; the `status:all` query intentionally excludes 245
 canceled fixtures under the command's current status-selection contract.
 
+## Health Verdicts
+
+Tracked by [pm-fkohe8](../.agents/pm/issues/pm-fkohe8.toon) and
+[pm-du93sr](../.agents/pm/issues/pm-du93sr.toon).
+
 `health --check-only` defaults to a summary verdict: all checks still run, but
 passing check evidence bodies are empty. Use `health --check-only --full` when
 diagnostic evidence is required. Explicit `--brief` or `--summary` retains the
 existing fast check-only mode that skips expensive optional scans.
 
+Use top-level `ok` to decide health. Each `checks[].ok` uses the same rule:
+true means no gate-failing findings belong to that check. A check can therefore
+have `status: "warn"` and `ok: true` when all its findings are advisory.
+`failed_because` names every deciding warning, including findings beyond the
+bounded warning sample. `findings[].severity` distinguishes advisory from
+`gate_failing` evidence without parsing prose.
+
+The `verdict` receipt names `authority: "ok"` and the invocation's `exit_code`.
+`strict_exit: true` and `require_merge_drivers: true` appear only when enabled;
+omission means false. The default invocation reports blocking findings without
+changing the process exit code. `--strict-exit` (alias `--fail-on-warn`) requires
+clone-local merge drivers and exits `1` when `ok` is false. Other advisory
+warnings retain their policy. Compare invocations with the same scan and policy
+options: enabling strict mode can legitimately change a missing-driver finding
+from advisory to blocking. The SDK accepts `strictExit` and `failOnWarn` with
+the same semantics, including MCP dispatch. Required merge-driver enforcement
+always runs the integrity check, even when `skipIntegrity` or an explicit compact
+check-only projection would otherwise skip optional integrity work.
+
+The required token corpus measures `health --check-only` on its medium workspace
+under the `health-default` ceiling. Its positive and negative controls run in
+the same repository quality composition as the other answer budgets. Full
+evidence remains an explicit restore path; the verdict receipt does not raise
+the existing default token ceiling.
+
+## Linked-File Repair Rows
+
+Tracked by [pm-zw9188](../.agents/pm/issues/pm-zw9188.toon).
+
+`validate --check-files` joins each missing path with its holders, lifecycle
+states, link fields, and candidate destinations before applying output limits.
+`missing_linked_path_rows` contains structured objects in both default and
+`--verbose-file-lists` output. The default caps paths and holders per path at
+40; verbose output restores both collections. `items_truncated` and
+`missing_linked_path_rows_truncated` identify the two independent omissions.
+
+`validate --counts` omits false `*_truncated` markers to keep its summary compact.
+True truncation markers, ordinary false values, and every zero count remain;
+its projection receipt declares that diagnostic rows were omitted.
+
+Counts describe the complete scanned population:
+
+- `missing_linked_links_count` counts distinct path, holder, and field triples.
+- `missing_linked_path_rows_count` counts distinct paths.
+- `active_missing_linked_links_count` and `active_missing_linked_paths_count`
+  identify actionable work under the configured workflow registry.
+- `legacy_closed_missing_linked_links_count` is the close-status subset of
+  `legacy_terminal_missing_linked_links_count`.
+
+Only active missing paths cause the missing-link warning. Historical terminal
+links remain visible for context reconstruction. Unknown statuses and absent
+holder metadata remain actionable. Rows and holders prioritize active work.
+Package authors can build the same pure report with
+`buildLinkedFileRepairReport` from `@unbrained/pm-cli/sdk/governance` and choose
+an explicit finite ceiling or `Infinity` for full output.
+
+Same-basename destinations are possibilities requiring review. Missing CSV or
+`path:note` literals receive `malformed` classification and no inferred move;
+explicit pruning never removes that category. Existing literal filenames are
+checked before classification, including names containing commas or colons.
+
 ## Completion Resolver Contract
 
 `resolveCompletionTimestamp` accepts legacy metadata where all timestamp fields

package/docs/PR_REVIEW_LOOP.md

@@ -1,19 +1,24 @@
 # Pull Request Review Loop
 
-Trackers: [pm-hq28](../.agents/pm/tasks/pm-hq28.toon), [pm-cp5pbo](../.agents/pm/tasks/pm-cp5pbo.toon)
+Trackers: [pm-hq28](../.agents/pm/tasks/pm-hq28.toon), [pm-cp5pbo](../.agents/pm/tasks/pm-cp5pbo.toon), [pm-8we38i](../.agents/pm/issues/pm-8we38i.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
 top-level comments, submitted reviews, inline review threads, edited timestamps,
 reaction state, thread resolution, outdated markers, and the reviewed head SHA.
 
+GitHub command responses have a 64 MiB transport bound and fail visibly on overflow;
+an overflow never certifies a complete inventory. Acknowledgement lookups retain
+every page but project only comment IDs, bodies, and reply-parent IDs before
+capture, avoiding repeated diff hunks that are irrelevant to marker matching.
+
 ```bash
 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 acknowledge --pr 123 --node-id PRR_kw... --revision '<revision>' --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."
+node scripts/reviews/pr-review-loop.mjs acknowledge-inline --pr 123 --comment-id 456 --node-id PRRC_kw... --revision '<revision>' --reaction THUMBS_UP --body "Addressed in abc123."
 ```
 
 Choose `THUMBS_UP` when feedback is useful or correct and `THUMBS_DOWN` when a
@@ -28,6 +33,16 @@ 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.
 
+Each comment and review also carries a `revision`: a SHA-256 identity of its
+body and review state. Compare these identities after each completed check watch
+and immediately before merge. A changed body or review verdict needs fresh
+triage even when its node ID already has an acknowledgement. Reaction timestamp
+changes alone do not create a new revision. Pass the observed revision to both
+`acknowledge` and `acknowledge-inline` with `--revision <revision>`; their hidden
+markers then distinguish revised feedback and suppress duplicate retry replies
+for that same revision. Inline markers are matched only within the selected
+reply thread. Legacy calls without the flag retain their existing behavior.
+
 After every push or reviewer retrigger, run `watch`. It delegates waiting to
 `gh pr checks --watch`, because reviewer agents report completion through GitHub
 checks, and only fetches the complete conversation inventory after those checks

package/docs/README.md

@@ -81,6 +81,7 @@ pm guide release --json
 - [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.
+- [SDK execution and recovery contracts](SDK_EXECUTION_CONTRACTS.md): schema-driven scheduling, handoff, and command recovery.
 - [Multi-Branch Merge Safety](MERGE_SAFETY.md) - semantic tracker merge drivers, post-merge integrity gates, delete/modify policy, and recovery-receipt retention.
 - [Codex Plugin](CODEX_PLUGIN.md) - native MCP plugin install, tools, skills, and safety notes.
 - [Native ChatGPT and Codex Plugin Implementation Plan](CHATGPT_CODEX_PLUGIN_IMPLEMENTATION.md) - official-source
@@ -90,6 +91,17 @@ pm guide release --json
 - [Releasing](RELEASING.md) - maintainer release checklist and failure handling.
 - [starter extension](examples/starter-extension/README.md) - compact extension scaffold reference.
 
+Additional SDK, operations, and generated contracts:
+
+- [Item Read Projections](ITEM_READ_PROJECTIONS.md) - identity, projections, and read completeness.
+- [MCP Capability Surfaces](MCP_CAPABILITY_SURFACES.md) - negotiated MCP discovery contracts.
+- [PR Review Loop](PR_REVIEW_LOOP.md) - complete review inventories and feedback acknowledgment.
+- [SDK Lifecycle](SDK_LIFECYCLE.md) - lifecycle primitives and package integration.
+- [SDK Runtime Boundaries](SDK_RUNTIME_BOUNDARIES.md) - runtime ownership and import boundaries.
+- [Sentry Contract Epochs](SENTRY_CONTRACT_EPOCHS.md) - diagnostic compatibility and release epochs.
+- [Generated Agent Command Surface](generated/AGENT_COMMAND_SURFACE.md) - command routing inventory.
+- [Generated Flag Lexicon Budgets](generated/FLAG_LEXICON_BUDGETS.md) - flag vocabulary and budget inventory.
+
 ## Guide Topic Map
 
 | Optional `pm guide` topic | Primary docs                                                                                        |
@@ -151,4 +163,10 @@ Public docs must not link to ignored local operations artifacts, unpublished evi
 - Put a short "Agent Quick Context" near the top of deep docs.
 - Prefer commands that agents can copy exactly.
 - Use `pm` item IDs as durable references when docs explain tracked work.
-- Run link/search checks before closing documentation tasks.
+- Run `pnpm quality:docs-links` before closing documentation tasks. Every Markdown
+  page under `docs/` must be reachable transitively from this index, and links to
+  heading fragments must resolve. Fenced examples do not create navigation edges.
+- A deliberately standalone page requires an individual path and nonempty reason
+  in `scripts/release/docs-reachability-exceptions.json`; stale exceptions fail.
+  This policy is tracked by [pm-s4y3z4](../.agents/pm/chores/pm-s4y3z4.toon)
+  and [pm-esbt](../.agents/pm/tasks/pm-esbt.toon).

package/docs/RELEASING.md

@@ -30,7 +30,10 @@ authoritative blocker-recovery run selection by
 [pm-db8onn](../.agents/pm/issues/pm-db8onn.toon), and queued automatic
 same-day recovery by [pm-dm2vfz](../.agents/pm/issues/pm-dm2vfz.toon).
 Bounded Sentry request latency is tracked by
-[pm-b9g2cs](../.agents/pm/issues/pm-b9g2cs.toon).
+[pm-b9g2cs](../.agents/pm/issues/pm-b9g2cs.toon), and exact-tag changelog
+stabilization by [pm-e63v1x](../.agents/pm/issues/pm-e63v1x.toon). Dual-phase
+package sizing around Sentry injection is tracked by
+[pm-llbnua](../.agents/pm/issues/pm-llbnua.toon).
 
 ## Version Policy
 
@@ -278,8 +281,12 @@ The automatic release commit is the sole non-identical-tree derivation. The
 gate requires one parent, the canonical release subject and body, an immutable
 `v<version>` tag resolving to the candidate, the complete expected manifest
 inventory, exact old-version to new-version substitutions in every manifest,
-and an exact `Unreleased` changelog-heading replacement. It then resolves the
-parent through the same exact or reviewed identical-tree analyzer contract.
+and an exact `Unreleased` changelog-heading replacement. The package-generated
+replacement may be `## <version>` or the historical
+`## <version> - <YYYY-MM-DD>` form, with the date matching the calendar version.
+The complete heading must match and every other changelog byte must remain
+unchanged. The gate then resolves the parent through the same exact or reviewed
+identical-tree analyzer contract.
 Added, deleted, renamed, missing, or otherwise modified paths are refused, as
 are malformed manifests, changelog edits, untagged commits, and parents without
 successful analyzer evidence. The receipt reports
@@ -333,7 +340,12 @@ The static phase includes `pnpm sdk:surface:check`,
 `pnpm benchmark:transport:check`. The packaging phase runs
 `pnpm quality:package-artifact`, which evaluates npm's actual packlist against
 the committed unpacked-size, file-count, required-runtime-file, and forbidden
-source-map budgets. Additive SDK exports require a reviewed
+source-map budgets. Release additionally reruns the packlist gate immediately
+after Sentry debug-ID injection and before any Sentry upload or finalization,
+using the separately committed `sentry-injected` ceiling. CI constrains the base
+build, publication constrains the exact mutated artifact users install, and a
+rejected package cannot leave finalized observability artifacts. Additive SDK
+exports require a reviewed
 snapshot refresh. A removal or semantic signature change fails until the
 maintainer supplies
 `pnpm sdk:surface:update -- --acknowledge-breaking "<release rationale>"`;
@@ -353,23 +365,27 @@ 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. An isolated anonymous exact-version probe keeps already-published 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
+- manual `workflow_dispatch` by tag for recovery. An isolated anonymous exact-version probe keeps already-published recovery on the reviewed dispatch-time `main` source; when the immutable tag exists but npm publication never completed, recovery preserves the reviewed package gate and budget in runner-temporary storage before checking out that exact tagged source. The controls inspect the untouched tagged package without becoming part of it, so recovery applies the current fail-closed distribution policy while retaining the original version guard and immutable package bytes.
 - pnpm install with frozen lockfile
 - version policy and tag guard
 - secret scan
 - 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. Recovery of an unpublished
-  immutable tag regenerates only `CHANGELOG.md` with the tagged checkout's
-  canonical package script and fails if that operation changes any other
-  tracked source path (apart from managed-extension install metadata).
+  managed extension's linked files as missing. Every exact-tag source,
+  including an ordinary tag push and recovery of an unpublished immutable tag,
+  regenerates only `CHANGELOG.md` with the tagged checkout's canonical package
+  script and fails if that operation changes any other tracked source path
+  (apart from managed-extension install metadata). Reviewed `main` recovery
+  sources retain the non-mutating drift check.
 - 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; Sentry requests use the fail-closed bounded `--sentry-request-timeout-ms` contract (default `120000`, maximum `300000`); `--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.
 - sandboxed `pm` coverage
-- optional Sentry release metadata and sourcemap upload when `SENTRY_AUTH_TOKEN` is configured
-- npm pack dry run and npx tarball smoke test
+- a base npm pack dry run, optional Sentry debug-ID injection, a second
+  `sentry-injected` packlist budget over the exact publishable bytes, and only
+  then optional Sentry release metadata/upload/finalization and the npx tarball
+  smoke test
 - generated release notes from changelog plus sanitized tracker metadata
 - artifact uploads
 - `npm publish --access public --provenance --tag latest`, skipped on retry
@@ -458,8 +474,10 @@ Use the npm registry package for maintainer global updates. Do not use `npm inst
   the existing immutable tag, reapplies the version guard, installs the managed
   changelog extension, regenerates the package changelog with the tagged
   checkout's canonical policy under a tracked-path mutation guard, and permits
-  first publication only from that tagged source. Other registry failures stop
-  before source selection or publication.
+  first publication only from that tagged source. Ordinary tag-push releases
+  use the same guarded regeneration because their tag did not exist when the
+  release commit's changelog was prepared. 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.

package/docs/SDK_CONTEXT_TRUTH_CONTRACTS.md

@@ -1,7 +1,9 @@
 # SDK Context Truth Contracts
 
 Tracker references: [pm-23xkss](../.agents/pm/issues/pm-23xkss.toon) and
-[pm-r8u2g6](../.agents/pm/issues/pm-r8u2g6.toon).
+[pm-r8u2g6](../.agents/pm/issues/pm-r8u2g6.toon),
+[pm-79gv6q](../.agents/pm/issues/pm-79gv6q.toon), and
+[pm-08mt4k](../.agents/pm/issues/pm-08mt4k.toon).
 
 ## Agent Quick Context
 
@@ -68,3 +70,24 @@ silently route tracker files through the wrong merge behavior. Run
 This policy does not weaken storage, history, merge-fence, or pending-receipt
 checks. It only distinguishes an optional never-installed clone capability
 from a broken capability that the repository appears to rely on.
+
+## Population and Focus Are Separate
+
+`context.summary.scope` is `matching_items`: lifecycle totals describe all items
+matching the request filters and parent subtree before the focus limit, intent
+projection, and token packing. Without filters this is the workspace population.
+`active_items`, `in_progress`, `open`, and `blocked` use that same population as
+`total_items`, `closed`, and `canceled`. `open` includes active statuses other than
+in-progress; `blocked` is an overlapping classification that includes unresolved
+dependency edges as well as blocked lifecycle states.
+
+`summary.returned_focus` reports the bounded focus selection. The existing
+`high_level` and `low_level` counts describe their emitted rows. An orient or
+handoff response limited to one row can therefore still report hundreds of open
+items. `omission_receipt.summary_scope` repeats `matching_items` so a consumer
+reading projection metadata cannot confuse omitted detail with absent work.
+
+Never infer a population count from an array length. To visit individual items,
+follow the response's continuation and omission receipts. To schedule work, use
+the shared [execution contracts](SDK_EXECUTION_CONTRACTS.md), which keep human
+input, gates, and containers visible without dispatching them by default.