@unbrained/pm-cli 2026.5.12 → 2026.5.18

package/dist/cli/register-mutation.js

@@ -1,77 +1,42 @@
-import { runAppend, runClose, runComments, runCommentsAudit, runCreate, runDelete, runDeps, runDocs, runFiles, runFilesDiscover, runLearnings, runNormalize, runNotes, runRestore, runUpdate, runUpdateMany, } from "./commands/index.js";
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="df6717c1-afaf-5933-945b-32b84cacd324")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.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;
+}
+function registerCommanderOptionContracts(command, contracts) {
+    for (const contract of contracts) {
+        if (contract.required) {
+            command.requiredOption(contract.option, contract.description);
+        }
+        else if (contract.repeatable) {
+            command.option(contract.option, contract.description, collect);
+        }
+        else {
+            command.option(contract.option, contract.description);
+        }
+        for (const aliasContract of contract.aliasOptions ?? []) {
+            if (contract.repeatable) {
+                command.option(aliasContract.option, aliasContract.description, collect);
+            }
+            else {
+                command.option(aliasContract.option, aliasContract.description);
+            }
+        }
+    }
+}
 export function registerMutationCommands(program) {
-    program
+    const createCommand = program
         .command("create")
-        .description("Create a new project management item.")
-        .requiredOption("--title, -t <value>", "Item title")
-        .requiredOption("--description, -d <value>", "Item description (allow empty string)")
-        .option("--type <value>", "Item type (built-ins plus any configured custom types)")
-        .option("--template <value>", "Apply named create template defaults before explicit flags")
-        .option("--create-mode <value>", "Create required-option policy mode: strict|progressive")
-        .option("--create_mode <value>", "Alias for --create-mode")
-        .option("--schedule-preset <value>", "Scheduling preset for Reminder|Meeting|Event: lightweight")
-        .option("--schedule_preset <value>", "Alias for --schedule-preset")
-        .option("--status, -s <value>", "Item status")
-        .option("--priority, -p <value>", "Priority 0..4")
-        .option("--tags <value>", "Comma-separated tags")
-        .option("--body, -b <value>", "Item markdown body (allow empty string)")
-        .option("--deadline <value>", "Deadline (ISO/date string or relative +6h/+1d/+2w/+6m)")
-        .option("--estimate, --estimated-minutes <value>", "Estimated minutes")
-        .option("--estimated_minutes <value>", "Alias for --estimated-minutes")
-        .option("--acceptance-criteria <value>", "Acceptance criteria (allow empty string)")
-        .option("--acceptance_criteria <value>", "Alias for --acceptance-criteria")
-        .option("--ac <value>", "Alias for --acceptance-criteria")
-        .option("--definition-of-ready <value>", "Definition of ready (allow empty string)")
-        .option("--definition_of_ready <value>", "Alias for --definition-of-ready")
-        .option("--order <value>", "Planning order/rank integer")
-        .option("--rank <value>", "Alias for --order")
-        .option("--goal <value>", "Goal identifier")
-        .option("--objective <value>", "Objective identifier")
-        .option("--value <value>", "Business value summary")
-        .option("--impact <value>", "Business impact summary")
-        .option("--outcome <value>", "Expected outcome summary")
-        .option("--why-now <value>", "Why-now rationale")
-        .option("--why_now <value>", "Alias for --why-now")
-        .option("--author <value>", "Mutation author")
-        .option("--message <value>", "History message (allow empty string)")
-        .option("--assignee <value>", "Item assignee")
-        .option("--parent <value>", "Parent item ID")
-        .option("--reviewer <value>", "Reviewer")
-        .option("--risk <value>", "Risk level: low|med|medium|high|critical (med persists as medium)")
-        .option("--confidence <value>", "Confidence level: 0..100|low|med|medium|high (med persists as medium)")
-        .option("--sprint <value>", "Sprint identifier")
-        .option("--release <value>", "Release identifier")
-        .option("--blocked-by <value>", "Blocked-by item ID or reason")
-        .option("--blocked_by <value>", "Alias for --blocked-by")
-        .option("--blocked-reason <value>", "Blocked reason")
-        .option("--blocked_reason <value>", "Alias for --blocked-reason")
-        .option("--unblock-note <value>", "Unblock rationale note")
-        .option("--unblock_note <value>", "Alias for --unblock-note")
-        .option("--reporter <value>", "Issue reporter")
-        .option("--severity <value>", "Issue severity: low|med|medium|high|critical (med persists as medium)")
-        .option("--environment <value>", "Issue environment context")
-        .option("--repro-steps <value>", "Issue reproduction steps")
-        .option("--repro_steps <value>", "Alias for --repro-steps")
-        .option("--resolution <value>", "Issue resolution summary")
-        .option("--expected-result <value>", "Issue expected behavior")
-        .option("--expected_result <value>", "Alias for --expected-result")
-        .option("--actual-result <value>", "Issue observed behavior")
-        .option("--actual_result <value>", "Alias for --actual-result")
-        .option("--affected-version <value>", "Affected version identifier")
-        .option("--affected_version <value>", "Alias for --affected-version")
-        .option("--fixed-version <value>", "Fixed version identifier")
-        .option("--fixed_version <value>", "Alias for --fixed-version")
-        .option("--component <value>", "Issue component ownership")
-        .option("--regression <value>", "Regression marker: true|false|1|0")
-        .option("--customer-impact <value>", "Customer impact summary")
-        .option("--customer_impact <value>", "Alias for --customer-impact")
-        .option("--dep <value>", "Seed dependency entry (key=value CSV, markdown key:value lines, or - for stdin; repeatable)", collect)
-        .option("--type-option <value>", "Type option key=value or key=<name>,value=<value> (also accepts key:value and markdown pairs; use - for stdin; repeatable)", collect)
-        .option("--type_option <value>", "Alias for --type-option", collect)
-        .option("--unset <field>", "Clear scalar metadata field by name (repeatable)", collect)
+        .argument("[title]", "Item title (positional shortcut for --title)")
+        .description("Create a new project management item.");
+    registerCommanderOptionContracts(createCommand, CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS);
+    createCommand
         .option("--clear-deps", "Clear dependency entries")
         .option("--clear-comments", "Clear comments")
         .option("--clear-notes", "Clear notes")
@@ -82,18 +47,14 @@ export function registerMutationCommands(program) {
         .option("--clear-reminders", "Clear reminders")
         .option("--clear-events", "Clear events")
         .option("--clear-type-options", "Clear type options")
-        .option("--reminder <value>", "Seed reminder entry at=<iso|relative>,text=<text> (also accepts markdown pairs and - for stdin; repeatable)", collect)
-        .option("--event <value>", "Seed event entry start=<iso|relative>,end=<iso|relative>,title=<text>,all_day=<true|false>,recur_* fields (also accepts markdown pairs and - for stdin; repeatable)", collect)
-        .option("--comment <value>", "Seed comment entry (text=<value> CSV/markdown pairs or - for stdin; repeatable)", collect)
-        .option("--note <value>", "Seed note entry (text=<value> CSV/markdown pairs or - for stdin; repeatable)", collect)
-        .option("--learning <value>", "Seed learning entry (text=<value> CSV/markdown pairs or - for stdin; repeatable)", collect)
-        .option("--file <value>", "Seed linked file entry (CSV/markdown pairs or - for stdin; repeatable)", collect)
-        .option("--test <value>", "Seed linked test entry (CSV/markdown pairs or - for stdin; repeatable)", collect)
-        .option("--doc <value>", "Seed linked doc entry (CSV/markdown pairs or - for stdin; repeatable)", collect)
-        .action(async (options, command) => {
+        .action(async (positionalTitle, options, command) => {
         const globalOptions = getGlobalOptions(command);
         const startedAt = Date.now();
+        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);
         await invalidateSearchCachesForMutation(globalOptions, result);
         printResult(result, globalOptions);
@@ -101,85 +62,14 @@ export function registerMutationCommands(program) {
             printError(`profile:command=create took_ms=${Date.now() - startedAt}`);
         }
     });
-    program
+    const updateCommand = program
         .command("update")
         .argument("<id>", "Item id")
-        .description("Update item fields and metadata.")
-        .option("--title, -t <value>", "Set title")
-        .option("--description, -d <value>", "Set description")
-        .option("--body, -b <value>", "Set body (allow empty string)")
-        .option("--status, -s <value>", "Set status (use close command for closed)")
-        .option("--close-reason <value>", "Set close reason")
-        .option("--close_reason <value>", "Alias for --close-reason")
-        .option("--priority, -p <value>", "Set priority")
-        .option("--type <value>", "Set type")
-        .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")
-        .option("--objective <value>", "Set objective identifier")
-        .option("--value <value>", "Set business value summary")
-        .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("--author <value>", "Mutation author")
-        .option("--message <value>", "Mutation message")
-        .option("--assignee <value>", "Set assignee")
-        .option("--parent <value>", "Set parent item ID")
-        .option("--reviewer <value>", "Set reviewer")
-        .option("--risk <value>", "Set risk level: low|med|medium|high|critical (med persists as medium)")
-        .option("--confidence <value>", "Set confidence level: 0..100|low|med|medium|high (med persists as medium)")
-        .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: low|med|medium|high|critical (med persists as medium)")
-        .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 entries id=<id>,kind=<value>,author=<value>,created_at=<iso|now>,source_kind=<value> (repeatable)", collect)
-        .option("--dep-remove <value>", "Remove dependencies by id or id=<id>,kind=<value>,source_kind=<value> selectors (repeatable)", collect)
-        .option("--dep_remove <value>", "Alias for --dep-remove", collect)
+        .description("Update item fields and metadata.");
+    registerCommanderOptionContracts(updateCommand, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS);
+    updateCommand
         .option("--replace-deps", "Atomically replace dependency entries with the provided --dep values")
         .option("--replace-tests", "Atomically replace linked test entries with the provided --test values")
-        .option("--comment <value>", "Append comment seed author=<value>,created_at=<iso|now>,text=<value> (also accepts markdown pairs and - for stdin; repeatable)", collect)
-        .option("--note <value>", "Append note seed author=<value>,created_at=<iso|now>,text=<value> (also accepts markdown pairs and - for stdin; repeatable)", collect)
-        .option("--learning <value>", "Append learning seed author=<value>,created_at=<iso|now>,text=<value> (also accepts markdown pairs and - for stdin; repeatable)", collect)
-        .option("--file <value>", "Append linked file path=<value>,scope=<project|global>,note=<text> (also accepts markdown pairs and - for stdin; repeatable)", collect)
-        .option("--test <value>", "Append linked test command=<value>,path=<value>,scope=<project|global>,timeout_seconds=<n>,pm_context_mode=<schema|tracker|auto> (also accepts markdown pairs and - for stdin; repeatable)", collect)
-        .option("--doc <value>", "Append linked doc path=<value>,scope=<project|global>,note=<text> (also accepts markdown pairs and - for stdin; repeatable)", collect)
-        .option("--reminder <value>", "Set reminders at=<iso|relative>,text=<text> (also accepts markdown pairs and - for stdin; repeatable)", collect)
-        .option("--event <value>", "Set events start=<iso|relative>,end=<iso|relative>,title=<text>,all_day=<true|false>,recur_* fields (also accepts markdown pairs and - for stdin; repeatable)", collect)
-        .option("--type-option <value>", "Set type options key=value or key=<name>,value=<value> (also accepts key:value and markdown pairs; use - for stdin; 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")
         .option("--clear-notes", "Clear notes")
@@ -198,6 +88,7 @@ export function registerMutationCommands(program) {
         .action(async (id, options, command) => {
         const globalOptions = getGlobalOptions(command);
         const startedAt = Date.now();
+        const { runUpdate } = await loadMutationCommandsModule();
         const result = await runUpdate(id, normalizeUpdateOptions(options), globalOptions);
         await invalidateSearchCachesForMutation(globalOptions, result);
         printResult(result, globalOptions);
@@ -316,6 +207,7 @@ export function registerMutationCommands(program) {
         .action(async (options, command) => {
         const globalOptions = getGlobalOptions(command);
         const startedAt = Date.now();
+        const { runUpdateMany } = await loadMutationCommandsModule();
         const result = await runUpdateMany({
             status: typeof options.filterStatus === "string" ? options.filterStatus : undefined,
             list: {
@@ -348,75 +240,12 @@ export function registerMutationCommands(program) {
             printError(`profile:command=update-many took_ms=${Date.now() - startedAt}`);
         }
     });
-    program
-        .command("normalize")
-        .description("Normalize lifecycle metadata with deterministic dry-run plans and optional apply mode.")
-        .option("--filter-status <value>", "Filter by status before planning or apply")
-        .option("--filter-type <value>", "Filter by item type before planning or apply")
-        .option("--filter-tag <value>", "Filter by tag before planning or apply")
-        .option("--filter-priority <value>", "Filter by priority before planning or apply")
-        .option("--filter-deadline-before <value>", "Filter by deadline upper bound before planning or apply")
-        .option("--filter-deadline-after <value>", "Filter by deadline lower bound before planning or apply")
-        .option("--filter-assignee <value>", "Filter by assignee before planning or apply")
-        .option("--filter-assignee-filter <value>", "Filter assignee presence: assigned|unassigned before planning or apply")
-        .option("--filter-assignee_filter <value>", "Alias for --filter-assignee-filter")
-        .option("--filter-parent <value>", "Filter by parent item ID before planning or apply")
-        .option("--filter-sprint <value>", "Filter by sprint before planning or apply")
-        .option("--filter-release <value>", "Filter by release before planning or apply")
-        .option("--limit <n>", "Limit matched item count before planning/apply")
-        .option("--offset <n>", "Skip first n matched rows before planning/apply")
-        .option("--dry-run", "Preview normalize findings without mutating (default)")
-        .option("--apply", "Apply normalize changes using update semantics")
-        .option("--author <value>", "Mutation author for apply mode")
-        .option("--message <value>", "Mutation message for apply mode")
-        .option("--allow-audit-update", "Allow non-owner metadata-only audit updates without requiring --force")
-        .option("--allow_audit_update", "Alias for --allow-audit-update")
-        .option("--force", "Force ownership override for apply mode")
-        .action(async (options, command) => {
-        const globalOptions = getGlobalOptions(command);
-        const startedAt = Date.now();
-        const result = await runNormalize({
-            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,
-                assignee: typeof options.filterAssignee === "string" ? options.filterAssignee : undefined,
-                assigneeFilter: typeof options.filterAssigneeFilter === "string"
-                    ? options.filterAssigneeFilter
-                    : typeof options.filterAssignee_filter === "string"
-                        ? options.filterAssignee_filter
-                        : undefined,
-                parent: typeof options.filterParent === "string" ? options.filterParent : undefined,
-                sprint: typeof options.filterSprint === "string" ? options.filterSprint : undefined,
-                release: typeof options.filterRelease === "string" ? options.filterRelease : undefined,
-                limit: typeof options.limit === "string" ? options.limit : undefined,
-                offset: typeof options.offset === "string" ? options.offset : undefined,
-                includeBody: true,
-            },
-            dryRun: options.dryRun === true ? true : undefined,
-            apply: options.apply === true ? true : undefined,
-            author: typeof options.author === "string" ? options.author : undefined,
-            message: typeof options.message === "string" ? options.message : undefined,
-            allowAuditUpdate: options.allowAuditUpdate === true || options.allow_audit_update === true || options.allowAudit_update === true
-                ? true
-                : undefined,
-            force: options.force === true ? true : undefined,
-        }, globalOptions);
-        if (result.mode === "apply") {
-            await invalidateSearchCachesForMutation(globalOptions, result);
-        }
-        printResult(result, globalOptions);
-        if (globalOptions.profile) {
-            printError(`profile:command=normalize took_ms=${Date.now() - startedAt}`);
-        }
-    });
     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)')
@@ -425,7 +254,25 @@ export function registerMutationCommands(program) {
         .action(async (id, text, options, command) => {
         const globalOptions = getGlobalOptions(command);
         const startedAt = Date.now();
-        const result = await runClose(id, text, {
+        const { runClose } = await loadMutationCommandsModule();
+        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
@@ -451,6 +298,7 @@ export function registerMutationCommands(program) {
         .action(async (id, options, command) => {
         const globalOptions = getGlobalOptions(command);
         const startedAt = Date.now();
+        const { runDelete } = await loadMutationCommandsModule();
         const result = await runDelete(id, {
             author: typeof options.author === "string" ? options.author : undefined,
             message: typeof options.message === "string" ? options.message : undefined,
@@ -473,6 +321,7 @@ export function registerMutationCommands(program) {
         .action(async (id, options, command) => {
         const globalOptions = getGlobalOptions(command);
         const startedAt = Date.now();
+        const { runAppend } = await loadMutationCommandsModule();
         const result = await runAppend(id, {
             body: typeof options.body === "string" ? options.body : "",
             author: typeof options.author === "string" ? options.author : undefined,
@@ -496,6 +345,7 @@ export function registerMutationCommands(program) {
         .action(async (id, target, options, command) => {
         const globalOptions = getGlobalOptions(command);
         const startedAt = Date.now();
+        const { runRestore } = await loadMutationCommandsModule();
         const result = await runRestore(id, target, {
             author: typeof options.author === "string" ? options.author : undefined,
             message: typeof options.message === "string" ? options.message : undefined,
@@ -507,6 +357,204 @@ 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("--blocked_by <value>", "Alias for --blocked-by", 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("--resume_context <value>", "Alias for --resume-context")
+        .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("--from_search <value>", "Alias for --from-search")
+        .option("--step-title <value>", "Step title for add-step / update-step")
+        .option("--step_title <value>", "Alias for --step-title")
+        .option("--step-body <value>", "Step body text")
+        .option("--step_body <value>", "Alias for --step-body")
+        .option("--step-owner <value>", "Step owner")
+        .option("--step_owner <value>", "Alias for --step-owner")
+        .option("--step-status <value>", "Step status: pending|in_progress|completed|blocked|skipped|superseded")
+        .option("--step_status <value>", "Alias for --step-status")
+        .option("--step-evidence <value>", "Step evidence text (used by update-step/complete-step)")
+        .option("--step_evidence <value>", "Alias for --step-evidence")
+        .option("--step-blocked-reason <value>", "Step blocked reason (required when blocking)")
+        .option("--step_blocked_reason <value>", "Alias for --step-blocked-reason")
+        .option("--step-replacement <value>", "Replacement reference for a superseded step")
+        .option("--step_replacement <value>", "Alias for --step-replacement")
+        .option("--depends-on <value>", "Pm item ids the step depends on (repeatable, csv-friendly)", collect)
+        .option("--depends_on <value>", "Alias for --depends-on", 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_kind <value>", "Alias for --link-kind")
+        .option("--link-note <value>", "Optional note for the link")
+        .option("--link_note <value>", "Alias for --link-note")
+        .option("--promote-to-item-dep", "Also add the linked id as a top-level item dependency when linking")
+        .option("--promote_to_item_dep", "Alias for --promote-to-item-dep")
+        .option("--allow-multiple-active", "Allow multiple steps to be in_progress at once")
+        .option("--allow_multiple_active", "Alias for --allow-multiple-active")
+        .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_text <value>", "Alias for --decision-text")
+        .option("--decision-rationale <value>", "Decision log entry rationale")
+        .option("--decision_rationale <value>", "Alias for --decision-rationale")
+        .option("--decision-evidence <value>", "Decision log entry evidence")
+        .option("--decision_evidence <value>", "Alias for --decision-evidence")
+        .option("--discovery-text <value>", "Discovery log entry text")
+        .option("--discovery_text <value>", "Alias for --discovery-text")
+        .option("--validation-text <value>", "Validation log entry text")
+        .option("--validation_text <value>", "Alias for --validation-text")
+        .option("--validation-command <value>", "Validation log entry command")
+        .option("--validation_command <value>", "Alias for --validation-command")
+        .option("--validation-expected <value>", "Validation log entry expected outcome")
+        .option("--validation_expected <value>", "Alias for --validation-expected")
+        .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_type <value>", "Alias for --materialize-type")
+        .option("--materialize-parent <value>", "Parent item id for materialized children (default: the plan)")
+        .option("--materialize_parent <value>", "Alias for --materialize-parent")
+        .option("--materialize-tags <value>", "Comma-separated tags for materialized children")
+        .option("--materialize_tags <value>", "Alias for --materialize-tags")
+        .option("--author <value>", "Mutation author")
+        .option("--message <value>", "Mutation message")
+        .option("--force", "Force ownership override")
+        .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_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("comments")
         .argument("<id>", "Item id")
@@ -538,6 +586,7 @@ export function registerMutationCommands(program) {
             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 loadMutationCommandsModule();
         const result = await runComments(id, {
             add,
             stdin: readFromStdin,
@@ -556,46 +605,6 @@ export function registerMutationCommands(program) {
             printError(`profile:command=comments took_ms=${Date.now() - startedAt}`);
         }
     });
-    program
-        .command("comments-audit")
-        .option("--status <value>", "Filter by item status")
-        .option("--type <value>", "Filter by item type")
-        .option("--tag <value>", "Filter by tag")
-        .option("--priority <value>", "Filter by priority")
-        .option("--parent <value>", "Filter by parent item ID")
-        .option("--sprint <value>", "Filter by sprint")
-        .option("--release <value>", "Filter by release")
-        .option("--assignee <value>", "Filter by assignee")
-        .option("--assignee-filter <value>", "Filter assignee presence: assigned|unassigned")
-        .option("--assignee_filter <value>", "Alias for --assignee-filter")
-        .option("--limit-items <n>", "Limit returned item count")
-        .option("--limit <n>", "Alias for --limit-items")
-        .option("--full-history", "Export full comment history rows (cannot be combined with --latest)")
-        .option("--latest <n>", "Return latest n comments per item (default: 1, use 0 for summary-only rows)")
-        .description("Audit latest comments or full comment history across filtered items.")
-        .action(async (options, command) => {
-        const globalOptions = getGlobalOptions(command);
-        const startedAt = Date.now();
-        const result = await runCommentsAudit({
-            status: typeof options.status === "string" ? options.status : undefined,
-            type: typeof options.type === "string" ? options.type : undefined,
-            tag: typeof options.tag === "string" ? options.tag : undefined,
-            priority: typeof options.priority === "string" ? options.priority : undefined,
-            parent: typeof options.parent === "string" ? options.parent : undefined,
-            sprint: typeof options.sprint === "string" ? options.sprint : undefined,
-            release: typeof options.release === "string" ? options.release : undefined,
-            assignee: typeof options.assignee === "string" ? options.assignee : undefined,
-            assigneeFilter: typeof options.assigneeFilter === "string" ? options.assigneeFilter : undefined,
-            limit: typeof options.limit === "string" ? options.limit : undefined,
-            limitItems: typeof options.limitItems === "string" ? options.limitItems : undefined,
-            fullHistory: options.fullHistory === true,
-            latest: typeof options.latest === "string" ? options.latest : undefined,
-        }, globalOptions);
-        printResult(result, globalOptions);
-        if (globalOptions.profile) {
-            printError(`profile:command=comments-audit took_ms=${Date.now() - startedAt}`);
-        }
-    });
     program
         .command("notes")
         .argument("<id>", "Item id")
@@ -617,6 +626,7 @@ export function registerMutationCommands(program) {
             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 loadMutationCommandsModule();
         const result = await runNotes(id, {
             add,
             limit: typeof options.limit === "string" ? options.limit : undefined,
@@ -654,6 +664,7 @@ export function registerMutationCommands(program) {
             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 loadMutationCommandsModule();
         const result = await runLearnings(id, {
             add,
             limit: typeof options.limit === "string" ? options.limit : undefined,
@@ -693,6 +704,7 @@ export function registerMutationCommands(program) {
         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 loadMutationCommandsModule();
         const result = await runFiles(id, {
             add: addValues,
             addGlob: addGlobValues,
@@ -727,6 +739,7 @@ export function registerMutationCommands(program) {
         .action(async (id, options, command) => {
         const globalOptions = getGlobalOptions(command);
         const startedAt = Date.now();
+        const { runFilesDiscover } = await loadMutationCommandsModule();
         const result = await runFilesDiscover(id, {
             apply: Boolean(options.apply),
             note: typeof options.note === "string" ? options.note : undefined,
@@ -763,6 +776,7 @@ export function registerMutationCommands(program) {
         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 loadMutationCommandsModule();
         const result = await runDocs(id, {
             add: addValues,
             addGlob: addGlobValues,
@@ -793,6 +807,7 @@ export function registerMutationCommands(program) {
         .action(async (id, options, command) => {
         const globalOptions = getGlobalOptions(command);
         const startedAt = Date.now();
+        const { runDeps } = await loadMutationCommandsModule();
         const result = await runDeps(id, {
             format: typeof options.format === "string" ? options.format : undefined,
             maxDepth: typeof options.maxDepth === "string" ? options.maxDepth : undefined,
@@ -805,4 +820,5 @@ export function registerMutationCommands(program) {
         }
     });
 }
-//# sourceMappingURL=register-mutation.js.map
+//# sourceMappingURL=register-mutation.js.map
+//# debugId=df6717c1-afaf-5933-945b-32b84cacd324