@polygraph/claude-plugin 0.4.21

package/skills/await-polygraph-ci/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: await-polygraph-ci
+description: Wait for CI to settle across all repos in a Polygraph session, then report results and investigate failures. USE WHEN user says "await polygraph", "wait for polygraph ci", "polygraph ci status", "check polygraph ci", "watch polygraph session", "monitor polygraph".
+
+user-invocable: true
+allowed-tools:
+  - Bash
+  - Read
+  - Task
+  - AskUserQuestion
+  - mcp__plugin_polygraph_polygraph-mcp
+  - mcp__plugin_nx_nx-mcp
+
+---
+
+# Await Polygraph CI
+
+Wait for all CI pipelines in a Polygraph session to reach a stable state (succeeded, failed, etc.), then produce a unified summary. If any pipelines failed, investigate via child agents and present fix options.
+
+Some Polygraph tools have both MCP and CLI equivalents — use whichever is available in your environment. See the polygraph skill's tool table for the full mapping.
+
+## Phase 1: Session Setup
+
+Fetch the Polygraph session using `show_session`.
+
+**Parameters:**
+
+- `sessionId` (required): The Polygraph session ID
+
+```
+show_session(sessionId: "<session-id>")
+```
+
+1. Record `monitorStartedAt` = current timestamp (epoch millis).
+2. Build a tracking table of all repos with PRs. For each PR, record:
+   - `repo`: repository name
+   - `prUrl`: PR URL
+   - `prStatus`: DRAFT / OPEN / MERGED / CLOSED
+   - `ciStatus`: from session (may already be a terminal status from a previous run)
+   - `cipeUrl`: CI pipeline URL (null if none)
+   - `cipeCompletedAt`: `completedAt` from session (epoch millis, null if CIPE is active or absent)
+   - `selfHealingStatus`: self-healing fix status (null if none)
+   - `firstSeenAt`: current timestamp
+3. If no PRs found, report "No PRs in session" and exit.
+4. **Stale detection**: For each PR, determine if its CI status is **stale** — meaning it reflects a previous run, not a current one. A PR's CI status is stale if:
+   - `cipeCompletedAt` is non-null AND `cipeCompletedAt < monitorStartedAt` (the CIPE finished before the monitor started)
+   - Mark these PRs as `stale: true`
+5. Display the initial status table, annotating stale PRs:
+   ```
+   backend: SUCCEEDED (stale) | frontend: SUCCEEDED (stale) | shared-lib: NOT_STARTED
+   ```
+
+## Phase 2: Polling Loop
+
+**Configuration:**
+
+- Timeout: 30 minutes total
+- Backoff: 60s → 90s → 120s (cap)
+- Circuit breaker: exit after 5 consecutive polls with no status change
+
+**Each poll iteration:**
+
+1. Call `show_session(sessionId: <session-id>)`
+2. Update each tracked PR from the session response: `ciStatus`, `cipeUrl`, `cipeCompletedAt`, and `selfHealingStatus`
+3. **Clear stale flag**: If a PR was marked `stale: true` and its `cipeCompletedAt` has changed (or become null, meaning a new CIPE is active), clear the stale flag — this PR now has fresh CI data.
+4. Display status update:
+   ```
+   [await-polygraph-ci] Poll #N | Elapsed: Xm | Repos: Y total, Z completed
+    backend: SUCCEEDED | frontend: FAILED (self-healing: PENDING) | shared-lib: SUCCEEDED (stale)
+   ```
+   Include `selfHealingStatus` inline when non-null. Annotate stale PRs.
+5. Check exclusion rule: if a PR has `prStatus: DRAFT` and `ciStatus: NOT_STARTED` for more than 5 minutes since `firstSeenAt`, mark it as `EXCLUDED` (DRAFT PRs may not trigger CI)
+6. Check terminal conditions — a PR is terminal when:
+   - It is NOT stale, AND:
+     - CI status is `SUCCEEDED`, `CANCELED`, or `TIMED_OUT`, OR
+     - CI status is `FAILED` AND there is no active self-healing (i.e., `selfHealingStatus` is null or a final state like `APPLIED`, `REJECTED`, `FAILED`)
+   - A `FAILED` PR with `selfHealingStatus` indicating an in-progress fix (e.g., `PENDING`, `IN_PROGRESS`) is NOT terminal — keep polling to track the self-healing outcome
+   - A **stale** PR is NOT terminal — keep polling until it gets a fresh CIPE or is excluded
+7. **Stale timeout**: If a stale PR remains stale for more than 5 minutes, assume no new CI is expected for it. Clear the stale flag and treat its current status as final.
+8. If all non-excluded PRs are terminal → proceed to Phase 3
+9. If timeout or circuit breaker hit → proceed to Phase 3 with partial results
+10. Otherwise → wait with backoff, then poll again
+
+## Phase 3: Results Analysis
+
+Categorize repos into: succeeded, failed, canceled, timed_out, excluded, in_progress (if timed out).
+
+Display final summary table. When showing self-healing status, distinguish clearly between these states:
+
+- `COMPLETED` = a fix was **generated and verified**, but **NOT yet applied**. Display as `fix available`.
+- `APPLIED` = the fix was **applied** by the user or agent. Display as `fix applied, awaiting re-run`.
+- `IN_PROGRESS` / `PENDING` = the fix is still being generated. Display as `in progress`.
+- `REJECTED` = the fix was rejected. Display as `fix rejected`.
+- `FAILED` = self-healing failed to produce a fix. Display as `fix failed`.
+
+```
+[await-polygraph-ci] Final Results | Elapsed: Xm
+ SUCCEEDED: backend, shared-lib
+ FAILED: frontend (self-healing: fix available)
+ EXCLUDED: docs (DRAFT, no CI)
+```
+
+Include self-healing status for any repo that has one.
+
+- If all succeeded → report success and exit
+- If any failed with `selfHealingStatus: APPLIED`, inform the user that the fix was applied and a CI re-run may be in progress or needed
+- If any failed with `selfHealingStatus: COMPLETED`, inform the user that a fix is **available but not yet applied**, and offer to apply it
+- If any failed → proceed to Phase 4
+
+## Phase 4: Failure Investigation (Child Agent Delegation)
+
+For each repo with `ciStatus: FAILED`, first check the CI data source from `ciStatus[prId]`:
+
+- **If `cipeUrl` is non-null** → CIPE is authoritative. Delegate investigation using `ci_information`.
+- **If `cipeUrl` is null but `externalCIRuns` exists** → external CI only. Examine failed jobs from `externalCIRuns` in the session data and use `get_ci_logs` for log retrieval.
+
+1. Display known info from the session data before delegating:
+
+   ```
+   Repository: frontend
+   CI Source: <CIPE or External CI (GitHub Actions)>
+   CI Pipeline: <cipeUrl from session, or GitHub Actions run URL>
+   Self-healing: <selfHealingStatus from session, or "None">
+   Investigating failure details...
+   ```
+
+2. **Delegate investigation** (non-blocking) — call `spawn_agent` for each failed repo:
+
+   - `sessionId`: the session ID
+   - `repo`: the repository name
+   - `instruction` (when CIPE exists): Use the `ci_information` tool to investigate the CI failure on this branch. Return a structured summary with: (1) list of failed task IDs with a one-line error summary each, (2) failure category (Build / Test / Lint / E2E / Infra / Other).
+   - `instruction` (when no CIPE, external CI only): The session data shows external CI failures with these failed jobs: [list jobId + name from `externalCIRuns[].jobs` where `conclusion` is `failure`]. Use `get_ci_logs(sessionId, repoId, jobId)` to save the log for each failed job to a local file, then use the `Read` tool to examine the log file contents. Return a structured summary with: (1) one-line error summary per failed job, (2) failure category (Build / Test / Lint / E2E / Infra / Other), (3) relevant log excerpts.
+   - `context`: Polygraph session monitoring — investigating CI failure for unified summary. The repository ID for this repo is available from the session data.
+
+   Since `spawn_agent` is non-blocking, you can delegate to multiple failed repos in parallel.
+
+3. **Monitor investigation progress** — poll `show_agent` to wait for each child agent to complete:
+
+   ```
+   show_agent(sessionId: "<session-id>", repo: "frontend")
+   ```
+
+   Poll until the child agent's status indicates completion. Use the `tail` parameter to retrieve recent output lines containing the investigation results.
+
+4. Collect each child agent's response from the status output. If a child agent fails or gets stuck, use `stop_agent` to terminate it and skip that repo.
+
+5. Display failure summary for each repo:
+
+   ```
+   Repository: frontend
+   CI Pipeline: <cipeUrl>
+   Failed Tasks (2):
+     - frontend:build → TypeScript error in src/app.tsx:42
+     - frontend:test  → 3 test suites failed
+   Category: Build + Test failures
+   Self-healing: <selfHealingStatus>
+   Job Logs: <number of logs retrieved, if any>
+   ```
+
+   If CI job logs were retrieved via `get_ci_logs`, include relevant excerpts (error messages, stack traces) in the summary. Keep excerpts concise — only the most relevant lines.
+
+## Phase 5: Fix Planning
+
+1. Group failures by category (Build, Test, Lint, E2E, Infra)
+2. Identify cross-repo dependency issues (e.g., shared-lib build failure blocking frontend)
+3. Suggest fix order based on dependency graph (upstream repos first)
+4. Present next actions to the user based on self-healing status:
+   - If any repo has `selfHealingStatus` with an available fix → offer to **apply self-healing** via `update_self_healing_fix(action: "APPLY")` or **reject** it
+   - If self-healing was already applied → offer to **resume monitoring** to watch the re-triggered CI
+   - **Delegate fixes**: use Polygraph to send fix instructions to child agents (for repos without self-healing or where self-healing was rejected/failed)
+   - **Get more details**: drill into a specific repo's failure
+   - **Exit**: done monitoring
+
+## Notes
+
+- This skill does NOT push code directly. The only write action it may take is applying/rejecting a self-healing fix via `update_self_healing_fix`, which is an Nx Cloud operation (not a local code change).
+- Both `ci_information` and `update_self_healing_fix` responses include a `hints` array with contextual guidance (e.g., disclaimers about which CI Attempt was retrieved). Always check and surface non-empty hints.
+- All heavy CI data inspection happens in child agents via `spawn_agent` to keep this context window clean.
+
+- Child agents can use `get_ci_logs` to save CI job logs to local files, but ONLY when no CIPE exists for the PR (`ciStatus[prId].cipeUrl` is null). When a CIPE exists, logs come from the CIPE system via `ci_information`. Job IDs come from `ciStatus[prId].externalCIRuns[].jobs[].jobId` in the `show_session` response. The tool returns a file path (`logFile`) and size (`sizeBytes`) — use the `Read` tool to examine the log content. Logs can be large (100KB+), so only fetch logs for failed or relevant jobs.
+- `spawn_agent` is **non-blocking** — it starts the child agent and returns immediately. Use `show_agent` to poll for results and `stop_agent` to terminate stuck agents.
+- The `show_session` response is compact and safe to poll from the main agent.

