@unbrained/pm-cli 2026.8.23 → 2026.8.25

package/dist/sdk/scheduling-shortcuts.js

@@ -1,5 +1,6 @@
 
-!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]="32223457-5f57-5049-99cf-c5d766413fb6")}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]="c7c75b13-7317-5089-9869-7e6e22ed95b2")}catch(e){}}();
+import { transferMutationStdinTokenPolicy, } from "./runtime-primitives.js";
 import { runCreate, } from "./lifecycle/create.js";
 const DEFAULT_DURATION = "1h";
 const DEFAULT_START = "now";
@@ -10,7 +11,7 @@ function appendQuotedPair(pairs, key, value) {
     }
 }
 function buildCommonOptions(type, title, options) {
-    return {
+    const createOptions = {
         type,
         title,
         schedulePreset: "lightweight",
@@ -23,6 +24,7 @@ function buildCommonOptions(type, title, options) {
         author: options.author,
         message: options.message,
     };
+    return transferMutationStdinTokenPolicy(options, createOptions);
 }
 async function createMeetingOrEvent(type, title, options, global) {
     const createOptions = buildCommonOptions(type, title, options);
@@ -59,4 +61,4 @@ export function runRemind(title, options, global) {
     return runCreate(createOptions, global);
 }
 //# sourceMappingURL=scheduling-shortcuts.js.map
-//# debugId=32223457-5f57-5049-99cf-c5d766413fb6
+//# debugId=c7c75b13-7317-5089-9869-7e6e22ed95b2

package/dist/sdk/structured-mutations.js

@@ -5,9 +5,10 @@
  * transaction contract and normalizes full item documents for CLI round trips.
  */
 
-!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]="07876c03-63a8-5c69-9c6c-c3446076a382")}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]="3f348972-0c8f-52da-abeb-46690df967d8")}catch(e){}}();
 import crypto from "node:crypto";
 import { normalizeItemId, normalizePrefix } from "../core/item/id.js";
+import { preserveMutationStdinTokenLiterals } from "../core/item/parse.js";
 import { EXIT_CODE, ITEM_PROJECT_CONTEXT_KEYS, } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { levenshteinDistanceWithinLimit } from "../core/shared/levenshtein.js";
@@ -244,7 +245,13 @@ export function parseItemMutationBatch(input) {
     if (rows === undefined || rows.length === 0) {
         throw new PmCliError("Mutation batch must be a non-empty JSON array or an object with a non-empty mutations array.", EXIT_CODE.USAGE);
     }
-    return rows.map((row, index) => validateMutationRow(row, index));
+    return rows.map((row, index) => {
+        const mutation = validateMutationRow(row, index);
+        if (mutation.options !== undefined) {
+            preserveMutationStdinTokenLiterals(mutation.options);
+        }
+        return mutation;
+    });
 }
 function deriveReferencedItemId(transactionId, reference, idPrefix) {
     const digest = crypto
@@ -571,4 +578,4 @@ export function validateItemMutationRows(value) {
     return parseItemMutationBatch(JSON.stringify(value));
 }
 //# sourceMappingURL=structured-mutations.js.map
-//# debugId=07876c03-63a8-5c69-9c6c-c3446076a382
+//# debugId=3f348972-0c8f-52da-abeb-46690df967d8

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/docs/MERGE_SAFETY.md

@@ -2,6 +2,9 @@
 
 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).
 
