@unbrained/pm-cli 2026.8.10 → 2026.8.12

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

@@ -53,7 +53,10 @@ pm guide release --json
 - [Agent Provenance ADR Amendment](AGENT_PROVENANCE_ADR.md) - extensible model, effort, role, and host provenance with privacy and compatibility boundaries.
 - [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/RELEASING.md

@@ -106,7 +106,7 @@ The pipeline performs:
 1. change detection + one-release-per-day guard
 2. a single `YYYY.M.D` version bump; ordinal targets and the removed
    `--allow-same-day-release` override fail closed
-3. latest `pm-changelog` install and main changelog refresh through package-owned full-history generation; the release pipeline passes `--release-version` with `--all-release-tags` so the pending release section matches post-tag CI checks
+3. latest `pm-changelog` install and main changelog refresh through package-owned full-history generation; the release pipeline passes `--release-version`, `--all-release-tags`, and the canonical `--exclude-tag changelog-exclude` policy so the pending release section matches post-tag CI checks
 4. build, clone-local merge-driver installation, then the remaining strict gates (typecheck, docs/skills freshness, coverage, static quality, compatibility, security, smoke checks, reliability gate); this ordering makes the checkout-owned CLI available before bootstrap, matches CI, and prevents fresh-clone tracker measurements from observing undeclared merge-driver repairs
 5. release note generation from changelog + pm evidence
 6. commit and tag creation (plus optional push)
@@ -265,7 +265,10 @@ git push origin v<version>
 - build, clone-local merge-driver installation, typecheck, test, and coverage
 - generated changelog verification and `pm-changelog` installation before the
   tracker-bearing static gate, so a clean checkout does not misclassify the
-  managed extension's linked files as missing
+  managed extension's linked files as missing. Recovery of an unpublished
+  immutable tag regenerates only `CHANGELOG.md` with the tagged checkout's
+  canonical package script and fails if that operation changes any other
+  tracked source path (apart from managed-extension install metadata).
 - static quality gate (shared complexity, duplication, dead/orphan module, file/folder hygiene, source/exported docstring coverage profile)
 - temporary-project compatibility gate against latest published tracker data
 - reliability threshold gate (Sentry severity threshold, bounded to a recent-activity window via `--sentry-window-days` (default `14`, `0` = unbounded) so a stale benign unresolved issue cannot block every scheduled release; `--telemetry-mode` gate policy: `off` | `best-effort` | `required`). Scheduled `auto-release.yml` failures open/update an `Auto Release blocked` GitHub issue so blocked daily releases are never silently skipped.
@@ -350,9 +353,10 @@ Use the npm registry package for maintainer global updates. Do not use `npm inst
   existing version keeps the reviewed dispatch-time `main` source and cannot
   be republished. A definitive missing-version response pins the checkout to
   the existing immutable tag, reapplies the version guard, installs the managed
-  changelog extension before tracker measurement, and permits first publication
-  only from that exact tagged source. Other registry failures stop before
-  source selection or publication.
+  changelog extension, regenerates the package changelog with the tagged
+  checkout's canonical policy under a tracked-path mutation guard, and permits
+  first publication only from that tagged source. Other registry failures stop
+  before source selection or publication.
 - If an immutable published package contains a defect that cannot be repaired
   by rerunning the same tag workflow, document the incident and ship the code
   fix in the next UTC day's release.

package/docs/SDK.md

@@ -317,7 +317,8 @@ 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; `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` 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.
+- 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`
 - Typed package and extension lifecycle primitives on `PmClient`: `extension`, `extensionList`, `extensionActivate`, `extensionDeactivate`, `package`, `packageList`, `packageInstall`, `packageUninstall`, `packageDoctor`, `packageManage`, `packageDescribe`, `packageReload`, `packageCatalog`, `packageActivate`, `packageDeactivate`, `packageMigrate`, and `upgrade`; one-shot `extensionMigrate` and `packageMigrate` helpers mirror those lifecycle actions.
@@ -3274,6 +3275,10 @@ For SDK and automation consumers, the key runtime change is the optional `recove
 - `normalized_args`
 - `provided_fields`
 - `missing`
+- `allowed_values`
+- `candidate_commands`
+- `candidate_commands_total`
+- `candidate_commands_truncated`
 - `suggested_retry`
 
 Treat `recovery.suggested_retry` as the first-choice deterministic replay
@@ -3287,6 +3292,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.
 
+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.
+Unknown positional subcommands expose the complete `allowed_values` vocabulary
+and use `suggested_retry` only when a deterministic nearby value exists.
+
 ## Authoring Pattern
 
 - Keep handlers deterministic and JSON-like.

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
@@ -85,10 +86,38 @@ values are ignored instead of polluting analytics. Presence-only harness flags,
 including `CLAUDE_CODE_CHILD_SESSION=1`, are detection evidence and are never
 persisted as semantic roles.
 
-For ordinary CLI mutations, the detector can infer an `implementer` or
-`reviewer` role from the bounded command verb and a topic from an explicit
-`pm-...` item argument. Explicit overrides, session declarations, and trusted
-host declarations retain precedence over this inference.
+## Infer semantic context from lifecycle state
+
+Successful `claim`, `release`, and `focus` operations maintain a bounded,
+checkout-local semantic workset. Later CLI and SDK mutations can therefore
+record useful role and topic provenance without repeating identity flags or
+retaining prompt text:
+
+- a claim records the item and at most 16 canonical parent ancestors, infers
+  `role=implementer`, and uses the item or stable multi-item workset as topic;
+- an explicit focus becomes the high-confidence topic and infers
+  `role=planner`;
+- a release removes only that claim and records `role=release-operator` while
+  other active claims remain; and
+- clearing the final claim and focus removes the inferred session record.
+
+At most 64 active item ids and 32 evidence rows are retained. Multi-item topics
+are deterministically bounded and hashed when their full identity would exceed
+the provenance limit. The state is partitioned by the privacy-safe agent
+instance when available, otherwise by a truncated hash of the resolved author.
+It lives in the gitignored runtime session file and malformed records fail open.
+
+The same workset feeds `pm context` as `claim_focus` relevance: claimed and
+focused items receive affinity `1`, while bounded canonical ancestors receive
+`0.75`. Active work is preserved by the context packer under its existing token
+ceiling; the inference never raises the requested budget.
+
+Explicit overrides, declared session context, command flags, environment,
+MCP-client declarations, host declarations, and configured probes all retain
+precedence. Automatic observations use `source=inferred`, `rule_version=v2`,
+and carry the bounded claim/focus/lineage evidence that supports them. The pure
+`semanticAttributionAffinity()` helper and lifecycle recording primitives are
+public SDK exports for custom hosts.
 
 ## Diagnose missing provenance
 
@@ -109,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
@@ -145,6 +184,11 @@ declared a dimension but supplied no value. The compatibility helper
 `summarizeAgentModelProvenance(entries)` remains available for model-only
 consumers.
 
+`evaluateSemanticAttributionCoverage(entries, options)` groups role/topic
+availability by harness and precedence source. Its explicit minimum-entry and
+minimum-coverage ratchet fails empty corpora, making a negative control part of
+the contract instead of allowing an unobserved harness to pass vacuously.
+
 `groupHistoryByEpisode(entries)` returns deterministic nested groups:
 
 - recorded episode keys produce `source: "declared"`;
@@ -166,3 +210,6 @@ channel. Do not put tokens, private hostnames, signed URLs, or raw external
 payloads in ids, labels, roles, or topics. Session ids used to derive
 `agent_instance` remain transient and are not persisted. Every new history
 field is optional, so existing streams and packages remain readable.
+Automatic semantic attribution is likewise restricted to item ids, controlled
+roles, rule metadata, and canonical lineage ids. It never persists argv,
+environment values, prompts, filesystem contents, or raw harness session ids.

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

@@ -12,6 +12,8 @@ Use `pm files lookup` with one or more project-relative or absolute paths:
 pm files lookup src/sdk/files.ts
 pm files lookup src/sdk/files.ts docs/SDK_EVIDENCE_TRACEABILITY.md --limit 20
 pm files lookup /absolute/project/src/sdk/files.ts --scope project --strict-read --json
+pm files lookup src/sdk/files.ts --explain
+pm files lookup src/sdk/files.ts --lines 650:720 --decision-depth 12 --json
 ```
 
 The command normalizes in-project absolute paths to project-relative paths, deduplicates targets, and returns referencing items in deterministic priority, update-time, and ID order. The default result limit is 50. Use `--offset` for bounded pagination or `--no-truncate` for an authoritative unbounded source scan.
@@ -26,6 +28,34 @@ Every response includes:
 
 `--strict-read` fails instead of returning partial source-scan results. Indexed reads are intentionally reported as `unchecked`: they are cursor-bound projections optimized for bounded context retrieval, while strict reads force authoritative item loading.
 
+## Explain why source exists
+
+`--explain` upgrades reverse lookup from an ownership list to a bounded context
+projection. Every match adds:
+
+- its linked-file evidence and compact `value`, `why_now`, `outcome`, and
+  `objective` rationale;
+- the shortest typed relationship path to a governing Decision, including
+  inverse edge names when traversal crosses an edge backwards;
+- a deterministic relevance score used before normal priority, update-time,
+  and id tie-breakers; and
+- explicit ambiguity codes when Git attribution is unavailable, selected lines
+  have no mapped commit, no governing Decision is reachable, or several
+  equally short Decisions exist.
+
+`--lines start:end` is an inclusive, one-based selector that implies
+`--explain` and accepts exactly one path. It runs bounded `git blame` and a
+256-commit path log. A blamed commit contributes only when its commit message
+contains the exact pm item id, so Git history supplements linked tracker
+evidence without inventing lineage. Git failures are non-fatal and appear as
+ambiguity rather than silently claiming attribution. `--decision-depth` is
+bounded from 1 through 32 and defaults to 8.
+
+The top-level `traceability_receipt` reports the requested range, blamed,
+mapped, and unmapped commit counts, and effective decision depth. Explained
+lookups use an authoritative source scan because a compact metadata index does
+not contain the rationale and graph fields required to support the answer.
+
 ## SDK and MCP
 
 The public SDK exposes both reusable-client and one-shot forms:
@@ -37,6 +67,9 @@ const client = new PmClient({ cwd: process.cwd() });
 const fromClient = await client.filesLookup({
   paths: ["src/sdk/files.ts"],
   limit: 20,
+  explain: true,
+  lineRange: { start: 650, end: 720 },
+  decisionDepth: 12,
 });
 
 const oneShot = await filesLookup(
@@ -45,7 +78,12 @@ const oneShot = await filesLookup(
 );
 ```
 
-The MCP `files` action uses the same primitive when `lookupPath` is present. `id` remains required for item-local add, remove, discover, and list operations; reverse lookup instead requires one or more `lookupPath` values. Use `pm contracts --command files --flags-only --json` for the active machine contract.
+The MCP `files` action uses the same primitive when `lookupPath` is present and
+accepts `explain`, `lines`, and `decisionDepth`. The dedicated `files_lookup`
+tool exposes the same fields. `id` remains required for item-local add, remove,
+discover, and list operations; reverse lookup instead requires one or more
+`lookupPath` values. Use `pm contracts --command files --flags-only --json` for
+the active machine contract.
 
 SDK hosts that manage authoritative item writes directly can use `queryLinkedFileMetadataIndex` from the public item-metadata-index surface. The reverse projection is rebuilt from linked-file collections and updated in the same derived-index writer section as normal metadata deltas. A missing, stale, corrupt, or extension-incompatible index must fall back to authoritative reads.
 

package/docs/SDK_RUNTIME_BOUNDARIES.md

@@ -2,7 +2,11 @@
 
 Tracker: [pm-1eted6](../.agents/pm/issues/pm-1eted6.toon),
 [pm-3lhth4](../.agents/pm/issues/pm-3lhth4.toon), and
-[pm-0xmajx](../.agents/pm/issues/pm-0xmajx.toon).
+[pm-0xmajx](../.agents/pm/issues/pm-0xmajx.toon). Refusal reachability and
+recovery completeness are tracked by
+[pm-elmpav](../.agents/pm/features/pm-elmpav.toon),
+[pm-185870](../.agents/pm/issues/pm-185870.toon), and
+[pm-yqe0mo](../.agents/pm/issues/pm-yqe0mo.toon).
 
 These SDK primitives keep host and project-runtime policy consistent across the
 bundled CLI, packages, and automation without requiring consumers to reproduce
@@ -56,3 +60,34 @@ guidance when presenting refusals as human-readable or structured output.
 Host-only validation remains at the transport boundary, while rules shared by
 packages and commands live in public SDK primitives so callers receive the
 same refusal contract regardless of entrypoint.
+
+`createUnknownSubcommandError` is the shared constructor for positional command
+families. It emits `unknown_subcommand` with the stable
+`unknown_positional_token` reason, a complete sorted `allowed_values` set, the
+attempted command, and a nearest copy-pasteable retry when edit distance gives
+an unambiguous candidate. CLI, direct SDK dispatch, MCP, and package hosts use
+the same primitive. The CLI also recognizes split schema actions such as
+`schema add type Name` and recommends the declared `schema add-type Name`
+form instead of collapsing the failure into a generic arity error.
+Core graph, config, plan, schema, profile, merge, telemetry, workspace, and
+package/extension lifecycle dispatchers use this contract. The bundled
+templates package demonstrates the same primitive for package-registered
+families; custom packages can import it from the public SDK instead of
+inventing a private refusal envelope. The former `unknown_lifecycle_action`
+catalog name remains a compatibility alias of `unknown_subcommand`.
+
+`PmErrorCodeContract.owned_states` declares concrete refusal states, their
+probe ids, reachable entrypoints, and expected exit classes. The generated
+catalog joins those declarations to the discovered error-code inventory.
+Package and test harnesses can pass real-entrypoint observations to
+`verifyPmRefusalReachability`; missing probes, wrong codes, wrong exit classes,
+and undeclared observations fail closed. This makes an error code's existence
+and its runtime reachability independently testable.
+
+Unknown-option recovery separates human and machine budgets. Human guidance
+shows the first three ranked command paths plus an explicit remainder count.
+The structured envelope returns up to twelve ranked paths alongside
+`candidate_commands_total` and `candidate_commands_truncated`, ordered by
+shared option vocabulary and then command path. Consumers must inspect another
+command contract before changing operations; candidate discovery is not an
+instruction to run a different command.

package/docs/TESTING.md

@@ -242,12 +242,12 @@ baseline, scorer tests, and SDK documentation together.
 Tracked by [pm-k6t4yb](../.agents/pm/tasks/pm-k6t4yb.toon) and
 [pm-b2hc4x](../.agents/pm/tasks/pm-b2hc4x.toon).
 
-Every named workflow step that makes a build, test, quality, security, package,
-or release claim is discovered and matched exactly against
-`scripts/release/gate-registry.json`. Each registry entry declares:
+Every workflow job is discovered by its stable `workflow-file#job-id` identity
+and matched exactly against `scripts/release/gate-registry.json`; human-facing
+step names never define the inventory. Each registry entry declares:
 
 - a canonical pm owner;
-- the enforced workflow steps it owns;
+- the enforced workflow jobs it participates in;
 - actionable failure taxonomy;
 - explicit bypass policy and audit rationale;
 - an executable negative-control test and assertion.
@@ -259,11 +259,14 @@ pnpm quality:gate-registry
 node scripts/release/gate-registry.mjs --inventory
 ```
 
-`pnpm quality:static` includes the registry. A newly named workflow gate fails
-until it has an owner and negative-control proof; a removed or renamed workflow
-step also fails until stale policy is reconciled. Public source claims are
-mapped to exact evidence strings and an enforced registry entry so
-documentation cannot silently advertise advisory behavior.
+`pnpm quality:static` includes the registry. A new workflow job fails until it
+is declared under at least one canonical gate, and a removed or renamed job id
+fails until stale policy is reconciled. Display-name edits do not mutate gate
+identity. Public source claims are mapped to exact evidence strings and an
+enforced registry entry so documentation cannot silently advertise advisory
+behavior.
+The inventory output lists registry-derived `registered` job IDs beside the
+parsed `workflow_jobs`; validation requires the two sets to match exactly.
 
 ## Tracker Context-Quality Ratchets