@unbrained/pm-cli 2026.8.22 → 2026.8.24

package/dist/sdk/test/trust.js

@@ -0,0 +1,207 @@
+/**
+ * @module sdk/test/trust
+ *
+ * Provides provenance and clone-local trust decisions for stored linked-test
+ * commands. Tracker items remain portable while execution acknowledgements stay
+ * outside the merge-unioned project record.
+ */
+
+!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]="30a61f26-5db8-50ba-af37-1990a4742ce8")}catch(e){}}();
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { ensureDir, writeFileAtomic, } from "../../core/fs/fs-utils.js";
+import { sha256Hex, stableStringify } from "../../core/shared/serialization.js";
+import { isTimestampLiteral } from "../../core/shared/time.js";
+import { getRuntimePath } from "../../core/store/paths.js";
+const execFileAsync = promisify(execFile);
+const LINKED_TEST_TRUST_LEDGER_VERSION = 1;
+const LINKED_TEST_TRUST_LEDGER_FILE = "linked-test-trust.json";
+function trustLedgerPath(pmRoot) {
+    return path.join(getRuntimePath(pmRoot), LINKED_TEST_TRUST_LEDGER_FILE);
+}
+function emptyTrustLedger() {
+    return { version: LINKED_TEST_TRUST_LEDGER_VERSION, acknowledged: {} };
+}
+async function readTrustLedger(pmRoot) {
+    try {
+        const parsed = JSON.parse(await readFile(trustLedgerPath(pmRoot), "utf8"));
+        if (parsed.version !== LINKED_TEST_TRUST_LEDGER_VERSION ||
+            typeof parsed.acknowledged !== "object" ||
+            parsed.acknowledged === null ||
+            Array.isArray(parsed.acknowledged)) {
+            return emptyTrustLedger();
+        }
+        return {
+            version: LINKED_TEST_TRUST_LEDGER_VERSION,
+            acknowledged: parsed.acknowledged,
+        };
+    }
+    catch {
+        // A missing, corrupt, or unreadable ledger grants no acknowledgements.
+        // The local/source-ref provenance checks remain independent of this file.
+        return emptyTrustLedger();
+    }
+}
+/** Resolve the current Git branch without invoking a shell. */
+export async function resolveLinkedTestSourceRef(cwd = process.cwd()) {
+    const hostedRef = process.env.GITHUB_HEAD_REF?.trim() || process.env.GITHUB_REF_NAME?.trim();
+    if (hostedRef && hostedRef !== "merge") {
+        return hostedRef;
+    }
+    try {
+        const { stdout } = await execFileAsync("git", ["symbolic-ref", "--quiet", "--short", "HEAD"], { cwd, encoding: "utf8", windowsHide: true, timeout: 10_000 });
+        const ref = stdout.trim();
+        /* c8 ignore start -- successful git symbolic-ref output is non-empty by contract */
+        if (ref.length === 0)
+            return undefined;
+        /* c8 ignore stop */
+        return ref;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Resolve the source checkout shared by linked-test provenance and execution. */
+export function resolveLinkedTestSourceWorkspaceRoot(cwd = process.cwd()) {
+    return process.env.PM_SOURCE_WORKSPACE_ROOT?.trim() || cwd;
+}
+function hasValidLinkedTestProvenance(provenance) {
+    if (provenance === null || typeof provenance !== "object")
+        return false;
+    return (typeof provenance.author === "string" &&
+        provenance.author.trim().length > 0 &&
+        typeof provenance.created_at === "string" &&
+        isTimestampLiteral(provenance.created_at) &&
+        (provenance.source_kind === "local_mutation" ||
+            provenance.source_kind === "merge_union"));
+}
+/** Build the optional ref portion shared by clone-local trust decisions. */
+function linkedTestTrustRefs(sourceRef, currentSourceRef) {
+    return {
+        ...(sourceRef ? { source_ref: sourceRef } : {}),
+        ...(currentSourceRef ? { current_source_ref: currentSourceRef } : {}),
+    };
+}
+/** Attach immutable author/time/ref provenance to newly stored commands. */
+export function attachLinkedTestProvenance(tests, author, createdAt, sourceRef) {
+    return tests?.map((test) => test.command && !test.provenance
+        ? {
+            ...test,
+            provenance: {
+                author,
+                created_at: createdAt,
+                source_kind: "local_mutation",
+                ...(sourceRef ? { source_ref: sourceRef } : {}),
+            },
+        }
+        : test);
+}
+/** Attach provenance while avoiding Git inspection for an empty mutation. */
+export async function attachLinkedTestMutationProvenance(tests, author, createdAt) {
+    if (!tests || tests.length === 0)
+        return tests;
+    const sourceWorkspaceRoot = resolveLinkedTestSourceWorkspaceRoot();
+    return attachLinkedTestProvenance(tests, author, createdAt, await resolveLinkedTestSourceRef(sourceWorkspaceRoot));
+}
+/** Produce the clone-local trust identity for one linked-test entry. */
+export function linkedTestTrustFingerprint(test) {
+    return sha256Hex(stableStringify({
+        command: test.command ?? null,
+        path: test.path ?? null,
+        scope: test.scope,
+        pm_context_mode: test.pm_context_mode ?? null,
+        workspace_context_mode: test.workspace_context_mode ?? null,
+        env_set: test.env_set ?? null,
+        env_clear: test.env_clear ?? null,
+        shared_host_safe: test.shared_host_safe ?? null,
+        provenance: test.provenance ?? null,
+        provenance_invalid: test.provenance_invalid ?? null,
+    }));
+}
+/** Resolve whether one stored command is trusted by this clone. */
+export async function resolveLinkedTestTrust(pmRoot, test, currentSourceRef) {
+    const ledger = await readTrustLedger(pmRoot);
+    return resolveLinkedTestTrustFromLedger(test, currentSourceRef, ledger);
+}
+function resolveLinkedTestTrustFromLedger(test, currentSourceRef, ledger) {
+    const fingerprint = linkedTestTrustFingerprint(test);
+    const sourceRef = test.provenance?.source_ref;
+    if (test.provenance === undefined &&
+        test.provenance_invalid !== true) {
+        return { fingerprint, trusted: true, reason: "legacy" };
+    }
+    const acknowledged = Object.hasOwn(ledger.acknowledged, fingerprint);
+    if (test.provenance_invalid === true ||
+        !hasValidLinkedTestProvenance(test.provenance)) {
+        if (acknowledged) {
+            return {
+                fingerprint,
+                trusted: true,
+                reason: "acknowledged",
+                ...linkedTestTrustRefs(undefined, currentSourceRef),
+            };
+        }
+        return {
+            fingerprint,
+            trusted: false,
+            reason: "invalid_provenance",
+            ...linkedTestTrustRefs(undefined, currentSourceRef),
+        };
+    }
+    if (test.provenance.source_kind === "local_mutation" &&
+        sourceRef === undefined) {
+        return {
+            fingerprint,
+            trusted: true,
+            reason: "local_mutation",
+            ...linkedTestTrustRefs(undefined, currentSourceRef),
+        };
+    }
+    if (test.provenance.source_kind === "local_mutation" &&
+        sourceRef !== undefined &&
+        sourceRef === currentSourceRef) {
+        return {
+            fingerprint,
+            trusted: true,
+            reason: "local_source_ref",
+            source_ref: sourceRef,
+            current_source_ref: currentSourceRef,
+        };
+    }
+    if (acknowledged) {
+        return {
+            fingerprint,
+            trusted: true,
+            reason: "acknowledged",
+            ...linkedTestTrustRefs(sourceRef, currentSourceRef),
+        };
+    }
+    return {
+        fingerprint,
+        trusted: false,
+        reason: "foreign_source_ref",
+        ...linkedTestTrustRefs(sourceRef, currentSourceRef),
+    };
+}
+/** Resolve a collection with one ledger read for validation and batch runs. */
+export async function resolveLinkedTestTrustBatch(pmRoot, tests, currentSourceRef) {
+    const ledger = await readTrustLedger(pmRoot);
+    return tests.map((test) => resolveLinkedTestTrustFromLedger(test, currentSourceRef, ledger));
+}
+/** Persist explicit clone-local acknowledgement for selected linked tests. */
+export async function acknowledgeLinkedTests(pmRoot, tests, acknowledgedAt) {
+    const ledger = await readTrustLedger(pmRoot);
+    const fingerprints = tests
+        .filter((test) => typeof test.command === "string" && test.command.length > 0)
+        .map(linkedTestTrustFingerprint);
+    for (const fingerprint of fingerprints) {
+        ledger.acknowledged[fingerprint] = { acknowledged_at: acknowledgedAt };
+    }
+    await ensureDir(path.dirname(trustLedgerPath(pmRoot)));
+    await writeFileAtomic(trustLedgerPath(pmRoot), `${JSON.stringify(ledger, null, 2)}\n`);
+    return { acknowledged: fingerprints.length, fingerprints };
+}
+//# sourceMappingURL=trust.js.map
+//# debugId=30a61f26-5db8-50ba-af37-1990a4742ce8

package/dist/sdk/workspace-contracts.d.ts

@@ -4,6 +4,7 @@
  * Declares live workspace customization metadata for SDK and MCP consumers.
  */
 import type { RegisteredExtensionCommandDefinition } from "../core/extensions/extension-types.js";
+import type { PmCommandCapabilityFamily } from "./agent-capability-contracts.js";
 import { type RuntimeFieldDefinitionResolved } from "../core/schema/runtime-schema.js";
 import type { RuntimeFieldType } from "../types/index.js";
 /** Runtime custom-field metadata exposed to SDK and MCP consumers. */
@@ -46,6 +47,8 @@ export interface WorkspaceExtensionCommandContract {
     description?: string;
     /** Minimum agent surface tier requested by the extension. */
     tier: "core" | "standard" | "full" | "internal";
+    /** Capability family declared by the extension. */
+    family: PmCommandCapabilityFamily;
 }
 /** Project resolved custom-field definitions into the public workspace shape. */
 export declare function buildWorkspaceFieldContracts(definitions: RuntimeFieldDefinitionResolved[]): WorkspaceFieldContract[];

package/dist/sdk/workspace-contracts.js

@@ -1,5 +1,5 @@
 
-!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]="b9eae1a3-3eb6-5415-86c3-a8e8e1fedd1f")}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]="10052b6f-216f-5b50-81ec-ee373cc13d17")}catch(e){}}();
 import { runtimeFieldOptionTarget, } from "../core/schema/runtime-schema.js";
 /** Project resolved custom-field definitions into the public workspace shape. */
 export function buildWorkspaceFieldContracts(definitions) {
@@ -27,7 +27,8 @@ export function buildWorkspaceExtensionCommandContracts(definitions) {
         })),
         description: definition.description,
         tier: definition.tier ?? "standard",
