@unbrained/pm-cli 2026.9.11 → 2026.9.13

package/docs/HISTORY_OPERATIONS.md

@@ -0,0 +1,46 @@
+# History operation contracts
+
+Tracked by [pm-0elqjj](../.agents/pm/issues/pm-0elqjj.toon).
+
+History operation names are durable data. The public
+`PM_HISTORY_OPERATION_CONTRACT` declares native item operations, workspace
+operations, parameterized families, and historical aliases. Inspect it through
+`pm contracts --command history --json` or import it from
+`@unbrained/pm-cli/sdk/contracts`.
+
+Native write sites are checked against that declaration by the mandatory
+`operation-source-contract.spec.ts` test. New literal operation names fail the
+gate until their contract is declared. Schema migration families also have a
+type-exhaustive test covering their forward and compensation identities. JSON Patch verbs, extension write-hook
+labels, remediation-plan verbs, and telemetry span names are different domains;
+they do not become history operations merely because they have an `op` field.
+
+`createHistoryEntry` canonicalizes declared aliases before sealing new records.
+Both `init:type-preset` and `init:type_preset` write `init:type_preset`.
+Existing
+records retain their exact operation and hashes. Readers can explicitly call
+`resolveHistoryOperation` for comparison; unknown historical operations remain
+unchanged so a newer writer does not make an older reader destroy information.
+These additive naming contracts do not change the item storage format or hash
+epochs.
+
+Custom SDK consumers retain their own operation identities. New packages should
+use `extension:<package_name>:<snake_case_operation>`. Legacy custom names remain
+accepted when they use lowercase alphanumeric segments separated by underscores,
+hyphens, colons, or dots. Workspace retry keys remain opaque colon suffixes,
+including schema reference paths. Whitespace and control characters are rejected
+before new record construction. The native inventory
+gate is stricter than this compatibility grammar: a typo in product code cannot
+silently become a custom operation.
+
+Validation separates the prefix from its opaque suffix at the first colon.
+Both checks run in linear time, including long invalid inputs; no arbitrary
+length cap truncates or rejects otherwise valid SDK identities.
+
+`requireHistoryOperation` validates a native identity or a declared parameterized
+family. `normalizeHistoryOperationForWrite` applies the compatible SDK writer
+grammar. Existing append/rewrite primitives retain their responsibility to
+preserve imported and historical records; reading old records does not run a
+new-writer naming migration. Custom writers using other spellings must select
+grammar-compliant identities for new events; their retained records remain
+readable under their original names.

package/docs/HISTORY_RECOVERY.md

@@ -3,8 +3,9 @@
 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).
+[pm-e3gn0z](../.agents/pm/issues/pm-e3gn0z.toon),
+[pm-wlqxg3](../.agents/pm/tasks/pm-wlqxg3.toon), and
+[pm-nb4zwz](../.agents/pm/issues/pm-nb4zwz.toon).
 
 Project management depends on trustworthy context. History is not just an
 activity feed: it is the reconstructable source for prior item states, including
@@ -104,6 +105,30 @@ separate recovery implementation.
 
 ## Permanent item identities
 
+Reading a deleted ID returns `item_deleted`, distinct from an unknown ID.
+The SDK error context and JSON diagnostic include `item_id` and a bounded
+`tombstone` with deletion time, recoverability, and the last materialized durable
+version. Human output supplies the same recovery commands:
+
+```bash
+pm get <id> --at <last-materialized-version>
+pm restore <id> <last-materialized-version>
+```
+
+The not-found exit code remains `3`. Hosts that branch on diagnostic codes
+should handle `item_deleted` alongside other not-found cases; the new context
+fields are optional on general SDK errors. No existing required SDK input changes.
+
+The diagnostic verifies retained history before claiming deletion. A missing
+file whose history ends in a live state is not called deleted. A corrupt stream
+retains its integrity refusal. For legacy compacted streams, a timestamp is
+suggested only if it selects exactly the last materialized state; ambiguous
+timestamps or a pruned materialized state report `recoverable: false` and direct
+the caller to retained history and version control. The suggested read is
+available as `recovery.suggested_retry_args` for execution without shell parsing.
+
+Immutable event naming is documented in [History operations](HISTORY_OPERATIONS.md).
+
 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

