@kynetic-ai/spec 0.10.0 → 0.12.0

package/dist/cli/commands/plan.js

@@ -5,16 +5,16 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { markMutating } from "../command-annotations.js";
-import { buildIndexes, createPlan, createTask, filterPlansByStatus, getAuthor, initContext, loadAllTasks, loadPlans, mutatePlanAtomically, savePlan, saveTask, shortestUniqueUlid, } from "../../parser/index.js";
+import { addChildItem, addProjectLevelTraitItem, buildIndexes, createPlan, createSpecItem, createTask, findPlanByRef, filterPlansByStatus, getAuthor, initContext, loadPlans, mutatePlanAtomically, savePlan, saveTask, shortestUniqueUlid, } from "../../parser/index.js";
 import { commitIfShadow } from "../../parser/shadow.js";
+import { parsePlanDocument, topologicalSort, } from "../../parser/plan-document.js";
 import { errors } from "../../strings/index.js";
 import { fieldLabels } from "../../strings/labels.js";
 import { formatRelativeTime as formatRelativeTimeUtil } from "../../utils/time.js";
 import { EXIT_CODES } from "../exit-codes.js";
-import { error, info, output, success } from "../output.js";
+import { error, info, isJsonMode, output, success, warn } from "../output.js";
 import { ulid } from "ulid";
 import { registerPlanImportCommand } from "./plan-import.js";
-import { parseIntOption } from "../validators.js";
 /**
  * Format relative time for display
  */
@@ -31,14 +31,389 @@ function resolvePlanRef(ref, plans) {
         p._ulid.toLowerCase().startsWith(cleanRef.toLowerCase()) ||
         p.slugs.includes(cleanRef));
     if (!plan) {
-        error(errors.reference.planNotFound(ref));
-        process.exit(EXIT_CODES.NOT_FOUND);
+        exitDeriveWithGuidance(errors.reference.planNotFound(ref), EXIT_CODES.NOT_FOUND, "Check available plans with: kspec plan list", {
+            ref,
+            entity: "plan",
+        });
     }
     return plan;
 }
 function shortPlanRef(plan, plans) {
     return shortestUniqueUlid(plan._ulid, plans.map((candidate) => candidate._ulid));
 }
