@aefree/pi-plastic 0.7.5 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aefree/pi-plastic",
-  "version": "0.7.5",
+  "version": "0.8.0",
   "type": "module",
   "engines": {
     "node": ">=22.19.0"
@@ -16,6 +16,7 @@
     "extensions/",
     "src/",
     "skills/",
+    "docs/",
     "CHANGELOG.md",
     "LICENSE",
     "README.md"
@@ -35,18 +36,20 @@
   "scripts": {
     "typecheck": "tsc -p tsconfig.json",
     "pretest": "npm run typecheck",
-    "test": "tsx tests/tool-definition.test.ts && tsx tests/release-registry-preflight.test.ts && tsx tests/plastic-tool-validation.ts && tsx tests/plastic-status-machine-readable.test.ts && tsx tests/plastic-checkin-path-resolution.ts && tsx tests/plastic-diff-workflow.test.ts && tsx tests/plastic-workspace-diff.test.ts && tsx tests/plastic-process-lifecycle.test.ts && tsx tests/plastic-patch-command.test.ts && tsx tests/plastic-capability-diagnostics.test.ts && tsx tests/plastic-extension-registration.test.ts && tsx tests/plastic-dynamic-tool-loading.test.ts && tsx tests/plastic-tool-rendering.test.ts && tsx tests/plastic-branch-query.test.ts && tsx tests/plastic-workspace.test.ts && tsx tests/plastic-mutation-execution.test.ts && tsx tests/plastic-merge-branches.test.ts && tsx tests/file-discovery-filter.test.ts && tsx tests/file-discovery-filter-registration.test.ts && tsx tests/packed-copy-owner-conflict.test.ts && tsx tests/plastic-branch-status.test.ts && tsx tests/plastic-constrained-sampling.test.ts && tsx tests/bash-cm-diff-guard-validation.ts",
+    "test:docs": "tsx tests/plastic-documentation.test.ts",
+    "test": "tsx tests/plastic-documentation.test.ts && tsx tests/eval-mutation-guard.test.ts && tsx tests/tool-definition.test.ts && tsx tests/release-registry-preflight.test.ts && tsx tests/plastic-tool-validation.ts && tsx tests/plastic-status-machine-readable.test.ts && tsx tests/plastic-status-output.test.ts && tsx tests/plastic-status-xml.test.ts && tsx tests/plastic-branch-output.test.ts && tsx tests/plastic-checkin-output.test.ts && tsx tests/plastic-branch-create-output.test.ts && tsx tests/plastic-switch-output.test.ts && tsx tests/plastic-update-output.test.ts && tsx tests/plastic-add-output.test.ts && tsx tests/plastic-undo-output.test.ts && tsx tests/plastic-removal-output.test.ts && tsx tests/plastic-workspace-merge-output.test.ts && tsx tests/plastic-workspace-merge-closeout.test.ts && tsx tests/plastic-closeout-output.test.ts && tsx tests/plastic-closeout-parent.test.ts && tsx tests/plastic-copied-closeout.test.ts && tsx tests/plastic-copied-cardinality.test.ts && tsx tests/plastic-branch-delete-output.test.ts && tsx tests/plastic-object-delete-output.test.ts && tsx tests/plastic-object-write-output.test.ts && tsx tests/plastic-receipt-integration.test.ts && tsx tests/plastic-checkin-core-closeout.test.ts && tsx tests/plastic-selected-collector-retirement.test.ts && tsx tests/plastic-checkin-path-resolution.ts && tsx tests/plastic-diff-workflow.test.ts && tsx tests/plastic-diff-revisions-output.test.ts && tsx tests/plastic-local-snapshot.test.ts && tsx tests/plastic-workspace-diff.test.ts && tsx tests/plastic-process-lifecycle.test.ts && tsx tests/plastic-module-boundaries.test.ts && tsx tests/plastic-patch-command.test.ts && tsx tests/plastic-patch-output.test.ts && tsx tests/plastic-capability-diagnostics.test.ts && tsx tests/plastic-extension-registration.test.ts && tsx tests/plastic-dynamic-tool-loading.test.ts && tsx tests/plastic-tool-rendering.test.ts && tsx tests/plastic-rendering-runtime-isolation.test.ts && tsx tests/plastic-branch-query.test.ts && tsx tests/plastic-workspace.test.ts && tsx tests/plastic-workspace-list-output.test.ts && tsx tests/plastic-shelveset-list-output.test.ts && tsx tests/plastic-code-review-find-output.test.ts && tsx tests/plastic-mutation-execution.test.ts && tsx tests/plastic-merge-branches.test.ts && tsx tests/plastic-server-merge-output.test.ts && tsx tests/plastic-server-merge-resolutions.test.ts && tsx tests/file-discovery-filter.test.ts && tsx tests/file-discovery-filter-registration.test.ts && tsx tests/packed-copy-owner-conflict.test.ts && tsx tests/plastic-branch-status.test.ts && tsx tests/plastic-constrained-sampling.test.ts && tsx tests/bash-cm-diff-guard-validation.ts",
     "preview:tools": "tsx tests/plastic-tool-rendering.test.ts --preview",
+    "test:host:status": "tsx tests/pi-host-status-output.test.ts",
     "test:live": "tsx tests/plastic-live-smoke.test.ts",
     "test:live:branch-create": "tsx tests/plastic-branch-create-live.test.ts",
     "eval:tool-loading": "tsx evals/tool-loading/run-eval.ts"
   },
   "devDependencies": {
     "@aefree/pi-file-discovery": "^0.1.1",
-    "@earendil-works/pi-coding-agent": "0.87.0",
-    "@earendil-works/pi-tui": "0.87.0",
-    "@types/node": "22.20.2",
-    "tsx": "4.23.5",
+    "@earendil-works/pi-coding-agent": "1.1.0",
+    "@earendil-works/pi-tui": "1.1.0",
+    "@types/node": "22.20.4",
+    "tsx": "4.23.15",
     "typebox": "^1.3.8",
     "typescript": "7.0.2"
   },
@@ -79,5 +82,8 @@
     "typebox": {
       "optional": true
     }
+  },
+  "dependencies": {
+    "@xmldom/xmldom": "0.9.12"
   }
 }

