npm - @unbrained/pm-cli - Versions diffs - 2026.7.21 → 2026.7.22 - Mend

@unbrained/pm-cli 2026.7.21 → 2026.7.22

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (506) hide show

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

	@@ -1 +1 @@
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"}
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 {\n EXIT_CODE,\n ITEM_PROJECT_CONTEXT_KEYS,\n} 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 \"assignee\",\n ...ITEM_PROJECT_CONTEXT_KEYS,\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) => !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":"d482b64e-460e-515c-9dcd-43c6210167d2"}

package/docs/COMMANDS.md CHANGED Viewed

@@ -242,13 +242,21 @@ pm eval --fail-under 0.6 --json      # CI gate: exit non-zero when aggregate nDC
 ### Full results, totals, and bodies
-`pm list*` returns every matched row when neither `--limit` nor `--offset` is set. When a `--limit`/`--offset` _does_ drop rows, the result adds a top-level `total` (the pre-pagination match count) so an agent knows how many remain. Pass `--no-truncate` (alias `--all`) to force the entire matched set and override any `--limit` in one call — the canonical "give me everything" flag for large-corpus audits:
+`pm list*` returns every matched row when neither `--limit` nor `--offset` is set. Every JSON/TOON result has the same pagination envelope: `total` is the pre-pagination match count, `has_more` and `truncated` are booleans, and `next_cursor` is either the continuation token or `null`. The `filters` object omits unset values instead of emitting null placeholders, keeping long-running agent context stable and lean. Pass `--no-truncate` (alias `--all`) to force the entire matched set and override any `--limit` in one call — the canonical "give me everything" flag for large-corpus audits:
 ```bash
 pm list-all --no-truncate --brief          # every matched row, ignoring any --limit
-pm list-open --limit 20 --json             # result.total reports the full count when truncated
+pm list-open --limit 20 --json             # stable total/has_more/truncated/next_cursor envelope
 ```
+Compatibility note: older responses emitted `total` only when pagination
+omitted rows, omitted `next_cursor` on a completed page, and emitted unset
+verbose filter keys as `null`. Integrations should now read `total` as the
+unconditional pre-pagination match count, branch on `has_more` or
+`next_cursor != null`, and test filter-key presence rather than using
+`"total" in result`, `next_cursor !== undefined`, or
+`filters.<key> === null` guards.
 JSON output is compact by default (id/status/type/title) for token efficiency. To pull item bodies in bulk in a single call — instead of one `pm get` per item — add `--include-body`, which expands each row to the full field set plus `body`:
 ```bash
@@ -628,7 +636,7 @@ pm deps <id> --format context --direction both --kind blocked_by,parent --token-
 Linked files and docs keep reviews reproducible. `deps` is read-only and projects item relationships. `--format context` returns one bounded, explainable relationship packet: a counts-first summary, per-node `role`/`via`/`reasons`, root evidence pointers, enumerated `missing_references` with active-versus-legacy classification, `meta.completeness`, and cursor continuation; `--direction`, repeatable or comma-separated `--kind`, `--max-depth`, `--node-limit`, `--edge-limit`, `--token-budget`, and `--cursor` control the traversal (see [Relationship Graph](RELATIONSHIP_GRAPH.md)). `--edge-limit` caps both returned graph edges and enumerated `missing_references`; `missing_reference_count` retains the total when rows are omitted. The standalone `--note <text>` flag annotates every link added by `--add`/`--add-glob` in the same invocation (a per-entry embedded `note=` wins); `--note` without an add is a usage error.
-Structured key/value forms reject unrecognized keys with an `Allowed keys: …` error (matching `test --add`), so a typoed key (`lable=` instead of `label=`) fails fast instead of being silently dropped: `--add`/`--file`/`--doc` accept `path,scope,note`; `--add-glob` accepts `pattern,glob,path,scope,note`; `--remove` accepts `path`; `--migrate` accepts `from,to`; `--dep` accepts `id,kind,type,author,created_at` (plus `source_kind` on update); `--reminder` accepts `at,date,text,title`; `--event` accepts `start,date,end,duration,title,description,location,timezone,all_day` and the `recur_*` recurrence keys. Bare values (`--add src/cli/main.ts`) skip key validation.
+Structured key/value forms reject unrecognized keys with an `Allowed keys: …` error (matching `test --add`), so a typoed key (`lable=` instead of `label=`) fails fast instead of being silently dropped: `--add`/`--file`/`--doc` accept `path,scope,note`; `--add-glob` accepts `pattern,glob,path,scope,note`; `--remove` accepts `path`; `--migrate` accepts `from,to`; create/update `--dep` accepts `id,kind,type,author,created_at,source_kind`; `--reminder` accepts `at,date,text,title`; `--event` accepts `start,date,end,duration,title,description,location,timezone,all_day` and the `recur_*` recurrence keys. Set `source_kind=global` for a dependency owned by another workspace: pm preserves its id verbatim, materializes it as an external graph endpoint, and excludes it from dangling-local-reference findings. Dependencies without that explicit provenance retain normal local `id_prefix` normalization. Bare values (`--add src/cli/main.ts`) skip key validation.
 ## Graph Queries
@@ -814,6 +822,21 @@ When more than one history stream is drifted, the `history_drift` remediation co
 ## History and Recovery
+After a branch merge that touched tracker history, preview and apply the
+one-command reconciliation gate:
+```bash
+pm merge reconcile --dry-run --json
+pm merge reconcile --message "Reconcile branch histories" --json
+```
+The command scans every history stream, delegates repairs to the audited
+`history-repair --all` engine, then runs the history-drift and storage-integrity
+validation checks. Dry-run leaves drift intact and reports it in `validation`;
+apply exits nonzero if any stream fails or either invariant stays red. No Git
+hook is installed automatically—teams may call this command from an explicit
+post-merge hook after opting into that policy.
 ```bash
 pm history <id> --limit 20
 pm history <id> --diff