+        family: definition.family ?? "extensions",
     }));
 }
 //# sourceMappingURL=workspace-contracts.js.map
-//# debugId=b9eae1a3-3eb6-5415-86c3-a8e8e1fedd1f
+//# debugId=10052b6f-216f-5b50-81ec-ee373cc13d17

package/dist/types.d.ts

@@ -166,6 +166,17 @@ export interface LinkedFile {
     /** Value that configures or reports note for this contract. */
     note?: string;
 }
+/** Valid immutable provenance captured when a linked command enters tracker data. */
+export interface LinkedTestProvenance {
+    /** Author identity recorded by the originating mutation. */
+    author: string;
+    /** ISO 8601 time at which the command entered tracker data. */
+    created_at: string;
+    /** Mutation path that introduced the command. */
+    source_kind: "local_mutation" | "merge_union";
+    /** Best-effort Git branch or hosted head ref of the originating mutation. */
+    source_ref?: string;
+}
 /** Documents the linked test payload exchanged by command, SDK, and package integrations. */
 export interface LinkedTest {
     /** Value that configures or reports command for this contract. */
@@ -178,6 +189,12 @@ export interface LinkedTest {
     timeout_seconds?: number;
     /** Strategy used to control pm context behavior. */
     pm_context_mode?: "schema" | "tracker" | "auto";
+    /** Strategy used for source-workspace visibility and command working directory. */
+    workspace_context_mode?: "source" | "isolated" | "snapshot";
+    /** Immutable provenance captured when the linked command enters tracker data. */
+    provenance?: LinkedTestProvenance;
+    /** Explicit fail-closed marker retained when stored provenance is malformed. */
+    provenance_invalid?: true;
     /** Value that configures or reports env set for this contract. */
     env_set?: Record<string, string>;
     /** Value that configures or reports env clear for this contract. */
@@ -566,6 +583,10 @@ export interface ItemTestRunExecution {
     requested_pm_context_mode?: "schema" | "tracker" | "auto";
     /** Effective context mode used by the linked command. */
     pm_context_mode?: "schema" | "tracker" | "auto";
+    /** Effective source-workspace mode used by the linked command. */
+    workspace_context_mode?: "source" | "isolated" | "snapshot";
+    /** Trust classification applied before execution. */
+    trust_reason?: "legacy" | "local_mutation" | "local_source_ref" | "acknowledged" | "invalid_provenance" | "foreign_source_ref";
 }
 /** Documents the item test run summary payload exchanged by command, SDK, and package integrations. */
 export interface ItemTestRunSummary {
@@ -1121,6 +1142,8 @@ export interface PmSettings {
     /** Value that configures or reports testing for this contract. */
     testing: {
         record_results_to_items: boolean;
+        /** Permit explicit one-shot execution of commands not yet trusted by this clone. */
+        allow_untrusted_linked_tests: boolean;
     };
     /** Value that configures or reports telemetry for this contract. */
     telemetry: {

package/dist/types.js

@@ -5,7 +5,7 @@
  */
 /** Supported values accepted by the builtin item type contract. */
 
-!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]="13c65470-8f5f-59ca-acb5-50c926c68870")}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]="64223a83-1287-57ac-915d-dbd5e375a6eb")}catch(e){}}();
 export const BUILTIN_ITEM_TYPE_VALUES = [
     "Epic",
     "Feature",
@@ -243,4 +243,4 @@ export const CONTEXT_SECTION_VALUES = [
     "tests",
 ];
 //# sourceMappingURL=types.js.map
-//# debugId=13c65470-8f5f-59ca-acb5-50c926c68870
+//# debugId=64223a83-1287-57ac-915d-dbd5e375a6eb

package/docs/AGENT_PROVENANCE_ADR.md

@@ -10,7 +10,10 @@ Implementation lineage:
 resolution and patch-free historical reads implemented by
 [pm-ffz0a9](../.agents/pm/issues/pm-ffz0a9.toon),
 [pm-v8gfi7](../.agents/pm/issues/pm-v8gfi7.toon), and
-[pm-3yxwv5](../.agents/pm/issues/pm-3yxwv5.toon).
+[pm-3yxwv5](../.agents/pm/issues/pm-3yxwv5.toon). Cross-harness adapters and
+operator-managed probe/vocabulary controls are tracked by
+[pm-c0lrdm](../.agents/pm/features/pm-c0lrdm.toon) and
+[pm-yds9dt](../.agents/pm/chores/pm-yds9dt.toon).
 
 Status: accepted amendment to
 [pm-qwuber](../.agents/pm/decisions/pm-qwuber.toon). The original stable-author
@@ -51,10 +54,13 @@ Provenance values are descriptive context, never authentication or
 authorization principals. Values are trimmed, length-bounded, and obtained only
 from literal descriptor keys, trusted caller data, or a named bounded resolver.
 Detection does not spawn processes, traverse process trees, evaluate user
-regexes, or access the network. The built-in Claude resolver may read only the
-tail of the current session's harness-owned JSONL file to recover its recorded
-model/version. It caps file bytes, lines, and line length, extracts only those
-two allow-listed values, and fails closed. `agent_identity.probes_enabled` or
+regexes, or access the network. The built-in Claude and Codex resolvers read
+only bounded windows of the current session's harness-owned JSONL file. Claude
+uses the recent tail to recover its recorded model/version. Codex uses the
+recent tail plus a bounded initial-head fallback for oversized sessions to
+recover allow-listed `turn_context.model` and `turn_context.effort` values.
+Both cap traversal, file bytes, lines, and line length, ignore all other fields,
+never follow symlinks, and fail closed. `agent_identity.probes_enabled` or
 `PM_AGENT_PROBES=off` disables every local resolver without disabling ordinary
 environment, argv, client, or host detection.
 
@@ -113,6 +119,11 @@ fabricate precision that was never captured.
 The aggregate and core SDK entrypoints export:
 
 - `AGENT_PROVENANCE_DIMENSIONS`;
+- `BUILTIN_AGENT_PROVENANCE_ADAPTERS`,
+  `listAgentProvenanceAdapters()`, and
+  `registerAgentProvenanceAdapters()`;
+- `normalizeAgentProvenanceAdapterValue()` for stable model-family and effort
+  vocabulary projections that retain the bounded raw observation;
 - `detectAgentIdentity()` and `detectHarnessIdentity()`;
 - `analyzeAgentProvenanceDescriptorCoverage()` for the descriptor capability
   matrix and negative controls;
@@ -138,6 +149,31 @@ Legacy author interpretation is workspace-owned data under
 version and whether a harness was `recorded`, resolved by `vocabulary`, or
 remains `unresolved`; immutable authors and hashes are never rewritten.
 
+`pm config get agent-identity-vocabulary`, `config list`, and `config export`
+publish only its `version` and `alias_count`. Typed mutations use the existing
+config transport:
+
+```bash
+pm config set agent-identity-probes-enabled false
+pm config set agent-identity-vocabulary --policy preview-add \
+  --value "Legacy Codex=codex" --criterion "Legacy Codex" --criterion "Alice"
+pm config set agent-identity-vocabulary --policy add \
+  --value "Legacy Codex=codex"
+pm config set agent-identity-vocabulary --policy remove --value "Legacy Codex"
+```
+
+`preview-*` policies perform no write and report the exact residual unique
+author count without returning author spellings. Real add/remove/clear changes
+bump the vocabulary revision once; identical adds and absent removes are
+idempotent. Aliases for already canonical `harness:<name>` authors fail closed.
+
+Every built-in interactive harness has a contract-versioned adapter with an
+implementation version, priority, covered dimensions, source classes,
+normalization revisions, confidence, waivers, and immutable probe bounds.
+Packages may register a new namespace or explicitly replace a built-in only at
+a higher priority. Equal-priority ambiguity and descriptor mismatch fail
+closed, and the disposer restores the prior adapter.
+
 The SDK/CLI matrix classifies every input as shared, positional, transport,
 presentation, local adapter, scope selector, compatibility alias, or SDK-native.
 An unknown CLI flag fails closed as `unclassified`. Committed test baselines cap

package/docs/CONFIGURATION.md

@@ -29,6 +29,7 @@ pm config project export --json
 pm config project get item-format --json
 pm config project set item-format --format toon
 pm config project set test-result-tracking --policy enabled
+pm config project set untrusted-linked-test-execution --policy disabled
 ```
 
 `config set <key> <value>` also accepts the value as a positional argument; pm routes
@@ -85,6 +86,7 @@ When `settings.json` cannot be loaded, `pm` falls back to built-in defaults and
 | `history.compact_policy.max_entries`       | when the policy is enabled, the entry count above which a stream is flagged by `pm health` and the default `pm history-compact --all-over` threshold (default `500`)                                  |
 | `history.compact_policy.trigger`           | policy intent when enabled: `health_warn` (advisory only) or `auto` (scheduled sweeps expected)                                                                                                       |
 | `testing.record_results_to_items`          | persist bounded linked-test summaries                                                                                                                                                                 |
+| `testing.allow_untrusted_linked_tests`     | permit the explicit `pm test --allow-untrusted-linked-tests` one-run override (default `false`; does not trust or execute commands by itself)                                                         |
 | `validation.sprint_release_format`         | `warn` or `strict_error`                                                                                                                                                                              |
 | `validation.parent_reference`              | `warn` or `strict_error` (`strict_error` is the built-in default; `pm create --allow-missing-parent` is the explicit escape hatch)                                                                    |
 | `item_types.definitions[]`                 | custom item types and type options                                                                                                                                                                    |
@@ -115,6 +117,7 @@ pm config project set schema_unknown_field_policy reject   # (schema.unknown_fie
 pm config project set governance-duplicate-detection-mode strict         # (governance.duplicate_detection_mode) off | advisory | strict
 pm config project set governance-duplicate-detection-threshold 0.8       # (governance.duplicate_detection_threshold) ratio 0..1
 pm config project set governance-duplicate-detection-limit 3             # (governance.duplicate_detection_limit) integer 0..20
+pm config project set untrusted-linked-test-execution disabled            # (testing.allow_untrusted_linked_tests) enabled | disabled
 ```
 
 Duplicate governance uses the shared SDK scorer and bounded metadata query
@@ -227,6 +230,7 @@ pm config project set sprint-release-format-policy --policy warn
 pm config project set parent-reference-policy --policy strict_error
 pm config project set history-missing-stream-policy --policy auto_create
 pm config project set test-result-tracking --policy enabled
+pm config project set untrusted-linked-test-execution --policy disabled
 ```
 
 Use standalone checks when validating a repository:

package/docs/DIAGNOSTIC_OUTPUT_CONTRACTS.md

@@ -58,6 +58,15 @@ estimates, applied stages, and omitted top-level fields. Minimal fallbacks bound
 the named omission list and disclose any additional count through
 `omitted_fields_overflow_count`.
 
+Structured CLI refusals also include a compact `refusal` identity with the
+failing command/flag/operand surface, rejected scalar when observable, complete
+legal domain when one exists, and the process exit code. Recovery-bearing
+errors use the `recovery_bundle` diagnostic class. Collection degradation may
+compact explanatory domains inside `recovery`, but `refusal.legal_domain`
+remains complete and `recovery.suggested_retry_args` is atomic: the projector
+either retains the executable argv or removes the recovery rather than slicing
+it into a dead command.
+
 The deterministic ladder is:
 
 1. full diagnostic;
@@ -73,8 +82,12 @@ envelope.
 
 ## Executable Assurance
 
-`pnpm quality:recovery-closure` builds the current CLI and replays 22 refusal
-contracts in isolated trackers. Ten representative, high-frequency failure
+`pnpm quality:recovery-closure` builds the current CLI and replays 117 refusal
+contracts in isolated trackers: 18 closed-domain rows, 88 required-argument
+omissions derived from core executable positional signatures, seven
+closed-action families, and four tracker-preflight states. Package-owned
+commands enter executable coverage when their package runtime is active rather
+than being misreported as core. Ten representative, high-frequency failure
 paths are also ratcheted by
 `scripts/release/diagnostic-output-baseline.json`. The gate requires every row
 to remain within the SDK-declared JSON ceiling and retain a mechanically
@@ -85,6 +98,10 @@ The baseline is a coverage ratchet, not permission to weaken a ceiling. Its
 negative control requires a missing baseline probe to fail. The existing
 refusal-closure negative controls independently prove that incomplete domains,
 broken retries, and malformed recovery envelopes remain blocking findings.
+The grammar corpus additionally hashes authoritative tracker state around each
+refusal; schema, items, history, settings, and package state must not change.
+Ephemeral runtime lock/cache directories are excluded from that semantic
+snapshot.
 
 Run the focused proof with:
 

package/docs/MERGE_SAFETY.md

@@ -1,6 +1,6 @@
 # Multi-Branch Tracker Merge Safety
 
-Tracked by [pm-wc1r](../.agents/pm/features/pm-wc1r.toon), with the integrity and concurrency fixes [pm-9q2t](../.agents/pm/issues/pm-9q2t.toon), [pm-cxyv](../.agents/pm/issues/pm-cxyv.toon), [pm-gpo7](../.agents/pm/issues/pm-gpo7.toon), [pm-m3nl](../.agents/pm/issues/pm-m3nl.toon), [pm-wwfd](../.agents/pm/issues/pm-wwfd.toon), and [pm-xdn6](../.agents/pm/issues/pm-xdn6.toon). Fresh-init fence ownership is tracked by [pm-1w3ljt](../.agents/pm/issues/pm-1w3ljt.toon); runtime-cache index governance by [pm-hous](../.agents/pm/issues/pm-hous.toon); local allocation safety by [pm-khdq](../.agents/pm/issues/pm-khdq.toon); fence-coverage completeness and drift detection by [pm-i4fx](../.agents/pm/issues/pm-i4fx.toon); package-defined item coverage by [pm-5rexki](../.agents/pm/issues/pm-5rexki.toon); non-item JSON coverage by [pm-gjicmx](../.agents/pm/issues/pm-gjicmx.toon); portable driver identity by [pm-w91mvg](../.agents/pm/issues/pm-w91mvg.toon); pending receipt validation by [pm-ysqb6n](../.agents/pm/issues/pm-ysqb6n.toon); receipt classification by [pm-jtwsct](../.agents/pm/issues/pm-jtwsct.toon); direction-independent item conflict selection by [pm-dlx7v7](../.agents/pm/issues/pm-dlx7v7.toon); corrected reconciliation guidance by [pm-lwmstb](../.agents/pm/issues/pm-lwmstb.toon); cross-branch id collision safety by [pm-pibw](../.agents/pm/issues/pm-pibw.toon); auditable merge history by [pm-9j2r3b](../.agents/pm/tasks/pm-9j2r3b.toon); durable conflict decisions by [pm-rh98vo](../.agents/pm/issues/pm-rh98vo.toon); continuous conformance by [pm-76dnfg](../.agents/pm/tasks/pm-76dnfg.toon); workspace-wide CI enforcement by [pm-pdr8t1](../.agents/pm/tasks/pm-pdr8t1.toon); post-merge reconciliation by [pm-mfkv92](../.agents/pm/issues/pm-mfkv92.toon); this repository's own adoption by [pm-iwsj](../.agents/pm/chores/pm-iwsj.toon).
+Tracked by [pm-wc1r](../.agents/pm/features/pm-wc1r.toon), with the integrity and concurrency fixes [pm-9q2t](../.agents/pm/issues/pm-9q2t.toon), [pm-cxyv](../.agents/pm/issues/pm-cxyv.toon), [pm-gpo7](../.agents/pm/issues/pm-gpo7.toon), [pm-m3nl](../.agents/pm/issues/pm-m3nl.toon), [pm-wwfd](../.agents/pm/issues/pm-wwfd.toon), and [pm-xdn6](../.agents/pm/issues/pm-xdn6.toon). Fresh-init fence ownership is tracked by [pm-1w3ljt](../.agents/pm/issues/pm-1w3ljt.toon); runtime-cache index governance by [pm-hous](../.agents/pm/issues/pm-hous.toon); local allocation safety by [pm-khdq](../.agents/pm/issues/pm-khdq.toon); fence-coverage completeness and drift detection by [pm-i4fx](../.agents/pm/issues/pm-i4fx.toon); package-defined item coverage by [pm-5rexki](../.agents/pm/issues/pm-5rexki.toon); non-item JSON coverage by [pm-gjicmx](../.agents/pm/issues/pm-gjicmx.toon); portable driver identity by [pm-w91mvg](../.agents/pm/issues/pm-w91mvg.toon); pending receipt validation by [pm-ysqb6n](../.agents/pm/issues/pm-ysqb6n.toon); receipt classification by [pm-jtwsct](../.agents/pm/issues/pm-jtwsct.toon); direction-independent item conflict selection by [pm-dlx7v7](../.agents/pm/issues/pm-dlx7v7.toon); corrected reconciliation guidance by [pm-lwmstb](../.agents/pm/issues/pm-lwmstb.toon); cross-branch id collision safety by [pm-pibw](../.agents/pm/issues/pm-pibw.toon); auditable merge history by [pm-9j2r3b](../.agents/pm/tasks/pm-9j2r3b.toon); durable conflict decisions by [pm-rh98vo](../.agents/pm/issues/pm-rh98vo.toon); continuous conformance by [pm-76dnfg](../.agents/pm/tasks/pm-76dnfg.toon); workspace-wide CI enforcement by [pm-pdr8t1](../.agents/pm/tasks/pm-pdr8t1.toon); post-merge reconciliation by [pm-mfkv92](../.agents/pm/issues/pm-mfkv92.toon); linked-command execution trust by [pm-ed28wi](../.agents/pm/issues/pm-ed28wi.toon); this repository's own adoption by [pm-iwsj](../.agents/pm/chores/pm-iwsj.toon).
 
 pm stores project context as reviewable repository files. Concurrent agents can therefore use ordinary branches and worktrees, but tracker artifacts need semantic merge behavior: raw line merging cannot preserve TOON collection counts, JSON object structure, or append-only history hash chains.
 
@@ -61,6 +61,20 @@ pm merge install --dry-run --json
 | tracker `**/*.jsonl` except the later `history/*.jsonl` override | `pm-relationship`                   | Covers default and package-owned custom relationship event paths, unions divergent suffixes by `eventId` (timestamp-ordered, ours-first on ties), and renumbers `sequence` consecutively so the strict-sequence store loader accepts the merged stream. |
 | root `settings.json` and nested `**/*.json`                      | `pm-json`                           | Recursively merges objects per key. Arrays compose when both branches preserve the base and add distinct entries, so independent extension installs and evaluation additions merge without weakening edit/removal conflict detection.                   |
 
+The `tests` collection has an additional execution-safety rule. Its semantic
+identity excludes provenance so the same command/context does not duplicate
+when branches record different authorship metadata. A test definition newly
+contributed by the other merge side is persisted with
+`provenance.source_kind=merge_union` while retaining its author, creation time,
+and source ref. `pm test --run` and `pm test-all` refuse that command before
+spawning a process until the receiving clone acknowledges its fingerprint or
+uses the two-part project-policy plus per-run override documented in
+[Testing](TESTING.md#linked-test-command-trust). `pm validate
+--check-command-references` reports outstanding entries. This is the threat
+boundary for append-like data that becomes executable after a merge; ordinary
+notes, files, and other non-executable collections retain normal set-union
+behavior.
+
 When both sides change the same item scalar differently, the driver writes the same stable value regardless of which branch Git labels ours or theirs, but exits nonzero. Item results and receipts expose the caller's `requested_preference`; the per-decision `retained` and `discarded` values or hashes are authoritative because stable value order can retain either side. Readers normalize the legacy receipt key `preferred`, while new receipts no longer emit it. JSON leaf conflicts retain the explicit preferred-side policy. Git keeps either path conflicted so a human or coordinating agent must review the discarded value and explicitly `git add` the resolution. This correction is tracked by [pm-qckpnq](../.agents/pm/issues/pm-qckpnq.toon).
 
 The driver result's `guidance` always points unresolved conflicts to `pm merge report`. When a clone-local receipt exists, guidance includes its privacy-safe receipt and item ids for exact correlation; discarded values remain confined to the local receipt and never appear in generic logs or tracker history. Tracked by [pm-fbrz7p](../.agents/pm/issues/pm-fbrz7p.toon).

package/docs/README.md

@@ -50,6 +50,8 @@ pm guide release --json
 - [Output Token Accounting](OUTPUT_TOKEN_ACCOUNTING.md) - opt-in CLI/MCP byte attribution, bounded receipt overhead, and release-level tokens-per-task baselines.
 - [SDK Context Platform](SDK_CONTEXT.md) - task-oriented entry point for authoritative reads, ranking, package workflows, diagnostics, recovery, and verification.
 - [Self-Describing Context Contracts](SELF_DESCRIBING_CONTEXT_CONTRACTS.md) - intent-scoped reads, semantic flag invocation metadata, visibility parity, and generated error vocabulary.
+- [Generated Agent Capability Routing](generated/AGENT_CAPABILITY_ROUTING.md) - contract-derived command families shared by help, guide, skills, completion, MCP, and extensions.
+- [Generated Refusal Closure Census](generated/REFUSAL_CLOSURE_CENSUS.md) - complete error-catalog join to executable refusal evidence and explicit uncovered obligations.
 - [Universal Read Output Contracts](READ_OUTPUT_CONTRACTS.md) - cross-command include, amount, cost, and encoding controls for CLI, SDK, MCP, and packages.
 - [Diagnostic Output Contracts](DIAGNOSTIC_OUTPUT_CONTRACTS.md) - action-first error budgets, deterministic degradation, SDK projection, and executable refusal assurance.
 - [Mutation Integrity](MUTATION_INTEGRITY.md) - shared CLI/SDK/MCP author, secret, append-only disposition, and stale-work guardrails.

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), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-srns](../.agents/pm/issues/pm-srns.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).
+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-srns](../.agents/pm/issues/pm-srns.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), [pm-2qvq7a](../.agents/pm/issues/pm-2qvq7a.toon), and [pm-xam9bt](../.agents/pm/issues/pm-xam9bt.toon).
 
 ## Agent Quick Context
 
@@ -164,6 +164,16 @@ an unbounded multi-megabyte response;
 `recovery_budget_multiplier: 1` declares that each next page retains the same
 useful-result ceiling.
 
+When compaction affects a nested collection that is not declared resumable,
+the recovery budget is derived from the larger of the binding ceiling plus one
+and the measured pre-compaction result. The SDK adds a 25% envelope margin and
+rounds up to 100 tokens. The CLI, SDK, and MCP bindings therefore receive the
+same finite value, which is strictly larger than the request that already
+truncated. If safe-integer arithmetic cannot represent that value, recovery
+uses `unbounded` explicitly. `resolveReadOutputRecoveryBudget()` exposes the
+versioned pure calculation to package authors; there is no hard-coded smaller
+retry and no recovery cycle.
+
 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,