@unbrained/pm-cli 2026.8.11 → 2026.8.12

package/docs/MERGE_SAFETY.md

@@ -61,7 +61,7 @@ pm merge install --dry-run --json
 | tracker `**/*.jsonl` except the later `history/*.jsonl` override | `pm-relationship`                   | Covers default and package-owned custom relationship event paths, unions divergent suffixes by `eventId` (timestamp-ordered, ours-first on ties), and renumbers `sequence` consecutively so the strict-sequence store loader accepts the merged stream. |
 | root `settings.json` and nested `**/*.json`                      | `pm-json`                           | Recursively merges objects per key. Arrays compose when both branches preserve the base and add distinct entries, so independent extension installs and evaluation additions merge without weakening edit/removal conflict detection.                   |
 
-When both sides change the same item scalar differently, the driver writes the same stable value regardless of which branch Git labels ours or theirs, but exits nonzero. JSON leaf conflicts retain the explicit preferred-side policy. Git keeps either path conflicted so a human or coordinating agent must review the discarded value and explicitly `git add` the resolution.
+When both sides change the same item scalar differently, the driver writes the same stable value regardless of which branch Git labels ours or theirs, but exits nonzero. Item results and receipts expose the caller's `requested_preference`; the per-decision `retained` and `discarded` values or hashes are authoritative because stable value order can retain either side. Readers normalize the legacy receipt key `preferred`, while new receipts no longer emit it. JSON leaf conflicts retain the explicit preferred-side policy. Git keeps either path conflicted so a human or coordinating agent must review the discarded value and explicitly `git add` the resolution. This correction is tracked by [pm-qckpnq](../.agents/pm/issues/pm-qckpnq.toon).
 
 The driver result's `guidance` always points unresolved conflicts to `pm merge report`. When a clone-local receipt exists, guidance includes its privacy-safe receipt and item ids for exact correlation; discarded values remain confined to the local receipt and never appear in generic logs or tracker history. Tracked by [pm-fbrz7p](../.agents/pm/issues/pm-fbrz7p.toon).
 
@@ -133,6 +133,8 @@ pm merge reconcile --dry-run --json
 
 `history-repair` records the reconciliation patch and classifies its changed fields against the final item. Append-only collection unions and deterministic reordering are reported as preserved context without a data-loss warning. Fields whose replayed values are actually removed or replaced remain loud with discarded event authors/operations and recovery guidance. Re-apply any intended losing mutation as a normal `pm update` so it remains explicit and auditable.
 
+History events now declare an item-hash epoch. The current epoch preserves linked-test insertion order; unversioned streams are verified against both the legacy sorted-test canonicalization and the order-preserving canonicalization. An unknown explicit epoch is reported as `unsupported_item_hash_version` and repair refuses to guess. This keeps version incompatibility distinct from item corruption and is tracked by [pm-2htk4p](../.agents/pm/issues/pm-2htk4p.toon).
+
 ## Delete versus modify policy
 
 A delete on one branch and an edit on another is not safely resolvable by a generic file driver. The merged workspace must not silently resurrect the item. `storage_integrity` reports the live document plus delete-terminated history as a hard finding. The coordinator chooses one policy explicitly:

package/docs/OUTPUT_PROJECTION_CONTRACTS.md

@@ -12,7 +12,10 @@ cursor-chain amortization are tracked by
 [pm-yekkvt](../.agents/pm/issues/pm-yekkvt.toon), and
 [pm-sf31yl](../.agents/pm/issues/pm-sf31yl.toon). Trustworthy collection
 selectors are tracked by
-[pm-x710qm](../.agents/pm/issues/pm-x710qm.toon).
+[pm-x710qm](../.agents/pm/issues/pm-x710qm.toon). Default contract suppression
+and canonical TOON tables are tracked by
+[pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon) and
+[pm-5y05kq](../.agents/pm/issues/pm-5y05kq.toon).
 
 ## Agent Quick Context
 
@@ -38,12 +41,13 @@ explicit receipt with `has_omissions: false`,
 
 Mutually exclusive output modes emit only their active row collection:
 
