@unbrained/pm-cli 2026.6.10 → 2026.6.12

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../../../core/diagnostics/remediation.ts"],
+  "sourcesContent": ["/**\n * Shared machine-executable remediation registry.\n *\n * `pm health` and `pm validate` both emit stable, colon-delimited warning tokens\n * (for example `history_drift_missing_stream:pm-abcd` or\n * `validate_resolution_missing_fields:3`). Agents that gate on these commands\n * previously had to hardcode the mapping from a warning code to the `pm` command\n * that fixes it. This module is the single source of truth for that mapping so\n * `pm health --json` (per-check `remediation_map`) and `pm validate --fix-hints`\n * (per-check `fix_hints`) can both surface executable remediation without any\n * duplicated, drift-prone lookup tables.\n *\n * Semantics of {@link RemediationEntry.command}: the suggested next `pm` command\n * an operator/agent should run to resolve findings with that code. Per-item\n * findings use an `<id>` placeholder (callers that have the concrete id may\n * substitute it); findings whose only fix is a manual file edit point at the\n * most useful diagnostic/repair command and describe the manual step in\n * {@link RemediationEntry.summary}.\n */\n\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  // --- 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: 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: 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  // --- 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  // --- 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"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cli-bundle/chunks/{chunk-VSS3CSTF.js → chunk-RXAP6JL5.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-O7IWB35H.js";
 import {
   readHistoryEntries
-} from "./chunk-WBU257Z4.js";
+} from "./chunk-IGVJRZ6H.js";
 import {
   EMPTY_REPLAY_DOCUMENT,
   historyEntriesToRaw,
@@ -11,27 +11,27 @@ import {
   replayToItemDocument,
   tryApplyReplayPatch,
   verifyHistoryChain
-} from "./chunk-TXWMLDMG.js";
+} from "./chunk-XMBI6TNW.js";
 import {
   acquireLock,
   createHistoryEntry,
   locateItem,
   readLocatedItem
-} from "./chunk-XRE4CTNP.js";
+} from "./chunk-3KLPFWZ4.js";
 import {
   normalizeItemId,
   normalizeRawItemId
-} from "./chunk-I2FM2SMO.js";
+} from "./chunk-VPEAS7PS.js";
 import {
   canonicalDocument,
   serializeItemDocument
-} from "./chunk-Q6PSD5DZ.js";
+} from "./chunk-73ZPG2I3.js";
 import {
   resolveItemTypeRegistry
-} from "./chunk-7GYMMDDW.js";
+} from "./chunk-5SCT2JCT.js";
 import {
   nowIso
-} from "./chunk-7TW64BS5.js";
+} from "./chunk-IUKD4W6Z.js";
 import {
   EXIT_CODE,
   PmCliError,
@@ -46,7 +46,7 @@ import {
   resolvePmRoot,
   runActiveOnWriteHooks,
   writeFileAtomic
-} from "./chunk-OQGJSCZZ.js";
+} from "./chunk-FY4SPXSC.js";
 
 // dist/cli/commands/history-redact.js
 import fs from "node:fs/promises";
@@ -547,4 +547,4 @@ export {
   resolveHistorySubject,
   runHistoryRedact
 };
-//# sourceMappingURL=chunk-VSS3CSTF.js.map
+//# sourceMappingURL=chunk-RXAP6JL5.js.map

package/dist/cli-bundle/chunks/{chunk-3VTWCBXL.js → chunk-S26FESD4.js}

@@ -1,13 +1,13 @@
 import {
   nowIso
-} from "./chunk-7TW64BS5.js";
+} from "./chunk-IUKD4W6Z.js";
 import {
   EXIT_CODE,
   PmCliError,
   pathExists,
   toErrorMessage,
   writeFileAtomic
-} from "./chunk-OQGJSCZZ.js";
+} from "./chunk-FY4SPXSC.js";
 
 // dist/core/checkpoint/mutation-checkpoint.js
 import { mkdir, readFile } from "node:fs/promises";
@@ -128,4 +128,4 @@ export {
   loadMutationCheckpoint,
   restoreCheckpointItems
 };
-//# sourceMappingURL=chunk-3VTWCBXL.js.map
+//# sourceMappingURL=chunk-S26FESD4.js.map

package/dist/cli-bundle/chunks/{chunk-DEYNERFX.js → chunk-S2ZLDYGS.js}

