@unbrained/pm-cli 2026.10.2 → 2026.10.4

package/docs/OUTPUT_PROJECTION_CONTRACTS.md

@@ -232,6 +232,29 @@ activity limits so the built-in orientation declaration remains feasible on a
 large tracker. All five intent commands accept the same
 `--token-budget` override. Explicit `--depth` and `--limit` controls still win.
 
+Context omission instructions request the named section, for example
+`--section files`, so they can be appended while retaining `--for handoff` or
+`--for orient`. An explicit depth suppresses the intent's default section subset;
+an explicit section remains authoritative at any depth. Workspace memory that
+is already present is never reported as omitted. The original filters and token
+budget remain binding; an oversized restoration reports its remaining budget
+constraint. Tracked by [pm-gh1367](../.agents/pm/issues/pm-gh1367.toon).
+
+For namespaced commands, options supplied on an ancestor apply only when the
+selected leaf declares them. `context --tag urgent next` forwards the tag;
+a leaf-supplied limit takes precedence. `context next --depth deep` and
+`context --depth deep next` fail with `unknown_option`, because `next` does not
+declare a depth projection. Inspect the leaf's help before applying context
+controls to it. Tracked by [pm-gh1368](../.agents/pm/issues/pm-gh1368.toon).
+
+Ownership compositions use the resolved canonical item ID in every stage and
+the root receipt, including short-ID invocations. Default CLI/MCP start, pause,
+and close receipts expose the final status and aggregate changed-field count
+without repeating item bodies. `--full-changed-fields` and typed SDK methods
+retain complete constituent results. A failed later step reports the canonical
+item and prior durable mutation without implying rollback.
+Tracked by [pm-gh1369](../.agents/pm/issues/pm-gh1369.toon).
+
 If a selected result exceeds its budget, long explanatory strings compact
 first, followed by deterministic root-row reduction that retains at least one
 useful row and reports `budget_row_compaction`. Only a result whose minimum

package/docs/SDK_AUDITED_MUTATIONS.md

@@ -3,6 +3,7 @@
 The extension settings contract is tracked by
 [pm-wtqltn](../.agents/pm/issues/pm-wtqltn.toon). Full-item JSON annotation
 integrity is tracked by [pm-2589e6](../.agents/pm/issues/pm-2589e6.toon).
+Canonical previews are tracked by [pm-2sef82](../.agents/pm/features/pm-2sef82.toon).
 
 ## Extension settings
 
@@ -36,10 +37,44 @@ the same operation ID can then be used for the real mutation. A normal return
 also reports `changed` and `dry_run`. Invalid results fail before writing, and
 a history-append failure restores the previous settings bytes. The callback
 must derive its complete next settings object from the locked `current` value.
+The callback receives normalized inline settings with defaults and preset knobs
+even when the source file is sparse. Returning that tree unchanged retains the
+original source bytes, including unknown fields, without creating an audit event.
+Changed writes apply known-setting changes to the captured source through the
+standard serializer, preserving sparse omissions and unrecognized fields in
+unchanged containers for forward compatibility. Those fields remain outside the
+typed callback and canonical preview. Replacing an array replaces its complete
+contents, as in normal settings writes. Present legacy values are canonicalized
+on a changed write; an identity no-op still retains the original bytes.
+The host also validates the final serialized bytes before committing, so a
+proposal that changes while being serialized cannot persist invalid settings.
 The host applies the standard settings serializer, including legacy format
 coercion and collection-name sanitization, and runs active `onWrite` hooks
 after a changed write.
 
