@unbrained/pm-cli 2026.7.3 → 2026.7.5

package/dist/core/history/history-rewrite.d.ts

@@ -2,6 +2,7 @@ import type { ItemTypeRegistry } from "../item/type-registry.js";
 import { locateItem, readLocatedItem } from "../store/item-store.js";
 import type { ItemDocument, PmSettings } from "../../types/index.js";
 type LoadedItem = Awaited<ReturnType<typeof readLocatedItem>>;
+type HistoryRawWriter = (filePath: string, content: string) => Promise<void>;
 /**
  * Documents the history rewrite subject payload exchanged by command, SDK, and package integrations.
  */
@@ -70,6 +71,15 @@ export interface ExecuteHistoryRewriteParams {
     applyRewrite: (verified: VerifiedHistoryRewriteState) => Promise<void>;
     applyPostRewrite?: (verified: VerifiedHistoryRewriteState) => Promise<string[]>;
 }
+/**
+ * Writes the rewritten history stream and restores the under-lock snapshot on failure.
+ */
+export declare function writeHistoryRawWithRollback(params: {
+    historyPath: string;
+    nextHistoryRaw: string;
+    historyRawUnderLock: string | null;
+    writeHistoryRaw?: HistoryRawWriter;
+}): Promise<void>;
 /**
  * Shared lock/verify/ownership orchestration for history-rewrite commands.
  * Callers provide the operation-specific write/rollback logic and optional

package/dist/core/history/history-rewrite.js

@@ -4,8 +4,9 @@
  * Implements append-only history and replay behavior for History Rewrite.
  */
 
-!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]="665cdb28-cf61-56a3-a037-708d2445359d")}catch(e){}}();
-import { readFileIfExists } from "../fs/fs-utils.js";
+!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]="b9f14848-6edc-507a-a543-7bf01d91db50")}catch(e){}}();
+import fs from "node:fs/promises";
+import { readFileIfExists, writeFileAtomic } from "../fs/fs-utils.js";
 import { acquireLock } from "../lock/lock.js";
 import { EXIT_CODE } from "../shared/constants.js";
 import { PmCliError } from "../shared/errors.js";
@@ -50,6 +51,29 @@ export async function verifyHistoryRewriteNoDrift(params) {
     }
     return { historyRawUnderLock, locatedUnderLock, loadedItemUnderLock };
 }
