@unbrained/pm-cli 2026.8.22 → 2026.8.24

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

@@ -1,7 +1,8 @@
 # Reproducible Workspaces and Snapshots
 
-Tracked by [pm-rbcvt2](../.agents/pm/features/pm-rbcvt2.toon) and
-[pm-dkrmzv](../.agents/pm/features/pm-dkrmzv.toon).
+Tracked by [pm-rbcvt2](../.agents/pm/features/pm-rbcvt2.toon),
+[pm-dkrmzv](../.agents/pm/features/pm-dkrmzv.toon), and
+[pm-gh1089](../.agents/pm/issues/pm-gh1089.toon).
 
 These SDK primitives make a pm workspace reproducible without changing normal
 interactive behavior. Recipes control time and identifier entropy only inside
@@ -22,9 +23,7 @@ const recipe: WorkspaceRecipe = {
   seed: "example-fixture-v1",
   clock: "2026-07-28T10:00:00.000Z",
   tickMs: 1,
-  operations: [
-    { action: "create", input: { title: "Deterministic task" } },
-  ],
+  operations: [{ action: "create", input: { title: "Deterministic task" } }],
 };
 
 const results = await executeWorkspaceRecipe(
@@ -36,9 +35,9 @@ const results = await executeWorkspaceRecipe(
 The caller owns action dispatch. pm owns the deterministic execution context:
 `nowIso()` advances from `clock` by `tickMs`, and generated item identifiers
 derive from `seed`. Async scopes are isolated with `AsyncLocalStorage`, so
-concurrent recipes do not share counters. Outside `runWithWorkspaceRecipe` or
-`executeWorkspaceRecipe`, the CLI continues using the system clock and
-cryptographic randomness.
+concurrent recipes do not share counters. Normal CLI and MCP execution still
+uses the system clock and cryptographic randomness unless the process opts in
+through the environment contract below.
 
 `defineWorkspaceRecipe` immediately validates the clock, seed, tick, schema,
 operation actions, and recursively JSON-compatible inputs. Its TypeScript
@@ -51,6 +50,41 @@ Seeds are reproducibility inputs, not secrets. A replay is byte-identical only
 when it begins from equivalent authoritative state and invokes the same ordered
 operations with the same recipe.
 
+## CLI and MCP process configuration
+
+Shell-based harnesses can install the same SDK-owned deterministic context for
+the `pm` and `pm-mcp` processes without patching JavaScript globals:
+
+```bash
+PM_CLOCK=2026-07-28T10:00:00.000Z \
+PM_CLOCK_TICK_MS=1 \
+PM_SEED=example-fixture-v1 \
+pm create --title "Deterministic task" --type Task --json
+```
+
+`PM_CLOCK` and `PM_SEED` are required together. `PM_CLOCK` must be an ISO-8601
+instant with `Z` or a numeric UTC offset; timezone-less and non-ISO inputs are
+rejected so separate hosts cannot interpret the same configuration differently.
+`PM_CLOCK_TICK_MS` is optional, defaults to `1`, and must be a non-negative integer. Partial or invalid input
+fails before command dispatch with the stable
+`invalid_reproducible_process_environment` code and recovery that names the
+missing or invalid variable. Unset all three variables for normal interactive
+behavior.
+
+Every CLI process invocation begins a fresh deterministic scope. A workflow
+that launches several CLI processes must derive a stable, distinct seed for
+each ordered step; reusing one seed intentionally reproduces the same entropy
+sequence and can reproduce an existing generated identifier. A long-lived MCP
+server instead owns one process-lifetime sequence and advances it across its
+serialized JSON-RPC requests. Two equivalent servers therefore produce the
+same files without generating duplicate identifiers inside either server.
+
+The public SDK exports `PM_REPRODUCIBLE_PROCESS_ENV`,
+`resolveReproducibleProcessEnvironment`,
+`runWithReproducibleProcessEnvironment`, and
+`createReproducibleProcessRunner` for custom one-shot and long-lived process
+transports.
+
 ## Content-addressed snapshots
 
 The SDK exports:

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

@@ -1702,6 +1702,15 @@ const telemetry = await runTelemetry(
 global tracker roots. `pm_context_mode`, run-level overrides, automatic tracker
 context, assertion requirements, empty-run detection, and failure categories are
 part of the SDK result contract rather than presentation-layer behavior.
+Workspace results distinguish the run-level requested mode from the effective
+per-test mode. `isolated` executes from an empty disposable directory;
+`snapshot` executes from a filtered disposable workspace. Trust preflight
+failures report `trust_refusal`, while malformed or incomplete provenance uses
+the additive `provenance_invalid` storage marker and fail-closed
+`invalid_provenance` trust reason. Package mutation adapters can call
+`attachLinkedTestMutationProvenance` so Git inspection occurs only when commands
+are added; `resolveLinkedTestSourceWorkspaceRoot` keeps their source-ref lookup
+aligned with CLI execution and `PM_SOURCE_WORKSPACE_ROOT` overrides.
 When item test-result tracking is enabled, `measure` persists typed numeric
 evidence on the producing run. Each entry has a stable name, finite numeric
 value, optional unit and threshold, and the run timestamp. Run history remains
@@ -2037,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"],
@@ -2091,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/SDK_AGENT_SESSION_CONTEXT.md

@@ -6,7 +6,8 @@ Tracker references: [pm-9wbiye](../.agents/pm/issues/pm-9wbiye.toon),
 [pm-3zgh2c](../.agents/pm/features/pm-3zgh2c.toon),
 [pm-eq9dlw](../.agents/pm/issues/pm-eq9dlw.toon), and
 [pm-lu6sca](../.agents/pm/features/pm-lu6sca.toon), plus
-[pm-5q8wa0](../.agents/pm/issues/pm-5q8wa0.toon).
+[pm-5q8wa0](../.agents/pm/issues/pm-5q8wa0.toon) and
+[pm-c0lrdm](../.agents/pm/features/pm-c0lrdm.toon).
 
 Project management is context management. The public SDK therefore carries a
 session's purpose and episode boundary through the same immutable history that
@@ -128,9 +129,10 @@ public SDK exports for custom hosts.
 the bounded built-in resolver. It never contains environment values, session
 paths, prompts, or file contents.
 
-New mutation history records failed resolver outcomes under
-`context.agent_provenance_outcomes`; ordinary unavailable dimensions retain
-the compact legacy-compatible null projection. A resolver is only counted as
+New mutation history records failed or explicitly unavailable configured
+resolver outcomes under `context.agent_provenance_outcomes`; dimensions with
+no configured resolver retain the compact legacy-compatible null projection.
+A resolver is only counted as
 attempted when its required input belongs to the detected harness; a foreign
 host's shared `AI_AGENT` value is not Codex input. Consequently `pm health` can report
 `provenance_resolver_zero_success:<harness>:<dimension>:<resolver>:<attempts>`

package/docs/SDK_EVIDENCE_TRACEABILITY.md

@@ -111,7 +111,7 @@ pair pre-redaction item content with post-redaction history during validation.
 
 ## Operational receipts
 
-Linked tests recognize compound acquisition failures such as “could not acquire … lock” together with contention context such as “already running” or “held by another” as `infra_collision`. Generic assertion text mentioning a lock or timeout remains `assertion_failure`, preventing false infrastructure classifications.
+Linked tests recognize compound acquisition failures such as “could not acquire … lock” together with contention context such as “already running” or “held by another” as `infra_collision`. Generic assertion text mentioning a lock or timeout remains `assertion_failure`, preventing false infrastructure classifications. A command refused by clone-local provenance policy is classified separately as `trust_refusal`, so reports do not misstate a pre-execution safety decision as an assertion failure.
 
 Telemetry flush receipts distinguish progress from completion:
 

package/docs/TESTING.md

@@ -2,7 +2,7 @@
 
 This page describes safe local tests, linked tests, coverage, and release-readiness checks.
 
-Tracked implementation updates: [pm-52eh](../.agents/pm/features/pm-52eh.toon), [pm-mcxr](../.agents/pm/issues/pm-mcxr.toon), [pm-u42x](../.agents/pm/issues/pm-u42x.toon), [pm-atfm](../.agents/pm/features/pm-atfm.toon), [pm-xmp5](../.agents/pm/tasks/pm-xmp5.toon), [pm-39cqqx](../.agents/pm/tasks/pm-39cqqx.toon), [pm-5cgm2z](../.agents/pm/chores/pm-5cgm2z.toon), [pm-avv3wx](../.agents/pm/issues/pm-avv3wx.toon), [pm-rizqb6](../.agents/pm/issues/pm-rizqb6.toon), [pm-95h7pg](../.agents/pm/issues/pm-95h7pg.toon), [pm-giks4s](../.agents/pm/issues/pm-giks4s.toon), [pm-xa3t0o](../.agents/pm/issues/pm-xa3t0o.toon).
+Tracked implementation updates: [pm-52eh](../.agents/pm/features/pm-52eh.toon), [pm-mcxr](../.agents/pm/issues/pm-mcxr.toon), [pm-u42x](../.agents/pm/issues/pm-u42x.toon), [pm-atfm](../.agents/pm/features/pm-atfm.toon), [pm-xmp5](../.agents/pm/tasks/pm-xmp5.toon), [pm-39cqqx](../.agents/pm/tasks/pm-39cqqx.toon), [pm-5cgm2z](../.agents/pm/chores/pm-5cgm2z.toon), [pm-avv3wx](../.agents/pm/issues/pm-avv3wx.toon), [pm-rizqb6](../.agents/pm/issues/pm-rizqb6.toon), [pm-95h7pg](../.agents/pm/issues/pm-95h7pg.toon), [pm-giks4s](../.agents/pm/issues/pm-giks4s.toon), [pm-xa3t0o](../.agents/pm/issues/pm-xa3t0o.toon), [pm-e97jyf](../.agents/pm/issues/pm-e97jyf.toon), [pm-efkvdy](../.agents/pm/issues/pm-efkvdy.toon), and [pm-ed28wi](../.agents/pm/issues/pm-ed28wi.toon).
 
 ## Agent Quick Context
 
@@ -372,11 +372,14 @@ Diagnostic ceilings share the executable refusal gate:
 pnpm quality:recovery-closure
 ```
 
-The gate replays 22 refusal contracts and ratchets ten representative failure
-paths against `PM_DIAGNOSTIC_OUTPUT_BUDGET_CONTRACTS`. Every diagnostic must fit
-its declared JSON ceiling and preserve a mechanically actionable correction;
-the missing-probe negative control proves that the diagnostic corpus cannot
-silently shrink.
+The gate replays 117 refusal contracts: 18 closed-domain rows, 88
+grammar-derived required-argument omissions, seven closed positional-action
+families, and four tracker-preflight states. It also ratchets ten representative
+failure paths against `PM_DIAGNOSTIC_OUTPUT_BUDGET_CONTRACTS`. Every diagnostic
+must fit its declared JSON ceiling and preserve a mechanically actionable
+correction; executable retry argv is never collection-truncated. The
+missing-probe negative control and the authoritative tracker-state snapshot
+prove that the corpus cannot silently shrink or turn a refusal into a mutation.
 
 The gate derives every supported harness, model, session, and provenance
 environment key from the SDK-owned harness descriptor registry. It deletes
@@ -441,6 +444,69 @@ into constrained temporary storage.
 Capacity, permission, and resource failures while seeding a required tracker
 surface as typed, path-redacted host-environment refusals with recovery steps.
 
+## Source Workspace Modes
+
+Linked tests have a separate source-workspace contract. Store a default on one
+entry with `workspace_context_mode`, or choose a run-level mode with
+`--workspace-context`:
+
+```bash
+pm test <item-id> --add-json '{"command":"pnpm quality:static","workspace_context_mode":"isolated"}'
+pm test <item-id> --run --workspace-context snapshot --override-linked-workspace-context
+```
+
+- `source` (default) runs in the source checkout and exposes its read-only
+  source-context environment, preserving existing linked-test behavior.
+- `isolated` runs from an empty disposable directory and removes
+  `PM_SOURCE_WORKSPACE_ROOT`, `PM_SOURCE_PM_PATH`, and the source-context access
+  declaration. Use it only for commands that do not require checkout files.
+- `snapshot` copies the workspace into the linked-test sandbox, runs from that
+  copy, and binds its `.agents/pm` path to the selected temporary tracker.
+  `.git`, `.agents`, `node_modules`, coverage output, and common cache
+  directories are excluded at every directory depth; an existing top-level
+  `node_modules` is linked read-only by convention. Built output remains
+  available so linked commands such as `node dist/cli.js` keep working. Writes
+  therefore land in the disposable snapshot rather than the source checkout.
+
+Every result reports the requested/effective workspace mode, working
+directory, exposed source root, and trust decision. Recorded `test_runs` retain
+the effective workspace mode and trust reason beside the command.
+
+## Linked-Test Command Trust
+
+Linked commands are stored shell programs, so merge-unioned tracker data is an
+execution boundary. New command entries record author, creation time, source
+branch when available, and whether the item merge driver introduced the entry.
+Locally created commands keep their previous run behavior. Commands marked as
+merge-unioned or carrying a different source ref fail before process creation.
+Malformed provenance is sanitized to the additive `provenance_invalid` marker
+and receives the same fail-closed treatment; it is never normalized into a
+trusted legacy command.
+These pre-execution refusals use the `trust_refusal` failure category, separate
+from command or assertion failures.
+
+Choose one explicit recovery:
+
+```bash
+# Review and trust the item's current command fingerprints in this clone.
+pm test <item-id> --acknowledge-linked-tests
+
+# Or permit a single reviewed run. Both controls are required.
+pm config project set untrusted-linked-test-execution enabled
+pm test <item-id> --run --allow-untrusted-linked-tests
+```
+
+Acknowledgments live in the clone-local ignored runtime directory and bind to
+the full command, tracker/workspace context, environment controls, host-safety
+mode, and provenance fingerprint; editing any of those fields requires a new
+review. Enabling the project policy alone never executes
+an untrusted command, and the per-run flag alone is also refused. Inspect all
+unacknowledged entries without executing them with:
+
+```bash
+pm validate --check-command-references --verbose-diagnostics
+```
+
 Use explicit modes when needed:
 
 ```bash
@@ -493,8 +559,9 @@ pm test <item-id> --metric-below coverage=100 --metric-diff p95_latency
 Measurements are stored on the producing `test_runs` row, retained with the
 bounded run history, and exposed consistently by CLI, SDK, MCP, and contracts.
 Each recorded row also keeps a bounded `executions` list with the exact linked
-command plus its requested and effective `pm_context_mode`, so tracker-backed
-verification remains attributable after the transient process logs are gone.
+command, requested/effective `pm_context_mode`, effective workspace mode, and
+trust reason, so tracker-backed verification remains attributable after the
+transient process logs are gone.
 
 ## Linked-Test Assertions
 

package/docs/agent-task-token-baseline.json

@@ -18,8 +18,8 @@
     },
     {
       "id": "failing-command",
-      "max_estimated_tokens": 200
+      "max_estimated_tokens": 219
     }
   ],
-  "composite_max_estimated_tokens": 2178
+  "composite_max_estimated_tokens": 2197
 }

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 |

package/docs/generated/FLAG_LEXICON_BUDGETS.md

@@ -55,8 +55,8 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
 | `docs` | evidence | 30 | 30 |
 | `deps` | graph | 32 | 32 |
 | `plan` | graph | 109 | 109 |
-| `test` | quality | 48 | 48 |
-| `test-all` | quality | 37 | 37 |
+| `test` | quality | 52 | 52 |
+| `test-all` | quality | 40 | 40 |
 | `telemetry` | workspace | 21 | 21 |
 | `stats` | context | 29 | 29 |
 | `health` | workspace | 36 | 36 |