@unbrained/pm-cli 2026.9.10 → 2026.9.12

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/README.md

@@ -62,6 +62,7 @@ pm guide release --json
 - [Generated Refusal Closure Census](generated/REFUSAL_CLOSURE_CENSUS.md) - complete error-catalog join to executable refusal evidence and explicit uncovered obligations.
 - [Universal Read Output Contracts](READ_OUTPUT_CONTRACTS.md) - cross-command include, amount, cost, and encoding controls for CLI, SDK, MCP, and packages.
 - [Diagnostic Output Contracts](DIAGNOSTIC_OUTPUT_CONTRACTS.md) - action-first error budgets, deterministic degradation, SDK projection, and executable refusal assurance.
+- [History Algorithms and Detached Attestations](HISTORY_ATTESTATION.md) - named record digests, portable exact-byte proofs, and read-only verification.
 - [History Maintenance and Recovery](HISTORY_MAINTENANCE.md) - native history commands, permanent aliases, shared SDK transforms, and transactional recovery.
 - [Declarative Workflow Policies](WORKFLOW_POLICIES.md) - portable lifecycle requirements, independent approvals, and completeness reports.
 - [Mutation Integrity](MUTATION_INTEGRITY.md) - shared CLI/SDK/MCP author, secret, append-only disposition, and stale-work guardrails.

package/docs/READ_OUTPUT_CONTRACTS.md

@@ -153,6 +153,19 @@ pm contracts --full --json
 
 Every projected result carries a `read_output` receipt with the requested dimensions, precedence, observed option provenance, deterministic estimated token count, string/row compaction signals, and budget outcome. When canonical controls are present, `canonical_options_used` records spellings such as `--output-include`; the optional field is omitted when no canonical control was supplied so minimum-budget session receipts remain compact. `legacy_aliases_used` and `migration_hints` record only compatibility flags the caller actually supplied. A command-local flag synthesized internally to execute a canonical projection mode is therefore never misreported as deprecated syntax. When both spellings are supplied, both provenance arrays report that mixed invocation. Budget degradation discovers nested arrays as well as declared result rows, so validation diagnostics and other governance payloads compact their inner findings before the useful result is omitted. `compacted_row_paths` names every reduced collection without redefining those nested arrays as ordinary pagination rows.
 
+The estimate is `ceil(utf8_bytes / 4)` for the complete envelope. The CLI uses
+its selected built-in JSON or TOON representation, including indentation and
+the final newline. SDK calls that select `outputFormat` use that representation;
+structured SDK calls without a renderer retain compact JSON measurement.
+Those unformatted calls keep the conservative workload-class ceiling
+(`default_max_estimated_tokens`, also used as the generated TOON ceiling).
+Selecting JSON explicitly opts into its larger declared rendering allowance;
+serializing an SDK object for measurement does not implicitly select that policy.
+Per-call and session receipts include their own cost and continuation disclosure.
+Compaction reserves room for that disclosure before returning a useful page, so
+an envelope cannot claim to fit merely because its rows fit before receipts were
+added. An infeasible ceiling returns the explicit omission result.
+
 For `context` and `next`, that final projection is also the usage-feedback
 delivery boundary. The SDK carries a JSON-invisible serve receipt through
 intent and universal output projection, then appends the final omitted decision

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

@@ -6,11 +6,11 @@ This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it ma
 
 | Capability family | Commands |
 | --- | --- |
