@unbrained/pm-cli 2026.6.20 → 2026.6.21

package/dist/core/diagnostics/remediation.js.map

@@ -1 +1 @@
-{"version":3,"file":"remediation.js","sources":["core/diagnostics/remediation.ts"],"sourceRoot":"/","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: 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\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"],"names":[],"mappings":"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","debugId":"18ec090a-cfc4-5acf-90b6-7e6fade40d8d"}
+{"version":3,"file":"remediation.js","sources":["core/diagnostics/remediation.ts"],"sourceRoot":"/","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"],"names":[],"mappings":"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","debugId":"6700669e-bb33-5b85-a194-73e559d13abd"}

package/dist/core/item/item-format-version.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @module core/item/item-format-version
+ *
+ * Tracks the on-disk item front-matter format version so a future breaking
+ * storage change can tell already-current items apart from items that a staged
+ * migration must rewrite, without re-parsing and structurally guessing every
+ * file. The version is an explicit, monotonically increasing integer stamped in
+ * front-matter as `pm_format_version`.
+ *
+ * Token economy is a first-class constraint here: the baseline version (1) is
+ * the implicit default and is never serialized, so today's corpus gains zero
+ * bytes and zero churn. The field only materializes once an item reaches
+ * version 2 or higher. Absence of the field is therefore always interpreted as
+ * the baseline version, both now and after future bumps. The classification
+ * helpers below power the advisory `pm health` integrity surface and the
+ * `pm validate` format-version check.
+ */
+import type { ItemMetadata } from "../../types/index.js";
+/**
+ * The original (and implicit) item front-matter format version. Items missing a
+ * `pm_format_version` field are always treated as this version, so the baseline
+ * is never written to disk and adds no per-item token cost.
+ */
+export declare const BASELINE_ITEM_FORMAT_VERSION = 1;
+/**
+ * The format version this runtime writes and considers current. When a breaking
+ * front-matter change ships, bump this constant and add a migration that
+ * rewrites items whose {@link effectiveItemFormatVersion} is lower; items at or
+ * above it need no migration. It stays equal to
+ * {@link BASELINE_ITEM_FORMAT_VERSION} until the first such change.
+ */
+export declare const CURRENT_ITEM_FORMAT_VERSION = 1;
+/**
+ * Resolve the format version an item is effectively stored at. A present,
+ * positive-integer `pm_format_version` is taken verbatim (including versions
+ * ahead of this runtime, so they can be flagged rather than silently clamped);
+ * an absent, malformed, or sub-baseline value resolves to
+ * {@link BASELINE_ITEM_FORMAT_VERSION}.
+ */
+export declare function effectiveItemFormatVersion(metadata: Pick<ItemMetadata, "pm_format_version">): number;
+/**
+ * Reduce an item's `pm_format_version` to its persisted form: the baseline
+ * version (and any malformed or sub-baseline value) is dropped so it is never
+ * serialized, while versions at or above {@link BASELINE_ITEM_FORMAT_VERSION}
+ * plus one are preserved verbatim. This keeps the field absent for the entire
+ * current corpus and only writes it once an item genuinely advances past the
+ * implicit baseline.
+ */
+export declare function normalizeItemFormatVersion(value: unknown): number | undefined;
+/**
+ * Relationship between an item's stored format version and the runtime's
+ * current version: `outdated` (below current, a migration would rewrite it),
+ * `ahead` (above current, written by a newer pm than this one), or `current`.
+ */
+export type ItemFormatVersionStatus = "current" | "outdated" | "ahead";
+/**
+ * Classify a single stored format version against the runtime's current
+ * version. Defaults to {@link CURRENT_ITEM_FORMAT_VERSION}; the `current`
+ * parameter exists so callers (and tests) can evaluate against a hypothetical
+ * future version without mutating the module constant.
+ */
+export declare function classifyItemFormatVersion(version: number, current?: number): ItemFormatVersionStatus;
+/**
+ * One item's reference (id or relative path) paired with the format version it
+ * is stored at, used as input to {@link scanItemFormatVersions}.
+ */
+export interface ItemFormatVersionScanEntry {
+    ref: string;
+    version: number;
+}
+/**
+ * Sorted references partitioned by how their stored format version compares to
+ * the runtime's current version. References at the current version are omitted
+ * from both lists.
+ */
+export interface ItemFormatVersionScanResult {
+    outdated: string[];
+    ahead: string[];
+}
+/**
+ * Partition a set of items by format version into `outdated` (need migration)
+ * and `ahead` (written by a newer pm) reference lists, each sorted for stable
+ * diagnostics. Pushing all comparison branches into this pure, exhaustively
+ * tested helper lets `pm health` and `pm validate` emit findings by iterating
+ * the result lists, with no version-comparison branching of their own.
+ */
+export declare function scanItemFormatVersions(entries: readonly ItemFormatVersionScanEntry[], current?: number): ItemFormatVersionScanResult;

