@unbrained/pm-cli 2026.9.27 → 2026.9.29

package/docs/ECOSYSTEM_PLANNING_REVIEW.md

@@ -0,0 +1,270 @@
+# Ecosystem planning review — 2026-09-28
+
+Tracked by [pm-p9a4](../.agents/pm/tasks/pm-p9a4.toon),
+[pm-m08hza](../.agents/pm/decisions/pm-m08hza.toon),
+[pm-1jzupz](../.agents/pm/features/pm-1jzupz.toon), and
+[pm-wg07](../.agents/pm/chores/pm-wg07.toon).
+
+Project management = context management. This review records a complete
+structural census, targeted semantic review, measured operational checks, and
+planning decisions on existing canonical items. It does not certify that every
+historical sentence is correct or that every future capability is implemented.
+Read the live item before acting on this dated evidence.
+
+## Population and evidence
+
+The strict CLI snapshot at `2026-09-28T05:40:12.139Z` contains 2,826 items:
+2,532 closed, 221 open, 59 draft, and 14 canceled. No records or fields were
+omitted, and no item or directory was unreadable. Blocking is also a derived
+dependency condition: the initial orientation reported 60 blocked open items,
+although no item used a literal `blocked` lifecycle status.
+
+The cursor-resumed event read collected 68,876 complete events from 2,841
+streams through `2026-09-28T05:41:59.143Z`, including deleted-item and workspace
+history. All 23 Plan items also received deep plan reads for steps, decisions,
+validation and resume metadata. This later cutoff includes the first review claim/comment events;
+it is not silently equated with the earlier item snapshot. History-drift
+validation passed across all 2,826 current items. The public SDK independently
+verified hash chains for all 2,841 collected streams with zero failures.
+
+[The per-item census](ecosystem-review-2026-09-28.json) records every snapshot
+ID, status, content fingerprint, structural classification, missing planning
+fields, historical evidence gaps, and remediation owner. These are mechanical
+findings, not invented historical estimates, outcomes, or review approvals.
+The full raw corpus stays outside public documentation.
+
+| Measure | Initial observation | Interpretation |
+| --- | ---: | --- |
+| Directed graph edges | 14,097 | Deduplicated directed basis |
+| Ordering layers / critical-path edges | 12 / 11 | Acyclic prerequisite graph |
+| Missing graph endpoints / isolated items | 0 / 0 | Across all statuses |
+| Active / terminal outcome-unreachable items | 0 / 0 | Typed reachability basis |
+| Generic `related` edges | 5,589 | 39.65% of directed edges |
+| Specialized semantic edges | 1,885 | Discovery, recurrence, incident, verification, supersession |
+| Items without a specialized semantic edge | 1,463 | 86 active, 1,377 terminal; not necessarily invalid |
+| Legacy hierarchy exceptions | 7 children | Existing informational cardinality/direction findings |
+| Closed items missing structured resolution evidence | 170 | Preserved residual, not a new regression |
+| Active items missing required planning fields | 1 | Sentry major-upgrade item, repaired in this review |
+| Tracked non-tracker artifacts with exact item links | 1,921 / 1,921 | Path ownership, not proof for every code change |
+| Duplicate candidate clusters | 28 | Reviewed candidates, not 28 duplicate obligations |
+
+Scanner records with different provider identities, parent/child acceptance
+slices, distinct incidents and dated release executions remain separate. The
+three identically titled accidental probes are already canceled. Similar audit
+titles require their own event/acceptance comparison before any consolidation.
+No existing item was deleted or closed merely because it matched a title.
+
+## Graph organization
+
+Use one structural parent and outcome paths for scope, `implements` for delivery,
+`blocked_by` for an actual prerequisite, `discovered_from` for provenance,
+`verifies` for verification responsibility, and `recurs_from` only for an
+established recurring mechanism. Maintain prior evidence when correcting a link.
+A declaration that an item will verify something is not a passing test result.
+
+The native reconstruction plan retains its original execution obligations;
+overlapping newly added steps are explicitly superseded by their existing owners,
+and a dated census checkpoint records the completed refresh.
+
+The planning pass restores explicit missing prerequisites in prospective
+reminders, cross-branch relevance and external-package verification. The
+historical batch restores three `discovered_from` edges to the governance run
+whose original comment explicitly named the discoveries. Their release and
+closure evidence remain unchanged. Generic links and transitive ordering
+shortcuts are not added to meet density or depth targets.
+
+[pm-qnl2](../.agents/pm/tasks/pm-qnl2.toon) owns active enrichment;
+[pm-lnrk](../.agents/pm/tasks/pm-lnrk.toon) owns historical batches;
+[pm-pj2isb](../.agents/pm/chores/pm-pj2isb.toon) owns misleading placeholder
+metadata. The completed [pm-e9zh](../.agents/pm/chores/pm-e9zh.toon) preserves
+its explicitly unrecoverable 170-item residual. A missing historical observation
+must remain unknown until independent evidence is found.
+
+After this pass the live graph contains 2,829 items and 14,118 directed edges,
+including 1,894 specialized semantic edges. Generic `related` is 5,590 after one
+reviewed correction from causal provenance to non-causal coordination; no dangling endpoints, isolated items or ordering contradictions were
+introduced. Outcome reachability remains 100%. The 1,458 records without a
+specialized semantic edge remain visible for evidence review; absence alone
+does not justify inventing a relationship.
+
+## Horizon and outcome organization
+
+These are planning windows, not delivery promises. Capacity, prerequisites and
+measured evidence govern promotion. Priority measures impact; horizon measures
+readiness and uncertainty. Review monthly and when a material observation changes.
+
+| Horizon | Illustrative window | Canonical outcomes and promotion evidence |
+| --- | --- | --- |
+| Current | 0–3 months | [Agent-legible grammar](../.agents/pm/milestones/pm-j82fd3.toon), active readiness, retrieval failures, release diagnosis and current protocol proof. Require completed-task token comparisons, preserved compatibility and actual installed-consumer evidence. |
+| Emerging | 3–12 months | [Provable history](../.agents/pm/milestones/pm-w7ccmv.toon), reproducible observations and [measured self-improvement](../.agents/pm/milestones/pm-zzylb9.toon). Require independent replay, mutation coverage and three consecutive measured improvement cycles. |
+| Expansion | 12–36 months | [Proven scale](../.agents/pm/milestones/pm-o87av6.toon), [universal domain platform](../.agents/pm/milestones/pm-t4d7nz.toon), [federated agents](../.agents/pm/milestones/pm-z1kr34.toon). Require published million-item/fleet distributions and SDK-only domain exemplars. |
+| Exploratory | 36+ months | [Multi-decade continuity](../.agents/pm/milestones/pm-ljrh29.toon) and independently evaluated cognitive mechanisms. Require explicit architecture decisions, migration proofs, calibrated uncertainty and rejection criteria. |
+
+The [SDK-complete outcome](../.agents/pm/milestones/pm-9rgaal.toon) and
+[GA stability contract](../.agents/pm/milestones/pm-xp1xsw.toon) retain their own
+acceptance boundaries. Earlier SDK promotion work remains completed history;
+future integrations must use published SDK contracts and expose gaps as individual
+items. New names or parallel roadmap trees do not improve traceability.
+
+## Concrete planning refinements
+
+- **Command simplicity:** root help already has thirteen entries including help.
+  Evaluate the remaining grammar through complete orient/retrieve/claim/mutate/
+  verify/close and recovery journeys. Preserve working aliases and capabilities.
+  Count tokens across errors, retries, cursor pages and contract discovery.
+  The new [Plan receipt issue](../.agents/pm/issues/pm-hqy7lr.toon) records
+  whole-plan output amplification observed during single-step mutations; its
+  acceptance requires bounded SDK-owned receipts and preserved full inspection.
+- **Algorithms:** the [existing portfolio](CONTEXT_ALGORITHM_PORTFOLIO.md)
+  remains authoritative. Individual items now detail bounded candidate quotas,
+  evidence coverage per token, typed spreading activation, activation decay,
+  approximate affinity sketches and content-addressed summary trees. Each names
+  inputs, costs, fallback, negative controls and a promotion/rejection rule.
+  Mathematical guarantees require their assumptions; a heuristic is not a proof.
+- **Scale and branches:** separately measure cold build and warm reads at 3,
+  100,000 and 1,000,000 items, and 1/10/100/1,000 agents. Exercise partitions,
+  retries, expired claims, clock skew and arbitrary merge order. Record p50/p95/
+  p99, memory, index amplification and no-lost-acknowledged-write evidence.
+- **Recursive improvement:** bind observe, propose, evaluate, land and remeasure
+  stages to immutable evidence. Keep the evaluator and held-out data independent
+  of the change under evaluation. Rejected proposals stay searchable.
+- **Universal environments:** episodes use SDK reset/observe/step/score contracts,
+  seeded snapshots, idempotent actions, independent verdicts and temporal cutoffs.
+  Distinguish termination from truncation and prevent future-evidence leakage.
+- **Durability:** append-only API behavior, hash-chain tamper evidence,
+  authenticated authorship and externally anchored proof are different guarantees.
+  Migration, redaction and cryptographic rotation need explicit restore tests.
+
+## Verified behavior and remaining limits
+
+### Local qwen3 retrieval
+
+The project already selects local Ollama `qwen3-embedding:0.6b`. Refresh embedded
+1,085 stale inputs in 34 requests, with zero retries or splits, at approximately
+11.91 inputs/second. This proves multi-input batching at the current corpus size;
+it does not prove the outstanding 100k/1M performance acceptance.
+
+Five project golden queries were evaluated at k=10:
+
+| Mode | Mean nDCG | Mean MRR | Mean recall | Broad history/episode query recall |
+| --- | ---: | ---: | ---: | ---: |
+| Keyword | 0.7451 | 0.80 | 0.8727 | 4/11 |
+| Semantic | 0.7944 | 0.85 | 0.8182 | 1/11 |
+| Hybrid | 0.8405 | 0.90 | 0.8364 | 2/11 |
+
+Aggregate passes conceal weak queries. The existing retrieval-quality owner
+[pm-p1g43q](../.agents/pm/features/pm-p1g43q.toon) now carries this observation,
+feasible per-query floors, held-out paraphrase evaluation and mode comparisons.
+At k=10, a query with eleven relevant items cannot attain recall 1. The final
+semantic index check covered all 2,829 current items with zero stale vectors.
+
+### MCP and SDK
+
+The official [versioning page](https://modelcontextprotocol.io/docs/2026-07-28/learn/versioning)
+identifies `2026-07-28` as current. The repository
+[conformance matrix](MCP_2026_07_28_CONFORMANCE.md) was compared with the official
+[key changes](https://modelcontextprotocol.io/specification/2026-07-28/changelog).
+The focused SDK, stateless stdio, Streamable HTTP and legacy-handshake run passed
+145 tests in twelve files. Exact-version public verification also passed direct
+and package-selected npx/bunx CLI dispatch, MCP discovery, Skills, Apps and HTTP,
+including missing-bin negative controls. This is focused conformance evidence, not an assertion
+that every optional extension or every deployment is certified. Deprecated
+features must not be newly advertised merely to increase a feature count.
+
+Ordinary review mutations recorded detected Codex identity, model and effort
+without `PM_AUTHOR` or author flags. Role/topic inference carries its source and
+confidence. Missing signals remain unknown; configuration is not native proof.
+
+### Daily release
+
+Version `2026.9.28` exists in npm and GitHub. The
+[original automatic attempt](https://github.com/unbraind/pm-cli/actions/runs/36375818142)
+failed after Windows global npm installation failed in the child release run.
+The [same-version recovery](https://github.com/unbraind/pm-cli/actions/runs/36380136948)
+passed npm, global npm and Bun on Linux, macOS and Windows and advertised the
+existing version. It did not create a second automatic version that day.
+
+The new [installer-diagnostics issue](../.agents/pm/issues/pm-q7c36n.toon)
+records why the original cause remains unknown: the subprocess wrapper discards
+error/signal details and the installer labels every retry registry availability.
+Recovery proves the artifact can pass; it does not erase the failed attempt or
+establish its cause. Keep automatic reliability, publication and consumer
+acceptance as separate measurements.
+
+## Prevention and repeatability
+
+Six active-only zero-debt assertions now join `tracker-context-quality` for
+missing description, acceptance criteria, risk, confidence, estimate and expected
+result. The existing local and hosted quality pipeline invokes this same native
+SDK gate. Terminal evidence gaps are deliberately outside the active-only policy.
+An isolated temporary workspace failed all six assertions with missing fields
+and passed all six after repair. This checks presence; semantic quality still
+requires evidence review.
+
+For repeat reviews, follow the
+[ecosystem planning skill](../.agents/skills/pm-user/references/ECOSYSTEM_PLANNING.md).
+Use complete CLI snapshots outside the prompt, cursor-resumed event streams,
+exact source fingerprints, all-status duplicate checks and bounded mutation
+batches. At million-item scale, use streaming/indexed consumers rather than
+loading a whole JSON collection into the agent's context. Every changed item
+retains its canonical owner, history and original acceptance boundary.
+
+## Verification record
+
+Quiescent validation passed for all 2,829 final items. The 170 historical
+structured-evidence warnings are unchanged. All 38 changed history streams pass
+the public SDK chain verifier; the 35 pre-existing streams retain byte-identical
+historical prefixes. The three enriched closed features retain identical status,
+closure, resolution and release fields. Final graph-composition and all 47
+tracker-context-quality assertions pass, including the six new readiness rules.
+
+An earlier long-running context gate saw one history-drift failure while this
+review was still mutating the tracker. Independent validation and the final gate
+pass with writes stopped; the earlier result is retained as a concurrent-read
+observation, not rewritten as success. Skill/document validation, local links
+and the generated changelog check also pass. All review claims are released. Three distinct issues were added after duplicate
+checks: installer diagnostics, Plan mutation receipts and startup admission
+diagnosis. Existing programmes retain their original acceptance boundaries.
+
+The broad static run passed its build, lint, generated contracts, SDK parity,
+command grammar, task-token, MCP deprecation, gate-registry and context-quality
+checks, then failed the import-cost timing gate (bare Node median 305 ms against
+106 ms). An isolated rerun passed all ten SDK entrypoints with unchanged budgets.
+The initial timing failure remains part of the evidence; it is not a continuous
+all-green static invocation.
+
+The remaining graph and record-integrity gates passed. The mutation gate passed
+with 323 of 330 mutants killed and seven classified as equivalent. The CLI
+transport benchmark initially exceeded its list threshold (442 ms versus 419 ms);
+the isolated rerun also failed: get 385/362 ms, context 466/433 ms, next
+457/440 ms and create 424/398 ms. No performance limit was raised. The new
+[startup investigation](../.agents/pm/issues/pm-bj7rq0.toon) distinguishes runner
+qualification from a demonstrated product regression and preserves the completed
+transport-floor implementation. This is an unresolved validation limitation.
+
+## PR review corrections
+
+PR #1333 identified two overly broad relationship claims. The standing release
+reminder predates the new installer-diagnostics issue, so their link is `related`
+coordination rather than `discovered_from` provenance. Four `verifies` rows from
+the historical batch were removed: checking citations, history continuity and
+release attribution does not verify the source run or feature behavior. The three
+source-backed discovery links on closed features remain valid and unchanged.
+
+The original writes and their corrections remain in immutable history. Five
+holder/target/text-scoped citation exemptions distinguish the batch inventory
+from verification claims without raising the prose-edge ceiling. The corrected
+graph-composition gate passes.
+
+The follow-up review narrowed those five exemptions to the complete original
+paragraphs, including their historical source-event coordinates. In an isolated
+temporary tracker the original citations pass, while a later batch comment
+asserting an unrecorded prerequisite is blocked with one detected gap. This
+prevents the common phrase “Historical batch” from exempting future claims.
+
+Annotation review corrected 26 notes and five comments that contained literal
+JSON wrappers around prose. Supported note/comment edits retain the exact inner
+text and append correction events. Per-item rereads confirm lifecycle, closure,
+release, expected and actual fields are unchanged; original annotations remain
+in the history streams. Planning guidance now distinguishes plain-text input
+from intentional JSON events.

package/docs/PACKAGE_EVIDENCE.md

@@ -1,8 +1,10 @@
 # Install Plans and Update Evidence
 
-Tracked by [pm-5bsofk](../.agents/pm/issues/pm-5bsofk.toon) and
+Tracked by [pm-erogk1](../.agents/pm/issues/pm-erogk1.toon),
+[pm-5bsofk](../.agents/pm/issues/pm-5bsofk.toon) and
 [pm-gf5zw8](../.agents/pm/issues/pm-gf5zw8.toon), with claim controls tracked by
-[pm-eqdo85](../.agents/pm/issues/pm-eqdo85.toon).
+[pm-eqdo85](../.agents/pm/issues/pm-eqdo85.toon) and Git metadata exclusion by
+[pm-k7nxaz](../.agents/pm/issues/pm-k7nxaz.toon).
 
 ## Install planning
 
@@ -10,17 +12,26 @@ Preview an install with `pm package install ./local-package --project --dry-run`
 The `details.install_plan` receipt distinguishes directory, archive, npm, and
 GitHub sources and reports logical file bytes, file/directory/link counts, and
 the copy policy. External local directories are directory snapshots, including
-development artifacts; nested destinations exclude `.agents`, `node_modules`,
-and installer backup directories at every depth using the installer's filter.
-Counts are lower bounds when `complete` is false, with `stop_reason`
-identifying the entry or depth limit. A source-directory alias resolves to its
+development artifacts other than `.git`. All copied directory sources exclude
+`.git` entries at every depth, including worktree files and symlinks, and count
+those entries in `excluded_entries`. Nested destinations also exclude `.agents`,
+`node_modules`, and installer backup directories at every depth using the
+installer's filter.
+The bounded planner can return lower-bound counts with `complete: false` and a
+`stop_reason` when called directly. Installing a local directory now refuses
+that incomplete scan in both dry-run and real modes before writing or
+activating. SDK callers receive
+`extension_install_incomplete_source_scan`; the CLI exits nonzero with the
+entry or depth limit and a packed-archive recovery step. That recovery keeps
+the requested `--project` or `--global` installation scope. A source-directory
+alias resolves to its
 directory before copying; symlink entries inside the source remain links and
 their targets are never traversed.
 Planning writes no destination files, managed state, or activation settings;
 archive and remote source resolution can still prepare temporary source files
 and perform network or dependency-resolution work.
 
-For development-heavy or incomplete local snapshots, `packed_alternative`
+For development-heavy local snapshots, `packed_alternative`
 provides argument vectors for `npm pack --ignore-scripts --json` and archive
 installation. Run packing in its reported `cwd`, substitute the returned
 `pack_result[0].filename`, and install the resulting archive. Normal local

package/docs/README.md

@@ -34,6 +34,7 @@ pm guide release --json
 - [Quickstart](QUICKSTART.md) - install, initialize, create, claim, link, test, close.
 - [Onboarding](ONBOARDING.md) - first-two-hours maintainer and contributor setup.
 - [Agent Guide](AGENT_GUIDE.md) - canonical agent loop, tracker linking, and token-minimal command choices.
+- [Agent Read and Test Receipts](AGENT_READ_AND_TEST_RECEIPTS.md) - JSON help provenance, linked-test persistence, and history diff continuation.
 - [Command Reference](COMMANDS.md) - command families with examples and when to use each family.
 - [Context and Operations Namespaces](COMMAND_NAMESPACES.md) - native navigation, diagnostics, event streams, and compatibility aliases.
 - [CLI Scripting Contract](SCRIPTING.md) - exit codes, flat mutation receipts versus read envelopes, stdout/stderr boundaries, stable JSON fields, uniform OR filters, and shell composition recipes.
@@ -58,6 +59,7 @@ pm guide release --json
 - [Context Relevance and Packing](CONTEXT_RELEVANCE.md) - shared CLI/SDK signals, derived-store provenance, ranking explanations, and token budgets.
 - [Next-work Selection Budgets](NEXT_SELECTION_BUDGETS.md) - bounded executable recommendations, omission receipts, and graded 10k/100k context verification.
 - [Context Algorithm Portfolio](CONTEXT_ALGORITHM_PORTFOLIO.md) - stable proposal slugs, historical aliases, individual owners, cognitive compositions, and experiment gates.
+- [Ecosystem Planning Review](ECOSYSTEM_PLANNING_REVIEW.md) - dated all-status census, canonical horizons, operational evidence, and active-readiness gates.
 - [Output Projection and Omission Contracts](OUTPUT_PROJECTION_CONTRACTS.md) - explicit withheld-field receipts, mode-paired row keys, and completion resolver outcomes.
 - [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.

package/docs/SDK_EVIDENCE_TRACEABILITY.md

@@ -103,12 +103,46 @@ Replacement requires at least one corresponding `--file` or `--doc` value and ca
 
 Repeating an already-present `pm files --add` or `pm docs --add` batch is a true no-op: `changed` is false, the item file is not rewritten, and append-only history receives no synthetic mutation entry.
 
+An explicit non-empty replacement note updates the existing path/scope entry
+atomically. A bare-path retry preserves its note; a different scope identifies
+a separate link. The same rule applies to glob additions and standalone
+`--note`. Migration collisions first retain the established last matching
+entry; an explicit note revision then applies to that surviving identity.
+This fixes [pm-zqxlfs](../.agents/pm/issues/pm-zqxlfs.toon):
+
+```bash
+pm files <id> --add path=src/new.ts,note="verified current implementation"
+pm docs <id> --add docs/new.md --note "verified current contract"
+```
+
 Audited history redaction participates in the same projection transaction as
 ordinary item mutation. After rewriting an item and its history stream, pm
 invalidates drift verification state and incrementally refreshes the metadata
 index before releasing the derived-index lock. A warmed index therefore cannot
 pair pre-redaction item content with post-redaction history during validation.
 
+## Compact Plan mutation receipts
+
+Tracked by [pm-hqy7lr](../.agents/pm/issues/pm-hqy7lr.toon).
+CLI and MCP Plan mutations return identity, action, step identity when available,
+complete step counts, materialization/skip/warning counts, and an inspection
+command. They omit bodies, resume context, and unrelated steps, so a single-step
+update does not grow with the Plan. `pm plan show <id> --depth deep` retrieves
+the complete current Plan without repeating a mutation. The omission receipt
+explicitly distinguishes this acknowledgement from a full read.
+Local CLI/SDK recovery commands include the resolved `--pm-path`, safely quoted,
+so they inspect the same tracker even with a non-default root. MCP receipts
+omit the server-resolved filesystem root in both compact and full output.
+For MCP recovery, call `pm_plan` with `subcommand: "show"`, `depth: "deep"`,
+the receipt ID, and the original request's workspace selection (`path` or `cwd`).
+
+SDK `runPlan` retains its full typed result and adds `mutation_receipt` for
+consumers that need a compact acknowledgement. Existing full transport output
+is available with CLI `--full-changed-fields` or MCP `fullChangedFields: true`.
+The named `PlanMutationReceipt` type is exported from `@unbrained/pm-cli/sdk`.
+CLI `--no-changed-fields` also selects a compact Plan receipt.
+Read-only `plan show` retains its existing projection behavior.
+
 ## 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. 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.

package/docs/TESTING.md

@@ -2,17 +2,22 @@
 
 This page describes safe local tests, linked tests, coverage, and release-readiness checks.
 
+Current linked-test and merge-fence work: [pm-t05d8d](../.agents/pm/issues/pm-t05d8d.toon), [pm-kynkl8](../.agents/pm/issues/pm-kynkl8.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), [pm-ed28wi](../.agents/pm/issues/pm-ed28wi.toon), and [pm-5ug5xq](../.agents/pm/issues/pm-5ug5xq.toon).
 
 ## Agent Quick Context
 
 - Unit and integration tests must not read or write real `.agents/pm` data.
 - Prefer `node scripts/run-tests.mjs ...` because it creates sandboxed `PM_PATH` and `PM_GLOBAL_PATH`.
-- Linked-test execution injects isolated `PM_PATH` and `PM_GLOBAL_PATH` for
-  every command and applies stored-command provenance checks before process
+- Linked-test execution injects isolated `PM_GLOBAL_PATH` and normally
+  `PM_PATH`; `pm_context_mode=none` omits `PM_PATH` for self-isolating SDK tests
+  in disposable workspaces. It applies stored-command provenance checks before process
   creation. Direct runners are accepted; prefer
   `node scripts/run-tests.mjs ...` when the repository provides it because the
-  wrapper also reproduces build, coverage, and cleanup policy.
+  wrapper also reproduces build, coverage, and cleanup policy. Use a direct
+  runner when a `none`-mode test must observe an unset `PM_PATH`; the wrapper
+  creates its own sandboxed `PM_PATH`.
 - Run linked tests before closing the item that owns the work.
 
 Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
@@ -510,6 +515,11 @@ only their schema roots; a non-PM command explicitly configured with
 data are materialized only when at least one selected command requires tracker
 context. This preserves source isolation without copying an unrelated tracker
 into constrained temporary storage.
+For SDK tests that create independent temporary PM roots, use
+`pm_context_mode: "none"` with `workspace_context_mode: "isolated"` or
+`"snapshot"`. The runner omits `PM_PATH` so each SDK client can resolve its
+explicit workspace independently; `PM_GLOBAL_PATH` remains sandboxed. Source
+workspace execution and direct PM commands refuse this mode before execution.
 Capacity, permission, and resource failures while seeding a required tracker
 surface as typed, path-redacted host-environment refusals with recovery steps.
 When a legacy source tracker has settings but no `_workspace` history, tracker
@@ -593,6 +603,7 @@ Use explicit modes when needed:
 pm test <item-id> --run --pm-context schema
 pm test <item-id> --run --pm-context tracker
 pm test <item-id> --run --pm-context auto --check-context --auto-pm-context
+pm test <item-id> --add-json '{"command":"pnpm exec vitest run tests/integration/linked-test-context-trust.integration.spec.ts","pm_context_mode":"none","workspace_context_mode":"snapshot"}'
 ```
 
 For complex linked-test commands, prefer JSON input so shell syntax survives unchanged:

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

@@ -1,7 +1,7 @@
 {
   "version": 4,
   "transcript_version": 2,
-  "transcript_digest": "sha256:b8a6aea318c41e6a40dbcaf8094da8397ca747515a7df249d35c1f21ad94a307",
+  "transcript_digest": "sha256:6d4041acfaa4075dde1972d6127a74f18916f7661738b4f5d5fd47a61c179a78",
   "estimator": "ceil(utf8_bytes / 4)",
   "measurement_scope": "output_before_token_accounting",
   "published_with_release": true,
@@ -259,7 +259,33 @@
           "accounting_mode": "self_reported"
         }
       ]
+    },
+    {
+      "id": "plan-execution-mutations",
+      "max_estimated_tokens": 848,
+      "steps": [
+        {
+          "id": "create-plan",
+          "max_estimated_tokens": 21,
+          "accounting_mode": "self_reported"
+        },
+        {
+          "id": "add-step",
+          "max_estimated_tokens": 275,
+          "accounting_mode": "self_reported"
+        },
+        {
+          "id": "complete-step",
+          "max_estimated_tokens": 274,
+          "accounting_mode": "self_reported"
+        },
+        {
+          "id": "inspect-plan",
+          "max_estimated_tokens": 278,
+          "accounting_mode": "self_reported"
+        }
+      ]
     }
   ],
-  "composite_max_estimated_tokens": 13034
+  "composite_max_estimated_tokens": 13882
 }