@unbrained/pm-cli 2026.9.3 → 2026.9.5

package/dist/sdk/governance/merge-receipt-history.d.ts

@@ -0,0 +1,62 @@
+/** First commit timestamp at which merge receipts gained a tracked durable copy. */
+export declare const DURABLE_MERGE_RECEIPT_INTRODUCED_AT = "2026-08-09T16:15:18.000Z";
+/** One receipt reference discovered at an immutable history coordinate. */
+export interface HistoryMergeReceiptReference {
+    /** Item whose history contains the summary. */
+    itemId: string;
+    /** One-based history line containing the summary. */
+    line: number;
+    /** Privacy-safe receipt identifier. */
+    receiptId: string;
+    /** Whether the summary is a complete supported preferred-era record. */
+    legacySummaryAccepted: boolean;
+    /** Timestamp of the history event that introduced the reference, when valid. */
+    eventTimestamp?: string;
+}
+/** Audited disposition for one receipt that a pre-durable writer could never publish. */
+export interface HistoryMergeReceiptDisposition {
+    /** Item whose history contains both the original reference and disposition. */
+    itemId: string;
+    /** Receipt identity explicitly accepted as unrecoverable. */
+    receiptId: string;
+    /** One-based coordinate of the original merge event. */
+    originalHistoryLine: number;
+    /** Timestamp copied from the original merge event for exact matching. */
+    originalEventTimestamp: string;
+    /** One-based coordinate of the later audit event that records this disposition. */
+    auditHistoryLine: number;
+    /** Closed reason vocabulary for this exceptional compatibility path. */
+    reason: "legacy_clone_local_only";
+}
+/** Missing-reference coordinate returned to bounded integrity diagnostics. */
+export interface MissingHistoryMergeReceiptReference {
+    /** Item whose history contains the unresolved reference. */
+    item_id: string;
+    /** One-based history line containing the unresolved reference. */
+    history_line: number;
+    /** Safe identifier when the source value is suitable for diagnostics. */
+    receipt_id?: string;
+    /** Digest used instead of an unsafe identifier. */
+    receipt_reference_hash?: string;
+}
+/** Partitioned compatibility outcome for all scanned history references. */
+export interface HistoryMergeReceiptReferenceClassification {
+    /** References requiring authoritative external evidence. */
+    missing: MissingHistoryMergeReceiptReference[];
+    /** Complete preferred-era summaries accepted without impossible migration. */
+    acceptedLegacyCount: number;
+    /** Pre-durable references accepted by a later explicit audited disposition. */
+    acceptedDispositionCount: number;
+}
+/** Return whether one summary is a complete, self-contained preferred-era receipt. */
+export declare function isLegacyMergeReceiptSummary(value: Record<string, unknown>, historyItemId: string): boolean;
+/** Return whether a summary matches the final clone-local-only schema before durable receipts. */
+export declare function isPreDurableCloneLocalReceiptSummary(value: Record<string, unknown>, historyItemId: string): boolean;
+/** Return whether an extracted reference carried a validated pre-durable summary. */
+export declare function isPreDurableDispositionEligibleReference(reference: Omit<HistoryMergeReceiptReference, "itemId" | "line">): boolean;
+/** Extract receipt ids and legacy compatibility disposition from one history entry. */
+export declare function extractHistoryMergeReceiptReferences(value: unknown, historyItemId: string): Array<Omit<HistoryMergeReceiptReference, "itemId" | "line">>;
+/** Extract validated explicit missing-receipt dispositions from one merge audit event. */
+export declare function extractHistoryMergeReceiptDispositions(value: unknown, historyItemId: string, historyLine: number): HistoryMergeReceiptDisposition[];
+/** Classify scanned references without treating complete legacy summaries as absent. */
+export declare function classifyHistoryMergeReceiptReferences(references: readonly HistoryMergeReceiptReference[], availableReceiptIds: ReadonlySet<string>, dispositions?: readonly HistoryMergeReceiptDisposition[]): HistoryMergeReceiptReferenceClassification;

