@unbrained/pm-cli 2026.7.1 → 2026.7.3

package/dist/cli/register-mutation.js

@@ -4,7 +4,7 @@
  * Provides CLI runtime support for Register Mutation.
  */
 
-!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]="703247b2-e81d-5a78-999d-6d493a4cf9bf")}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]="506e1f95-1444-5306-9a5e-c1fb3726b2df")}catch(e){}}();
 import { Option } from "commander";
 import { resolveBodyFileContent } from "../core/io/body-file.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
@@ -18,7 +18,7 @@ import { BUILTIN_ITEM_TYPE_VALUES } from "../types/index.js";
 // positional exactly matches a known type AND no --title was given, we throw
 // instead of silently creating a Task titled with the type name.
 const BUILTIN_TYPE_NAME_LOOKUP = new Set(BUILTIN_ITEM_TYPE_VALUES.map((value) => value.toLowerCase()));
-import { collect, extractUpdateManyMutationOptionSource, formatHookWarnings, getGlobalOptions, invalidateSearchCachesForMutation, normalizeCreateOptions, normalizeUpdateOptions, printError, printResult, writeStdout, } from "./registration-helpers.js";
+import { collect, extractUpdateManyMutationOptionSource, formatHookWarnings, getGlobalOptions, invalidateSearchCachesForMutation, normalizeCreateOptions, normalizeUpdateOptions, printError, printResult, readOptionString, writeStdout, } from "./registration-helpers.js";
 /**
  * Register a flag and hide it from `--help` text while keeping it fully
  * functional as a parse-time alias. The option still appears in
@@ -33,6 +33,11 @@ function addHiddenOption(command, flags, description, repeatable) {
     }
     command.addOption(option);
 }
+function addHiddenOptions(command, aliases, repeatable) {
+    for (const [flags, description] of aliases) {
+        addHiddenOption(command, flags, description, repeatable);
+    }
+}
 const SCHEMA_SHORTHAND_RESERVED_PREFIXES = ["add-", "apply-", "list-", "remove-", "show-"];
 const SCHEMA_SHORTHAND_RESERVED_TOKENS = new Set([
     "field",
@@ -399,6 +404,732 @@ function buildUpdateManyListOptions(options) {
         includeBody: true,
     };
 }
+function pickStringOption(...candidates) {
+    for (const candidate of candidates) {
+        if (typeof candidate === "string") {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+function stringArrayOption(value) {
+    if (Array.isArray(value)) {
+        return value;
+    }
+    if (typeof value === "string") {
+        return [value];
+    }
+    return undefined;
+}
+function resolveCreatePositionals(typeOrTitle, secondTitle, options) {
+    if (typeof secondTitle === "string" && secondTitle.length > 0) {
+        return { positionalType: typeOrTitle, positionalTitle: secondTitle };
+    }
+    if (typeof typeOrTitle !== "string" || typeOrTitle.length === 0) {
+        return { positionalType: undefined, positionalTitle: undefined };
+    }
+    const explicitTitleProvided = typeof options.title === "string" && options.title.trim().length > 0;
+    return explicitTitleProvided && options.type === undefined
+        ? { positionalType: typeOrTitle, positionalTitle: undefined }
+        : { positionalType: undefined, positionalTitle: typeOrTitle };
+}
+function assertCreatePositionalTypeHasTitle(positionalType, positionalTitle, options) {
+    if (positionalType !== undefined ||
+        typeof positionalTitle !== "string" ||
+        positionalTitle.length === 0 ||
+        options.title !== undefined ||
+        options.type !== undefined ||
+        !BUILTIN_TYPE_NAME_LOOKUP.has(positionalTitle.trim().toLowerCase())) {
+        return;
+    }
+    const matchedType = positionalTitle.trim();
+    throw new PmCliError(`pm create needs a title — "${matchedType}" looks like an item type, not a title. Use either: pm create ${matchedType} "<title>" or pm create "<title>" --type ${matchedType}.`, EXIT_CODE.USAGE, {
+        code: "create_positional_type_without_title",
+        why: "Without this guard the single positional is used as the title and the type defaults to Task — so the command would silently create a Task literally titled \"" + matchedType + "\".",
+        examples: [
+            `pm create ${matchedType} "Wire up SSO for the agent harness"`,
+            `pm create "Wire up SSO for the agent harness" --type ${matchedType}`,
+        ],
+        nextSteps: [
+            `Re-run with both type and title: pm create ${matchedType} "<title>"`,
+        ],
+    });
+}
+async function runCreateAction(typeOrTitle, secondTitle, options, command) {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const positionals = resolveCreatePositionals(typeOrTitle, secondTitle, options);
+    assertCreatePositionalTypeHasTitle(positionals.positionalType, positionals.positionalTitle, options);
+    if (typeof positionals.positionalType === "string" && positionals.positionalType.length > 0 && options.type === undefined) {
+        options.type = positionals.positionalType;
+    }
+    if (typeof positionals.positionalTitle === "string" && positionals.positionalTitle.length > 0 && options.title === undefined) {
+        options.title = positionals.positionalTitle;
+    }
+    if (typeof options.bodyFile === "string") {
+        options.body = await resolveBodyFileContent(options.bodyFile, options.body !== undefined ? String(options.body) : undefined);
+        delete options.bodyFile;
+    }
+    const normalized = normalizeCreateOptions(options, { requireType: false });
+    const { runCreate } = await import("./commands/create.js");
+    const result = await runCreate(normalized, globalOptions);
+    await invalidateSearchCachesForMutation(globalOptions, result);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=create took_ms=${Date.now() - startedAt}`);
+    }
+}
+function buildCloseManyListOptions(options) {
+    return {
+        type: readOptionString(options, "filterType"),
+        tag: readOptionString(options, "filterTag"),
+        priority: readOptionString(options, "filterPriority"),
+        deadlineBefore: readOptionString(options, "filterDeadlineBefore"),
+        deadlineAfter: readOptionString(options, "filterDeadlineAfter"),
+        updatedAfter: readOptionString(options, "filterUpdatedAfter"),
+        updatedBefore: readOptionString(options, "filterUpdatedBefore"),
+        createdAfter: readOptionString(options, "filterCreatedAfter"),
+        createdBefore: readOptionString(options, "filterCreatedBefore"),
+        ids: readOptionString(options, "ids"),
+        assignee: readOptionString(options, "filterAssignee"),
+        assigneeFilter: pickStringOption(options.filterAssigneeFilter, options.filterAssignee_filter),
+        parent: readOptionString(options, "filterParent"),
+        sprint: readOptionString(options, "filterSprint"),
+        release: readOptionString(options, "filterRelease"),
+        ...mapBulkContentAndGovernanceFilters(options),
+        limit: readOptionString(options, "limit"),
+        offset: readOptionString(options, "offset"),
+    };
+}
+async function runCloseManyAction(options, command) {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const { runCloseMany } = await import("./commands/close-many.js");
+    const result = await runCloseMany({
+        status: readOptionString(options, "filterStatus"),
+        list: buildCloseManyListOptions(options),
+        reason: readOptionString(options, "reason"),
+        resolution: readOptionString(options, "resolution"),
+        expectedResult: pickStringOption(options.expectedResult, options.expected_result, options.expected),
+        actualResult: pickStringOption(options.actualResult, options.actual_result, options.actual),
+        validateClose: options.validateClose === true
+            ? "warn"
+            : readOptionString(options, "validateClose"),
+        author: readOptionString(options, "author"),
+        message: readOptionString(options, "message"),
+        force: Boolean(options.force),
+        dryRun: options.dryRun === true ? true : undefined,
+        rollback: readOptionString(options, "rollback"),
+        checkpoint: options.checkpoint === false ? false : undefined,
+    }, globalOptions);
+    await invalidateSearchCachesForMutation(globalOptions, result);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=close-many took_ms=${Date.now() - startedAt}`);
+    }
+}
+async function runUpdateManyAction(options, command) {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const { runUpdateMany } = await import("./commands/update-many.js");
+    const result = await runUpdateMany({
+        status: readOptionString(options, "filterStatus"),
+        list: buildUpdateManyListOptions(options),
+        update: normalizeUpdateOptions(extractUpdateManyMutationOptionSource(options)),
+        dryRun: options.dryRun === true ? true : undefined,
+        rollback: readOptionString(options, "rollback"),
+        checkpoint: options.checkpoint === false ? false : undefined,
+    }, globalOptions);
+    await invalidateSearchCachesForMutation(globalOptions, result);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=update-many took_ms=${Date.now() - startedAt}`);
+    }
+}
+async function runCloseAction(id, text, options, command) {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const { runClose } = await import("./commands/close.js");
+    const reasonFromOption = (typeof options.reason === "string" && options.reason.trim().length > 0 && options.reason) ||
+        (typeof options.closeReason === "string" && options.closeReason.trim().length > 0 && options.closeReason) ||
+        undefined;
+    const resolvedText = typeof text === "string" && text.length > 0 ? text : reasonFromOption;
+    const result = await runClose(id, resolvedText, {
+        author: readOptionString(options, "author"),
+        message: readOptionString(options, "message"),
+        validateClose: options.validateClose === true
+            ? "warn"
+            : readOptionString(options, "validateClose"),
+        force: Boolean(options.force),
+        duplicateOf: readOptionString(options, "duplicateOf"),
+        resolution: readOptionString(options, "resolution"),
+        expectedResult: pickStringOption(options.expectedResult, options.expected_result, options.expected),
+        actualResult: pickStringOption(options.actualResult, options.actual_result, options.actual),
+    }, globalOptions);
+    await invalidateSearchCachesForMutation(globalOptions, result);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=close took_ms=${Date.now() - startedAt}`);
+    }
+}
+function normalizePlanAliases(options) {
+    const planOptions = { ...options };
+    const aliasPairs = [
+        ["blocked_by", "blockedBy"],
+        ["resume_context", "resumeContext"],
+        ["from_search", "fromSearch"],
+        ["step_title", "stepTitle"],
+        ["step_body", "stepBody"],
+        ["step_owner", "stepOwner"],
+        ["step_status", "stepStatus"],
+        ["step_evidence", "stepEvidence"],
+        ["step_blocked_reason", "stepBlockedReason"],
+        ["step_replacement", "stepReplacement"],
+        ["depends_on", "dependsOn"],
+        ["link_kind", "linkKind"],
+        ["link_note", "linkNote"],
+        ["promote_to_item_dep", "promoteToItemDep"],
+        ["allow_multiple_active", "allowMultipleActive"],
+        ["decision_text", "decisionText"],
+        ["decision_rationale", "decisionRationale"],
+        ["decision_evidence", "decisionEvidence"],
+        ["discovery_text", "discoveryText"],
+        ["validation_text", "validationText"],
+        ["validation_command", "validationCommand"],
+        ["validation_expected", "validationExpected"],
+        ["materialize_type", "materializeType"],
+        ["materialize_parent", "materializeParent"],
+        ["materialize_tags", "materializeTags"],
+    ];
+    for (const [snake, camel] of aliasPairs) {
+        if (planOptions[snake] !== undefined && planOptions[camel] === undefined) {
+            planOptions[camel] = planOptions[snake];
+        }
+    }
+    return planOptions;
+}
+function assertKnownPlanSubcommand(subcommand, normalized, allowed) {
+    if (!normalized) {
+        throw new PmCliError(`pm plan requires a subcommand. Allowed: ${allowed.join(", ")}`, EXIT_CODE.USAGE, {
+            code: "missing_required_argument",
+            examples: [
+                'pm plan create --title "Refactor lock retry"',
+                "pm plan show pm-a1b2 --depth standard",
+                'pm plan add-step pm-a1b2 --step-title "Read lock.ts"',
+            ],
+        });
+    }
+    if (allowed.includes(normalized)) {
+        return;
+    }
+    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);
+}
+function parsePlanReorderTo(normalizedSubcommand, reorderToken) {
+    if (normalizedSubcommand !== "reorder-step" || typeof reorderToken !== "string") {
+        return undefined;
+    }
+    const parsed = Number.parseInt(reorderToken, 10);
+    if (!Number.isFinite(parsed)) {
+        throw new PmCliError(`reorder-step requires an integer new order, got "${reorderToken}"`, EXIT_CODE.USAGE);
+    }
+    return parsed;
+}
+async function runPlanAction(subcommand, id, stepRef, reorderToken, options, command) {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const { runPlan, PLAN_SUBCOMMANDS } = await import("./commands/plan.js");
+    const normalizedSubcommand = (subcommand ?? "").trim().toLowerCase();
+    assertKnownPlanSubcommand(subcommand, normalizedSubcommand, PLAN_SUBCOMMANDS);
+    const planOptions = normalizePlanAliases(options);
+    const reorderTo = parsePlanReorderTo(normalizedSubcommand, reorderToken);
+    const planId = normalizedSubcommand === "create" && typeof id === "string" && id.length > 0 && planOptions.title === undefined
+        ? undefined
+        : id;
+    if (planId === undefined && typeof id === "string" && id.length > 0) {
+        planOptions.title = id;
+    }
+    const result = await runPlan({
+        subcommand: normalizedSubcommand,
+        id: planId,
+        stepRef,
+        reorderTo,
+        options: planOptions,
+        global: globalOptions,
+    });
+    await invalidateSearchCachesForMutation(globalOptions, result);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=plan took_ms=${Date.now() - startedAt}`);
+    }
+}
+function parseNonNegativeIntFlag(raw, flag) {
+    if (typeof raw !== "string") {
+        return undefined;
+    }
+    if (!/^\d+$/.test(raw.trim())) {
+        throw new PmCliError(`history-compact ${flag} must be a non-negative integer.`, EXIT_CODE.USAGE);
+    }
+    return Number.parseInt(raw, 10);
+}
+async function runHistoryCompactAction(id, options, command) {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const { runHistoryCompact, runHistoryCompactBulk, assertHistoryCompactTarget } = await import("./commands/history-compact.js");
+    const ids = typeof options.ids === "string" ? splitCommaList(options.ids) : undefined;
+    const allOver = parseNonNegativeIntFlag(options.allOver, "--all-over");
+    const minEntries = parseNonNegativeIntFlag(options.minEntries, "--min-entries");
+    if (options.closed === true && options.allStreams === true) {
+        throw new PmCliError("history-compact: --closed and --all-streams are mutually exclusive; pick one lifecycle scope.", EXIT_CODE.USAGE);
+    }
+    const scope = options.closed === true ? "closed" : options.allStreams === true ? "all-streams" : undefined;
+    const isBulk = ids !== undefined || allOver !== undefined || scope !== undefined;
+    if (isBulk && typeof options.before === "string") {
+        throw new PmCliError("history-compact: --before applies only in single-id mode (bulk mode always compacts full streams).", EXIT_CODE.USAGE);
+    }
+    assertHistoryCompactTarget(id, { ids, allOver, scope });
+    if (id === undefined) {
+        const result = await runHistoryCompactBulk({
+            ids,
+            scope,
+            allOver,
+            minEntries,
+            dryRun: options.dryRun === true,
+            author: readOptionString(options, "author"),
+            message: readOptionString(options, "message"),
+            force: Boolean(options.force),
+        }, globalOptions);
+        printResult(result, globalOptions);
+        if (result.totals.items_errored > 0) {
+            process.exitCode = EXIT_CODE.GENERIC_FAILURE;
+        }
+    }
+    else {
+        const result = await runHistoryCompact(id, {
+            before: readOptionString(options, "before"),
+            dryRun: options.dryRun === true,
+            author: readOptionString(options, "author"),
+            message: readOptionString(options, "message"),
+            force: Boolean(options.force),
+        }, globalOptions);
+        printResult(result, globalOptions);
+    }
+    if (globalOptions.profile) {
+        printError(`profile:command=history-compact took_ms=${Date.now() - startedAt}`);
+    }
+}
+function splitCollectedCommaList(raw) {
+    if (!Array.isArray(raw)) {
+        return undefined;
+    }
+    return raw
+        .flatMap((value) => value.split(","))
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0);
+}
+async function runSchemaAction(subcommand, name, options, command) {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const schemaModule = await import("./commands/schema.js");
+    const { SCHEMA_SUBCOMMANDS } = schemaModule;
+    let normalizedSubcommand = (subcommand ?? "").trim().toLowerCase();
+    let typeName = name;
+    assertSchemaSubcommandPresent(normalizedSubcommand, SCHEMA_SUBCOMMANDS);
+    if (!SCHEMA_SUBCOMMANDS.includes(normalizedSubcommand) &&
+        typeName === undefined &&
+        !looksLikeSchemaSubcommandTypo(normalizedSubcommand)) {
+        typeName = subcommand;
+        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" });
+    }
+    const result = await dispatchSchemaSubcommand(schemaModule, {
+        normalizedSubcommand,
+        typeName,
+        options,
+        aliases: stringArrayOption(options.alias),
+        roles: stringArrayOption(options.role),
+        commands: splitCollectedCommaList(options.commands),
+        requiredTypes: splitCollectedCommaList(options.requiredTypes),
+        defaultStatus: pickStringOption(options.defaultStatus, options.default_status),
+        order: parseSchemaOrderOption(options.order),
+        minCount: parseSchemaOrderOption(options.minCount),
+        author: readOptionString(options, "author"),
+        force: Boolean(options.force),
+        description: readOptionString(options, "description"),
+        globalOptions,
+    });
+    if (globalOptions.json === true || globalOptions.defaultOutputFormat === "json") {
+        printResult(result, globalOptions);
+    }
+    else if (!globalOptions.quiet) {
+        renderSchemaResultHuman(schemaModule, result);
+    }
+    if (globalOptions.profile) {
+        printError(`profile:command=schema took_ms=${Date.now() - startedAt}`);
+    }
+}
+function assertSchemaSubcommandPresent(normalizedSubcommand, allowed) {
+    if (normalizedSubcommand) {
+        return;
+    }
+    throw new PmCliError(`pm schema requires a subcommand. Allowed: ${allowed.join(", ")}`, EXIT_CODE.USAGE, {
+        code: "missing_required_argument",
+        examples: [
+            "pm schema list",
+            "pm schema show Task",
+            "pm schema show-status open",
+            'pm schema add-type Spike --description "Time-boxed investigation" --default-status open',
+            "pm schema remove-type Spike",
+            "pm schema add-status review --role active --alias in_review",
+            "pm schema remove-status review",
+            "pm schema add-field severity_level --type string --commands create,update",
+            "pm schema list-fields",
+            "pm schema apply-preset agile",
+            "pm schema add-type --infer --min-count 10",
+        ],
+    });
+}
+function resolveCommentSources(text, options) {
+    const editIndex = typeof options.edit === "number" ? options.edit : undefined;
+    const deleteIndex = typeof options.delete === "number" ? options.delete : undefined;
+    const addFromOption = readOptionString(options, "add");
+    const addFromPositional = typeof text === "string" ? text : undefined;
+    const readFromStdin = options.stdin === true;
+    const readFromFile = readOptionString(options, "file");
+    const sourceCount = Number(addFromOption !== undefined) +
+        Number(addFromPositional !== undefined) +
+        Number(readFromStdin) +
+        Number(readFromFile !== undefined);
+    if (sourceCount > 1) {
+        if (addFromOption !== undefined && addFromPositional !== undefined && !readFromStdin && readFromFile === undefined) {
+            throw new PmCliError("Specify comment text either as positional [text] or with --add, not both", EXIT_CODE.USAGE);
+        }
+        throw new PmCliError("Specify comment text with exactly one source: positional [text], --add, --stdin, or --file", EXIT_CODE.USAGE);
+    }
+    const add = addFromOption ?? addFromPositional;
+    const isMutation = typeof add === "string" || readFromStdin || readFromFile !== undefined || editIndex !== undefined || deleteIndex !== undefined;
+    return { add, readFromStdin, readFromFile, editIndex, deleteIndex, isMutation };
+}
+async function runCommentsAction(id, text, options, command) {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const sources = resolveCommentSources(text, options);
+    const { runComments } = await import("./commands/comments.js");
+    const result = await runComments(id, {
+        add: sources.add,
+        stdin: sources.readFromStdin,
+        file: sources.readFromFile,
+        edit: sources.editIndex,
+        delete: sources.deleteIndex,
+        limit: readOptionString(options, "limit"),
+        author: readOptionString(options, "author"),
+        message: readOptionString(options, "message"),
+        allowAuditComment: Boolean(options.allowAuditComment),
+        force: Boolean(options.force),
+    }, globalOptions);
+    if (sources.isMutation) {
+        await invalidateSearchCachesForMutation(globalOptions, result);
+    }
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=comments took_ms=${Date.now() - startedAt}`);
+    }
+}
+async function runCopyAction(id, options, command) {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const { runCopy } = await import("./commands/copy.js");
+    const result = await runCopy(id, {
+        title: readOptionString(options, "title"),
+        author: readOptionString(options, "author"),
+        message: readOptionString(options, "message"),
+    }, globalOptions);
+    await invalidateSearchCachesForMutation(globalOptions, result);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=copy took_ms=${Date.now() - startedAt}`);
+    }
+}
+async function runFocusAction(id, options, command) {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const { runFocus } = await import("./commands/focus.js");
+    const result = await runFocus(id, { clear: options.clear === true }, globalOptions);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=focus took_ms=${Date.now() - startedAt}`);
+    }
+}
+async function runUpdateAction(id, options, command) {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    // GH-214: resolve --body-file into the existing body field before
+    // normalization so the rest of update is unchanged. CLI-only input alias.
+    if (typeof options.bodyFile === "string") {
+        options.body = await resolveBodyFileContent(options.bodyFile, options.body !== undefined ? String(options.body) : undefined);
+        delete options.bodyFile;
+    }
+    const { runUpdate } = await import("./commands/update.js");
+    const result = await runUpdate(id, normalizeUpdateOptions(options), globalOptions);
+    await invalidateSearchCachesForMutation(globalOptions, result);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=update took_ms=${Date.now() - startedAt}`);
+    }
+}
+async function runDeleteAction(id, options, command) {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const { runDelete } = await import("./commands/delete.js");
+    const result = await runDelete(id, {
+        author: readOptionString(options, "author"),
+        message: readOptionString(options, "message"),
+        force: Boolean(options.force),
+        dryRun: options.dryRun === true,
+    }, globalOptions);
+    if (result.dry_run !== true) {
+        await invalidateSearchCachesForMutation(globalOptions, result);
+    }
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=delete took_ms=${Date.now() - startedAt}`);
+    }
+}
+function resolveSingleTextSource(label, positional, options) {
+    const addFromOption = readOptionString(options, "add");
+    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);
+    }
+    return addFromOption ?? addFromPositional;
+}
+function resolveAppendBody(text, options) {
+    const bodyFromOption = readOptionString(options, "body");
+    const bodyFromAlias = readOptionString(options, "text");
+    const bodyFromPositional = typeof text === "string" ? text : undefined;
+    const bodySourceCount = [bodyFromOption, bodyFromAlias, bodyFromPositional].filter((value) => value !== undefined).length;
+    if (bodySourceCount > 1) {
+        throw new PmCliError("Specify append text with exactly one source: positional [text], --body, or --text", EXIT_CODE.USAGE);
+    }
+    const resolvedBody = bodyFromOption ?? bodyFromAlias ?? bodyFromPositional;
+    if (resolvedBody === undefined) {
+        throw new PmCliError("Missing append text. Provide it as positional [text], --body <value>, or --text <value> (use - for stdin).", EXIT_CODE.USAGE);
+    }
+    return resolvedBody;
+}
+async function runAppendAction(id, text, options, command) {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const { runAppend } = await import("./commands/append.js");
+    const result = await runAppend(id, {
+        body: resolveAppendBody(text, options),
+        author: readOptionString(options, "author"),
+        message: readOptionString(options, "message"),
+        force: Boolean(options.force),
+    }, globalOptions);
+    await invalidateSearchCachesForMutation(globalOptions, result);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=append took_ms=${Date.now() - startedAt}`);
+    }
+}
+async function runRestoreAction(id, target, options, command) {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const { runRestore } = await import("./commands/restore.js");
+    const result = await runRestore(id, target, {
+        author: readOptionString(options, "author"),
+        message: readOptionString(options, "message"),
+        force: Boolean(options.force),
+    }, globalOptions);
+    await invalidateSearchCachesForMutation(globalOptions, result);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=restore took_ms=${Date.now() - startedAt}`);
+    }
+}
+async function runProfileAction(subcommand, name, options, command) {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const profileModule = await import("./commands/profile.js");
+    const { PROFILE_SUBCOMMANDS } = profileModule;
+    const normalizedSubcommand = (subcommand ?? "").trim().toLowerCase();
+    if (!normalizedSubcommand) {
+        throw new PmCliError(`pm profile requires a subcommand. Allowed: ${PROFILE_SUBCOMMANDS.join(", ")}`, EXIT_CODE.USAGE, {
+            code: "missing_required_argument",
+            examples: ["pm profile list", "pm profile show agile", "pm profile apply agile --dry-run", "pm profile lint agile"],
+        });
+    }
+    if (!PROFILE_SUBCOMMANDS.includes(normalizedSubcommand)) {
+        throw new PmCliError(`Unknown pm profile subcommand "${subcommand}". Allowed: ${PROFILE_SUBCOMMANDS.join(", ")}`, EXIT_CODE.USAGE, { code: "unknown_subcommand" });
+    }
+    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).
+    if (globalOptions.json === true || globalOptions.defaultOutputFormat === "json") {
+        printResult(result, globalOptions);
+    }
+    else if (!globalOptions.quiet) {
+        renderProfileResultHuman(profileModule, result);
+    }
+    // `pm profile lint` is a validation gate: exit non-zero when the profile has
+    // error-severity findings so shell/CI callers can fail on them. Warnings keep
+    // `ok` true and never fail the command.
+    if (result.action === "lint" && !result.ok) {
+        process.exitCode = EXIT_CODE.GENERIC_FAILURE;
+    }
+    if (globalOptions.profile) {
+        printError(`profile:command=profile took_ms=${Date.now() - startedAt}`);
+    }
+}
+async function runNotesAction(id, text, options, command) {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const add = resolveSingleTextSource("note", text, options);
+    const { runNotes } = await import("./commands/notes.js");
+    const result = await runNotes(id, {
+        add,
+        limit: readOptionString(options, "limit"),
+        author: readOptionString(options, "author"),
+        message: readOptionString(options, "message"),
+        allowAuditComment: Boolean(options.allowAuditNote || options.allowAuditComment),
+        force: Boolean(options.force),
+    }, globalOptions);
+    if (typeof add === "string") {
+        await invalidateSearchCachesForMutation(globalOptions, result);
+    }
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=notes took_ms=${Date.now() - startedAt}`);
+    }
+}
+async function runLearningsAction(id, text, options, command) {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const add = resolveSingleTextSource("learning", text, options);
+    const { runLearnings } = await import("./commands/learnings.js");
+    const result = await runLearnings(id, {
+        add,
+        limit: readOptionString(options, "limit"),
+        author: readOptionString(options, "author"),
+        message: readOptionString(options, "message"),
+        allowAuditComment: Boolean(options.allowAuditLearning || options.allowAuditComment),
+        force: Boolean(options.force),
+    }, globalOptions);
+    if (typeof add === "string") {
+        await invalidateSearchCachesForMutation(globalOptions, result);
+    }
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=learnings took_ms=${Date.now() - startedAt}`);
+    }
+}
+function readStringArrayOption(options, key) {
+    return stringArrayOption(options[key]) ?? [];
+}
+async function runFilesAction(id, options, command) {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const addValues = readStringArrayOption(options, "add");
+    const addGlobValues = readStringArrayOption(options, "addGlob");
+    const removeValues = readStringArrayOption(options, "remove");
+    const migrateValues = readStringArrayOption(options, "migrate");
+    const { runFiles } = await import("./commands/files.js");
+    const result = await runFiles(id, {
+        add: addValues,
+        addGlob: addGlobValues,
+        remove: removeValues,
+        migrate: migrateValues,
+        note: readOptionString(options, "note"),
+        list: Boolean(options.list),
+        appendStable: Boolean(options.appendStable),
+        validatePaths: Boolean(options.validatePaths),
+        audit: Boolean(options.audit),
+        author: readOptionString(options, "author"),
+        message: readOptionString(options, "message"),
+        force: Boolean(options.force),
+    }, globalOptions);
+    if (addValues.length > 0 || addGlobValues.length > 0 || removeValues.length > 0 || migrateValues.length > 0) {
+        await invalidateSearchCachesForMutation(globalOptions, result);
+    }
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=files took_ms=${Date.now() - startedAt}`);
+    }
+}
+async function runFilesDiscoverAction(id, options, command) {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    // Flags also declared on the parent files command (--note/--append-stable/
+    // --author/--message/--force) are consumed by the parent during parse, so
+    // merge ancestor opts back in (own options win) instead of reading opts() alone.
+    const mergedOptions = { ...command.optsWithGlobals(), ...options };
+    const { runFilesDiscover } = await import("./commands/files.js");
+    const result = await runFilesDiscover(id, {
+        apply: Boolean(mergedOptions.apply),
+        note: readOptionString(mergedOptions, "note"),
+        appendStable: Boolean(mergedOptions.appendStable),
+        author: readOptionString(mergedOptions, "author"),
+        message: readOptionString(mergedOptions, "message"),
+        force: Boolean(mergedOptions.force),
+    }, globalOptions);
+    if (result.changed) {
+        await invalidateSearchCachesForMutation(globalOptions, result);
+    }
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=files.discover took_ms=${Date.now() - startedAt}`);
+    }
+}
+async function runDocsAction(id, options, command) {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const addValues = readStringArrayOption(options, "add");
+    const addGlobValues = readStringArrayOption(options, "addGlob");
+    const removeValues = readStringArrayOption(options, "remove");
+    const migrateValues = readStringArrayOption(options, "migrate");
+    const { runDocs } = await import("./commands/docs.js");
+    const result = await runDocs(id, {
+        add: addValues,
+        addGlob: addGlobValues,
+        remove: removeValues,
+        migrate: migrateValues,
+        note: readOptionString(options, "note"),
+        list: Boolean(options.list),
+        validatePaths: Boolean(options.validatePaths),
+        audit: Boolean(options.audit),
+        author: readOptionString(options, "author"),
+        message: readOptionString(options, "message"),
+        force: Boolean(options.force),
+    }, globalOptions);
+    if (addValues.length > 0 || addGlobValues.length > 0 || removeValues.length > 0 || migrateValues.length > 0) {
+        await invalidateSearchCachesForMutation(globalOptions, result);
+    }
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=docs took_ms=${Date.now() - startedAt}`);
+    }
+}
+async function runDepsAction(id, options, command) {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const { runDeps } = await import("./commands/deps.js");
+    // --format and --collapse carry commander defaults ("tree"/"none"), so
+    // they are always strings by the time the action runs; --maxDepth has no
+    // default and may be unset. Use `as string` rather than String(...) so an
+    // omitted option stays undefined instead of becoming the literal "undefined".
+    const result = await runDeps(id, {
+        format: options.format,
+        maxDepth: readOptionString(options, "maxDepth"),
+        collapse: options.collapse,
+        summary: options.summary === true,
+    }, globalOptions);
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=deps took_ms=${Date.now() - startedAt}`);
+    }
+}
 /**
  * Implements register mutation commands for the public runtime surface of this module.
  */
