@unbrained/pm-cli 2026.8.15 → 2026.8.16

package/dist/sdk/author-attribution.js

@@ -4,7 +4,8 @@
  * Provides reusable diagnostics for mutation-author provenance in tracker 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]="4fd16197-979e-5269-bed7-f2fb0e2038c2")}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]="b389e521-f689-5895-a5f4-08c3866b3ea3")}catch(e){}}();
+import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { appendWorkspaceAuditEvent, WORKSPACE_HISTORY_ID, } from "../core/history/workspace-history.js";
@@ -204,6 +205,111 @@ export const scanHistoryAuthorAttribution = async (pmRoot, sampleLimit = 20, inc
         ...(includeActionableEvents ? { actionable_events: actionableEvents } : {}),
     };
 };
+/** Deduplicate and deterministically order history coordinates. */
+function normalizeUnknownAuthorHistoryEvents(events) {
+    return [
+        ...new Map(events.map((event) => [
+            `${event.item_id}:${event.line}`,
+            { item_id: event.item_id, line: event.line },
+        ])).values(),
+    ].sort((left, right) => left.item_id.localeCompare(right.item_id) || left.line - right.line);
+}
+/** Read the append-only set of previously dispositioned coordinates. */
+async function readAcknowledgedUnknownEvents(pmRoot) {
+    try {
+        return collectAcknowledgedUnknownEvents(await fs.readFile(path.join(pmRoot, "history", "_workspace.jsonl"), "utf8"));
+    }
+    catch {
+        return new Set();
+    }
+}
+/** Check whether a coordinate can safely name one immutable history line. */
+function isValidUnknownAuthorHistoryEvent(event) {
+    return ((event.item_id === WORKSPACE_HISTORY_ID ||
+        /^[a-z0-9][a-z0-9-]*$/iu.test(event.item_id)) &&
+        Number.isSafeInteger(event.line) &&
+        event.line >= 1);
+}
+/** Resolve one coordinate against its preloaded immutable source stream. */
+function resolveAcknowledgmentPlanCoordinate(event, acknowledgedEvents, sourceLines) {
+    const sourceLine = sourceLines[event.line - 1] ?? "";
+    let parsed;
+    try {
+        parsed = JSON.parse(sourceLine);
+    }
+    catch {
+        refuseAuthorAcknowledgmentArgument(`Unknown-author acknowledgment target ${event.item_id}:${event.line} is not readable.`, { code: "history_author_acknowledge_target_unreadable" });
+    }
+    if (classifyHistoryAuthorEvent(parsed) !== "actionable_unknown") {
+        refuseAuthorAcknowledgmentArgument(`Author acknowledgment target ${event.item_id}:${event.line} is not an actionable unknown-author event.`, { code: "history_author_acknowledge_target_not_actionable" });
+    }
+    return {
+        ...event,
+        source_event_hash: createHash("sha256").update(sourceLine).digest("hex"),
+        disposition: acknowledgedEvents.has(`${event.item_id}:${event.line}`)
+            ? "already_acknowledged"
+            : "actionable",
+    };
+}
+async function resolveUnknownAuthorAcknowledgmentPlan(pmRoot, selector, coordinateLimit) {
+    const explicitEvents = selector.events ?? [];
+    const selectorCount = Number(selector.all_actionable === true) +
+        Number(explicitEvents.length > 0);
+    if (selectorCount === 0) {
+        refuseAuthorAcknowledgmentArgument("Specify exactly one selector: events or all_actionable.", { code: "history_author_acknowledge_selector_required" });
+    }
+    if (selectorCount > 1) {
+        refuseAuthorAcknowledgmentArgument("Author acknowledgment accepts either explicit events or all_actionable, not both.", { code: "history_author_acknowledge_selector_conflict" });
+    }
+    if (!Number.isSafeInteger(coordinateLimit) || coordinateLimit < 0) {
+        refuseAuthorAcknowledgmentArgument("Author acknowledgment coordinate_limit must be a non-negative integer.", { code: "history_author_acknowledge_preview_limit_invalid" });
+    }
+    const selectedEvents = normalizeUnknownAuthorHistoryEvents(selector.all_actionable === true
+        ? (await scanHistoryAuthorAttribution(pmRoot, 0, true))
+            .actionable_events
+        : explicitEvents);
+    const acknowledgedEvents = await readAcknowledgedUnknownEvents(pmRoot);
+    const sourceLinesByItem = new Map();
+    for (const event of selectedEvents) {
+        if (!isValidUnknownAuthorHistoryEvent(event)) {
+            refuseAuthorAcknowledgmentArgument(`Unknown-author acknowledgment target ${event.item_id}:${event.line} is not readable.`, { code: "history_author_acknowledge_target_unreadable" });
+        }
+        if (sourceLinesByItem.has(event.item_id))
+            continue;
+        try {
+            sourceLinesByItem.set(event.item_id, (await fs.readFile(path.join(pmRoot, "history", `${event.item_id}.jsonl`), "utf8")).split(/\r?\n/u));
+        }
+        catch {
+            refuseAuthorAcknowledgmentArgument(`Unknown-author acknowledgment target ${event.item_id}:${event.line} is not readable.`, { code: "history_author_acknowledge_target_unreadable" });
+        }
+    }
+    const completeCoordinates = selectedEvents.map((event) => resolveAcknowledgmentPlanCoordinate(event, acknowledgedEvents, sourceLinesByItem.get(event.item_id)));
+    const kind = selector.all_actionable === true ? "all_actionable" : "events";
+    const planFingerprint = createHash("sha256")
+        .update(JSON.stringify({
+        version: 1,
+        selection: kind,
+        coordinates: completeCoordinates,
+    }))
+        .digest("hex");
+    const actionableCount = completeCoordinates.filter(({ disposition }) => disposition === "actionable").length;
+    return {
+        plan: {
+            selection: { kind },
+            selected_count: completeCoordinates.length,
+            actionable_count: actionableCount,
+            already_acknowledged_count: completeCoordinates.length - actionableCount,
+            omitted_count: Math.max(0, completeCoordinates.length - coordinateLimit),
+            coordinates: completeCoordinates.slice(0, coordinateLimit),
+            plan_fingerprint: planFingerprint,
+        },
+        completeCoordinates,
+    };
+}
+/** Resolve a deterministic, source-bound author-acknowledgement preview. */
+export async function planUnknownAuthorHistoryAcknowledgment(pmRoot, selector, coordinateLimit = 50) {
+    return (await resolveUnknownAuthorAcknowledgmentPlan(pmRoot, selector, coordinateLimit)).plan;
+}
 /** Resolve the mutually exclusive CLI and SDK acknowledgment selectors. */
 export function resolveUnknownAuthorAcknowledgmentSelector(rawEvents, allActionable) {
     const hasExplicitEvents = rawEvents.length > 0;
@@ -254,11 +360,19 @@ export function acknowledgeUnknownAuthorHistoryEventsFromTransport(pmRoot, input
     return acknowledgeUnknownAuthorHistoryEvents(pmRoot, {
         events: selector.events,
         all_actionable: selector.all_actionable,
+        dry_run: input.dryRun === true || input.dry_run === true,
+        plan_fingerprint: readRuntimeString(input, "planFingerprint") ??
+            readRuntimeString(input, "plan_fingerprint"),
+        coordinate_limit: typeof input.limit === "number"
+            ? input.limit
+            : typeof input.limit === "string"
+                ? Number(input.limit)
+                : undefined,
         attributed_author: readRuntimeString(input, "attributedAuthor") ??
             readRuntimeString(input, "attributed_author") ??
-            "",
-        reviewer: readRuntimeString(input, "reviewer") ?? "",
-        reason: readRuntimeString(input, "reason") ?? "",
+            undefined,
+        reviewer: readRuntimeString(input, "reviewer"),
+        reason: readRuntimeString(input, "reason"),
     });
 }
 /**
@@ -266,23 +380,21 @@ export function acknowledgeUnknownAuthorHistoryEventsFromTransport(pmRoot, input
  * rewriting their original streams.
  */
 export async function acknowledgeUnknownAuthorHistoryEvents(pmRoot, options) {
-    const reviewer = options.reviewer.trim();
-    const attributedAuthor = options.attributed_author.trim();
-    const reason = options.reason.trim();
-    const explicitEvents = options.events ?? [];
-    const selectorCount = Number(options.all_actionable === true) + Number(explicitEvents.length > 0);
-    if (selectorCount === 0) {
-        refuseAuthorAcknowledgmentArgument("Specify exactly one selector: events or all_actionable.", { code: "history_author_acknowledge_selector_required" });
+    const reviewer = options.reviewer?.trim() ?? "";
+    const attributedAuthor = options.attributed_author?.trim() ?? "";
+    const reason = options.reason?.trim() ?? "";
+    const resolved = await resolveUnknownAuthorAcknowledgmentPlan(pmRoot, options, options.coordinate_limit ?? 50);
+    if (options.dry_run === true) {
+        return {
+            dry_run: true,
+            mutated: false,
+            acknowledged: 0,
+            outcome: "preview",
+            exit_code: EXIT_CODE.SUCCESS,
+            plan: resolved.plan,
+        };
     }
-    if (selectorCount > 1) {
-        refuseAuthorAcknowledgmentArgument("Author acknowledgment accepts either explicit events or all_actionable, not both.", { code: "history_author_acknowledge_selector_conflict" });
-    }
-    const selectedEvents = options.all_actionable === true
-        ? (await scanHistoryAuthorAttribution(pmRoot, 0, true))
-            .actionable_events
-        : explicitEvents;
     const requiredValuesMissing = [
-        selectedEvents.length > 0,
         reviewer.length > 0,
         reviewer.toLowerCase() !== "unknown",
         attributedAuthor.length > 0,
@@ -292,34 +404,35 @@ export async function acknowledgeUnknownAuthorHistoryEvents(pmRoot, options) {
     if (requiredValuesMissing) {
         refuseAuthorAcknowledgmentArgument("Author acknowledgment requires events, reviewer, attributed_author, and reason.", { code: "history_author_acknowledge_required_values_missing" });
     }
-    const uniqueEvents = [
-        ...new Map(selectedEvents.map((event) => [
-            `${event.item_id}:${event.line}`,
-            { item_id: event.item_id, line: event.line },
-        ])).values(),
-    ].sort((left, right) => left.item_id.localeCompare(right.item_id) || left.line - right.line);
-    for (const event of uniqueEvents) {
-        const invalidCoordinate = [
-            event.item_id === WORKSPACE_HISTORY_ID ||
-                /^[a-z0-9][a-z0-9-]*$/i.test(event.item_id),
-            Number.isSafeInteger(event.line),
-            event.line >= 1,
-        ].includes(false);
-        if (invalidCoordinate) {
-            refuseAuthorAcknowledgmentArgument(`Unknown-author acknowledgment target ${event.item_id}:${event.line} is not readable.`, { code: "history_author_acknowledge_target_unreadable" });
-        }
-        let parsed;
-        try {
-            const raw = await fs.readFile(path.join(pmRoot, "history", `${event.item_id}.jsonl`), "utf8");
-            const line = raw.split(/\r?\n/)[event.line - 1];
-            parsed = JSON.parse(line ?? "");
-        }
-        catch {
-            refuseAuthorAcknowledgmentArgument(`Unknown-author acknowledgment target ${event.item_id}:${event.line} is not readable.`, { code: "history_author_acknowledge_target_unreadable" });
-        }
-        if (classifyHistoryAuthorEvent(parsed) !== "actionable_unknown") {
-            refuseAuthorAcknowledgmentArgument(`Author acknowledgment target ${event.item_id}:${event.line} is not an actionable unknown-author event.`, { code: "history_author_acknowledge_target_not_actionable" });
-        }
+    if (!options.plan_fingerprint?.trim()) {
+        refuseAuthorAcknowledgmentArgument("Author acknowledgment apply requires plan_fingerprint from a fresh dry-run preview.", {
+            code: "history_author_acknowledge_plan_fingerprint_required",
+            recovery: {
+                suggested_retry: "Rerun history-author-acknowledge with --dry-run, then pass --plan-fingerprint <value>.",
+            },
+        });
+    }
+    if (options.plan_fingerprint.trim() !== resolved.plan.plan_fingerprint) {
+        throw new PmCliError("Author acknowledgment selection changed after preview; no history was mutated.", EXIT_CODE.CONFLICT, {
+            code: "history_author_acknowledge_plan_conflict",
+            recovery: {
+                suggested_retry: "Rerun history-author-acknowledge with --dry-run and apply the fresh plan_fingerprint.",
+            },
+        });
+    }
+    const eventsToAcknowledge = resolved.completeCoordinates
+        .filter(({ disposition }) => resolved.plan.selection.kind === "events" ||
+        disposition === "actionable")
+        .map(({ item_id, line }) => ({ item_id, line }));
+    if (eventsToAcknowledge.length === 0) {
+        return {
+            dry_run: false,
+            mutated: false,
+            acknowledged: 0,
+            outcome: "no_effect",
+            exit_code: EXIT_CODE.NO_EFFECT,
+            plan: resolved.plan,
+        };
     }
     const settings = await readSettings(pmRoot);
     const appended = await appendWorkspaceAuditEvent({
@@ -328,7 +441,7 @@ export async function acknowledgeUnknownAuthorHistoryEvents(pmRoot, options) {
         author: reviewer,
         context: {
             author_acknowledgment: {
-                events: uniqueEvents,
+                events: eventsToAcknowledge,
                 attributed_author: attributedAuthor,
             },
         },
@@ -336,10 +449,21 @@ export async function acknowledgeUnknownAuthorHistoryEvents(pmRoot, options) {
         lockTtlSeconds: settings.locks.ttl_seconds,
         lockWaitMs: settings.locks.wait_ms,
     });
+    const effectResult = resolved.plan.actionable_count > 0 &&
+        resolved.plan.already_acknowledged_count > 0
+        ? {
+            outcome: "partial_effect",
+            exit_code: EXIT_CODE.PARTIAL_EFFECT,
+        }
+        : { outcome: "effect", exit_code: EXIT_CODE.SUCCESS };
     return {
-        acknowledged: uniqueEvents.length,
+        dry_run: false,
+        mutated: true,
+        acknowledged: eventsToAcknowledge.length,
+        ...effectResult,
+        plan: resolved.plan,
         history_path: appended.historyPath,
     };
 }
 //# sourceMappingURL=author-attribution.js.map
-//# debugId=4fd16197-979e-5269-bed7-f2fb0e2038c2
+//# debugId=b389e521-f689-5895-a5f4-08c3866b3ea3

package/dist/sdk/cli-contracts/flag-contracts.js

@@ -7,7 +7,7 @@
  * flag surface stays single-sourced across the CLI, SDK, and MCP boundaries.
  */
 
-!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]="512c41c1-624f-517c-abc3-4448b49cd9e6")}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]="c82d9b50-274f-585d-be0e-9a0c5067b9e9")}catch(e){}}();
 import { normalizeUniqueStringList } from "./string-lists.js";
 import { RESERVED_EXTENSION_HOST_FLAGS } from "../../core/extensions/reserved-host-flags.js";
 function normalizeFlagAliasKey(flag) {
@@ -351,6 +351,9 @@ export const HISTORY_REPAIR_FLAG_CONTRACTS = [
 export const HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS = [
     { flag: "--event", repeatable: true },
     { flag: "--all-actionable" },
+    { flag: "--dry-run" },
+    { flag: "--plan-fingerprint" },
+    { flag: "--limit", value_type: "number" },
     { flag: "--attributed-author", aliases: ["--attributed_author"] },
     { flag: "--reviewer" },
     { flag: "--reason" },
@@ -1818,4 +1821,4 @@ export function toCompletionFlagString(flagContracts, includeGlobal = true) {
     return normalizeUniqueStringList(all).join(" ");
 }
 //# sourceMappingURL=flag-contracts.js.map
-//# debugId=512c41c1-624f-517c-abc3-4448b49cd9e6
+//# debugId=c82d9b50-274f-585d-be0e-9a0c5067b9e9

package/dist/sdk/cli-contracts/tool-parameter-tables.js

@@ -4,7 +4,7 @@
  * Defines SDK command-contract metadata for Tool Parameter Tables.
  */
 
-!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]="ddb90f7e-f3ca-56d8-be75-13e238da306c")}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]="cb6f6915-307c-58e7-a892-3dff4c7ae399")}catch(e){}}();
 import { PLAN_HARNESS_VALUES, PLAN_MODE_VALUES, PLAN_STEP_LINK_KIND_VALUES, PLAN_STEP_STATUS_VALUES, } from "../../types/index.js";
 import { PM_READ_OUTPUT_SESSION_MAX_SEEN_ITEM_IDS } from "../read-output-session.js";
 import { ASSURANCE_DEFINITION_SCHEMA } from "./schemas/assurance-definition.js";
