@unbrained/pm-cli 2026.6.13 → 2026.6.17

package/dist/cli/register-mutation.js

@@ -1,6 +1,7 @@
 
-!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]="07f90455-c9f8-5cb9-86fe-be98e72908cb")}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]="e38412ec-cbfb-5416-8790-6ca1958f596b")}catch(e){}}();
 import { Option } from "commander";
+import { resolveBodyFileContent } from "../core/io/body-file.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { isPureSnakeCaseAlias } from "../core/shared/option-alias-visibility.js";
@@ -32,7 +33,7 @@ function addHiddenOption(command, flags, description, repeatable) {
  * supplied but does not parse to a finite integer (rather than silently dropping
  * it). Returns `undefined` only when the flag was genuinely not provided.
  */
-function parseSchemaOrderOption(raw) {
+export function parseSchemaOrderOption(raw) {
     if (raw === undefined || raw === null) {
         return undefined;
     }
@@ -54,7 +55,218 @@ function parseSchemaOrderOption(raw) {
     }
     throw new PmCliError("--order must be a finite integer.", EXIT_CODE.USAGE);
 }
-function registerCommanderOptionContracts(command, contracts) {
+/**
+ * Routes a normalized `pm schema` subcommand to its run function. Extracted from
+ * the schema `.action()` body so the per-subcommand dispatch lives in one
+ * single-purpose function and registerMutationCommands stays under the
+ * cyclomatic-complexity gate.
+ */
+async function dispatchSchemaSubcommand(schema, inputs) {
+    const { normalizedSubcommand, typeName, options, globalOptions } = inputs;
+    const { author, force, description } = inputs;
+    switch (normalizedSubcommand) {
+        case "list":
+            return schema.runSchemaList(globalOptions);
+        case "show":
+            return schema.runSchemaShow(typeName, globalOptions);
+        case "show-status":
+            return schema.runSchemaShowStatus(typeName, globalOptions);
+        case "list-fields":
+            return schema.runSchemaListFields(globalOptions);
+        case "show-field":
+            return schema.runSchemaShowField(typeName, globalOptions);
+        case "remove-type":
+            return schema.runSchemaRemoveType(typeName, { author, force }, globalOptions);
+        case "remove-field":
+            return schema.runSchemaRemoveField(typeName, { author, force }, globalOptions);
+        case "apply-preset":
+            return schema.runSchemaApplyPreset(typeName, { author, force }, globalOptions);
+        case "add-field":
+            return schema.runSchemaAddField(typeName, {
+                type: typeof options.type === "string" ? options.type : undefined,
+                commands: inputs.commands,
+                description,
+                cliFlag: typeof options.cliFlag === "string" ? options.cliFlag : undefined,
+                alias: inputs.aliases,
+                required: Boolean(options.required),
+                requiredOnCreate: Boolean(options.requiredOnCreate),
+                // commander stores --no-allow-unset as allowUnset:false; the default
+                // (flag omitted) is true. Forward the tri-state faithfully.
+                allowUnset: options.allowUnset !== false,
+                requiredTypes: inputs.requiredTypes,
+                author,
+                force,
+            }, globalOptions);
+        case "add-status":
+            return schema.runSchemaAddStatus(typeName, { role: inputs.roles, alias: inputs.aliases, description, order: inputs.order, author, force }, globalOptions);
+        case "remove-status":
+            return schema.runSchemaRemoveStatus(typeName, { author, force }, globalOptions);
+        default:
+            // add-type, optionally in --infer mode.
+            if (options.infer === true) {
+                return schema.runSchemaInferTypes({ minCount: inputs.minCount, apply: Boolean(options.apply), author, force }, globalOptions);
+            }
+            return schema.runSchemaAddType(typeName, {
+                description,
+                defaultStatus: inputs.defaultStatus,
+                folder: typeof options.folder === "string" ? options.folder : undefined,
+                alias: inputs.aliases,
+                author,
+                force,
+            }, globalOptions);
+    }
+}
+/**
+ * Renders a schema command result for non-JSON, non-quiet output and surfaces
+ * any on-write hook warnings. Extracted from the schema `.action()` body to keep
+ * registerMutationCommands under the cyclomatic-complexity gate.
+ */
+function renderSchemaResultHuman(schema, result) {
+    switch (result.action) {
+        case "list":
+            writeStdout(`${schema.formatSchemaListHuman(result)}\n`);
+            return;
+        case "show":
+            writeStdout(`${schema.formatSchemaShowHuman(result)}\n`);
+            return;
+        case "show-status":
+            writeStdout(`${schema.formatSchemaShowStatusHuman(result)}\n`);
+            return;
+        case "list-fields":
+            writeStdout(`${schema.formatSchemaListFieldsHuman(result)}\n`);
+            return;
+        case "show-field":
+            writeStdout(`${schema.formatSchemaShowFieldHuman(result)}\n`);
+            return;
+        case "remove-type":
+            writeStdout(`${schema.formatSchemaRemoveTypeHuman(result)}\n`);
+            break;
+        case "remove-field":
+            writeStdout(`${schema.formatSchemaRemoveFieldHuman(result)}\n`);
+            break;
+        case "apply-preset":
+            writeStdout(`${schema.formatSchemaApplyPresetHuman(result)}\n`);
+            break;
+        case "infer-types":
+            writeStdout(`${schema.formatSchemaInferTypesHuman(result)}\n`);
+            break;
+        case "add-field":
+            writeStdout(`${schema.formatSchemaAddFieldHuman(result)}\n`);
+            break;
+        case "add-status":
+            writeStdout(`${schema.formatSchemaAddStatusHuman(result)}\n`);
+            break;
+        case "remove-status":
+            writeStdout(`${schema.formatSchemaRemoveStatusHuman(result)}\n`);
+            break;
+        default:
+            writeStdout(`${schema.formatSchemaAddTypeHuman(result)}\n`);
+            break;
+    }
+    // Surface extension on-write hook diagnostics (mutation subcommands only;
+    // inspection results carry no warnings array).
+    if (result.warnings.length > 0) {
+        printError(`schema ${result.action} warnings: ${formatHookWarnings(result.warnings)}`);
+    }
+}
+/**
+ * Build a commander argParser that coerces a flag value into a positive
+ * (1-based) integer, throwing a usage error when the supplied value is not a
+ * whole number >= 1. Used by `pm comments --edit/--delete <index>` so an
+ * invalid index fails fast with a clear message instead of silently coercing.
+ */
+export function parsePositiveIntOption(flag) {
+    return (value) => {
+        const parsed = Number(value);
+        if (!Number.isInteger(parsed) || parsed < 1) {
+            throw new PmCliError(`${flag} must be a positive integer (1-based index).`, EXIT_CODE.USAGE);
+        }
+        return parsed;
+    };
+}
+// Bulk content-field selection filters (GH-242) shared by update-many and
+// close-many. Each pair mirrors the list-family presence/absence flags but uses
+// the `--filter-` prefix so they live in the bulk-selection namespace. The
+// governance-missing filters (GH-236) reuse the same `--filter-<gov>-missing`
+// spelling as the list family.
+function registerBulkContentAndGovernanceFilters(command, action) {
+    command
+        .option("--filter-has-notes", `Select only items that have notes before ${action}`)
+        .option("--filter-no-notes", `Select only items that have no notes before ${action}`)
+        .option("--filter-has-learnings", `Select only items that have learnings before ${action}`)
+        .option("--filter-no-learnings", `Select only items that have no learnings before ${action}`)
+        .option("--filter-has-files", `Select only items that have linked files before ${action}`)
+        .option("--filter-no-files", `Select only items that have no linked files before ${action}`)
+        .option("--filter-has-docs", `Select only items that have linked docs before ${action}`)
+        .option("--filter-no-docs", `Select only items that have no linked docs before ${action}`)
+        .option("--filter-has-tests", `Select only items that have linked tests before ${action}`)
+        .option("--filter-no-tests", `Select only items that have no linked tests before ${action}`)
+        .option("--filter-has-comments", `Select only items that have comments before ${action}`)
+        .option("--filter-no-comments", `Select only items that have no comments before ${action}`)
+        .option("--filter-has-deps", `Select only items that have dependencies before ${action}`)
+        .option("--filter-no-deps", `Select only items that have no dependencies before ${action}`)
+        .option("--filter-has-body", `Select only items that have a non-empty body before ${action}`)
+        .option("--filter-empty-body", `Select only items with an empty body before ${action}`)
+        .option("--filter-has-linked-command", `Select only items whose linked tests carry a runnable command before ${action}`)
+        .option("--filter-no-linked-command", `Select only items whose linked tests carry no runnable command before ${action}`)
+        .option("--filter-reviewer-missing", `Select only items missing reviewer before ${action}`)
+        .option("--filter-risk-missing", `Select only items missing risk before ${action}`)
+        .option("--filter-confidence-missing", `Select only items missing confidence before ${action}`)
+        .option("--filter-sprint-missing", `Select only items missing sprint before ${action}`)
+        .option("--filter-release-missing", `Select only items missing release before ${action}`);
+}
+// Map the bulk content/governance `--filter-*` commander options into the
+// ListOptions content/governance fields runList consumes. Shared by update-many
+// and close-many.
+// [hasCommanderKey, noCommanderKey, --filter-has flag, --filter-no flag]
+const BULK_CONTENT_FILTER_CONFLICTS = [
+    ["filterHasNotes", "filterNoNotes", "--filter-has-notes", "--filter-no-notes"],
+    ["filterHasLearnings", "filterNoLearnings", "--filter-has-learnings", "--filter-no-learnings"],
+    ["filterHasFiles", "filterNoFiles", "--filter-has-files", "--filter-no-files"],
+    ["filterHasDocs", "filterNoDocs", "--filter-has-docs", "--filter-no-docs"],
+    ["filterHasTests", "filterNoTests", "--filter-has-tests", "--filter-no-tests"],
+    ["filterHasComments", "filterNoComments", "--filter-has-comments", "--filter-no-comments"],
+    ["filterHasDeps", "filterNoDeps", "--filter-has-deps", "--filter-no-deps"],
+    ["filterHasBody", "filterEmptyBody", "--filter-has-body", "--filter-empty-body"],
+    ["filterHasLinkedCommand", "filterNoLinkedCommand", "--filter-has-linked-command", "--filter-no-linked-command"],
+];
+function mapBulkContentAndGovernanceFilters(options) {
+    const presence = (key) => (options[key] === true ? true : undefined);
+    // Catch a both-present-and-absent bulk request here so the error names the
+    // bulk --filter-* flags the user actually typed, rather than the downstream
+    // list-level --has-/--no- flags resolveContentFieldFilters would report.
+    for (const [hasKey, noKey, hasFlag, noFlag] of BULK_CONTENT_FILTER_CONFLICTS) {
+        if (options[hasKey] === true && options[noKey] === true) {
+            throw new PmCliError(`Cannot combine ${hasFlag} with ${noFlag} for the same field.`, EXIT_CODE.USAGE);
+        }
+    }
+    return {
+        filterReviewerMissing: presence("filterReviewerMissing"),
+        filterRiskMissing: presence("filterRiskMissing"),
+        filterConfidenceMissing: presence("filterConfidenceMissing"),
+        filterSprintMissing: presence("filterSprintMissing"),
+        filterReleaseMissing: presence("filterReleaseMissing"),
+        hasNotes: presence("filterHasNotes"),
+        hasLearnings: presence("filterHasLearnings"),
+        hasFiles: presence("filterHasFiles"),
+        hasDocs: presence("filterHasDocs"),
+        hasTests: presence("filterHasTests"),
+        hasComments: presence("filterHasComments"),
+        hasDeps: presence("filterHasDeps"),
+        hasBody: presence("filterHasBody"),
+        hasLinkedCommand: presence("filterHasLinkedCommand"),
+        noNotes: presence("filterNoNotes"),
+        noLearnings: presence("filterNoLearnings"),
+        noFiles: presence("filterNoFiles"),
+        noDocs: presence("filterNoDocs"),
+        noTests: presence("filterNoTests"),
+        noComments: presence("filterNoComments"),
+        noDeps: presence("filterNoDeps"),
+        emptyBody: presence("filterEmptyBody"),
+        noLinkedCommand: presence("filterNoLinkedCommand"),
+    };
+}
+export function registerCommanderOptionContracts(command, contracts) {
     for (const contract of contracts) {
         if (contract.required) {
             command.requiredOption(contract.option, contract.description);
@@ -81,6 +293,39 @@ function registerCommanderOptionContracts(command, contracts) {
         }
     }
 }
+/**
+ * Map raw `update-many --filter-*` commander options into the ListOptions shape
+ * runList consumes. Extracted from registerMutationCommands so its many
+ * string/boolean coercions do not inflate that function's cyclomatic complexity.
+ */
+function buildUpdateManyListOptions(options) {
+    const readString = (key) => typeof options[key] === "string" ? options[key] : undefined;
+    return {
+        type: readString("filterType"),
+        tag: readString("filterTag"),
+        priority: readString("filterPriority"),
+        deadlineBefore: readString("filterDeadlineBefore"),
+        deadlineAfter: readString("filterDeadlineAfter"),
+        updatedAfter: readString("filterUpdatedAfter"),
+        updatedBefore: readString("filterUpdatedBefore"),
+        createdAfter: readString("filterCreatedAfter"),
+        createdBefore: readString("filterCreatedBefore"),
+        ids: readString("ids"),
+        assignee: readString("filterAssignee"),
+        assigneeFilter: readString("filterAssigneeFilter") ?? readString("filterAssignee_filter"),
+        parent: readString("filterParent"),
+        sprint: readString("filterSprint"),
+        release: readString("filterRelease"),
+        filterAcMissing: options.filterAcMissing === true ? true : undefined,
+        filterEstimatesMissing: options.filterEstimatesMissing === true || options.filterEstimateMissing === true ? true : undefined,
+        filterResolutionMissing: options.filterResolutionMissing === true ? true : undefined,
+        filterMetadataMissing: options.filterMetadataMissing === true ? true : undefined,
+        ...mapBulkContentAndGovernanceFilters(options),
+        limit: readString("limit"),
+        offset: readString("offset"),
+        includeBody: true,
+    };
+}
 export function registerMutationCommands(program) {
     const createCommand = program
         .command("create")
@@ -89,6 +334,7 @@ export function registerMutationCommands(program) {
         .description("Create a new project management item.");
     registerCommanderOptionContracts(createCommand, CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS);
     createCommand
+        .option("--body-file <path>", "Load the item markdown body from a file (mutually exclusive with --body)")
         .option("--clear-deps", "Clear dependency entries")
         .option("--clear-comments", "Clear comments")
         .option("--clear-notes", "Clear notes")
@@ -112,7 +358,15 @@ export function registerMutationCommands(program) {
             positionalTitle = secondTitle;
         }
         else if (typeof typeOrTitle === "string" && typeOrTitle.length > 0) {
-            positionalTitle = typeOrTitle;
+            // Honor `pm create <type> --title ...` by treating the lone positional as
+            // type when an explicit --title is already present.
+            const explicitTitleProvided = typeof options.title === "string" && options.title.trim().length > 0;
+            if (explicitTitleProvided && options.type === undefined) {
+                positionalType = typeOrTitle;
+            }
+            else {
+                positionalTitle = typeOrTitle;
+            }
         }
         // pm-edge #1 (2026-05-28): when the sole positional matches a known
         // item type AND no --title was supplied, refuse early instead of
@@ -145,6 +399,12 @@ export function registerMutationCommands(program) {
         if (typeof positionalTitle === "string" && positionalTitle.length > 0 && options.title === undefined) {
             options.title = positionalTitle;
         }
+        // GH-214: resolve --body-file into the existing body field before
+        // normalization so the rest of create is unchanged. CLI-only input alias.
+        if (typeof options.bodyFile === "string") {
+            options.body = await resolveBodyFileContent(options.bodyFile, options.body !== undefined ? String(options.body) : undefined);
+            delete options.bodyFile;
+        }
         const normalized = normalizeCreateOptions(options, { requireType: false });
         const { runCreate } = await import("./commands/create.js");
         const result = await runCreate(normalized, globalOptions);
@@ -176,12 +436,28 @@ export function registerMutationCommands(program) {
             printError(`profile:command=copy took_ms=${Date.now() - startedAt}`);
         }
     });
+    program
+        .command("focus")
+        .argument("[id]", "Item id to focus (omit to show current focus)")
+        .option("--clear", "Clear the focused item")
+        .description("Set/clear/show the session focused item that new items default --parent to.")
+        .action(async (id, options, command) => {
+        const globalOptions = getGlobalOptions(command);
+        const startedAt = Date.now();
+        const { runFocus } = await import("./commands/focus.js");
+        const result = await runFocus(id, { clear: options.clear === true }, globalOptions);
+        printResult(result, globalOptions);
+        if (globalOptions.profile) {
+            printError(`profile:command=focus took_ms=${Date.now() - startedAt}`);
+        }
+    });
     const updateCommand = program
         .command("update")
         .argument("<id>", "Item id")
         .description("Update item fields and metadata.");
     registerCommanderOptionContracts(updateCommand, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS);
     updateCommand
+        .option("--body-file <path>", "Load the item markdown body from a file (mutually exclusive with --body)")
         .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("--clear-deps", "Clear dependency entries")
@@ -203,6 +479,12 @@ export function registerMutationCommands(program) {
         .action(async (id, options, command) => {
         const globalOptions = getGlobalOptions(command);
         const startedAt = Date.now();
+        // GH-214: resolve --body-file into the existing body field before
+        // normalization so the rest of update is unchanged. CLI-only input alias.
+        if (typeof options.bodyFile === "string") {
+            options.body = await resolveBodyFileContent(options.bodyFile, options.body !== undefined ? String(options.body) : undefined);
+            delete options.bodyFile;
+        }
         const { runUpdate } = await import("./commands/update.js");
         const result = await runUpdate(id, normalizeUpdateOptions(options), globalOptions);
         await invalidateSearchCachesForMutation(globalOptions, result);
@@ -229,6 +511,12 @@ export function registerMutationCommands(program) {
         .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")
+        .option("--filter-ac-missing", "Select only items missing acceptance_criteria (bulk backfill)")
+        .option("--filter-estimates-missing", "Select only items missing estimated_minutes (bulk backfill)")
+        .option("--filter-resolution-missing", "Select only terminal items missing resolution (bulk backfill)")
+        .option("--filter-metadata-missing", "Select only items missing any tracked metadata (AC, estimate, or resolution)");
+    registerBulkContentAndGovernanceFilters(updateManyCommand, "applying updates");
+    updateManyCommand
         .option("--ids <value>", "Restrict to an explicit comma-separated ID allowlist (intersected with other filters)")
         .option("--limit <n>", "Limit matched item count before apply/preview")
         .option("--offset <n>", "Skip first n matched rows before apply/preview")
@@ -329,6 +617,7 @@ export function registerMutationCommands(program) {
         ["--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"],
+        ["--filter-estimate-missing", "Alias for --filter-estimates-missing"],
     ]) {
         addHiddenOption(updateManyCommand, flags, description, false);
     }
@@ -347,30 +636,7 @@ export function registerMutationCommands(program) {
         const { runUpdateMany } = await import("./commands/update-many.js");
         const result = await runUpdateMany({
             status: typeof options.filterStatus === "string" ? options.filterStatus : undefined,
-            list: {
-                type: typeof options.filterType === "string" ? options.filterType : undefined,
-                tag: typeof options.filterTag === "string" ? options.filterTag : undefined,
-                priority: typeof options.filterPriority === "string" ? options.filterPriority : undefined,
-                deadlineBefore: typeof options.filterDeadlineBefore === "string" ? options.filterDeadlineBefore : undefined,
-                deadlineAfter: typeof options.filterDeadlineAfter === "string" ? options.filterDeadlineAfter : undefined,
-                updatedAfter: typeof options.filterUpdatedAfter === "string" ? options.filterUpdatedAfter : undefined,
-                updatedBefore: typeof options.filterUpdatedBefore === "string" ? options.filterUpdatedBefore : undefined,
-                createdAfter: typeof options.filterCreatedAfter === "string" ? options.filterCreatedAfter : undefined,
-                createdBefore: typeof options.filterCreatedBefore === "string" ? options.filterCreatedBefore : undefined,
-                ids: typeof options.ids === "string" ? options.ids : undefined,
-                assignee: typeof options.filterAssignee === "string" ? options.filterAssignee : undefined,
-                assigneeFilter: 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,
-            },
+            list: buildUpdateManyListOptions(options),
             update: normalizeUpdateOptions(extractUpdateManyMutationOptionSource(options)),
             dryRun: options.dryRun === true ? true : undefined,
             rollback: typeof options.rollback === "string" ? options.rollback : undefined,
@@ -386,11 +652,11 @@ export function registerMutationCommands(program) {
         .command("close")
         .argument("<id>", "Item id")
         .argument("[text]", "Close reason text (alias: --reason)")
-        .option("--reason <value>", "Close reason text (alias for positional <text>)")
+        .option("-r, --reason <value>", "Close reason text (alias for positional <text>)")
         .option("--close-reason <value>", "Close reason text (alias for positional <text>)")
-        .option("--duplicate-of <id>", "Close as a duplicate of the canonical item id and auto-fill duplicate closure metadata")
+        .option("-d, --duplicate-of <id>", "Close as a duplicate of the canonical item id and auto-fill duplicate closure metadata")
         .option("--author <value>", "Mutation author")
-        .option("--message <value>", "History message")
+        .option("-m, --message <value>", "History message")
         .option("--validate-close [mode]", 'Validate closure metadata before close: "off", "warn", or "strict" (default: settings governance preset)')
         .option("--resolution <value>", "Set the closure resolution summary inline (same field --validate-close strict checks; previously required a prior pm update)")
         .option("--expected-result <value>", "Set the expected-result note inline (closure validation field)")
@@ -458,7 +724,9 @@ export function registerMutationCommands(program) {
         .option("--filter-assignee-filter <value>", "Filter assignee presence: assigned|unassigned before closing")
         .option("--filter-parent <value>", "Filter by parent item ID before closing")
         .option("--filter-sprint <value>", "Filter by sprint before closing")
-        .option("--filter-release <value>", "Filter by release before closing")
+        .option("--filter-release <value>", "Filter by release before closing");
+    registerBulkContentAndGovernanceFilters(closeManyCommand, "closing");
+    closeManyCommand
         .option("--ids <value>", "Restrict to an explicit comma-separated ID allowlist (intersected with other filters)")
         .option("--limit <n>", "Limit matched item count before apply/preview")
         .option("--offset <n>", "Skip first n matched rows before apply/preview")
@@ -508,6 +776,7 @@ export function registerMutationCommands(program) {
                 parent: typeof options.filterParent === "string" ? options.filterParent : undefined,
                 sprint: typeof options.filterSprint === "string" ? options.filterSprint : undefined,
                 release: typeof options.filterRelease === "string" ? options.filterRelease : undefined,
+                ...mapBulkContentAndGovernanceFilters(options),
                 limit: typeof options.limit === "string" ? options.limit : undefined,
                 offset: typeof options.offset === "string" ? options.offset : undefined,
             },
@@ -911,22 +1180,33 @@ export function registerMutationCommands(program) {
         .command("schema")
         .argument("[subcommand]", "Schema subcommand: list, show, show-status, add-type, remove-type, add-status, remove-status, or a custom item type name shorthand")
         .argument("[name]", "Item type name (add-type/remove-type/show) or status id (show-status/add-status/remove-status)")
-        .option("--description <text>", "Human description for the custom item type or status")
+        .option("--description <text>", "Human description for the custom item type, status, or field")
         .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 or status (repeatable, csv-friendly)", collect)
+        .option("--alias <name>", "Alias for the custom type, status, or field flag (repeatable, csv-friendly)", collect)
         .option("--role <value>", "Lifecycle role for a custom status (repeatable): draft, active, blocked, terminal, terminal_done, terminal_canceled, default_open, default_close, default_cancel", collect)
         .option("--order <n>", "Display/sort order for a custom status")
+        .option("--type <type>", "Value type for a custom field (add-field): string, number, boolean, string_array")
+        .option("--commands <list>", "Commands a custom field is wired onto (add-field; repeatable, comma-friendly): create, update, update_many, list, search, calendar, context", collect)
+        .option("--cli-flag <flag>", "Override the auto-derived CLI flag for a custom field (add-field)")
+        .option("--required", "Mark a custom field as always required (add-field)")
+        .option("--required-on-create", "Mark a custom field as required at create time (add-field)")
+        .option("--no-allow-unset", "Disallow clearing a custom field via --unset (add-field)")
+        .option("--required-types <list>", "Restrict a custom field's requirement to specific item types (add-field; repeatable, comma-friendly)", collect)
+        .option("--infer", "Infer custom item types from title-prefix conventions (add-type; preview unless --apply)")
+        .option("--min-count <n>", "Minimum items sharing a prefix for add-type --infer (default 10)")
+        .option("--apply", "Register inferred types (add-type --infer); without it the command previews only")
         .option("--author <value>", "Mutation author")
         .option("--force", "Force ownership/lock override")
-        .description("Inspect and manage config-driven runtime schema.");
+        .description("Inspect and manage config-driven runtime schema (types, statuses, fields, presets).");
     // 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, runSchemaRemoveType, runSchemaAddStatus, runSchemaRemoveStatus, runSchemaList, runSchemaShow, runSchemaShowStatus, formatSchemaAddTypeHuman, formatSchemaRemoveTypeHuman, formatSchemaAddStatusHuman, formatSchemaRemoveStatusHuman, formatSchemaListHuman, formatSchemaShowHuman, formatSchemaShowStatusHuman, SCHEMA_SUBCOMMANDS, } = await import("./commands/schema.js");
+        const schemaModule = await import("./commands/schema.js");
+        const { SCHEMA_SUBCOMMANDS } = schemaModule;
         let normalizedSubcommand = (subcommand ?? "").trim().toLowerCase();
         let typeName = name;
         if (!normalizedSubcommand) {
@@ -940,15 +1220,23 @@ export function registerMutationCommands(program) {
                     "pm schema remove-type Spike",
                     "pm schema add-status review --role active --alias in_review",
                     "pm schema remove-status review",
+                    "pm schema add-field severity_level --type string --commands create,update",
+                    "pm schema list-fields",
+                    "pm schema apply-preset agile",
+                    "pm schema add-type --infer --min-count 10",
                 ],
             });
         }
-        const aliases = typeof options.alias === "string"
+        const aliases = 
+        /* c8 ignore next -- --alias is registered with commander `collect`, so it is always an array here; the string arm is a defensive guard for non-CLI (programmatic) callers */
+        typeof options.alias === "string"
             ? [options.alias]
             : Array.isArray(options.alias)
                 ? options.alias
                 : undefined;
-        const roles = typeof options.role === "string"
+        const roles = 
+        /* c8 ignore next -- --role is registered with commander `collect`, so it is always an array here; the string arm is a defensive guard for non-CLI (programmatic) callers */
+        typeof options.role === "string"
             ? [options.role]
             : Array.isArray(options.role)
                 ? options.role
@@ -959,6 +1247,21 @@ export function registerMutationCommands(program) {
                 ? options.default_status
                 : undefined;
         const order = parseSchemaOrderOption(options.order);
+        // --commands/--required-types are repeatable Commander `collect` flags, so
+        // their value is always a string[] (or undefined when omitted); each entry
+        // may itself be a comma-list, which we split and flatten here.
+        const splitCommaList = (raw) => {
+            if (!Array.isArray(raw)) {
+                return undefined;
+            }
+            return raw
+                .flatMap((value) => value.split(","))
+                .map((value) => value.trim())
+                .filter((value) => value.length > 0);
+        };
+        const commands = splitCommaList(options.commands);
+        const requiredTypes = splitCommaList(options.requiredTypes);
+        const minCount = parseSchemaOrderOption(options.minCount);
         if (!SCHEMA_SUBCOMMANDS.includes(normalizedSubcommand) && typeName === undefined) {
             typeName = subcommand;
             normalizedSubcommand = "add-type";
@@ -968,67 +1271,29 @@ export function registerMutationCommands(program) {
         }
         const author = typeof options.author === "string" ? options.author : undefined;
         const force = Boolean(options.force);
-        const result = normalizedSubcommand === "list"
-            ? await runSchemaList(globalOptions)
-            : normalizedSubcommand === "show"
-                ? await runSchemaShow(typeName, globalOptions)
-                : normalizedSubcommand === "show-status"
-                    ? await runSchemaShowStatus(typeName, globalOptions)
-                    : normalizedSubcommand === "remove-type"
-                        ? await runSchemaRemoveType(typeName, { author, force }, globalOptions)
-                        : normalizedSubcommand === "add-status"
-                            ? await runSchemaAddStatus(typeName, {
-                                role: roles,
-                                alias: aliases,
-                                description: typeof options.description === "string" ? options.description : undefined,
-                                order,
-                                author,
-                                force,
-                            }, globalOptions)
-                            : normalizedSubcommand === "remove-status"
-                                ? await runSchemaRemoveStatus(typeName, { author, force }, globalOptions)
-                                : await runSchemaAddType(typeName, {
-                                    description: typeof options.description === "string" ? options.description : undefined,
-                                    defaultStatus,
-                                    folder: typeof options.folder === "string" ? options.folder : undefined,
-                                    alias: aliases,
-                                    author,
-                                    force,
-                                }, globalOptions);
+        const description = typeof options.description === "string" ? options.description : undefined;
+        const result = await dispatchSchemaSubcommand(schemaModule, {
+            normalizedSubcommand,
+            typeName,
+            options,
+            aliases,
+            roles,
+            commands,
+            requiredTypes,
+            defaultStatus,
+            order,
+            minCount,
+            author,
+            force,
+            description,
+            globalOptions,
+        });
         // Schema inspection and type registration do not touch item content, so search caches stay valid.
         if (globalOptions.json === true || globalOptions.defaultOutputFormat === "json") {
             printResult(result, globalOptions);
         }
         else if (!globalOptions.quiet) {
-            if (result.action === "list") {
-                writeStdout(`${formatSchemaListHuman(result)}\n`);
-            }
-            else if (result.action === "show") {
-                writeStdout(`${formatSchemaShowHuman(result)}\n`);
-            }
-            else if (result.action === "show-status") {
-                writeStdout(`${formatSchemaShowStatusHuman(result)}\n`);
-            }
-            else if (result.action === "remove-type") {
-                writeStdout(`${formatSchemaRemoveTypeHuman(result)}\n`);
-            }
-            else if (result.action === "add-status") {
-                writeStdout(`${formatSchemaAddStatusHuman(result)}\n`);
-            }
-            else if (result.action === "remove-status") {
-                writeStdout(`${formatSchemaRemoveStatusHuman(result)}\n`);
-            }
-            else {
-                writeStdout(`${formatSchemaAddTypeHuman(result)}\n`);
-            }
-            // Surface extension on-write hook diagnostics so policy/enforcement
-            // warnings are visible without forcing --json.
-            if (result.action !== "list" &&
-                result.action !== "show" &&
-                result.action !== "show-status" &&
-                result.warnings.length > 0) {
-                printError(`schema ${result.action} warnings: ${formatHookWarnings(result.warnings)}`);
-            }
+            renderSchemaResultHuman(schemaModule, result);
         }
         if (globalOptions.profile) {
             printError(`profile:command=schema took_ms=${Date.now() - startedAt}`);
@@ -1041,15 +1306,19 @@ export function registerMutationCommands(program) {
         .option("--add <text>", "Add one comment entry (plain text fallback, text=<value>, markdown pairs, or - for stdin; CSV-like key fragments are preserved as plain text unless text is explicit)")
         .option("--stdin", "Read comment text from stdin (supports multiline markdown)")
         .option("--file <path>", "Read comment text from file (supports multiline markdown)")
+        .option("--edit <index>", "Replace the comment at 1-based <index> (replacement text from positional [text], --add, --stdin, or --file)", parsePositiveIntOption("--edit"))
+        .option("--delete <index>", "Delete the comment at 1-based <index>", parsePositiveIntOption("--delete"))
         .option("--limit <n>", "Return only latest n comments")
         .option("--author [value]", "Comment author (optional; falls back to PM_AUTHOR/settings)")
         .option("--message <value>", "History message")
-        .option("--allow-audit-comment", "Allow non-owner append-only comment audits without requiring --force")
+        .option("--allow-audit-comment", "Allow non-owner append-only comment audits (add/edit/delete) without requiring --force")
         .option("--force", "Force ownership override")
-        .description("List or add comments for an item.")
+        .description("List, add, edit, or delete comments for an item.")
         .action(async (id, text, options, command) => {
         const globalOptions = getGlobalOptions(command);
         const startedAt = Date.now();
+        const editIndex = typeof options.edit === "number" ? options.edit : undefined;
+        const deleteIndex = typeof options.delete === "number" ? options.delete : undefined;
         const addFromOption = typeof options.add === "string" ? options.add : undefined;
         const addFromPositional = typeof text === "string" ? text : undefined;
         const readFromStdin = options.stdin === true;
@@ -1070,13 +1339,16 @@ export function registerMutationCommands(program) {
             add,
             stdin: readFromStdin,
             file: readFromFile,
+            edit: editIndex,
+            delete: deleteIndex,
             limit: typeof options.limit === "string" ? options.limit : undefined,
             author: typeof options.author === "string" ? options.author : undefined,
             message: typeof options.message === "string" ? options.message : undefined,
             allowAuditComment: Boolean(options.allowAuditComment),
             force: Boolean(options.force),
         }, globalOptions);
-        if (typeof add === "string" || readFromStdin || readFromFile !== undefined) {
+        const isMutation = typeof add === "string" || readFromStdin || readFromFile !== undefined || editIndex !== undefined || deleteIndex !== undefined;
+        if (isMutation) {
             await invalidateSearchCachesForMutation(globalOptions, result);
         }
         printResult(result, globalOptions);
@@ -1297,10 +1569,14 @@ export function registerMutationCommands(program) {
         const globalOptions = getGlobalOptions(command);
         const startedAt = Date.now();
         const { runDeps } = await import("./commands/deps.js");
+        // --format and --collapse carry commander defaults ("tree"/"none"), so
+        // they are always strings by the time the action runs; --maxDepth has no
+        // default and may be unset. Use `as string` rather than String(...) so an
+        // omitted option stays undefined instead of becoming the literal "undefined".
         const result = await runDeps(id, {
-            format: typeof options.format === "string" ? options.format : undefined,
+            format: options.format,
             maxDepth: typeof options.maxDepth === "string" ? options.maxDepth : undefined,
-            collapse: typeof options.collapse === "string" ? options.collapse : undefined,
+            collapse: options.collapse,
             summary: options.summary === true,
         }, globalOptions);
         printResult(result, globalOptions);
@@ -1310,4 +1586,4 @@ export function registerMutationCommands(program) {
     });
 }
 //# sourceMappingURL=register-mutation.js.map
-//# debugId=07f90455-c9f8-5cb9-86fe-be98e72908cb
+//# debugId=e38412ec-cbfb-5416-8790-6ca1958f596b