@veewo/claw-core 0.1.62 → 0.1.63

package/dist/src/plan.js

@@ -2,12 +2,13 @@ import fs from "node:fs";
 import path from "node:path";
 import { buildCompletionHooks } from "./completion-hooks.js";
 import { ensureTaskMeta, resolveProjectContext, resolveTaskContext, resolveTaskName, saveTaskMeta } from "./context.js";
+import { resolvePlanEffectiveConfig } from "./effective-config.js";
 import { ClawError } from "./errors.js";
-import { readJsonFile, withFileLock, writeJsonFile } from "./io.js";
+import { readJsonFile, withFileLock, withSerializedAccess, writeJsonFile } from "./io.js";
 import { buildPlanEvent } from "./plan-events.js";
 import { isProcessStatus, } from "./requirements-gate.js";
 import { buildPlanViewModel } from "./plan-view.js";
-import { renderSeedTemplateText, resolveSeedPlanTemplate } from "./plan-templates.js";
+import { getTemplateTaskDoneChoices, renderSeedTemplateText, resolveSeedPlanTemplate } from "./plan-templates.js";
 import { ensureInsideDir, normalizePlanFile, slugFromFilePath } from "./paths.js";
 import { buildGoalModeObjective, buildPlanWorkflowGuidance } from "./workflow-guidance.js";
 const PLAN_STATUSES = [
@@ -98,12 +99,13 @@ export async function writePlan(input) {
         eventType,
         ...(plan.parentPlan ? { parentPlan: plan.parentPlan } : {}),
         ...(plan.parentTaskId !== undefined ? { parentTaskId: plan.parentTaskId } : {}),
-        workflowGuidance: buildPlanWorkflowGuidance({
+        workflowGuidance: await buildPlanWorkflowGuidance({
             taskName,
             planFile,
             plan,
             commandSource: input.parentTaskId !== undefined ? "subplan.create" : "plan.create",
-            projectConfig: project.projectConfig,
+            projectRoot: project.projectRoot,
+            projectConfig: resolvePlanEffectiveConfig(project.projectConfig, plan),
             host: input.host,
         }),
         plan,
@@ -125,155 +127,186 @@ export async function editPlan(input) {
             planFile,
         });
     }
-    const previous = normalizePlanDocument(readJsonFile(planPath));
-    const previousStatus = previous.status;
-    const events = [];
-    const changedTaskIds = [];
-    const completedTaskIds = [];
-    const next = structuredClone(previous);
-    const requestedStatus = input.planStatus ? normalizePlanStatus(input.planStatus) : undefined;
-    if (requestedStatus) {
-        const validation = canSetPlanStatus(previousStatus, requestedStatus);
-        if (!validation.ok) {
-            throw new ClawError(validation.code, validation.error);
+    if (input.patch?.tasks !== undefined && (input.taskId !== undefined || input.taskStatus !== undefined)) {
+        throw new ClawError("PROJECT_CONFIG_INVALID", "patch.tasks cannot be combined with taskId/taskStatus updates in the same plan edit. Update tasks and task progress in separate commands.");
+    }
+    return withSerializedAccess(planPath, async () => {
+        const previous = normalizePlanDocument(readJsonFile(planPath));
+        const previousStatus = previous.status;
+        const events = [];
+        const changedTaskIds = [];
+        const appendedTaskIds = [];
+        const completedTaskIds = [];
+        const next = structuredClone(previous);
+        const requestedStatus = input.planStatus ? normalizePlanStatus(input.planStatus) : undefined;
+        if (requestedStatus) {
+            const validation = canSetPlanStatus(previousStatus, requestedStatus);
+            if (!validation.ok) {
+                throw new ClawError(validation.code, validation.error);
+            }
+            next.status = requestedStatus;
         }
-        next.status = requestedStatus;
-    }
-    if (input.patch) {
-        applyPlanPatch(next, input.patch);
-    }
-    if (input.appendTasks?.length) {
-        if (isEnd(previous.status) && !requestedStatus && input.patch?.status === undefined) {
-            next.status = "prepare.requirements";
+        if (input.patch) {
+            applyPlanPatch(next, input.patch);
         }
-        const currentIds = new Set(next.tasks.map((taskItem) => taskItem.id));
-        const appendedTasks = normalizePlanTasks(input.appendTasks, nextAvailableTaskId(next.tasks));
-        for (const taskItem of appendedTasks) {
-            if (currentIds.has(taskItem.id)) {
-                throw new ClawError("PROJECT_CONFIG_INVALID", `Task id ${taskItem.id} already exists in plan.`);
+        if (input.appendTasks?.length) {
+            if (isEnd(previous.status) && !requestedStatus && input.patch?.status === undefined) {
+                next.status = "prepare.requirements";
+            }
+            const currentIds = new Set(next.tasks.map((taskItem) => taskItem.id));
+            const appendedTasks = normalizePlanTasks(input.appendTasks, nextAvailableTaskId(next.tasks));
+            for (const taskItem of appendedTasks) {
+                if (currentIds.has(taskItem.id)) {
+                    throw new ClawError("PROJECT_CONFIG_INVALID", `Task id ${taskItem.id} already exists in plan.`);
+                }
+                validatePlanTask(taskItem);
+                next.tasks.push(taskItem);
+                currentIds.add(taskItem.id);
+                appendedTaskIds.push(taskItem.id);
             }
-            validatePlanTask(taskItem);
-            next.tasks.push(taskItem);
-            currentIds.add(taskItem.id);
         }
-    }
-    if (input.taskId !== undefined || input.taskStatus !== undefined) {
-        if (input.taskId === undefined || input.taskStatus === undefined) {
-            throw new ClawError("PROJECT_CONFIG_INVALID", "taskId and taskStatus must be provided together when updating a plan task status.");
+        next.requirements = normalizePlanRequirements(next.requirements);
+        next.tasks = normalizePlanTasks(Array.isArray(next.tasks) ? next.tasks : []);
+        if (input.taskId !== undefined || input.taskStatus !== undefined) {
+            if (input.taskId === undefined || input.taskStatus === undefined) {
+                throw new ClawError("PROJECT_CONFIG_INVALID", "taskId and taskStatus must be provided together when updating a plan task status.");
+            }
+            if (!isProcess(next.status)) {
+                throw new ClawError("TASK_STATUS_FORBIDDEN_IN_NON_ACTIVE_PLAN", "Task progress can only be updated while plan.status is process.*. If requirements are already confirmed, move the plan to process.active first.", {
+                    planStatus: next.status,
+                    suggestedCommand: `claw plan edit --task ${task.taskName}${planFile === "plan.json" ? "" : ` --plan ${planFile}`} --plan-status process.active`,
+                });
+            }
+            const planTask = next.tasks.find((item) => item.id === input.taskId);
+            if (!planTask) {
+                throw new ClawError("PROJECT_CONFIG_INVALID", `Task id ${input.taskId} was not found in this plan.`);
+            }
+            validatePlanTaskStatus(input.taskStatus);
+            const previousTaskStatus = planTask.status;
+            planTask.status = input.taskStatus;
+            if (input.taskChoiceId !== undefined) {
+                planTask.choiceId = input.taskChoiceId;
+            }
+            else if (input.taskStatus !== "done") {
+                delete planTask.choiceId;
+            }
+            changedTaskIds.push(planTask.id);
+            if (previousTaskStatus !== "done" && input.taskStatus === "done") {
+                completedTaskIds.push(planTask.id);
+                events.push(buildPlanEvent("plan_task_completed", {
+                    planPath,
+                    planTitle: next.title,
+                    planStatus: next.status,
+                    taskId: planTask.id,
+                    affectedPlanTaskIds: [planTask.id],
+                }));
+            }
         }
-        if (!isProcess(next.status)) {
-            throw new ClawError("TASK_STATUS_FORBIDDEN_IN_NON_ACTIVE_PLAN", "Task progress can only be updated while plan.status is process.*. If requirements are already confirmed, move the plan to process.active first.", {
-                planStatus: next.status,
-                suggestedCommand: `claw plan edit --task ${task.taskName}${planFile === "plan.json" ? "" : ` --plan ${planFile}`} --plan-status process.active`,
-            });
+        await validateDoneTransitions({
+            projectRoot: task.project.projectRoot,
+            previousPlan: previous,
+            nextPlan: next,
+        });
+        validatePlanDocument(next);
+        if (next.status === "end.completed" && !next.retrospective?.summary?.trim()) {
+            throw new ClawError("RETROSPECTIVE_REQUIRED", "end.completed requires retrospective.summary before the plan can be completed.");
         }
-        const planTask = next.tasks.find((item) => item.id === input.taskId);
-        if (!planTask) {
-            throw new ClawError("PROJECT_CONFIG_INVALID", `Task id ${input.taskId} was not found in this plan.`);
+        withFileLock(planPath, () => {
+            const current = normalizePlanDocument(readJsonFile(planPath));
+            if (!plansMatch(current, previous)) {
+                throw new ClawError("PLAN_STALE_EDIT", `Plan "${planFile}" changed after this edit command read it. Re-run the edit after inspecting the latest plan state.`, {
+                    taskName: task.taskName,
+                    planFile,
+                    planPath,
+                    suggestedCommand: `claw plan show --task ${task.taskName}${planFile === "plan.json" ? "" : ` --plan ${planFile}`}`,
+                });
+            }
+            writeJsonFile(planPath, next);
+        });
+        task.meta.activePlan = planFile;
+        task.meta.rules = next.rules;
+        task.meta.status = taskMetaStatusForPlanStatus(next.status);
+        if (next.taskType !== undefined) {
+            task.meta.taskType = next.taskType;
         }
-        validatePlanTaskStatus(input.taskStatus);
-        const previousTaskStatus = planTask.status;
-        planTask.status = input.taskStatus;
-        changedTaskIds.push(planTask.id);
-        if (previousTaskStatus !== "done" && input.taskStatus === "done") {
-            completedTaskIds.push(planTask.id);
-            events.push(buildPlanEvent("plan_task_completed", {
+        saveTaskMeta(task);
+        if (previousStatus !== next.status || input.patch || changedTaskIds.length > 0 || input.appendTasks?.length) {
+            events.unshift(buildPlanEvent("plan_changed", {
                 planPath,
                 planTitle: next.title,
                 planStatus: next.status,
-                taskId: planTask.id,
-                affectedPlanTaskIds: [planTask.id],
+                previousStatus,
+                ...(changedTaskIds.length > 0 ? { affectedPlanTaskIds: changedTaskIds } : {}),
             }));
         }
-    }
-    validatePlanDocument(next);
-    if (next.status === "end.completed" && !next.retrospective?.summary?.trim()) {
-        throw new ClawError("RETROSPECTIVE_REQUIRED", "end.completed requires retrospective.summary before the plan can be completed.");
-    }
-    withFileLock(planPath, () => {
-        writeJsonFile(planPath, next);
-    });
-    task.meta.activePlan = planFile;
-    task.meta.rules = next.rules;
-    task.meta.status = taskMetaStatusForPlanStatus(next.status);
-    if (next.taskType !== undefined) {
-        task.meta.taskType = next.taskType;
-    }
-    saveTaskMeta(task);
-    if (previousStatus !== next.status || input.patch || changedTaskIds.length > 0 || input.appendTasks?.length) {
-        events.unshift(buildPlanEvent("plan_changed", {
-            planPath,
-            planTitle: next.title,
-            planStatus: next.status,
-            previousStatus,
-            ...(changedTaskIds.length > 0 ? { affectedPlanTaskIds: changedTaskIds } : {}),
-        }));
-    }
-    const completionHooks = previousStatus !== "end.completed" && next.status === "end.completed"
-        ? buildCompletionHooks({ task, planPath, plan: next })
-        : undefined;
-    if (completionHooks) {
-        events.push(buildPlanEvent("plan_completed", {
-            planPath,
-            planTitle: next.title,
-            planStatus: next.status,
-            previousStatus,
-        }));
-    }
-    let resultPlanFile = planFile;
-    let resultPlanPath = planPath;
-    let resultPlan = next;
-    if (completionHooks?.subplanClosureCandidate) {
-        const resumedParent = completeSubplanAndResumeParent({
-            task,
-            closure: completionHooks.subplanClosureCandidate,
-        });
-        resultPlanFile = resumedParent.planFile;
-        resultPlanPath = resumedParent.planPath;
-        resultPlan = resumedParent.plan;
-        task.meta.activePlan = resumedParent.planFile;
-        task.meta.rules = resumedParent.plan.rules;
-        task.meta.status = taskMetaStatusForPlanStatus(resumedParent.plan.status);
-        if (resumedParent.plan.taskType !== undefined) {
-            task.meta.taskType = resumedParent.plan.taskType;
+        const completionHooks = previousStatus !== "end.completed" && next.status === "end.completed"
+            ? buildCompletionHooks({ task, planPath, plan: next })
+            : undefined;
+        if (completionHooks) {
+            events.push(buildPlanEvent("plan_completed", {
+                planPath,
+                planTitle: next.title,
+                planStatus: next.status,
+                previousStatus,
+            }));
         }
-        else {
-            delete task.meta.taskType;
+        let resultPlanFile = planFile;
+        let resultPlanPath = planPath;
+        let resultPlan = next;
+        if (completionHooks?.subplanClosureCandidate) {
+            const resumedParent = completeSubplanAndResumeParent({
+                task,
+                closure: completionHooks.subplanClosureCandidate,
+            });
+            resultPlanFile = resumedParent.planFile;
+            resultPlanPath = resumedParent.planPath;
+            resultPlan = resumedParent.plan;
+            task.meta.activePlan = resumedParent.planFile;
+            task.meta.rules = resumedParent.plan.rules;
+            task.meta.status = taskMetaStatusForPlanStatus(resumedParent.plan.status);
+            if (resumedParent.plan.taskType !== undefined) {
+                task.meta.taskType = resumedParent.plan.taskType;
+            }
+            else {
+                delete task.meta.taskType;
+            }
+            saveTaskMeta(task);
         }
-        saveTaskMeta(task);
-    }
-    return {
-        taskName: task.taskName,
-        planPath: resultPlanPath,
-        planFile: resultPlanFile,
-        planStatus: resultPlan.status,
-        previousPlanStatus: previousStatus,
-        emittedEvents: events.map((event) => event.type),
-        changedTaskIds,
-        ...(completionHooks ? { completionHooks } : {}),
-        workflowGuidance: buildPlanWorkflowGuidance({
-            taskName: task.taskName,
-            planFile: resultPlanFile,
-            plan: resultPlan,
-            commandSource: "plan.edit",
-            projectConfig: task.project.projectConfig,
-            host: input.host,
-            ...(completionHooks?.subplanClosureCandidate
-                ? {}
-                : {
-                    previousStatus,
-                    completionHooks,
-                    changedTaskIds,
-                    completedTaskIds,
-                }),
-        }),
-        planView: buildPlanViewModel({
+        return {
             taskName: task.taskName,
+            planPath: resultPlanPath,
             planFile: resultPlanFile,
-            plan: resultPlan,
-        }),
-        events,
-    };
+            planStatus: resultPlan.status,
+            previousPlanStatus: previousStatus,
+            emittedEvents: events.map((event) => event.type),
+            changedTaskIds,
+            appendedTaskIds,
+            ...(completionHooks ? { completionHooks } : {}),
+            workflowGuidance: await buildPlanWorkflowGuidance({
+                taskName: task.taskName,
+                planFile: resultPlanFile,
+                plan: resultPlan,
+                commandSource: "plan.edit",
+                projectRoot: task.project.projectRoot,
+                projectConfig: resolvePlanEffectiveConfig(task.project.projectConfig, resultPlan),
+                host: input.host,
+                ...(completionHooks?.subplanClosureCandidate
+                    ? {}
+                    : {
+                        previousStatus,
+                        completionHooks,
+                        changedTaskIds,
+                        completedTaskIds,
+                    }),
+            }),
+            planView: buildPlanViewModel({
+                taskName: task.taskName,
+                planFile: resultPlanFile,
+                plan: resultPlan,
+            }),
+            events,
+        };
+    });
 }
 export function showPlan(input) {
     const resolved = resolveShowPlanTarget(input);
@@ -357,6 +390,9 @@ function normalizePlanRequirements(requirements) {
         acceptanceCriteria: Array.isArray(requirements?.acceptanceCriteria) ? requirements.acceptanceCriteria : [],
     };
 }
+function plansMatch(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
 function normalizePlanTasks(tasks, startId = 1) {
     const explicitIds = tasks
         .map((task) => task.id)
@@ -387,6 +423,7 @@ function normalizePlanTask(task, fallbackId) {
     const normalizedTask = {
         ...task,
         id: Number.isInteger(task.id) ? task.id : fallbackId ?? task.id,
+        status: task.status ?? "pending",
     };
     validatePlanTask(normalizedTask);
     return normalizedTask;
@@ -416,59 +453,55 @@ function validatePlanTask(task) {
         throw new ClawError("PROJECT_CONFIG_INVALID", `Plan task ${task.id} is missing title.`);
     }
     validatePlanTaskStatus(task.status);
+    if (task.choiceId !== undefined) {
+        if (typeof task.choiceId !== "string" || !task.choiceId.trim()) {
+            throw new ClawError("PROJECT_CONFIG_INVALID", `Plan task ${task.id} has an invalid choiceId.`);
+        }
+        if (task.status !== "done") {
+            throw new ClawError("PROJECT_CONFIG_INVALID", `Plan task ${task.id} can only use choiceId when status is done.`);
+        }
+    }
 }
 function validatePlanTaskStatus(status) {
     if (!PLAN_TASK_STATUSES.includes(status)) {
         throw new ClawError("PROJECT_CONFIG_INVALID", `Unsupported plan task status "${status}". Canonical values are pending, in_progress, subagent_running, done, blocked.`);
     }
 }
-function applyPlanPatch(target, patch) {
-    if (patch.title !== undefined) {
-        target.title = patch.title;
-    }
-    if (patch.goal !== undefined) {
-        target.goal = { text: patch.goal.text };
-    }
-    if (patch.summary !== undefined) {
-        target.summary = patch.summary;
-    }
-    if (patch.requirements !== undefined) {
-        target.requirements = normalizePlanRequirements(patch.requirements);
-    }
-    if (patch.taskType !== undefined) {
-        target.taskType = patch.taskType;
-    }
-    if (patch.leaveReason !== undefined) {
-        target.leaveReason = patch.leaveReason;
-    }
-    if (patch.parentPlan !== undefined) {
-        target.parentPlan = patch.parentPlan;
-    }
-    if (patch.parentTaskId !== undefined) {
-        target.parentTaskId = patch.parentTaskId;
-    }
-    if (patch.references !== undefined) {
-        target.references = patch.references;
-    }
-    if (patch.rules !== undefined) {
-        target.rules = patch.rules;
-    }
-    if (patch.retrospective !== undefined) {
-        target.retrospective = patch.retrospective;
-    }
-    if (patch.keyDecisions !== undefined) {
-        target.keyDecisions = patch.keyDecisions;
+const DELETE_PATCH_VALUE = Symbol("delete-plan-patch-value");
+function isPlainPatchObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function mergePlanPatchValue(current, patch) {
+    if (patch === null) {
+        return DELETE_PATCH_VALUE;
+    }
+    if (Array.isArray(patch)) {
+        return structuredClone(patch);
+    }
+    if (isPlainPatchObject(patch)) {
+        const base = isPlainPatchObject(current) ? structuredClone(current) : {};
+        for (const [key, value] of Object.entries(patch)) {
+            const merged = mergePlanPatchValue(base[key], value);
+            if (merged === DELETE_PATCH_VALUE) {
+                delete base[key];
+            }
+            else {
+                base[key] = merged;
+            }
+        }
+        return base;
     }
-    if (patch.tasks !== undefined) {
-        target.tasks = normalizePlanTasks(patch.tasks);
+    return patch;
+}
+function applyPlanPatch(target, patch) {
+    const merged = mergePlanPatchValue(target, patch);
+    if (!isPlainPatchObject(merged)) {
+        throw new ClawError("PROJECT_CONFIG_INVALID", "Plan patch must be a JSON object.");
     }
-    if (patch.status !== undefined) {
-        const normalized = normalizePlanStatus(patch.status);
-        if (!normalized) {
-            throw new ClawError("PLAN_STATUS_INVALID", `Unsupported plan status "${String(patch.status)}".`);
-        }
-        target.status = normalized;
+    for (const key of Object.keys(target)) {
+        delete target[key];
     }
+    Object.assign(target, merged);
 }
 async function createSeedPlan(projectRoot, projectConfig, templateName, taskName, title, goalText, status = "prepare.requirements", forcePlanning = false, host) {
     const effectiveTemplateName = templateName?.trim() || projectConfig?.defaultPlanTemplate?.trim() || defaultPlanTemplateName();
@@ -476,12 +509,17 @@ async function createSeedPlan(projectRoot, projectConfig, templateName, taskName
         projectRoot,
         templateName: effectiveTemplateName,
     });
-    const planningEnabled = forcePlanning || projectConfig?.planning !== false;
-    const planningSkill = projectConfig?.externalPlanningSkill?.trim() || "the built-in planning skill";
+    const effectiveConfig = resolvePlanEffectiveConfig(projectConfig, {
+        configOverride: template.configOverride,
+    });
+    const planningEnabled = forcePlanning || effectiveConfig?.planning !== false;
+    const planningSkill = effectiveConfig?.externalPlanningSkill?.trim() || "the built-in planning skill";
     if (!planningEnabled) {
         return {
             title: title ?? taskName,
-            status: template.planningDisabledStatus,
+            templateId: template.id,
+            ...(template.configOverride ? { configOverride: template.configOverride } : {}),
+            status: "process.active",
             goal: {
                 text: goalText ?? title ?? taskName,
             },
@@ -505,47 +543,84 @@ async function createSeedPlan(projectRoot, projectConfig, templateName, taskName
             },
         };
     }
-    const effectiveGoalText = goalText ?? title ?? taskName;
-    const activationDetail = buildActivationTaskDetail({
-        baseDetail: template.activationTask.detail,
-        goalModeDetail: template.activationTask.goalModeDetail,
-        host,
-        goalModeEnabled: projectConfig?.goalMode !== false,
-        planGoal: effectiveGoalText,
-    });
+    const effectiveTitle = title ?? template.title ?? taskName;
+    const effectiveGoalText = goalText ?? (template.goal?.text?.trim() || effectiveTitle);
+    const compiledTasks = template.tasks.map((taskItem) => ({
+        id: taskItem.id,
+        title: taskItem.title,
+        ...(taskItem.detail || taskItem.goalModeDetail
+            ? {
+                detail: buildCompiledTaskDetail({
+                    baseDetail: taskItem.detail,
+                    goalModeDetail: taskItem.goalModeDetail,
+                    host,
+                    goalModeEnabled: effectiveConfig?.goalMode !== false,
+                    planGoal: effectiveGoalText,
+                    planningSkill,
+                }),
+            }
+            : {}),
+        status: taskItem.status,
+        ...(taskItem.execution ? { execution: taskItem.execution } : {}),
+        ...(taskItem.sessionKey ? { sessionKey: taskItem.sessionKey } : {}),
+    }));
     return {
-        title: title ?? taskName,
-        status: template.planningEnabledStatus ?? status,
+        title: effectiveTitle,
+        templateId: template.id,
+        ...(template.configOverride ? { configOverride: template.configOverride } : {}),
+        status: template.status ?? status,
         goal: {
             text: effectiveGoalText,
         },
-        requirements: {
+        requirements: template.requirements ?? {
             summary: "",
             openQuestions: [],
             acceptanceCriteria: [],
         },
-        tasks: [
-            {
-                id: 1,
-                title: template.planningTask.title,
-                detail: renderSeedTemplateText(template.planningTask.detail, { planningSkill }),
-                status: "pending",
-            },
-            {
-                id: 2,
-                title: template.activationTask.title,
-                detail: activationDetail,
-                status: "pending",
-            },
-        ],
-        references: [],
-        rules: [],
-        keyDecisions: [],
-        retrospective: {
+        tasks: compiledTasks,
+        references: template.references ?? [],
+        rules: template.rules ?? [],
+        keyDecisions: template.keyDecisions ?? [],
+        retrospective: template.retrospective ?? {
             summary: "",
         },
     };
 }
+async function validateDoneTransitions(params) {
+    const { projectRoot, previousPlan, nextPlan } = params;
+    if (!nextPlan.templateId?.trim()) {
+        return;
+    }
+    const template = await resolveSeedPlanTemplate({
+        projectRoot,
+        templateName: nextPlan.templateId,
+    });
+    const previousTasks = new Map(previousPlan.tasks.map((task) => [task.id, task]));
+    for (const task of nextPlan.tasks) {
+        const previousTask = previousTasks.get(task.id);
+        const choices = getTemplateTaskDoneChoices(template, task.id);
+        const availableChoices = choices ? Object.keys(choices) : [];
+        const isDoneTransition = previousTask?.status !== "done" && task.status === "done";
+        if (isDoneTransition && choices && !task.choiceId) {
+            throw new ClawError("PROJECT_CONFIG_INVALID", `Task ${task.id} requires choiceId because this template defines onDone choices. Provide one of: ${availableChoices.join(", ")}.`, {
+                taskId: task.id,
+                availableChoices,
+            });
+        }
+        if (task.choiceId && !choices) {
+            throw new ClawError("PROJECT_CONFIG_INVALID", `Task ${task.id} does not define onDone choices, so choiceId is not allowed.`, {
+                taskId: task.id,
+            });
+        }
+        if (task.choiceId && choices && !Object.prototype.hasOwnProperty.call(choices, task.choiceId)) {
+            throw new ClawError("PROJECT_CONFIG_INVALID", `Task ${task.id} has an invalid choiceId "${task.choiceId}". Expected one of: ${availableChoices.join(", ")}.`, {
+                taskId: task.id,
+                choiceId: task.choiceId,
+                availableChoices,
+            });
+        }
+    }
+}
 function defaultPlanTemplateName() {
     return "default";
 }
@@ -562,6 +637,19 @@ function buildActivationTaskDetail(params) {
         : goalModeDetail;
     return `${baseDetail} ${normalizedGoalModeDetail} and use \`${buildGoalModeObjective(planGoal)}\` as the goal objective.`;
 }
+function buildCompiledTaskDetail(params) {
+    const renderedBase = params.baseDetail ? renderSeedTemplateText(params.baseDetail, { planningSkill: params.planningSkill }) : "";
+    if (!params.goalModeDetail) {
+        return renderedBase || undefined;
+    }
+    return buildActivationTaskDetail({
+        baseDetail: renderedBase,
+        goalModeDetail: params.goalModeDetail,
+        host: params.host,
+        goalModeEnabled: params.goalModeEnabled,
+        planGoal: params.planGoal,
+    });
+}
 function deriveTaskName(input) {
     if (input.taskName?.trim()) {
         return resolveTaskName(input.taskName);