package/docs/LIFECYCLE_COMMANDS.md

@@ -1,7 +1,8 @@
 # Lifecycle Commands and Ownership
 
 Tracked by [pm-ik19](../.agents/pm/tasks/pm-ik19.toon) and
-[pm-eq4x](../.agents/pm/tasks/pm-eq4x.toon).
+[pm-eq4x](../.agents/pm/tasks/pm-eq4x.toon) and
+[pm-r1f9f1](../.agents/pm/tasks/pm-r1f9f1.toon).
 
 Bulk mutations and ownership compositions share SDK implementations with their
 compatibility spellings. Runtime help and contracts describe the active surface:
@@ -41,7 +42,23 @@ close and its inline evidence, then releases ownership.
 Each constituent operation enforces its own policy and writes its own history.
 Compositions do not provide rollback across operations: for example, if the
 status transition fails after a successful claim, the claim remains. Inspect the
-item before retrying after an error.
+item before retrying after an error. A second-step failure retains the original
+error code and adds recovery guidance naming the completed operation. Its SDK
+error `cause` retains the underlying failure.
+
+## Compact transport receipts
+
+CLI and MCP compositions default to an `id`, final `status`, `action`, and
+`changed_field_count`, plus compact receipts for each constituent step. The root
+count is the number of distinct fields touched across the steps, not their sum.
+Step receipts retain ownership, close reason, warnings, and recovery evidence.
+Item descriptions, bodies, and annotation histories are not echoed by default.
+
+Use CLI `--full-changed-fields` or MCP `fullChangedFields: true` for complete
+constituent results; `--id-only` or `idOnly: true` returns only the final identity
+and status. CLI `--no-changed-fields` preserves item snapshots while replacing
+field arrays with counts. Plain release supports the same output controls.
+Typed `PmClient` methods and the direct SDK primitives retain full results.
 
 ## SDK and MCP
 

package/docs/MERGE_SAFETY.md

@@ -235,18 +235,79 @@ 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:
+Tracked by [pm-qx95lz](../.agents/pm/issues/pm-qx95lz.toon).
+
+Item ids are `<prefix>` plus random base36 characters. Local allocation reserves
+both live documents and retained history, but cannot see independent creations
+on another branch. The four-character default is a small, synchronized-workspace
+setting; it is not a fleet uniqueness guarantee. `ids.token_length` accepts 4–12.
+The allocator increases width after 32 local collisions to escape local density;
+this does not measure concurrent branch activity.
+
+For a shared base containing `n` reserved ids and `m` unsynchronized creations,
+choose width `L` so `m*(m-1)/(2*(36^L-n))` stays below the desired per-sync
+collision probability. This birthday union bound assumes independent uniform
+allocation and all branches know the same reserved ids. At one million reserved
+ids, eight characters keep 1,000 concurrent creations below one in a million;
+nine characters do so for 10,000 creations. Configure the width before branching:
 
-- **Entropy budget** — `ids.token_length` in `settings.json` (default 4, accepted range 4–12) sets the random token length for newly minted ids. Approximate 1%-birthday-collision workloads per length: 4 chars ≈ 1.68M ids (~184 concurrent unsynced creations), 6 chars ≈ 2.18B (~6.6k), 8 chars ≈ 2.8T (~238k). Multi-agent repositories that fan out many branches between merges should raise it, e.g. `pm config project set ids_token_length 6`.
-- **Post-merge detection** — the `storage_integrity` validate check reports `validate_storage_duplicate_item_ids` whenever one id is claimed by multiple item documents (across type folders or format variants), which is how a same-id/different-item merge materializes. Remediation: keep one document, recreate the other item under a fresh id (`pm copy` then delete the colliding file), and re-point any dependencies.
+```bash
+pm config project set ids_token_length 8
+```
+
+The SDK item merge refuses an empty common ancestor with
+`item_identity_conflict`, even for equal item content: document equality alone
+cannot prove a common creation. It leaves the driver output untouched instead
+of combining two identities through scalar preference. The history merge also
+refuses different create events across its inputs, multiple creates in either
+input, or creations on both sides when the ancestor lacks a create event even
+when their bytes match, before fast-forwarding or reanchoring. A common ancestor
+containing the shared create event remains valid.
+
+`storage_integrity` detects multiple physical documents and a second create event
+within one history stream, reporting its line in `history_unparseable_streams`
+as an invalid lifecycle. This check also protects merges Git resolves without
+invoking a content driver. `pm get` and SDK item lookup refuse multiple physical
+matches with `item_identity_ambiguous`; the message lists tracker-relative paths
+and SDK error context exposes a typed `paths` array. Format preference cannot
+select a winner. Only candidate paths are probed, so lookup
+does not enumerate every item in the workspace.
+
+Preserve both branches when a collision is reported. Recover each item from its
+unambiguous source branch, create the second under a fresh id, and update its
+references before retrying the merge. Do not repair a fused stream merely to
+make its hashes pass: a new hash chain does not recover a lost identity.
 
 Within one working tree, create and copy serialize on the candidate id and
 recheck every built-in and extension-defined type folder before the
 authoritative write. A raced collision fails with `item_id_collision` instead
 of replacing the existing document.
 