package/docs/CONFIGURATION.md CHANGED Viewed

@@ -50,7 +50,7 @@ Precedence:
 4. global settings
 5. built-in defaults
-When `settings.json` cannot be loaded, `pm` falls back to built-in defaults and prints a one-time `settings_read_invalid_json` or `settings_read_invalid_schema` warning to stderr (stdout output is unchanged); run `pm health` for remediation.
+When `settings.json` cannot be loaded, `pm` falls back to built-in defaults and prints a one-time `settings_read_fs_error`, `settings_read_invalid_json`, or `settings_read_invalid_schema` warning to stderr (stdout output is unchanged); run `pm health` for remediation.
 ## Common Settings

package/docs/MERGE_SAFETY.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # Multi-Branch Tracker Merge Safety
-Tracked by [pm-wc1r](../.agents/pm/features/pm-wc1r.toon), with the integrity and concurrency fixes [pm-9q2t](../.agents/pm/issues/pm-9q2t.toon), [pm-cxyv](../.agents/pm/issues/pm-cxyv.toon), [pm-gpo7](../.agents/pm/issues/pm-gpo7.toon), [pm-m3nl](../.agents/pm/issues/pm-m3nl.toon), [pm-wwfd](../.agents/pm/issues/pm-wwfd.toon), and [pm-xdn6](../.agents/pm/issues/pm-xdn6.toon). Fence-coverage completeness and drift detection are tracked by [pm-i4fx](../.agents/pm/issues/pm-i4fx.toon); cross-branch id collision safety by [pm-pibw](../.agents/pm/issues/pm-pibw.toon); this repository's own adoption by [pm-iwsj](../.agents/pm/chores/pm-iwsj.toon).
+Tracked by [pm-wc1r](../.agents/pm/features/pm-wc1r.toon), with the integrity and concurrency fixes [pm-9q2t](../.agents/pm/issues/pm-9q2t.toon), [pm-cxyv](../.agents/pm/issues/pm-cxyv.toon), [pm-gpo7](../.agents/pm/issues/pm-gpo7.toon), [pm-m3nl](../.agents/pm/issues/pm-m3nl.toon), [pm-wwfd](../.agents/pm/issues/pm-wwfd.toon), and [pm-xdn6](../.agents/pm/issues/pm-xdn6.toon). Fence-coverage completeness and drift detection are tracked by [pm-i4fx](../.agents/pm/issues/pm-i4fx.toon); cross-branch id collision safety by [pm-pibw](../.agents/pm/issues/pm-pibw.toon); post-merge reconciliation by [pm-mfkv92](../.agents/pm/issues/pm-mfkv92.toon); this repository's own adoption by [pm-iwsj](../.agents/pm/chores/pm-iwsj.toon).
 pm stores project context as reviewable repository files. Concurrent agents can therefore use ordinary branches and worktrees, but tracker artifacts need semantic merge behavior: raw line merging cannot preserve TOON collection counts, JSON object structure, or append-only history hash chains.
@@ -16,6 +16,8 @@ git commit -m "chore(pm): install tracker merge drivers"
 `pm merge install` writes an idempotent, fenced `.gitattributes` block and repository-local `git config` entries. The attributes are committed; the driver commands are clone-local, so every collaborator and fresh CI clone that performs merges must run the install command.
+The installer publishes the shared `.gitattributes` fence only after the clone-local driver commands are configured. If the repository Git config is read-only or another Git process holds its lock, the command returns the stable `merge_git_config_unwritable` error with recovery guidance and leaves an absent fence absent. Use `pm merge install --dry-run --json` to inspect the contract in intentionally read-only workspaces.
 ### Fence coverage contract
 The fenced block is generated by one shared coverage contract (`buildMergeAttributePatterns`) covering every mergeable artifact class: per-type item folders (`*.toon`/`*.md`), all tracker `**/*.jsonl` paths under the relationship-event driver with the more-specific `history/*.jsonl` rule overriding history streams, `settings.json`, and `schema/*.json`. The broad JSONL rule is required because `RelationshipEventStore` supports package-owned custom relative paths anywhere below the tracker root. Two mechanisms keep the committed fence from drifting out of that contract:
