@aefree/pi-plastic 0.4.0

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@aefree/pi-plastic",
+  "version": "0.4.0",
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "keywords": [
+    "pi-package",
+    "plastic-scm",
+    "unity-version-control",
+    "developer-tools"
+  ],
+  "files": [
+    "index.ts",
+    "extensions/",
+    "src/",
+    "references/",
+    "skills/",
+    "evals/tool-loading/",
+    "tests/",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "LICENSE",
+    "README.md",
+    "SECURITY.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts",
+      "./extensions/plastic-branch-status.ts",
+      "./extensions/bash-cm-diff-guard.ts",
+      "./extensions/bash-cm-merge-guard.ts",
+      "./extensions/repository-search-provider.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "scripts": {
+    "test": "npx --yes tsx tests/plastic-tool-validation.ts && npx --yes tsx tests/plastic-checkin-path-resolution.ts && npx --yes tsx tests/plastic-diff-workflow.test.ts && npx --yes tsx tests/plastic-process-lifecycle.test.ts && npx --yes tsx tests/plastic-patch-command.test.ts && npx --yes tsx tests/plastic-extension-registration.test.ts && npx --yes tsx tests/plastic-dynamic-tool-loading.test.ts && npx --yes tsx tests/plastic-tool-rendering.test.ts && npx --yes tsx tests/plastic-branch-query.test.ts && npx --yes tsx tests/plastic-workspace.test.ts && npx --yes tsx tests/plastic-mutation-execution.test.ts && npx --yes tsx tests/repository-search-provider.test.ts && npx --yes tsx tests/repository-search-provider-registration.test.ts && npx --yes tsx tests/packed-copy-owner-conflict.test.ts && npx --yes tsx tests/plastic-branch-status.test.ts && npx --yes tsx tests/plastic-constrained-sampling.test.ts && npx --yes tsx tests/bash-cm-diff-guard-validation.ts",
+    "test:live": "npx --yes tsx tests/plastic-live-smoke.test.ts",
+    "test:live:branch-create": "npx --yes tsx tests/plastic-branch-create-live.test.ts",
+    "eval:tool-loading": "npx --yes tsx evals/tool-loading/run-eval.ts"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.83.0",
+    "typebox": "^1.3.8"
+  },
+  "peerDependencies": {
+    "@aefree/pi-repo-search": "^0.1.0",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "description": "Pi tools and skills for Plastic SCM and Unity Version Control workflows.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/aefreedman/pi-plastic.git"
+  },
+  "bugs": {
+    "url": "https://github.com/aefreedman/pi-plastic/issues"
+  },
+  "homepage": "https://github.com/aefreedman/pi-plastic#readme",
+  "peerDependenciesMeta": {
+    "@aefree/pi-repo-search": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  }
+}

package/skills/_shared/references/conventional-commits.md

