@unbrained/pm-cli 2026.9.4 → 2026.9.5

package/dist/sdk/generated/generated-error-code-catalog-part-1.js

@@ -1,6 +1,6 @@
 /** Generated partition 1 of the exhaustive error-code catalog. */
 
-!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]="f9059953-1d3c-5c1c-b739-4ad6cc8815a3")}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]="2d5b7e84-f6a6-5c48-a72b-a929ab2186f7")}catch(e){}}();
 export const PM_ERROR_CODE_CATALOG_PART_1 = [
     {
         code: "acceptance_criteria_mutation_conflict",
@@ -1163,6 +1163,18 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "history_author_acknowledge_target_unreadable",
         aliases: [],
     },
+    {
+        code: "history_baseline_unavailable",
+        meaning: "History baseline unavailable condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["core/history/projection.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "history_baseline_unavailable",
+        aliases: [],
+    },
     {
         code: "history_drift_chain_mismatch",
         meaning: "History drift chain mismatch condition.",
@@ -1235,6 +1247,18 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "history_drift_version_skew",
         aliases: ["validate_history_drift_version_skews"],
     },
+    {
+        code: "history_json_invalid",
+        meaning: "History json invalid condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["core/history/read.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "history_json_invalid",
+        aliases: [],
+    },
     {
         code: "history_merge_conflict_markers_detected",
         meaning: "History merge conflict markers detected condition.",
@@ -1247,6 +1271,30 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "merge_conflict_markers_detected",
         aliases: [],
     },
+    {
+        code: "history_replay_invalid",
+        meaning: "History replay invalid condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["core/history/projection.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "history_replay_invalid",
+        aliases: [],
+    },
+    {
+        code: "history_salvage_refused",
+        meaning: "History salvage refused condition.",
+        stability: "provisional",
+        exit_code: 4,
+        class: "conflict",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/history/salvage.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "history_salvage_refused",
+        aliases: [],
+    },
     {
         code: "history_stream_over_compact_threshold",
         meaning: "History stream over compact threshold condition.",
@@ -1295,6 +1343,30 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "history_unknown_author_events",
         aliases: ["validate_history_unknown_author_events"],
     },
+    {
+        code: "history_version_mapping_unavailable",
+        meaning: "History version mapping unavailable condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["core/history/version-address.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "history_version_mapping_unavailable",
+        aliases: [],
+    },
+    {
+        code: "history_version_pruned",
+        meaning: "History version pruned condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["core/history/projection.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "history_version_pruned",
+        aliases: [],
+    },
     {
         code: "host_environment_capacity_fault",
         meaning: "Host environment capacity fault condition.",
@@ -1797,6 +1869,18 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "item_already_active",
         aliases: [],
     },
+    {
+        code: "item_document_encoding_invalid",
+        meaning: "Item document encoding invalid condition.",
+        stability: "provisional",
+        exit_code: 4,
+        class: "conflict",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["core/store/item-store.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "item_document_encoding_invalid",
+        aliases: [],
+    },
     {
         code: "item_document_invalid",
         meaning: "Item document invalid condition.",
@@ -1833,6 +1917,18 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "item_id_collision",
         aliases: [],
     },
+    {
+        code: "item_identity_reserved",
+        meaning: "Item identity reserved condition.",
+        stability: "provisional",
+        exit_code: 4,
+        class: "conflict",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["core/history/history.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "item_identity_reserved",
+        aliases: [],
+    },
     {
         code: "item_not_found",
         meaning: "Item not found condition.",
@@ -2124,54 +2220,6 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "merge_reconcile_receipt_evidence_untrusted",
         aliases: [],
     },
-    {
-        code: "merge_root_not_found",
-        meaning: "Merge root not found condition.",
-        stability: "stable",
-        exit_code: 3,
-        class: "not_found",
-        recovery: "Inspect the structured error guidance and retry the suggested command.",
-        sources: ["sdk/merge/install.ts"],
-        emitting_commands: ["*"],
-        canonical_code: "merge_root_not_found",
-        aliases: [],
-    },
-    {
-        code: "missing_allowed_values",
-        meaning: "Missing allowed values condition.",
-        stability: "provisional",
-        exit_code: 1,
-        class: "generic_failure",
-        recovery: "Inspect the structured error guidance and retry the suggested command.",
-        sources: ["sdk/agent/refusal-closure.ts"],
-        emitting_commands: ["*"],
-        canonical_code: "missing_allowed_values",
-        aliases: [],
-    },
-    {
-        code: "missing_budget",
-        meaning: "Missing budget condition.",
-        stability: "provisional",
-        exit_code: 1,
-        class: "generic_failure",
-        recovery: "Inspect the structured error guidance and retry the suggested command.",
-        sources: ["sdk/cli-contracts/flag-lexicon-contracts.ts"],
-        emitting_commands: ["*"],
-        canonical_code: "missing_budget",
-        aliases: [],
-    },
-    {
-        code: "missing_cli_flag",
-        meaning: "Missing cli flag condition.",
-        stability: "provisional",
-        exit_code: 1,
-        class: "generic_failure",
-        recovery: "Inspect the structured error guidance and retry the suggested command.",
-        sources: ["sdk/cli-contracts/tool-option-contracts.ts"],
-        emitting_commands: ["*"],
-        canonical_code: "missing_cli_flag",
-        aliases: [],
-    },
 ];
 //# sourceMappingURL=generated-error-code-catalog-part-1.js.map
-//# debugId=f9059953-1d3c-5c1c-b739-4ad6cc8815a3
+//# debugId=2d5b7e84-f6a6-5c48-a72b-a929ab2186f7

package/dist/sdk/generated/generated-error-code-catalog-part-2.js

@@ -1,7 +1,55 @@
 /** Generated partition 2 of the exhaustive error-code catalog. */
 
-!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]="f1a77960-6191-5e11-9622-4250be7b0e89")}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]="aa8f034d-d4b6-595b-af76-f7203d062971")}catch(e){}}();
 export const PM_ERROR_CODE_CATALOG_PART_2 = [
+    {
+        code: "merge_root_not_found",
+        meaning: "Merge root not found condition.",
+        stability: "stable",
+        exit_code: 3,
+        class: "not_found",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/merge/install.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "merge_root_not_found",
+        aliases: [],
+    },
+    {
+        code: "missing_allowed_values",
+        meaning: "Missing allowed values condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/agent/refusal-closure.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "missing_allowed_values",
+        aliases: [],
+    },
+    {
+        code: "missing_budget",
+        meaning: "Missing budget condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/cli-contracts/flag-lexicon-contracts.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "missing_budget",
+        aliases: [],
+    },
+    {
+        code: "missing_cli_flag",
+        meaning: "Missing cli flag condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/cli-contracts/tool-option-contracts.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "missing_cli_flag",
+        aliases: [],
+    },
     {
         code: "missing_destination",
         meaning: "Missing destination condition.",
@@ -2186,4 +2234,4 @@ export const PM_ERROR_CODE_CATALOG_PART_2 = [
     },
 ];
 //# sourceMappingURL=generated-error-code-catalog-part-2.js.map
-//# debugId=f1a77960-6191-5e11-9622-4250be7b0e89
+//# debugId=aa8f034d-d4b6-595b-af76-f7203d062971

package/dist/sdk/governance/validate-history-drift.js

@@ -6,7 +6,7 @@
  * orchestration module.
  */
 
-!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]="8bec3c39-b871-5c7c-907c-6da66274d9be")}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]="a2c96f3a-fa7a-538f-ae11-7b821e5b7ab2")}catch(e){}}();
 import { scanHistoryDrift } from "../../core/history/drift-scan.js";
 const DEFAULT_DIAGNOSTIC_LIMIT = 5;
 /** Build the validation warning and bounded evidence projection for history drift. */