@@ -40,7 +42,7 @@ pm merge install --dry-run --json
 When both sides change the same scalar or JSON leaf differently, the driver writes a parseable preferred-side result but exits nonzero. Git keeps the path conflicted so a human or coordinating agent must review the losing value and explicitly `git add` the resolution. Use `--prefer theirs` only when that is the intended resolution policy.
-The underlying public SDK exports are `mergeItemDocuments`, `mergeHistoryStreams`, `mergeRelationshipEventStreams`, `mergeJsonDocuments`, `runMergeDriver`, `runMergeInstall`, `refreshMergeAttributeFenceIfInstalled`, `buildMergeAttributePatterns`, and `auditMergeAttributeFence` from `@unbrained/pm-cli/sdk`. Hosts can embed the same semantics without shelling out.
+The underlying public SDK exports are `mergeItemDocuments`, `mergeHistoryStreams`, `mergeRelationshipEventStreams`, `mergeJsonDocuments`, `runMergeDriver`, `runMergeInstall`, `runMergeReconcile`, `refreshMergeAttributeFenceIfInstalled`, `buildMergeAttributePatterns`, and `auditMergeAttributeFence` from `@unbrained/pm-cli/sdk`. Hosts can embed the same semantics without shelling out.
 ## Cross-branch id collision safety
@@ -54,10 +56,17 @@ Item ids are `<prefix>` plus random base36 characters, and uniqueness is only pr
 After every branch merge that touches `.agents/pm`, run:
 ```bash
-pm validate --check-history-drift --strict-exit
-pm history <item-id> --verify --strict-exit
+pm merge reconcile --dry-run --json
+pm merge reconcile --message "Reconcile merged tracker histories" --json
 ```
+The preview reports every drifted stream without mutation. The apply pass uses
+the audited bulk history-repair engine and immediately validates history drift
+plus storage integrity; it exits nonzero when a stream cannot be repaired or an
+invariant remains red. Clean workspaces are a successful no-op. Default Git
+hooks remain unchanged: repositories that want automatic enforcement must opt
+in by invoking this command from their own post-merge hook.
 The default validation surface includes `storage_integrity`. It fails on unreadable item documents, history conflict markers, malformed history tails, live items whose latest history operation is `delete` (a delete/modify resurrection candidate), and unparseable settings/schema files. This prevents the ordinary tolerant read path from turning corruption into a green gate.
 A history union can be structurally valid while replayed history and the chosen item document describe different effective state. In that case inspect both authors' events before reconciliation, then run the audited repair:
@@ -66,7 +75,7 @@ A history union can be structurally valid while replayed history and the chosen
 pm history <item-id> --verify --strict-exit
 pm history-repair <item-id> --dry-run
 pm history-repair <item-id>
-pm validate --check-history-drift --strict-exit
+pm merge reconcile --dry-run --json
 ```
 `history-repair` records the reconciliation patch and surfaces discarded event authors/operations when the on-disk document would otherwise revert effective merged history. Re-apply any intended losing mutation as a normal `pm update` so it remains explicit and auditable.

package/docs/PERFORMANCE.md CHANGED Viewed

@@ -38,6 +38,34 @@ pnpm benchmark:scale --items ci --iterations 3 --transport both --check
 The JSON report records fixture generation time plus one excluded warmup observation and measured p50/p95/min/max latency, peak RSS on Linux, output bytes, and estimated tokens for `list`, `get`, `next`, `context`, `search`, `create`, and `claim`. The warmup exposes initial index-build cost while regression percentiles measure the continuously warm derived-index contract across real cold CLI processes and in-process SDK calls. Run the committed local regression check with `pnpm benchmark:scale:check`. GitHub-hosted runners do not execute the scale suite, which keeps expensive performance work off Actions and avoids consuming hosted-runner capacity.
+The metadata read cache is rebuildable derived state. Workspaces with at least
+500 indexed items use its directory-validated fast path to avoid per-item
+stats; validation and recovery can force a canonical source scan. Every
+metadata, body, and collection tier carries one `source_cursor`. A small
+manifest exposes the base cursor and item count without parsing the full index.
+A supported create, update, move, or delete acquires the cross-process
+derived-index writer lock before the authoritative item commit and atomically
+publishes one collapsed delta containing every compatible tier projection,
+directory signatures, and the next cursor before releasing the lock. Mutation
+cost therefore follows changed items rather than total workspace size. A torn,
+corrupt, or base-mismatched delta is rejected and rebuilt from source.
+SDK hosts that commit authoritative item documents outside the stock mutation
+commands use `acquireItemMetadataDerivedIndexLock` and
+`refreshItemMetadataDerivedIndex` from `@unbrained/pm-cli/sdk` around the same
+commit boundary. Repeated writes collapse by item path in the delta instead of
+growing an event log; a later source scan compacts the projection into fresh
+base tiers. Projection failure removes the rebuildable tiers, delta, and
+manifest and returns a warning; it never rolls back or outranks the
+authoritative item/history write. Small workspaces without an active index
+receive a no-op release function and retain direct external-edit detection.
+Context-signal snapshots follow the same rule: they are versioned and
+cursor-stamped, never authoritative, and rebuild from the metadata index or
+source-scan fallback when missing, stale, or corrupt. SDK hosts can persist
+that layer with `ContextSignalStore` while retaining explicit `fresh`/`rebuilt`
+and `derived_index`/`scan_fallback` diagnostics.
 To refresh a baseline after an intentional, measured improvement:
 ```bash

