@unbrained/pm-cli 2026.11.3 → 2026.11.5

package/docs/SDK.md

@@ -107,19 +107,19 @@ Choose the narrowest stable entrypoint that owns the capability you need. This
 keeps package startup and memory proportional to its purpose while the aggregate
 barrel remains source-compatible:
 
-| Package export                              | Intended capability family                                                 |
-| ------------------------------------------- | -------------------------------------------------------------------------- |
-| `@unbrained/pm-cli/sdk/authoring`           | Extension blueprints, builders, manifests, and package-author helpers      |
-| `@unbrained/pm-cli/sdk/contracts`           | Static CLI command/action contracts and expected-error protocol            |
-| `@unbrained/pm-cli/sdk/core`                | Broad item, schema, profile, transaction, and runtime primitives           |
-| `@unbrained/pm-cli/sdk/governance`          | Validation, health, garbage collection, and transaction cleanup            |
-| `@unbrained/pm-cli/sdk/graph`               | Relationship stores, graph assembly, traversal, analytics, and remediation |
-| `@unbrained/pm-cli/sdk/merge`               | VCS-neutral tracker merge contracts                                        |
-| `@unbrained/pm-cli/sdk/query`               | List/search engines, filtering, pagination, and query rendering            |
-| `@unbrained/pm-cli/sdk/runtime`             | Embedded command execution and package runtime helpers                     |
-| `@unbrained/pm-cli/sdk/testing`             | Package and extension assertion/invocation helpers                         |
-| `@unbrained/pm-cli/sdk/public-surface.json` | Published machine-readable SDK compatibility snapshot                      |
-| `@unbrained/pm-cli/sdk`                     | Compatibility aggregate containing every supported SDK export              |
+| Package export | Intended capability family |
+|---|---|
+| `@unbrained/pm-cli/sdk/authoring` | Extension blueprints, builders, manifests, and package-author helpers |
+| `@unbrained/pm-cli/sdk/contracts` | Static CLI command/action contracts and expected-error protocol |
+| `@unbrained/pm-cli/sdk/core` | Broad item, schema, profile, transaction, and runtime primitives |
+| `@unbrained/pm-cli/sdk/governance` | Validation, health, garbage collection, and transaction cleanup |
+| `@unbrained/pm-cli/sdk/graph` | Relationship stores, graph assembly, traversal, analytics, and remediation |
+| `@unbrained/pm-cli/sdk/merge` | VCS-neutral tracker merge contracts |
+| `@unbrained/pm-cli/sdk/query` | List/search engines, filtering, pagination, and query rendering |
+| `@unbrained/pm-cli/sdk/runtime` | Embedded command execution and package runtime helpers |
+| `@unbrained/pm-cli/sdk/testing` | Package and extension assertion/invocation helpers |
+| `@unbrained/pm-cli/sdk/public-surface.json` | Published machine-readable SDK compatibility snapshot |
+| `@unbrained/pm-cli/sdk` | Compatibility aggregate containing every supported SDK export |
 
 `@unbrained/pm-cli/cli` is the supported embeddable CLI entrypoint and exports
 only `runPmCli`. Repository tests import their internal seams from source; those
@@ -177,6 +177,13 @@ preflight refusal. An absent property gives no guarantee about writes; do not
 coerce it to `false` or treat an executed failure as safe to retry. Consumers
 that enumerate error keys should accept the additional optional property.
 
+The telemetry consent update (pm-gh1660) records two conservative breaking
+acknowledgements. `WriteSettingsOptions` gains optional `omitSections` and
+`skipIfStored`; existing calls compile and behave unchanged. `ConfigResult.values`
+becomes `Partial`, because project-scope `list` and `export` omit the global-only
+`telemetry_tracking` key: treat that key as possibly absent, and read consent
+from a global-scope export. No data migration or new dependency bounds are needed.
+
 Validation refusals for item status and priority carry producer-owned
 `code: "invalid_argument_value"` and `context.field`, `context.value` and
 `context.allowed`. The allowed spellings come from the active status schema or
