@unbrained/pm-cli 2026.7.3 → 2026.7.5

package/dist/cli/commands/copy.js

@@ -4,7 +4,7 @@
  * Implements the pm copy command surface and its agent-facing runtime behavior.
  */
 
-!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]="35ce2b1f-202f-57c1-a17d-95d1e7e06f19")}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]="9f18adf2-5e40-5104-b7fa-5b5d77ffe54b")}catch(e){}}();
 import { pathExists, removeFileIfExists, writeFileAtomic } from "../../core/fs/fs-utils.js";
 import { appendHistoryEntry, createHistoryEntry } from "../../core/history/history.js";
 import { generateItemId } from "../../core/item/id.js";
@@ -89,7 +89,7 @@ export async function runCopy(sourceId, options, global) {
     const changedFields = buildChangedFields(copiedDocument.metadata, copiedDocument.body);
     const itemPath = getItemPath(pmRoot, copiedDocument.metadata.type, newId, settings.item_format, typeRegistry.type_to_folder);
     const historyPath = getHistoryPath(pmRoot, newId);
-    const lockRelease = await acquireLock(pmRoot, newId, settings.locks.ttl_seconds, author, false, settings.governance.force_required_for_stale_lock);
+    const lockRelease = await acquireLock(pmRoot, newId, settings.locks.ttl_seconds, author, false, settings.governance.force_required_for_stale_lock, settings.locks.wait_ms);
     const beforeDocument = {
         metadata: {},
         body: "",
@@ -158,4 +158,4 @@ export async function runCopy(sourceId, options, global) {
     };
 }
 //# sourceMappingURL=copy.js.map
-//# debugId=35ce2b1f-202f-57c1-a17d-95d1e7e06f19
+//# debugId=9f18adf2-5e40-5104-b7fa-5b5d77ffe54b

package/dist/cli/commands/copy.js.map

@@ -1 +1 @@
-{"version":3,"file":"copy.js","sources":["cli/commands/copy.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module cli/commands/copy\n *\n * Implements the pm copy command surface and its agent-facing runtime behavior.\n */\nimport { pathExists, removeFileIfExists, writeFileAtomic } from \"../../core/fs/fs-utils.js\";\nimport { appendHistoryEntry, createHistoryEntry } from \"../../core/history/history.js\";\nimport { generateItemId } from \"../../core/item/id.js\";\nimport { canonicalDocument, serializeItemDocument } from \"../../core/item/item-format.js\";\nimport { acquireLock } from \"../../core/lock/lock.js\";\nimport {\n  getActiveExtensionRegistrations,\n  projectAfterCommandItemSnapshot,\n  recordAfterCommandAffectedItem,\n  runActiveOnWriteHooks,\n} from \"../../core/extensions/index.js\";\nimport { collectRegisteredItemFieldNames } from \"../../core/extensions/item-fields.js\";\nimport { resolveRuntimeStatusRegistry } from \"../../core/schema/runtime-schema.js\";\nimport { EXIT_CODE, FRONT_MATTER_KEY_ORDER } from \"../../core/shared/constants.js\";\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { nowIso } from \"../../core/shared/time.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport { resolveItemTypeRegistry } from \"../../core/item/type-registry.js\";\nimport { buildItemNotFoundError, locateItem, readLocatedItem } from \"../../core/store/item-store.js\";\nimport { getHistoryPath, getItemPath, getSettingsPath, resolvePmRoot } from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\nimport type { ItemDocument, ItemMetadata } from \"../../types/index.js\";\n\n/**\n * Documents the copy options payload exchanged by command, SDK, and package integrations.\n */\nexport interface CopyOptions {\n  title?: string;\n  author?: string;\n  message?: string;\n}\n\n/**\n * Documents the copy result payload exchanged by command, SDK, and package integrations.\n */\nexport interface CopyResult {\n  source_id: string;\n  item: ItemMetadata;\n  changed_fields: string[];\n  warnings: string[];\n}\n\nfunction selectAuthor(explicitAuthor: string | undefined, settingsAuthor: string): string {\n  const candidate = explicitAuthor ?? process.env.PM_AUTHOR ?? settingsAuthor;\n  const trimmed = candidate.trim();\n  return trimmed.length > 0 ? trimmed : \"unknown\";\n}\n\nfunction buildChangedFields(frontMatter: ItemMetadata, body: string): string[] {\n  const changed = [\n    ...new Set([\n      ...FRONT_MATTER_KEY_ORDER.filter((key) => frontMatter[key] !== undefined),\n      ...Object.keys(frontMatter).filter((key) => frontMatter[key] !== undefined),\n      ...(body.length > 0 ? [\"body\"] : []),\n    ]),\n  ];\n  return changed.sort((left, right) => left.localeCompare(right));\n}\n\nfunction buildCopyMessage(sourceId: string, message: string | undefined): string {\n  const suffix = `copied_from=${sourceId}`;\n  if (!message) {\n    return suffix;\n  }\n  const trimmed = message.trim();\n  return trimmed.length > 0 ? `${trimmed} | ${suffix}` : suffix;\n}\n\n/**\n * Implements run copy for the public runtime surface of this module.\n */\nexport async function runCopy(sourceId: string, options: CopyOptions, global: GlobalOptions): Promise<CopyResult> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  if (!(await pathExists(getSettingsPath(pmRoot)))) {\n    throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);\n  }\n\n  const settings = await readSettings(pmRoot);\n  const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());\n  const located = await locateItem(pmRoot, sourceId, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);\n  if (!located) {\n    throw await buildItemNotFoundError(pmRoot, sourceId, settings.id_prefix, typeRegistry.type_to_folder);\n  }\n  const sourceLoaded = await readLocatedItem(located, { schema: settings.schema });\n  const sourceMetadata = sourceLoaded.document.metadata;\n  const copiedAt = nowIso();\n  const author = selectAuthor(options.author, settings.author_default);\n  const newId = await generateItemId(pmRoot, settings.id_prefix);\n  const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);\n  const titleOverride = options.title?.trim();\n  if (titleOverride !== undefined && titleOverride.length === 0) {\n    throw new PmCliError(\"Copy --title must not be empty\", EXIT_CODE.USAGE);\n  }\n\n  const copiedMetadata: ItemMetadata = {\n    ...(sourceMetadata as Record<string, unknown>),\n    id: newId,\n    title: titleOverride ?? sourceMetadata.title,\n    status: statusRegistry.open_status,\n    created_at: copiedAt,\n    updated_at: copiedAt,\n  } as ItemMetadata;\n  delete copiedMetadata.closed_at;\n  delete copiedMetadata.close_reason;\n  delete copiedMetadata.test_runs;\n\n  const extensionFieldNames = collectRegisteredItemFieldNames(getActiveExtensionRegistrations());\n  const copiedDocument = canonicalDocument(\n    {\n      metadata: copiedMetadata,\n      body: sourceLoaded.document.body,\n    },\n    {\n      schema: settings.schema,\n      extensionFieldNames,\n    },\n  );\n  const changedFields = buildChangedFields(copiedDocument.metadata, copiedDocument.body);\n  const itemPath = getItemPath(pmRoot, copiedDocument.metadata.type, newId, settings.item_format, typeRegistry.type_to_folder);\n  const historyPath = getHistoryPath(pmRoot, newId);\n  const lockRelease = await acquireLock(\n    pmRoot,\n    newId,\n    settings.locks.ttl_seconds,\n    author,\n    false,\n    settings.governance.force_required_for_stale_lock,\n  );\n  const beforeDocument: ItemDocument = {\n    metadata: {} as ItemMetadata,\n    body: \"\",\n  };\n\n  let hookWarnings: string[] = [];\n  try {\n    await writeFileAtomic(\n      itemPath,\n      serializeItemDocument(copiedDocument, {\n        format: settings.item_format,\n        schema: settings.schema,\n        extensionFieldNames,\n      }),\n    );\n    try {\n      const historyEntry = createHistoryEntry({\n        nowIso: copiedAt,\n        author,\n        op: \"create\",\n        before: beforeDocument,\n        after: copiedDocument,\n        message: buildCopyMessage(located.id, options.message),\n      });\n      await appendHistoryEntry(historyPath, historyEntry);\n    } catch (error: unknown) {\n      await removeFileIfExists(itemPath);\n      throw error;\n    }\n\n    hookWarnings = [\n      ...(await runActiveOnWriteHooks({\n        path: itemPath,\n        scope: \"project\",\n        op: \"create\",\n        item_id: copiedDocument.metadata.id,\n        item_type: copiedDocument.metadata.type,\n        before: beforeDocument,\n        after: copiedDocument,\n        changed_fields: changedFields,\n      })),\n      ...(await runActiveOnWriteHooks({\n        path: historyPath,\n        scope: \"project\",\n        op: \"create:history\",\n        item_id: copiedDocument.metadata.id,\n        item_type: copiedDocument.metadata.type,\n        before: beforeDocument,\n        after: copiedDocument,\n        changed_fields: changedFields,\n      })),\n    ];\n    recordAfterCommandAffectedItem({\n      id: copiedDocument.metadata.id,\n      op: \"create\",\n      item_type: copiedDocument.metadata.type,\n      status: copiedDocument.metadata.status,\n      current: projectAfterCommandItemSnapshot(copiedDocument.metadata, changedFields),\n      changed_fields: changedFields,\n    });\n  } finally {\n    await lockRelease();\n  }\n\n  return {\n    source_id: located.id,\n    item: structuredClone(copiedDocument.metadata),\n    changed_fields: changedFields,\n    warnings: hookWarnings,\n  };\n}\n"],"names":[],"mappings":"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","debugId":"35ce2b1f-202f-57c1-a17d-95d1e7e06f19"}
+{"version":3,"file":"copy.js","sources":["cli/commands/copy.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module cli/commands/copy\n *\n * Implements the pm copy command surface and its agent-facing runtime behavior.\n */\nimport { pathExists, removeFileIfExists, writeFileAtomic } from \"../../core/fs/fs-utils.js\";\nimport { appendHistoryEntry, createHistoryEntry } from \"../../core/history/history.js\";\nimport { generateItemId } from \"../../core/item/id.js\";\nimport { canonicalDocument, serializeItemDocument } from \"../../core/item/item-format.js\";\nimport { acquireLock } from \"../../core/lock/lock.js\";\nimport {\n  getActiveExtensionRegistrations,\n  projectAfterCommandItemSnapshot,\n  recordAfterCommandAffectedItem,\n  runActiveOnWriteHooks,\n} from \"../../core/extensions/index.js\";\nimport { collectRegisteredItemFieldNames } from \"../../core/extensions/item-fields.js\";\nimport { resolveRuntimeStatusRegistry } from \"../../core/schema/runtime-schema.js\";\nimport { EXIT_CODE, FRONT_MATTER_KEY_ORDER } from \"../../core/shared/constants.js\";\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { nowIso } from \"../../core/shared/time.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport { resolveItemTypeRegistry } from \"../../core/item/type-registry.js\";\nimport { buildItemNotFoundError, locateItem, readLocatedItem } from \"../../core/store/item-store.js\";\nimport { getHistoryPath, getItemPath, getSettingsPath, resolvePmRoot } from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\nimport type { ItemDocument, ItemMetadata } from \"../../types/index.js\";\n\n/**\n * Documents the copy options payload exchanged by command, SDK, and package integrations.\n */\nexport interface CopyOptions {\n  title?: string;\n  author?: string;\n  message?: string;\n}\n\n/**\n * Documents the copy result payload exchanged by command, SDK, and package integrations.\n */\nexport interface CopyResult {\n  source_id: string;\n  item: ItemMetadata;\n  changed_fields: string[];\n  warnings: string[];\n}\n\nfunction selectAuthor(explicitAuthor: string | undefined, settingsAuthor: string): string {\n  const candidate = explicitAuthor ?? process.env.PM_AUTHOR ?? settingsAuthor;\n  const trimmed = candidate.trim();\n  return trimmed.length > 0 ? trimmed : \"unknown\";\n}\n\nfunction buildChangedFields(frontMatter: ItemMetadata, body: string): string[] {\n  const changed = [\n    ...new Set([\n      ...FRONT_MATTER_KEY_ORDER.filter((key) => frontMatter[key] !== undefined),\n      ...Object.keys(frontMatter).filter((key) => frontMatter[key] !== undefined),\n      ...(body.length > 0 ? [\"body\"] : []),\n    ]),\n  ];\n  return changed.sort((left, right) => left.localeCompare(right));\n}\n\nfunction buildCopyMessage(sourceId: string, message: string | undefined): string {\n  const suffix = `copied_from=${sourceId}`;\n  if (!message) {\n    return suffix;\n  }\n  const trimmed = message.trim();\n  return trimmed.length > 0 ? `${trimmed} | ${suffix}` : suffix;\n}\n\n/**\n * Implements run copy for the public runtime surface of this module.\n */\nexport async function runCopy(sourceId: string, options: CopyOptions, global: GlobalOptions): Promise<CopyResult> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  if (!(await pathExists(getSettingsPath(pmRoot)))) {\n    throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);\n  }\n\n  const settings = await readSettings(pmRoot);\n  const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());\n  const located = await locateItem(pmRoot, sourceId, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);\n  if (!located) {\n    throw await buildItemNotFoundError(pmRoot, sourceId, settings.id_prefix, typeRegistry.type_to_folder);\n  }\n  const sourceLoaded = await readLocatedItem(located, { schema: settings.schema });\n  const sourceMetadata = sourceLoaded.document.metadata;\n  const copiedAt = nowIso();\n  const author = selectAuthor(options.author, settings.author_default);\n  const newId = await generateItemId(pmRoot, settings.id_prefix);\n  const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);\n  const titleOverride = options.title?.trim();\n  if (titleOverride !== undefined && titleOverride.length === 0) {\n    throw new PmCliError(\"Copy --title must not be empty\", EXIT_CODE.USAGE);\n  }\n\n  const copiedMetadata: ItemMetadata = {\n    ...(sourceMetadata as Record<string, unknown>),\n    id: newId,\n    title: titleOverride ?? sourceMetadata.title,\n    status: statusRegistry.open_status,\n    created_at: copiedAt,\n    updated_at: copiedAt,\n  } as ItemMetadata;\n  delete copiedMetadata.closed_at;\n  delete copiedMetadata.close_reason;\n  delete copiedMetadata.test_runs;\n\n  const extensionFieldNames = collectRegisteredItemFieldNames(getActiveExtensionRegistrations());\n  const copiedDocument = canonicalDocument(\n    {\n      metadata: copiedMetadata,\n      body: sourceLoaded.document.body,\n    },\n    {\n      schema: settings.schema,\n      extensionFieldNames,\n    },\n  );\n  const changedFields = buildChangedFields(copiedDocument.metadata, copiedDocument.body);\n  const itemPath = getItemPath(pmRoot, copiedDocument.metadata.type, newId, settings.item_format, typeRegistry.type_to_folder);\n  const historyPath = getHistoryPath(pmRoot, newId);\n  const lockRelease = await acquireLock(\n    pmRoot,\n    newId,\n    settings.locks.ttl_seconds,\n    author,\n    false,\n    settings.governance.force_required_for_stale_lock,\n    settings.locks.wait_ms,\n  );\n  const beforeDocument: ItemDocument = {\n    metadata: {} as ItemMetadata,\n    body: \"\",\n  };\n\n  let hookWarnings: string[] = [];\n  try {\n    await writeFileAtomic(\n      itemPath,\n      serializeItemDocument(copiedDocument, {\n        format: settings.item_format,\n        schema: settings.schema,\n        extensionFieldNames,\n      }),\n    );\n    try {\n      const historyEntry = createHistoryEntry({\n        nowIso: copiedAt,\n        author,\n        op: \"create\",\n        before: beforeDocument,\n        after: copiedDocument,\n        message: buildCopyMessage(located.id, options.message),\n      });\n      await appendHistoryEntry(historyPath, historyEntry);\n    } catch (error: unknown) {\n      await removeFileIfExists(itemPath);\n      throw error;\n    }\n\n    hookWarnings = [\n      ...(await runActiveOnWriteHooks({\n        path: itemPath,\n        scope: \"project\",\n        op: \"create\",\n        item_id: copiedDocument.metadata.id,\n        item_type: copiedDocument.metadata.type,\n        before: beforeDocument,\n        after: copiedDocument,\n        changed_fields: changedFields,\n      })),\n      ...(await runActiveOnWriteHooks({\n        path: historyPath,\n        scope: \"project\",\n        op: \"create:history\",\n        item_id: copiedDocument.metadata.id,\n        item_type: copiedDocument.metadata.type,\n        before: beforeDocument,\n        after: copiedDocument,\n        changed_fields: changedFields,\n      })),\n    ];\n    recordAfterCommandAffectedItem({\n      id: copiedDocument.metadata.id,\n      op: \"create\",\n      item_type: copiedDocument.metadata.type,\n      status: copiedDocument.metadata.status,\n      current: projectAfterCommandItemSnapshot(copiedDocument.metadata, changedFields),\n      changed_fields: changedFields,\n    });\n  } finally {\n    await lockRelease();\n  }\n\n  return {\n    source_id: located.id,\n    item: structuredClone(copiedDocument.metadata),\n    changed_fields: changedFields,\n    warnings: hookWarnings,\n  };\n}\n"],"names":[],"mappings":"AAAA;;;;GAIG;;;AACH,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5F,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACvF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAC1F,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EACL,+BAA+B,EAC/B,+BAA+B,EAC/B,8BAA8B,EAC9B,qBAAqB,GACtB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,+BAA+B,EAAE,MAAM,sCAAsC,CAAC;AACvF,OAAO,EAAE,4BAA4B,EAAE,MAAM,qCAAqC,CAAC;AACnF,OAAO,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAEnF,OAAO,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAC3E,OAAO,EAAE,sBAAsB,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACrG,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AACxG,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAsB5D,SAAS,YAAY,CAAC,cAAkC,EAAE,cAAsB;IAC9E,MAAM,SAAS,GAAG,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,cAAc,CAAC;IAC5E,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC;IACjC,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AAClD,CAAC;AAED,SAAS,kBAAkB,CAAC,WAAyB,EAAE,IAAY;IACjE,MAAM,OAAO,GAAG;QACd,GAAG,IAAI,GAAG,CAAC;YACT,GAAG,sBAAsB,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC;YACzE,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC;YAC3E,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;SACrC,CAAC;KACH,CAAC;IACF,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,SAAS,gBAAgB,CAAC,QAAgB,EAAE,OAA2B;IACrE,MAAM,MAAM,GAAG,eAAe,QAAQ,EAAE,CAAC;IACzC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAC/B,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,MAAM,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;AAChE,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,QAAgB,EAAE,OAAoB,EAAE,MAAqB;IACzF,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IACzD,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,UAAU,CAAC,iCAAiC,MAAM,sBAAsB,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC3G,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,MAAM,CAAC,CAAC;IAC5C,MAAM,YAAY,GAAG,uBAAuB,CAAC,QAAQ,EAAE,+BAA+B,EAAE,CAAC,CAAC;IAC1F,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,WAAW,EAAE,YAAY,CAAC,cAAc,CAAC,CAAC;IAC1H,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,MAAM,sBAAsB,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC,cAAc,CAAC,CAAC;IACxG,CAAC;IACD,MAAM,YAAY,GAAG,MAAM,eAAe,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACjF,MAAM,cAAc,GAAG,YAAY,CAAC,QAAQ,CAAC,QAAQ,CAAC;IACtD,MAAM,QAAQ,GAAG,MAAM,EAAE,CAAC;IAC1B,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;IACrE,MAAM,KAAK,GAAG,MAAM,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC/D,MAAM,cAAc,GAAG,4BAA4B,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACrE,MAAM,aAAa,GAAG,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC;IAC5C,IAAI,aAAa,KAAK,SAAS,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9D,MAAM,IAAI,UAAU,CAAC,gCAAgC,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;IAC1E,CAAC;IAED,MAAM,cAAc,GAAiB;QACnC,GAAI,cAA0C;QAC9C,EAAE,EAAE,KAAK;QACT,KAAK,EAAE,aAAa,IAAI,cAAc,CAAC,KAAK;QAC5C,MAAM,EAAE,cAAc,CAAC,WAAW;QAClC,UAAU,EAAE,QAAQ;QACpB,UAAU,EAAE,QAAQ;KACL,CAAC;IAClB,OAAO,cAAc,CAAC,SAAS,CAAC;IAChC,OAAO,cAAc,CAAC,YAAY,CAAC;IACnC,OAAO,cAAc,CAAC,SAAS,CAAC;IAEhC,MAAM,mBAAmB,GAAG,+BAA+B,CAAC,+BAA+B,EAAE,CAAC,CAAC;IAC/F,MAAM,cAAc,GAAG,iBAAiB,CACtC;QACE,QAAQ,EAAE,cAAc;QACxB,IAAI,EAAE,YAAY,CAAC,QAAQ,CAAC,IAAI;KACjC,EACD;QACE,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,mBAAmB;KACpB,CACF,CAAC;IACF,MAAM,aAAa,GAAG,kBAAkB,CAAC,cAAc,CAAC,QAAQ,EAAE,cAAc,CAAC,IAAI,CAAC,CAAC;IACvF,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,CAAC,WAAW,EAAE,YAAY,CAAC,cAAc,CAAC,CAAC;IAC7H,MAAM,WAAW,GAAG,cAAc,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAClD,MAAM,WAAW,GAAG,MAAM,WAAW,CACnC,MAAM,EACN,KAAK,EACL,QAAQ,CAAC,KAAK,CAAC,WAAW,EAC1B,MAAM,EACN,KAAK,EACL,QAAQ,CAAC,UAAU,CAAC,6BAA6B,EACjD,QAAQ,CAAC,KAAK,CAAC,OAAO,CACvB,CAAC;IACF,MAAM,cAAc,GAAiB;QACnC,QAAQ,EAAE,EAAkB;QAC5B,IAAI,EAAE,EAAE;KACT,CAAC;IAEF,IAAI,YAAY,GAAa,EAAE,CAAC;IAChC,IAAI,CAAC;QACH,MAAM,eAAe,CACnB,QAAQ,EACR,qBAAqB,CAAC,cAAc,EAAE;YACpC,MAAM,EAAE,QAAQ,CAAC,WAAW;YAC5B,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,mBAAmB;SACpB,CAAC,CACH,CAAC;QACF,IAAI,CAAC;YACH,MAAM,YAAY,GAAG,kBAAkB,CAAC;gBACtC,MAAM,EAAE,QAAQ;gBAChB,MAAM;gBACN,EAAE,EAAE,QAAQ;gBACZ,MAAM,EAAE,cAAc;gBACtB,KAAK,EAAE,cAAc;gBACrB,OAAO,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,OAAO,CAAC;aACvD,CAAC,CAAC;YACH,MAAM,kBAAkB,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;QACtD,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,MAAM,kBAAkB,CAAC,QAAQ,CAAC,CAAC;YACnC,MAAM,KAAK,CAAC;QACd,CAAC;QAED,YAAY,GAAG;YACb,GAAG,CAAC,MAAM,qBAAqB,CAAC;gBAC9B,IAAI,EAAE,QAAQ;gBACd,KAAK,EAAE,SAAS;gBAChB,EAAE,EAAE,QAAQ;gBACZ,OAAO,EAAE,cAAc,CAAC,QAAQ,CAAC,EAAE;gBACnC,SAAS,EAAE,cAAc,CAAC,QAAQ,CAAC,IAAI;gBACvC,MAAM,EAAE,cAAc;gBACtB,KAAK,EAAE,cAAc;gBACrB,cAAc,EAAE,aAAa;aAC9B,CAAC,CAAC;YACH,GAAG,CAAC,MAAM,qBAAqB,CAAC;gBAC9B,IAAI,EAAE,WAAW;gBACjB,KAAK,EAAE,SAAS;gBAChB,EAAE,EAAE,gBAAgB;gBACpB,OAAO,EAAE,cAAc,CAAC,QAAQ,CAAC,EAAE;gBACnC,SAAS,EAAE,cAAc,CAAC,QAAQ,CAAC,IAAI;gBACvC,MAAM,EAAE,cAAc;gBACtB,KAAK,EAAE,cAAc;gBACrB,cAAc,EAAE,aAAa;aAC9B,CAAC,CAAC;SACJ,CAAC;QACF,8BAA8B,CAAC;YAC7B,EAAE,EAAE,cAAc,CAAC,QAAQ,CAAC,EAAE;YAC9B,EAAE,EAAE,QAAQ;YACZ,SAAS,EAAE,cAAc,CAAC,QAAQ,CAAC,IAAI;YACvC,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,MAAM;YACtC,OAAO,EAAE,+BAA+B,CAAC,cAAc,CAAC,QAAQ,EAAE,aAAa,CAAC;YAChF,cAAc,EAAE,aAAa;SAC9B,CAAC,CAAC;IACL,CAAC;YAAS,CAAC;QACT,MAAM,WAAW,EAAE,CAAC;IACtB,CAAC;IAED,OAAO;QACL,SAAS,EAAE,OAAO,CAAC,EAAE;QACrB,IAAI,EAAE,eAAe,CAAC,cAAc,CAAC,QAAQ,CAAC;QAC9C,cAAc,EAAE,aAAa;QAC7B,QAAQ,EAAE,YAAY;KACvB,CAAC;AACJ,CAAC","debugId":"9f18adf2-5e40-5104-b7fa-5b5d77ffe54b"}

package/dist/cli/commands/create.d.ts

@@ -2,11 +2,12 @@ import { type ResolvedItemTypeDefinition } from "../../core/item/type-registry.j
 import { type RuntimeFieldRegistry } from "../../core/schema/runtime-schema.js";
 import type { GlobalOptions } from "../../core/shared/command-types.js";
 import { type LifecycleTransitionSuggestion } from "./lifecycle-transitions.js";
+import type { MutationMetadataCommandOptions, SharedLinkedResourceClearOptions, SharedLinkedResourceOptions } from "./mutation-command-options.js";
 import type { Comment, ItemMetadata, LinkedDoc, LinkedFile, LinkedTest, LogNote } from "../../types/index.js";
 /**
  * Documents the create command options payload exchanged by command, SDK, and package integrations.
  */
-export interface CreateCommandOptions {
+export interface CreateCommandOptions extends MutationMetadataCommandOptions, SharedLinkedResourceOptions, SharedLinkedResourceClearOptions {
     title?: string;
     description?: string;
     type?: string;
@@ -15,68 +16,10 @@ export interface CreateCommandOptions {
     tags?: string;
     addTags?: string[];
     body?: string;
-    deadline?: string;
-    estimatedMinutes?: string;
-    acceptanceCriteria?: string;
-    definitionOfReady?: string;
-    order?: string;
-    rank?: string;
-    goal?: string;
-    objective?: string;
-    value?: string;
-    impact?: string;
-    outcome?: string;
-    whyNow?: string;
-    author?: string;
-    message?: string;
-    assignee?: string;
-    parent?: string;
     allowMissingParent?: boolean;
-    reviewer?: string;
-    risk?: string;
-    confidence?: string;
-    sprint?: string;
-    release?: string;
-    blockedBy?: string;
-    blockedReason?: string;
-    unblockNote?: string;
-    reporter?: string;
-    severity?: string;
-    environment?: string;
-    reproSteps?: string;
-    resolution?: string;
-    expectedResult?: string;
-    actualResult?: string;
-    affectedVersion?: string;
-    fixedVersion?: string;
-    component?: string;
-    regression?: string;
-    customerImpact?: string;
-    dep?: string[];
-    comment?: string[];
-    note?: string[];
-    learning?: string[];
-    file?: string[];
-    test?: string[];
-    doc?: string[];
-    reminder?: string[];
-    event?: string[];
-    typeOption?: string[];
-    field?: string[];
     template?: string;
     createMode?: string;
     schedulePreset?: string;
-    unset?: string[];
-    clearDeps?: boolean;
-    clearComments?: boolean;
-    clearNotes?: boolean;
-    clearLearnings?: boolean;
-    clearFiles?: boolean;
-    clearTests?: boolean;
-    clearDocs?: boolean;
-    clearReminders?: boolean;
-    clearEvents?: boolean;
-    clearTypeOptions?: boolean;
     [key: string]: unknown;
 }
 /**
@@ -126,6 +69,12 @@ export declare function parseDocs(raw: string[] | undefined): {
 };
 declare function buildHistoryMessage(baseMessage: string | undefined, explicitUnsets: string[]): string | undefined;
 declare function normalizeCreatePolicyOptionKey(raw: string, typeName: string, sourceLabel: string): string;
+interface CreateOptionValueLookup {
+    scalarValues: Record<string, unknown>;
+    repeatableValues: Record<string, unknown>;
+    addTags: string[] | undefined;
+}
+declare function hasCreateOptionValue(lookup: CreateOptionValueLookup, optionKey: string): boolean;
 declare function collectMissingRequiredTypeOptionKeys(errors: string[], typeName: string): string[];
 declare function filterNonMissingTypeOptionErrors(errors: string[], typeName: string): string[];
 declare function typeOptionExampleValue(typeDefinition: ResolvedItemTypeDefinition, key: string): string;
@@ -149,6 +98,7 @@ export declare const _testOnlyCreateCommand: {
     createExampleTokensForFlag: typeof createExampleTokensForFlag;
     filterNonMissingTypeOptionErrors: typeof filterNonMissingTypeOptionErrors;
     hasTemplatesShowHandler: typeof hasTemplatesShowHandler;
+    hasCreateOptionValue: typeof hasCreateOptionValue;
     loadCreateTemplateOptionsFromRuntime: typeof loadCreateTemplateOptionsFromRuntime;
     looksLikeStructuredEntry: typeof looksLikeStructuredEntry;
     mergeCreateOptionsWithTemplate: typeof mergeCreateOptionsWithTemplate;

package/dist/cli/commands/create.js

@@ -4,12 +4,12 @@
  * Implements the pm create command surface and its agent-facing runtime behavior.
  */
 
-!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]="08a62e80-5fdd-53f6-8253-4f6eb6f166e9")}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]="f7516a2a-f728-55b0-99a6-50501443acb4")}catch(e){}}();
 import { pathExists, removeFileIfExists, writeFileAtomic } from "../../core/fs/fs-utils.js";
 import { appendHistoryEntry, createHistoryEntry } from "../../core/history/history.js";
 import { generateItemId, normalizeItemId } from "../../core/item/id.js";
 import { canonicalDocument, normalizeFrontMatter, serializeItemDocument } from "../../core/item/item-format.js";
