@unbrained/pm-cli 2026.9.4 → 2026.9.6

package/docs/SDK_EXECUTION_CONTRACTS.md

@@ -0,0 +1,105 @@
+# SDK Execution and Recovery Contracts
+
+Tracker references: [pm-08mt4k](../.agents/pm/issues/pm-08mt4k.toon),
+[pm-ugld](../.agents/pm/issues/pm-ugld.toon),
+[pm-2bqgs7](../.agents/pm/issues/pm-2bqgs7.toon),
+[pm-u4t9gp](../.agents/pm/issues/pm-u4t9gp.toon), and
+[pm-bfa1ob](../.agents/pm/issues/pm-bfa1ob.toon).
+
+## Declare Who Can Execute a Type
+
+Custom settings definitions and package `defineItemType` definitions accept
+`execution_role: "agent" | "human" | "gate"`. An omitted role defaults to agent
+execution; built-in Decision and Milestone types default to human and gate,
+respectively. A definition can override a built-in role. Aliases resolve through
+the type registry, and invalid roles are rejected rather than silently enabling
+execution.
+
+Package authors can declare a review checkpoint alongside the rest of their item
+type definition:
+
+```ts
+import { defineItemType } from "@unbrained/pm-cli/sdk/authoring";
+
+export const checkpoint = defineItemType({
+  name: "Checkpoint",
+  folder: "checkpoints",
+  aliases: ["checkpoint"],
+  execution_role: "gate",
+});
+```
+
+`computeActionabilityReport` is the pure SDK primitive: it accepts candidates,
+the surrounding item corpus, a status registry, and an optional item type
+registry. It resolves both forward `blocked_by` and reverse `blocks` edges,
+terminal prerequisites, active descendants, and execution roles. Its result
+contains ready leaves, blocked leaves, human decisions, gates, and containers.
+`selectActionableEntries` applies explicit dispatch opt-ins to that report;
+ownership and ranking remain the responsibility of the caller. The selector
+returns `ready`, `decisions`, and `gates`: eligible opted-in containers enter
+`ready`, subject to their execution role. Read `report.containers` for the full
+classified container worklist; the selector does not return a separate
+`containers` property.
+
+Integrations that construct an `ActionabilityReport` themselves must now provide
+the `containers`, `decisions`, and `gates` arrays. Prefer computing the report
+through the SDK so these classifications stay consistent with dependency and
+schema rules. Existing callers may omit the new selection options and type
+registry argument.
+
+## Read Every Scheduling Bucket
+
+`pm next` exposes `ready`, `decision_needed`, `gate_needed`, `containers`,
+`blocked`, and `held_by_others`. Summary counts describe the full matching
+buckets; each bounded worklist has truncation totals when needed. The row
+contract advertises the new gate and container collections to generic consumers.
+Intent budgets compact these worklists along with the other scheduling rows.
+Final-delivery feedback records their visible identifiers so recursive context
+improvement observes what the caller actually received.
+A workspace containing only outcome gates returns no recommendation and explains
+how to inspect or explicitly include gates.
+
+`--include-decisions`, `--include-gates`, and `--include-containers` opt into
+held-out work for both `next` and `claim --next`. The SDK and MCP use
+`includeDecisions`, `includeGates`, and `includeContainers`. These options do not
+bypass unresolved blockers, blocked lifecycle states, or ownership checks.
+Context places gates, human work, and containers in high-level context rather
+than agent execution detail. Population summaries retain all matching work.
+
+## Stop Work Explicitly
+
+`release` relinquishes ownership and preserves status. When an in-progress item
+is released (using the configured workflow status), its result includes `released_unclaimed_in_progress` and a concrete
+`pm pause-task <id>` suggestion. Use `pause-task` when the intended operation is
+to stop work and return it to the configured open state. Consumers should not
+interpret an ownership release as evidence that work has stopped.
+
+## Recover from Command Mistakes
+
+Unknown commands direct the caller to `pm --help --all`, the complete core
+command surface. `pm tests <id>` is an executable alias of `pm test <id>`.
+Positional item operands are accepted in help requests, including hybrid
+commands such as `pm files <id> --help --json`; invalid child command names still
+produce usage errors.
+
+With `--token-accounting`, JSON refusals carry the same serialized-output
+accounting used by successful commands. Accounting is attached after diagnostic
+projection and recalculated if extension failures enrich the refusal. The
+receipt measures the emitted diagnostic, including its own receipt overhead.
+Recovery metadata retains the actual invocation, including the accounting flag.
+The executable transcript gate predicts that transport change independently and
+rejects any other payload drift. It also verifies that the accounting-off
+attempted command agrees with its normalized arguments before projection.
+Detailed recovery evidence must contain argument and provided-field arrays.
+Compact recovery is accepted only when the transcript explicitly declares and
+verifies that mode; its advertised retry still executes as a separate step.
+Serialized JSON refusals use the SDK `writeStderr` transport primitive so an
+`error_format` text override cannot replace a measured machine payload.
+Human-readable error formatting remains customizable through `error_format`.
+
+The flag-invocation gate compares registered executable options against SDK
+contracts without filtering out undeclared observations. An option missing from
+the contract and a root command missing a resolver both fail the gate. A seeded
+undeclared option is a mandatory negative control. Contract snapshots, MCP
+parameter declarations, help, and completion are regenerated from the shared
+contract tables.

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

