@unbrained/pm-cli 2026.7.20 → 2026.7.21

package/dist/sdk/structured-mutations.d.ts

@@ -0,0 +1,21 @@
+import type { BulkItemMutation } from "./item-transaction.js";
+/** Validated transaction controls shared by atomic CLI and MCP adapters. */
+export interface AtomicMutationControls {
+    /** Compensation policy applied to created items when a later step fails. */
+    createCompensation?: "close" | "delete";
+    /** Workspace transaction lock lifetime in seconds. */
+    lockTtlSeconds?: number;
+    /** Maximum time to wait for the workspace transaction lock. */
+    lockWaitMs?: number;
+}
+/** Validate and normalize atomic transaction controls at every transport boundary. */
+export declare function parseAtomicMutationControls(value: Record<string, unknown>): AtomicMutationControls;
+/** Parse a JSON array, or an object containing `mutations`, into an atomic mutation batch. */
+export declare function parseItemMutationBatch(input: string): BulkItemMutation[];
+/**
+ * Convert a direct item JSON document or `pm get --json` envelope into the
+ * create/update option shape. Explicit CLI flags override document values.
+ */
+export declare function itemDocumentToMutationOptions(input: string, mode: "create" | "update", explicitOptions?: Record<string, unknown>): Record<string, unknown>;
+/** Validate an already-decoded MCP mutation array through the same strict parser as CLI stdin. */
+export declare function validateItemMutationRows(value: unknown): BulkItemMutation[];

package/dist/sdk/structured-mutations.js