-import { normalizeParentReferenceValue, validateMissingParentReference, } from "../../core/item/parent-reference-policy.js";
+import { assertParentReferenceIsNotSelf, isPlaceholderReferenceToken, normalizeParentReferenceValue, validateMissingParentReference, } from "../../core/item/parent-reference-policy.js";
 import { validateSprintOrReleaseValue } from "../../core/item/sprint-release-format.js";
 import { assertNoUnknownCsvKeys, createStdinTokenResolver, looksLikeGenericKeyValueEntry, mergeAdditiveTags, parseCsvKv, parseOptionalNumber, parseTags, } from "../../core/item/parse.js";
 import { resolvePriority } from "../../core/item/priority.js";
@@ -36,7 +36,7 @@ import { applyLegacyNoneCollectionNormalizers, assertNoLegacyNoneToken, assertNo
 import { suggestNextLifecycleTransition, } from "./lifecycle-transitions.js";
 import { parseLinkedTestAssertionEqualsMap, parseLinkedTestAssertionGteMap, parseLinkedTestBoolean, parseLinkedTestContextMode, parseLinkedTestEnvClear, parseLinkedTestEnvSet, parseLinkedTestMinLines, parseLinkedTestRegexList, parseLinkedTestStringList, } from "./linked-test-parsers.js";
 import { looksLikeStructuredLinkedTestEntry, normalizeStructuredLinkedTestEntry } from "./linked-test-entry.js";
-import { COMMON_UNSET_FIELD_DEFINITIONS_AFTER_AUTHOR, COMMON_UNSET_FIELD_DEFINITIONS_BEFORE_AUTHOR, resolveRuntimeUnsetFieldDefinition, } from "./shared-unset-fields.js";
+import { COMMON_UNSET_FIELD_DEFINITIONS_AFTER_AUTHOR, COMMON_UNSET_FIELD_DEFINITIONS_BEFORE_AUTHOR, parseCommandUnsetTargets, resolveRuntimeUnsetFieldDefinition, } from "./shared-unset-fields.js";
 import { ensureEnumValue } from "./recurrence-parsers.js";
 import { parseEventEntries, parseReminderEntries, parseTypeOptionEntries, } from "./repeatable-metadata-parsers.js";
 import { DEPENDENCY_KIND_VALUES, ISSUE_SEVERITY_VALUES, RISK_VALUES, SCOPE_VALUES, } from "../../types/index.js";
@@ -157,27 +157,11 @@ function parseOptionalString(value) {
     return value;
 }
 function parseCreateUnsetTargets(raw, runtimeFieldRegistry) {
-    const frontMatterKeys = new Set();
-    const optionKeys = new Set();
-    if (!raw || raw.length === 0) {
-        return { frontMatterKeys, optionKeys };
-    }
-    for (const entry of raw) {
-        const trimmed = entry.trim().toLowerCase();
-        if (!trimmed) {
-            throw new PmCliError("--unset values must not be empty", EXIT_CODE.USAGE);
-        }
-        if (isLegacyNoneToken(trimmed)) {
-            throw new PmCliError('--unset no longer accepts "none" or "null". Specify concrete field names such as --unset deadline', EXIT_CODE.USAGE);
-        }
-        const definition = CREATE_UNSET_ALIAS_MAP.get(trimmed) ?? resolveRuntimeUnsetFieldDefinition(trimmed, "create", runtimeFieldRegistry);
-        if (!definition) {
-            throw new PmCliError(`Unsupported --unset field "${entry}". Supported fields: ${CREATE_UNSET_SUPPORTED_CANONICAL_FIELDS}`, EXIT_CODE.USAGE);
-        }
-        frontMatterKeys.add(definition.frontMatterKey);
-        optionKeys.add(definition.optionKey);
-    }
-    return { frontMatterKeys, optionKeys };
+    return parseCommandUnsetTargets({
+        raw,
+        supportedFields: CREATE_UNSET_SUPPORTED_CANONICAL_FIELDS,
+        resolveDefinition: (trimmed) => CREATE_UNSET_ALIAS_MAP.get(trimmed) ?? resolveRuntimeUnsetFieldDefinition(trimmed, "create", runtimeFieldRegistry),
+    });
 }
 /** Allowed CSV/markdown keys for the create `--dep` seed (GH-258). */
 const DEP_SEED_KEYS = ["id", "kind", "type", "author", "created_at"];
@@ -432,6 +416,122 @@ function normalizeCreatePolicyOptionKey(raw, typeName, sourceLabel) {
     }
     return canonical;
 }
