@unbrained/pm-cli 2026.9.6 → 2026.9.8

package/dist/core/diagnostics/remediation.js

@@ -1,507 +1,2 @@
-/**
- * Shared machine-executable remediation registry.
- *
- * `pm health` and `pm validate` both emit stable, colon-delimited warning tokens
- * (for example `history_drift_missing_stream:pm-abcd` or
- * `validate_resolution_missing_fields:3`). Agents that gate on these commands
- * previously had to hardcode the mapping from a warning code to the `pm` command
- * that fixes it. This module is the single source of truth for that mapping so
- * `pm health --json` (per-check `remediation_map`) and `pm validate --fix-hints`
- * (per-check `fix_hints`) can both surface executable remediation without any
- * duplicated, drift-prone lookup tables.
- *
- * Semantics of {@link RemediationEntry.command}: the suggested next `pm` command
- * an operator/agent should run to resolve findings with that code. Per-item
- * findings use an `<id>` placeholder (callers that have the concrete id may
- * substitute it); findings whose only fix is a manual file edit point at the
- * most useful diagnostic/repair command and describe the manual step in
- * {@link RemediationEntry.summary}.
- */
-/** Registry of every non-extension `pm health` / `pm validate` warning code and its remediation. Extension findings keep their richer, contextual `details.triage.remediation` produced by the extension health triage and are intentionally excluded here (see pm-0hnu: "all non-extension checks"). */
-
-!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]="8e57e03e-3c60-5c1b-b455-9318df8027f6")}catch(e){}}();
-export const REMEDIATION_REGISTRY = Object.freeze([
-    // --- pm health: directories ---
-    {
-        code: "missing_directory",
-        command: "pm init",
-        summary: "Recreate missing tracker directories (pm init is idempotent and restores the scaffold).",
-    },
-    // --- pm health: settings (read/parse) ---
-    {
-        code: "settings_read_fs_error",
-        command: "pm config list --json",
-        summary: "settings.json could not be read as a regular file and pm fell back to defaults; repair the reported path or permissions, then re-run.",
-    },
-    {
-        code: "settings_read_invalid_json",
-        command: "pm config list --json",
-        summary: "settings.json is not valid JSON and pm fell back to defaults; fix the syntax error in the reported path, then re-run.",
-    },
-    {
-        code: "settings_read_invalid_schema",
-        command: "pm config list --json",
-        summary: "settings.json failed schema validation and pm fell back to defaults; correct the reported key in the file, then re-run.",
-    },
-    {
-        code: "settings_read_merge_failed",
-        command: "pm config list --json",
-        summary: "Global/project settings could not be merged; reconcile the conflicting keys in the reported settings files.",
-    },
-    // --- pm health: settings_values ---
-    {
-        code: "settings:id_prefix_empty",
-        command: "pm config list --json",
-        summary: 'id_prefix is empty; set a non-empty "id_prefix" in settings.json so generated item ids are well-formed.',
-    },
-    {
-        code: "settings:locks_ttl_non_positive",
-        command: "pm config list --json",
-        summary: 'locks.ttl_seconds must be positive; set a positive "locks.ttl_seconds" in settings.json.',
-    },
-    // --- pm health: telemetry (advisory) ---
-    {
-        code: "telemetry_state_invalid_json",
-        command: "pm health --check-telemetry",
-        summary: "Local telemetry state file is corrupt; pm recreates it on the next flush. Advisory only.",
-    },
-    {
-        code: "telemetry_queue_invalid_rows",
-        command: "pm health --check-telemetry",
-        summary: "The telemetry queue has unparseable rows; they are skipped on the next flush. Advisory only.",
-    },
-    {
-        code: "telemetry_queue_pending",
-        command: "pm health --check-telemetry",
-        summary: "Telemetry events are queued; they flush automatically on the next reachable command. Advisory only.",
-    },
-    {
-        code: "telemetry_queue_high_retries",
-        command: "pm telemetry flush",
-        summary: "Some queued telemetry events are near retry exhaustion; flush now and verify endpoint reachability before entries are dropped.",
-    },
-    {
-        code: "telemetry_endpoint_probe_failed",
-        command: "pm health --check-telemetry",
-        summary: "The telemetry endpoint is unreachable; events stay queued until it recovers. Advisory only.",
-    },
-    {
-        code: "telemetry_endpoint_probe_http_status",
-        command: "pm health --check-telemetry",
-        summary: "The telemetry endpoint returned a non-success status; events stay queued until it recovers. Advisory only.",
-    },
-    {
-        code: "telemetry_schema_version_behind",
-        command: "pm health --check-telemetry",
-        summary: "Client schema is behind server; upgrade pm-cli to emit the latest event shape.",
-    },
-    {
-        code: "telemetry_otel_export_failing",
-        command: "pm health --check-telemetry",
-        summary: "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.",
-    },
-    // --- pm health: integrity ---
-    {
-        code: "integrity_item_unreadable",
-        command: "pm validate --check-files --verbose-diagnostics",
-        summary: "An item file could not be read; restore or repair the file at the reported path.",
-    },
-    {
-        code: "integrity_item_parse_failed",
-        command: "pm validate --check-files --verbose-diagnostics",
-        summary: "An item file failed to parse; fix the malformed item metadata at the reported path.",
-    },
-    {
-        code: "integrity_item_conflict_marker",
-        command: "pm validate --check-files --verbose-diagnostics",
-        summary: "An item file contains Git conflict markers; resolve the <<<<<<< / >>>>>>> markers at the reported line.",
-    },
-    {
-        code: "integrity_history_unreadable",
-        command: "pm history-repair <id>",
-        summary: "A history stream could not be read; re-anchor the affected item's history chain.",
-    },
-    {
-        code: "integrity_history_invalid_json",
-        command: "pm history-repair <id>",
-        summary: "A history stream contains invalid JSON; re-anchor the affected item's history chain.",
-    },
-    {
-        code: "integrity_history_conflict_marker",
-        command: "pm history-repair <id>",
-        summary: "A history stream contains Git conflict markers; resolve the markers, then re-anchor the chain.",
-    },
-    // --- pm validate: storage_integrity (post-merge corruption detection) ---
-    {
-        code: "validate_storage_unreadable_items",
-        command: "pm validate --check-storage-integrity --verbose-diagnostics",
-        summary: "An on-disk item file cannot be parsed (for example a botched merge resolution with stale TOON count headers); repair or restore the file at the reported path — list commands silently skip it while pm get hard-errors.",
-    },
-    {
-        code: "validate_storage_duplicate_item_ids",
-        command: "pm validate --check-storage-integrity --verbose-diagnostics",
-        summary: "One item id is claimed by multiple item documents — usually two branches minting the same id for different items before merging (GH-600). Keep one document, recreate the other item under a fresh id (pm copy, then delete the colliding file), and consider raising ids.token_length for concurrent multi-agent work.",
-    },
-    {
-        code: "validate_storage_history_conflict_markers",
-        command: "pm merge driver history <base> <ours> <theirs>",
-        summary: "A history stream contains unresolved Git conflict markers; re-merge it with the pm history merge driver (or resolve the markers by hand), then run pm history-repair for the item.",
-    },
-    {
-        code: "validate_storage_unparseable_history",
-        command: "pm history-repair <id>",
-        summary: "A history stream's newest line is not valid JSONL; repair or restore the stream before further mutations.",
-    },
-    {
-        code: "validate_storage_resurrected_items",
-        command: "pm delete <id>",
-        summary: "A live item's newest history operation is a delete: a delete/modify merge silently resurrected it. Decide the winner — re-delete the item, or keep it and append a mutation documenting the revival.",
-    },
-    {
-        code: "validate_storage_unparseable_config",
-        command: "pm merge driver json <base> <ours> <theirs>",
-        summary: "settings.json or a schema file cannot be parsed, so pm silently falls back to defaults; re-merge it with the pm JSON merge driver or fix the file by hand, then rerun pm validate.",
-    },
-    {
-        code: "validate_merge_fence_drift",
-        command: "pm merge install",
-        summary: "The committed .gitattributes merge fence no longer matches the active schema's type folders or tracker JSONL stores; rerun pm merge install (and commit .gitattributes) so every tracker artifact keeps its field-aware merge driver.",
-    },
-    {
-        code: "validate_storage_tracked_runtime_cache_files",
-        command: "git rm --cached -r -- <tracked-runtime-directories>",
-        summary: "Clone-local tracker runtime artifacts are committed. Run the exact tracked_runtime_cache.remediation_command, commit the index-only removals and managed .gitignore fence, then rerun validation.",
-    },
-    // --- 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.",
-    },
-    {
-        code: "tracked_runtime_cache_files",
-        command: "git rm --cached -r -- <tracked-runtime-directories>",
-        summary: "Clone-local tracker runtime artifacts are committed. Run the exact tracked_runtime_cache.remediation_command from the integrity check, commit the index-only removals, and keep the managed .gitignore fence.",
-    },
-    {
-        code: "merge_decisions_unreviewed",
-        command: "pm merge reconcile --dry-run",
-        summary: "Review the pending merge receipts, re-apply any intended discarded values, then run pm merge reconcile; lossy receipts require explicit --force acceptance.",
-    },
-    {
-        code: "merge_receipts_pending",
-        command: "pm merge reconcile",
-        summary: "A lossless merge receipt is still pending; run pm merge reconcile to settle it (optionally preview first with --dry-run) so a green health gate certifies receipt settlement, not only intact data.",
-    },
-    {
-        code: "merge_receipt_evidence_invalid",
-        command: "pm merge report --include-reconciled --json",
-        summary: "One or more receipt candidates failed bounded-file, schema, identity, or copy-consistency validation; inspect the report's privacy-safe source, receipt id, and reason before repairing only the named evidence.",
-    },
-    {
-        code: "merge_receipt_history_reference_missing",
-        command: "pm merge reconcile --dry-run",
-        summary: "Review the bounded coordinates and recover available evidence first; for exact pre-durable clone-local-only references, rerun with --force so pm appends an audited disposition and proves the health finding is cleared without rewriting history.",
-    },
-    {
-        code: "validate_merge_decisions_unreviewed",
-        command: "pm merge reconcile --dry-run",
-        summary: "Review the pending merge receipts before reconciliation; history-repair alone does not settle them, and lossy receipts require explicit --force acceptance.",
-    },
-    // --- 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.
-    {
-        code: "history_drift_missing_stream",
-        command: "pm history-repair <id>",
-        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).",
-    },
-    {
-        code: "history_drift_unreadable_stream",
-        command: "pm history-repair <id>",
-        summary: "The item's history stream is unreadable; re-anchor the chain (pm history-repair --all repairs every drifted stream in one pass).",
-    },
-    {
-        code: "history_drift_hash_mismatch",
-        command: "pm history-repair <id>",
-        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).",
-    },
-    {
-        code: "history_drift_chain_mismatch",
-        command: "pm history-repair <id>",
-        summary: "The item's history chain is broken; re-anchor the chain (pm history-repair --all repairs every drifted stream in one pass).",
-    },
-    {
-        code: "history_drift_version_skew",
-        command: "npm install -g @unbrained/pm-cli@latest",
-        summary: "A history stream declares an item hash version this runtime does not support; upgrade pm to verify the chain instead of re-anchoring it.",
-    },
-    {
-        code: "history_drift_merge_receipt",
-        command: "pm merge reconcile",
-        summary: "Canonical path, changed-field, and merged-value hash evidence attributes this drift to a pending receipt; run reconciliation (optionally preview first with --dry-run) instead of repairing history directly.",
-    },
-    // --- pm health: storage (history compaction policy) ---
-    {
-        code: "history_stream_over_compact_threshold",
-        command: "pm history-compact <id>",
-        summary: "The history stream exceeds the configured compaction threshold; compact it (pm history-compact --all-streams sweeps every over-threshold stream in one pass).",
-    },
-    {
-        code: "history_unknown_author_events",
-        command: 'pm history-author-acknowledge --all-actionable --attributed-author "<principal>" --reviewer "<reviewer>" --reason "<evidence>"',
-        summary: "Review the actionable coordinates, then record an append-only attribution disposition for the complete current set.",
-    },
-    {
-        code: "provenance_value_domain_invalid",
-        command: "pm history-repair --all --normalize-provenance",
-        summary: "Remove invalid bounded provenance observations from affected streams and append privacy-safe aggregate repair receipts.",
-    },
-    {
-        code: "validate_history_unknown_author_events",
-        command: 'pm history-author-acknowledge --all-actionable --attributed-author "<principal>" --reviewer "<reviewer>" --reason "<evidence>"',
-        summary: "Review the actionable coordinates, then record an append-only attribution disposition for the complete current set.",
-    },
-    // --- pm health: locks ---
-    {
-        code: "locks_stale_count",
-        command: "pm gc --scope locks",
-        summary: "Stale item-claim locks (embedded ttl elapsed) can block mutations; sweep them — gc retains active and unparseable locks.",
-    },
-    {
-        code: "locks_unreadable",
-        command: "pm gc --scope locks --dry-run",
-        summary: "Some lock files could not be read; preview the sweep and inspect the unreadable files manually — 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",
-        command: "pm health --refresh-vectors",
-        summary: "Some items have stale embeddings; refresh vectors so semantic search results stay current.",
-    },
-    {
-        code: "vectorization_embedding_identity_changed",
-        command: "pm reindex --mode semantic",
-        summary: "Embedding provider/model changed since the last index; run a semantic reindex to rebuild vectors.",
-    },
-    // --- pm validate: metadata ---
-    // Note: validate_metadata_missing_author has no entry on purpose. `pm update
-    // --author` sets the mutation/audit author (history), not the item's
-    // `metadata.author` item-metadata field, and there is no CLI flag that writes
-    // that field — so emitting a command here would record an audit entry without
-    // clearing the finding. A missing item author must be restored at the source.
-    {
-        code: "validate_metadata_missing_acceptance_criteria",
-        command: 'pm update <id> --acceptance-criteria "<criteria>"',
-        summary: "Backfill the missing acceptance criteria on the reported item(s).",
-    },
-    {
-        code: "validate_metadata_missing_estimate",
-        command: 'pm update <id> --estimate "<estimate>"',
-        summary: "Backfill the missing estimate on the reported item(s).",
-    },
-    {
-        code: "validate_metadata_missing_close_reason",
-        command: 'pm update <id> --close-reason "<reason>"',
-        summary: "Backfill the missing close reason on the reported closed item(s).",
-    },
-    {
-        code: "validate_metadata_missing_reviewer",
-        command: 'pm update <id> --reviewer "<name>"',
-        summary: "Backfill the missing reviewer on the reported item(s).",
-    },
-    {
-        code: "validate_metadata_missing_risk",
-        command: 'pm update <id> --risk "<level>"',
-        summary: "Backfill the missing risk on the reported item(s).",
-    },
-    {
-        code: "validate_metadata_missing_confidence",
-        command: 'pm update <id> --confidence "<level>"',
-        summary: "Backfill the missing confidence on the reported item(s).",
-    },
-    {
-        code: "validate_metadata_missing_sprint",
-        command: 'pm update <id> --sprint "<sprint>"',
-        summary: "Backfill the missing sprint on the reported item(s).",
-    },
-    {
-        code: "validate_metadata_missing_release",
-        command: 'pm update <id> --release "<release>"',
-        summary: "Backfill the missing release on the reported item(s).",
-    },
-    {
-        code: "validate_metadata_custom_profile_missing_required_fields",
-        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",
-        command: 'pm update <id> --resolution "<how resolved>"',
-        summary: "Backfill resolution / expected_result / actual_result on the reported closed item(s).",
-    },
-    // --- pm validate: lifecycle ---
-    {
-        code: "validate_lifecycle_active_closure_like_metadata",
-        command: "pm update <id> --unset <closure-like-field>",
-        summary: "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.",
-    },
-    {
-        code: "validate_lifecycle_active_terminal_parent",
-        command: "pm update <id> --parent <active-parent-id>",
-        summary: "Reopen the terminal parent or move the active child under a non-terminal parent.",
-    },
-    {
-        code: "validate_lifecycle_stale_blockers",
-        command: "pm update <id> --unset blocked-by --unset blocked-reason",
-        summary: "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.",
-    },
-    {
-        code: "validate_lifecycle_dependency_cycles_error",
-        command: "pm update <id> --dep-remove <dep-id>",
-        summary: "Break the dependency cycle by removing one edge from the reported cycle.",
-    },
-    {
-        code: "validate_lifecycle_dependency_cycles",
-        command: "pm update <id> --dep-remove <dep-id>",
-        summary: "Break the dependency cycle by removing one edge from the reported cycle.",
-    },
-    {
-        code: "validate_hierarchy_parent_cycle_error",
-        command: "pm update <id> --parent <other-id>",
-        summary: "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).",
-    },
-    {
-        code: "validate_hierarchy_parent_cycle",
-        command: "pm update <id> --parent <other-id>",
-        summary: "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).",
-    },
-    // --- pm validate: files ---
-    {
-        code: "validate_files_missing_linked_paths",
-        command: "pm <files|docs> <id> --remove <path>",
-        summary: "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).",
-    },
-    {
-        code: "validate_files_orphaned_paths",
-        command: "pm <files|docs> <id> --add <path>",
-        summary: "Link the orphaned artifact with pm files (file) or pm docs (doc), or remove it from the workspace.",
-    },
-    {
-        code: "validate_files_tracked_all_strict_forces_pm_internals",
-        command: "pm validate --check-files --include-pm-internals",
-        summary: "tracked-all-strict scan flagged pm internals; re-run with --include-pm-internals or a softer --scan-mode.",
-    },
-    // --- pm validate: history_drift ---
-    {
-        code: "validate_history_drift_missing_streams",
-        command: "pm history-repair <id>",
-        summary: "Re-anchor the history chains of the items missing a history stream.",
-    },
-    {
-        code: "validate_history_drift_unreadable_streams",
-        command: "pm history-repair <id>",
-        summary: "Re-anchor the history chains of the items with an unreadable history stream.",
-    },
-    {
-        code: "validate_history_drift_hash_mismatches",
-        command: "pm history-repair <id>",
-        summary: "Re-anchor the history chains of the items whose content hash drifted.",
-    },
-    {
-        code: "validate_history_drift_chain_mismatches",
-        command: "pm history-repair <id>",
-        summary: "Re-anchor the history chains of the items with a broken history chain.",
-    },
-    {
-        code: "validate_history_drift_version_skews",
-        command: "npm install -g @unbrained/pm-cli@latest",
-        summary: "One or more history streams declare an item hash version this runtime does not support; upgrade pm to verify the chains instead of re-anchoring them.",
-    },
-    // --- pm validate: command_references ---
-    {
-        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.",
-    },
-]);
-/**
- * Resolve the remediation entry for a warning token, or `undefined` when no
- * entry is registered. A warning matches an entry when it equals the entry code
- * or begins with `<code>:` (the colon boundary keeps sibling codes such as
- * `validate_lifecycle_dependency_cycles` and
- * `validate_lifecycle_dependency_cycles_error` disjoint).
- *
- * First match is intentional and correct: registry codes are mutually exclusive
- * under the colon-boundary rule, so at most one entry can ever match a warning
- * and order is irrelevant. That invariant is enforced by a test (see
- * remediation-registry.spec.ts "keeps every registry code mutually exclusive"),
- * which is why this stays a simple linear scan rather than a longest-prefix
- * search — a longest-prefix tie-break is unreachable with disjoint codes.
- *
- * Accepts unknown input defensively (this is an exported helper SDK consumers
- * may call from untyped JS): a non-string `warning` resolves to `undefined`.
- */
-export function resolveRemediation(warning) {
-    if (typeof warning !== "string") {
-        return undefined;
-    }
-    const normalized = warning.trim();
-    for (const entry of REMEDIATION_REGISTRY) {
-        if (normalized === entry.code || normalized.startsWith(`${entry.code}:`)) {
-            return entry;
-        }
-    }
-    return undefined;
-}
-/** Build a compact `remediation_map` (code -> command) for a set of warning tokens. First match wins per code; unknown codes are skipped. Used by `pm health --json` per-check details and as the source of deduped executable commands for `pm validate --fix-hints`. */
-export function buildRemediationMap(warnings) {
-    const map = {};
-    for (const warning of warnings) {
-        const entry = resolveRemediation(warning);
-        if (entry !== undefined &&
-            !Object.prototype.hasOwnProperty.call(map, entry.code)) {
-            map[entry.code] = entry.command;
-        }
-    }
-    return map;
-}
-/** Build a deduped, ordered list of executable remediation commands for a set of warning tokens (one command per distinct matched code). Used by `pm validate --fix-hints` for checks that do not already emit per-row remediation commands. */
-export function buildRemediationCommands(warnings) {
-    return Object.values(buildRemediationMap(warnings));
-}
+!(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]="836da277-15e2-5b29-9b18-5b3227a8d247")}catch(e2){}})();const REMEDIATION_REGISTRY=Object.freeze([{code:"missing_directory",command:"pm init",summary:"Recreate missing tracker directories (pm init is idempotent and restores the scaffold)."},{code:"settings_read_fs_error",command:"pm config list --json",summary:"settings.json could not be read as a regular file and pm fell back to defaults; repair the reported path or permissions, then re-run."},{code:"settings_read_invalid_json",command:"pm config list --json",summary:"settings.json is not valid JSON and pm fell back to defaults; fix the syntax error in the reported path, then re-run."},{code:"settings_read_invalid_schema",command:"pm config list --json",summary:"settings.json failed schema validation and pm fell back to defaults; correct the reported key in the file, then re-run."},{code:"settings_read_merge_failed",command:"pm config list --json",summary:"Global/project settings could not be merged; reconcile the conflicting keys in the reported settings files."},{code:"settings:id_prefix_empty",command:"pm config list --json",summary:'id_prefix is empty; set a non-empty "id_prefix" in settings.json so generated item ids are well-formed.'},{code:"settings:locks_ttl_non_positive",command:"pm config list --json",summary:'locks.ttl_seconds must be positive; set a positive "locks.ttl_seconds" in settings.json.'},{code:"telemetry_state_invalid_json",command:"pm health --check-telemetry",summary:"Local telemetry state file is corrupt; pm recreates it on the next flush. Advisory only."},{code:"telemetry_queue_invalid_rows",command:"pm health --check-telemetry",summary:"The telemetry queue has unparseable rows; they are skipped on the next flush. Advisory only."},{code:"telemetry_queue_pending",command:"pm health --check-telemetry",summary:"Telemetry events are queued; they flush automatically on the next reachable command. Advisory only."},{code:"telemetry_queue_high_retries",command:"pm telemetry flush",summary:"Some queued telemetry events are near retry exhaustion; flush now and verify endpoint reachability before entries are dropped."},{code:"telemetry_endpoint_probe_failed",command:"pm health --check-telemetry",summary:"The telemetry endpoint is unreachable; events stay queued until it recovers. Advisory only."},{code:"telemetry_endpoint_probe_http_status",command:"pm health --check-telemetry",summary:"The telemetry endpoint returned a non-success status; events stay queued until it recovers. Advisory only."},{code:"telemetry_schema_version_behind",command:"pm health --check-telemetry",summary:"Client schema is behind server; upgrade pm-cli to emit the latest event shape."},{code:"telemetry_otel_export_failing",command:"pm health --check-telemetry",summary:"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."},{code:"integrity_item_unreadable",command:"pm validate --check-files --verbose-diagnostics",summary:"An item file could not be read; restore or repair the file at the reported path."},{code:"integrity_item_parse_failed",command:"pm validate --check-files --verbose-diagnostics",summary:"An item file failed to parse; fix the malformed item metadata at the reported path."},{code:"integrity_item_conflict_marker",command:"pm validate --check-files --verbose-diagnostics",summary:"An item file contains Git conflict markers; resolve the <<<<<<< / >>>>>>> markers at the reported line."},{code:"integrity_history_unreadable",command:"pm history-repair <id>",summary:"A history stream could not be read; re-anchor the affected item's history chain."},{code:"integrity_history_invalid_json",command:"pm history-repair <id>",summary:"A history stream contains invalid JSON; re-anchor the affected item's history chain."},{code:"integrity_history_conflict_marker",command:"pm history-repair <id>",summary:"A history stream contains Git conflict markers; resolve the markers, then re-anchor the chain."},{code:"validate_storage_unreadable_items",command:"pm validate --check-storage-integrity --verbose-diagnostics",summary:"An on-disk item file cannot be parsed (for example a botched merge resolution with stale TOON count headers); repair or restore the file at the reported path \u2014 list commands silently skip it while pm get hard-errors."},{code:"validate_storage_duplicate_item_ids",command:"pm validate --check-storage-integrity --verbose-diagnostics",summary:"One item id is claimed by multiple item documents \u2014 usually two branches minting the same id for different items before merging (GH-600). Keep one document, recreate the other item under a fresh id (pm copy, then delete the colliding file), and consider raising ids.token_length for concurrent multi-agent work."},{code:"validate_storage_history_conflict_markers",command:"pm merge driver history <base> <ours> <theirs>",summary:"A history stream contains unresolved Git conflict markers; re-merge it with the pm history merge driver (or resolve the markers by hand), then run pm history-repair for the item."},{code:"validate_storage_unparseable_history",command:"pm history-repair <id>",summary:"A history stream's newest line is not valid JSONL; repair or restore the stream before further mutations."},{code:"validate_storage_resurrected_items",command:"pm delete <id>",summary:"A live item's newest history operation is a delete: a delete/modify merge silently resurrected it. Decide the winner \u2014 re-delete the item, or keep it and append a mutation documenting the revival."},{code:"validate_storage_unparseable_config",command:"pm merge driver json <base> <ours> <theirs>",summary:"settings.json or a schema file cannot be parsed, so pm silently falls back to defaults; re-merge it with the pm JSON merge driver or fix the file by hand, then rerun pm validate."},{code:"validate_merge_fence_drift",command:"pm merge install",summary:"The committed .gitattributes merge fence no longer matches the active schema's type folders or tracker JSONL stores; rerun pm merge install (and commit .gitattributes) so every tracker artifact keeps its field-aware merge driver."},{code:"validate_storage_tracked_runtime_cache_files",command:"git rm --cached -r -- <tracked-runtime-directories>",summary:"Clone-local tracker runtime artifacts are committed. Run the exact tracked_runtime_cache.remediation_command, commit the index-only removals and managed .gitignore fence, then rerun validation."},{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."},{code:"tracked_runtime_cache_files",command:"git rm --cached -r -- <tracked-runtime-directories>",summary:"Clone-local tracker runtime artifacts are committed. Run the exact tracked_runtime_cache.remediation_command from the integrity check, commit the index-only removals, and keep the managed .gitignore fence."},{code:"merge_decisions_unreviewed",command:"pm merge reconcile --dry-run",summary:"Review the pending merge receipts, re-apply any intended discarded values, then run pm merge reconcile; lossy receipts require explicit --force acceptance."},{code:"merge_receipts_pending",command:"pm merge reconcile",summary:"A lossless merge receipt is still pending; run pm merge reconcile to settle it (optionally preview first with --dry-run) so a green health gate certifies receipt settlement, not only intact data."},{code:"merge_receipt_evidence_invalid",command:"pm merge report --include-reconciled --json",summary:"One or more receipt candidates failed bounded-file, schema, identity, or copy-consistency validation; inspect the report's privacy-safe source, receipt id, and reason before repairing only the named evidence."},{code:"merge_receipt_history_reference_missing",command:"pm merge reconcile --dry-run",summary:"Review the bounded coordinates and recover available evidence first; for exact pre-durable clone-local-only references, rerun with --force so pm appends an audited disposition and proves the health finding is cleared without rewriting history."},{code:"validate_merge_decisions_unreviewed",command:"pm merge reconcile --dry-run",summary:"Review the pending merge receipts before reconciliation; history-repair alone does not settle them, and lossy receipts require explicit --force acceptance."},{code:"history_drift_missing_stream",command:"pm history-repair <id>",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)."},{code:"history_drift_unreadable_stream",command:"pm history-repair <id>",summary:"The item's history stream is unreadable; re-anchor the chain (pm history-repair --all repairs every drifted stream in one pass)."},{code:"history_drift_hash_mismatch",command:"pm history-repair <id>",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)."},{code:"history_drift_chain_mismatch",command:"pm history-repair <id>",summary:"The item's history chain is broken; re-anchor the chain (pm history-repair --all repairs every drifted stream in one pass)."},{code:"history_drift_version_skew",command:"npm install -g @unbrained/pm-cli@latest",summary:"A history stream declares an item hash version this runtime does not support; upgrade pm to verify the chain instead of re-anchoring it."},{code:"history_drift_merge_receipt",command:"pm merge reconcile",summary:"Canonical path, changed-field, and merged-value hash evidence attributes this drift to a pending receipt; run reconciliation (optionally preview first with --dry-run) instead of repairing history directly."},{code:"history_stream_over_compact_threshold",command:"pm history-compact <id>",summary:"The history stream exceeds the configured compaction threshold; compact it (pm history-compact --all-streams sweeps every over-threshold stream in one pass)."},{code:"history_unknown_author_events",command:'pm history-author-acknowledge --all-actionable --attributed-author "<principal>" --reviewer "<reviewer>" --reason "<evidence>"',summary:"Review the actionable coordinates, then record an append-only attribution disposition for the complete current set."},{code:"provenance_value_domain_invalid",command:"pm history-repair --all --normalize-provenance",summary:"Remove invalid bounded provenance observations from affected streams and append privacy-safe aggregate repair receipts."},{code:"validate_history_unknown_author_events",command:'pm history-author-acknowledge --all-actionable --attributed-author "<principal>" --reviewer "<reviewer>" --reason "<evidence>"',summary:"Review the actionable coordinates, then record an append-only attribution disposition for the complete current set."},{code:"locks_stale_count",command:"pm gc --scope locks",summary:"Stale item-claim locks (embedded ttl elapsed) can block mutations; sweep them \u2014 gc retains active and unparseable locks."},{code:"locks_unreadable",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."},{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)."},{code:"vectorization_stale_items_remaining",command:"pm health --refresh-vectors",summary:"Some items have stale embeddings; refresh vectors so semantic search results stay current."},{code:"vectorization_embedding_identity_changed",command:"pm reindex --mode semantic",summary:"Embedding provider/model changed since the last index; run a semantic reindex to rebuild vectors."},{code:"validate_metadata_missing_acceptance_criteria",command:'pm update <id> --acceptance-criteria "<criteria>"',summary:"Backfill the missing acceptance criteria on the reported item(s)."},{code:"validate_metadata_missing_estimate",command:'pm update <id> --estimate "<estimate>"',summary:"Backfill the missing estimate on the reported item(s)."},{code:"validate_metadata_missing_close_reason",command:'pm update <id> --close-reason "<reason>"',summary:"Backfill the missing close reason on the reported closed item(s)."},{code:"validate_metadata_missing_reviewer",command:'pm update <id> --reviewer "<name>"',summary:"Backfill the missing reviewer on the reported item(s)."},{code:"validate_metadata_missing_risk",command:'pm update <id> --risk "<level>"',summary:"Backfill the missing risk on the reported item(s)."},{code:"validate_metadata_missing_confidence",command:'pm update <id> --confidence "<level>"',summary:"Backfill the missing confidence on the reported item(s)."},{code:"validate_metadata_missing_sprint",command:'pm update <id> --sprint "<sprint>"',summary:"Backfill the missing sprint on the reported item(s)."},{code:"validate_metadata_missing_release",command:'pm update <id> --release "<release>"',summary:"Backfill the missing release on the reported item(s)."},{code:"validate_metadata_custom_profile_missing_required_fields",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)."},{code:"validate_resolution_missing_fields",command:'pm update <id> --resolution "<how resolved>"',summary:"Backfill resolution / expected_result / actual_result on the reported closed item(s)."},{code:"validate_lifecycle_active_closure_like_metadata",command:"pm update <id> --unset <closure-like-field>",summary:"Clear the closure-like field the validator flags on this active item \u2014 the detail row names it (resolution / actual-result / blocked-reason) \u2014 or close the item if it is actually done."},{code:"validate_lifecycle_active_terminal_parent",command:"pm update <id> --parent <active-parent-id>",summary:"Reopen the terminal parent or move the active child under a non-terminal parent."},{code:"validate_lifecycle_stale_blockers",command:"pm update <id> --unset blocked-by --unset blocked-reason",summary:"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."},{code:"validate_lifecycle_dependency_cycles_error",command:"pm update <id> --dep-remove <dep-id>",summary:"Break the dependency cycle by removing one edge from the reported cycle."},{code:"validate_lifecycle_dependency_cycles",command:"pm update <id> --dep-remove <dep-id>",summary:"Break the dependency cycle by removing one edge from the reported cycle."},{code:"validate_hierarchy_parent_cycle_error",command:"pm update <id> --parent <other-id>",summary:"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)."},{code:"validate_hierarchy_parent_cycle",command:"pm update <id> --parent <other-id>",summary:"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)."},{code:"validate_files_missing_linked_paths",command:"pm <files|docs> <id> --remove <path>",summary:"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)."},{code:"validate_files_orphaned_paths",command:"pm <files|docs> <id> --add <path>",summary:"Link the orphaned artifact with pm files (file) or pm docs (doc), or remove it from the workspace."},{code:"validate_files_tracked_all_strict_forces_pm_internals",command:"pm validate --check-files --include-pm-internals",summary:"tracked-all-strict scan flagged pm internals; re-run with --include-pm-internals or a softer --scan-mode."},{code:"validate_history_drift_missing_streams",command:"pm history-repair <id>",summary:"Re-anchor the history chains of the items missing a history stream."},{code:"validate_history_drift_unreadable_streams",command:"pm history-repair <id>",summary:"Re-anchor the history chains of the items with an unreadable history stream."},{code:"validate_history_drift_hash_mismatches",command:"pm history-repair <id>",summary:"Re-anchor the history chains of the items whose content hash drifted."},{code:"validate_history_drift_chain_mismatches",command:"pm history-repair <id>",summary:"Re-anchor the history chains of the items with a broken history chain."},{code:"validate_history_drift_version_skews",command:"npm install -g @unbrained/pm-cli@latest",summary:"One or more history streams declare an item hash version this runtime does not support; upgrade pm to verify the chains instead of re-anchoring them."},{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){if(typeof warning!=="string"){return void 0}const normalized=warning.trim();for(const entry of REMEDIATION_REGISTRY){if(normalized===entry.code||normalized.startsWith(`${entry.code}:`)){return entry}}return void 0}function buildRemediationMap(warnings){const map={};for(const warning of warnings){const entry=resolveRemediation(warning);if(entry!==void 0&&!Object.prototype.hasOwnProperty.call(map,entry.code)){map[entry.code]=entry.command}}return map}function buildRemediationCommands(warnings){return Object.values(buildRemediationMap(warnings))}export{REMEDIATION_REGISTRY,buildRemediationCommands,buildRemediationMap,resolveRemediation};
 //# sourceMappingURL=remediation.js.map
-//# debugId=8e57e03e-3c60-5c1b-b455-9318df8027f6