@unbrained/pm-cli 2026.8.10 → 2026.8.12

package/dist/cli/register-annotations.js

@@ -1,10 +1,52 @@
 
-!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]="0977d72e-6e4d-5ece-bfaf-eb24a4e9982c")}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]="616fff4b-f86e-54e5-b569-0b9894da5221")}catch(e){}}();
 import { EXIT_CODE, PmCliError, } from "../sdk/runtime-primitives.js";
+import { renderPmCommand } from "../sdk/command-line.js";
 import { runComments } from "./commands/comments.js";
 import { runLearnings } from "./commands/learnings.js";
 import { runNotes } from "./commands/notes.js";
 import { addHiddenOption, getGlobalOptions, invalidateSearchCachesForMutation, printError, printResult, readOptionString, } from "./registration-helpers.js";
+function assertNoTransposedAnnotationAction(collection, id, text, options) {
+    if (id.trim().toLowerCase() !== "add" || !text?.trim()) {
+        return;
+    }
+    const suppliedText = readOptionString(options, "add") ??
+        readOptionString(options, "note") ??
+        readOptionString(options, "body") ??
+        readOptionString(options, "comment");
+    const file = readOptionString(options, "file");
+    const retryArgs = [collection, text.trim()];
+    if (suppliedText !== undefined)
+        retryArgs.push("--add", suppliedText);
+    else if (options.stdin === true)
+        retryArgs.push("--stdin");
+    else if (file !== undefined)
+        retryArgs.push("--file", file);
+    else
+        retryArgs.push("--add", "-");
+    const suggestedRetry = renderPmCommand(retryArgs);
+    const stdinRetry = renderPmCommand([
+        collection,
+        text.trim(),
+        "--add",
+        "-",
+    ]);
+    throw new PmCliError(`The positional token "add" was parsed as the item id, while "${text.trim()}" was parsed as annotation text. ${collection} does not use an add subcommand.`, EXIT_CODE.USAGE, {
+        code: "annotation_transposed_subcommand",
+        reason: "noun_verb_object_transposition",
+        required: `Place the item id immediately after ${collection}, then use --add for annotation text.`,
+        examples: [...new Set([suggestedRetry, stdinRetry])],
+        recovery: {
+            attempted_command: `pm ${collection} add ${text.trim()}`,
+            normalized_args: [collection, "add", text.trim()],
+            parsed_positionals: [
+                { role: "transposed_subcommand", value: "add" },
+                { role: "item_id", value: text.trim() },
+            ],
+            suggested_retry: suggestedRetry,
+        },
+    });
+}
 function resolveCommentSources(text, options) {
     const editIndex = typeof options.edit === "number" ? options.edit : undefined;
     const deleteIndex = typeof options.delete === "number" ? options.delete : undefined;
@@ -42,7 +84,14 @@ function resolveCommentSources(text, options) {
     };
 }
 function resolveSingleTextSource(label, positional, options) {
-    const addFromOption = readOptionString(options, "add");
+    const canonicalAdd = readOptionString(options, "add");
+    const aliasAdd = label === "note" ? readOptionString(options, "note") : undefined;
+    if (canonicalAdd !== undefined &&
+        aliasAdd !== undefined &&
+        canonicalAdd !== aliasAdd) {
+        throw new PmCliError("Specify note text with either --add or --note, not conflicting values for both aliases", EXIT_CODE.USAGE, { code: "annotation_alias_conflict" });
+    }
+    const addFromOption = canonicalAdd ?? aliasAdd;
     const addFromPositional = typeof positional === "string" ? positional : undefined;
     if (addFromOption !== undefined && addFromPositional !== undefined) {
         throw new PmCliError(`Specify ${label} text either as positional [text] or with --add, not both`, EXIT_CODE.USAGE);
@@ -52,6 +101,7 @@ function resolveSingleTextSource(label, positional, options) {
 async function runCommentsAction(id, text, options, command) {
     const globalOptions = getGlobalOptions(command);
     const startedAt = Date.now();
+    assertNoTransposedAnnotationAction("comments", id, text, options);
     const sources = resolveCommentSources(text, options);
     const result = await runComments(id, {
         add: sources.add,
@@ -74,6 +124,7 @@ async function runCommentsAction(id, text, options, command) {
 async function runNotesAction(id, text, options, command) {
     const globalOptions = getGlobalOptions(command);
     const startedAt = Date.now();
+    assertNoTransposedAnnotationAction("notes", id, text, options);
     const add = resolveSingleTextSource("note", text, options);
     const result = await runNotes(id, {
         add,
@@ -105,6 +156,7 @@ async function runNotesAction(id, text, options, command) {
 async function runLearningsAction(id, text, options, command) {
     const globalOptions = getGlobalOptions(command);
     const startedAt = Date.now();
+    assertNoTransposedAnnotationAction("learnings", id, text, options);
     const add = resolveSingleTextSource("learning", text, options);
     const result = await runLearnings(id, {
         add,
@@ -159,6 +211,7 @@ export function registerAnnotationCommands(program, parsePositiveInteger) {
         .argument("<id>", "Item id")
         .argument("[text]", "Optional note text shorthand (equivalent to --add; use - for stdin)")
         .option("--add <text>", "Add a text note (- reads stdin)")
+        .option("--note <text>", "Alias for --add")
         .option("--add-json <json>", "Append a merge-safe JSON event")
         .option("--stdin", "Read note text from stdin")
         .option("--file <path>", "Read note text from a UTF-8 file")
@@ -192,4 +245,4 @@ export function registerAnnotationCommands(program, parsePositiveInteger) {
         .action(runLearningsAction);
 }
 //# sourceMappingURL=register-annotations.js.map
-//# debugId=0977d72e-6e4d-5ece-bfaf-eb24a4e9982c
+//# debugId=616fff4b-f86e-54e5-b569-0b9894da5221

package/dist/cli/register-assurance.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @module cli/register-assurance
+ *
+ * Thin Commander adapter over the transport-neutral public assurance action.
+ */
+import type { Command } from "commander";
+/** Register the declarative assurance command family. */
+export declare function registerAssuranceCommand(program: Command): void;

package/dist/cli/register-assurance.js

@@ -0,0 +1,52 @@
+
+!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]="1adbac08-0950-55be-82bf-cc4dc7b6ad18")}catch(e){}}();
+import { ASSURANCE_ACTIONS, ASSURANCE_DECLARATION_KINDS, runAssuranceAction, } from "../sdk/governance/assurance-action.js";
+import { printResult } from "../sdk/runtime-primitives.js";
+import { getGlobalOptions, readOptionString } from "./registration-helpers.js";
+async function runAssuranceCliAction(action, kindOrGate, id, options, command) {
+    const global = getGlobalOptions(command);
+    const isRun = action === "run";
+    const isVerdicts = action === "verdicts";
+    const result = await runAssuranceAction({
+        action,
+        ...(isRun || isVerdicts ? {} : { kind: kindOrGate }),
+        id: isRun || isVerdicts ? (id ?? kindOrGate) : id,
+        definition: readOptionString(options, "definition"),
+        trigger: readOptionString(options, "trigger"),
+        tree: readOptionString(options, "tree"),
+        gate: readOptionString(options, "gate"),
+        limit: readOptionString(options, "limit"),
+        dry_run: options.dryRun === true,
+        fullChangedFields: global.fullChangedFields,
+        idOnly: global.idOnly,
+        author: readOptionString(options, "author"),
+        message: readOptionString(options, "message"),
+    }, global);
+    printResult(result, global);
+    if (typeof result === "object" &&
+        result !== null &&
+        "exit_code" in result &&
+        result.exit_code === 1) {
+        process.exitCode = 1;
+    }
+}
+/** Register the declarative assurance command family. */
+export function registerAssuranceCommand(program) {
+    program
+        .command("assurance")
+        .argument("<action>", `Action: ${ASSURANCE_ACTIONS.join(", ")}`)
+        .argument("[kind]", `Declaration kind: ${ASSURANCE_DECLARATION_KINDS.join(", ")}; for run this may be the gate id`)
+        .argument("[id]", "Declaration or gate id")
+        .description("Declare and evaluate SDK-owned project assurance contracts.")
+        .option("--definition <json>", "JSON declaration for put")
+        .option("--trigger <value>", "Gate lifecycle trigger")
+        .option("--tree <value>", "Commit, tree, or snapshot identity being judged")
+        .option("--gate <id>", "Filter verdict history by gate id")
+        .option("--limit <number>", "Maximum newest verdicts returned")
+        .option("--dry-run", "Evaluate a gate without appending a verdict")
+        .option("--author <value>", "Mutation author override")
+        .option("--message <value>", "Audited mutation rationale")
+        .action(runAssuranceCliAction);
+}
+//# sourceMappingURL=register-assurance.js.map
+//# debugId=1adbac08-0950-55be-82bf-cc4dc7b6ad18

package/dist/cli/register-files-lookup.js

@@ -1,6 +1,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]="dabf24f7-406d-57e0-af3c-25391325a1b4")}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]="452f6689-f5bd-5398-915b-52ce7e2fd55e")}catch(e){}}();
 import { runFilesLookup } from "../sdk/files.js";
+import { parseSourceLineRange } from "../sdk/traceability/source-traceability.js";
 import { EXIT_CODE, PmCliError } from "../sdk/runtime-primitives.js";
 import { getGlobalOptions, printResult } from "./registration-helpers.js";
 function parseIntegerBound(flag, minimum) {
@@ -26,6 +27,13 @@ async function runFilesLookupAction(paths, options, command) {
         offset: typeof options.offset === "number" ? options.offset : undefined,
         noTruncate: options.noTruncate === true,
         strictRead: options.strictRead === true,
+        explain: options.explain === true,
+        lineRange: typeof options.lines === "string"
+            ? parseSourceLineRange(options.lines)
+            : undefined,
+        decisionDepth: typeof options.decisionDepth === "number"
+            ? options.decisionDepth
+            : undefined,
     }, globalOptions);
     printResult(result, globalOptions);
 }
@@ -39,8 +47,11 @@ export function registerFilesLookupCommand(filesCommand) {
         .option("--offset <n>", "Number of referencing items to skip", parseIntegerBound("--offset", 0))
         .option("--no-truncate", "Return every referencing item")
         .option("--strict-read", "Fail when any authoritative item cannot be read")
-        .description("Find pm items that link the requested source paths.")
+        .option("--explain", "Include ranked source-to-work rationale")
+        .option("--lines <start:end>", "Attribute an inclusive source line range")
+        .option("--decision-depth <n>", "Maximum governing-decision relationship depth", parseIntegerBound("--decision-depth", 1))
+        .description("Find and explain pm items that govern requested source paths.")
         .action(runFilesLookupAction);
 }
 //# sourceMappingURL=register-files-lookup.js.map
-//# debugId=dabf24f7-406d-57e0-af3c-25391325a1b4
+//# debugId=452f6689-f5bd-5398-915b-52ce7e2fd55e

package/dist/cli/register-list-query.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]="6a380419-3ed6-5e3d-a66f-40a6d5408b6b")}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]="0bcbdc33-3145-54cc-b4b6-10df50aef57a")}catch(e){}}();
 import { EXIT_CODE, PmCliError, renderRowsAsCsv, renderRowsAsTable, } from "../sdk/runtime-primitives.js";
 import { EVAL_QUERY_SET_SCHEMA_ID } from "../sdk/eval.js";
 import { applyContextIntentProjection } from "../sdk/context-intent-contracts.js";