+function buildCreateOptionValueLookup(options) {
+    return {
+        scalarValues: {
+            title: options.title,
+            description: options.description,
+            type: options.type,
+            status: options.status,
+            priority: options.priority,
+            tags: options.tags,
+            body: options.body,
+            deadline: options.deadline,
+            estimatedMinutes: options.estimatedMinutes,
+            acceptanceCriteria: options.acceptanceCriteria,
+            definitionOfReady: options.definitionOfReady,
+            order: options.order ?? options.rank,
+            goal: options.goal,
+            objective: options.objective,
+            value: options.value,
+            impact: options.impact,
+            outcome: options.outcome,
+            whyNow: options.whyNow,
+            author: options.author,
+            message: options.message,
+            assignee: options.assignee,
+            parent: options.parent,
+            reviewer: options.reviewer,
+            risk: options.risk,
+            confidence: options.confidence,
+            sprint: options.sprint,
+            release: options.release,
+            blockedBy: options.blockedBy,
+            blockedReason: options.blockedReason,
+            unblockNote: options.unblockNote,
+            reporter: options.reporter,
+            severity: options.severity,
+            environment: options.environment,
+            reproSteps: options.reproSteps,
+            resolution: options.resolution,
+            expectedResult: options.expectedResult,
+            actualResult: options.actualResult,
+            affectedVersion: options.affectedVersion,
+            fixedVersion: options.fixedVersion,
+            component: options.component,
+            regression: options.regression,
+            customerImpact: options.customerImpact,
+        },
+        repeatableValues: {
+            dep: options.dep,
+            comment: options.comment,
+            note: options.note,
+            learning: options.learning,
+            file: options.file,
+            test: options.test,
+            doc: options.doc,
+            reminder: options.reminder,
+            event: options.event,
+            typeOption: options.typeOption,
+            field: options.field,
+        },
+        addTags: options.addTags,
+    };
+}
+function hasCreateOptionValue(lookup, optionKey) {
+    // `--add-tags` mutates the same `tags` field as `--tags`, so it must count
+    // toward the `tags` command_option_policy (both the disabled guard and the
+    // required check) — otherwise `--add-tags` would bypass a rule disabling
+    // tags, or fail to satisfy a rule requiring them even though the created
+    // item ends up tagged.
+    if (optionKey === "tags") {
+        return lookup.scalarValues.tags !== undefined || (Array.isArray(lookup.addTags) && lookup.addTags.length > 0);
+    }
+    if (Object.prototype.hasOwnProperty.call(lookup.scalarValues, optionKey)) {
+        return lookup.scalarValues[optionKey] !== undefined;
+    }
+    /* c8 ignore start -- policy probes only pass canonical CREATE_COMMAND_OPTION_KEYS, all of which exist in scalarValues/repeatableValues, so the in-repeatableValues false arm and trailing return are unreachable. */
+    if (Object.prototype.hasOwnProperty.call(lookup.repeatableValues, optionKey)) {
+        const value = lookup.repeatableValues[optionKey];
+        return Array.isArray(value) && value.length > 0;
+    }
+    return false;
+    /* c8 ignore stop */
+}
+function buildRequiredCreateOptions(typeDefinition, createMode) {
+    const requiredOptions = new Set(["title", "type"]);
+    if (createMode !== "strict") {
+        return requiredOptions;
+    }
+    for (const field of typeDefinition.required_create_fields) {
+        requiredOptions.add(normalizeCreatePolicyOptionKey(field, typeDefinition.name, "required_create_fields"));
+    }
+    for (const field of typeDefinition.required_create_repeatables) {
+        requiredOptions.add(normalizeCreatePolicyOptionKey(field, typeDefinition.name, "required_create_repeatables"));
+    }
+    return requiredOptions;
+}
+function assertNoDisabledCreateOptions(disabledOptions, lookup, clearOptionKeys, typeName) {
+    for (const option of disabledOptions) {
+        if (!hasCreateOptionValue(lookup, option) && !clearOptionKeys.has(option)) {
+            continue;
+        }
+        throw new PmCliError(`Option ${commandOptionFlagLabel("create", option)} is disabled for type "${typeName}" by command_option_policies`, EXIT_CODE.USAGE);
+    }
+}
+function assertNoStrictRequiredOptionClears(requiredOptions, createMode, clearOptionKeys) {
+    if (createMode !== "strict") {
+        return;
+    }
+    const strictRequiredClears = requiredOptions.filter((required) => clearOptionKeys.has(required));
+    if (strictRequiredClears.length === 0) {
+        return;
+    }
+    /* c8 ignore next -- deterministic ordering fallback only matters when required clear list contains locale ties. */
+    const requiredFlags = [...new Set(strictRequiredClears.map((required) => commandOptionFlagLabel("create", required)))].sort((left, right) => left.localeCompare(right));
+    /* c8 ignore next -- strict clear conflict envelope is covered by policy integration scenarios. */
+    throw new PmCliError(`Strict create mode requires concrete values for ${requiredFlags.join(", ")}; --unset/--clear-* directives cannot satisfy required options`, EXIT_CODE.USAGE);
+}
 function parseTypeOptions(raw) {
     if (!raw || raw.length === 0) {
         return { values: undefined, explicitEmpty: false };
@@ -499,112 +599,14 @@ function resolveEffectiveCreateMode(createMode, schedulePreset, defaultMode) {
 }
 function requireCreateOptionByType(typeDefinition, options, createMode, clearOptionKeys) {
     const typeName = typeDefinition.name;
-    const scalarValues = {
-        title: options.title,
-        description: options.description,
-        type: options.type,
-        status: options.status,
-        priority: options.priority,
-        tags: options.tags,
-        body: options.body,
-        deadline: options.deadline,
-        estimatedMinutes: options.estimatedMinutes,
-        acceptanceCriteria: options.acceptanceCriteria,
-        definitionOfReady: options.definitionOfReady,
-        order: options.order ?? options.rank,
-        goal: options.goal,
-        objective: options.objective,
-        value: options.value,
-        impact: options.impact,
-        outcome: options.outcome,
-        whyNow: options.whyNow,
-        author: options.author,
-        message: options.message,
-        assignee: options.assignee,
-        parent: options.parent,
-        reviewer: options.reviewer,
-        risk: options.risk,
-        confidence: options.confidence,
-        sprint: options.sprint,
-        release: options.release,
-        blockedBy: options.blockedBy,
-        blockedReason: options.blockedReason,
-        unblockNote: options.unblockNote,
-        reporter: options.reporter,
-        severity: options.severity,
-        environment: options.environment,
-        reproSteps: options.reproSteps,
-        resolution: options.resolution,
-        expectedResult: options.expectedResult,
-        actualResult: options.actualResult,
-        affectedVersion: options.affectedVersion,
-        fixedVersion: options.fixedVersion,
-        component: options.component,
-        regression: options.regression,
-        customerImpact: options.customerImpact,
-    };
-    const repeatableValues = {
-        dep: options.dep,
-        comment: options.comment,
-        note: options.note,
-        learning: options.learning,
-        file: options.file,
-        test: options.test,
-        doc: options.doc,
-        reminder: options.reminder,
-        event: options.event,
-        typeOption: options.typeOption,
-        field: options.field,
-    };
-    const hasOptionValue = (optionKey) => {
-        // `--add-tags` mutates the same `tags` field as `--tags`, so it must count
-        // toward the `tags` command_option_policy (both the disabled guard and the
-        // required check) — otherwise `--add-tags` would bypass a rule disabling
-        // tags, or fail to satisfy a rule requiring them even though the created
-        // item ends up tagged.
-        if (optionKey === "tags") {
-            return scalarValues.tags !== undefined || (Array.isArray(options.addTags) && options.addTags.length > 0);
-        }
-        if (optionKey in scalarValues) {
-            return scalarValues[optionKey] !== undefined;
-        }
-        /* c8 ignore start -- policy probes only pass canonical CREATE_COMMAND_OPTION_KEYS, all of which exist in scalarValues/repeatableValues, so the in-repeatableValues false arm and trailing return are unreachable. */
-        if (optionKey in repeatableValues) {
-            const value = repeatableValues[optionKey];
-            return Array.isArray(value) && value.length > 0;
-        }
-        return false;
-        /* c8 ignore stop */
-    };
-    /* c8 ignore next -- policy probes only pass normalized option keys in command-level tests. */
-    const hasOptionMutation = (optionKey) => hasOptionValue(optionKey) || clearOptionKeys.has(optionKey);
-    const baseRequiredOptions = new Set(["title", "type"]);
-    if (createMode === "strict") {
-        for (const field of typeDefinition.required_create_fields) {
-            baseRequiredOptions.add(normalizeCreatePolicyOptionKey(field, typeName, "required_create_fields"));
-        }
-        for (const field of typeDefinition.required_create_repeatables) {
-            baseRequiredOptions.add(normalizeCreatePolicyOptionKey(field, typeName, "required_create_repeatables"));
-        }
-    }
+    const optionLookup = buildCreateOptionValueLookup(options);
+    const baseRequiredOptions = buildRequiredCreateOptions(typeDefinition, createMode);
     const policyState = resolveCommandOptionPolicyState(typeDefinition, "create", baseRequiredOptions);
     if (policyState.errors.length > 0) {
         throw new PmCliError(policyState.errors.join("; "), EXIT_CODE.CONFLICT);
     }
-    for (const option of policyState.disabled) {
-        if (hasOptionMutation(option)) {
-            throw new PmCliError(`Option ${commandOptionFlagLabel("create", option)} is disabled for type "${typeName}" by command_option_policies`, EXIT_CODE.USAGE);
-        }
-    }
-    if (createMode === "strict") {
-        const strictRequiredClears = policyState.required.filter((required) => clearOptionKeys.has(required));
-        if (strictRequiredClears.length > 0) {
-            /* c8 ignore next -- deterministic ordering fallback only matters when required clear list contains locale ties. */
-            const requiredFlags = [...new Set(strictRequiredClears.map((required) => commandOptionFlagLabel("create", required)))].sort((left, right) => left.localeCompare(right));
-            /* c8 ignore next -- strict clear conflict envelope is covered by policy integration scenarios. */
-            throw new PmCliError(`Strict create mode requires concrete values for ${requiredFlags.join(", ")}; --unset/--clear-* directives cannot satisfy required options`, EXIT_CODE.USAGE);
-        }
-    }
+    assertNoDisabledCreateOptions(policyState.disabled, optionLookup, clearOptionKeys, typeName);
+    assertNoStrictRequiredOptionClears(policyState.required, createMode, clearOptionKeys);
     // A configured per-type default_status satisfies a required `status` policy:
     // when --status is omitted, runCreate resolves to that default (or degrades to
     // the workflow open status), so blocking the agent for a "missing --status"
@@ -615,7 +617,7 @@ function requireCreateOptionByType(typeDefinition, options, createMode, clearOpt
         if (optionKey === "status" && typeDefinition.default_status !== undefined) {
             return true;
         }
-        return hasOptionValue(optionKey);
+        return hasCreateOptionValue(optionLookup, optionKey);
     };
     const missingRequiredOptions = policyState.required.filter((required) => !satisfiesRequiredOption(required));
     return [...new Set(missingRequiredOptions.map((required) => commandOptionFlagLabel("create", required)))].sort((left, right) => left.localeCompare(right));
@@ -880,8 +882,9 @@ async function inheritFocusedParent(parent, resolvedOptions, unsetKeys, pmRoot)
  * value plus any never-blocking missing-parent warnings the configured
  * `parent_reference` policy produces when the target does not resolve.
  */
-async function validateCreateParentReference(pmRoot, settings, typeRegistry, parent, policy) {
+async function validateCreateParentReference(pmRoot, settings, typeRegistry, itemId, parent, policy) {
     const normalized = normalizeParentReferenceValue(parent);
+    assertParentReferenceIsNotSelf(itemId, normalized, settings.id_prefix);
     const parentLocated = await locateItem(pmRoot, normalized, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);
     if (parentLocated) {
         return { parent: normalized, warnings: [] };
@@ -893,9 +896,26 @@ async function resolveCreateParentWithWarnings(params) {
     if (params.parent === undefined) {
         return { parent: undefined, warnings: [] };
     }
-    const parentValidation = await validateCreateParentReference(params.pmRoot, params.settings, params.typeRegistry, params.parent, params.policy);
+    const parentValidation = await validateCreateParentReference(params.pmRoot, params.settings, params.typeRegistry, params.itemId, params.parent, params.policy);
     return parentValidation;
 }
+async function resolveCreateItemId(params) {
+    if (params.explicitId === undefined) {
+        return generateItemId(params.pmRoot, params.settings.id_prefix);
+    }
+    if (typeof params.explicitId !== "string") {
+        throw new PmCliError("--id must be a string", EXIT_CODE.USAGE);
+    }
+    const trimmedId = params.explicitId.trim();
+    if (trimmedId.length === 0 || isPlaceholderReferenceToken(trimmedId)) {
+        throw new PmCliError("--id must not be empty or use a placeholder token", EXIT_CODE.USAGE);
+    }
+    const normalizedId = normalizeItemId(trimmedId, params.settings.id_prefix);
+    if (!/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(normalizedId)) {
+        throw new PmCliError("--id must contain only letters, numbers, and dashes after normalization", EXIT_CODE.USAGE);
+    }
+    return normalizedId;
+}
 /**
  * Resolve a sprint or release field: `undefined` when cleared/absent, otherwise
  * the format-validated value plus any never-blocking format warnings from the
@@ -1284,9 +1304,13 @@ async function writeCreatedItem(params) {
     const { pmRoot, type, id, settings, typeRegistry, author, extensionFieldNames, afterDocument, beforeDocument, historyMessage, changedFields, nowValue } = params;
     const itemPath = getItemPath(pmRoot, type, id, settings.item_format, typeRegistry.type_to_folder);
     const historyPath = getHistoryPath(pmRoot, id);
-    const lockRelease = await acquireLock(pmRoot, id, settings.locks.ttl_seconds, author, false, settings.governance.force_required_for_stale_lock);
+    const lockRelease = await acquireLock(pmRoot, id, settings.locks.ttl_seconds, author, false, settings.governance.force_required_for_stale_lock, settings.locks.wait_ms);
     let hookWarnings = [];
     try {
+        const existing = await locateItem(pmRoot, id, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);
+        if (existing) {
+            throw new PmCliError(`Item "${id}" already exists`, EXIT_CODE.CONFLICT);
+        }
         await writeFileAtomic(itemPath, serializeItemDocument(afterDocument, { format: settings.item_format, schema: settings.schema, extensionFieldNames }));
         try {
             const entry = createHistoryEntry({ nowIso: nowValue, author, op: "create", before: beforeDocument, after: afterDocument, message: historyMessage });
@@ -1389,7 +1413,11 @@ export async function runCreate(options, global) {
         createMode,
     });
     assertNoInvalidTypeOptions(validatedTypeOptions.errors, type, typeDefinition, statusRegistry);
-    const id = await generateItemId(pmRoot, settings.id_prefix);
+    const id = await resolveCreateItemId({
+        pmRoot,
+        settings,
+        explicitId: resolvedOptions.id,
+    });
     let status = resolvedOptions.status !== undefined
         ? parseStatusValue(resolvedOptions.status, statusRegistry)
         : resolveCreateDefaultStatus(typeDefinition, statusRegistry);
@@ -1426,6 +1454,7 @@ export async function runCreate(options, global) {
     const sprintReleasePolicy = settings.validation.sprint_release_format;
     const validationWarnings = collectCreateScheduleWarnings(type, id, deadline, reminders.values, events.values);
     const parentValidation = await resolveCreateParentWithWarnings({
+        itemId: id,
         parent,
         pmRoot,
         settings,
@@ -1603,6 +1632,7 @@ export const _testOnlyCreateCommand = {
     createExampleTokensForFlag,
     filterNonMissingTypeOptionErrors,
     hasTemplatesShowHandler,
+    hasCreateOptionValue,
     loadCreateTemplateOptionsFromRuntime,
     looksLikeStructuredEntry,
     mergeCreateOptionsWithTemplate,
@@ -1616,4 +1646,4 @@ export const _testOnlyCreateCommand = {
     typeOptionExampleValue,
 };
 //# sourceMappingURL=create.js.map
-//# debugId=08a62e80-5fdd-53f6-8253-4f6eb6f166e9
+//# debugId=f7516a2a-f728-55b0-99a6-50501443acb4