@@ -146,6 +146,11 @@ boilerplate summaries are rejected.
 
 ## TOON Storage Round-Trip Gate
 
+History-only lifecycle reconstruction and recovery contracts are described in
+[History durability and recovery](HISTORY_RECOVERY.md). Their integration suite
+is part of the required all-source test run and compares historical projections
+against independently captured item files, including after removing those files.
+
 TOON item serialization is a fail-closed storage boundary. Before returning
 bytes to any create, update, merge, migration, or package caller, pm decodes the
 new `@toon-format/toon` output and compares it with the JSON-like canonical

package/docs/agent-task-token-baseline.json

@@ -1,7 +1,7 @@
 {
   "version": 4,
   "transcript_version": 2,
-  "transcript_digest": "sha256:4f9e96bb6ce12bbbeb2514e4bd5958d201c4e62e95083bcbebd749d1e48cc82d",
+  "transcript_digest": "sha256:b8a6aea318c41e6a40dbcaf8094da8397ca747515a7df249d35c1f21ad94a307",
   "estimator": "ceil(utf8_bytes / 4)",
   "measurement_scope": "output_before_token_accounting",
   "published_with_release": true,
@@ -12,12 +12,12 @@
       "active_ownership",
       "workspace_state"
     ],
-    "measured_winner_tokens": 1055,
+    "measured_winner_tokens": 1102,
     "protocols": [
       {
         "task_id": "orientation-context-intent",
         "command_count": 1,
-        "estimated_tokens": 1055,
+        "estimated_tokens": 1102,
         "capabilities": [
           "actionable_work",
           "active_ownership",
@@ -47,7 +47,7 @@
       {
         "task_id": "orientation-operating-rules",
         "command_count": 4,
-        "estimated_tokens": 2293,
+        "estimated_tokens": 2340,
         "capabilities": [
           "actionable_work",
           "active_ownership",
@@ -77,7 +77,7 @@
       {
         "task_id": "orientation-contracts-next",
         "command_count": 2,
-        "estimated_tokens": 4798,
+        "estimated_tokens": 4829,
         "capabilities": [
           "actionable_work",
           "active_ownership",
@@ -109,18 +109,18 @@
   "tasks": [
     {
       "id": "orientation-context-intent",
-      "max_estimated_tokens": 1055,
+      "max_estimated_tokens": 1102,
       "steps": [
         {
           "id": "context",
-          "max_estimated_tokens": 1055,
+          "max_estimated_tokens": 1102,
           "accounting_mode": "self_reported"
         }
       ]
     },
     {
       "id": "orientation-contracts-next",
-      "max_estimated_tokens": 4798,
+      "max_estimated_tokens": 4829,
       "steps": [
         {
           "id": "contracts",
@@ -129,18 +129,18 @@
         },
         {
           "id": "next",
-          "max_estimated_tokens": 687,
+          "max_estimated_tokens": 718,
           "accounting_mode": "self_reported"
         }
       ]
     },
     {
       "id": "orientation-operating-rules",
-      "max_estimated_tokens": 2293,
+      "max_estimated_tokens": 2340,
       "steps": [
         {
           "id": "context",
-          "max_estimated_tokens": 1055,
+          "max_estimated_tokens": 1102,
           "accounting_mode": "self_reported"
         },
         {
@@ -162,7 +162,7 @@
     },
     {
       "id": "context-bootstrap",
-      "max_estimated_tokens": 1978,
+      "max_estimated_tokens": 2025,
       "steps": [
         {
           "id": "triage",
@@ -171,7 +171,7 @@
         },
         {
           "id": "orient",
-          "max_estimated_tokens": 1055,
+          "max_estimated_tokens": 1102,
           "accounting_mode": "self_reported"
         },
         {
@@ -199,12 +199,12 @@
     },
     {
       "id": "unknown-option-recovery",
-      "max_estimated_tokens": 585,
+      "max_estimated_tokens": 603,
       "steps": [
         {
           "id": "refuse-option",
-          "max_estimated_tokens": 422,
-          "accounting_mode": "independent_transport"
+          "max_estimated_tokens": 440,
+          "accounting_mode": "self_reported"
         },
         {
           "id": "retry-option",
@@ -261,5 +261,5 @@
       ]
     }
   ],
-  "composite_max_estimated_tokens": 12477
+  "composite_max_estimated_tokens": 12667
 }

package/docs/agent-task-transcripts.json

@@ -186,6 +186,7 @@
           "expected_accounting_mode": "self_reported",
           "required_fields": ["code", "refusal", "recovery"],
           "expected_error_code": "unknown_context_intent",
+          "expected_field_values": { "recovery.recovery_mode": "compact" },
           "expected_refusal_surface": "--for"
         },
         {
@@ -216,7 +217,7 @@
           ],
           "expected_exit_code": 2,
           "expected_output_kind": "refusal",
-          "expected_accounting_mode": "independent_transport",
+          "expected_accounting_mode": "self_reported",
           "required_fields": ["code", "refusal", "recovery"],
           "expected_error_code": "unknown_option",
           "expected_refusal_surface": "--include-body"

package/docs/generated/FLAG_LEXICON_BUDGETS.md

@@ -5,7 +5,7 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
 | Command | Capability family | Canonical flags | Maximum |
 | --- | --- | ---: | ---: |
 | `init` | workspace | 30 | 30 |
-| `config` | workspace | 35 | 35 |
+| `config` | workspace | 36 | 36 |
 | `extension` | extensions | 53 | 53 |
 | `package` | extensions | 54 | 54 |
 | `packages` | extensions | 54 | 54 |
@@ -15,7 +15,7 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
 | `copy` | intake | 24 | 24 |
 | `focus` | intake | 22 | 22 |
 | `list` | context | 86 | 86 |
-| `list-all` | context | 85 | 85 |
+| `list-all` | context | 86 | 86 |
 | `list-draft` | context | 84 | 84 |
 | `list-open` | context | 84 | 84 |
 | `list-in-progress` | context | 84 | 84 |
@@ -28,34 +28,34 @@ 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 | 35 | 35 |
+| `next` | context | 38 | 38 |
 | `history` | evidence | 35 | 35 |
 | `events` | evidence | 33 | 33 |
 | `history-redact` | evidence | 27 | 27 |
-| `history-repair` | evidence | 26 | 26 |
+| `history-repair` | evidence | 27 | 27 |
 | `history-compact` | evidence | 30 | 30 |
 | `history-author-acknowledge` | evidence | 28 | 28 |
-| `merge` | workspace | 24 | 24 |
+| `merge` | workspace | 27 | 27 |
 | `schema` | workspace | 40 | 40 |
 | `profile` | workspace | 22 | 22 |
 | `activity` | context | 35 | 35 |
 | `restore` | intake | 23 | 23 |
 | `update` | lifecycle | 105 | 105 |
-| `update-many` | lifecycle | 140 | 140 |
+| `update-many` | lifecycle | 146 | 146 |
 | `close` | lifecycle | 31 | 31 |
 | `close-many` | lifecycle | 72 | 72 |
 | `delete` | lifecycle | 24 | 24 |
-| `append` | evidence | 24 | 24 |
+| `append` | evidence | 25 | 25 |
 | `comments` | evidence | 31 | 31 |
 | `notes` | evidence | 35 | 35 |
-| `learnings` | evidence | 27 | 27 |
+| `learnings` | evidence | 31 | 31 |
 | `files` | evidence | 39 | 39 |
 | `docs` | evidence | 30 | 30 |
 | `deps` | graph | 32 | 32 |
 | `plan` | graph | 109 | 109 |
-| `test` | quality | 52 | 52 |
+| `test` | quality | 53 | 53 |
 | `test-all` | quality | 40 | 40 |
 | `telemetry` | workspace | 21 | 21 |
 | `stats` | context | 29 | 29 |
@@ -65,7 +65,7 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
 | `gc` | workspace | 22 | 22 |
 | `workspace` | workspace | 23 | 23 |
 | `contracts` | quality | 29 | 29 |
-| `claim` | lifecycle | 36 | 36 |
+| `claim` | lifecycle | 38 | 38 |
 | `release` | lifecycle | 23 | 23 |
 | `start-task` | lifecycle | 23 | 23 |
 | `pause-task` | lifecycle | 23 | 23 |

package/docs/generated/REFUSAL_CLOSURE_CENSUS.md

@@ -4,12 +4,12 @@ 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: 357
+- Catalog error codes: 365
 - 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: 338
-- Coverage fraction: 0.053221
+- Uncovered error codes: 346
+- Coverage fraction: 0.052055
 - Closed-domain probes: 19
 - Grammar probes: 94
 
@@ -111,17 +111,23 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `history_author_acknowledge_selector_required` | `history_author_acknowledge_selector_required` | uncovered | none | 0 |
 | `history_author_acknowledge_target_not_actionable` | `history_author_acknowledge_target_not_actionable` | uncovered | none | 0 |
 | `history_author_acknowledge_target_unreadable` | `history_author_acknowledge_target_unreadable` | uncovered | none | 0 |
+| `history_baseline_unavailable` | `history_baseline_unavailable` | uncovered | none | 0 |
 | `history_drift_chain_mismatch` | `history_drift_chain_mismatch` | uncovered | none | 0 |
 | `history_drift_hash_mismatch` | `history_drift_hash_mismatch` | uncovered | none | 0 |
 | `history_drift_merge_receipt` | `history_drift_merge_receipt` | uncovered | none | 0 |
 | `history_drift_missing_stream` | `history_drift_missing_stream` | uncovered | none | 0 |
 | `history_drift_unreadable_stream` | `history_drift_unreadable_stream` | uncovered | none | 0 |
 | `history_drift_version_skew` | `history_drift_version_skew` | uncovered | none | 0 |
+| `history_json_invalid` | `history_json_invalid` | uncovered | none | 0 |
 | `history_merge_conflict_markers_detected` | `merge_conflict_markers_detected` | uncovered | none | 0 |
+| `history_replay_invalid` | `history_replay_invalid` | uncovered | none | 0 |
+| `history_salvage_refused` | `history_salvage_refused` | uncovered | none | 0 |
 | `history_stream_over_compact_threshold` | `history_stream_over_compact_threshold` | uncovered | none | 0 |
 | `history_target_out_of_range` | `history_target_out_of_range` | uncovered | none | 0 |
 | `history_timestamp_invalid` | `history_timestamp_invalid` | uncovered | none | 0 |
 | `history_unknown_author_events` | `history_unknown_author_events` | uncovered | none | 0 |
+| `history_version_mapping_unavailable` | `history_version_mapping_unavailable` | uncovered | none | 0 |
+| `history_version_pruned` | `history_version_pruned` | uncovered | none | 0 |
 | `host_environment_capacity_fault` | `host_environment_capacity_fault` | uncovered | none | 0 |
 | `host_environment_operation_invalid` | `host_environment_operation_invalid` | uncovered | none | 0 |
 | `host_environment_permission_fault` | `host_environment_permission_fault` | uncovered | none | 0 |
@@ -163,9 +169,11 @@ 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_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_reserved` | `item_identity_reserved` | uncovered | none | 0 |
 | `item_not_found` | `item_not_found` | uncovered | none | 0 |
 | `likely_duplicate` | `likely_duplicate` | uncovered | none | 0 |
 | `linked_artifact_mutation_conflict` | `linked_artifact_mutation_conflict` | 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.4"
+    "version": "2026.9.6"
   },
   "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.4",
+      "version": "2026.9.6",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.9.4",
+  "version": "2026.9.6",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -76,7 +76,7 @@
       "import": "./dist/cli-bundle/sdk-testing.js",
       "default": "./dist/cli-bundle/sdk-testing.js"
     },
-    "./sdk/public-surface.json": "./sdk/public-surface.json",
+    "./sdk/public-surface.json": "./dist/sdk/public-surface.json",
     "./cli": {
       "types": "./dist/cli/public.d.ts",
       "import": "./dist/cli/public.js",
@@ -95,7 +95,6 @@
     "LICENSE",
     "AGENTS.md",
     "docs/**",
-    "sdk/public-surface.json",
     ".claude-plugin/**",
     "plugins/**",
     "packages/pm-*/**",
@@ -225,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.4.2",
-    "jscpd": "^5.1.1",
+    "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.4",
+  "version": "2026.9.6",
   "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.4",
+  "version": "2026.9.6",
   "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.4",
+  "version": "2026.9.6",
   "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.4",
+  "version": "2026.9.6",
   "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.