package/dist/sdk/governance/merge-receipt-history.js

@@ -0,0 +1,207 @@
+/**
+ * @module sdk/governance/merge-receipt-history
+ *
+ * Classifies privacy-safe merge receipt references embedded in history.
+ */
+
+!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]="1e73338f-221a-580f-85a8-6f2a488fb89d")}catch(e){}}();
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { compareTimestampStrings, isRfc3339DateTime, } from "../../core/shared/time.js";
+import { isSafeReceiptId } from "../merge/receipts.js";
+/** First commit timestamp at which merge receipts gained a tracked durable copy. */
+export const DURABLE_MERGE_RECEIPT_INTRODUCED_AT = "2026-08-09T16:15:18.000Z";
+const PRE_DURABLE_DISPOSITION_ELIGIBLE = Symbol("pre-durable-disposition-eligible");
+/** Return whether an unknown value is a non-array record. */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Return a bounded dense list of unique, non-empty field names. */
+function isFieldArray(value) {
+    if (!Array.isArray(value) || value.length > 256)
+        return false;
+    const fields = new Set();
+    for (let index = 0; index < value.length; index += 1) {
+        const field = value[index];
+        if (!(index in value) ||
+            typeof field !== "string" ||
+            field.length === 0 ||
+            field.length > 256 ||
+            field.includes("\0") ||
+            fields.has(field)) {
+            return false;
+        }
+        fields.add(field);
+    }
+    return true;
+}
+/** Return whether an unknown value is one complete legacy field decision. */
+function isLegacyDecision(value) {
+    if (!isRecord(value))
+        return false;
+    return (typeof value.field === "string" &&
+        value.field.length > 0 &&
+        value.field.length <= 256 &&
+        !value.field.includes("\0") &&
+        typeof value.retained_hash === "string" &&
+        /^[a-f0-9]{64}$/u.test(value.retained_hash) &&
+        typeof value.discarded_hash === "string" &&
+        /^[a-f0-9]{64}$/u.test(value.discarded_hash));
+}
+/** Return whether a legacy item path is normalized, bounded, and item-scoped. */
+function isLegacyItemPath(value, historyItemId) {
+    if (typeof value !== "string")
+        return false;
+    const normalized = path.posix.normalize(value);
+    return (value.length <= 4_096 &&
+        !value.includes("\\") &&
+        !value.includes("\0") &&
+        !path.posix.isAbsolute(value) &&
+        normalized === value &&
+        !normalized.startsWith("../") &&
+        (path.posix.basename(normalized) === `${historyItemId}.toon` ||
+            path.posix.basename(normalized) === `${historyItemId}.md`));
+}
+/** Return whether a preferred-era summary has one safe canonical identity. */
+function hasLegacyReceiptIdentity(value, historyItemId) {
+    return (typeof value.receipt_id === "string" &&
+        isSafeReceiptId(value.receipt_id) &&
+        (value.preferred === "ours" || value.preferred === "theirs") &&
+        value.requested_preference === undefined &&
+        value.conflict_resolution === undefined &&
+        value.item_id === historyItemId &&
+        isLegacyItemPath(value.item_path, historyItemId));
+}
+/** Return whether preferred-era summary collections are dense and self-consistent. */
+function hasLegacyReceiptCollections(value) {
+    const conflictFields = value.conflict_fields;
+    const fieldsFromTheirs = value.fields_from_theirs;
+    const unionFields = value.union_fields;
+    const decisions = value.decisions;
+    const decisionFields = Array.isArray(decisions)
+        ? new Set(decisions.flatMap((decision) => isLegacyDecision(decision) ? [decision.field] : []))
+        : new Set();
+    return (isFieldArray(conflictFields) &&
+        isFieldArray(fieldsFromTheirs) &&
+        isFieldArray(unionFields) &&
+        Array.isArray(decisions) &&
+        decisions.length > 0 &&
+        decisions.length <= 256 &&
+        Object.keys(decisions).length === decisions.length &&
+        decisions.every(isLegacyDecision) &&
+        decisionFields.size === decisions.length &&
+        conflictFields.length === decisionFields.size &&
+        conflictFields.every((field) => decisionFields.has(field)));
+}
+/** Return whether one summary is a complete, self-contained preferred-era receipt. */
+export function isLegacyMergeReceiptSummary(value, historyItemId) {
+    return (hasLegacyReceiptIdentity(value, historyItemId) &&
+        hasLegacyReceiptCollections(value));
+}
+/** Return whether a summary matches the final clone-local-only schema before durable receipts. */
+export function isPreDurableCloneLocalReceiptSummary(value, historyItemId) {
+    return (typeof value.receipt_id === "string" &&
+        isSafeReceiptId(value.receipt_id) &&
+        (value.preferred === "ours" || value.preferred === "theirs") &&
+        value.requested_preference === undefined &&
+        (value.conflict_resolution === "preferred_side" ||
+            value.conflict_resolution === "stable_value_order") &&
+        value.item_id === historyItemId &&
+        isLegacyItemPath(value.item_path, historyItemId) &&
+        hasLegacyReceiptCollections(value));
+}
+/** Return whether an extracted reference carried a validated pre-durable summary. */
+export function isPreDurableDispositionEligibleReference(reference) {
+    return (reference[PRE_DURABLE_DISPOSITION_ELIGIBLE] === true);
+}
+/** Extract receipt ids and legacy compatibility disposition from one history entry. */
+export function extractHistoryMergeReceiptReferences(value, historyItemId) {
+    if (!isRecord(value) || !isRecord(value.context))
+        return [];
+    const merge = value.context.merge;
+    if (!isRecord(merge) || !Array.isArray(merge.receipts))
+        return [];
+    return merge.receipts.flatMap((receipt) => {
+        if (!isRecord(receipt) ||
+            typeof receipt.receipt_id !== "string" ||
+            receipt.receipt_id.trim().length === 0) {
+            return [];
+        }
+        const reference = {
+            receiptId: receipt.receipt_id,
+            legacySummaryAccepted: isLegacyMergeReceiptSummary(receipt, historyItemId),
+            [PRE_DURABLE_DISPOSITION_ELIGIBLE]: isPreDurableCloneLocalReceiptSummary(receipt, historyItemId),
+            ...(typeof value.ts === "string" && isRfc3339DateTime(value.ts)
+                ? { eventTimestamp: value.ts }
+                : {}),
+        };
+        return [reference];
+    });
+}
+/** Extract validated explicit missing-receipt dispositions from one merge audit event. */
+export function extractHistoryMergeReceiptDispositions(value, historyItemId, historyLine) {
+    if (!isRecord(value) || value.op !== "merge_reconcile")
+        return [];
+    if (!isRecord(value.context) || !isRecord(value.context.merge))
+        return [];
+    const dispositions = value.context.merge.missing_receipt_dispositions;
+    if (!Array.isArray(dispositions) || dispositions.length > 256)
+        return [];
+    return dispositions.flatMap((disposition) => {
+        if (!isRecord(disposition) ||
+            typeof disposition.receipt_id !== "string" ||
+            !isSafeReceiptId(disposition.receipt_id) ||
+            typeof disposition.original_history_line !== "number" ||
+            !Number.isSafeInteger(disposition.original_history_line) ||
+            disposition.original_history_line < 1 ||
+            typeof disposition.original_event_ts !== "string" ||
+            !isRfc3339DateTime(disposition.original_event_ts) ||
+            disposition.reason !== "legacy_clone_local_only") {
+            return [];
+        }
+        return [
+            {
+                itemId: historyItemId,
+                receiptId: disposition.receipt_id,
+                originalHistoryLine: disposition.original_history_line,
+                originalEventTimestamp: disposition.original_event_ts,
+                auditHistoryLine: historyLine,
+                reason: disposition.reason,
+            },
+        ];
+    });
+}
+/** Classify scanned references without treating complete legacy summaries as absent. */
+export function classifyHistoryMergeReceiptReferences(references, availableReceiptIds, dispositions = []) {
+    const dispositionAuditLineByCoordinate = new Map();
+    for (const disposition of dispositions) {
+        const coordinate = `${disposition.itemId}\0${disposition.originalHistoryLine}\0${disposition.receiptId}\0${disposition.originalEventTimestamp}`;
+        dispositionAuditLineByCoordinate.set(coordinate, Math.max(dispositionAuditLineByCoordinate.get(coordinate) ?? 0, disposition.auditHistoryLine));
+    }
+    const dispositionAccepts = (reference) => isPreDurableDispositionEligibleReference(reference) &&
+        reference.eventTimestamp !== undefined &&
+        compareTimestampStrings(reference.eventTimestamp, DURABLE_MERGE_RECEIPT_INTRODUCED_AT) < 0 &&
+        (dispositionAuditLineByCoordinate.get(`${reference.itemId}\0${reference.line}\0${reference.receiptId}\0${reference.eventTimestamp}`) ?? 0) > reference.line;
+    const missing = references
+        .filter((reference) => !reference.legacySummaryAccepted &&
+        !availableReceiptIds.has(reference.receiptId) &&
+        !dispositionAccepts(reference))
+        .map((reference) => ({
+        item_id: reference.itemId,
+        history_line: reference.line,
+        ...(isSafeReceiptId(reference.receiptId)
+            ? { receipt_id: reference.receiptId }
+            : {
+                receipt_reference_hash: createHash("sha256")
+                    .update(reference.receiptId)
+                    .digest("hex"),
+            }),
+    }));
+    return {
+        missing,
+        acceptedLegacyCount: references.filter((reference) => reference.legacySummaryAccepted).length,
+        acceptedDispositionCount: references.filter(dispositionAccepts).length,
+    };
+}
+//# sourceMappingURL=merge-receipt-history.js.map
+//# debugId=1e73338f-221a-580f-85a8-6f2a488fb89d