-| Command mode                | Active row key     | Withheld group | Restore          |
-| --------------------------- | ------------------ | -------------- | ---------------- |
-| `activity --compact`        | `compact_activity` | `provenance`   | `--full`         |
-| `activity --full`           | `activity`         | none           | already complete |
-| `history` (compact default) | `compact_history`  | `raw_history`  | `--full`         |
-| `history --full`            | `history`          | none           | already complete |
+| Command mode                | Active row key        | Withheld group | Restore          |
+| --------------------------- | --------------------- | -------------- | ---------------- |
+| `activity` (digest default) | `activity_digest`     | `event_rows`   | `--raw`          |
+| `activity --raw/--compact`  | `compact_activity`    | `provenance`   | `--full`         |
+| `activity --full`           | `activity`            | none           | already complete |
+| `history` (compact default) | `compact_history`     | `raw_history`  | `--full`         |
+| `history --full`            | `history`             | none           | already complete |
 
 Inactive row keys are omitted, not zero-filled. This makes a wrong parser loud:
 reading `.activity` from compact activity now yields a missing key instead of a
@@ -57,8 +61,11 @@ integrations and built-in output cannot drift independently.
 
 ## Universal Read Rows
 
-Core read results expose a `row_contract` whether or not the current page has
-rows:
+Core read results expose `row_contract` only when callers request
+`--output-row-contract` / `outputRowContract: true`. Keeping discovery metadata
+off by default makes ordinary reads pay for project data rather than repeating
+the same selector declaration. The explicit contract remains available whether
+or not the current page has rows:
 
 ```json
 {
@@ -67,7 +74,8 @@ rows:
     "row_kind": "collection",
     "row_keys": ["items"],
     "fields": "supported",
-    "jq_selector": ".row_contract.row_keys[] as $key | getpath($key | split(\".\")) | if type == \"array\" then .[] else if type == \"object\" then to_entries[] else empty end end"
+    "jq_selector": ".row_contract.row_keys[] as $key | getpath($key | split(\".\")) | if type == \"array\" then .[] else if type == \"object\" then to_entries[] else empty end end",
+    "toon_encoding": "tabular_when_uniform"
   }
 }
 ```
@@ -80,7 +88,12 @@ collections declare every active dot-delimited path. This keeps
 nested dependency graph and relationship-context rows addressable as
 `graph.nodes`, `graph.edges`, `context.nodes`, and `context.edges` without
 duplicating them at the envelope root. Array collections produce their
-elements; object maps such as stats counts produce jq `to_entries` rows.
+elements; object maps produce jq `to_entries` rows.
+`toon_encoding: "tabular_when_uniform"` declares that an array of flat objects
+with one shared key set renders as a length-marked TOON table; mixed, nested,
+or heterogeneous arrays retain the expanded representation. Quoted,
+separator-bearing, and multiline values use the canonical TOON encoder and
+round-trip through the strict decoder.
 Commands without a row collection, including a dependency tree or leaf `get`,
 declare `row_kind: "none"`, an empty `row_keys` array, and omit `jq_selector`.
 The absence is therefore distinguishable from a legitimate empty collection.
@@ -94,8 +107,8 @@ publish a row contract.
 SDK and package authors can import `PM_READ_ROW_CONTRACTS`,
 `PM_READ_ROW_JQ_SELECTOR`, and `resolveReadRowContract` from
 `@unbrained/pm-cli/sdk`. Existing package declarations are preserved only
-when `command`, `row_kind`, `row_keys`, `fields`, and the conditional
-`jq_selector` form a structurally valid row contract; malformed declarations
+when `command`, `row_kind`, `row_keys`, `fields`, the conditional
+`jq_selector`, and any supplied `toon_encoding` form a structurally valid row contract; malformed declarations
 are replaced by the canonical built-in contract when one applies.
 
 ## Self-Describing SDK Projections

package/docs/README.md

@@ -54,7 +54,9 @@ pm guide release --json
 - [SDK Agent Session and Episode Context](SDK_AGENT_SESSION_CONTEXT.md) - inherited role/topic context, cross-process episode identity, and deterministic history grouping.
 - [Improvement Ledger and History Analytics](IMPROVEMENT_ANALYTICS.md) - audited quantitative observations, live provenance coverage, and bounded observational fleet outcomes.
 - [Project Assurance Primitives](ASSURANCE.md) - SDK-owned measurements, assertions, lifecycle gates, cost receipts, and durable verdict history shared by CLI and MCP.
