@unbrained/pm-cli 2026.9.5 → 2026.9.7

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

@@ -91,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                                                                                        |
@@ -152,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

@@ -99,6 +99,7 @@ Policy:
   manifest changed by version substitution alone, and only the generated
   changelog heading changed. Any other path or content still fails closed
 - `CHANGELOG.md` is generated by the latest npm `pm-changelog` package (`pm install npm:pm-changelog --project`, then `pm changelog generate --mode replace --all-release-tags`) from closed tracker items across git release tag windows and checked in CI; do not edit it by hand
+- Release preparation passes `--date-from-version` with the target calendar version so the generated heading already has its UTC release date before the tag exists. This keeps the preparation commit consistent with canonical post-tag generation and the normal `main` changelog check.
 - protected-branch pushes require `RELEASE_PAT`; Auto Release fails fast before the expensive release gates when `push=true`, `dry_run=false`, and that secret is not configured
 - release reliability gating requires `SENTRY_PERSONAL_ADMIN_TOKEN` for issue-threshold checks; Auto Release fails before creating the version commit/tag when the token is missing and `push=true`, while sourcemap upload remains optional through `SENTRY_AUTH_TOKEN`
 - after creating and pushing a new tag, auto-release waits for the tag-push `.github/workflows/release.yml` run to finish instead of dispatching a second publish workflow
@@ -281,8 +282,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

package/docs/SDK_LIFECYCLE.md

@@ -39,6 +39,33 @@ Package authors can import these operations from `@unbrained/pm-cli/sdk`
 without importing CLI modules or spawning the executable. Existing CLI import
 paths remain source-compatible while integrations migrate.
 
+## Relationship Identity
+
+Tracked by [pm-olcoon](../.agents/pm/issues/pm-olcoon.toon).
+
+`normalizeItemReference(reference, prefix, sourceKind?)` is the shared public
+SDK primitive for parent and dependency identities. Local shorthand, optional
+leading `#`, and case variants normalize to the workspace's canonical prefix.
+Explicit URL or provider locators (`github:`, `gitlab:`, `jira:`, `linear:`)
+retain their spelling and case; externally sourced dependency IDs do too.
+Only surrounding whitespace is trimmed from remote identities.
+
+Create, update, and plan materialization persist the canonical local parent,
+so lookup success cannot leave an unresolved shorthand in the stored graph.
+Explicit remote parents remain external references without a local
+missing-parent warning. Local missing parents still follow workspace policy,
+and self-parent and hierarchy-cycle checks remain enforced. A foreign-looking
+bare string is treated as local unless external provenance is supplied; the
+SDK does not guess a remote workspace from punctuation.
+
+```ts
+import { normalizeItemReference } from "@unbrained/pm-cli/sdk";
+
+normalizeItemReference("#ABC", "team-"); // team-abc
+normalizeItemReference("github:Org/Repo#42", "team-"); // unchanged
+normalizeItemReference("OTHER-Case", "team-", "external"); // unchanged
+```
+
 ## Reason Contract
 
 `resolveTerminalReason` is the pure precedence primitive. It chooses the first

package/docs/SDK_RUNTIME_BOUNDARIES.md

@@ -72,6 +72,17 @@ exceeds temporary-filesystem capacity fails with a stable recovery contract,
 while linked tests whose effective context is schema avoid materializing
 tracker data at all.
 
+Package installation applies the same boundary to `extension_install_copy`,
+`extension_install_backup`, `extension_install_rollback`, and
+`extension_module_graph_snapshot`. These fixed operation labels identify the
+failed stage without exposing source, destination, backup, or temporary paths.
+Capacity and permission faults are not transient copy races and are not retried;
+existing bounded retries for concurrent filesystem changes remain available.
+The shared implementation lives under `core/fs`, while the public SDK exports
+remain stable for package authors. This coverage does not imply that every
+filesystem operation in the repository has adopted the boundary; the complete
+migration and recurrence-gate obligation remains tracked in `pm-3lhth4`.
+
 Existing SDK surfaces can supply category-specific `codes` to preserve their
 published error vocabulary while still sharing classification, path redaction,
 and recovery guidance. Workspace snapshots use this compatibility path for

package/docs/generated/FLAG_LEXICON_BUDGETS.md

@@ -28,7 +28,7 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
 | `get` | context | 30 | 30 |
 | `graph` | graph | 34 | 34 |
 | `search` | context | 78 | 78 |
-| `duplicates` | context | 24 | 24 |
+| `duplicates` | context | 25 | 25 |
 | `eval` | context | 25 | 25 |
 | `next` | context | 38 | 38 |
 | `history` | evidence | 35 | 35 |

package/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
-    "version": "2026.9.5"
+    "version": "2026.9.7"
   },
   "plugins": [
     {
       "name": "pm-claude",
       "source": "./plugins/pm-claude",
       "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
-      "version": "2026.9.5",
+      "version": "2026.9.7",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.9.5",
+  "version": "2026.9.7",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -224,12 +224,15 @@
     "@types/npm-package-arg": "^6.1.4",
     "@vitest/coverage-v8": "^4.1.11",
     "esbuild": "0.28.2",
-    "eslint": "^10.9.1",
+    "eslint": "^10.10.0",
     "eslint-plugin-sonarjs": "^4.2.0",
     "eslint-plugin-unicorn": "74.0.0",
     "fast-check": "^4.9.0",
-    "greptile": "^3.5.0",
+    "github-slugger": "2.0.0",
+    "greptile": "^3.5.2",
     "jscpd": "^5.1.2",
+    "marked": "18.0.11",
+    "parse5": "8.0.1",
     "tsx": "^4.23.13",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.69.0",

package/packages/pm-beads/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-beads",
-  "version": "2026.9.5",
+  "version": "2026.9.7",
   "private": true,
   "type": "module",
   "description": "First-party pm package for importing Beads JSONL records.",

package/packages/pm-calendar/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-calendar",
-  "version": "2026.9.5",
+  "version": "2026.9.7",
   "private": true,
   "type": "module",
   "description": "First-party pm package for calendar and agenda views.",

package/packages/pm-command-kit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-command-kit",
-  "version": "2026.9.5",
+  "version": "2026.9.7",
   "private": true,
   "type": "module",
   "description": "First-party pm exemplar package for the commands capability: registerCommand, registerFlags, and registerParser.",

package/packages/pm-digital-twin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-digital-twin",
-  "version": "2026.9.5",
+  "version": "2026.9.7",
   "private": true,
   "type": "module",
   "description": "Beyond-PM exemplar: a temporal production-facility digital twin built entirely on public pm SDK and extension primitives.",

package/packages/pm-governance-audit/README.md

@@ -67,7 +67,16 @@ pm normalize --dry-run --json
 ```
 
 `dedupe-audit --status all` explicitly selects every status and is equivalent
-to omitting the filter. For `comments-audit`, `--limit-items` caps item
+to omitting the filter. The receipt retains `filters.status: "all"` for an
+explicit all-status request. Configured status aliases and comma-separated OR
+filters use the host SDK parser; combining `all` with another status or using
+an unknown status fails. `--limit` caps returned clusters after the complete
+matching item population is scanned, and unreadable source items fail the read.
+Workflow terminality is captured per invocation so concurrent SDK calls cannot
+exchange workspace policy. These contracts are tracked by
+[pm-449do9](../../.agents/pm/issues/pm-449do9.toon).
+
+For `comments-audit`, `--limit-items` caps item
 scanning while `--limit-rows` caps emitted comment rows across the whole
 result. The older `--limit` spelling remains a deprecated alias for
 `--limit-rows`; do not combine the two row-limit spellings.