+/**
+ * Writes the rewritten history stream and restores the under-lock snapshot on failure.
+ */
+export async function writeHistoryRawWithRollback(params) {
+    const writeHistoryRaw = params.writeHistoryRaw ?? writeFileAtomic;
+    try {
+        await writeHistoryRaw(params.historyPath, params.nextHistoryRaw);
+    }
+    catch (error) {
+        try {
+            if (params.historyRawUnderLock === null) {
+                await fs.rm(params.historyPath, { force: true });
+            }
+            else {
+                await writeHistoryRaw(params.historyPath, params.historyRawUnderLock);
+            }
+        }
+        catch (rollbackError) {
+            throw new AggregateError([error, rollbackError], `History rewrite failed and rollback also failed: ${String(error)}`);
+        }
+        throw error;
+    }
+}
 /**
  * Shared lock/verify/ownership orchestration for history-rewrite commands.
  * Callers provide the operation-specific write/rollback logic and optional
@@ -64,7 +88,7 @@ export async function executeHistoryRewrite(params) {
             force: params.force,
             settings: params.settings,
         })];
-    const releaseLock = await acquireLock(params.pmRoot, params.subject.id, params.settings.locks.ttl_seconds, params.author, Boolean(params.force), params.settings.governance.force_required_for_stale_lock);
+    const releaseLock = await acquireLock(params.pmRoot, params.subject.id, params.settings.locks.ttl_seconds, params.author, Boolean(params.force), params.settings.governance.force_required_for_stale_lock, params.settings.locks.wait_ms);
     try {
         const verified = await verifyHistoryRewriteNoDrift({
             pmRoot: params.pmRoot,
@@ -86,4 +110,4 @@ export async function executeHistoryRewrite(params) {
     }
 }
 //# sourceMappingURL=history-rewrite.js.map
-//# debugId=665cdb28-cf61-56a3-a037-708d2445359d
+//# debugId=b9f14848-6edc-507a-a543-7bf01d91db50

package/dist/core/history/history-rewrite.js.map

@@ -1 +1 @@
-{"version":3,"file":"history-rewrite.js","sources":["core/history/history-rewrite.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/history/history-rewrite\n *\n * Implements append-only history and replay behavior for History Rewrite.\n */\nimport { readFileIfExists } from \"../fs/fs-utils.js\";\nimport type { ItemTypeRegistry } from \"../item/type-registry.js\";\nimport { acquireLock } from \"../lock/lock.js\";\nimport { EXIT_CODE } from \"../shared/constants.js\";\nimport { PmCliError } from \"../shared/errors.js\";\nimport { locateItem, readLocatedItem } from \"../store/item-store.js\";\nimport { resolveGovernanceKnobs } from \"../store/settings.js\";\nimport type { ItemDocument, PmSettings } from \"../../types/index.js\";\n\ntype LoadedItem = Awaited<ReturnType<typeof readLocatedItem>>;\n\n/**\n * Documents the history rewrite subject payload exchanged by command, SDK, and package integrations.\n */\nexport interface HistoryRewriteSubject {\n  id: string;\n  historyPath: string;\n}\n\n/**\n * Documents the history rewrite ownership params payload exchanged by command, SDK, and package integrations.\n */\nexport interface HistoryRewriteOwnershipParams {\n  itemDocument: ItemDocument | null;\n  subjectId: string;\n  author: string;\n  force: boolean | undefined;\n  settings: PmSettings;\n}\n\n/**\n * Apply ownership_enforcement governance to a history-rewriting operation.\n * Returns the warning(s) the caller should append (empty when no conflict or strict-throws).\n * Throws PmCliError(CONFLICT) in strict mode when the assignee conflicts and --force is not set.\n */\nexport function checkHistoryRewriteOwnership(params: HistoryRewriteOwnershipParams): string[] {\n  if (!params.itemDocument) return [];\n  const assigned = params.itemDocument.metadata?.assignee?.trim();\n  if (!assigned || assigned === params.author || params.force) return [];\n\n  const governance = resolveGovernanceKnobs(params.settings);\n  if (governance.ownership_enforcement === \"strict\") {\n    throw new PmCliError(\n      `Item ${params.subjectId} is assigned to ${assigned}. Use --force to override.`,\n      EXIT_CODE.CONFLICT,\n    );\n  }\n  if (governance.ownership_enforcement === \"warn\") {\n    return [`ownership_warning:assignee_conflict:${params.subjectId}:${assigned}`];\n  }\n  return [];\n}\n\n/**\n * Documents the verify history rewrite drift params payload exchanged by command, SDK, and package integrations.\n */\nexport interface VerifyHistoryRewriteDriftParams {\n  pmRoot: string;\n  subject: HistoryRewriteSubject;\n  settings: PmSettings;\n  typeRegistry: ItemTypeRegistry;\n  historyRawBeforeLock: string | null;\n  currentItemRawBeforeLock: string | null;\n  /** Short operation name used in the conflict message (e.g. \"history-redact\"). */\n  operation: string;\n}\n\n/**\n * Documents the verified history rewrite state payload exchanged by command, SDK, and package integrations.\n */\nexport interface VerifiedHistoryRewriteState {\n  historyRawUnderLock: string | null;\n  locatedUnderLock: Awaited<ReturnType<typeof locateItem>>;\n  loadedItemUnderLock: LoadedItem | null;\n}\n\n/**\n * Re-read the history stream and the located item document under the acquired lock and\n * compare both with the pre-lock raw snapshots. Throws PmCliError(CONFLICT) if either\n * diverged while waiting for the lock so the caller surfaces an actionable retry.\n */\nexport async function verifyHistoryRewriteNoDrift(\n  params: VerifyHistoryRewriteDriftParams,\n): Promise<VerifiedHistoryRewriteState> {\n  const historyRawUnderLock = await readFileIfExists(params.subject.historyPath);\n  if (historyRawUnderLock !== params.historyRawBeforeLock) {\n    throw new PmCliError(\n      `History for ${params.subject.id} changed while waiting for lock; retry ${params.operation}.`,\n      EXIT_CODE.CONFLICT,\n    );\n  }\n  const locatedUnderLock = await locateItem(\n    params.pmRoot,\n    params.subject.id,\n    params.settings.id_prefix,\n    params.settings.item_format,\n    params.typeRegistry.type_to_folder,\n  );\n  const loadedItemUnderLock = locatedUnderLock\n    ? await readLocatedItem(locatedUnderLock, { schema: params.settings.schema })\n    : null;\n  if ((loadedItemUnderLock?.raw ?? null) !== (params.currentItemRawBeforeLock ?? null)) {\n    throw new PmCliError(\n      `Item ${params.subject.id} changed while waiting for lock; retry ${params.operation}.`,\n      EXIT_CODE.CONFLICT,\n    );\n  }\n  return { historyRawUnderLock, locatedUnderLock, loadedItemUnderLock };\n}\n\n/**\n * Documents the execute history rewrite params payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExecuteHistoryRewriteParams {\n  pmRoot: string;\n  subject: HistoryRewriteSubject;\n  settings: PmSettings;\n  typeRegistry: ItemTypeRegistry;\n  historyRawBeforeLock: string | null;\n  currentItemRawBeforeLock: string | null;\n  /** Short operation name used in conflict guidance (e.g. \"history-redact\"). */\n  operation: string;\n  author: string;\n  force: boolean | undefined;\n  itemDocument: ItemDocument | null;\n  applyRewrite: (verified: VerifiedHistoryRewriteState) => Promise<void>;\n  applyPostRewrite?: (verified: VerifiedHistoryRewriteState) => Promise<string[]>;\n}\n\n/**\n * Shared lock/verify/ownership orchestration for history-rewrite commands.\n * Callers provide the operation-specific write/rollback logic and optional\n * post-write hook execution while this helper enforces the common governance +\n * lock sequencing contract.\n */\nexport async function executeHistoryRewrite(params: ExecuteHistoryRewriteParams): Promise<string[]> {\n  const warnings = [...checkHistoryRewriteOwnership({\n    itemDocument: params.itemDocument,\n    subjectId: params.subject.id,\n    author: params.author,\n    force: params.force,\n    settings: params.settings,\n  })];\n  const releaseLock = await acquireLock(\n    params.pmRoot,\n    params.subject.id,\n    params.settings.locks.ttl_seconds,\n    params.author,\n    Boolean(params.force),\n    params.settings.governance.force_required_for_stale_lock,\n  );\n  try {\n    const verified = await verifyHistoryRewriteNoDrift({\n      pmRoot: params.pmRoot,\n      subject: params.subject,\n      settings: params.settings,\n      typeRegistry: params.typeRegistry,\n      historyRawBeforeLock: params.historyRawBeforeLock,\n      currentItemRawBeforeLock: params.currentItemRawBeforeLock,\n      operation: params.operation,\n    });\n    await params.applyRewrite(verified);\n    if (params.applyPostRewrite) {\n      warnings.push(...(await params.applyPostRewrite(verified)));\n    }\n    return warnings;\n  } finally {\n    await releaseLock();\n  }\n}\n"],"names":[],"mappings":"AAAA;;;;GAIG;;;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAwB9D;;;;GAIG;AACH,MAAM,UAAU,4BAA4B,CAAC,MAAqC;IAChF,IAAI,CAAC,MAAM,CAAC,YAAY;QAAE,OAAO,EAAE,CAAC;IACpC,MAAM,QAAQ,GAAG,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAChE,IAAI,CAAC,QAAQ,IAAI,QAAQ,KAAK,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IAEvE,MAAM,UAAU,GAAG,sBAAsB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC3D,IAAI,UAAU,CAAC,qBAAqB,KAAK,QAAQ,EAAE,CAAC;QAClD,MAAM,IAAI,UAAU,CAClB,QAAQ,MAAM,CAAC,SAAS,mBAAmB,QAAQ,4BAA4B,EAC/E,SAAS,CAAC,QAAQ,CACnB,CAAC;IACJ,CAAC;IACD,IAAI,UAAU,CAAC,qBAAqB,KAAK,MAAM,EAAE,CAAC;QAChD,OAAO,CAAC,uCAAuC,MAAM,CAAC,SAAS,IAAI,QAAQ,EAAE,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAyBD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,MAAuC;IAEvC,MAAM,mBAAmB,GAAG,MAAM,gBAAgB,CAAC,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/E,IAAI,mBAAmB,KAAK,MAAM,CAAC,oBAAoB,EAAE,CAAC;QACxD,MAAM,IAAI,UAAU,CAClB,eAAe,MAAM,CAAC,OAAO,CAAC,EAAE,0CAA0C,MAAM,CAAC,SAAS,GAAG,EAC7F,SAAS,CAAC,QAAQ,CACnB,CAAC;IACJ,CAAC;IACD,MAAM,gBAAgB,GAAG,MAAM,UAAU,CACvC,MAAM,CAAC,MAAM,EACb,MAAM,CAAC,OAAO,CAAC,EAAE,EACjB,MAAM,CAAC,QAAQ,CAAC,SAAS,EACzB,MAAM,CAAC,QAAQ,CAAC,WAAW,EAC3B,MAAM,CAAC,YAAY,CAAC,cAAc,CACnC,CAAC;IACF,MAAM,mBAAmB,GAAG,gBAAgB;QAC1C,CAAC,CAAC,MAAM,eAAe,CAAC,gBAAgB,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;QAC7E,CAAC,CAAC,IAAI,CAAC;IACT,IAAI,CAAC,mBAAmB,EAAE,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,wBAAwB,IAAI,IAAI,CAAC,EAAE,CAAC;QACrF,MAAM,IAAI,UAAU,CAClB,QAAQ,MAAM,CAAC,OAAO,CAAC,EAAE,0CAA0C,MAAM,CAAC,SAAS,GAAG,EACtF,SAAS,CAAC,QAAQ,CACnB,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,CAAC;AACxE,CAAC;AAqBD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,MAAmC;IAC7E,MAAM,QAAQ,GAAG,CAAC,GAAG,4BAA4B,CAAC;YAChD,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE;YAC5B,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,QAAQ,EAAE,MAAM,CAAC,QAAQ;SAC1B,CAAC,CAAC,CAAC;IACJ,MAAM,WAAW,GAAG,MAAM,WAAW,CACnC,MAAM,CAAC,MAAM,EACb,MAAM,CAAC,OAAO,CAAC,EAAE,EACjB,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,WAAW,EACjC,MAAM,CAAC,MAAM,EACb,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EACrB,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,6BAA6B,CACzD,CAAC;IACF,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,2BAA2B,CAAC;YACjD,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,oBAAoB,EAAE,MAAM,CAAC,oBAAoB;YACjD,wBAAwB,EAAE,MAAM,CAAC,wBAAwB;YACzD,SAAS,EAAE,MAAM,CAAC,SAAS;SAC5B,CAAC,CAAC;QACH,MAAM,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;QACpC,IAAI,MAAM,CAAC,gBAAgB,EAAE,CAAC;YAC5B,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QAC9D,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;YAAS,CAAC;QACT,MAAM,WAAW,EAAE,CAAC;IACtB,CAAC;AACH,CAAC","debugId":"665cdb28-cf61-56a3-a037-708d2445359d"}
+{"version":3,"file":"history-rewrite.js","sources":["core/history/history-rewrite.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/history/history-rewrite\n *\n * Implements append-only history and replay behavior for History Rewrite.\n */\nimport fs from \"node:fs/promises\";\nimport { readFileIfExists, writeFileAtomic } from \"../fs/fs-utils.js\";\nimport type { ItemTypeRegistry } from \"../item/type-registry.js\";\nimport { acquireLock } from \"../lock/lock.js\";\nimport { EXIT_CODE } from \"../shared/constants.js\";\nimport { PmCliError } from \"../shared/errors.js\";\nimport { locateItem, readLocatedItem } from \"../store/item-store.js\";\nimport { resolveGovernanceKnobs } from \"../store/settings.js\";\nimport type { ItemDocument, PmSettings } from \"../../types/index.js\";\n\ntype LoadedItem = Awaited<ReturnType<typeof readLocatedItem>>;\ntype HistoryRawWriter = (filePath: string, content: string) => Promise<void>;\n\n/**\n * Documents the history rewrite subject payload exchanged by command, SDK, and package integrations.\n */\nexport interface HistoryRewriteSubject {\n  id: string;\n  historyPath: string;\n}\n\n/**\n * Documents the history rewrite ownership params payload exchanged by command, SDK, and package integrations.\n */\nexport interface HistoryRewriteOwnershipParams {\n  itemDocument: ItemDocument | null;\n  subjectId: string;\n  author: string;\n  force: boolean | undefined;\n  settings: PmSettings;\n}\n\n/**\n * Apply ownership_enforcement governance to a history-rewriting operation.\n * Returns the warning(s) the caller should append (empty when no conflict or strict-throws).\n * Throws PmCliError(CONFLICT) in strict mode when the assignee conflicts and --force is not set.\n */\nexport function checkHistoryRewriteOwnership(params: HistoryRewriteOwnershipParams): string[] {\n  if (!params.itemDocument) return [];\n  const assigned = params.itemDocument.metadata?.assignee?.trim();\n  if (!assigned || assigned === params.author || params.force) return [];\n\n  const governance = resolveGovernanceKnobs(params.settings);\n  if (governance.ownership_enforcement === \"strict\") {\n    throw new PmCliError(\n      `Item ${params.subjectId} is assigned to ${assigned}. Use --force to override.`,\n      EXIT_CODE.CONFLICT,\n    );\n  }\n  if (governance.ownership_enforcement === \"warn\") {\n    return [`ownership_warning:assignee_conflict:${params.subjectId}:${assigned}`];\n  }\n  return [];\n}\n\n/**\n * Documents the verify history rewrite drift params payload exchanged by command, SDK, and package integrations.\n */\nexport interface VerifyHistoryRewriteDriftParams {\n  pmRoot: string;\n  subject: HistoryRewriteSubject;\n  settings: PmSettings;\n  typeRegistry: ItemTypeRegistry;\n  historyRawBeforeLock: string | null;\n  currentItemRawBeforeLock: string | null;\n  /** Short operation name used in the conflict message (e.g. \"history-redact\"). */\n  operation: string;\n}\n\n/**\n * Documents the verified history rewrite state payload exchanged by command, SDK, and package integrations.\n */\nexport interface VerifiedHistoryRewriteState {\n  historyRawUnderLock: string | null;\n  locatedUnderLock: Awaited<ReturnType<typeof locateItem>>;\n  loadedItemUnderLock: LoadedItem | null;\n}\n\n/**\n * Re-read the history stream and the located item document under the acquired lock and\n * compare both with the pre-lock raw snapshots. Throws PmCliError(CONFLICT) if either\n * diverged while waiting for the lock so the caller surfaces an actionable retry.\n */\nexport async function verifyHistoryRewriteNoDrift(\n  params: VerifyHistoryRewriteDriftParams,\n): Promise<VerifiedHistoryRewriteState> {\n  const historyRawUnderLock = await readFileIfExists(params.subject.historyPath);\n  if (historyRawUnderLock !== params.historyRawBeforeLock) {\n    throw new PmCliError(\n      `History for ${params.subject.id} changed while waiting for lock; retry ${params.operation}.`,\n      EXIT_CODE.CONFLICT,\n    );\n  }\n  const locatedUnderLock = await locateItem(\n    params.pmRoot,\n    params.subject.id,\n    params.settings.id_prefix,\n    params.settings.item_format,\n    params.typeRegistry.type_to_folder,\n  );\n  const loadedItemUnderLock = locatedUnderLock\n    ? await readLocatedItem(locatedUnderLock, { schema: params.settings.schema })\n    : null;\n  if ((loadedItemUnderLock?.raw ?? null) !== (params.currentItemRawBeforeLock ?? null)) {\n    throw new PmCliError(\n      `Item ${params.subject.id} changed while waiting for lock; retry ${params.operation}.`,\n      EXIT_CODE.CONFLICT,\n    );\n  }\n  return { historyRawUnderLock, locatedUnderLock, loadedItemUnderLock };\n}\n\n/**\n * Documents the execute history rewrite params payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExecuteHistoryRewriteParams {\n  pmRoot: string;\n  subject: HistoryRewriteSubject;\n  settings: PmSettings;\n  typeRegistry: ItemTypeRegistry;\n  historyRawBeforeLock: string | null;\n  currentItemRawBeforeLock: string | null;\n  /** Short operation name used in conflict guidance (e.g. \"history-redact\"). */\n  operation: string;\n  author: string;\n  force: boolean | undefined;\n  itemDocument: ItemDocument | null;\n  applyRewrite: (verified: VerifiedHistoryRewriteState) => Promise<void>;\n  applyPostRewrite?: (verified: VerifiedHistoryRewriteState) => Promise<string[]>;\n}\n\n/**\n * Writes the rewritten history stream and restores the under-lock snapshot on failure.\n */\nexport async function writeHistoryRawWithRollback(params: {\n  historyPath: string;\n  nextHistoryRaw: string;\n  historyRawUnderLock: string | null;\n  writeHistoryRaw?: HistoryRawWriter;\n}): Promise<void> {\n  const writeHistoryRaw = params.writeHistoryRaw ?? writeFileAtomic;\n  try {\n    await writeHistoryRaw(params.historyPath, params.nextHistoryRaw);\n  } catch (error) {\n    try {\n      if (params.historyRawUnderLock === null) {\n        await fs.rm(params.historyPath, { force: true });\n      } else {\n        await writeHistoryRaw(params.historyPath, params.historyRawUnderLock);\n      }\n    } catch (rollbackError) {\n      throw new AggregateError(\n        [error, rollbackError],\n        `History rewrite failed and rollback also failed: ${String(error)}`,\n      );\n    }\n    throw error;\n  }\n}\n\n/**\n * Shared lock/verify/ownership orchestration for history-rewrite commands.\n * Callers provide the operation-specific write/rollback logic and optional\n * post-write hook execution while this helper enforces the common governance +\n * lock sequencing contract.\n */\nexport async function executeHistoryRewrite(params: ExecuteHistoryRewriteParams): Promise<string[]> {\n  const warnings = [...checkHistoryRewriteOwnership({\n    itemDocument: params.itemDocument,\n    subjectId: params.subject.id,\n    author: params.author,\n    force: params.force,\n    settings: params.settings,\n  })];\n  const releaseLock = await acquireLock(\n    params.pmRoot,\n    params.subject.id,\n    params.settings.locks.ttl_seconds,\n    params.author,\n    Boolean(params.force),\n    params.settings.governance.force_required_for_stale_lock,\n    params.settings.locks.wait_ms,\n  );\n  try {\n    const verified = await verifyHistoryRewriteNoDrift({\n      pmRoot: params.pmRoot,\n      subject: params.subject,\n      settings: params.settings,\n      typeRegistry: params.typeRegistry,\n      historyRawBeforeLock: params.historyRawBeforeLock,\n      currentItemRawBeforeLock: params.currentItemRawBeforeLock,\n      operation: params.operation,\n    });\n    await params.applyRewrite(verified);\n    if (params.applyPostRewrite) {\n      warnings.push(...(await params.applyPostRewrite(verified)));\n    }\n    return warnings;\n  } finally {\n    await releaseLock();\n  }\n}\n"],"names":[],"mappings":"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","debugId":"b9f14848-6edc-507a-a543-7bf01d91db50"}