+### Executable convergence evidence
+
+[pm-1tns7o](../.agents/pm/tasks/pm-1tns7o.toon) replaces the tag-only property
+with generated complete-document comparisons. Fixed branch snapshots are folded
+in original, reversed, and rotated order, with both ours/theirs directions.
+Cases cover conflicting scalar writes and bodies, collection additions, distinct
+and equal timestamps, disjoint edits, and optional-field deletion. Independent
+expected documents are constructed directly for every N-branch case to check
+retained values and preserved context. A policy table
+also asserts that the compatibility `preferred_side` option is directional.
+The field-class inventories are pinned so changes require an explicit test update.
+
+These properties exercise the declared three-way policies; they do not turn the
+document-level timestamp into per-field causal provenance. In particular, the
+N-branch conflict fixture compares competing writes to the same scalar set.
+Arbitrary histories, ordered executable test definitions with receiving-clone
+trust, and relationship-event ordering retain their separate conformance contracts.
+
 ## Required post-merge gate
 
+Reconciliation resolves receipt discovery and settlement from the requested
+tracker. An explicit tracker outside Git does not consume clone-local receipts
+from an unrelated invocation directory; see
+[pm-q5grv5](../.agents/pm/issues/pm-q5grv5.toon).
+
 After every branch merge that touches `.agents/pm`, run:
 
 ```bash

package/docs/WORKFLOW_POLICIES.md

@@ -1,6 +1,6 @@
 # Declarative workflow policies
 
-Tracker: [pm-mj42og](../.agents/pm/features/pm-mj42og.toon) and [pm-htbetn](../.agents/pm/features/pm-htbetn.toon).
+Tracker: [pm-mj42og](../.agents/pm/features/pm-mj42og.toon) [pm-htbetn](../.agents/pm/features/pm-htbetn.toon), [pm-khd2fd](../.agents/pm/issues/pm-khd2fd.toon), and [pm-ycv2cz](../.agents/pm/issues/pm-ycv2cz.toon).
 
 Projects can describe their lifecycle requirements as versioned data. The SDK
 uses the same evaluator for item mutations, policy previews, and completeness
@@ -10,7 +10,7 @@ warn, or refuse; refusal also requires an explicit workspace opt-in.
 ## Configure a requirement
 
 ```bash
-pm schema policy-put close-evidence --definition '{"id":"close-evidence","effect":"refuse","subject":{"statuses":["closed"]},"rule":{"kind":"require_fields","fields":["resolution","actual_result"]}}'
+pm schema policy-put close-evidence --definition '{"effect":"refuse","subject":{"statuses":["closed"]},"rule":{"kind":"require_fields","fields":["resolution","actual_result"]}}'
 pm schema policies
 pm schema policy-check pm-example --definition '{"status":"closed"}'
 pm schema policy-mode refuse
@@ -21,6 +21,10 @@ body. Custom fields can use dotted paths with at most eight segments. Empty
 strings, arrays, objects, null, and absent values do not satisfy required fields;
 zero and false are meaningful values.
 
+`policy-put` accepts the id once: pass it as the operand, or omit the operand
+and include `id` in the definition. When both are supplied their normalized ids
+must agree; a mismatch refuses without changing the registry or history.
+The same normalization applies to JSON strings, objects, previews, SDK, and MCP.
 `policy-put` replaces a declaration with the same id. `policy-remove <id>` removes
 one declaration. `policy-mode advise` disables refusal while retaining diagnostics.
 Registry writes are locked and recorded in workspace history. `--dry-run` previews