@@ -372,7 +372,7 @@ async function runGetAction(id, options, command) {
 async function runHistoryAction(id, options, command) {
     const globalOptions = getGlobalOptions(command);
     const startedAt = Date.now();
-    if ([options.compact, options.full, options.provenance].filter((value) => value === true).length > 1) {
+    if ([options.compact, options.raw, options.full, options.provenance].filter((value) => value === true).length > 1) {
         throw new PmCliError("History projection options are mutually exclusive. Use --compact, --provenance, or --full.", EXIT_CODE.USAGE);
     }
     const field = typeof options.field === "string" ? options.field : undefined;
@@ -472,15 +472,17 @@ async function runEventsAction(options, command) {
 async function runActivityAction(options, command) {
     const globalOptions = getGlobalOptions(command);
     const startedAt = Date.now();
-    if ([options.compact, options.full, options.provenance].filter((value) => value === true).length > 1) {
-        throw new PmCliError("Activity projection options are mutually exclusive. Use --compact, --provenance, or --full.", EXIT_CODE.USAGE);
+    if ([options.raw, options.compact, options.full, options.provenance].filter((value) => value === true).length > 1) {
+        throw new PmCliError("Activity projection options are mutually exclusive. Use --raw, --compact, --provenance, or --full.", EXIT_CODE.USAGE);
     }
-    const normalized = normalizeActivityOptions(options);
-    const result = await runActivity(normalized, globalOptions);
     const streamMode = resolveActivityStreamMode(options.stream);
     if (streamMode && !globalOptions.json) {
         throw new PmCliError("--stream requires --json output mode.", EXIT_CODE.USAGE);
     }
+    const normalized = normalizeActivityOptions(options);
+    const result = await runActivity(streamMode && options.full !== true && options.provenance !== true
+        ? { ...normalized, raw: true, compact: true }
+        : normalized, globalOptions);
     if (streamMode) {
         printActivityJsonStream(result, normalized, globalOptions);
     }
@@ -795,6 +797,7 @@ export function registerListQueryCommands(program, options) {
             .option("--limit <n>", "Return only the latest n activity entries")
             .option("--unbounded", "Explicitly return every matching activity entry (disables the default bound)")
             .option("--compact", "Condensed output: show only id, op, ts, author, msg per entry")
+            .option("--raw", "Show the legacy compact per-event stream instead of the item digest")
             .option("--full", "Show full activity entries with JSON Patch payloads")
             .option("--provenance", "Show patch-free author, harness, instance, and extensible provenance")
             .option("--provenance-summary", "Include bounded provenance completeness counts")
@@ -835,4 +838,4 @@ export const _testOnlyRegisterListQuery = {
     parseListFormat,
 };
 //# sourceMappingURL=register-list-query.js.map
-//# debugId=6a380419-3ed6-5e3d-a66f-40a6d5408b6b
+//# debugId=0bcbdc33-3145-54cc-b4b6-10df50aef57a

package/dist/cli/register-mutation.js

@@ -1,6 +1,6 @@
 
-!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]="e5b9b4c9-c2eb-5282-99da-702a8887c4e4")}catch(e){}}();
-import { resolveBodyFileContent, EXIT_CODE, splitCommaList, PmCliError, } from "../sdk/runtime-primitives.js";
+!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]="6c7d647c-e489-51e3-b84b-5b62b4114033")}catch(e){}}();
+import { resolveBodyFileContent, EXIT_CODE, splitCommaList, PmCliError, createUnknownSubcommandError, } from "../sdk/runtime-primitives.js";
 import { CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, PLAN_CREATE_METADATA_PARAMETER_KEYS, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, } from "../sdk/cli-contracts.js";
 import { BUILTIN_ITEM_TYPE_VALUES } from "../types/index.js";
 import { MERGE_DRIVER_ARTIFACT_VALUES, runMergeDriver, runMergeInstall, runMergeReconcile, runMergeReceiptReport, } from "./commands/merge.js";