@@ -0,0 +1,375 @@
+/**
+ * @module sdk/structured-mutations
+ *
+ * Parses agent-authored JSON mutation payloads into the public atomic item
+ * 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]="916a227a-1ec9-5af6-9b71-e871af2d7f0c")}catch(e){}}();
+import { EXIT_CODE } 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 { 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 ITEM_ENVELOPE_KEYS = [
+    "item",
+    "linked",
+    "schedule",
+    "claim_state",
+    "children",
+];
+const READ_ONLY_ITEM_KEYS = new Set([
+    "created_at",
+    "updated_at",
+    "closed_at",
+    "version",
+    "format_version",
+    "path",
+    "author",
+]);
+const UPDATE_READ_ONLY_ITEM_KEYS = new Set([...READ_ONLY_ITEM_KEYS, "id"]);
+const ITEM_FIELD_KEYS = new Set([
+    "id",
+    "title",
+    "description",
+    "type",
+    "status",
+    "priority",
+    "tags",
+    "body",
+    "deadline",
+    "estimated_minutes",
+    "acceptance_criteria",
+    "definition_of_ready",
+    "order",
+    "rank",
+    "goal",
+    "objective",
+    "value",
+    "impact",
+    "outcome",
+    "why_now",
+    "assignee",
+    "parent",
+    "reviewer",
+    "risk",
+    "confidence",
+    "sprint",
+    "release",
+    "blocked_by",
+    "blocked_reason",
+    "unblock_note",
+    "reporter",
+    "severity",
+    "environment",
+    "repro_steps",
+    "resolution",
+    "expected_result",
+    "actual_result",
+    "affected_version",
+    "fixed_version",
+    "component",
+    "regression",
+    "customer_impact",
+    "close_reason",
+    "dependencies",
+    "comments",
+    "notes",
+    "learnings",
+    "files",
+    "tests",
+    "docs",
+    "reminders",
+    "events",
+    "type_options",
+]);
+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"),
+};
+/** Validate and normalize atomic transaction controls at every transport boundary. */
+export function parseAtomicMutationControls(value) {
+    const controls = {};
+    const compensation = value.createCompensation;
+    if (compensation !== undefined) {
+        if (compensation !== "close" && compensation !== "delete") {
+            throw new PmCliError("createCompensation must be close or delete.", EXIT_CODE.USAGE);
+        }
+        controls.createCompensation = compensation;
+    }
+    for (const key of ["lockTtlSeconds", "lockWaitMs"]) {
+        const raw = value[key];
+        if (raw === undefined)
+            continue;
+        const parsed = typeof raw === "number" ||
+            (typeof raw === "string" && raw.trim().length > 0)
+            ? Number(raw)
+            : Number.NaN;
+        if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+            throw new PmCliError(`${key} must be a positive safe integer.`, EXIT_CODE.USAGE);
+        }
+        controls[key] = parsed;
+    }
+    return controls;
+}
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function nearestKey(key, candidates) {
+    const limit = Math.max(1, Math.min(3, Math.floor(key.length / 4) + 1));
+    let best;
+    for (const candidate of candidates) {
+        const distance = levenshteinDistanceWithinLimit(key, candidate, limit);
+        if (distance !== null && (best === undefined || distance < best.distance)) {
+            best = { key: candidate, distance };
+        }
+    }
+    return best?.key;
+}
+function unknownKeyError(scope, key, candidates) {
+    const suggestion = nearestKey(key, candidates);
+    return new PmCliError(suggestion === undefined
+        ? `${scope} does not recognize key "${key}". Allowed keys: ${candidates.join(", ")}.`
+        : `${scope} does not recognize key "${key}". Did you mean "${suggestion}"?`, EXIT_CODE.USAGE, {
+        code: "stdin_json_unknown_key",
+        required: `Use documented ${scope} keys only.`,
+        why: "Strict structured input prevents silent typos from creating incomplete or unintended mutations.",
+        nextSteps: [
+            suggestion === undefined
+                ? `Remove or correct "${key}".`
+                : `Replace "${key}" with "${suggestion}".`,
+        ],
+    });
+}
+function parseJsonValue(input, label) {
+    try {
+        return JSON.parse(input);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new PmCliError(`${label} must be valid JSON: ${detail}`, EXIT_CODE.USAGE, {
+            code: "stdin_json_invalid",
+            required: `Pipe one valid JSON ${label.toLowerCase()} into stdin.`,
+            why: "Structured mutation input must parse deterministically before any tracker write begins.",
+        });
+    }
+}
+function validateMutationObject(value, index) {
+    if (!isPlainObject(value)) {
+        throw new PmCliError(`Mutation ${index + 1} must be an object.`, EXIT_CODE.USAGE);
+    }
+    for (const key of Object.keys(value)) {
+        if (!MUTATION_ROW_KEYS.includes(key)) {
+            throw unknownKeyError(`mutation ${index + 1}`, key, MUTATION_ROW_KEYS);
+        }
+    }
+    return value;
+}
+function validateMutationOptions(options, op, index) {
+    if (options === undefined)
+        return undefined;
+    if (!isPlainObject(options)) {
+        throw new PmCliError(`Mutation ${index + 1} options must be an object.`, EXIT_CODE.USAGE);
+    }
+    for (const key of Object.keys(options)) {
+        if (!MUTATION_OPTION_KEYS[op].includes(key)) {
+            throw unknownKeyError(`mutation ${index + 1} ${op} options`, key, MUTATION_OPTION_KEYS[op]);
+        }
+    }
+    return options;
+}
+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);
+    }
+    const options = validateMutationOptions(mutation.options, op, index);
+    if (typeof id !== "string" || id.trim().length === 0) {
+        throw new PmCliError(`Mutation ${index + 1} requires a non-empty id.`, EXIT_CODE.USAGE);
+    }
+    const normalizedId = id.trim();
+    if (op === "close") {
+        if (typeof reason !== "string" || reason.trim().length === 0) {
+            throw new PmCliError(`Mutation ${index + 1} close requires a non-empty reason.`, EXIT_CODE.USAGE);
+        }
+        return {
+            op,
+            id: normalizedId,
+            reason: reason.trim(),
+            ...(options === undefined
+                ? {}
+                : { options: options }),
+        };
+    }
+    if (!isPlainObject(options)) {
+        throw new PmCliError(`Mutation ${index + 1} ${op} requires an options object.`, EXIT_CODE.USAGE);
+    }
+    return {
+        op,
+        id: normalizedId,
+        options: options,
+    };
+}
+/** Parse a JSON array, or an object containing `mutations`, into an atomic mutation batch. */
+export function parseItemMutationBatch(input) {
+    const parsed = parseJsonValue(input, "Mutation batch");
+    const rows = Array.isArray(parsed)
+        ? parsed
+        : isPlainObject(parsed) && Array.isArray(parsed.mutations)
+            ? parsed.mutations
+            : undefined;
+    if (rows === undefined || rows.length === 0) {
+        throw new PmCliError("Mutation batch must be a non-empty JSON array or an object with a non-empty mutations array.", EXIT_CODE.USAGE);
+    }
+    return rows.map((row, index) => validateMutationRow(row, index));
+}
+function serializePairs(value, keys) {
+    return keys
+        .filter((key) => value[key] !== undefined && value[key] !== null)
+        .map((key) => {
+        const rendered = String(value[key]);
+        return `${key}=${/[",\n\r\\]/u.test(rendered) ? JSON.stringify(rendered) : rendered}`;
+    })
+        .join(",");
+}
+function serializeObjectArray(value, keys, label) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || !value.every(isPlainObject)) {
+        throw new PmCliError(`${label} must be an array of objects.`, EXIT_CODE.USAGE);
+    }
+    return value.map((entry) => serializePairs(entry, keys));
+}
+function scalarItemOption(key, value) {
+    if (key === "tags" &&
+        Array.isArray(value) &&
+        value.every((entry) => typeof entry === "string")) {
+        return JSON.stringify(value);
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    return value;
+}
+function appendFacetOptions(target, source, skipPersistedAnnotations = false) {
+    const mappings = [
+        ["dependencies", "dep", ["id", "kind", "created_at", "author"]],
+        ["comments", "comment", ["text", "created_at", "author"]],
+        ["notes", "note", ["text", "created_at", "author"]],
+        ["learnings", "learning", ["text", "created_at", "author"]],
+        ["files", "file", ["path", "scope", "note"]],
+        ["tests", "test", ["command", "scope", "timeout_seconds"]],
+        ["docs", "doc", ["path", "scope", "note"]],
+        ["reminders", "reminder", ["at", "text", "created_at"]],
+        ["events", "event", ["start_at", "end_at", "title", "location"]],
+        ["type_options", "typeOption", ["key", "value"]],
+    ];
+    for (const [sourceKey, targetKey, keys] of mappings) {
+        const sourceValue = source[sourceKey];
+        const serialized = serializeObjectArray(skipPersistedAnnotations &&
+            ["comments", "notes", "learnings"].includes(sourceKey) &&
+            Array.isArray(sourceValue)
+            ? sourceValue.filter((entry) => !isPlainObject(entry) || entry.created_at === undefined)
+            : sourceValue, keys, sourceKey);
+        if (serialized !== undefined && serialized.length > 0)
+            target[targetKey] = serialized;
+    }
+}
+function validateItemDocumentKeys(parsed, envelope) {
+    for (const key of Object.keys(parsed)) {
+        if (envelope) {
+            if (!ITEM_ENVELOPE_KEYS.includes(key))
+                throw unknownKeyError("item envelope", key, ITEM_ENVELOPE_KEYS);
+            continue;
+        }
+        if (!ITEM_FIELD_KEYS.has(key) &&
+            nearestKey(key, [...ITEM_FIELD_KEYS]) === undefined &&
+            nearestKey(key, ITEM_ENVELOPE_KEYS) === "item")
+            throw unknownKeyError("item envelope", key, ITEM_ENVELOPE_KEYS);
+    }
+}
+function resolveItemDocument(parsed) {
+    const envelope = Object.hasOwn(parsed, "item");
+    validateItemDocumentKeys(parsed, envelope);
+    const item = envelope ? parsed.item : parsed;
+    if (!isPlainObject(item)) {
+        throw new PmCliError("Item document item must be an object.", EXIT_CODE.USAGE);
+    }
+    return {
+        item,
+        ...(envelope && isPlainObject(parsed.linked)
+            ? { linked: parsed.linked }
+            : {}),
+    };
+}
+function appendItemDocumentEntry(documentOptions, key, value, mode) {
+    const readOnlyKeys = mode === "update" ? UPDATE_READ_ONLY_ITEM_KEYS : READ_ONLY_ITEM_KEYS;
+    if (readOnlyKeys.has(key))
+        return;
+    if (!ITEM_FIELD_KEYS.has(key)) {
+        const suggestion = nearestKey(key, [...ITEM_FIELD_KEYS]);
+        if (suggestion !== undefined)
+            throw unknownKeyError("item document", key, [...ITEM_FIELD_KEYS]);
+        const fields = Array.isArray(documentOptions.field)
+            ? documentOptions.field
+            : [];
+        fields.push(serializePairs({
+            key,
+            value: typeof value === "string" ? value : JSON.stringify(value),
+        }, ["key", "value"]));
+        documentOptions.field = fields;
+        return;
+    }
+    if ([
+        "dependencies",
+        "comments",
+        "notes",
+        "learnings",
+        "files",
+        "tests",
+        "docs",
+        "reminders",
+        "events",
+        "type_options",
+    ].includes(key))
+        return;
+    documentOptions[key.replaceAll(/_([a-z])/gu, (_match, letter) => letter.toUpperCase())] = scalarItemOption(key, value);
+}
+/**
+ * Convert a direct item JSON document or `pm get --json` envelope into the
+ * create/update option shape. Explicit CLI flags override document values.
+ */
+export function itemDocumentToMutationOptions(input, mode, explicitOptions = {}) {
+    const parsed = parseJsonValue(input, "Item document");
+    if (!isPlainObject(parsed)) {
+        throw new PmCliError("Item document must be a JSON object.", EXIT_CODE.USAGE);
+    }
+    const { item, linked } = resolveItemDocument(parsed);
+    const documentOptions = {};
+    for (const [key, value] of Object.entries(item)) {
+        appendItemDocumentEntry(documentOptions, key, value, mode);
+    }
+    appendFacetOptions(documentOptions, item, mode === "update");
+    if (linked !== undefined)
+        appendFacetOptions(documentOptions, linked);
+    return {
+        ...documentOptions,
+        ...Object.fromEntries(Object.entries(explicitOptions).filter(([, value]) => value !== undefined)),
+        stdinJson: undefined,
+    };
+}
+/** Validate an already-decoded MCP mutation array through the same strict parser as CLI stdin. */
+export function validateItemMutationRows(value) {
+    return parseItemMutationBatch(JSON.stringify(value));
+}
+//# sourceMappingURL=structured-mutations.js.map
+//# debugId=916a227a-1ec9-5af6-9b71-e871af2d7f0c

package/dist/sdk/structured-mutations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-mutations.js","sources":["sdk/structured-mutations.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/structured-mutations\n *\n * Parses agent-authored JSON mutation payloads into the public atomic item\n * transaction contract and normalizes full item documents for CLI round trips.\n */\nimport { EXIT_CODE } from \"../core/shared/constants.js\";\nimport { PmCliError } from \"../core/shared/errors.js\";\nimport { levenshteinDistanceWithinLimit } from \"../core/shared/levenshtein.js\";\nimport { CLOSE_FLAG_CONTRACTS } from \"./cli-contracts/flag-contracts.js\";\nimport {\n  CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS,\n  UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS,\n} from \"./cli-contracts/commander-mutation-options.js\";\nimport type { PmClientFullMutationOptions } from \"./runtime.js\";\nimport type { BulkItemMutation } from \"./item-transaction.js\";\n\nconst MUTATION_ROW_KEYS = [\"op\", \"id\", \"reason\", \"options\"] as const;\nconst ITEM_ENVELOPE_KEYS = [\n  \"item\",\n  \"linked\",\n  \"schedule\",\n  \"claim_state\",\n  \"children\",\n] as const;\nconst READ_ONLY_ITEM_KEYS = new Set([\n  \"created_at\",\n  \"updated_at\",\n  \"closed_at\",\n  \"version\",\n  \"format_version\",\n  \"path\",\n  \"author\",\n]);\nconst UPDATE_READ_ONLY_ITEM_KEYS = new Set([...READ_ONLY_ITEM_KEYS, \"id\"]);\nconst ITEM_FIELD_KEYS = new Set([\n  \"id\",\n  \"title\",\n  \"description\",\n  \"type\",\n  \"status\",\n  \"priority\",\n  \"tags\",\n  \"body\",\n  \"deadline\",\n  \"estimated_minutes\",\n  \"acceptance_criteria\",\n  \"definition_of_ready\",\n  \"order\",\n  \"rank\",\n  \"goal\",\n  \"objective\",\n  \"value\",\n  \"impact\",\n  \"outcome\",\n  \"why_now\",\n  \"assignee\",\n  \"parent\",\n  \"reviewer\",\n  \"risk\",\n  \"confidence\",\n  \"sprint\",\n  \"release\",\n  \"blocked_by\",\n  \"blocked_reason\",\n  \"unblock_note\",\n  \"reporter\",\n  \"severity\",\n  \"environment\",\n  \"repro_steps\",\n  \"resolution\",\n  \"expected_result\",\n  \"actual_result\",\n  \"affected_version\",\n  \"fixed_version\",\n  \"component\",\n  \"regression\",\n  \"customer_impact\",\n  \"close_reason\",\n  \"dependencies\",\n  \"comments\",\n  \"notes\",\n  \"learnings\",\n  \"files\",\n  \"tests\",\n  \"docs\",\n  \"reminders\",\n  \"events\",\n  \"type_options\",\n]);\nconst MUTATION_OPTION_KEYS: Readonly<\n  Record<BulkItemMutation[\"op\"], readonly string[]>\n> = {\n  create: CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS.map(\n    (contract) => contract.target,\n  ),\n  update: UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS.map(\n    (contract) => contract.target,\n  ),\n  close: CLOSE_FLAG_CONTRACTS.map((contract) =>\n    contract.flag\n      .slice(2)\n      .replaceAll(/-([a-z])/gu, (_match, letter: string) =>\n        letter.toUpperCase(),\n      ),\n  ).filter((key) => key !== \"reason\"),\n};\n\n/** Validated transaction controls shared by atomic CLI and MCP adapters. */\nexport interface AtomicMutationControls {\n  /** Compensation policy applied to created items when a later step fails. */\n  createCompensation?: \"close\" | \"delete\";\n  /** Workspace transaction lock lifetime in seconds. */\n  lockTtlSeconds?: number;\n  /** Maximum time to wait for the workspace transaction lock. */\n  lockWaitMs?: number;\n}\n\n/** Validate and normalize atomic transaction controls at every transport boundary. */\nexport function parseAtomicMutationControls(\n  value: Record<string, unknown>,\n): AtomicMutationControls {\n  const controls: AtomicMutationControls = {};\n  const compensation = value.createCompensation;\n  if (compensation !== undefined) {\n    if (compensation !== \"close\" && compensation !== \"delete\") {\n      throw new PmCliError(\n        \"createCompensation must be close or delete.\",\n        EXIT_CODE.USAGE,\n      );\n    }\n    controls.createCompensation = compensation;\n  }\n  for (const key of [\"lockTtlSeconds\", \"lockWaitMs\"] as const) {\n    const raw = value[key];\n    if (raw === undefined) continue;\n    const parsed =\n      typeof raw === \"number\" ||\n      (typeof raw === \"string\" && raw.trim().length > 0)\n        ? Number(raw)\n        : Number.NaN;\n    if (!Number.isSafeInteger(parsed) || parsed <= 0) {\n      throw new PmCliError(\n        `${key} must be a positive safe integer.`,\n        EXIT_CODE.USAGE,\n      );\n    }\n    controls[key] = parsed;\n  }\n  return controls;\n}\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n    return false;\n  }\n  const prototype = Object.getPrototypeOf(value);\n  return prototype === Object.prototype || prototype === null;\n}\n\nfunction nearestKey(\n  key: string,\n  candidates: readonly string[],\n): string | undefined {\n  const limit = Math.max(1, Math.min(3, Math.floor(key.length / 4) + 1));\n  let best: { key: string; distance: number } | undefined;\n  for (const candidate of candidates) {\n    const distance = levenshteinDistanceWithinLimit(key, candidate, limit);\n    if (distance !== null && (best === undefined || distance < best.distance)) {\n      best = { key: candidate, distance };\n    }\n  }\n  return best?.key;\n}\n\nfunction unknownKeyError(\n  scope: string,\n  key: string,\n  candidates: readonly string[],\n): PmCliError {\n  const suggestion = nearestKey(key, candidates);\n  return new PmCliError(\n    suggestion === undefined\n      ? `${scope} does not recognize key \"${key}\". Allowed keys: ${candidates.join(\", \")}.`\n      : `${scope} does not recognize key \"${key}\". Did you mean \"${suggestion}\"?`,\n    EXIT_CODE.USAGE,\n    {\n      code: \"stdin_json_unknown_key\",\n      required: `Use documented ${scope} keys only.`,\n      why: \"Strict structured input prevents silent typos from creating incomplete or unintended mutations.\",\n      nextSteps: [\n        suggestion === undefined\n          ? `Remove or correct \"${key}\".`\n          : `Replace \"${key}\" with \"${suggestion}\".`,\n      ],\n    },\n  );\n}\n\nfunction parseJsonValue(input: string, label: string): unknown {\n  try {\n    return JSON.parse(input) as unknown;\n  } catch (error: unknown) {\n    const detail = error instanceof Error ? error.message : String(error);\n    throw new PmCliError(\n      `${label} must be valid JSON: ${detail}`,\n      EXIT_CODE.USAGE,\n      {\n        code: \"stdin_json_invalid\",\n        required: `Pipe one valid JSON ${label.toLowerCase()} into stdin.`,\n        why: \"Structured mutation input must parse deterministically before any tracker write begins.\",\n      },\n    );\n  }\n}\n\nfunction validateMutationObject(\n  value: unknown,\n  index: number,\n): Record<string, unknown> {\n  if (!isPlainObject(value)) {\n    throw new PmCliError(\n      `Mutation ${index + 1} must be an object.`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  for (const key of Object.keys(value)) {\n    if (\n      !MUTATION_ROW_KEYS.includes(key as (typeof MUTATION_ROW_KEYS)[number])\n    ) {\n      throw unknownKeyError(`mutation ${index + 1}`, key, MUTATION_ROW_KEYS);\n    }\n  }\n  return value;\n}\n\nfunction validateMutationOptions(\n  options: unknown,\n  op: BulkItemMutation[\"op\"],\n  index: number,\n): Record<string, unknown> | undefined {\n  if (options === undefined) return undefined;\n  if (!isPlainObject(options)) {\n    throw new PmCliError(\n      `Mutation ${index + 1} options must be an object.`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  for (const key of Object.keys(options)) {\n    if (!MUTATION_OPTION_KEYS[op].includes(key)) {\n      throw unknownKeyError(\n        `mutation ${index + 1} ${op} options`,\n        key,\n        MUTATION_OPTION_KEYS[op],\n      );\n    }\n  }\n  return options;\n}\n\nfunction validateMutationRow(value: unknown, index: number): BulkItemMutation {\n  const mutation = validateMutationObject(value, index);\n  const { op, id, reason } = mutation;\n  if (op !== \"create\" && op !== \"update\" && op !== \"close\") {\n    throw new PmCliError(\n      `Mutation ${index + 1} op must be create, update, or close.`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  const options = validateMutationOptions(mutation.options, op, index);\n  if (typeof id !== \"string\" || id.trim().length === 0) {\n    throw new PmCliError(\n      `Mutation ${index + 1} requires a non-empty id.`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  const normalizedId = id.trim();\n  if (op === \"close\") {\n    if (typeof reason !== \"string\" || reason.trim().length === 0) {\n      throw new PmCliError(\n        `Mutation ${index + 1} close requires a non-empty reason.`,\n        EXIT_CODE.USAGE,\n      );\n    }\n    return {\n      op,\n      id: normalizedId,\n      reason: reason.trim(),\n      ...(options === undefined\n        ? {}\n        : { options: options as PmClientFullMutationOptions }),\n    };\n  }\n  if (!isPlainObject(options)) {\n    throw new PmCliError(\n      `Mutation ${index + 1} ${op} requires an options object.`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  return {\n    op,\n    id: normalizedId,\n    options: options as PmClientFullMutationOptions,\n  };\n}\n\n/** Parse a JSON array, or an object containing `mutations`, into an atomic mutation batch. */\nexport function parseItemMutationBatch(input: string): BulkItemMutation[] {\n  const parsed = parseJsonValue(input, \"Mutation batch\");\n  const rows = Array.isArray(parsed)\n    ? parsed\n    : isPlainObject(parsed) && Array.isArray(parsed.mutations)\n      ? parsed.mutations\n      : undefined;\n  if (rows === undefined || rows.length === 0) {\n    throw new PmCliError(\n      \"Mutation batch must be a non-empty JSON array or an object with a non-empty mutations array.\",\n      EXIT_CODE.USAGE,\n    );\n  }\n  return rows.map((row, index) => validateMutationRow(row, index));\n}\n\nfunction serializePairs(\n  value: Record<string, unknown>,\n  keys: readonly string[],\n): string {\n  return keys\n    .filter((key) => value[key] !== undefined && value[key] !== null)\n    .map((key) => {\n      const rendered = String(value[key]);\n      return `${key}=${/[\",\\n\\r\\\\]/u.test(rendered) ? JSON.stringify(rendered) : rendered}`;\n    })\n    .join(\",\");\n}\n\nfunction serializeObjectArray(\n  value: unknown,\n  keys: readonly string[],\n  label: string,\n): string[] | undefined {\n  if (value === undefined) return undefined;\n  if (!Array.isArray(value) || !value.every(isPlainObject)) {\n    throw new PmCliError(\n      `${label} must be an array of objects.`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  return value.map((entry) => serializePairs(entry, keys));\n}\n\nfunction scalarItemOption(key: string, value: unknown): unknown {\n  if (\n    key === \"tags\" &&\n    Array.isArray(value) &&\n    value.every((entry) => typeof entry === \"string\")\n  ) {\n    return JSON.stringify(value);\n  }\n  if (typeof value === \"number\" || typeof value === \"boolean\") {\n    return String(value);\n  }\n  return value;\n}\n\nfunction appendFacetOptions(\n  target: Record<string, unknown>,\n  source: Record<string, unknown>,\n  skipPersistedAnnotations = false,\n): void {\n  const mappings: ReadonlyArray<readonly [string, string, readonly string[]]> =\n    [\n      [\"dependencies\", \"dep\", [\"id\", \"kind\", \"created_at\", \"author\"]],\n      [\"comments\", \"comment\", [\"text\", \"created_at\", \"author\"]],\n      [\"notes\", \"note\", [\"text\", \"created_at\", \"author\"]],\n      [\"learnings\", \"learning\", [\"text\", \"created_at\", \"author\"]],\n      [\"files\", \"file\", [\"path\", \"scope\", \"note\"]],\n      [\"tests\", \"test\", [\"command\", \"scope\", \"timeout_seconds\"]],\n      [\"docs\", \"doc\", [\"path\", \"scope\", \"note\"]],\n      [\"reminders\", \"reminder\", [\"at\", \"text\", \"created_at\"]],\n      [\"events\", \"event\", [\"start_at\", \"end_at\", \"title\", \"location\"]],\n      [\"type_options\", \"typeOption\", [\"key\", \"value\"]],\n    ];\n  for (const [sourceKey, targetKey, keys] of mappings) {\n    const sourceValue = source[sourceKey];\n    const serialized = serializeObjectArray(\n      skipPersistedAnnotations &&\n        [\"comments\", \"notes\", \"learnings\"].includes(sourceKey) &&\n        Array.isArray(sourceValue)\n        ? sourceValue.filter(\n            (entry) =>\n              !isPlainObject(entry) || entry.created_at === undefined,\n          )\n        : sourceValue,\n      keys,\n      sourceKey,\n    );\n    if (serialized !== undefined && serialized.length > 0)\n      target[targetKey] = serialized;\n  }\n}\n\nfunction validateItemDocumentKeys(\n  parsed: Record<string, unknown>,\n  envelope: boolean,\n): void {\n  for (const key of Object.keys(parsed)) {\n    if (envelope) {\n      if (\n        !ITEM_ENVELOPE_KEYS.includes(key as (typeof ITEM_ENVELOPE_KEYS)[number])\n      )\n        throw unknownKeyError(\"item envelope\", key, ITEM_ENVELOPE_KEYS);\n      continue;\n    }\n    if (\n      !ITEM_FIELD_KEYS.has(key) &&\n      nearestKey(key, [...ITEM_FIELD_KEYS]) === undefined &&\n      nearestKey(key, ITEM_ENVELOPE_KEYS) === \"item\"\n    )\n      throw unknownKeyError(\"item envelope\", key, ITEM_ENVELOPE_KEYS);\n  }\n}\n\nfunction resolveItemDocument(parsed: Record<string, unknown>): {\n  item: Record<string, unknown>;\n  linked?: Record<string, unknown>;\n} {\n  const envelope = Object.hasOwn(parsed, \"item\");\n  validateItemDocumentKeys(parsed, envelope);\n  const item = envelope ? parsed.item : parsed;\n  if (!isPlainObject(item)) {\n    throw new PmCliError(\n      \"Item document item must be an object.\",\n      EXIT_CODE.USAGE,\n    );\n  }\n  return {\n    item,\n    ...(envelope && isPlainObject(parsed.linked)\n      ? { linked: parsed.linked }\n      : {}),\n  };\n}\n\nfunction appendItemDocumentEntry(\n  documentOptions: Record<string, unknown>,\n  key: string,\n  value: unknown,\n  mode: \"create\" | \"update\",\n): void {\n  const readOnlyKeys =\n    mode === \"update\" ? UPDATE_READ_ONLY_ITEM_KEYS : READ_ONLY_ITEM_KEYS;\n  if (readOnlyKeys.has(key)) return;\n  if (!ITEM_FIELD_KEYS.has(key)) {\n    const suggestion = nearestKey(key, [...ITEM_FIELD_KEYS]);\n    if (suggestion !== undefined)\n      throw unknownKeyError(\"item document\", key, [...ITEM_FIELD_KEYS]);\n    const fields = Array.isArray(documentOptions.field)\n      ? (documentOptions.field as string[])\n      : [];\n    fields.push(\n      serializePairs(\n        {\n          key,\n          value: typeof value === \"string\" ? value : JSON.stringify(value),\n        },\n        [\"key\", \"value\"],\n      ),\n    );\n    documentOptions.field = fields;\n    return;\n  }\n  if (\n    [\n      \"dependencies\",\n      \"comments\",\n      \"notes\",\n      \"learnings\",\n      \"files\",\n      \"tests\",\n      \"docs\",\n      \"reminders\",\n      \"events\",\n      \"type_options\",\n    ].includes(key)\n  )\n    return;\n  documentOptions[\n    key.replaceAll(/_([a-z])/gu, (_match, letter: string) =>\n      letter.toUpperCase(),\n    )\n  ] = scalarItemOption(key, value);\n}\n\n/**\n * Convert a direct item JSON document or `pm get --json` envelope into the\n * create/update option shape. Explicit CLI flags override document values.\n */\nexport function itemDocumentToMutationOptions(\n  input: string,\n  mode: \"create\" | \"update\",\n  explicitOptions: Record<string, unknown> = {},\n): Record<string, unknown> {\n  const parsed = parseJsonValue(input, \"Item document\");\n  if (!isPlainObject(parsed)) {\n    throw new PmCliError(\n      \"Item document must be a JSON object.\",\n      EXIT_CODE.USAGE,\n    );\n  }\n  const { item, linked } = resolveItemDocument(parsed);\n  const documentOptions: Record<string, unknown> = {};\n  for (const [key, value] of Object.entries(item)) {\n    appendItemDocumentEntry(documentOptions, key, value, mode);\n  }\n  appendFacetOptions(documentOptions, item, mode === \"update\");\n  if (linked !== undefined) appendFacetOptions(documentOptions, linked);\n  return {\n    ...documentOptions,\n    ...Object.fromEntries(\n      Object.entries(explicitOptions).filter(\n        ([, value]) => value !== undefined,\n      ),\n    ),\n    stdinJson: undefined,\n  };\n}\n\n/** Validate an already-decoded MCP mutation array through the same strict parser as CLI stdin. */\nexport function validateItemMutationRows(value: unknown): BulkItemMutation[] {\n  return parseItemMutationBatch(JSON.stringify(value));\n}\n"],"names":[],"mappings":"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","debugId":"916a227a-1ec9-5af6-9b71-e871af2d7f0c"}

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         | `update-many`, `close-many`                                                                                                    | apply one change across a matched, dry-run-previewed set with a rollback checkpoint                                                                                                                                                                                                             |
+| 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                                                                                                                                                    |
 | 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                                                                                                                                                                                                                                            |