-| workspace | `init`, `config`, `merge`, `schema`, `profile`, `ops telemetry`, `ops health`, `ops gc`, `workspace` |
-| intake | `create`, `copy`, `context focus`, `history restore` |
-| context | `list`, `aggregate`, `context`, `get`, `search`, `duplicates`, `ops eval`, `context next`, `history activity`, `ops stats`, `help` |
+| workspace | `init`, `config`, `workspace merge`, `schema`, `profile`, `ops telemetry`, `ops health`, `ops gc`, `workspace` |
+| intake | `create`, `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-author-acknowledge`, `append`, `comments`, `notes`, `learnings`, `files`, `docs` |
+| 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` |
 | automation | `meet`, `event`, `remind` |

package/docs/generated/AGENT_COMMAND_SURFACE.md

@@ -14,6 +14,7 @@ This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it ma
 | `create` | core | intake |
 | `item-reopen` | full | lifecycle |
 | `copy` | full | intake |
+| `item copy` | full | intake |
 | `focus` | standard | intake |
 | `context focus` | standard | intake |
 | `list` | core | context |
@@ -31,6 +32,7 @@ This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it ma
 | `graph` | standard | graph |
 | `search` | core | context |
 | `duplicates` | full | context |
+| `item duplicates` | full | context |
 | `eval` | full | context |
 | `ops eval` | full | context |
 | `next` | core | context |
@@ -44,8 +46,11 @@ This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it ma
 | `history repair` | full | evidence |
 | `history-compact` | full | evidence |
 | `history compact` | full | evidence |
+| `history-attest` | full | evidence |
+| `history attest` | full | evidence |
 | `history-author-acknowledge` | full | evidence |
 | `merge` | full | workspace |
+| `workspace merge` | full | workspace |
 | `schema` | standard | workspace |
 | `profile` | standard | workspace |
 | `activity` | full | context |

package/docs/generated/FLAG_LEXICON_BUDGETS.md

@@ -33,6 +33,7 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
 | `next` | context | 38 | 38 |
 | `history` | evidence | 35 | 35 |
 | `events` | evidence | 33 | 33 |
+| `history-attest` | evidence | 23 | 23 |
 | `history-redact` | evidence | 27 | 27 |
 | `history-repair` | evidence | 27 | 27 |
 | `history-compact` | evidence | 30 | 30 |
@@ -74,6 +75,7 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
 | `event` | automation | 33 | 33 |
 | `remind` | automation | 29 | 29 |
 | `test-runs-worker` | internal | 25 | 25 |
+| `history attest` | evidence | 23 | 23 |
 | `history redact` | evidence | 27 | 27 |
 | `history repair` | evidence | 27 | 27 |
 | `history compact` | evidence | 30 | 30 |
@@ -92,3 +94,6 @@ 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 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: 98
+- Grammar probes: 101
 
 | 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 | 61 |
+| `missing_required_argument` | `missing_required_argument` | executable | grammar | 63 |
 | `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 |
@@ -313,13 +316,13 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `unknown_field` | `unknown_field` | uncovered | none | 0 |
 | `unknown_field_projection` | `unknown_field_projection` | executable | closed_domain | 10 |
 | `unknown_item_type` | `unknown_item_type` | uncovered | none | 0 |
-| `unknown_lifecycle_action` | `unknown_subcommand` | executable | grammar, owned_state | 11 |
+| `unknown_lifecycle_action` | `unknown_subcommand` | executable | grammar, owned_state | 12 |
 | `unknown_noun` | `unknown_noun` | uncovered | none | 0 |
 | `unknown_option` | `unknown_option` | executable | owned_state | 1 |
 | `unknown_plan_template` | `unknown_plan_template` | uncovered | none | 0 |
 | `unknown_provenance_dimension` | `unknown_provenance_dimension` | uncovered | none | 0 |
 | `unknown_status` | `unknown_status` | uncovered | none | 0 |
-| `unknown_subcommand` | `unknown_subcommand` | executable | grammar, owned_state | 11 |
+| `unknown_subcommand` | `unknown_subcommand` | executable | grammar, owned_state | 12 |
 | `unsafe_init_recovery` | `unsafe_init_recovery` | uncovered | none | 0 |
 | `unsupported_update_option` | `unsupported_update_option` | uncovered | none | 0 |
 | `validate_command_references_stale_pm_ids` | `validate_command_references_stale_pm_ids` | 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.10"
+    "version": "2026.9.12"
   },
   "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.10",
