@unbrained/pm-cli 2026.7.1 → 2026.7.3

package/dist/cli/commands/plan.js

@@ -4,7 +4,7 @@
  * Implements the pm plan command surface and its agent-facing runtime behavior.
  */
 
-!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]="441230c4-0ce6-5c75-8fcb-3af1fc95a584")}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]="1e64f96b-b7e3-5228-839a-65a187cb7020")}catch(e){}}();
 import { pathExists } from "../../core/fs/fs-utils.js";
 import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
 import { resolveItemTypeRegistry, resolveTypeName } from "../../core/item/type-registry.js";
@@ -483,6 +483,129 @@ async function readPlanItem(ctx, id) {
     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 : undefined;
+}
+function buildInitialValidation(options) {
+    const text = options.validationText?.trim();
+    const command = options.validationCommand?.trim();
+    const expected = options.validationExpected?.trim();
+    if (!text && !command && !expected) {
+        return undefined;
+    }
+    return {
+        text: text || command || "Validation check",
+        command: command || undefined,
+        expected: expected || undefined,
+    };
+}
+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() || undefined;
+    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() || undefined,
+        status,
+        owner: options.stepOwner?.trim() || undefined,
+        evidence: options.stepEvidence?.trim() || undefined,
+        blocked_reason: status === "blocked" ? options.stepBlockedReason?.trim() || "" : undefined,
+        linked_items: linkedItems.length > 0 ? linkedItems : undefined,
+        files: files.length > 0 ? files : undefined,
+        tests: tests.length > 0 ? tests : undefined,
+        docs: docs.length > 0 ? docs : undefined,
+        created_at: now,
+        updated_at: now,
+        completed_at: status === "completed" ? now : undefined,
+    };
+}
+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) {
@@ -494,19 +617,6 @@ async function planCreate(options, global, ctx) {
     const mode = asPlanMode(options.mode, DEFAULT_PLAN_MODE);
     const harness = asHarness(options.harness);
     const fromSearch = options.fromSearch?.trim();
-    const related = toArray(options.related);
-    const blocks = toArray(options.blocks);
-    const blockedBy = toArray(options.blockedBy);
-    const deps = [];
-    if (options.parent) {
-        deps.push(`id=${options.parent.trim()},kind=parent`);
-    }
-    for (const ref of related)
-        deps.push(`id=${ref},kind=related`);
-    for (const ref of blocks)
-        deps.push(`id=${ref},kind=blocks`);
-    for (const ref of blockedBy)
-        deps.push(`id=${ref},kind=blocked_by`);
     const description = options.description?.trim() ?? options.scope?.trim() ?? title;
     const createOptions = {
         title,
@@ -516,7 +626,7 @@ async function planCreate(options, global, ctx) {
         tags: options.tags,
         priority: options.priority,
         parent: options.parent,
-        dep: deps.length > 0 ? deps : undefined,
+        dep: buildPlanCreateDependencies(options),
         author: options.author,
         message: options.message ?? (fromSearch ? `plan create (search: ${fromSearch})` : `plan create`),
     };
@@ -551,96 +661,8 @@ async function planCreate(options, global, ctx) {
     });
     let finalMetadata = seedResult.item;
     let initialStep;
-    const initialValidationText = options.validationText?.trim();
-    const initialValidationCommand = options.validationCommand?.trim();
-    const initialValidationExpected = options.validationExpected?.trim();
-    const initialValidation = initialValidationText || initialValidationCommand || initialValidationExpected
-        ? {
-            text: initialValidationText || initialValidationCommand || "Validation check",
-            command: initialValidationCommand || undefined,
-            expected: initialValidationExpected || undefined,
-        }
-        : undefined;
-    // pm-6mit: collect ordered initial-step titles. Mixed-usage semantics
-    // (documented on pm-6mit): --step-title (when present) is the FIRST step,
-    // followed by each repeated --step value in argv order.
-    const stepTitleFlag = options.stepTitle?.trim();
-    const repeatedStepTitles = toOrderedStepTitles(options.step);
-    const templateSteps = options.template?.trim() ? resolvePlanTemplateSteps(options.template) : [];
-    const stepTitles = [
-        ...(stepTitleFlag ? [stepTitleFlag] : []),
-        ...repeatedStepTitles,
-        ...templateSteps.map((step) => step.title),
-    ];
-    const hasPerStepDetailOptions = 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;
-    if ((stepTitleFlag || repeatedStepTitles.length > 0) && 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 (stepTitles.length > 1 && hasPerStepDetailOptions) {
-        // Per-step detail flags target exactly one step; silently attaching them to
-        // the first (or all) of several seeded steps would be unpredictable.
-        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"',
-            ],
-        });
-    }
-    let initialSteps = [];
-    if (stepTitles.length === 1) {
-        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();
-        initialSteps = [{
-                id: "plan-step-001",
-                order: 1,
-                title: stepTitles[0],
-                body: options.stepBody?.trim() || undefined,
-                status,
-                owner: options.stepOwner?.trim() || undefined,
-                evidence: options.stepEvidence?.trim() || undefined,
-                blocked_reason: status === "blocked" ? options.stepBlockedReason?.trim() || "" : undefined,
-                linked_items: linkedItems.length > 0 ? linkedItems : undefined,
-                files: files.length > 0 ? files : undefined,
-                tests: tests.length > 0 ? tests : undefined,
-                docs: docs.length > 0 ? docs : undefined,
-                created_at: now,
-                updated_at: now,
-                completed_at: status === "completed" ? now : undefined,
-            }];
-    }
-    else if (stepTitles.length > 1) {
-        const now = nowIso();
-        initialSteps = stepTitles.map((stepTitle, index) => ({
-            id: `${STEP_ID_PREFIX}${String(index + 1).padStart(3, "0")}`,
-            order: index + 1,
-            title: stepTitle,
-            body: templateSteps[index]?.body,
-            status: "pending",
-            created_at: now,
-            updated_at: now,
-        }));
-    }
+    const initialValidation = buildInitialValidation(options);
+    const { steps: initialSteps, hasPerStepDetailOptions } = buildInitialSteps(options);
     if (initialSteps.length > 0) {
         initialStep = initialSteps[0];
         const stepped = await mutateItem({
@@ -767,10 +789,6 @@ async function planAddStep(id, options, ctx) {
     }
     const status = asStepStatus(options.stepStatus, "pending");
     const allowMultipleActive = options.allowMultipleActive === true;
-    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 { document, resultStep, itemId } = await mutatePlanSteps({
         id,
         options,
@@ -779,31 +797,8 @@ async function planAddStep(id, options, ctx) {
         message: `plan add-step "${title}"`,
         mutator(steps) {
             const order = steps.length + 1;
-            if (status === "in_progress" && !allowMultipleActive) {
-                for (const step of steps) {
-                    if (step.status === "in_progress") {
-                        throw new PmCliError(`Plan already has step ${step.id} in_progress. Pass --allow-multiple-active or update that step first.`, EXIT_CODE.CONFLICT);
-                    }
-                }
-            }
-            const now = nowIso();
-            const step = {
-                id: newStepId(steps),
-                order,
-                title,
-                body: options.stepBody?.trim() || undefined,
-                status,
-                owner: options.stepOwner?.trim() || undefined,
-                evidence: options.stepEvidence?.trim() || undefined,
-                blocked_reason: status === "blocked" ? options.stepBlockedReason?.trim() || "" : undefined,
-                linked_items: linkedItems.length > 0 ? linkedItems : undefined,
-                files: files.length > 0 ? files : undefined,
-                tests: tests.length > 0 ? tests : undefined,
-                docs: docs.length > 0 ? docs : undefined,
-                created_at: now,
-                updated_at: now,
-                completed_at: status === "completed" ? now : undefined,
-            };
+            assertInProgressStepAllowed(steps, undefined, status, allowMultipleActive);
+            const step = buildAddedPlanStep(steps, options, { order, title, status });
             steps.push(step);
             return { changedSteps: [step.id], resultStep: step };
         },
@@ -818,6 +813,40 @@ async function planAddStep(id, options, ctx) {
         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() || undefined,
+        status: seed.status,
+        owner: options.stepOwner?.trim() || undefined,
+        evidence: options.stepEvidence?.trim() || undefined,
+        blocked_reason: seed.status === "blocked" ? options.stepBlockedReason?.trim() || "" : undefined,
+        linked_items: linkedItems.length > 0 ? linkedItems : undefined,
+        files: files.length > 0 ? files : undefined,
+        tests: tests.length > 0 ? tests : undefined,
+        docs: docs.length > 0 ? docs : undefined,
+        created_at: now,
+        updated_at: now,
+        completed_at: seed.status === "completed" ? now : undefined,
+    };
+}
 function buildLinkInputs(options, fallbackKind) {
     const dependsOn = toArray(options.dependsOn).map((id) => ({ id, kind: fallbackKind }));
     const related = toArray(options.related).map((id) => ({ id, kind: "related" }));
@@ -845,36 +874,9 @@ async function planUpdateStep(id, options, ctx, args) {
             const step = resolveStepRef(steps, args.stepRef);
             const now = nowIso();
             const desiredStatus = args.finalStatus ?? asStepStatus(options.stepStatus, step.status);
-            if (desiredStatus === "in_progress" && step.status !== "in_progress" && !options.allowMultipleActive && !args.allowMultipleActive) {
-                for (const other of steps) {
-                    if (other.id !== step.id && other.status === "in_progress") {
-                        throw new PmCliError(`Plan already has step ${other.id} in_progress. Pass --allow-multiple-active or update that step first.`, EXIT_CODE.CONFLICT);
-                    }
-                }
-            }
-            if (desiredStatus === "blocked" && !options.stepBlockedReason?.trim() && !step.blocked_reason) {
-                throw new PmCliError("Blocking a step requires --step-blocked-reason or an already-recorded blocked_reason.", EXIT_CODE.USAGE);
-            }
-            if (options.stepTitle?.trim())
-                step.title = options.stepTitle.trim();
-            if (options.stepBody !== undefined)
-                step.body = options.stepBody.trim() || undefined;
-            if (options.stepOwner !== undefined)
-                step.owner = options.stepOwner.trim() || undefined;
-            if (options.stepEvidence !== undefined)
-                step.evidence = options.stepEvidence.trim() || undefined;
-            if (options.stepBlockedReason !== undefined)
-                step.blocked_reason = options.stepBlockedReason.trim() || undefined;
-            if (options.stepReplacement !== undefined)
-                step.superseded_by = options.stepReplacement.trim() || undefined;
-            step.status = desiredStatus;
-            step.updated_at = now;
-            if (desiredStatus === "completed" && !step.completed_at) {
-                step.completed_at = now;
-            }
-            else if (desiredStatus !== "completed") {
-                step.completed_at = undefined;
-            }
+            const allowMultipleActive = options.allowMultipleActive === true || args.allowMultipleActive === true;
+            assertInProgressStepAllowed(steps, step.status === "in_progress" ? step.id : undefined, desiredStatus, allowMultipleActive);
+            applyStepUpdates(step, options, desiredStatus, now);
             doc.metadata.updated_at = now;
             return { changedSteps: [step.id], resultStep: step };
         },
@@ -889,6 +891,49 @@ async function planUpdateStep(id, options, ctx, args) {
         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 !== undefined) {
+        step.body = options.stepBody.trim() || undefined;
+    }
+    if (options.stepOwner !== undefined) {
+        step.owner = options.stepOwner.trim() || undefined;
+    }
+    if (options.stepEvidence !== undefined) {
+        step.evidence = options.stepEvidence.trim() || undefined;
+    }
+    if (options.stepBlockedReason !== undefined) {
+        step.blocked_reason = options.stepBlockedReason.trim() || undefined;
+    }
+    if (options.stepReplacement !== undefined) {
+        step.superseded_by = options.stepReplacement.trim() || undefined;
+    }
+}
+function applyStepCompletionTimestamp(step, desiredStatus, now) {
+    if (desiredStatus === "completed" && !step.completed_at) {
+        step.completed_at = now;
+        return;
+    }
+    if (desiredStatus !== "completed") {
+        step.completed_at = undefined;
+    }
+}
 async function planReorderStep(id, options, ctx, stepRef, newOrder) {
     const { document, itemId } = await mutatePlanSteps({
         id,
@@ -1141,6 +1186,67 @@ async function planApprove(id, options, ctx) {
         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) {
@@ -1159,68 +1265,27 @@ async function planMaterialize(id, options, ctx) {
     const { targets, skipped: materializeSkipped } = resolveMaterializeTargets(steps, stepRefs);
     if (targets.length === 0) {
         if (materializeSkipped.length > 0) {
-            // PR #78 / Gemini medium follow-up: when every selected step was
-            // already materialized or completed, return a successful no-op
-            // result (exit 0) instead of throwing NOT_FOUND. This makes
-            // `pm plan materialize --steps all` truly idempotent for CI/agent
-            // workflows; the skip reasons + warnings still surface what was
-            // intentionally not redone.
-            const plan = projectPlan(planRead.document.metadata, "standard");
-            return {
-                action: "materialize",
-                plan,
-                materialized: [],
-                materialize_skipped: materializeSkipped,
-                next_actions: nextActionsFor(planRead.itemId, plan),
-                warnings: materializeSkipped.map((entry) => `plan_materialize_skipped:${entry.from_step}:${entry.reason}${entry.existing_id ? `:${entry.existing_id}` : ""}`),
-                generated_at: nowIso(),
-            };
+            return buildMaterializeNoopResult(planRead, materializeSkipped);
         }
         throw new PmCliError("No matching plan steps found for --steps", EXIT_CODE.NOT_FOUND);
     }
-    const materialized = [];
-    for (const step of targets) {
-        const deps = [
-            `id=${parent},kind=parent`,
-            `id=${planRead.itemId},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}`);
-        }
-        const created = await runCreate({
-            title: step.title,
-            description: step.body?.trim() || step.title,
-            type: resolvedTypeName,
-            parent,
-            tags,
-            author: options.author,
-            message: options.message ?? `materialized from plan ${planRead.itemId} step ${step.id}`,
-            dep: deps,
-        }, ctx.settings ? { ...{}, path: ctx.pmRoot } : {});
-        materialized.push({ id: created.item.id, type: resolvedTypeName, from_step: step.id });
-    }
+    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, doc) {
-            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();
-            }
+        mutator(currentSteps) {
+            linkMaterializedStepItems(currentSteps, targets, materialized);
             return { changedSteps: targets.map((entry) => entry.id) };
         },
     });
@@ -1231,94 +1296,104 @@ async function planMaterialize(id, options, ctx) {
         materialized,
         ...(materializeSkipped.length > 0 ? { materialize_skipped: materializeSkipped } : {}),
         next_actions: nextActionsFor(itemId, plan),
-        warnings: materializeSkipped.map((entry) => `plan_materialize_skipped:${entry.from_step}:${entry.reason}${entry.existing_id ? `:${entry.existing_id}` : ""}`),
+        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 === undefined) {
+        throw new PmCliError("pm plan reorder-step requires <plan-id> <step> <new-order>", EXIT_CODE.USAGE);
+    }
+    return { ...target, reorderTo: input.reorderTo };
+}
+const 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;
+}
 /**
  * Implements run plan for the public runtime surface of this module.
  */
 export async function runPlan(input) {
     const ctx = await loadContext(input.global);
-    // pm-6mit: --step accumulates ordered step titles on create. For every other
-    // subcommand a single --step value keeps its historical alias-of---step-title
-    // behavior; multiple values would be ambiguous there (one step is targeted),
-    // so they are rejected instead of silently dropping all but the last.
-    if (input.subcommand !== "create") {
-        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()) {
-            input = { ...input, options: { ...input.options, stepTitle: stepValues[0] } };
-        }
-    }
-    switch (input.subcommand) {
-        case "create":
-            return planCreate(input.options, input.global, ctx);
-        case "show":
-            if (!input.id)
-                throw new PmCliError("pm plan show requires a plan id", EXIT_CODE.USAGE);
-            return planShow(input.id, input.options, ctx);
-        case "add-step":
-            if (!input.id)
-                throw new PmCliError("pm plan add-step requires a plan id", EXIT_CODE.USAGE);
-            return planAddStep(input.id, input.options, ctx);
-        case "update-step":
-            if (!input.id || !input.stepRef)
-                throw new PmCliError("pm plan update-step requires <plan-id> <step>", EXIT_CODE.USAGE);
-            return planUpdateStep(input.id, input.options, ctx, { stepRef: input.stepRef, op: "plan_update_step" });
-        case "complete-step":
-            if (!input.id || !input.stepRef)
-                throw new PmCliError("pm plan complete-step requires <plan-id> <step>", EXIT_CODE.USAGE);
-            return planUpdateStep(input.id, input.options, ctx, { stepRef: input.stepRef, finalStatus: "completed", op: "plan_complete_step" });
-        case "block-step":
-            if (!input.id || !input.stepRef)
-                throw new PmCliError("pm plan block-step requires <plan-id> <step>", EXIT_CODE.USAGE);
-            return planUpdateStep(input.id, input.options, ctx, { stepRef: input.stepRef, finalStatus: "blocked", op: "plan_block_step" });
-        case "reorder-step":
-            if (!input.id || !input.stepRef || input.reorderTo === undefined)
-                throw new PmCliError("pm plan reorder-step requires <plan-id> <step> <new-order>", EXIT_CODE.USAGE);
-            return planReorderStep(input.id, input.options, ctx, input.stepRef, input.reorderTo);
-        case "remove-step":
-            if (!input.id || !input.stepRef)
-                throw new PmCliError("pm plan remove-step requires <plan-id> <step>", EXIT_CODE.USAGE);
-            return planRemoveStep(input.id, input.options, ctx, input.stepRef);
-        case "link":
-            if (!input.id || !input.stepRef)
-                throw new PmCliError("pm plan link requires <plan-id> <step>", EXIT_CODE.USAGE);
-            return planLink(input.id, input.options, ctx, input.stepRef);
-        case "unlink":
-            if (!input.id || !input.stepRef)
-                throw new PmCliError("pm plan unlink requires <plan-id> <step>", EXIT_CODE.USAGE);
-            return planUnlink(input.id, input.options, ctx, input.stepRef);
-        case "decision":
-            if (!input.id)
-                throw new PmCliError("pm plan decision requires a plan id", EXIT_CODE.USAGE);
-            return planAppendLog(input.id, input.options, ctx, "decision");
-        case "discovery":
-            if (!input.id)
-                throw new PmCliError("pm plan discovery requires a plan id", EXIT_CODE.USAGE);
-            return planAppendLog(input.id, input.options, ctx, "discovery");
-        case "validation":
-            if (!input.id)
-                throw new PmCliError("pm plan validation requires a plan id", EXIT_CODE.USAGE);
-            return planAppendLog(input.id, input.options, ctx, "validation");
-        case "resume":
-            if (!input.id)
-                throw new PmCliError("pm plan resume requires a plan id", EXIT_CODE.USAGE);
-            return planResume(input.id, input.options, ctx);
-        case "approve":
-            if (!input.id)
-                throw new PmCliError("pm plan approve requires a plan id", EXIT_CODE.USAGE);
-            return planApprove(input.id, input.options, ctx);
-        case "materialize":
-            if (!input.id)
-                throw new PmCliError("pm plan materialize requires a plan id", EXIT_CODE.USAGE);
-            return planMaterialize(input.id, input.options, ctx);
-        default:
-            throw new PmCliError(`Unknown pm plan subcommand "${input.subcommand}"`, EXIT_CODE.USAGE);
-    }
+    const normalizedInput = normalizePlanStepAliasInput(input);
+    return resolvePlanDispatcher(normalizedInput.subcommand)(normalizedInput, ctx);
 }
 //# sourceMappingURL=plan.js.map
-//# debugId=441230c4-0ce6-5c75-8fcb-3af1fc95a584
+//# debugId=1e64f96b-b7e3-5228-839a-65a187cb7020