@@ -327,6 +327,13 @@ When a flag is rejected with `Unknown option`, the error guidance now suggests t
 
 ## Create and Update
 
+Tracked structured-input and compact-output work:
+[pm-xm7c](../.agents/pm/features/pm-xm7c.toon),
+[pm-kipd](../.agents/pm/features/pm-kipd.toon),
+[pm-nilh](../.agents/pm/features/pm-nilh.toon),
+[pm-cfed](../.agents/pm/features/pm-cfed.toon), and
+[pm-g9xk](../.agents/pm/features/pm-g9xk.toon).
+
 Shortest agent-friendly create (positional title + defaults to `Task` type):
 
 ```bash
@@ -376,6 +383,25 @@ pm update pm-a1b2 --body-file ./specs/updated-spec.md
 
 `--body-file` is mutually exclusive with `--body` (passing both errors). Use `--body -` to read the body from piped stdin.
 
+For whole-item automation, `--stdin-json` on create/update accepts either a
+direct item object or the envelope emitted by `pm get <id> --json`. Read-only
+fields are ignored, linked facets are normalized through their audited mutation
+inputs, and explicit CLI flags override document values:
+
+```bash
+# Create from a complete document.
+printf '%s' '{"title":"Imported incident","type":"Issue","tags":["imported"]}' \
+  | pm create --stdin-json --json
+
+# Lossless get -> edit -> update round trip.
+pm get pm-a1b2 --json > item.json
+# edit item.json with an ordinary JSON-aware tool
+pm update pm-a1b2 --stdin-json < item.json
+```
+
+Input is strict: a near-miss such as `acceptance_criterai` fails with a
+did-you-mean diagnostic instead of becoming an accidental custom field.
+
 Repeated singular/plural list flags now accumulate, so `--tag a --tag b` is equivalent to `--tags a,b` (the same holds for `--status`, `--ids`, and `--fields` on read commands). Earlier versions silently kept only the last value. `list`/`search` also accept `--tags` as a never-block alias for the canonical read filter `--tag`.
 
 `--tags` REPLACES the whole tag list. To edit tags without restating the full set, use the additive/subtractive flags on `create`/`update`/`update-many`:
@@ -389,7 +415,7 @@ pm update pm-abc1 --remove-tags stale            # drops "stale", keeps the rest
 pm create "New backend task" --add-tags backend,p1
 ```
 
