@unbrained/pm-cli 2026.8.11 → 2026.8.13

package/docs/RELATIONSHIP_GRAPH.md

@@ -257,6 +257,21 @@ bounded deterministic samples, truncation, policy text, and safe remediation;
 the audit never invents an edge. Explicit isolate exemptions suppress policy
 findings without changing structural coverage metrics.
 
+The audit profile also exposes graph-wide resilience and delivery-lineage
+metrics. `articulation_points` and `bridge_edges` reuse the exact cut-structure
+algorithm; outcome metrics count explicit `Milestone` titles beginning with
+`Outcome milestone:` and follow only hierarchy or `implements` edges toward
+them. Active and terminal populations are reported separately, with integer
+basis-point rates and all-status reachable/unreachable totals; the explicit
+outcome milestones are roots, not work subjects, and are excluded from those
+populations. Rate or
+all-status floors are lifecycle-stable; an absolute active-population floor is
+invalid because completing reachable work legitimately moves it into the
+terminal population. `finding_subjects_by_code` includes every known finding
+code even when its population is zero, so assurance selectors never confuse a
+clean class with a missing contract field. Generic `related` edges cannot
+satisfy outcome reachability.
+
 ```ts
 import {
   assembleWorkspaceRelationshipGraph,

package/docs/SDK.md

@@ -297,7 +297,7 @@ Command/action contract exports:
 - Remediation planning: `planRelationshipRemediation` (with `RelationshipRemediationPlan`, `RelationshipRemediationStep`, and operation/confidence/code contracts) derives exact dry-run `remove`/`retype`/`supersede`/`waive`/`investigate` proposals from governance-audit findings and witnessed redundancy rows — evidence-backed, confidence-rated, and never auto-applied.
 - Annotation and relationship option/result contracts: `CommentsCommandOptions` / `CommentsResult`, `NotesCommandOptions` / `NotesResult`, `LearningsCommandOptions` / `LearningsResult`, `FilesCommandOptions` / `FilesResult`, `FilesDiscoverOptions` / `FilesDiscoverResult`, `DocsCommandOptions` / `DocsResult`, `DepsCommandOptions` / `DepsResult`, `AppendCommandOptions` / `AppendResult`
 - Annotation kernel primitives: `resolveAnnotationInput`, `runAnnotationCommand`, `resolveAnnotationIndex`, `parseAnnotationTextInput`, `limitAnnotationEntries`, `readAnnotationEntries`, `wrapOwnershipConflict`, `isErrnoError`, and their typed input/config/result contracts
-- Linked-resource kernel primitives: `runFiles`, `runFilesDiscover`, `runDocs`, `runDeps`, `runLinkedArtifacts`, parsing/normalization/path-validation helpers, and their typed contracts. The CLI files/docs/deps modules are presentation-only re-exports of these SDK implementations.
+- Linked-resource kernel primitives: `runFiles`, `runFilesDiscover`, `runDocs`, `runDeps`, `runLinkedArtifacts`, `assertLinkedArtifactMutationIsUnambiguous`, parsing/normalization/path-validation helpers, and their typed contracts. The CLI files/docs/deps modules are presentation-only re-exports of these SDK implementations. A transaction that resolves one path into both its add and remove sets fails before item or history mutation; split an intentional replacement into two commands so its context remains explicit.
 - Actionability primitives: `collectBlockedByIds`, `resolveItemBlockers`, `collectDependencyBlockedIds`, and `computeActionabilityReport` expose the same edge-aware blocked/ready definition used by `pm next`, `pm context`, and `pm list-blocked`. Embedded schedulers can therefore classify custom lifecycle schemas without importing CLI or core modules.
 - Dependency-governance primitives: `collectDanglingDependencyReferences`, `collectMissingDependencyTargetIds`, and `assembleWorkspaceRelationshipGraph` normalize hierarchy, scalar blockers, and structured dependencies into one graph while partitioning missing targets into actionable active holders, informational terminal-history holders, and the legacy `no-active-blocker` sentinel without mutating stored history.
 - Relationship graph primitives: `RelationshipKindRegistry`, `createRelationshipKindRegistry`, `assertRelationshipEdgeAllowed`, `RelationshipGraph`, `RelationshipEventLog`, `RelationshipEventStore`, `planRelationshipEventBackfill`, `buildRelationshipContext`, `buildDepsRelationshipContext`, `hierarchyAncestors`, `hierarchyDescendants`, `orderingPredecessors`, `orderingSuccessors`, `enumerateRelationshipPaths`, `auditWorkspaceRelationshipGraph`, `isOrderingRelationshipKind`, and `dependencyToRelationship` provide application-defined edge semantics, durable replay, deterministic legacy migration, bounded semantic traversal, policy-aware governance, and explainable context queries. Mutation adapters should call `assertRelationshipEdgeAllowed` with the active registry before persistence; it resolves aliases and honors custom `allowSelf` definitions while built-in self edges fail before item or history writes. `RelationshipEventLog.stream/project` and their durable-store equivalents page immutable prefixes and fold them into deterministic application state with exact version, processed-count, and as-of metadata. `RelationshipEventStore.appendBatch` validates a complete import under one cross-process lock and atomically publishes it; `skip_identical` resume mode rejects same-id semantic collisions. `RelationshipGraphAdapter`, `createRelationshipGraphSnapshot`, `syncRelationshipGraphAdapter`, `loadRelationshipGraphAdapter`, and `federateRelationshipGraphSnapshots` form the backend-neutral content-addressed projection boundary for database or remote graph packages. `MemoryRelationshipGraphAdapter`, `assertRelationshipGraphAdapterConformance`, and `createRelationshipGraphScaleFixture` give package authors a reference implementation, reusable compatibility contract, and lazy deterministic fixtures through one million nodes. See [Relationship graph semantics](RELATIONSHIP_GRAPH.md).
@@ -317,7 +317,7 @@ Command/action contract exports:
 - Execution and diagnostics engines: `runTest`, `runLinkedTests`, `runTestAll`, `runStartBackgroundRun`, `runTestRunsList`, `runTestRunsStatus`, `runTestRunsLogs`, `runTestRunsStop`, `runTestRunsResume`, `runTestRunsWorker`, `runEval`, `runTelemetry`, and `runStats`. Their CLI modules are compatibility re-exports of SDK-owned implementations.
 - Execution and diagnostics contracts: `TestCommandOptions` / `TestResult` / `TestRunResult`, `TestAllCommandOptions` / `TestAllResult`, `StartBackgroundRunCommandOptions` / `StartBackgroundRunResult`, `TestRuns*CommandOptions`, `EvalOptions` / `EvalResult`, `TelemetryCommandOptions` / `TelemetrySubcommand`, and `StatsCommandOptions` / `StatsResult`.
 - Linked-test authoring primitives: `parseLinkedTestJsonEntries`, the `parseLinkedTest*` field parsers, `LINKED_TEST_PM_CONTEXT_MODE_VALUES`, `LINKED_TEST_PROTECTED_ENV_KEYS`, `classifyLinkedTestFailure`, `countFailureCategories`, and `summarizeContextPreflight` let custom hosts validate, execute, classify, and report linked tests without duplicating CLI policy.
-- Agent command primitives: `normalizeItemAddressInvocation` and `supportsItemIdAlias` project one item-id grammar across CLI adapters; `renderMissingOptionRetry` and `resolveMissingOptionPlaceholder` preserve attempted argv while deriving enum, boolean, and scalar recovery arity from flag contracts; `createUnknownSubcommandError` provides one typed positional refusal with complete allowed values and deterministic nearest retry; `rankCommandPaths` and `scoreCommandPathMatch` provide deterministic synonym/edit-distance/substring ranking; `resolveCreateExplicitEmptyFlag` and `supportsCreateExplicitEmpty` model a considered-but-empty strict repeatable input without inventing metadata or graph edges.
+- Agent command primitives: `normalizeItemAddressInvocation` and `supportsItemIdAlias` project one item-id grammar across CLI adapters; `renderMissingOptionRetry`, `resolveMissingOptionPlaceholder`, and `resolveRecoveryCommandName` preserve attempted argv, derive enum/boolean/scalar recovery arity from flag contracts, and identify the actual command without mistaking a global option value for one; `createUnknownSubcommandError` provides one typed positional refusal with complete allowed values and deterministic nearest retry; `rankCommandPaths` and `scoreCommandPathMatch` provide deterministic synonym/edit-distance/substring ranking; `resolveCreateExplicitEmptyFlag` and `supportsCreateExplicitEmpty` model a considered-but-empty strict repeatable input without inventing metadata or graph edges.
 - Refusal reachability primitives: generated `PmErrorCodeContract.owned_states` declarations bind stable codes to concrete states, probe ids, entrypoints, and exit classes; `verifyPmRefusalReachability` compares those declarations with real CLI, SDK, MCP, or package observations and fails closed for missing, duplicate, wrong-entrypoint, mismatched, or undeclared probes.
 - Typed plan workflow primitives on `PmClient`: `plan`, `planCreate`, `planShow`, `planAddStep`, `planUpdateStep`, `planCompleteStep`, `planBlockStep`, `planReorderStep`, `planRemoveStep`, `planLink`, `planUnlink`, `planDecision`, `planDiscovery`, `planValidation`, `planResume`, `planApprove`, and `planMaterialize`
 - Plan contracts: `PlanSubcommand`, `PlanCommandOptions`, `PlanCommandResult`, `PlanResultPlan`, `PlanStepSummary`, `PlanShowDepth`, and `PlanTemplateName`
@@ -512,7 +512,8 @@ loud with attributed events and authors.
 Tracked: [pm-jcvg](../.agents/pm/tasks/pm-jcvg.toon),
 [pm-2ler](../.agents/pm/issues/pm-2ler.toon),
 [pm-chyh](../.agents/pm/issues/pm-chyh.toon), and
-[pm-p9sc](../.agents/pm/issues/pm-p9sc.toon).
+[pm-p9sc](../.agents/pm/issues/pm-p9sc.toon). Conflicting batch refusal is
+tracked by [pm-c6urop](../.agents/pm/issues/pm-c6urop.toon).
 
 Custom tools can use the same domain primitives as the CLI without dispatching a
 command action. The direct functions accept the typed command options plus a
@@ -556,6 +557,13 @@ tool invoked from a nested package never records a path that changes meaning
 when another agent runs from the repository root. Root-layout trackers use the
 tracker directory itself as their workspace.
 
+Add and remove sets are compared after invocation-root anchoring, slash
+normalization, glob expansion, and requested migrations. If the same path is in
+both sets, `runFiles`, `runDocs`, and `runLinkedArtifacts` throw
+`PmCliError` code `linked_artifact_mutation_conflict` before calling the item
+store. This contract deliberately refuses to guess whether replacement or
+removal should win and guarantees that no item or history write is published.
+
 `runDeps` also projects missing `parent` and legacy `blocked_by` references as
 typed missing edges, alongside structured dependencies. Tree and graph payloads
 apply shared depth/node/edge/token bounds and expose deterministic truncation
@@ -3292,6 +3300,12 @@ interpreted as a missing input. Strict close validation reports missing
 resolution fields first and suggests a targeted `pm update` before retrying the
 original close invocation.
 
+Recovery help examples resolve their command through
+`resolveRecoveryCommandName`, which uses the same bootstrap grammar as the CLI.
+Global value flags such as `--pm-path <path>` may appear before or after the
+subcommand; their values are never exposed as inferred command names or help
+targets.
+
 Unknown-option envelopes rank command paths that accept the rejected flag by
 shared vocabulary and include explicit total/truncation metadata. They are
 contract-discovery hints, not permission to change the requested operation.

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

@@ -270,28 +270,37 @@ parsed `workflow_jobs`; validation requires the two sets to match exactly.
 
 ## Tracker Context-Quality Ratchets
 
-Tracked by [pm-ips23h](../.agents/pm/issues/pm-ips23h.toon) and
-[pm-kpftft](../.agents/pm/tasks/pm-kpftft.toon).
-
-`scripts/release/tracker-measurements.json` turns measured tracker populations
-into reviewed, shrinking-only ceilings. Each declaration names its canonical
-pm owner and a selector over stored dependency kinds, validator warnings,
-graph-profile fields, or health-check severity. Open owners enforce their
-ceiling; terminal owners retire it. Validator warnings and health checks are
-exhaustive, so a newly observed class fails until it has a canonical owner and
-reviewed declaration.
+Tracked by [pm-ips23h](../.agents/pm/issues/pm-ips23h.toon),
+[pm-kpftft](../.agents/pm/tasks/pm-kpftft.toon), and
+[pm-4ok4ex](../.agents/pm/tasks/pm-4ok4ex.toon), with lifecycle-stable outcome
+reachability owned by [pm-g4k74y](../.agents/pm/issues/pm-g4k74y.toon) and
+[pm-bzmeaa](../.agents/pm/tasks/pm-bzmeaa.toon).
+
+The SDK-owned assurance registry stores tracker context-quality measurements,
+floors, ceilings, lifetimes, enforcement, and executable negative controls in
+`.agents/pm/assurance.json`. The `tracker-context-quality` gate covers stored
+relationship kinds, validator debt, health checks, graph findings, structural
+cut points, and typed reachability to outcome milestones. One workspace
+assurance context reuses identical graph, validate, and health evaluations, so
+a broad gate has one authoritative snapshot without repeatedly rescanning it.
+Outcome enforcement uses an all-status reachable population, unreachable
+ceiling, and basis-point floor. Active and terminal populations remain
+diagnostics: absolute per-lifecycle floors would mistake normal close or reopen
+transitions for relationship loss.
 
 Run the same gate used by hosted CI:
 
 ```bash
 pnpm quality:tracker-measurements