package/dist/core/item/parent-reference-policy.d.ts

@@ -11,10 +11,18 @@ export declare function normalizeParentReferencePolicy(value: string | undefined
 /**
  * Implements normalize parent reference value for the public runtime surface of this module.
  */
-export declare function normalizeParentReferenceValue(rawValue: string): string;
+export declare function normalizeParentReferenceValue(rawValue: unknown): string;
+/**
+ * Detects parent-style placeholder tokens that should never become stored ids.
+ */
+export declare function isPlaceholderReferenceToken(value: string): boolean;
 /**
  * Implements validate missing parent reference for the public runtime surface of this module.
  */
 export declare function validateMissingParentReference(parentId: string, policy: ParentReferencePolicy): {
     warnings: string[];
 };
+/**
+ * Rejects the one-node hierarchy cycle where an item points at itself.
+ */
+export declare function assertParentReferenceIsNotSelf(itemId: string, parentId: string, prefix: string): void;

package/dist/core/item/parent-reference-policy.js

@@ -1,7 +1,9 @@
 
-!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]="14feaca7-1c1f-59a0-a258-e2d33a848526")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="a8ef1b95-7cd2-572b-b1c3-9c782616bdf3")}catch(e){}}();
+import { normalizeItemId } from "./id.js";
 import { EXIT_CODE } from "../shared/constants.js";
 import { PmCliError } from "../shared/errors.js";