+Request `includePreview: true` to receive an optional `preview` settings tree
+alongside the receipt. The host resolves it from the exact serialized bytes
+inside the audit lock, using the same defaults and governance presets as normal
+settings reads. A named `minimal` preset therefore reports ownership `none`
+even if the callback proposed `strict`. Custom presets retain their configured
+knobs. Legacy formats and collection names reflect their canonical persisted
+values. This tree describes inline settings before optional file-backed schema
+overlays; it does not load or create those files.
+
+Use `dryRun: true, includePreview: true` to inspect the result before applying
+the same operation. A fresh no-op also includes its canonical tree. An idempotent
+replay omits `preview`: the original callback is not re-executed, and later
+settings changes cannot reconstruct its historical proposal. Receipts remain
+three booleans when the option is absent. Direct SDK dry runs read configuration
+without executing read hooks, scaffolding optional schemas, or populating the
+hydrated settings cache. Mutation callbacks should only derive settings and
+avoid external side effects.
+
+For an extension that requires previews, set its manifest `pm_min_version` to
+a published host release containing this option. Check for `preview` on a fresh
+dry-run operation before applying settings, while allowing replay receipts to
+omit it as described above.
+
 ## Full-item JSON updates
 
 `pm update <id> --stdin-json` accepts a full item read document. New comments,

package/docs/TESTING.md

@@ -288,6 +288,8 @@ control and fails if `pm eval --fail-under` stops returning a non-zero exit.
 Refresh the baseline only with `pnpm quality:retrieval-eval:update` after
 reviewing query-level ranking changes.
 
+Development tools must also pass the [development dependency security gate](DEVELOPMENT_DEPENDENCY_SECURITY.md), including the full audit and installed bundle integrity policy.
+
 ## Context Quality Evaluation
 
 The required context relevance gate proves that `pm context` and `pm next`
@@ -545,11 +547,44 @@ pm test <item-id> --run --workspace-context snapshot --override-linked-workspace
   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.
+  `.git`, `.agents`, coverage output, and common cache directories are excluded
+  at every directory depth, with reserved names matched case-insensitively for
+  portable admission. Each existing root or nested `node_modules`
+  directory is linked at its original relative path, including installations
+  already represented by directory symlinks. This preserves independent
+  monorepo dependency versions without copying dependency trees. Dependency
+  aliases into excluded trees or included workspace source are refused. Internal
+  shared targets must remain within admitted `node_modules` subtrees; external
+  installations must be disjoint from the source workspace, rather than
+  containing it. They remain available even when an external ancestor shares an
+  excluded directory name.
+  Links are read-only **by convention**; they do not prevent a trusted command
+  from modifying the original installation. Use an independent installation
+  when testing package-manager operations or dependency writes. Built output
+  remains available so linked commands such as `node dist/cli.js` keep working.
+  The source workspace root is resolved before copying. Ordinary file and
+  directory symlinks into included workspace source are rebased into the copy,
+  including dangling file aliases; writes through those aliases stay in the
+  disposable snapshot. Targets are canonicalized through their nearest existing
+  ancestor, so absolute aliases through another workspace path spelling and
+  missing target suffixes retain the same isolation on supported platforms.
+  Source aliases into unadmitted external directories or excluded tracker/build
+  trees fail before the linked command runs. An alias into an admitted shared
+  dependency namespace retains the dependency-write convention above, including
+  packages linked within that installation. Source and snapshot destinations
+  must be physically disjoint; overlapping roots fail before copying with a
+  diagnostic directing the caller to a temporary root outside the checkout.
+
+  Snapshot target probes treat only `ENOENT` as absence and propagate other
+  filesystem failures. They use explicit error handling so Node 22 and older
+  Node 24 releases retain the same dangling-link behavior; the async `stat`
+  `throwIfNoEntry` option was added in
+  [Node 24.15](https://nodejs.org/download/release/v24.20.0/docs/api/fs.html#fspromisesstatpath-options).
+  The real filesystem and CLI snapshot suite runs in the required Node 22
+  telemetry regression job and native Windows regression job before merge.
+
+  The real-filesystem regression for this contract is tracked by
+  [pm-5iwfkj](../.agents/pm/issues/pm-5iwfkj.toon).
 
 Every result reports the requested/effective workspace mode, working
 directory, exposed source root, and trust decision. Recorded `test_runs` retain