@@ -0,0 +1,198 @@
+# Conventional Commits
+
+This reference file documents the conventional commit format used across the project.
+
+---
+
+## Format
+
+```
+<type>(<scope>): <subject>
+
+[optional body]
+
+[optional footer]
+```
+
+---
+
+## Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| **feat** | New feature | `feat(auth): add OAuth login` |
+| **fix** | Bug fix | `fix(cart): calculate tax correctly` |
+| **refactor** | Code restructuring (no behavior change) | `refactor(api): extract service layer` |
+| **perf** | Performance improvement | `perf(query): optimize user lookup` |
+| **test** | Adding or updating tests | `test(auth): add login edge cases` |
+| **docs** | Documentation changes | `docs(readme): update installation steps` |
+| **style** | Code style changes (formatting, etc.) | `style(lint): fix indentation` |
+| **chore** | Build process or auxiliary tool changes | `chore(deps): update to Rails 7.1` |
+| **ci** | CI/CD configuration changes | `ci(github): add test workflow` |
+
+---
+
+## Scope
+
+The scope is optional but recommended. It specifies which part of the codebase was affected:
+
+**Examples:**
+- `feat(player): add dash mechanic`
+- `fix(inventory): prevent negative quantities`
+- `refactor(ui): simplify menu navigation`
+- `perf(rendering): batch sprite draws`
+
+**Guidelines:**
+- Use lowercase
+- Be specific but concise
+- Match your module/component names
+- Omit if change is global
+
+---
+
+## Subject
+
+The subject contains a succinct description of the change:
+
+- **Use imperative mood:** "add" not "added" or "adds"
+- **Don't capitalize first letter:** "add feature" not "Add feature"
+- **No period at the end:** "fix bug" not "fix bug."
+- **Limit to 50 characters**
+
+**Good examples:**
+- `feat(auth): add password reset flow`
+- `fix(api): handle null responses`
+- `refactor(utils): extract string helpers`
+
+**Bad examples:**
+- `feat(auth): Added password reset flow` (not imperative)
+- `feat(auth): Add Password Reset Flow` (capitalized)
+- `feat(auth): add password reset flow.` (period at end)
+
+---
+
+## Body (Optional)
+
+Use the body to explain **what** and **why**, not **how**:
+
+```
+feat(player): add dash mechanic
+
+Adds a dash ability to the player character for enhanced mobility.
+Dash has 1-second cooldown and consumes 10 stamina.
+
+Closes #42
+```
+
+**Guidelines:**
+- Wrap at 72 characters
+- Separate from subject with blank line
+- Focus on context and reasoning
+- Link to issues if applicable
+
+---
+
+## Footer (Optional)
+
+Use footer for metadata:
+
+**Breaking changes:**
+```
+feat(api)!: change authentication endpoint
+
+BREAKING CHANGE: /api/login now requires email instead of username
+```
+
+**Issue references:**
+```
+fix(cart): calculate tax correctly
+
+Fixes #123
+Closes #124
+Related to #125
+```
+
+**Attribution:**
+```
+feat(dashboard): add analytics widget
+
+Co-Authored-By: <AI Assistant Name (e.g., Codex, Claude, Pi Coding Agent)>
+```
+
+---
+
+## Attribution Footer
+
+Add a simple attribution line in the footer when needed:
+
+```
+feat(feature): implement new capability
+
+[Body explaining the change]
+
+Co-Authored-By: <AI Assistant Name (e.g., Codex, Claude, Pi Coding Agent)>
+```
+
+---
+
+## Examples
+
+### Simple Feature
+```
+feat(player): add jump mechanic
+```
+
+### Bug Fix with Context
+```
+fix(inventory): prevent item duplication
+
+Items were duplicating when rapidly clicking the pickup button.
+Added debounce logic to prevent double-processing.
+
+Fixes #156
+```
+
+### Refactor with Explanation
+```
+refactor(rendering): extract camera controller
+
+Moved camera logic from PlayerController to dedicated CameraController
+for better separation of concerns and reusability.
+```
+
+### Performance Improvement
+```
+perf(physics): optimize collision detection
+
+Changed from O(n²) all-pairs check to spatial hashing.
+Reduces frame time by ~15ms with 100+ objects.
+```
+
+### Attribution Example
+```
+feat(multiplayer): add lobby system
+
+Implements matchmaking lobby with room creation, joining, and ready-up.
+Uses WebSocket for real-time updates.
+
+Closes #89
+
+Co-Authored-By: <AI Assistant Name (e.g., Codex, Claude, Pi Coding Agent)>
+```
+
+---
+
+## Usage in Skills
+
+**Reference this file when:**
+- Creating commits (Git or Plastic)
+- Generating commit messages
+- Validating commit format
+- Writing PR/code review descriptions
+
+**Load this file:**
+```markdown
+Load conventional commit format from ../../_shared/references/conventional-commits.md
+```
+
+Then format all commits according to this standard.

package/skills/using-plastic/SKILL.md