+async function resolveDeriveModuleRef(ctx, plans, foundPlan, moduleOption) {
+    const moduleRef = moduleOption ?? foundPlan.module_ref ?? null;
+    if (!moduleRef) {
+        return null;
+    }
+    const { refIndex } = await buildIndexes(ctx, plans);
+    const moduleResult = refIndex.resolve(moduleRef);
+    if (!moduleResult.ok) {
+        exitDeriveWithGuidance(errors.reference.itemNotFound(moduleRef), EXIT_CODES.NOT_FOUND, "Check available modules with: kspec item list --type module", {
+            ref: moduleRef,
+            entity: "module",
+        });
+    }
+    const moduleItem = moduleResult.item;
+    if (moduleItem.type !== "module") {
+        exitDeriveWithGuidance(`${moduleRef} is not a module (type: ${moduleItem.type})`, EXIT_CODES.USAGE_ERROR, "Pass a module @ref from: kspec item list --type module", {
+            field: "module",
+            value: moduleItem.type,
+        });
+    }
+    return moduleRef.startsWith("@") ? moduleRef : `@${moduleRef}`;
+}
+function slugify(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 50);
+}
+function toRef(ref) {
+    return ref.startsWith("@") ? ref : `@${ref}`;
+}
+function canonicalRef(item) {
+    return `@${item.slugs[0] || item._ulid}`;
+}
+function nextUniqueSlug(baseSlug, reservedSlugs) {
+    let slug = baseSlug;
+    let counter = 1;
+    while (reservedSlugs.has(slug)) {
+        slug = `${baseSlug}-${counter}`;
+        counter++;
+    }
+    reservedSlugs.add(slug);
+    return slug;
+}
+function createNote(content, author) {
+    return {
+        _ulid: ulid(),
+        created_at: new Date().toISOString(),
+        author,
+        content,
+    };
+}
+function exitDeriveWithGuidance(message, exitCode, suggestion, details) {
+    if (suggestion) {
+        if (isJsonMode()) {
+            error(message, {
+                ...details,
+                suggestion,
+                guidance: suggestion,
+            });
+        }
+        else {
+            error(message);
+            console.error(`Suggestion: ${suggestion}`);
+        }
+    }
+    else {
+        error(message, isJsonMode() ? details : undefined);
+    }
+    process.exit(exitCode);
+}
+function emitDeriveResult(result) {
+    output(result, () => {
+        if (result.dry_run) {
+            console.log("Dry run - no changes made\n");
+        }
+        console.log(`Plan: ${result.plan_ref}`);
+        console.log(`Module: ${result.module_ref}`);
+        console.log(`Created specs: ${result.created_specs.length}`);
+        for (const ref of result.created_specs) {
+            console.log(`  - ${ref}`);
+        }
+        console.log(`Created tasks: ${result.created_tasks.length}`);
+        for (const ref of result.created_tasks) {
+            console.log(`  - ${ref}`);
+        }
+        if (result.skipped.length > 0) {
+            console.log(`Skipped: ${result.skipped.length}`);
+            for (const skipped of result.skipped) {
+                console.log(`  - ${skipped.ref} (${skipped.title}): ${skipped.reason}`);
+            }
+        }
+        if (result.errors.length > 0) {
+            console.log(`Errors: ${result.errors.length}`);
+            for (const err of result.errors) {
+                console.log(`  - [${err.type}] ${err.message}`);
+            }
+        }
+    });
+}
+function reportWarnings(warnings) {
+    for (const warning of warnings) {
+        warn(warning.ref ? `${warning.ref}: ${warning.message}` : warning.message);
+    }
+}
+function normalizeSpecTraits(spec, refIndex, createdSpecs, warnings) {
+    const normalized = new Set();
+    for (const rawTrait of spec.traits || []) {
+        const traitRef = toRef(rawTrait);
+        const localTrait = createdSpecs.get(traitRef.slice(1));
+        if (localTrait?.item.type === "trait") {
+            normalized.add(localTrait.ref);
+            continue;
+        }
+        const resolved = refIndex.resolve(traitRef);
+        if (resolved.ok) {
+            const item = resolved.item;
+            if (item.type !== "trait") {
+                warnings.push({
+                    kind: "spec",
+                    ref: spec.slug ? `@${spec.slug}` : undefined,
+                    message: `${traitRef} resolved to ${item.type}, not a trait. Storing normalized reference for later review.`,
+                });
+                normalized.add(traitRef);
+                continue;
+            }
+            normalized.add(canonicalRef(item));
+            continue;
+        }
+        normalized.add(traitRef);
+    }
+    return [...normalized];
+}
+function normalizeSpecDependencies(spec, refIndex, createdSpecs, warnings) {
+    return (spec.depends_on || []).map((rawDependency) => {
+        const dependencyRef = toRef(rawDependency);
+        const localDependency = createdSpecs.get(dependencyRef.slice(1));
+        if (localDependency) {
+            return localDependency.ref;
+        }
+        const resolved = refIndex.resolve(dependencyRef);
+        if (resolved.ok) {
+            const item = resolved.item;
+            return canonicalRef(item);
+        }
+        warnings.push({
+            kind: "spec",
+            ref: spec.slug ? `@${spec.slug}` : undefined,
+            message: `Unresolved dependency ${dependencyRef}. Keeping the reference as-is for later resolution.`,
+        });
+        return dependencyRef;
+    });
+}
+async function materializePlanSpecs(ctx, foundPlan, moduleRef, parsedPlan, refIndex, items, reservedSlugs, dryRun, warnings, skipped) {
+    const sortResult = topologicalSort(parsedPlan.specs);
+    if (sortResult.error) {
+        exitDeriveWithGuidance(sortResult.error.message, EXIT_CODES.USAGE_ERROR, "Fix the parent references in the plan content so they form an acyclic tree.", {
+            type: sortResult.error.type,
+        });
+    }
+    const createdSpecs = new Map();
+    const materialized = [];
+    const moduleResult = refIndex.resolve(moduleRef);
+    if (!moduleResult.ok) {
+        exitDeriveWithGuidance(errors.reference.itemNotFound(moduleRef), EXIT_CODES.NOT_FOUND, "Check available modules with: kspec item list --type module", {
+            ref: moduleRef,
+            entity: "module",
+        });
+    }
+    const moduleItem = moduleResult.item;
+    for (const spec of sortResult.sorted) {
+        const localSlug = spec.slug || slugify(spec.title);
+        const itemType = (spec.type || "feature");
+        const itemSlug = nextUniqueSlug(localSlug, reservedSlugs);
+        const itemRef = `@${itemSlug}`;
+        let parent = null;
+        if (!(itemType === "trait" && !spec.parent)) {
+            if (spec.parent) {
+                const localParent = createdSpecs.get(spec.parent.startsWith("@") ? spec.parent.slice(1) : spec.parent);
+                if (localParent) {
+                    parent = localParent.item;
+                }
+                else {
+                    const resolvedParent = refIndex.resolve(spec.parent);
+                    if (!resolvedParent.ok) {
+                        const reason = `Parent ${toRef(spec.parent)} not found. Use an existing @ref or add the parent spec to the plan.`;
+                        warnings.push({ kind: "spec", ref: itemRef, message: reason });
+                        skipped.push({
+                            kind: "spec",
+                            ref: itemRef,
+                            title: spec.title,
+                            reason,
+                        });
+                        continue;
+                    }
+                    parent = resolvedParent.item;
+                }
+            }
+            else {
+                parent = moduleItem;
+            }
+        }
+        const input = {
+            title: spec.title,
+            type: itemType,
+            slugs: [itemSlug],
+            description: spec.description,
+            priority: spec.priority,
+            tags: [],
+            acceptance_criteria: spec.acceptance_criteria,
+            depends_on: normalizeSpecDependencies(spec, refIndex, createdSpecs, warnings),
+            implements: [],
+            relates_to: [],
+            tests: [],
+            traits: normalizeSpecTraits(spec, refIndex, createdSpecs, warnings),
+            notes: [],
+        };
+        const newItem = createSpecItem(input);
+        let createdItem;
+        if (dryRun) {
+            createdItem = {
+                ...newItem,
+                _sourceFile: parent?._sourceFile,
+            };
+        }
+        else if (itemType === "trait" && !spec.parent) {
+            const addResult = await addProjectLevelTraitItem(ctx, newItem);
+            createdItem = {
+                ...addResult.item,
+                _sourceFile: ctx.manifestPath || undefined,
+                _path: addResult.path,
+            };
+        }
+        else {
+            const addResult = await addChildItem(ctx, parent, newItem);
+            createdItem = {
+                ...addResult.item,
+                _sourceFile: parent._sourceFile,
+                _path: addResult.path,
+            };
+        }
+        const materializedSpec = {
+            localSlug,
+            ref: itemRef,
+            item: createdItem,
+            source: spec,
+        };
+        createdSpecs.set(localSlug, materializedSpec);
+        materialized.push(materializedSpec);
+    }
+    return materialized;
+}
+function buildTaskPlans(planRef, specItems, deriveFromSpecs, additionalTasks, refIndex, allTasks, reservedSlugs, author, warnings) {
+    const taskPlans = [];
+    const specTaskRefByLocalSlug = new Map();
+    const taskRefByLocalKey = new Map();
+    const shouldDeriveFromSpecs = deriveFromSpecs !== false;
+    if (shouldDeriveFromSpecs) {
+        for (const specItem of specItems) {
+            const taskSlug = nextUniqueSlug(slugify(`implement-${specItem.source.title}`), reservedSlugs);
+            const taskRef = `@${taskSlug}`;
+            specTaskRefByLocalSlug.set(specItem.localSlug, taskRef);
+            taskRefByLocalKey.set(specItem.localSlug, taskRef);
+        }
+    }
+    for (const task of additionalTasks || []) {
+        const localKey = task.slug || slugify(task.title);
+        const taskSlug = nextUniqueSlug(task.slug || localKey, reservedSlugs);
+        taskRefByLocalKey.set(localKey, `@${taskSlug}`);
+    }
+    if (shouldDeriveFromSpecs) {
+        for (const specItem of specItems) {
+            const taskRef = specTaskRefByLocalSlug.get(specItem.localSlug);
+            const taskSlug = taskRef.slice(1);
+            const dependsOn = (specItem.item.depends_on || []).map((dependencyRef) => {
+                const localDependency = specTaskRefByLocalSlug.get(dependencyRef.slice(1));
+                return localDependency || dependencyRef;
+            });
+            const notes = specItem.source.implementation_notes
+                ? [createNote(specItem.source.implementation_notes, author)]
+                : [];
+            taskPlans.push({
+                localKey: specItem.localSlug,
+                ref: taskRef,
+                input: {
+                    title: `Implement ${specItem.source.title}`,
+                    type: "task",
+                    slugs: [taskSlug],
+                    spec_ref: specItem.ref,
+                    plan_ref: planRef,
+                    priority: specItem.source.priority ?? 3,
+                    tags: [],
+                    depends_on: dependsOn,
+                    notes,
+                    origin: "derived",
+                    derivation: "auto",
+                },
+            });
+        }
+    }
+    for (const task of additionalTasks || []) {
+        const localKey = task.slug || slugify(task.title);
+        const taskRef = taskRefByLocalKey.get(localKey);
+        const taskSlug = taskRef.slice(1);
+        const specRef = task.spec_ref
+            ? (() => {
+                const localSpec = specItems.find((candidate) => candidate.localSlug ===
+                    (task.spec_ref.startsWith("@")
+                        ? task.spec_ref.slice(1)
+                        : task.spec_ref));
+                if (localSpec) {
+                    return localSpec.ref;
+                }
+                const resolved = refIndex.resolve(task.spec_ref);
+                if (resolved.ok) {
+                    return canonicalRef(resolved.item);
+                }
+                warnings.push({
+                    kind: "task",
+                    ref: taskRef,
+                    message: `Unresolved spec_ref ${toRef(task.spec_ref)} on additional task. Keeping normalized reference.`,
+                });
+                return toRef(task.spec_ref);
+            })()
+            : null;
+        const dependsOn = (task.depends_on || []).map((dependencyRef) => {
+            const normalized = toRef(dependencyRef);
+            const localTaskDependency = taskRefByLocalKey.get(normalized.slice(1));
+            if (localTaskDependency) {
+                return localTaskDependency;
+            }
+            const resolved = refIndex.resolve(normalized);
+            if (resolved.ok) {
+                return canonicalRef(resolved.item);
+            }
+            warnings.push({
+                kind: "task",
+                ref: taskRef,
+                message: `Unresolved depends_on ${normalized} on additional task. Keeping normalized reference.`,
+            });
+            return normalized;
+        });
+        taskPlans.push({
+            localKey,
+            ref: taskRef,
+            input: {
+                title: task.title,
+                type: "task",
+                slugs: [taskSlug],
+                description: task.description,
+                spec_ref: specRef,
+                plan_ref: planRef,
+                priority: task.priority ?? 3,
+                tags: task.tags || [],
+                depends_on: dependsOn,
+                notes: [],
+                origin: "derived",
+            },
+        });
+    }
+    const existingTaskSlugs = new Set(allTasks.flatMap((task) => task.slugs));
+    for (const taskPlan of taskPlans) {
+        if (existingTaskSlugs.has(taskPlan.input.slugs?.[0] || "")) {
+            warnings.push({
+                kind: "task",
+                ref: taskPlan.ref,
+                message: "Task slug collided with existing work and was renumbered.",
+            });
+        }
+    }
+    return taskPlans;
+}
 /**
  * Register the 'plan' command group
  */