@@ -6,13 +6,13 @@ import {
   normalizeStringList,
   parseExtensionManifest,
   validateExtensionDirectory
-} from "./chunk-6N46IM44.js";
+} from "./chunk-VAOUX6TK.js";
 import {
   splitCommaList
 } from "./chunk-LXYVKYMQ.js";
 import {
   nowIso
-} from "./chunk-PYULT32I.js";
+} from "./chunk-WUNFKP7M.js";
 import {
   EXIT_CODE,
   EXTENSION_CAPABILITY_CONTRACT,
@@ -31,7 +31,7 @@ import {
   resolvePmPackageRootFromModule,
   resolvePmRoot,
   writeSettings
-} from "./chunk-WNMRICXH.js";
+} from "./chunk-A6LXQFO7.js";
 
 // dist/cli/commands/extension.js
 import { execFile as execFile2 } from "node:child_process";
@@ -3091,6 +3091,6 @@ export {
   copyExtensionDirectoryForInstall,
   runExtension
 };
-//# sourceMappingURL=chunk-DEYNERFX.js.map
+//# sourceMappingURL=chunk-S2ZLDYGS.js.map
 
 //# debugId=029b7973-a2d9-540e-b989-c911896db3a6

package/dist/cli-bundle/chunks/{chunk-QGIWURY3.js → chunk-SO55HRA5.js}