@@ -229,6 +229,7 @@ export const PM_TOOL_PARAMETER_PROPERTIES = {
     parent: { type: "string" },
     reviewer: { type: "string" },
     attributedAuthor: { type: "string" },
+    planFingerprint: { type: "string", pattern: "^[a-f0-9]{64}$" },
     historyEvent: { type: "array", items: { type: "string" } },
     risk: { type: "string" },
     confidence: { anyOf: [{ type: "string" }, { type: "number" }] },
@@ -1197,6 +1198,12 @@ export const PM_TOOL_PARAMETER_METADATA = {
         description: "Unknown-author history target in <item-id>:<one-based-line> form.",
         examples: [["pm-example:4", "pm-example:5"]],
     },
+    planFingerprint: {
+        description: "Exact SHA-256 returned by a history-author-acknowledge dry-run preview; apply refuses stale or changed source coordinates.",
+        examples: [
+            "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+        ],
+    },
     estimate: {
         description: "Estimated effort in minutes.",
         examples: [60, "120"],
@@ -2059,4 +2066,4 @@ export const PM_TOOL_ACTION_SCOPED_PARAMETER_METADATA = {
     },
 };
 //# sourceMappingURL=tool-parameter-tables.js.map
-//# debugId=ddb90f7e-f3ca-56d8-be75-13e238da306c
+//# debugId=cb6f6915-307c-58e7-a892-3dff4c7ae399

package/dist/sdk/cli-contracts/tool-schema.js

@@ -7,7 +7,7 @@
  * consumers from a single source of truth.
  */
 
-!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]="aa58e280-0a39-5285-a451-811e60481661")}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]="1d6089b2-ab59-59ad-a475-9a6ef1356b40")}catch(e){}}();
 import { normalizeUniqueStringList } from "./string-lists.js";
 import { PM_TOOL_ACTIONS } from "./enum-contracts.js";
 import { TOOL_CREATE_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, } from "./tool-option-contracts.js";