package/skills/get-latest-ci/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: get-latest-ci
+description: Fetch the latest CI pipeline execution for the current branch. Returns the most recent CIPE which may be completed, in progress, or null. Use when you need to review CI status, check failures, or inspect CI state.
+
+allowed-tools:
+  - mcp__plugin_nx_nx-mcp
+
+---
+
+# Get Latest CI Information
+
+Fetch the latest CI pipeline execution for the current branch. This is a **one-shot fetch** — return results immediately. Do NOT poll, loop, or wait for status changes.
+
+## Context
+
+- **Current Branch:** !`git branch --show-current`
+- **Current Commit:** !`git rev-parse --short HEAD`
+
+## Step 1: Fetch CI Status via Subagent
+
+Spawn a `general-purpose` subagent using the Task tool. The subagent will call the MCP tool and return results. Do NOT attempt to fetch CI information yourself — always delegate to the subagent.
+
+```
+Task(
+  subagent_type: "general-purpose",
+  description: "Fetch latest CI status",
+  prompt: "Fetch the latest CI pipeline execution status. Do NOT use Bash for this.
+
+    Use the ci_information tool from the nx MCP server with these parameters:
+      select: 'cipeStatus,cipeUrl,branch,commitSha,selfHealingStatus,verificationStatus,userAction,failedTaskIds,verifiedTaskIds,selfHealingEnabled,failureClassification,couldAutoApplyTasks,shortLink,confidence,confidenceReasoning,hints'
+
+    Return ALL fields from the response as-is. Do not summarize or omit any fields.
+
+    If cipeStatus is FAILED and selfHealingStatus is COMPLETED or FAILED and there are failedTaskIds, make a SECOND call to the same tool with:
+      select: 'taskOutputSummary,suggestedFix,suggestedFixReasoning,suggestedFixDescription'
+
+    Return those fields too. Only return the first page — do not paginate."
+)
+```
+
+## Step 2: Report Results
+
+Based on the subagent's response, report to the user. Always include the CIPE URL when available.
+
+If the response contains a non-empty `hints` array, include those hints in the output to the user.
+
+### No CIPE found (null/empty response)
+
+```
+[get-latest-ci] No CI pipeline execution found for branch '<branch>'.
+```
+
+### CI Succeeded
+
+```
+[get-latest-ci] CI passed!
+[get-latest-ci] URL: <cipeUrl>
+[get-latest-ci] Commit: <commitSha>
+```
+
+### CI In Progress / Not Started
+
+```
+[get-latest-ci] CI is <IN_PROGRESS|NOT_STARTED>.
+[get-latest-ci] URL: <cipeUrl>
+[get-latest-ci] Commit: <commitSha>
+```
+
+If self-healing is also in progress, add:
+
+```
+[get-latest-ci] Self-healing: <selfHealingStatus> | Verification: <verificationStatus>
+```
+
+### CI Failed — With Self-Healing Fix Available
+
+When `cipeStatus == 'FAILED'` AND `selfHealingStatus == 'COMPLETED'` AND `suggestedFix != null`:
+
+```
+[get-latest-ci] CI failed.
+[get-latest-ci] URL: <cipeUrl>
+[get-latest-ci] Commit: <commitSha>
+[get-latest-ci] Failed tasks: <failedTaskIds>
+[get-latest-ci]
+[get-latest-ci] Self-healing fix available!
+[get-latest-ci] Short link: <shortLink>
+[get-latest-ci] Confidence: <confidence> — <confidenceReasoning>
+[get-latest-ci] Verification: <verificationStatus>
+[get-latest-ci] Auto-apply eligible: <couldAutoApplyTasks>
+[get-latest-ci]
+[get-latest-ci] Fix description: <suggestedFixDescription>
+[get-latest-ci] Fix reasoning: <suggestedFixReasoning> (truncated to first page)
+```
+
+### CI Failed — Self-Healing In Progress
+
+When `cipeStatus == 'FAILED'` AND `selfHealingStatus == 'IN_PROGRESS'`:
+
+```
+[get-latest-ci] CI failed. Self-healing is generating a fix...
+[get-latest-ci] URL: <cipeUrl>
+[get-latest-ci] Commit: <commitSha>
+[get-latest-ci] Failed tasks: <failedTaskIds>
+[get-latest-ci]
+[get-latest-ci] Use /monitor-ci to wait for the fix and apply it.
+```
+
+### CI Failed — Self-Healing Failed or Not Available
+
+When `cipeStatus == 'FAILED'` AND (`selfHealingStatus` is `FAILED`, `NOT_EXECUTABLE`, or `null`):
+
+```
+[get-latest-ci] CI failed.
+[get-latest-ci] URL: <cipeUrl>
+[get-latest-ci] Commit: <commitSha>
+[get-latest-ci] Failed tasks: <failedTaskIds>
+[get-latest-ci] Self-healing: <selfHealingStatus or "not available">
+[get-latest-ci] Classification: <failureClassification>
+```
+
+If `taskOutputSummary` was fetched, include a brief summary of failures.
+
+### CI Failed — Environment Issue
+
+When `failureClassification == 'ENVIRONMENT_STATE'`:
+
+```
+[get-latest-ci] CI failed due to environment issue.
+[get-latest-ci] URL: <cipeUrl>
+[get-latest-ci] Classification: ENVIRONMENT_STATE
+[get-latest-ci]
+[get-latest-ci] Use /monitor-ci to request an environment rerun.
+```
+
+### CI Canceled / Timed Out
+
+```
+[get-latest-ci] CI was <CANCELED|TIMED_OUT>.
+[get-latest-ci] URL: <cipeUrl>
+[get-latest-ci] Commit: <commitSha>
+```
+
+### CI Failed — No Tasks Recorded
+
+When `cipeStatus == 'FAILED'` AND `failedTaskIds` is empty AND `selfHealingStatus` is null:
+
+```
+[get-latest-ci] CI failed but no Nx tasks were recorded (likely infrastructure issue).
+[get-latest-ci] URL: <cipeUrl>
+[get-latest-ci] Check CI provider logs for details.
+```
+
+## Important
+
+- This skill is **read-only**. Do NOT apply fixes, push code, or modify anything.
+
+- Always delegate the MCP call to a subagent. Do NOT call ci_information yourself.
+
+- If the user wants to act on the results (apply a fix, monitor, etc.), suggest `/monitor-ci`.
+- If the subagent returns an error, report it and suggest the user check their Nx Cloud connection.