@@ -0,0 +1,50 @@
+---
+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.
+
+Never run interactive `cm merge --merge` flows. Use `plastic_merge` (preferred) or explicitly pass `--nointeractiveresolution --mergetype=try` (safe default). Use source/destination policy flags only as explicit overrides.
+
+Treat `plastic_merge` success as provisional until `plastic_status` confirms there are no merge-in-progress hints. Pending merge links are expected until the merge result is checked in; merge-in-progress hints are not. If files are manually resolved and validated but checkin is blocked by Plastic merge metadata, use `plastic_finalizeMerge` with an explicit source/destination policy before retrying checkin.
+
+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.
+
+`plastic_diff` is intentionally disabled. For the common workspace change, use `plastic_diffFile(path="<workspace-path>")` with no revision; it materializes the Plastic base internally and returns a bounded portable text diff. Use a revision only when needed: a changeset number/`cs:<number>`, `br:/<branch>`, `lb:<label>`, file-qualified spec, or global `revid:`/`rev:` spec. `base`, `head`, and `cs:head` are intentionally rejected rather than guessed. Use `plastic_diffRevisions` only for two explicit file-qualified revisions. Binary content is reported rather than decoded as text.
+
+Use `plastic_status()` for “what changed?” and changed-path/status listing; do not use `cm diff` formatting for that purpose. Use `plastic_patch` for review patch generation with `clean` and `integration` filters; it is generation-only and does not apply patches. It uses `PI_PLASTIC_DIFF_EXECUTABLE` when set, otherwise portable `diff` on PATH; pass `toolPath` only for an intentional one-call override. For a large patch, pass an intentional new `output` path because Plastic will not overwrite it.
+
+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, use available preflight modes, and rely on the tools' command, workspace, path-containment, and non-interactive process guards. 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.
+
+## 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.
+
+## 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

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