+- [Trustworthy Context and Evidence Contracts](TRUSTWORTHY_CONTEXT_EVIDENCE.md) - full-record assurance, graph composition, boolean health rows, lossless linked-test removal, and role-labelled recovery.
 - [SDK Evidence Traceability and Integrity](SDK_EVIDENCE_TRACEABILITY.md) - reverse source-to-item lookup, atomic evidence replacement, no-op history, linked-test collision classification, and telemetry drain receipts.
+- [SDK Context and Evidence Contracts](SDK_CONTEXT_EVIDENCE_CONTRACTS.md) - material omission receipts, scoped preflight activation, truthful merge preference, claim-race classification, and versioned history hashes.
 - [Reproducible Workspaces and Snapshots](REPRODUCIBLE_WORKSPACES.md) - deterministic SDK recipes and content-addressed authoritative tracker restore points.
 - [Portable Corpus Shapes](CORPUS_SHAPES.md) - versioned SDK populations for realistic benchmarks, evaluations, and package tests.
 - [Agent UX Contracts](AGENT_UX_CONTRACTS.md) - ordering-cycle advisories, graph count units, collision safety, compact context, ownership wording, and recovery behavior.

package/docs/READ_OUTPUT_CONTRACTS.md

@@ -1,6 +1,6 @@
 # Universal Read Output Contracts
 
-Tracker references: [pm-hb7ug8](../.agents/pm/features/pm-hb7ug8.toon), [pm-cxr0jb](../.agents/pm/features/pm-cxr0jb.toon), [pm-hid9g1](../.agents/pm/features/pm-hid9g1.toon), and [pm-sb0tns](../.agents/pm/issues/pm-sb0tns.toon).
+Tracker references: [pm-hb7ug8](../.agents/pm/features/pm-hb7ug8.toon), [pm-cxr0jb](../.agents/pm/features/pm-cxr0jb.toon), [pm-hid9g1](../.agents/pm/features/pm-hid9g1.toon), [pm-sb0tns](../.agents/pm/issues/pm-sb0tns.toon), and [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon).
 
 ## Agent Quick Context
 
@@ -19,6 +19,10 @@ Row shaping follows each envelope's `row_contract.row_keys`, including
 dot-delimited nested arrays and object maps such as `graph.nodes`. Include,
 amount, repeat suppression, and cost compaction therefore operate on the same
 machine-declared rows; they do not rely on command-specific top-level keys.
+The runtime uses that declaration internally on every read but omits the
+repeated metadata from results by default. Request
+`--output-row-contract` / `outputRowContract: true` when a consumer needs the
+row paths, jq selector, and active TOON encoding contract.
 
 ## Cross-Call Context Sessions
 
@@ -46,6 +50,15 @@ tokens separately when the remaining group allowance is smaller than the
 minimum control envelope, plus the accumulated spend, remaining capacity,
 newly served items, and suppressed repeats.
 
+The carried served-item set accepts at most 10,000 identities. A receipt always
+preserves identities already present in the supplied state and retains newly
+served identities in deterministic order until that capacity is full. When a
+single read crosses the boundary, `seen_item_overflow_count` reports how many
+new identities were not carried forward; those facts remain in the current
+envelope and may be served in full again on a later read. The emitted
+`next_state` therefore always remains valid input to the next call without
+silently widening the safety bound.
+
 Session state is deliberately caller-carried: CLI processes, SDK clients, MCP
 hosts, and packages share the same deterministic primitive without a hidden
 daemon or mutable cache. Validation rejects unknown fields, invalid identifiers,
@@ -69,12 +82,13 @@ tracker content.
 
 ## Precedence and Compatibility
 
-Resolution is deterministic: canonical controls win over command-local compatibility options, which win over intent defaults, which win over command defaults. Existing options such as `--fields`, `--limit`, `--token-budget`, `--format`, `--brief`, and `--full` remain accepted. Contract output marks them as hidden compatibility aliases and supplies a migration hint; traversal, cursor, side-effect, and streaming controls instead receive an explicit behavior-preservation hint because a static output control cannot replace their semantics. Callers that omit the canonical controls receive the byte-identical established result.
+Resolution is deterministic: canonical controls win over command-local compatibility options, which win over intent defaults, which win over command defaults. Existing options such as `--fields`, `--limit`, `--token-budget`, `--format`, `--brief`, and `--full` remain accepted. Contract output marks them as hidden compatibility aliases and supplies a migration hint; traversal, cursor, side-effect, and streaming controls instead receive an explicit behavior-preservation hint because a static output control cannot replace their semantics. Callers that omit the four shaping dimensions retain the established data projection; the one intentional envelope correction is that repeated `row_contract` metadata is now opt-in.
 
 ```bash
 pm list-open --output-include id,title,status --output-limit 10
 pm context --for orient --output-budget 900 --output-format toon
 pm search "runtime contracts" --output-limit 5 --output-format json
+pm stats --output-row-contract
 pm contracts --full --json
 ```
 