+Lossless receipt health gating is tracked by
+[pm-baksix](../.agents/pm/issues/pm-baksix.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.
 
 ## Install the repository merge contract
@@ -118,11 +121,37 @@ pm merge reconcile --force --message "Accept reviewed merge decisions" --json
 ```
 
 The preview reports every drifted stream and pending receipt without mutation.
-Lossless receipts are reported as provenance but do not become blocking merge
-decisions. Receipts with discarded scalar values remain blocking and the apply
-pass refuses them unless the coordinator explicitly supplies `--force` after
-review. This prevents a routine history repair from silently accepting data
-loss while preserving a zero-noise path for merges that retained both changes.
+Lossless receipts do not become discarded-value decisions and reconcile without
+`--force`, but `pm health` reports `merge_receipts_pending:<n>` and remains
+non-green until the apply pass settles them. `pm history-repair` cannot clear
+that receipt finding. When a drifted item also has a pending receipt, the
+`history_drift` remediation map prioritizes `pm merge reconcile --dry-run` only
+when canonical item path, changed-field, and merged-value hash evidence all
+attribute that finding to one or more receipts loaded from the clone-local Git
+evidence store. Every field declared by each receipt must match its current merged-value
+hash, even when only a subset appears in the history reconciliation diff.
+Disjoint valid receipts may collectively cover a multi-field reconciliation;
+the audit and settlement then retain every individually proven receipt id.
+Serialized source claims are ignored. Receipt readers validate the complete
+bounded schema, safe identifiers, filename and item-path identity, timestamps,
+and bounded decision structure before a sidecar enters health or
+reconciliation. Reads use size-preflighted, no-follow regular-file descriptors;
+durable decisions must retain hash-only values. Legacy or durable-only receipts,
+receipts whose declared fields disagree with their hashes, same-item tampering,
+and drift on unrelated items fail closed to the normal `pm history-repair`
+guidance. Health indexes clone-local evidence once by item and reconciliation
+uses the same per-item groups with a fixed receipt-only worker pool, so committed
+sidecars cannot amplify drift scans into unbounded parallel repair work.
+Apply-mode reconciliation repeats the same proof against the exact
+item snapshot used by the audited history rewrite. The audit event and
+settlement include only the individually proven receipt id, so one valid receipt
+cannot authorize an untrusted same-item sibling. Failed or unproven receipts
+remain pending unless the coordinator explicitly reviews and supplies `--force`.
+Receipts with discarded scalar values retain the distinct
+`merge_decisions_unreviewed:<n>` finding, and the apply pass refuses them unless
+the coordinator explicitly supplies `--force` after review. This prevents a
+routine history repair from hiding unfinished reconciliation or silently
+accepting data loss.
 It exits nonzero while either merge-critical validation check is non-green, so
 CI and explicit post-merge hooks cannot approve unresolved receipts or drift.
 The apply pass uses the audited history rewrite boundary to append a

package/docs/OUTPUT_PROJECTION_CONTRACTS.md

@@ -16,7 +16,10 @@ selectors are tracked by
 and canonical TOON tables are tracked by
 [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon) and
 [pm-5y05kq](../.agents/pm/issues/pm-5y05kq.toon). Nested evidence continuation
-is tracked by [pm-8nev0o](../.agents/pm/issues/pm-8nev0o.toon).
+is tracked by [pm-8nev0o](../.agents/pm/issues/pm-8nev0o.toon) and
+[pm-oahhyc](../.agents/pm/issues/pm-oahhyc.toon). Exact command-local
+projection discovery is tracked by
+[pm-q4isdq](../.agents/pm/issues/pm-q4isdq.toon).
 
 ## Agent Quick Context
 
@@ -112,6 +115,15 @@ machine-iterable without a command-specific selector. `fields` is always explici
 shape. NDJSON event streams do not carry an envelope and therefore do not
 publish a row contract.
 
+Projection mode discovery is command-local even though the compatibility
+degradation ladder is global. Read
+`output_projection_contracts.commands` from a command-scoped contracts call or
+the full contracts matrix before selecting a whole-result mode. The
+contract labels the global ladder `union_not_per_command`, so clients cannot
+infer that `list` accepts `summary` or that `health` accepts `compact`.
+`PM_READ_OUTPUT_SURFACE_CONTRACTS[].projection_modes` provides the identical
+canonical matrix to SDK and package consumers.
+
 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

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), [pm-2qvq7a](../.agents/pm/issues/pm-2qvq7a.toon), and [pm-xam9bt](../.agents/pm/issues/pm-xam9bt.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-oahhyc](../.agents/pm/issues/pm-oahhyc.toon), [pm-q4isdq](../.agents/pm/issues/pm-q4isdq.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
 
@@ -60,6 +60,17 @@ removing spelling receipts and volatile run metadata. A selector that matches
 neither a declared mode nor any field on any returned row is refused with the
 legal domain, rather than returning rows with every field removed.
 
+Runtime discovery publishes the same exact vocabulary before invocation.
+`pm contracts --command <command> --summary` returns
+`output_projection_contracts.commands`, while
+`output_projection_contracts.global_ladder_scope: "union_not_per_command"`
+explicitly marks `output_policy.degradation_ladder` as a cross-command union,
+not a promise that every member is accepted by the selected command. For
+example, `list` declares `brief`, `compact`, and `full`; `health` declares
+`brief`, `full`, and `summary`. The full `read_output_dimensions` matrix also
+includes `projection_modes` for every canonical read surface, including an
+explicit empty array when a surface has no whole-result modes.
+
 ## Cross-Call Context Sessions
 
 `--output-session <json>` / `outputSession` composes the four per-call
@@ -164,6 +175,18 @@ an unbounded multi-megabyte response;
 `recovery_budget_multiplier: 1` declares that each next page retains the same
 useful-result ceiling.
 
+Health continuation fingerprints use a versioned nonvolatile-snapshot policy
+for the `checks` row. Command-lifecycle telemetry may refresh timestamps, queue
+counters, and pending spans between pages, so the policy excludes only those
+explicit direct fields from the `telemetry` row's `details`. The row identity,
+verdict, enabled state, capture level, endpoint, environment overrides, probe
+result, and failure errors remain fingerprinted. Every other health check also
+remains fully fingerprinted; changing storage, integrity, history, or another
+stable check fails closed. `PM_READ_OUTPUT_CONTINUATION_FINGERPRINT_POLICIES`
+publishes the exact ignored detail fields per dynamic row. Other commands still
+fingerprint every field, including fields with the same spelling, and any
+policy-version change fails closed against an older cursor.
+
 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
@@ -221,7 +244,7 @@ const result = await pm.list({
 });
 ```
 
-Package authors should use the exported read-output contracts instead of inventing package-local limit or projection vocabularies. `PM_READ_OUTPUT_SURFACE_CONTRACTS` is the machine-readable matrix and `resolveReadOutputDimensions` plus `applyReadOutputDimensions` are the shared execution primitives.
+Package authors should use the exported read-output contracts instead of inventing package-local limit or projection vocabularies. `PM_READ_OUTPUT_SURFACE_CONTRACTS` is the machine-readable matrix, `PM_READ_OUTPUT_CONTINUATION_FINGERPRINT_POLICIES` declares stable-snapshot exceptions, and `resolveReadOutputDimensions` plus `applyReadOutputDimensions` are the shared execution primitives.
 
 ## Drift Gates
 

package/docs/RELEASING.md

@@ -59,13 +59,13 @@ pnpm version:check
 
 ## One-Time Setup
 
-- Use npm provenance publishing for `.github/workflows/release.yml` so GitHub-hosted release jobs publish signed packages. Keep `id-token: write`, Node 24 or newer, npm 11.5.1 or newer, `NODE_AUTH_TOKEN` from the `release` environment `NPM_TOKEN` secret, and `npm publish --access public --provenance`. The token must authenticate as a maintainer with read-write access to `@unbrained/pm-cli`.
+- Use npm trusted publishing for `.github/workflows/release.yml` so GitHub-hosted release jobs exchange their OIDC identity for a short-lived npm publish credential and publish signed packages. Keep `id-token: write`, the `release` environment, Node 24 or newer, npm 11.5.1 or newer, and `npm publish --access public --provenance`. The npm Trusted Publisher must match repository `unbraind/pm-cli`, workflow `release.yml`, and environment `release`. The release job performs a tokenless `npm publish --dry-run` OIDC exchange before the long release gates and fails early with npm's sanitized exchange diagnostic when the registry refuses the configured identity. Do not pass `registry-url` to `actions/setup-node`: its generated token-placeholder npmrc can suppress npm's OIDC exchange when no token is present. Keep `@unbrained/pm-cli` public; trusted publishing authorizes `npm publish`, not `npm access`, so restore package visibility manually before retrying if an anonymous metadata probe fails. Do not expose `NODE_AUTH_TOKEN` or `NPM_TOKEN` to the publish step; if private dependencies ever require a read token, scope it only to the install step.
 - Add `RELEASE_PAT` to the `release` environment from a maintainer token with `contents:write` and branch-protection bypass rights. Auto Release creates a checked version/changelog commit and tag on `main`; the default `GITHUB_TOKEN` has `contents:write` but cannot satisfy protected-branch required status checks for that freshly-created commit. The workflow does not persist this elevated token during checkout or dependency installation; `run-release-pipeline.mjs` scopes it to the git push process.
 - Add `SENTRY_AUTH_TOKEN` as an optional GitHub Environment or repository secret when Sentry release creation and sourcemap upload should run. Add `SENTRY_PERSONAL_ADMIN_TOKEN` for the GitHub-hosted Sentry issue-threshold gate; CI-scoped release tokens may not have issue-read scope. The release workflow skips Sentry upload cleanly when `SENTRY_AUTH_TOKEN` is absent, but fails the reliability threshold gate when `SENTRY_PERSONAL_ADMIN_TOKEN` is absent; local maintainers should still run the token-backed Sentry gate before release.
 - Keep any `release` environment compatible with free GitHub features. This repository is public, so environment secrets and tag/branch deployment rules are compatible with the free GitHub path; do not add paid-only release gates.
 - Ensure `GITHUB_TOKEN` has `contents: write` for GitHub Release creation.
 - Keep `package.json` repository, homepage, and bugs URLs aligned with `https://github.com/unbraind/pm-cli`.
-- Keep npm publishing compatible with provenance. The release workflow must keep `id-token: write`, a GitHub-hosted runner, Node 24 or newer, npm 11.5.1 or newer, a valid `NPM_TOKEN`, and `npm publish --access public --provenance`.
+- Keep npm publishing compatible with provenance. The release workflow must keep `id-token: write`, a GitHub-hosted runner, Node 24 or newer, npm 11.5.1 or newer, tokenless public metadata probes, and `npm publish --access public --provenance` through the configured Trusted Publisher.
 
 ## Automated Daily Driver
 
@@ -88,6 +88,11 @@ Policy:
 - 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
+- after the automatic version commit lands, main CI accepts its parent's
+  analyzer evidence only when the commit is the exact immutable-tagged release
+  projection: the canonical commit message, every expected distribution
+  manifest changed by version substitution alone, and only the generated
+  changelog heading changed. Any other path or content still fails closed
 - `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`
@@ -248,8 +253,9 @@ 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,
+instead of inventing a positive result. Exact, immutable identical-tree, or
+fully validated deterministic-release 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
@@ -260,9 +266,23 @@ 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 automatic release commit is the sole non-identical-tree derivation. The
+gate requires one parent, the canonical release subject and body, an immutable
+`v<version>` tag resolving to the candidate, the complete expected manifest
+inventory, exact old-version to new-version substitutions in every manifest,
+and an exact `Unreleased` changelog-heading replacement. It then resolves the
+parent through the same exact or reviewed identical-tree analyzer contract.
+Added, deleted, renamed, missing, or otherwise modified paths are refused, as
+are malformed manifests, changelog edits, untagged commits, and parents without
+successful analyzer evidence. The receipt reports
+`analysis_source: deterministic_release_transform` and names both the release
+parent and the parent's analyzer source; it never describes the changed release
+tree as identical to the analyzed tree.
+
 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
+to that exact commit or it is the narrowly validated automatic release
+projection above; when neither condition holds, 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
@@ -325,7 +345,7 @@ git push origin v<version>
 `.github/workflows/release.yml` runs on `v*.*.*` tags and handles:
 
 - full-history checkout
-- manual `workflow_dispatch` by tag for recovery. An authenticated exact-version probe keeps already-published access recovery on the reviewed dispatch-time `main` source; when the immutable tag exists but npm publication never completed, recovery checks out that exact tagged source and retains the original version guard
+- manual `workflow_dispatch` by tag for recovery. An isolated anonymous exact-version probe keeps already-published recovery on the reviewed dispatch-time `main` source; when the immutable tag exists but npm publication never completed, recovery checks out that exact tagged source and retains the original version guard
 - pnpm install with frozen lockfile
 - version policy and tag guard
 - secret scan
@@ -351,13 +371,12 @@ git push origin v<version>
   dispatch may do so only when its source-selection preflight pinned the
   checkout to the requested immutable tag; reviewed-main recovery continues
   to refuse publication of a missing target. Only
-  when neither the target nor package metadata is anonymously visible does the
-  same-tag recovery path attempt to restore public package access, because a
-  hidden version can also return 404 to authenticated metadata reads. After a
-  successful access recovery it rechecks anonymous metadata, then either skips
-  the now-visible target or publishes the still-missing version. Permission,
-  authentication, and registry failures stop the workflow instead of risking
-  an immutable-version overwrite. The checked-out tag's `package.json` supplies
+  when neither the target nor package metadata is anonymously visible, the
+  same-tag recovery path fails closed and instructs the maintainer to restore
+  public package visibility outside the workflow. Trusted publishing does not
+  authorize package-access mutations. Permission, authentication, and registry
+  failures stop the workflow instead of risking an immutable-version overwrite.
+  The checked-out tag's `package.json` supplies
   the canonical package identity to both the publish guard and the
   post-publish npm/npx/bunx verifier so those identities cannot drift. The
   explicit stable dist-tag also preserves
@@ -415,8 +434,8 @@ Use the npm registry package for maintainer global updates. Do not use `npm inst
   `workflow_dispatch` and `tag=v<version>` (or close the current bot-created
   blocker once to trigger the guarded exact-run recovery). The workflow skips
   duplicate npm publication for an anonymously visible version. Before
-  installing or running gates, dispatch performs an authenticated exact-version
-  probe. An
+  installing or running gates, dispatch performs an isolated anonymous
+  exact-version probe. An
   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
@@ -428,12 +447,12 @@ Use the npm registry package for maintainer global updates. Do not use `npm inst
   by rerunning the same tag workflow, document the incident and ship the code
   fix in the next UTC day's release.
 - A manual exact-tag `workflow_dispatch` recovery uses isolated anonymous
-  registry probes before any account-level access mutation. A visible package
-  with a missing target version proceeds directly to exact-tag publication, so
-  a publish-capable automation token is not required to change package access.
-  Access recovery is reserved for the ambiguous case where neither the package
-  nor target version is anonymously visible. An already-visible immutable
-  version is still verified and never republished. Recovery starts from the
+  registry probes and never mutates package access. A visible package with a
+  missing target version proceeds directly to exact-tag OIDC publication. When
+  neither the package nor target version is anonymously visible, recovery fails
+  closed until a maintainer restores public visibility outside the workflow. An
+  already-visible immutable version is still verified and never republished.
+  Recovery starts from the
   dispatch-time commit SHA and fails unless the dispatch ref is the repository
   default branch (`main`). It remains on that reviewed source when the exact
   npm version exists. When the version is definitively absent, it switches to

package/docs/SCRIPTING.md

@@ -1,6 +1,6 @@
 # CLI Scripting Contract
 
-Tracked by [pm-psy1](../.agents/pm/tasks/pm-psy1.toon), [pm-hqa8g1](../.agents/pm/tasks/pm-hqa8g1.toon), [pm-gknu](../.agents/pm/issues/pm-gknu.toon), [pm-999jh7](../.agents/pm/issues/pm-999jh7.toon), and [pm-srns](../.agents/pm/issues/pm-srns.toon).
+Tracked by [pm-psy1](../.agents/pm/tasks/pm-psy1.toon), [pm-hqa8g1](../.agents/pm/tasks/pm-hqa8g1.toon), [pm-gknu](../.agents/pm/issues/pm-gknu.toon), [pm-999jh7](../.agents/pm/issues/pm-999jh7.toon), [pm-srns](../.agents/pm/issues/pm-srns.toon), [pm-3oq022](../.agents/pm/issues/pm-3oq022.toon), [pm-iktj](../.agents/pm/tasks/pm-iktj.toon), and [pm-kexu](../.agents/pm/issues/pm-kexu.toon).
 
 Use this contract when composing `pm` with shells, CI runners, `jq`, or another process. Exact flags remain discoverable from `pm <command> --help --json` and `pm contracts --command <command> --flags-only --json`.
 
@@ -14,8 +14,8 @@ Use this contract when composing `pm` with shells, CI runners, `jq`, or another
 | `3`  | Requested tracker or resource was not found.                                     | Correct the path or ID.                              |
 | `4`  | State or concurrency conflict.                                                   | Refresh live state before deciding whether to retry. |
 | `5`  | A required dependency operation failed.                                          | Inspect the dependency evidence before retrying.     |
-| `6`  | The request succeeded but matched nothing to change.                              | Treat as success and inspect the effect receipt.      |
-| `7`  | The request succeeded and changed only part of the selected targets.              | Treat as success and inspect unmatched/skipped rows.  |
+| `6`  | The request succeeded but matched nothing to change.                             | Treat as success and inspect the effect receipt.     |
+| `7`  | The request succeeded and changed only part of the selected targets.             | Treat as success and inspect unmatched/skipped rows. |
 
 Exits `0`, `6`, and `7` are successful outcomes. Bulk mutation envelopes repeat
 the distinction as `outcome: effect`, `outcome: no_effect`, or `outcome:
@@ -134,6 +134,65 @@ else
 fi
 ```
 
+Bulk selectors on `update-many`, `close-many`, and `history-compact` accept the
+same explicit ID grammar through three CLI channels: comma/newline-delimited
+argv text, `-` for stdin, and `@path` for a UTF-8 file. This makes a
+read-selector-write pipeline executable without `xargs` command fan-out:
+
+```bash
+pm list --status open,in_progress --fields id,priority --json |
+  jq -r '.items[] | select(.priority >= 2) | .id' |
+  pm update-many --ids - --priority 1 --dry-run --json
+
+pm close-many --ids @reviewed-ids.txt \
+  --reason "Reviewed batch completed" --dry-run --json
+
+pm list --status closed --fields id --json |
+  jq -r '.items[].id' |
+  pm history-compact --ids - --dry-run --json
+```
+
+An unreadable `@path`, empty stdin, or empty file fails before the tracker is
+read or mutated. `unmatched_ids` means the requested ID does not exist; an
+existing ID excluded by another filter is not misreported as nonexistent.
+Apply-mode exit `6`/`7` and the structured effect receipt remain authoritative.
+
+`update-many --dry-run` may be filter-only. It returns the matched rows with an
+empty `planned_update_options` object and empty per-row `changes`, which is a
+bounded way to validate a selector before choosing a mutation. The same
+filter-only invocation without `--dry-run` is rejected with exit `2`.
+
+Direct SDK and MCP callers may pass `ids` as a string, a finite numeric scalar,
+or an array of string and finite numeric IDs. The SDK normalizes every accepted
+shape through the same stable-deduplicating parser; non-finite numbers and
+unsupported explicit selector values are rejected before target selection:
+
+```ts
+import { PmClient } from "@unbrained/pm-cli/sdk";
+
+const pm = new PmClient({ pmRoot: ".agents/pm" });
+await pm.run("update-many", {
+  options: {
+    ids: ["pm-a1b2", "pm-c3d4"],
+    priority: 1,
+    dryRun: true,
+  },
+});
+```
+
+File-reading text flags use the same stdin sentinel. `--body-file -` reads a
+create/update body, while `comments`, `notes`, and `learnings` accept
+`--file -`. Real file paths remain compatible:
+
+```bash
+generate_body | pm create --title "Generated plan" --body-file -
+render_review | pm comments pm-a1b2 --file -
+```
+
+Each command invocation may consume stdin for only one option. Competing
+stdin-backed inputs such as `--description - --body-file -` are rejected before
+the stream is read.
+
 Use NDJSON for streaming row-by-row tools:
 
 ```bash

package/docs/SDK.md

@@ -2046,6 +2046,8 @@ export default defineExtension({
     api.registerCommand({
       name: "hello",
       action: "hello",
+      tier: "standard",
+      family: "extensions",
       description: "Return a deterministic hello payload.",
       intent: "verify SDK extension activation",
       examples: ["pm hello"],
@@ -2100,6 +2102,12 @@ For a complete commands-capability package that combines `registerCommand`,
 `registerFlags`, and `registerParser`, see the first-party
 [pm-command-kit exemplar](../packages/pm-command-kit/README.md).
 
+Every command definition can declare its agent-surface `tier` (`core`,
+`standard`, `full`, or `internal`) and capability `family`. These are the same
+fields projected into CLI help, completion, MCP profiles, workspace contracts,
+and generated routing documentation. Omitted package values normalize to
+`standard` and `extensions`.
+
 For a generated starter, use `pm package init ./my-package`. Pass
 `--capability hooks` to scaffold a command plus an `afterCommand` lifecycle
 reactor and a runnable `node:test` file that exercises

package/docs/generated/AGENT_CAPABILITY_ROUTING.md

@@ -0,0 +1,17 @@
+# Generated agent capability routing
+
+Tracker: `pm-kxci8x`.
+
+This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it manually.
+
+| Capability family | Commands |
+| --- | --- |
+| workspace | `init`, `config`, `merge`, `schema`, `profile`, `telemetry`, `health`, `gc`, `workspace` |
+| intake | `create`, `copy`, `focus`, `restore` |
+| context | `list`, `aggregate`, `context`, `get`, `search`, `duplicates`, `eval`, `next`, `activity`, `stats`, `help` |
+| lifecycle | `update`, `update-many`, `close`, `close-many`, `delete`, `claim`, `release`, `start-task`, `pause-task`, `close-task` |
+| evidence | `history`, `events`, `history-redact`, `history-repair`, `history-compact`, `history-author-acknowledge`, `append`, `comments`, `notes`, `learnings`, `files`, `docs` |
+| graph | `graph`, `deps`, `plan` |
+| quality | `test`, `test-all`, `validate`, `assurance`, `contracts` |
+| automation | `meet`, `event`, `remind` |
+| extensions | `extension`, `package`, `packages`, `install`, `upgrade` |

package/docs/generated/AGENT_COMMAND_SURFACE.md

@@ -4,7 +4,7 @@ This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it ma
 
 | Command | Minimum visibility tier | Capability family |
 | --- | --- | --- |
-| `init` | full | workspace |
+| `init` | core | workspace |
 | `config` | standard | workspace |
 | `extension` | full | extensions |
 | `package` | full | extensions |