+const PLACEHOLDER_REFERENCE_TOKENS = new Set(["none", "null", "undefined"]);
 /**
  * Implements normalize parent reference policy for the public runtime surface of this module.
  */
@@ -19,16 +21,24 @@ export function normalizeParentReferencePolicy(value) {
  * Implements normalize parent reference value for the public runtime surface of this module.
  */
 export function normalizeParentReferenceValue(rawValue) {
+    if (typeof rawValue !== "string") {
+        throw new PmCliError("--parent must be a string. Use --unset parent to clear this field.", EXIT_CODE.USAGE);
+    }
     const value = rawValue.trim();
     if (value.length === 0) {
         throw new PmCliError("--parent must not be empty. Use --parent none to unset.", EXIT_CODE.USAGE);
     }
-    const normalized = value.toLowerCase();
-    if (normalized === "none" || normalized === "null" || normalized === "undefined") {
+    if (isPlaceholderReferenceToken(value)) {
         throw new PmCliError(`--parent must not use placeholder token "${value}". Use --unset parent to clear this field.`, EXIT_CODE.USAGE);
     }
     return value;
 }
+/**
+ * Detects parent-style placeholder tokens that should never become stored ids.
+ */
+export function isPlaceholderReferenceToken(value) {
+    return PLACEHOLDER_REFERENCE_TOKENS.has(value.trim().toLowerCase());
+}
 /**
  * Implements validate missing parent reference for the public runtime surface of this module.
  */
@@ -40,5 +50,19 @@ export function validateMissingParentReference(parentId, policy) {
         warnings: [`validation_warning:parent_reference_missing:${parentId}`],
     };
 }
+/**
+ * Rejects the one-node hierarchy cycle where an item points at itself.
+ */
+export function assertParentReferenceIsNotSelf(itemId, parentId, prefix) {
+    const normalizedItemId = normalizeItemId(itemId, prefix);
+    const normalizedParentId = normalizeItemId(parentId, prefix);
+    if (normalizedItemId !== normalizedParentId) {
+        return;
+    }
+    const normalizationDetail = parentId !== normalizedParentId || itemId !== normalizedItemId
+        ? ` (normalized from parent "${parentId}" and item "${itemId}")`
+        : "";
+    throw new PmCliError(`Parent item "${normalizedParentId}" cannot be the same as item "${normalizedItemId}"${normalizationDetail}. Use --unset parent to clear this field.`, EXIT_CODE.USAGE);
+}
 //# sourceMappingURL=parent-reference-policy.js.map
-//# debugId=14feaca7-1c1f-59a0-a258-e2d33a848526
+//# debugId=a8ef1b95-7cd2-572b-b1c3-9c782616bdf3

package/dist/core/item/parent-reference-policy.js.map

@@ -1 +1 @@
-{"version":3,"file":"parent-reference-policy.js","sources":["core/item/parent-reference-policy.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/item/parent-reference-policy\n *\n * Defines item parsing, formatting, and lifecycle helpers for Parent Reference Policy.\n */\nimport type { ParentReferencePolicy } from \"../../types/index.js\";\nimport { EXIT_CODE } from \"../shared/constants.js\";\nimport { PmCliError } from \"../shared/errors.js\";\n\n/**\n * Implements normalize parent reference policy for the public runtime surface of this module.\n */\nexport function normalizeParentReferencePolicy(value: string | undefined): ParentReferencePolicy {\n  const normalized = value?.trim().toLowerCase().replaceAll(\"-\", \"_\");\n  if (normalized === \"warn\" || normalized === \"strict_error\") {\n    return normalized;\n  }\n  if (normalized === \"strict\") {\n    return \"strict_error\";\n  }\n  throw new PmCliError(\n    \"Config set parent-reference-policy requires --policy with one of: warn, strict_error (alias: strict)\",\n    EXIT_CODE.USAGE,\n  );\n}\n\n/**\n * Implements normalize parent reference value for the public runtime surface of this module.\n */\nexport function normalizeParentReferenceValue(rawValue: string): string {\n  const value = rawValue.trim();\n  if (value.length === 0) {\n    throw new PmCliError(\"--parent must not be empty. Use --parent none to unset.\", EXIT_CODE.USAGE);\n  }\n  const normalized = value.toLowerCase();\n  if (normalized === \"none\" || normalized === \"null\" || normalized === \"undefined\") {\n    throw new PmCliError(\n      `--parent must not use placeholder token \"${value}\". Use --unset parent to clear this field.`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  return value;\n}\n\n/**\n * Implements validate missing parent reference for the public runtime surface of this module.\n */\nexport function validateMissingParentReference(\n  parentId: string,\n  policy: ParentReferencePolicy,\n): { warnings: string[] } {\n  if (policy === \"strict_error\") {\n    throw new PmCliError(\n      `Parent item \"${parentId}\" was not found. Create it first or use --parent none.`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  return {\n    warnings: [`validation_warning:parent_reference_missing:${parentId}`],\n  };\n}\n"],"names":[],"mappings":";;AAMA,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEjD;;GAEG;AACH,MAAM,UAAU,8BAA8B,CAAC,KAAyB;IACtE,MAAM,UAAU,GAAG,KAAK,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACpE,IAAI,UAAU,KAAK,MAAM,IAAI,UAAU,KAAK,cAAc,EAAE,CAAC;QAC3D,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,IAAI,UAAU,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,cAAc,CAAC;IACxB,CAAC;IACD,MAAM,IAAI,UAAU,CAClB,sGAAsG,EACtG,SAAS,CAAC,KAAK,CAChB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,6BAA6B,CAAC,QAAgB;IAC5D,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,UAAU,CAAC,yDAAyD,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;IACnG,CAAC;IACD,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IACvC,IAAI,UAAU,KAAK,MAAM,IAAI,UAAU,KAAK,MAAM,IAAI,UAAU,KAAK,WAAW,EAAE,CAAC;QACjF,MAAM,IAAI,UAAU,CAClB,4CAA4C,KAAK,4CAA4C,EAC7F,SAAS,CAAC,KAAK,CAChB,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,8BAA8B,CAC5C,QAAgB,EAChB,MAA6B;IAE7B,IAAI,MAAM,KAAK,cAAc,EAAE,CAAC;QAC9B,MAAM,IAAI,UAAU,CAClB,gBAAgB,QAAQ,wDAAwD,EAChF,SAAS,CAAC,KAAK,CAChB,CAAC;IACJ,CAAC;IACD,OAAO;QACL,QAAQ,EAAE,CAAC,+CAA+C,QAAQ,EAAE,CAAC;KACtE,CAAC;AACJ,CAAC","debugId":"14feaca7-1c1f-59a0-a258-e2d33a848526"}
+{"version":3,"file":"parent-reference-policy.js","sources":["core/item/parent-reference-policy.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/item/parent-reference-policy\n *\n * Defines item parsing, formatting, and lifecycle helpers for Parent Reference Policy.\n */\nimport type { ParentReferencePolicy } from \"../../types/index.js\";\nimport { normalizeItemId } from \"./id.js\";\nimport { EXIT_CODE } from \"../shared/constants.js\";\nimport { PmCliError } from \"../shared/errors.js\";\n\nconst PLACEHOLDER_REFERENCE_TOKENS = new Set([\"none\", \"null\", \"undefined\"]);\n\n/**\n * Implements normalize parent reference policy for the public runtime surface of this module.\n */\nexport function normalizeParentReferencePolicy(value: string | undefined): ParentReferencePolicy {\n  const normalized = value?.trim().toLowerCase().replaceAll(\"-\", \"_\");\n  if (normalized === \"warn\" || normalized === \"strict_error\") {\n    return normalized;\n  }\n  if (normalized === \"strict\") {\n    return \"strict_error\";\n  }\n  throw new PmCliError(\n    \"Config set parent-reference-policy requires --policy with one of: warn, strict_error (alias: strict)\",\n    EXIT_CODE.USAGE,\n  );\n}\n\n/**\n * Implements normalize parent reference value for the public runtime surface of this module.\n */\nexport function normalizeParentReferenceValue(rawValue: unknown): string {\n  if (typeof rawValue !== \"string\") {\n    throw new PmCliError(\"--parent must be a string. Use --unset parent to clear this field.\", EXIT_CODE.USAGE);\n  }\n  const value = rawValue.trim();\n  if (value.length === 0) {\n    throw new PmCliError(\"--parent must not be empty. Use --parent none to unset.\", EXIT_CODE.USAGE);\n  }\n  if (isPlaceholderReferenceToken(value)) {\n    throw new PmCliError(\n      `--parent must not use placeholder token \"${value}\". Use --unset parent to clear this field.`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  return value;\n}\n\n/**\n * Detects parent-style placeholder tokens that should never become stored ids.\n */\nexport function isPlaceholderReferenceToken(value: string): boolean {\n  return PLACEHOLDER_REFERENCE_TOKENS.has(value.trim().toLowerCase());\n}\n\n/**\n * Implements validate missing parent reference for the public runtime surface of this module.\n */\nexport function validateMissingParentReference(\n  parentId: string,\n  policy: ParentReferencePolicy,\n): { warnings: string[] } {\n  if (policy === \"strict_error\") {\n    throw new PmCliError(\n      `Parent item \"${parentId}\" was not found. Create it first or use --parent none.`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  return {\n    warnings: [`validation_warning:parent_reference_missing:${parentId}`],\n  };\n}\n\n/**\n * Rejects the one-node hierarchy cycle where an item points at itself.\n */\nexport function assertParentReferenceIsNotSelf(itemId: string, parentId: string, prefix: string): void {\n  const normalizedItemId = normalizeItemId(itemId, prefix);\n  const normalizedParentId = normalizeItemId(parentId, prefix);\n  if (normalizedItemId !== normalizedParentId) {\n    return;\n  }\n  const normalizationDetail =\n    parentId !== normalizedParentId || itemId !== normalizedItemId\n      ? ` (normalized from parent \"${parentId}\" and item \"${itemId}\")`\n      : \"\";\n  throw new PmCliError(\n    `Parent item \"${normalizedParentId}\" cannot be the same as item \"${normalizedItemId}\"${normalizationDetail}. Use --unset parent to clear this field.`,\n    EXIT_CODE.USAGE,\n  );\n}\n"],"names":[],"mappings":";;AAMA,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEjD,MAAM,4BAA4B,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;AAE5E;;GAEG;AACH,MAAM,UAAU,8BAA8B,CAAC,KAAyB;IACtE,MAAM,UAAU,GAAG,KAAK,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACpE,IAAI,UAAU,KAAK,MAAM,IAAI,UAAU,KAAK,cAAc,EAAE,CAAC;QAC3D,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,IAAI,UAAU,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,cAAc,CAAC;IACxB,CAAC;IACD,MAAM,IAAI,UAAU,CAClB,sGAAsG,EACtG,SAAS,CAAC,KAAK,CAChB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,6BAA6B,CAAC,QAAiB;IAC7D,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACjC,MAAM,IAAI,UAAU,CAAC,oEAAoE,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;IAC9G,CAAC;IACD,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,UAAU,CAAC,yDAAyD,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;IACnG,CAAC;IACD,IAAI,2BAA2B,CAAC,KAAK,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,UAAU,CAClB,4CAA4C,KAAK,4CAA4C,EAC7F,SAAS,CAAC,KAAK,CAChB,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,2BAA2B,CAAC,KAAa;IACvD,OAAO,4BAA4B,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;AACtE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,8BAA8B,CAC5C,QAAgB,EAChB,MAA6B;IAE7B,IAAI,MAAM,KAAK,cAAc,EAAE,CAAC;QAC9B,MAAM,IAAI,UAAU,CAClB,gBAAgB,QAAQ,wDAAwD,EAChF,SAAS,CAAC,KAAK,CAChB,CAAC;IACJ,CAAC;IACD,OAAO;QACL,QAAQ,EAAE,CAAC,+CAA+C,QAAQ,EAAE,CAAC;KACtE,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,8BAA8B,CAAC,MAAc,EAAE,QAAgB,EAAE,MAAc;IAC7F,MAAM,gBAAgB,GAAG,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzD,MAAM,kBAAkB,GAAG,eAAe,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC7D,IAAI,gBAAgB,KAAK,kBAAkB,EAAE,CAAC;QAC5C,OAAO;IACT,CAAC;IACD,MAAM,mBAAmB,GACvB,QAAQ,KAAK,kBAAkB,IAAI,MAAM,KAAK,gBAAgB;QAC5D,CAAC,CAAC,6BAA6B,QAAQ,eAAe,MAAM,IAAI;QAChE,CAAC,CAAC,EAAE,CAAC;IACT,MAAM,IAAI,UAAU,CAClB,gBAAgB,kBAAkB,iCAAiC,gBAAgB,IAAI,mBAAmB,2CAA2C,EACrJ,SAAS,CAAC,KAAK,CAChB,CAAC;AACJ,CAAC","debugId":"a8ef1b95-7cd2-572b-b1c3-9c782616bdf3"}

package/dist/core/item/type-registry.d.ts

@@ -6,6 +6,7 @@ export declare const DEFAULT_REQUIRED_CREATE_REPEATABLES: readonly ["dep", "comm
  * Restricts command option policy command values accepted by command, SDK, and storage contracts.
  */
 export type CommandOptionPolicyCommand = "create" | "update";
+export declare const COMMON_MUTATION_COMMAND_OPTION_KEYS: readonly ["deadline", "estimatedMinutes", "acceptanceCriteria", "definitionOfReady", "order", "goal", "objective", "value", "impact", "outcome", "whyNow", "assignee", "parent", "reviewer", "risk", "confidence", "sprint", "release", "blockedBy", "blockedReason", "unblockNote", "reporter", "severity", "environment", "reproSteps", "resolution", "expectedResult", "actualResult", "affectedVersion", "fixedVersion", "component", "regression", "customerImpact"];
 /**
  * Documents the command option policy state payload exchanged by command, SDK, and package integrations.
  */

package/dist/core/item/type-registry.js

@@ -4,7 +4,7 @@
  * Defines item parsing, formatting, and lifecycle helpers for Type Registry.
  */
 
-!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]="e9e27e2d-967c-5e17-8266-d661f65b78ac")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="563d02b1-6a96-539c-9e2c-dc118aa5dd72")}catch(e){}}();
 import { TYPE_TO_FOLDER } from "../shared/constants.js";
 import { ITEM_TYPE_VALUES } from "../../types/index.js";
 import { normalizeItemTypeDefinition as normalizeSharedItemTypeDefinition, normalizeItemTypeStringList, strictPolicyCommand, } from "./item-type-definition.js";