@@ -632,8 +632,16 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
         oneOfRequired: [["id"], ["all"]],
     },
     "history-author-acknowledge": {
-        required: ["attributedAuthor", "reviewer", "reason"],
-        optional: ["historyEvent", "allActionable"],
+        optional: [
+            "historyEvent",
+            "allActionable",
+            "dryRun",
+            "planFingerprint",
+            "limit",
+            "attributedAuthor",
+            "reviewer",
+            "reason",
+        ],
         oneOfRequired: [["historyEvent"], ["allActionable"]],
     },
     "history-compact": {
@@ -1580,4 +1588,4 @@ export const _testOnlyCliContracts = {
     withFlagAliasMetadata,
 };
 //# sourceMappingURL=tool-schema.js.map
-//# debugId=aa58e280-0a39-5285-a451-811e60481661
+//# debugId=1d6089b2-ab59-59ad-a475-9a6ef1356b40

package/dist/sdk/completion.js

@@ -4,11 +4,11 @@
  * Implements the pm completion command surface and its agent-facing runtime behavior.
  */
 
-!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]="fca471b1-155a-5fc4-9aa9-d45e5f1315dd")}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]="c337a436-ac3e-5447-9c76-de9aeebb2a1c")}catch(e){}}();
 import { EXIT_CODE, PmCliError } from "./runtime-primitives.js";
 import { listPmCommandsForTier } from "./agent-capability-contracts.js";
 import { SCAFFOLD_CAPABILITIES } from "./extension/scaffold.js";