@@ -122,8 +126,48 @@ declaration once. Later edits to the supplied document do not change that
 snapshot; create another evaluator to adopt them. Completeness validation uses
 one such snapshot for the whole supplied corpus.
 
-The schema contract version is 4.16. Existing schema operations remain available;
+The schema contract version is 4.19; `policy-put` requires `definition` but
+no longer requires a separate `name`. Existing schema operations remain available;
 `SchemaResult` now also includes `WorkflowPolicyActionResult`. Consumers that
 exhaustively narrow schema results should handle the `policy_result: true`
 discriminant. Validation options include `checkCompleteness`, and validation
 results can contain a `completeness` check.
+
+## Require a meaningful completeness contract
+
+A successful completeness check means no applicable field requirement was
+violated. It does not establish that a project declared any requirements.
+The receipt exposes these independent measurements even in counts mode:
+
+| Field | Meaning |
+| --- | --- |
+| `declared_requirement_count` | Number of `require_fields` declarations, including operation-specific ones |
+| `state_requirement_count` | Number eligible for a state scan, without operation selectors |
+| `applicable_requirement_count` | Distinct requirements that matched at least one supplied item |
+| `requirement_application_count` | Item/requirement pairs actually evaluated |
+| `governed_items`, `ungoverned_items` | Items with and without a matching state requirement |
+| `contract_status` | `undeclared`, `empty`, `inapplicable`, `partial`, or `covered` |
+
+`applied_policy_ids` is bounded by the diagnostic row limit; its truncation flag
+and `applicable_requirement_count` retain the complete total. `covered` describes
+applicability, not compliance: violations are reported independently. Unreadable
+source data still fails the check, regardless of the coverage of readable items.
+
+Projects can require a nonempty applied contract with the existing assurance
+primitives. Replace `pm-example` with the accountable item in your workspace:
+
+```bash
+pm assurance put measurement completeness-contract --definition '{"id":"completeness-contract","source":{"kind":"validate","check":"completeness","field":"applicable_requirement_count"}}'
+pm assurance put assertion completeness-contract-required --definition '{"id":"completeness-contract-required","measurement_id":"completeness-contract","owner_item_id":"pm-example","scope":{"kind":"all"},"floor":1,"lifetime":"hold","enforcement":"block","negative_control":{"cases":[{"observed":0,"expected":"fail"},{"observed":1,"expected":"pass"}]}}'
+pm assurance put gate completeness-contract --definition '{"id":"completeness-contract","assertion_ids":["completeness-contract-required"],"triggers":["ci"]}'
+pm assurance run completeness-contract --trigger ci --dry-run
+pm ops validate --check-completeness --strict-exit
+```
+
+Run both checks: the gate requires applicability and validation checks compliance.
+Deleting the last applicable policy fails the gate. For an empty workspace, or a
+contract intended only for a future lifecycle state, measure
+`state_requirement_count` instead. To require coverage of every current item,
+also enforce a zero bound on `ungoverned_items`. Higher per-project floors can
+protect against partial policy deletion; a floor of one only proves at least
+one requirement applies.

package/docs/generated/AGENT_CAPABILITY_ROUTING.md

@@ -7,11 +7,11 @@ This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it ma
 | Capability family | Commands |
 | --- | --- |
 | workspace | `init`, `config`, `workspace merge`, `schema`, `profile`, `ops telemetry`, `ops health`, `ops gc`, `workspace` |
-| intake | `create`, `item copy`, `context focus`, `history restore` |
+| intake | `create`, `item`, `item copy`, `context focus`, `history restore` |
 | context | `list`, `aggregate`, `context`, `get`, `search`, `item duplicates`, `ops eval`, `context next`, `history activity`, `ops stats`, `help` |
 | lifecycle | `update`, `update many`, `close`, `close many`, `close delete`, `claim`, `release` |