package/dist/sdk/governance/provenance-health.js

@@ -4,9 +4,10 @@
  * Reads bounded, privacy-safe provenance resolver outcomes for health 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]="6efed404-acd2-5c3a-a008-856df67c8b77")}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]="cb3bf7ee-808f-5ff6-af84-edb034760c54")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
+import { resealHistoryRewrite, verifyHistoryRecordHash, } from "../../core/history/history.js";
 const DEFAULT_PROVENANCE_HISTORY_BYTE_LIMIT = 8_388_608;
 const ATTEMPTED_PROVENANCE_OUTCOME_STATUSES = new Set(["resolved", "failed"]);
 const INVALID_PROVENANCE_VALUE_CLASSIFIERS = [
@@ -45,6 +46,8 @@ export function normalizeInvalidHistoryProvenance(entries) {
             : undefined;
         if (provenance === undefined)
             return entry;
+        if (!verifyHistoryRecordHash(entry).ok)
+            return entry;
         const retained = {};
         let eventChanged = false;
         for (const [dimension, observation] of Object.entries(provenance)) {
@@ -78,7 +81,10 @@ export function normalizeInvalidHistoryProvenance(entries) {
         else {
             next.agent_provenance = retained;
         }
-        return next;
+        return resealHistoryRewrite(entry, next, {
+            retainPriorRecord: true,
+            retainPriorRecordHash: false,
+        });
     });
     return {
         entries: normalized,
@@ -274,4 +280,4 @@ export async function scanProvenanceResolverHealth(pmRoot, eventLimit = 10_000)
     };
 }
 //# sourceMappingURL=provenance-health.js.map
-//# debugId=6efed404-acd2-5c3a-a008-856df67c8b77
+//# debugId=cb3bf7ee-808f-5ff6-af84-edb034760c54

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>;