-import { AGGREGATE_FLAG_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, CONTEXT_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, CREATE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, NEXT_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PLAN_FLAG_CONTRACTS, SEARCH_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, toCompletionFlagString, } from "./cli-contracts.js";
+import { AGGREGATE_FLAG_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, CONTEXT_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, CREATE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, NEXT_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PLAN_FLAG_CONTRACTS, SEARCH_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, toCompletionFlagString, } from "./cli-contracts.js";
 import { BUILTIN_ITEM_TYPE_VALUES, STATUS_VALUES } from "../types/index.js";
 import { listGuideTopicIds } from "./guide-topics.js";
 const VALID_SHELLS = ["bash", "zsh", "fish"];
@@ -29,6 +29,7 @@ const UPDATE_MANY_FLAGS = toCompletionFlagString(UPDATE_MANY_FLAG_CONTRACTS);
 const CLOSE_MANY_FLAGS = toCompletionFlagString(CLOSE_MANY_FLAG_CONTRACTS);
 const ACTIVITY_FLAGS = toCompletionFlagString(ACTIVITY_FLAG_CONTRACTS);
 const HISTORY_FLAGS = toCompletionFlagString(HISTORY_FLAG_CONTRACTS);
+const HISTORY_AUTHOR_ACKNOWLEDGE_FLAGS = toCompletionFlagString(HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, false);
 const EVENTS_FLAGS = toCompletionFlagString(EVENTS_FLAG_CONTRACTS);
 const CALENDAR_FLAGS = toCompletionFlagString(CALENDAR_FLAG_CONTRACTS);
 const CONTEXT_FLAGS = toCompletionFlagString(CONTEXT_FLAG_CONTRACTS);