@@ -158,6 +533,12 @@ Examples:
                 if (foundPlan.slugs.length > 0) {
                     console.log(`Slugs:    ${foundPlan.slugs.join(", ")}`);
                 }
+                if (foundPlan.module_ref) {
+                    console.log(`Module:   ${foundPlan.module_ref}`);
+                }
+                if (foundPlan.source_path) {
+                    console.log(`Source:   ${foundPlan.source_path}`);
+                }
                 console.log(`${fieldLabels.created}  ${foundPlan.created_at} (${formatRelativeTime(foundPlan.created_at)})`);
                 if (foundPlan.approved_at) {
                     console.log(`Approved: ${foundPlan.approved_at} (${formatRelativeTime(foundPlan.approved_at)})`);
@@ -198,6 +579,52 @@ Examples:
             process.exit(EXIT_CODES.ERROR);
         }
     });
+    // kspec plan export <ref>
+    // AC: @plan-export ac-stdout, ac-output-file, ac-empty, ac-not-found, ac-json
+    plan
+        .command("export <ref>")
+        .description("Export stored plan content to stdout or a file")
+        .option("--output <path>", "Write plan content to the specified file")
+        .addHelpText("after", `
+Examples:
+  $ kspec plan export @plan-ref
+  $ kspec plan export @plan-ref --output ./plan.md
+  $ kspec plan export @plan-ref --json`)
+        .action(async (ref, options) => {
+        try {
+            const ctx = await initContext();
+            const foundPlan = await findPlanByRef(ctx, ref);
+            if (!foundPlan) {
+                error(errors.reference.planNotFound(ref));
+                process.exit(EXIT_CODES.USAGE_ERROR);
+            }
+            if (foundPlan.content.length === 0) {
+                error("Plan has no content to export");
+                process.exit(EXIT_CODES.USAGE_ERROR);
+            }
+            if (isJsonMode()) {
+                output(foundPlan);
+                return;
+            }
+            if (options.output) {
+                const outputPath = path.resolve(process.cwd(), options.output);
+                try {
+                    await fs.writeFile(outputPath, foundPlan.content, "utf-8");
+                }
+                catch (err) {
+                    error(`Failed to write plan export file: ${options.output}`, err);
+                    process.exit(EXIT_CODES.ERROR);
+                }
+                success(`Exported plan content to ${options.output}`);
+                return;
+            }
+            process.stdout.write(foundPlan.content);
+        }
+        catch (err) {
+            error("Failed to export plan", err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
     // kspec plan set <ref>
     // AC: @plan-crud ac-3, ac-4
     markMutating(plan.command("set <ref>"))
@@ -362,102 +789,125 @@ Examples:
         }
     });
     // kspec plan derive <ref>
-    // AC: @plan-derive ac-5, ac-6
+    // AC: @plan-derive-enhanced ac-parse-content through ac-commit
     markMutating(plan.command("derive <ref>"))
-        .description("Create a task from a plan")
-        .option("--title <title>", "Override task title")
-        .option("--priority <n>", "Set task priority (1-5)")
+        .description("Materialize plan content into specs and optional tasks")
+        .option("--module <ref>", "Module context for derivation (overrides stored plan module)")
+        .option("--tasks", "Also derive implementation tasks after creating specs")
+        .option("--dry-run", "Preview derived specs/tasks without saving changes")
         .addHelpText("after", `
 Examples:
-  $ kspec plan derive @plan-ref
-  $ kspec plan derive @plan-ref --title "Custom title"
-  $ kspec plan derive @plan-ref --priority 1`)
+  $ kspec plan derive @plan-ref --module @core
+  $ kspec plan derive @plan-ref --tasks
+  $ kspec plan derive @plan-ref --module @core --tasks --dry-run`)
         .action(async (ref, options) => {
         try {
             const ctx = await initContext();
             const plans = await loadPlans(ctx);
-            const tasks = await loadAllTasks(ctx);
             const foundPlan = resolvePlanRef(ref, plans);
-            // AC: @plan-derive ac-5 - check plan status
-            if (foundPlan.status !== "approved" && foundPlan.status !== "active") {
-                error(`Plan must be in 'approved' or 'active' status to derive tasks (current: ${foundPlan.status})`);
-                process.exit(EXIT_CODES.USAGE_ERROR);
+            const planRef = canonicalRef(foundPlan);
+            const author = getAuthor(ctx.config?.identity?.author);
+            if (foundPlan.status === "active") {
+                exitDeriveWithGuidance("Plan already derived. Manage specs directly via kspec item set.", EXIT_CODES.CONFLICT, `Update derived work directly, for example: kspec item set ${planRef} ...`, {
+                    current_status: foundPlan.status,
+                    valid_next_states: ["manage-derived-work"],
+                });
+            }
+            if (foundPlan.status !== "approved") {
+                exitDeriveWithGuidance(`Plan must be in approved status to derive (current: ${foundPlan.status})`, EXIT_CODES.CONFLICT, `Approve the plan first with: kspec plan set ${planRef} --status approved`, {
+                    current_status: foundPlan.status,
+                    valid_next_states: ["approved"],
+                });
             }
-            // Validate priority if provided
-            if (options.priority !== undefined) {
-                const priorityResult = parseIntOption(options.priority, {
-                    min: 1,
-                    max: 5,
-                    name: "Priority",
+            const moduleRef = await resolveDeriveModuleRef(ctx, plans, foundPlan, options.module);
+            if (!moduleRef) {
+                exitDeriveWithGuidance("Plan derive requires --module when the plan has no stored module ref", EXIT_CODES.USAGE_ERROR, `Re-run with a module, for example: kspec plan derive ${planRef} --module @your-module`, {
+                    field: "module",
+                    value: null,
                 });
-                if (!priorityResult.ok) {
-                    error(priorityResult.error);
-                    process.exit(EXIT_CODES.USAGE_ERROR);
+            }
+            const parsedPlan = parsePlanDocument(foundPlan.content);
+            const errorsList = [];
+            const warnings = [];
+            const skipped = [];
+            for (const parseError of parsedPlan.errors) {
+                if (parseError.type === "yaml") {
+                    exitDeriveWithGuidance(parseError.message, EXIT_CODES.USAGE_ERROR, "Fix the YAML block in the plan document and run kspec plan derive again.", {
+                        type: parseError.type,
+                    });
                 }
-                // Replace raw string with validated number for downstream use
-                options.priority = priorityResult.value;
+                errorsList.push({
+                    type: parseError.type,
+                    message: parseError.message,
+                });
             }
-            // Generate task slug from plan title
-            const generateSlug = (title) => {
-                return title
-                    .toLowerCase()
-                    .replace(/[^a-z0-9]+/g, "-")
-                    .replace(/^-|-$/g, "")
-                    .slice(0, 50);
-            };
-            // Generate task title and slug
-            const taskTitle = options.title || `Implement: ${foundPlan.title}`;
-            let taskSlug = generateSlug(taskTitle);
-            // Ensure slug uniqueness
-            let slugSuffix = 1;
-            const originalSlug = taskSlug;
-            while (tasks.some((t) => t.slugs.includes(taskSlug))) {
-                taskSlug = `${originalSlug}-${slugSuffix}`;
-                slugSuffix++;
+            if (parsedPlan.specs.length === 0) {
+                exitDeriveWithGuidance("No specs found in plan content. Ensure ## Specs section contains a fenced YAML code block.", EXIT_CODES.USAGE_ERROR, "Add a ## Specs section with a ```yaml fenced block, then re-run derive.");
             }