-node scripts/release/tracker-measurement-gate.mjs --negative-control
+pm assurance run tracker-context-quality --trigger ci --dry-run --json
 ```
 
-`--update` can only lower a ceiling. It refuses to write while any population
-has regressed or remains undeclared, so updating the baseline cannot absorb a
-failure. Dependency-kind regressions include the post-measurement item, target,
-author, timestamp, and mutation-source rows in the JSON receipt.
+Every native assertion contains both a passing boundary case and an impossible
+case that must fail. Changes flow through `pm assurance put`, which refuses a
+weaker bound, scope, lifetime, or enforcement unless a verified Decision item
+authorizes it. `scripts/release/gate-registry.json` separately inventories the
+retired bespoke gate and gives every graph subcommand either a named automated
+consumer or an explicit interactive-only classification.
 
 ## Agent Output Token Budgets
 

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.13"
   },
   "plugins": [
     {
       "name": "pm-claude",
       "source": "./plugins/pm-claude",
       "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
-      "version": "2026.8.11",
+      "version": "2026.8.13",
       "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.13",
   "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 dist/cli.js assurance run tracker-context-quality --trigger ci --dry-run --json && 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",
@@ -130,7 +130,7 @@
     "quality:retrieval-eval": "pnpm build && node scripts/release/retrieval-eval-gate.mjs",
     "quality:retrieval-eval:update": "pnpm build && node scripts/release/retrieval-eval-gate.mjs --update",
     "quality:gate-registry": "pnpm build && node scripts/release/gate-registry.mjs",
-    "quality:tracker-measurements": "pnpm build && node scripts/release/tracker-measurement-gate.mjs",
+    "quality:tracker-measurements": "pnpm build && node dist/cli.js assurance run tracker-context-quality --trigger ci --dry-run --json",
     "quality:package-artifact": "pnpm build && node scripts/release/package-artifact-gate.mjs",
     "quality:surface-replication": "node scripts/release/surface-replication-gate.mjs",
     "quality:absence-tolerance": "node scripts/release/absence-tolerance-gate.mjs",
@@ -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.13",
   "private": true,
   "type": "module",
   "description": "First-party pm package for importing Beads JSONL records.",

package/packages/pm-calendar/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-calendar",
-  "version": "2026.8.11",
+  "version": "2026.8.13",
   "private": true,
   "type": "module",
   "description": "First-party pm package for calendar and agenda views.",

package/packages/pm-command-kit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-command-kit",
-  "version": "2026.8.11",
+  "version": "2026.8.13",
   "private": true,
   "type": "module",
   "description": "First-party pm exemplar package for the commands capability: registerCommand, registerFlags, and registerParser.",

package/packages/pm-digital-twin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-digital-twin",
-  "version": "2026.8.11",
+  "version": "2026.8.13",
   "private": true,
   "type": "module",
   "description": "Beyond-PM exemplar: a temporal production-facility digital twin built entirely on public pm SDK and extension primitives.",

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

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-governance-audit",
-  "version": "2026.8.11",
+  "version": "2026.8.13",
   "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.13",
   "private": true,
   "type": "module",
   "description": "First-party pm package for guide and shell completion workflows.",

package/packages/pm-kanban/package.json

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

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

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

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

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

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

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

package/packages/pm-templates/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-templates",
-  "version": "2026.8.11",
+  "version": "2026.8.13",
   "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.13",
   "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.13",
   "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.13",
   "author": {
     "name": "unbrained",
     "url": "https://github.com/unbraind/pm-cli"

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

@@ -1,6 +1,6 @@
 {
   "name": "pm-codex",
-  "version": "2026.8.11",
+  "version": "2026.8.13",
   "description": "Native Codex integration for pm-cli with bundled MCP tools, skills, commands, and agent workflows.",
   "author": {
     "name": "unbrained",