-| evidence | `history`, `history events`, `history redact`, `history repair`, `history compact`, `history attest`, `history-author-acknowledge`, `append`, `comments`, `notes`, `learnings`, `files`, `docs` |
-| graph | `graph`, `deps`, `plan` |
-| quality | `test`, `ops test-all`, `ops validate`, `assurance`, `contracts`, `ops` |
+| evidence | `history`, `history events`, `history redact`, `history repair`, `history compact`, `history attest`, `history-author-acknowledge`, `item append`, `item comments`, `item notes`, `item learnings`, `item files`, `item docs` |
+| graph | `graph`, `item deps`, `plan` |
+| quality | `item test`, `ops test-all`, `ops validate`, `assurance`, `contracts`, `ops` |
 | automation | `meet`, `event`, `remind` |
 | extensions | `package` |

package/docs/generated/AGENT_COMMAND_SURFACE.md

@@ -12,6 +12,7 @@ This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it ma
 | `install` | full | extensions |
 | `upgrade` | full | extensions |
 | `create` | core | intake |
+| `item` | full | intake |
 | `item-reopen` | full | lifecycle |
 | `copy` | full | intake |
 | `item copy` | full | intake |
@@ -66,14 +67,22 @@ This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it ma
 | `delete` | full | lifecycle |
 | `close delete` | full | lifecycle |
 | `append` | standard | evidence |
+| `item append` | standard | evidence |
 | `comments` | standard | evidence |
+| `item comments` | standard | evidence |
 | `notes` | standard | evidence |
+| `item notes` | standard | evidence |
 | `learnings` | standard | evidence |
+| `item learnings` | standard | evidence |
 | `files` | standard | evidence |
+| `item files` | standard | evidence |
 | `docs` | standard | evidence |
+| `item docs` | standard | evidence |
 | `deps` | standard | graph |
+| `item deps` | standard | graph |
 | `plan` | core | graph |
 | `test` | standard | quality |
+| `item test` | standard | quality |
 | `test-all` | full | quality |
 | `ops test-all` | full | quality |
 | `telemetry` | full | workspace |
@@ -103,3 +112,4 @@ This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it ma
 | `completion-tags` | internal | internal |
 | `completion-types` | internal | internal |
 | `test-runs-worker` | internal | internal |
+| `item test worker` | internal | internal |

package/docs/generated/FLAG_LEXICON_BUDGETS.md

@@ -5,6 +5,7 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
 | Command | Capability family | Canonical flags | Maximum |
 | --- | --- | ---: | ---: |
 | `init` | workspace | 30 | 30 |
+| `item` | intake | 20 | 20 |
 | `config` | workspace | 36 | 36 |
 | `extension` | extensions | 54 | 54 |
 | `package` | extensions | 55 | 55 |
@@ -74,7 +75,7 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
 | `meet` | automation | 33 | 33 |
 | `event` | automation | 33 | 33 |
 | `remind` | automation | 29 | 29 |
-| `test-runs-worker` | internal | 25 | 25 |
+| `test-runs-worker` | internal | 20 | 20 |
 | `history attest` | evidence | 23 | 23 |
 | `history redact` | evidence | 27 | 27 |
 | `history repair` | evidence | 27 | 27 |
@@ -94,6 +95,15 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
 | `update many` | lifecycle | 146 | 146 |
 | `close many` | lifecycle | 72 | 72 |
 | `close delete` | lifecycle | 24 | 24 |
+| `item comments` | evidence | 31 | 31 |
+| `item notes` | evidence | 35 | 35 |
+| `item learnings` | evidence | 31 | 31 |
+| `item files` | evidence | 39 | 39 |
+| `item docs` | evidence | 30 | 30 |
+| `item deps` | graph | 32 | 32 |
+| `item append` | evidence | 25 | 25 |
+| `item test` | quality | 53 | 53 |
+| `item test worker` | internal | 20 | 20 |
 | `item copy` | intake | 24 | 24 |
 | `workspace merge` | workspace | 27 | 27 |
 | `item duplicates` | context | 25 | 25 |

package/docs/generated/REFUSAL_CLOSURE_CENSUS.md

@@ -4,14 +4,14 @@ Tracker: `pm-f05lsg`.
 
 Every catalog code is listed. An `uncovered` row is an explicit closure obligation, never an omission or implied approval.
 