package/skills/using-plastic/SKILL.md

@@ -18,21 +18,23 @@ Treat `plastic_merge` success as provisional until `plastic_status` confirms the
 
 For the common closeout flow of merging a finished source branch into its parent branch, prefer `plastic_mergeToBranch` when available. When `target` is omitted, it resolves the source branch's Plastic parent branch instead of assuming `/dev`. It switches to the target, optionally updates, runs the safe merge, checks merge state, and checks in the merge result. Pass `target` only when the user explicitly wants a different integration branch.
 
-Use `plastic_mergeBranches` only for the separate workspace-free server-side route. It requires explicit same-repository/server `br:/...@<repository>@<server>` source and target selectors plus a nonempty message. Its preflight renders the command only; it does not contact Plastic or analyze conflicts. A completed result proves one emitted root-mount target changeset for the dispatch, but does not verify the source merge link, target-head exclusivity, rollback, or xlink effects. No-op and conflict output do not prove that no effect occurred. Do not use it for xlink handling, conflict-policy selection, shelve merges, retries, target-head unification, or a workspace fallback; undetected server-side xlink effects remain possible.
+Use `plastic_mergeBranches` for the separate workspace-free server-side route with explicit same-repository/server `br:/...@<repository>@<server>` source and target selectors. Read the [agent conflict-resolution workflow](../../docs/2026-10-06-merging.md#agent-conflict-resolution-workflow) before resolving server file conflicts. `mode="analyze"` contacts the server read-only without a message or applying merge; inspect exact `conflictPaths`, completeness and omissions. Default apply requires a nonempty message and can submit reviewed `fileConflictsResolutionsFile` JSON with per-file keep/source/destination or merged result-file decisions. Verify contributors independently, preserve baselines, validate merged bytes, and keep all inputs immutable until completion. Optional `unlistedConflictPolicy` is an explicit discard policy, never an automatic repair. Preflight only validates local inputs/renders argv; it does not contact Plastic. A completed result proves one emitted root-mount target changeset, not source links, head exclusivity, rollback or Xlink effects. Native receipts distinguish analyzed/preflight/completed/no-op/conflict/uncertain/failed outcomes; inspect attempt/capture/effect before continuing. Full @cloud/@unity qualifiers are preserved; requested/emitted server names stay separate with alias equivalence unverified. No-op/conflict output does not prove absent effects. Do not use this for directory-conflict repair, shelve merges, retries, head unification or workspace fallback; Xlink ownership/effects remain unverified.
 
 Plastic merges are workspace- and branch-oriented, not Git fast-forwards: the merge is applied to the branch currently loaded in the workspace, and the merge checkin must be created on that target branch. Switching to the target after a checkin on the source branch does not move or integrate that changeset. Treat any source/target/final-branch mismatch as a failed closeout; inspect target-branch history and rerun the merge from the actual target rather than merely switching branches.
 
-`plastic_diff` is intentionally disabled. Route changed-path listing to `plastic_status()`, one intentional workspace-file comparison to `plastic_diffFile(path="<workspace-path>")`, an explicitly scoped pending review to `plastic_workspaceDiff(paths=[...])`, and an explicit historical pair to `plastic_diffRevisions`. Do not use diffs as routine post-edit validation or checkin preflight. Prefer focused tests, `plastic_status` for pending scope, and direct reads for current file content; diff only when change-boundary evidence is needed. `plastic_diffFile` uses machine-readable status: added and explicitly selected private/new files compare against an empty base; changed, moved, and deleted items use their reported base revision when available. An added empty file reports `status="added-empty"`, not generic unchanged. A `--nodata` base failure means Plastic cannot provide historical bytes; refresh/update the workspace or use two known file-qualified revisions. Explicit `revision` behavior remains a separate historical request. Binary content is reported rather than decoded as text. Text backends receive ASCII-safe package materializations while returned headers preserve logical Unicode labels.
+Use one `plastic_diff` with explicit `mode="file"|"revisions"|"workspace"`. File mode requires `path`; omit `revision` for a verified loaded base, or supply a supported historical selector. Revisions mode requires `leftRevision` and `rightRevision`; exported selectors remain unresolved identities unless loaded metadata is independently observed. Workspace mode requires nonempty `paths` or `allPending=true`; `includePrivate` applies only to all-pending. Old specialized names are removed, not aliases. Prefer focused tests, `plastic_status` for pending scope, and direct reads; diff only when change-boundary evidence is needed, not routine validation or checkin preflight.
 
-`plastic_workspaceDiff` requires selected paths or explicit `allPending=true`, runs status once, has small default file/per-file/combined-output bounds, and returns per-file outcomes without aborting when one file is unavailable. Selected private paths are included; whole-workspace private review additionally requires `includePrivate=true`. Keep `maxChars` small unless more output is intentional. Text-diff selection and patch-backend selection are distinct: text tools use `PI_PLASTIC_DIFF_EXECUTABLE` or bare PATH `diff`. On macOS, bare `diff` can resolve either to GNU Diffutils or Apple’s BSD `/usr/bin/diff`; Pi uses the resolved executable and does not auto-select `gdiff`.
+Loaded bases use strict UTF-8 status/fileinfo/ls observations and a qualified genuine revision ID, verified against the loaded file hash. Controlled deletions use the frozen loaded workspace tree; local moves use observed OldPath metadata. Added/explicitly selected private files use a deliberate empty base; an added empty file reports `added-empty`. Unavailable bytes, ownership or unsupported observations are errors, never empty bases or guessed IDs. Workspace results retain per-file failures with `ok=false`, counts, unmatched paths, skipped/limited/unattempted/omitted outcomes and completeness; inspect these before concluding review is complete. Defaults: 3 all-pending items (20 scoped), 3000 characters per workspace excerpt; file/revisions excerpts default to 8000. Keep bounds small. Comparisons use stable bounded local snapshots and owned ASCII-safe operands, not an atomic workspace/repository snapshot. Binary inputs use exact byte equality. Text comparison uses the configured `PI_PLASTIC_DIFF_EXECUTABLE` or PATH `diff`, with no backend retry or automatic substitution.
 
-Use `plastic_patch` for review patch generation with `clean` and `integration` filters; it is generation-only and does not apply patches. `toolPath` is its highest-priority one-call patch-backend override, followed by `PI_PLASTIC_PATCH_EXECUTABLE`. On Windows, configure one to a verified patch-capable non-GUI executable such as Git's `diff.exe`: patch generation deliberately does not reuse `PI_PLASTIC_DIFF_EXECUTABLE`/GnuWin32. On macOS with Plastic 11, Apple BSD `/usr/bin/diff` works for text-only `plastic_diffFile` but rejects the `--binary` argument used by `cm patch`; set the patch-specific policy to a verified GNU Diffutils-compatible non-GUI executable. The non-Windows fallback to the text setting or bare `diff` is only valid when that executable accepts the local Plastic patch arguments. Interactive Pi sessions issue one path-redacted package capability warning per runtime for an invalid configured patch override or missing Windows setting; fix `PI_PLASTIC_PATCH_EXECUTABLE` and retry, while headless sessions retain `plastic_patch` tool-time validation. Unqualified `br:/...` patch selectors are qualified only from the current workspace's exact selector repository; otherwise pass `br:/<branch>@<repository>@<server>`. For a large patch, pass an intentional new `output` path: the package stages and atomically publishes it, never overwriting an existing path. Do not use `cm cat --raw`: it is unsupported for this workflow. Typed retrieval owns cleanup; the low-level byte-preserving fallback is `cm cat --file` only when a typed tool cannot represent the case. Plastic/server output may represent moves as moves or delete/add records, so inspect generated patches rather than assuming a move-aware encoding.
+Use `plastic_patch` for review patch generation with `clean` and `integration` filters; it is generation-only and does not apply patches. `toolPath` is its highest-priority one-call patch-backend override, followed by `PI_PLASTIC_PATCH_EXECUTABLE`. On Windows, configure one to a verified patch-capable non-GUI executable such as Git's `diff.exe`: patch generation deliberately does not reuse `PI_PLASTIC_DIFF_EXECUTABLE`/GnuWin32. On macOS with Plastic 11, Apple BSD `/usr/bin/diff` has prior text-only evidence but rejects the `--binary` argument used by `cm patch`; set the patch-specific policy to a verified GNU Diffutils-compatible non-GUI executable. The non-Windows fallback to the text setting or bare `diff` is only valid when that executable accepts the local Plastic patch arguments. Interactive Pi sessions issue one path-redacted package capability warning per runtime for an invalid configured patch override or missing Windows setting; fix `PI_PLASTIC_PATCH_EXECUTABLE` and retry, while headless sessions retain `plastic_patch` tool-time validation. Unqualified `br:/...` patch selectors are qualified only from the current workspace's exact selector repository; otherwise pass `br:/<branch>@<repository>@<server>`. For a large patch, pass an intentional new `output` path: the package stages and atomically publishes it, never overwriting an existing path. Do not use `cm cat --raw`: it is unsupported for this workflow. Typed retrieval owns cleanup; the low-level byte-preserving fallback is `cm cat --file` only when a typed tool cannot represent the case. Plastic/server output may represent moves as moves or delete/add records, so inspect generated patches rather than assuming a move-aware encoding.
 
 Prefer runtime `plastic_*` tools first. Keep `cm` shell commands as manual fallback.
 
 Directly invoked mutating `plastic_*` tools run without package-owned approval tokens or UI confirmation. Inspect exact targets and rely on the tools' command, workspace, path-containment, and non-interactive process guards. Do not call preflight and then the same operation as routine ceremony. Use preflight when mutation scope is ambiguous or broad, moved/deleted paths may need rewriting, a compound operation needs preview, or the user explicitly asks for one. A command process is attempted once without implicit retry; after an ambiguous failure, inspect Plastic status before deciding whether to retry manually.
 
-Create normal work branches beneath an intended parent: use `<parent-branch>/<new-branch>`, not `/<new-branch>`. The parent does not need to be the branch loaded in the workspace. Prefer `plastic_branchCreate(branch="<new-branch>", parent="<parent-branch>")`; omitting `parent` uses the current branch only as a convenience. Rare top-level branch creation requires the explicit `allowRootBranch=true` override.
+Create normal work branches beneath an intended parent: use `<parent-branch>/<new-branch>`, not `/<new-branch>`. The parent does not need to be the branch loaded in the workspace. Prefer `plastic_branchCreate(branch="<new-branch>", parent="<parent-branch>")`; omitting `parent` requires directly observed standard-status loaded-branch identity, not a changeset owner. Qualifier-bearing relative names/parents are rejected: use a full qualified hierarchical target. Successful branch-create receipts prove command completion only, not created identity or repository effects; no automatic verification/switch follows. Rare top-level branch creation requires the explicit `allowRootBranch=true` override.
+
+Checkin receipts distinguish observed root changesets from unverified scope/head/alias/Xlink/link effects. Checkin preflight reads pending scope but does not mutate. Eligible complete admitted failures may trigger existing safe-private add/retry or path fallback; capture/timeout/abort uncertainty must not be retried automatically. Failed post/recovery reads stay unknown, and even an empty pending read after failed checkin is not completion proof. Earlier child effects remain recorded; inspect them before another attempt.
 
 ## External File Loading
 
@@ -43,6 +45,10 @@ CRITICAL: Use relative path references and load files only when needed for the c
 - Read the reference files only when relevant.
 - For long files, use Read with `offset`/`limit` to load only needed sections.
 
+## Public Tool Documentation (Load On Demand)
+
+For parameter semantics, structured receipts, source restrictions, and bounds, start at the [package documentation index](../../docs/README.md), then read only the relevant tool-family section. [Safety and receipts](../../docs/2026-10-06-safety-and-receipts.md) explains completion versus verified effects. Resolve these same-package links relative to this skill directory; no external reference-reader tool is needed. Do not load the entire manual routinely.
+
 ## Reference Files (Load On Demand)
 
 Quick reference -> ../using-plastic/references/quick-reference.md

package/skills/using-plastic/references/branch-management.md

@@ -29,7 +29,9 @@ plastic_branchCreate(
 plastic_switchBranch(branch="<parent-branch>/<new-branch>") # only when work should continue there
 ```
 
-Omitting `parent` for a relative branch name uses the current workspace branch as a convenience. A full hierarchical path is also accepted regardless of the loaded branch. Rare top-level branch creation requires `allowRootBranch=true`; use that override only when the user explicitly intends a new top-level hierarchy.
+Omitting `parent` for a relative name requires directly observed standard-status loaded-branch identity. A changeset owner (including compact cs-only status) is not the loaded parent; provide an explicit parent when it cannot be observed. Qualifier-bearing relative names/parents are rejected rather than stripped; full hierarchical qualified targets stay verbatim. Rare top-level creation requires `allowRootBranch=true` only when explicitly intended.
+
+A successful receipt proves `command-completed` only, with null observed created identity and unverified repository/domain effects, even for empty stdout. It does not switch the workspace or run a hidden verification query. After an uncertain attempt, inspect the receipt and state before retrying; command completion is not independent creation proof.
 
 Manual shell fallback requires constructing the hierarchical path explicitly:
 
@@ -45,6 +47,8 @@ Pending-change behavior in unattended runs:
 - `pendingChanges="bring"` is only blocked when tracked pending changes exist (Plastic requires interactive prompts).
 - If pending changes are private-only, `plastic_switchBranch` performs a direct non-interactive switch and keeps private files local.
 - `pendingChanges="shelve"` shelves tracked changes; for private-only pending changes, shelve is skipped and switch proceeds.
+- Defaulted cancel permits private-only direct switching; explicit cancel blocks switching with any pending items. Native cancellation is not a successful switch; core non-preflight cancellation rejects to stop compound callers.
+- Inspect native switch outcome, step effects and target verification. A shelve or switch command completing does not prove preservation, reusable shelveset identity, alias equivalence or rollback. Failed/malformed pending or recovery observations stop; compact changeset ownership is not the loaded branch. Qualification-ambiguous same-name requests are not skipped as already loaded; unverified post-qualification returns an error after retaining possible effects. Preflight is sequential local inspection only, not server-verified switchability.
 
 ## Merge Branches (Non-Interactive)
 

package/skills/using-plastic/references/changeset-operations.md

@@ -38,8 +38,9 @@ Unattended behavior notes:
   the tool auto-runs `cm add` for safe in-scope private paths, then retries checkin once.
 - Sensitive private paths (for example `.env*`, private key extensions, `.npmrc`, credentials/secrets JSON)
   are excluded from auto-add and reported as warnings/errors for explicit handling.
-- The JSON response includes decision metadata (`decisionPath`, pre/post pending summaries, and auto-add info)
-  so agents can continue unattended without asking for confirmation.
+- The closed receipt includes per-step attempts/capture/effects, pending summaries (null when unverified), and private-add/fallback decisions. Eligibility requires complete admitted native failure, never launch/capture/timeout/abort uncertainty.
+- A failed checkin followed by an empty or failed pending read remains uncertain, not completed. Successful earlier add/checkin effects remain recorded after later failure. Completion requires an admitted root changeset, not exit zero or empty output. Scope exhaustion, branch head, alias equivalence and Xlink/link effects stay unverified.
+- `preflight=true` performs one pending read, no mutation. Text/JSON present the same bounded receipt; registered native errors set `isError`.
 
 Note: avoid `updateAfter=true` in unattended runs because it can trigger interactive update-merge. Use `plastic_update()` followed by `plastic_merge(...)` (default auto strategy) when a merge is required.
 
@@ -75,18 +76,18 @@ Never run `cm diff` in Pi. Do not replace it with a routine safe-diff call: use
 
 ```text
 plastic_status(machineReadable=true) # list pending paths/statuses
-plastic_diffFile(path="<workspace-path>", maxChars=4000) # one intentional file comparison
-plastic_workspaceDiff(paths=["<workspace-path>"], maxChars=3000) # explicitly scoped review
-plastic_workspaceDiff(allPending=true) # explicit small whole-workspace review
-plastic_diffFile(path="<workspace-path>", revision="cs:<number>")
-plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>")
+plastic_diff(mode="file", path="<workspace-path>", maxChars=4000) # one intentional file comparison
+plastic_diff(mode="workspace", paths=["<workspace-path>"], maxChars=3000) # explicitly scoped review
+plastic_diff(mode="workspace", allPending=true) # explicit small whole-workspace review
+plastic_diff(mode="file", path="<workspace-path>", revision="cs:<number>")
+plastic_diff(mode="revisions", leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>")
 ```
 
 The typed diff tools own historical `cm cat --file` materialization and cleanup; do not create agent-authored temporary files for ordinary diffs. `cm cat --raw` is unsupported for this workflow. Use typed retrieval first; `cm cat --file` is the byte-preserving low-level fallback only when a typed tool cannot represent the case.
 
 ## Historical Export Fallback
 
-Use this fallback only when typed retrieval cannot represent the required case. For an ordinary workspace-base comparison, omit `revision` from `plastic_diffFile`; for a changeset comparison, supply its `revision="cs:<number>"` argument.
+Use this fallback only when typed retrieval cannot represent the required case. For an ordinary workspace-base comparison, omit `revision` from `plastic_diff` in file mode; for a changeset comparison, supply its `revision="cs:<number>"` argument.
 
 `cm cat <revspec> --file=<output-file>` writes historical bytes to the output file and can overwrite it. `--file` does not select the source. Piping this command to `Set-Content` or redirecting stdout does not change the destination or protect it: with `--file`, the file contents are written there rather than to stdout.
 

package/skills/using-plastic/references/code-review-creation.md

@@ -1,30 +1,37 @@
 # Code Review Creation
 
-## CLI (Preferred)
+## Tool-first flow
 
-```bash
-branch=$(cm status | head -1 | cut -d@ -f1 | xargs)
-review_id=$(cm codereview "br:${branch}" "Feature: Brief description" --format="{id}")
-
-# Assign reviewer immediately after creating the review
-cm codereview -e "$review_id" --reviewer="reviewer-name"
+Use `plastic_codeReviewCreate` with an explicitly inspected target and title. Optional `status`, `assignee`, and `repository` retain their CLI meanings. Set an assignee only when the user requests that assignment; creating a review does not authorize assigning another person.
 
-# List reviews for this branch
-cm find review "where target='br:${branch}'" --format="{id} {status} {title}"
+```text
+plastic_codeReviewCreate(target="br:/main/owned-feature", title="Feature: Brief description", output="json")
+# Inspect the receipt before using its observedCreatedIdentity in a separately authorized update.
+plastic_codeReviewUpdate(id="<observed ID>", status="Reviewed", output="json")
 ```
 
-Agent preference: use runtime `plastic_*` methods first for status/branch lookup; keep shell commands as manual fallback.
+Default numeric/GUID creation scalars can be emitted identity evidence. Requested repository scope and requested review state remain unverified. An update completing with empty stdout is command completion, not proof that the status changed. No automatic readback, retry, assignment, or review conversation follows.
 
-Reviewer assignment is required in the workflow. If your server uses different reviewer flags, run `cm codereview --help` and use the server-specific reviewer option right after review creation.
+`output="text"|"json"` controls receipt presentation independently of creation `format`, which is passed to CM unchanged. Custom formatted stdout always remains opaque, even when it contains a numeric ID. Do not chain a substring of custom output into an update; an explicitly planned unique-title query can provide separate identity evidence.
 
-Tool-first flow (preferred):
+## Manual CLI fallback
 
-```text
-plastic_status()
-# Then use cm codereview ... as fallback for review create/assign
+Inspect the exact branch/changeset/shelveset selector first. Do not derive it by splitting or trimming human-readable status output.
+
+```bash
+cm codereview "br:/main/owned-feature" "Feature: Brief description"
+# Only if separately authorized, using an observed ID:
+cm codereview -e "<observed ID>" --status="Reviewed"
+# Only when an assignment was explicitly requested:
+cm codereview -e "<observed ID>" --assignee="<requested user>"
 ```
 
-## CLI Not Available
+Installed CM11 help documents creation formatter `{0}` as ID and `{1}` as GUID. A bounded owned fixture validated `--format="{0}|{1}"`; a named `{id}|{title}` creation formatter failed with `Invalid format string`. Creation formatting and `cm find review` field formatting are different protocols: the tested find query accepts `{id}|{status}|{title}`, but `{guid}` failed. Do not infer support from an inconsistent help example.
+
+```bash
+cm codereview "br:/main/owned-feature" "Owned review title" --format="{0}|{1}"
+# Separate, explicitly scoped observation; not an automatic creation/update verification:
+cm find review "where title='Owned review title'" --format="{id}|{status}|{title}" --nototal
+```
 
-- Document branch and changeset in plan/issue tracker.
-- Or create review via Plastic GUI and assign a reviewer before sharing the review link.
+Failed commands may have effects; retain receipts and inspect the exact owned fixture before deciding what to do. If CLI access is unavailable, report that limitation or use the GUI only when requested. Do not silently create or assign a replacement review.

package/skills/using-plastic/references/integration.md

@@ -21,6 +21,10 @@ Plastic does not perform a Git-style fast-forward. It applies the merge into the
 - Only then create the merge checkin.
 - Verify the merge checkin was created on the target branch. If the workspace or changeset is on the source branch, stop: do not switch to the target and claim completion. Inspect target history and rerun the merge while the target is actually loaded.
 
+## Server-side File Conflict Resolution
+
+Use `plastic_mergeBranches(mode="analyze", source="<qualified-source>", target="<qualified-target>")` for read-only conflict discovery, not `preflight`. Then independently inspect contributors, produce merged files, validate them, and submit a reviewed absolute `fileConflictsResolutionsFile` with a nonempty message. Follow the [full workflow and safety boundaries](../../../docs/2026-10-06-merging.md#agent-conflict-resolution-workflow). Exact destination conflict paths are JSON keys, not local workspace paths. Never guess the roles/repository of numeric FILE_CONFLICT fields, export over workspace files, automatically discard unlisted conflicts, or retry uncertain applying results. Keep all inputs immutable through completion; directory conflicts and shelve modes remain separate.
+
 ## Review Workflow
 
 - Create or reuse review workspace.
@@ -42,11 +46,11 @@ plastic_patch(source="<branch-spec>", clean=true, integration=true, output="<new
 - When change-boundary evidence is needed, inspect specific files first and opt into multi-file output explicitly:
 
 ```text
-plastic_diffFile(path="<workspace-path>", maxChars=4000) # one intentional file comparison
-plastic_workspaceDiff(paths=["<workspace-path>"], maxChars=3000) # explicitly scoped pending review
-plastic_workspaceDiff(allPending=true) # explicit small whole-workspace review
-plastic_diffFile(path="<workspace-path>", revision="cs:<number>")
-plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>")
+plastic_diff(mode="file", path="<workspace-path>", maxChars=4000) # one intentional file comparison
+plastic_diff(mode="workspace", paths=["<workspace-path>"], maxChars=3000) # explicitly scoped pending review
+plastic_diff(mode="workspace", allPending=true) # explicit small whole-workspace review
+plastic_diff(mode="file", path="<workspace-path>", revision="cs:<number>")
+plastic_diff(mode="revisions", leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>")
 ```
 
 ## Plan Workflow

package/skills/using-plastic/references/quick-reference.md

@@ -18,10 +18,10 @@ Note: command examples target current `cm` 11.x CLI syntax; legacy aliases may d
 | Shelve | `plastic_shelvesetCreate(comment="description")` | `cm shelveset create -c="description"` | Save work temporarily |
 | Patch for review | `plastic_patch(source="<branch-spec>", clean=true, integration=true, output="<new-patch-file>")` | `cm patch <branch-spec> --clean --integration --output=<patch-file>` | Uses `toolPath` then `PI_PLASTIC_PATCH_EXECUTABLE`; Windows requires a verified patch-capable non-GUI executable. New output is staged and atomically published without overwrite; use repository-qualified `br:/...@<repository>@<server>` if selector resolution is unavailable |
 | Changed-file listing | `plastic_status(machineReadable=true)` | `cm status --all` | Lists changed, added, moved, deleted, and private items without GUI diff |
-| Diff (one workspace file) | `plastic_diffFile(path="<workspace-path>", maxChars=4000)` | None recommended | Intentional focused comparison only; not routine validation |
-| Diff (pending review) | `plastic_workspaceDiff(paths=["<workspace-path>"], maxChars=3000)` | None recommended | Requires selected paths or explicit `allPending=true`; use status for changed-path listing |
-| Diff (workspace vs supported revision) | `plastic_diffFile(path="<workspace-path>", revision="cs:<number>")` | None recommended | Also accepts a branch, label, file-qualified, or global revision spec |
-| Diff (revision vs revision) | `plastic_diffRevisions(leftRevision="<left-revspec>", rightRevision="<right-revspec>")` | None recommended | Requires two file-qualified revisions; avoids GUI and package temp-file recipes |
+| Diff (one workspace file) | `plastic_diff(mode="file", path="<workspace-path>", maxChars=4000)` | None recommended | Intentional focused comparison only; not routine validation |
+| Diff (pending review) | `plastic_diff(mode="workspace", paths=["<workspace-path>"], maxChars=3000)` | None recommended | Requires selected paths or explicit `allPending=true`; use status for changed-path listing |
+| Diff (workspace vs supported revision) | `plastic_diff(mode="file", path="<workspace-path>", revision="cs:<number>")` | None recommended | Also accepts a branch, label, file-qualified, or global revision spec |
+| Diff (revision vs revision) | `plastic_diff(mode="revisions", leftRevision="<left-revspec>", rightRevision="<right-revspec>")` | None recommended | Requires two file-qualified revisions; avoids GUI and package temp-file recipes |
 
 ## Merge verification checklist
 

package/skills/using-plastic/references/reviewing-changes.md

@@ -4,7 +4,7 @@
 
 Never run `cm diff` in Pi. It may open a GUI window and block CLI automation.
 
-`plastic_diff` is disabled by design.
+`plastic_diff` requires an explicit mode and performs bounded non-GUI comparison.
 
 ## Focused Patch Generation
 
@@ -24,14 +24,14 @@ Do not use diffs as routine post-edit validation or checkin preflight. Prefer fo
 
 ```text
 plastic_status(machineReadable=true) # “what changed?” / changed-path listing
-plastic_diffFile(path="<workspace-path>", maxChars=4000) # one intentional file comparison
-plastic_workspaceDiff(paths=["<workspace-path>"], maxChars=3000) # explicitly scoped pending review
-plastic_workspaceDiff(allPending=true) # explicit small whole-workspace review
-plastic_diffFile(path="<workspace-path>", revision="cs:<number>") # explicit historical comparison
-plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>")
+plastic_diff(mode="file", path="<workspace-path>", maxChars=4000) # one intentional file comparison
+plastic_diff(mode="workspace", paths=["<workspace-path>"], maxChars=3000) # explicitly scoped pending review
+plastic_diff(mode="workspace", allPending=true) # explicit small whole-workspace review
+plastic_diff(mode="file", path="<workspace-path>", revision="cs:<number>") # explicit historical comparison
+plastic_diff(mode="revisions", leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>")
 ```
 
-The diff tools materialize historical bytes and remove their temporary files internally. Added and explicitly selected private/new files use an empty base; an added empty file is reported as `added-empty`, not generic unchanged. Changed, moved, and deleted records use their status revision ID when available. A `--nodata` item cannot supply historical/base bytes: refresh the workspace or use two known file-qualified revisions. `plastic_workspaceDiff` requires selected paths or `allPending=true` and returns per-file unavailable outcomes instead of aborting the batch. Text-diff tools use bounded GNU/POSIX text diff, materialize backend operands to ASCII-safe package paths while preserving logical Unicode output labels, treat valid Unity YAML as text, and report genuine binary content explicitly. Do not construct `cm cat` temporary-file recipes for ordinary review. `cm cat --raw` is unsupported in this workflow; typed retrieval owns cleanup, and `cm cat --file` is the byte-preserving low-level fallback only when needed.
+The consolidated tool owns historical exports, stable bounded local snapshots and cleanup. Added and explicitly selected private files use a deliberate empty base; added-empty is distinct from unchanged. Loaded bases use strict fileinfo/ls metadata, a genuine qualified file revision ID, and hash-verified exported bytes, never status changesets relabeled as revisions. Controlled deletions use the frozen loaded workspace tree; local moves use observed OldPath metadata. Workspace mode retains per-file failures with ok=false; inspect counts, exclusions, unmatched paths and read/projection completeness, including limited, skipped and unattempted comparisons. Default all-pending review selects at most three items. Directory selections include pending descendants; directory rows are explicitly skipped. No failed export becomes an empty side, no atomic snapshot is claimed, and general mixed-Xlink ownership remains unverified. Text uses one configured GNU/POSIX backend with ASCII-safe operands and logical Unicode labels; binary inputs use byte equality. Do not construct cm cat recipes for ordinary review.
 
 `cm cat --file` is a filesystem write: its argument is the output destination, never the source file. Pointing it at a working file overwrites pending changes even if stdout is piped to a temporary file. Reviewers must use typed comparisons for ordinary baseline review; a necessary unsupported export must follow the [historical export rules](changeset-operations.md#historical-export-fallback), with a new absolute temporary destination outside the workspace and a verified file revision selector.
 
@@ -52,9 +52,9 @@ Use the Read tool for full context instead of GUI diffs.
 Use the common no-revision path first; `base`, `head`, and `cs:head` are rejected rather than guessed:
 
 ```text
-plastic_diffFile(path="<workspace-path>", maxChars=4000)
-plastic_diffFile(path="<workspace-path>", revision="br:/<branch>", maxChars=4000)
-plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>", maxChars=4000)
+plastic_diff(mode="file", path="<workspace-path>", maxChars=4000)
+plastic_diff(mode="file", path="<workspace-path>", revision="br:/<branch>", maxChars=4000)
+plastic_diff(mode="revisions", leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>", maxChars=4000)
 ```
 
 ## Pending Changes

package/skills/using-plastic/references/shelving.md

@@ -1,25 +1,40 @@
 # Shelving
 
-## Save Work
+Prefer runtime `plastic_*` tools. Inspect the intended paths and shelveset spelling before mutation; do not broaden into existing objects or workspace-wide recovery automatically.
 
-```bash
-cm shelveset create -c="Working on feature X"
+## Save work
+
+```text
+plastic_shelvesetCreate(paths=["owned.txt"], comment="Working on feature X", summaryFormat=true, output="json")
 ```
 
-## List Shelves
+A supported full emitted shelveset scalar can provide created identity evidence; repository scope, workspace exclusivity and rollback remain unverified. Preserve every qualifier. Paths and requested `all`/`dependencies` controls are passed unchanged. Comment and commentsFile are exclusive. Comment-less creation is refused when PLASTICEDITOR is configured; supply a comment rather than overriding the environment.
 
-```bash
-cm find shelve "where owner='me'" --format="{shelveid} {date} {comment}"
+## Inspect and apply
+
+```text
+plastic_shelvesetList()
+plastic_shelvesetApply(shelveset="<observed exact shelveset selector>", output="json")
 ```
 
-## Restore Work
+Command completion does not prove which items applied or that the workspace is restored/clean. Inspect the receipt and independently scoped workspace observations. `preview=true` really dispatches CM and can still prompt/fail on conflicts; `preflight=true` only renders argv with zero CLI calls and does not analyze conflicts. Do not run both routinely.
 
-```bash
-cm shelveset apply sh:5
+A fresh checked-out tracked text change has conflict-free same-base preview/apply evidence on Windows CM11. An earlier added-item preview prompted evil-twin resolution and failed. This does not establish a safe general conflict-resolution policy. Never force a choice, replay an uncertain apply or undo broad workspace scope automatically. Owned parent restoration is a separate authorized action, not producer rollback.
+
+## Delete
+
+```text
+plastic_shelvesetDelete(shelveset="<explicitly owned exact selector>", output="json")
 ```
 
-## Delete Shelve
+Delete only when requested. Exit0 does not prove deletion/absence or history restoration; the receipt leaves those effects unverified.
+
+## Manual CLI fallback
 
 ```bash
-cm shelveset delete sh:5
+cm shelveset create "owned.txt" -c="Working on feature X" --summaryformat
+cm shelveset apply "<observed exact shelveset selector>"
+cm shelveset delete "<explicitly owned exact selector>"
 ```
+
+These are separate mutations, not a default chained workflow. Preserve prior positive effects and failed probes; missing identity or unsafe interaction is a stop signal, not permission to guess a selector or change strategy.

package/skills/using-plastic/references/troubleshooting.md

@@ -48,11 +48,11 @@ cm codereview -e <review-id> --reviewer="reviewer-name"
 - `cm diff` is blocked in Pi because it can launch GUI windows and hang the CLI.
 - Use text-only alternatives:
   - `plastic_status(machineReadable=true)` for changed paths/statuses.
-  - `plastic_diffFile(path="<workspace-path>", maxChars=4000)` when one intentional file comparison is needed.
-  - `plastic_workspaceDiff(paths=["<workspace-path>"], maxChars=3000)` for an explicitly scoped pending review, or `allPending=true` for an intentional small whole-workspace review.
+  - `plastic_diff(mode="file", path="<workspace-path>", maxChars=4000)` when one intentional file comparison is needed.
+  - `plastic_diff(mode="workspace", paths=["<workspace-path>"], maxChars=3000)` for an explicitly scoped pending review, or `allPending=true` for an intentional small whole-workspace review.
   - Use `plastic_status` instead when only pending paths are needed; do not diff routinely.
-  - `plastic_diffFile(path="<workspace-path>", revision="cs:<number>")` for an explicit supported revision.
-  - `plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>")` for two historical files.
+  - `plastic_diff(mode="file", path="<workspace-path>", revision="cs:<number>")` for an explicit supported revision.
+  - `plastic_diff(mode="revisions", leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>")` for two historical files.
 
 ## GUI/Prompt Opens During Merge
 

package/src/diff/local-snapshot.ts

@@ -0,0 +1,74 @@
+import { constants, promises as fs, type Stats } from "node:fs";
+import { isAbsolute, relative, sep } from "node:path";
+
+export const LOCAL_SNAPSHOT_MAX_BYTES = 4 * 1024 * 1024;
+export type LocalSnapshotErrorCode = "missing_file" | "unsupported_file" | "outside_workspace" | "file_limit" | "file_changed" | "aborted" | "read_failed";
+export class LocalSnapshotError extends Error {
+    constructor(readonly code: LocalSnapshotErrorCode) { super("A bounded local file snapshot could not be verified."); }
+}
+interface SnapshotHandle {
+    stat(): Promise<Stats>;
+    read(buffer: Buffer, offset: number, length: number, position: number): Promise<{ bytesRead: number }>;
+    close(): Promise<void>;
+}
+export interface LocalSnapshotFilesystem {
+    lstat(path: string): Promise<Stats>;
+    realpath(path: string): Promise<string>;
+    open(path: string): Promise<SnapshotHandle>;
+}
+const filesystem: LocalSnapshotFilesystem = {
+    lstat: path => fs.lstat(path),
+    realpath: path => fs.realpath(path),
+    open: path => fs.open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0)),
+};
+const same = (a: Stats, b: Stats): boolean =>
+    a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeMs === b.mtimeMs && a.ctimeMs === b.ctimeMs;
+const regular = (s: Stats) => s.isFile() && !s.isSymbolicLink();
+const abort = (signal?: AbortSignal) => { if (signal?.aborted) throw new LocalSnapshotError("aborted"); };
+
+// The caller supplies an absolute file and the discovered workspace root. This
+// helper never discovers a different workspace, retries, or writes a local file.
+// Timestamp/identity checks detect observable changes; they are not an atomic
+// filesystem snapshot or protection against an adversary restoring timestamps.
+export async function snapshotLocalFile(
+    filePath: string,
+    workspaceRoot: string,
+    signal?: AbortSignal,
+    io: LocalSnapshotFilesystem = filesystem,
+): Promise<{ bytes: Buffer; physicalPath: string }> {
+    abort(signal);
+    if (!isAbsolute(filePath) || !isAbsolute(workspaceRoot)) throw new LocalSnapshotError("outside_workspace");
+    try {
+        const root = await io.realpath(workspaceRoot);
+        const initial = await io.lstat(filePath);
+        if (!regular(initial)) throw new LocalSnapshotError("unsupported_file");
+        const physicalPath = await io.realpath(filePath);
+        const scope = relative(root, physicalPath);
+        if (!scope || scope === ".." || scope.startsWith(".." + sep) || isAbsolute(scope)) throw new LocalSnapshotError("outside_workspace");
+        abort(signal);
+        const handle = await io.open(filePath);
+        try {
+            const before = await handle.stat();
+            if (!regular(before) || !same(initial, before)) throw new LocalSnapshotError("file_changed");
+            if (!Number.isSafeInteger(before.size) || before.size < 0 || before.size > LOCAL_SNAPSHOT_MAX_BYTES) throw new LocalSnapshotError("file_limit");
+            const buffer = Buffer.alloc(before.size + 1);
+            let length = 0;
+            while (length < buffer.length) {
+                abort(signal);
+                const read = await handle.read(buffer, length, buffer.length - length, length);
+                if (!Number.isInteger(read.bytesRead) || read.bytesRead < 0 || read.bytesRead > buffer.length - length) throw new LocalSnapshotError("read_failed");
+                if (!read.bytesRead) break;
+                length += read.bytesRead;
+            }
+            const after = await handle.stat();
+            const current = await io.lstat(filePath);
+            if (length !== before.size || !same(before, after) || !regular(current) || !same(before, current) || await io.realpath(filePath) !== physicalPath) throw new LocalSnapshotError("file_changed");
+            abort(signal);
+            return { bytes: buffer.subarray(0, length), physicalPath };
+        } finally { await handle.close(); }
+    } catch (error) {
+        if (error instanceof LocalSnapshotError) throw error;
+        const code = (error as NodeJS.ErrnoException)?.code;
+        throw new LocalSnapshotError(code === "ENOENT" ? "missing_file" : code === "ELOOP" ? "unsupported_file" : "read_failed");
+    }
+}