@@ -228,7 +235,7 @@ entrypoint from [Import Surfaces](#import-surfaces) for direct primitives.
 Use these focused guides to choose the primitive and understand its policy:
 
 | Capability | Reference |
-| --- | --- |
+|---|---|
 | Item lifecycle, schema, profiles and initialization | [Customization primitives](SDK_CUSTOMIZATION_PRIMITIVES.md), [Lifecycle](SDK_LIFECYCLE.md) |
 | History, whole-item input, transactions and previews | [Audited mutations](SDK_AUDITED_MUTATIONS.md), [Atomic transactions](#atomic-workspace-transactions), [Schema evolution](#schema-evolution-and-workspace-history) |
 | Context ranking, packing, memory and evaluation | [Context relevance](#context-relevance-and-evaluation), [Context coordination](SDK_CONTEXT_COORDINATION.md) |
@@ -1220,8 +1227,31 @@ SDK `create`, `update`, and `append` inputs are data: `"-"` remains text,
 file. This also applies to the corresponding `runCreate`, `runUpdate`,
 `runAppend` operations and update-many mutation values. Normal field validation,
 whitespace handling, structured collection syntax, and project schemas still
-apply. Clear fields explicitly with `unset: ["assignee"]` or the declared
-`clear*` collection options; JavaScript `null` is not an unset directive.
+apply. Clear a scalar field with `unset: ["assignee"]`, or pass JavaScript
+`null` for any option the command's `unset` list covers: `{ parent: null }` is
+`unset: ["parent"]`, and `tags: null` clears the tags (`tags` takes a CSV string,
+not an array, and has no `clearTags`).
+The nullable keys are exactly the unset table's option keys
+(`CreateNullClearableOptionKey`, `UpdateNullClearableOptionKey`). `rank` is only
+an unset alias of `order`, so `rank: null` is refused (pass `order: null`), and
+create accepts `unset: ["author"]` but refuses `author: null`. `null` on any
+other option (`title`, `author`, collection options such as `comment` or `dep`)
+refuses by name; clear collections with their `clear*` options. When typed input
+stores a former clear sentinel (`"none"`, `"null"` or `"-"`) in a clearable
+field, the result warns `literal_sentinel_stored:<field>:<value>`: the value is
+now data (an assignee called `none`). The advisory appears only while the
+document pm committed and recorded in history still holds the value, so an
+`item_store_write` override that rewrites stored contents can drop it from
+storage while the advisory still reports it. Typed SDK and MCP refusals name the
+option key and the `unset` remedy both accept, for example `parent must not be
+the placeholder "none". Pass unset: ["parent"] to clear it, or omit parent.`;
+CLI refusals keep their flag wording. `PmCreateActionOptions`,
+`PmUpdateActionOptions`, `CreateOperationOptions` and `UpdateOperationOptions`
+type the clearable fields as nullable, so `runCreate`/`runUpdate` accept the
+same input as `PmClient.create`/`update`. A direct SDK `runUpdateMany` folds a
+null in its update record like `runUpdate`, but `runAction("update-many")` drops
+it (pm-w7clh6), so `PmUpdateManyActionOptions` stays non-nullable: use `unset`
+there and in MCP tools.
 CLI adapters retain `--description -`, append stdin, file flags, and legacy
 clear-token compatibility. Values inside CLI `--stdin-json` documents are
 literal data, including `"none"` and `"null"`. Explicit CLI flags override
@@ -1236,7 +1266,7 @@ For example, `estimatedMinutes` requires `"45"`, while `priority` accepts a
 string or finite number. JavaScript and JSON bridge callers must correct invalid
 types instead of relying on coercion. Integrations that previously used `"-"`
 to request stdin should read that input themselves and pass the resulting text;
-integrations that used `"none"` to clear must migrate to `unset`.
+integrations that used `"none"` to clear must migrate to `unset` or `null`.
 Direct `runCreate`/`runUpdate` calls require the declared string arrays for
 repeatable fields. Generic action dispatch retains its documented scalar-to-array
 normalization before invoking those operations.
@@ -1307,8 +1337,21 @@ atomic evidence-backed completion tracked by
 commands that must coordinate several SDK mutations. A plan supplies a stable
 transaction id plus ordered steps. Each step can inspect its durable state,
 apply an idempotent forward mutation, and append an idempotent compensation.
-The coordinator serializes transaction writers with one workspace lock and
+The coordinator serializes transaction coordinators with one workspace lock and
 persists `.agents/pm/transactions/sdk/<transaction-id>.json` after every step.
+That lock does not exclude ordinary writers ([GH-1620](https://github.com/unbraind/pm-cli/issues/1620)):
+`update`, `close`, `pm comments --add` and every other SDK, CLI or MCP mutation
+take per-item locks, so a peer can commit between a step's `inspect()` and
+`apply()`. A step that decides from what it read guards its write with an
+[expected item revision](#expected-item-revisions): in `inspect()`, take both
+the decision data and `item_hash` from one `get()`, then run the write inside
+`withExpectedItemRevisions()`. The
+write then refuses with `item_revision_conflict` instead of overwriting the
+peer's change, and the transaction compensates. The coordinator invokes
+`compensate()`, including during recovery, without an expected revision.
+Built-in item compensations detect intervening writes. A custom adapter must
+fence or reconcile its own compensation, or it can restore a stale value over a
+peer's write.
 Before invoking a pending step, it also persists that step's durable ownership
 marker. Recovery and compensation therefore distinguish mutations begun by
 this transaction from matching domain state that existed before the attempt.
@@ -1348,6 +1391,108 @@ failures and the journal keeps recovery data. Repeated compensation recognizes
 its durable marker even when a peer adds context afterward. Legacy timestamp
 receipts remain supported, with ambiguous partial effects refused.
 
+### Expected item revisions
+
+Expected-revision preconditions are tracked by
+[pm-gh1576](../.agents/pm/features/pm-gh1576.toon).
+
+Read-decide-write agents and packages guard a write with the revision their
+decision was based on. Every current `pm get` / `PmClient.get` read reports
+`item_hash`, the SHA-256 of the canonical item document and the same value as
+the item's latest history `after_hash` (a field-projected read includes it only
+when the selection names the bare `item_hash`, for example `--fields title,tags,item_hash`;
+the item-qualified `item.item_hash` still projects a custom metadata field of that name).
+`readItemRevision(id)` returns it alone. Take the hash from the same read your
+decision uses: a separate read could observe a newer revision than the data you
+decided on. Run the write inside `withExpectedItemRevisions`:
+
+```ts
+import { PmClient, isItemRevisionConflict } from "@unbrained/pm-cli/sdk";
+
+const pm = new PmClient({ pmRoot });
+// Decide from the same read that reports the revision, never from a separate one.
+const read = await pm.get(id);
+const reason = `Delivered by ${read.item.tags?.find((tag) => tag.startsWith("delivery-pr:"))}`;
+try {
+  const { result, unchecked } = await pm.withExpectedItemRevisions(
+    [{ id, itemHash: read.item_hash! }],
+    () => pm.close(id, reason),
+  );
+} catch (error) {
+  if (!isItemRevisionConflict(error)) throw error;
+  // error.context.current_revision and error.context.details.changes_since
+  // describe what changed; re-read, decide again, retry with the new hash.
+}
+```
+
+The check runs inside the locked item store, after the item lock is held and
+before that write. It therefore covers every item write the wrapped
+operation makes: lifecycle commands, annotations, linked files/docs/tests,
+dependency edits, `restore`, `delete`, history maintenance (`history-redact`,
+`history-repair`, `history-compact`, checked under the stream lock), bulk
+transactions and extension commands that mutate through the SDK. A `delete`
+advances the expectation to the item's absent (tombstone) revision, and a
+`restore` of a deleted item is judged under its own id, so a peer deletion
+between the read and the restore refuses instead of being resurrected over. A mismatch refuses that write with `item_revision_conflict`
+(exit 4); writes the operation already committed stay durable. The refusal carries `item_id`, `expected_revision`,
+`current_revision` and `details` with `changes_since`, the newest
+10 history entries after the declared revision
+(`op`, `author`, `ts`, top-level `fields`), plus `changes_since_omitted`.
+`expected_revision_recorded: false` means no history entry ever had that hash.
+After one of the operation's own writes commits, the expectation advances to
+that revision, so a multi-write composition such as `claim --start` does not
+refuse itself; an interleaved peer write still refuses the next step. The
+result lists `checked` ids and `unchecked` ids that the operation never wrote:
+an unchecked expectation proved nothing. Expectations bind to the item's embedded id, so every
+spelling that locates the item (a short id, or a case variant on a
+case-insensitive filesystem) is guarded. The scope is shared process-wide across the
+published SDK entrypoints (`/sdk`, `/sdk/core`, ...), and
+`isItemRevisionConflict` checks the refusal structurally, so mixing entrypoints
+neither drops a guard nor hides its conflict. Trackers are compared by physical
+path (`realpath`), so a symlinked spelling of the same tracker is guarded too. `PmClient.readItemRevision` and
+`PmClient.withExpectedItemRevisions` resolve targets inside the client's
+extension context, so extension item types bind exactly as `get` reads them,
+then run the operation outside it, so its own actions (extension commands
+included) activate and dispatch normally. The standalone `readItemRevision` /
+`withExpectedItemRevisions` functions use the registrations already active in
+the calling context. A deleted item with retained history binds too: its
+revision is the empty tombstone its `delete` recorded (the delete entry's
+`after_hash`), so a guarded `restore` or history maintenance of a deleted item
+can declare it. Bulk `update-many`
+and `close-many` keep their partial-success semantics: a stale row fails with
+`error_code: "item_revision_conflict"` plus its `expected_revision`,
+`current_revision` and the same `details` (`changes_since`,
+`changes_since_omitted`) a single-item refusal carries, while fresh rows
+proceed. The exported `ItemRevisionConflictRowFields` type declares those row
+fields; `HistoryCompactBulkItemResult` and `HistoryRepairAllStreamResult` extend
+it. When an `item_store_write` or `item_store_delete` override transforms,
+redirects or skips a guarded write, the scope advances to the revision read back
+from storage under the item lock: its own next write is admitted, a competing
+one refuses. If the item cannot be read back, or its embedded id was rewritten,
+the next guarded write refuses (fail closed). When a peer writes while `restore` or history maintenance waits for
+its lock, a declared revision turns the generic drift refusal into this typed
+conflict. Linked-test result recording (`test --run`, `test-all` with
+`test_result_tracking` enabled) stays best-effort, except that a stale declared
+revision refuses with `item_revision_conflict` instead of a warning. A guard cannot reach a `--background` test worker,
+which runs in another process, so `test`/`test-all --background` with an
+expected revision refuses with `expect_hash_background_unsupported`. Only the CLI invocation scope reads `GlobalOptions.expectHash`;
+direct `run*` SDK calls ignore it, so guard SDK writes with the functions above
+or `runAction`/MCP `expectHash`.
+
+Transports use the same grammar. The CLI's global `--expect-hash <item_hash>`
+binds to the command's `<id>`; `--expect-hash <id>=<item_hash>` (repeatable or
+comma-separated) names targets explicitly and is required for bulk commands.
+MCP tools and `PmClient.run` accept `expectHash` (string or string array) on
+every item-writing action, at the top level or inside `options`; either
+placement is enforced. A native read action refuses the flag with
+`expect_hash_requires_mutation`, and a malformed, supplied-but-empty or `null`
+value (for example an unset shell variable) refuses with `expect_hash_invalid`
+rather than silently dropping the guard. An expectation no write reached is reported as the
+warning `expect_hash_unchecked:<id>:no_locked_write_reached_this_item`. This
+precondition guards the gap between an agent's read and its write; lease
+fencing ([pm-gh1549](../.agents/pm/issues/pm-gh1549.toon)) still guards the
+write itself against lock takeover, and the two compose.
+
 ### Schema evolution and workspace history
 
 Tracked by [pm-dijg](../.agents/pm/features/pm-dijg.toon) and
@@ -2559,25 +2704,25 @@ For provider-safe schemas, use `PM_PROVIDER_TOOL_PARAMETERS_SCHEMA`. It is flat
 
 ## Capability Requirements
 
-| Registration                 | Manifest capability |
-| ---------------------------- | ------------------- |
-| `registerCommand`            | `commands`          |
-| inline command flags         | `schema`            |
-| `registerFlags`              | `schema`            |
-| `registerItemFields`         | `schema`            |
-| `registerItemTypes`          | `schema`            |
-| `registerRelationshipKinds`  | `schema`            |
-| `registerMigration`          | `schema`            |
-| `registerProfile`            | `schema`            |
-| `registerImporter`           | `importers`         |
-| `registerExporter`           | `importers`         |
-| `registerParser`             | `parser`            |
-| `registerPreflight`          | `preflight`         |
-| `registerService`            | `services`          |
-| `registerRenderer`           | `renderers`         |
-| lifecycle hooks              | `hooks`             |
-| `registerSearchProvider`     | `search`            |
-| `registerVectorStoreAdapter` | `search`            |
+| Registration | Manifest capability |
+|---|---|
+| `registerCommand` | `commands` |
+| inline command flags | `schema` |
+| `registerFlags` | `schema` |
+| `registerItemFields` | `schema` |
+| `registerItemTypes` | `schema` |
+| `registerRelationshipKinds` | `schema` |
+| `registerMigration` | `schema` |
+| `registerProfile` | `schema` |
+| `registerImporter` | `importers` |
+| `registerExporter` | `importers` |
+| `registerParser` | `parser` |
+| `registerPreflight` | `preflight` |
+| `registerService` | `services` |
+| `registerRenderer` | `renderers` |
+| lifecycle hooks | `hooks` |
+| `registerSearchProvider` | `search` |
+| `registerVectorStoreAdapter` | `search` |
 
 Some override surfaces are single-winner: command overrides, parser overrides,
 preflight overrides, and output renderers. Preflight overrides can declare
@@ -3608,7 +3753,7 @@ const report = assertExtensionPreflight(blueprint, {
 When a custom harness needs individual registries, use this ownership map:
 
 | Surface | Registry from `activateExtensionForTest` | Assertion / invocation |
-| --- | --- | --- |
+|---|---|---|
 | Commands, schema types/fields, migrations, importers/exporters, search/vector providers | `registrations` | `assertRegisteredCommandContract`, corresponding `assertRegistered*` |
 | Command overrides | `commands` | `assertRegisteredCommandOverride`, `runRegisteredCommandOverrideForTest` |
 | Parser overrides | `parsers` | `assertRegisteredParserOverride`, `runRegisteredParserOverrideForTest` |

package/docs/SDK_ARTIFACT_OUTPUT.md

@@ -49,7 +49,7 @@ description.
 ## Channel behavior
 
 | Artifact channel | Default receipt | stdout | stderr |
-| --- | --- | --- | --- |
+|---|---|---|---|
 | `stdout` | `suppress` | Artifact bytes only | Extension-owned diagnostics or summary |
 | `file` | `render` | Bounded structured receipt | Extension-owned diagnostics |
 

package/docs/SDK_PRIMITIVE_INVENTORY.md

@@ -35,7 +35,7 @@ inline tracker-not-initialized message anywhere under `src/sdk`.
 ## Promotion Partition
 
 | Promotion item | Primitive family | Primary private domains to promote |
-| --- | --- | --- |
+|---|---|---|
 | [pm-98cz](../.agents/pm/features/pm-98cz.toon) | Item lifecycle | `core/item`, `core/store`, `core/lock`, mutation checkpoints |
 | [pm-rjqr](../.agents/pm/features/pm-rjqr.toon) | Query and read | `core/search`, read projections, context/next/list/get aggregation |
 | [pm-zwpp](../.agents/pm/features/pm-zwpp.toon) | Annotations and links | comments, notes, learnings, files, docs, deps, append metadata |
@@ -48,7 +48,7 @@ inline tracker-not-initialized message anywhere under `src/sdk`.
 ## Command Family Map
 
 | CLI/MCP source family | SDK destination | Notes |
-| --- | --- | --- |
+|---|---|---|
 | `create`, `update`, `update-many`, `copy`, `delete`, `restore` | [pm-98cz](../.agents/pm/features/pm-98cz.toon) | Item CRUD and replay paths should become typed lifecycle SDK calls. |
 | `claim`, `release`, `focus`, lifecycle shortcut helpers | [pm-98cz](../.agents/pm/features/pm-98cz.toon) | Ownership and actionable-state changes belong beside lifecycle primitives. |
 | `list`, `get`, `search`, `context`, `next`, `aggregate`, `stats` | [pm-rjqr](../.agents/pm/features/pm-rjqr.toon) | `list` and `search` implementations now live under `src/sdk/query/**`; remaining read models should follow the same SDK-owned pattern. |

package/docs/SELF_DESCRIBING_CONTEXT_CONTRACTS.md

@@ -17,13 +17,13 @@ Use `pm contracts --summary --json` for the bounded bootstrap and `pm contracts
 
 The read primitives accept `--for <intent>`:
 
-| Command                 | Built-in intent     | Purpose                                          |
-| ----------------------- | ------------------- | ------------------------------------------------ |
-| `context`               | `orient`, `handoff` | Active hierarchy or continuation context         |
-| `get`                   | `inspect`           | Complete item lifecycle and relationship context |
-| `list` and list aliases | `triage`            | Compact governance and ownership fields          |
-| `next`                  | `execute`           | One actionable recommendation                    |
-| `search`                | `discover`          | Ranked canonical-lineage candidates              |
+| Command | Built-in intent | Purpose |
+|---|---|---|
+| `context` | `orient`, `handoff` | Active hierarchy or continuation context |
+| `get` | `inspect` | Complete item lifecycle and relationship context |
+| `list` and list aliases | `triage` | Compact governance and ownership fields |
+| `next` | `execute` | One actionable recommendation |
+| `search` | `discover` | Ranked canonical-lineage candidates |
 
 Explicit projection and token flags win over intent defaults:
 

package/docs/TESTING.md

@@ -280,7 +280,7 @@ required CI asks for as few runners as the proofs allow
 ([pm-m6ig79](../.agents/pm/issues/pm-m6ig79.toon)):
 
 | Job | Runs |
-| --- | --- |
+|---|---|
 | `Build foundation (Ubuntu, Node 24)` | Build, `dist` artifact, packed tarball. |
 | `Packed runtime (<os>)` × 3 | Packed first run on Node 22.18.0 and 24 in isolated prefixes, dist version smoke; Ubuntu adds the Node 22 telemetry and snapshot regressions, macOS the native shell and portability checks, Windows the full npm npx and Bun bunx acceptance. |
 | `Gates (static)` | Typecheck, version, changelog, secret scan, `pnpm lint` (`quality:static`), package artifact, token budgets, tracker merge-safety and assurance gates. |

package/docs/WORKFLOW_POLICIES.md

@@ -40,7 +40,7 @@ match the destination; other selectors inspect both snapshots so a mutation cann
 escape a protected scope by removing its tag or changing its type.
 
 | Rule kind | Required properties | Behavior |
-| --- | --- | --- |
+|---|---|---|
 | `require_fields` | `fields` | Checks evidence on lifecycle, scope, or required-field changes |
 | `transition` | `allowed` | Allows listed `[from, to]` status pairs; `$create` and `$delete` represent absent records |
 | `authors` | `authors` | Requires a listed mutation actor |
@@ -153,7 +153,7 @@ 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 |

package/docs/WORKSPACE_POSITION_AND_LIFECYCLE.md

@@ -69,14 +69,14 @@ tokenized recovery actions.
 
 Recovery precedence is intentional:
 
-| State                           | Next action                                | Why it comes first                                                        |
-| ------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------- |
-| `merge_evidence_invalid`        | `pm merge report`                          | Untrusted evidence must be inspected before it can drive repair.          |
-| `history_evidence_invalid`      | `pm validate --check-history-drift --full` | Required history evidence could not be interpreted safely.                |
-| `merge_reconciliation_required` | `pm merge reconcile`                       | Pending scalar decisions can explain and settle merge-created divergence. |
-| `history_repair_required`       | `pm history-repair --all`                  | Remaining append-only drift needs an audited re-anchor.                   |
-| `merge_fence_unprepared`        | `pm merge install`                         | The committed fence or clone-local drivers are absent or drifted.         |
-| `ready`                         | none                                       | All included readiness predicates passed.                                 |
+| State | Next action | Why it comes first |
+|---|---|---|
+| `merge_evidence_invalid` | `pm merge report` | Untrusted evidence must be inspected before it can drive repair. |
+| `history_evidence_invalid` | `pm validate --check-history-drift --full` | Required history evidence could not be interpreted safely. |
+| `merge_reconciliation_required` | `pm merge reconcile` | Pending scalar decisions can explain and settle merge-created divergence. |
+| `history_repair_required` | `pm history-repair --all` | Remaining append-only drift needs an audited re-anchor. |
+| `merge_fence_unprepared` | `pm merge install` | The committed fence or clone-local drivers are absent or drifted. |
+| `ready` | none | All included readiness predicates passed. |
 
 `pm health --strict-exit` also treats missing clone-local merge drivers as blocking. Default health remains advisory for never-installed drivers so ordinary diagnostics retain backward compatibility.
 

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

@@ -1 +1 @@
-{"version":5,"transcript_version":2,"transcript_digest":"sha256:b4b151f3d36860e73cd535d0520e9f03b4ecec4444ee81a8b868896b5b0bba47","estimator":"ceil(utf8_bytes / 4)","comparison_scope":"plan_recovery_tracker_root_canonicalized","measurement_scope":"output_before_token_accounting","published_with_release":true,"orientation":{"canonical_task_id":"orientation-context-intent","required_capabilities":["actionable_work","active_ownership","workspace_state"],"measured_winner_tokens":1051,"protocols":[{"task_id":"orientation-context-intent","command_count":1,"estimated_tokens":1051,"capabilities":["actionable_work","active_ownership","workspace_state"],"capability_evidence":{"actionable_work":[{"step_id":"context","field_path":"hierarchy"}],"active_ownership":[{"step_id":"context","field_path":"activity"}],"workspace_state":[{"step_id":"context","field_path":"summary.active_items"}]}},{"task_id":"orientation-operating-rules","command_count":4,"estimated_tokens":2067,"capabilities":["actionable_work","active_ownership","workspace_state"],"capability_evidence":{"actionable_work":[{"step_id":"open","field_path":"items"}],"active_ownership":[{"step_id":"in-progress","field_path":"items"}],"workspace_state":[{"step_id":"context","field_path":"summary.active_items"}]}},{"task_id":"orientation-contracts-next","command_count":2,"estimated_tokens":5213,"capabilities":["actionable_work","active_ownership","workspace_state"],"capability_evidence":{"actionable_work":[{"step_id":"next","field_path":"recommended.id"}],"active_ownership":[{"step_id":"next","field_path":"held_by_others"}],"workspace_state":[{"step_id":"next","field_path":"summary.in_progress"}]}}]},"tasks":[{"id":"orientation-context-intent","max_estimated_tokens":1051,"steps":[{"id":"context","max_estimated_tokens":1051,"accounting_mode":"self_reported"}]},{"id":"orientation-contracts-next","max_estimated_tokens":5213,"steps":[{"id":"contracts","max_estimated_tokens":4481,"accounting_mode":"self_reported"},{"id":"next","max_estimated_tokens":732,"accounting_mode":"self_reported"}]},{"id":"orientation-operating-rules","max_estimated_tokens":2067,"steps":[{"id":"context","max_estimated_tokens":1015,"accounting_mode":"self_reported"},{"id":"search","max_estimated_tokens":164,"accounting_mode":"self_reported"},{"id":"open","max_estimated_tokens":712,"accounting_mode":"self_reported"},{"id":"in-progress","max_estimated_tokens":176,"accounting_mode":"self_reported"}]},{"id":"context-bootstrap","max_estimated_tokens":2005,"steps":[{"id":"triage","max_estimated_tokens":619,"accounting_mode":"self_reported"},{"id":"orient","max_estimated_tokens":1015,"accounting_mode":"self_reported"},{"id":"inspect","max_estimated_tokens":371,"accounting_mode":"self_reported"}]},{"id":"closed-domain-recovery","max_estimated_tokens":630,"steps":[{"id":"refuse-intent","max_estimated_tokens":259,"accounting_mode":"self_reported"},{"id":"retry-intent","max_estimated_tokens":371,"accounting_mode":"self_reported"}]},{"id":"unknown-option-recovery","max_estimated_tokens":596,"steps":[{"id":"refuse-option","max_estimated_tokens":433,"accounting_mode":"self_reported"},{"id":"retry-option","max_estimated_tokens":163,"accounting_mode":"self_reported"}]},{"id":"lifecycle-mutation","max_estimated_tokens":873,"steps":[{"id":"create","max_estimated_tokens":20,"accounting_mode":"self_reported"},{"id":"inspect-open","max_estimated_tokens":363,"accounting_mode":"self_reported"},{"id":"close","max_estimated_tokens":92,"accounting_mode":"self_reported"},{"id":"inspect-closed","max_estimated_tokens":398,"accounting_mode":"self_reported"}]},{"id":"bulk-effect-outcomes","max_estimated_tokens":392,"steps":[{"id":"create-bulk-target","max_estimated_tokens":20,"accounting_mode":"self_reported"},{"id":"partial-effect","max_estimated_tokens":240,"accounting_mode":"self_reported"},{"id":"no-effect","max_estimated_tokens":132,"accounting_mode":"self_reported"}]},{"id":"plan-execution-mutations","max_estimated_tokens":806,"steps":[{"id":"create-plan","max_estimated_tokens":21,"accounting_mode":"self_reported"},{"id":"add-step","max_estimated_tokens":254,"accounting_mode":"self_reported"},{"id":"complete-step","max_estimated_tokens":253,"accounting_mode":"self_reported"},{"id":"inspect-plan","max_estimated_tokens":278,"accounting_mode":"self_reported"}]}],"composite_max_estimated_tokens":13633}
+{"version":5,"transcript_version":2,"transcript_digest":"sha256:b4b151f3d36860e73cd535d0520e9f03b4ecec4444ee81a8b868896b5b0bba47","estimator":"ceil(utf8_bytes / 4)","comparison_scope":"plan_recovery_tracker_root_canonicalized","measurement_scope":"output_before_token_accounting","published_with_release":true,"orientation":{"canonical_task_id":"orientation-context-intent","required_capabilities":["actionable_work","active_ownership","workspace_state"],"measured_winner_tokens":1051,"protocols":[{"task_id":"orientation-context-intent","command_count":1,"estimated_tokens":1051,"capabilities":["actionable_work","active_ownership","workspace_state"],"capability_evidence":{"actionable_work":[{"step_id":"context","field_path":"hierarchy"}],"active_ownership":[{"step_id":"context","field_path":"activity"}],"workspace_state":[{"step_id":"context","field_path":"summary.active_items"}]}},{"task_id":"orientation-operating-rules","command_count":4,"estimated_tokens":2067,"capabilities":["actionable_work","active_ownership","workspace_state"],"capability_evidence":{"actionable_work":[{"step_id":"open","field_path":"items"}],"active_ownership":[{"step_id":"in-progress","field_path":"items"}],"workspace_state":[{"step_id":"context","field_path":"summary.active_items"}]}},{"task_id":"orientation-contracts-next","command_count":2,"estimated_tokens":5213,"capabilities":["actionable_work","active_ownership","workspace_state"],"capability_evidence":{"actionable_work":[{"step_id":"next","field_path":"recommended.id"}],"active_ownership":[{"step_id":"next","field_path":"held_by_others"}],"workspace_state":[{"step_id":"next","field_path":"summary.in_progress"}]}}]},"tasks":[{"id":"orientation-context-intent","max_estimated_tokens":1051,"steps":[{"id":"context","max_estimated_tokens":1051,"accounting_mode":"self_reported"}]},{"id":"orientation-contracts-next","max_estimated_tokens":5213,"steps":[{"id":"contracts","max_estimated_tokens":4481,"accounting_mode":"self_reported"},{"id":"next","max_estimated_tokens":732,"accounting_mode":"self_reported"}]},{"id":"orientation-operating-rules","max_estimated_tokens":2067,"steps":[{"id":"context","max_estimated_tokens":1015,"accounting_mode":"self_reported"},{"id":"search","max_estimated_tokens":164,"accounting_mode":"self_reported"},{"id":"open","max_estimated_tokens":712,"accounting_mode":"self_reported"},{"id":"in-progress","max_estimated_tokens":176,"accounting_mode":"self_reported"}]},{"id":"context-bootstrap","max_estimated_tokens":2025,"steps":[{"id":"triage","max_estimated_tokens":619,"accounting_mode":"self_reported"},{"id":"orient","max_estimated_tokens":1015,"accounting_mode":"self_reported"},{"id":"inspect","max_estimated_tokens":391,"accounting_mode":"self_reported"}]},{"id":"closed-domain-recovery","max_estimated_tokens":650,"steps":[{"id":"refuse-intent","max_estimated_tokens":259,"accounting_mode":"self_reported"},{"id":"retry-intent","max_estimated_tokens":391,"accounting_mode":"self_reported"}]},{"id":"unknown-option-recovery","max_estimated_tokens":596,"steps":[{"id":"refuse-option","max_estimated_tokens":433,"accounting_mode":"self_reported"},{"id":"retry-option","max_estimated_tokens":163,"accounting_mode":"self_reported"}]},{"id":"lifecycle-mutation","max_estimated_tokens":915,"steps":[{"id":"create","max_estimated_tokens":20,"accounting_mode":"self_reported"},{"id":"inspect-open","max_estimated_tokens":384,"accounting_mode":"self_reported"},{"id":"close","max_estimated_tokens":92,"accounting_mode":"self_reported"},{"id":"inspect-closed","max_estimated_tokens":419,"accounting_mode":"self_reported"}]},{"id":"bulk-effect-outcomes","max_estimated_tokens":392,"steps":[{"id":"create-bulk-target","max_estimated_tokens":20,"accounting_mode":"self_reported"},{"id":"partial-effect","max_estimated_tokens":240,"accounting_mode":"self_reported"},{"id":"no-effect","max_estimated_tokens":132,"accounting_mode":"self_reported"}]},{"id":"plan-execution-mutations","max_estimated_tokens":806,"steps":[{"id":"create-plan","max_estimated_tokens":21,"accounting_mode":"self_reported"},{"id":"add-step","max_estimated_tokens":254,"accounting_mode":"self_reported"},{"id":"complete-step","max_estimated_tokens":253,"accounting_mode":"self_reported"},{"id":"inspect-plan","max_estimated_tokens":278,"accounting_mode":"self_reported"}]}],"composite_max_estimated_tokens":13715}

package/docs/generated/AGENT_CAPABILITY_ROUTING.md

@@ -5,7 +5,7 @@ Tracker: `pm-kxci8x`.
 This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it manually.
 
 | Capability family | Commands |
-| --- | --- |
+|---|---|
 | workspace | `workspace init`, `workspace config`, `workspace merge`, `workspace schema`, `workspace profile`, `ops telemetry`, `ops health`, `ops gc`, `workspace` |
 | 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` |

package/docs/generated/AGENT_COMMAND_SURFACE.md

@@ -3,7 +3,7 @@
 This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it manually.
 
 | Command | Minimum visibility tier | Capability family |
-| --- | --- | --- |
+|---|---|---|
 | `init` | core | workspace |
 | `workspace init` | core | workspace |
 | `config` | standard | workspace |