-- Catalog error codes: 371
+- Catalog error codes: 374
 - Executable error codes: 19
 - Executable-code ratchet floor: 18
 - Required executable canonical codes: `bulk_ids_input_empty`, `bulk_ids_input_missing_path`, `bulk_ids_input_unreadable`, `invalid_argument_value`, `manifest_unknown_key`, `missing_lifecycle_target`, `missing_required_argument`, `no_version_bounds_declared`, `projection_options_mutually_exclusive`, `tracker_not_initialized`, `tracker_root_missing`, `tracker_root_not_directory`, `tracker_root_unreadable`, `unknown_context_intent`, `unknown_field_projection`, `unknown_option`, `unknown_subcommand`
-- Uncovered error codes: 352
-- Coverage fraction: 0.051213
+- Uncovered error codes: 355
+- Coverage fraction: 0.050802
 - Closed-domain probes: 19
-- Grammar probes: 101
+- Grammar probes: 113
 
 | Error code | Canonical code | Disposition | Evidence kinds | Probe count |
 | --- | --- | --- | --- | --- |
@@ -169,10 +169,13 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `invalid_reproducible_process_environment` | `invalid_reproducible_process_environment` | uncovered | none | 0 |
 | `invalid_workspace_snapshot_target` | `invalid_workspace_snapshot_target` | uncovered | none | 0 |
 | `item_already_active` | `item_already_active` | uncovered | none | 0 |
+| `item_deleted` | `item_deleted` | uncovered | none | 0 |
 | `item_document_encoding_invalid` | `item_document_encoding_invalid` | uncovered | none | 0 |
 | `item_document_invalid` | `item_document_invalid` | uncovered | none | 0 |
 | `item_document_roundtrip_failed` | `item_document_roundtrip_failed` | uncovered | none | 0 |
 | `item_id_collision` | `item_id_collision` | uncovered | none | 0 |
+| `item_identity_ambiguous` | `item_identity_ambiguous` | uncovered | none | 0 |
+| `item_identity_conflict` | `item_identity_conflict` | uncovered | none | 0 |
 | `item_identity_reserved` | `item_identity_reserved` | uncovered | none | 0 |
 | `item_not_found` | `item_not_found` | uncovered | none | 0 |
 | `likely_duplicate` | `likely_duplicate` | uncovered | none | 0 |
@@ -211,7 +214,7 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `missing_parameter_alias` | `missing_parameter_alias` | uncovered | none | 0 |
 | `missing_positive_execution_receipt` | `missing_positive_execution_receipt` | uncovered | none | 0 |
 | `missing_probe` | `missing_probe` | uncovered | none | 0 |
-| `missing_required_argument` | `missing_required_argument` | executable | grammar | 63 |
+| `missing_required_argument` | `missing_required_argument` | executable | grammar | 75 |
 | `missing_required_option` | `missing_required_option` | uncovered | none | 0 |
 | `missing_suggested_retry` | `missing_suggested_retry` | uncovered | none | 0 |
 | `missing_suggested_retry_args` | `missing_suggested_retry_args` | uncovered | none | 0 |

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.11"
+    "version": "2026.9.13"
   },
   "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.11",
+      "version": "2026.9.13",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.9.11",
+  "version": "2026.9.13",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",

package/packages/pm-beads/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-beads",
-  "version": "2026.9.11",
+  "version": "2026.9.13",
   "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.11",
+  "version": "2026.9.13",
   "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.11",
+  "version": "2026.9.13",
   "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.11",
+  "version": "2026.9.13",
   "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

@@ -4,6 +4,28 @@ Trackers: [pm-fmy9ih](../../.agents/pm/tasks/pm-fmy9ih.toon), [pm-vjk3](../../.a
 
 First-party package that restores optional governance audit surfaces in bare-core `pm`.
 
+## Concurrent annotations under strict ownership
+
+Tracked by [pm-nrkjik](../../.agents/pm/issues/pm-nrkjik.toon).
+
+Merge-safe notes preserve independent entries during merging. Strict ownership
+still applies to writes. For an approved append across owners, install this
+package and use its narrow flag:
+
+```bash
+pm package install governance-audit --project
+pm notes pm-example "Review observation" --allow-audit-comment
+```
+
+The same flag works for `comments` and `learnings`. It permits additions only:
+edit and delete still require ownership, and the existing assignee is preserved.
+For a non-terminal handoff, the current owner runs `pm release <id>`, then the
+new owner runs `pm claim <id>`; claim refuses work still held by another owner.
+This changes the assignee;
+it is a different operation from appending an observation. Bare `--force` remains
+an explicit override requiring approval. Body `append` is not merge-safe and has
+no annotation bypass; use a note when the information is an independent event.
+
 ## Hooks
 
 The package also registers default-inert `onRead` and `onWrite` hooks as the

package/packages/pm-governance-audit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-governance-audit",
-  "version": "2026.9.11",
+  "version": "2026.9.13",
   "private": true,
   "type": "module",
   "description": "First-party pm package for governance audit and normalization workflows.",

package/packages/pm-guide-shell/extensions/guide-shell/index.ts

@@ -126,50 +126,37 @@ function completionCommand(): CommandDefinition {
       runCompletionPackage(context.args, context.options, context.global),
   };
 }