+      "version": "2026.9.12",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.9.10",
+  "version": "2026.9.12",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -205,7 +205,7 @@
     "node": ">=22.18.0"
   },
   "dependencies": {
-    "@sentry/node": "10.73.0",
+    "@sentry/node": "10.74.0",
     "@toon-format/toon": "^4.1.1",
     "@types/node": ">=22",
     "commander": "^15.0.0",
@@ -218,7 +218,7 @@
   "devDependencies": {
     "@codspeed/vitest-plugin": "^5.7.1",
     "@eslint/js": "^10.0.1",
-    "@modelcontextprotocol/ext-apps": "1.7.5",
+    "@modelcontextprotocol/ext-apps": "2.0.0",
     "@sentry/cli": "^3.7.0",
     "@types/node": "^26.5.0",
     "@types/npm-package-arg": "^6.1.4",
@@ -230,7 +230,7 @@
     "fast-check": "^4.9.0",
     "github-slugger": "2.0.0",
     "greptile": "^3.5.2",
-    "jscpd": "^5.1.2",
+    "jscpd": "^5.2.0",
     "marked": "18.0.12",
     "parse5": "8.0.1",
     "tsx": "^4.23.13",

package/packages/pm-beads/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-beads",
-  "version": "2026.9.10",
+  "version": "2026.9.12",
   "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.10",
+  "version": "2026.9.12",
   "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.10",
+  "version": "2026.9.12",
   "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.10",
+  "version": "2026.9.12",
   "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

@@ -1,9 +1,31 @@
 # pm-governance-audit
 
-Trackers: [pm-vjk3](../../.agents/pm/features/pm-vjk3.toon), [pm-mp49](../../.agents/pm/issues/pm-mp49.toon), [pm-v657](../../.agents/pm/issues/pm-v657.toon)
+Trackers: [pm-fmy9ih](../../.agents/pm/tasks/pm-fmy9ih.toon), [pm-vjk3](../../.agents/pm/features/pm-vjk3.toon), [pm-mp49](../../.agents/pm/issues/pm-mp49.toon), [pm-v657](../../.agents/pm/issues/pm-v657.toon)
 
 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
@@ -20,9 +42,9 @@ bodies and full before/after snapshots.
 
 ## Commands
 
-- `pm dedupe-audit`
-- `pm dedupe-merge`
-- `pm comments-audit`
+- `pm item duplicates audit`
+- `pm item duplicates merge`
+- `pm item audit-comments`
 - `pm ops normalize`
 
 The package also augments existing commands with audit-only flags:
@@ -60,9 +82,9 @@ pm install audit --project
 ## Verify
 
 ```bash
-pm dedupe-audit --mode parent_scope --status all --limit 20 --json
-pm dedupe-merge --keep pm-canonical --close pm-duplicate --dry-run --json
-pm comments-audit --latest 3 --limit-items 20 --limit-rows 50 --json
+pm item duplicates audit --mode parent_scope --status all --limit 20 --json
+pm item duplicates merge --keep pm-canonical --close pm-duplicate --dry-run --json
+pm item audit-comments --latest 3 --limit-items 20 --limit-rows 50 --json
 pm ops normalize --dry-run --json
 ```
 
@@ -82,3 +104,5 @@ result. The older `--limit` spelling remains a deprecated alias for
 `--limit-rows`; do not combine the two row-limit spellings.
 
 `pm normalize` remains a compatibility alias for `pm ops normalize`.
+
+`dedupe-audit`, `dedupe-merge`, and `comments-audit` remain hidden compatibility aliases. Core `pm item duplicates` discovers bounded candidate clusters; this package adds detailed audit and explicit reconciliation. Comment coverage is an independent item audit, not a duplicate detector. SDK action names remain unchanged.

package/packages/pm-governance-audit/extensions/governance-audit/index.ts

@@ -321,9 +321,10 @@ const allowAuditCommentFlags = [
   },
 ];
 
+/** Expose duplicate discovery under the item namespace while retaining its stable action and read-only handler. */
 function dedupeAuditCommand(): CommandDefinition {
   return {
-    name: "dedupe-audit",
+    name: "item duplicates audit",
     action: "dedupe-audit",
     description:
       "Audit likely duplicate items by title and parent scope heuristics.",
@@ -334,9 +335,10 @@ function dedupeAuditCommand(): CommandDefinition {
   };
 }
 
+/** Declare duplicate consolidation flags and route preview or apply requests to the existing package handler. */
 function dedupeMergeCommand(): CommandDefinition {
   return {
-    name: "dedupe-merge",
+    name: "item duplicates merge",
     action: "dedupe-merge",
     description:
       "Consolidate duplicates into a canonical item: re-parent active children and close duplicates with duplicate_of.",
@@ -347,9 +349,10 @@ function dedupeMergeCommand(): CommandDefinition {
   };
 }
 
+/** Register bounded comment-coverage inspection under the item namespace with the existing action identity. */
 function commentsAuditCommand(): CommandDefinition {
   return {
-    name: "comments-audit",
+    name: "item audit-comments",
     action: "comments-audit",
     description: "Audit item comment coverage and export comment history rows.",
     intent: "Audit comment coverage and read bounded comment-history evidence.",