@@ -2,7 +2,7 @@
 !function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="bc69cde3-7c0d-5ce3-a6fa-8ccd67d46d4b")}catch(e){}}();
 import {
   runClose
-} from "./chunk-KMMUDSSB.js";
+} from "./chunk-QKW5D45B.js";
 import {
   assertNoLegacyNoneToken,
   assertNoLegacyNoneTokens,
@@ -20,7 +20,7 @@ import {
   parseTests,
   parseTypeOptionEntries,
   resolvePriority
-} from "./chunk-XH6RA5A5.js";
+} from "./chunk-7AMK6DOW.js";
 import {
   applyTagRemovals,
   createStdinTokenResolver,
@@ -28,15 +28,15 @@ import {
   parseCsvKv,
   parseOptionalNumber,
   parseTags
-} from "./chunk-K7SXBA75.js";
+} from "./chunk-I7NYDZDV.js";
 import {
   normalizeParentReferenceValue,
   validateMissingParentReference,
   validateSprintOrReleaseValue
-} from "./chunk-OROMGSBP.js";
+} from "./chunk-Y3YKK7CY.js";
 import {
   buildInvalidTypeError
-} from "./chunk-TALBUVWF.js";
+} from "./chunk-FDH2X65L.js";
 import {
   applyRegisteredItemFieldDefaultsAndValidation,
   buildItemNotFoundError,
@@ -46,14 +46,14 @@ import {
   parseRegisteredItemFieldAssignments,
   readLocatedItem,
   toItemRecord
-} from "./chunk-MF6KSSMF.js";
+} from "./chunk-HI7STVF2.js";
 import {
   normalizeItemId
-} from "./chunk-UDWUDUJI.js";
+} from "./chunk-ATEES5SX.js";
 import {
   collectRuntimeUpdateFieldValues,
   normalizeStatusInput
-} from "./chunk-SNASEDXB.js";
+} from "./chunk-UUWGCWBU.js";
 import {
   canonicalizeCommandOptionKey,
   commandOptionFlagLabel,
@@ -62,10 +62,10 @@ import {
   resolveTypeDefinition,
   resolveTypeName,
   validateTypeOptions
-} from "./chunk-344GDQTH.js";
+} from "./chunk-CCX4RSYZ.js";
 import {
   resolveIsoOrRelative
-} from "./chunk-PYULT32I.js";
+} from "./chunk-WUNFKP7M.js";
 import {
   DEPENDENCY_KIND_VALUES,
   EXIT_CODE,
@@ -80,7 +80,7 @@ import {
   resolveRuntimeFieldRegistry,
   resolveRuntimeStatusRegistry,
   stableValueEquals
-} from "./chunk-WNMRICXH.js";
+} from "./chunk-A6LXQFO7.js";
 
 // dist/core/schema/type-workflows.js
 function normalizeStatusToken(value) {
@@ -1699,6 +1699,6 @@ async function runUpdate(id, options, global) {
 export {
   runUpdate
 };
-//# sourceMappingURL=chunk-QGIWURY3.js.map
+//# sourceMappingURL=chunk-SO55HRA5.js.map
 
 //# debugId=bc69cde3-7c0d-5ce3-a6fa-8ccd67d46d4b

package/dist/cli-bundle/chunks/{chunk-F2PVV7IX.js → chunk-SXKNJPQ7.js}

@@ -1,6 +1,6 @@
 import {
   parseOptionalNumber
-} from "./chunk-UY26RIBR.js";
+} from "./chunk-TNAP7EJX.js";
 import {
   splitCommaList
 } from "./chunk-3HUE7XOF.js";
@@ -8,7 +8,7 @@ import {
   EXIT_CODE,
   PmCliError,
   SCOPE_VALUES
-} from "./chunk-OQGJSCZZ.js";
+} from "./chunk-FY4SPXSC.js";
 
 // dist/cli/commands/linked-test-entry.js
 !(function() {
@@ -525,4 +525,4 @@ export {
   parseLinkedTestAssertionGteMap,
   parseLinkedTestJsonEntries
 };
-//# sourceMappingURL=chunk-F2PVV7IX.js.map
+//# sourceMappingURL=chunk-SXKNJPQ7.js.map

package/dist/cli-bundle/chunks/{chunk-5OMABP7I.js → chunk-TK5VZFHY.js}

@@ -3,21 +3,21 @@ import {
 } from "./chunk-O7IWB35H.js";
 import {
   parseCsvKv
-} from "./chunk-UY26RIBR.js";
+} from "./chunk-TNAP7EJX.js";
 import {
   parseLimit
-} from "./chunk-TV6FZGVK.js";
+} from "./chunk-QJMGRZO2.js";
 import {
   locateItem,
   mutateItem,
   readLocatedItem
-} from "./chunk-XRE4CTNP.js";
+} from "./chunk-3KLPFWZ4.js";
 import {
   resolveItemTypeRegistry
-} from "./chunk-7GYMMDDW.js";
+} from "./chunk-5SCT2JCT.js";
 import {
   nowIso
-} from "./chunk-7TW64BS5.js";
+} from "./chunk-IUKD4W6Z.js";
 import {
   EXIT_CODE,
   PmCliError,
@@ -26,7 +26,7 @@ import {
   pathExists,
   readSettings,
   resolvePmRoot
-} from "./chunk-OQGJSCZZ.js";
+} from "./chunk-FY4SPXSC.js";
 
 // dist/cli/commands/annotation-command.js
 !(function() {
@@ -154,4 +154,4 @@ export {
   wrapOwnershipConflict,
   runAnnotationCommand
 };
-//# sourceMappingURL=chunk-5OMABP7I.js.map
+//# sourceMappingURL=chunk-TK5VZFHY.js.map

package/dist/cli-bundle/chunks/{chunk-UY26RIBR.js → chunk-TNAP7EJX.js}

@@ -1,7 +1,7 @@
 import {
   EXIT_CODE,
   PmCliError
-} from "./chunk-OQGJSCZZ.js";
+} from "./chunk-FY4SPXSC.js";
 
 // dist/core/item/parse.js
 !(function() {
@@ -338,4 +338,4 @@ export {
   createStdinTokenResolver,
   parseOptionalNumber
 };
-//# sourceMappingURL=chunk-UY26RIBR.js.map
+//# sourceMappingURL=chunk-TNAP7EJX.js.map

package/dist/cli-bundle/chunks/{chunk-QJ2OIEOC.js → chunk-UIG4TW2H.js}

@@ -1,5 +1,5 @@
 
-!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]="2533bfec-8cab-58ea-acd2-3582f0f1b6bd")}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]="60d8e31c-b4ba-5c8f-b2dc-523d0a2b3b13")}catch(e){}}();
 import {
   KNOWN_EXTENSION_CAPABILITIES,
   KNOWN_EXTENSION_POLICY_MODES,
@@ -11,7 +11,7 @@ import {
   PLAN_MODE_VALUES,
   PLAN_STEP_LINK_KIND_VALUES,
   PLAN_STEP_STATUS_VALUES
-} from "./chunk-WNMRICXH.js";
+} from "./chunk-A6LXQFO7.js";
 
 // dist/sdk/cli-contracts/commander-types.js
 var LIST_COMMANDER_STRING_OPTION_CONTRACTS = [
@@ -1267,6 +1267,9 @@ var PM_TOOL_PARAMETER_PROPERTIES = {
   strictExit: { type: "boolean" },
   failOnWarn: { type: "boolean" },
   fixHints: { type: "boolean" },
+  autoFix: { type: "boolean" },
+  fixScope: { type: "array", items: { type: "string", enum: ["metadata", "resolution", "lifecycle"] } },
+  pruneMissing: { type: "boolean" },
   checkHistoryDrift: { type: "boolean" },
   checkCommandReferences: { type: "boolean" },
   allowAuditNote: { type: "boolean" },
@@ -1276,6 +1279,7 @@ var PM_TOOL_PARAMETER_PROPERTIES = {
   allowAuditDepUpdate: { type: "boolean" },
   allowAuditRelease: { type: "boolean" },
   dryRun: { type: "boolean" },
+  all: { type: "boolean" },
   cliOnly: { type: "boolean" },
   packagesOnly: { type: "boolean" },
   repair: { type: "boolean" },
@@ -1315,6 +1319,10 @@ var PM_TOOL_PARAMETER_PROPERTIES = {
   discover: { type: "boolean" },
   apply: { type: "boolean" },
   discoveryNote: { type: "string" },
+  // GH-170 (pm-pfnx): single-string note for files/docs add batches (the shared
+  // `note` key below is the array-typed create/update note seed).
+  addNote: { type: "string" },
+  list: { type: "boolean" },
   appendStable: { type: "boolean" },
   validatePaths: { type: "boolean" },
   audit: { type: "boolean" },
@@ -1386,6 +1394,9 @@ var PLAN_ACTION_PARAMETER_PROPERTIES = {
   claim: { type: "boolean" },
   fromSearch: { type: "string" },
   stepTitle: { type: "string" },
+  // pm-6mit: ordered step titles for create (string or array; values are never
+  // comma-split). On step subcommands a single value aliases stepTitle.
+  step: { anyOf: [{ type: "string" }, { type: "array", items: { type: "string" } }] },
   stepBody: { type: "string" },
   stepOwner: { type: "string" },
   stepStatus: { type: "string", enum: [...PLAN_STEP_STATUS_VALUES] },
@@ -1437,6 +1448,10 @@ var PLAN_ACTION_PARAMETER_METADATA = {
     description: "Plan lifecycle mode.",
     examples: ["draft", "research", "approved"]
   },
+  step: {
+    description: "Ordered initial step titles for create (string or array, never comma-split; stepTitle, when also set, becomes the first step). For step subcommands a single value aliases stepTitle.",
+    examples: [["Read the code", "Write the fix", "Run the tests"]]
+  },
   file: {
     description: "File link to attach while creating or materializing a Plan.",
     examples: ["path=src/cli.ts,note=implementation surface"]
@@ -1771,6 +1786,9 @@ var PM_TOOL_PARAMETER_METADATA = {
   dryRun: {
     description: "Preview command effects without mutating storage artifacts."
   },
+  all: {
+    description: "For history-repair action: scan every stream for drift and repair each drifted stream in one audited pass (mutually exclusive with id)."
+  },
   gcScope: {
     description: "Repeatable gc scope selector values (index, embeddings, runtime, locks).",
     examples: [["index", "embeddings"], ["runtime"], ["locks"]]
@@ -1885,6 +1903,16 @@ var PM_TOOL_PARAMETER_METADATA = {
   fixHints: {
     description: "For validate action, add a machine-executable fix_hints[] of pm commands to each failing check's details."
   },
+  autoFix: {
+    description: "For validate action, apply the safe, deterministic subset of fix-hint remediations (field backfills) automatically; combine with dryRun to preview and fixScope to grant gated scopes."
+  },
+  fixScope: {
+    description: "For validate action, grant --auto-fix scopes (metadata, resolution, lifecycle). Defaults to the safe scopes metadata and resolution; lifecycle must be named explicitly.",
+    examples: [["lifecycle"], ["metadata", "resolution"]]
+  },
+  pruneMissing: {
+    description: "For validate action, remove stale linked-file/doc LINKS whose paths classified as deleted (link removal only \u2014 never touches real files); honors dryRun."
+  },
   checkHistoryDrift: {
     description: "Run item/history hash drift checks."
   },
@@ -1933,6 +1961,14 @@ var PM_TOOL_PARAMETER_METADATA = {
     description: "Note attached to file links added by files discovery.",
     examples: ["discovered from item text"]
   },
+  addNote: {
+    description: "Note attached to every link added by add/addGlob in this call (per-entry embedded note= wins; requires add or addGlob). Maps to the CLI --note flag on pm files/pm docs.",
+    examples: ["command wiring"]
+  },
+  list: {
+    description: "When true for files/docs action, list the current linked paths without mutating them.",
+    examples: [true]
+  },
   stream: {
     description: "Stream selector: test-runs logs accepts stdout|stderr|both; activity accepts boolean/rows|ndjson|jsonl for line-delimited output.",
     examples: ["stderr", "stdout", "both", "rows", "ndjson", "jsonl", true]
@@ -2242,6 +2278,9 @@ var FILES_FLAG_CONTRACTS = [
   { flag: "--add-glob" },
   { flag: "--remove" },
   { flag: "--migrate" },
+  // GH-170 (pm-pfnx): single-value note applied to every --add/--add-glob link
+  // in the invocation (embedded note= wins; usage error without an add).
+  { flag: "--note" },
   { flag: "--list" },
   { flag: "--append-stable" },
   { flag: "--validate-paths" },
@@ -2255,6 +2294,9 @@ var DOCS_FLAG_CONTRACTS = [
   { flag: "--add-glob" },
   { flag: "--remove" },
   { flag: "--migrate" },
+  // GH-170 (pm-pfnx): see FILES_FLAG_CONTRACTS --note.
+  { flag: "--note" },
+  { flag: "--list" },
   { flag: "--validate-paths" },
   { flag: "--audit" },
   { flag: "--author" },
@@ -2279,6 +2321,7 @@ var HISTORY_REDACT_FLAG_CONTRACTS = [
   { flag: "--force" }
 ];
 var HISTORY_REPAIR_FLAG_CONTRACTS = [
+  { flag: "--all" },
   { flag: "--dry-run" },
   { flag: "--author" },
   { flag: "--message" },
@@ -2320,7 +2363,12 @@ var PLAN_FLAG_CONTRACTS = [
   { flag: "--body" },
   { flag: "--claim" },
   { flag: "--from-search", aliases: ["--from_search"] },
-  { flag: "--step-title", aliases: ["--step", "--step_title"] },
+  { flag: "--step-title", aliases: ["--step_title"] },
+  // pm-6mit: --step is a Commander collect repeatable (ordered step titles on
+  // create; single-value stepTitle alias elsewhere). It must NOT be list:true —
+  // the bootstrap coalescer comma-joins list flags and would corrupt titles
+  // containing commas.
+  { flag: "--step" },
   { flag: "--step-body", aliases: ["--step_body"] },
   { flag: "--step-owner", aliases: ["--step_owner"] },
   { flag: "--step-status", aliases: ["--step_status"] },
@@ -2663,6 +2711,13 @@ var VALIDATE_FLAG_CONTRACTS = [
   { flag: "--strict-exit" },
   { flag: "--fail-on-warn" },
   { flag: "--fix-hints" },
+  { flag: "--auto-fix" },
+  { flag: "--dry-run" },
+  // NOT list:true — repeatable via Commander's collector; the bootstrap
+  // coalescer must not comma-join occurrences (values may also be
+  // comma-separated lists which the resolver splits itself).
+  { flag: "--fix-scope" },
+  { flag: "--prune-missing" },
   { flag: "--check-history-drift" },
   { flag: "--check-command-references" }
 ];
@@ -3523,8 +3578,9 @@ var PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
     anyOfRequired: [["literal"], ["regex"]]
   },
   "history-repair": {
-    required: ["id"],
-    optional: ["dryRun", ...AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS]
+    // Exactly one of `id` (single stream) or `all` (bulk drift repair) is required.
+    optional: ["id", "all", "dryRun", ...AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS],
+    oneOfRequired: [["id"], ["all"]]
   },
   "history-compact": {
     required: ["id"],
@@ -3566,6 +3622,7 @@ var PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
       "claim",
       "fromSearch",
       "stepTitle",
+      "step",
       "stepBody",
       "stepOwner",
       "stepStatus",
@@ -3645,6 +3702,10 @@ var PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
       "addGlob",
       "remove",
       "migrate",
+      // GH-170 (pm-pfnx): `addNote` is the MCP spelling of the CLI --note flag
+      // (the shared `note` parameter is the array-typed create/update note
+      // seed, so files/docs use a distinct single-string key).
+      "addNote",
       "discover",
       "apply",
       "discoveryNote",
@@ -3652,11 +3713,23 @@ var PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
       "validatePaths",
       "audit",
       ...AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS
-    ]
+    ],
+    dependentAnyOfRequired: [{ property: "addNote", anyOfRequired: [["add"], ["addGlob"]] }]
   },
   docs: {
     required: ["id"],
-    optional: ["add", "addGlob", "remove", "migrate", "validatePaths", "audit", ...AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS]
+    optional: [
+      "add",
+      "addGlob",
+      "remove",
+      "migrate",
+      "addNote",
+      "list",
+      "validatePaths",
+      "audit",
+      ...AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS
+    ],
+    dependentAnyOfRequired: [{ property: "addNote", anyOfRequired: [["add"], ["addGlob"]] }]
   },
   deps: { required: ["id"], optional: ["format", "maxDepth", "collapse", "summary"] },
   test: {
@@ -3762,6 +3835,10 @@ var PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
       "strictExit",
       "failOnWarn",
       "fixHints",
+      "autoFix",
+      "dryRun",
+      "fixScope",
+      "pruneMissing",
       "checkHistoryDrift",
       "checkCommandReferences"
     ]
@@ -3842,6 +3919,16 @@ function buildActionScopedToolSchema(action) {
       required: [...requiredFields]
     }));
   }
+  if (contract.oneOfRequired && contract.oneOfRequired.length > 0) {
+    schema.oneOf = contract.oneOfRequired.map((requiredFields) => {
+      const otherFields = contract.oneOfRequired?.flat().filter((field) => !requiredFields.includes(field)) ?? [];
+      return {
+        required: [...requiredFields],
+        ...otherFields.length > 0 ? { not: { anyOf: otherFields.map((field) => ({ required: [field] })) } } : {},
+        ...action === "history-repair" && requiredFields.includes("all") ? { properties: { all: { const: true } } } : {}
+      };
+    });
+  }
   if (contract.conditionalRequired && contract.conditionalRequired.length > 0) {
     schema.allOf = contract.conditionalRequired.map((entry) => ({
       if: {
@@ -3855,6 +3942,20 @@ function buildActionScopedToolSchema(action) {
       }
     }));
   }
+  if (contract.dependentAnyOfRequired && contract.dependentAnyOfRequired.length > 0) {
+    const allOf = Array.isArray(schema.allOf) ? [...schema.allOf] : [];
+    for (const entry of contract.dependentAnyOfRequired) {
+      allOf.push({
+        if: { required: [entry.property] },
+        then: {
+          anyOf: entry.anyOfRequired.map((requiredFields) => ({
+            required: [...requiredFields]
+          }))
+        }
+      });
+    }
+    schema.allOf = allOf;
+  }
   return schema;
 }
 function createLazyContractSchema(build) {
@@ -3873,7 +3974,7 @@ function createLazyContractSchema(build) {
     }
   });
 }
-var PM_TOOL_PARAMETERS_SCHEMA_VERSION = "4.0.2";
+var PM_TOOL_PARAMETERS_SCHEMA_VERSION = "4.0.3";
 var PM_TOOL_PARAMETERS_SCHEMA_MAJOR = PM_TOOL_PARAMETERS_SCHEMA_VERSION.split(".")[0];
 var PM_PROVIDER_TOOL_PARAMETERS_SCHEMA_VERSION = "1.0.0";
 var PM_TOOL_PARAMETERS_SCHEMA = createLazyContractSchema(() => ({
@@ -4022,6 +4123,6 @@ export {
   resolveSubcommandFlagContractsForCommand,
   PM_TOOL_PARAMETERS_SCHEMA
 };
-//# sourceMappingURL=chunk-QJ2OIEOC.js.map
+//# sourceMappingURL=chunk-UIG4TW2H.js.map
 
-//# debugId=2533bfec-8cab-58ea-acd2-3582f0f1b6bd
+//# debugId=60d8e31c-b4ba-5c8f-b2dc-523d0a2b3b13