@@ -648,7 +649,7 @@ export function generateBashScript(itemTypes = [], tags = [], eagerTagExpansion
         `      COMPREPLY=(${compgen("--before --ids --all-over --closed --all-streams --min-entries --dry-run --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
         "      ;;",
         "    history-author-acknowledge)",
-        `      COMPREPLY=(${compgen("--event --all-actionable --attributed-author --reviewer --reason --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
+        `      COMPREPLY=(${compgen(`${HISTORY_AUTHOR_ACKNOWLEDGE_FLAGS} --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help`)})`,
         "      ;;",
         "    get)",
         `      COMPREPLY=(${compgen(GET_FLAGS)})`,
@@ -1199,6 +1200,9 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
           _arguments \\
             '*--event[Actionable unknown-author event]:item_and_line' \\
             '--all-actionable[Select every currently actionable event]' \\
+            '--dry-run[Preview a deterministic source-bound plan]' \\
+            '--plan-fingerprint[Apply the exact dry-run plan]:sha256' \\
+            '--limit[Maximum coordinate rows returned in the plan]:number' \\
             '--attributed-author[Principal attributed by maintainer review]:author' \\
             '--reviewer[Reviewer recording the disposition]:reviewer' \\
             '--reason[Evidence-backed review rationale]:reason' \\
@@ -2308,6 +2312,9 @@ complete -c pm -n '__fish_seen_subcommand_from history-compact' -l message -d 'A
 complete -c pm -n '__fish_seen_subcommand_from history-compact' -l force -d 'Force ownership/lock override'
 complete -c pm -n '__fish_seen_subcommand_from history-author-acknowledge' -l event -d 'Actionable unknown-author event' -r
 complete -c pm -n '__fish_seen_subcommand_from history-author-acknowledge' -l all-actionable -d 'Select every currently actionable event'
+complete -c pm -n '__fish_seen_subcommand_from history-author-acknowledge' -l dry-run -d 'Preview a deterministic source-bound plan'
+complete -c pm -n '__fish_seen_subcommand_from history-author-acknowledge' -l plan-fingerprint -d 'Apply the exact dry-run plan' -r
+complete -c pm -n '__fish_seen_subcommand_from history-author-acknowledge' -l limit -d 'Maximum coordinate rows returned in the plan' -r
 complete -c pm -n '__fish_seen_subcommand_from history-author-acknowledge' -l attributed-author -d 'Principal attributed by maintainer review' -r
 complete -c pm -n '__fish_seen_subcommand_from history-author-acknowledge' -l reviewer -d 'Reviewer recording the disposition' -r
 complete -c pm -n '__fish_seen_subcommand_from history-author-acknowledge' -l reason -d 'Evidence-backed review rationale' -r
@@ -2762,4 +2769,4 @@ export function runCompletion(shell, itemTypes = [], tags = [], eagerTagExpansio
     };
 }
 //# sourceMappingURL=completion.js.map
-//# debugId=fca471b1-155a-5fc4-9aa9-d45e5f1315dd
+//# debugId=c337a436-ac3e-5447-9c76-de9aeebb2a1c

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]="3891c17c-c79d-54d4-8b62-da8fe9c1eaf4")}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]="515e0f67-1d1d-5ee7-9000-bbe9aa201507")}catch(e){}}();
 export const PM_ERROR_CODE_CATALOG_PART_1 = [
     {
         code: "acceptance_criteria_mutation_conflict",
@@ -806,6 +806,42 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "github_source_entry_unbuilt",
         aliases: [],
     },
+    {
+        code: "history_author_acknowledge_plan_conflict",
+        meaning: "History author acknowledge plan conflict condition.",
+        stability: "provisional",
+        exit_code: 4,
+        class: "conflict",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/author-attribution.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "history_author_acknowledge_plan_conflict",
+        aliases: [],
+    },
+    {
+        code: "history_author_acknowledge_plan_fingerprint_required",
+        meaning: "History author acknowledge plan fingerprint required condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/author-attribution.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "history_author_acknowledge_plan_fingerprint_required",
+        aliases: [],
+    },
+    {
+        code: "history_author_acknowledge_preview_limit_invalid",
+        meaning: "History author acknowledge preview limit invalid condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/author-attribution.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "history_author_acknowledge_preview_limit_invalid",
+        aliases: [],
+    },
     {
         code: "history_author_acknowledge_required_values_missing",
         meaning: "History author acknowledge required values missing condition.",
@@ -1604,18 +1640,6 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "merge_conflict_markers_detected",
         aliases: ["history_merge_conflict_markers_detected"],
     },
-    {
-        code: "merge_decisions_unreviewed",
-        meaning: "Merge decisions unreviewed condition.",
-        stability: "provisional",
-        exit_code: 1,
-        class: "generic_failure",
-        recovery: "Inspect the structured error guidance and retry the suggested command.",
-        sources: ["core/diagnostics/remediation.ts"],
-        emitting_commands: ["*"],
-        canonical_code: "merge_decisions_unreviewed",
-        aliases: [],
-    },
 ];
 //# sourceMappingURL=generated-error-code-catalog-part-1.js.map