package/dist/core/item/item-format-version.js

@@ -0,0 +1,85 @@
+/**
+ * The original (and implicit) item front-matter format version. Items missing a
+ * `pm_format_version` field are always treated as this version, so the baseline
+ * is never written to disk and adds no per-item token cost.
+ */
+
+!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]="f0e67d63-2f7b-5f4a-b441-7a499c82e0a8")}catch(e){}}();
+export const BASELINE_ITEM_FORMAT_VERSION = 1;
+/**
+ * The format version this runtime writes and considers current. When a breaking
+ * front-matter change ships, bump this constant and add a migration that
+ * rewrites items whose {@link effectiveItemFormatVersion} is lower; items at or
+ * above it need no migration. It stays equal to
+ * {@link BASELINE_ITEM_FORMAT_VERSION} until the first such change.
+ */
+export const CURRENT_ITEM_FORMAT_VERSION = 1;
+/**
+ * Resolve the format version an item is effectively stored at. A present,
+ * positive-integer `pm_format_version` is taken verbatim (including versions
+ * ahead of this runtime, so they can be flagged rather than silently clamped);
+ * an absent, malformed, or sub-baseline value resolves to
+ * {@link BASELINE_ITEM_FORMAT_VERSION}.
+ */
+export 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;
+}
+/**
+ * Reduce an item's `pm_format_version` to its persisted form: the baseline
+ * version (and any malformed or sub-baseline value) is dropped so it is never
+ * serialized, while versions at or above {@link BASELINE_ITEM_FORMAT_VERSION}
+ * plus one are preserved verbatim. This keeps the field absent for the entire
+ * current corpus and only writes it once an item genuinely advances past the
+ * implicit baseline.
+ */
+export function normalizeItemFormatVersion(value) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= BASELINE_ITEM_FORMAT_VERSION) {
+        return undefined;
+    }
+    return value;
+}
+/**
+ * Classify a single stored format version against the runtime's current
+ * version. Defaults to {@link CURRENT_ITEM_FORMAT_VERSION}; the `current`
+ * parameter exists so callers (and tests) can evaluate against a hypothetical
+ * future version without mutating the module constant.
+ */
+export function classifyItemFormatVersion(version, current = CURRENT_ITEM_FORMAT_VERSION) {
+    if (version < current) {
+        return "outdated";
+    }
+    if (version > current) {
+        return "ahead";
+    }
+    return "current";
+}
+/**
+ * Partition a set of items by format version into `outdated` (need migration)
+ * and `ahead` (written by a newer pm) reference lists, each sorted for stable
+ * diagnostics. Pushing all comparison branches into this pure, exhaustively
+ * tested helper lets `pm health` and `pm validate` emit findings by iterating
+ * the result lists, with no version-comparison branching of their own.
+ */
+export 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)),
+    };
+}
+//# sourceMappingURL=item-format-version.js.map
+//# debugId=f0e67d63-2f7b-5f4a-b441-7a499c82e0a8