@@ -14,7 +14,10 @@ export async function buildValidateHistoryDriftCheck(pmRoot, items, verboseDiagn
     const drift = await scanHistoryDrift(pmRoot, items);
     const warningCounts = [
         ["validate_history_drift_missing_streams", drift.missingStreams.length],
-        ["validate_history_drift_unreadable_streams", drift.unreadableStreams.length],
+        [
+            "validate_history_drift_unreadable_streams",
+            drift.unreadableStreams.length,
+        ],
         ["validate_history_drift_hash_mismatches", drift.hashMismatches.length],
         ["validate_history_drift_chain_mismatches", drift.chainMismatches.length],
         ["validate_history_drift_version_skews", drift.versionSkews.length],
@@ -38,12 +41,20 @@ export async function buildValidateHistoryDriftCheck(pmRoot, items, verboseDiagn
         ? Number.POSITIVE_INFINITY
         : DEFAULT_DIAGNOSTIC_LIMIT;
     const driftedItems = drift.driftedItems.slice(0, diagnosticLimit);
+    const identityDiscontinuities = drift.identityDiscontinuities ?? [];
     return {
         check: {
             name: "history_drift",
-            status: warnings.length === 0 ? "ok" : "warn",
-            ok: warnings.length === 0,
+            status: identityDiscontinuities.length > 0
+                ? "error"
+                : warnings.length === 0
+                    ? "ok"
+                    : "warn",
+            ok: identityDiscontinuities.length === 0 && warnings.length === 0,
             details: {
+                identity_discontinuities: identityDiscontinuities.slice(0, diagnosticLimit),
+                identity_discontinuities_count: identityDiscontinuities.length,
+                identity_discontinuities_truncated: identityDiscontinuities.length > diagnosticLimit,
                 checked_items: items.length,
                 drifted_items_count: drift.driftedItems.length,
                 drifted_items: driftedItems,
@@ -68,4 +79,4 @@ export async function buildValidateHistoryDriftCheck(pmRoot, items, verboseDiagn
     };
 }
 //# sourceMappingURL=validate-history-drift.js.map
-//# debugId=8bec3c39-b871-5c7c-907c-6da66274d9be
+//# debugId=a2c96f3a-fa7a-538f-ae11-7b821e5b7ab2

package/dist/sdk/guide-topics.js

@@ -4,7 +4,7 @@
  * Provides CLI runtime support for Guide Topics.
  */
 
-!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]="7c57f381-8318-5235-aa92-c96c6cedb021")}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]="feba1227-c2a2-5ca3-83e6-3fd2780e6cbb")}catch(e){}}();
 import { listPmCommandCapabilityGroups } from "./agent-capability-contracts.js";
 function normalizeTopicToken(value) {
     return value.trim().toLowerCase().replaceAll("_", "-");
@@ -518,6 +518,8 @@ const GUIDE_TOPICS = [
         intent: "Use this when more than one agent or worktree mutates the same tracker and the results must merge without hand resolution.",
         commands: [
             "pm merge install",
+            "pm merge report",
+            "pm merge reconcile --dry-run",
             "pm claim <ID>",
             "pm release <ID>",
             "pm validate --check-history-drift",
@@ -530,6 +532,17 @@ const GUIDE_TOPICS = [
                 prompt: "Run the merge installer in every fresh clone or worktree before the first branch merge of tracker data.",
                 commands: ["pm merge install", "pm health --check-only"],
             },
+            {
+                name: "Settle A Merge Before Trusting Health",
+                goal: "A lossless merge still leaves pending receipts that strict health reports until they are reconciled.",
+                prompt: "After any branch merge that touched tracker data, read the merge report, preview the reconciliation, then apply it; only then treat a health verdict as a statement about the data.",
+                commands: [
+                    "pm merge report",
+                    "pm merge reconcile --dry-run",
+                    'pm merge reconcile --message "Post-merge history reconciliation"',
+                    "pm health --check-only",
+                ],
+            },
             {
                 name: "Hand Work Between Agents Safely",
                 goal: "Ownership and evidence survive the handoff.",
@@ -553,6 +566,107 @@ const GUIDE_TOPICS = [
         ],
         related: ["workflows", "assurance", "commands"],
     },
+    {
+        id: "evidence",
+        aliases: ["record", "annotations", "learnings", "history-maintenance"],
+        title: "Evidence, Durable Knowledge, and Record Maintenance",
+        summary: "Append comments, notes, learnings, files, docs, and tests to items, and maintain the immutable history those records live in.",
+        intent: "Use this when work must be explained to the next agent, when a durable lesson should outlive the item, or when a history stream needs verification, repair, redaction, compaction, or author attribution.",
+        commands: [
+            'pm comments <ID> "<progress or verification evidence>"',
+            'pm notes <ID> --add "<rationale that belongs on the item>"',
+            'pm learnings <ID> --add "<lesson that should outlive the item>"',
+            "pm append <ID> --body -",
+            "pm files <ID> --add path=<path>,scope=project,note=<why>",
+            "pm history <ID> --verify --strict-exit",
+            "pm history-repair --all --dry-run",
+            "pm history-redact <ID> --literal <secret> --dry-run",
+            "pm history-compact <ID> --dry-run",
+            "pm history-author-acknowledge --all-actionable --dry-run",
+            "pm close-many --ids <ID>,<ID> --reason <text> --dry-run",
+            "pm test-all --status open --limit 10 --progress",
+        ],
+        workflows: [
+            {
+                name: "Record While Working, Not After",
+                goal: "Another agent can rebuild the full situation from the item alone.",
+                prompt: "Add a comment for each verified step, a note for each rationale the item body does not carry, and a learning for each lesson that applies beyond this item. Prefer appending over rewriting.",
+                commands: [
+                    'pm comments <ID> "Evidence: <what changed and what passed>"',
+                    'pm notes <ID> --add "Decision log: <why this shape>"',
+                    'pm learnings <ID> --add "<durable lesson>"',
+                    "pm learnings <ID> --limit 5",
+                ],
+            },
+            {
+                name: "Verify And Repair A History Stream",
+                goal: "Every mutation stays provable and the chain re-anchors after drift.",
+                prompt: "Verify the chain with a strict exit before trusting a stream, preview any repair, and record why the repair was needed in the audit message.",
+                commands: [
+                    "pm history <ID> --verify --strict-exit",
+                    "pm history-repair --all --dry-run",
+                    'pm history-repair --all --message "<why the chain drifted>"',
+                    "pm validate --check-history-drift",
+                ],
+            },
+            {
+                name: "Redact, Compact, Or Attribute Without Losing Proof",
+                goal: "Sensitive text, stream length, and unknown authors are handled through audited rewrites.",
+                prompt: "Preview every history rewrite with --dry-run, read the receipt, then apply. Compaction renumbers ordinal versions, so record the checkpoint it created.",
+                commands: [
+                    "pm history-redact <ID> --literal <secret> --dry-run",
+                    "pm history-compact <ID> --dry-run",
+                    "pm history-author-acknowledge --all-actionable --dry-run",
+                ],
+            },
+        ],
+        docs: [
+            {
+                path: "docs/COMMANDS.md",
+                purpose: "Annotation, bulk, and history-and-recovery command families.",
+            },
+            {
+                path: "docs/MUTATION_INTEGRITY.md",
+                purpose: "Provenance and content-safety policy every mutation shares.",
+            },
+            {
+                path: "docs/AGENT_GUIDE.md",
+                purpose: "Evidence expectations in the agent loop and self-repair remediation.",
+            },
+        ],
+        related: ["workflows", "assurance", "merge", "graph"],
+    },
+    {
+        id: "automation",
+        aliases: ["calendar", "reminders", "meetings", "events"],
+        title: "Reminders, Events, and Meetings",
+        summary: "Attach time to items so context and agenda views can surface deadlines, meetings, and reminders when they matter.",
+        intent: "Use this when an item needs a due signal, a scheduled event, or a meeting record that later context reads should surface.",
+        commands: [
+            "pm remind <title> --at <when> --parent <ID>",
+            "pm event <title> --start <when> --parent <ID>",
+            "pm meet <title> --start <when> --duration <span> --parent <ID>",
+            "pm context --limit 10",
+        ],
+        workflows: [
+            {
+                name: "Put A Deadline Where Context Will Find It",
+                goal: "Time-bound work surfaces in the agenda section of context reads.",
+                prompt: "Record the reminder or event under the item that owns the work, then confirm it appears in the agenda summary of a context read.",
+                commands: [
+                    "pm remind <title> --at <when> --parent <ID>",
+                    "pm context --limit 10",
+                ],
+            },
+        ],
+        docs: [
+            {
+                path: "docs/COMMANDS.md",
+                purpose: "Calendar and context command family.",
+            },
+        ],
+        related: ["workflows", "quickstart", "extensions"],
+    },
 ];
 const TOPIC_BY_TOKEN = new Map();
 for (const topic of GUIDE_TOPICS) {
@@ -591,4 +705,4 @@ export function resolveGuideTopic(rawTopic) {
     return TOPIC_BY_TOKEN.get(normalized) ?? null;
 }
 //# sourceMappingURL=guide-topics.js.map
-//# debugId=7c57f381-8318-5235-aa92-c96c6cedb021
+//# debugId=feba1227-c2a2-5ca3-83e6-3fd2780e6cbb

package/dist/sdk/history/salvage.d.ts

@@ -0,0 +1,35 @@
+import { type HistoryItemHashVersion } from "../../core/history/history.js";
+import type { ItemTypeRegistry } from "../../core/item/type-registry.js";
+import type { HistoryEntry, PmSettings } from "../../types/index.js";
+import type { HistorySubject } from "../history-redact.js";
+import type { HistoryRepairCommandOptions, HistoryRepairResult } from "../history-repair.js";
+/** Evidence describing only the discarded suffix, without retaining its contents. */
+export interface HistorySalvageReceipt {
+    /** One-based physical line where invalid trailing bytes begin. */
+    first_invalid_line: number;
+    /** UTF-8 bytes removed from the suffix. */
+    discarded_bytes: number;
+    /** SHA-256 of the removed bytes for local backup comparison. */
+    discarded_sha256: string;
+    /** Number of complete verified records retained. */
+    retained_entries: number;
+}
+/**
+ * Select a hash-verified prefix. Any parseable JSON after the first invalid
+ * line makes the corruption interior and therefore unsalvageable by truncation.
+ */
+export declare function inspectHistoryTail(raw: string): {
+    entries: HistoryEntry[];
+    prefix: string;
+    receipt: HistorySalvageReceipt | null;
+    itemHashVersion: HistoryItemHashVersion;
+};
+/** Salvage one explicitly selected stream under its normal ownership and lock policy. */
+export declare function salvageHistoryTail(params: {
+    pmRoot: string;
+    subject: HistorySubject;
+    settings: PmSettings;
+    typeRegistry: ItemTypeRegistry;
+    options: HistoryRepairCommandOptions;
+    author: string;
+}): Promise<HistoryRepairResult>;