@@ -25,7 +25,7 @@ export const DEFAULT_REQUIRED_CREATE_FIELDS = [
 export const DEFAULT_REQUIRED_CREATE_REPEATABLES = ["dep", "comment", "note", "learning", "file", "test", "doc"];
 // Keep aligned with cli/commands/shared-unset-fields.ts. This core registry
 // cannot import CLI unset metadata without creating a core -> CLI dependency.
-const COMMON_MUTATION_COMMAND_OPTION_KEYS = [
+export const COMMON_MUTATION_COMMAND_OPTION_KEYS = [
     "deadline",
     "estimatedMinutes",
     "acceptanceCriteria",
@@ -152,116 +152,85 @@ const UPDATE_COMMAND_OPTION_ALIASES = {
     "allow-audit-update": "allowAuditUpdate",
     allow_audit_update: "allowAuditUpdate",
 };
-const CREATE_COMMAND_OPTION_FLAG_LABELS = {
-    title: "--title",
-    description: "--description",
-    type: "--type",
-    status: "--status",
-    priority: "--priority",
-    tags: "--tags",
-    body: "--body",
-    deadline: "--deadline",
-    estimatedMinutes: "--estimate/--estimated-minutes",
-    acceptanceCriteria: "--acceptance-criteria/--ac",
-    definitionOfReady: "--definition-of-ready",
-    order: "--order/--rank",
-    goal: "--goal",
-    objective: "--objective",
-    value: "--value",
-    impact: "--impact",
-    outcome: "--outcome",
-    whyNow: "--why-now",
-    author: "--author",
-    message: "--message",
-    assignee: "--assignee",
-    parent: "--parent",
-    reviewer: "--reviewer",
-    risk: "--risk",
-    confidence: "--confidence",
-    sprint: "--sprint",
-    release: "--release",
-    blockedBy: "--blocked-by",
-    blockedReason: "--blocked-reason",
-    unblockNote: "--unblock-note",
-    reporter: "--reporter",
-    severity: "--severity",
-    environment: "--environment",
-    reproSteps: "--repro-steps",
-    resolution: "--resolution",
-    expectedResult: "--expected-result",
-    actualResult: "--actual-result",
-    affectedVersion: "--affected-version",
-    fixedVersion: "--fixed-version",
-    component: "--component",
-    regression: "--regression",
-    customerImpact: "--customer-impact",
-    dep: "--dep",
-    comment: "--comment",
-    note: "--note",
-    learning: "--learning",
-    file: "--file",
-    test: "--test",
-    doc: "--doc",
-    reminder: "--reminder",
-    event: "--event",
-    typeOption: "--type-option",
-};
-const UPDATE_COMMAND_OPTION_FLAG_LABELS = {
-    title: "--title",
-    description: "--description",
-    body: "--body",
-    status: "--status",
-    closeReason: "--close-reason",
-    priority: "--priority",
-    type: "--type",
-    tags: "--tags",
-    deadline: "--deadline",
-    estimatedMinutes: "--estimate/--estimated-minutes",
-    acceptanceCriteria: "--acceptance-criteria/--ac",
-    definitionOfReady: "--definition-of-ready",
-    order: "--order/--rank",
-    goal: "--goal",
-    objective: "--objective",
-    value: "--value",
-    impact: "--impact",
-    outcome: "--outcome",
-    whyNow: "--why-now",
-    assignee: "--assignee",
-    parent: "--parent",
-    reviewer: "--reviewer",
-    risk: "--risk",
-    confidence: "--confidence",
-    sprint: "--sprint",
-    release: "--release",
-    blockedBy: "--blocked-by",
-    blockedReason: "--blocked-reason",
-    unblockNote: "--unblock-note",
-    reporter: "--reporter",
-    severity: "--severity",
-    environment: "--environment",
-    reproSteps: "--repro-steps",
-    resolution: "--resolution",
-    expectedResult: "--expected-result",
-    actualResult: "--actual-result",
-    affectedVersion: "--affected-version",
-    fixedVersion: "--fixed-version",
-    component: "--component",
-    regression: "--regression",
-    customerImpact: "--customer-impact",
-    comment: "--comment",
-    note: "--note",
-    learning: "--learning",
-    file: "--file",
-    test: "--test",
-    doc: "--doc",
-    reminder: "--reminder",
-    event: "--event",
-    typeOption: "--type-option",
-    allowAuditUpdate: "--allow-audit-update",
-    author: "--author",
-    message: "--message",
-    force: "--force",
-};
+const COMMON_MUTATION_COMMAND_OPTION_FLAG_LABEL_ENTRIES = [
+    ["deadline", "--deadline"],
+    ["estimatedMinutes", "--estimate/--estimated-minutes"],
+    ["acceptanceCriteria", "--acceptance-criteria/--ac"],
+    ["definitionOfReady", "--definition-of-ready"],
+    ["order", "--order/--rank"],
+    ["goal", "--goal"],
+    ["objective", "--objective"],
+    ["value", "--value"],
+    ["impact", "--impact"],
+    ["outcome", "--outcome"],
+    ["whyNow", "--why-now"],
+    ["assignee", "--assignee"],
+    ["parent", "--parent"],
+    ["reviewer", "--reviewer"],
+    ["risk", "--risk"],
+    ["confidence", "--confidence"],
+    ["sprint", "--sprint"],
+    ["release", "--release"],
+    ["blockedBy", "--blocked-by"],
+    ["blockedReason", "--blocked-reason"],
+    ["unblockNote", "--unblock-note"],
+    ["reporter", "--reporter"],
+    ["severity", "--severity"],
+    ["environment", "--environment"],
+    ["reproSteps", "--repro-steps"],
+    ["resolution", "--resolution"],
+    ["expectedResult", "--expected-result"],
+    ["actualResult", "--actual-result"],
+    ["affectedVersion", "--affected-version"],
+    ["fixedVersion", "--fixed-version"],
+    ["component", "--component"],
+    ["regression", "--regression"],
+    ["customerImpact", "--customer-impact"],
+];
+const LINKED_RESOURCE_COMMAND_OPTION_FLAG_LABEL_ENTRIES = [
+    ["comment", "--comment"],
+    ["note", "--note"],
+    ["learning", "--learning"],
+    ["file", "--file"],
+    ["test", "--test"],
+    ["doc", "--doc"],
+    ["reminder", "--reminder"],
+    ["event", "--event"],
+    ["typeOption", "--type-option"],
+];
+function commandOptionLabelMap(entries) {
+    return Object.fromEntries(entries);
+}
+const CREATE_COMMAND_OPTION_FLAG_LABELS = commandOptionLabelMap([
+    ["title", "--title"],
+    ["description", "--description"],
+    ["type", "--type"],
+    ["status", "--status"],
+    ["priority", "--priority"],
+    ["tags", "--tags"],
+    ["body", "--body"],
+    ...COMMON_MUTATION_COMMAND_OPTION_FLAG_LABEL_ENTRIES,
+    ["author", "--author"],
+    ["message", "--message"],
+    ["dep", "--dep"],
+    ...LINKED_RESOURCE_COMMAND_OPTION_FLAG_LABEL_ENTRIES,
+]);
+const UPDATE_COMMAND_OPTION_FLAG_LABELS = commandOptionLabelMap([
+    ["title", "--title"],
+    ["description", "--description"],
+    ["body", "--body"],
+    ["status", "--status"],
+    ["closeReason", "--close-reason"],
+    ["priority", "--priority"],
+    ["type", "--type"],
+    ["tags", "--tags"],
+    ...COMMON_MUTATION_COMMAND_OPTION_FLAG_LABEL_ENTRIES,
+    ...LINKED_RESOURCE_COMMAND_OPTION_FLAG_LABEL_ENTRIES,
+    ["allowAuditUpdate", "--allow-audit-update"],
+    ["author", "--author"],
+    ["message", "--message"],
+    ["force", "--force"],
+]);
 function normalizeCommandOptionToken(value) {
     return value.trim().replace(/^--+/, "").toLowerCase();
 }
@@ -430,6 +399,27 @@ function resolveDefinitionCommandOptionPolicies(normalizedDefinition, existing)
             ? [...existing.command_option_policies]
             : [];
 }
+function buildResolvedTypeDefinition(normalizedDefinition, existing) {
+    const keepName = existing?.name ?? normalizedDefinition.name;
+    const description = normalizedDefinition.description ?? existing?.description;
+    const defaultStatus = normalizedDefinition.default_status ?? existing?.default_status;
+    const resolvedDefinition = {
+        name: keepName,
+        folder: normalizedDefinition.folder ?? existing?.folder ?? toDefaultFolder(keepName),
+        aliases: normalizeItemTypeStringList([...(existing?.aliases ?? []), ...(normalizedDefinition.aliases ?? [])]),
+        required_create_fields: resolveDefinitionRequiredCreateFields(normalizedDefinition, existing),
+        required_create_repeatables: resolveDefinitionRequiredCreateRepeatables(normalizedDefinition, existing),
+        options: resolveDefinitionOptions(normalizedDefinition, existing),
+        command_option_policies: resolveDefinitionCommandOptionPolicies(normalizedDefinition, existing),
+    };
+    if (description) {
+        resolvedDefinition.description = description;
+    }
+    if (defaultStatus) {
+        resolvedDefinition.default_status = defaultStatus;
+    }
+    return resolvedDefinition;
+}
 function applyTypeDefinitions(source, target) {
     for (const rawDefinition of source) {
         const normalizedDefinition = normalizeTypeDefinition(rawDefinition);
@@ -438,25 +428,7 @@ function applyTypeDefinitions(source, target) {
         }
         const lowerName = normalizedDefinition.name.toLowerCase();
         const existing = target.get(lowerName);
-        const keepName = existing?.name ?? normalizedDefinition.name;
-        const folder = normalizedDefinition.folder ?? existing?.folder ?? toDefaultFolder(keepName);
-        const aliases = normalizeItemTypeStringList([
-            ...(existing?.aliases ?? []),
-            ...(normalizedDefinition.aliases ?? []),
-        ]);
-        const defaultStatus = normalizedDefinition.default_status ?? existing?.default_status;
-        const description = normalizedDefinition.description ?? existing?.description;
-        target.set(lowerName, {
-            name: keepName,
-            ...(description ? { description } : {}),
-            ...(defaultStatus ? { default_status: defaultStatus } : {}),
-            folder,
-            aliases,
-            required_create_fields: resolveDefinitionRequiredCreateFields(normalizedDefinition, existing),
-            required_create_repeatables: resolveDefinitionRequiredCreateRepeatables(normalizedDefinition, existing),
-            options: resolveDefinitionOptions(normalizedDefinition, existing),
-            command_option_policies: resolveDefinitionCommandOptionPolicies(normalizedDefinition, existing),
-        });
+        target.set(lowerName, buildResolvedTypeDefinition(normalizedDefinition, existing));
     }
 }
 function collectExtensionTypeDefinitions(registrations) {
@@ -536,61 +508,65 @@ export function resolveTypeDefinition(typeName, registry) {
     }
     return registry.by_type[resolvedName];
 }
-/**
- * Implements resolve command option policy state for the public runtime surface of this module.
- */
-export function resolveCommandOptionPolicyState(typeDefinition, command, baseRequiredOptions) {
-    const errors = [];
-    const required = new Set();
-    const hidden = new Set();
-    const disabled = new Set();
+function applyBaseRequiredCommandOptions(state, typeDefinition, command, baseRequiredOptions) {
     for (const rawBase of baseRequiredOptions) {
         const canonical = canonicalizeCommandOptionKey(command, rawBase);
-        if (!canonical) {
-            errors.push(`Unsupported base required option "${rawBase}" for command "${command}" on type "${typeDefinition.name}"`);
+        if (canonical) {
+            state.required.add(canonical);
             continue;
         }
-        required.add(canonical);
+        state.errors.push(`Unsupported base required option "${rawBase}" for command "${command}" on type "${typeDefinition.name}"`);
+    }
+}
+function applyBooleanPolicySet(target, option, enabled) {
+    if (enabled) {
+        target.add(option);
+        return;
+    }
+    target.delete(option);
+}
+function applyCommandOptionPolicy(state, typeDefinition, command, policy) {
+    const canonical = canonicalizeCommandOptionKey(command, policy.option);
+    if (!canonical) {
+        state.errors.push(`Unsupported command_option_policies option "${policy.option}" for command "${command}" on type "${typeDefinition.name}"`);
+        return;
+    }
+    if (policy.required !== undefined) {
+        applyBooleanPolicySet(state.required, canonical, policy.required);
+    }
+    if (policy.visible !== undefined) {
+        applyBooleanPolicySet(state.hidden, canonical, !policy.visible);
     }
+    if (policy.enabled !== undefined) {
+        applyBooleanPolicySet(state.disabled, canonical, !policy.enabled);
+    }
+}
+function applyCommandOptionPolicies(state, typeDefinition, command) {
     for (const policy of typeDefinition.command_option_policies) {
-        if (policy.command !== command) {
-            continue;
-        }
-        const canonical = canonicalizeCommandOptionKey(command, policy.option);
-        if (!canonical) {
-            errors.push(`Unsupported command_option_policies option "${policy.option}" for command "${command}" on type "${typeDefinition.name}"`);
-            continue;
-        }
-        if (policy.required !== undefined) {
-            if (policy.required) {
-                required.add(canonical);
-            }
-            else {
-                required.delete(canonical);
-            }
-        }
-        if (policy.visible !== undefined) {
-            if (policy.visible) {
-                hidden.delete(canonical);
-            }
-            else {
-                hidden.add(canonical);
-            }
-        }
-        if (policy.enabled !== undefined) {
-            if (policy.enabled) {
-                disabled.delete(canonical);
-            }
-            else {
-                disabled.add(canonical);
-            }
+        if (policy.command === command) {
+            applyCommandOptionPolicy(state, typeDefinition, command, policy);
         }
     }
-    for (const option of required) {
-        if (disabled.has(option)) {
-            errors.push(`Option "${option}" cannot be both required and disabled for command "${command}" on type "${typeDefinition.name}"`);
+}
+function appendRequiredDisabledPolicyErrors(state, typeDefinition, command) {
+    for (const option of state.required) {
+        if (state.disabled.has(option)) {
+            state.errors.push(`Option "${option}" cannot be both required and disabled for command "${command}" on type "${typeDefinition.name}"`);
         }
     }
+}
+/**
+ * Implements resolve command option policy state for the public runtime surface of this module.
+ */
+export function resolveCommandOptionPolicyState(typeDefinition, command, baseRequiredOptions) {
+    const errors = [];
+    const required = new Set();
+    const hidden = new Set();
+    const disabled = new Set();
+    const state = { required, hidden, disabled, errors };
+    applyBaseRequiredCommandOptions(state, typeDefinition, command, baseRequiredOptions);
+    applyCommandOptionPolicies(state, typeDefinition, command);
+    appendRequiredDisabledPolicyErrors(state, typeDefinition, command);
     return {
         required: [...required],
         hidden: [...hidden].sort((left, right) => left.localeCompare(right)),
@@ -678,4 +654,4 @@ export function validateTypeOptions(typeName, rawTypeOptions, registry) {
     };
 }
 //# sourceMappingURL=type-registry.js.map
-//# debugId=e9e27e2d-967c-5e17-8266-d661f65b78ac
+//# debugId=563d02b1-6a96-539c-9e2c-dc118aa5dd72