-Acceptance criteria get the same additive treatment on `update`/`update-many`: `--acceptance-criteria`/`--ac` REPLACES the whole value, while `--add-ac <text>` appends one criterion (repeatable; deduped on exact text) and `--remove-ac <text>` removes one criterion by exact text match (repeatable; a non-matching selector adds a `remove_ac_unmatched:<text>` warning instead of silently no-oping). Criteria are stored joined by `` ;  ``, so one criterion cannot contain a semicolon. Disjoint `--add-ac` edits from concurrent agents/branches merge cleanly instead of clobbering each other.
+Acceptance criteria get the same additive treatment on `update`/`update-many`: `--acceptance-criteria`/`--ac` REPLACES the whole value, while `--add-ac <text>` appends one criterion (repeatable; deduped on exact text) and `--remove-ac <text>` removes one criterion by exact text match (repeatable; a non-matching selector adds a `remove_ac_unmatched:<text>` warning instead of silently no-oping). Criteria are stored with semicolon-space separators, so one criterion cannot contain a semicolon. Disjoint `--add-ac` edits from concurrent agents/branches merge cleanly instead of clobbering each other.
 
 ```bash
 pm update pm-abc1 --add-ac "error path covered by a regression test"
@@ -426,13 +452,29 @@ pm update <id> --expected "Retry succeeds after backoff" --actual "Retry threw o
 
 Repeat `--ac`/`--acceptance-criteria` to build multi-part criteria; values are stored in order joined by `; `. Dependency inputs accept either a bare existing item id or the explicit `id=<id>,kind=<kind>` form, and malformed shorthand such as `related:pm-abcd` fails before it can create a dangling graph edge.
 
-Mutation commands (`create`/`update`/`close`/`append`/...) echo a `changed_fields` array. In high-volume agent loops that array is mostly redundant with the item echo above it, so pass the global `--no-changed-fields` flag to replace it with a compact `changed_field_count`:
+Mutation commands (`create`/`update`/`close`/`append`/...) default to an
+agent-efficient `id`/`status`/`changed_field_count` envelope. Use
+`--no-changed-fields` for the full item echo without the redundant delta array,
+or `--full-changed-fields` to restore the legacy complete envelope:
 
 ```bash