@@ -421,75 +1152,7 @@ export function registerMutationCommands(program) {
         .option("--clear-reminders", "Clear reminders")
         .option("--clear-events", "Clear events")
         .option("--clear-type-options", "Clear type options")
-        .action(async (typeOrTitle, secondTitle, options, command) => {
-        const globalOptions = getGlobalOptions(command);
-        const startedAt = Date.now();
-        // Support both `pm create "<title>"` and the natural subcommand-style
-        // `pm create <type> "<title>"` so agents are never blocked by argument
-        // count. When two positionals are given, the first is the item type.
-        let positionalType;
-        let positionalTitle;
-        if (typeof secondTitle === "string" && secondTitle.length > 0) {
-            positionalType = typeOrTitle;
-            positionalTitle = secondTitle;
-        }
-        else if (typeof typeOrTitle === "string" && typeOrTitle.length > 0) {
-            // Honor `pm create <type> --title ...` by treating the lone positional as
-            // type when an explicit --title is already present.
-            const explicitTitleProvided = typeof options.title === "string" && options.title.trim().length > 0;
-            if (explicitTitleProvided && options.type === undefined) {
-                positionalType = typeOrTitle;
-            }
-            else {
-                positionalTitle = typeOrTitle;
-            }
-        }
-        // pm-edge #1 (2026-05-28): when the sole positional matches a known
-        // item type AND no --title was supplied, refuse early instead of
-        // silently creating a Task titled with the type name (e.g. `pm create
-        // Epic` would previously produce a Task literally titled "Epic"). The
-        // guard fires only for the ambiguous single-positional case so the
-        // documented `pm create <type> <title>` flow stays a never-block.
-        if (positionalType === undefined &&
-            typeof positionalTitle === "string" &&
-            positionalTitle.length > 0 &&
-            options.title === undefined &&
-            options.type === undefined &&
-            BUILTIN_TYPE_NAME_LOOKUP.has(positionalTitle.trim().toLowerCase())) {
-            const matchedType = positionalTitle.trim();
-            throw new PmCliError(`pm create needs a title — "${matchedType}" looks like an item type, not a title. Use either: pm create ${matchedType} "<title>" or pm create "<title>" --type ${matchedType}.`, EXIT_CODE.USAGE, {
-                code: "create_positional_type_without_title",
-                why: "Without this guard the single positional is used as the title and the type defaults to Task — so the command would silently create a Task literally titled \"" + matchedType + "\".",
-                examples: [
-                    `pm create ${matchedType} "Wire up SSO for the agent harness"`,
-                    `pm create "Wire up SSO for the agent harness" --type ${matchedType}`,
-                ],
-                nextSteps: [
-                    `Re-run with both type and title: pm create ${matchedType} "<title>"`,
-                ],
-            });
-        }
-        if (typeof positionalType === "string" && positionalType.length > 0 && options.type === undefined) {
-            options.type = positionalType;
-        }
-        if (typeof positionalTitle === "string" && positionalTitle.length > 0 && options.title === undefined) {
-            options.title = positionalTitle;
-        }
-        // GH-214: resolve --body-file into the existing body field before
-        // normalization so the rest of create is unchanged. CLI-only input alias.
-        if (typeof options.bodyFile === "string") {
-            options.body = await resolveBodyFileContent(options.bodyFile, options.body !== undefined ? String(options.body) : undefined);
-            delete options.bodyFile;
-        }
-        const normalized = normalizeCreateOptions(options, { requireType: false });
-        const { runCreate } = await import("./commands/create.js");
-        const result = await runCreate(normalized, globalOptions);
-        await invalidateSearchCachesForMutation(globalOptions, result);
-        printResult(result, globalOptions);
-        if (globalOptions.profile) {
-            printError(`profile:command=create took_ms=${Date.now() - startedAt}`);
-        }
-    });
+        .action(runCreateAction);
     program
         .command("copy")
         .argument("<id>", "Source item id")
@@ -497,36 +1160,13 @@ export function registerMutationCommands(program) {
         .option("--author <value>", "Mutation author")
         .option("--message <value>", "History message")
         .description("Copy an item into a new item id while resetting lifecycle fields.")
-        .action(async (id, options, command) => {
-        const globalOptions = getGlobalOptions(command);
-        const startedAt = Date.now();
-        const { runCopy } = await import("./commands/copy.js");
-        const result = await runCopy(id, {
-            title: typeof options.title === "string" ? options.title : undefined,
-            author: typeof options.author === "string" ? options.author : undefined,
-            message: typeof options.message === "string" ? options.message : undefined,
-        }, globalOptions);
-        await invalidateSearchCachesForMutation(globalOptions, result);
-        printResult(result, globalOptions);
-        if (globalOptions.profile) {
-            printError(`profile:command=copy took_ms=${Date.now() - startedAt}`);
-        }
-    });
+        .action(runCopyAction);
     program
         .command("focus")
         .argument("[id]", "Item id to focus (omit to show current focus)")
         .option("--clear", "Clear the focused item")
         .description("Set/clear/show the session focused item that new items default --parent to.")
-        .action(async (id, options, command) => {
-        const globalOptions = getGlobalOptions(command);
-        const startedAt = Date.now();
-        const { runFocus } = await import("./commands/focus.js");
-        const result = await runFocus(id, { clear: options.clear === true }, globalOptions);
-        printResult(result, globalOptions);
-        if (globalOptions.profile) {
-            printError(`profile:command=focus took_ms=${Date.now() - startedAt}`);
-        }
-    });
+        .action(runFocusAction);
     const updateCommand = program
         .command("update")
         .argument("<id>", "Item id")
@@ -551,24 +1191,7 @@ export function registerMutationCommands(program) {
         .option("--force", "Force ownership override");
     addHiddenOption(updateCommand, "--allow_audit_update", "Alias for --allow-audit-update", false);
     addHiddenOption(updateCommand, "--allow_audit_dep_update", "Alias for --allow-audit-dep-update", false);
-    updateCommand
-        .action(async (id, options, command) => {
-        const globalOptions = getGlobalOptions(command);
-        const startedAt = Date.now();
-        // GH-214: resolve --body-file into the existing body field before
-        // normalization so the rest of update is unchanged. CLI-only input alias.
-        if (typeof options.bodyFile === "string") {
-            options.body = await resolveBodyFileContent(options.bodyFile, options.body !== undefined ? String(options.body) : undefined);
-            delete options.bodyFile;
-        }
-        const { runUpdate } = await import("./commands/update.js");
-        const result = await runUpdate(id, normalizeUpdateOptions(options), globalOptions);
-        await invalidateSearchCachesForMutation(globalOptions, result);
-        printResult(result, globalOptions);
-        if (globalOptions.profile) {
-            printError(`profile:command=update took_ms=${Date.now() - startedAt}`);
-        }
-    });
+    updateCommand.action(runUpdateAction);
     const updateManyCommand = program
         .command("update-many")
         .description("Bulk-update matched items with dry-run plans and rollback checkpoints.")
@@ -676,7 +1299,7 @@ export function registerMutationCommands(program) {
         .option("--force", "Force ownership override");
     // Hidden pure snake_case underscore-duplicate aliases (kept parse-functional,
     // omitted from --help to save agent context).
-    for (const [flags, description] of [
+    addHiddenOptions(updateManyCommand, [
         ["--filter-assignee_filter <value>", "Alias for --filter-assignee-filter"],
         ["--estimated_minutes <value>", "Alias for --estimated-minutes"],
         ["--acceptance_criteria <value>", "Alias for --acceptance-criteria"],
@@ -694,36 +1317,14 @@ export function registerMutationCommands(program) {
         ["--allow_audit_update", "Alias for --allow-audit-update"],
         ["--allow_audit_dep_update", "Alias for --allow-audit-dep-update"],
         ["--filter-estimate-missing", "Alias for --filter-estimates-missing"],
-    ]) {
-        addHiddenOption(updateManyCommand, flags, description, false);
-    }
-    for (const [flags, description] of [
+    ], false);
+    addHiddenOptions(updateManyCommand, [
         ["--dep_remove <value>", "Alias for --dep-remove"],
         ["--type_option <value>", "Alias for --type-option"],
         ["--add_tags <value>", "Alias for --add-tags"],
         ["--remove_tags <value>", "Alias for --remove-tags"],
-    ]) {
-        addHiddenOption(updateManyCommand, flags, description, true);
-    }
-    updateManyCommand
-        .action(async (options, command) => {
-        const globalOptions = getGlobalOptions(command);
-        const startedAt = Date.now();
-        const { runUpdateMany } = await import("./commands/update-many.js");
-        const result = await runUpdateMany({
-            status: typeof options.filterStatus === "string" ? options.filterStatus : undefined,
-            list: buildUpdateManyListOptions(options),
-            update: normalizeUpdateOptions(extractUpdateManyMutationOptionSource(options)),
-            dryRun: options.dryRun === true ? true : undefined,
-            rollback: typeof options.rollback === "string" ? options.rollback : undefined,
-            checkpoint: options.checkpoint === false ? false : undefined,
-        }, globalOptions);
-        await invalidateSearchCachesForMutation(globalOptions, result);
-        printResult(result, globalOptions);
-        if (globalOptions.profile) {
-            printError(`profile:command=update-many took_ms=${Date.now() - startedAt}`);
-        }
-    });
+    ], true);
+    updateManyCommand.action(runUpdateManyAction);
     const closeCommand = program
         .command("close")
         .argument("<id>", "Item id")
@@ -746,43 +1347,7 @@ export function registerMutationCommands(program) {
     // Unknown option error; the rendered help stays clean (aliases hidden).
     addHiddenOption(closeCommand, "--expected_result <value>", "Alias for --expected-result", false);
     addHiddenOption(closeCommand, "--actual_result <value>", "Alias for --actual-result", false);
-    closeCommand
-        .action(async (id, text, options, command) => {
-        const globalOptions = getGlobalOptions(command);
-        const startedAt = Date.now();
-        const { runClose } = await import("./commands/close.js");
-        const reasonFromOption = (typeof options.reason === "string" && options.reason.trim().length > 0 && options.reason) ||
-            (typeof options.closeReason === "string" && options.closeReason.trim().length > 0 && options.closeReason) ||
-            undefined;
-        const resolvedText = typeof text === "string" && text.length > 0 ? text : reasonFromOption;
-        const pickInlineString = (...candidates) => {
-            for (const candidate of candidates) {
-                if (typeof candidate === "string") {
-                    return candidate;
-                }
-            }
-            return undefined;
-        };
-        const result = await runClose(id, resolvedText, {
-            author: typeof options.author === "string" ? options.author : undefined,
-            message: typeof options.message === "string" ? options.message : undefined,
-            validateClose: options.validateClose === true
-                ? "warn"
-                : typeof options.validateClose === "string"
-                    ? options.validateClose
-                    : undefined,
-            force: Boolean(options.force),
-            duplicateOf: typeof options.duplicateOf === "string" ? options.duplicateOf : undefined,
-            resolution: typeof options.resolution === "string" ? options.resolution : undefined,
-            expectedResult: pickInlineString(options.expectedResult, options.expected_result, options.expected),
-            actualResult: pickInlineString(options.actualResult, options.actual_result, options.actual),
-        }, globalOptions);
-        await invalidateSearchCachesForMutation(globalOptions, result);
-        printResult(result, globalOptions);
-        if (globalOptions.profile) {
-            printError(`profile:command=close took_ms=${Date.now() - startedAt}`);
-        }
-    });
+    closeCommand.action(runCloseAction);
     const closeManyCommand = program
         .command("close-many")
         .description("Bulk-close matched items with a shared reason and full runClose semantics (dry-run + rollback checkpoint).")
@@ -822,62 +1387,7 @@ export function registerMutationCommands(program) {
     addHiddenOption(closeManyCommand, "--filter-assignee_filter <value>", "Alias for --filter-assignee-filter", false);
     addHiddenOption(closeManyCommand, "--expected_result <value>", "Alias for --expected-result", false);
     addHiddenOption(closeManyCommand, "--actual_result <value>", "Alias for --actual-result", false);
-    closeManyCommand.action(async (options, command) => {
-        const globalOptions = getGlobalOptions(command);
-        const startedAt = Date.now();
-        const pickString = (...candidates) => {
-            for (const candidate of candidates) {
-                if (typeof candidate === "string") {
-                    return candidate;
-                }
-            }
-            return undefined;
-        };
-        const { runCloseMany } = await import("./commands/close-many.js");
-        const result = await runCloseMany({
-            status: typeof options.filterStatus === "string" ? options.filterStatus : undefined,
-            list: {
-                type: typeof options.filterType === "string" ? options.filterType : undefined,
-                tag: typeof options.filterTag === "string" ? options.filterTag : undefined,
-                priority: typeof options.filterPriority === "string" ? options.filterPriority : undefined,
-                deadlineBefore: typeof options.filterDeadlineBefore === "string" ? options.filterDeadlineBefore : undefined,
-                deadlineAfter: typeof options.filterDeadlineAfter === "string" ? options.filterDeadlineAfter : undefined,
-                updatedAfter: typeof options.filterUpdatedAfter === "string" ? options.filterUpdatedAfter : undefined,
-                updatedBefore: typeof options.filterUpdatedBefore === "string" ? options.filterUpdatedBefore : undefined,
-                createdAfter: typeof options.filterCreatedAfter === "string" ? options.filterCreatedAfter : undefined,
-                createdBefore: typeof options.filterCreatedBefore === "string" ? options.filterCreatedBefore : undefined,
-                ids: typeof options.ids === "string" ? options.ids : undefined,
-                assignee: typeof options.filterAssignee === "string" ? options.filterAssignee : undefined,
-                assigneeFilter: pickString(options.filterAssigneeFilter, options.filterAssignee_filter),
-                parent: typeof options.filterParent === "string" ? options.filterParent : undefined,
-                sprint: typeof options.filterSprint === "string" ? options.filterSprint : undefined,
-                release: typeof options.filterRelease === "string" ? options.filterRelease : undefined,
-                ...mapBulkContentAndGovernanceFilters(options),
-                limit: typeof options.limit === "string" ? options.limit : undefined,
-                offset: typeof options.offset === "string" ? options.offset : undefined,
-            },
-            reason: typeof options.reason === "string" ? options.reason : undefined,
-            resolution: typeof options.resolution === "string" ? options.resolution : undefined,
-            expectedResult: pickString(options.expectedResult, options.expected_result, options.expected),
-            actualResult: pickString(options.actualResult, options.actual_result, options.actual),
-            validateClose: options.validateClose === true
-                ? "warn"
-                : typeof options.validateClose === "string"
-                    ? options.validateClose
-                    : undefined,
-            author: typeof options.author === "string" ? options.author : undefined,
-            message: typeof options.message === "string" ? options.message : undefined,
-            force: Boolean(options.force),
-            dryRun: options.dryRun === true ? true : undefined,
-            rollback: typeof options.rollback === "string" ? options.rollback : undefined,
-            checkpoint: options.checkpoint === false ? false : undefined,
-        }, globalOptions);
-        await invalidateSearchCachesForMutation(globalOptions, result);
-        printResult(result, globalOptions);
-        if (globalOptions.profile) {
-            printError(`profile:command=close-many took_ms=${Date.now() - startedAt}`);
-        }
-    });
+    closeManyCommand.action(runCloseManyAction);
     program
         .command("delete")
         .argument("<id>", "Item id")
@@ -886,24 +1396,7 @@ export function registerMutationCommands(program) {
         .option("--force", "Force ownership override")
         .option("--dry-run", "Preview the item file that would be deleted without mutating")
         .description("Delete an item and record the change in history.")
-        .action(async (id, options, command) => {
-        const globalOptions = getGlobalOptions(command);
-        const startedAt = Date.now();
-        const { runDelete } = await import("./commands/delete.js");
-        const result = await runDelete(id, {
-            author: typeof options.author === "string" ? options.author : undefined,
-            message: typeof options.message === "string" ? options.message : undefined,
-            force: Boolean(options.force),
-            dryRun: options.dryRun === true,
-        }, globalOptions);
-        if (result.dry_run !== true) {
-            await invalidateSearchCachesForMutation(globalOptions, result);
-        }
-        printResult(result, globalOptions);
-        if (globalOptions.profile) {
-            printError(`profile:command=delete took_ms=${Date.now() - startedAt}`);
-        }
-    });
+        .action(runDeleteAction);
     program
         .command("append")
         .argument("<id>", "Item id")
@@ -914,33 +1407,7 @@ export function registerMutationCommands(program) {
         .option("--message <value>", "Mutation message")
         .option("--force", "Force ownership override")
         .description("Append text to an item's body.")
-        .action(async (id, text, options, command) => {
-        const globalOptions = getGlobalOptions(command);
-        const startedAt = Date.now();
-        const bodyFromOption = typeof options.body === "string" ? options.body : undefined;
-        const bodyFromAlias = typeof options.text === "string" ? options.text : undefined;
-        const bodyFromPositional = typeof text === "string" ? text : undefined;
-        const bodySourceCount = [bodyFromOption, bodyFromAlias, bodyFromPositional].filter((value) => value !== undefined).length;
-        if (bodySourceCount > 1) {
-            throw new PmCliError("Specify append text with exactly one source: positional [text], --body, or --text", EXIT_CODE.USAGE);
-        }
-        const resolvedBody = bodyFromOption ?? bodyFromAlias ?? bodyFromPositional;
-        if (resolvedBody === undefined) {
-            throw new PmCliError("Missing append text. Provide it as positional [text], --body <value>, or --text <value> (use - for stdin).", EXIT_CODE.USAGE);
-        }
-        const { runAppend } = await import("./commands/append.js");
-        const result = await runAppend(id, {
-            body: resolvedBody,
-            author: typeof options.author === "string" ? options.author : undefined,
-            message: typeof options.message === "string" ? options.message : undefined,
-            force: Boolean(options.force),
-        }, globalOptions);
-        await invalidateSearchCachesForMutation(globalOptions, result);
-        printResult(result, globalOptions);
-        if (globalOptions.profile) {
-            printError(`profile:command=append took_ms=${Date.now() - startedAt}`);
-        }
-    });
+        .action(runAppendAction);
     program
         .command("restore")
         .argument("<id>", "Item id")
@@ -949,21 +1416,7 @@ export function registerMutationCommands(program) {
         .option("--message <value>", "History message")
         .option("--force", "Force ownership/lock override")
         .description("Restore an item to an earlier timestamp or version.")
-        .action(async (id, target, options, command) => {
-        const globalOptions = getGlobalOptions(command);
-        const startedAt = Date.now();
-        const { runRestore } = await import("./commands/restore.js");
-        const result = await runRestore(id, target, {
-            author: typeof options.author === "string" ? options.author : undefined,
-            message: typeof options.message === "string" ? options.message : undefined,
-            force: Boolean(options.force),
-        }, globalOptions);
-        await invalidateSearchCachesForMutation(globalOptions, result);
-        printResult(result, globalOptions);
-        if (globalOptions.profile) {
-            printError(`profile:command=restore took_ms=${Date.now() - startedAt}`);
-        }
-    });
+        .action(runRestoreAction);
     const planCommand = program
         .command("plan")
         .description("Agent-optimized Plan item workflow: create, manage steps, link dependencies, approve, and materialize.")
@@ -1030,7 +1483,7 @@ export function registerMutationCommands(program) {
         .option("--force", "Force ownership override");
     // Hidden pure snake_case underscore-duplicate aliases (kept parse-functional,
     // omitted from --help to save agent context).
-    for (const [flags, description] of [
+    addHiddenOptions(planCommand, [
         ["--resume_context <value>", "Alias for --resume-context"],
         ["--from_search <value>", "Alias for --from-search"],
         ["--step_title <value>", "Alias for --step-title"],
@@ -1054,104 +1507,12 @@ export function registerMutationCommands(program) {
         ["--materialize_type <value>", "Alias for --materialize-type"],
         ["--materialize_parent <value>", "Alias for --materialize-parent"],
         ["--materialize_tags <value>", "Alias for --materialize-tags"],
-    ]) {
-        addHiddenOption(planCommand, flags, description, false);
-    }
-    for (const [flags, description] of [
+    ], false);
+    addHiddenOptions(planCommand, [
         ["--blocked_by <value>", "Alias for --blocked-by"],
         ["--depends_on <value>", "Alias for --depends-on"],
-    ]) {
-        addHiddenOption(planCommand, flags, description, true);
-    }
-    planCommand
-        .action(async (subcommand, id, stepRef, reorderToken, options, command) => {
-        const globalOptions = getGlobalOptions(command);
-        const startedAt = Date.now();
-        const { runPlan, PLAN_SUBCOMMANDS } = await import("./commands/plan.js");
-        const normalizedSubcommand = (subcommand ?? "").trim().toLowerCase();
-        if (!normalizedSubcommand) {
-            throw new PmCliError(`pm plan requires a subcommand. Allowed: ${PLAN_SUBCOMMANDS.join(", ")}`, EXIT_CODE.USAGE, {
-                code: "missing_required_argument",
-                examples: [
-                    'pm plan create --title "Refactor lock retry"',
-                    "pm plan show pm-a1b2 --depth standard",
-                    'pm plan add-step pm-a1b2 --step-title "Read lock.ts"',
-                ],
-            });
-        }
-        if (!PLAN_SUBCOMMANDS.includes(normalizedSubcommand)) {
-            const didYouMean = normalizedSubcommand === "list" || normalizedSubcommand === "ls"
-                ? ['pm list --type Plan', 'pm list-all --type Plan']
-                : undefined;
-            throw new PmCliError(`Unknown pm plan subcommand "${subcommand}". Allowed: ${PLAN_SUBCOMMANDS.join(", ")}`, EXIT_CODE.USAGE, didYouMean ? { code: "unknown_subcommand", examples: didYouMean } : undefined);
-        }
-        const planOptions = { ...options };
-        // Normalize alternate-snake/camel aliases that Commander parses as different keys.
-        const aliasPairs = [
-            ["blocked_by", "blockedBy"],
-            ["resume_context", "resumeContext"],
-            ["from_search", "fromSearch"],
-            // pm-6mit: "step" is no longer folded into stepTitle here — it is a
-            // first-class repeatable option normalized inside runPlan (create
-            // accumulates ordered steps; other subcommands accept a single value
-            // as a stepTitle alias).
-            ["step_title", "stepTitle"],
-            ["step_body", "stepBody"],
-            ["step_owner", "stepOwner"],
-            ["step_status", "stepStatus"],
-            ["step_evidence", "stepEvidence"],
-            ["step_blocked_reason", "stepBlockedReason"],
-            ["step_replacement", "stepReplacement"],
-            ["depends_on", "dependsOn"],
-            ["link_kind", "linkKind"],
-            ["link_note", "linkNote"],
-            ["promote_to_item_dep", "promoteToItemDep"],
-            ["allow_multiple_active", "allowMultipleActive"],
-            ["decision_text", "decisionText"],
-            ["decision_rationale", "decisionRationale"],
-            ["decision_evidence", "decisionEvidence"],
-            ["discovery_text", "discoveryText"],
-            ["validation_text", "validationText"],
-            ["validation_command", "validationCommand"],
-            ["validation_expected", "validationExpected"],
-            ["materialize_type", "materializeType"],
-            ["materialize_parent", "materializeParent"],
-            ["materialize_tags", "materializeTags"],
-        ];
-        for (const [snake, camel] of aliasPairs) {
-            if (planOptions[snake] !== undefined && planOptions[camel] === undefined) {
-                planOptions[camel] = planOptions[snake];
-            }
-        }
-        let reorderTo;
-        if (normalizedSubcommand === "reorder-step" && typeof reorderToken === "string") {
-            const parsed = Number.parseInt(reorderToken, 10);
-            if (!Number.isFinite(parsed)) {
-                throw new PmCliError(`reorder-step requires an integer new order, got "${reorderToken}"`, EXIT_CODE.USAGE);
-            }
-            reorderTo = parsed;
-        }
-        // Allow positional title for `pm plan create "Title"` (mirrors pm create UX).
-        // Plan create never takes an id positional; the second token is the title.
-        let planId = id;
-        if (normalizedSubcommand === "create" && typeof id === "string" && id.length > 0 && planOptions.title === undefined) {
-            planOptions.title = id;
-            planId = undefined;
-        }
-        const result = await runPlan({
-            subcommand: normalizedSubcommand,
-            id: planId,
-            stepRef,
-            reorderTo,
-            options: planOptions,
-            global: globalOptions,
-        });
-        await invalidateSearchCachesForMutation(globalOptions, result);
-        printResult(result, globalOptions);
-        if (globalOptions.profile) {
-            printError(`profile:command=plan took_ms=${Date.now() - startedAt}`);
-        }
-    });
+    ], true);
+    planCommand.action(runPlanAction);
     void planCommand;
     program
         .command("history-redact")
@@ -1241,65 +1602,7 @@ export function registerMutationCommands(program) {
         .option("--message <value>", "Audit history message for the compaction marker entry")
         .option("--force", "Force ownership/lock override")
         .description("Compact item history streams into a synthetic baseline plus retained tail entries. Pass an item id for one stream, or a bulk selector (--ids/--all-over/--closed/--all-streams) to compact many.")
-        .action(async (id, options, command) => {
-        const globalOptions = getGlobalOptions(command);
-        const startedAt = Date.now();
-        const { runHistoryCompact, runHistoryCompactBulk, assertHistoryCompactTarget } = await import("./commands/history-compact.js");
-        const parseNonNegativeIntFlag = (raw, flag) => {
-            if (typeof raw !== "string") {
-                return undefined;
-            }
-            // Strict: reject "10abc"/"3.5"/"-3" that Number.parseInt would silently truncate.
-            if (!/^\d+$/.test(raw.trim())) {
-                throw new PmCliError(`history-compact ${flag} must be a non-negative integer.`, EXIT_CODE.USAGE);
-            }
-            return Number.parseInt(raw, 10);
-        };
-        const ids = typeof options.ids === "string" ? splitCommaList(options.ids) : undefined;
-        const allOver = parseNonNegativeIntFlag(options.allOver, "--all-over");
-        const minEntries = parseNonNegativeIntFlag(options.minEntries, "--min-entries");
-        if (options.closed === true && options.allStreams === true) {
-            throw new PmCliError("history-compact: --closed and --all-streams are mutually exclusive; pick one lifecycle scope.", EXIT_CODE.USAGE);
-        }
-        const scope = options.closed === true ? "closed" : options.allStreams === true ? "all-streams" : undefined;
-        const isBulk = ids !== undefined || allOver !== undefined || scope !== undefined;
-        if (isBulk && typeof options.before === "string") {
-            throw new PmCliError("history-compact: --before applies only in single-id mode (bulk mode always compacts full streams).", EXIT_CODE.USAGE);
-        }
-        assertHistoryCompactTarget(id, { ids, allOver, scope });
-        if (id === undefined) {
-            const result = await runHistoryCompactBulk({
-                ids,
-                scope,
-                allOver,
-                minEntries,
-                dryRun: options.dryRun === true,
-                author: typeof options.author === "string" ? options.author : undefined,
-                message: typeof options.message === "string" ? options.message : undefined,
-                force: Boolean(options.force),
-            }, globalOptions);
-            printResult(result, globalOptions);
-            if (result.totals.items_errored > 0) {
-                // One failing stream never aborts the pass, but the command must still
-                // fail for gating callers.
-                process.exitCode = EXIT_CODE.GENERIC_FAILURE;
-            }
-        }
-        else {
-            const result = await runHistoryCompact(id, {
-                before: typeof options.before === "string" ? options.before : undefined,
-                dryRun: options.dryRun === true,
-                author: typeof options.author === "string" ? options.author : undefined,
-                message: typeof options.message === "string" ? options.message : undefined,
-                force: Boolean(options.force),
-            }, globalOptions);
-            printResult(result, globalOptions);
-        }
-        // history-compact only rewrites the history stream; item content is untouched.
-        if (globalOptions.profile) {
-            printError(`profile:command=history-compact took_ms=${Date.now() - startedAt}`);
-        }
-    });
+        .action(runHistoryCompactAction);
     const schemaCommand = program
         .command("schema")
         .argument("[subcommand]", "Schema subcommand: list, show, show-status, add-type, remove-type, add-status, remove-status, or a custom item type name shorthand")
@@ -1326,105 +1629,7 @@ export function registerMutationCommands(program) {
     // Hidden pure snake_case underscore-duplicate alias.
     addHiddenOption(schemaCommand, "--default_status <status>", "Alias for --default-status", false);
     schemaCommand
-        .action(async (subcommand, name, options, command) => {
-        const globalOptions = getGlobalOptions(command);
-        const startedAt = Date.now();
-        const schemaModule = await import("./commands/schema.js");
-        const { SCHEMA_SUBCOMMANDS } = schemaModule;
-        let normalizedSubcommand = (subcommand ?? "").trim().toLowerCase();
-        let typeName = name;
-        if (!normalizedSubcommand) {
-            throw new PmCliError(`pm schema requires a subcommand. Allowed: ${SCHEMA_SUBCOMMANDS.join(", ")}`, EXIT_CODE.USAGE, {
-                code: "missing_required_argument",
-                examples: [
-                    "pm schema list",
-                    "pm schema show Task",
-                    "pm schema show-status open",
-                    'pm schema add-type Spike --description "Time-boxed investigation" --default-status open',
-                    "pm schema remove-type Spike",
-                    "pm schema add-status review --role active --alias in_review",
-                    "pm schema remove-status review",
-                    "pm schema add-field severity_level --type string --commands create,update",
-                    "pm schema list-fields",
-                    "pm schema apply-preset agile",
-                    "pm schema add-type --infer --min-count 10",
-                ],
-            });
-        }
-        const aliases = 
-        /* c8 ignore next -- --alias is registered with commander `collect`, so it is always an array here; the string arm is a defensive guard for non-CLI (programmatic) callers */
-        typeof options.alias === "string"
-            ? [options.alias]
-            : Array.isArray(options.alias)
-                ? options.alias
-                : undefined;
-        const roles = 
-        /* c8 ignore next -- --role is registered with commander `collect`, so it is always an array here; the string arm is a defensive guard for non-CLI (programmatic) callers */
-        typeof options.role === "string"
-            ? [options.role]
-            : Array.isArray(options.role)
-                ? options.role
-                : undefined;
-        const defaultStatus = typeof options.defaultStatus === "string"
-            ? options.defaultStatus
-            : typeof options.default_status === "string"
-                ? options.default_status
-                : undefined;
-        const order = parseSchemaOrderOption(options.order);
-        // --commands/--required-types are repeatable Commander `collect` flags, so
-        // their value is always a string[] (or undefined when omitted); each entry
-        // may itself be a comma-list, which we split and flatten here.
-        const splitCollectedCommaList = (raw) => {
-            if (!Array.isArray(raw)) {
-                return undefined;
-            }
-            return raw
-                .flatMap((value) => value.split(","))
-                .map((value) => value.trim())
-                .filter((value) => value.length > 0);
-        };
-        const commands = splitCollectedCommaList(options.commands);
-        const requiredTypes = splitCollectedCommaList(options.requiredTypes);
-        const minCount = parseSchemaOrderOption(options.minCount);
-        if (!SCHEMA_SUBCOMMANDS.includes(normalizedSubcommand) &&
-            typeName === undefined &&
-            !looksLikeSchemaSubcommandTypo(normalizedSubcommand)) {
-            typeName = subcommand;
-            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" });
-        }
-        const author = typeof options.author === "string" ? options.author : undefined;
-        const force = Boolean(options.force);
-        const description = typeof options.description === "string" ? options.description : undefined;
-        const result = await dispatchSchemaSubcommand(schemaModule, {
-            normalizedSubcommand,
-            typeName,
-            options,
-            aliases,
-            roles,
-            commands,
-            requiredTypes,
-            defaultStatus,
-            order,
-            minCount,
-            author,
-            force,
-            description,
-            globalOptions,
-        });
-        // Schema inspection and type registration do not touch item content, so search caches stay valid.
-        if (globalOptions.json === true || globalOptions.defaultOutputFormat === "json") {
-            printResult(result, globalOptions);
-        }
-        else if (!globalOptions.quiet) {
-            renderSchemaResultHuman(schemaModule, result);
-        }
-        if (globalOptions.profile) {
-            printError(`profile:command=schema took_ms=${Date.now() - startedAt}`);
-        }
-    });
+        .action(runSchemaAction);
     const profileCommand = program
         .command("profile")
         .argument("[subcommand]", "Profile subcommand: list, show, apply, or lint")
@@ -1433,39 +1638,7 @@ export function registerMutationCommands(program) {
         .option("--author <value>", "Mutation author")
         .option("--force", "Force ownership/lock override")
         .description("List, show, apply, and lint project profiles — archetype bundles of item types, statuses, fields, workflows, config, templates, and recommended packages.");
-    profileCommand.action(async (subcommand, name, options, command) => {
-        const globalOptions = getGlobalOptions(command);
-        const startedAt = Date.now();
-        const profileModule = await import("./commands/profile.js");
-        const { PROFILE_SUBCOMMANDS } = profileModule;
-        const normalizedSubcommand = (subcommand ?? "").trim().toLowerCase();
-        if (!normalizedSubcommand) {
-            throw new PmCliError(`pm profile requires a subcommand. Allowed: ${PROFILE_SUBCOMMANDS.join(", ")}`, EXIT_CODE.USAGE, {
-                code: "missing_required_argument",
-                examples: ["pm profile list", "pm profile show agile", "pm profile apply agile --dry-run", "pm profile lint agile"],
-            });
-        }
-        if (!PROFILE_SUBCOMMANDS.includes(normalizedSubcommand)) {
-            throw new PmCliError(`Unknown pm profile subcommand "${subcommand}". Allowed: ${PROFILE_SUBCOMMANDS.join(", ")}`, EXIT_CODE.USAGE, { code: "unknown_subcommand" });
-        }
-        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).
-        if (globalOptions.json === true || globalOptions.defaultOutputFormat === "json") {
-            printResult(result, globalOptions);
-        }
-        else if (!globalOptions.quiet) {
-            renderProfileResultHuman(profileModule, result);
-        }
-        // `pm profile lint` is a validation gate: exit non-zero when the profile has
-        // error-severity findings so shell/CI callers can fail on them. Warnings keep
-        // `ok` true and never fail the command.
-        if (result.action === "lint" && !result.ok) {
-            process.exitCode = EXIT_CODE.GENERIC_FAILURE;
-        }
-        if (globalOptions.profile) {
-            printError(`profile:command=profile took_ms=${Date.now() - startedAt}`);
-        }
-    });
+    profileCommand.action(runProfileAction);
     program
         .command("comments")
         .argument("<id>", "Item id")
@@ -1481,48 +1654,7 @@ export function registerMutationCommands(program) {
         .option("--allow-audit-comment", "Allow non-owner append-only comment audits (add/edit/delete) without requiring --force")
         .option("--force", "Force ownership override")
         .description("List, add, edit, or delete comments for an item.")
-        .action(async (id, text, options, command) => {
-        const globalOptions = getGlobalOptions(command);
-        const startedAt = Date.now();
-        const editIndex = typeof options.edit === "number" ? options.edit : undefined;
-        const deleteIndex = typeof options.delete === "number" ? options.delete : undefined;
-        const addFromOption = typeof options.add === "string" ? options.add : undefined;
-        const addFromPositional = typeof text === "string" ? text : undefined;
-        const readFromStdin = options.stdin === true;
-        const readFromFile = typeof options.file === "string" ? options.file : undefined;
-        const sourceCount = Number(addFromOption !== undefined) +
-            Number(addFromPositional !== undefined) +
-            Number(readFromStdin) +
-            Number(readFromFile !== undefined);
-        if (sourceCount > 1) {
-            if (addFromOption !== undefined && addFromPositional !== undefined && !readFromStdin && readFromFile === undefined) {
-                throw new PmCliError("Specify comment text either as positional [text] or with --add, not both", EXIT_CODE.USAGE);
-            }
-            throw new PmCliError("Specify comment text with exactly one source: positional [text], --add, --stdin, or --file", EXIT_CODE.USAGE);
-        }
-        const add = addFromOption ?? addFromPositional;
-        const { runComments } = await import("./commands/comments.js");
-        const result = await runComments(id, {
-            add,
-            stdin: readFromStdin,
-            file: readFromFile,
-            edit: editIndex,
-            delete: deleteIndex,
-            limit: typeof options.limit === "string" ? options.limit : undefined,
-            author: typeof options.author === "string" ? options.author : undefined,
-            message: typeof options.message === "string" ? options.message : undefined,
-            allowAuditComment: Boolean(options.allowAuditComment),
-            force: Boolean(options.force),
-        }, globalOptions);
-        const isMutation = typeof add === "string" || readFromStdin || readFromFile !== undefined || editIndex !== undefined || deleteIndex !== undefined;
-        if (isMutation) {
-            await invalidateSearchCachesForMutation(globalOptions, result);
-        }
-        printResult(result, globalOptions);
-        if (globalOptions.profile) {
-            printError(`profile:command=comments took_ms=${Date.now() - startedAt}`);
-        }
-    });
+        .action(runCommentsAction);
     program
         .command("notes")
         .argument("<id>", "Item id")
@@ -1535,32 +1667,7 @@ export function registerMutationCommands(program) {
         .option("--allow-audit-comment", "Backward-compatible alias for --allow-audit-note")
         .option("--force", "Force ownership override")
         .description("List or add notes for an item.")
-        .action(async (id, text, options, command) => {
-        const globalOptions = getGlobalOptions(command);
-        const startedAt = Date.now();
-        const addFromOption = typeof options.add === "string" ? options.add : undefined;
-        const addFromPositional = typeof text === "string" ? text : undefined;
-        if (addFromOption !== undefined && addFromPositional !== undefined) {
-            throw new PmCliError("Specify note text either as positional [text] or with --add, not both", EXIT_CODE.USAGE);
-        }
-        const add = addFromOption ?? addFromPositional;
-        const { runNotes } = await import("./commands/notes.js");
-        const result = await runNotes(id, {
-            add,
-            limit: typeof options.limit === "string" ? options.limit : undefined,
-            author: typeof options.author === "string" ? options.author : undefined,
-            message: typeof options.message === "string" ? options.message : undefined,
-            allowAuditComment: Boolean(options.allowAuditNote || options.allowAuditComment),
-            force: Boolean(options.force),
-        }, globalOptions);
-        if (typeof add === "string") {
-            await invalidateSearchCachesForMutation(globalOptions, result);
-        }
-        printResult(result, globalOptions);
-        if (globalOptions.profile) {
-            printError(`profile:command=notes took_ms=${Date.now() - startedAt}`);
-        }
-    });
+        .action(runNotesAction);
     program
         .command("learnings")
         .argument("<id>", "Item id")
@@ -1573,32 +1680,7 @@ export function registerMutationCommands(program) {
         .option("--allow-audit-comment", "Backward-compatible alias for --allow-audit-learning")
         .option("--force", "Force ownership override")
         .description("List or add learnings for an item.")
-        .action(async (id, text, options, command) => {
-        const globalOptions = getGlobalOptions(command);
-        const startedAt = Date.now();
-        const addFromOption = typeof options.add === "string" ? options.add : undefined;
-        const addFromPositional = typeof text === "string" ? text : undefined;
-        if (addFromOption !== undefined && addFromPositional !== undefined) {
-            throw new PmCliError("Specify learning text either as positional [text] or with --add, not both", EXIT_CODE.USAGE);
-        }
-        const add = addFromOption ?? addFromPositional;
-        const { runLearnings } = await import("./commands/learnings.js");
-        const result = await runLearnings(id, {
-            add,
-            limit: typeof options.limit === "string" ? options.limit : undefined,
-            author: typeof options.author === "string" ? options.author : undefined,
-            message: typeof options.message === "string" ? options.message : undefined,
-            allowAuditComment: Boolean(options.allowAuditLearning || options.allowAuditComment),
-            force: Boolean(options.force),
-        }, globalOptions);
-        if (typeof add === "string") {
-            await invalidateSearchCachesForMutation(globalOptions, result);
-        }
-        printResult(result, globalOptions);
-        if (globalOptions.profile) {
-            printError(`profile:command=learnings took_ms=${Date.now() - startedAt}`);
-        }
-    });
+        .action(runLearningsAction);
     const filesCommand = program
         .command("files")
         .description("Manage files linked to an item.");
@@ -1616,36 +1698,7 @@ export function registerMutationCommands(program) {
         .option("--author <value>", "Mutation author")
         .option("--message <value>", "History message")
         .option("--force", "Force ownership override")
-        .action(async (id, options, command) => {
-        const globalOptions = getGlobalOptions(command);
-        const startedAt = Date.now();
-        const addValues = Array.isArray(options.add) ? options.add : [];
-        const addGlobValues = Array.isArray(options.addGlob) ? options.addGlob : [];
-        const removeValues = Array.isArray(options.remove) ? options.remove : [];
-        const migrateValues = Array.isArray(options.migrate) ? options.migrate : [];
-        const { runFiles } = await import("./commands/files.js");
-        const result = await runFiles(id, {
-            add: addValues,
-            addGlob: addGlobValues,
-            remove: removeValues,
-            migrate: migrateValues,
-            note: typeof options.note === "string" ? options.note : undefined,
-            list: Boolean(options.list),
-            appendStable: Boolean(options.appendStable),
-            validatePaths: Boolean(options.validatePaths),
-            audit: Boolean(options.audit),
-            author: typeof options.author === "string" ? options.author : undefined,
-            message: typeof options.message === "string" ? options.message : undefined,
-            force: Boolean(options.force),
-        }, globalOptions);
-        if (addValues.length > 0 || addGlobValues.length > 0 || removeValues.length > 0 || migrateValues.length > 0) {
-            await invalidateSearchCachesForMutation(globalOptions, result);
-        }
-        printResult(result, globalOptions);
-        if (globalOptions.profile) {
-            printError(`profile:command=files took_ms=${Date.now() - startedAt}`);
-        }
-    });
+        .action(runFilesAction);
     filesCommand
         .command("discover")
         .argument("<id>", "Item id")
@@ -1656,30 +1709,7 @@ export function registerMutationCommands(program) {
         .option("--message <value>", "History message")
         .option("--force", "Force ownership override")
         .description("Discover existing file paths referenced in item text and optionally link missing files.")
-        .action(async (id, options, command) => {
-        const globalOptions = getGlobalOptions(command);
-        const startedAt = Date.now();
-        // Flags also declared on the parent files command (--note/--append-stable/
-        // --author/--message/--force) are consumed by the parent during parse, so
-        // merge ancestor opts back in (own options win) instead of reading opts() alone.
-        const mergedOptions = { ...command.optsWithGlobals(), ...options };
-        const { runFilesDiscover } = await import("./commands/files.js");
-        const result = await runFilesDiscover(id, {
-            apply: Boolean(mergedOptions.apply),
-            note: typeof mergedOptions.note === "string" ? mergedOptions.note : undefined,
-            appendStable: Boolean(mergedOptions.appendStable),
-            author: typeof mergedOptions.author === "string" ? mergedOptions.author : undefined,
-            message: typeof mergedOptions.message === "string" ? mergedOptions.message : undefined,
-            force: Boolean(mergedOptions.force),
-        }, globalOptions);
-        if (result.changed) {
-            await invalidateSearchCachesForMutation(globalOptions, result);
-        }
-        printResult(result, globalOptions);
-        if (globalOptions.profile) {
-            printError(`profile:command=files.discover took_ms=${Date.now() - startedAt}`);
-        }
-    });
+        .action(runFilesDiscoverAction);
     program
         .command("docs")
         .argument("<id>", "Item id")
@@ -1695,35 +1725,7 @@ export function registerMutationCommands(program) {
         .option("--message <value>", "History message")
         .option("--force", "Force ownership override")
         .description("Manage docs linked to an item.")
-        .action(async (id, options, command) => {
-        const globalOptions = getGlobalOptions(command);
-        const startedAt = Date.now();
-        const addValues = Array.isArray(options.add) ? options.add : [];
-        const addGlobValues = Array.isArray(options.addGlob) ? options.addGlob : [];
-        const removeValues = Array.isArray(options.remove) ? options.remove : [];
-        const migrateValues = Array.isArray(options.migrate) ? options.migrate : [];
-        const { runDocs } = await import("./commands/docs.js");
-        const result = await runDocs(id, {
-            add: addValues,
-            addGlob: addGlobValues,
-            remove: removeValues,
-            migrate: migrateValues,
-            note: typeof options.note === "string" ? options.note : undefined,
-            list: Boolean(options.list),
-            validatePaths: Boolean(options.validatePaths),
-            audit: Boolean(options.audit),
-            author: typeof options.author === "string" ? options.author : undefined,
-            message: typeof options.message === "string" ? options.message : undefined,
-            force: Boolean(options.force),
-        }, globalOptions);
-        if (addValues.length > 0 || addGlobValues.length > 0 || removeValues.length > 0 || migrateValues.length > 0) {
-            await invalidateSearchCachesForMutation(globalOptions, result);
-        }
-        printResult(result, globalOptions);
-        if (globalOptions.profile) {
-            printError(`profile:command=docs took_ms=${Date.now() - startedAt}`);
-        }
-    });
+        .action(runDocsAction);
     program
         .command("deps")
         .argument("<id>", "Item id")
@@ -1732,25 +1734,7 @@ export function registerMutationCommands(program) {
         .option("--collapse <value>", "Collapse mode (none or repeated)", "none")
         .option("--summary", "Return counts only without full tree/graph payload")
         .description("Show dependency relationships for an item.")
-        .action(async (id, options, command) => {
-        const globalOptions = getGlobalOptions(command);
-        const startedAt = Date.now();
-        const { runDeps } = await import("./commands/deps.js");
-        // --format and --collapse carry commander defaults ("tree"/"none"), so
-        // they are always strings by the time the action runs; --maxDepth has no
-        // default and may be unset. Use `as string` rather than String(...) so an
-        // omitted option stays undefined instead of becoming the literal "undefined".
-        const result = await runDeps(id, {
-            format: options.format,
-            maxDepth: typeof options.maxDepth === "string" ? options.maxDepth : undefined,
-            collapse: options.collapse,
-            summary: options.summary === true,
-        }, globalOptions);
-        printResult(result, globalOptions);
-        if (globalOptions.profile) {
-            printError(`profile:command=deps took_ms=${Date.now() - startedAt}`);
-        }
-    });
+        .action(runDepsAction);
 }
 //# sourceMappingURL=register-mutation.js.map
-//# debugId=703247b2-e81d-5a78-999d-6d493a4cf9bf
+//# debugId=506e1f95-1444-5306-9a5e-c1fb3726b2df