@unbrained/pm-cli 2026.5.18 → 2026.5.24

package/dist/cli/commands/notes.js

@@ -1,124 +1,25 @@
 
-!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]="e775672d-e669-5b8d-bd54-5340390b2120")}catch(e){}}();
-import { pathExists } from "../../core/fs/fs-utils.js";
-import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
-import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
-import { EXIT_CODE } from "../../core/shared/constants.js";
-import { PmCliError } from "../../core/shared/errors.js";
-import { nowIso } from "../../core/shared/time.js";
-import { createStdinTokenResolver, parseCsvKv } from "../../core/item/parse.js";
-import { locateItem, mutateItem, readLocatedItem } from "../../core/store/item-store.js";
-import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
-import { readSettings } from "../../core/store/settings.js";
-import { parseLimit } from "../shared-parsers.js";
-function resolveAuthor(candidate, fallback) {
-    const resolved = candidate ?? process.env.PM_AUTHOR ?? fallback;
-    const trimmed = resolved.trim();
-    return trimmed || "unknown";
-}
-function limitNotes(values, limit) {
-    if (limit === undefined)
-        return values;
-    if (limit === 0)
-        return [];
-    return values.slice(Math.max(0, values.length - limit));
-}
-function parseNoteTextInput(raw) {
-    const trimmed = raw.trim();
-    if (!trimmed) {
-        return "";
-    }
-    const looksStructured = /^(?:[-*+]\s*)?text\s*[:=]/im.test(trimmed) || trimmed.startsWith("```");
-    if (!looksStructured) {
-        return trimmed;
-    }
-    try {
-        const kv = parseCsvKv(trimmed, "--add");
-        const keys = Object.keys(kv).map((key) => key.trim().toLowerCase());
-        if (keys.some((key) => key !== "text")) {
-            return trimmed;
-        }
-        const text = kv.text?.trim();
-        return text || trimmed;
-    }
-    catch {
-        return trimmed;
-    }
-}
+!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]="60f1e397-2d8b-5ef9-a3e2-d4e20160ed6a")}catch(e){}}();
+import { createStdinTokenResolver } from "../../core/item/parse.js";
+import { parseAnnotationTextInput, runAnnotationCommand } from "./annotation-command.js";
 export async function runNotes(id, options, global) {
     const stdinResolver = createStdinTokenResolver();
-    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);
-    const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
-    const limit = parseLimit(options.limit);
-    if (options.add === undefined) {
-        const located = await locateItem(pmRoot, id, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);
-        if (!located) {
-            throw new PmCliError(`Item ${id} not found`, EXIT_CODE.NOT_FOUND);
-        }
-        const loaded = await readLocatedItem(located, { schema: settings.schema });
-        const notes = limitNotes(loaded.document.metadata.notes ?? [], limit);
-        return {
-            id: located.id,
-            notes,
-            count: notes.length,
-        };
-    }
-    const author = resolveAuthor(options.author, settings.author_default);
-    const addInput = await stdinResolver.resolveValue(options.add, "--add");
-    const text = parseNoteTextInput(addInput ?? "");
-    if (!text) {
-        throw new PmCliError("--add text cannot be empty", EXIT_CODE.USAGE);
-    }
-    let result;
-    try {
-        result = await mutateItem({
-            pmRoot,
-            settings,
-            id,
-            op: "note_add",
-            author,
-            message: options.message,
-            force: options.force,
-            bypassAssigneeConflict: Boolean(options.allowAuditNote || options.allowAuditComment),
-            mutate(document) {
-                const notes = document.metadata.notes ?? [];
-                notes.push({
-                    created_at: nowIso(),
-                    author,
-                    text,
-                });
-                document.metadata.notes = notes;
-                return { changedFields: ["notes"] };
-            },
-        });
-    }
-    catch (error) {
-        if (error instanceof PmCliError &&
-            error.exitCode === EXIT_CODE.CONFLICT &&
-            error.message.includes("is assigned to") &&
-            error.message.includes("Use --force to override")) {
-            throw new PmCliError(error.message, error.exitCode, {
-                code: "ownership_conflict",
-                required: "For append-only note audits on another owner's item, prefer --allow-audit-note (legacy alias: --allow-audit-comment) before considering --force.",
-                examples: ['pm notes pm-a1b2 --add "audit note" --author "reviewer" --allow-audit-note'],
-                nextSteps: [
-                    "Retry with --allow-audit-note (or legacy --allow-audit-comment) for append-only note audits that do not mutate item metadata beyond notes.",
-                    "Use --force only when an ownership override is explicitly approved.",
-                ],
-            });
-        }
-        throw error;
-    }
-    const notes = limitNotes(result.item.notes, limit);
-    return {
-        id: result.item.id,
-        notes,
-        count: notes.length,
-    };
+    const addInput = options.add === undefined ? undefined : await stdinResolver.resolveValue(options.add, "--add");
+    return runAnnotationCommand(id, options, global, {
+        input: options.add === undefined ? { mode: "list" } : { mode: "add", value: addInput ?? "", emptyFlag: "--add" },
+        collectionKey: "notes",
+        op: "note_add",
+        parseText: (raw) => parseAnnotationTextInput(raw),
+        allowAuditBypass: Boolean(options.allowAuditNote || options.allowAuditComment),
+        conflictGuidance: {
+            required: "For append-only note audits on another owner's item, prefer --allow-audit-note (legacy alias: --allow-audit-comment) before considering --force.",
+            examples: ['pm notes pm-a1b2 --add "audit note" --author "reviewer" --allow-audit-note'],
+            nextSteps: [
+                "Retry with --allow-audit-note (or legacy --allow-audit-comment) for append-only note audits that do not mutate item metadata beyond notes.",
+                "Use --force only when an ownership override is explicitly approved.",
+            ],
+        },
+    });
 }
 //# sourceMappingURL=notes.js.map