-pm --no-changed-fields create "Probe item"   # output keeps changed_field_count, drops the array
+pm create "Probe item"                       # id + status + changed_field_count
+pm --no-changed-fields create "Probe item"   # item echo + changed_field_count
+pm --full-changed-fields create "Probe item" # item echo + changed_fields array
 pm --id-only create "Probe item"             # output is only id + status
 ```
 
+For strict JSON consumers, the global `--lean` flag recursively omits null,
+undefined, empty-array, and empty-object noise while preserving meaningful
+false/zero/empty-string values. On usage failures it keeps only actionable
+error fields (`type`, `code`, `detail`, `exit_code`, examples, next steps, and
+recovery), reducing retry context without hiding the deterministic fix:
+
+```bash
+pm --json --lean get pm-a1b2
+pm --json --lean create --unknown-option
+```
+
 Use `pm create --allow-missing-parent --parent <id>` only for deliberate imports or staged backlog reconstruction. Normal `pm create --parent <id>` fails fast when the parent id cannot be resolved.
 
 Use `pm close <duplicate-id> --duplicate-of <canonical-id>` to close duplicates. The command validates the canonical target exists, records `duplicate_of`, auto-fills the close reason as `Duplicate of <canonical-id>` when no reason text was supplied, and fills the resolution/expected/actual closure fields when they were not provided explicitly.
@@ -447,6 +489,32 @@ When closing a blocker, `pm close` scans reverse `blocked_by` edges and auto-unb
 
 Over MCP the mutation tools (`pm_create`/`pm_update`/`pm_close`/`pm_run` append/update-many) are compact by default; pass `fullChangedFields=true` to restore the full `changed_fields` delta, or `idOnly=true` for single-item id/status output.
 
+### 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:
+
+```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"}
+]
+JSON
+```
+
+Use `--dry-run` to validate and preview without acquiring a writer lock. Reuse
+the exact transaction id and deterministic batch after interruption: the SDK
+journal resumes pending steps and never duplicates a successfully applied
+step. `--create-compensation close|delete`, `--lock-ttl-seconds`, and
+`--lock-wait-ms` expose the transaction safety controls. The equivalent MCP
+surface is `pm_mutate`.
+
 ## 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.
@@ -574,10 +642,22 @@ pm graph audit --sample 5 --exempt-isolate pm-root
 pm graph communities --kind blocked_by --limit 5
 pm graph redundancy --max-depth 6 --limit 20
 pm graph dominators <id> --direction outgoing --limit 10
+pm graph slack --limit 20
+pm graph centrality --kind blocked_by --limit 10
+pm graph articulation --limit 20
 pm graph plan --sample 5 --limit 20
+pm graph audit --save-baseline
+pm graph audit --exempt-isolate-type Reminder,Event
+pm graph index
+pm graph index --rebuild
+pm graph index --clear
 ```
 
