@unbrained/pm-cli 2026.5.6 → 2026.5.10

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

@@ -1 +1 @@
-{"version":3,"file":"claim.js","sourceRoot":"/","sources":["cli/commands/claim.ts"],"names":[],"mappings":"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","sourcesContent":["import { pathExists } from \"../../core/fs/fs-utils.js\";\nimport { resolveRuntimeStatusRegistry, statusIsTerminal } from \"../../core/schema/runtime-schema.js\";\nimport { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport { mutateItem } from \"../../core/store/item-store.js\";\nimport { getSettingsPath, resolvePmRoot } from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\n\nexport interface ClaimResult {\n  item: Record<string, unknown>;\n  claimed_by: string;\n  previous_assignee: string | null;\n  forced: boolean;\n}\n\nexport interface ReleaseResult {\n  item: Record<string, unknown>;\n  released_by: string;\n  previous_assignee: string | null;\n  audit_release: boolean;\n  forced: boolean;\n}\n\nexport interface ClaimMutationOptions {\n  author?: string;\n  message?: string;\n}\n\nexport interface ReleaseMutationOptions extends ClaimMutationOptions {\n  allowAuditRelease?: boolean;\n}\n\nfunction resolveAuthor(candidate: string | undefined, fallback: string): string {\n  const resolved = candidate ?? process.env.PM_AUTHOR ?? fallback;\n  const trimmed = resolved.trim();\n  return trimmed || \"unknown\";\n}\n\nexport async function runClaim(\n  id: string,\n  force: boolean,\n  global: GlobalOptions,\n  options: ClaimMutationOptions = {},\n): Promise<ClaimResult> {\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  const settings = await readSettings(pmRoot);\n  const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);\n  const author = resolveAuthor(options.author, settings.author_default);\n  let previousAssignee: string | null = null;\n\n  const result = await mutateItem({\n    pmRoot,\n    settings,\n    id,\n    op: \"claim\",\n    author,\n    message: options.message,\n    force,\n    mutate(document) {\n      previousAssignee = document.front_matter.assignee ?? null;\n      if (statusIsTerminal(document.front_matter.status, statusRegistry) && !force) {\n        throw new PmCliError(`Cannot claim terminal item ${document.front_matter.id} without --force`, EXIT_CODE.CONFLICT);\n      }\n      document.front_matter.assignee = author;\n      return { changedFields: [\"assignee\"] };\n    },\n  });\n\n  return {\n    item: result.item as unknown as Record<string, unknown>,\n    claimed_by: author,\n    previous_assignee: previousAssignee,\n    forced: force,\n  };\n}\n\nexport async function runRelease(\n  id: string,\n  force: boolean,\n  global: GlobalOptions,\n  options: ReleaseMutationOptions = {},\n): Promise<ReleaseResult> {\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  const settings = await readSettings(pmRoot);\n  const author = resolveAuthor(options.author, settings.author_default);\n  let previousAssignee: string | null = null;\n\n  let result: Awaited<ReturnType<typeof mutateItem>>;\n  try {\n    result = await mutateItem({\n      pmRoot,\n      settings,\n      id,\n      op: \"release\",\n      author,\n      message: options.message,\n      force,\n      bypassAssigneeConflict: Boolean(options.allowAuditRelease),\n      mutate(document) {\n        previousAssignee = document.front_matter.assignee ?? null;\n        if (!previousAssignee) {\n          return { changedFields: [] };\n        }\n        delete document.front_matter.assignee;\n        return { changedFields: [\"assignee\"] };\n      },\n    });\n  } catch (error: unknown) {\n    if (\n      error instanceof PmCliError &&\n      error.exitCode === EXIT_CODE.CONFLICT &&\n      error.message.includes(\"is assigned to\") &&\n      error.message.includes(\"Use --force to override\")\n    ) {\n      throw new PmCliError(error.message, error.exitCode, {\n        code: \"ownership_conflict\",\n        required: \"For audited non-owner handoffs, prefer --allow-audit-release before considering --force.\",\n        examples: ['pm release pm-a1b2 --author \"reviewer\" --allow-audit-release'],\n        nextSteps: [\n          \"Use --allow-audit-release for append-only release handoffs that only clear assignee metadata.\",\n          \"Use --force only when an explicit override is approved for broader ownership conflicts.\",\n        ],\n      });\n    }\n    throw error;\n  }\n\n  return {\n    item: result.item as unknown as Record<string, unknown>,\n    released_by: author,\n    previous_assignee: previousAssignee,\n    audit_release: options.allowAuditRelease === true,\n    forced: force,\n  };\n}\n"]}
+{"version":3,"file":"claim.js","sourceRoot":"/","sources":["cli/commands/claim.ts"],"names":[],"mappings":"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","sourcesContent":["import { pathExists } from \"../../core/fs/fs-utils.js\";\nimport { resolveRuntimeStatusRegistry, statusIsTerminal } from \"../../core/schema/runtime-schema.js\";\nimport { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport { mutateItem } from \"../../core/store/item-store.js\";\nimport { getSettingsPath, resolvePmRoot } from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\n\nexport interface ClaimResult {\n  item: Record<string, unknown>;\n  claimed_by: string;\n  previous_assignee: string | null;\n  forced: boolean;\n}\n\nexport interface ReleaseResult {\n  item: Record<string, unknown>;\n  released_by: string;\n  previous_assignee: string | null;\n  audit_release: boolean;\n  forced: boolean;\n}\n\nexport interface ClaimMutationOptions {\n  author?: string;\n  message?: string;\n}\n\nexport interface ReleaseMutationOptions extends ClaimMutationOptions {\n  allowAuditRelease?: boolean;\n}\n\nfunction resolveAuthor(candidate: string | undefined, fallback: string): string {\n  const resolved = candidate ?? process.env.PM_AUTHOR ?? fallback;\n  const trimmed = resolved.trim();\n  return trimmed || \"unknown\";\n}\n\nexport async function runClaim(\n  id: string,\n  force: boolean,\n  global: GlobalOptions,\n  options: ClaimMutationOptions = {},\n): Promise<ClaimResult> {\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  const settings = await readSettings(pmRoot);\n  const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);\n  const author = resolveAuthor(options.author, settings.author_default);\n  let previousAssignee: string | null = null;\n\n  const result = await mutateItem({\n    pmRoot,\n    settings,\n    id,\n    op: \"claim\",\n    author,\n    message: options.message,\n    force,\n    mutate(document) {\n      previousAssignee = document.metadata.assignee ?? null;\n      if (statusIsTerminal(document.metadata.status, statusRegistry) && !force) {\n        throw new PmCliError(`Cannot claim terminal item ${document.metadata.id} without --force`, EXIT_CODE.CONFLICT);\n      }\n      document.metadata.assignee = author;\n      return { changedFields: [\"assignee\"] };\n    },\n  });\n\n  return {\n    item: result.item as unknown as Record<string, unknown>,\n    claimed_by: author,\n    previous_assignee: previousAssignee,\n    forced: force,\n  };\n}\n\nexport async function runRelease(\n  id: string,\n  force: boolean,\n  global: GlobalOptions,\n  options: ReleaseMutationOptions = {},\n): Promise<ReleaseResult> {\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  const settings = await readSettings(pmRoot);\n  const author = resolveAuthor(options.author, settings.author_default);\n  let previousAssignee: string | null = null;\n\n  let result: Awaited<ReturnType<typeof mutateItem>>;\n  try {\n    result = await mutateItem({\n      pmRoot,\n      settings,\n      id,\n      op: \"release\",\n      author,\n      message: options.message,\n      force,\n      bypassAssigneeConflict: Boolean(options.allowAuditRelease),\n      mutate(document) {\n        previousAssignee = document.metadata.assignee ?? null;\n        if (!previousAssignee) {\n          return { changedFields: [] };\n        }\n        delete document.metadata.assignee;\n        return { changedFields: [\"assignee\"] };\n      },\n    });\n  } catch (error: unknown) {\n    if (\n      error instanceof PmCliError &&\n      error.exitCode === EXIT_CODE.CONFLICT &&\n      error.message.includes(\"is assigned to\") &&\n      error.message.includes(\"Use --force to override\")\n    ) {\n      throw new PmCliError(error.message, error.exitCode, {\n        code: \"ownership_conflict\",\n        required: \"For audited non-owner handoffs, prefer --allow-audit-release before considering --force.\",\n        examples: ['pm release pm-a1b2 --author \"reviewer\" --allow-audit-release'],\n        nextSteps: [\n          \"Use --allow-audit-release for append-only release handoffs that only clear assignee metadata.\",\n          \"Use --force only when an explicit override is approved for broader ownership conflicts.\",\n        ],\n      });\n    }\n    throw error;\n  }\n\n  return {\n    item: result.item as unknown as Record<string, unknown>,\n    released_by: author,\n    previous_assignee: previousAssignee,\n    audit_release: options.allowAuditRelease === true,\n    forced: force,\n  };\n}\n"]}

package/dist/cli/commands/close.js

@@ -72,24 +72,24 @@ export async function runClose(id, closeReasonText, options, global) {
         message: options.message,
         force: options.force,
         mutate(document) {
-            if (isTerminal(document.front_matter.status, statusRegistry) && !options.force) {
-                throw new PmCliError(`Item ${document.front_matter.id} is already terminal; use --force to close again.`, EXIT_CODE.CONFLICT);
+            if (isTerminal(document.metadata.status, statusRegistry) && !options.force) {
+                throw new PmCliError(`Item ${document.metadata.id} is already terminal; use --force to close again.`, EXIT_CODE.CONFLICT);
             }
             const mutationWarnings = [];
             if (validateCloseMode !== "off") {
-                const missingFields = findMissingCloseValidationFields(document.front_matter);
+                const missingFields = findMissingCloseValidationFields(document.metadata);
                 if (missingFields.length > 0) {
                     if (validateCloseMode === "strict") {
-                        throw new PmCliError(`Cannot close item ${document.front_matter.id}: missing ${missingFields.join(", ")}. Populate fields or use --validate-close warn.`, EXIT_CODE.USAGE);
+                        throw new PmCliError(`Cannot close item ${document.metadata.id}: missing ${missingFields.join(", ")}. Populate fields or use --validate-close warn.`, EXIT_CODE.USAGE);
                     }
-                    mutationWarnings.push(`close_validation_missing_fields:${document.front_matter.id}:${missingFields.join(",")}`);
+                    mutationWarnings.push(`close_validation_missing_fields:${document.metadata.id}:${missingFields.join(",")}`);
                 }
             }
-            document.front_matter.status = statusRegistry.close_status;
-            document.front_matter.close_reason = closeReason;
+            document.metadata.status = statusRegistry.close_status;
+            document.metadata.close_reason = closeReason;
             const changedFields = ["status", "close_reason"];
-            if (document.front_matter.assignee !== undefined) {
-                delete document.front_matter.assignee;
+            if (document.metadata.assignee !== undefined) {
+                delete document.metadata.assignee;
                 changedFields.push("assignee");
             }
             return {

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

@@ -1 +1 @@
-{"version":3,"file":"close.js","sourceRoot":"/","sources":["cli/commands/close.ts"],"names":[],"mappings":"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","sourcesContent":["import { pathExists } from \"../../core/fs/fs-utils.js\";\nimport { normalizeStatusInput } from \"../../core/item/status.js\";\nimport { resolveRuntimeStatusRegistry, type RuntimeStatusRegistry } from \"../../core/schema/runtime-schema.js\";\nimport { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport { mutateItem } from \"../../core/store/item-store.js\";\nimport { getSettingsPath, resolvePmRoot } from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\nimport type { ItemFrontMatter, ItemStatus } from \"../../types/index.js\";\n\nexport interface CloseCommandOptions {\n  author?: string;\n  message?: string;\n  validateClose?: string;\n  force?: boolean;\n}\n\nexport interface CloseResult {\n  item: Record<string, unknown>;\n  changed_fields: string[];\n  warnings: string[];\n}\n\nfunction toAuthor(candidate: string | undefined, defaultAuthor: string): string {\n  const resolved = candidate ?? process.env.PM_AUTHOR ?? defaultAuthor;\n  const trimmed = resolved.trim();\n  return trimmed || \"unknown\";\n}\n\nfunction ensureCloseReason(reasonText: string): string {\n  const reason = reasonText.trim();\n  if (reason.length === 0) {\n    throw new PmCliError(\"Close reason text must not be empty\", EXIT_CODE.USAGE);\n  }\n  return reason;\n}\n\nfunction isTerminal(status: ItemStatus, statusRegistry: RuntimeStatusRegistry): boolean {\n  const normalized = normalizeStatusInput(status, statusRegistry) ?? status;\n  return statusRegistry.terminal_statuses.has(normalized);\n}\n\ntype ValidateCloseMode = \"off\" | \"warn\" | \"strict\";\n\nconst CLOSE_VALIDATION_FIELDS: Array<{ key: keyof Pick<ItemFrontMatter, \"resolution\" | \"expected_result\" | \"actual_result\">; label: string }> = [\n  { key: \"resolution\", label: \"resolution\" },\n  { key: \"expected_result\", label: \"expected_result\" },\n  { key: \"actual_result\", label: \"actual_result\" },\n];\n\nfunction parseValidateCloseMode(raw: string | undefined): ValidateCloseMode | undefined {\n  if (raw === undefined) {\n    return undefined;\n  }\n  const normalized = raw.trim().toLowerCase();\n  if (normalized.length === 0 || normalized === \"warn\") {\n    return \"warn\";\n  }\n  if (normalized === \"off\" || normalized === \"none\" || normalized === \"disabled\") {\n    return \"off\";\n  }\n  if (normalized === \"strict\") {\n    return \"strict\";\n  }\n  throw new PmCliError(`Invalid --validate-close mode \"${raw}\" (expected \"off\", \"warn\", or \"strict\")`, EXIT_CODE.USAGE);\n}\n\nfunction findMissingCloseValidationFields(frontMatter: ItemFrontMatter): string[] {\n  const missing: string[] = [];\n  for (const field of CLOSE_VALIDATION_FIELDS) {\n    const rawValue = frontMatter[field.key];\n    if (typeof rawValue !== \"string\" || rawValue.trim().length === 0) {\n      missing.push(field.label);\n    }\n  }\n  return missing;\n}\n\nexport async function runClose(\n  id: string,\n  closeReasonText: string,\n  options: CloseCommandOptions,\n  global: GlobalOptions,\n): Promise<CloseResult> {\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 statusRegistry = resolveRuntimeStatusRegistry(settings.schema);\n  const author = toAuthor(options.author, settings.author_default);\n  const closeReason = ensureCloseReason(closeReasonText);\n  const validateCloseMode = parseValidateCloseMode(options.validateClose) ?? settings.governance.close_validation_default;\n\n  const result = await mutateItem({\n    pmRoot,\n    settings,\n    id,\n    op: \"close\",\n    author,\n    message: options.message,\n    force: options.force,\n    mutate(document) {\n      if (isTerminal(document.front_matter.status, statusRegistry) && !options.force) {\n        throw new PmCliError(`Item ${document.front_matter.id} is already terminal; use --force to close again.`, EXIT_CODE.CONFLICT);\n      }\n      const mutationWarnings: string[] = [];\n      if (validateCloseMode !== \"off\") {\n        const missingFields = findMissingCloseValidationFields(document.front_matter);\n        if (missingFields.length > 0) {\n          if (validateCloseMode === \"strict\") {\n            throw new PmCliError(\n              `Cannot close item ${document.front_matter.id}: missing ${missingFields.join(\", \")}. Populate fields or use --validate-close warn.`,\n              EXIT_CODE.USAGE,\n            );\n          }\n          mutationWarnings.push(\n            `close_validation_missing_fields:${document.front_matter.id}:${missingFields.join(\",\")}`,\n          );\n        }\n      }\n\n      document.front_matter.status = statusRegistry.close_status;\n      document.front_matter.close_reason = closeReason;\n\n      const changedFields = [\"status\", \"close_reason\"];\n      if (document.front_matter.assignee !== undefined) {\n        delete document.front_matter.assignee;\n        changedFields.push(\"assignee\");\n      }\n\n      return {\n        changedFields,\n        ...(mutationWarnings.length > 0 ? { warnings: mutationWarnings } : {}),\n      };\n    },\n  });\n\n  return {\n    item: result.item as unknown as Record<string, unknown>,\n    changed_fields: result.changedFields,\n    warnings: result.warnings,\n  };\n}\n"]}
+{"version":3,"file":"close.js","sourceRoot":"/","sources":["cli/commands/close.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,4BAA4B,EAA8B,MAAM,qCAAqC,CAAC;AAC/G,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAE3D,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC3E,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAgB5D,SAAS,QAAQ,CAAC,SAA6B,EAAE,aAAqB;IACpE,MAAM,QAAQ,GAAG,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,aAAa,CAAC;IACrE,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;IAChC,OAAO,OAAO,IAAI,SAAS,CAAC;AAC9B,CAAC;AAED,SAAS,iBAAiB,CAAC,UAAkB;IAC3C,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC;IACjC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,UAAU,CAAC,qCAAqC,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,UAAU,CAAC,MAAkB,EAAE,cAAqC;IAC3E,MAAM,UAAU,GAAG,oBAAoB,CAAC,MAAM,EAAE,cAAc,CAAC,IAAI,MAAM,CAAC;IAC1E,OAAO,cAAc,CAAC,iBAAiB,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;AAC1D,CAAC;AAID,MAAM,uBAAuB,GAAmH;IAC9I,EAAE,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE;IAC1C,EAAE,GAAG,EAAE,iBAAiB,EAAE,KAAK,EAAE,iBAAiB,EAAE;IACpD,EAAE,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,eAAe,EAAE;CACjD,CAAC;AAEF,SAAS,sBAAsB,CAAC,GAAuB;IACrD,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,UAAU,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC5C,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,IAAI,UAAU,KAAK,MAAM,EAAE,CAAC;QACrD,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,UAAU,KAAK,KAAK,IAAI,UAAU,KAAK,MAAM,IAAI,UAAU,KAAK,UAAU,EAAE,CAAC;QAC/E,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,UAAU,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,MAAM,IAAI,UAAU,CAAC,kCAAkC,GAAG,yCAAyC,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;AACxH,CAAC;AAED,SAAS,gCAAgC,CAAC,WAA4B;IACpE,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,KAAK,IAAI,uBAAuB,EAAE,CAAC;QAC5C,MAAM,QAAQ,GAAG,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACjE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,EAAU,EACV,eAAuB,EACvB,OAA4B,EAC5B,MAAqB;IAErB,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,cAAc,GAAG,4BAA4B,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACrE,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;IACjE,MAAM,WAAW,GAAG,iBAAiB,CAAC,eAAe,CAAC,CAAC;IACvD,MAAM,iBAAiB,GAAG,sBAAsB,CAAC,OAAO,CAAC,aAAa,CAAC,IAAI,QAAQ,CAAC,UAAU,CAAC,wBAAwB,CAAC;IAExH,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC;QAC9B,MAAM;QACN,QAAQ;QACR,EAAE;QACF,EAAE,EAAE,OAAO;QACX,MAAM;QACN,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,MAAM,CAAC,QAAQ;YACb,IAAI,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;gBAC3E,MAAM,IAAI,UAAU,CAAC,QAAQ,QAAQ,CAAC,QAAQ,CAAC,EAAE,mDAAmD,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;YAC5H,CAAC;YACD,MAAM,gBAAgB,GAAa,EAAE,CAAC;YACtC,IAAI,iBAAiB,KAAK,KAAK,EAAE,CAAC;gBAChC,MAAM,aAAa,GAAG,gCAAgC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;gBAC1E,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAC7B,IAAI,iBAAiB,KAAK,QAAQ,EAAE,CAAC;wBACnC,MAAM,IAAI,UAAU,CAClB,qBAAqB,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,iDAAiD,EAC/H,SAAS,CAAC,KAAK,CAChB,CAAC;oBACJ,CAAC;oBACD,gBAAgB,CAAC,IAAI,CAAC,mCAAmC,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBAC9G,CAAC;YACH,CAAC;YAED,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,cAAc,CAAC,YAAY,CAAC;YACvD,QAAQ,CAAC,QAAQ,CAAC,YAAY,GAAG,WAAW,CAAC;YAE7C,MAAM,aAAa,GAAG,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;YACjD,IAAI,QAAQ,CAAC,QAAQ,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAC7C,OAAO,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBAClC,aAAa,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YACjC,CAAC;YAED,OAAO;gBACL,aAAa;gBACb,GAAG,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACvE,CAAC;QACJ,CAAC;KACF,CAAC,CAAC;IAEH,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAA0C;QACvD,cAAc,EAAE,MAAM,CAAC,aAAa;QACpC,QAAQ,EAAE,MAAM,CAAC,QAAQ;KAC1B,CAAC;AACJ,CAAC","sourcesContent":["import { pathExists } from \"../../core/fs/fs-utils.js\";\nimport { normalizeStatusInput } from \"../../core/item/status.js\";\nimport { resolveRuntimeStatusRegistry, type RuntimeStatusRegistry } from \"../../core/schema/runtime-schema.js\";\nimport { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport { mutateItem } from \"../../core/store/item-store.js\";\nimport { getSettingsPath, resolvePmRoot } from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\nimport type { ItemFrontMatter, ItemStatus } from \"../../types/index.js\";\n\nexport interface CloseCommandOptions {\n  author?: string;\n  message?: string;\n  validateClose?: string;\n  force?: boolean;\n}\n\nexport interface CloseResult {\n  item: Record<string, unknown>;\n  changed_fields: string[];\n  warnings: string[];\n}\n\nfunction toAuthor(candidate: string | undefined, defaultAuthor: string): string {\n  const resolved = candidate ?? process.env.PM_AUTHOR ?? defaultAuthor;\n  const trimmed = resolved.trim();\n  return trimmed || \"unknown\";\n}\n\nfunction ensureCloseReason(reasonText: string): string {\n  const reason = reasonText.trim();\n  if (reason.length === 0) {\n    throw new PmCliError(\"Close reason text must not be empty\", EXIT_CODE.USAGE);\n  }\n  return reason;\n}\n\nfunction isTerminal(status: ItemStatus, statusRegistry: RuntimeStatusRegistry): boolean {\n  const normalized = normalizeStatusInput(status, statusRegistry) ?? status;\n  return statusRegistry.terminal_statuses.has(normalized);\n}\n\ntype ValidateCloseMode = \"off\" | \"warn\" | \"strict\";\n\nconst CLOSE_VALIDATION_FIELDS: Array<{ key: keyof Pick<ItemFrontMatter, \"resolution\" | \"expected_result\" | \"actual_result\">; label: string }> = [\n  { key: \"resolution\", label: \"resolution\" },\n  { key: \"expected_result\", label: \"expected_result\" },\n  { key: \"actual_result\", label: \"actual_result\" },\n];\n\nfunction parseValidateCloseMode(raw: string | undefined): ValidateCloseMode | undefined {\n  if (raw === undefined) {\n    return undefined;\n  }\n  const normalized = raw.trim().toLowerCase();\n  if (normalized.length === 0 || normalized === \"warn\") {\n    return \"warn\";\n  }\n  if (normalized === \"off\" || normalized === \"none\" || normalized === \"disabled\") {\n    return \"off\";\n  }\n  if (normalized === \"strict\") {\n    return \"strict\";\n  }\n  throw new PmCliError(`Invalid --validate-close mode \"${raw}\" (expected \"off\", \"warn\", or \"strict\")`, EXIT_CODE.USAGE);\n}\n\nfunction findMissingCloseValidationFields(frontMatter: ItemFrontMatter): string[] {\n  const missing: string[] = [];\n  for (const field of CLOSE_VALIDATION_FIELDS) {\n    const rawValue = frontMatter[field.key];\n    if (typeof rawValue !== \"string\" || rawValue.trim().length === 0) {\n      missing.push(field.label);\n    }\n  }\n  return missing;\n}\n\nexport async function runClose(\n  id: string,\n  closeReasonText: string,\n  options: CloseCommandOptions,\n  global: GlobalOptions,\n): Promise<CloseResult> {\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 statusRegistry = resolveRuntimeStatusRegistry(settings.schema);\n  const author = toAuthor(options.author, settings.author_default);\n  const closeReason = ensureCloseReason(closeReasonText);\n  const validateCloseMode = parseValidateCloseMode(options.validateClose) ?? settings.governance.close_validation_default;\n\n  const result = await mutateItem({\n    pmRoot,\n    settings,\n    id,\n    op: \"close\",\n    author,\n    message: options.message,\n    force: options.force,\n    mutate(document) {\n      if (isTerminal(document.metadata.status, statusRegistry) && !options.force) {\n        throw new PmCliError(`Item ${document.metadata.id} is already terminal; use --force to close again.`, EXIT_CODE.CONFLICT);\n      }\n      const mutationWarnings: string[] = [];\n      if (validateCloseMode !== \"off\") {\n        const missingFields = findMissingCloseValidationFields(document.metadata);\n        if (missingFields.length > 0) {\n          if (validateCloseMode === \"strict\") {\n            throw new PmCliError(\n              `Cannot close item ${document.metadata.id}: missing ${missingFields.join(\", \")}. Populate fields or use --validate-close warn.`,\n              EXIT_CODE.USAGE,\n            );\n          }\n          mutationWarnings.push(`close_validation_missing_fields:${document.metadata.id}:${missingFields.join(\",\")}`);\n        }\n      }\n\n      document.metadata.status = statusRegistry.close_status;\n      document.metadata.close_reason = closeReason;\n\n      const changedFields = [\"status\", \"close_reason\"];\n      if (document.metadata.assignee !== undefined) {\n        delete document.metadata.assignee;\n        changedFields.push(\"assignee\");\n      }\n\n      return {\n        changedFields,\n        ...(mutationWarnings.length > 0 ? { warnings: mutationWarnings } : {}),\n      };\n    },\n  });\n\n  return {\n    item: result.item as unknown as Record<string, unknown>,\n    changed_fields: result.changedFields,\n    warnings: result.warnings,\n  };\n}\n"]}

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

@@ -2,6 +2,8 @@ import type { GlobalOptions } from "../../core/shared/command-types.js";
 import type { Comment } from "../../types/index.js";
 export interface CommentsCommandOptions {
     add?: string;
+    stdin?: boolean;
+    file?: string;
     limit?: string;
     author?: string;
     message?: string;

package/dist/cli/commands/comments.js

@@ -1,3 +1,4 @@
+import { readFile } from "node:fs/promises";
 import { pathExists } from "../../core/fs/fs-utils.js";
 import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
 import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
@@ -43,6 +44,53 @@ function parseCommentTextInput(raw) {
         return trimmed;
     }
 }
+function isErrnoError(error) {
+    return typeof error === "object" && error !== null && "code" in error;
+}
+async function resolveCommentInput(options, stdinResolver) {
+    const hasAdd = options.add !== undefined;
+    const hasStdin = options.stdin === true;
+    const hasFile = typeof options.file === "string";
+    const sourceCount = Number(hasAdd) + Number(hasStdin) + Number(hasFile);
+    if (sourceCount === 0) {
+        return { mode: "list" };
+    }
+    if (sourceCount > 1) {
+        throw new PmCliError("Specify comment text using only one input source: --add, --stdin, or --file", EXIT_CODE.USAGE);
+    }
+    if (hasAdd) {
+        const addInput = await stdinResolver.resolveValue(options.add, "--add");
+        return {
+            mode: "add",
+            value: addInput ?? "",
+        };
+    }
+    if (hasStdin) {
+        const stdinInput = await stdinResolver.resolveValue("-", "--stdin");
+        return {
+            mode: "stdin",
+            value: stdinInput ?? "",
+        };
+    }
+    const filePath = options.file?.trim() ?? "";
+    if (!filePath) {
+        throw new PmCliError("--file path cannot be empty", EXIT_CODE.USAGE);
+    }
+    try {
+        const fileInput = await readFile(filePath, "utf8");
+        return {
+            mode: "file",
+            value: fileInput,
+        };
+    }
+    catch (error) {
+        if (isErrnoError(error) && error.code === "ENOENT") {
+            throw new PmCliError(`--file path not found: ${filePath}`, EXIT_CODE.USAGE);
+        }
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new PmCliError(`Failed to read --file path "${filePath}": ${detail}`, EXIT_CODE.USAGE);
+    }
+}
 export async function runComments(id, options, global) {
     const stdinResolver = createStdinTokenResolver();
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
@@ -52,13 +100,14 @@ export async function runComments(id, options, global) {
     const settings = await readSettings(pmRoot);
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
     const limit = parseLimit(options.limit);
-    if (options.add === undefined) {
+    const commentInput = await resolveCommentInput(options, stdinResolver);
+    if (commentInput.mode === "list") {
         const located = await locateItem(pmRoot, id, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);
         if (!located) {
             throw new PmCliError(`Item ${id} not found`, EXIT_CODE.NOT_FOUND);
         }
         const loaded = await readLocatedItem(located, { schema: settings.schema });
-        const comments = limitComments(loaded.document.front_matter.comments ?? [], limit);
+        const comments = limitComments(loaded.document.metadata.comments ?? [], limit);
         return {
             id: located.id,
             comments,
@@ -66,10 +115,10 @@ export async function runComments(id, options, global) {
         };
     }
     const author = resolveAuthor(options.author, settings.author_default);
-    const addInput = await stdinResolver.resolveValue(options.add, "--add");
-    const text = parseCommentTextInput(addInput ?? "");
-    if (!text) {
-        throw new PmCliError("--add text cannot be empty", EXIT_CODE.USAGE);
+    const text = commentInput.mode === "add" ? parseCommentTextInput(commentInput.value ?? "") : (commentInput.value ?? "");
+    if (!text.trim()) {
+        const inputFlag = commentInput.mode === "add" ? "--add" : commentInput.mode === "stdin" ? "--stdin" : "--file";
+        throw new PmCliError(`${inputFlag} text cannot be empty`, EXIT_CODE.USAGE);
     }
     let result;
     try {
@@ -83,13 +132,13 @@ export async function runComments(id, options, global) {
             force: options.force,
             bypassAssigneeConflict: Boolean(options.allowAuditComment),
             mutate(document) {
-                const comments = document.front_matter.comments ?? [];
+                const comments = document.metadata.comments ?? [];
                 comments.push({
                     created_at: nowIso(),
                     author,
                     text,
                 });
-                document.front_matter.comments = comments;
+                document.metadata.comments = comments;
                 return { changedFields: ["comments"] };
             },
         });

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

@@ -1 +1 @@
-{"version":3,"file":"comments.js","sourceRoot":"/","sources":["cli/commands/comments.ts"],"names":[],"mappings":"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","sourcesContent":["import { pathExists } from \"../../core/fs/fs-utils.js\";\nimport { getActiveExtensionRegistrations } from \"../../core/extensions/index.js\";\nimport { resolveItemTypeRegistry } from \"../../core/item/type-registry.js\";\nimport { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport { nowIso } from \"../../core/shared/time.js\";\nimport { createStdinTokenResolver, parseCsvKv } from \"../../core/item/parse.js\";\nimport { locateItem, mutateItem, readLocatedItem } from \"../../core/store/item-store.js\";\nimport { getSettingsPath, resolvePmRoot } from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\nimport { parseLimit } from \"../shared-parsers.js\";\nimport type { Comment } from \"../../types/index.js\";\n\nexport interface CommentsCommandOptions {\n  add?: string;\n  limit?: string;\n  author?: string;\n  message?: string;\n  force?: boolean;\n  allowAuditComment?: boolean;\n}\n\nexport interface CommentsResult {\n  id: string;\n  comments: Comment[];\n  count: number;\n}\n\nfunction resolveAuthor(candidate: string | undefined, fallback: string): string {\n  const resolved = candidate ?? process.env.PM_AUTHOR ?? fallback;\n  const trimmed = resolved.trim();\n  return trimmed || \"unknown\";\n}\n\nfunction limitComments(values: Comment[], limit: number | undefined): Comment[] {\n  if (limit === undefined) return values;\n  if (limit === 0) return [];\n  return values.slice(Math.max(0, values.length - limit));\n}\n\nfunction parseCommentTextInput(raw: string): string {\n  const trimmed = raw.trim();\n  if (!trimmed) {\n    return \"\";\n  }\n  const looksStructured = /^(?:[-*+]\\s*)?text\\s*[:=]/im.test(trimmed) || trimmed.startsWith(\"```\");\n  if (!looksStructured) {\n    return trimmed;\n  }\n  try {\n    const kv = parseCsvKv(trimmed, \"--add\");\n    const keys = Object.keys(kv).map((key) => key.trim().toLowerCase());\n    if (keys.some((key) => key !== \"text\")) {\n      return trimmed;\n    }\n    const text = kv.text?.trim();\n    return text || trimmed;\n  } catch {\n    return trimmed;\n  }\n}\n\nexport async function runComments(id: string, options: CommentsCommandOptions, global: GlobalOptions): Promise<CommentsResult> {\n  const stdinResolver = createStdinTokenResolver();\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  const settings = await readSettings(pmRoot);\n  const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());\n  const limit = parseLimit(options.limit);\n\n  if (options.add === undefined) {\n    const located = await locateItem(pmRoot, id, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);\n    if (!located) {\n      throw new PmCliError(`Item ${id} not found`, EXIT_CODE.NOT_FOUND);\n    }\n    const loaded = await readLocatedItem(located, { schema: settings.schema });\n    const comments = limitComments(loaded.document.front_matter.comments ?? [], limit);\n    return {\n      id: located.id,\n      comments,\n      count: comments.length,\n    };\n  }\n\n  const author = resolveAuthor(options.author, settings.author_default);\n  const addInput = await stdinResolver.resolveValue(options.add, \"--add\");\n  const text = parseCommentTextInput(addInput ?? \"\");\n  if (!text) {\n    throw new PmCliError(\"--add text cannot be empty\", EXIT_CODE.USAGE);\n  }\n\n  let result: Awaited<ReturnType<typeof mutateItem>>;\n  try {\n    result = await mutateItem({\n      pmRoot,\n      settings,\n      id,\n      op: \"comment_add\",\n      author,\n      message: options.message,\n      force: options.force,\n      bypassAssigneeConflict: Boolean(options.allowAuditComment),\n      mutate(document) {\n        const comments = document.front_matter.comments ?? [];\n        comments.push({\n          created_at: nowIso(),\n          author,\n          text,\n        });\n        document.front_matter.comments = comments;\n        return { changedFields: [\"comments\"] };\n      },\n    });\n  } catch (error: unknown) {\n    if (\n      error instanceof PmCliError &&\n      error.exitCode === EXIT_CODE.CONFLICT &&\n      error.message.includes(\"is assigned to\") &&\n      error.message.includes(\"Use --force to override\")\n    ) {\n      throw new PmCliError(error.message, error.exitCode, {\n        code: \"ownership_conflict\",\n        required:\n          \"For append-only comment audits on another owner's item, prefer --allow-audit-comment before considering --force.\",\n        examples: ['pm comments pm-a1b2 --add \"audit note\" --author \"reviewer\" --allow-audit-comment'],\n        nextSteps: [\n          \"Retry with --allow-audit-comment for append-only audits that do not mutate item metadata beyond comments.\",\n          \"Use --force only when an ownership override is explicitly approved.\",\n        ],\n      });\n    }\n    throw error;\n  }\n\n  const comments = limitComments(result.item.comments as Comment[], limit);\n  return {\n    id: result.item.id,\n    comments,\n    count: comments.length,\n  };\n}\n"]}
+{"version":3,"file":"comments.js","sourceRoot":"/","sources":["cli/commands/comments.ts"],"names":[],"mappings":"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","sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { pathExists } from \"../../core/fs/fs-utils.js\";\nimport { getActiveExtensionRegistrations } from \"../../core/extensions/index.js\";\nimport { resolveItemTypeRegistry } from \"../../core/item/type-registry.js\";\nimport { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport { nowIso } from \"../../core/shared/time.js\";\nimport { createStdinTokenResolver, parseCsvKv } from \"../../core/item/parse.js\";\nimport { locateItem, mutateItem, readLocatedItem } from \"../../core/store/item-store.js\";\nimport { getSettingsPath, resolvePmRoot } from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\nimport { parseLimit } from \"../shared-parsers.js\";\nimport type { Comment } from \"../../types/index.js\";\n\nexport interface CommentsCommandOptions {\n  add?: string;\n  stdin?: boolean;\n  file?: string;\n  limit?: string;\n  author?: string;\n  message?: string;\n  force?: boolean;\n  allowAuditComment?: boolean;\n}\n\nexport interface CommentsResult {\n  id: string;\n  comments: Comment[];\n  count: number;\n}\n\nfunction resolveAuthor(candidate: string | undefined, fallback: string): string {\n  const resolved = candidate ?? process.env.PM_AUTHOR ?? fallback;\n  const trimmed = resolved.trim();\n  return trimmed || \"unknown\";\n}\n\nfunction limitComments(values: Comment[], limit: number | undefined): Comment[] {\n  if (limit === undefined) return values;\n  if (limit === 0) return [];\n  return values.slice(Math.max(0, values.length - limit));\n}\n\nfunction parseCommentTextInput(raw: string): string {\n  const trimmed = raw.trim();\n  if (!trimmed) {\n    return \"\";\n  }\n  const looksStructured = /^(?:[-*+]\\s*)?text\\s*[:=]/im.test(trimmed) || trimmed.startsWith(\"```\");\n  if (!looksStructured) {\n    return trimmed;\n  }\n  try {\n    const kv = parseCsvKv(trimmed, \"--add\");\n    const keys = Object.keys(kv).map((key) => key.trim().toLowerCase());\n    if (keys.some((key) => key !== \"text\")) {\n      return trimmed;\n    }\n    const text = kv.text?.trim();\n    return text || trimmed;\n  } catch {\n    return trimmed;\n  }\n}\n\ninterface ResolvedCommentInput {\n  mode: \"list\" | \"add\" | \"stdin\" | \"file\";\n  value?: string;\n}\n\nfunction isErrnoError(error: unknown): error is NodeJS.ErrnoException {\n  return typeof error === \"object\" && error !== null && \"code\" in error;\n}\n\nasync function resolveCommentInput(\n  options: CommentsCommandOptions,\n  stdinResolver: ReturnType<typeof createStdinTokenResolver>,\n): Promise<ResolvedCommentInput> {\n  const hasAdd = options.add !== undefined;\n  const hasStdin = options.stdin === true;\n  const hasFile = typeof options.file === \"string\";\n  const sourceCount = Number(hasAdd) + Number(hasStdin) + Number(hasFile);\n  if (sourceCount === 0) {\n    return { mode: \"list\" };\n  }\n  if (sourceCount > 1) {\n    throw new PmCliError(\"Specify comment text using only one input source: --add, --stdin, or --file\", EXIT_CODE.USAGE);\n  }\n  if (hasAdd) {\n    const addInput = await stdinResolver.resolveValue(options.add, \"--add\");\n    return {\n      mode: \"add\",\n      value: addInput ?? \"\",\n    };\n  }\n  if (hasStdin) {\n    const stdinInput = await stdinResolver.resolveValue(\"-\", \"--stdin\");\n    return {\n      mode: \"stdin\",\n      value: stdinInput ?? \"\",\n    };\n  }\n  const filePath = options.file?.trim() ?? \"\";\n  if (!filePath) {\n    throw new PmCliError(\"--file path cannot be empty\", EXIT_CODE.USAGE);\n  }\n  try {\n    const fileInput = await readFile(filePath, \"utf8\");\n    return {\n      mode: \"file\",\n      value: fileInput,\n    };\n  } catch (error: unknown) {\n    if (isErrnoError(error) && error.code === \"ENOENT\") {\n      throw new PmCliError(`--file path not found: ${filePath}`, EXIT_CODE.USAGE);\n    }\n    const detail = error instanceof Error ? error.message : String(error);\n    throw new PmCliError(`Failed to read --file path \"${filePath}\": ${detail}`, EXIT_CODE.USAGE);\n  }\n}\n\nexport async function runComments(id: string, options: CommentsCommandOptions, global: GlobalOptions): Promise<CommentsResult> {\n  const stdinResolver = createStdinTokenResolver();\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  const settings = await readSettings(pmRoot);\n  const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());\n  const limit = parseLimit(options.limit);\n  const commentInput = await resolveCommentInput(options, stdinResolver);\n\n  if (commentInput.mode === \"list\") {\n    const located = await locateItem(pmRoot, id, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);\n    if (!located) {\n      throw new PmCliError(`Item ${id} not found`, EXIT_CODE.NOT_FOUND);\n    }\n    const loaded = await readLocatedItem(located, { schema: settings.schema });\n    const comments = limitComments(loaded.document.metadata.comments ?? [], limit);\n    return {\n      id: located.id,\n      comments,\n      count: comments.length,\n    };\n  }\n\n  const author = resolveAuthor(options.author, settings.author_default);\n  const text = commentInput.mode === \"add\" ? parseCommentTextInput(commentInput.value ?? \"\") : (commentInput.value ?? \"\");\n  if (!text.trim()) {\n    const inputFlag = commentInput.mode === \"add\" ? \"--add\" : commentInput.mode === \"stdin\" ? \"--stdin\" : \"--file\";\n    throw new PmCliError(`${inputFlag} text cannot be empty`, EXIT_CODE.USAGE);\n  }\n\n  let result: Awaited<ReturnType<typeof mutateItem>>;\n  try {\n    result = await mutateItem({\n      pmRoot,\n      settings,\n      id,\n      op: \"comment_add\",\n      author,\n      message: options.message,\n      force: options.force,\n      bypassAssigneeConflict: Boolean(options.allowAuditComment),\n      mutate(document) {\n        const comments = document.metadata.comments ?? [];\n        comments.push({\n          created_at: nowIso(),\n          author,\n          text,\n        });\n        document.metadata.comments = comments;\n        return { changedFields: [\"comments\"] };\n      },\n    });\n  } catch (error: unknown) {\n    if (\n      error instanceof PmCliError &&\n      error.exitCode === EXIT_CODE.CONFLICT &&\n      error.message.includes(\"is assigned to\") &&\n      error.message.includes(\"Use --force to override\")\n    ) {\n      throw new PmCliError(error.message, error.exitCode, {\n        code: \"ownership_conflict\",\n        required:\n          \"For append-only comment audits on another owner's item, prefer --allow-audit-comment before considering --force.\",\n        examples: ['pm comments pm-a1b2 --add \"audit note\" --author \"reviewer\" --allow-audit-comment'],\n        nextSteps: [\n          \"Retry with --allow-audit-comment for append-only audits that do not mutate item metadata beyond comments.\",\n          \"Use --force only when an ownership override is explicitly approved.\",\n        ],\n      });\n    }\n    throw error;\n  }\n\n  const comments = limitComments(result.item.comments as Comment[], limit);\n  return {\n    id: result.item.id,\n    comments,\n    count: comments.length,\n  };\n}\n"]}

package/dist/cli/commands/completion.js

@@ -1,7 +1,8 @@
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
-import { ACTIVITY_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CREATE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, NORMALIZE_FLAG_CONTRACTS, PM_CORE_COMMAND_NAMES, SEARCH_FLAG_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, toCompletionFlagString, } from "../../sdk/cli-contracts.js";
+import { ACTIVITY_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CREATE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, NORMALIZE_FLAG_CONTRACTS, PM_CORE_COMMAND_NAMES, SEARCH_FLAG_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, toCompletionFlagString, } from "../../sdk/cli-contracts.js";
 import { BUILTIN_ITEM_TYPE_VALUES } from "../../types/index.js";
+import { listGuideTopicIds } from "../guide-topics.js";
 const VALID_SHELLS = ["bash", "zsh", "fish"];
 const DEFAULT_ITEM_TYPES = [...BUILTIN_ITEM_TYPE_VALUES];
 const DEFAULT_STATUS_VALUES = ["draft", "open", "in_progress", "blocked", "closed", "canceled"];
@@ -16,12 +17,14 @@ const ACTIVITY_FLAGS = toCompletionFlagString(ACTIVITY_FLAG_CONTRACTS);
 const CALENDAR_FLAGS = toCompletionFlagString(CALENDAR_FLAG_CONTRACTS);
 const CONTEXT_FLAGS = toCompletionFlagString(CONTEXT_FLAG_CONTRACTS);
 const DEPS_FLAGS = toCompletionFlagString(DEPS_FLAG_CONTRACTS);
+const GUIDE_FLAGS = toCompletionFlagString(GUIDE_FLAG_CONTRACTS);
 const SEARCH_FLAGS = toCompletionFlagString(SEARCH_FLAG_CONTRACTS);
 const HEALTH_FLAGS = toCompletionFlagString(HEALTH_FLAG_CONTRACTS);
 const INIT_FLAGS = toCompletionFlagString(INIT_FLAG_CONTRACTS);
 const CONTRACTS_FLAGS = toCompletionFlagString(CONTRACTS_FLAG_CONTRACTS);
 const COMPLETION_FLAGS = toCompletionFlagString(COMPLETION_FLAG_CONTRACTS);
 const COMPLETION_SHELL_CHOICES = `${COMPLETION_FLAGS} bash zsh fish`;
+const GUIDE_TOPIC_CHOICES = joinCompletionValues(listGuideTopicIds());
 const MUTATION_FLAGS = "--author --message --force --json --quiet --path --no-extensions --no-pager --profile --help";
 const CLOSE_MUTATION_FLAGS = "--author --message --validate-close --force --json --quiet --path --no-extensions --no-pager --profile --help";
 const RELEASE_MUTATION_FLAGS = "--allow-audit-release --author --message --force --json --quiet --path --no-extensions --no-pager --profile --help";
@@ -135,6 +138,9 @@ export function generateBashScript(itemTypes = DEFAULT_ITEM_TYPES, tags = [], ea
         "    context|ctx)",
         `      COMPREPLY=(${compgen(contextFlags)})`,
         "      ;;",
+        "    guide)",
+        `      COMPREPLY=(${compgen(`${GUIDE_FLAGS} ${GUIDE_TOPIC_CHOICES}`)})`,
+        "      ;;",
         "    search)",
         `      COMPREPLY=(${compgen(searchFlags)})`,
         "      ;;",
@@ -151,7 +157,7 @@ export function generateBashScript(itemTypes = DEFAULT_ITEM_TYPES, tags = [], ea
         `      COMPREPLY=(${compgen("init scaffold install uninstall explore manage doctor adopt adopt-all activate deactivate --init --scaffold --install --uninstall --explore --manage --doctor --adopt --adopt-all --activate --deactivate --project --local --global --gh --github --ref --detail --trace --runtime-probe --fix-managed-state --strict-exit --fail-on-warn --json --quiet --path --no-extensions --no-pager --profile --help")})`,
         "      ;;",
         "    comments)",
-        `      COMPREPLY=(${compgen("--add --limit --author --message --allow-audit-comment --force --json --quiet --path --no-extensions --no-pager --profile --help")})`,
+        `      COMPREPLY=(${compgen("--add --stdin --file --limit --author --message --allow-audit-comment --force --json --quiet --path --no-extensions --no-pager --profile --help")})`,
         "      ;;",
         "    comments-audit)",
         `      COMPREPLY=(${compgen("--status --type --tag --priority --parent --sprint --release --assignee --assignee-filter --limit-items --limit --full-history --latest --json --quiet --path --no-extensions --no-pager --profile --help")})`,
@@ -229,6 +235,7 @@ export function generateBashScript(itemTypes = DEFAULT_ITEM_TYPES, tags = [], ea
 export function generateZshScript(itemTypes = DEFAULT_ITEM_TYPES, tags = [], eagerTagExpansion = false) {
     const cmds = ALL_COMMANDS.map((c) => `'${c}'`).join(" ");
     const typeChoices = itemTypes.join(" ");
+    const guideTopicChoices = GUIDE_TOPIC_CHOICES;
     const tagChoices = joinCompletionValues(tags);
     const useEagerTagExpansion = eagerTagExpansion || tags.length > 0;
     const zshTagChoices = useEagerTagExpansion ? tagChoices : '${(f)"$(_pm_tag_choices)"}';
@@ -270,6 +277,7 @@ _pm_commands() {
     'list-canceled:List canceled items with optional filters'
     'aggregate:Aggregate grouped item counts for governance queries'
     'dedupe-audit:Audit potential duplicate items and emit merge suggestions'
+    'guide:Browse local progressive-disclosure guides'
     'calendar:Show calendar views for deadlines and reminders'
     'cal:Alias for calendar'
     'context:Show a token-efficient project context snapshot'
@@ -615,6 +623,15 @@ _pm() {
             '--json[Output JSON]' \\
             '--quiet[Suppress stdout]'
           ;;
+        guide)
+          _arguments \\
+            '1:topic:(${guideTopicChoices})' \\
+            '--list[Show guide topic index]' \\
+            '--format[Output override]:(markdown toon json)' \\
+            '--depth[Guide detail depth]:(brief standard deep)' \\
+            '--json[Output JSON]' \\
+            '--quiet[Suppress stdout]'
+          ;;
         search)
           _arguments \\
             '--mode[Search mode]:(keyword semantic hybrid)' \\
@@ -675,6 +692,8 @@ _pm() {
         comments)
           _arguments \\
             '--add[Add one entry (plain text, text=<value>, markdown pairs, or - for stdin)]:text' \\
+            '--stdin[Read comment text from stdin (supports multiline markdown)]' \\
+            '--file[Read comment text from file (supports multiline markdown)]:path' \\
             '--limit[Return only latest n entries]:number' \\
             '--author[Entry author (falls back to PM_AUTHOR/settings)]:author' \\
             '--message[History message]:message' \\
@@ -791,7 +810,7 @@ _pm() {
           _arguments \\
             '--criterion[Criteria value for definition-of-done metadata-required-fields or lifecycle pattern keys (repeatable for set)]:criterion' \\
             '--clear-criteria[Clear config criteria-list key values]' \\
-            '--format[Item format for item-format key]:format:(toon json_markdown)' \\
+            '--format[Item format for item-format key]:format:(toon)' \\
             '--policy[Policy value for supported policy keys]:policy' \\
             '--json[Output JSON]' \\
             '--quiet[Suppress stdout]'
@@ -939,6 +958,7 @@ export function generateFishScript(itemTypes = DEFAULT_ITEM_TYPES, tags = [], ea
     const listCmds = ALL_COMMANDS.filter((command) => command === "list" || command.startsWith("list-")).join(" ");
     const noSubcommandList = ALL_COMMANDS.join(" ");
     const typeChoices = itemTypes.join(" ");
+    const guideTopicChoices = GUIDE_TOPIC_CHOICES;
     const tagChoices = joinCompletionValues(tags);
     const useEagerTagExpansion = eagerTagExpansion || tags.length > 0;
     const fishTagChoices = useEagerTagExpansion ? `'${tagChoices}'` : "'(__pm_tag_choices)'";
@@ -1004,6 +1024,7 @@ complete -c pm -n __pm_no_subcommand -a list-closed   -d 'List closed items with
 complete -c pm -n __pm_no_subcommand -a list-canceled -d 'List canceled items with optional filters'
 complete -c pm -n __pm_no_subcommand -a aggregate     -d 'Aggregate grouped item counts for governance queries'
 complete -c pm -n __pm_no_subcommand -a dedupe-audit  -d 'Audit potential duplicate items and emit merge suggestions'
+complete -c pm -n __pm_no_subcommand -a guide         -d 'Browse local progressive-disclosure guides'
 complete -c pm -n __pm_no_subcommand -a calendar      -d 'Show deadline/reminder calendar views'
 complete -c pm -n __pm_no_subcommand -a cal           -d 'Alias for calendar'
 complete -c pm -n __pm_no_subcommand -a context       -d 'Show a token-efficient project context snapshot'
@@ -1308,6 +1329,12 @@ complete -c pm -n '__fish_seen_subcommand_from context ctx' -l release   -d 'Fil
 complete -c pm -n '__fish_seen_subcommand_from context ctx' -l limit     -d 'Limit focus and agenda rows per section' -r
 complete -c pm -n '__fish_seen_subcommand_from context ctx' -l format    -d 'Output override' -r -a 'markdown toon json'
 
+# guide flags
+complete -c pm -n '__fish_seen_subcommand_from guide' -l list      -d 'Show guide topic index'
+complete -c pm -n '__fish_seen_subcommand_from guide' -l format    -d 'Output override' -r -a 'markdown toon json'
+complete -c pm -n '__fish_seen_subcommand_from guide' -l depth     -d 'Guide detail depth' -r -a 'brief standard deep'
+complete -c pm -n '__fish_seen_subcommand_from guide' -a '${guideTopicChoices}' -d 'Guide topic'
+
 # reindex flags
 complete -c pm -n '__fish_seen_subcommand_from reindex' -l mode -d 'Reindex mode' -r -a 'keyword semantic hybrid'
 complete -c pm -n '__fish_seen_subcommand_from reindex' -l progress -d 'Emit progress updates to stderr'
@@ -1337,6 +1364,8 @@ complete -c pm -n '__fish_seen_subcommand_from deps' -l summary -d 'Return count
 
 # comments / notes / learnings flags
 complete -c pm -n '__fish_seen_subcommand_from comments notes learnings' -l add -d 'Add one entry (text=<value> or plain text)' -r
+complete -c pm -n '__fish_seen_subcommand_from comments' -l stdin -d 'Read comment text from stdin (supports multiline markdown)'
+complete -c pm -n '__fish_seen_subcommand_from comments' -l file -d 'Read comment text from file (supports multiline markdown)' -r
 complete -c pm -n '__fish_seen_subcommand_from comments notes learnings' -l limit -d 'Return only latest n entries' -r
 complete -c pm -n '__fish_seen_subcommand_from comments notes learnings' -l author -d 'Entry author' -r
 complete -c pm -n '__fish_seen_subcommand_from comments notes learnings' -l message -d 'History message' -r
@@ -1430,7 +1459,7 @@ complete -c pm -n '__fish_seen_subcommand_from validate' -l check-command-refere
 complete -c pm -n '__fish_seen_subcommand_from init' -l preset -d 'Governance preset for new setups' -r -a 'minimal default strict'
 complete -c pm -n '__fish_seen_subcommand_from config' -l criterion -d 'Criteria value for definition-of-done metadata-required-fields or lifecycle pattern keys (repeatable for set)' -r
 complete -c pm -n '__fish_seen_subcommand_from config' -l clear-criteria -d 'Clear config criteria-list key values'
-complete -c pm -n '__fish_seen_subcommand_from config' -l format -d 'Item format for item-format key' -r -a 'toon json_markdown'
+complete -c pm -n '__fish_seen_subcommand_from config' -l format -d 'Item format for item-format key' -r -a 'toon'
 complete -c pm -n '__fish_seen_subcommand_from config' -l policy -d 'Policy value for supported policy keys' -r
 complete -c pm -n '__fish_seen_subcommand_from health' -l strict-directories -d 'Treat optional item-type directories as required failures'
 complete -c pm -n '__fish_seen_subcommand_from health' -l check-only -d 'Run read-only health diagnostics without refreshing vectors'