package/dist/core/item/item-format-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-format-version.js","sources":["core/item/item-format-version.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/item/item-format-version\n *\n * Tracks the on-disk item front-matter format version so a future breaking\n * storage change can tell already-current items apart from items that a staged\n * migration must rewrite, without re-parsing and structurally guessing every\n * file. The version is an explicit, monotonically increasing integer stamped in\n * front-matter as `pm_format_version`.\n *\n * Token economy is a first-class constraint here: the baseline version (1) is\n * the implicit default and is never serialized, so today's corpus gains zero\n * bytes and zero churn. The field only materializes once an item reaches\n * version 2 or higher. Absence of the field is therefore always interpreted as\n * the baseline version, both now and after future bumps. The classification\n * helpers below power the advisory `pm health` integrity surface and the\n * `pm validate` format-version check.\n */\nimport type { ItemMetadata } from \"../../types/index.js\";\n\n/**\n * The original (and implicit) item front-matter format version. Items missing a\n * `pm_format_version` field are always treated as this version, so the baseline\n * is never written to disk and adds no per-item token cost.\n */\nexport const BASELINE_ITEM_FORMAT_VERSION = 1;\n\n/**\n * The format version this runtime writes and considers current. When a breaking\n * front-matter change ships, bump this constant and add a migration that\n * rewrites items whose {@link effectiveItemFormatVersion} is lower; items at or\n * above it need no migration. It stays equal to\n * {@link BASELINE_ITEM_FORMAT_VERSION} until the first such change.\n */\nexport const CURRENT_ITEM_FORMAT_VERSION = 1;\n\n/**\n * Resolve the format version an item is effectively stored at. A present,\n * positive-integer `pm_format_version` is taken verbatim (including versions\n * ahead of this runtime, so they can be flagged rather than silently clamped);\n * an absent, malformed, or sub-baseline value resolves to\n * {@link BASELINE_ITEM_FORMAT_VERSION}.\n */\nexport function effectiveItemFormatVersion(metadata: Pick<ItemMetadata, \"pm_format_version\">): number {\n  const raw = metadata.pm_format_version;\n  if (typeof raw === \"number\" && Number.isInteger(raw) && raw >= BASELINE_ITEM_FORMAT_VERSION) {\n    return raw;\n  }\n  return BASELINE_ITEM_FORMAT_VERSION;\n}\n\n/**\n * Reduce an item's `pm_format_version` to its persisted form: the baseline\n * version (and any malformed or sub-baseline value) is dropped so it is never\n * serialized, while versions at or above {@link BASELINE_ITEM_FORMAT_VERSION}\n * plus one are preserved verbatim. This keeps the field absent for the entire\n * current corpus and only writes it once an item genuinely advances past the\n * implicit baseline.\n */\nexport function normalizeItemFormatVersion(value: unknown): number | undefined {\n  if (typeof value !== \"number\" || !Number.isInteger(value) || value <= BASELINE_ITEM_FORMAT_VERSION) {\n    return undefined;\n  }\n  return value;\n}\n\n/**\n * Relationship between an item's stored format version and the runtime's\n * current version: `outdated` (below current, a migration would rewrite it),\n * `ahead` (above current, written by a newer pm than this one), or `current`.\n */\nexport type ItemFormatVersionStatus = \"current\" | \"outdated\" | \"ahead\";\n\n/**\n * Classify a single stored format version against the runtime's current\n * version. Defaults to {@link CURRENT_ITEM_FORMAT_VERSION}; the `current`\n * parameter exists so callers (and tests) can evaluate against a hypothetical\n * future version without mutating the module constant.\n */\nexport function classifyItemFormatVersion(\n  version: number,\n  current: number = CURRENT_ITEM_FORMAT_VERSION,\n): ItemFormatVersionStatus {\n  if (version < current) {\n    return \"outdated\";\n  }\n  if (version > current) {\n    return \"ahead\";\n  }\n  return \"current\";\n}\n\n/**\n * One item's reference (id or relative path) paired with the format version it\n * is stored at, used as input to {@link scanItemFormatVersions}.\n */\nexport interface ItemFormatVersionScanEntry {\n  ref: string;\n  version: number;\n}\n\n/**\n * Sorted references partitioned by how their stored format version compares to\n * the runtime's current version. References at the current version are omitted\n * from both lists.\n */\nexport interface ItemFormatVersionScanResult {\n  outdated: string[];\n  ahead: string[];\n}\n\n/**\n * Partition a set of items by format version into `outdated` (need migration)\n * and `ahead` (written by a newer pm) reference lists, each sorted for stable\n * diagnostics. Pushing all comparison branches into this pure, exhaustively\n * tested helper lets `pm health` and `pm validate` emit findings by iterating\n * the result lists, with no version-comparison branching of their own.\n */\nexport function scanItemFormatVersions(\n  entries: readonly ItemFormatVersionScanEntry[],\n  current: number = CURRENT_ITEM_FORMAT_VERSION,\n): ItemFormatVersionScanResult {\n  const outdated: string[] = [];\n  const ahead: string[] = [];\n  for (const entry of entries) {\n    const status = classifyItemFormatVersion(entry.version, current);\n    if (status === \"outdated\") {\n      outdated.push(entry.ref);\n    } else if (status === \"ahead\") {\n      ahead.push(entry.ref);\n    }\n  }\n  return {\n    outdated: outdated.sort((left, right) => left.localeCompare(right)),\n    ahead: ahead.sort((left, right) => left.localeCompare(right)),\n  };\n}\n"],"names":[],"mappings":"AAmBA;;;;GAIG;;;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC;AAE7C;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CAAC,QAAiD;IAC1F,MAAM,GAAG,GAAG,QAAQ,CAAC,iBAAiB,CAAC;IACvC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,4BAA4B,EAAE,CAAC;QAC5F,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,4BAA4B,CAAC;AACtC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CAAC,KAAc;IACvD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,4BAA4B,EAAE,CAAC;QACnG,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AASD;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAAe,EACf,UAAkB,2BAA2B;IAE7C,IAAI,OAAO,GAAG,OAAO,EAAE,CAAC;QACtB,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,IAAI,OAAO,GAAG,OAAO,EAAE,CAAC;QACtB,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAqBD;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAA8C,EAC9C,UAAkB,2BAA2B;IAE7C,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,yBAAyB,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACjE,IAAI,MAAM,KAAK,UAAU,EAAE,CAAC;YAC1B,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC;aAAM,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;YAC9B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IACD,OAAO;QACL,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QACnE,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;KAC9D,CAAC;AACJ,CAAC","debugId":"f0e67d63-2f7b-5f4a-b441-7a499c82e0a8"}