package/docs/RELATIONSHIP_GRAPH.md CHANGED Viewed

@@ -28,8 +28,14 @@ Hierarchy kinds likewise declare which endpoint is the structural parent. `sourc
 `RelationshipEventStore` is the built-in durable filesystem adapter. It stores validated JSONL at `.agents/pm/relationships/events.jsonl` by default, replays every row through the same registry and cardinality checks on open, and serializes cross-process appends with the tracker lock. Async `currentVersion()`, `snapshot()`, and `page()` reads take the same lock before refreshing, so long-lived readers observe completed appends without torn JSONL tails. Store paths must stay lexically inside a non-symlinked tracker root and cannot traverse symlinked components. Database, replicated-log, and event-bus adapters can persist the same public events and rebuild the same snapshots.
+`appendBatch(inputs)` is the migration/import path. It refreshes under the writer lock, validates every event against one evolving in-memory view, and publishes the complete JSONL replacement with one atomic rename. A validation or write failure leaves the prior stream byte-for-byte unchanged. The ordinary `append(input)` remains the low-latency single-event path and retains its append-only write. `existingEventPolicy: "skip_identical"` makes deterministic migrations resumable across processes: an existing event id is skipped only when its relationship id, action, canonical edge, author, timestamp, and reason are identical; a same-id/different-content collision fails closed.
 ```ts