@@ -675,7 +675,7 @@ function normalizePlanAliases(options) {
     normalized.blockedBy = planOptions.blockedBy;
     return normalized;
 }
-function assertKnownPlanSubcommand(subcommand, normalized, allowed) {
+function assertKnownPlanSubcommand(normalized, allowed) {
     if (!normalized) {
         throw new PmCliError(`pm plan requires a subcommand. Allowed: ${allowed.join(", ")}`, EXIT_CODE.USAGE, {
             code: "missing_required_argument",
@@ -692,7 +692,15 @@ function assertKnownPlanSubcommand(subcommand, normalized, allowed) {
     const examples = normalized === "list" || normalized === "ls"
         ? ["pm list --type Plan", "pm list-all --type Plan"]
         : undefined;
-    throw new PmCliError(`Unknown pm plan subcommand "${subcommand}". Allowed: ${allowed.join(", ")}`, EXIT_CODE.USAGE, examples ? { code: "unknown_subcommand", examples } : undefined);
+    throw createUnknownSubcommandError({
+        command_path: "plan",
+        token: normalized,
+        allowed,
+        examples,
+        retry_command: normalized === "list" || normalized === "ls"
+            ? "pm list --type Plan"
+            : undefined,
+    });
 }
 function parsePlanReorderTo(normalizedSubcommand, reorderToken) {
     if (normalizedSubcommand !== "reorder-step" ||
@@ -709,7 +717,7 @@ async function runPlanAction(subcommand, id, stepRef, reorderToken, options, com
     const globalOptions = getGlobalOptions(command);
     const startedAt = Date.now();
     const normalizedSubcommand = (subcommand ?? "").trim().toLowerCase();
-    assertKnownPlanSubcommand(subcommand, normalizedSubcommand, PLAN_SUBCOMMANDS);
+    assertKnownPlanSubcommand(normalizedSubcommand, PLAN_SUBCOMMANDS);
     const planOptions = normalizePlanAliases(options);
     const reorderTo = parsePlanReorderTo(normalizedSubcommand, reorderToken);
     const planId = normalizedSubcommand === "create" &&
@@ -812,7 +820,12 @@ async function runMergeAction(subcommand, artifact, base, ours, theirs, options,
             await runMergeDriverSubcommand(artifact, base, ours, theirs, options, globalOptions);
             break;
         default:
-            throw new PmCliError(`Unknown merge subcommand "${subcommand}". Supported subcommands: install, reconcile, report, driver.`, EXIT_CODE.USAGE);
+            throw createUnknownSubcommandError({
+                command_path: "merge",
+                token: subcommand,
+                allowed: ["install", "reconcile", "report", "driver"],
+                display_name: "merge",
+            });
     }
     if (globalOptions.profile) {
         printError(`profile:command=merge took_ms=${Date.now() - startedAt}`);
@@ -890,7 +903,11 @@ async function runSchemaAction(subcommand, name, options, command) {
         normalizedSubcommand = "add-type";
     }
     if (!SCHEMA_SUBCOMMANDS.includes(normalizedSubcommand)) {
-        throw new PmCliError(`Unknown pm schema subcommand "${subcommand}". Allowed: ${SCHEMA_SUBCOMMANDS.join(", ")}`, EXIT_CODE.USAGE, { code: "unknown_subcommand" });
+        throw createUnknownSubcommandError({
+            command_path: "schema",
+            token: normalizedSubcommand,
+            allowed: SCHEMA_SUBCOMMANDS,
+        });
     }
     const result = await dispatchSchemaSubcommand(schemaModule, {
         normalizedSubcommand,
@@ -1070,7 +1087,11 @@ async function runProfileAction(subcommand, name, options, command) {
         });
     }
     if (!PROFILE_SUBCOMMANDS.includes(normalizedSubcommand)) {
-        throw new PmCliError(`Unknown pm profile subcommand "${subcommand}". Allowed: ${PROFILE_SUBCOMMANDS.join(", ")}`, EXIT_CODE.USAGE, { code: "unknown_subcommand" });
+        throw createUnknownSubcommandError({
+            command_path: "profile",
+            token: normalizedSubcommand,
+            allowed: PROFILE_SUBCOMMANDS,
+        });
     }
     const result = await dispatchProfileSubcommand(profileModule, normalizedSubcommand, name, options, globalOptions);
     // Profile inspection and schema staging do not mutate item content, so search caches stay valid (mirrors pm schema).
@@ -1817,4 +1838,4 @@ export function registerMutationCommands(program, registrationOptions = {}) {
         .action(runDepsAction);
 }
 //# sourceMappingURL=register-mutation.js.map
-//# debugId=e5b9b4c9-c2eb-5282-99da-702a8887c4e4
+//# debugId=6c7d647c-e489-51e3-b84b-5b62b4114033

package/dist/cli/register-operations.js

@@ -1,6 +1,6 @@
 
-!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]="4856ec1e-7841-5ad0-95e3-6e3057ed999c")}catch(e){}}();
-import { resolveRuntimeStatusRegistry, setActiveCommandResult, EXIT_CODE, PmCliError, resolveAuthor, resolvePmRoot, readSettings, } from "../sdk/runtime-primitives.js";
+!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]="7796ea07-0de7-5db8-a3b5-a8021ceebc69")}catch(e){}}();
+import { resolveRuntimeStatusRegistry, setActiveCommandResult, EXIT_CODE, PmCliError, createUnknownSubcommandError, resolveAuthor, resolvePmRoot, readSettings, } from "../sdk/runtime-primitives.js";
 import { resolveStartTaskInProgressStatus } from "../sdk/start-task-status.js";
 import { parseStatsAnalyticsJson } from "./stats-analytics-json.js";
 import { createWorkspaceSnapshot, deleteWorkspaceSnapshot, inspectWorkspaceSnapshot, listWorkspaceSnapshots, planWorkspaceSnapshotRestore, restoreWorkspaceSnapshotWithRecovery, } from "../sdk/workspace-snapshot.js";
@@ -19,6 +19,7 @@ import { runStartBackgroundRun, runTestRunsWorker, } from "./commands/test-runs.
 import { runUpdate } from "./commands/update.js";
 import { runValidate } from "./commands/validate.js";
 import { buildBackgroundTestAllCommandArgs, applyActiveCommandResultService, buildBackgroundTestCommandArgs, addHiddenOption, collect, getGlobalOptions, invalidateSearchCachesForMutation, printError, printResult, readOptionString, } from "./registration-helpers.js";
+import { registerAssuranceCommand } from "./register-assurance.js";
 function resolveTelemetrySubcommand(namespaceOrSubcommand, subcommand) {
     const normalizedNamespace = namespaceOrSubcommand?.trim().toLowerCase();
     const normalizedSubcommand = subcommand?.trim().toLowerCase();
@@ -31,13 +32,13 @@ function resolveTelemetrySubcommand(namespaceOrSubcommand, subcommand) {
             : "status";
     }
     if (normalizedSubcommand !== undefined && normalizedSubcommand.length > 0) {
-        throw new PmCliError(`Unknown pm telemetry path "${namespaceOrSubcommand} ${subcommand}". Use "pm telemetry ${namespaceOrSubcommand}" or legacy alias "pm telemetry local-analytics ${normalizedSubcommand}".`, EXIT_CODE.USAGE, {
-            code: "unknown_subcommand",
+        throw createUnknownSubcommandError({
+            command_path: "telemetry",
+            token: `${namespaceOrSubcommand} ${subcommand}`,
+            allowed: ["status", "flush", "stats", "clear", "local-analytics"],
+            token_kind: "path",
             examples: [
-                "pm telemetry status",
-                "pm telemetry flush",
                 "pm telemetry stats --limit 10",
-                "pm telemetry clear",
                 "pm telemetry local-analytics status --json",
             ],
         });
@@ -53,6 +54,9 @@ function collectTestMutationValues(options) {
         removeValues: Array.isArray(options.remove)
             ? options.remove
             : [],
+        removeIndexValues: Array.isArray(options.removeIndex)
+            ? options.removeIndex
+            : [],
     };
 }
 function validateBackgroundTestOptions(options, values) {
@@ -64,8 +68,9 @@ function validateBackgroundTestOptions(options, values) {
     }
     if (values.addValues.length > 0 ||
         values.addJsonValues.length > 0 ||
-        values.removeValues.length > 0) {
-        throw new PmCliError("--background does not support --add/--add-json/--remove; update linked tests first, then run in background", EXIT_CODE.USAGE);
+        values.removeValues.length > 0 ||
+        values.removeIndexValues.length > 0) {
+        throw new PmCliError("--background does not support --add/--add-json/--remove/--remove-index; update linked tests first, then run in background", EXIT_CODE.USAGE);
     }
 }
 async function runBackgroundLinkedTests(id, options, globalOptions, values) {
@@ -76,6 +81,7 @@ async function runBackgroundLinkedTests(id, options, globalOptions, values) {
             add: values.addValues,
             addJson: values.addJsonValues,
             remove: values.removeValues,
+            removeIndex: values.removeIndexValues,
         }),
         targetId: id,
         author: typeof options.author === "string" ? options.author : undefined,
@@ -88,6 +94,7 @@ function buildRunTestOptions(options, values) {
         add: values.addValues,
         addJson: values.addJsonValues,
         remove: values.removeValues,
+        removeIndex: values.removeIndexValues,
         list: Boolean(options.list),
         run: Boolean(options.run),
         match: typeof options.match === "string" ? options.match : undefined,
@@ -126,7 +133,8 @@ async function runForegroundLinkedTests(id, options, globalOptions, values) {
     if (values.addValues.length > 0 ||
         values.addJsonValues.length > 0 ||
         values.removeValues.length > 0 ||
-        options.run === true) {
+        options.run === true ||
+        values.removeIndexValues.length > 0) {
         await invalidateSearchCachesForMutation(globalOptions, result);
     }
     printResult(result, globalOptions);
@@ -235,6 +243,7 @@ async function runStatsAction(options, command) {
     const startedAt = Date.now();
     const analytics = parseStatsAnalyticsJson(readOptionString(options, "analytics"));
     const result = await runStats(globalOptions, {
+        includeEmpty: options.includeEmpty === true,
         storage: options.storage === true,
         metadataCoverage: options.metadataCoverage === true,
         byAssignee: options.byAssignee === true,
@@ -372,11 +381,14 @@ async function runWorkspaceSnapshotAction(action, target, options, command) {
     const pmRoot = resolvePmRoot(process.cwd(), globalOptions.path);
     const normalizedAction = action.trim().toLowerCase();
     if (!["create", "list", "inspect", "restore", "delete"].includes(normalizedAction)) {
-        throw new PmCliError(`Unknown workspace snapshot action "${action}". Use create, list, inspect, restore, or delete.`, EXIT_CODE.USAGE, {
-            code: "unknown_subcommand",
+        throw createUnknownSubcommandError({
+            command_path: "workspace snapshot",
+            token: action,
+            allowed: ["create", "list", "inspect", "restore", "delete"],
+            display_name: "workspace snapshot",
+            token_kind: "action",
             examples: [
                 "pm workspace snapshot create before-migration",
-                "pm workspace snapshot list",
                 "pm workspace snapshot restore before-migration",
             ],
         });
@@ -555,12 +567,14 @@ function addLinkedTestExecutionOptions(command) {
 }
 /** Implements register operation commands for the public runtime surface of this module. */
 export function registerOperationCommands(program) {
+    registerAssuranceCommand(program);
     const testCommand = program
         .command("test")
         .argument("<id>", "Item id")
         .option("--add <value>", "Add linked test entry (CSV/markdown pairs or - for stdin)", collect)
         .option("--add-json <value>", "Add linked test entry from JSON object/array (or - for stdin)", collect)
-        .option("--remove <value>", "Remove linked test entry by command/path (command=<value>, path=<value>, markdown pairs, plain value, or - for stdin)", collect)
+        .option("--remove <value>", "Remove linked test entry by exact command/path (command=<value> and path=<value> preserve commas and equals signs; or - for stdin)", collect)
+        .option("--remove-index <n>", "Remove the 1-based linked-test index from --list order (repeatable)", collect)
         .option("--list", "List linked tests without mutating")
         .option("--run", "Run linked test commands")
         .option("--match <value>", "Run only linked tests whose command/path contains this substring")
@@ -608,6 +622,7 @@ export function registerOperationCommands(program) {
     program
         .command("stats")
         .description("Show project tracker statistics.")
+        .option("--include-empty", "Restore zero-count registered item-type and lifecycle-status buckets")
         .option("--storage", "Include aggregate history-stream storage metrics (total streams/lines/bytes, largest + deepest streams, oldest/newest entries)")
         .option("--metadata-coverage", "Include metadata coverage % (acceptance_criteria, estimated_minutes, resolution, tags, parent) overall and by type")
         .option("--by-assignee", "Include a lifecycle-bucketed item breakdown grouped by assignee")
@@ -858,4 +873,4 @@ function registerSchedulingShortcutCommands(program) {
     });
 }
 //# sourceMappingURL=register-operations.js.map
-//# debugId=4856ec1e-7841-5ad0-95e3-6e3057ed999c
+//# debugId=7796ea07-0de7-5db8-a3b5-a8021ceebc69