-`graph` is read-only and answers workspace-wide relationship questions through the public SDK graph toolkit. `ancestors`/`descendants` walk registered hierarchy kinds, `predecessors`/`successors` walk order-bearing kinds, `paths` enumerates bounded simple paths between two items with per-edge kinds, and `impact` reports the bounded blast radius with an explaining path per affected item. `analyze` returns workspace execution analytics (topological layers, prerequisite frontier, critical path, genuine ordering cycles) plus knowledge-graph structure (components, orphans, hubs), and `audit` runs the policy-aware governance audit with counts-first findings, severities, and bounded evidence samples. Audit severity gates on lifecycle: ordering cycles and duplicated edge spellings confined to closed/canceled items downgrade to informational `legacy_ordering_cycle`/`legacy_duplicate_edge` findings (history debt, never repaired ad hoc), while `ordering_cycle` errors and `duplicate_edge` findings are reserved for subjects touching at least one active item; `duplicate_edge` reports parallel same-family spellings — including reciprocal inverse pairs such as `A blocked_by B` plus `B blocks A` — that transitive-reduction redundancy deliberately cannot see. `communities` clusters the undirected structure with deterministic label propagation (reporting `iterations` and `converged`), `redundancy` finds stored edges implied by a longer path of the same semantic family (`blocked_by`/`blocks` and hierarchy spellings witness each other, each row carrying its witness path), and `dominators` reports the structural bottlenecks of one item's reachable subgraph — nodes every path from the root must pass through, ranked by how much work they gate (`dominated_count`). `plan` derives a dry-run remediation plan from the audit plus the redundancy scan: exact `remove`/`retype`/`supersede`/`waive`/`investigate` proposals with per-step policy code, evidence, rationale, and confidence — nothing is ever applied automatically and no proposal invents an edge. Every envelope is counts-first with explicit `truncated`, `cost` (visited nodes, inspected edges), and `cache` (workspace fingerprint plus assembly/result hit-or-miss) metadata; repeated identical queries in long-lived hosts such as the MCP server are answered from a fingerprint-keyed snapshot cache that invalidates on any relationship-relevant item change. `--summary` suppresses row collections entirely. `--kind` accepts registered relationship kinds (repeatable or comma-separated) and fails fast on unknown values (`redundancy` additionally requires directed ordering or hierarchy kinds); `--after` resumes hierarchy/ordering walks after a previously returned node id (see [Relationship Graph](RELATIONSHIP_GRAPH.md)).
+`graph` is read-only and answers workspace-wide relationship questions through the public SDK graph toolkit. `ancestors`/`descendants` walk registered hierarchy kinds, `predecessors`/`successors` walk order-bearing kinds, `paths` enumerates bounded simple paths between two items with per-edge kinds, and `impact` reports the bounded blast radius with an explaining path per affected item. `analyze` returns workspace execution analytics (topological layers, prerequisite frontier, critical path, genuine ordering cycles) plus knowledge-graph structure (components, orphans, hubs), and `audit` runs the policy-aware governance audit with counts-first findings, severities, and bounded evidence samples. Audit severity gates on lifecycle: ordering cycles and duplicated edge spellings confined to closed/canceled items downgrade to informational `legacy_ordering_cycle`/`legacy_duplicate_edge` findings (history debt, never repaired ad hoc), while `ordering_cycle` errors and `duplicate_edge` findings are reserved for subjects touching at least one active item; `duplicate_edge` reports parallel same-family spellings — including reciprocal inverse pairs such as `A blocked_by B` plus `B blocks A` — that transitive-reduction redundancy deliberately cannot see. `communities` clusters the undirected structure with deterministic label propagation (reporting `iterations` and `converged`), `redundancy` finds stored edges implied by a longer path of the same semantic family (`blocked_by`/`blocks` and hierarchy spellings witness each other, each row carrying its witness path), and `dominators` reports the structural bottlenecks of one item's reachable subgraph — nodes every path from the root must pass through, ranked by how much work they gate (`dominated_count`). Three planning and structural analytics complete the surface: `slack` runs the Critical Path Method over the order-bearing DAG and reports each task's earliest start, latest start, total float (`slack`), and whether it is `critical` (zero slack), plus the overall `makespan` and critical path — unit task durations keep it deterministic and metadata-independent, and genuine cycles are reported apart from the schedule; `centrality` ranks nodes by exact shortest-path `betweenness` (Brandes) with Wasserman–Faust `closeness`, undirected `degree`, and dependency fan-in/fan-out (`in_degree`/`out_degree`, ordering predecessors/successors oriented by precedence) over the simple undirected graph; and `articulation` reports the graph's articulation points and bridges — the cut vertices and cut edges whose removal fragments the knowledge graph into more components (single points of failure). `plan` derives a dry-run remediation plan from the audit plus the redundancy scan: exact `remove`/`retype`/`supersede`/`waive`/`investigate` proposals with per-step policy code, evidence, rationale, and confidence — nothing is ever applied automatically and no proposal invents an edge. Every envelope is counts-first with explicit `truncated`, `cost` (visited nodes, inspected edges), and `cache` (workspace fingerprint plus assembly/result hit-or-miss) metadata; repeated identical queries in long-lived hosts such as the MCP server are answered from a fingerprint-keyed snapshot cache that invalidates on any relationship-relevant item change. `--summary` suppresses row collections entirely. `--kind` accepts registered relationship kinds (repeatable or comma-separated) and fails fast on unknown values (`redundancy` additionally requires directed ordering or hierarchy kinds); `--after` resumes hierarchy/ordering walks after a previously returned node id (see [Relationship Graph](RELATIONSHIP_GRAPH.md)).
+
+The audit also reports storage-layer integrity and per-type coverage. `duplicate_dependency_row` (warning on active holders, informational `legacy_duplicate_dependency_row` on terminal ones) catches raw dependency rows whose exact identity — holder, kind, and case-insensitive target — is stored more than once on one item; graph edge-identity dedup hides these from every assembled-graph projection, so the pre-assembly scan is the only surface that can see them. The audit `profile` gains `coverage_by_type`, a per-item-type breakdown of active, isolated, and degree-at-most-one nodes (untyped items bucket under `(untyped)`), and `--exempt-isolate-type <type>` (repeatable or comma-separated, case-insensitive) suppresses isolate/sparse coverage findings for types whose disconnection is policy-valid (reminders, calendar events) while keeping them counted in the profile. `--save-baseline` persists the audit census (`affected_subjects_by_code` plus the profile) as the machine-local comparison point under `.agents/pm/runtime/graph-audit-baseline.json`; every later audit automatically attaches a `baseline` block with the signed drift since that census (`same_snapshot`, per-code deltas, profile deltas including per-kind edge counts) — the temporal primitive for tracking relationship-graph health across sessions without storing full finding collections.
+
+`index` maintains the durable cross-process graph index at `.agents/pm/runtime/graph-cache.json` (gitignored, machine-local): a fingerprint-keyed, atomically written, crash-safe envelope of deterministic query results that lets one-shot CLI invocations reuse analysis computed by earlier processes. Every non-index graph envelope reports `cache.durable` (`hit`, `miss`, or `off`). Persistence is automatic at ≥500 items and otherwise opt-in: `pm graph index` reports status (`fresh`/`stale`/`absent`, entry count, size, thresholds), `pm graph index --rebuild` clears, re-creates, and warms the envelope with the counts-first `analyze`/`audit` census queries (and enables persistence on small workspaces), and `pm graph index --clear` deletes it. The index is never authoritative — any relationship-relevant item change invalidates the fingerprint and queries transparently recompute from item storage.
 
 ## Linked Tests