@@ -0,0 +1,78 @@
+# Branch Management
+
+## Detect Current Branch
+
+```bash
+current_branch=$(cm status | head -1 | cut -d@ -f1 | xargs)
+```
+
+## Detect Naming Convention
+
+```bash
+cm find branches --format="{name}" | head -20
+```
+
+Use the detected parent branch from the repository instead of copying a branch name from documentation.
+
+## Create Branch
+
+Normal work branches must be children of an intended parent branch. Create `<parent-branch>/<new-branch>`, not `/<new-branch>`. The parent may differ from the branch loaded in the workspace; Plastic bases the new branch on the parent's latest changeset by default.
+
+Preferred tool-first flow:
+
+```text
+plastic_branchCreate(
+  branch="<new-branch>",
+  parent="<parent-branch>",
+  comment="<branch-description>",
+) # creates <parent-branch>/<new-branch>
+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.
+
+Manual shell fallback requires constructing the hierarchical path explicitly:
+
+```bash
+cm branch create "<parent-branch>/<new-branch>" -c="<branch-description>"
+cm switch --silent --noinput "<parent-branch>/<new-branch>"
+```
+
+Agent preference: use runtime `plastic_*` methods first; keep shell commands as manual fallback
+
+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.
+
+## Merge Branches (Non-Interactive)
+
+Preferred tool-first flow:
+
+```text
+plastic_merge(source="<source-branch-spec>")
+```
+
+Manual shell fallback:
+
+```bash
+cm merge <source-branch-spec> --merge --nointeractiveresolution --mergetype=try
+```
+
+Optional explicit override (higher clobber risk, use only when required):
+
+```text
+plastic_merge(source="<source-branch-spec>", strategy="destination")
+plastic_merge(source="<source-branch-spec>", strategy="source")
+```
+
+## Naming Guidelines
+
+- Prefer a leaf name plus an explicit `parent` with `plastic_branchCreate`.
+- The parent branch may differ from the branch currently loaded in the workspace.
+- For full paths and manual `cm` commands, start with `/` and include the intended parent branch.
+- Never shorten `<parent-branch>/<new-branch>` to `/<new-branch>`; that creates a top-level branch.
+- Use lowercase and hyphens
+- Follow repository conventions
+- Check for issue-tracker conventions in branch names like issue ID prefixes

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

@@ -0,0 +1,96 @@
+# Changeset Operations
+
+## Status
+
+```bash
+cm status --all
+```
+
+Tool-first:
+
+```text
+plastic_status()
+```
+
+## Add Files
+
+```bash
+cm add <workspace-path>
+```
+
+## Checkin
+
+```bash
+cm checkin -c="feat(player): add dash mechanic"
+```
+
+Tool-first:
+
+```text
+plastic_checkin(message="feat(player): add dash mechanic", includeAll=true)
+```
+
+Unattended behavior notes:
+
+- `includeAll=true` includes changed/moved/deleted tracked items, but does not include private items by itself.
+- `plastic_checkin` now inspects machine-readable pending changes before running checkin.
+- If Plastic reports `There are no changes in the workspace` and only private items are pending in scope,
+  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.
+
+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.
+
+## Checkins With Deletions
+
+Before checkin, verify deleted items are present in pending changes:
+
+```bash
+cm status --all
+```
+
+Safe checklist:
+- Confirm deleted items appear in status output before checkin.
+- Prefer `plastic_checkin(preflight=true, paths=[...])` so the tool can rewrite unstable file scopes (moved/deleted) to stable parent scopes.
+- `plastic_checkin` now inspects `cm status --machinereadable` and auto-enables `--applychanged` when moved/deleted items are in scope.
+- Re-run `cm status --all` after add/scope changes, then checkin.
+
+Example path-scoped checkin including a deletion:
+
+```bash
+cm checkin -c="<commit-message>" <workspace-path-1> <workspace-path-2>
+```
+
+Use full-scope checkin when in doubt:
+
+```bash
+cm checkin -c="<commit-message>"
+```
+
+## Safe Diff Usage
+
+Never run `cm diff` in Pi.
+
+Use one of these safe alternatives:
+
+```text
+plastic_status(machineReadable=true) # list pending paths/statuses
+plastic_diffFile(path="<workspace-path>") # common workspace-base diff
+plastic_diffFile(path="<workspace-path>", revision="cs:<number>")
+plastic_diffRevisions(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.
+
+## Commit Message Format
+
+Use conventional commits from ../../_shared/references/conventional-commits.md.
+
+## Changeset History
+
+```bash
+cm find changeset --orderby="date desc" --limit=20 \
+  --format="{changesetid} {date} {owner} {comment}"
+```

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

@@ -0,0 +1,30 @@
+# Code Review Creation
+
+## CLI (Preferred)
+
+```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"
+
+# List reviews for this branch
+cm find review "where target='br:${branch}'" --format="{id} {status} {title}"
+```
+
+Agent preference: use runtime `plastic_*` methods first for status/branch lookup; keep shell commands as manual fallback.
+
+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.
+
+Tool-first flow (preferred):
+
+```text
+plastic_status()
+# Then use cm codereview ... as fallback for review create/assign
+```
+
+## CLI Not Available
+
+- Document branch and changeset in plan/issue tracker.
+- Or create review via Plastic GUI and assign a reviewer before sharing the review link.

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

@@ -0,0 +1,47 @@
+# Integration Points
+
+## Work Workflow
+
+- Create feature branch following detected conventions.
+- Use incremental checkins.
+- Never use `cm diff`; use text-only diff tools.
+- Use `plastic_merge` (or `cm merge ... --nointeractiveresolution --mergetype=try`) for autonomous merges.
+
+## Autonomous Merge Workflow
+
+- Switch to the target branch/workspace and ensure you understand the current pending state.
+- Run `plastic_merge(...)`.
+- If Plastic stops on a delete/change directory conflict and source deletion is the intended resolution, run `plastic_resolveDeleteChangeConflict(...)`, then rerun `plastic_merge(...)`.
+- Immediately run `plastic_status()` and treat it as the source of truth.
+- Do not treat merge-tool success alone as proof that the merge is finished.
+- If `plastic_status()` still shows `Pending merge links`, merge-in-progress state, or conflict-like pending items, stop and follow troubleshooting before any checkin.
+- After compile/tests, run `plastic_status()` again so Unity-generated private artifacts are not mistaken for merge fallout.
+- Only then create the merge checkin.
+
+## Review Workflow
+
+- Create or reuse review workspace.
+- Switch to target branch and list recent changesets:
+
+```bash
+cm find changeset "where branch = '<branch-name>' order by changesetid desc limit 20" --format="{changesetid} {owner} {date} {comment}" --nototal
+```
+
+- Generate a focused branch-review patch when a whole-branch view is useful:
+
+```text
+plastic_patch(source="<branch-spec>", integration=true)
+plastic_patch(source="<branch-spec>", clean=true, integration=true, output="<patch-file>")
+```
+
+- Inspect specific file content changes with the common workspace-base path first:
+
+```text
+plastic_diffFile(path="<workspace-path>")
+plastic_diffFile(path="<workspace-path>", revision="cs:<number>")
+plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>")
+```
+
+## Plan Workflow
+
+- Search changeset history for related work.

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

@@ -0,0 +1,32 @@
+# Plastic Quick Reference
+
+Use runtime `plastic_*` tools first. Keep shell commands below as manual fallback.
+
+Note: command examples target current `cm` 11.x CLI syntax; legacy aliases may differ.
+
+| Operation | Preferred tool method | Shell fallback | Notes |
+|-----------|------------------------|----------------|-------|
+| Status | `plastic_status()` | `cm status` | Pending changes |
+| Current branch | `plastic_currentBranch()` | `cm status | head -1 | cut -d@ -f1 | xargs` | Reads active branch |
+| Create child branch | `plastic_branchCreate(branch="<new-branch>", parent="<parent-branch>")` | `cm branch create <parent-branch>/<new-branch>` | Parent may differ from the loaded branch; top-level creation requires explicit override |
+| Switch branch | `plastic_switchBranch(branch="<branch-spec>")` | `cm switch --silent --noinput <branch-spec>` | `pendingChanges="shelve"` for tracked pending changes; private-only pending changes switch directly unattended |
+| Add files | `plastic_add(paths=[...])` | `cm add <files>` | Stage for checkin |
+| Checkin | `plastic_checkin(message="...")` | `cm checkin -c="message"` | Commit changes (`includeAll` excludes private unless added/`includePrivate`) |
+| Update | `plastic_update()` | `cm update --dontmerge --noinput` | Pull latest without interactive merge |
+| Merge | `plastic_merge(source="<source-branch-spec>")` | `cm merge <source-branch-spec> --merge --nointeractiveresolution --mergetype=try` | Surfaces `FILE_CONFLICT`; run `plastic_status()` before checkin |
+| Finalize merge metadata | `plastic_finalizeMerge(source="<source-branch-spec>", strategy="destination")` | `cm merge <source-branch-spec> --merge --nointeractiveresolution --mergetype=forced --keepdestination` | Use after manual/reviewed resolution when checkin says merge is still in progress |
+| 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="<patch-file>")` | `cm patch <branch-spec> --clean --integration --output=<patch-file>` | Focused branch-review patch; inspect before sharing |
+| Changed-file listing | `plastic_status(machineReadable=true)` | `cm status --all` | Lists changed, added, moved, deleted, and private items without GUI diff |
+| Diff (workspace vs Plastic base) | `plastic_diffFile(path="<workspace-path>")` | None recommended | Bounded portable text diff; no guessed revision needed |
+| 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 |
+
+## Merge verification checklist
+
+- Run `plastic_merge(...)`.
+- If `plastic_merge(...)` reports `FILE_CONFLICT`, inspect/resolve the listed paths and validate before finalizing.
+- Immediately run `plastic_status()`.
+- Pending merge links are expected until the merge result is checked in; merge-in-progress hints are blockers.
+- If validation/tests were run after the merge, run `plastic_status()` again before checkin so generated private artifacts do not muddy the result.
+- If `plastic_checkin(...)` says a merge is still in progress after files are resolved and validated, run `plastic_finalizeMerge(source=..., strategy="destination")`, then retry checkin.

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

@@ -0,0 +1,7 @@
+# Resources
+
+- CLI Reference: https://docs.unity.com/en-us/unity-version-control/uvcs-cli
+- Branch Management: https://docs.unity.com/en-us/unity-version-control/branches
+- Code Reviews: https://docs.unity.com/en-us/unity-version-control/code-reviews
+
+Minimum version: PlasticSCM 11.0+