-//# debugId=e775672d-e669-5b8d-bd54-5340390b2120
+//# debugId=60f1e397-2d8b-5ef9-a3e2-d4e20160ed6a

package/dist/cli/commands/notes.js.map

@@ -1 +1 @@
-{"version":3,"file":"notes.js","sources":["cli/commands/notes.ts"],"sourceRoot":"/","sourcesContent":["import { pathExists } from \"../../core/fs/fs-utils.js\";\nimport { getActiveExtensionRegistrations } from \"../../core/extensions/index.js\";\nimport { resolveItemTypeRegistry } from \"../../core/item/type-registry.js\";\nimport { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport { nowIso } from \"../../core/shared/time.js\";\nimport { createStdinTokenResolver, parseCsvKv } from \"../../core/item/parse.js\";\nimport { locateItem, mutateItem, readLocatedItem } from \"../../core/store/item-store.js\";\nimport { getSettingsPath, resolvePmRoot } from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\nimport { parseLimit } from \"../shared-parsers.js\";\nimport type { LogNote } from \"../../types/index.js\";\n\nexport interface NotesCommandOptions {\n  add?: string;\n  limit?: string;\n  author?: string;\n  message?: string;\n  allowAuditNote?: boolean;\n  allowAuditComment?: boolean;\n  force?: boolean;\n}\n\nexport interface NotesResult {\n  id: string;\n  notes: LogNote[];\n  count: number;\n}\n\nfunction resolveAuthor(candidate: string | undefined, fallback: string): string {\n  const resolved = candidate ?? process.env.PM_AUTHOR ?? fallback;\n  const trimmed = resolved.trim();\n  return trimmed || \"unknown\";\n}\n\nfunction limitNotes(values: LogNote[], limit: number | undefined): LogNote[] {\n  if (limit === undefined) return values;\n  if (limit === 0) return [];\n  return values.slice(Math.max(0, values.length - limit));\n}\n\nfunction parseNoteTextInput(raw: string): string {\n  const trimmed = raw.trim();\n  if (!trimmed) {\n    return \"\";\n  }\n  const looksStructured = /^(?:[-*+]\\s*)?text\\s*[:=]/im.test(trimmed) || trimmed.startsWith(\"```\");\n  if (!looksStructured) {\n    return trimmed;\n  }\n  try {\n    const kv = parseCsvKv(trimmed, \"--add\");\n    const keys = Object.keys(kv).map((key) => key.trim().toLowerCase());\n    if (keys.some((key) => key !== \"text\")) {\n      return trimmed;\n    }\n    const text = kv.text?.trim();\n    return text || trimmed;\n  } catch {\n    return trimmed;\n  }\n}\n\nexport async function runNotes(id: string, options: NotesCommandOptions, global: GlobalOptions): Promise<NotesResult> {\n  const stdinResolver = createStdinTokenResolver();\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  if (!(await pathExists(getSettingsPath(pmRoot)))) {\n    throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);\n  }\n  const settings = await readSettings(pmRoot);\n  const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());\n  const limit = parseLimit(options.limit);\n\n  if (options.add === undefined) {\n    const located = await locateItem(pmRoot, id, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);\n    if (!located) {\n      throw new PmCliError(`Item ${id} not found`, EXIT_CODE.NOT_FOUND);\n    }\n    const loaded = await readLocatedItem(located, { schema: settings.schema });\n    const notes = limitNotes(loaded.document.metadata.notes ?? [], limit);\n    return {\n      id: located.id,\n      notes,\n      count: notes.length,\n    };\n  }\n\n  const author = resolveAuthor(options.author, settings.author_default);\n  const addInput = await stdinResolver.resolveValue(options.add, \"--add\");\n  const text = parseNoteTextInput(addInput ?? \"\");\n  if (!text) {\n    throw new PmCliError(\"--add text cannot be empty\", EXIT_CODE.USAGE);\n  }\n\n  let result: Awaited<ReturnType<typeof mutateItem>>;\n  try {\n    result = await mutateItem({\n      pmRoot,\n      settings,\n      id,\n      op: \"note_add\",\n      author,\n      message: options.message,\n      force: options.force,\n      bypassAssigneeConflict: Boolean(options.allowAuditNote || options.allowAuditComment),\n      mutate(document) {\n        const notes = document.metadata.notes ?? [];\n        notes.push({\n          created_at: nowIso(),\n          author,\n          text,\n        });\n        document.metadata.notes = notes;\n        return { changedFields: [\"notes\"] };\n      },\n    });\n  } catch (error: unknown) {\n    if (\n      error instanceof PmCliError &&\n      error.exitCode === EXIT_CODE.CONFLICT &&\n      error.message.includes(\"is assigned to\") &&\n      error.message.includes(\"Use --force to override\")\n    ) {\n      throw new PmCliError(error.message, error.exitCode, {\n        code: \"ownership_conflict\",\n        required:\n          \"For append-only note audits on another owner's item, prefer --allow-audit-note (legacy alias: --allow-audit-comment) before considering --force.\",\n        examples: ['pm notes pm-a1b2 --add \"audit note\" --author \"reviewer\" --allow-audit-note'],\n        nextSteps: [\n          \"Retry with --allow-audit-note (or legacy --allow-audit-comment) for append-only note audits that do not mutate item metadata beyond notes.\",\n          \"Use --force only when an ownership override is explicitly approved.\",\n        ],\n      });\n    }\n    throw error;\n  }\n\n  const notes = limitNotes(result.item.notes as LogNote[], limit);\n  return {\n    id: result.item.id,\n    notes,\n    count: notes.length,\n  };\n}\n"],"names":[],"mappings":"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","debugId":"e775672d-e669-5b8d-bd54-5340390b2120"}
+{"version":3,"file":"notes.js","sources":["cli/commands/notes.ts"],"sourceRoot":"/","sourcesContent":["import type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { createStdinTokenResolver } from \"../../core/item/parse.js\";\nimport type { LogNote } from \"../../types/index.js\";\nimport { parseAnnotationTextInput, runAnnotationCommand } from \"./annotation-command.js\";\n\nexport interface NotesCommandOptions {\n  add?: string;\n  limit?: string;\n  author?: string;\n  message?: string;\n  allowAuditNote?: boolean;\n  allowAuditComment?: boolean;\n  force?: boolean;\n}\n\nexport interface NotesResult {\n  id: string;\n  notes: LogNote[];\n  count: number;\n}\n\nexport async function runNotes(id: string, options: NotesCommandOptions, global: GlobalOptions): Promise<NotesResult> {\n  const stdinResolver = createStdinTokenResolver();\n  const addInput = options.add === undefined ? undefined : await stdinResolver.resolveValue(options.add, \"--add\");\n\n  return runAnnotationCommand<\"notes\", LogNote>(id, options, global, {\n    input: options.add === undefined ? { mode: \"list\" } : { mode: \"add\", value: addInput ?? \"\", emptyFlag: \"--add\" },\n    collectionKey: \"notes\",\n    op: \"note_add\",\n    parseText: (raw) => parseAnnotationTextInput(raw),\n    allowAuditBypass: Boolean(options.allowAuditNote || options.allowAuditComment),\n    conflictGuidance: {\n      required:\n        \"For append-only note audits on another owner's item, prefer --allow-audit-note (legacy alias: --allow-audit-comment) before considering --force.\",\n      examples: ['pm notes pm-a1b2 --add \"audit note\" --author \"reviewer\" --allow-audit-note'],\n      nextSteps: [\n        \"Retry with --allow-audit-note (or legacy --allow-audit-comment) for append-only note audits that do not mutate item metadata beyond notes.\",\n        \"Use --force only when an ownership override is explicitly approved.\",\n      ],\n    },\n  });\n}\n"],"names":[],"mappings":";;AACA,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,OAAO,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAkBzF,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,EAAU,EAAE,OAA4B,EAAE,MAAqB;IAC5F,MAAM,aAAa,GAAG,wBAAwB,EAAE,CAAC;IACjD,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,aAAa,CAAC,YAAY,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAEhH,OAAO,oBAAoB,CAAmB,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE;QACjE,KAAK,EAAE,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,IAAI,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE;QAChH,aAAa,EAAE,OAAO;QACtB,EAAE,EAAE,UAAU;QACd,SAAS,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,wBAAwB,CAAC,GAAG,CAAC;QACjD,gBAAgB,EAAE,OAAO,CAAC,OAAO,CAAC,cAAc,IAAI,OAAO,CAAC,iBAAiB,CAAC;QAC9E,gBAAgB,EAAE;YAChB,QAAQ,EACN,kJAAkJ;YACpJ,QAAQ,EAAE,CAAC,4EAA4E,CAAC;YACxF,SAAS,EAAE;gBACT,4IAA4I;gBAC5I,qEAAqE;aACtE;SACF;KACF,CAAC,CAAC;AACL,CAAC","debugId":"60f1e397-2d8b-5ef9-a3e2-d4e20160ed6a"}

