@unbrained/pm-cli 2026.8.11 → 2026.8.13

package/dist/cli/error-guidance.js

@@ -1,5 +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]="4d6caae5-76d6-5563-acb9-b435f8cdfe9c")}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]="9ec35c35-f2dc-5f86-a166-cf0c80eab1bd")}catch(e){}}();
+import { resolveRecoveryCommandName } from "../sdk/agent/command-recovery.js";
 import { renderPmCommand } from "./argv-utils.js";
 import { discoverNearbyPmRoot } from "../sdk/tracker-root-discovery.js";
 /** Compact an error envelope to fields that change the caller's next action. */
@@ -125,7 +126,21 @@ function assignRecoveryString(normalized, key, value) {
         normalized[key] = value.trim();
     }
 }
-function assignRecoveryStringArray(normalized, key, value) {
+function assignRecoveryCollection(normalized, key, value) {
+    if (key === "parsed_positionals") {
+        if (!Array.isArray(value))
+            return;
+        const parsedPositionals = value
+            .map((entry) => ({
+            role: typeof entry?.role === "string" ? entry.role.trim() : "",
+            value: typeof entry?.value === "string" ? entry.value.trim() : "",
+        }))
+            .filter((entry) => entry.role.length > 0 && entry.value.length > 0);
+        if (parsedPositionals.length > 0) {
+            normalized.parsed_positionals = parsedPositionals;
+        }
+        return;
+    }
     const values = normalizeStringArray(value);
     if (values) {
         normalized[key] = values;
@@ -140,13 +155,14 @@ function normalizeRecoveryPayload(payload) {
         normalized.recovery_mode = "compact";
     }
     assignRecoveryString(normalized, "attempted_command", payload.attempted_command);
-    assignRecoveryStringArray(normalized, "normalized_args", payload.normalized_args);
-    assignRecoveryStringArray(normalized, "provided_fields", payload.provided_fields);
-    assignRecoveryStringArray(normalized, "missing", payload.missing);
-    assignRecoveryStringArray(normalized, "missing_required_fields", payload.missing_required_fields);
-    assignRecoveryStringArray(normalized, "suggested_flags", payload.suggested_flags);
-    assignRecoveryStringArray(normalized, "allowed_values", payload.allowed_values);
-    assignRecoveryStringArray(normalized, "candidate_commands", payload.candidate_commands);
+    assignRecoveryCollection(normalized, "normalized_args", payload.normalized_args);
+    assignRecoveryCollection(normalized, "parsed_positionals", payload.parsed_positionals);
+    assignRecoveryCollection(normalized, "provided_fields", payload.provided_fields);
+    assignRecoveryCollection(normalized, "missing", payload.missing);
+    assignRecoveryCollection(normalized, "missing_required_fields", payload.missing_required_fields);
+    assignRecoveryCollection(normalized, "suggested_flags", payload.suggested_flags);
+    assignRecoveryCollection(normalized, "allowed_values", payload.allowed_values);
+    assignRecoveryCollection(normalized, "candidate_commands", payload.candidate_commands);
     if (typeof payload.candidate_commands_total === "number" &&
         Number.isSafeInteger(payload.candidate_commands_total) &&
         payload.candidate_commands_total >= 0) {
@@ -186,6 +202,13 @@ function renderRecoveryBundle(recovery) {
     const lines = ["Recovery bundle:"];
     appendRecoveryTextLine(lines, "attempted_command", normalized.attempted_command);
     appendRecoveryListLine(lines, "normalized_args", normalized.normalized_args, " ");
+    if (normalized.parsed_positionals &&
+        normalized.parsed_positionals.length > 0) {
+        lines.push("  parsed_positionals:");
+        for (const positional of normalized.parsed_positionals) {
+            lines.push(`    - ${positional.role}: ${positional.value}`);
+        }
+    }
     appendRecoveryListLine(lines, "provided_fields", normalized.provided_fields, ", ");
     appendRecoveryListLine(lines, "missing", normalized.missing, ", ");
     appendRecoveryListLine(lines, "missing_required_fields", normalized.missing_required_fields, ", ");
@@ -319,12 +342,7 @@ function dedupeStrings(values) {
     return result;
 }
 function inferCommandNameFromRecovery(recovery) {
-    const args = recovery?.normalized_args;
-    if (!Array.isArray(args) || args.length === 0) {
-        return undefined;
-    }
-    const firstCommandArg = args.find((arg) => arg.trim().length > 0 && !arg.startsWith("-"));
-    return firstCommandArg?.trim();
+    return resolveRecoveryCommandName(recovery?.normalized_args);
 }
 function inferAllowedValuesFromMessage(message) {
     const match = message.match(/\bmust be one of:?\s+([A-Za-z0-9_.|,\- ]+)/i);
@@ -822,8 +840,7 @@ function buildUnknownOptionGuidance(message, commandName, context) {
         return buildUnsupportedUpdateOptionGuidance(optionName, context, suggestions);
     }
     const otherCommands = normalizeContextList(guidanceContext.unknownOptionOtherCommands) ?? [];
-    const candidateTotal = guidanceContext.unknownOptionOtherCommandsTotal ??
-        otherCommands.length;
+    const candidateTotal = guidanceContext.unknownOptionOtherCommandsTotal ?? otherCommands.length;
     const proseCommands = otherCommands.slice(0, 3);
     const proseRemainder = candidateTotal - proseCommands.length;
     let proseRemainderText = "";
@@ -842,7 +859,10 @@ function buildUnknownOptionGuidance(message, commandName, context) {
             ? `Replay with suggested correction: ${retryCommand}`
             : undefined,
     ].filter((entry) => typeof entry === "string");
-    const examples = [retryCommand, `pm ${commandName ?? "<command>"} --help`].filter((entry) => typeof entry === "string");
+    const examples = [
+        retryCommand,
+        `pm ${commandName ?? "<command>"} --help`,
+    ].filter((entry) => typeof entry === "string");
     return makeGuidanceMessage({
         code: "unknown_option",
         title: `Unknown option ${optionName}`,
@@ -966,6 +986,48 @@ function buildLinkedTestValueNotQuotedGuidance(message, commandName, context) {
         recovery: buildCommanderRecoveryPayload(context, retryCommand ? { suggested_retry: retryCommand } : {}),
     });
 }
+const TRANSPOSED_COLLECTION_COMMANDS = new Set([
+    "comments",
+    "docs",
+    "files",
+    "learnings",
+    "notes",
+    "test",
+]);
+function buildTransposedCollectionActionGuidance(message, commandName, context) {
+    if (!/too many arguments/i.test(message) ||
+        !TRANSPOSED_COLLECTION_COMMANDS.has(commandName ?? "")) {
+        return null;
+    }
+    const argv = context?.normalizedInvocationArgs ?? [];
+    const commandIndex = argv.findIndex((token) => token === commandName);
+    const action = argv[commandIndex + 1];
+    const parsedItemId = argv[commandIndex + 2];
+    const itemId = context?.verifiedCollectionItemId?.trim();
+    if (action?.toLowerCase() !== "add" ||
+        !parsedItemId ||
+        parsedItemId.startsWith("-") ||
+        !itemId ||
+        itemId.toLowerCase() !== parsedItemId.toLowerCase()) {
+        return null;
+    }
+    const suggestedRetry = `pm ${commandName} ${itemId} --add <value>`;
+    return makeGuidanceMessage({
+        code: "collection_transposed_subcommand",
+        title: `Transposed ${commandName} add syntax`,
+        happened: `The positional token "add" occupied the item-id role and "${itemId}" occupied the next positional role. pm ${commandName} does not use an add subcommand.`,
+        required: `Place the item id immediately after ${commandName}, then use --add for the value.`,
+        why: "Collection mutations use object-first grammar: pm <collection> <item-id> --add <value>.",
+        examples: [suggestedRetry, `pm ${commandName} --help`],
+        recovery: buildCommanderRecoveryPayload(context, {
+            parsed_positionals: [
+                { role: "transposed_subcommand", value: action },
+                { role: "item_id", value: itemId },
+            ],
+            suggested_retry: suggestedRetry,
+        }),
+    });
+}
 const CONTEXT_GUIDANCE_VALUE_FLAGS = new Set([
     "--activity-limit",
     "--assignee",
@@ -1041,6 +1103,7 @@ function buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, cont
         buildUnknownOptionGuidance(message, commandName, context) ??
         buildUnknownCommandGuidance(message, context) ??
         buildUnknownSubcommandGuidance(context) ??
+        buildTransposedCollectionActionGuidance(message, commandName, context) ??
         buildLinkedTestValueNotQuotedGuidance(message, commandName, context) ??
         buildContextItemArgumentGuidance(message, commandName, context);
     if (guidance) {
@@ -1134,4 +1197,4 @@ export const _testOnly = {
     resolveKnownPackageCommandHint,
 };
 //# sourceMappingURL=error-guidance.js.map
-//# debugId=4d6caae5-76d6-5563-acb9-b435f8cdfe9c
+//# debugId=9ec35c35-f2dc-5f86-a166-cf0c80eab1bd

package/dist/cli/main.js

@@ -3,7 +3,7 @@
  * @module cli/main
  */
 
-!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]="80e9dea8-2bb3-50e7-b21e-50ec328c3d3d")}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]="8aed7a8b-4c51-5aba-b27e-80f87f8f3d35")}catch(e){}}();
 import { Command } from "commander";
 import { activateExtensions, clearActiveExtensionHooks, createCoreCommandHookContext, resetActiveExtensionRuntimeState, createEmptyExtensionRegistrationRegistry, discoverExtensions, getActiveCommandResult, getActiveExtensionRegistrations, loadExtensions, consumeAfterCommandAffectedItems, runActiveCommandHandler, runActiveParserOverride, runActivePreflightOverride, runAfterCommandHooks, runBeforeCommandHooks, setActiveCommandResult, setActiveCommandContext, setActiveExtensionCommands, setActiveExtensionHooks, setActiveExtensionParsers, setActiveExtensionPreflight, setActiveExtensionRegistrations, setActiveExtensionRenderers, setActiveExtensionServices, pathExists, resolvePmCliVersion, resolvePmPackageRootFromModule, resolveItemTypeRegistry, resolveRuntimeFieldRegistry, EXIT_CODE, resolveTelemetryErrorCategory, PmCliError, asRecordOrNull, printError, printResult, maybeRunFirstUseTelemetryPrompt, emitTelemetryErrorEvent, startTelemetryCommand, deriveTelemetryCommandResolution, sentryCaptureCliError, sentryFinishCommandSpan, sentryFlush, sentryLogCliUsageError, sentrySetCommandContext, sentryStartCommandSpan, ensureSentryInit, getSettingsPath, resolvePmRoot, readSettings, readSettingsWithMetadata, runWithWorkspaceHarnessSignalDescriptors, createLazyModule, } from "../sdk/runtime-primitives.js";
 import { resolveSubcommandFlagContractsForCommand } from "../sdk/cli-contracts.js";
@@ -846,15 +846,29 @@ function activationCommandMatchesProbe(command, probe) {
     return false;
 }
 function extensionActivationCommands(extension) {
-    return (extension.activation?.commands ??
-        [
-            ...(extension.contributions?.commands ?? []),
-            ...(extension.contributions?.command_handlers ?? []),
-            ...(extension.contributions?.command_overrides ?? []),
-            ...(extension.contributions?.flag_commands ?? []),
-            ...(extension.contributions?.parser_overrides ?? []),
-            ...(extension.contributions?.renderer_ownership?.flatMap((entry) => entry.commands) ?? []),
-        ]);
+    const explicitCommands = extension.activation?.commands;
+    if (explicitCommands) {
+        return explicitCommands;
+    }
+    const contributions = extension.contributions;
+    if (!contributions) {
+        return [];
+    }
+    return [
+        ...entriesOrEmpty(contributions.commands),
+        ...entriesOrEmpty(contributions.command_handlers),
+        ...entriesOrEmpty(contributions.command_overrides),
+        ...entriesOrEmpty(contributions.flag_commands),
+        ...entriesOrEmpty(contributions.parser_overrides),
+        ...ownershipCommands(contributions.preflight_ownership),
+        ...ownershipCommands(contributions.renderer_ownership),
+    ];
+}
+function entriesOrEmpty(entries) {
+    return entries ?? [];
+}
+function ownershipCommands(entries) {
+    return entriesOrEmpty(entries).flatMap((entry) => entry.commands);
 }
 function extensionCapabilities(extension) {
     /* c8 ignore next */
@@ -917,14 +931,16 @@ function matchesStaticExtensionCommand(commands, probe) {
 /** Identify contribution surfaces that participate in global runtime behavior. */
 function hasGlobalExtensionContributions(contributions) {
     const contributionCounts = [
-        contributions.hooks?.length ?? 0,
-        contributions.preflight_overrides ?? 0,
-        contributions.item_types?.length ?? 0,
-        contributions.item_fields?.length ?? 0,
-        contributions.relationship_kinds?.length ?? 0,
-        contributions.service_overrides?.length ?? 0,
-        (contributions.renderer_overrides?.length ?? 0) -
-            (contributions.renderer_ownership?.length ?? 0),
+        entriesOrEmpty(contributions.hooks).length,
+        (contributions.preflight_overrides ?? 0) -
+            entriesOrEmpty(contributions.preflight_ownership).length,
+        entriesOrEmpty(contributions.item_types).length,
+        entriesOrEmpty(contributions.item_fields).length,
+        entriesOrEmpty(contributions.relationship_kinds).length,
+        entriesOrEmpty(contributions.service_overrides).length,
+        entriesOrEmpty(contributions.assurance_providers).length,
+        entriesOrEmpty(contributions.renderer_overrides).length -
+            entriesOrEmpty(contributions.renderer_ownership).length,
     ];
     return contributionCounts.some((count) => count > 0);
 }
@@ -2459,4 +2475,4 @@ export const _testOnly = {
     wrapThrownErrorForSentry,
 };
 //# sourceMappingURL=main.js.map
-//# debugId=80e9dea8-2bb3-50e7-b21e-50ec328c3d3d
+//# debugId=8aed7a8b-4c51-5aba-b27e-80f87f8f3d35

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.js

@@ -1,16 +1,21 @@
 
-!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";
+!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]="41d01430-1e95-5f09-9a2f-7e7f8fad8184")}catch(e){}}();
+import { 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 isPresetAction = action === "presets" || action === "apply";
+    const isPromote = action === "promote";
     const result = await runAssuranceAction({
         action,
-        ...(isRun || isVerdicts ? {} : { kind: kindOrGate }),
-        id: isRun || isVerdicts ? (id ?? kindOrGate) : id,
+        ...(isRun || isVerdicts || isPresetAction || isPromote
+            ? {}
+            : { kind: kindOrGate }),
+        id: isRun || isVerdicts || isPromote ? (id ?? kindOrGate) : id,
+        preset: isPresetAction ? (id ?? kindOrGate) : undefined,
         definition: readOptionString(options, "definition"),
         trigger: readOptionString(options, "trigger"),
         tree: readOptionString(options, "tree"),
@@ -21,6 +26,9 @@ async function runAssuranceCliAction(action, kindOrGate, id, options, command) {
         idOnly: global.idOnly,
         author: readOptionString(options, "author"),
         message: readOptionString(options, "message"),
+        owner: readOptionString(options, "owner"),
+        apply: options.apply === true,
+        enforcement: readOptionString(options, "enforcement"),
     }, global);
     printResult(result, global);
     if (typeof result === "object" &&
@@ -34,19 +42,22 @@ async function runAssuranceCliAction(action, kindOrGate, id, options, command) {
 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")
+        .argument("<action>", "Action; inspect `pm contracts --command assurance`")
+        .argument("[kind]", "Declaration kind or run gate id")
+        .argument("[id]", "Declaration/gate id")
+        .description("Manage SDK-owned assurance contracts.")
+        .option("--definition <json>", "Put declaration JSON")
+        .option("--trigger <value>", "Gate trigger")
+        .option("--tree <value>", "Revision identity")
+        .option("--gate <id>", "Verdict gate filter")
+        .option("--limit <number>", "Verdict limit")
+        .option("--dry-run", "Evaluate without recording")
+        .option("--author <value>", "Mutation author")
+        .option("--message <value>", "Mutation rationale")
+        .option("--owner <item-id>", "Preset/derivation owner")
+        .option("--apply", "Persist derived proposals")
+        .option("--enforcement <level>", "Promote to warn or block")
         .action(runAssuranceCliAction);
 }
 //# sourceMappingURL=register-assurance.js.map
-//# debugId=1adbac08-0950-55be-82bf-cc4dc7b6ad18
+//# debugId=41d01430-1e95-5f09-9a2f-7e7f8fad8184

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-operations.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]="8bd1cf90-5ac8-5470-903d-b9b61d62bb85")}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]="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";
@@ -54,6 +54,9 @@ function collectTestMutationValues(options) {
         removeValues: Array.isArray(options.remove)
             ? options.remove
             : [],
+        removeIndexValues: Array.isArray(options.removeIndex)
+            ? options.removeIndex
+            : [],
     };
 }
 function validateBackgroundTestOptions(options, values) {
@@ -65,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) {
@@ -77,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,
@@ -89,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,
@@ -127,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);
@@ -236,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,
@@ -565,7 +573,8 @@ export function registerOperationCommands(program) {
         .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")
@@ -613,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")
@@ -863,4 +873,4 @@ function registerSchedulingShortcutCommands(program) {
     });
 }
 //# sourceMappingURL=register-operations.js.map
-//# debugId=8bd1cf90-5ac8-5470-903d-b9b61d62bb85
+//# debugId=7796ea07-0de7-5db8-a3b5-a8021ceebc69