@unbrained/pm-cli 2026.8.4 → 2026.8.6

package/dist/sdk/structured-mutations.js

@@ -5,13 +5,26 @@
  * transaction contract and normalizes full item documents for CLI round trips.
  */
 
-!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]="6471aca6-b7e1-51c0-b905-5617dfb7ef2a")}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]="91be2c5d-c495-54bc-ac79-b4c645ad2c6e")}catch(e){}}();
+import crypto from "node:crypto";
+import { normalizeItemId, normalizePrefix } from "../core/item/id.js";
 import { EXIT_CODE, ITEM_PROJECT_CONTEXT_KEYS, } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { levenshteinDistanceWithinLimit } from "../core/shared/levenshtein.js";
-import { CLOSE_FLAG_CONTRACTS } from "./cli-contracts/flag-contracts.js";
+import { CLOSE_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, } from "./cli-contracts/flag-contracts.js";
 import { CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, } from "./cli-contracts/commander-mutation-options.js";
 const MUTATION_ROW_KEYS = ["op", "id", "reason", "options"];
+const REFERENCED_MUTATION_ROW_KEYS = [
+    ...MUTATION_ROW_KEYS,
+    "ref",
+];
+const MUTATION_DOCUMENT_KEYS = ["schema_version", "mutations"];
+const MUTATION_REFERENCE_SOURCE = "[a-z][a-z0-9._-]{0,63}";
+const MUTATION_REFERENCE_PATTERN = new RegExp(`^${MUTATION_REFERENCE_SOURCE}$`, "u");
+const MUTATION_DEPENDENCY_REFERENCE_PATTERN = new RegExp(`(^|,)id=@(${MUTATION_REFERENCE_SOURCE})(?=,|$)`, "gu");
+const flagToOptionKey = (flag) => flag
+    .slice(2)
+    .replaceAll(/-([a-z])/gu, (_match, letter) => letter.toUpperCase());
 const ITEM_ENVELOPE_KEYS = [
     "item",
     "linked",
@@ -26,13 +39,16 @@ const READ_ONLY_ITEM_KEYS = new Set([
     "created_at",
     "updated_at",
     "closed_at",
-    "completed_at",
     "version",
     "format_version",
     "path",
     "author",
 ]);
-const UPDATE_READ_ONLY_ITEM_KEYS = new Set([...READ_ONLY_ITEM_KEYS, "id"]);
+const UPDATE_READ_ONLY_ITEM_KEYS = new Set([
+    ...READ_ONLY_ITEM_KEYS,
+    "completed_at",
+    "id",
+]);
 const ITEM_FIELD_KEYS = new Set([
     "id",
     "title",
@@ -56,6 +72,7 @@ const ITEM_FIELD_KEYS = new Set([
     "regression",
     "customer_impact",
     "close_reason",
+    "completed_at",
     "dependencies",
     "comments",
     "notes",
@@ -70,9 +87,8 @@ const ITEM_FIELD_KEYS = new Set([
 const MUTATION_OPTION_KEYS = {
     create: CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS.map((contract) => contract.target),
     update: UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS.map((contract) => contract.target),
-    close: CLOSE_FLAG_CONTRACTS.map((contract) => contract.flag
-        .slice(2)
-        .replaceAll(/-([a-z])/gu, (_match, letter) => letter.toUpperCase())).filter((key) => key !== "reason"),
+    close: CLOSE_FLAG_CONTRACTS.map((contract) => flagToOptionKey(contract.flag)).filter((key) => key !== "reason"),
+    release: RELEASE_FLAG_CONTRACTS.map((contract) => flagToOptionKey(contract.flag)),
 };
 /** Validate and normalize atomic transaction controls at every transport boundary. */
 export function parseAtomicMutationControls(value) {
@@ -172,8 +188,11 @@ function validateMutationOptions(options, op, index) {
 function validateMutationRow(value, index) {
     const mutation = validateMutationObject(value, index);
     const { op, id, reason } = mutation;
-    if (op !== "create" && op !== "update" && op !== "close") {
-        throw new PmCliError(`Mutation ${index + 1} op must be create, update, or close.`, EXIT_CODE.USAGE);
+    if (op !== "create" &&
+        op !== "update" &&
+        op !== "close" &&
+        op !== "release") {
+        throw new PmCliError(`Mutation ${index + 1} op must be create, update, close, or release.`, EXIT_CODE.USAGE);
     }
     const options = validateMutationOptions(mutation.options, op, index);
     if (typeof id !== "string" || id.trim().length === 0) {
@@ -193,6 +212,15 @@ function validateMutationRow(value, index) {
                 : { options: options }),
         };
     }
+    if (op === "release") {
+        return {
+            op,
+            id: normalizedId,
+            ...(options === undefined
+                ? {}
+                : { options: options }),
+        };
+    }
     if (!isPlainObject(options)) {
         throw new PmCliError(`Mutation ${index + 1} ${op} requires an options object.`, EXIT_CODE.USAGE);
     }
@@ -215,6 +243,187 @@ export function parseItemMutationBatch(input) {
     }
     return rows.map((row, index) => validateMutationRow(row, index));
 }
+function deriveReferencedItemId(transactionId, reference, idPrefix) {
+    const digest = crypto
+        .createHash("sha256")
+        .update(transactionId)
+        .update("\0")
+        .update(reference)
+        .digest("hex");
+    const token = BigInt(`0x${digest.slice(0, 16)}`)
+        .toString(36)
+        .padStart(13, "0")
+        .slice(-12);
+    return `${normalizePrefix(idPrefix)}${token}`;
+}
+function replaceExactMutationReference(value, references) {
+    if (typeof value !== "string" || !value.startsWith("@")) {
+        return value;
+    }
+    const reference = value.slice(1);
+    const resolved = references[reference];
+    if (resolved === undefined) {
+        throw new PmCliError(`Unknown mutation reference "${value}".`, EXIT_CODE.USAGE);
+    }
+    return resolved;
+}
+function replaceDependencyReference(value, references) {
+    if (typeof value !== "string")
+        return value;
+    const resolvedValue = value.replace(MUTATION_DEPENDENCY_REFERENCE_PATTERN, (_match, prefix, reference) => {
+        const resolved = references[reference];
+        if (resolved === undefined) {
+            throw new PmCliError(`Unknown mutation reference "@${reference}".`, EXIT_CODE.USAGE);
+        }
+        return `${prefix}id=${resolved}`;
+    });
+    if (/(^|,)id=@/u.test(resolvedValue)) {
+        throw new PmCliError(`Malformed mutation reference in dependency "${value}".`, EXIT_CODE.USAGE);
+    }
+    return resolvedValue;
+}
+function referencedAliases(value) {
+    if (typeof value !== "string")
+        return [];
+    if (value.startsWith("@"))
+        return [value.slice(1)];
+    return [...value.matchAll(MUTATION_DEPENDENCY_REFERENCE_PATTERN)]
+        .map((match) => match[1])
+        .filter((reference) => reference !== undefined);
+}
+function assertAcyclicCreateReferences(rows) {
+    const graph = new Map();
+    for (const row of rows) {
+        if (row.op !== "create" || typeof row.ref !== "string")
+            continue;
+        const mutationOptions = isPlainObject(row.options) ? row.options : {};
+        const dependencies = Array.isArray(mutationOptions.dep)
+            ? mutationOptions.dep
+            : mutationOptions.dep === undefined
+                ? []
+                : [mutationOptions.dep];
+        graph.set(row.ref, [mutationOptions.parent, mutationOptions.blockedBy, ...dependencies]
+            .flatMap(referencedAliases));
+    }
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (reference) => {
+        if (visiting.has(reference)) {
+            throw new PmCliError(`Mutation reference cycle includes "@${reference}".`, EXIT_CODE.USAGE);
+        }
+        if (visited.has(reference))
+            return;
+        visiting.add(reference);
+        for (const dependency of graph.get(reference)) {
+            if (graph.has(dependency))
+                visit(dependency);
+        }
+        visiting.delete(reference);
+        visited.add(reference);
+    };
+    for (const reference of graph.keys())
+        visit(reference);
+}
+function parseMutationDocumentRows(input) {
+    const parsed = parseJsonValue(input, "Mutation document");
+    const envelope = Array.isArray(parsed)
+        ? { schema_version: 1, mutations: parsed }
+        : parsed;
+    if (!isPlainObject(envelope)) {
+        throw new PmCliError("Mutation document must be a JSON array or object.", EXIT_CODE.USAGE);
+    }
+    for (const key of Object.keys(envelope)) {
+        if (!MUTATION_DOCUMENT_KEYS.includes(key)) {
+            throw unknownKeyError("mutation document", key, MUTATION_DOCUMENT_KEYS);
+        }
+    }
+    if (envelope.schema_version !== undefined &&
+        envelope.schema_version !== 1) {
+        throw new PmCliError("Mutation document schema_version must be 1.", EXIT_CODE.USAGE);
+    }
+    if (!Array.isArray(envelope.mutations) || envelope.mutations.length === 0) {
+        throw new PmCliError("Mutation document requires a non-empty mutations array.", EXIT_CODE.USAGE);
+    }
+    return envelope.mutations.map((row, index) => {
+        if (!isPlainObject(row)) {
+            throw new PmCliError(`Mutation ${index + 1} must be an object.`, EXIT_CODE.USAGE);
+        }
+        for (const key of Object.keys(row)) {
+            if (!REFERENCED_MUTATION_ROW_KEYS.includes(key)) {
+                throw unknownKeyError(`mutation ${index + 1}`, key, REFERENCED_MUTATION_ROW_KEYS);
+            }
+        }
+        return { ...row };
+    });
+}
+function collectMutationReferences(rows, options) {
+    const references = Object.create(null);
+    for (const [index, row] of rows.entries()) {
+        if (row.ref === undefined)
+            continue;
+        if (row.op !== "create") {
+            throw new PmCliError(`Mutation ${index + 1} ref is only valid for create operations.`, EXIT_CODE.USAGE);
+        }
+        if (typeof row.ref !== "string" ||
+            !MUTATION_REFERENCE_PATTERN.test(row.ref)) {
+            throw new PmCliError(`Mutation ${index + 1} ref must match ${MUTATION_REFERENCE_PATTERN.source}.`, EXIT_CODE.USAGE);
+        }
+        if (references[row.ref] !== undefined) {
+            throw new PmCliError(`Duplicate mutation ref "${row.ref}".`, EXIT_CODE.USAGE);
+        }
+        references[row.ref] =
+            typeof row.id === "string" && row.id.trim().length > 0
+                ? normalizeItemId(row.id, options.idPrefix)
+                : deriveReferencedItemId(options.transactionId, row.ref, options.idPrefix);
+    }
+    return references;
+}
+/**
+ * Resolve a versioned heterogeneous mutation document. Create rows may declare
+ * a unique `ref`; omitted ids are derived deterministically from the stable
+ * transaction id, and `@ref` forward references are supported in target ids,
+ * parent/blocked-by options, and dependency entries.
+ */
+export function resolveItemMutationDocument(input, options) {
+    const rows = parseMutationDocumentRows(input);
+    const references = collectMutationReferences(rows, options);
+    assertAcyclicCreateReferences(rows);
+    const resolvedRows = rows.map((row) => {
+        const resolved = { ...row };
+        const reference = typeof resolved.ref === "string" ? resolved.ref : undefined;
+        delete resolved.ref;
+        if (reference !== undefined) {
+            resolved.id = references[reference];
+        }
+        else {
+            resolved.id = replaceExactMutationReference(resolved.id, references);
+        }
+        if (isPlainObject(resolved.options)) {
+            const mutationOptions = { ...resolved.options };
+            for (const key of ["parent", "blockedBy"]) {
+                if (mutationOptions[key] !== undefined) {
+                    mutationOptions[key] = replaceExactMutationReference(mutationOptions[key], references);
+                }
+            }
+            if (Array.isArray(mutationOptions.dep)) {
+                mutationOptions.dep = mutationOptions.dep.map((entry) => replaceDependencyReference(entry, references));
+            }
+            else if (mutationOptions.dep !== undefined) {
+                mutationOptions.dep = replaceDependencyReference(mutationOptions.dep, references);
+            }
+            resolved.options = mutationOptions;
+        }
+        return resolved;
+    });
+    const mutations = parseItemMutationBatch(JSON.stringify(resolvedRows));
+    const createIds = mutations
+        .filter((mutation) => mutation.op === "create")
+        .map((mutation) => mutation.id);
+    if (new Set(createIds).size !== createIds.length) {
+        throw new PmCliError("Duplicate resolved create id in mutation document.", EXIT_CODE.USAGE);
+    }
+    return { schema_version: 1, mutations, references };
+}
 function serializePairs(value, keys) {
     return keys
         .filter((key) => value[key] !== undefined && value[key] !== null)
@@ -359,4 +568,4 @@ export function validateItemMutationRows(value) {
     return parseItemMutationBatch(JSON.stringify(value));
 }
 //# sourceMappingURL=structured-mutations.js.map
-//# debugId=6471aca6-b7e1-51c0-b905-5617dfb7ef2a
+//# debugId=91be2c5d-c495-54bc-ac79-b4c645ad2c6e

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                                                                                                                                                                                                   |
@@ -82,6 +82,8 @@ pm install npm:@scope/pm-package --project
 pm package describe --project   # by-name surface map of every loaded package
 pm package describe my-package --markdown --output docs/my-package-reference.md
 pm package doctor --project --detail summary
+pm package migrate --project --dry-run --json
+pm package migrate --project --json
 pm upgrade --dry-run
 pm upgrade --packages-only
 pm upgrade --cli-only --repair
@@ -89,6 +91,13 @@ pm upgrade --cli-only --repair
 
 `pm install` and `pm package` are the preferred package-first workflow. `pm package` and `pm extension` bare invocations default to `--explore` so agents can list installed packages without remembering an action flag. `pm install '*'`, shell-expanded `pm install *`, and `pm install all` install bundled first-party packages. `pm extension` remains as a compatibility command for direct extension lifecycle operations.
 Install output includes a light `verification` summary with target tracker root, activation state, registered commands/actions/item types, and an `ok|degraded` health verdict. Runtime activation failure sets the command result and process exit status to failure; inspect `activation_diagnostics` and `command_discovery.next_steps` for the exact recovery path.
+Bare install names use bundled aliases before installed npm packages. Every
+install result reports `source_resolution`; when both candidates exist it marks
+the choice ambiguous and provides explicit bare and `npm:` retry commands.
+`package migrate` plans or applies active migration registrations and writes
+durable workspace-history receipts; a successful migration is skipped on later
+processes, while a failed migration remains retryable. `extension migrate` is
+the compatibility spelling.
 When package-owned commands are unavailable, usage guidance includes an install-ready retry (for example `pm install calendar`, `pm install search-advanced`, `pm install governance-audit`, or `pm install guide-shell`).
 
 ## Triage
@@ -516,20 +525,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 +559,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

@@ -1,6 +1,6 @@
 # Packages and Extensions
 
-Extension flags declared with `list: true` accumulate repeated long/short alias occurrences and comma-separated values into one array. Dynamic commands preserve flag-like variadic content after `--`, and package handlers can use the public `suppressHostOutput()` protocol when they already emitted streaming, binary, or pre-rendered output. Declarative blueprints are also checked for reserved item-field collisions during SDK lint/preflight and harness activation, so a package cannot pass author-time validation and then fail only when users create or update items. Local archive installation, command ownership, and MCP custom-field diagnostics are tracked by [pm-lw6acw](../.agents/pm/issues/pm-lw6acw.toon), [pm-6z0wzf](../.agents/pm/issues/pm-6z0wzf.toon), and [pm-yfdav2](../.agents/pm/issues/pm-yfdav2.toon). Transactional mutation guards, host-bound command test SDKs, and installed custom-type lifecycle parity are tracked by [pm-hx23u5](../.agents/pm/issues/pm-hx23u5.toon), [pm-wx2lr5](../.agents/pm/issues/pm-wx2lr5.toon), and [pm-scga6k](../.agents/pm/issues/pm-scga6k.toon).
+Extension flags declared with `list: true` accumulate repeated long/short alias occurrences and comma-separated values into one array. Dynamic commands preserve flag-like variadic content after `--`, and package handlers can use the public `suppressHostOutput()` protocol when they already emitted streaming, binary, or pre-rendered output. Declarative blueprints are also checked for reserved item-field collisions during SDK lint/preflight and harness activation, so a package cannot pass author-time validation and then fail only when users create or update items. Local archive installation, command ownership, and MCP custom-field diagnostics are tracked by [pm-lw6acw](../.agents/pm/issues/pm-lw6acw.toon), [pm-6z0wzf](../.agents/pm/issues/pm-6z0wzf.toon), and [pm-yfdav2](../.agents/pm/issues/pm-yfdav2.toon). Transactional mutation guards, host-bound command test SDKs, and installed custom-type lifecycle parity are tracked by [pm-hx23u5](../.agents/pm/issues/pm-hx23u5.toon), [pm-wx2lr5](../.agents/pm/issues/pm-wx2lr5.toon), and [pm-scga6k](../.agents/pm/issues/pm-scga6k.toon). Durable migration application, explicit source resolution, and composable preflight ownership are covered in [Extension Lifecycle Contracts](EXTENSION_LIFECYCLE.md).
 
 Packages add optional `pm` workflows without changing the core CLI. A package can ship one or more runtime extensions plus metadata such as docs and examples. Prefer the package-first commands in new docs and automation:
 
@@ -38,7 +38,7 @@ pm install calendar --project
 pm install search-advanced --project
 pm install kanban --project
 ```
-`pm install '*'`, `pm install all`, and shell-expanded `pm install *` are normalized to the same bundled install-all request. First-party package aliases come from each package manifest, with a fallback derived from the `packages/pm-*` directory name.
+`pm install '*'`, `pm install all`, and shell-expanded `pm install *` are normalized to the same bundled install-all request. First-party package aliases come from each package manifest, with a fallback derived from the `packages/pm-*` directory name. A bare bundled alias that also names an installed npm package reports both explicit choices in `source_resolution`; see [Extension Lifecycle Contracts](EXTENSION_LIFECYCLE.md).
 
 External registry packages are installed by exact package name. If `npm:<name>` returns a registry 404, JSON error output includes `fallback_candidates` and `next_best_command`; unpublished first-party packages fall back to `pm install --project github.com/unbraind/<name>`. Install results include package-owned `command_paths`, `action_paths`, `contributions`, `command_discovery`, and a light `verification` block covering the target tracker, activation status, registered commands/actions/item types, and health verdict. Agents should consume those fields instead of guessing from the package name or immediately spending another invocation on doctor. A successful activation persists the versioned contribution inventory in `.managed-extensions.json`; subsequent discovery can enumerate command handlers, hooks, parser/renderer targets, schema names, and the other registered surfaces without importing the package module. A failed runtime activation returns `ok: false`, `activated: false`, a non-zero CLI exit, and actionable diagnostics; missing SDK resolution adds an explicit dependency recovery step. Local installs are containment-safe when the extension destination is nested inside the source checkout: pm stages the package outside the source and prunes the destination, `.agents`, `node_modules`, and install-backup directories before copying, so reinstalling cannot recursively copy tracker history, host dependencies, or prior backups.
 Local `.tgz` and `.tar.gz` npm archives are inspected and extracted in an isolated temporary directory without invoking a shell. Archives must contain one `package/package.json` root, regular files/directories only, and bounded entry and expanded-byte totals. Absolute paths, traversal, alternate roots, links, device entries, oversized entries, and decompression-ratio abuse fail before installation. The managed source remains the original archive path, so reload and upgrade provenance do not point at a temporary extraction directory.
@@ -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: