@unbrained/pm-cli 2026.6.19 → 2026.6.21

package/dist/cli-bundle/chunks/{chunk-K5TD74VU.js → chunk-J4MYYSOL.js}

@@ -6,16 +6,19 @@ import {
   createStdinTokenResolver,
   looksLikeGenericKeyValueEntry,
   parseCsvKv
-} from "./chunk-VG3B2CYD.js";
+} from "./chunk-UV6IYE5U.js";
+import {
+  splitCommaList
+} from "./chunk-5HIZDR5A.js";
 import {
   listAllFrontMatter,
   locateItem,
   mutateItem,
   readLocatedItem
-} from "./chunk-X7RKOJXL.js";
+} from "./chunk-SX75ADBK.js";
 import {
   resolveItemTypeRegistry
-} from "./chunk-SO2IOH37.js";
+} from "./chunk-FRUFKWNK.js";
 import {
   EXIT_CODE,
   PmCliError,
@@ -25,7 +28,7 @@ import {
   pathExists,
   readSettings,
   resolvePmRoot
-} from "./chunk-5QLHQK7V.js";
+} from "./chunk-HMOADQVT.js";
 
 // dist/cli/commands/linked-artifacts.js
 import fs from "node:fs/promises";
@@ -34,7 +37,7 @@ import fg from "fast-glob";
 !(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] = "605627c6-5263-59a0-9afa-e8d1c54c8f93");
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "cea5b020-7acc-5139-8d8e-619d60c06105");
   } catch (e2) {
   }
 })();
@@ -59,10 +62,19 @@ function looksLikeStructuredPathEntry(raw) {
   }
   return looksLikeGenericKeyValueEntry(raw);
 }
+function expandBareCommaSeparatedAddEntries(raw) {
+  return raw.flatMap((entry) => {
+    const trimmed = entry.trim();
+    if (trimmed.length === 0 || looksLikeStructuredPathEntry(trimmed) || !trimmed.includes(",")) {
+      return [entry];
+    }
+    return splitCommaList(trimmed);
+  });
+}
 function parseAddEntries(raw, bareNoun) {
   if (!raw)
     return [];
-  return raw.map((entry) => {
+  return expandBareCommaSeparatedAddEntries(raw).map((entry) => {
     const trimmed = entry.trim();
     const kv = looksLikeStructuredPathEntry(trimmed) ? parseCsvKv(entry, "--add") : { path: trimmed };
     assertNoUnknownCsvKeys(kv, "--add", LINKED_ARTIFACT_ADD_KEYS);
@@ -377,4 +389,4 @@ export {
   runLinkedArtifacts,
   renameArtifactsResultKey
 };
-//# sourceMappingURL=chunk-K5TD74VU.js.map
+//# sourceMappingURL=chunk-J4MYYSOL.js.map

package/dist/cli-bundle/chunks/chunk-J4MYYSOL.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../../../cli/commands/linked-artifacts.ts"],
+  "sourcesContent": ["/**\n * @module cli/commands/linked-artifacts\n *\n * Implements the pm linked artifacts command surface and its agent-facing runtime behavior.\n */\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport fg from \"fast-glob\";\nimport { pathExists } from \"../../core/fs/fs-utils.js\";\nimport { getActiveExtensionRegistrations } from \"../../core/extensions/index.js\";\nimport {\n  assertNoUnknownCsvKeys,\n  createStdinTokenResolver,\n  looksLikeGenericKeyValueEntry,\n  parseCsvKv,\n} from \"../../core/item/parse.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 { splitCommaList } from \"../../core/shared/split-comma-list.js\";\nimport { listAllFrontMatter, 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 { SCOPE_VALUES } from \"../../types/index.js\";\nimport { resolveAuthor } from \"../../core/shared/author.js\";\nimport type { LinkScope } from \"../../types/index.js\";\n\n/**\n * Restricts linked artifact values accepted by command, SDK, and storage contracts.\n */\nexport type LinkedArtifact = {\n  path: string;\n  scope: LinkScope;\n  note?: string;\n};\n\n/** Allowed CSV/markdown keys for each structured linked-artifact option (GH-258). */\nexport const LINKED_ARTIFACT_ADD_KEYS = [\"path\", \"scope\", \"note\"] as const;\nexport const LINKED_ARTIFACT_ADD_GLOB_KEYS = [\"pattern\", \"glob\", \"path\", \"scope\", \"note\"] as const;\nexport const LINKED_ARTIFACT_REMOVE_KEYS = [\"path\"] as const;\nexport const LINKED_ARTIFACT_MIGRATE_KEYS = [\"from\", \"to\"] as const;\n/**\n * Keys that are valid on --add but meaningless on --remove (GH-277). Rejected\n * with audit-trail guidance (--message) rather than the generic unknown-key\n * error so agents are not left believing a removal note was recorded.\n */\nconst LINKED_ARTIFACT_REMOVE_UNSUPPORTED_KEYS: ReadonlySet<string> = new Set([\"note\", \"scope\"]);\n\n/**\n * Documents the linked artifact command options payload exchanged by command, SDK, and package integrations.\n */\nexport interface LinkedArtifactCommandOptions {\n  add?: string[];\n  addGlob?: string[];\n  remove?: string[];\n  migrate?: string[];\n  /**\n   * GH-170 (pm-pfnx): standalone note applied to every link added by --add /\n   * --add-glob in the same invocation. A per-entry embedded note (the\n   * `path=...,note=...` pair syntax) takes precedence over this flag.\n   * Requires at least one --add/--add-glob; rejected otherwise.\n   */\n  note?: string;\n  list?: boolean;\n  appendStable?: boolean;\n  validatePaths?: boolean;\n  audit?: boolean;\n  author?: string;\n  message?: string;\n  force?: boolean;\n}\n\n/**\n * Documents the path migration payload exchanged by command, SDK, and package integrations.\n */\nexport interface PathMigration {\n  from: string;\n  to: string;\n}\n\n/**\n * Documents the add glob entry payload exchanged by command, SDK, and package integrations.\n */\nexport interface AddGlobEntry {\n  pattern: string;\n  scope: LinkScope;\n  note?: string;\n}\n\n/**\n * Documents the linked path validation payload exchanged by command, SDK, and package integrations.\n */\nexport interface LinkedPathValidation {\n  checked: number;\n  existing_files: string[];\n  missing_paths: string[];\n  non_file_paths: string[];\n}\n\n/**\n * Documents the linked path audit entry payload exchanged by command, SDK, and package integrations.\n */\nexport interface LinkedPathAuditEntry {\n  path: string;\n  linked_by_count: number;\n  linked_item_ids: string[];\n}\n\n/**\n * Documents the linked artifact result payload exchanged by command, SDK, and package integrations.\n */\nexport interface LinkedArtifactResult {\n  id: string;\n  changed: boolean;\n  count: number;\n  migrations_applied?: number;\n  validation?: LinkedPathValidation;\n  audit?: LinkedPathAuditEntry[];\n  artifacts: LinkedArtifact[];\n}\n\n/**\n * Configuration that adapts the shared linked-artifact command core to a\n * specific resource kind (files or docs) while preserving every behavioral\n * detail of the original twin implementations.\n */\nexport interface LinkedArtifactKindConfig {\n  /** Metadata key under which the artifacts are stored (e.g. \"files\" | \"docs\"). */\n  metadataKey: \"files\" | \"docs\";\n  /** Mutation op recorded in history (e.g. \"files_add\" | \"docs_add\"). */\n  op: \"files_add\" | \"docs_add\";\n  /** Noun used in the \"bare <noun> path\" --add usage error (e.g. \"file\" | \"doc\"). */\n  bareNoun: \"file\" | \"doc\";\n  /**\n   * Whether this kind honors the append-stable option. files supports it;\n   * docs always sorts and must never expose append-stable behavior.\n   */\n  supportsAppendStable: boolean;\n}\n\n/**\n * Implements ensure scope for the public runtime surface of this module.\n */\nexport function ensureScope(raw: string | undefined): LinkScope {\n  const value = (raw ?? \"project\") as LinkScope;\n  if (!SCOPE_VALUES.includes(value)) {\n    throw new PmCliError(\n      `Invalid scope \"${raw}\". Valid scopes: ${SCOPE_VALUES.join(\", \")} (default: project).`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  return value;\n}\n\n/**\n * Implements looks like structured path entry for the public runtime surface of this module.\n */\nexport function looksLikeStructuredPathEntry(raw: string): boolean {\n  if (raw.startsWith(\"```\") || raw.includes(\"\\n\")) {\n    return true;\n  }\n  if (/^(?:[-*+]\\s+)?(?:path|scope|note)\\s*[:=]/i.test(raw)) {\n    return true;\n  }\n  // A first-key typo (e.g. `lable=main,path=…`) must still be parsed so the\n  // unknown key is rejected rather than swallowed as a bare path (GH-258).\n  return looksLikeGenericKeyValueEntry(raw);\n}\n\nfunction expandBareCommaSeparatedAddEntries(raw: string[]): string[] {\n  return raw.flatMap((entry) => {\n    const trimmed = entry.trim();\n    if (trimmed.length === 0 || looksLikeStructuredPathEntry(trimmed) || !trimmed.includes(\",\")) {\n      return [entry];\n    }\n    return splitCommaList(trimmed);\n  });\n}\n\n/**\n * Implements parse add entries for the public runtime surface of this module.\n */\nexport function parseAddEntries(raw: string[] | undefined, bareNoun: \"file\" | \"doc\"): LinkedArtifact[] {\n  if (!raw) return [];\n  return expandBareCommaSeparatedAddEntries(raw).map((entry) => {\n    const trimmed = entry.trim();\n    const kv = looksLikeStructuredPathEntry(trimmed) ? parseCsvKv(entry, \"--add\") : { path: trimmed };\n    assertNoUnknownCsvKeys(kv, \"--add\", LINKED_ARTIFACT_ADD_KEYS);\n    if (!kv.path) {\n      throw new PmCliError(`--add requires path=<value> or a bare ${bareNoun} path`, EXIT_CODE.USAGE);\n    }\n    return {\n      path: kv.path,\n      scope: ensureScope(kv.scope),\n      note: kv.note?.trim() || undefined,\n    };\n  });\n}\n\n/**\n * Implements parse add glob entries for the public runtime surface of this module.\n */\nexport function parseAddGlobEntries(raw: string[] | undefined): AddGlobEntry[] {\n  if (!raw) return [];\n  return raw.map((entry) => {\n    const trimmed = entry.trim();\n    if (!trimmed) {\n      throw new PmCliError(\"--add-glob requires a glob pattern value\", EXIT_CODE.USAGE);\n    }\n    if (trimmed.includes(\"=\") || /^(?:[-*+]\\s+)?(?:pattern|glob|path)\\s*[:=]/i.test(trimmed) || trimmed.startsWith(\"```\")) {\n      const kv = parseCsvKv(trimmed, \"--add-glob\");\n      assertNoUnknownCsvKeys(kv, \"--add-glob\", LINKED_ARTIFACT_ADD_GLOB_KEYS);\n      const pattern = kv.pattern?.trim() || kv.glob?.trim() || kv.path?.trim();\n      if (!pattern) {\n        throw new PmCliError(\"--add-glob key/value form requires pattern=<glob>\", EXIT_CODE.USAGE);\n      }\n      return {\n        pattern,\n        scope: ensureScope(kv.scope),\n        note: kv.note?.trim() || undefined,\n      };\n    }\n    return {\n      pattern: trimmed,\n      scope: \"project\",\n    };\n  });\n}\n\n/**\n * Implements parse remove entries for the public runtime surface of this module.\n */\nexport function parseRemoveEntries(raw: string[] | undefined): string[] {\n  if (!raw) return [];\n  return raw.map((entry) => {\n    const trimmed = entry.trim();\n    if (!trimmed) {\n      throw new PmCliError(\"--remove requires a path value\", EXIT_CODE.USAGE);\n    }\n    if (trimmed.includes(\"=\") || /^(?:[-*+]\\s+)?path\\s*[:=]/i.test(trimmed) || trimmed.startsWith(\"```\")) {\n      const kv = parseCsvKv(trimmed, \"--remove\");\n      // GH-277: --remove identifies an existing link by path only; it does not\n      // attach per-link metadata. Reject the --add-only keys with guidance toward\n      // the audit-trail path (--message) rather than the generic \"unrecognized\n      // key\" error, which left agents believing they had recorded a removal note.\n      const unsupportedRemoveKeys = Object.keys(kv).filter((key) =>\n        LINKED_ARTIFACT_REMOVE_UNSUPPORTED_KEYS.has(key.toLowerCase()),\n      );\n      if (unsupportedRemoveKeys.length > 0) {\n        throw new PmCliError(\n          `--remove identifies a linked artifact by path only and does not accept ${unsupportedRemoveKeys\n            .map((key) => `\"${key}\"`)\n            .join(\", \")}. Pass just the path (path=<value>, path:<value>, or a bare path); record removal context with --message \"<why removed>\".`,\n          EXIT_CODE.USAGE,\n        );\n      }\n      assertNoUnknownCsvKeys(kv, \"--remove\", LINKED_ARTIFACT_REMOVE_KEYS);\n      if (!kv.path) {\n        throw new PmCliError(\"--remove key/value form requires path=<value>\", EXIT_CODE.USAGE);\n      }\n      return kv.path;\n    }\n    return trimmed;\n  });\n}\n\n/**\n * Implements parse migrate entries for the public runtime surface of this module.\n */\nexport function parseMigrateEntries(raw: string[] | undefined): PathMigration[] {\n  if (!raw) return [];\n  return raw.map((entry) => {\n    const kv = parseCsvKv(entry, \"--migrate\");\n    assertNoUnknownCsvKeys(kv, \"--migrate\", LINKED_ARTIFACT_MIGRATE_KEYS);\n    const from = kv.from?.trim();\n    const to = kv.to?.trim();\n    if (!from || !to) {\n      throw new PmCliError(\"--migrate requires from=<value> and to=<value>\", EXIT_CODE.USAGE);\n    }\n    return { from, to };\n  });\n}\n\n/**\n * Implements apply path migrations for the public runtime surface of this module.\n */\nexport function applyPathMigrations(artifactPath: string, migrations: PathMigration[]): string {\n  let next = artifactPath;\n  for (const migration of migrations) {\n    if (next.startsWith(migration.from)) {\n      next = `${migration.to}${next.slice(migration.from.length)}`;\n    }\n  }\n  return next;\n}\n\n/**\n * Implements normalize linked path for the public runtime surface of this module.\n */\nexport function normalizeLinkedPath(value: string): string {\n  return value.split(path.sep).join(\"/\");\n}\n\n/**\n * Implements expand add glob entries for the public runtime surface of this module.\n */\nexport async function expandAddGlobEntries(entries: AddGlobEntry[]): Promise<LinkedArtifact[]> {\n  const expanded: LinkedArtifact[] = [];\n  for (const entry of entries) {\n    const absolutePattern = path.isAbsolute(entry.pattern);\n    const matches = await fg(entry.pattern, {\n      cwd: process.cwd(),\n      absolute: absolutePattern,\n      onlyFiles: true,\n      dot: true,\n      unique: true,\n      followSymbolicLinks: true,\n    });\n    const sortedMatches = [...new Set(matches.map((match) => normalizeLinkedPath(path.normalize(match))))].sort((left, right) =>\n      left.localeCompare(right),\n    );\n    for (const matchedPath of sortedMatches) {\n      expanded.push({\n        path: matchedPath,\n        scope: entry.scope,\n        note: entry.note,\n      });\n    }\n  }\n  return expanded;\n}\n\n/**\n * GH-170 (pm-pfnx): apply a standalone --note to the links added in this\n * invocation. Semantics (documented on pm-pfnx): the note is attached to EVERY\n * entry added via --add/--add-glob so a single flag annotates the whole batch\n * predictably; a per-entry embedded `note=` wins over the standalone flag; and\n * --note without any --add/--add-glob flag is a usage error because there is\n * nothing to annotate (it never retro-edits existing links). `hasAddFlags`\n * reflects flag presence, not match count, so a glob that legitimately matches\n * zero files is not an error.\n */\nexport function applyStandaloneNote(\n  adds: LinkedArtifact[],\n  note: string | undefined,\n  hasAddFlags: boolean,\n): LinkedArtifact[] {\n  if (note === undefined) {\n    return adds;\n  }\n  if (!hasAddFlags) {\n    throw new PmCliError(\n      \"--note requires --add or --add-glob in the same invocation (the note annotates the links being added)\",\n      EXIT_CODE.USAGE,\n    );\n  }\n  const trimmed = note.trim();\n  if (trimmed.length === 0) {\n    return adds;\n  }\n  return adds.map((entry) => (entry.note === undefined ? { ...entry, note: trimmed } : entry));\n}\n\n/**\n * Implements artifact key for the public runtime surface of this module.\n */\nexport function artifactKey(value: Pick<LinkedArtifact, \"path\" | \"scope\">): string {\n  return `${value.path}::${value.scope}`;\n}\n\n/**\n * Implements sort linked artifacts for the public runtime surface of this module.\n */\nexport function sortLinkedArtifacts(artifacts: LinkedArtifact[]): LinkedArtifact[] {\n  return [...artifacts].sort((left, right) => {\n    const byPath = left.path.localeCompare(right.path);\n    if (byPath !== 0) return byPath;\n    return left.scope.localeCompare(right.scope);\n  });\n}\n\n/**\n * Implements dedupe linked artifacts for the public runtime surface of this module.\n */\nexport function dedupeLinkedArtifacts(artifacts: LinkedArtifact[]): LinkedArtifact[] {\n  return [...new Map(artifacts.map((entry) => [artifactKey(entry), entry])).values()].map((entry) => ({\n    ...entry,\n    note: entry.note?.trim() || undefined,\n  }));\n}\n\n/**\n * Implements validate linked paths for the public runtime surface of this module.\n */\nexport async function validateLinkedPaths(paths: string[]): Promise<LinkedPathValidation> {\n  const uniquePaths = [...new Set(paths)].sort((left, right) => left.localeCompare(right));\n  const existingFiles: string[] = [];\n  const missingPaths: string[] = [];\n  const nonFilePaths: string[] = [];\n  for (const relativePath of uniquePaths) {\n    const resolvedPath = path.isAbsolute(relativePath) ? relativePath : path.resolve(process.cwd(), relativePath);\n    try {\n      const stats = await fs.stat(resolvedPath);\n      if (stats.isFile()) {\n        existingFiles.push(relativePath);\n      } else {\n        nonFilePaths.push(relativePath);\n      }\n    } catch (error: unknown) {\n      if (typeof error === \"object\" && error !== null && \"code\" in error && (error as { code?: string }).code === \"ENOENT\") {\n        missingPaths.push(relativePath);\n        continue;\n      }\n      nonFilePaths.push(relativePath);\n    }\n  }\n  return {\n    checked: uniquePaths.length,\n    existing_files: existingFiles,\n    missing_paths: missingPaths,\n    non_file_paths: nonFilePaths,\n  };\n}\n\n/**\n * Implements build linked path audit for the public runtime surface of this module.\n */\nexport function buildLinkedPathAudit(\n  paths: string[],\n  allItems: Array<{ id: string; artifacts?: LinkedArtifact[] }>,\n): LinkedPathAuditEntry[] {\n  const index = new Map<string, Set<string>>();\n  for (const item of allItems) {\n    for (const linkedArtifact of item.artifacts ?? []) {\n      const seen = index.get(linkedArtifact.path) ?? new Set<string>();\n      seen.add(item.id);\n      index.set(linkedArtifact.path, seen);\n    }\n  }\n  return [...new Set(paths)]\n    .sort((left, right) => left.localeCompare(right))\n    .map((linkedPath) => {\n      const linkedIds = [...(index.get(linkedPath) ?? new Set<string>())].sort((left, right) => left.localeCompare(right));\n      return {\n        path: linkedPath,\n        linked_by_count: linkedIds.length,\n        linked_item_ids: linkedIds,\n      };\n    });\n}\n\n/**\n * Shared linked-artifact list/mutate command core used by runFiles and runDocs.\n * The kind config selects metadata key, op, bare-path noun, and whether\n * append-stable ordering is honored, preserving each twin's exact semantics.\n */\nexport async function runLinkedArtifacts(\n  id: string,\n  options: LinkedArtifactCommandOptions,\n  global: GlobalOptions,\n  config: LinkedArtifactKindConfig,\n): Promise<LinkedArtifactResult> {\n  const { metadataKey } = config;\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 resolvedAdds = await stdinResolver.resolveList(options.add, \"--add\");\n  const resolvedAddGlobs = await stdinResolver.resolveList(options.addGlob, \"--add-glob\");\n  const resolvedRemoves = await stdinResolver.resolveList(options.remove, \"--remove\");\n  const resolvedMigrations = await stdinResolver.resolveList(options.migrate, \"--migrate\");\n  const parsedAdds = parseAddEntries(resolvedAdds, config.bareNoun);\n  const addGlobs = parseAddGlobEntries(resolvedAddGlobs);\n  const expandedGlobAdds = await expandAddGlobEntries(addGlobs);\n  const adds = applyStandaloneNote(\n    [...parsedAdds, ...expandedGlobAdds],\n    options.note,\n    parsedAdds.length > 0 || addGlobs.length > 0,\n  );\n  const removes = parseRemoveEntries(resolvedRemoves);\n  const migrations = parseMigrateEntries(resolvedMigrations);\n  const shouldMutate = adds.length > 0 || removes.length > 0 || migrations.length > 0;\n\n  const collectAuditItems = async (): Promise<Array<{ id: string; artifacts?: LinkedArtifact[] }>> =>\n    (await listAllFrontMatter(pmRoot, settings.item_format, typeRegistry.type_to_folder, undefined, settings.schema)).map((entry) => ({\n      id: entry.id,\n      artifacts: (entry as Record<string, unknown>)[metadataKey] as LinkedArtifact[] | undefined,\n    }));\n\n  if (!shouldMutate) {\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 artifacts = ((loaded.document.metadata as Record<string, unknown>)[metadataKey] as LinkedArtifact[] | undefined) ?? [];\n    return {\n      id: located.id,\n      artifacts,\n      changed: false,\n      count: artifacts.length,\n      validation: options.validatePaths ? await validateLinkedPaths(artifacts.map((entry) => entry.path)) : undefined,\n      audit: options.audit ? buildLinkedPathAudit(artifacts.map((entry) => entry.path), await collectAuditItems()) : undefined,\n    };\n  }\n\n  const author = resolveAuthor(options.author, settings.author_default);\n  const result = await mutateItem({\n    pmRoot,\n    settings,\n    id,\n    op: config.op,\n    author,\n    message: options.message,\n    force: options.force,\n    mutate(document) {\n      const metadata = document.metadata as Record<string, unknown>;\n      const next = [...((metadata[metadataKey] as LinkedArtifact[] | undefined) ?? [])];\n      let migrationCount = 0;\n      if (migrations.length > 0) {\n        for (let index = 0; index < next.length; index += 1) {\n          const migratedPath = applyPathMigrations(next[index].path, migrations);\n          if (migratedPath !== next[index].path) {\n            next[index] = { ...next[index], path: migratedPath };\n            migrationCount += 1;\n          }\n        }\n      }\n      const migratedAdds = adds.map((entry) => {\n        const migratedPath = applyPathMigrations(entry.path, migrations);\n        if (migratedPath !== entry.path) {\n          migrationCount += 1;\n        }\n        return {\n          ...entry,\n          path: migratedPath,\n        };\n      });\n      const migratedRemoves = removes.map((entry) => applyPathMigrations(entry, migrations));\n      for (const add of migratedAdds) {\n        const exists = next.some((entry) => entry.path === add.path && entry.scope === add.scope);\n        if (!exists) {\n          next.push(add);\n        }\n      }\n      if (migratedRemoves.length > 0) {\n        for (let i = next.length - 1; i >= 0; i -= 1) {\n          if (migratedRemoves.includes(next[i].path)) {\n            next.splice(i, 1);\n          }\n        }\n      }\n      const deduped = dedupeLinkedArtifacts(next);\n      const normalized = config.supportsAppendStable && options.appendStable ? deduped : sortLinkedArtifacts(deduped);\n      if (normalized.length > 0) {\n        metadata[metadataKey] = normalized;\n      } else {\n        delete metadata[metadataKey];\n      }\n      return { changedFields: [metadataKey], warnings: migrationCount > 0 ? [`path_migrations_applied:${migrationCount}`] : [] };\n    },\n  });\n\n  const artifacts = ((result.item as Record<string, unknown>)[metadataKey] as LinkedArtifact[] | undefined) ?? [];\n  const migrationWarning = result.warnings.find((warning) => warning.startsWith(\"path_migrations_applied:\"));\n  const migrationCount = migrationWarning ? Number(migrationWarning.slice(\"path_migrations_applied:\".length)) : 0;\n  const allItems = options.audit ? await collectAuditItems() : [];\n  return {\n    id: result.item.id,\n    artifacts,\n    changed: true,\n    count: artifacts.length,\n    migrations_applied: migrationCount > 0 ? migrationCount : undefined,\n    validation: options.validatePaths ? await validateLinkedPaths(artifacts.map((entry) => entry.path)) : undefined,\n    audit: options.audit ? buildLinkedPathAudit(artifacts.map((entry) => entry.path), allItems) : undefined,\n  };\n}\n\n/**\n * Re-key the generic `artifacts` field to the resource-specific name (files/docs)\n * while preserving the original key order and presence so kind-specific result\n * shapes (and their deterministic JSON key ordering) stay byte-identical.\n */\nexport function renameArtifactsResultKey(result: LinkedArtifactResult, key: \"files\" | \"docs\"): Record<string, unknown> {\n  const out: Record<string, unknown> = {};\n  for (const [field, value] of Object.entries(result)) {\n    out[field === \"artifacts\" ? key : field] = value;\n  }\n  return out;\n}\n"],
+  "mappings": "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",
+  "names": ["global", "artifacts", "migrationCount"]
+}

package/dist/cli-bundle/chunks/{chunk-GDOTTY2S.js → chunk-JINYH2DB.js}

@@ -2,7 +2,7 @@
 !(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] = "b4fea4d7-ec26-5176-a1ee-77473d6a5d9b");
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "6700669e-bb33-5b85-a194-73e559d13abd");
   } catch (e2) {
   }
 })();
@@ -112,6 +112,17 @@ var REMEDIATION_REGISTRY = Object.freeze([
     command: "pm history-repair <id>",
     summary: "A history stream contains Git conflict markers; resolve the markers, then re-anchor the chain."
   },
+  // --- pm health (integrity) + pm validate (format_version): item format version ---
+  {
+    code: "integrity_item_outdated_format_version",
+    command: "pm validate --verbose-diagnostics",
+    summary: "An item predates the current storage format version; a pm storage migration rewrites it. Use --verbose-diagnostics to list the affected items."
+  },
+  {
+    code: "integrity_item_ahead_format_version",
+    command: "npm install -g @unbrained/pm-cli@latest",
+    summary: "An item was written by a newer pm format version than this runtime supports; upgrade pm to read and validate it safely."
+  },
   // --- pm health: history_drift ---
   // `pm health` rewrites these commands to `pm history-repair --all` in the
   // per-check remediation_map when more than one stream is drifted.
@@ -152,6 +163,18 @@ var REMEDIATION_REGISTRY = Object.freeze([
     command: "pm gc --scope locks --dry-run",
     summary: "Some lock files could not be read; preview the sweep and inspect the unreadable files manually \u2014 gc never deletes what it cannot read."
   },
+  // --- pm health: extensions ---
+  // Most extension findings keep their richer, contextual
+  // `details.triage.remediation` and are intentionally absent here. The
+  // partial-coverage code is the exception: it is not a per-extension triage
+  // result but a system-wide adoption gap (unmanaged installs the update-health
+  // scan had to skip), so it has a single deterministic fix and belongs in the
+  // shared registry like any other health finding (pm-bdvm).
+  {
+    code: "extension_update_health_partial_coverage",
+    command: "pm extension --adopt-all --project",
+    summary: "Update-health coverage is partial because unmanaged extensions were skipped; adopt the existing installs into managed metadata so the update scan covers them (use --global for global-scope extensions, or pm package --adopt-all when working with packages)."
+  },
   // --- pm health: vectorization ---
   {
     code: "vectorization_stale_items_remaining",
@@ -214,6 +237,11 @@ var REMEDIATION_REGISTRY = Object.freeze([
     command: 'pm config set metadata-required-fields --criterion "<field>"',
     summary: "Config-driven finding: the custom metadata profile has no required fields configured and falls back to core, so configure the fields rather than mutating items."
   },
+  {
+    code: "validate_metadata_duplicate_issue_codes",
+    command: 'pm update <id> --title "<distinct title>"',
+    summary: "Two or more items share one logical issue code (GH-235); give each a distinct title so the derived code is unique, or close the redundant item with pm close <id> --duplicate-of <canonical-id> (closed-as-duplicate items are excluded from the check)."
+  },
   // --- pm validate: resolution ---
   {
     code: "validate_resolution_missing_fields",
@@ -298,6 +326,16 @@ var REMEDIATION_REGISTRY = Object.freeze([
     code: "validate_command_references_stale_pm_ids",
     command: 'pm update <id> --replace-tests --test "command=<corrected-command>" [--test ...]',
     summary: "Correct the stale pm-ID inside the item's linked test command (the check scans tests[].command, not the body). --replace-tests overwrites the entire tests list, so re-include the item's other linked tests in the same call."
+  },
+  {
+    code: "validate_format_version_outdated_items",
+    command: "pm validate --verbose-diagnostics",
+    summary: "One or more items predate the current storage format version; a pm storage migration rewrites them. Use --verbose-diagnostics to list the affected items."
+  },
+  {
+    code: "validate_format_version_ahead_items",
+    command: "npm install -g @unbrained/pm-cli@latest",
+    summary: "One or more items were written by a newer pm format version than this runtime supports; upgrade pm to read and validate them safely."
   }
 ]);
 function resolveRemediation(warning) {
@@ -330,4 +368,4 @@ export {
   buildRemediationMap,
   buildRemediationCommands
 };
-//# sourceMappingURL=chunk-GDOTTY2S.js.map
+//# sourceMappingURL=chunk-JINYH2DB.js.map

package/dist/cli-bundle/chunks/chunk-JINYH2DB.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../../../core/diagnostics/remediation.ts"],
+  "sourcesContent": ["/**\n * Shared machine-executable remediation registry.\n *\n * `pm health` and `pm validate` both emit stable, colon-delimited warning tokens\n * (for example `history_drift_missing_stream:pm-abcd` or\n * `validate_resolution_missing_fields:3`). Agents that gate on these commands\n * previously had to hardcode the mapping from a warning code to the `pm` command\n * that fixes it. This module is the single source of truth for that mapping so\n * `pm health --json` (per-check `remediation_map`) and `pm validate --fix-hints`\n * (per-check `fix_hints`) can both surface executable remediation without any\n * duplicated, drift-prone lookup tables.\n *\n * Semantics of {@link RemediationEntry.command}: the suggested next `pm` command\n * an operator/agent should run to resolve findings with that code. Per-item\n * findings use an `<id>` placeholder (callers that have the concrete id may\n * substitute it); findings whose only fix is a manual file edit point at the\n * most useful diagnostic/repair command and describe the manual step in\n * {@link RemediationEntry.summary}.\n */\n\n/** Maps a stable diagnostic warning code to the command and summary that resolve it. */\nexport interface RemediationEntry {\n  /**\n   * Stable warning-code prefix this entry resolves. A warning matches when it\n   * equals this code or begins with `<code>:`. Registry codes are mutually\n   * exclusive under that colon-boundary rule (no code is a `:`-delimited prefix\n   * of another — e.g. `settings:id_prefix_empty` is distinct from a bare\n   * `settings`, which is intentionally not registered), so `resolveRemediation`\n   * uses first-match with no ordering dependency.\n   */\n  readonly code: string;\n  /** Executable `pm` command (or imperative) that resolves the finding. May contain an `<id>` placeholder. */\n  readonly command: string;\n  /** One-line description of what the command does / which manual step it covers. */\n  readonly summary: string;\n}\n\n/**\n * Registry of every non-extension `pm health` / `pm validate` warning code and\n * its remediation. Extension findings keep their richer, contextual\n * `details.triage.remediation` produced by the extension health triage and are\n * intentionally excluded here (see pm-0hnu: \"all non-extension checks\").\n */\nexport const REMEDIATION_REGISTRY: readonly RemediationEntry[] = Object.freeze([\n  // --- pm health: directories ---\n  {\n    code: \"missing_directory\",\n    command: \"pm init\",\n    summary: \"Recreate missing tracker directories (pm init is idempotent and restores the scaffold).\",\n  },\n  // --- pm health: settings (read/parse) ---\n  {\n    code: \"settings_read_invalid_json\",\n    command: \"pm config list --json\",\n    summary:\n      \"settings.json is not valid JSON and pm fell back to defaults; fix the syntax error in the reported path, then re-run.\",\n  },\n  {\n    code: \"settings_read_invalid_schema\",\n    command: \"pm config list --json\",\n    summary:\n      \"settings.json failed schema validation and pm fell back to defaults; correct the reported key in the file, then re-run.\",\n  },\n  {\n    code: \"settings_read_merge_failed\",\n    command: \"pm config list --json\",\n    summary: \"Global/project settings could not be merged; reconcile the conflicting keys in the reported settings files.\",\n  },\n  // --- pm health: settings_values ---\n  {\n    code: \"settings:id_prefix_empty\",\n    command: \"pm config list --json\",\n    summary: 'id_prefix is empty; set a non-empty \"id_prefix\" in settings.json so generated item ids are well-formed.',\n  },\n  {\n    code: \"settings:locks_ttl_non_positive\",\n    command: \"pm config list --json\",\n    summary: 'locks.ttl_seconds must be positive; set a positive \"locks.ttl_seconds\" in settings.json.',\n  },\n  // --- pm health: telemetry (advisory) ---\n  {\n    code: \"telemetry_state_invalid_json\",\n    command: \"pm health --check-telemetry\",\n    summary: \"Local telemetry state file is corrupt; pm recreates it on the next flush. Advisory only.\",\n  },\n  {\n    code: \"telemetry_queue_invalid_rows\",\n    command: \"pm health --check-telemetry\",\n    summary: \"The telemetry queue has unparseable rows; they are skipped on the next flush. Advisory only.\",\n  },\n  {\n    code: \"telemetry_queue_pending\",\n    command: \"pm health --check-telemetry\",\n    summary: \"Telemetry events are queued; they flush automatically on the next reachable command. Advisory only.\",\n  },\n  {\n    code: \"telemetry_queue_high_retries\",\n    command: \"pm telemetry flush\",\n    summary:\n      \"Some queued telemetry events are near retry exhaustion; flush now and verify endpoint reachability before entries are dropped.\",\n  },\n  {\n    code: \"telemetry_endpoint_probe_failed\",\n    command: \"pm health --check-telemetry\",\n    summary: \"The telemetry endpoint is unreachable; events stay queued until it recovers. Advisory only.\",\n  },\n  {\n    code: \"telemetry_endpoint_probe_http_status\",\n    command: \"pm health --check-telemetry\",\n    summary: \"The telemetry endpoint returned a non-success status; events stay queued until it recovers. Advisory only.\",\n  },\n  {\n    code: \"telemetry_schema_version_behind\",\n    command: \"pm health --check-telemetry\",\n    summary: \"Client schema is behind server; upgrade pm-cli to emit the latest event shape.\",\n  },\n  {\n    code: \"telemetry_otel_export_failing\",\n    command: \"pm health --check-telemetry\",\n    summary:\n      \"OTLP trace spans are queued but the traces endpoint export is failing; spans retry automatically on the next reachable command, or set PM_TELEMETRY_OTEL_DISABLED=1 to skip OTLP export. Advisory only.\",\n  },\n  // --- pm health: integrity ---\n  {\n    code: \"integrity_item_unreadable\",\n    command: \"pm validate --check-files --verbose-diagnostics\",\n    summary: \"An item file could not be read; restore or repair the file at the reported path.\",\n  },\n  {\n    code: \"integrity_item_parse_failed\",\n    command: \"pm validate --check-files --verbose-diagnostics\",\n    summary: \"An item file failed to parse; fix the malformed front matter at the reported path.\",\n  },\n  {\n    code: \"integrity_item_conflict_marker\",\n    command: \"pm validate --check-files --verbose-diagnostics\",\n    summary: \"An item file contains Git conflict markers; resolve the <<<<<<< / >>>>>>> markers at the reported line.\",\n  },\n  {\n    code: \"integrity_history_unreadable\",\n    command: \"pm history-repair <id>\",\n    summary: \"A history stream could not be read; re-anchor the affected item's history chain.\",\n  },\n  {\n    code: \"integrity_history_invalid_json\",\n    command: \"pm history-repair <id>\",\n    summary: \"A history stream contains invalid JSON; re-anchor the affected item's history chain.\",\n  },\n  {\n    code: \"integrity_history_conflict_marker\",\n    command: \"pm history-repair <id>\",\n    summary: \"A history stream contains Git conflict markers; resolve the markers, then re-anchor the chain.\",\n  },\n  // --- pm health (integrity) + pm validate (format_version): item format version ---\n  {\n    code: \"integrity_item_outdated_format_version\",\n    command: \"pm validate --verbose-diagnostics\",\n    summary: \"An item predates the current storage format version; a pm storage migration rewrites it. Use --verbose-diagnostics to list the affected items.\",\n  },\n  {\n    code: \"integrity_item_ahead_format_version\",\n    command: \"npm install -g @unbrained/pm-cli@latest\",\n    summary: \"An item was written by a newer pm format version than this runtime supports; upgrade pm to read and validate it safely.\",\n  },\n  // --- pm health: history_drift ---\n  // `pm health` rewrites these commands to `pm history-repair --all` in the\n  // per-check remediation_map when more than one stream is drifted.\n  {\n    code: \"history_drift_missing_stream\",\n    command: \"pm history-repair <id>\",\n    summary: \"The item has no history stream; re-anchor the chain to rebuild it (pm history-repair --all repairs every drifted stream in one pass).\",\n  },\n  {\n    code: \"history_drift_unreadable_stream\",\n    command: \"pm history-repair <id>\",\n    summary: \"The item's history stream is unreadable; re-anchor the chain (pm history-repair --all repairs every drifted stream in one pass).\",\n  },\n  {\n    code: \"history_drift_hash_mismatch\",\n    command: \"pm history-repair <id>\",\n    summary: \"The item's content hash no longer matches its history; re-anchor the chain (pm history-repair --all repairs every drifted stream in one pass).\",\n  },\n  {\n    code: \"history_drift_chain_mismatch\",\n    command: \"pm history-repair <id>\",\n    summary: \"The item's history chain is broken; re-anchor the chain (pm history-repair --all repairs every drifted stream in one pass).\",\n  },\n  // --- pm health: storage (history compaction policy) ---\n  {\n    code: \"history_stream_over_compact_threshold\",\n    command: \"pm history-compact <id>\",\n    summary: \"The history stream exceeds the configured compaction threshold; compact it (pm history-compact --all-streams sweeps every over-threshold stream in one pass).\",\n  },\n  // --- pm health: locks ---\n  {\n    code: \"locks_stale_count\",\n    command: \"pm gc --scope locks\",\n    summary:\n      \"Stale item-claim locks (embedded ttl elapsed) can block mutations; sweep them — gc retains active and unparseable locks.\",\n  },\n  {\n    code: \"locks_unreadable\",\n    command: \"pm gc --scope locks --dry-run\",\n    summary:\n      \"Some lock files could not be read; preview the sweep and inspect the unreadable files manually — gc never deletes what it cannot read.\",\n  },\n  // --- pm health: extensions ---\n  // Most extension findings keep their richer, contextual\n  // `details.triage.remediation` and are intentionally absent here. The\n  // partial-coverage code is the exception: it is not a per-extension triage\n  // result but a system-wide adoption gap (unmanaged installs the update-health\n  // scan had to skip), so it has a single deterministic fix and belongs in the\n  // shared registry like any other health finding (pm-bdvm).\n  {\n    code: \"extension_update_health_partial_coverage\",\n    command: \"pm extension --adopt-all --project\",\n    summary:\n      \"Update-health coverage is partial because unmanaged extensions were skipped; adopt the existing installs into managed metadata so the update scan covers them (use --global for global-scope extensions, or pm package --adopt-all when working with packages).\",\n  },\n  // --- pm health: vectorization ---\n  {\n    code: \"vectorization_stale_items_remaining\",\n    command: \"pm health --refresh-vectors\",\n    summary: \"Some items have stale embeddings; refresh vectors so semantic search results stay current.\",\n  },\n  {\n    code: \"vectorization_embedding_identity_changed\",\n    command: \"pm reindex --mode semantic\",\n    summary: \"Embedding provider/model changed since the last index; run a semantic reindex to rebuild vectors.\",\n  },\n  // --- pm validate: metadata ---\n  // Note: validate_metadata_missing_author has no entry on purpose. `pm update\n  // --author` sets the mutation/audit author (history), not the item's\n  // `metadata.author` front-matter field, and there is no CLI flag that writes\n  // that field — so emitting a command here would record an audit entry without\n  // clearing the finding. A missing item author must be restored at the source.\n  {\n    code: \"validate_metadata_missing_acceptance_criteria\",\n    command: 'pm update <id> --acceptance-criteria \"<criteria>\"',\n    summary: \"Backfill the missing acceptance criteria on the reported item(s).\",\n  },\n  {\n    code: \"validate_metadata_missing_estimate\",\n    command: 'pm update <id> --estimate \"<estimate>\"',\n    summary: \"Backfill the missing estimate on the reported item(s).\",\n  },\n  {\n    code: \"validate_metadata_missing_close_reason\",\n    command: 'pm update <id> --close-reason \"<reason>\"',\n    summary: \"Backfill the missing close reason on the reported closed item(s).\",\n  },\n  {\n    code: \"validate_metadata_missing_reviewer\",\n    command: 'pm update <id> --reviewer \"<name>\"',\n    summary: \"Backfill the missing reviewer on the reported item(s).\",\n  },\n  {\n    code: \"validate_metadata_missing_risk\",\n    command: 'pm update <id> --risk \"<level>\"',\n    summary: \"Backfill the missing risk on the reported item(s).\",\n  },\n  {\n    code: \"validate_metadata_missing_confidence\",\n    command: 'pm update <id> --confidence \"<level>\"',\n    summary: \"Backfill the missing confidence on the reported item(s).\",\n  },\n  {\n    code: \"validate_metadata_missing_sprint\",\n    command: 'pm update <id> --sprint \"<sprint>\"',\n    summary: \"Backfill the missing sprint on the reported item(s).\",\n  },\n  {\n    code: \"validate_metadata_missing_release\",\n    command: 'pm update <id> --release \"<release>\"',\n    summary: \"Backfill the missing release on the reported item(s).\",\n  },\n  {\n    code: \"validate_metadata_custom_profile_missing_required_fields\",\n    command: 'pm config set metadata-required-fields --criterion \"<field>\"',\n    summary:\n      \"Config-driven finding: the custom metadata profile has no required fields configured and falls back to core, so configure the fields rather than mutating items.\",\n  },\n  {\n    code: \"validate_metadata_duplicate_issue_codes\",\n    command: 'pm update <id> --title \"<distinct title>\"',\n    summary:\n      \"Two or more items share one logical issue code (GH-235); give each a distinct title so the derived code is unique, or close the redundant item with pm close <id> --duplicate-of <canonical-id> (closed-as-duplicate items are excluded from the check).\",\n  },\n  // --- pm validate: resolution ---\n  {\n    code: \"validate_resolution_missing_fields\",\n    command: 'pm update <id> --resolution \"<how resolved>\"',\n    summary: \"Backfill resolution / expected_result / actual_result on the reported closed item(s).\",\n  },\n  // --- pm validate: lifecycle ---\n  {\n    code: \"validate_lifecycle_active_closure_like_metadata\",\n    command: \"pm update <id> --unset <closure-like-field>\",\n    summary:\n      \"Clear the closure-like field the validator flags on this active item — the detail row names it (resolution / actual-result / blocked-reason) — or close the item if it is actually done.\",\n  },\n  {\n    code: \"validate_lifecycle_active_terminal_parent\",\n    command: \"pm update <id> --parent <active-parent-id>\",\n    summary: \"Reopen the terminal parent or move the active child under a non-terminal parent.\",\n  },\n  {\n    code: \"validate_lifecycle_stale_blockers\",\n    command: \"pm update <id> --unset blocked-by --unset blocked-reason\",\n    summary:\n      \"Resolve the stale blocker the validator flags: clear blocked-by/blocked-reason when they linger on a non-blocked item or report a resolved blocker; if instead a blocked item is missing blocker context, add the context or move it out of a blocked status.\",\n  },\n  {\n    code: \"validate_lifecycle_dependency_cycles_error\",\n    command: \"pm update <id> --dep-remove <dep-id>\",\n    summary: \"Break the dependency cycle by removing one edge from the reported cycle.\",\n  },\n  {\n    code: \"validate_lifecycle_dependency_cycles\",\n    command: \"pm update <id> --dep-remove <dep-id>\",\n    summary: \"Break the dependency cycle by removing one edge from the reported cycle.\",\n  },\n  {\n    code: \"validate_hierarchy_parent_cycle_error\",\n    command: \"pm update <id> --parent <other-id>\",\n    summary:\n      \"Break the parent-hierarchy cycle by reparenting one item in the reported cycle to a non-cyclic parent (or clear it with pm update <id> --unset parent).\",\n  },\n  {\n    code: \"validate_hierarchy_parent_cycle\",\n    command: \"pm update <id> --parent <other-id>\",\n    summary:\n      \"Break the parent-hierarchy cycle by reparenting one item in the reported cycle to a non-cyclic parent (or clear it with pm update <id> --unset parent).\",\n  },\n  // --- pm validate: files ---\n  {\n    code: \"validate_files_missing_linked_paths\",\n    command: \"pm <files|docs> <id> --remove <path>\",\n    summary:\n      \"The check spans both item.files and item.docs under one code: restore the missing linked artifact, or unlink it with pm files (linked file) or pm docs (linked doc).\",\n  },\n  {\n    code: \"validate_files_orphaned_paths\",\n    command: \"pm <files|docs> <id> --add <path>\",\n    summary:\n      \"Link the orphaned artifact with pm files (file) or pm docs (doc), or remove it from the workspace.\",\n  },\n  {\n    code: \"validate_files_tracked_all_strict_forces_pm_internals\",\n    command: \"pm validate --check-files --include-pm-internals\",\n    summary: \"tracked-all-strict scan flagged pm internals; re-run with --include-pm-internals or a softer --scan-mode.\",\n  },\n  // --- pm validate: history_drift ---\n  {\n    code: \"validate_history_drift_missing_streams\",\n    command: \"pm history-repair <id>\",\n    summary: \"Re-anchor the history chains of the items missing a history stream.\",\n  },\n  {\n    code: \"validate_history_drift_unreadable_streams\",\n    command: \"pm history-repair <id>\",\n    summary: \"Re-anchor the history chains of the items with an unreadable history stream.\",\n  },\n  {\n    code: \"validate_history_drift_hash_mismatches\",\n    command: \"pm history-repair <id>\",\n    summary: \"Re-anchor the history chains of the items whose content hash drifted.\",\n  },\n  {\n    code: \"validate_history_drift_chain_mismatches\",\n    command: \"pm history-repair <id>\",\n    summary: \"Re-anchor the history chains of the items with a broken history chain.\",\n  },\n  // --- pm validate: command_references ---\n  {\n    code: \"validate_command_references_stale_pm_ids\",\n    command: 'pm update <id> --replace-tests --test \"command=<corrected-command>\" [--test ...]',\n    summary:\n      \"Correct the stale pm-ID inside the item's linked test command (the check scans tests[].command, not the body). --replace-tests overwrites the entire tests list, so re-include the item's other linked tests in the same call.\",\n  },\n  {\n    code: \"validate_format_version_outdated_items\",\n    command: \"pm validate --verbose-diagnostics\",\n    summary: \"One or more items predate the current storage format version; a pm storage migration rewrites them. Use --verbose-diagnostics to list the affected items.\",\n  },\n  {\n    code: \"validate_format_version_ahead_items\",\n    command: \"npm install -g @unbrained/pm-cli@latest\",\n    summary: \"One or more items were written by a newer pm format version than this runtime supports; upgrade pm to read and validate them safely.\",\n  },\n]);\n\n/**\n * Resolve the remediation entry for a warning token, or `undefined` when no\n * entry is registered. A warning matches an entry when it equals the entry code\n * or begins with `<code>:` (the colon boundary keeps sibling codes such as\n * `validate_lifecycle_dependency_cycles` and\n * `validate_lifecycle_dependency_cycles_error` disjoint).\n *\n * First match is intentional and correct: registry codes are mutually exclusive\n * under the colon-boundary rule, so at most one entry can ever match a warning\n * and order is irrelevant. That invariant is enforced by a test (see\n * remediation-registry.spec.ts \"keeps every registry code mutually exclusive\"),\n * which is why this stays a simple linear scan rather than a longest-prefix\n * search — a longest-prefix tie-break is unreachable with disjoint codes.\n *\n * Accepts unknown input defensively (this is an exported helper SDK consumers\n * may call from untyped JS): a non-string `warning` resolves to `undefined`.\n */\nexport function resolveRemediation(warning: string): RemediationEntry | undefined {\n  if (typeof warning !== \"string\") {\n    return undefined;\n  }\n  const normalized = warning.trim();\n  for (const entry of REMEDIATION_REGISTRY) {\n    if (normalized === entry.code || normalized.startsWith(`${entry.code}:`)) {\n      return entry;\n    }\n  }\n  return undefined;\n}\n\n/**\n * Build a compact `remediation_map` (code -> command) for a set of warning\n * tokens. First match wins per code; unknown codes are skipped. Used by\n * `pm health --json` per-check details and as the source of deduped executable\n * commands for `pm validate --fix-hints`.\n */\nexport function buildRemediationMap(warnings: Iterable<string>): Record<string, string> {\n  const map: Record<string, string> = {};\n  for (const warning of warnings) {\n    const entry = resolveRemediation(warning);\n    if (entry !== undefined && !Object.prototype.hasOwnProperty.call(map, entry.code)) {\n      map[entry.code] = entry.command;\n    }\n  }\n  return map;\n}\n\n/**\n * Build a deduped, ordered list of executable remediation commands for a set of\n * warning tokens (one command per distinct matched code). Used by\n * `pm validate --fix-hints` for checks that do not already emit per-row\n * remediation commands.\n */\nexport function buildRemediationCommands(warnings: Iterable<string>): string[] {\n  return Object.values(buildRemediationMap(warnings));\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cli-bundle/chunks/{chunk-EMFDZ7N3.js → chunk-LEU5GHRC.js}

@@ -1,9 +1,9 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="1710ba93-021e-5d8c-bb9e-918813d13c5a")}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]="da8f95fe-2b22-59c6-af82-e0bd090502e4")}catch(e){}}();
 import {
   compareTimestampStrings,
   isTimestampLiteral
-} from "./chunk-5P2LQV2F.js";
+} from "./chunk-NSBZ2CKF.js";
 import {
   CONFIDENCE_TEXT_VALUES,
   EXIT_CODE,
@@ -19,7 +19,7 @@ import {
   resolveRuntimeStatusRegistry,
   runtimeFieldOptionTarget,
   weekdayOrderIndex
-} from "./chunk-I2VJM36R.js";
+} from "./chunk-434HM6Z5.js";
 
 // dist/core/schema/runtime-field-values.js
 function toCamelToken(value) {
@@ -168,6 +168,48 @@ function collectRuntimeUpdateFieldValues(options, fieldRegistry, commands = ["up
   return values;
 }
 
+// dist/core/item/item-format-version.js
+var BASELINE_ITEM_FORMAT_VERSION = 1;
+var CURRENT_ITEM_FORMAT_VERSION = 1;
+function effectiveItemFormatVersion(metadata) {
+  const raw = metadata.pm_format_version;
+  if (typeof raw === "number" && Number.isInteger(raw) && raw >= BASELINE_ITEM_FORMAT_VERSION) {
+    return raw;
+  }
+  return BASELINE_ITEM_FORMAT_VERSION;
+}
+function normalizeItemFormatVersion(value) {
+  if (typeof value !== "number" || !Number.isInteger(value) || value <= BASELINE_ITEM_FORMAT_VERSION) {
+    return void 0;
+  }
+  return value;
+}
+function classifyItemFormatVersion(version, current = CURRENT_ITEM_FORMAT_VERSION) {
+  if (version < current) {
+    return "outdated";
+  }
+  if (version > current) {
+    return "ahead";
+  }
+  return "current";
+}
+function scanItemFormatVersions(entries, current = CURRENT_ITEM_FORMAT_VERSION) {
+  const outdated = [];
+  const ahead = [];
+  for (const entry of entries) {
+    const status = classifyItemFormatVersion(entry.version, current);
+    if (status === "outdated") {
+      outdated.push(entry.ref);
+    } else if (status === "ahead") {
+      ahead.push(entry.ref);
+    }
+  }
+  return {
+    outdated: outdated.sort((left, right) => left.localeCompare(right)),
+    ahead: ahead.sort((left, right) => left.localeCompare(right))
+  };
+}
+
 // dist/core/item/status.js
 var STATUS_ALIAS_MAP = {
   "in-progress": "in_progress",
@@ -372,6 +414,10 @@ function assertValidFrontMatter(frontMatter, runtimeContext) {
   }
   const itemType = record.type;
   assertFrontMatterCondition(typeof itemType === "string" && itemType.trim().length > 0, "type must be a non-empty string");
+  const formatVersion = record.pm_format_version;
+  if (formatVersion !== void 0) {
+    assertFrontMatterCondition(typeof formatVersion === "number" && Number.isInteger(formatVersion) && formatVersion >= BASELINE_ITEM_FORMAT_VERSION, `pm_format_version must be an integer >= ${BASELINE_ITEM_FORMAT_VERSION}`);
+  }
   const status = record.status;
   assertFrontMatterCondition(typeof status === "string" && status.trim().length > 0, "status must be a non-empty string");
   const statusRegistry = runtimeContext?.statusRegistry;
@@ -1019,6 +1065,7 @@ function normalizeFrontMatter(frontMatter, options = {}) {
     title: frontMatter.title,
     description: frontMatter.description,
     type: frontMatter.type,
+    pm_format_version: normalizeItemFormatVersion(frontMatter.pm_format_version),
     source_type: frontMatter.source_type?.trim() || void 0,
     type_options: normalizeTypeOptions(frontMatter.type_options),
     status: normalizedStatus,
@@ -1289,6 +1336,9 @@ export {
   coerceRuntimeFieldValue,
   collectRuntimeCreateFieldValues,
   collectRuntimeUpdateFieldValues,
+  CURRENT_ITEM_FORMAT_VERSION,
+  effectiveItemFormatVersion,
+  scanItemFormatVersions,
   normalizeStatusInput,
   normalizeStatusForRegistry,
   isTerminalStatus,
@@ -1298,6 +1348,6 @@ export {
   serializeItemDocument,
   canonicalDocument
 };
-//# sourceMappingURL=chunk-EMFDZ7N3.js.map
+//# sourceMappingURL=chunk-LEU5GHRC.js.map
 
-//# debugId=1710ba93-021e-5d8c-bb9e-918813d13c5a
+//# debugId=da8f95fe-2b22-59c6-af82-e0bd090502e4