@@ -93,6 +107,7 @@ const result = await pm.list({
   outputInclude: "id,title,status",
   outputLimit: 10,
   outputBudget: 800,
+  outputRowContract: true,
   outputSession: {
     version: 1,
     id: "orientation",

package/docs/SDK_AGENT_SESSION_CONTEXT.md

@@ -5,7 +5,8 @@ Tracker references: [pm-9wbiye](../.agents/pm/issues/pm-9wbiye.toon),
 [pm-oqo9l2](../.agents/pm/features/pm-oqo9l2.toon),
 [pm-3zgh2c](../.agents/pm/features/pm-3zgh2c.toon),
 [pm-eq9dlw](../.agents/pm/issues/pm-eq9dlw.toon), and
-[pm-lu6sca](../.agents/pm/features/pm-lu6sca.toon).
+[pm-lu6sca](../.agents/pm/features/pm-lu6sca.toon), plus
+[pm-5q8wa0](../.agents/pm/issues/pm-5q8wa0.toon).
 
 Project management is context management. The public SDK therefore carries a
 session's purpose and episode boundary through the same immutable history that
@@ -137,6 +138,16 @@ without confusing an unavailable harness signal with a failed resolver. The
 warning is advisory and the storage check includes the bounded attempt and
 success counters for diagnosis.
 
+Older immutable history can also contain roles outside the controlled domain,
+including values recorded from presence-only harness flags before semantic role
+validation existed. `pm health` retains the privacy-safe
+`provenance_value_domain_invalid:<harness>:<dimension>:<value-shape>:<count>`
+warning and its bounded storage aggregate, but treats the finding as advisory:
+truthful append-only history is not rewritten merely to make health green. New
+session, environment, MCP, and inferred provenance still pass through the
+controlled write-time validator, so this disposition does not permit new
+invalid values.
+
 ## Cross an MCP boundary
 
 An embedding MCP client can add bounded `provenance` and `episode` fields to

package/docs/SDK_CONTEXT_EVIDENCE_CONTRACTS.md

@@ -0,0 +1,53 @@
+# SDK Context and Evidence Contracts
+
+Tracked by [pm-gok2km](../.agents/pm/issues/pm-gok2km.toon), [pm-zryb9d](../.agents/pm/issues/pm-zryb9d.toon), [pm-qckpnq](../.agents/pm/issues/pm-qckpnq.toon), [pm-hfqju5](../.agents/pm/issues/pm-hfqju5.toon), [pm-2htk4p](../.agents/pm/issues/pm-2htk4p.toon), and [pm-v0a0un](../.agents/pm/issues/pm-v0a0un.toon).
+
+These contracts keep SDK context truthful, bounded, and reusable across the CLI, MCP, packages, and automation. They are designed around the project principle that project management is context management: a compact response must reveal material omissions, merge evidence must describe what actually survived, and compatibility failures must not masquerade as corruption.
+
+## Material omission receipts
+
+`pm get` derives omission receipts from non-serialized materiality evidence. Empty bodies and zero-cardinality collections do not consume receipt tokens merely because a richer projection could render them. Material body, linked-artifact, collection, schedule, child, and claim-state groups retain exact `--fields` restoration guidance.
+
+Package authors can use `registerOutputMaterialFieldGroups(result, groups)` before the shared output boundary attaches a receipt. The registration is held in process memory through a `WeakMap`; it never appears in JSON, TOON, item storage, history, or package output.
+
+## Scoped preflight ownership
+
+An extension contribution inventory can declare `preflight_ownership` command sets. Static activation uses those same sets as runtime dispatch:
+
+- a scoped preflight activates only for an owned command;
+- disjoint scoped preflights do not collide or activate for `pm health` merely because both advertise the `preflight` capability;
+- `preflight_overrides` entries without corresponding ownership remain global.
+
+This keeps health diagnostics and lazy runtime behavior on one ownership contract.
+
+## Merge provenance
+
+Stable-value item merges distinguish a caller request from the outcome. Low-level item results, driver results, clone-local receipts, and privacy-safe summaries expose `requested_preference`. The actual outcome remains in each decision's `retained` and `discarded` values or hashes. New receipts do not emit the ambiguous `preferred` key; readers still ingest legacy schema-v1 receipts and normalize that key to `requested_preference`.
+
+## Claim race classification
+
+Extensions can import `isAlreadyClaimedError` from either supported lifecycle entrypoint:
+
+```ts
+import { isAlreadyClaimedError } from "@unbrained/pm-cli/sdk";
+// or the compact lifecycle surface
+import { isAlreadyClaimedError as isCoreAlreadyClaimedError } from "@unbrained/pm-cli/sdk/core";
+```
+
+The predicate recognizes only the canonical `PmCliError` code `already_claimed_by`; consumers do not need to duplicate an internal string check.
+
+## Versioned history item hashes
+
+New history events carry `item_hash_version: 2`, whose canonicalization preserves linked-test insertion order. The verifier auto-detects unversioned legacy streams against both the legacy sorted-test epoch and the order-preserving epoch. `hashDocumentForVersion` and `verifyHistoryChainWithVersion` expose the same compatibility logic to SDK consumers.
+
+Unknown explicit epochs return `verify_failed:unsupported_item_hash_version:<version>:entry_<n>`. Repair refuses those streams instead of rewriting evidence with a guessed algorithm. Re-anchored supported streams are normalized to the current epoch, and the drift cache records the detected epoch so item-versus-history comparison uses the same canonicalization.
+
+## Assurance mutation refusals
+
+Assurance `put` and `remove` operations validate untrusted declaration shapes at the shared action boundary used by the CLI, SDK, and MCP. Malformed definitions, referenced-declaration removals, and unauthorized assertion weakening return `PmCliError` with the canonical `invalid_argument_value` code and usage exit semantics. Evaluation and storage failures that are not input `TypeError`s remain unexpected and fail closed.
+
+This boundary keeps deterministic operator refusals out of unexpected-error reporting while preserving Sentry and release-gate signal for genuine runtime faults.
+
+## Verification expectations
+
+Changes to these contracts require focused unit coverage, exact repository coverage, packed ESM and TypeScript consumption, and temporary-workspace CLI acceptance. Merge changes additionally require the temporary-Git workflow in [Multi-Branch Merge Safety](MERGE_SAFETY.md).

package/docs/SDK_CONTEXT_INTEGRITY.md

@@ -1,6 +1,6 @@
 # SDK Context Integrity
 
-Tracker: [pm-0k19l7](../.agents/pm/issues/pm-0k19l7.toon), [pm-9stazf](../.agents/pm/issues/pm-9stazf.toon), [pm-tu71](../.agents/pm/issues/pm-tu71.toon), [pm-0xmajx](../.agents/pm/issues/pm-0xmajx.toon), [pm-7rrqsk](../.agents/pm/issues/pm-7rrqsk.toon), [pm-ety1qc](../.agents/pm/issues/pm-ety1qc.toon), and [pm-lu6sca](../.agents/pm/features/pm-lu6sca.toon).
+Tracker: [pm-0k19l7](../.agents/pm/issues/pm-0k19l7.toon), [pm-9stazf](../.agents/pm/issues/pm-9stazf.toon), [pm-tu71](../.agents/pm/issues/pm-tu71.toon), [pm-0xmajx](../.agents/pm/issues/pm-0xmajx.toon), [pm-7rrqsk](../.agents/pm/issues/pm-7rrqsk.toon), [pm-ety1qc](../.agents/pm/issues/pm-ety1qc.toon), [pm-lu6sca](../.agents/pm/features/pm-lu6sca.toon), [pm-5y05kq](../.agents/pm/issues/pm-5y05kq.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), and [pm-h97qxd](../.agents/pm/issues/pm-h97qxd.toon).
 
 ## Agent Quick Context
 
@@ -31,6 +31,28 @@ selector grammar and omission receipts as any other SDK-owned item field.
 
 The same SDK-owned read-output registry now declares `package manage` as a first-class read surface. Package authors can resolve either `package manage` or `package-manage` to its canonical contract and discover the universal include, amount, cost, and encoding dimensions without copying CLI knowledge.
 
+## Row discovery and exact output receipts
+
+Row locations and encoding capabilities remain part of the SDK-owned read
+contract, but the `row_contract` discovery block is opt-in on rendered command
+results. Use `--output-row-contract` in the CLI or `outputRowContract: true` in
+SDK and MCP options when a generic consumer must discover row selectors. Normal
+agent reads omit the repeated metadata and retain the same internal projections.
+
+Uniform flat object arrays use canonical tabular TOON when TOON output is
+selected. Mixed, nested, or scalar collections retain the general recursive
+encoding, so package authors can add richer shapes without pretending they are
+tabular. The optional row contract declares
+`toon_encoding: tabular_when_uniform` for consumers that negotiate this
+optimization.
+
+When discovery metadata is omitted, every `context_intent`, `read_output`, and
+`read_session` estimate is stabilized against the final serialized envelope.
+Consequently `estimated_tokens` and `spent_this_call_tokens` never charge an
+agent for hidden row metadata, and a caller-carried output session remains an
+exact cross-command budget rather than an approximation of an intermediate
+shape.
+
 ## Bounded annotation mutations
 
 Adding, editing, or deleting a comment, note, or learning returns the changed entry plus mutation and omission receipts. The reply size therefore stays independent of the item’s existing annotation history. Pass `--full-history` when a human or integration genuinely needs the complete post-mutation collection:
@@ -68,6 +90,11 @@ reader. Validation uses collection-bearing metadata for evidence and
 relationship checks and materializes bodies only when strict history-drift
 verification is requested.
 
+Every health check row exposes both its tri-state `status` and a required
+boolean `ok`. The boolean is exactly `status === "ok"` in full, brief, and
+summary projections, so generic SDK and package consumers can use a stable
+success predicate without discarding warning-versus-error detail.
+
 The storage check also reads at most 10,000 local immutable events for bounded
 agent-provenance resolver outcomes. This scan performs no network or provider
 I/O, tolerates malformed streams already owned by integrity diagnostics, and

package/docs/TRUSTWORTHY_CONTEXT_EVIDENCE.md

@@ -0,0 +1,106 @@
+# Trustworthy Context and Evidence Contracts
+
+Tracker: [pm-py7qv2](../.agents/pm/issues/pm-py7qv2.toon), [pm-33mjrw](../.agents/pm/issues/pm-33mjrw.toon), [pm-q6n8sj](../.agents/pm/issues/pm-q6n8sj.toon), [pm-h97qxd](../.agents/pm/issues/pm-h97qxd.toon), [pm-rncuf7](../.agents/pm/issues/pm-rncuf7.toon), [pm-m0b7h8](../.agents/pm/issues/pm-m0b7h8.toon), [pm-wqhzhg](../.agents/pm/issues/pm-wqhzhg.toon)
+
+## Agent Quick Context
+
+Project management is context management. These contracts make absence, identity, composition, and mutation outcomes explicit across CLI, SDK, MCP, packages, and persisted history:
+
+- Assurance evaluates authoritative full item records, supports first-class field presence predicates, canonicalizes relationship aliases, fingerprints measurement definitions, and attributes writes through the normal detected-author chain.
+- Graph audit reports both counts and ratios: `edge_share_by_kind`, `semantic_edges`, and `semantic_edge_share` alongside the existing structural profile.
+- Every health check row carries `ok: boolean` beside its compatible `status: ok|warn` value, including brief, summary, skipped, and full projections.
+- Linked-test removal preserves commands containing commas or equals signs, offers a lossless 1-based index selector, reports `removed`, and refuses a zero-match removal.
+- Collection grammar recovery labels positional roles when noun-verb-object input is transposed, then provides the accepted object-first command.
+
+Use runtime contracts for the exact active surface:
+
+```bash
+pm contracts --command test --flags-only --json
+pm contracts --action test --schema-only --json
+pm health --summary --json
+pm graph audit --summary --json
+```
+
+## Assurance Predicates and Verdict Identity
+
+An item-field measurement must choose exactly one predicate:
+
+```json
+{
+  "id": "missing-tests",
+  "source": { "kind": "items", "field": "tests", "state": "missing" }
+}
+```
+
+```json
+{
+  "id": "priority-one",
+  "source": { "kind": "items", "field": "priority", "equals": 1 }
+}
+```
+
+`state: missing` covers absent properties, `null`, empty strings, and empty arrays. `state: present` is its complement. Explicit `equals: null` remains an exact-value predicate and is not conflated with missing configuration.
+
+Each measurement result carries `definition_fingerprint`; assertion verdicts copy it as `measurement_definition_fingerprint`. A stored verdict can therefore be joined to the exact declaration semantics that produced it. Older verdicts remain readable and are visibly legacy because the fingerprint field is absent.
+
+## Graph Composition
+
+`pm graph audit` uses deduplicated directed edges as the denominator:
+
+```json
+{
+  "edges": 12,
+  "edges_by_kind": { "parent": 4, "related": 6, "verifies": 2 },
+  "edge_share_by_kind": {
+    "parent": 0.3333333333333333,
+    "related": 0.5,
+    "verifies": 0.16666666666666666
+  },
+  "semantic_edges": 2,
+  "semantic_edge_share": 0.16666666666666666
+}
+```
+
+The semantic numerator is the sum of `discovered_from`, `incident_from`, `supersedes`, and `verifies`. Audit baselines preserve the new fields, accept older snapshots with explicit zero defaults, and report signed count/share deltas.
+
+## Health Row Predicate
+
+Every entry in `health.checks` has this stable shape:
+
+```json
+{ "name": "storage", "status": "ok", "ok": true, "details": {} }
+```
+
+`status` remains for compatibility and human rendering. `ok` is the direct machine predicate; it survives brief and summary projections. Assurance health sources accept either `field: status` or `field: ok` and normalize success to `0`, warning to `1`.
+
+## Lossless Linked-Test Removal
+
+List first when selecting an index:
+
+```bash
+pm test pm-example --list --json
+pm test pm-example --remove-index 2 --json
+```
+
+`--remove-index` is repeatable and uses the current 1-based list order. Exact identity selectors remain available:
+
+```bash
+pm test pm-example --remove "command=node -e 'console.log(\"left=right,still-command\")'" --json
+pm test pm-example --remove 'path=tests/example.spec.ts' --json
+```
+
+For `command=` and `path=`, everything after the first identity prefix is the value; commas and equals signs are not re-parsed as fields. A successful mutation reports `removed`; a selector matching nothing raises `linked_test_remove_no_match` with unmatched selectors and a list-first recovery instead of returning a false-success no-op.
+
+## Collection Grammar Recovery
+
+Collection mutations use object-first grammar:
+
+```bash
+pm notes pm-example --add "context"
+pm comments pm-example --add "reviewed"
+pm files pm-example --add path=src/example.ts
+pm docs pm-example --add path=docs/example.md
+pm test pm-example --add 'command=pnpm test'
+```
+
+Inputs such as `pm notes add pm-example --note context` are refused as a transposed `add` subcommand. Structured recovery reports `transposed_subcommand=add` and `item_id=pm-example`, then supplies `pm notes pm-example --add context`. The visible notes `--note` alias remains accepted for compatibility, but new automation should use canonical `--add`.

package/docs/performance/sdk-entrypoint-import-costs.md

@@ -1,13 +1,17 @@
 # SDK entrypoint import costs
 
-Tracked by [pm-38bskj](../../.agents/pm/tasks/pm-38bskj.toon).
+Tracked by [pm-38bskj](../../.agents/pm/tasks/pm-38bskj.toon) and
+[pm-cg1sjb](../../.agents/pm/issues/pm-cg1sjb.toon).
 
 This table measures fresh-process ESM import and module evaluation. The bare
 Node v26.5.0 process floor on linux/x64
 was 41 ms p50 (48 ms p95) across
 5 measured runs after one warm-up. Focused entrypoints are
 compared with the compatibility aggregate; negative reduction means the focused
-entrypoint was slower in this sample.
+entrypoint was slower in this sample. The gate admits the median measured run
+against the unchanged upper-bound budget and 30 ms scheduler margin. A single
+cold or descheduled process therefore cannot fail the gate, while a majority of
+over-budget samples still does; p95 remains visible as diagnostic evidence.
 
 | Package export | p50 | p95 | p50 above Node | Reduction vs aggregate |
 |---|---:|---:|---:|---:|

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.8.11",
+  "version": "2026.8.12",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -120,7 +120,7 @@
     "lint:complexity:baseline": "eslint . --suppress-rule complexity --suppress-rule sonarjs/cognitive-complexity",
     "lint:duplicates": "jscpd --config .jscpd.json",
     "lint:codefactor": "pnpm quality:static",
-    "quality:static": "pnpm build && pnpm exec tsx scripts/release/static-quality-gate.mts --max-eslint-suppressions 114 --max-coverage-ignore-pragmas 477 --min-docstring-coverage 100 --min-exported-docstring-coverage 100 --min-member-docstring-coverage 100 && node scripts/release/audit-package-boundary.mjs && node scripts/release/package-sdk-contract-parity.mjs && node scripts/release/surface-replication-gate.mjs && node scripts/release/absence-tolerance-gate.mjs && node scripts/release/token-budget-gate.mjs && node scripts/release/context-intent-calibration-gate.mjs && node scripts/release/tracker-measurement-gate.mjs && node scripts/release/gate-registry.mjs && node scripts/sdk-surface-snapshot.mjs --check && node scripts/bench/sdk-entrypoint-costs.mjs --check && node scripts/bench/cli-transport-floor.mjs --check",
+    "quality:static": "pnpm build && pnpm exec tsx scripts/release/static-quality-gate.mts --max-eslint-suppressions 114 --max-coverage-ignore-pragmas 477 --min-docstring-coverage 100 --min-exported-docstring-coverage 100 --min-member-docstring-coverage 100 && node scripts/release/audit-package-boundary.mjs && node scripts/release/package-sdk-contract-parity.mjs && node scripts/release/surface-replication-gate.mjs && node scripts/release/absence-tolerance-gate.mjs && node scripts/release/token-budget-gate.mjs && node scripts/release/context-intent-calibration-gate.mjs && node scripts/release/tracker-measurement-gate.mjs && node scripts/release/gate-registry.mjs && node scripts/sdk-surface-snapshot.mjs --check && node scripts/bench/sdk-entrypoint-costs.mjs --check && node scripts/bench/cli-transport-floor.mjs --check && node dist/cli.js assurance run graph-composition --trigger ci --dry-run --json && node dist/cli.js assurance run record-integrity --trigger ci --dry-run --json",
     "quality:token-budget": "node scripts/release/token-budget-gate.mjs",
     "quality:token-surface": "node scripts/measure-agent-token-surface.mjs --check",
     "quality:token-surface:update": "pnpm build && node scripts/measure-agent-token-surface.mjs --update",
@@ -198,7 +198,7 @@
     "node": ">=22.18.0"
   },
   "dependencies": {
-    "@sentry/node": "10.69.0",
+    "@sentry/node": "10.70.0",
     "@toon-format/toon": "^4.1.1",
     "@types/node": ">=22",
     "commander": "^15.0.0",
@@ -214,14 +214,14 @@
     "@types/node": "^26.2.0",
     "@types/npm-package-arg": "^6.1.4",
     "@vitest/coverage-v8": "^4.1.10",
-    "esbuild": "0.28.1",
+    "esbuild": "0.28.2",
     "eslint": "^10.8.1",
     "eslint-plugin-sonarjs": "^4.2.0",
     "eslint-plugin-unicorn": "^73.0.0",
     "fast-check": "^4.9.0",
     "greptile": "^3.3.1",
     "jscpd": "^5.0.14",
-    "tsx": "^4.23.11",
+    "tsx": "^4.23.12",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.66.0",
     "vitest": "^4.1.10",

package/packages/pm-beads/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-beads",
-  "version": "2026.8.11",
+  "version": "2026.8.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.8.11",
+  "version": "2026.8.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.8.11",
+  "version": "2026.8.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.8.11",
+  "version": "2026.8.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/package.json

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

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

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

package/packages/pm-kanban/package.json

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

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

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

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

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

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

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

package/packages/pm-templates/package.json

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

package/packages/pm-todos/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-todos",
-  "version": "2026.8.11",
+  "version": "2026.8.12",
   "private": true,
   "type": "module",
   "description": "First-party pm package for Todo markdown import and export.",

package/packages/pm-vcs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-vcs-sdk-exemplar",
-  "version": "2026.8.11",
+  "version": "2026.8.12",
   "private": true,
   "type": "module",
   "description": "Beyond-PM exemplar: a VCS-style changeset workflow built entirely on public pm SDK and extension primitives.",

package/plugins/pm-claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pm-claude",
   "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents (coordinator, delivery-chain, triage, verification), hybrid TUI task tracking (pm as persistent store + Claude Code task panel as live view), session context injection, and full git-based project management without leaving Claude Code.",
-  "version": "2026.8.11",
+  "version": "2026.8.12",
   "author": {
     "name": "unbrained",
     "url": "https://github.com/unbraind/pm-cli"