-//# debugId=3891c17c-c79d-54d4-8b62-da8fe9c1eaf4
+//# debugId=515e0f67-1d1d-5ee7-9000-bbe9aa201507

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

@@ -1,7 +1,19 @@
 /** 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]="5d64a86d-6ba6-5bbe-a83a-9703690a851e")}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]="e17917c7-8433-5de1-a895-ca5a03ce03da")}catch(e){}}();
 export const PM_ERROR_CODE_CATALOG_PART_2 = [
+    {
+        code: "merge_decisions_unreviewed",
+        meaning: "Merge decisions unreviewed condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["core/diagnostics/remediation.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "merge_decisions_unreviewed",
+        aliases: [],
+    },
     {
         code: "merge_git_config_unwritable",
         meaning: "Merge git config unwritable condition.",
@@ -774,6 +786,18 @@ export const PM_ERROR_CODE_CATALOG_PART_2 = [
         canonical_code: "tracker_root_not_directory",
         aliases: [],
     },
+    {
+        code: "tracker_root_unreadable",
+        meaning: "Tracker root unreadable condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["core/store/item-store.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "tracker_root_unreadable",
+        aliases: [],
+    },
     {
         code: "type_duplicate",
         meaning: "Type duplicate condition.",
@@ -1507,6 +1531,18 @@ export const PM_ERROR_CODE_CATALOG_PART_2 = [
         canonical_code: "workflow_type_unknown",
         aliases: [],
     },
+    {
+        code: "workspace_history_chain_invalid",
+        meaning: "Workspace history chain invalid condition.",
+        stability: "provisional",
+        exit_code: 4,
+        class: "conflict",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["core/history/workspace-history.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "workspace_history_chain_invalid",
+        aliases: [],
+    },
     {
         code: "workspace_history_state_conflict",
         meaning: "Workspace history state conflict condition.",
@@ -1629,4 +1665,4 @@ export const PM_ERROR_CODE_CATALOG_PART_2 = [
     },
 ];
 //# sourceMappingURL=generated-error-code-catalog-part-2.js.map
-//# debugId=5d64a86d-6ba6-5bbe-a83a-9703690a851e
+//# debugId=e17917c7-8433-5de1-a895-ca5a03ce03da

package/dist/sdk/governance/coverage-assurance.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @module sdk/governance/coverage-assurance
+ *
+ * Provides exact integer coverage assurance for repository and package gates.
+ */
+/** Coverage metrics required by the exact repository quality contract. */
+export declare const PM_EXACT_COVERAGE_METRICS: readonly ["lines", "branches", "functions", "statements"];
+/** Required exact coverage metric. */
+export type PmExactCoverageMetric = (typeof PM_EXACT_COVERAGE_METRICS)[number];
+/** One exact uncovered-count finding. */
+export interface PmCoverageDeficit {
+    /** Coverage summary entry or source filename. */
+    file: string;
+    /** Deficient required metric. */
+    metric: PmExactCoverageMetric;
+    /** Integer statements or paths not covered. */
+    uncovered: number;
+    /** Exact covered count. */
+    covered: number;
+    /** Exact total count. */
+    total: number;
+}
+/** Return exact uncovered counts for every summary entry and required metric. */
+export declare function findCoverageDeficits(summary: unknown): PmCoverageDeficit[];