-import { RelationshipEventLog, RelationshipEventStore } from "@unbrained/pm-cli/sdk";
+import {
+  RelationshipEventLog,
+  RelationshipEventStore,
+  planRelationshipEventBackfill,
+} from "@unbrained/pm-cli/sdk";
 const history = new RelationshipEventLog(["design", "build", "ship"]);
 history.append({
@@ -57,6 +63,30 @@ await durable.append({
   author: "release-agent",
   timestamp: new Date().toISOString(),
 });
+const legacyItems = [
+  { id: "design", title: "Design", status: "closed" as const },
+  {
+    id: "build",
+    title: "Build",
+    status: "open" as const,
+    parent: "design",
+    dependencies: [{ id: "design", kind: "blocked_by" }],
+  },
+];
+const migration = planRelationshipEventBackfill(legacyItems, {
+  migrationId: "legacy-items-v1",
+  author: "migration-agent",
+  timestamp: "2026-07-21T20:45:00.000Z",
+});
+const migrationStore = await RelationshipEventStore.open({
+  pmRoot: ".agents/pm",
+  nodes: migration.nodes,
+  relativePath: "relationships/legacy-items-v1.jsonl",
+});
+await migrationStore.appendBatch(migration.events, {
+  existingEventPolicy: "skip_identical",
+});
 ```
 ## Explainable analytics
@@ -232,6 +262,18 @@ every entry rebuilds from item storage on fingerprint mismatch, and
 envelopes report the `cache.durable` disposition. Ids resolve
 case-insensitively; `--summary` returns envelopes without row collections.
+The graph fingerprint consumes the item-metadata-derived index, whose metadata,
+body, and collection tiers plus collapsed mutation delta publish one effective
+source cursor. Supported item mutations serialize authoritative writes with a
+bounded derived-index projection, so a long-lived SDK host or later CLI process
+observes the committed relationship fields without paying for a full source
+scan or rewriting the whole index. Cursor disagreement, an invalid projection
+path, or any refresh failure invalidates the rebuildable base/delta state; the
+next graph read source-scans and reconstructs both indexes. Package-owned
+storage adapters can preserve this contract with the public
+`acquireItemMetadataDerivedIndexLock` and
+`refreshItemMetadataDerivedIndex` SDK primitives.
 Mutation advisories reuse the same cycle semantics incrementally:
 `collectNewOrderingCycleWarnings` builds a lightweight ordering digraph
 directly from the before/after item snapshots (no full workspace assembly)
@@ -243,6 +285,10 @@ longer paying two whole-graph SCC analyses per dependency-bearing mutation.
 Aliases normalize at registry boundaries; stored values are not silently rewritten. Imports must carry or select a compatible registry version. Federation merges definitions before edges and rejects identifier or alias collisions. Rollback removes the custom definition and its derived index only after application-owned edges have been exported or superseded; immutable history is retained.
+`planRelationshipEventBackfill(items, options)` is the side-effect-free bridge from legacy item `parent`, scalar `blocked_by`, and structured `dependencies` fields to the event platform. It uses the same workspace assembly and registry semantics as graph queries, so custom kinds, aliases, external targets, case normalization, duplicate-row governance, and explicit missing-target placeholders cannot drift between migration and reads. Input order does not affect the SHA-256 plan fingerprint, deterministic event ids, relationship ids, node universe, or event order. The plan reports total normalized edges, raw duplicate dependency groups, dangling internal references, and ids skipped through `existingEventIds` before any write occurs.
+For a resumable migration, keep `migrationId`, `author`, and `timestamp` stable, inspect the plan evidence, open the store with `plan.nodes`, and publish with `appendBatch(..., { existingEventPolicy: "skip_identical" })`. Changing semantic input under the same migration id intentionally produces an event-id collision instead of silently rewriting history. A plan is not an authority transfer: legacy item/history files remain authoritative until the application explicitly switches its read adapter and records that cutover.
 Validation rejects missing endpoints, disallowed self-edges, cardinality violations at mutation boundaries, ordering-only cycles, and incompatible aliases or versions. Immutable graph snapshots deduplicate canonical edges deterministically, retaining the last supplied edge; mutation boundaries may reject duplicates before snapshot construction. Evidence freshness and application payload schemas are extension policy: the core preserves payloads but does not invent domain meaning.
 ## Consequences and non-goals

package/docs/SDK.md CHANGED Viewed

@@ -64,6 +64,7 @@ Source of truth:
 - [`src/sdk/graph/run.ts`](../src/sdk/graph/run.ts)
 - [`src/sdk/relationship-history.ts`](../src/sdk/relationship-history.ts)
 - [`src/sdk/relationship-context.ts`](../src/sdk/relationship-context.ts)
+- [`src/sdk/context-signal-store.ts`](../src/sdk/context-signal-store.ts)
 - [`src/sdk/governance/validate.ts`](../src/sdk/governance/validate.ts)
 - [`src/sdk/governance/health.ts`](../src/sdk/governance/health.ts)
 - [`src/sdk/governance/gc.ts`](../src/sdk/governance/gc.ts)
@@ -161,8 +162,8 @@ Command/action contract exports:
 - `PmClient` / `runAction` (high-level in-process action execution for custom tools, bots, CI, and embedded runtimes)
 - Typed read primitives on `PmClient`: `get` (including `GetOptions.at` point-in-time reads), `list`, `search`, `context`, `next`, `aggregate`, and `stats`; direct `getItemAt` reconstructs a canonical historical document without mutation
 - Read primitive option/result contracts: `GetOptions` / `GetResult`, `ListOptions` / `ListResult`, `SearchOptions` / `SearchResult`, `ContextOptions` / `ContextResult`, `NextOptions` / `NextResult`, `AggregateOptions` / `AggregateResult`, `StatsCommandOptions` / `StatsResult`
-- Context relevance primitives: `buildItemContextRelevanceCandidates`, `defaultScoreContextCandidates`, `scoreContextCandidates`, `scoreContextCandidatesWithActiveExtensions`, `evaluateContextRanking`, `runContextEvaluationScenario`, `runContextEvaluationCorpus`, and `summarizeContextEvaluationReports`
-- Context relevance contracts: `ContextRelevanceCandidate`, `ContextRelevanceSignals`, `ContextRelevanceScorer`, `ContextRelevanceReport`, `ContextEvaluationReader`, `ContextEvaluationScenario`, `ContextEvaluationScenarioReport`, `ContextEvaluationThresholds`, and `ContextEvaluationCorpusReport`
+- Context relevance primitives: `buildItemContextRelevanceCandidates`, `buildContextSignalSnapshot`, `ContextSignalStore`, `JsonFileContextSignalStoreAdapter`, `parseContextSignalSnapshot`, `defaultScoreContextCandidates`, `scoreContextCandidates`, `scoreContextCandidatesWithActiveExtensions`, `evaluateContextRanking`, `runContextEvaluationScenario`, `runContextEvaluationCorpus`, and `summarizeContextEvaluationReports`
+- Context relevance contracts: `ContextRelevanceCandidate`, `ContextRelevanceSignals`, `ContextSignalSnapshot`, `ContextSignalStoreAdapter`, `ContextSignalStoreReadResult`, `ContextRelevanceScorer`, `ContextRelevanceReport`, `ContextEvaluationReader`, `ContextEvaluationScenario`, `ContextEvaluationScenarioReport`, `ContextEvaluationThresholds`, and `ContextEvaluationCorpusReport`
 - Context packing and feedback primitives: `packContextCandidates`, `recordContextUsageServing`, `recordContextUsageTouch`, `recordContextUsageTouches`, and `readContextUsageAffinity`
 - Typed annotation and relationship primitives on `PmClient`: `comments`, `notes`, `learnings`, `files`, `filesDiscover`, `docs`, `deps`, `graph`, and `append`
 - Workspace graph-query runner: `runGraph` (with `GraphCommandOptions`, `GraphResult`, and per-subcommand envelopes) resolves the workspace relationship graph through the shared fingerprint-keyed cache and dispatches bounded `ancestors`/`descendants`/`predecessors`/`successors`/`paths`/`impact`/`analyze`/`audit`/`communities`/`redundancy`/`dominators`/`slack`/`centrality`/`articulation`/`plan` queries with counts-first cost, truncation, and cache metadata; the `pm graph` CLI command and `pm_graph` MCP tool are thin adapters over it.
@@ -179,9 +180,11 @@ Command/action contract exports:
 - Linked-resource kernel primitives: `runFiles`, `runFilesDiscover`, `runDocs`, `runDeps`, `runLinkedArtifacts`, parsing/normalization/path-validation helpers, and their typed contracts. The CLI files/docs/deps modules are presentation-only re-exports of these SDK implementations.
 - Actionability primitives: `collectBlockedByIds`, `resolveItemBlockers`, `collectDependencyBlockedIds`, and `computeActionabilityReport` expose the same edge-aware blocked/ready definition used by `pm next`, `pm context`, and `pm list-blocked`. Embedded schedulers can therefore classify custom lifecycle schemas without importing CLI or core modules.
 - Dependency-governance primitives: `collectDanglingDependencyReferences`, `collectMissingDependencyTargetIds`, and `assembleWorkspaceRelationshipGraph` normalize hierarchy, scalar blockers, and structured dependencies into one graph while partitioning missing targets into actionable active holders, informational terminal-history holders, and the legacy `no-active-blocker` sentinel without mutating stored history.
-- Relationship graph primitives: `RelationshipKindRegistry`, `createRelationshipKindRegistry`, `RelationshipGraph`, `RelationshipEventLog`, `RelationshipEventStore`, `buildRelationshipContext`, `buildDepsRelationshipContext`, `hierarchyAncestors`, `hierarchyDescendants`, `orderingPredecessors`, `orderingSuccessors`, `enumerateRelationshipPaths`, `auditWorkspaceRelationshipGraph`, `isOrderingRelationshipKind`, and `dependencyToRelationship` provide application-defined edge semantics, durable replay, bounded semantic traversal, policy-aware governance, and explainable context queries. `RelationshipEventLog.stream/project` and their durable-store equivalents page immutable prefixes and fold them into deterministic application state with exact version, processed-count, and as-of metadata. See [Relationship graph semantics](RELATIONSHIP_GRAPH.md).
+- Relationship graph primitives: `RelationshipKindRegistry`, `createRelationshipKindRegistry`, `RelationshipGraph`, `RelationshipEventLog`, `RelationshipEventStore`, `planRelationshipEventBackfill`, `buildRelationshipContext`, `buildDepsRelationshipContext`, `hierarchyAncestors`, `hierarchyDescendants`, `orderingPredecessors`, `orderingSuccessors`, `enumerateRelationshipPaths`, `auditWorkspaceRelationshipGraph`, `isOrderingRelationshipKind`, and `dependencyToRelationship` provide application-defined edge semantics, durable replay, deterministic legacy migration, bounded semantic traversal, policy-aware governance, and explainable context queries. `RelationshipEventLog.stream/project` and their durable-store equivalents page immutable prefixes and fold them into deterministic application state with exact version, processed-count, and as-of metadata. `RelationshipEventStore.appendBatch` validates a complete import under one cross-process lock and atomically publishes it; `skip_identical` resume mode rejects same-id semantic collisions. See [Relationship graph semantics](RELATIONSHIP_GRAPH.md).
 - Atomic application transactions: `commitWorkspaceTransaction` coordinates ordered, idempotent item and relationship mutations under one workspace writer lock and a durable replay journal. Interrupted work resumes from step inspection; ordinary failures append reverse-order compensations without rewriting immutable histories.
-- Multi-branch merge primitives: `mergeItemDocuments`, `mergeHistoryStreams`, `mergeRelationshipEventStreams`, `mergeJsonDocuments`, `runMergeDriver`, and `runMergeInstall` provide the same field-aware item, hash-chain-preserving history, sequence-renumbering relationship-event, and key-level configuration semantics as `pm merge`; `buildMergeAttributePatterns`, `refreshMergeAttributeFenceIfInstalled`, and `auditMergeAttributeFence` expose the fence coverage contract, the post-schema-mutation refresh, and the validate-side drift audit. See [Multi-Branch Merge Safety](MERGE_SAFETY.md).
+- Multi-branch merge primitives: `mergeItemDocuments`, `mergeHistoryStreams`, `mergeRelationshipEventStreams`, `mergeJsonDocuments`, `runMergeDriver`, `runMergeInstall`, and `runMergeReconcile` provide the same field-aware item, hash-chain-preserving history, sequence-renumbering relationship-event, key-level configuration, and audited post-merge repair-and-verify semantics as `pm merge`; `buildMergeAttributePatterns`, `refreshMergeAttributeFenceIfInstalled`, and `auditMergeAttributeFence` expose the fence coverage contract, the post-schema-mutation refresh, and the validate-side drift audit. See [Multi-Branch Merge Safety](MERGE_SAFETY.md).
+- Dependency provenance primitives: `EXTERNAL_DEPENDENCY_SOURCE_KIND`, `isExternalDependencySourceKind`, and `normalizeDependencySeedId` let custom importers preserve cross-workspace dependency ids explicitly while retaining local prefix normalization for ordinary seeds.
+- Compile-cache lifecycle primitive: `pruneCompileCacheGenerations` bounds pm-owned Node bytecode caches to the current package generation; embedded hosts can apply the same upgrade cleanup without importing the executable entrypoint.
 - Typed mutation inputs (pm-x29o / GH-601): `PmCreateActionOptions`, `PmUpdateActionOptions`, and `PmCloseActionOptions` (`PmClientCloseActionOptions` on the client method) strip the permissive custom-field index signature from the executable command-option contracts, retaining their exact public keys and value types without a second hand-written shape; the free `create`/`update`/`close` functions and `PmClient` methods share those types. `PmUpdateManyActionOptions`, `PmCloseManyActionOptions`, and `OptionsFromContracts` cover flat action-contract composition. Field typos, object values, invalid scalar kinds, and MCP-only aliases on a `PmClient` command-option bag fail `tsc` under strict. Runtime-schema custom fields use the repeatable `field` option and `PmClient.run` remains the wide escape hatch. Projected list rows expose the typed `ListProjectedItemCore` fields (`row.id` is `string | undefined`, never `unknown`).
 - Typed customization primitives on `PmClient`: `init`, `config`, `schema`, `schemaList`, `schemaShow`, `schemaAddType`, `schemaRemoveType`, `schemaAddStatus`, `schemaRemoveStatus`, `schemaAddField`, `schemaRemoveField`, `schemaListFields`, `schemaShowField`, `schemaApplyPreset`, `schemaInferTypes`, `schemaShowStatus`, `profile`, `profileList`, `profileShow`, `profileApply`, and `profileLint`
 - Workspace-scaffold primitives: `ensurePmGitignore` and `getPmGitignoreBlock` let custom tools apply the same idempotent runtime/search cache policy as `pm init` without importing CLI internals.
@@ -1081,12 +1084,24 @@ the SDK search engine directly. Package authors can import these functions and
 their typed result contracts from `@unbrained/pm-cli/sdk` without importing CLI
 implementation modules.
-List result rows are modeled by projection: `ListFullResult` contains complete
+List results always expose `total`, `has_more`, `truncated`, and a nullable
+`next_cursor`, whether or not the page was truncated; unset filter echoes are
+omitted. This stable, lean envelope lets agents plan continuation without
+branching on key presence. Result rows are modeled by projection:
+`ListFullResult` contains complete
 `ListedItem` records, tree ordering may enrich them with `ListTreeMetadata`, and
 compact or `fields` projections return `ListProjectedItem` dictionaries. Use
 `full: true` when an integration requires complete item metadata; the overload
 then returns `ListFullResult` without an assertion or cast.
+Migration note: before this contract, `total` was present only when pagination
+omitted rows, a completed page omitted `next_cursor`, and verbose results
+emitted unset filter keys with `null` values. Consumers must use `has_more` or
+`next_cursor != null` for continuation, read `total` as the unconditional
+pre-pagination match count, and use key presence for filter diagnostics;
+`"total" in result`, strict `next_cursor !== undefined`, and
+`filters.<key> === null` checks do not express the stable envelope semantics.
 ### Execution and diagnostics
 Tracked by [pm-oslr](../.agents/pm/features/pm-oslr.toon) and the SDK boundary
@@ -1153,6 +1168,8 @@ compact rounded report metrics for stable machine output.
 Tracked by [pm-4k6b](../.agents/pm/features/pm-4k6b.toon),
 [pm-h3no](../.agents/pm/tasks/pm-h3no.toon),
+[pm-3hps](../.agents/pm/tasks/pm-3hps.toon),
+[pm-801d](../.agents/pm/features/pm-801d.toon),
 [pm-atfm](../.agents/pm/features/pm-atfm.toon), and
 [pm-qyc6](../.agents/pm/issues/pm-qyc6.toon).
@@ -1168,6 +1185,57 @@ throwing override degrades to the deterministic default and emits an
 `extension_context_relevance_invalid_result` warning instead of breaking the
 read path.
+For persistent derived signals, use `ContextSignalStore` with a caller-owned
+`ContextSignalStoreAdapter`, or use `JsonFileContextSignalStoreAdapter` for a
+same-directory atomic JSON snapshot. Each snapshot carries both a
+`format_version` and `signal_set_version`, the authoritative history or index
+`source_cursor`, the stable caller clock, and whether its items came from the
+`derived_index` or `scan_fallback` path. Item rows are deterministic and sorted;
+the snapshot never replaces item or history data.
+`readOrRebuild(items, options)` reuses a snapshot only when the cursor and
+complete item-id set match. Missing, stale, version-incompatible, or corrupt
+state is rebuilt from the authoritative items and atomically replaced. The
+result reports `cache_status` and non-fatal `context_signal_store_stale`,
+`context_signal_store_invalid`, or `context_signal_store_write_failed`
+warnings. A write failure still serves the in-memory rebuilt candidates because
+the snapshot is derived, never authoritative. Optional maps for activity density,
+graph proximity, claim/focus, knowledge density, author affinity, usage
+affinity, and semantic similarity let an index or application-specific host
+supply richer signals without changing the canonical scorer contract.
+```ts
+import {
+  ContextSignalStore,
+  JsonFileContextSignalStoreAdapter,
+  readSettings,
+  resolvePmRoot,
+  resolveRuntimeStatusRegistry,
+  scoreContextCandidates,
+} from "@unbrained/pm-cli/sdk";
+const pmRoot = resolvePmRoot(process.cwd());
+const statusRegistry = resolveRuntimeStatusRegistry(
+  (await readSettings(pmRoot)).schema,
+);
+const store = new ContextSignalStore(
+  new JsonFileContextSignalStoreAdapter(
+    ".agents/pm/runtime/context-signals.json",
+  ),
+);
+const signalRead = await store.readOrRebuild(itemsFromDerivedIndex, {
+  statusRegistry,
+  now: "2026-07-21T12:00:00.000Z",
+  source: "derived_index",
+  sourceCursor: historyCursor,
+  activityDensity,
+  graphProximity,
+  semanticSimilarity,
+});
+const report = await scoreContextCandidates(signalRead.candidates);
+```
 Use `--explain-ranking --json` on `pm context` or `pm next` to include the model,
 available signals, baseline rank, final rank, score, and per-signal
 contributions. Explanation data is opt-in so default agent output stays bounded.
@@ -2486,6 +2554,11 @@ By default the auto-created command only has a handler. Pass an optional third
 description, flags, intent, examples, failure hints, and positional arguments —
 surfaced in `--help` and runtime contracts exactly like `registerCommand`:
+When a package also registers a rich canonical nested command such as
+`csv export`, the compatible flattened adapter path (`csv-export export`)
+inherits that canonical description, arguments, and flags. Both help surfaces
+and option parsing therefore stay identical without duplicating metadata.
 ```ts
 import { defineExtension } from "@unbrained/pm-cli/sdk";

package/marketplace.json CHANGED Viewed

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
-    "version": "2026.7.21"
+    "version": "2026.7.22"
   },
   "plugins": [
     {
       "name": "pm-claude",
       "source": "./plugins/pm-claude",
       "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
-      "version": "2026.7.21",
+      "version": "2026.7.22",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.7.21",
+  "version": "2026.7.22",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -80,7 +80,7 @@
     "lint:complexity:baseline": "eslint . --suppress-rule complexity --suppress-rule sonarjs/cognitive-complexity",
     "lint:duplicates": "jscpd --config .jscpd.json",
     "lint:codefactor": "pnpm quality:static",
-    "quality:static": "pnpm build && pnpm exec tsx scripts/release/static-quality-gate.mts --max-eslint-suppressions 154 --max-coverage-ignore-pragmas 477 --min-docstring-coverage 100 --min-exported-docstring-coverage 100 --min-member-docstring-coverage 100 && node scripts/release/audit-package-boundary.mjs && node scripts/release/token-budget-gate.mjs",
+    "quality:static": "pnpm build && pnpm exec tsx scripts/release/static-quality-gate.mts --max-eslint-suppressions 150 --max-coverage-ignore-pragmas 477 --min-docstring-coverage 100 --min-exported-docstring-coverage 100 --min-member-docstring-coverage 100 && node scripts/release/audit-package-boundary.mjs && node scripts/release/token-budget-gate.mjs",
     "quality:token-budget": "node scripts/release/token-budget-gate.mjs",
     "quality:context-eval": "node scripts/release/context-eval-gate.mjs",
     "quality:docs-skills": "node scripts/release/docs-skills-gate.mjs",

package/packages/pm-beads/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-beads",
-  "version": "2026.7.21",
+  "version": "2026.7.22",
   "private": true,
   "type": "module",
   "description": "First-party pm package for importing Beads JSONL records.",

package/packages/pm-calendar/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-calendar",
-  "version": "2026.7.21",
+  "version": "2026.7.22",
   "private": true,
   "type": "module",
   "description": "First-party pm package for calendar and agenda views.",

package/packages/pm-command-kit/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-command-kit",
-  "version": "2026.7.21",
+  "version": "2026.7.22",
   "private": true,
   "type": "module",
   "description": "First-party pm exemplar package for the commands capability: registerCommand, registerFlags, and registerParser.",

package/packages/pm-governance-audit/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-governance-audit",
-  "version": "2026.7.21",
+  "version": "2026.7.22",
   "private": true,
   "type": "module",
   "description": "First-party pm package for governance audit and normalization workflows.",