@unbrained/pm-cli 2026.5.18 → 2026.5.24

package/dist/cli/register-mutation.js

@@ -1,13 +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]="df6717c1-afaf-5933-945b-32b84cacd324")}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]="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) {
@@ -21,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 {
@@ -33,7 +52,8 @@ function registerCommanderOptionContracts(command, contracts) {
 export function registerMutationCommands(program) {
     const createCommand = program
         .command("create")
-        .argument("[title]", "Item title (positional shortcut for --title)")
+        .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
@@ -47,9 +67,24 @@ export function registerMutationCommands(program) {
         .option("--clear-reminders", "Clear reminders")
         .option("--clear-events", "Clear events")
         .option("--clear-type-options", "Clear type options")
-        .action(async (positionalTitle, 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;
         }
@@ -81,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();
@@ -96,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")
@@ -107,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")
@@ -125,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")
@@ -139,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")
@@ -148,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)
@@ -182,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")
@@ -198,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();
@@ -294,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);
@@ -303,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}`);
@@ -313,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),
@@ -371,71 +435,86 @@ export function registerMutationCommands(program) {
         .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 <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 <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("--discovery <value>", "Alias for --discovery-text")
         .option("--validation-text <value>", "Validation log entry text")
-        .option("--validation_text <value>", "Alias for --validation-text")
+        .option("--validation <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")
+        .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();
@@ -463,6 +542,7 @@ export function registerMutationCommands(program) {
             ["blocked_by", "blockedBy"],
             ["resume_context", "resumeContext"],
             ["from_search", "fromSearch"],
+            ["step", "stepTitle"],
             ["step_title", "stepTitle"],
             ["step_body", "stepBody"],
             ["step_owner", "stepOwner"],
@@ -555,6 +635,92 @@ export function registerMutationCommands(program) {
             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")
@@ -763,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")
@@ -782,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,
@@ -821,4 +989,4 @@ export function registerMutationCommands(program) {
     });
 }
 //# sourceMappingURL=register-mutation.js.map
-//# debugId=df6717c1-afaf-5933-945b-32b84cacd324
+//# debugId=634fa316-811c-5a12-a391-225313b2c754