package/dist/core/item/item-format.js

@@ -4,11 +4,12 @@
  * Defines item parsing, formatting, and lifecycle helpers for Item Format.
  */
 
-!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]="c295802c-f55f-56e8-afdc-257cdef6a4cb")}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]="777ea2a9-5aa6-5a90-abb5-a0b6052645f2")}catch(e){}}();
 import { encode as encodeToon } from "@toon-format/toon";
 import { CONFIDENCE_TEXT_VALUES, ISSUE_SEVERITY_VALUES, RECURRENCE_FREQUENCY_VALUES, RECURRENCE_WEEKDAY_VALUES, STATUS_VALUES, weekdayOrderIndex, } from "../../types/index.js";
 import { coerceRuntimeFieldValue } from "../schema/runtime-field-values.js";
 import { resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, } from "../schema/runtime-schema.js";
+import { BASELINE_ITEM_FORMAT_VERSION, normalizeItemFormatVersion } from "./item-format-version.js";
 import { normalizeStatusInput } from "./status.js";
 import { decodeToonItemContent } from "./toon-decode.js";
 import { EXIT_CODE, FRONT_MATTER_KEY_ORDER } from "../shared/constants.js";
@@ -129,6 +130,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 !== undefined) {
+        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;
@@ -849,6 +854,7 @@ export 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() || undefined,
         type_options: normalizeTypeOptions(frontMatter.type_options),
         status: normalizedStatus,
@@ -1149,4 +1155,4 @@ export const _testOnlyItemFormat = {
     sortTests,
 };
 //# sourceMappingURL=item-format.js.map
-//# debugId=c295802c-f55f-56e8-afdc-257cdef6a4cb
+//# debugId=777ea2a9-5aa6-5a90-abb5-a0b6052645f2