@unbrained/pm-cli 2026.8.4 → 2026.8.5

package/dist/sdk/workspace-snapshot.js

@@ -5,7 +5,7 @@
  * state while excluding clone-local caches, locks, and recovery journals.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="343fc918-e300-504c-80be-779c0d01b93e")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="3e32be7c-f8a4-547d-8c19-456b4567982e")}catch(e){}}();
 import crypto from "node:crypto";
 import { cp, lstat, mkdir, readFile, readdir, rename, rm, writeFile, } from "node:fs/promises";
 import path from "node:path";
@@ -13,6 +13,8 @@ import { writeFileAtomic } from "../core/fs/fs-utils.js";
 import { appendWorkspaceAuditEvent } from "../core/history/workspace-history.js";
 import { acquireLock } from "../core/lock/lock.js";
 import { getLockPath } from "../core/store/paths.js";
+import { EXIT_CODE } from "../core/shared/constants.js";
+import { PmCliError } from "../core/shared/errors.js";
 /** Current content-addressed workspace snapshot manifest schema identifier. */
 export const SNAPSHOT_SCHEMA = "https://schema.unbrained.dev/pm/workspace-snapshot/v1";
 const SNAPSHOT_RUNTIME_PATH = path.join("runtime", "workspace-snapshots");
@@ -168,7 +170,21 @@ async function snapshotContents(root, files) {
 }
 function validateSnapshotTarget(target) {
     if (!SNAPSHOT_TARGET_PATTERN.test(target)) {
-        throw new Error("Snapshot names and fingerprints must use lowercase letters, digits, dots, underscores, or hyphens");
+        throw new PmCliError("Snapshot names and fingerprints must use lowercase letters, digits, dots, underscores, or hyphens", EXIT_CODE.USAGE, {
+            code: "invalid_workspace_snapshot_target",
+            required: "Provide a non-empty lowercase snapshot name or 64-character hexadecimal fingerprint.",
+            why: "Snapshot targets are used as portable reference filenames and content identities.",
+            examples: [
+                "pm workspace snapshot list --json",
+                "pm workspace snapshot inspect baseline --json",
+            ],
+            nextSteps: [
+                "List available snapshots, then retry with a returned name or fingerprint.",
+            ],
+            recovery: {
+                suggested_retry: "pm workspace snapshot list --json",
+            },
+        });
     }
 }
 function isErrno(error, code) {
@@ -180,15 +196,23 @@ function isErrno(error, code) {
 function snapshotStore(pmRoot) {
     return path.join(pmRoot, SNAPSHOT_RUNTIME_PATH);
 }
+function workspaceSnapshotNotFound(target) {
+    return new PmCliError(`Unknown workspace snapshot: ${target}`, EXIT_CODE.NOT_FOUND, {
+        code: "workspace_snapshot_not_found",
+        required: "Use a snapshot name or fingerprint returned by snapshot list.",
+        why: "The requested reference or immutable snapshot object does not exist.",
+        examples: ["pm workspace snapshot list --json"],
+        nextSteps: ["List available snapshots and retry with an exact target."],
+        recovery: { suggested_retry: "pm workspace snapshot list --json" },
+    });
+}
 async function readSnapshotJson(file, target) {
     try {
         return JSON.parse(await readFile(file, "utf8"));
     }
     catch (error) {
         if (isErrno(error, "ENOENT")) {
-            throw new Error(`Unknown workspace snapshot: ${target}`, {
-                cause: error,
-            });
+            throw workspaceSnapshotNotFound(target);
         }
         throw error;
     }
@@ -199,9 +223,7 @@ async function removeSnapshotEntry(entry, target, recursive) {
     }
     catch (error) {
         if (isErrno(error, "ENOENT")) {
-            throw new Error(`Unknown workspace snapshot: ${target}`, {
-                cause: error,
-            });
+            throw workspaceSnapshotNotFound(target);
         }
         throw error;
     }
@@ -256,7 +278,13 @@ export async function createWorkspaceSnapshot(pmRoot, options = {}) {
     if (options.name !== undefined) {
         validateSnapshotTarget(options.name);
         if (/^[a-f0-9]{64}$/.test(options.name)) {
-            throw new Error("Snapshot names must not be 64-character lowercase hexadecimal fingerprints");
+            throw new PmCliError("Snapshot names must not be 64-character lowercase hexadecimal fingerprints", EXIT_CODE.USAGE, {
+                code: "workspace_snapshot_name_reserved_fingerprint",
+                required: "Choose a human-readable reference name that cannot be mistaken for a content fingerprint.",
+                why: "Exact 64-character hexadecimal values address immutable objects.",
+                examples: ["pm workspace snapshot create baseline --json"],
+                nextSteps: ["Retry with a shorter descriptive snapshot name."],
+            });
         }
     }
     const { manifest, contents } = await buildManifest(pmRoot);
@@ -307,7 +335,13 @@ export async function inspectWorkspaceSnapshot(pmRoot, target) {
     const manifest = await readSnapshotJson(path.join(snapshotStore(pmRoot), "objects", fingerprint, "manifest.json"), target);
     if (manifest.schema !== SNAPSHOT_SCHEMA ||
         manifest.fingerprint !== fingerprint) {
-        throw new Error(`Snapshot manifest identity mismatch: ${target}`);
+        throw new PmCliError(`Snapshot manifest identity mismatch: ${target}`, EXIT_CODE.CONFLICT, {
+            code: "workspace_snapshot_manifest_mismatch",
+            required: "Use an intact snapshot whose manifest fingerprint matches its object path.",
+            why: "Content identity must be verified before snapshot data is trusted.",
+            examples: ["pm workspace snapshot list --json"],
+            nextSteps: ["Inspect or recreate the snapshot before restoring it."],
+        });
     }
     return manifest;
 }
@@ -399,7 +433,19 @@ export async function planWorkspaceSnapshotRestore(pmRoot, target) {
  */
 export async function restoreWorkspaceSnapshotWithRecovery(pmRoot, target, options = {}) {
     if (options.force !== true) {
-        throw new Error("Workspace snapshot restore requires explicit force confirmation; inspect the impact with planWorkspaceSnapshotRestore or pm workspace snapshot restore <target> --dry-run, then retry with force");
+        throw new PmCliError("Workspace snapshot restore requires explicit force confirmation; inspect the impact with planWorkspaceSnapshotRestore or pm workspace snapshot restore <target> --dry-run, then retry with force", EXIT_CODE.USAGE, {
+            code: "workspace_snapshot_force_required",
+            required: "Preview the destructive impact, then explicitly confirm the restore.",
+            why: "A restore replaces the complete authoritative tracker state.",
+            examples: [
+                `pm workspace snapshot restore ${target} --dry-run --json`,
+                `pm workspace snapshot restore ${target} --force --json`,
+            ],
+            nextSteps: ["Review the dry-run counts before retrying with --force."],
+            recovery: {
+                suggested_retry: `pm workspace snapshot restore ${target} --dry-run --json`,
+            },
+        });
     }
     const author = options.author?.trim() || "pm-sdk";
     const lockTtlSeconds = options.lockTtlSeconds ?? 60;
@@ -518,4 +564,4 @@ export async function deleteWorkspaceSnapshot(pmRoot, target) {
     return { deleted: "object", target };
 }
 //# sourceMappingURL=workspace-snapshot.js.map
-//# debugId=343fc918-e300-504c-80be-779c0d01b93e
+//# debugId=3e32be7c-f8a4-547d-8c19-456b4567982e

package/dist/sdk/workspace.js

@@ -4,9 +4,11 @@
  * Maintains repository-scaffold contracts shared by the public SDK and CLI.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="786d5cc6-521d-521e-9e91-95d82551c279")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="bbfa5b19-d801-582a-98e8-0c4925dd57c0")}catch(e){}}();
 import { readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { EXIT_CODE } from "../core/shared/constants.js";
+import { PmCliError } from "../core/shared/errors.js";
 /** Opening marker for the init-owned ignore block. */
 export const PM_GITIGNORE_START = "# pm-cli:runtime-cache:start";
 /** Closing marker for the init-owned ignore block. */
@@ -31,6 +33,30 @@ export const PM_GITIGNORE_RUNTIME_DIRECTORIES = [
 ];
 /** Tracker-relative curated search evidence that remains version controlled. */
 export const PM_GITIGNORE_TRACKED_FILES = ["search/eval-queries.json"];
+/** Convert expected workspace permission failures into stable, path-safe recovery. */
+async function withGitignorePermissionRecovery(operation) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            "code" in error &&
+            typeof error.code === "string" &&
+            ["EACCES", "EPERM", "EROFS"].includes(error.code)) {
+            throw new PmCliError("The workspace .gitignore is not writable.", EXIT_CODE.GENERIC_FAILURE, {
+                code: "init_gitignore_unwritable",
+                reason: error.code.toLowerCase(),
+                required: "Grant the current user read and write access to the workspace .gitignore before initialization.",
+                why: "pm init must publish its managed runtime-cache ignore fence without replacing unrelated entries.",
+                nextSteps: [
+                    "Grant read and write access to the workspace .gitignore and rerun pm init.",
+                    "If the workspace is intentionally read-only, initialize pm in a writable workspace or clone.",
+                ],
+            });
+        }
+        throw error;
+    }
+}
 function normalizeTrackerRelativeRoot(trackerRelativeRoot) {
     return trackerRelativeRoot
         .replaceAll("\\", "/")
@@ -78,7 +104,7 @@ export async function ensurePmGitignore(workspaceRoot, options = {}) {
     }
     let current = "";
     try {
-        current = await readFile(gitignorePath, "utf8");
+        current = await withGitignorePermissionRecovery(() => readFile(gitignorePath, "utf8"));
     }
     catch (error) {
         if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) {
@@ -95,8 +121,8 @@ export async function ensurePmGitignore(workspaceRoot, options = {}) {
     if (next === current) {
         return { path: gitignorePath, changed: false };
     }
-    await writeFile(gitignorePath, next, "utf8");
+    await withGitignorePermissionRecovery(() => writeFile(gitignorePath, next, "utf8"));
     return { path: gitignorePath, changed: true };
 }
 //# sourceMappingURL=workspace.js.map
-//# debugId=786d5cc6-521d-521e-9e91-95d82551c279
+//# debugId=bbfa5b19-d801-582a-98e8-0c4925dd57c0

package/docs/COMMANDS.md

@@ -27,7 +27,7 @@ Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
 | ------------ | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | Bootstrap    | `init`, `config`, `health`, `telemetry`                                                                                        | create and inspect tracker setup                                                                                                                                                                                                                       |
 | Lifecycle    | `create`, `copy`, `focus`, `claim`, `update`, `append`, `close`, `release`, `delete`, `start-task`, `pause-task`, `close-task` | mutate item state                                                                                                                                                                                                                                      |
-| Bulk         | `item mutate`, `update-many`, `close-many`                                                                                     | atomically commit heterogeneous SDK mutation batches, or apply one change across a matched, dry-run-previewed set with a rollback checkpoint                                                                                                           |
+| Bulk         | `item mutate`, `item complete`, `update-many`, `close-many`                                                                    | atomically commit heterogeneous SDK mutation batches or evidence-backed completion, or apply one change across a matched, dry-run-previewed set with a rollback checkpoint                                                                             |
 | Scheduling   | `meet`, `event`, `remind`                                                                                                      | low-friction Meeting/Event/Reminder creation                                                                                                                                                                                                           |
 | Planning     | `plan create`, `plan add-step`, `plan update-step`, `plan complete-step`, `plan link`, `plan approve`, `plan materialize`      | agent-optimized living plans with ordered steps, evidence, decisions, validation, and materialization                                                                                                                                                  |
 | Links        | `files`, `docs`, `test`, `deps`                                                                                                | connect items to artifacts, tests, and relationships                                                                                                                                                                                                   |
@@ -516,20 +516,30 @@ row summaries. See tracker item [pm-awe3t6](../.agents/pm/issues/pm-awe3t6.toon)
 
 ### Atomic heterogeneous mutation batches
 
-`pm item mutate` is the noun-first CLI adapter over the public SDK
-`commitItemMutations` primitive. Pipe a non-empty JSON array (or an object with a
-`mutations` array), provide one stable transaction id, and mix create/update/
-close operations in order:
+Tracked by [pm-o8z748](../.agents/pm/issues/pm-o8z748.toon) and
+[pm-cyn0y6](../.agents/pm/issues/pm-cyn0y6.toon).
+
+`pm item mutate` is the noun-first CLI adapter over the public SDK resolver and
+`commitItemMutations` primitive. Pipe either the legacy non-empty JSON array or
+a versioned `{ "schema_version": 1, "mutations": [...] }` document, provide one
+stable transaction id, and mix create/update/close/release operations in order.
+Create rows may declare a unique `ref` and omit `id`; exact `@ref` values work
+in target ids, `parent`, `blockedBy`, and dependency `id` fields. The resolver
+derives replay-stable ids before the writer lock and returns a `references`
+receipt:
 
 ```bash
 pm item mutate \
   --transaction-id sync-2026-07-20-001 \
   --stdin-json <<'JSON'
-[
-  {"op":"create","id":"ext-1042","options":{"title":"Imported issue","type":"Issue"}},
-  {"op":"update","id":"pm-a1b2","options":{"priority":"1","addTags":["synced"]}},
-  {"op":"close","id":"pm-c3d4","reason":"Resolved upstream"}
-]
+{
+  "schema_version": 1,
+  "mutations": [
+    {"op":"create","ref":"initiative","options":{"title":"Imported initiative","type":"Epic"}},
+    {"op":"create","ref":"delivery","options":{"title":"Deliver it","type":"Feature","parent":"@initiative","dep":["id=@initiative,kind=implements"]}},
+    {"op":"update","id":"@initiative","options":{"addTags":["synced"]}}
+  ]
+}
 JSON
 ```
 
@@ -540,6 +550,26 @@ step. `--create-compensation close|delete`, `--lock-ttl-seconds`, and
 `--lock-wait-ms` expose the transaction safety controls. The equivalent MCP
 surface is `pm_mutate`.
 
+`pm item complete` composes evidence, governed closure, and claim release into
+one compensating SDK transaction. It accepts the normal repeatable evidence
+flags and can preview the exact ordered mutations before writing:
+
+```bash
+pm item complete pm-a1b2 "Implemented and verified" \
+  --transaction-id complete-pm-a1b2-v1 \
+  --file path=src/index.ts,scope=project,note=implementation \
+  --doc path=docs/SDK.md,scope=project,note=contract \
+  --test command="pnpm test",scope=project,timeout_seconds=240 \
+  --comment "Evidence: full verification passed" \
+  --validate-close warn
+```
+
+If any phase fails, the SDK restores the evidence, lifecycle, and prior claim.
+Reusing the exact transaction id and payload returns the committed result;
+changing a replayed payload fails against the journal plan fingerprint.
+`--lock-ttl-seconds` and `--lock-wait-ms` tune the same workspace transaction
+controls exposed by `pm item mutate` for slow or contended trackers.
+
 ## Focus (session default parent)
 
 `pm focus` sets a session "focused" item so subsequent `pm create` calls default their `--parent` to it — project management is context management, and focus keeps new work attached to the active parent without restating `--parent` every time.

package/docs/EXTENSIONS.md

@@ -270,7 +270,7 @@ Surface tokens include command handlers/overrides, parser/preflight/services/ren
 
 ## Registration Collisions
 
-Some extension surfaces are intentionally single-winner: command handlers and overrides, parser overrides, preflight overrides, and format renderers. If multiple packages register the same single-winner surface, the later-loaded registration wins and `pm package doctor` / `pm health` report deterministic `extension_*_collision` warnings. `pm package describe --json` also exposes `command_ownership`: every claimant in activation order, the effective winner, collision state, and the explicit `last_activated_wins` policy. SDK hosts can build the identical table with `buildExtensionDescribeResult` and the exported `ExtensionCommandOwnership` contracts.
+Some extension surfaces are intentionally single-winner: command handlers and overrides, parser overrides, preflight overrides, and format renderers. Activation is deterministic: lower manifest `priority` values load first, omitted priority defaults to `100`, equal priorities sort by package identity/path, and the last registration wins. If multiple packages register the same single-winner surface, `pm package doctor` / `pm health` report deterministic `extension_*_collision` warnings whose suffix names the winning layer/package before the displaced layer/package. `pm package describe --json` also exposes `command_ownership`: every claimant in activation order, the effective winner, collision state, and the explicit `last_activated_wins` policy. SDK hosts can build the identical table with `buildExtensionDescribeResult` and the exported `ExtensionCommandOwnership` contracts. Renderer ownership is evaluated per command: same-format renderers with disjoint `commands` lists safely coexist, while an unscoped or overlapping claim still warns; runtime `resultDiscriminator` predicates alone cannot prove static disjointness. Tracked by [pm-6mjxgq](../.agents/pm/issues/pm-6mjxgq.toon).
 
 For definition-based commands, validation is isolated per command: a malformed definition is recorded as `extension_command_quarantined:*` with a registration trace while valid siblings continue to activate. Unknown-command recovery reports that failure without recommending reinstallation.
 Use the warning details to resolve the overlap:

package/docs/MERGE_SAFETY.md

@@ -63,6 +63,8 @@ pm merge install --dry-run --json
 
 When both sides change the same scalar or JSON leaf differently, the driver writes a parseable preferred-side result but exits nonzero. Git keeps the path conflicted so a human or coordinating agent must review the losing value and explicitly `git add` the resolution. Use `--prefer theirs` only when that is the intended resolution policy.
 
+The driver result's `guidance` always points unresolved conflicts to `pm merge report`. When a clone-local receipt exists, guidance includes its privacy-safe receipt and item ids for exact correlation; discarded values remain confined to the local receipt and never appear in generic logs or tracker history. Tracked by [pm-fbrz7p](../.agents/pm/issues/pm-fbrz7p.toon).
+
 For item conflicts, the driver also writes a clone-local receipt below the Git
 directory. It contains retained and discarded values so recovery does not
 depend on a reflog. Raw values never enter public tracker history:

package/docs/PR_REVIEW_LOOP.md

@@ -1,6 +1,6 @@
 # Pull Request Review Loop
 
-Tracker: [pm-hq28](../.agents/pm/tasks/pm-hq28.toon)
+Trackers: [pm-hq28](../.agents/pm/tasks/pm-hq28.toon), [pm-cp5pbo](../.agents/pm/tasks/pm-cp5pbo.toon)
 
 Use `scripts/reviews/pr-review-loop.mjs` to inventory every GitHub pull-request
 conversation surface before deciding that review is complete. The inventory includes
@@ -11,6 +11,7 @@ reaction state, thread resolution, outdated markers, and the reviewed head SHA.
 node scripts/reviews/pr-review-loop.mjs inventory --pr 123 > /tmp/pr-123-review-inventory.json
 node scripts/reviews/pr-review-loop.mjs watch --pr 123 --interval 30 > /tmp/pr-123-review-inventory.json
 node scripts/reviews/pr-review-loop.mjs react --node-id IC_kw... --reaction THUMBS_UP
+node scripts/reviews/pr-review-loop.mjs acknowledge --pr 123 --node-id PRR_kw... --reaction THUMBS_UP --body "CodeRabbit feedback implemented: https://github.com/owner/repo/pull/123#pullrequestreview-456. The suggested edge case is covered by test X."
 node scripts/reviews/pr-review-loop.mjs reply-inline --pr 123 --comment-id 456 --body "Addressed in abc123."
 node scripts/reviews/pr-review-loop.mjs acknowledge-inline --pr 123 --comment-id 456 --node-id PRRC_kw... --reaction THUMBS_UP --body "Addressed in abc123."
 ```
@@ -18,9 +19,14 @@ node scripts/reviews/pr-review-loop.mjs acknowledge-inline --pr 123 --comment-id
 Choose `THUMBS_UP` when feedback is useful or correct and `THUMBS_DOWN` when a
 finding is materially incorrect. Use `acknowledge-inline` so the reaction and
 explanation land on the actual review comment and its thread. GitHub does not expose
-a reply thread for top-level PR conversation comments or submitted review summaries;
-react to those surfaces, but do not create a generic PR comment that pretends to be
-a direct reply. The complete inventory keeps those non-threadable surfaces visible.
+a reply thread for top-level PR conversation comments or submitted review summaries.
+Use `acknowledge` for those surfaces: its PR comment must identify the bot, link the
+exact GitHub artifact, and explain whether the feedback was implemented or declined.
+That keeps the response auditable without pretending GitHub created a direct thread.
+The command adds a hidden artifact marker and reuses an existing marked comment on
+retry, so a lost response cannot create duplicate acknowledgements. It reports a
+partial result and exits unsuccessfully when either the comment or reaction write
+fails, allowing the missing write to be retried safely.
 
 After every push or reviewer retrigger, run `watch`. It delegates waiting to
 `gh pr checks --watch`, because reviewer agents report completion through GitHub

package/docs/README.md

@@ -17,17 +17,17 @@ pm guide release --json
 
 ## Read Path
 
-| Reader | First page | Then read |
-|--------|------------|-----------|
-| New user | [Quickstart](QUICKSTART.md) | [Command Reference](COMMANDS.md) |
-| New maintainer | [Onboarding](ONBOARDING.md) | [Agent Guide](AGENT_GUIDE.md), [Testing](TESTING.md), [Releasing](RELEASING.md) |
-| Coding agent | [Agent Guide](AGENT_GUIDE.md) | [Configuration](CONFIGURATION.md), then command help |
-| Maintainer | [Contributing](../CONTRIBUTING.md) | [Testing](TESTING.md), [Releasing](RELEASING.md), [Architecture](ARCHITECTURE.md) |
-| Package author | [Packages and Extensions](EXTENSIONS.md) | [SDK](SDK.md), [starter extension](examples/starter-extension/README.md) |
-| Codex or ChatGPT plugin implementer | [Codex Plugin](CODEX_PLUGIN.md) | [Native ChatGPT and Codex Plugin Implementation Plan](CHATGPT_CODEX_PLUGIN_IMPLEMENTATION.md) |
-| Codex user | [Codex Plugin](CODEX_PLUGIN.md) | [Agent Guide](AGENT_GUIDE.md), then [Command Reference](COMMANDS.md) |
-| Claude Code user | [Claude Code Plugin](CLAUDE_CODE_PLUGIN.md) | [Agent Guide](AGENT_GUIDE.md), then [Command Reference](COMMANDS.md) |
-| Machine client | `pm contracts --json` | [CLI Scripting Contract](SCRIPTING.md), [Command Reference](COMMANDS.md#machine-contracts), optionally `pm install guide-shell --project && pm guide commands` |
+| Reader                              | First page                                  | Then read                                                                                                                                                      |
+| ----------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| New user                            | [Quickstart](QUICKSTART.md)                 | [Command Reference](COMMANDS.md)                                                                                                                               |
+| New maintainer                      | [Onboarding](ONBOARDING.md)                 | [Agent Guide](AGENT_GUIDE.md), [Testing](TESTING.md), [Releasing](RELEASING.md)                                                                                |
+| Coding agent                        | [Agent Guide](AGENT_GUIDE.md)               | [Configuration](CONFIGURATION.md), then command help                                                                                                           |
+| Maintainer                          | [Contributing](../CONTRIBUTING.md)          | [Testing](TESTING.md), [Releasing](RELEASING.md), [Architecture](ARCHITECTURE.md)                                                                              |
+| Package author                      | [Packages and Extensions](EXTENSIONS.md)    | [SDK](SDK.md), [starter extension](examples/starter-extension/README.md)                                                                                       |
+| Codex or ChatGPT plugin implementer | [Codex Plugin](CODEX_PLUGIN.md)             | [Native ChatGPT and Codex Plugin Implementation Plan](CHATGPT_CODEX_PLUGIN_IMPLEMENTATION.md)                                                                  |
+| Codex user                          | [Codex Plugin](CODEX_PLUGIN.md)             | [Agent Guide](AGENT_GUIDE.md), then [Command Reference](COMMANDS.md)                                                                                           |
+| Claude Code user                    | [Claude Code Plugin](CLAUDE_CODE_PLUGIN.md) | [Agent Guide](AGENT_GUIDE.md), then [Command Reference](COMMANDS.md)                                                                                           |
+| Machine client                      | `pm contracts --json`                       | [CLI Scripting Contract](SCRIPTING.md), [Command Reference](COMMANDS.md#machine-contracts), optionally `pm install guide-shell --project && pm guide commands` |
 
 ## Documentation Map
 
@@ -35,7 +35,7 @@ pm guide release --json
 - [Onboarding](ONBOARDING.md) - first-two-hours maintainer and contributor setup.
 - [Agent Guide](AGENT_GUIDE.md) - canonical agent loop, tracker linking, and token-minimal command choices.
 - [Command Reference](COMMANDS.md) - command families with examples and when to use each family.
-- [CLI Scripting Contract](SCRIPTING.md) - exit codes, stdout/stderr boundaries, stable JSON fields, uniform OR filters, and shell composition recipes.
+- [CLI Scripting Contract](SCRIPTING.md) - exit codes, flat mutation receipts versus read envelopes, stdout/stderr boundaries, stable JSON fields, uniform OR filters, and shell composition recipes.
 - [Configuration](CONFIGURATION.md) - settings, storage formats, output, search, validation, and environment variables.
 - [Testing](TESTING.md) - sandbox-safe local tests and linked-test orchestration.
 - [Security Governance](SECURITY_GOVERNANCE.md) - vulnerability reporting, review discipline, property fuzzing, and OpenSSF limitations.
@@ -72,16 +72,16 @@ pm guide release --json
 
 ## Guide Topic Map
 
-| Optional `pm guide` topic | Primary docs |
-|-----------------------------|--------------|
-| `quickstart` | [Quickstart](QUICKSTART.md), [Command Reference](COMMANDS.md) |
-| `commands` | [Command Reference](COMMANDS.md), [Configuration](CONFIGURATION.md) |
-| `workflows` | [Agent Guide](AGENT_GUIDE.md), [Testing](TESTING.md) |
-| `sdk` | [SDK](SDK.md), [Architecture](ARCHITECTURE.md) |
-| `extensions`, `packages` | [Packages and Extensions](EXTENSIONS.md), [starter extension](examples/starter-extension/README.md) |
-| `skills` | [Agent Guide](AGENT_GUIDE.md) plus `.agents/skills/*` |
-| `harnesses` | [Agent Guide](AGENT_GUIDE.md) plus `.agents/skills/HARNESS_COMPATIBILITY.md` |
-| `release` | [Releasing](RELEASING.md), [CHANGELOG](../CHANGELOG.md) |
+| Optional `pm guide` topic | Primary docs                                                                                        |
+| ------------------------- | --------------------------------------------------------------------------------------------------- |
+| `quickstart`              | [Quickstart](QUICKSTART.md), [Command Reference](COMMANDS.md)                                       |
+| `commands`                | [Command Reference](COMMANDS.md), [Configuration](CONFIGURATION.md)                                 |
+| `workflows`               | [Agent Guide](AGENT_GUIDE.md), [Testing](TESTING.md)                                                |
+| `sdk`                     | [SDK](SDK.md), [Architecture](ARCHITECTURE.md)                                                      |
+| `extensions`, `packages`  | [Packages and Extensions](EXTENSIONS.md), [starter extension](examples/starter-extension/README.md) |
+| `skills`                  | [Agent Guide](AGENT_GUIDE.md) plus `.agents/skills/*`                                               |
+| `harnesses`               | [Agent Guide](AGENT_GUIDE.md) plus `.agents/skills/HARNESS_COMPATIBILITY.md`                        |
+| `release`                 | [Releasing](RELEASING.md), [CHANGELOG](../CHANGELOG.md)                                             |
 
 Community files:
 

package/docs/RELEASING.md

@@ -66,7 +66,7 @@ pnpm version:check
 Policy:
 
 - release only when commits exist after the latest release tag
-- ignore `.agents/pm`-only tracker commits for publish eligibility so post-release evidence and closure updates do not create a package release by themselves
+- ignore tracker-governance-only commits for publish eligibility: `.agents/pm/**` and the mechanically generated `CHANGELOG.md` projection do not create a package release by themselves, while any product, test, documentation, workflow, or other changed path remains release-relevant
 - create at most one production tag and npm version per UTC day; if no tag was
   created, a non-`github-actions[bot]` closure of the exact bot-created
   `Auto Release blocked` issue on the same UTC day triggers one preparation
@@ -103,7 +103,7 @@ The pipeline performs:
 2. a single `YYYY.M.D` version bump; ordinal targets and the removed
    `--allow-same-day-release` override fail closed
 3. latest `pm-changelog` install and main changelog refresh through package-owned full-history generation; the release pipeline passes `--release-version` with `--all-release-tags` so the pending release section matches post-tag CI checks
-4. strict gates (build, typecheck, docs/skills freshness, coverage, static quality, compatibility, security, smoke checks, reliability gate)
+4. build, clone-local merge-driver installation, then the remaining strict gates (typecheck, docs/skills freshness, coverage, static quality, compatibility, security, smoke checks, reliability gate); this ordering makes the checkout-owned CLI available before bootstrap, matches CI, and prevents fresh-clone tracker measurements from observing undeclared merge-driver repairs
 5. release note generation from changelog + pm evidence
 6. commit and tag creation (plus optional push)
 
@@ -337,7 +337,7 @@ Use the npm registry package for maintainer global updates. Do not use `npm inst
 
 When auto-release exits green but does not cut a version, inspect the pipeline's JSON skip `reason` from `scripts/release/run-release-pipeline.mjs` (or rerun locally with `pnpm release:pipeline:dry-run -- --json`):
 
-- tracker-only skip family: `tracker_only_changes_since_last_tag` (all changed paths are `.agents/pm` only)
+- tracker-only skip family: `tracker_only_changes_since_last_tag` (all changed paths are `.agents/pm/**` and/or the generated `CHANGELOG.md` projection; a product-visible path is the required negative control)
 - changelog-empty skip family: `empty_generated_changelog_section_for_target_version` (generated release section exists but has no non-empty entries)
 
 `pm-changelog` is maintained in a separate repository/package. Classifier or release-window bugs must be fixed and released there first, then consumed here via the latest npm package (`pm install npm:pm-changelog --project`) before rerunning release generation.

package/docs/SCRIPTING.md

@@ -1,19 +1,19 @@
 # CLI Scripting Contract
 
-Tracked by [pm-psy1](../.agents/pm/tasks/pm-psy1.toon), [pm-gknu](../.agents/pm/issues/pm-gknu.toon), and [pm-999jh7](../.agents/pm/issues/pm-999jh7.toon).
+Tracked by [pm-psy1](../.agents/pm/tasks/pm-psy1.toon), [pm-gknu](../.agents/pm/issues/pm-gknu.toon), [pm-999jh7](../.agents/pm/issues/pm-999jh7.toon), and [pm-srns](../.agents/pm/issues/pm-srns.toon).
 
 Use this contract when composing `pm` with shells, CI runners, `jq`, or another process. Exact flags remain discoverable from `pm <command> --help --json` and `pm contracts --command <command> --flags-only --json`.
 
 ## Process Contract
 
-| Exit | Meaning | Script response |
-|------|---------|-----------------|
-| `0` | The requested operation completed. A successful read may still return zero rows. | Parse stdout. |
-| `1` | Runtime or unexpected failure. | Preserve stderr and stop. |
-| `2` | Invalid flags, values, or command composition. | Correct the invocation; do not retry unchanged. |
-| `3` | Requested tracker or resource was not found. | Correct the path or ID. |
-| `4` | State or concurrency conflict. | Refresh live state before deciding whether to retry. |
-| `5` | A required dependency operation failed. | Inspect the dependency evidence before retrying. |
+| Exit | Meaning                                                                          | Script response                                      |
+| ---- | -------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| `0`  | The requested operation completed. A successful read may still return zero rows. | Parse stdout.                                        |
+| `1`  | Runtime or unexpected failure.                                                   | Preserve stderr and stop.                            |
+| `2`  | Invalid flags, values, or command composition.                                   | Correct the invocation; do not retry unchanged.      |
+| `3`  | Requested tracker or resource was not found.                                     | Correct the path or ID.                              |
+| `4`  | State or concurrency conflict.                                                   | Refresh live state before deciding whether to retry. |
+| `5`  | A required dependency operation failed.                                          | Inspect the dependency evidence before retrying.     |
 
 Successful structured results are written to stdout. Diagnostics, warnings, profiles, and errors are written to stderr so `--json`, `--format ndjson`, CSV, and table stdout remain pipe-safe. Never merge stderr into stdout before parsing structured output.
 
@@ -29,6 +29,29 @@ fi
 
 ## Stable Structured Fields
 
+Mutation and read envelopes are intentionally different. Single-item mutation
+commands emit a flat receipt whose `id`, `status`, and `changed_field_count`
+are top-level fields. Reads wrap their primary entity or rows under documented
+keys such as `item` or `items`. Bulk mutations such as `close-many` and
+`update-many` use collection envelopes under `rows`; consult
+`command_output_contracts` for the exact command path. Never infer one shape
+from another.
+
+TypeScript package consumers should parse mutation stdout with the SDK boundary
+helper so a wrapped or malformed result fails loudly:
+
+```ts
+import { parseMutationReceipt } from "@unbrained/pm-cli/sdk/contracts";
+
+const { id, status, changedFieldCount } = parseMutationReceipt(stdout);
+```
+
+`pm contracts --summary --json` keeps bootstrap discovery compact while
+declaring every command's default token ceiling. Use `pm contracts --full
+--json` for `command_output_contracts`, which pairs the envelope declaration
+with TOON- and JSON-specific token ceilings for every active core or package
+command.
+
 JSON object field order is not an API. Consume fields by name. Read envelopes keep the stable pagination vocabulary `items`, `count`, `total`, `has_more`, and, when another page exists, `next_cursor`. The `filters` object echoes the effective query scope. Plain `pm list` and `pm search` are all-status reads and disclose `filters.status: "all"`; lifecycle-specific commands such as `pm list-open` remain explicit shortcuts.
 
 Projection flags intentionally change row shape. Use `--fields` when a script requires an exact subset, `--brief` or `--compact` only when the documented sparse shape is sufficient, and `--full` when linked metadata is required. Check `row_contract` on generic read surfaces that expose one; do not infer omitted fields as empty values.