--- name: using-plastic description: PlasticSCM operations for Unity workflows - branch management, checkins, workspace isolation, and code reviews. --- # using-plastic Skill Purpose: PlasticSCM operations for Unity workflows. ## Critical Rule Never run `cm diff` in Pi. It may launch GUI windows and block the CLI agent. `cm cat --file=` writes to that path and can overwrite existing files; `--file` is never an input selector. Never point it at a canonical workspace file during inspection or review, even when piping stdout elsewhere. Use typed diff tools for baseline comparisons. If a typed tool cannot represent a required export, read the [historical export rules](references/changeset-operations.md#historical-export-fallback) first. A changeset number is not a file revision ID; never turn `cs:` into `revid:`. Never run interactive `cm merge --merge` flows. Use `plastic_merge` (preferred) or explicitly pass `--nointeractiveresolution --mergetype=try --conflict-markers` (safe default). Use source/destination policy flags only as explicit overrides. CM **11.0.16.10512** is the native workspace marker baseline. Default `plastic_merge(strategy="auto")` emits `--conflict-markers` for diff3 text conflicts without a GUI. Read the [marker workflow](../../docs/2026-10-23-marker-merges-and-comments.md). Exit 1 can mean partial application: do not reapply, force-finalize or check in automatically. Use `plastic_mergeListConflictMarkers`, edit/reconcile files, validate, then re-inspect markers AND remaining conflicts, source links, branch and pending scope. Observed complete ASCII CRLF `CONFLICT_MARKERS /path` exit-1 listings return informational `pending` (ok, but `commandCompleted=false`); pending and unknown both block checkin/closeout. Invalid UTF-8/Unicode-loss output remains unknown without fallback or retry. Listing paths are not mutation operands. An empty list is never all-conflict readiness. Binary, symlink, recursive, directory and delete-change conflicts still require explicit decisions. `plastic_mergeMarkResolved(paths=[...], acknowledgeIntentionalMarkers=true)` bypasses content checks only for intentional marker text in exact contained regular files, never real conflicts. No older-client fallback or automatic retry exists. For branch/label descriptions, scoped review discussions, reviewers and own-status changes, load [comments and review workflow](../../docs/2026-10-23-comments-and-review-workflow.md) on demand. Find exact comment GUIDs before reply/edit/delete; discard, deletion, status and re-request each need explicit intent. No automatic discussion, retry, editor or stdin fallback. Use `plastic_changesetEditComment` to replace/clear one exact changeset comment. Supply exactly one of `comment` (empty clears) or `commentsFile`; completion is not independent stored-text verification. Treat `plastic_merge` completion as provisional until independent marker and pending/full-status state is admitted. Pending merge links are expected until checkin; merge-in-progress hints are blockers. Checkin rejection requires listing/editing/validation and reinspection, not another forced merge or a backup/restore dance. Existing explicit `strategy="source"`/`"destination"` are intentional discard policies, not preservation or metadata-only completion proof. 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` for the separate workspace-free server-side route with explicit same-repository/server `br:/...@@` 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. 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. 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` 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:/@@`. 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 `/`, not `/`. The parent does not need to be the branch loaded in the workspace. Prefer `plastic_branchCreate(branch="", parent="")`; 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 CRITICAL: Use relative path references and load files only when needed for the current step. - Do NOT preemptively load all reference files. - Treat loaded references as mandatory instructions for the active task scope. - 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 Branch management -> ../using-plastic/references/branch-management.md Changesets -> ../using-plastic/references/changeset-operations.md Reviewing changes -> ../using-plastic/references/reviewing-changes.md Shelving -> ../using-plastic/references/shelving.md Workspaces -> ../using-plastic/references/workspaces.md Code review creation -> ../using-plastic/references/code-review-creation.md Integration -> ../using-plastic/references/integration.md Troubleshooting -> ../using-plastic/references/troubleshooting.md Resources -> ../using-plastic/references/resources.md Conventional commits -> ../_shared/references/conventional-commits.md