package/dist/cli/commands/plan.d.ts

@@ -37,10 +37,13 @@ export interface PlanCommandOptions {
     test?: string | string[];
     doc?: string | string[];
     decisionText?: string;
+    decision?: string;
     decisionRationale?: string;
     decisionEvidence?: string;
     discoveryText?: string;
+    discovery?: string;
     validationText?: string;
+    validation?: string;
     validationCommand?: string;
     validationExpected?: string;
     depth?: string;

package/dist/cli/commands/plan.js

@@ -1,5 +1,5 @@
 
-!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]="588c239a-66d0-5d60-b675-5a5a4e79d70b")}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]="55dd5c6d-22e8-50d4-a39c-f08a7db05b06")}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";
@@ -117,18 +117,53 @@ function parsePlanFields(raw) {
     }
     return fields;
 }
+const PLAN_FIELD_KEYS = 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) {
@@ -224,6 +259,38 @@ function resolveStepRef(steps, ref) {
     }
     throw new PmCliError(`Step "${ref}" not found in plan`, EXIT_CODE.NOT_FOUND);
 }
+function resolveMaterializeTargets(steps, refs) {
+    const allRefs = refs.filter((ref) => ref.trim().toLowerCase() === "all");
+    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);
+        }
+        return steps.slice().sort((left, right) => left.order - right.order);
+    }
+    const targets = [];
+    const seen = new Set();
+    for (const ref of refs) {
+        const step = resolveStepRef(steps, ref);
+        if (seen.has(step.id))
+            continue;
+        targets.push(step);
+        seen.add(step.id);
+    }
+    return targets;
+}
+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() || undefined;
+}
 function findCurrentStep(steps) {
     return steps.find((step) => step.status === "in_progress")
         ?? steps.find((step) => step.status === "pending");
@@ -285,7 +352,15 @@ function nextActionsFor(planId, plan) {
 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);
+        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) {
@@ -373,6 +448,91 @@ 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;
+    if (options.stepTitle?.trim()) {
+        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();
+        initialStep = {
+            id: "plan-step-001",
+            order: 1,
+            title: options.stepTitle.trim(),
+            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,
+        };
+        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: `plan create initial step "${initialStep.title}"`,
+            mutate(doc) {
+                ensurePlanItem(doc.metadata);
+                doc.metadata.plan_steps = [initialStep];
+                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 (options.stepBody?.trim() ||
+        options.stepOwner?.trim() ||
+        options.stepStatus?.trim() ||
+        options.stepEvidence?.trim() ||
+        options.stepBlockedReason?.trim() ||
+        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) {
+        throw new PmCliError("pm plan create step options require --step-title", 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,
@@ -392,6 +552,7 @@ async function planCreate(options, global, ctx) {
     return {
         action: "create",
         plan,
+        step: initialStep,
         next_actions: nextActionsFor(createResult.item.id, plan),
         warnings: [...createResult.warnings],
         generated_at: nowIso(),
@@ -401,7 +562,7 @@ 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, depth);
+    const fullPlan = projectPlan(document.metadata, fields === null ? depth : "deep");
     const plan = fields === null ? fullPlan : projectPlanForFields(fullPlan, fields);
     return {
         action: "show",
@@ -720,14 +881,20 @@ async function planUnlink(id, options, ctx, stepRef) {
     };
 }
 async function planAppendLog(id, options, ctx, kind) {
-    if (kind === "decision" && !options.decisionText?.trim()) {
-        throw new PmCliError("pm plan decision requires --decision-text", EXIT_CODE.USAGE);
-    }
-    if (kind === "discovery" && !options.discoveryText?.trim()) {
-        throw new PmCliError("pm plan discovery requires --discovery-text", EXIT_CODE.USAGE);
-    }
-    if (kind === "validation" && !options.validationText?.trim()) {
-        throw new PmCliError("pm plan validation requires --validation-text", EXIT_CODE.USAGE);
+    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({
@@ -743,7 +910,7 @@ async function planAppendLog(id, options, ctx, kind) {
                 list.push({
                     ts: now,
                     author,
-                    decision: options.decisionText.trim(),
+                    decision: logText,
                     rationale: options.decisionRationale?.trim() || undefined,
                     evidence: options.decisionEvidence?.trim() || undefined,
                 });
@@ -752,13 +919,13 @@ async function planAppendLog(id, options, ctx, kind) {
             }
             if (kind === "discovery") {
                 const list = doc.metadata.plan_discoveries ?? [];
-                list.push({ ts: now, author, text: options.discoveryText.trim() });
+                list.push({ ts: now, author, text: logText });
                 doc.metadata.plan_discoveries = list;
                 return { changedSteps: [] };
             }
             const list = doc.metadata.plan_validation ?? [];
             list.push({
-                text: options.validationText.trim(),
+                text: logText,
                 command: options.validationCommand?.trim() || undefined,
                 expected: options.validationExpected?.trim() || undefined,
             });
@@ -825,7 +992,7 @@ async function planApprove(id, options, ctx) {
 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>", EXIT_CODE.USAGE);
+        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());
@@ -837,7 +1004,7 @@ async function planMaterialize(id, options, ctx) {
     const tags = options.materializeTags;
     const planRead = await readPlanItem(ctx, id);
     const steps = (planRead.document.metadata.plan_steps ?? []).slice();
-    const targets = stepRefs.map((ref) => resolveStepRef(steps, ref));
+    const targets = resolveMaterializeTargets(steps, stepRefs);
     if (targets.length === 0) {
         throw new PmCliError("No matching plan steps found for --steps", EXIT_CODE.NOT_FOUND);
     }
@@ -884,11 +1051,6 @@ async function planMaterialize(id, options, ctx) {
                 step.linked_items = links;
                 step.updated_at = nowIso();
             }
-            const deps = doc.metadata.dependencies ?? [];
-            for (const m of materialized) {
-                deps.push({ id: m.id, kind: "child", created_at: nowIso(), author: resolveAuthor(options.author, ctx.settings.author_default) });
-            }
-            doc.metadata.dependencies = deps;
             return { changedSteps: targets.map((entry) => entry.id) };
         },
     });
@@ -972,4 +1134,4 @@ export async function runPlan(input) {
     }
 }
 //# sourceMappingURL=plan.js.map
-//# debugId=588c239a-66d0-5d60-b675-5a5a4e79d70b
+//# debugId=55dd5c6d-22e8-50d4-a39c-f08a7db05b06