@unbrained/pm-cli 2026.8.14 → 2026.8.16

package/dist/sdk/read-output-rows.js

@@ -5,11 +5,14 @@
  * envelopes, including dot-delimited nested paths used by graph projections.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="03e25a43-f05c-5bc6-a42a-140914e522d5")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="0c69ff43-7bbc-5128-9533-bbf15365126b")}catch(e){}}();
 const BUDGET_METADATA_ROOT_KEYS = new Set([
     "applied_bound",
     "completeness",
+    "budget_retention_policy",
     "continuation_contract",
+    "continuation_kind",
+    "continuation_path",
     "filters",
     "omission_receipt",
     "output_budget_truncation",
@@ -48,6 +51,16 @@ function replaceValueAtPath(result, rowPath, replacement) {
     target[segments.at(-1)] = replacement;
     return root;
 }
+/** Replace one declared row collection with a suffix beginning at an offset. */
+export function sliceReadOutputRowCollection(result, rowPath, offset) {
+    const collection = readOutputRowCollections(result).find((entry) => entry.path === rowPath);
+    if (!collection)
+        return result;
+    const replacement = Array.isArray(collection.value)
+        ? collection.value.slice(offset)
+        : Object.fromEntries(Object.entries(collection.value).slice(offset));
+    return replaceValueAtPath(result, rowPath, replacement);
+}
 /** Resolve declared row paths, falling back to top-level array properties. */
 export function readOutputRowPaths(result) {
     const contract = result.row_contract;
@@ -142,4 +155,4 @@ export function boundReadOutputRows(result, amount) {
     return { result: projected, truncated };
 }
 //# sourceMappingURL=read-output-rows.js.map
-//# debugId=03e25a43-f05c-5bc6-a42a-140914e522d5
+//# debugId=0c69ff43-7bbc-5128-9533-bbf15365126b

package/dist/sdk/runtime-input.js

@@ -5,7 +5,7 @@
  * primitives are shared by native action dispatchers and MCP-specific adapters.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="bcda2578-3b01-5e64-9d53-cd32c0f927b8")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="0e153ece-4fc0-5134-97f0-c2315aff0031")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { asRecordClone } from "../core/shared/primitives.js";
@@ -83,6 +83,7 @@ export function actionGlobalOptions(args) {
         outputLimit: readRuntimeScalarString(args, "outputLimit"),
         outputBudget: readRuntimeScalarString(args, "outputBudget"),
         outputSession: readRuntimeString(args, "outputSession"),
+        outputCursor: readRuntimeString(args, "outputCursor"),
         outputFormat: outputFormat === "json" || outputFormat === "toon"
             ? outputFormat
             : undefined,
@@ -167,6 +168,7 @@ const UNIVERSAL_READ_OUTPUT_OPTION_KEYS = [
     "outputBudget",
     "outputFormat",
     "outputSession",
+    "outputCursor",
 ];
 /** Reconcile MCP array/scalar option spellings with CLI flag expectations. */
 export function normalizeMcpOptionsArrays(options, action) {
@@ -501,4 +503,4 @@ export function updateManyOptionsFromFlat(options) {
     };
 }
 //# sourceMappingURL=runtime-input.js.map
-//# debugId=bcda2578-3b01-5e64-9d53-cd32c0f927b8
+//# debugId=0e153ece-4fc0-5134-97f0-c2315aff0031

package/dist/sdk/runtime.d.ts

@@ -33,7 +33,7 @@ import { type GcCommandOptions, type GcResult } from "./governance/gc.js";
 import { type HealthResult, type RunHealthOptions } from "./governance/health.js";
 import { type ValidateCommandOptions, type ValidateCountsResult, type ValidateResult } from "./governance/validate.js";
 import { type ExtensionCommandOptions, type ExtensionCommandResult } from "./extension.js";
-import { type AcknowledgeUnknownAuthorEventsOptions } from "./author-attribution.js";
+import { type AcknowledgeUnknownAuthorEventsOptions, type UnknownAuthorAcknowledgmentResult } from "./author-attribution.js";
 import { type HistoryCompactBulkCommandOptions, type HistoryCompactBulkResult, type HistoryCompactCommandOptions, type HistoryCompactResult } from "./history-compact.js";
 import { type HistoryRedactCommandOptions, type HistoryRedactResult } from "./history-redact.js";
 import { type HistoryRepairAllResult, type HistoryRepairCommandOptions, type HistoryRepairResult } from "./history-repair.js";
@@ -250,10 +250,7 @@ export declare class PmClient {
     /** Compact an explicit or policy-selected set of history streams. */
     historyCompactBulk(options: HistoryCompactBulkCommandOptions): Promise<HistoryCompactBulkResult>;
     /** Disposition immutable unknown-author events through append-only audit history. */
-    historyAuthorAcknowledge(options: AcknowledgeUnknownAuthorEventsOptions): Promise<{
-        acknowledged: number;
-        history_path: string;
-    }>;
+    historyAuthorAcknowledge(options: AcknowledgeUnknownAuthorEventsOptions): Promise<UnknownAuthorAcknowledgmentResult>;
     /** Run any typed plan workflow primitive through the shared CLI/MCP engine. */
     plan(subcommand: PlanSubcommand, id?: string, options?: PlanCommandOptions, stepRef?: string, reorderTo?: number): Promise<PlanCommandResult>;
     /** Create a durable plan with optional ordered seed steps. */

package/dist/sdk/runtime.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Runtime.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="a387cd7a-cb16-5082-80e1-9632ebd02480")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="bedbe090-60c3-5935-a656-da4997cd80f7")}catch(e){}}();
 export { PM_GITIGNORE_END, PM_GITIGNORE_START, ensurePmGitignore, getPmGitignoreBlock, } from "./workspace.js";
 export { SEARCH_EXTENSION_FLAG_DEFINITIONS } from "./extension-contracts.js";
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -442,6 +442,7 @@ export class PmClient {
         return this.runTyped("history-author-acknowledge", {
             historyEvent: (options.events ?? []).map((event) => `${event.item_id}:${String(event.line)}`),
             allActionable: options.all_actionable === true,
+            dryRun: options.dry_run === true, planFingerprint: options.plan_fingerprint, limit: options.coordinate_limit,
             attributedAuthor: options.attributed_author,
             reviewer: options.reviewer,
             reason: options.reason,
@@ -1932,4 +1933,4 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=a387cd7a-cb16-5082-80e1-9632ebd02480
+//# debugId=bedbe090-60c3-5935-a656-da4997cd80f7

package/docs/ASSURANCE.md

@@ -1,6 +1,6 @@
 # Project Assurance Primitives
 
-Tracker: [pm-2lex4r](../.agents/pm/features/pm-2lex4r.toon), [pm-lyfu7b](../.agents/pm/features/pm-lyfu7b.toon), [pm-wn6wot](../.agents/pm/features/pm-wn6wot.toon), [pm-91xeam](../.agents/pm/features/pm-91xeam.toon), [pm-uhv1m5](../.agents/pm/features/pm-uhv1m5.toon), [pm-m7bb7r](../.agents/pm/features/pm-m7bb7r.toon), [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-h06944](../.agents/pm/issues/pm-h06944.toon), [pm-dwj33e](../.agents/pm/decisions/pm-dwj33e.toon)
+Tracker: [pm-2lex4r](../.agents/pm/features/pm-2lex4r.toon), [pm-lyfu7b](../.agents/pm/features/pm-lyfu7b.toon), [pm-wn6wot](../.agents/pm/features/pm-wn6wot.toon), [pm-91xeam](../.agents/pm/features/pm-91xeam.toon), [pm-uhv1m5](../.agents/pm/features/pm-uhv1m5.toon), [pm-m7bb7r](../.agents/pm/features/pm-m7bb7r.toon), [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-h06944](../.agents/pm/issues/pm-h06944.toon), [pm-88mo8m](../.agents/pm/issues/pm-88mo8m.toon), [pm-atnfh4](../.agents/pm/issues/pm-atnfh4.toon), [pm-xmmafu](../.agents/pm/issues/pm-xmmafu.toon), [pm-4ok4ex](../.agents/pm/tasks/pm-4ok4ex.toon), [pm-dwj33e](../.agents/pm/decisions/pm-dwj33e.toon)
 
 ## Agent Quick Context
 
@@ -43,6 +43,14 @@ Measurements support these built-in sources:
 | `derived`         | Combine numeric measurements with deterministic arithmetic and cycle detection.                                                          |
 | `provider`        | Delegate a measurement to an explicitly supplied host/package resolver.                                                                  |
 
+`ASSURANCE_MEASUREMENT_SOURCE_KINDS` and `ASSURANCE_GATE_TRIGGERS` are the
+public SDK constants for these closed vocabularies. Runtime validation rejects
+missing arrays and unknown discriminants with `AssuranceMutationRefusalError`;
+it never persists an unrecognized source or leaks an incidental JavaScript
+property-access error. Hosts that generate forms or package schemas can obtain
+the same values from `pm contracts --command assurance --json` under
+`assurance_contracts`.
+
 Each measurement may declare `max_cost`. Evaluation fails closed when the total abstract compute units exceed that ceiling. Every result reports units, scanned items, scanned history rows, provider calls, duration, population size, and contributors.
 
 One workspace context memoizes identical graph operations and the shared
@@ -263,15 +271,64 @@ await pm.assurance({
 });
 ```
 
-For direct host composition, use `evaluateMeasurement`, `evaluateAssuranceGate`, `createAssuranceWorkspaceContext`, the preset/derivation helpers, and the audited declaration/verdict helpers exported from `@unbrained/pm-cli/sdk`. Active extension registrations are discovered automatically. Embedding hosts may additionally pass stable resolver ids and matching `provider_capabilities` to `createAssuranceWorkspaceContext`; an absent resolver or capability fails loudly. The core evaluator bounds concurrent assertions and expression operands, and workspace history loading uses bounded concurrency; item-only callers can explicitly skip history and Git identity resolution.
+For direct host composition, use `evaluateMeasurement`, `evaluateAssuranceGate`, `createAssuranceWorkspaceContext`, the preset/derivation helpers, and the audited declaration/verdict helpers exported from `@unbrained/pm-cli/sdk` and its focused `@unbrained/pm-cli/sdk/governance` entrypoint. Active extension registrations are discovered automatically. Embedding hosts may additionally pass stable resolver ids and matching `provider_capabilities` to `createAssuranceWorkspaceContext`; an absent resolver or capability fails loudly. The core evaluator bounds concurrent assertions and expression operands, and workspace history loading uses bounded concurrency; item-only callers can explicitly skip history and Git identity resolution.
+
+Hosts that want the normal action transport and its audited registry lookup can
+pass the same adapters as the third `runAssuranceAction` argument. The request
+and project path remain transport data; resolver capabilities remain explicit
+runtime authority:
+
+```ts
+await runAssuranceAction(
+  {
+    action: "run",
+    id: "repository-static-quality",
+    trigger: "ci",
+    dry_run: true,
+  },
+  { path: ".agents/pm" },
+  {
+    workspace: {
+      include_history: false,
+      providers: {
+        "repository-quality": resolveRepositoryQualityMeasurement,
+      },
+      provider_capabilities: {
+        "repository-quality": { cost_class: "high", network: false },
+      },
+    },
+  },
+);
+```
+
+This is the migration boundary for repository automation: scripts may remain
+focused process adapters, while assertion composition, provider policy,
+negative controls, lifecycle triggers, and verdicts move into ordinary
+assurance declarations. `scripts/release/gate-registry.json` records every
+gate script as migrated, provider-backed, or retained and fails unless the
+migrated/provider-backed population is the majority.
+
+`AssuranceMutationRefusalError` and `AssuranceEvaluationRefusalError` are
+exported from both `@unbrained/pm-cli/sdk` and
+`@unbrained/pm-cli/sdk/governance`, so hosts can classify expected declaration
+or evaluation refusals without parsing messages. Source-resolution refusals
+also carry the gate, assertion, measurement, source kind, field, and optional
+health/validate check, so a zero value remains distinct from an absent or
+mistyped field.
 
 Generic SDK and MCP dispatch use `action: "assurance"` with `subcommand` set to `list`, `show`, `put`, `remove`, `run`, `verdicts`, `presets`, `apply`, `derive`, or `promote`. Discover the current machine contract instead of copying parameter lists:
 
 ```bash
 pm contracts --action assurance --schema-only --json
 pm contracts --command assurance --flags-only --json
+pm contracts --command assurance --json
 ```
 
+Command-scoped contract output omits unrelated extension, governance,
+relationship, and Commander-alias catalogs unless `--full` is requested. This
+keeps the selected action schema and its assurance vocabularies complete under
+the default output budget instead of truncating the very enum a caller needs.
+
 ## Verdict Contract
 
 A gate emits one object containing:

package/docs/COMMANDS.md

@@ -4,6 +4,8 @@ This is a task-oriented command guide. For exact flags, use runtime help because
 
 Tracked implementation updates: [pm-52eh](../.agents/pm/features/pm-52eh.toon), [pm-mcxr](../.agents/pm/issues/pm-mcxr.toon), [pm-qd3woa](../.agents/pm/issues/pm-qd3woa.toon), [pm-ypuc39](../.agents/pm/issues/pm-ypuc39.toon), [pm-tz2ikr](../.agents/pm/issues/pm-tz2ikr.toon), the schema-migration recovery contract [pm-s79kel](../.agents/pm/issues/pm-s79kel.toon), the lossless mutation contracts [pm-x3dq0l](../.agents/pm/issues/pm-x3dq0l.toon), [pm-lppm6y](../.agents/pm/issues/pm-lppm6y.toon), and [pm-embm6t](../.agents/pm/issues/pm-embm6t.toon), and the SDK-first agent grammar tranche [pm-p316vn](../.agents/pm/issues/pm-p316vn.toon), [pm-st7wgu](../.agents/pm/issues/pm-st7wgu.toon), [pm-mkinft](../.agents/pm/issues/pm-mkinft.toon), [pm-ulqu](../.agents/pm/issues/pm-ulqu.toon), [pm-qmjx](../.agents/pm/issues/pm-qmjx.toon), [pm-4bzq](../.agents/pm/features/pm-4bzq.toon), [pm-x2vx](../.agents/pm/issues/pm-x2vx.toon), and [pm-g543](../.agents/pm/issues/pm-g543.toon).
 
+Workspace-integrity contracts are tracked by [pm-22rzjp](../.agents/pm/issues/pm-22rzjp.toon), [pm-76fkpp](../.agents/pm/issues/pm-76fkpp.toon), [pm-igdvfq](../.agents/pm/issues/pm-igdvfq.toon), [pm-643e0k](../.agents/pm/issues/pm-643e0k.toon), and [pm-larv4r](../.agents/pm/issues/pm-larv4r.toon).
+
 ```bash
 pm <command> --help
 pm <command> --help --json
@@ -965,6 +967,8 @@ pm history-repair <id> --dry-run
 pm history-repair <id> --message "re-anchor legacy drift"
 pm history-repair --all --dry-run
 pm history-repair --all --message "bulk re-anchor drifted streams"
+pm history-repair --all --normalize-provenance --dry-run
+pm history-repair --all --normalize-provenance --message "normalize invalid legacy provenance"
 pm activity                         # item digest for the last 24 hours
 pm activity --raw --id <id> --limit 50
 pm activity --full --id <id> --limit 50
@@ -1020,8 +1024,10 @@ For governance dashboards, `--metadata-coverage` adds a `metadata_coverage` bloc
 `history-redact` rewrites matching history payloads deterministically, recomputes hash chains, and appends an auditable `history_redact` marker entry when changes are applied. Its result reports only `literal_count`, `regex_count`, `total_count`, and whether the default replacement was selected; literal values, regex source text, and replacement text are never echoed in CLI, SDK, MCP, recovery, profile, or telemetry output. Treat regex text as sensitive input because it can contain the exact material being removed.
 `history-compact` rewrites long streams into a synthetic checkpoint baseline plus a retained tail (`--before` accepts a 1-based version or ISO timestamp), re-anchors hashes, verifies integrity, and appends an auditable `history_compact` marker when applied.
 `history-compact` bulk mode (mutually exclusive with a positional `<id>`) compacts many streams in one audited pass. Select with `--ids <a,b,c>` (an explicit list — used on its own, not combined with the scan selectors below), or a scan: `--all-over <N>` (every stream with more than N entries) and/or a lifecycle filter `--closed` (terminal items only) or `--all-streams` (every stream). `--closed` and `--all-streams` are mutually exclusive. `--min-entries <N>` (default 3) skips already-compact streams; when `history.compact_policy` is enabled and `--all-over` is omitted, the policy's `max_entries` becomes the default threshold. `--before` is single-id only and is rejected in bulk mode. Each selected stream runs the same single-item compaction; one failing stream never aborts the rest — the result reports `totals` (`streams_considered`/`selected`/`items_compacted`/`items_skipped`/`items_errored`) plus one row per stream (`compacted`/`skipped` with a `skip_reason`/`errored`), and the command exits non-zero only if any stream errored.
-`history-repair` re-anchors a drifted history chain when `pm health`/`pm validate --check-history-drift` report stale hashes: it replays the stream, recomputes every before/after hash, repairs legacy patch ops that no longer strictly apply, reconciles the latest hash with the on-disk item, and appends an auditable `history_repair` marker. It never modifies item content and is a safe no-op on a clean stream.
-`history-repair --all` (mutually exclusive with `<id>`) runs the same drift scan `pm health` uses and applies the audited single-stream repair (ownership check, lock, post-repair no-drift verification, `--message` audit marker, per-stream `--force`) to every drifted stream in one pass. One failing stream never aborts the rest: the result lists one compact row per drifted stream (`repaired` / `skipped_clean` / `failed`) plus `totals`, and the command exits non-zero only if any stream failed.
+`history-repair` re-anchors a drifted history chain when `pm health`/`pm validate --check-history-drift` report stale hashes: it replays the stream, recomputes every before/after hash using the stream's detected hash epoch, repairs legacy patch ops that no longer strictly apply, reconciles the latest hash with the on-disk item, and appends an auditable `history_repair` marker. It never modifies item content and is a safe no-op on a clean stream. The result reports the before/after hash versions and whether the epoch was preserved or selected for an ambiguous broken stream, preventing old/new runtimes from alternately rewriting an otherwise consistent legacy chain.
+`history-repair --all` (mutually exclusive with `<id>`) runs the same drift scan `pm health` uses and applies the audited single-stream repair (ownership check, lock, post-repair no-drift verification, `--message` audit marker, per-stream `--force`) to every drifted stream in one pass. One failing stream never aborts the rest: the result lists one compact row per targeted stream (`repaired` / `skipped_clean` / `failed`) plus `totals`, and the command exits non-zero only if any stream failed. Add `--normalize-provenance` to include streams containing invalid boolean or single-digit provenance observations. The normalizer removes only those invalid observations and writes aggregate harness/dimension/kind counts in the audit receipt; it never echoes or retains the removed value.
+
+Every `pm health` projection exposes `findings` and `failed_because`. A finding binds one warning token to its owning check, stable code, `advisory|gate_failing` severity, and either an executable remediation or `no_safe_automatic_remediation`. Extension health also publishes `host_version_census`, which enumerates the host and every pm-cli copy resolved by loaded extensions across npm/pnpm layouts. A version mismatch makes the extension check non-clean; matching workspace-linked or deduplicated copies remain healthy.
 
 `pm health --verbose-author-events --json` includes the complete actionable unknown-author coordinate list and an explicit `samples_truncated` marker. After evidence review, `pm history-author-acknowledge --all-actionable --attributed-author <principal> --reviewer <reviewer> --reason <evidence>` records one append-only disposition for the current complete set. `--all-actionable` and repeatable `--event <item-id:line>` are mutually exclusive; reviewer, attributed author, and reason remain mandatory.
 

package/docs/READ_OUTPUT_CONTRACTS.md

@@ -1,17 +1,17 @@
 # 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), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-sb0tns](../.agents/pm/issues/pm-sb0tns.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-eugaqy](../.agents/pm/issues/pm-eugaqy.toon), [pm-jt8aa2](../.agents/pm/issues/pm-jt8aa2.toon), and [pm-kyjdne](../.agents/pm/issues/pm-kyjdne.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-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-sb0tns](../.agents/pm/issues/pm-sb0tns.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-eugaqy](../.agents/pm/issues/pm-eugaqy.toon), [pm-jt8aa2](../.agents/pm/issues/pm-jt8aa2.toon), [pm-kyjdne](../.agents/pm/issues/pm-kyjdne.toon), [pm-8nev0o](../.agents/pm/issues/pm-8nev0o.toon), [pm-e5gl05](../.agents/pm/issues/pm-e5gl05.toon), [pm-cha95z](../.agents/pm/tasks/pm-cha95z.toon), and [pm-2qvq7a](../.agents/pm/issues/pm-2qvq7a.toon).
 
 ## Agent Quick Context
 
 Every built-in read surface uses four output dimensions: what to include, how much to return, how much the result may cost, and how to encode it. The same canonical controls work through the CLI, SDK, MCP, generated schemas, runtime contracts, and shell completions.
 
-| Dimension | CLI                             | SDK and MCP     | Meaning                                                                |
-| --------- | ------------------------------- | --------------- | ---------------------------------------------------------------------- |
-| Include   | `--output-include <csv>`        | `outputInclude` | Retain named fields or sections, or select a declared projection mode. |
-| Amount    | `--output-limit <n\|unbounded>` | `outputLimit`   | Bound shared row collections.                                          |
-| Cost      | `--output-budget <tokens>`      | `outputBudget`  | Fail closed when even the compact result cannot fit.                   |
-| Encoding  | `--output-format <toon\|json>`  | `outputFormat`  | Select the CLI renderer and record the requested encoding.             |
+| Dimension | CLI                              | SDK and MCP     | Meaning                                                                |
+| --------- | -------------------------------- | --------------- | ---------------------------------------------------------------------- |
+| Include   | `--output-include <csv>`         | `outputInclude` | Retain named fields or sections, or select a declared projection mode. |
+| Amount    | `--output-limit <n\|unbounded>`  | `outputLimit`   | Bound shared row collections.                                          |
+| Cost      | `--output-budget <n\|unbounded>` | `outputBudget`  | Fail closed when even the compact result cannot fit.                   |
+| Encoding  | `--output-format <toon\|json>`   | `outputFormat`  | Select the CLI renderer and record the requested encoding.             |
 
 The contract covers `list`, `context`, `search`, `get`, `next`, `health`, `deps`, `graph`, `history`, `activity`, `validate`, `events`, `contracts`, `comments`, `notes`, `files`, `docs`, `stats`, and `aggregate`, including list aliases and `ctx`.
 
@@ -117,6 +117,18 @@ tracker content.
 
 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.
 
+Completeness spellings preserve their established promise. `pm list-all` and
+list-family `--no-truncate` imply an unbounded cost dimension when the caller
+does not supply `--output-budget`; they cannot silently return a budget-trimmed
+subset while claiming to return every matched row. An explicit canonical
+budget still has precedence and may request a bounded result deliberately.
+The same SDK-native rule applies to every declared complete-result spelling,
+including `contracts --full`: explicit completeness defeats only the implicit
+default ceiling. If an explicit caller budget cannot retain any useful domain
+result, the CLI still prints the parseable omission receipt but exits 2; a
+consumer therefore cannot interpret the missing command or action arrays as a
+successful empty contract.
+
 ```bash
 pm list-open --output-include id,title,status --output-limit 10
 pm context --for orient --output-budget 900 --output-format toon
@@ -127,7 +139,41 @@ pm contracts --full --json
 
 Every projected result carries a `read_output` receipt with the requested dimensions, precedence, observed compatibility aliases, deterministic estimated token count, string/row compaction signals, and budget outcome. Budget degradation discovers nested arrays as well as declared result rows, so validation diagnostics and other governance payloads compact their inner findings before the useful result is omitted. `compacted_row_paths` names every reduced collection without redefining those nested arrays as ordinary pagination rows.
 
-When rows are dropped to satisfy a ceiling, the result also carries `output_budget_truncation`, naming the binding budget and its source, any explicitly requested dimension the budget overrode, every compacted collection path, and an executable recovery instruction — a default ceiling can override an explicit `--output-limit unbounded`, and that override is reported rather than silent. If no useful content can fit, `PmReadOutputBudgetExceeded` provides a discriminated omission result and reports `omitted_result_estimated_tokens`, the last useful-result estimate before omission; use `isReadOutputBudgetExceeded` before accessing result-specific fields. Universal controls are rejected on mutation commands and on the mutation mode of hybrid commands such as `comments`, `notes`, `files`, and `docs`.
+When rows are dropped to satisfy a ceiling, the result also carries `output_budget_truncation`, naming the binding budget and its source, any explicitly requested dimension the budget overrode, every compacted collection path, and executable CLI/SDK/MCP recovery options — a default ceiling can override an explicit `--output-limit unbounded`, and that override is reported rather than silent. If a producer supplied an opaque item-page cursor, compaction rebases it to the last row actually returned and reports `continuation_cursor_rebased: true`; following the cursor therefore cannot skip rows removed from the middle of a producer page. If no useful content can fit, `PmReadOutputBudgetExceeded` provides a discriminated omission result, a compact `{ outputBudget: "unbounded" }` recovery object, and `omitted_result_estimated_tokens`, the last useful-result estimate before omission; use `isReadOutputBudgetExceeded` before accessing result-specific fields. Universal controls are rejected on mutation commands and on the mutation mode of hybrid commands such as `comments`, `notes`, `files`, and `docs`.
+
+Cursor recovery carries the opaque value once in `recovery.cursor` and declares
+the accepting `cli`, `sdk`, and `mcp` binding beside it. This avoids
+serializing the same cursor once per transport while retaining an executable,
+machine-readable binding for each surface.
+
+Budget-compacted declared row paths are independently resumable. The
+disclosure's `continuations` entries name the row path, retained/remaining/total
+counts, and an opaque cursor. `continuation_kind` distinguishes a rebased
+producer cursor, a universal output cursor, and a terminal page;
+`next_cursor` mirrors the first universal entry for ordinary one-path
+consumers. Replay the same query and budget
+with `--output-cursor <cursor>` / `outputCursor`. The cursor validates the
+command, declared row path, total, and stable row identities before slicing, so
+a mismatched or stale replay fails closed instead of skipping evidence. A
+bounded recovery therefore does not require replacing a 600-token request with
+an unbounded multi-megabyte response;
+`recovery_budget_multiplier: 1` declares that each next page retains the same
+useful-result ceiling.
+
+Assurance declares `budget_retention_policy: verdict_priority`: failing block,
+warn, and observe rows precede retired and passing rows while preserving order
+within each class. `assertions_total` remains the pre-projection denominator,
+and the `assertions` row path uses the same continuation primitive. A blocking
+verdict consequently keeps its causal evidence on the first bounded page even
+when the failing assertion was declared last.
+
+Diagnostic gates retain bounded, actionable predicates. Every metadata field
+required by the active validation profile emits a numeric count, including
+zero, so assurance expressions can distinguish a clean check from a missing
+key. Health retains at most 100 warning rows and reports `warning_count`,
+`warning_limit`, and `warnings_truncated`; `--strict-exit` defaults to summary
+projection unless `--full` is explicit, keeping the failing check identities
+and warning codes inside the ordinary budget.
 
 ## SDK and Package Usage
 
@@ -150,6 +196,7 @@ const result = await pm.list({
     spent_tokens: 0,
     seen_item_ids: [],
   },
+  // Supply outputCursor from output_budget_truncation to fetch the next row page.
 });
 ```
 

package/docs/RELEASING.md

@@ -24,7 +24,10 @@ Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon),
 [pm-lwnifd](../.agents/pm/issues/pm-lwnifd.toon), and SDK-bound reliability
 classification [pm-dqtzva](../.agents/pm/issues/pm-dqtzva.toon).
 The local/hosted gate selection contract is tracked by
-[pm-ei6x66](../.agents/pm/tasks/pm-ei6x66.toon).
+[pm-ei6x66](../.agents/pm/tasks/pm-ei6x66.toon). Release-candidate analyzer
+provenance is tracked by [pm-u1baah](../.agents/pm/issues/pm-u1baah.toon), and
+authoritative blocker-recovery run selection by
+[pm-db8onn](../.agents/pm/issues/pm-db8onn.toon).
 
 ## Version Policy
 
@@ -75,11 +78,15 @@ Policy:
   created, a non-`github-actions[bot]` closure of the exact bot-created
   `Auto Release blocked` issue on the same UTC day triggers one preparation
   retry
-- if today's tag already exists, blocker closure reruns and watches the exact
-  tag-driven Release workflow instead of invoking release preparation or
-  creating an ordinal replacement; an already-successful run is recorded as
+- if today's tag already exists, blocker closure bypasses release-preparation
+  provenance, dependency installation, and build work, then selects immutable
+  Release evidence across both tag-push and guarded workflow-dispatch runs; a
+  completed success is authoritative over stale failures and is recorded as
   recovered without republishing
 - release preparation must pass all quality and compatibility gates before commit+tag push
+- before dependency installation or build, auto-release verifies that the
+  candidate has exact-commit analyzer results or an immutable tree-identical
+  reviewed PR head with successful DeepScan and CodeFactor results
 - `CHANGELOG.md` is generated by the latest npm `pm-changelog` package (`pm install npm:pm-changelog --project`, then `pm changelog generate --mode replace --all-release-tags`) from closed tracker items across git release tag windows and checked in CI; do not edit it by hand
 - protected-branch pushes require `RELEASE_PAT`; Auto Release fails fast before the expensive release gates when `push=true`, `dry_run=false`, and that secret is not configured
 - release reliability gating requires `SENTRY_PERSONAL_ADMIN_TOKEN` for issue-threshold checks; Auto Release fails before creating the version commit/tag when the token is missing and `push=true`, while sourcemap upload remains optional through `SENTRY_AUTH_TOKEN`
@@ -88,9 +95,12 @@ Policy:
 - when scheduled failures continue across multiple UTC days, auto-release supersedes a stale open blocker with a fresh current-day blocker so same-day retry detection follows the latest scheduled failure
 - closing the exact bot-created `Auto Release blocked: scheduled run failed`
   issue as a maintainer or agent records a same-day retry marker, then either
-  retries preparation when no tag exists or reruns the exact existing tag's
-  Release workflow; it comments with the recovered tag on success and reopens
-  the same issue on failure. A second close on the same UTC day is refused
+  retries preparation when no tag exists or watches an active exact-tag Release
+  workflow. If only failed or missing evidence exists, it dispatches the
+  reviewed current `release.yml` from `main` with the immutable tag input; it
+  never reruns historical workflow code. It comments with the recovered tag on
+  success and reopens the same issue on failure. A second close on the same UTC
+  day is refused
   before release mutation and reported as `retry_already_attempted`, and
   workflow cleanup closures by `github-actions[bot]` are ignored.
 - after a scheduled run publishes a tag and the downstream release workflow succeeds, auto-release closes any open `Auto Release blocked` issue so the GitHub tracker reflects current release health
@@ -196,8 +206,9 @@ The build writes `dist/cli-bundle/bundle-manifest.json` atomically with SHA-256
 
 4. Run the same release pipeline locally.
 
-Push the final implementation commit first, wait for DeepScan and CodeFactor to
-finish on that reviewed SHA, then run the canonical registry-owned preflight:
+Push the final implementation commit through a reviewed pull request first,
+wait for DeepScan and CodeFactor to finish on that reviewed SHA, then run the
+canonical registry-owned preflight:
 
 ```bash
 pnpm verify:preflight
@@ -207,7 +218,8 @@ The registry supplies the ordered executable plan, command arguments,
 environment, capture policy, and explicit skip policy. Its receipt distinguishes
 passed checks from declared skips. The same registry maps named PR, nightly,
 and release workflow gates; hosted-only entries must explain why no faithful
-local equivalent exists.
+local equivalent exists. Analyzer provenance is the first executable step, so
+an unreleasable candidate fails before build, coverage, or package work.
 
 The preflight includes the mandatory local hosted-analysis proof:
 
@@ -218,13 +230,44 @@ pnpm quality:hosted-analysis
 The gate accepts only DeepScan's explicit zero-new-issue status and
 CodeFactor's explicit no-issues result. Both contexts are required by `main`
 branch protection, and the release pipeline reruns the same immutable-tree
-proof. It reads the release commit first. When GitHub does not copy app results
+proof. The gate reads branch protection through REST first; if that transport
+is unavailable or its core API quota is exhausted, it queries the equivalent
+GraphQL rules across every cursor-paginated page and still requires one exact
+`main` rule with strict updates plus both analyzer contexts. Malformed,
+truncated, missing, or ambiguous admin policy data fails closed. GitHub Actions'
+ephemeral token cannot request the repository `Administration: read` permission
+required by both of those policy surfaces. When both admin transports reject
+that token, the gate uses the contents-readable `GET /branches/main` summary
+and requires that the exact candidate is the current protected branch head,
+protection is enabled and enforced, and CodeFactor plus DeepScan are effective
+required contexts. That summary intentionally cannot attest the admin-only
+strict-update setting: its receipt reports `strict: null`,
+`strict_verified: false`, and `verification_scope: effective_required_checks`
+instead of inventing a positive result. Exact or immutable identical-tree
+analyzer provenance remains mandatory and is emitted beside the policy receipt,
+so the restricted-token recovery cannot admit an unanalyzed or different-tree
+candidate. A maintainer token with administration-read access still verifies
+and reports `strict: true` through REST or paginated GraphQL. It reads the
+release commit first. When GitHub does not copy app results
 onto a merge commit, the gate may reuse a reviewed merge-parent or squash-PR
 head only when its immutable Git tree SHA exactly matches the release commit.
 Squash provenance additionally requires one unambiguous GitHub association to a
 closed PR merged into `main` with the release commit as its merge commit.
 Missing, ambiguous, or different-tree provenance fails closed.
 
+The supported default-branch arrival path is a reviewed pull request. A direct
+push to `main` is releasable only if both analyzers attached successful evidence
+to that exact commit; when they did not, the gate explicitly refuses the
+candidate instead of letting the next scheduled release discover the missing
+precondition after expensive work. CI runs `Release analyzer readiness (main)`
+on every product-relevant push to `main`, providing continuous visibility
+between release attempts. If GitHub's commit-association endpoint has not yet
+published a new merge, the gate reads the pull-request number from GitHub's
+standard merge message and accepts it only after the immutable PR resource
+confirms that exact merge SHA, `main` base, and reviewed head. Remediate a
+refused direct-main candidate by landing the next tree-changing fix through a
+reviewed PR; never copy, synthesize, or bypass analyzer evidence.
+
 ```bash
 # Read-only parity check
 pnpm release:pipeline:dry-run

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), [pm-lu6sca](../.agents/pm/features/pm-lu6sca.toon), [pm-5y05kq](../.agents/pm/issues/pm-5y05kq.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-h97qxd](../.agents/pm/issues/pm-h97qxd.toon), [pm-h06944](../.agents/pm/issues/pm-h06944.toon), and [pm-5t33or](../.agents/pm/features/pm-5t33or.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), [pm-h97qxd](../.agents/pm/issues/pm-h97qxd.toon), [pm-h06944](../.agents/pm/issues/pm-h06944.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-in23qu](../.agents/pm/issues/pm-in23qu.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-okgxwa](../.agents/pm/issues/pm-okgxwa.toon), [pm-22rzjp](../.agents/pm/issues/pm-22rzjp.toon), [pm-76fkpp](../.agents/pm/issues/pm-76fkpp.toon), [pm-igdvfq](../.agents/pm/issues/pm-igdvfq.toon), [pm-643e0k](../.agents/pm/issues/pm-643e0k.toon), [pm-larv4r](../.agents/pm/issues/pm-larv4r.toon), [pm-mcxk8v](../.agents/pm/issues/pm-mcxk8v.toon), and [pm-2zkvxm](../.agents/pm/issues/pm-2zkvxm.toon).
 
 ## Agent Quick Context
 
@@ -54,7 +54,48 @@ rows. This lets governance envelopes reduce diagnostic findings before
 omitting the whole verdict without redefining a nested tag or remediation list
 as a pagination row. Receipts name every `compacted_row_paths` entry; a complete
 omission also records the useful result's pre-omission estimate, while the
-universal recovery remains `--output-budget unbounded`.
+recovery names a bounded budget increase when no declared row path can resume.
+
+Budget-compacted declared rows instead publish a bounded `outputCursor`
+continuation on every transport. The cursor resumes the first withheld row and
+rejects a command, path, row-total, or stable-identity mismatch. This gives SDK
+and package loops a recursive self-improvement primitive: consume a bounded
+page, update context, and continue without abandoning the ceiling.
+
+`context --explain-ranking` projects explanations to the focus rows actually
+served. `candidate_count` records the scorer population and `omitted_count`
+records explanations intentionally withheld, while each returned row retains
+its rank, baseline rank, score, and per-signal contributions. Explanation cost
+therefore scales with the answer rather than with the active workspace.
+
+Unknown-option recovery is likewise derived from the declared flag lexicon.
+The structured `option_scope` is `declared_on_path`, `declared_elsewhere`, or
+`declared_nowhere`; accepting command paths are included only for the second
+case, while the third names the nearest current-path spellings and explicitly
+terminates the otherwise-unbounded command search.
+
+## Executable recovery-reference coverage
+
+Structured refusal guidance is a forward-reference contract, not decorative
+text. `verifyPmRecoveryReferences` accepts obligations derived from real error
+envelopes and observations produced by executing a retry, resolving a declared
+command path, or linking prose to an already executed recovery. Its report
+includes the total obligation set, pass fraction, sorted findings, and stable
+coverage buckets for `suggested_retry`, `candidate_command`, `example`,
+`next_step`, `migration_hint`, and `restore_with`, including zero-population
+buckets. `derivePmRecoveryReferenceObligations` walks emitted envelopes and
+generated read-output contracts, so tests cannot silently omit a producer
+family. Each obligation declares `recovery`, `replacement`, or
+`behavior_preserving` semantics and its proof must demonstrate the same
+promise.
+
+The repository integration corpus drives real CLI refusals, executes the
+emitted retry in a temporary tracker, compares candidate commands with the
+unbounded runtime contract enumeration, and binds examples and next steps to
+those proofs. A seeded unreachable observation must lower the pass fraction
+and produce `unreachable_reference`. The same corpus is a provider-backed
+blocking assertion in `repository-context-quality`, so a well-formed but broken
+recovery promise cannot pass CI merely because its text or target flag exists.
 
 ## Row discovery and exact output receipts
 
@@ -92,17 +133,32 @@ SDK callers use `fullHistory: true`; MCP callers use `full: true`. The default s
 
 ## Author acknowledgment coordinates
 
-CLI, SDK, and MCP use the same selector and coordinate parser for `history-author-acknowledge`. A coordinate is `<item-id>:<line>` or `_workspace:<line>`, with a positive one-based line number. Exactly one of explicit events or `all_actionable` is required.
+CLI, SDK, and MCP use the same selector and coordinate parser for `history-author-acknowledge`. A coordinate is `<item-id>:<line>` or `_workspace:<line>`, with a positive one-based line number. Exactly one of explicit events or `all_actionable` is required. Applying is a two-step operation: dry-run returns a deterministic SHA-256 over the complete, ordered coordinate set and every exact source-line hash; apply requires that fingerprint and refuses stale source or selection drift with `CONFLICT` exit 4 before writing history.
 
 ```bash
 pm history-author-acknowledge \
   --event _workspace:4 \
+  --dry-run
+
+pm history-author-acknowledge \
+  --event _workspace:4 \
+  --plan-fingerprint <sha256-from-preview> \
   --attributed-author import-agent \
   --reviewer maintainer \
   --reason "Verified workspace provenance"
 ```
 
-The SDK exposes `resolveUnknownAuthorAcknowledgmentSelector` and `parseUnknownAuthorHistoryEventCoordinates` so packages never need a private copy of this grammar. Health and validate map actionable unknown-author warnings directly to this append-only acknowledgment command instead of sending callers through another diagnostic loop.
+Preview coordinates are bounded with `--limit`, but the fingerprint and counts always cover the complete selection. Plans distinguish already acknowledged coordinates, and apply reports `effect`, `no_effect` (exit 6), or `partial_effect` (exit 7). Bulk selection appends only newly actionable rows, while explicit coordinates may append a superseding disposition as described below. The SDK exposes `planUnknownAuthorHistoryAcknowledgment`, `resolveUnknownAuthorAcknowledgmentSelector`, and `parseUnknownAuthorHistoryEventCoordinates` so packages never need a private copy of this grammar. Health and validate map actionable unknown-author warnings directly to this append-only acknowledgment command instead of sending callers through another diagnostic loop.
+
+An explicit `--event` selection is also the append-only correction path: if a
+coordinate already has a disposition, preview marks it
+`already_acknowledged`, and fingerprint-bound apply appends a later disposition
+that supersedes the earlier attribution. Recover the original coordinates from
+`context.author_acknowledgment.events` in the applicable
+`history/_workspace.jsonl` record, preview those same coordinates, and apply the
+fresh fingerprint with the corrected author and review evidence. By contrast,
+`--all-actionable` intentionally selects only undispositioned rows; an empty
+bulk selection remains `no_effect` and never repeats existing dispositions.
 
 ## Health provider boundary
 
@@ -116,6 +172,14 @@ That agreement check reads only local history and JSON files: mismatched,
 missing, or unreadable singleton paths become bounded `history_drift` evidence
 without enabling embeddings, vector-store access, or any other provider I/O.
 
+Every SDK operation that requires a valid `_workspace` chain refuses the same
+way when verification fails. The typed `workspace_history_chain_invalid`
+conflict includes `verification_errors` in CLI JSON and SDK error context plus
+an executable `pm history _workspace --verify --json` recovery command. This
+keeps deliberate corruption tests and recoverable tracker drift out of the
+unexpected-runtime-error channel without weakening the fail-closed mutation
+boundary.
+
 Brief and summary check-only health projections use the scalar-only metadata
 reader. Validation uses collection-bearing metadata for evidence and
 relationship checks and materializes bodies only when strict history-drift
@@ -134,6 +198,26 @@ never succeeded. The same bounded pass classifies bare boolean and single-digit
 values across every recorded provenance dimension, publishes only aggregate
 harness/dimension/kind counts, and never echoes the historical value.
 
+`historyRepair` and `historyRepairAll` retain the detected history hash epoch
+instead of unconditionally upgrading it. `normalizeProvenance: true` adds a
+privacy-safe repair mode that removes invalid bounded observations and records
+only aggregate counts/classes in the synthetic audit event. The bulk form
+selects both drifted streams and streams requiring provenance normalization.
+
+Health results are self-indexing: every retained warning has a `findings` row
+with its owning check, stable code, severity, and either executable remediation
+or an explicit safe refusal. `failed_because` contains the exact warning tokens
+that decide `ok: false` and survives brief/summary projection. Extension health
+adds a host-version census by resolving the pm-cli package visible from each
+loaded extension; npm/pnpm duplicate-version skew is gate-failing while matching
+workspace-linked and deduplicated copies remain green.
+
+Linked file/doc add parsing uses one SDK allowlist. Whitespace-free filesystem
+paths and scheme-prefixed URLs remain positional even when a path or query
+contains `=`. Leading assignment syntax, including malformed URL-plus-note
+input, must use the declared `path`, `scope`, and `note` keys or fail before
+mutation.
+
 ## Replication and refusal gate
 
 `scripts/release/surface-replication-sets.json` declares replicated SDK, CLI, MCP, documentation, and test members. `pnpm quality:surface-replication` activates sets from the Git changeset, verifies every member invariant, and reports:
@@ -145,6 +229,12 @@ harness/dimension/kind counts, and never echoes the historical value.
 - an AST-derived denominator of identical named rule bodies, declared coverage,
   and a non-decreasing detected-cluster floor.
 
+Trigger entries may constrain a shared file with `changed_lines_contain_any`.
+The set then activates only when an added or removed diff line carries one of
+those contract markers. Missing diff evidence fails closed and activates the
+set, while an unrelated hunk in the same shared table does not force artificial
+edits across every replicated member.
+
 Query waivers directly with:
 
 ```bash