-
-function completionTagsCommand(): CommandDefinition {
-  return {
-    name: "completion-tags",
+/** Registers this package's commands, actions, and runtime hooks with the host. */
+export function activate(api: ExtensionApi): void {
+  api.registerCommand(guideCommand());
+  api.registerCommand(completionCommand());
+  api.registerCommand({
+    name: "completion tags",
     action: "completion-tags",
     tier: "internal",
     family: "internal",
     description: "Print known tags for completion filters.",
     intent: "List tag values for lazy shell completion.",
     run: async (context) => runCompletionTagsPackage(context.global),
-  };
-}
-
-function completionStatusesCommand(): CommandDefinition {
-  return {
-    name: "completion-statuses",
+  });
+  api.registerCommand({
+    name: "completion statuses",
     action: "completion-statuses",
     tier: "internal",
     family: "internal",
     description: "Print runtime status IDs for completion filters.",
     intent: "List runtime status values for shell completion.",
     run: async (context) => runCompletionStatusesPackage(context.global),
-  };
-}
-
-function completionTypesCommand(): CommandDefinition {
-  return {
-    name: "completion-types",
+  });
+  api.registerCommand({
+    name: "completion types",
     action: "completion-types",
     tier: "internal",
     family: "internal",
     description: "Print runtime item type IDs for completion filters.",
     intent: "List runtime item types for shell completion.",
     run: async (context) => runCompletionTypesPackage(context.global),
-  };
-}
-
-/** Registers this package's commands, actions, and runtime hooks with the host. */
-export function activate(api: ExtensionApi): void {
-  api.registerCommand(guideCommand());
-  api.registerCommand(completionCommand());
-  api.registerCommand(completionTagsCommand());
-  api.registerCommand(completionStatusesCommand());
-  api.registerCommand(completionTypesCommand());
+  });
   api.registerService("output_format", (context) => {
     const rendered = renderGuideShellPackageOutput(
       context as ServiceOverrideContext,

package/packages/pm-guide-shell/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-guide-shell",
-  "version": "2026.9.11",
+  "version": "2026.9.13",
   "private": true,
   "type": "module",
   "description": "First-party pm package for guide and shell completion workflows.",

package/packages/pm-kanban/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-kanban",
-  "version": "2026.9.11",
+  "version": "2026.9.13",
   "private": true,
   "type": "module",
   "description": "First-party pm archetype package: a complete Kanban continuous-flow profile built on public SDK primitives.",

package/packages/pm-lifecycle-hooks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-lifecycle-hooks",
-  "version": "2026.9.11",
+  "version": "2026.9.13",
   "private": true,
   "type": "module",
   "description": "First-party pm package demonstrating safe lifecycle hook registration.",

package/packages/pm-linked-test-adapters/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-linked-test-adapters",
-  "version": "2026.9.11",
+  "version": "2026.9.13",
   "private": true,
   "type": "module",
   "description": "First-party pm package for optional linked-test run management adapters and reporters.",

package/packages/pm-search-advanced/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-search-advanced",
-  "version": "2026.9.11",
+  "version": "2026.9.13",
   "private": true,
   "type": "module",
   "description": "First-party pm package for semantic, hybrid, and reindex search workflows.",

package/packages/pm-templates/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-templates",
-  "version": "2026.9.11",
+  "version": "2026.9.13",
   "private": true,
   "type": "module",
   "description": "First-party pm package for reusable create templates.",