@unbrained/pm-cli 2026.5.14 → 2026.5.24

package/dist/cli/register-mutation.js

@@ -1,11 +1,26 @@
+
+!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]="634fa316-811c-5a12-a391-225313b2c754")}catch(e){}}();
+import { Option } from "commander";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
+import { isPureSnakeCaseAlias } from "../core/shared/option-alias-visibility.js";
 import { CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, } from "../sdk/cli-contracts.js";
-import { collect, extractUpdateManyMutationOptionSource, getGlobalOptions, invalidateSearchCachesForMutation, normalizeCreateOptions, normalizeUpdateOptions, printError, printResult, } from "./registration-helpers.js";
-let mutationCommandsModulePromise = null;
-async function loadMutationCommandsModule() {
-    mutationCommandsModulePromise ??= import("./commands/index.js");
-    return mutationCommandsModulePromise;
+import { collect, extractUpdateManyMutationOptionSource, formatHookWarnings, getGlobalOptions, invalidateSearchCachesForMutation, normalizeCreateOptions, normalizeUpdateOptions, printError, printResult, writeStdout, } from "./registration-helpers.js";
+import { createLazyModule } from "../core/shared/lazy-module.js";
+const loadMutationCommandsModule = createLazyModule(() => import("./commands/index.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
+ * `command.options`, so the JSON help payload and shell completion (which read
+ * from the contracts/commander option list, not the rendered text) are
+ * unchanged — only commander's text `--help` omits it.
+ */
+function addHiddenOption(command, flags, description, repeatable) {
+    const option = new Option(flags, description).hideHelp();
+    if (repeatable) {
+        option.argParser(collect);
+    }
+    command.addOption(option);
 }
 function registerCommanderOptionContracts(command, contracts) {
     for (const contract of contracts) {
@@ -19,7 +34,13 @@ function registerCommanderOptionContracts(command, contracts) {
             command.option(contract.option, contract.description);
         }
         for (const aliasContract of contract.aliasOptions ?? []) {
-            if (contract.repeatable) {
+            // Hide pure snake_case underscore-duplicate aliases (e.g. --create_mode
+            // for --create-mode) from --help, but keep semantically-distinct aliases
+            // (e.g. --ac for --acceptance-criteria) visible.
+            if (isPureSnakeCaseAlias(contract.option, aliasContract.option)) {
+                addHiddenOption(command, aliasContract.option, aliasContract.description, contract.repeatable === true);
+            }
+            else if (contract.repeatable) {
                 command.option(aliasContract.option, aliasContract.description, collect);
             }
             else {
@@ -31,6 +52,8 @@ function registerCommanderOptionContracts(command, contracts) {
 export function registerMutationCommands(program) {
     const createCommand = program
         .command("create")
+        .argument("[typeOrTitle]", "Item title, or item type when a title follows (e.g. `pm create task \"Fix bug\"`)")
+        .argument("[title]", "Item title when the first argument is an item type")
         .description("Create a new project management item.");
     registerCommanderOptionContracts(createCommand, CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS);
     createCommand
@@ -44,9 +67,27 @@ export function registerMutationCommands(program) {
         .option("--clear-reminders", "Clear reminders")
         .option("--clear-events", "Clear events")
         .option("--clear-type-options", "Clear type options")
-        .action(async (options, command) => {
+        .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) {
+            positionalTitle = typeOrTitle;
+        }
+        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;
+        }
         const normalized = normalizeCreateOptions(options, { requireType: false });
         const { runCreate } = await loadMutationCommandsModule();
         const result = await runCreate(normalized, globalOptions);
@@ -75,10 +116,11 @@ export function registerMutationCommands(program) {
         .option("--clear-events", "Clear events")
         .option("--clear-type-options", "Clear type options")
         .option("--allow-audit-update", "Allow non-owner metadata-only audit updates without requiring --force")
-        .option("--allow_audit_update", "Alias for --allow-audit-update")
         .option("--allow-audit-dep-update", "Allow non-owner append-only dependency updates without requiring --force")
-        .option("--allow_audit_dep_update", "Alias for --allow-audit-dep-update")
-        .option("--force", "Force ownership override")
+        .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();
@@ -90,7 +132,7 @@ export function registerMutationCommands(program) {
             printError(`profile:command=update took_ms=${Date.now() - startedAt}`);
         }
     });
-    program
+    const updateManyCommand = program
         .command("update-many")
         .description("Bulk-update matched items with dry-run plans and rollback checkpoints.")
         .option("--filter-status <value>", "Filter by status before applying updates")
@@ -101,7 +143,6 @@ export function registerMutationCommands(program) {
         .option("--filter-deadline-after <value>", "Filter by deadline lower bound before applying updates")
         .option("--filter-assignee <value>", "Filter by assignee before applying updates")
         .option("--filter-assignee-filter <value>", "Filter assignee presence: assigned|unassigned before applying updates")
-        .option("--filter-assignee_filter <value>", "Alias for --filter-assignee-filter")
         .option("--filter-parent <value>", "Filter by parent item ID before applying updates")
         .option("--filter-sprint <value>", "Filter by sprint before applying updates")
         .option("--filter-release <value>", "Filter by release before applying updates")
@@ -119,12 +160,9 @@ export function registerMutationCommands(program) {
         .option("--tags <value>", "Set comma-separated tags")
         .option("--deadline <value>", "Set deadline (ISO/date string or relative)")
         .option("--estimate, --estimated-minutes <value>", "Set estimated minutes")
-        .option("--estimated_minutes <value>", "Alias for --estimated-minutes")
         .option("--acceptance-criteria <value>", "Set acceptance criteria")
-        .option("--acceptance_criteria <value>", "Alias for --acceptance-criteria")
         .option("--ac <value>", "Alias for --acceptance-criteria")
         .option("--definition-of-ready <value>", "Set definition of ready")
-        .option("--definition_of_ready <value>", "Alias for --definition-of-ready")
         .option("--order <value>", "Set planning order/rank integer")
         .option("--rank <value>", "Alias for --order")
         .option("--goal <value>", "Set goal identifier")
@@ -133,7 +171,6 @@ export function registerMutationCommands(program) {
         .option("--impact <value>", "Set business impact summary")
         .option("--outcome <value>", "Set expected outcome summary")
         .option("--why-now <value>", "Set why-now rationale")
-        .option("--why_now <value>", "Alias for --why-now")
         .option("--assignee <value>", "Set assignee")
         .option("--parent <value>", "Set parent item ID")
         .option("--reviewer <value>", "Set reviewer")
@@ -142,32 +179,22 @@ export function registerMutationCommands(program) {
         .option("--sprint <value>", "Set sprint identifier")
         .option("--release <value>", "Set release identifier")
         .option("--blocked-by <value>", "Set blocked-by item ID or reason")
-        .option("--blocked_by <value>", "Alias for --blocked-by")
         .option("--blocked-reason <value>", "Set blocked reason")
-        .option("--blocked_reason <value>", "Alias for --blocked-reason")
         .option("--unblock-note <value>", "Set unblock rationale note")
-        .option("--unblock_note <value>", "Alias for --unblock-note")
         .option("--reporter <value>", "Set issue reporter")
         .option("--severity <value>", "Set issue severity")
         .option("--environment <value>", "Set issue environment context")
         .option("--repro-steps <value>", "Set issue reproduction steps")
-        .option("--repro_steps <value>", "Alias for --repro-steps")
         .option("--resolution <value>", "Set issue resolution summary")
         .option("--expected-result <value>", "Set issue expected behavior")
-        .option("--expected_result <value>", "Alias for --expected-result")
         .option("--actual-result <value>", "Set issue observed behavior")
-        .option("--actual_result <value>", "Alias for --actual-result")
         .option("--affected-version <value>", "Set affected version identifier")
-        .option("--affected_version <value>", "Alias for --affected-version")
         .option("--fixed-version <value>", "Set fixed version identifier")
-        .option("--fixed_version <value>", "Alias for --fixed-version")
         .option("--component <value>", "Set issue component ownership")
         .option("--regression <value>", "Set regression marker: true|false|1|0")
         .option("--customer-impact <value>", "Set customer impact summary")
-        .option("--customer_impact <value>", "Alias for --customer-impact")
         .option("--dep <value>", "Add dependency entry id=<id>,kind=<kind>,author=<author>,created_at=<timestamp>", collect)
         .option("--dep-remove <value>", "Remove dependency entries by id/kind/author/timestamp signature", collect)
-        .option("--dep_remove <value>", "Alias for --dep-remove", collect)
         .option("--replace-deps", "Atomically replace dependency entries with provided --dep values")
         .option("--replace-tests", "Atomically replace linked tests with provided --test values")
         .option("--comment <value>", "Add comment seed author=<value>,created_at=<iso|now>,text=<value>", collect)
@@ -176,10 +203,9 @@ export function registerMutationCommands(program) {
         .option("--file <value>", "Add linked file path=<value>,scope=<project|global>,note=<text>", collect)
         .option("--test <value>", "Add linked test command=<value>,path=<value>,scope=<project|global>", collect)
         .option("--doc <value>", "Add linked doc path=<value>,scope=<project|global>,note=<text>", collect)
-        .option("--reminder <value>", "Add reminder entry at=<iso|relative>,text=<text>", collect)
+        .option("--reminder <value>", "Add reminder entry at=<iso|relative>|date=<iso|relative>,text=<text>|title=<text>", collect)
         .option("--event <value>", "Add event entry start=<iso|relative>,end=<iso|relative>,recur_*", collect)
         .option("--type-option <value>", "Set type options key=value (repeatable)", collect)
-        .option("--type_option <value>", "Alias for --type-option", collect)
         .option("--unset <field>", "Clear scalar metadata field by name (repeatable)", collect)
         .option("--clear-deps", "Clear dependency entries")
         .option("--clear-comments", "Clear comments")
@@ -192,12 +218,39 @@ export function registerMutationCommands(program) {
         .option("--clear-events", "Clear events")
         .option("--clear-type-options", "Clear type options")
         .option("--allow-audit-update", "Allow non-owner metadata-only audit updates without requiring --force")
-        .option("--allow_audit_update", "Alias for --allow-audit-update")
         .option("--allow-audit-dep-update", "Allow non-owner append-only dependency updates without requiring --force")
-        .option("--allow_audit_dep_update", "Alias for --allow-audit-dep-update")
         .option("--author <value>", "Mutation author")
         .option("--message <value>", "Mutation message")
-        .option("--force", "Force ownership override")
+        .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 [
+        ["--filter-assignee_filter <value>", "Alias for --filter-assignee-filter"],
+        ["--estimated_minutes <value>", "Alias for --estimated-minutes"],
+        ["--acceptance_criteria <value>", "Alias for --acceptance-criteria"],
+        ["--definition_of_ready <value>", "Alias for --definition-of-ready"],
+        ["--why_now <value>", "Alias for --why-now"],
+        ["--blocked_by <value>", "Alias for --blocked-by"],
+        ["--blocked_reason <value>", "Alias for --blocked-reason"],
+        ["--unblock_note <value>", "Alias for --unblock-note"],
+        ["--repro_steps <value>", "Alias for --repro-steps"],
+        ["--expected_result <value>", "Alias for --expected-result"],
+        ["--actual_result <value>", "Alias for --actual-result"],
+        ["--affected_version <value>", "Alias for --affected-version"],
+        ["--fixed_version <value>", "Alias for --fixed-version"],
+        ["--customer_impact <value>", "Alias for --customer-impact"],
+        ["--allow_audit_update", "Alias for --allow-audit-update"],
+        ["--allow_audit_dep_update", "Alias for --allow-audit-dep-update"],
+    ]) {
+        addHiddenOption(updateManyCommand, flags, description, false);
+    }
+    for (const [flags, description] of [
+        ["--dep_remove <value>", "Alias for --dep-remove"],
+        ["--type_option <value>", "Alias for --type-option"],
+    ]) {
+        addHiddenOption(updateManyCommand, flags, description, true);
+    }
+    updateManyCommand
         .action(async (options, command) => {
         const globalOptions = getGlobalOptions(command);
         const startedAt = Date.now();
@@ -237,7 +290,9 @@ export function registerMutationCommands(program) {
     program
         .command("close")
         .argument("<id>", "Item id")
-        .argument("<text>", "Close reason text")
+        .argument("[text]", "Close reason text (alias: --reason)")
+        .option("--reason <value>", "Close reason text (alias for positional <text>)")
+        .option("--close-reason <value>", "Close reason text (alias for positional <text>)")
         .option("--author <value>", "Mutation author")
         .option("--message <value>", "History message")
         .option("--validate-close [mode]", 'Validate closure metadata before close: "off", "warn", or "strict" (default: settings governance preset)')
@@ -247,7 +302,24 @@ export function registerMutationCommands(program) {
         const globalOptions = getGlobalOptions(command);
         const startedAt = Date.now();
         const { runClose } = await loadMutationCommandsModule();
-        const result = await runClose(id, text, {
+        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;
+        if (typeof resolvedText !== "string" || resolvedText.length === 0) {
+            throw new PmCliError("pm close requires a close reason as the second positional argument or via --reason.", EXIT_CODE.USAGE, {
+                code: "missing_required_argument",
+                why: "Close mutations are auditable; a reason is mandatory for the history record.",
+                examples: [
+                    `pm close ${id} "All acceptance criteria met"`,
+                    `pm close ${id} --reason "Verified by integration test"`,
+                ],
+                nextSteps: [
+                    "Re-run with the close reason as the second positional argument, or pass --reason \"<text>\".",
+                ],
+            });
+        }
+        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
@@ -269,6 +341,7 @@ export function registerMutationCommands(program) {
         .option("--author <value>", "Mutation author")
         .option("--message <value>", "History message")
         .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);
@@ -278,8 +351,11 @@ export function registerMutationCommands(program) {
             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);
-        await invalidateSearchCachesForMutation(globalOptions, result);
+        if (result.dry_run !== true) {
+            await invalidateSearchCachesForMutation(globalOptions, result);
+        }
         printResult(result, globalOptions);
         if (globalOptions.profile) {
             printError(`profile:command=delete took_ms=${Date.now() - startedAt}`);
@@ -288,17 +364,30 @@ export function registerMutationCommands(program) {
     program
         .command("append")
         .argument("<id>", "Item id")
-        .requiredOption("--body <value>", "Text to append to body (or - for stdin)")
+        .argument("[text]", "Optional body text shorthand (equivalent to --body; use - for stdin)")
+        .option("--body <value>", "Text to append to body (or - for stdin)")
+        .option("--text <value>", "Alias for --body")
         .option("--author <value>", "Mutation author")
         .option("--message <value>", "Mutation message")
         .option("--force", "Force ownership override")
         .description("Append text to an item's body.")
-        .action(async (id, options, command) => {
+        .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 loadMutationCommandsModule();
         const result = await runAppend(id, {
-            body: typeof options.body === "string" ? options.body : "",
+            body: resolvedBody,
             author: typeof options.author === "string" ? options.author : undefined,
             message: typeof options.message === "string" ? options.message : undefined,
             force: Boolean(options.force),
@@ -332,6 +421,306 @@ export function registerMutationCommands(program) {
             printError(`profile:command=restore took_ms=${Date.now() - startedAt}`);
         }
     });
+    const planCommand = program
+        .command("plan")
+        .description("Agent-optimized Plan item workflow: create, manage steps, link dependencies, approve, and materialize.")
+        .argument("[subcommand]", "Plan subcommand: create|show|add-step|update-step|complete-step|block-step|reorder-step|remove-step|link|unlink|decision|discovery|validation|resume|approve|materialize")
+        .argument("[id]", "Plan id (required for non-create subcommands); for create this may be the positional title")
+        .argument("[stepRef]", "Step reference: stable id (plan-step-001) or order integer")
+        .argument("[reorderTo]", "New order integer for reorder-step")
+        .option("--title <value>", "Plan title")
+        .option("--description <value>", "Plan description")
+        .option("--scope <value>", "Short scope statement of the target change or investigation")
+        .option("--parent <value>", "Parent pm item id")
+        .option("--related <value>", "Related pm item ids (repeatable, csv-friendly)", collect)
+        .option("--blocks <value>", "Pm item ids this plan blocks (repeatable, csv-friendly)", collect)
+        .option("--blocked-by <value>", "Pm item ids that block this plan (repeatable, csv-friendly)", collect)
+        .option("--harness <value>", "Plan harness provenance: codex|claude-code|cursor|generic")
+        .option("--mode <value>", "Plan mode: draft|research|review|approved|executing|paused|completed|superseded")
+        .option("--resume-context <value>", "Compact context summary for a future stateless agent")
+        .option("--tags <value>", "Comma-separated tags")
+        .option("--priority <value>", "Priority 0-4")
+        .option("--body <value>", "Plan item body")
+        .option("--claim", "Claim the plan on create for the author")
+        .option("--from-search <value>", "Record the search query that led to plan creation")
+        .option("--step-title <value>", "Step title for add-step / update-step")
+        .option("--step <value>", "Alias for --step-title")
+        .option("--step-body <value>", "Step body text")
+        .option("--step-owner <value>", "Step owner")
+        .option("--step-status <value>", "Step status: pending|in_progress|completed|blocked|skipped|superseded")
+        .option("--step-evidence <value>", "Step evidence text (used by update-step/complete-step)")
+        .option("--step-blocked-reason <value>", "Step blocked reason (required when blocking)")
+        .option("--step-replacement <value>", "Replacement reference for a superseded step")
+        .option("--depends-on <value>", "Pm item ids the step depends on (repeatable, csv-friendly)", collect)
+        .option("--link <value>", "Pm item id to link (repeatable, csv-friendly)", collect)
+        .option("--link-kind <value>", "Link kind: related|blocks|blocked_by|depends_on|discovered_from|implements|verifies|supersedes")
+        .option("--link-note <value>", "Optional note for the link")
+        .option("--promote-to-item-dep", "Also add the linked id as a top-level item dependency when linking")
+        .option("--allow-multiple-active", "Allow multiple steps to be in_progress at once")
+        .option("--file <value>", "Step linked file path=<value>[,scope=project|global,note=<text>] (repeatable)", collect)
+        .option("--test <value>", "Step linked test command=<value>[,path=<value>,note=<text>] (repeatable)", collect)
+        .option("--doc <value>", "Step linked doc path=<value>[,scope=project|global,note=<text>] (repeatable)", collect)
+        .option("--decision-text <value>", "Decision log entry text")
+        .option("--decision <value>", "Alias for --decision-text")
+        .option("--decision-rationale <value>", "Decision log entry rationale")
+        .option("--decision-evidence <value>", "Decision log entry evidence")
+        .option("--discovery-text <value>", "Discovery log entry text")
+        .option("--discovery <value>", "Alias for --discovery-text")
+        .option("--validation-text <value>", "Validation log entry text")
+        .option("--validation <value>", "Alias for --validation-text")
+        .option("--validation-command <value>", "Validation log entry command")
+        .option("--validation-expected <value>", "Validation log entry expected outcome")
+        .option("--depth <value>", "Show depth: brief|standard|deep (default: brief)")
+        .option("--fields <value>", "Comma-separated field projection for show output")
+        .option("--steps <value>", "Comma-separated step ids/orders for materialize")
+        .option("--materialize-type <value>", "Item type for materialized steps (default: Task)")
+        .option("--materialize-parent <value>", "Parent item id for materialized children (default: the plan)")
+        .option("--materialize-tags <value>", "Comma-separated tags for materialized children")
+        .option("--author <value>", "Mutation author")
+        .option("--message <value>", "Mutation message")
+        .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 [
+        ["--resume_context <value>", "Alias for --resume-context"],
+        ["--from_search <value>", "Alias for --from-search"],
+        ["--step_title <value>", "Alias for --step-title"],
+        ["--step_body <value>", "Alias for --step-body"],
+        ["--step_owner <value>", "Alias for --step-owner"],
+        ["--step_status <value>", "Alias for --step-status"],
+        ["--step_evidence <value>", "Alias for --step-evidence"],
+        ["--step_blocked_reason <value>", "Alias for --step-blocked-reason"],
+        ["--step_replacement <value>", "Alias for --step-replacement"],
+        ["--link_kind <value>", "Alias for --link-kind"],
+        ["--link_note <value>", "Alias for --link-note"],
+        ["--promote_to_item_dep", "Alias for --promote-to-item-dep"],
+        ["--allow_multiple_active", "Alias for --allow-multiple-active"],
+        ["--decision_text <value>", "Alias for --decision-text"],
+        ["--decision_rationale <value>", "Alias for --decision-rationale"],
+        ["--decision_evidence <value>", "Alias for --decision-evidence"],
+        ["--discovery_text <value>", "Alias for --discovery-text"],
+        ["--validation_text <value>", "Alias for --validation-text"],
+        ["--validation_command <value>", "Alias for --validation-command"],
+        ["--validation_expected <value>", "Alias for --validation-expected"],
+        ["--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 [
+        ["--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 loadMutationCommandsModule();
+        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"],
+            ["step", "stepTitle"],
+            ["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}`);
+        }
+    });
+    void planCommand;
+    program
+        .command("history-redact")
+        .argument("<id>", "Item id")
+        .option("--literal <value>", "Literal string to redact (repeatable)", collect)
+        .option("--regex <value>", "Regex pattern to redact (repeatable; accepts /pattern/flags or raw pattern)", collect)
+        .option("--replacement <value>", 'Replacement string (default: "[redacted]")')
+        .option("--dry-run", "Preview redaction impact without writing item/history files")
+        .option("--author <value>", "Mutation author")
+        .option("--message <value>", "Audit history message for the redaction marker entry")
+        .option("--force", "Force ownership/lock override")
+        .description("Redact sensitive literals/patterns from an item history stream and recompute hashes.")
+        .action(async (id, options, command) => {
+        const globalOptions = getGlobalOptions(command);
+        const startedAt = Date.now();
+        const { runHistoryRedact } = await loadMutationCommandsModule();
+        const literal = Array.isArray(options.literal) ? options.literal : undefined;
+        const regex = Array.isArray(options.regex) ? options.regex : undefined;
+        const result = await runHistoryRedact(id, {
+            literal,
+            regex,
+            replacement: typeof options.replacement === "string" ? options.replacement : 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);
+        if (result.changed && !result.dry_run) {
+            await invalidateSearchCachesForMutation(globalOptions, result);
+        }
+        printResult(result, globalOptions);
+        if (globalOptions.profile) {
+            printError(`profile:command=history-redact took_ms=${Date.now() - startedAt}`);
+        }
+    });
+    program
+        .command("history-repair")
+        .argument("<id>", "Item id")
+        .option("--dry-run", "Preview the re-anchor impact without writing the history file")
+        .option("--author <value>", "Mutation author")
+        .option("--message <value>", "Audit history message for the repair marker entry")
+        .option("--force", "Force ownership/lock override")
+        .description("Re-anchor a drifted item history chain (recompute hashes, reconcile with the on-disk item) and record an audit marker.")
+        .action(async (id, options, command) => {
+        const globalOptions = getGlobalOptions(command);
+        const startedAt = Date.now();
+        const { runHistoryRepair } = await loadMutationCommandsModule();
+        const result = await runHistoryRepair(id, {
+            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);
+        // history-repair only re-anchors the audit stream; item content is untouched,
+        // so search caches do not need invalidation.
+        printResult(result, globalOptions);
+        if (globalOptions.profile) {
+            printError(`profile:command=history-repair took_ms=${Date.now() - startedAt}`);
+        }
+    });
+    const schemaCommand = program
+        .command("schema")
+        .argument("[subcommand]", "Schema subcommand: add-type")
+        .argument("[name]", "Custom item type name (for add-type)")
+        .option("--description <text>", "Human description for the custom item type")
+        .option("--default-status <status>", "Default status hint recorded for the custom item type")
+        .option("--folder <dir>", "Storage folder for items of this custom type")
+        .option("--alias <name>", "Alias for the custom type (repeatable, csv-friendly)", collect)
+        .option("--author <value>", "Mutation author")
+        .option("--force", "Force ownership/lock override")
+        .description("Manage config-driven runtime schema: register custom item types into .agents/pm/schema/types.json.");
+    // 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 { runSchemaAddType, formatSchemaAddTypeHuman, SCHEMA_SUBCOMMANDS } = await loadMutationCommandsModule();
+        const normalizedSubcommand = (subcommand ?? "").trim().toLowerCase();
+        if (!normalizedSubcommand) {
+            throw new PmCliError(`pm schema requires a subcommand. Allowed: ${SCHEMA_SUBCOMMANDS.join(", ")}`, EXIT_CODE.USAGE, {
+                code: "missing_required_argument",
+                examples: [
+                    'pm schema add-type Spike --description "Time-boxed investigation" --default-status open',
+                    'pm schema add-type Spike --alias spike --alias research',
+                ],
+            });
+        }
+        if (!SCHEMA_SUBCOMMANDS.includes(normalizedSubcommand)) {
+            throw new PmCliError(`Unknown pm schema subcommand "${subcommand}". Allowed: ${SCHEMA_SUBCOMMANDS.join(", ")}`, EXIT_CODE.USAGE, { code: "unknown_subcommand" });
+        }
+        const aliases = Array.isArray(options.alias) ? options.alias : undefined;
+        const defaultStatus = typeof options.defaultStatus === "string"
+            ? options.defaultStatus
+            : typeof options.default_status === "string"
+                ? options.default_status
+                : undefined;
+        const result = await runSchemaAddType(name, {
+            description: typeof options.description === "string" ? options.description : undefined,
+            defaultStatus,
+            folder: typeof options.folder === "string" ? options.folder : undefined,
+            alias: aliases,
+            author: typeof options.author === "string" ? options.author : undefined,
+            force: Boolean(options.force),
+        }, globalOptions);
+        // Registering a type does not touch item content, so search caches stay valid.
+        if (globalOptions.json === true || globalOptions.defaultOutputFormat === "json") {
+            printResult(result, globalOptions);
+        }
+        else if (!globalOptions.quiet) {
+            writeStdout(`${formatSchemaAddTypeHuman(result)}\n`);
+            // Surface extension on-write hook diagnostics so policy/enforcement
+            // warnings are visible without forcing --json.
+            if (result.warnings.length > 0) {
+                printError(`schema add-type warnings: ${formatHookWarnings(result.warnings)}`);
+            }
+        }
+        if (globalOptions.profile) {
+            printError(`profile:command=schema took_ms=${Date.now() - startedAt}`);
+        }
+    });
     program
         .command("comments")
         .argument("<id>", "Item id")
@@ -540,6 +929,7 @@ export function registerMutationCommands(program) {
         .option("--add-glob <value>", "Add linked doc entries from a glob (plain glob or pattern=<glob>,scope=<scope>,note=<text>; repeatable)", collect)
         .option("--remove <value>", "Remove linked doc by path (path=<value>, path:<value>, plain path, or - for stdin)", collect)
         .option("--migrate <value>", "Migrate linked doc paths in-place (from=<prefix>,to=<prefix>; repeatable)", collect)
+        .option("--list", "List linked docs without mutating")
         .option("--validate-paths", "Validate linked doc paths for existence and file shape")
         .option("--audit", "Audit linked doc usage across all items for this item's linked paths")
         .option("--author <value>", "Mutation author")
@@ -559,6 +949,7 @@ export function registerMutationCommands(program) {
             addGlob: addGlobValues,
             remove: removeValues,
             migrate: migrateValues,
+            list: Boolean(options.list),
             validatePaths: Boolean(options.validatePaths),
             audit: Boolean(options.audit),
             author: typeof options.author === "string" ? options.author : undefined,
@@ -597,4 +988,5 @@ export function registerMutationCommands(program) {
         }
     });
 }
-//# sourceMappingURL=register-mutation.js.map
+//# sourceMappingURL=register-mutation.js.map
+//# debugId=634fa316-811c-5a12-a391-225313b2c754