-            // AC: @plan-derive ac-5 - create task with plan_ref
-            const planRef = foundPlan.slugs[0]
-                ? `@${foundPlan.slugs[0]}`
-                : `@${shortPlanRef(foundPlan, plans)}`;
-            const taskInput = {
-                title: taskTitle,
-                type: "task",
-                plan_ref: planRef,
-                priority: options.priority ?? 3,
-                slugs: [taskSlug],
-                tags: [],
-                depends_on: [],
-                notes: [],
-            };
-            const newTask = createTask(taskInput);
-            await saveTask(ctx, newTask);
-            // AC: @plan-derive ac-5 - update plan's derived_tasks array
-            const taskRef = `@${taskSlug}`;
-            const updatedPlan = await mutatePlanAtomically(ctx, foundPlan, (latestPlan) => {
-                const nextPlan = {
-                    ...latestPlan,
-                    slugs: [...latestPlan.slugs],
-                    derived_tasks: [...latestPlan.derived_tasks],
-                    derived_specs: [...latestPlan.derived_specs],
-                    notes: [...latestPlan.notes],
-                };
-                if (!nextPlan.derived_tasks.includes(taskRef)) {
-                    nextPlan.derived_tasks.push(taskRef);
+            const { refIndex, items, tasks } = await buildIndexes(ctx, plans);
+            const reservedSlugs = new Set([
+                ...plans.flatMap((plan) => plan.slugs),
+                ...items.flatMap((item) => item.slugs),
+                ...tasks.flatMap((task) => task.slugs),
+            ]);
+            const materializedSpecs = await materializePlanSpecs(ctx, foundPlan, moduleRef, parsedPlan, refIndex, items, reservedSlugs, Boolean(options.dryRun), warnings, skipped);
+            const createdSpecRefs = materializedSpecs.map((item) => item.ref);
+            let taskPlans = [];
+            if (options.tasks) {
+                taskPlans = buildTaskPlans(planRef, materializedSpecs, parsedPlan.tasks.derive_from_specs, parsedPlan.tasks.additional_tasks, refIndex, tasks, reservedSlugs, author, warnings);
+            }
+            const createdTaskRefs = taskPlans.map((taskPlan) => taskPlan.ref);
+            if (!options.dryRun) {
+                for (const taskPlan of taskPlans) {
+                    const newTask = createTask(taskPlan.input);
+                    await saveTask(ctx, newTask);
                 }
-                // AC: @plan-derive ac-5 - transition plan to active if not already
-                if (nextPlan.status === "approved") {
+                const updatedPlan = await mutatePlanAtomically(ctx, foundPlan, (latestPlan) => {
+                    const nextPlan = {
+                        ...latestPlan,
+                        slugs: [...latestPlan.slugs],
+                        derived_tasks: [...latestPlan.derived_tasks],
+                        derived_specs: [...latestPlan.derived_specs],
+                        notes: [...latestPlan.notes],
+                    };
+                    for (const specRef of createdSpecRefs) {
+                        if (!nextPlan.derived_specs.includes(specRef)) {
+                            nextPlan.derived_specs.push(specRef);
+                        }
+                    }
+                    for (const taskRef of createdTaskRefs) {
+                        if (!nextPlan.derived_tasks.includes(taskRef)) {
+                            nextPlan.derived_tasks.push(taskRef);
+                        }
+                    }
                     nextPlan.status = "active";
-                }
-                return nextPlan;
-            });
-            await commitIfShadow(ctx.shadow, "plan-derive", updatedPlan.slugs[0] || updatedPlan._ulid.slice(0, 8), taskTitle);
-            success(`Created task from plan: ${taskRef}`, {
-                task: newTask,
-                plan: updatedPlan,
+                    if (parsedPlan.implementationNotes?.trim()) {
+                        nextPlan.notes.push(createNote(parsedPlan.implementationNotes.trim(), author));
+                    }
+                    return nextPlan;
+                });
+                await commitIfShadow(ctx.shadow, "plan-derive", updatedPlan.slugs[0] || updatedPlan._ulid.slice(0, 8), `${createdSpecRefs.length} specs${options.tasks ? `, ${createdTaskRefs.length} tasks` : ""}`);
+            }
+            else if (parsedPlan.implementationNotes?.trim()) {
+                warnings.push({
+                    kind: "plan",
+                    ref: planRef,
+                    message: "Global implementation notes would be added to the plan during execution.",
+                });
+            }
+            reportWarnings(warnings);
+            emitDeriveResult({
+                dry_run: Boolean(options.dryRun),
+                plan_ref: planRef,
+                module_ref: moduleRef,
+                created_specs: createdSpecRefs,
+                created_tasks: createdTaskRefs,
+                skipped,
+                errors: errorsList,
             });
         }
         catch (err) {
-            error("Failed to derive task from plan", err);
+            error("Failed to derive plan content", err);
             process.exit(EXIT_CODES.ERROR);
         }
     });