@mcoda/core 0.1.4

package/dist/services/planning/RefineTasksService.js

@@ -0,0 +1,1328 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { AgentService } from "@mcoda/agents";
+import { DocdexClient } from "@mcoda/integrations";
+import { GlobalRepository, WorkspaceRepository } from "@mcoda/db";
+import { JobService } from "../jobs/JobService.js";
+import { RoutingService } from "../agents/RoutingService.js";
+import { createTaskKeyGenerator } from "./KeyHelpers.js";
+const DEFAULT_STRATEGY = "auto";
+const FORBIDDEN_TARGET_STATUSES = new Set(["ready_to_review", "ready_to_qa", "completed"]);
+const DEFAULT_MAX_TASKS = 250;
+const MAX_AGENT_OUTPUT_CHARS = 10000000;
+const estimateTokens = (text) => Math.max(1, Math.ceil(text.length / 4));
+const extractJson = (raw) => {
+    try {
+        const fenced = raw.match(/```json([\s\S]*?)```/);
+        const candidate = fenced ? fenced[1] : raw;
+        const start = candidate.indexOf("{");
+        const end = candidate.lastIndexOf("}");
+        if (start === -1 || end === -1 || end <= start)
+            return JSON.parse(raw);
+        return JSON.parse(candidate.slice(start, end + 1));
+    }
+    catch {
+        return undefined;
+    }
+};
+const normalizeOperation = (op) => {
+    if (!op || typeof op !== "object")
+        return op;
+    if (op.op !== "update_task")
+        return op;
+    const taskKey = op.taskKey ?? op.key ?? op.task ?? op.targetTaskKey ?? null;
+    const updates = { ...op.updates };
+    const inlineFields = ["title", "description", "acceptanceCriteria", "type", "status", "storyPoints", "priority", "dependsOn", "metadata"];
+    for (const field of inlineFields) {
+        if (op[field] !== undefined && updates[field] === undefined) {
+            updates[field] = op[field];
+        }
+    }
+    return {
+        ...op,
+        taskKey,
+        updates,
+    };
+};
+const safeParsePlan = (content) => {
+    try {
+        const parsed = JSON.parse(content);
+        if (parsed && Array.isArray(parsed.operations))
+            return parsed;
+    }
+    catch {
+        /* ignore */
+    }
+    return undefined;
+};
+const formatTaskSummary = (task) => {
+    return [
+        `- ${task.key}: ${task.title} [${task.status}${task.type ? `/${task.type}` : ""}]`,
+        task.storyPoints !== null && task.storyPoints !== undefined ? `  SP: ${task.storyPoints}` : "",
+        task.dependencies.length ? `  Depends on: ${task.dependencies.join(", ")}` : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+};
+export class RefineTasksService {
+    constructor(workspace, deps) {
+        this.workspace = workspace;
+        this.docdex = deps.docdex;
+        this.jobService = deps.jobService;
+        this.agentService = deps.agentService;
+        this.repo = deps.repo;
+        this.workspaceRepo = deps.workspaceRepo;
+        this.routingService = deps.routingService;
+    }
+    static async create(workspace) {
+        const repo = await GlobalRepository.create();
+        const agentService = new AgentService(repo);
+        const routingService = await RoutingService.create();
+        const docdex = new DocdexClient({
+            workspaceRoot: workspace.workspaceRoot,
+            baseUrl: workspace.config?.docdexUrl ?? process.env.MCODA_DOCDEX_URL,
+        });
+        const workspaceRepo = await WorkspaceRepository.create(workspace.workspaceRoot);
+        const jobService = new JobService(workspace, workspaceRepo);
+        return new RefineTasksService(workspace, {
+            docdex,
+            jobService,
+            agentService,
+            repo,
+            workspaceRepo,
+            routingService,
+        });
+    }
+    async close() {
+        const tryClose = async (target) => {
+            try {
+                if (target?.close) {
+                    await target.close();
+                }
+            }
+            catch {
+                // ignore close errors
+            }
+        };
+        await tryClose(this.agentService);
+        await tryClose(this.repo);
+        await tryClose(this.jobService);
+        await tryClose(this.workspaceRepo);
+        await tryClose(this.routingService);
+        await tryClose(this.docdex);
+    }
+    async resolveAgent(agentName) {
+        const resolved = await this.routingService.resolveAgentForCommand({
+            workspace: this.workspace,
+            commandName: "refine-tasks",
+            overrideAgentSlug: agentName,
+        });
+        return resolved.agent;
+    }
+    async selectTasks(projectKey, filters) {
+        const db = this.workspaceRepo.getDb();
+        const warnings = [];
+        const project = await this.workspaceRepo.getProjectByKey(projectKey);
+        if (!project) {
+            throw new Error(`Unknown project key: ${projectKey}`);
+        }
+        const epicRow = filters.epicKey
+            ? await db.get(`SELECT id, key, title, description FROM epics WHERE key = ? AND project_id = ?`, filters.epicKey, project.id)
+            : undefined;
+        if (filters.epicKey && !epicRow) {
+            throw new Error(`Unknown epic key ${filters.epicKey} under project ${projectKey}`);
+        }
+        const storyRow = filters.storyKey
+            ? await db.get(`SELECT id, key, epic_id, title, description, acceptance_criteria FROM user_stories WHERE key = ?`, filters.storyKey)
+            : undefined;
+        if (filters.storyKey && !storyRow) {
+            throw new Error(`Unknown user story key ${filters.storyKey}`);
+        }
+        if (filters.storyKey && epicRow && storyRow && storyRow.epic_id !== epicRow.id) {
+            throw new Error(`Story ${filters.storyKey} is not under epic ${filters.epicKey}`);
+        }
+        const clauses = ["t.project_id = ?"];
+        const params = [project.id];
+        if (epicRow) {
+            clauses.push("t.epic_id = ?");
+            params.push(epicRow.id);
+        }
+        if (storyRow) {
+            clauses.push("t.user_story_id = ?");
+            params.push(storyRow.id);
+        }
+        if (filters.taskKeys && filters.taskKeys.length > 0) {
+            clauses.push(`t.key IN (${filters.taskKeys.map(() => "?").join(", ")})`);
+            params.push(...filters.taskKeys);
+        }
+        if (filters.statusFilter && filters.statusFilter.length > 0) {
+            clauses.push(`LOWER(t.status) IN (${filters.statusFilter.map(() => "?").join(", ")})`);
+            params.push(...filters.statusFilter.map((s) => s.toLowerCase()));
+        }
+        if (filters.excludeAlreadyRefined) {
+            clauses.push(`NOT EXISTS (
+          SELECT 1
+          FROM task_runs tr
+          WHERE tr.task_id = t.id
+            AND tr.command = ?
+            AND LOWER(tr.status) = 'succeeded'
+        )`);
+            params.push("refine-tasks");
+        }
+        const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+        const limit = filters.maxTasks ? `LIMIT ${filters.maxTasks}` : "";
+        const rows = await db.all(`
+      SELECT
+        t.id AS task_id,
+        t.key AS task_key,
+        t.project_id AS project_id,
+        t.epic_id AS epic_id,
+        t.user_story_id AS story_id,
+        t.title AS task_title,
+        t.description AS task_description,
+        t.type AS task_type,
+        t.status AS task_status,
+        t.story_points AS task_story_points,
+        t.priority AS task_priority,
+        t.metadata_json AS task_metadata,
+        e.key AS epic_key,
+        e.title AS epic_title,
+        e.description AS epic_description,
+        s.key AS story_key,
+        s.title AS story_title,
+        s.description AS story_description,
+        s.acceptance_criteria AS story_acceptance
+      FROM tasks t
+      INNER JOIN epics e ON e.id = t.epic_id
+      INNER JOIN user_stories s ON s.id = t.user_story_id
+      ${where}
+      ORDER BY s.priority IS NULL, s.priority, t.priority IS NULL, t.priority, t.created_at
+      ${limit}
+    `, params);
+        const taskIds = rows.map((r) => r.task_id);
+        const depMap = new Map();
+        if (taskIds.length > 0) {
+            const depRows = await db.all(`
+        SELECT td.task_id, dep.key AS dep_key
+        FROM task_dependencies td
+        INNER JOIN tasks dep ON dep.id = td.depends_on_task_id
+        WHERE td.task_id IN (${taskIds.map(() => "?").join(", ")})
+      `, taskIds);
+            for (const dep of depRows) {
+                const list = depMap.get(dep.task_id) ?? [];
+                list.push(dep.dep_key);
+                depMap.set(dep.task_id, list);
+            }
+        }
+        const groups = new Map();
+        for (const row of rows) {
+            const acceptance = row.story_acceptance ? String(row.story_acceptance).split(/\r?\n/).filter(Boolean) : [];
+            const groupKey = row.story_id;
+            if (!groups.has(groupKey)) {
+                groups.set(groupKey, {
+                    epic: { id: row.epic_id, key: row.epic_key, title: row.epic_title, description: row.epic_description ?? undefined },
+                    story: { id: row.story_id, key: row.story_key, title: row.story_title, description: row.story_description ?? undefined, acceptance },
+                    tasks: [],
+                });
+            }
+            const group = groups.get(groupKey);
+            const task = {
+                id: row.task_id,
+                projectId: row.project_id,
+                epicId: row.epic_id,
+                userStoryId: row.story_id,
+                key: row.task_key,
+                title: row.task_title,
+                description: row.task_description ?? undefined,
+                type: row.task_type ?? undefined,
+                status: row.task_status,
+                storyPoints: row.task_story_points ?? null,
+                priority: row.task_priority ?? null,
+                assignedAgentId: null,
+                assigneeHuman: null,
+                vcsBranch: null,
+                vcsBaseBranch: null,
+                vcsLastCommitSha: null,
+                metadata: row.task_metadata ? JSON.parse(row.task_metadata) : undefined,
+                openapiVersionAtCreation: null,
+                createdAt: "",
+                updatedAt: "",
+                storyKey: row.story_key,
+                epicKey: row.epic_key,
+                dependencies: depMap.get(row.task_id) ?? [],
+            };
+            group.tasks.push(task);
+        }
+        if (filters.maxTasks && rows.length > filters.maxTasks) {
+            warnings.push(`max-tasks=${filters.maxTasks} truncated selection to ${filters.maxTasks} tasks.`);
+        }
+        return { projectId: project.id, groups: Array.from(groups.values()), warnings };
+    }
+    parseTaskKeyParts(taskKey) {
+        const match = taskKey.match(/^(.*-us-\d+)-t\d+$/);
+        if (!match)
+            return null;
+        const storyKey = match[1];
+        const epicMatch = storyKey.match(/^(.*)-us-\d+$/);
+        const epicKey = epicMatch ? epicMatch[1] : storyKey.split("-us-")[0];
+        return { storyKey, epicKey };
+    }
+    async ensureTaskExists(projectId, projectKey, taskKey, createIfMissing, seed) {
+        const parts = this.parseTaskKeyParts(taskKey);
+        if (!parts)
+            return undefined;
+        const db = this.workspaceRepo.getDb();
+        const existing = await this.workspaceRepo.getTaskByKey(taskKey);
+        const loadDeps = async (taskId) => {
+            const depRows = await db.all(`SELECT dep.key AS dep_key
+         FROM task_dependencies td
+         INNER JOIN tasks dep ON dep.id = td.depends_on_task_id
+         WHERE td.task_id = ?`, taskId);
+            return depRows.map((d) => d.dep_key);
+        };
+        const ensureEpic = async () => {
+            const row = await db.get(`SELECT id, key, title, description FROM epics WHERE key = ? AND project_id = ?`, parts.epicKey, projectId);
+            if (row)
+                return { id: row.id, key: row.key, title: row.title, description: row.description ?? undefined };
+            const [inserted] = await this.workspaceRepo.insertEpics([
+                {
+                    projectId,
+                    key: parts.epicKey,
+                    title: `Epic ${parts.epicKey}`,
+                    description: `Auto-created while applying refine plan for ${projectKey}`,
+                    storyPointsTotal: null,
+                    priority: null,
+                },
+            ], false);
+            return { id: inserted.id, key: inserted.key, title: inserted.title, description: inserted.description ?? undefined };
+        };
+        const ensureStory = async (epicId) => {
+            const row = await db.get(`SELECT id, key, title, description, acceptance_criteria FROM user_stories WHERE key = ?`, parts.storyKey);
+            if (row) {
+                const acceptance = row.acceptance_criteria ? String(row.acceptance_criteria).split(/\r?\n/).filter(Boolean) : [];
+                return {
+                    id: row.id,
+                    key: row.key,
+                    title: row.title,
+                    description: row.description ?? undefined,
+                    acceptance,
+                };
+            }
+            const [inserted] = await this.workspaceRepo.insertStories([
+                {
+                    projectId,
+                    epicId,
+                    key: parts.storyKey,
+                    title: `Story ${parts.storyKey}`,
+                    description: `Auto-created while applying refine plan for ${projectKey}`,
+                    acceptanceCriteria: undefined,
+                    storyPointsTotal: null,
+                    priority: null,
+                },
+            ], false);
+            return {
+                id: inserted.id,
+                key: inserted.key,
+                title: inserted.title,
+                description: inserted.description ?? undefined,
+                acceptance: [],
+            };
+        };
+        if (existing) {
+            const epicRow = await db.get(`SELECT id, key, title, description FROM epics WHERE id = ?`, existing.epicId);
+            const storyRow = await db.get(`SELECT id, key, title, description, acceptance_criteria FROM user_stories WHERE id = ?`, existing.userStoryId);
+            const acceptance = storyRow?.acceptance_criteria
+                ? String(storyRow.acceptance_criteria).split(/\r?\n/).filter(Boolean)
+                : [];
+            return {
+                task: {
+                    ...existing,
+                    storyKey: storyRow?.key ?? parts.storyKey,
+                    epicKey: epicRow?.key ?? parts.epicKey,
+                    dependencies: await loadDeps(existing.id),
+                },
+                epic: {
+                    id: epicRow?.id ?? existing.epicId,
+                    key: epicRow?.key ?? parts.epicKey,
+                    title: epicRow?.title ?? `Epic ${parts.epicKey}`,
+                    description: epicRow?.description ?? undefined,
+                },
+                story: {
+                    id: storyRow?.id ?? existing.userStoryId,
+                    key: storyRow?.key ?? parts.storyKey,
+                    title: storyRow?.title ?? `Story ${parts.storyKey}`,
+                    description: storyRow?.description ?? undefined,
+                    acceptance,
+                },
+            };
+        }
+        if (!createIfMissing)
+            return undefined;
+        const updates = seed?.updates ?? seed?.fields ?? {};
+        const epic = await ensureEpic();
+        const story = await ensureStory(epic.id);
+        const [task] = await this.workspaceRepo.insertTasks([
+            {
+                projectId,
+                epicId: epic.id,
+                userStoryId: story.id,
+                key: taskKey,
+                title: updates.title ?? `Task ${taskKey}`,
+                description: updates.description ?? "",
+                type: updates.type ?? "feature",
+                status: updates.status ?? "not_started",
+                storyPoints: updates.storyPoints ?? null,
+                priority: updates.priority ?? null,
+                metadata: updates.metadata ?? undefined,
+            },
+        ], false);
+        return {
+            task: {
+                ...task,
+                storyKey: story.key,
+                epicKey: epic.key,
+                dependencies: [],
+            },
+            epic,
+            story,
+        };
+    }
+    buildStoryPrompt(group, strategy, docSummary) {
+        const taskList = group.tasks.map((t) => formatTaskSummary(t)).join("\n");
+        const constraints = [
+            "- Immutable: project_id, epic_id, user_story_id, task keys.",
+            "- Allowed edits: title, description, acceptanceCriteria, metadata/labels, type, priority, storyPoints, status (but NOT ready_to_review/qa/completed).",
+            "- Splits: children stay under same story; keep parent unless keepParent=false; child dependsOn must reference existing tasks or siblings.",
+            "- Merges: target and sources must be in same story; prefer cancelling redundant sources (status=cancelled) and preserve useful details in target updates.",
+            "- Dependencies: maintain DAG; do not introduce cycles or cross-story edges.",
+            "- Story points: non-negative, keep within typical agile range (0-13).",
+            "- Do not invent new epics/stories or change parentage.",
+        ].join("\n");
+        return [
+            `You are refining tasks for epic ${group.epic.key} "${group.epic.title}" and story ${group.story.key} "${group.story.title}".`,
+            `Strategy: ${strategy}`,
+            "Story acceptance criteria:",
+            group.story.acceptance?.length ? group.story.acceptance.map((c) => `- ${c}`).join("\n") : "- (none provided)",
+            "Current tasks:",
+            taskList || "- (no tasks selected)",
+            "Doc context (summaries only):",
+            docSummary || "(none)",
+            "Recent task history (logs/comments):",
+            group.historySummary || "(none)",
+            "Constraints:",
+            constraints,
+            "Return JSON ONLY matching: { \"operations\": [UpdateTaskOp | SplitTaskOp | MergeTasksOp | UpdateEstimateOp] } where each item has an `op` discriminator (update_task|split_task|merge_tasks|update_estimate).",
+        ].join("\n\n");
+    }
+    async summarizeDocs(projectKey, epicKey, storyKey) {
+        const warnings = [];
+        const startedAt = Date.now();
+        try {
+            const docs = await this.docdex.search({
+                projectKey,
+                profile: "sds",
+                query: [epicKey, storyKey].filter(Boolean).join(" "),
+            });
+            if (!docs || docs.length === 0) {
+                return { summary: "(no relevant docdex entries)", warnings: [] };
+            }
+            const top = docs
+                .filter((doc) => {
+                const type = (doc.docType ?? "").toLowerCase();
+                return type.includes("sds") || type.includes("pdr") || type.includes("rfp");
+            })
+                .slice(0, 5);
+            const summary = top
+                .map((doc) => {
+                const segments = (doc.segments ?? []).slice(0, 3);
+                const segText = segments
+                    .map((seg, idx) => {
+                    const snippet = seg.content.length > 180 ? `${seg.content.slice(0, 180)}...` : seg.content;
+                    return `    (${idx + 1}) ${seg.heading ? `${seg.heading}: ` : ""}${snippet}`;
+                })
+                    .join("\n");
+                const head = doc.content ? doc.content.split(/\r?\n/).slice(0, 2).join(" ").slice(0, 160) : "";
+                return [`- [${doc.docType}] ${doc.title ?? doc.path ?? doc.id}${head ? ` — ${head}` : ""}`, segText].filter(Boolean).join("\n");
+            })
+                .join("\n");
+            const durationSeconds = (Date.now() - startedAt) / 1000;
+            await this.jobService.recordTokenUsage({
+                workspaceId: this.workspace.workspaceId,
+                jobId: undefined,
+                commandRunId: undefined,
+                agentId: undefined,
+                modelName: "docdex",
+                tokensPrompt: null,
+                tokensCompletion: null,
+                tokensTotal: null,
+                durationSeconds,
+                timestamp: new Date().toISOString(),
+                metadata: { command: "refine-tasks", action: "docdex_search", projectKey, epicKey, storyKey },
+            });
+            return { summary: summary || "(no doc segments found)", warnings };
+        }
+        catch (error) {
+            warnings.push(`Docdex lookup failed: ${error.message}`);
+            return { summary: "(docdex unavailable)", warnings };
+        }
+    }
+    async summarizeHistory(taskIds) {
+        if (taskIds.length === 0)
+            return "(none)";
+        const db = this.workspaceRepo.getDb();
+        const placeholders = taskIds.map(() => "?").join(", ");
+        try {
+            const rows = await db.all(`
+        SELECT r.task_id, l.timestamp, l.level, l.message, l.source
+        FROM task_logs l
+        INNER JOIN task_runs r ON r.id = l.task_run_id
+        WHERE r.task_id IN (${placeholders})
+        ORDER BY l.timestamp DESC
+        LIMIT 15
+      `, taskIds);
+            if (!rows || rows.length === 0)
+                return "(none)";
+            return rows
+                .map((row) => {
+                const level = row.level ? row.level.toUpperCase() : "INFO";
+                const msg = row.message ?? "";
+                return `- ${row.task_id}: [${level}] ${msg} (${row.source ?? "run"})`;
+            })
+                .join("\n");
+        }
+        catch {
+            return "(unavailable)";
+        }
+    }
+    async logWarningsToTasks(taskIds, jobId, commandRunId, message) {
+        const now = new Date().toISOString();
+        for (const taskId of taskIds) {
+            try {
+                const run = await this.workspaceRepo.createTaskRun({
+                    taskId,
+                    command: "refine-tasks",
+                    status: "succeeded",
+                    jobId,
+                    commandRunId,
+                    startedAt: now,
+                    finishedAt: now,
+                    runContext: { warning: true },
+                });
+                await this.workspaceRepo.insertTaskLog({
+                    taskRunId: run.id,
+                    sequence: 0,
+                    timestamp: now,
+                    level: "warn",
+                    source: "refine-tasks",
+                    message,
+                    details: { warning: true },
+                });
+            }
+            catch {
+                // Best-effort logging only.
+            }
+        }
+    }
+    mergeMetadata(existing, updates) {
+        if (!updates)
+            return existing;
+        return { ...(existing ?? {}), ...updates };
+    }
+    validateOperation(group, op) {
+        const allowedOps = new Set(["update_task", "split_task", "merge_tasks", "update_estimate"]);
+        if (!op || typeof op.op !== "string" || !allowedOps.has(op.op)) {
+            return { valid: false, reason: "Unknown op type" };
+        }
+        if (op.op === "update_task") {
+            if (!op.taskKey || typeof op.updates !== "object") {
+                return { valid: false, reason: "update_task missing taskKey or updates" };
+            }
+        }
+        if (op.op === "split_task") {
+            const split = op;
+            if (!split.taskKey || !Array.isArray(split.children) || split.children.length === 0) {
+                return { valid: false, reason: "split_task missing taskKey or children" };
+            }
+        }
+        if (op.op === "merge_tasks") {
+            if (!op.targetTaskKey || !Array.isArray(op.sourceTaskKeys) || op.sourceTaskKeys.length === 0) {
+                return { valid: false, reason: "merge_tasks missing targets" };
+            }
+        }
+        if (op.op === "update_estimate") {
+            if (!op.taskKey)
+                return { valid: false, reason: "update_estimate missing taskKey" };
+        }
+        const keySet = new Set(group.tasks.map((t) => t.key));
+        if (op.taskKey && !keySet.has(op.taskKey)) {
+            return { valid: false, reason: `Unknown task key ${op.taskKey} for story ${group.story.key}` };
+        }
+        if (op.targetTaskKey && !keySet.has(op.targetTaskKey)) {
+            return { valid: false, reason: `Unknown merge target ${op.targetTaskKey}` };
+        }
+        if (op.sourceTaskKeys) {
+            const missing = op.sourceTaskKeys.filter((k) => !keySet.has(k));
+            if (missing.length) {
+                return { valid: false, reason: `Merge sources not in story ${group.story.key}: ${missing.join(", ")}` };
+            }
+        }
+        if (op.op === "update_task" && op.updates.status && FORBIDDEN_TARGET_STATUSES.has(op.updates.status.toLowerCase())) {
+            return { valid: false, reason: `Status ${op.updates.status} not allowed in refine-tasks` };
+        }
+        if (op.op === "update_task" && op.updates.storyPoints !== undefined) {
+            const sp = op.updates.storyPoints;
+            if (sp !== null && (typeof sp !== "number" || sp < 0 || sp > 13)) {
+                return { valid: false, reason: `Story points out of bounds for ${op.taskKey}` };
+            }
+        }
+        if (op.op === "split_task") {
+            const split = op;
+            const invalidDep = split.children.some((child) => child.dependsOn?.some((dep) => !keySet.has(dep)));
+            if (invalidDep) {
+                return { valid: false, reason: "Split child references unknown dependency" };
+            }
+            if (split.children.some((child) => child.storyPoints !== undefined && child.storyPoints !== null && (child.storyPoints < 0 || child.storyPoints > 13))) {
+                return { valid: false, reason: "Child story points out of bounds" };
+            }
+            const crossStory = split.children.some((child) => child.storyKey && child.storyKey !== group.story.key);
+            if (crossStory) {
+                return { valid: false, reason: "Split children must stay within the same story" };
+            }
+        }
+        if (op.op === "merge_tasks") {
+            const crossStory = op.sourceTaskKeys.some((k) => !keySet.has(k)) ||
+                (op.targetTaskKey && !keySet.has(op.targetTaskKey));
+            if (crossStory) {
+                return { valid: false, reason: "Merge must stay within the same story" };
+            }
+            const uniqueSources = new Set(op.sourceTaskKeys.filter(Boolean));
+            if (uniqueSources.size !== op.sourceTaskKeys.length) {
+                return { valid: false, reason: "Duplicate source task keys in merge" };
+            }
+            if (uniqueSources.has(op.targetTaskKey)) {
+                return { valid: false, reason: "Merge sources cannot include target" };
+            }
+        }
+        return { valid: true };
+    }
+    detectCycle(edges) {
+        const adj = new Map();
+        for (const edge of edges) {
+            const list = adj.get(edge.from) ?? [];
+            list.push(edge.to);
+            adj.set(edge.from, list);
+        }
+        const visiting = new Set();
+        const visited = new Set();
+        const dfs = (node) => {
+            if (visiting.has(node))
+                return true;
+            if (visited.has(node))
+                return false;
+            visiting.add(node);
+            for (const nxt of adj.get(node) ?? []) {
+                if (dfs(nxt))
+                    return true;
+            }
+            visiting.delete(node);
+            visited.add(node);
+            return false;
+        };
+        for (const node of adj.keys()) {
+            if (dfs(node))
+                return true;
+        }
+        return false;
+    }
+    async applyOperations(projectId, jobId, commandRunId, group, operations) {
+        const created = [];
+        const updated = [];
+        const cancelled = [];
+        let storyPointsDelta = 0;
+        const warnings = [];
+        const taskByKey = new Map(group.tasks.map((t) => [t.key, t]));
+        await this.workspaceRepo.withTransaction(async () => {
+            let stage = "start";
+            const newTasks = [];
+            const pendingDeps = [];
+            const dependencyEdges = [];
+            try {
+                stage = "load:storyKeys";
+                const storyKeyRows = await this.workspaceRepo.getDb().all(`SELECT key FROM tasks WHERE user_story_id = ?`, group.story.id);
+                const existingKeys = storyKeyRows.map((r) => r.key);
+                const keyGen = createTaskKeyGenerator(group.story.key, existingKeys);
+                for (const op of operations) {
+                    stage = `op:${op.op}`;
+                    if (op.op === "update_task") {
+                        const target = taskByKey.get(op.taskKey);
+                        if (!target)
+                            continue;
+                        const before = { ...target };
+                        const metadata = this.mergeMetadata(target.metadata, op.updates.metadata);
+                        const beforeSp = target.storyPoints ?? 0;
+                        const afterSp = op.updates.storyPoints ?? target.storyPoints ?? null;
+                        storyPointsDelta += (afterSp ?? 0) - (beforeSp ?? 0);
+                        await this.workspaceRepo.updateTask(target.id, {
+                            title: op.updates.title ?? target.title,
+                            description: op.updates.description ?? target.description ?? null,
+                            type: op.updates.type ?? target.type ?? null,
+                            storyPoints: afterSp,
+                            priority: op.updates.priority ?? target.priority ?? null,
+                            status: op.updates.status ?? target.status,
+                            metadata,
+                        });
+                        updated.push(target.key);
+                        await this.workspaceRepo.insertTaskRevision({
+                            taskId: target.id,
+                            jobId,
+                            commandRunId,
+                            snapshotBefore: before,
+                            snapshotAfter: { ...before, ...op.updates, storyPoints: afterSp, metadata },
+                            createdAt: new Date().toISOString(),
+                        });
+                    }
+                    else if (op.op === "split_task") {
+                        const target = taskByKey.get(op.taskKey);
+                        if (!target)
+                            continue;
+                        if (op.parentUpdates) {
+                            const before = { ...target };
+                            await this.workspaceRepo.updateTask(target.id, {
+                                title: op.parentUpdates.title ?? target.title,
+                                description: op.parentUpdates.description ?? target.description ?? null,
+                                type: op.parentUpdates.type ?? target.type ?? null,
+                                storyPoints: op.parentUpdates.storyPoints ?? target.storyPoints ?? null,
+                                priority: op.parentUpdates.priority ?? target.priority ?? null,
+                                metadata: this.mergeMetadata(target.metadata, op.parentUpdates.metadata),
+                            });
+                            updated.push(target.key);
+                            await this.workspaceRepo.insertTaskRevision({
+                                taskId: target.id,
+                                jobId,
+                                commandRunId,
+                                snapshotBefore: before,
+                                snapshotAfter: {
+                                    ...before,
+                                    ...op.parentUpdates,
+                                    storyPoints: op.parentUpdates.storyPoints ?? before.storyPoints,
+                                    metadata: this.mergeMetadata(before.metadata, op.parentUpdates.metadata),
+                                },
+                                createdAt: new Date().toISOString(),
+                            });
+                        }
+                        for (const child of op.children) {
+                            const childKey = keyGen();
+                            const childSp = child.storyPoints ?? null;
+                            if (childSp) {
+                                storyPointsDelta += childSp;
+                            }
+                            const childInsert = {
+                                projectId,
+                                epicId: target.epicId,
+                                userStoryId: target.userStoryId,
+                                key: childKey,
+                                title: child.title,
+                                description: child.description ?? target.description ?? "",
+                                type: child.type ?? target.type ?? "feature",
+                                status: "not_started",
+                                storyPoints: childSp,
+                                priority: child.priority ?? target.priority ?? null,
+                                metadata: this.mergeMetadata({}, child.metadata),
+                                assignedAgentId: target.assignedAgentId ?? null,
+                                assigneeHuman: target.assigneeHuman ?? null,
+                                vcsBranch: null,
+                                vcsBaseBranch: null,
+                                vcsLastCommitSha: null,
+                                openapiVersionAtCreation: target.openapiVersionAtCreation ?? null,
+                            };
+                            newTasks.push(childInsert);
+                            const dependsOn = child.dependsOn ?? [];
+                            for (const depKey of dependsOn) {
+                                const depTask = taskByKey.get(depKey);
+                                if (depTask) {
+                                    pendingDeps.push({ childKey, dependsOnId: depTask.id, relationType: "blocks" });
+                                    dependencyEdges.push({ from: childKey, to: depTask.key });
+                                }
+                            }
+                            taskByKey.set(childKey, {
+                                ...childInsert,
+                                id: "",
+                                createdAt: "",
+                                updatedAt: "",
+                                storyKey: group.story.key,
+                                epicKey: group.epic.key,
+                                dependencies: child.dependsOn ?? [],
+                            });
+                            created.push(childKey);
+                        }
+                    }
+                    else if (op.op === "merge_tasks") {
+                        const target = taskByKey.get(op.targetTaskKey);
+                        if (!target)
+                            continue;
+                        if (op.updates) {
+                            const before = { ...target };
+                            await this.workspaceRepo.updateTask(target.id, {
+                                title: op.updates.title ?? target.title,
+                                description: op.updates.description ?? target.description ?? null,
+                                type: op.updates.type ?? target.type ?? null,
+                                storyPoints: op.updates.storyPoints ?? target.storyPoints ?? null,
+                                priority: op.updates.priority ?? target.priority ?? null,
+                                metadata: this.mergeMetadata(target.metadata, op.updates.metadata),
+                            });
+                            updated.push(target.key);
+                            await this.workspaceRepo.insertTaskRevision({
+                                taskId: target.id,
+                                jobId,
+                                commandRunId,
+                                snapshotBefore: before,
+                                snapshotAfter: {
+                                    ...before,
+                                    ...op.updates,
+                                    storyPoints: op.updates.storyPoints ?? before.storyPoints,
+                                    metadata: this.mergeMetadata(before.metadata, op.updates.metadata),
+                                },
+                                createdAt: new Date().toISOString(),
+                            });
+                        }
+                        for (const sourceKey of op.sourceTaskKeys) {
+                            const source = taskByKey.get(sourceKey);
+                            if (!source || source.key === target.key)
+                                continue;
+                            const before = { ...source };
+                            const mergedMetadata = this.mergeMetadata(source.metadata, { merged_into: target.key });
+                            await this.workspaceRepo.updateTask(source.id, {
+                                status: source.status, // do not cancel; requirement: no deletes/cancels
+                                metadata: mergedMetadata,
+                            });
+                            updated.push(source.key);
+                            await this.workspaceRepo.insertTaskRevision({
+                                taskId: source.id,
+                                jobId,
+                                commandRunId,
+                                snapshotBefore: before,
+                                snapshotAfter: { ...before, metadata: mergedMetadata },
+                                createdAt: new Date().toISOString(),
+                            });
+                        }
+                    }
+                    else if (op.op === "update_estimate") {
+                        const target = taskByKey.get(op.taskKey);
+                        if (!target)
+                            continue;
+                        const beforeSp = target.storyPoints ?? 0;
+                        const afterSp = op.storyPoints ?? target.storyPoints ?? null;
+                        storyPointsDelta += (afterSp ?? 0) - (beforeSp ?? 0);
+                        await this.workspaceRepo.updateTask(target.id, {
+                            storyPoints: afterSp,
+                            type: op.type ?? target.type ?? null,
+                            priority: op.priority ?? target.priority ?? null,
+                        });
+                        updated.push(target.key);
+                        await this.workspaceRepo.insertTaskRevision({
+                            taskId: target.id,
+                            jobId,
+                            commandRunId,
+                            snapshotBefore: { ...target },
+                            snapshotAfter: { ...target, storyPoints: afterSp, type: op.type ?? target.type ?? null, priority: op.priority ?? target.priority ?? null },
+                            createdAt: new Date().toISOString(),
+                        });
+                    }
+                }
+                if (newTasks.length > 0) {
+                    stage = "insert:newTasks";
+                    const inserted = await this.workspaceRepo.insertTasks(newTasks, false);
+                    const idByKey = new Map(inserted.map((t) => [t.key, t.id]));
+                    for (const row of inserted) {
+                        const current = taskByKey.get(row.key);
+                        if (current) {
+                            current.id = row.id;
+                            current.createdAt = row.createdAt;
+                            current.updatedAt = row.updatedAt;
+                        }
+                    }
+                    const deps = [];
+                    for (const dep of pendingDeps) {
+                        const childId = idByKey.get(dep.childKey);
+                        if (childId) {
+                            deps.push({ taskId: childId, dependsOnTaskId: dep.dependsOnId, relationType: dep.relationType });
+                        }
+                    }
+                    if (deps.length > 0) {
+                        stage = "insert:deps";
+                        await this.workspaceRepo.insertTaskDependencies(deps, false);
+                    }
+                }
+                // cycle detection on current + new dependencies (by key)
+                const edgeSet = [];
+                for (const task of group.tasks) {
+                    for (const dep of task.dependencies) {
+                        edgeSet.push({ from: task.key, to: dep });
+                    }
+                }
+                edgeSet.push(...dependencyEdges);
+                const hasCycle = this.detectCycle(edgeSet);
+                if (hasCycle) {
+                    throw new Error("Dependency cycle detected after refinement; aborting apply.");
+                }
+                stage = "rollup:story";
+                const storyTotalRow = await this.workspaceRepo.getDb().get(`SELECT SUM(story_points) AS total FROM tasks WHERE user_story_id = ?`, group.story.id);
+                await this.workspaceRepo.updateStoryPointsTotal(group.story.id, storyTotalRow?.total ?? null);
+                stage = "rollup:epic";
+                const epicTotalRow = await this.workspaceRepo.getDb().get(`SELECT SUM(story_points_total) AS total FROM user_stories WHERE epic_id = ?`, group.epic.id);
+                await this.workspaceRepo.updateEpicStoryPointsTotal(group.epic.id, epicTotalRow?.total ?? null);
+                stage = "task-runs";
+                const allTouched = [...new Set([...created, ...updated, ...cancelled])];
+                const now = new Date().toISOString();
+                for (const key of allTouched) {
+                    try {
+                        const task = group.tasks.find((t) => t.key === key) ??
+                            (await this.workspaceRepo.getDb().get(`SELECT id FROM tasks WHERE key = ?`, key));
+                        if (task && task.id) {
+                            const run = await this.workspaceRepo.createTaskRun({
+                                taskId: task.id,
+                                command: "refine-tasks",
+                                status: "succeeded",
+                                jobId,
+                                commandRunId,
+                                startedAt: now,
+                                finishedAt: now,
+                                runContext: { key },
+                            });
+                            await this.workspaceRepo.insertTaskLog({
+                                taskRunId: run.id,
+                                sequence: 0,
+                                timestamp: now,
+                                level: "info",
+                                source: "refine-tasks",
+                                message: `Applied refine operation for ${key}`,
+                                details: { opCount: operations.length },
+                            });
+                        }
+                    }
+                    catch (error) {
+                        warnings.push(`Logging failed for ${key}: ${error.message}`);
+                    }
+                }
+            }
+            catch (error) {
+                throw new Error(`refine apply failed at ${stage}: ${error.message}`);
+            }
+        });
+        return { created, updated, cancelled, storyPointsDelta, warnings };
+    }
+    async invokeAgent(agentName, prompt, stream, jobId, commandRunId, metadata) {
+        const startedAt = Date.now();
+        const agent = await this.resolveAgent(agentName);
+        const parts = [];
+        let capturedChars = 0;
+        let truncated = false;
+        const logChunk = async (chunk) => {
+            if (!chunk)
+                return;
+            await this.jobService.appendLog(jobId, chunk);
+            if (stream)
+                process.stdout.write(chunk);
+        };
+        const capture = (chunk) => {
+            if (!chunk || truncated)
+                return;
+            const next = capturedChars + chunk.length;
+            if (next > MAX_AGENT_OUTPUT_CHARS) {
+                truncated = true;
+                return;
+            }
+            parts.push(chunk);
+            capturedChars = next;
+        };
+        const formatContext = () => {
+            const meta = metadata;
+            const epic = typeof meta?.epicKey === "string" && meta.epicKey ? ` epic=${meta.epicKey}` : "";
+            const story = typeof meta?.storyKey === "string" && meta.storyKey ? ` story=${meta.storyKey}` : "";
+            return `${epic}${story}`;
+        };
+        try {
+            if (stream) {
+                const gen = await this.agentService.invokeStream(agent.id, { input: prompt, metadata: { jobId, commandRunId } });
+                for await (const chunk of gen) {
+                    const text = chunk.output ?? "";
+                    capture(text);
+                    await logChunk(text);
+                }
+            }
+            else {
+                const result = await this.agentService.invoke(agent.id, { input: prompt, metadata: { jobId, commandRunId } });
+                const text = result.output ?? "";
+                capture(text);
+                await logChunk(text);
+            }
+        }
+        catch (error) {
+            const message = error.message ?? String(error);
+            if (message.includes("Invalid string length")) {
+                throw new Error(`Agent output exceeded runtime limits (Invalid string length) while refining tasks.${formatContext()} ` +
+                    `Try rerunning with a smaller scope (e.g. --max-tasks 200, or filter by --epic/--story/--status), or disable streaming (--agent-stream false).`);
+            }
+            throw error;
+        }
+        if (truncated) {
+            throw new Error(`Agent output exceeded ${MAX_AGENT_OUTPUT_CHARS.toLocaleString()} characters while refining tasks.${formatContext()} ` +
+                `Rerun with a smaller scope (e.g. --max-tasks 200, or filter by --epic/--story/--status), or disable streaming (--agent-stream false).`);
+        }
+        const output = parts.join("");
+        const promptTokens = estimateTokens(prompt);
+        const completionTokens = estimateTokens(output);
+        const durationSeconds = (Date.now() - startedAt) / 1000;
+        await this.jobService.recordTokenUsage({
+            workspaceId: this.workspace.workspaceId,
+            agentId: agent.id,
+            modelName: agent.defaultModel,
+            jobId,
+            commandRunId,
+            projectId: undefined,
+            epicId: undefined,
+            userStoryId: undefined,
+            tokensPrompt: promptTokens,
+            tokensCompletion: completionTokens,
+            tokensTotal: promptTokens + completionTokens,
+            durationSeconds,
+            timestamp: new Date().toISOString(),
+            metadata: { command: "refine-tasks", action: "agent_refine", ...(metadata ?? {}) },
+        });
+        return { raw: output, promptTokens, completionTokens };
+    }
+    async refineTasks(options) {
+        const strategy = options.strategy ?? DEFAULT_STRATEGY;
+        const agentStream = options.agentStream !== false;
+        const applyChanges = options.apply === true; // default to no DB writes unless explicitly requested
+        const shouldDefaultMaxTasks = options.planInPath == null &&
+            options.maxTasks == null &&
+            !options.epicKey &&
+            !(options.userStoryKey ?? options.storyKey) &&
+            !(options.taskKeys && options.taskKeys.length) &&
+            !(options.statusFilter && options.statusFilter.length);
+        await this.workspaceRepo.createProjectIfMissing({
+            key: options.projectKey,
+            name: options.projectKey,
+            description: `Workspace project ${options.projectKey}`,
+        });
+        const commandRun = await this.jobService.startCommandRun("refine-tasks", options.projectKey, {
+            taskIds: options.taskKeys,
+        });
+        const job = await this.jobService.startJob("task_refinement", commandRun.id, options.projectKey, {
+            commandName: "refine-tasks",
+            payload: {
+                projectKey: options.projectKey,
+                epicKey: options.epicKey,
+                storyKey: options.userStoryKey ?? options.storyKey,
+                taskKeys: options.taskKeys,
+                statusFilter: options.statusFilter,
+                strategy,
+                maxTasks: options.maxTasks,
+                dryRun: options.dryRun,
+                fromDb: options.fromDb !== false,
+                planIn: options.planInPath,
+                planOut: options.planOutPath,
+            },
+        });
+        try {
+            if (options.fromDb === false) {
+                throw new Error("refine-tasks currently only supports DB-backed selection; set --from-db true");
+            }
+            const selection = await this.selectTasks(options.projectKey, {
+                epicKey: options.epicKey,
+                storyKey: options.userStoryKey ?? options.storyKey,
+                taskKeys: options.taskKeys,
+                statusFilter: options.statusFilter,
+                maxTasks: shouldDefaultMaxTasks ? DEFAULT_MAX_TASKS : options.maxTasks,
+                excludeAlreadyRefined: options.excludeAlreadyRefined === true,
+            });
+            const plan = {
+                strategy,
+                operations: [],
+                warnings: [...selection.warnings],
+                metadata: {
+                    generatedAt: new Date().toISOString(),
+                    projectKey: options.projectKey,
+                    epicKeys: selection.groups.map((g) => g.epic.key),
+                    storyKeys: selection.groups.map((g) => g.story.key),
+                    strategy,
+                    jobId: job.id,
+                    commandRunId: commandRun.id,
+                },
+            };
+            if (selection.groups.length === 0 && !options.planInPath) {
+                if (!options.allowEmptySelection) {
+                    throw new Error("No tasks matched the provided filters.");
+                }
+                plan.warnings?.push("No tasks matched the provided filters.");
+                await this.jobService.updateJobStatus(job.id, "completed", {
+                    payload: {
+                        dryRun: options.dryRun ?? true,
+                        operations: 0,
+                        applied: false,
+                        emptySelection: true,
+                    },
+                    processedItems: 0,
+                    totalItems: 0,
+                    lastCheckpoint: "empty_selection",
+                });
+                await this.jobService.finishCommandRun(commandRun.id, "succeeded");
+                return {
+                    jobId: job.id,
+                    commandRunId: commandRun.id,
+                    plan,
+                    applied: false,
+                    createdTasks: [],
+                    updatedTasks: [],
+                    cancelledTasks: [],
+                    summary: { tasksProcessed: 0, tasksAffected: 0, storyPointsDelta: 0 },
+                };
+            }
+            let planInput;
+            if (options.planInPath) {
+                const raw = await fs.readFile(options.planInPath, "utf8");
+                planInput = safeParsePlan(raw);
+                if (!planInput) {
+                    throw new Error(`Failed to parse plan from ${options.planInPath}`);
+                }
+                if (planInput.metadata?.projectKey && planInput.metadata.projectKey !== options.projectKey) {
+                    throw new Error(`Plan project mismatch: ${planInput.metadata.projectKey} !== ${options.projectKey}`);
+                }
+                if (planInput.metadata?.jobId && options.jobId && planInput.metadata.jobId !== options.jobId) {
+                    throw new Error(`Plan was generated for job ${planInput.metadata.jobId}, mismatch with --job-id ${options.jobId}`);
+                }
+                const mergedMeta = {
+                    generatedAt: planInput.metadata?.generatedAt ?? plan.metadata?.generatedAt ?? new Date().toISOString(),
+                    projectKey: planInput.metadata?.projectKey ?? plan.metadata?.projectKey ?? options.projectKey,
+                    epicKeys: planInput.metadata?.epicKeys ?? plan.metadata?.epicKeys,
+                    storyKeys: planInput.metadata?.storyKeys ?? plan.metadata?.storyKeys,
+                    jobId: planInput.metadata?.jobId ?? plan.metadata?.jobId,
+                    commandRunId: planInput.metadata?.commandRunId ?? plan.metadata?.commandRunId,
+                    strategy: planInput.metadata?.strategy ?? plan.metadata?.strategy ?? strategy,
+                };
+                plan.metadata = mergedMeta;
+                if (planInput.warnings)
+                    plan.warnings?.push(...planInput.warnings);
+                // Validate ops against current selection and group membership.
+                const taskToGroup = new Map();
+                selection.groups.forEach((g) => g.tasks.forEach((t) => taskToGroup.set(t.key, g)));
+                const allowCreateMissingPlanIn = false;
+                for (const rawOp of planInput.operations) {
+                    const op = normalizeOperation(rawOp);
+                    const keyCandidate = op.taskKey ?? op.targetTaskKey ?? null;
+                    let group = keyCandidate ? taskToGroup.get(keyCandidate) : undefined;
+                    if (!group && allowCreateMissingPlanIn && keyCandidate) {
+                        const ensured = await this.ensureTaskExists(selection.projectId, options.projectKey, keyCandidate, true, op);
+                        if (ensured) {
+                            group =
+                                selection.groups.find((g) => g.story.key === ensured.story.key) ??
+                                    (() => {
+                                        const newGroup = {
+                                            epic: ensured.epic,
+                                            story: ensured.story,
+                                            tasks: [],
+                                        };
+                                        selection.groups.push(newGroup);
+                                        return newGroup;
+                                    })();
+                            group.tasks.push(ensured.task);
+                            taskToGroup.set(keyCandidate, group);
+                        }
+                    }
+                    if (!group) {
+                        plan.warnings?.push(`Skipped plan-in op because task key not in selection: ${keyCandidate ?? op.op}`);
+                        continue;
+                    }
+                    const { valid, reason } = this.validateOperation(group, op);
+                    if (!valid) {
+                        if (reason)
+                            plan.warnings?.push(`Skipped plan-in op: ${reason}`);
+                        continue;
+                    }
+                    plan.operations.push(op);
+                }
+            }
+            if (!planInput) {
+                if (shouldDefaultMaxTasks) {
+                    plan.warnings?.push(`No filters were provided; defaulted --max-tasks to ${DEFAULT_MAX_TASKS} to keep refinement tractable. Pass --max-tasks explicitly to override.`);
+                }
+                for (const group of selection.groups) {
+                    try {
+                        const { summary: docSummary, warnings: docWarnings } = await this.summarizeDocs(options.projectKey, group.epic.key, group.story.key);
+                        group.docSummary = docSummary;
+                        const historySummary = await this.summarizeHistory(group.tasks.map((t) => t.id));
+                        group.historySummary = historySummary;
+                        await this.jobService.writeCheckpoint(job.id, {
+                            stage: "context_built",
+                            timestamp: new Date().toISOString(),
+                            details: { epic: group.epic.key, story: group.story.key, tasks: group.tasks.length },
+                        });
+                        if (docWarnings.length) {
+                            plan.warnings?.push(...docWarnings);
+                            // eslint-disable-next-line no-console
+                            console.warn(docWarnings.join("; "));
+                            await this.jobService.appendLog(job.id, docWarnings.join("\n"));
+                            await this.logWarningsToTasks(group.tasks.map((t) => t.id), job.id, commandRun.id, docWarnings.join("; "));
+                        }
+                        const prompt = this.buildStoryPrompt(group, strategy, docSummary);
+                        const { raw } = await this.invokeAgent(options.agentName, prompt, agentStream, job.id, commandRun.id, { epicKey: group.epic.key, storyKey: group.story.key });
+                        const parsed = extractJson(raw);
+                        const ops = parsed?.operations && Array.isArray(parsed.operations) ? parsed.operations : [];
+                        const normalized = ops.map(normalizeOperation);
+                        const filtered = normalized.filter((op) => {
+                            const { valid, reason } = this.validateOperation(group, op);
+                            if (!valid && reason) {
+                                plan.warnings?.push(`Skipped op for story ${group.story.key}: ${reason}`);
+                            }
+                            return valid;
+                        });
+                        plan.operations.push(...filtered);
+                    }
+                    catch (error) {
+                        throw new Error(`Failed while refining epic ${group.epic.key} story ${group.story.key}: ${error.message}`);
+                    }
+                }
+            }
+            // Always persist the plan to disk in a unique folder (similar to create-tasks)
+            const ensureUniquePath = async (candidate) => {
+                try {
+                    await fs.access(candidate);
+                    const dir = path.dirname(candidate);
+                    const base = path.basename(candidate, path.extname(candidate));
+                    const ext = path.extname(candidate) || ".json";
+                    const suffix = new Date().toISOString().replace(/[:.]/g, "-");
+                    return path.join(dir, `${base}-${suffix}${ext}`);
+                }
+                catch {
+                    return candidate;
+                }
+            };
+            const defaultPlanPath = path.join(this.workspace.workspaceRoot, ".mcoda", "tasks", options.projectKey, "refinements", job.id, "plan.json");
+            const requestedOutPath = options.planOutPath ? path.resolve(options.planOutPath) : defaultPlanPath;
+            const outPath = await ensureUniquePath(requestedOutPath);
+            await fs.mkdir(path.dirname(outPath), { recursive: true });
+            await fs.writeFile(outPath, JSON.stringify(plan, null, 2), "utf8");
+            await this.jobService.writeCheckpoint(job.id, {
+                stage: "plan_written",
+                timestamp: new Date().toISOString(),
+                details: { path: outPath, ops: plan.operations.length },
+            });
+            if (plan.operations.length === 0) {
+                await this.jobService.updateJobStatus(job.id, "completed", {
+                    payload: {
+                        dryRun: options.dryRun ?? !applyChanges,
+                        operations: 0,
+                        planPath: outPath,
+                        applied: false,
+                        reason: "no_operations",
+                    },
+                    processedItems: 0,
+                    totalItems: 0,
+                    lastCheckpoint: "no_operations",
+                });
+                await this.jobService.finishCommandRun(commandRun.id, "succeeded");
+                return {
+                    jobId: job.id,
+                    commandRunId: commandRun.id,
+                    plan,
+                    applied: false,
+                    createdTasks: [],
+                    updatedTasks: [],
+                    cancelledTasks: [],
+                    summary: { tasksProcessed: selection.groups.reduce((acc, g) => acc + g.tasks.length, 0), tasksAffected: 0, storyPointsDelta: 0 },
+                };
+            }
+            if (options.dryRun || !applyChanges) {
+                await this.jobService.updateJobStatus(job.id, "completed", {
+                    payload: {
+                        dryRun: options.dryRun ?? true,
+                        operations: plan.operations.length,
+                        planPath: outPath,
+                        applied: false,
+                    },
+                    processedItems: plan.operations.length,
+                    totalItems: plan.operations.length,
+                    lastCheckpoint: "dry_run",
+                });
+                await this.jobService.finishCommandRun(commandRun.id, "succeeded");
+                return {
+                    jobId: job.id,
+                    commandRunId: commandRun.id,
+                    plan,
+                    applied: false,
+                    createdTasks: [],
+                    updatedTasks: [],
+                    cancelledTasks: [],
+                    summary: { tasksProcessed: selection.groups.reduce((acc, g) => acc + g.tasks.length, 0), tasksAffected: 0 },
+                };
+            }
+            const created = [];
+            const updated = [];
+            const cancelled = [];
+            let storyPointsDelta = 0;
+            const operationsByStory = new Map();
+            for (const op of plan.operations) {
+                const key = op.taskKey ?? op.targetTaskKey ?? null;
+                if (!key)
+                    continue;
+                const group = selection.groups.find((g) => g.tasks.some((t) => t.key === key));
+                if (!group)
+                    continue;
+                const list = operationsByStory.get(group.story.id) ?? [];
+                list.push(op);
+                operationsByStory.set(group.story.id, list);
+            }
+            for (const group of selection.groups) {
+                const ops = operationsByStory.get(group.story.id) ?? [];
+                if (ops.length === 0)
+                    continue;
+                const { created: c, updated: u, cancelled: x, storyPointsDelta: delta, warnings: opWarnings } = await this.applyOperations(selection.projectId, job.id, commandRun.id, group, ops);
+                await this.jobService.writeCheckpoint(job.id, {
+                    stage: "story_applied",
+                    timestamp: new Date().toISOString(),
+                    details: { epic: group.epic.key, story: group.story.key, ops: ops.length, created: c.length, updated: u.length, cancelled: x.length },
+                });
+                if (opWarnings.length) {
+                    plan.warnings?.push(...opWarnings);
+                }
+                created.push(...c);
+                updated.push(...u);
+                cancelled.push(...x);
+                storyPointsDelta += delta;
+            }
+            await this.jobService.updateJobStatus(job.id, "completed", {
+                payload: {
+                    created: created.length,
+                    updated: updated.length,
+                    cancelled: cancelled.length,
+                    storyPointsDelta,
+                },
+                processedItems: created.length + updated.length + cancelled.length,
+                totalItems: plan.operations.length,
+                lastCheckpoint: "completed",
+            });
+            await this.jobService.finishCommandRun(commandRun.id, "succeeded");
+            return {
+                jobId: job.id,
+                commandRunId: commandRun.id,
+                plan,
+                applied: true,
+                createdTasks: created,
+                updatedTasks: updated,
+                cancelledTasks: cancelled,
+                summary: {
+                    tasksProcessed: selection.groups.reduce((acc, g) => acc + g.tasks.length, 0),
+                    tasksAffected: created.length + updated.length + cancelled.length,
+                    storyPointsDelta,
+                },
+            };
+        }
+        catch (error) {
+            const message = error.message;
+            await this.jobService.updateJobStatus(job.id, "failed", { errorSummary: message });
+            await this.jobService.finishCommandRun(commandRun.id, "failed", message);
+            throw error;
+        }
+    }
+}