package/skills/pack-and-copy/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: pack-and-copy
+description: Validate a publisher package change against consumer repos by building + packing the publisher and installing the tarballs into each consumer, so consumer CI can run against the unmerged change. USE WHEN a publisher repo (e.g. a design system, shared library, SDK) has a pending change that needs to be tested in downstream repos before its version is merged and published. TRIGGER when user says "pack and copy", "pre-release test in consumers", "test this package change in <consumer>", "install the unreleased version into the apps", or "validate this change against <consumer repo>".
+
+user-invocable: true
+allowed-tools:
+  - Bash
+  - Read
+  - Task
+  - AskUserQuestion
+
+---
+
+# Pack and Copy
+
+Validate a publisher package change against its consumer repos **before** the publisher's version bump is merged and published. The flow is:
+
+1. Build the publisher package(s) — repo-specific, not automatable.
+2. Run `polygraph _pack-and-copy` (or the `pack_and_copy` MCP tool) to pack them and install the tarballs into each consumer, rewriting `package.json` to a `file:` dependency.
+3. Commit the consumer changes, including `.polygraph-packages/*.tgz`, to a branch, open a PR, and let consumer CI validate the change.
+
+This skill covers **steps 1 and 2**. PR creation / CI monitoring is left to the `polygraph` and `await-polygraph-ci` skills.
+
+## Available Tools
+
+Pack-and-copy functionality is available via both an MCP tool and a CLI command. Use whichever is available in your current environment.
+
+| MCP Tool | CLI Equivalent | Description |
+| --- | --- | --- |
+| `pack_and_copy` | `polygraph _pack-and-copy` | Pack publisher packages and install tarballs into consumer repos for pre-release validation. |
+
+Session discovery / inspection tools (`show_session`, `list_repos`, etc.) come from the `polygraph` skill — see that skill's tool table for the full mapping.
+
+## Prerequisites
+
+- An active Polygraph session that includes the publisher repo and one or more consumer repos. If you don't have a session yet, run the `polygraph` skill first to create one.
+- The publisher repo's built artifacts are **packable** — i.e. running `npm pack` in the package directory produces a tarball that, when installed, Just Works. If the publisher needs to be built first, you'll need to do that explicitly.
+
+## Phase 1: Identify Publishers and Consumers
+
+Determine which packages are being changed in the publisher, and which consumer repos need to validate the change.
+
+**If the user specified them**, skip to Phase 2.
+
+**Otherwise**, inspect the session and the publisher's change:
+
+1. Call `show_session(sessionId)` to enumerate the repos in the session and their local paths.
+2. The **publisher** is usually the current repo (where the change is being made). Look at its `package.json` files to find the packages being shipped — the one being changed, or all packages in a monorepo package tree.
+3. The **consumers** are the other repos in the session. Only repos that actually depend on one of the publisher's packages are relevant — the command will auto-skip the rest, but listing them up front keeps the user informed.
+
+Before proceeding, print a short table:
+
+| Publisher package | Publisher path          | Consumer repo | Consumer path     |
+| ----------------- | ----------------------- | ------------- | ----------------- |
+| @org/tokens       | /path/to/ds/packages/tokens | web-app       | /path/to/web-app |
+| @org/button       | /path/to/ds/packages/button | web-app       | /path/to/web-app |
+
+and confirm with the user using `AskUserQuestion` if anything is ambiguous.
+
+## Phase 2: Build the Publisher Packages
+
+**This step is not automatable.** Build commands vary per repo and per package. Ask the user how to build, or inspect the repo for conventions.
+
+Common hints to surface to the user:
+
+- A root-level `package.json` with a `build` script that builds all packages (e.g. `npm run build`, `nx run-many -t build`, `pnpm -r build`).
+- Per-package `build` scripts (check each publisher's `package.json`).
+- A `prepack` script — if one exists, `npm pack` will run it automatically and you don't need a separate build step.
+
+Run the build. Verify the `dist/` or equivalent output exists in each publisher package directory before proceeding.
+
+**If the build fails**, surface the error to the user and stop. Do not attempt to pack a broken package.
+
+## Phase 3: Pack and Copy
+
+Run `polygraph _pack-and-copy` (or the `pack_and_copy` MCP tool), passing a `--pair` for every (publisher, consumer) combination the user wants to test. The command is deterministic: it computes a unique pre-release version, runs `npm pack` in each publisher, copies the tarballs into each consumer's `.polygraph-packages/` directory, rewrites the consumer's `package.json` deps to point at the tarballs via `file:`, and POSTs a summary of published and consumed packages to the Polygraph session so the UI reflects what was packed where.
+
+CLI form:
+
+```bash
+polygraph _pack-and-copy \
+  --session <session-id> \
+  --pair <publisher-path>=<consumer-path> \
+  [--pair <publisher-path>=<consumer-path> ...] \
+  --json
+```
+
+MCP tool form — call `pack_and_copy` with:
+
+- `sessionId` (string, required): the Polygraph session ID
+- `pairs` (array, required): one `{ publisherPath, consumerPath }` object per (publisher, consumer) combination
+- `runScripts` (boolean, optional): enable npm lifecycle scripts during `npm pack` (off by default)
+
+**Notes:**
+
+- `<publisher-path>` / `publisherPath` is the directory containing the publisher package's `package.json` (not necessarily the repo root — for monorepos, this is `packages/<name>/`).
+- `<consumer-path>` / `consumerPath` is the consumer repo's root (where its `package.json` lives).
+- If a consumer doesn't declare a dependency on a publisher's package, that pair is silently skipped for that consumer — the tarball is still produced but not installed there.
+- The command creates a new unique version on each run, but package managers can still keep stale `file:` dependency contents in `node_modules`. Use a forced install on reruns if the consumer still sees old package contents.
+- Consumers' `.polygraph-packages/*.tgz` files **must be tracked and committed** with the consumer branch. Fresh CI clones need those tarballs to install the `file:` dependencies.
+
+Parse the JSON output to get the `published` and `consumed` summaries. Print them back to the user:
+
+```
+Packed:
+- @org/tokens  1.4.2 -> 1.4.3-pg.<session>.<timestamp>
+- @org/button  2.1.0 -> 2.1.1-pg.<session>.<timestamp>
+
+Installed into:
+- web-app: @org/tokens, @org/button
+- docs:    @org/tokens
+```
+
+## Phase 4: Install in Consumers and Commit
+
+For each consumer that received a tarball:
+
+1. Run the consumer's package manager install command, e.g. `npm install`, `pnpm install`, or `yarn install`, so the lockfile and `node_modules/` reflect the new `file:` dep. On reruns in the same worktree, use `npm install --force`, `pnpm install --force`, or `yarn install --force` if the consumer still sees old package contents.
+2. Commit the `package.json`, lockfile, and `.polygraph-packages/*.tgz` changes on a dedicated branch.
+
+3. Push the branch and open a draft PR using the `polygraph` skill's `push_branch` + `create_pr` flow — **not** directly. The PR description should explain that this is validating an unmerged publisher change.
+
+4. Once CI results come in (see the `await-polygraph-ci` skill), report back. Do **not** merge any consumer PR opened via this flow — these PRs are for validation only and should be closed once the publisher's real version lands.
+
+## Common Pitfalls
+
+- **Forgetting to build**: `npm pack` packs whatever the package's `files` field points at. If `dist/` is stale or missing, the tarball will be broken. Always rebuild before packing unless a `prepack` script does it.
+- **Stale `file:` installs**: package managers may keep old extracted contents for local tarball dependencies after reruns. Use `install --force` if a consumer still sees old package contents.
+- **Peer dependency mismatches**: if the publisher bumps a peer dep, consumers that don't satisfy it may fail to install. Surface this to the user.
+- **Lockfile churn**: installing after a `file:` swap will change the lockfile. That's expected and should be committed alongside the `package.json` and tarball changes.
+- **Multiple publishers in one repo**: pass one `--pair` per publisher package, using the same consumer path. They'll all be bundled into the same `.polygraph-packages/` dir.
+
+## Related Skills
+
+- `polygraph` — session setup, branch push, PR creation.
+- `await-polygraph-ci` — monitor consumer CI after the PRs are opened.