@unbrained/pm-cli 2026.7.5 → 2026.7.6

package/dist/cli-bundle/chunks/chunk-HFDADVJZ.js

@@ -0,0 +1,1356 @@
+
+!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]="b3ee81eb-626f-58f7-9a58-78d41be890a7")}catch(e){}}();
+import {
+  runCreate
+} from "./chunk-TULGS6X6.js";
+import {
+  splitCommaList
+} from "./chunk-P4SESZGT.js";
+import {
+  locateItem,
+  mutateItem,
+  readLocatedItem
+} from "./chunk-ENGQOEUY.js";
+import {
+  nowIso
+} from "./chunk-3GCS5SKL.js";
+import {
+  PmCliError,
+  getActiveExtensionRegistrations,
+  readSettings
+} from "./chunk-E3SZTQ4K.js";
+import {
+  EXIT_CODE,
+  PLAN_HARNESS_VALUES,
+  PLAN_MODE_VALUES,
+  PLAN_STEP_LINK_KIND_VALUES,
+  PLAN_STEP_STATUS_VALUES,
+  getSettingsPath,
+  pathExists,
+  resolveItemTypeRegistry,
+  resolvePmRoot,
+  resolveTypeName
+} from "./chunk-57NWPFF2.js";
+
+// dist/cli/commands/plan.js
+var PLAN_SUBCOMMANDS = [
+  "create",
+  "show",
+  "add-step",
+  "update-step",
+  "complete-step",
+  "block-step",
+  "reorder-step",
+  "remove-step",
+  "link",
+  "unlink",
+  "decision",
+  "discovery",
+  "validation",
+  "resume",
+  "approve",
+  "materialize"
+];
+var PLAN_SHOW_DEPTH_VALUES = ["brief", "standard", "deep"];
+var STEP_ID_PREFIX = "plan-step-";
+var DEFAULT_PLAN_MODE = "draft";
+var PLAN_TEMPLATE_NAMES = ["bug-investigation", "feature-implementation", "refactoring-sprint"];
+var PLAN_TEMPLATES = {
+  "bug-investigation": [
+    { title: "Reproduce the bug", body: "Capture exact steps, inputs, and the observed vs expected behavior." },
+    { title: "Locate the root cause", body: "Trace the failure to the responsible code path with evidence." },
+    { title: "Write a failing test", body: "Add a regression test that fails for the current bug." },
+    { title: "Implement the fix", body: "Apply the minimal change that makes the failing test pass." },
+    { title: "Verify and document", body: "Run the full suite and record the resolution and verification." }
+  ],
+  "feature-implementation": [
+    { title: "Clarify requirements & acceptance criteria", body: "Confirm scope, edge cases, and done-conditions." },
+    { title: "Design the approach", body: "Decide the data model, interfaces, and integration points." },
+    { title: "Implement the change", body: "Build the feature behind the agreed design." },
+    { title: "Add tests", body: "Cover the new behavior and its edge cases." },
+    { title: "Update docs & changelog", body: "Document the feature and surface it to users." }
+  ],
+  "refactoring-sprint": [
+    { title: "Map the current structure & risks", body: "Inventory the code to change and its blast radius." },
+    { title: "Add characterization tests", body: "Lock in current behavior before refactoring." },
+    { title: "Refactor incrementally", body: "Apply small, reversible steps keeping tests green." },
+    { title: "Verify behavior is unchanged", body: "Run the full suite and compare against the baseline." },
+    { title: "Clean up & document", body: "Remove dead code and record the new structure." }
+  ]
+};
+function resolvePlanTemplateSteps(raw) {
+  const normalized = raw.trim().toLowerCase();
+  const template = Object.prototype.hasOwnProperty.call(PLAN_TEMPLATES, normalized) ? PLAN_TEMPLATES[normalized] : void 0;
+  if (!template) {
+    throw new PmCliError(`Unknown plan template "${raw}". Allowed: ${PLAN_TEMPLATE_NAMES.join(", ")}`, EXIT_CODE.USAGE, {
+      code: "unknown_plan_template",
+      examples: [`pm plan create --title "Fix login crash" --template ${PLAN_TEMPLATE_NAMES[0]}`]
+    });
+  }
+  return template.map((step) => ({ ...step }));
+}
+function planCompletionPct(completed, total) {
+  return total > 0 ? Math.round(completed / total * 100) : 0;
+}
+function resolveAuthor(candidate, fallback) {
+  const resolved = candidate ?? process.env.PM_AUTHOR ?? fallback;
+  const trimmed = resolved.trim();
+  return trimmed.length > 0 ? trimmed : "unknown";
+}
+function toOrderedStepTitles(value) {
+  const values = Array.isArray(value) ? value : value === void 0 || value === null ? [] : [value];
+  return values.filter((entry) => entry !== void 0 && entry !== null).map((entry) => (typeof entry === "string" ? entry : String(entry)).trim()).filter((entry) => entry.length > 0);
+}
+function toArray(value) {
+  if (Array.isArray(value))
+    return value.flatMap((entry) => splitCommaList(entry, { unique: false }));
+  if (typeof value === "string" && value.trim().length > 0) {
+    return splitCommaList(value, { unique: false });
+  }
+  return [];
+}
+function toSpecArray(value) {
+  if (Array.isArray(value))
+    return value.map((entry) => entry.trim()).filter(Boolean);
+  if (typeof value === "string" && value.trim().length > 0)
+    return [value.trim()];
+  return [];
+}
+function asPlanMode(value, fallback = DEFAULT_PLAN_MODE) {
+  if (value === void 0)
+    return fallback;
+  const normalized = value.trim().toLowerCase();
+  const found = PLAN_MODE_VALUES.find((entry) => entry === normalized);
+  if (!found) {
+    throw new PmCliError(`Invalid plan mode "${value}". Allowed: ${PLAN_MODE_VALUES.join(", ")}`, EXIT_CODE.USAGE);
+  }
+  return found;
+}
+function asStepStatus(value, fallback = "pending") {
+  if (value === void 0)
+    return fallback;
+  const normalized = value.trim().toLowerCase();
+  const found = PLAN_STEP_STATUS_VALUES.find((entry) => entry === normalized);
+  if (!found) {
+    throw new PmCliError(`Invalid step status "${value}". Allowed: ${PLAN_STEP_STATUS_VALUES.join(", ")}`, EXIT_CODE.USAGE);
+  }
+  return found;
+}
+function asLinkKind(value, fallback = "related") {
+  if (value === void 0)
+    return fallback;
+  const normalized = value.trim().toLowerCase();
+  const found = PLAN_STEP_LINK_KIND_VALUES.find((entry) => entry === normalized);
+  if (!found) {
+    throw new PmCliError(`Invalid step link kind "${value}". Allowed: ${PLAN_STEP_LINK_KIND_VALUES.join(", ")}`, EXIT_CODE.USAGE);
+  }
+  return found;
+}
+function asHarness(value) {
+  if (value === void 0)
+    return void 0;
+  const normalized = value.trim().toLowerCase();
+  if (normalized.length === 0)
+    return void 0;
+  const found = PLAN_HARNESS_VALUES.find((entry) => entry === normalized);
+  if (!found) {
+    throw new PmCliError(`Invalid plan harness "${value}". Allowed: ${PLAN_HARNESS_VALUES.join(", ")}`, EXIT_CODE.USAGE);
+  }
+  return found;
+}
+function asDepth(value) {
+  if (value === void 0)
+    return "brief";
+  const normalized = value.trim().toLowerCase();
+  const found = PLAN_SHOW_DEPTH_VALUES.find((entry) => entry === normalized);
+  if (!found) {
+    throw new PmCliError(`Invalid --depth "${value}". Allowed: ${PLAN_SHOW_DEPTH_VALUES.join(", ")}`, EXIT_CODE.USAGE);
+  }
+  return found;
+}
+function parsePlanFields(raw) {
+  if (raw === void 0) {
+    return null;
+  }
+  const fields = raw.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+  if (fields.length === 0) {
+    throw new PmCliError("Plan --fields requires a comma-separated list of plan field names", EXIT_CODE.USAGE);
+  }
+  return fields;
+}
+var PLAN_FIELD_KEYS = /* @__PURE__ */ new Set([
+  "id",
+  "title",
+  "status",
+  "mode",
+  "scope",
+  "harness",
+  "parent",
+  "resume_context",
+  "steps_summary",
+  "current_step",
+  "blocked_steps",
+  "steps",
+  "decisions",
+  "discoveries",
+  "validation",
+  "linked_items"
+]);
+function projectPlanForFields(plan, fields) {
+  const source = plan;
+  const projected = {};
+  const unknownFields = [];
+  for (const field of fields) {
+    const normalized = field.startsWith("plan.") ? field.slice("plan.".length) : field;
+    if (normalized.length === 0) {
+      continue;
+    }
+    if (!PLAN_FIELD_KEYS.has(normalized)) {
+      unknownFields.push(field);
+      continue;
+    }
+    if (Object.prototype.hasOwnProperty.call(source, normalized)) {
+      projected[normalized] = source[normalized];
+    }
+  }
+  if (unknownFields.length > 0) {
+    throw new PmCliError(`Unknown Plan --fields value(s): ${unknownFields.join(", ")}`, EXIT_CODE.USAGE, {
+      nextSteps: [
+        `Use --fields ${[...PLAN_FIELD_KEYS].join(",")}`,
+        "Run pm plan show <id> --depth brief for compact default fields."
+      ],
+      recovery: {
+        provided_fields: unknownFields,
+        suggested_retry: `pm plan show <id> --fields ${[...PLAN_FIELD_KEYS].join(",")}`
+      }
+    });
+  }
+  return projected;
+}
+function parsePairList(raw, label) {
+  const out = {};
+  for (const entry of raw.split(",")) {
+    const trimmed = entry.trim();
+    if (trimmed.length === 0)
+      continue;
+    const equalsIndex = trimmed.indexOf("=");
+    if (equalsIndex <= 0) {
+      throw new PmCliError(`Invalid ${label} entry "${trimmed}"; expected key=value`, EXIT_CODE.USAGE);
+    }
+    out[trimmed.slice(0, equalsIndex).trim().toLowerCase()] = trimmed.slice(equalsIndex + 1).trim();
+  }
+  return out;
+}
+function parseStepFile(spec) {
+  const fields = parsePairList(spec, "--file");
+  if (!fields.path) {
+    throw new PmCliError("--file requires path=<value>", EXIT_CODE.USAGE);
+  }
+  const file = { path: fields.path };
+  if (fields.scope === "global" || fields.scope === "project")
+    file.scope = fields.scope;
+  if (fields.note)
+    file.note = fields.note;
+  return file;
+}
+function parseStepTest(spec) {
+  const fields = parsePairList(spec, "--test");
+  if (!fields.command && !fields.path) {
+    throw new PmCliError("--test requires at least command=<value> or path=<value>", EXIT_CODE.USAGE);
+  }
+  const test = {};
+  if (fields.command)
+    test.command = fields.command;
+  if (fields.path)
+    test.path = fields.path;
+  if (fields.note)
+    test.note = fields.note;
+  return test;
+}
+function parseStepDoc(spec) {
+  const fields = parsePairList(spec, "--doc");
+  if (!fields.path) {
+    throw new PmCliError("--doc requires path=<value>", EXIT_CODE.USAGE);
+  }
+  const doc = { path: fields.path };
+  if (fields.scope === "global" || fields.scope === "project")
+    doc.scope = fields.scope;
+  if (fields.note)
+    doc.note = fields.note;
+  return doc;
+}
+function summarizeSteps(steps) {
+  const summary = {
+    total: steps.length,
+    pending: 0,
+    in_progress: 0,
+    blocked: 0,
+    completed: 0,
+    skipped: 0,
+    superseded: 0,
+    completion_pct: 0
+  };
+  for (const step of steps) {
+    summary[step.status] += 1;
+  }
+  summary.completion_pct = planCompletionPct(summary.completed, summary.total);
+  return summary;
+}
+function newStepId(existing) {
+  const used = new Set(existing.map((step) => step.id));
+  for (let cursor = existing.length + 1; cursor < existing.length + 1024; cursor += 1) {
+    const candidate = `${STEP_ID_PREFIX}${String(cursor).padStart(3, "0")}`;
+    if (!used.has(candidate))
+      return candidate;
+  }
+  throw new PmCliError("Could not allocate step id (limit reached)", EXIT_CODE.GENERIC_FAILURE);
+}
+function resolveStepRef(steps, ref) {
+  const trimmed = ref.trim();
+  if (trimmed.length === 0) {
+    throw new PmCliError("Step reference cannot be empty", EXIT_CODE.USAGE);
+  }
+  const direct = steps.find((step) => step.id === trimmed);
+  if (direct)
+    return direct;
+  if (/^\d+$/.test(trimmed)) {
+    const order = Number.parseInt(trimmed, 10);
+    const byOrder = steps.find((step) => step.order === order);
+    if (byOrder)
+      return byOrder;
+  }
+  throw new PmCliError(`Step "${ref}" not found in plan`, EXIT_CODE.NOT_FOUND);
+}
+function classifyMaterializeSkip(step) {
+  if (step.status === "completed") {
+    return { reason: "already_completed" };
+  }
+  const existingImplements = (step.linked_items ?? []).find((link) => link.kind === "implements");
+  if (existingImplements) {
+    return { reason: "already_materialized", existing_id: existingImplements.id };
+  }
+  return void 0;
+}
+function resolveMaterializeTargets(steps, refs) {
+  const allRefs = refs.filter((ref) => ref.trim().toLowerCase() === "all");
+  const targets = [];
+  const skipped = [];
+  if (allRefs.length > 0) {
+    if (refs.length > allRefs.length) {
+      throw new PmCliError("pm plan materialize --steps all cannot be combined with other step refs", EXIT_CODE.USAGE);
+    }
+    for (const step of steps.slice().sort((left, right) => left.order - right.order)) {
+      const skip = classifyMaterializeSkip(step);
+      if (skip) {
+        skipped.push({ from_step: step.id, ...skip });
+        continue;
+      }
+      targets.push(step);
+    }
+    return { targets, skipped };
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const ref of refs) {
+    const step = resolveStepRef(steps, ref);
+    if (seen.has(step.id))
+      continue;
+    seen.add(step.id);
+    const skip = classifyMaterializeSkip(step);
+    if (skip) {
+      skipped.push({ from_step: step.id, ...skip });
+      continue;
+    }
+    targets.push(step);
+  }
+  return { targets, skipped };
+}
+function resolvePlanLogText(kind, options) {
+  const canonical = kind === "decision" ? options.decisionText : kind === "discovery" ? options.discoveryText : options.validationText;
+  const shorthand = kind === "decision" ? options.decision : kind === "discovery" ? options.discovery : options.validation;
+  return canonical?.trim() || shorthand?.trim() || void 0;
+}
+function findCurrentStep(steps) {
+  return steps.find((step) => step.status === "in_progress") ?? steps.find((step) => step.status === "pending");
+}
+function blockedSteps(steps) {
+  return steps.filter((step) => step.status === "blocked").map((step) => ({ id: step.id, order: step.order, title: step.title, blocked_reason: step.blocked_reason }));
+}
+function projectPlan(item, depth = "brief") {
+  const steps = (item.plan_steps ?? []).slice().sort((left, right) => left.order - right.order);
+  const summary = summarizeSteps(steps);
+  const current = findCurrentStep(steps);
+  const projection = {
+    id: item.id,
+    title: item.title,
+    status: item.status,
+    mode: item.plan_mode ?? DEFAULT_PLAN_MODE,
+    scope: item.plan_scope,
+    harness: item.plan_harness,
+    parent: item.parent,
+    resume_context: item.plan_resume_context,
+    steps_summary: summary,
+    current_step: current ? { id: current.id, order: current.order, title: current.title, status: current.status } : void 0,
+    blocked_steps: blockedSteps(steps),
+    linked_items: (item.dependencies ?? []).map((dep) => ({ id: dep.id, kind: dep.kind }))
+  };
+  if (depth === "standard" || depth === "deep") {
+    projection.steps = steps;
+  }
+  if (depth === "deep") {
+    projection.decisions = item.plan_decisions ?? [];
+    projection.discoveries = item.plan_discoveries ?? [];
+    projection.validation = item.plan_validation ?? [];
+  }
+  return projection;
+}
+function nextActionsFor(planId, plan) {
+  const tips = [];
+  if (plan.steps_summary.total === 0) {
+    tips.push(`pm plan add-step ${planId} --step-title "First step"`);
+  }
+  if (plan.current_step) {
+    tips.push(`pm plan update-step ${planId} ${plan.current_step.id} --step-status in_progress`, `pm plan complete-step ${planId} ${plan.current_step.id} --step-evidence "..."`);
+  }
+  if (plan.steps_summary.blocked > 0) {
+    tips.push(`pm plan show ${planId} --depth standard`);
+  }
+  if (plan.mode === "draft" || plan.mode === "research") {
+    tips.push(`pm plan approve ${planId} --message "ready to execute"`);
+  }
+  if (plan.steps_summary.completed === plan.steps_summary.total && plan.steps_summary.total > 0) {
+    tips.push(`pm close ${planId} "plan complete"`);
+  }
+  return tips;
+}
+function ensurePlanItem(item) {
+  const normalizedType = (item.type ?? "").trim().toLowerCase();
+  if (normalizedType !== "plan") {
+    throw new PmCliError(`Item ${item.id} is type ${item.type}; pm plan commands require type=Plan. Use pm plan create or pm create --type Plan first.`, EXIT_CODE.USAGE, {
+      code: "wrong_item_type",
+      required: "Use pm plan commands only with items whose type is Plan.",
+      why: "Plan commands read and mutate Plan-specific step, decision, discovery, and validation fields.",
+      examples: [
+        `pm get ${item.id} --depth brief`,
+        'pm plan create --title "Execution plan" --scope "<goal>"'
+      ]
+    });
+  }
+}
+async function loadContext(global) {
+  const pmRoot = resolvePmRoot(process.cwd(), global.path);
+  if (!await pathExists(getSettingsPath(pmRoot))) {
+    throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
+  }
+  const settings = await readSettings(pmRoot);
+  return { pmRoot, settings };
+}
+async function readPlanItem(ctx, id) {
+  const typeRegistry = resolveItemTypeRegistry(ctx.settings, getActiveExtensionRegistrations());
+  const located = await locateItem(ctx.pmRoot, id, ctx.settings.id_prefix, ctx.settings.item_format, typeRegistry.type_to_folder);
+  if (!located) {
+    throw new PmCliError(`Plan ${id} not found`, EXIT_CODE.NOT_FOUND);
+  }
+  const loaded = await readLocatedItem(located, { schema: ctx.settings.schema });
+  ensurePlanItem(loaded.document.metadata);
+  return { document: loaded.document, itemId: located.id };
+}
+function buildPlanCreateDependencies(options) {
+  const deps = [];
+  if (options.parent) {
+    deps.push(`id=${options.parent.trim()},kind=parent`);
+  }
+  for (const ref of toArray(options.related))
+    deps.push(`id=${ref},kind=related`);
+  for (const ref of toArray(options.blocks))
+    deps.push(`id=${ref},kind=blocks`);
+  for (const ref of toArray(options.blockedBy))
+    deps.push(`id=${ref},kind=blocked_by`);
+  return deps.length > 0 ? deps : void 0;
+}
+function buildInitialValidation(options) {
+  const text = options.validationText?.trim();
+  const command = options.validationCommand?.trim();
+  const expected = options.validationExpected?.trim();
+  if (!text && !command && !expected) {
+    return void 0;
+  }
+  return {
+    text: text || command || "Validation check",
+    command: command || void 0,
+    expected: expected || void 0
+  };
+}
+function hasPlanStepDetailOptions(options) {
+  return Boolean(options.stepBody?.trim()) || Boolean(options.stepOwner?.trim()) || Boolean(options.stepStatus?.trim()) || Boolean(options.stepEvidence?.trim()) || Boolean(options.stepBlockedReason?.trim()) || Boolean(options.stepReplacement?.trim()) || toArray(options.dependsOn).length > 0 || toArray(options.link).length > 0 || toSpecArray(options.file).length > 0 || toSpecArray(options.test).length > 0 || toSpecArray(options.doc).length > 0;
+}
+function resolveInitialStepSeed(options) {
+  const stepTitleFlag = options.stepTitle?.trim() || void 0;
+  const repeatedStepTitles = toOrderedStepTitles(options.step);
+  const templateSteps = options.template?.trim() ? resolvePlanTemplateSteps(options.template) : [];
+  return {
+    repeatedStepTitles,
+    stepTitleFlag,
+    stepTitles: [
+      ...stepTitleFlag ? [stepTitleFlag] : [],
+      ...repeatedStepTitles,
+      ...templateSteps.map((step) => step.title)
+    ],
+    templateSteps
+  };
+}
+function assertInitialStepSeedAllowed(seed, hasPerStepDetailOptions) {
+  if ((seed.stepTitleFlag || seed.repeatedStepTitles.length > 0) && seed.templateSteps.length > 0) {
+    throw new PmCliError("pm plan create --template cannot be combined with --step-title or --step; choose one step seeding source", EXIT_CODE.USAGE, {
+      code: "ambiguous_option_combination",
+      examples: [
+        `pm plan create --title "Fix login crash" --template ${PLAN_TEMPLATE_NAMES[0]}`,
+        'pm plan create --title "Custom plan" --step "Read the code" --step "Write the fix"'
+      ]
+    });
+  }
+  if (seed.stepTitles.length > 1 && hasPerStepDetailOptions) {
+    throw new PmCliError("pm plan create per-step options apply to a single initial step; with multiple --step values create the plan first, then refine steps individually", EXIT_CODE.USAGE, {
+      code: "ambiguous_option_combination",
+      examples: [
+        'pm plan create --title "Execution plan" --step "Read the code" --step "Write the fix"',
+        'pm plan update-step <plan-id> plan-step-001 --step-body "Inspect retry path"'
+      ]
+    });
+  }
+}
+function buildSingleInitialStep(options, title) {
+  const status = asStepStatus(options.stepStatus, "pending");
+  const linkedItems = buildLinkInputs(options, "depends_on");
+  const files = toSpecArray(options.file).map(parseStepFile);
+  const tests = toSpecArray(options.test).map(parseStepTest);
+  const docs = toSpecArray(options.doc).map(parseStepDoc);
+  const now = nowIso();
+  return {
+    id: "plan-step-001",
+    order: 1,
+    title,
+    body: options.stepBody?.trim() || void 0,
+    status,
+    owner: options.stepOwner?.trim() || void 0,
+    evidence: options.stepEvidence?.trim() || void 0,
+    blocked_reason: status === "blocked" ? options.stepBlockedReason?.trim() || "" : void 0,
+    linked_items: linkedItems.length > 0 ? linkedItems : void 0,
+    files: files.length > 0 ? files : void 0,
+    tests: tests.length > 0 ? tests : void 0,
+    docs: docs.length > 0 ? docs : void 0,
+    created_at: now,
+    updated_at: now,
+    completed_at: status === "completed" ? now : void 0
+  };
+}
+function buildInitialSteps(options) {
+  const seed = resolveInitialStepSeed(options);
+  const hasDetailOptions = hasPlanStepDetailOptions(options);
+  assertInitialStepSeedAllowed(seed, hasDetailOptions);
+  if (seed.stepTitles.length === 0) {
+    return { steps: [], hasPerStepDetailOptions: hasDetailOptions };
+  }
+  if (seed.stepTitles.length === 1) {
+    return { steps: [buildSingleInitialStep(options, seed.stepTitles[0])], hasPerStepDetailOptions: hasDetailOptions };
+  }
+  const now = nowIso();
+  return {
+    steps: seed.stepTitles.map((stepTitle, index) => ({
+      id: `${STEP_ID_PREFIX}${String(index + 1).padStart(3, "0")}`,
+      order: index + 1,
+      title: stepTitle,
+      body: seed.templateSteps[index]?.body,
+      status: "pending",
+      created_at: now,
+      updated_at: now
+    })),
+    hasPerStepDetailOptions: hasDetailOptions
+  };
+}
+async function planCreate(options, global, ctx) {
+  const title = options.title?.trim();
+  if (!title) {
+    throw new PmCliError("pm plan create requires --title", EXIT_CODE.USAGE, {
+      code: "missing_required_option",
+      examples: ['pm plan create --title "Refactor lock retry" --scope pm-a1b2']
+    });
+  }
+  const mode = asPlanMode(options.mode, DEFAULT_PLAN_MODE);
+  const harness = asHarness(options.harness);
+  const fromSearch = options.fromSearch?.trim();
+  const description = options.description?.trim() ?? options.scope?.trim() ?? title;
+  const createOptions = {
+    title,
+    description,
+    type: "Plan",
+    body: options.body,
+    tags: options.tags,
+    priority: options.priority,
+    parent: options.parent,
+    dep: buildPlanCreateDependencies(options),
+    author: options.author,
+    message: options.message ?? (fromSearch ? `plan create (search: ${fromSearch})` : `plan create`)
+  };
+  const createResult = await runCreate(createOptions, global);
+  const seedResult = await mutateItem({
+    pmRoot: ctx.pmRoot,
+    settings: ctx.settings,
+    id: createResult.item.id,
+    op: "plan_create_metadata",
+    author: resolveAuthor(options.author, ctx.settings.author_default),
+    message: "seed plan metadata",
+    mutate(doc) {
+      const changed = [];
+      doc.metadata.plan_mode = mode;
+      changed.push("plan_mode");
+      if (harness) {
+        doc.metadata.plan_harness = harness;
+        changed.push("plan_harness");
+      }
+      if (options.scope?.trim()) {
+        doc.metadata.plan_scope = options.scope.trim();
+        changed.push("plan_scope");
+      }
+      if (options.resumeContext?.trim()) {
+        doc.metadata.plan_resume_context = options.resumeContext.trim();
+        changed.push("plan_resume_context");
+      }
+      doc.metadata.plan_steps = doc.metadata.plan_steps ?? [];
+      return { changedFields: changed };
+    }
+  });
+  let finalMetadata = seedResult.item;
+  let initialStep;
+  const initialValidation = buildInitialValidation(options);
+  const { steps: initialSteps, hasPerStepDetailOptions } = buildInitialSteps(options);
+  if (initialSteps.length > 0) {
+    initialStep = initialSteps[0];
+    const stepped = await mutateItem({
+      pmRoot: ctx.pmRoot,
+      settings: ctx.settings,
+      id: createResult.item.id,
+      op: "plan_create_initial_step",
+      author: resolveAuthor(options.author, ctx.settings.author_default),
+      message: initialSteps.length === 1 ? `plan create initial step "${initialSteps[0].title}"` : `plan create ${initialSteps.length} initial steps`,
+      mutate(doc) {
+        ensurePlanItem(doc.metadata);
+        doc.metadata.plan_steps = initialSteps;
+        if (initialValidation) {
+          doc.metadata.plan_validation = [...doc.metadata.plan_validation ?? [], initialValidation];
+        }
+        return { changedFields: initialValidation ? ["plan_steps", "plan_validation"] : ["plan_steps"] };
+      }
+    });
+    finalMetadata = stepped.item;
+  } else if (initialValidation) {
+    const validated = await mutateItem({
+      pmRoot: ctx.pmRoot,
+      settings: ctx.settings,
+      id: createResult.item.id,
+      op: "plan_create_initial_validation",
+      author: resolveAuthor(options.author, ctx.settings.author_default),
+      message: "plan create initial validation",
+      mutate(doc) {
+        ensurePlanItem(doc.metadata);
+        doc.metadata.plan_validation = [...doc.metadata.plan_validation ?? [], initialValidation];
+        return { changedFields: ["plan_validation"] };
+      }
+    });
+    finalMetadata = validated.item;
+  } else if (hasPerStepDetailOptions) {
+    throw new PmCliError("pm plan create step options require --step-title (or a single --step)", EXIT_CODE.USAGE, {
+      code: "missing_required_option",
+      examples: ['pm plan create --title "Execution plan" --step-title "Read the code"']
+    });
+  }
+  if (options.claim) {
+    const claimed = await mutateItem({
+      pmRoot: ctx.pmRoot,
+      settings: ctx.settings,
+      id: createResult.item.id,
+      op: "claim",
+      author: resolveAuthor(options.author, ctx.settings.author_default),
+      message: "plan claim by author",
+      mutate(doc) {
+        doc.metadata.assignee = resolveAuthor(options.author, ctx.settings.author_default);
+        return { changedFields: ["assignee"] };
+      }
+    });
+    finalMetadata = claimed.item;
+  }
+  const plan = projectPlan(finalMetadata, "brief");
+  return {
+    action: "create",
+    plan,
+    step: initialStep,
+    next_actions: nextActionsFor(createResult.item.id, plan),
+    warnings: [...createResult.warnings],
+    generated_at: nowIso()
+  };
+}
+async function planShow(id, options, ctx) {
+  const depth = asDepth(options.depth);
+  const fields = parsePlanFields(options.fields);
+  const { document, itemId } = await readPlanItem(ctx, id);
+  const fullPlan = projectPlan(document.metadata, fields === null ? depth : "deep");
+  const plan = fields === null ? fullPlan : projectPlanForFields(fullPlan, fields);
+  return {
+    action: "show",
+    plan,
+    next_actions: nextActionsFor(itemId, fullPlan),
+    warnings: [],
+    generated_at: nowIso()
+  };
+}
+async function mutatePlanSteps(args) {
+  const author = resolveAuthor(args.options.author, args.ctx.settings.author_default);
+  let resultStep;
+  const result = await mutateItem({
+    pmRoot: args.ctx.pmRoot,
+    settings: args.ctx.settings,
+    id: args.id,
+    op: args.op,
+    author,
+    message: args.options.message ?? args.message,
+    force: args.options.force,
+    mutate(doc) {
+      ensurePlanItem(doc.metadata);
+      const steps = (doc.metadata.plan_steps ?? []).slice();
+      const before = JSON.stringify(steps);
+      const outcome = args.mutator(steps, doc);
+      resultStep = outcome.resultStep;
+      const sorted = steps.slice().sort((left, right) => left.order - right.order).map((step, index) => ({ ...step, order: index + 1 }));
+      doc.metadata.plan_steps = sorted;
+      const after = JSON.stringify(sorted);
+      const changedFields = before === after ? [] : ["plan_steps"];
+      if (changedFields.length === 0 && outcome.changedSteps.length === 0) {
+        return { changedFields: [] };
+      }
+      return { changedFields: changedFields.length > 0 ? changedFields : ["plan_steps"] };
+    }
+  });
+  return {
+    document: { metadata: result.item, body: result.body },
+    resultStep,
+    itemId: result.item.id
+  };
+}
+async function planAddStep(id, options, ctx) {
+  const title = options.stepTitle?.trim();
+  if (!title) {
+    throw new PmCliError("pm plan add-step requires --step-title", EXIT_CODE.USAGE);
+  }
+  const status = asStepStatus(options.stepStatus, "pending");
+  const allowMultipleActive = options.allowMultipleActive === true;
+  const { document, resultStep, itemId } = await mutatePlanSteps({
+    id,
+    options,
+    ctx,
+    op: "plan_add_step",
+    message: `plan add-step "${title}"`,
+    mutator(steps) {
+      const order = steps.length + 1;
+      assertInProgressStepAllowed(steps, void 0, status, allowMultipleActive);
+      const step = buildAddedPlanStep(steps, options, { order, title, status });
+      steps.push(step);
+      return { changedSteps: [step.id], resultStep: step };
+    }
+  });
+  const plan = projectPlan(document.metadata, "standard");
+  return {
+    action: "add-step",
+    plan,
+    step: resultStep,
+    next_actions: nextActionsFor(itemId, plan),
+    warnings: [],
+    generated_at: nowIso()
+  };
+}
+function assertInProgressStepAllowed(steps, currentStepId, desiredStatus, allowMultipleActive) {
+  if (desiredStatus !== "in_progress" || allowMultipleActive) {
+    return;
+  }
+  const activeStep = steps.find((step) => step.id !== currentStepId && step.status === "in_progress");
+  if (!activeStep) {
+    return;
+  }
+  throw new PmCliError(`Plan already has step ${activeStep.id} in_progress. Pass --allow-multiple-active or update that step first.`, EXIT_CODE.CONFLICT);
+}
+function buildAddedPlanStep(existingSteps, options, seed) {
+  const linkedItems = buildLinkInputs(options, "depends_on");
+  const files = toSpecArray(options.file).map(parseStepFile);
+  const tests = toSpecArray(options.test).map(parseStepTest);
+  const docs = toSpecArray(options.doc).map(parseStepDoc);
+  const now = nowIso();
+  return {
+    id: newStepId(existingSteps),
+    order: seed.order,
+    title: seed.title,
+    body: options.stepBody?.trim() || void 0,
+    status: seed.status,
+    owner: options.stepOwner?.trim() || void 0,
+    evidence: options.stepEvidence?.trim() || void 0,
+    blocked_reason: seed.status === "blocked" ? options.stepBlockedReason?.trim() || "" : void 0,
+    linked_items: linkedItems.length > 0 ? linkedItems : void 0,
+    files: files.length > 0 ? files : void 0,
+    tests: tests.length > 0 ? tests : void 0,
+    docs: docs.length > 0 ? docs : void 0,
+    created_at: now,
+    updated_at: now,
+    completed_at: seed.status === "completed" ? now : void 0
+  };
+}
+function buildLinkInputs(options, fallbackKind) {
+  const dependsOn = toArray(options.dependsOn).map((id) => ({ id, kind: fallbackKind }));
+  const related = toArray(options.related).map((id) => ({ id, kind: "related" }));
+  const blocks = toArray(options.blocks).map((id) => ({ id, kind: "blocks" }));
+  const blockedBy = toArray(options.blockedBy).map((id) => ({ id, kind: "blocked_by" }));
+  const explicit = toArray(options.link);
+  const explicitKind = asLinkKind(options.linkKind, fallbackKind);
+  const note = options.linkNote?.trim();
+  const explicitLinks = explicit.map((id) => {
+    const link = { id, kind: explicitKind };
+    if (note)
+      link.note = note;
+    return link;
+  });
+  return [...dependsOn, ...related, ...blocks, ...blockedBy, ...explicitLinks];
+}
+async function planUpdateStep(id, options, ctx, args) {
+  const { document, resultStep, itemId } = await mutatePlanSteps({
+    id,
+    options,
+    ctx,
+    op: args.op,
+    message: options.message ?? `${args.op} ${args.stepRef}`,
+    mutator(steps, doc) {
+      const step = resolveStepRef(steps, args.stepRef);
+      const now = nowIso();
+      const desiredStatus = args.finalStatus ?? asStepStatus(options.stepStatus, step.status);
+      const allowMultipleActive = options.allowMultipleActive === true || args.allowMultipleActive === true;
+      assertInProgressStepAllowed(steps, step.status === "in_progress" ? step.id : void 0, desiredStatus, allowMultipleActive);
+      applyStepUpdates(step, options, desiredStatus, now);
+      doc.metadata.updated_at = now;
+      return { changedSteps: [step.id], resultStep: step };
+    }
+  });
+  const plan = projectPlan(document.metadata, "standard");
+  return {
+    action: args.op === "plan_complete_step" ? "complete-step" : args.op === "plan_block_step" ? "block-step" : "update-step",
+    plan,
+    step: resultStep,
+    next_actions: nextActionsFor(itemId, plan),
+    warnings: [],
+    generated_at: nowIso()
+  };
+}
+function applyStepUpdates(step, options, desiredStatus, now) {
+  assertBlockedStepReason(step, options, desiredStatus);
+  applyStepFieldUpdates(step, options);
+  step.status = desiredStatus;
+  step.updated_at = now;
+  applyStepCompletionTimestamp(step, desiredStatus, now);
+}
+function assertBlockedStepReason(step, options, desiredStatus) {
+  if (desiredStatus !== "blocked" || options.stepBlockedReason?.trim() || step.blocked_reason) {
+    return;
+  }
+  throw new PmCliError("Blocking a step requires --step-blocked-reason or an already-recorded blocked_reason.", EXIT_CODE.USAGE);
+}
+function applyStepFieldUpdates(step, options) {
+  const title = options.stepTitle?.trim();
+  if (title) {
+    step.title = title;
+  }
+  if (options.stepBody !== void 0) {
+    step.body = options.stepBody.trim() || void 0;
+  }
+  if (options.stepOwner !== void 0) {
+    step.owner = options.stepOwner.trim() || void 0;
+  }
+  if (options.stepEvidence !== void 0) {
+    step.evidence = options.stepEvidence.trim() || void 0;
+  }
+  if (options.stepBlockedReason !== void 0) {
+    step.blocked_reason = options.stepBlockedReason.trim() || void 0;
+  }
+  if (options.stepReplacement !== void 0) {
+    step.superseded_by = options.stepReplacement.trim() || void 0;
+  }
+}
+function applyStepCompletionTimestamp(step, desiredStatus, now) {
+  if (desiredStatus === "completed" && !step.completed_at) {
+    step.completed_at = now;
+    return;
+  }
+  if (desiredStatus !== "completed") {
+    step.completed_at = void 0;
+  }
+}
+async function planReorderStep(id, options, ctx, stepRef, newOrder) {
+  const { document, itemId } = await mutatePlanSteps({
+    id,
+    options,
+    ctx,
+    op: "plan_reorder_step",
+    message: options.message ?? `plan reorder-step ${stepRef} -> ${newOrder}`,
+    mutator(steps) {
+      const step = resolveStepRef(steps, stepRef);
+      const filtered = steps.filter((entry) => entry.id !== step.id);
+      const clamped = Math.max(1, Math.min(newOrder, filtered.length + 1));
+      filtered.splice(clamped - 1, 0, step);
+      filtered.forEach((entry, index) => {
+        entry.order = index + 1;
+        entry.updated_at = nowIso();
+      });
+      steps.length = 0;
+      steps.push(...filtered);
+      return { changedSteps: [step.id], resultStep: step };
+    }
+  });
+  const plan = projectPlan(document.metadata, "standard");
+  return {
+    action: "reorder-step",
+    plan,
+    next_actions: nextActionsFor(itemId, plan),
+    warnings: [],
+    generated_at: nowIso()
+  };
+}
+async function planRemoveStep(id, options, ctx, stepRef) {
+  const { document, itemId } = await mutatePlanSteps({
+    id,
+    options,
+    ctx,
+    op: "plan_remove_step",
+    message: options.message ?? `plan remove-step ${stepRef}`,
+    mutator(steps) {
+      const step = resolveStepRef(steps, stepRef);
+      const remaining = steps.filter((entry) => entry.id !== step.id);
+      remaining.forEach((entry, index) => {
+        entry.order = index + 1;
+      });
+      steps.length = 0;
+      steps.push(...remaining);
+      return { changedSteps: [step.id] };
+    }
+  });
+  const plan = projectPlan(document.metadata, "standard");
+  return {
+    action: "remove-step",
+    plan,
+    next_actions: nextActionsFor(itemId, plan),
+    warnings: [],
+    generated_at: nowIso()
+  };
+}
+async function planLink(id, options, ctx, stepRef) {
+  const newLinks = buildLinkInputs(options, asLinkKind(options.linkKind, "related"));
+  if (newLinks.length === 0) {
+    throw new PmCliError("pm plan link requires at least one --link/--related/--blocks/--blocked-by/--depends-on id", EXIT_CODE.USAGE);
+  }
+  const promoteToItemDep = options.promoteToItemDep === true;
+  const { document, itemId, resultStep } = await mutatePlanSteps({
+    id,
+    options,
+    ctx,
+    op: "plan_link_step",
+    message: options.message ?? `plan link ${stepRef}`,
+    mutator(steps, doc) {
+      const step = resolveStepRef(steps, stepRef);
+      const existing = step.linked_items ?? [];
+      const dedupKey = (link) => `${link.kind}:${link.id}`;
+      const seen = new Set(existing.map(dedupKey));
+      for (const link of newLinks) {
+        const key = dedupKey(link);
+        if (seen.has(key))
+          continue;
+        existing.push(link);
+        seen.add(key);
+      }
+      step.linked_items = existing;
+      step.updated_at = nowIso();
+      if (promoteToItemDep) {
+        const deps = doc.metadata.dependencies ?? [];
+        const depKey = (dep) => `${dep.kind}:${dep.id}`;
+        const seenDeps = new Set(deps.map(depKey));
+        for (const link of newLinks) {
+          const candidate = {
+            id: link.id,
+            kind: link.kind,
+            created_at: nowIso(),
+            author: resolveAuthor(options.author, ctx.settings.author_default)
+          };
+          if (seenDeps.has(depKey(candidate)))
+            continue;
+          deps.push(candidate);
+          seenDeps.add(depKey(candidate));
+        }
+        doc.metadata.dependencies = deps;
+      }
+      return { changedSteps: [step.id], resultStep: step };
+    }
+  });
+  const plan = projectPlan(document.metadata, "standard");
+  return {
+    action: "link",
+    plan,
+    step: resultStep,
+    next_actions: nextActionsFor(itemId, plan),
+    warnings: [],
+    generated_at: nowIso()
+  };
+}
+async function planUnlink(id, options, ctx, stepRef) {
+  const removeIds = toArray(options.link);
+  if (removeIds.length === 0) {
+    throw new PmCliError("pm plan unlink requires --link <id> to remove", EXIT_CODE.USAGE);
+  }
+  const { document, itemId, resultStep } = await mutatePlanSteps({
+    id,
+    options,
+    ctx,
+    op: "plan_unlink_step",
+    message: options.message ?? `plan unlink ${stepRef}`,
+    mutator(steps) {
+      const step = resolveStepRef(steps, stepRef);
+      const filtered = (step.linked_items ?? []).filter((link) => !removeIds.includes(link.id));
+      step.linked_items = filtered.length > 0 ? filtered : void 0;
+      step.updated_at = nowIso();
+      return { changedSteps: [step.id], resultStep: step };
+    }
+  });
+  const plan = projectPlan(document.metadata, "standard");
+  return {
+    action: "unlink",
+    plan,
+    step: resultStep,
+    next_actions: nextActionsFor(itemId, plan),
+    warnings: [],
+    generated_at: nowIso()
+  };
+}
+async function planAppendLog(id, options, ctx, kind) {
+  const logText = resolvePlanLogText(kind, options);
+  if (!logText) {
+    const canonical = `--${kind}-text`;
+    const shorthand = `--${kind}`;
+    throw new PmCliError(`pm plan ${kind} requires ${canonical}`, EXIT_CODE.USAGE, {
+      code: "missing_required_option",
+      examples: [
+        `pm plan ${kind} <plan-id> ${canonical} "..."`,
+        `pm plan ${kind} <plan-id> ${shorthand} "..."`
+      ],
+      recovery: {
+        suggested_retry: `pm plan ${kind} <plan-id> ${canonical} <value>`
+      }
+    });
+  }
+  const author = resolveAuthor(options.author, ctx.settings.author_default);
+  const { document, itemId } = await mutatePlanSteps({
+    id,
+    options,
+    ctx,
+    op: `plan_append_${kind}`,
+    message: options.message ?? `plan ${kind} append`,
+    mutator(_steps, doc) {
+      const now = nowIso();
+      if (kind === "decision") {
+        const list2 = doc.metadata.plan_decisions ?? [];
+        list2.push({
+          ts: now,
+          author,
+          decision: logText,
+          rationale: options.decisionRationale?.trim() || void 0,
+          evidence: options.decisionEvidence?.trim() || void 0
+        });
+        doc.metadata.plan_decisions = list2;
+        return { changedSteps: [] };
+      }
+      if (kind === "discovery") {
+        const list2 = doc.metadata.plan_discoveries ?? [];
+        list2.push({ ts: now, author, text: logText });
+        doc.metadata.plan_discoveries = list2;
+        return { changedSteps: [] };
+      }
+      const list = doc.metadata.plan_validation ?? [];
+      list.push({
+        text: logText,
+        command: options.validationCommand?.trim() || void 0,
+        expected: options.validationExpected?.trim() || void 0
+      });
+      doc.metadata.plan_validation = list;
+      return { changedSteps: [] };
+    }
+  });
+  const plan = projectPlan(document.metadata, "deep");
+  return {
+    action: kind,
+    plan,
+    next_actions: nextActionsFor(itemId, plan),
+    warnings: [],
+    generated_at: nowIso()
+  };
+}
+async function planResume(id, options, ctx) {
+  const text = options.resumeContext?.trim();
+  if (!text) {
+    throw new PmCliError("pm plan resume requires --resume-context <text>", EXIT_CODE.USAGE);
+  }
+  const { document, itemId } = await mutatePlanSteps({
+    id,
+    options,
+    ctx,
+    op: "plan_resume",
+    message: options.message ?? "plan resume context update",
+    mutator(_steps, doc) {
+      doc.metadata.plan_resume_context = text;
+      return { changedSteps: [] };
+    }
+  });
+  const plan = projectPlan(document.metadata, "brief");
+  return {
+    action: "resume",
+    plan,
+    next_actions: nextActionsFor(itemId, plan),
+    warnings: [],
+    generated_at: nowIso()
+  };
+}
+async function planApprove(id, options, ctx) {
+  const mode = asPlanMode(options.mode ?? "approved", "approved");
+  const { document, itemId } = await mutatePlanSteps({
+    id,
+    options,
+    ctx,
+    op: "plan_approve",
+    message: options.message ?? `plan approve mode=${mode}`,
+    mutator(_steps, doc) {
+      doc.metadata.plan_mode = mode;
+      return { changedSteps: [] };
+    }
+  });
+  const plan = projectPlan(document.metadata, "brief");
+  return {
+    action: "approve",
+    plan,
+    next_actions: nextActionsFor(itemId, plan),
+    warnings: [],
+    generated_at: nowIso()
+  };
+}
+function buildMaterializeSkippedWarnings(materializeSkipped) {
+  return materializeSkipped.map((entry) => `plan_materialize_skipped:${entry.from_step}:${entry.reason}${entry.existing_id ? `:${entry.existing_id}` : ""}`);
+}
+function buildMaterializeNoopResult(planRead, materializeSkipped) {
+  const plan = projectPlan(planRead.document.metadata, "standard");
+  return {
+    action: "materialize",
+    plan,
+    materialized: [],
+    materialize_skipped: materializeSkipped,
+    next_actions: nextActionsFor(planRead.itemId, plan),
+    warnings: buildMaterializeSkippedWarnings(materializeSkipped),
+    generated_at: nowIso()
+  };
+}
+function buildMaterializeDependencies(parent, planItemId, step) {
+  const deps = [
+    `id=${parent},kind=parent`,
+    `id=${planItemId},kind=discovered_from`
+  ];
+  for (const link of step.linked_items ?? []) {
+    const realKind = link.kind === "blocked_by" || link.kind === "blocks" || link.kind === "related" || link.kind === "discovered_from" ? link.kind : "related";
+    deps.push(`id=${link.id},kind=${realKind}`);
+  }
+  return deps;
+}
+async function createMaterializedStepItems(params) {
+  const materialized = [];
+  for (const step of params.targets) {
+    const created = await runCreate({
+      title: step.title,
+      description: step.body?.trim() || step.title,
+      type: params.resolvedTypeName,
+      parent: params.parent,
+      tags: params.tags,
+      author: params.options.author,
+      message: params.options.message ?? `materialized from plan ${params.planItemId} step ${step.id}`,
+      dep: buildMaterializeDependencies(params.parent, params.planItemId, step)
+    }, { ...{}, path: params.pmRoot });
+    materialized.push({ id: created.item.id, type: params.resolvedTypeName, from_step: step.id });
+  }
+  return materialized;
+}
+function linkMaterializedStepItems(currentSteps, targets, materialized) {
+  for (const target of targets) {
+    const matched = materialized.find((entry) => entry.from_step === target.id);
+    if (!matched) {
+      continue;
+    }
+    const step = currentSteps.find((entry) => entry.id === target.id);
+    if (!step) {
+      continue;
+    }
+    const links = step.linked_items ?? [];
+    links.push({ id: matched.id, kind: "implements", note: `materialized as ${matched.type}` });
+    step.linked_items = links;
+    step.updated_at = nowIso();
+  }
+}
+async function planMaterialize(id, options, ctx) {
+  const stepRefs = toArray(options.steps);
+  if (stepRefs.length === 0) {
+    throw new PmCliError("pm plan materialize requires --steps <ids|orders|all>", EXIT_CODE.USAGE);
+  }
+  const targetType = options.materializeType?.trim() || "Task";
+  const typeRegistry = resolveItemTypeRegistry(ctx.settings, getActiveExtensionRegistrations());
+  const resolvedTypeName = resolveTypeName(targetType, typeRegistry);
+  if (!resolvedTypeName) {
+    throw new PmCliError(`Invalid --materialize-type "${targetType}"`, EXIT_CODE.USAGE);
+  }
+  const parent = options.materializeParent?.trim() || id;
+  const tags = options.materializeTags;
+  const planRead = await readPlanItem(ctx, id);
+  const steps = (planRead.document.metadata.plan_steps ?? []).slice();
+  const { targets, skipped: materializeSkipped } = resolveMaterializeTargets(steps, stepRefs);
+  if (targets.length === 0) {
+    if (materializeSkipped.length > 0) {
+      return buildMaterializeNoopResult(planRead, materializeSkipped);
+    }
+    throw new PmCliError("No matching plan steps found for --steps", EXIT_CODE.NOT_FOUND);
+  }
+  const materialized = await createMaterializedStepItems({
+    targets,
+    parent,
+    planItemId: planRead.itemId,
+    resolvedTypeName,
+    tags,
+    options,
+    pmRoot: ctx.pmRoot
+  });
+  const { document, itemId } = await mutatePlanSteps({
+    id,
+    options,
+    ctx,
+    op: "plan_materialize",
+    message: options.message ?? `plan materialize ${stepRefs.join(",")}`,
+    mutator(currentSteps) {
+      linkMaterializedStepItems(currentSteps, targets, materialized);
+      return { changedSteps: targets.map((entry) => entry.id) };
+    }
+  });
+  const plan = projectPlan(document.metadata, "standard");
+  return {
+    action: "materialize",
+    plan,
+    materialized,
+    ...materializeSkipped.length > 0 ? { materialize_skipped: materializeSkipped } : {},
+    next_actions: nextActionsFor(itemId, plan),
+    warnings: buildMaterializeSkippedWarnings(materializeSkipped),
+    generated_at: nowIso()
+  };
+}
+function normalizePlanStepAliasInput(input) {
+  if (input.subcommand === "create") {
+    return input;
+  }
+  const stepValues = toOrderedStepTitles(input.options.step);
+  if (stepValues.length > 1) {
+    throw new PmCliError(`pm plan ${input.subcommand} accepts a single --step/--step-title value (repeated --step seeds ordered steps only on pm plan create)`, EXIT_CODE.USAGE);
+  }
+  if (stepValues.length === 1 && !input.options.stepTitle?.trim()) {
+    return { ...input, options: { ...input.options, stepTitle: stepValues[0] } };
+  }
+  return input;
+}
+function requirePlanId(input, label) {
+  if (!input.id) {
+    throw new PmCliError(`pm plan ${label} requires a plan id`, EXIT_CODE.USAGE);
+  }
+  return input.id;
+}
+function requirePlanStepRef(input, label) {
+  const id = requirePlanId(input, label);
+  if (!input.stepRef) {
+    throw new PmCliError(`pm plan ${label} requires <plan-id> <step>`, EXIT_CODE.USAGE);
+  }
+  return { id, stepRef: input.stepRef };
+}
+function requireReorderTarget(input) {
+  const target = requirePlanStepRef(input, "reorder-step");
+  if (input.reorderTo === void 0) {
+    throw new PmCliError("pm plan reorder-step requires <plan-id> <step> <new-order>", EXIT_CODE.USAGE);
+  }
+  return { ...target, reorderTo: input.reorderTo };
+}
+var PLAN_DISPATCHERS = {
+  create: (input, ctx) => planCreate(input.options, input.global, ctx),
+  show: (input, ctx) => planShow(requirePlanId(input, "show"), input.options, ctx),
+  "add-step": (input, ctx) => planAddStep(requirePlanId(input, "add-step"), input.options, ctx),
+  "update-step": (input, ctx) => {
+    const target = requirePlanStepRef(input, "update-step");
+    return planUpdateStep(target.id, input.options, ctx, { stepRef: target.stepRef, op: "plan_update_step" });
+  },
+  "complete-step": (input, ctx) => {
+    const target = requirePlanStepRef(input, "complete-step");
+    return planUpdateStep(target.id, input.options, ctx, {
+      stepRef: target.stepRef,
+      finalStatus: "completed",
+      op: "plan_complete_step"
+    });
+  },
+  "block-step": (input, ctx) => {
+    const target = requirePlanStepRef(input, "block-step");
+    return planUpdateStep(target.id, input.options, ctx, {
+      stepRef: target.stepRef,
+      finalStatus: "blocked",
+      op: "plan_block_step"
+    });
+  },
+  "reorder-step": (input, ctx) => {
+    const target = requireReorderTarget(input);
+    return planReorderStep(target.id, input.options, ctx, target.stepRef, target.reorderTo);
+  },
+  "remove-step": (input, ctx) => {
+    const target = requirePlanStepRef(input, "remove-step");
+    return planRemoveStep(target.id, input.options, ctx, target.stepRef);
+  },
+  link: (input, ctx) => {
+    const target = requirePlanStepRef(input, "link");
+    return planLink(target.id, input.options, ctx, target.stepRef);
+  },
+  unlink: (input, ctx) => {
+    const target = requirePlanStepRef(input, "unlink");
+    return planUnlink(target.id, input.options, ctx, target.stepRef);
+  },
+  decision: (input, ctx) => planAppendLog(requirePlanId(input, "decision"), input.options, ctx, "decision"),
+  discovery: (input, ctx) => planAppendLog(requirePlanId(input, "discovery"), input.options, ctx, "discovery"),
+  validation: (input, ctx) => planAppendLog(requirePlanId(input, "validation"), input.options, ctx, "validation"),
+  resume: (input, ctx) => planResume(requirePlanId(input, "resume"), input.options, ctx),
+  approve: (input, ctx) => planApprove(requirePlanId(input, "approve"), input.options, ctx),
+  materialize: (input, ctx) => planMaterialize(requirePlanId(input, "materialize"), input.options, ctx)
+};
+function resolvePlanDispatcher(subcommand) {
+  const dispatcher = PLAN_DISPATCHERS[subcommand];
+  if (!dispatcher) {
+    throw new PmCliError(`Unknown pm plan subcommand "${subcommand}"`, EXIT_CODE.USAGE);
+  }
+  return dispatcher;
+}
+async function runPlan(input) {
+  const ctx = await loadContext(input.global);
+  const normalizedInput = normalizePlanStepAliasInput(input);
+  return resolvePlanDispatcher(normalizedInput.subcommand)(normalizedInput, ctx);
+}
+
+export {
+  PLAN_SUBCOMMANDS,
+  PLAN_SHOW_DEPTH_VALUES,
+  PLAN_TEMPLATE_NAMES,
+  resolvePlanTemplateSteps,
+  runPlan
+};
+//# sourceMappingURL=chunk-HFDADVJZ.js.map
+
+//# debugId=b3ee81eb-626f-58f7-9a58-78d41be890a7