@mcoda/core 0.1.8 → 0.1.11

package/dist/services/backlog/TaskOrderingService.js

@@ -2,19 +2,21 @@ import fs from "node:fs/promises";
 import { AgentService } from "@mcoda/agents";
 import { DocdexClient } from "@mcoda/integrations";
 import { GlobalRepository, WorkspaceRepository, Connection } from "@mcoda/db";
-import { PathHelper } from "@mcoda/shared";
+import { PathHelper, READY_TO_CODE_REVIEW, normalizeReviewStatuses } from "@mcoda/shared";
 import { JobService } from "../jobs/JobService.js";
 import { RoutingService } from "../agents/RoutingService.js";
-const DEFAULT_STATUSES = ["not_started", "in_progress", "blocked", "ready_to_review", "ready_to_qa"];
+import { classifyTask } from "./TaskOrderingHeuristics.js";
+const DEFAULT_STATUSES = ["not_started", "in_progress", "changes_requested", READY_TO_CODE_REVIEW, "ready_to_qa"];
 const DONE_STATUSES = new Set(["completed", "cancelled"]);
+const DEFAULT_STAGE_ORDER = ["foundation", "backend", "frontend", "other"];
 const STATUS_RANK = {
     in_progress: 0,
+    changes_requested: 0,
     not_started: 1,
-    ready_to_review: 2,
+    [READY_TO_CODE_REVIEW]: 2,
     ready_to_qa: 3,
-    blocked: 4,
-    completed: 5,
-    cancelled: 6,
+    completed: 4,
+    cancelled: 5,
 };
 const hasTables = async (db, required) => {
     const placeholders = required.map(() => "?").join(", ");
@@ -24,7 +26,8 @@ const hasTables = async (db, required) => {
 const normalizeStatuses = (statuses) => {
     if (!statuses || statuses.length === 0)
         return DEFAULT_STATUSES;
-    return Array.from(new Set(statuses.map((s) => s.toLowerCase().trim()).filter(Boolean)));
+    const normalized = Array.from(new Set(statuses.map((s) => s.toLowerCase().trim()).filter(Boolean))).filter((status) => status !== "blocked");
+    return normalizeReviewStatuses(normalized);
 };
 const estimateTokens = (text) => Math.max(1, Math.ceil((text ?? "").length / 4));
 const SDS_DEPENDENCY_GUIDE = [
@@ -32,8 +35,160 @@ const SDS_DEPENDENCY_GUIDE = [
     "- Enforce topological ordering: never place a task before any of its dependencies.",
     "- Prioritize tasks that unlock the most downstream work (direct + indirect dependents).",
     "- Tie-break by existing priority, then lower story points, then older tasks, then status (in_progress before not_started).",
-    "- Blocked tasks should remain after unblocked tasks unless explicitly requested.",
 ].join("\n");
+const extractJson = (raw) => {
+    if (!raw)
+        return undefined;
+    const fencedMatches = [...raw.matchAll(/```json([\s\S]*?)```/g)].map((match) => match[1]);
+    const stripped = raw.replace(/<think>[\s\S]*?<\/think>/g, "");
+    const candidates = [...fencedMatches, stripped, raw].filter((candidate) => candidate.trim().length > 0);
+    for (const candidate of candidates) {
+        const parsed = tryParseJson(candidate);
+        if (parsed !== undefined)
+            return parsed;
+    }
+    return undefined;
+};
+const tryParseJson = (value) => {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        // continue
+    }
+    const blocks = extractJsonBlocks(value).reverse();
+    for (const block of blocks) {
+        try {
+            return JSON.parse(block);
+        }
+        catch {
+            // continue
+        }
+    }
+    return undefined;
+};
+const extractJsonBlocks = (value) => {
+    const results = [];
+    const stack = [];
+    let start = -1;
+    let inString = false;
+    let escaped = false;
+    for (let i = 0; i < value.length; i += 1) {
+        const ch = value[i];
+        if (inString) {
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (ch === "\\") {
+                escaped = true;
+                continue;
+            }
+            if (ch === "\"")
+                inString = false;
+            continue;
+        }
+        if (ch === "\"") {
+            inString = true;
+            continue;
+        }
+        if (ch === "{") {
+            if (stack.length === 0)
+                start = i;
+            stack.push("}");
+            continue;
+        }
+        if (ch === "[") {
+            if (stack.length === 0)
+                start = i;
+            stack.push("]");
+            continue;
+        }
+        if (stack.length > 0 && ch === stack[stack.length - 1]) {
+            stack.pop();
+            if (stack.length === 0 && start >= 0) {
+                results.push(value.slice(start, i + 1));
+                start = -1;
+            }
+        }
+    }
+    return results;
+};
+export const parseDependencyInferenceOutput = (output, validTaskKeys, warnings) => {
+    const parsed = extractJson(output);
+    if (!parsed) {
+        warnings.push("Agent dependency inference output could not be parsed; skipping.");
+        return [];
+    }
+    const dependencyEntries = Array.isArray(parsed)
+        ? parsed
+        : Array.isArray(parsed?.dependencies)
+            ? parsed.dependencies
+            : Array.isArray(parsed?.deps)
+                ? parsed.deps
+                : undefined;
+    if (!Array.isArray(dependencyEntries)) {
+        warnings.push("Agent dependency inference missing dependencies list; skipping.");
+        return [];
+    }
+    const dependenciesByTask = new Map();
+    let invalidTasks = 0;
+    let invalidDeps = 0;
+    let selfDeps = 0;
+    for (const entry of dependencyEntries) {
+        const taskKey = typeof entry?.task_key === "string"
+            ? entry.task_key
+            : typeof entry?.taskKey === "string"
+                ? entry.taskKey
+                : undefined;
+        if (!taskKey || !validTaskKeys.has(taskKey)) {
+            invalidTasks += 1;
+            continue;
+        }
+        const rawDepends = entry?.depends_on ?? entry?.dependsOn;
+        if (rawDepends === undefined) {
+            continue;
+        }
+        if (!Array.isArray(rawDepends)) {
+            invalidDeps += 1;
+            continue;
+        }
+        const dependsRaw = rawDepends;
+        const deps = dependenciesByTask.get(taskKey) ?? new Set();
+        for (const dep of dependsRaw) {
+            if (typeof dep !== "string") {
+                invalidDeps += 1;
+                continue;
+            }
+            if (dep === taskKey) {
+                selfDeps += 1;
+                continue;
+            }
+            if (!validTaskKeys.has(dep)) {
+                invalidDeps += 1;
+                continue;
+            }
+            deps.add(dep);
+        }
+        if (deps.size > 0) {
+            dependenciesByTask.set(taskKey, deps);
+        }
+    }
+    if (invalidTasks > 0) {
+        warnings.push(`Agent dependency inference ignored ${invalidTasks} invalid task keys.`);
+    }
+    if (invalidDeps > 0) {
+        warnings.push(`Agent dependency inference ignored ${invalidDeps} invalid dependency keys.`);
+    }
+    if (selfDeps > 0) {
+        warnings.push(`Agent dependency inference ignored ${selfDeps} self-dependencies.`);
+    }
+    const inferred = [];
+    for (const [taskKey, deps] of dependenciesByTask.entries()) {
+        inferred.push({ taskKey, dependsOnKeys: Array.from(deps) });
+    }
+    return inferred;
+};
 export class TaskOrderingService {
     constructor(workspace, db, repo, jobService, agentService, globalRepo, routingService, docdex, recordTelemetry) {
         this.workspace = workspace;
@@ -65,9 +220,11 @@ export class TaskOrderingService {
         const globalRepo = await GlobalRepository.create();
         const agentService = new AgentService(globalRepo);
         const routingService = await RoutingService.create();
+        const docdexRepoId = workspace.config?.docdexRepoId ?? process.env.MCODA_DOCDEX_REPO_ID ?? process.env.DOCDEX_REPO_ID;
         const docdex = new DocdexClient({
             workspaceRoot: workspace.workspaceRoot,
             baseUrl: workspace.config?.docdexUrl ?? process.env.MCODA_DOCDEX_URL,
+            repoId: docdexRepoId,
         });
         return new TaskOrderingService(workspace, connection.db, repo, jobService, agentService, globalRepo, routingService, docdex, options.recordTelemetry !== false);
     }
@@ -207,6 +364,19 @@ export class TaskOrderingService {
         }
         return grouped;
     }
+    async loadMissingContext(taskIds) {
+        if (!taskIds.length)
+            return new Set();
+        const placeholders = taskIds.map(() => "?").join(", ");
+        const rows = await this.db.all(`
+        SELECT DISTINCT task_id
+        FROM task_comments
+        WHERE task_id IN (${placeholders})
+          AND LOWER(category) = 'missing_context'
+          AND (status IS NULL OR LOWER(status) = 'open')
+      `, ...taskIds);
+        return new Set(rows.map((row) => row.task_id));
+    }
     dependencyImpactMap(dependents) {
         const memo = new Map();
         const visit = (taskId, stack) => {
@@ -238,7 +408,210 @@ export class TaskOrderingService {
         }
         return memo;
     }
-    compareTasks(a, b, impact, agentRank) {
+    resolveClassification(task) {
+        const metadata = task.metadata ?? {};
+        const stage = typeof metadata.stage === "string" ? metadata.stage.toLowerCase() : undefined;
+        const foundation = typeof metadata.foundation === "boolean" ? metadata.foundation : undefined;
+        if (stage && ["foundation", "backend", "frontend", "other"].includes(stage)) {
+            return {
+                stage: stage,
+                foundation: foundation ?? stage === "foundation",
+            };
+        }
+        const inferred = classifyTask({ title: task.title, description: task.description, type: task.type ?? undefined });
+        return { stage: inferred.stage, foundation: inferred.foundation };
+    }
+    buildDependencyGraph(tasks, deps) {
+        const taskIds = new Set(tasks.map((task) => task.id));
+        const graph = new Map();
+        for (const task of tasks) {
+            const rows = deps.get(task.id) ?? [];
+            const edges = new Set();
+            for (const dep of rows) {
+                if (!dep.depends_on_task_id)
+                    continue;
+                if (!taskIds.has(dep.depends_on_task_id))
+                    continue;
+                edges.add(dep.depends_on_task_id);
+            }
+            if (edges.size > 0) {
+                graph.set(task.id, edges);
+            }
+        }
+        return graph;
+    }
+    hasDependencyPath(graph, fromId, toId) {
+        if (fromId === toId)
+            return true;
+        const visited = new Set();
+        const stack = [fromId];
+        while (stack.length > 0) {
+            const current = stack.pop();
+            if (current === toId)
+                return true;
+            if (visited.has(current))
+                continue;
+            visited.add(current);
+            const neighbors = graph.get(current);
+            if (!neighbors)
+                continue;
+            for (const next of neighbors) {
+                if (!visited.has(next))
+                    stack.push(next);
+            }
+        }
+        return false;
+    }
+    async injectFoundationDependencies(tasks, deps, warnings) {
+        const classification = new Map();
+        for (const task of tasks) {
+            classification.set(task.id, this.resolveClassification(task));
+        }
+        const foundationTasks = tasks.filter((task) => classification.get(task.id)?.foundation);
+        const nonFoundationTasks = tasks.filter((task) => !classification.get(task.id)?.foundation);
+        if (foundationTasks.length === 0 || nonFoundationTasks.length === 0)
+            return;
+        const taskById = new Map(tasks.map((task) => [task.id, task]));
+        const dependencyGraph = this.buildDependencyGraph(tasks, deps);
+        const inserts = [];
+        let skippedCycles = 0;
+        const skippedEdges = [];
+        for (const task of nonFoundationTasks) {
+            const existing = new Set((deps.get(task.id) ?? [])
+                .map((dep) => dep.depends_on_task_id ?? "")
+                .filter(Boolean));
+            for (const foundation of foundationTasks) {
+                if (task.id === foundation.id)
+                    continue;
+                if (existing.has(foundation.id))
+                    continue;
+                if (this.hasDependencyPath(dependencyGraph, foundation.id, task.id)) {
+                    skippedCycles += 1;
+                    if (skippedEdges.length < 5) {
+                        skippedEdges.push(`${task.key}->${foundation.key}`);
+                    }
+                    continue;
+                }
+                inserts.push({
+                    taskId: task.id,
+                    dependsOnTaskId: foundation.id,
+                    relationType: "inferred_foundation",
+                });
+                existing.add(foundation.id);
+                const edges = dependencyGraph.get(task.id) ?? new Set();
+                edges.add(foundation.id);
+                dependencyGraph.set(task.id, edges);
+            }
+        }
+        if (inserts.length === 0) {
+            if (skippedCycles > 0) {
+                warnings.push(`Skipped ${skippedCycles} inferred foundation deps due to cycles.`);
+                if (skippedEdges.length > 0) {
+                    warnings.push(`Skipped inferred foundation deps (cycle sample): ${skippedEdges.join(", ")}`);
+                }
+            }
+            return;
+        }
+        await this.repo.insertTaskDependencies(inserts, true);
+        for (const insert of inserts) {
+            const depList = deps.get(insert.taskId) ?? [];
+            const dependsOn = taskById.get(insert.dependsOnTaskId);
+            depList.push({
+                task_id: insert.taskId,
+                depends_on_task_id: insert.dependsOnTaskId,
+                depends_on_key: dependsOn?.key,
+                depends_on_status: dependsOn?.status,
+            });
+            deps.set(insert.taskId, depList);
+        }
+        warnings.push(`Injected ${inserts.length} inferred foundation deps.`);
+        if (skippedCycles > 0) {
+            warnings.push(`Skipped ${skippedCycles} inferred foundation deps due to cycles.`);
+            if (skippedEdges.length > 0) {
+                warnings.push(`Skipped inferred foundation deps (cycle sample): ${skippedEdges.join(", ")}`);
+            }
+        }
+    }
+    async applyInferredDependencies(tasks, deps, inferred, warnings) {
+        if (inferred.length === 0)
+            return;
+        const taskByKey = new Map(tasks.map((task) => [task.key, task]));
+        const dependencyGraph = this.buildDependencyGraph(tasks, deps);
+        const inserts = [];
+        let skippedCycles = 0;
+        const skippedEdges = [];
+        for (const entry of inferred) {
+            const task = taskByKey.get(entry.taskKey);
+            if (!task)
+                continue;
+            const existing = new Set((deps.get(task.id) ?? [])
+                .map((dep) => dep.depends_on_task_id ?? "")
+                .filter(Boolean));
+            for (const depKey of entry.dependsOnKeys) {
+                const dependsOn = taskByKey.get(depKey);
+                if (!dependsOn)
+                    continue;
+                if (dependsOn.id === task.id)
+                    continue;
+                if (existing.has(dependsOn.id))
+                    continue;
+                if (this.hasDependencyPath(dependencyGraph, dependsOn.id, task.id)) {
+                    skippedCycles += 1;
+                    if (skippedEdges.length < 5) {
+                        skippedEdges.push(`${task.key}->${dependsOn.key}`);
+                    }
+                    continue;
+                }
+                inserts.push({
+                    taskId: task.id,
+                    dependsOnTaskId: dependsOn.id,
+                    relationType: "inferred_agent",
+                });
+                existing.add(dependsOn.id);
+                const edges = dependencyGraph.get(task.id) ?? new Set();
+                edges.add(dependsOn.id);
+                dependencyGraph.set(task.id, edges);
+            }
+        }
+        if (inserts.length === 0) {
+            if (skippedCycles > 0) {
+                warnings.push(`Skipped ${skippedCycles} inferred agent deps due to cycles.`);
+                if (skippedEdges.length > 0) {
+                    warnings.push(`Skipped inferred agent deps (cycle sample): ${skippedEdges.join(", ")}`);
+                }
+            }
+            return;
+        }
+        await this.repo.insertTaskDependencies(inserts, true);
+        const taskById = new Map(tasks.map((task) => [task.id, task]));
+        for (const insert of inserts) {
+            const depList = deps.get(insert.taskId) ?? [];
+            const dependsOn = taskById.get(insert.dependsOnTaskId);
+            depList.push({
+                task_id: insert.taskId,
+                depends_on_task_id: insert.dependsOnTaskId,
+                depends_on_key: dependsOn?.key,
+                depends_on_status: dependsOn?.status,
+            });
+            deps.set(insert.taskId, depList);
+        }
+        warnings.push(`Applied ${inserts.length} inferred agent deps.`);
+        if (skippedCycles > 0) {
+            warnings.push(`Skipped ${skippedCycles} inferred agent deps due to cycles.`);
+            if (skippedEdges.length > 0) {
+                warnings.push(`Skipped inferred agent deps (cycle sample): ${skippedEdges.join(", ")}`);
+            }
+        }
+    }
+    compareTasks(a, b, impact, agentRank, stageOrderMap) {
+        const priorityA = a.priority ?? Number.MAX_SAFE_INTEGER;
+        const priorityB = b.priority ?? Number.MAX_SAFE_INTEGER;
+        if (priorityA !== priorityB)
+            return priorityA - priorityB;
+        const impactA = impact.get(a.id)?.total ?? 0;
+        const impactB = impact.get(b.id)?.total ?? 0;
+        if (impactA !== impactB)
+            return impactB - impactA;
         const rankA = agentRank?.get(a.id);
         const rankB = agentRank?.get(b.id);
         if (rankA !== undefined || rankB !== undefined) {
@@ -249,14 +622,17 @@ export class TaskOrderingService {
             if (rankA !== rankB)
                 return rankA - rankB;
         }
-        const impactA = impact.get(a.id)?.total ?? 0;
-        const impactB = impact.get(b.id)?.total ?? 0;
-        if (impactA !== impactB)
-            return impactB - impactA;
-        const priorityA = a.priority ?? Number.MAX_SAFE_INTEGER;
-        const priorityB = b.priority ?? Number.MAX_SAFE_INTEGER;
-        if (priorityA !== priorityB)
-            return priorityA - priorityB;
+        const classA = this.resolveClassification(a);
+        const classB = this.resolveClassification(b);
+        if (classA.foundation !== classB.foundation) {
+            return classA.foundation ? -1 : 1;
+        }
+        if (stageOrderMap) {
+            const stageA = stageOrderMap.get(classA.stage) ?? stageOrderMap.get("other") ?? Number.MAX_SAFE_INTEGER;
+            const stageB = stageOrderMap.get(classB.stage) ?? stageOrderMap.get("other") ?? Number.MAX_SAFE_INTEGER;
+            if (stageA !== stageB)
+                return stageA - stageB;
+        }
         const spA = a.story_points ?? Number.POSITIVE_INFINITY;
         const spB = b.story_points ?? Number.POSITIVE_INFINITY;
         if (spA !== spB)
@@ -271,7 +647,7 @@ export class TaskOrderingService {
             return statusA - statusB;
         return a.key.localeCompare(b.key);
     }
-    topologicalSort(tasks, edges, impact, agentRank) {
+    topologicalSort(tasks, edges, impact, agentRank, stageOrderMap) {
         const indegree = new Map();
         const taskMap = new Map(tasks.map((t) => [t.id, t]));
         for (const task of tasks) {
@@ -285,7 +661,7 @@ export class TaskOrderingService {
             }
         }
         const queue = tasks.filter((t) => (indegree.get(t.id) ?? 0) === 0);
-        const sortQueue = () => queue.sort((a, b) => this.compareTasks(a, b, impact, agentRank));
+        const sortQueue = () => queue.sort((a, b) => this.compareTasks(a, b, impact, agentRank, stageOrderMap));
         sortQueue();
         const ordered = [];
         const visited = new Set();
@@ -313,7 +689,7 @@ export class TaskOrderingService {
                 }
             }
             const remaining = tasks.filter((t) => !visited.has(t.id));
-            remaining.sort((a, b) => this.compareTasks(a, b, impact, agentRank));
+            remaining.sort((a, b) => this.compareTasks(a, b, impact, agentRank, stageOrderMap));
             ordered.push(...remaining);
         }
         return { ordered, cycle, cycleMembers };
@@ -324,29 +700,23 @@ export class TaskOrderingService {
         const missingRefs = new Set();
         const nodes = tasks.map((task) => {
             const taskDeps = deps.get(task.id) ?? [];
-            const blockedBy = [];
             const missing = [];
             for (const dep of taskDeps) {
                 const status = dep.depends_on_status?.toLowerCase();
                 if (!dep.depends_on_task_id) {
                     missing.push(dep.depends_on_key ?? "unknown");
                     missingRefs.add(dep.depends_on_key ?? "unknown");
-                    blockedBy.push(dep.depends_on_key ?? "unknown");
                     continue;
                 }
                 const inScope = taskIds.has(dep.depends_on_task_id);
                 const isDone = DONE_STATUSES.has(status ?? "");
                 if (!inScope) {
                     if (!isDone) {
-                        blockedBy.push(dep.depends_on_key ?? dep.depends_on_task_id);
                         missing.push(dep.depends_on_key ?? dep.depends_on_task_id);
                         missingRefs.add(dep.depends_on_key ?? dep.depends_on_task_id);
                     }
                     continue;
                 }
-                if (!isDone) {
-                    blockedBy.push(dep.depends_on_key ?? dep.depends_on_task_id);
-                }
                 const list = dependents.get(dep.depends_on_task_id) ?? [];
                 list.push(task.id);
                 dependents.set(dep.depends_on_task_id, list);
@@ -354,7 +724,6 @@ export class TaskOrderingService {
             return {
                 ...task,
                 dependencies: taskDeps,
-                blockedBy,
                 missingDependencies: missing,
             };
         });
@@ -388,12 +757,20 @@ export class TaskOrderingService {
         return { output: result.output, adapter: result.adapter };
     }
     applyAgentRanking(ordered, agentOutput, warnings) {
+        const parsed = extractJson(agentOutput);
+        if (!parsed) {
+            warnings.push("Agent output could not be parsed; using dependency-only ordering.");
+            return undefined;
+        }
+        const order = Array.isArray(parsed) ? parsed : parsed.order;
+        if (!Array.isArray(order)) {
+            warnings.push("Agent output missing order list; using dependency-only ordering.");
+            return undefined;
+        }
         try {
-            const parsed = JSON.parse(agentOutput);
-            const order = parsed.order ?? [];
             const ranking = new Map();
             order.forEach((entry, idx) => {
-                const key = entry.task_key ?? entry.key;
+                const key = typeof entry === "string" ? entry : entry.task_key ?? entry.taskKey ?? entry.key;
                 if (typeof key === "string") {
                     ranking.set(key, idx);
                 }
@@ -414,6 +791,45 @@ export class TaskOrderingService {
             return undefined;
         }
     }
+    async inferDependenciesWithAgent(agent, tasks, context) {
+        const summary = {
+            project: context.project.key,
+            epic: context.epic?.key,
+            story: context.story?.key,
+            tasks: tasks.map((task) => ({
+                task_key: task.key,
+                epic_key: task.epic_key,
+                story_key: task.story_key,
+                title: task.title,
+                description: task.description,
+                type: task.type,
+                depends_on: (task.dependencies ?? [])
+                    .map((dep) => dep.depends_on_key ?? dep.depends_on_task_id)
+                    .filter(Boolean),
+            })),
+        };
+        const prompt = [
+            "You are inferring dependencies across epics, stories, and tasks.",
+            "Return ONLY JSON matching:",
+            `{"dependencies":[{"task_key":"<key>","depends_on":["<key>"]}]}`,
+            "Only include task_key values from the input.",
+            "Do not add self-dependencies. Omit empty depends_on arrays.",
+            context.docContext ? `Doc context:\n${context.docContext.content}` : undefined,
+            "Task summary:",
+            JSON.stringify(summary, null, 2),
+        ]
+            .filter(Boolean)
+            .join("\n\n");
+        const { output } = await this.invokeAgent(agent, prompt, context.stream, {
+            command: "order-tasks",
+            phase: "infer_dependencies",
+            project: context.project.key,
+            epic: context.epic?.key,
+            story: context.story?.key,
+        });
+        const taskKeys = new Set(tasks.map((task) => task.key));
+        return parseDependencyInferenceOutput(output, taskKeys, context.warnings);
+    }
     async persistPriorities(ordered, epicMap, storyMap) {
         await this.repo.withTransaction(async () => {
             for (let i = 0; i < ordered.length; i += 1) {
@@ -440,7 +856,7 @@ export class TaskOrderingService {
             }
         });
     }
-    mapResult(ordered, blockedSet, impact, cycleMembers) {
+    mapResult(ordered, impact, cycleMembers) {
         const result = ordered.map((task, idx) => ({
             taskId: task.id,
             taskKey: task.key,
@@ -453,15 +869,12 @@ export class TaskOrderingService {
             storyId: task.story_id,
             storyKey: task.story_key,
             storyTitle: task.story_title,
-            blocked: blockedSet.has(task.id),
-            blockedBy: task.blockedBy,
             dependencyKeys: (task.dependencies ?? []).map((d) => d.depends_on_key ?? d.depends_on_task_id ?? "").filter(Boolean),
             dependencyImpact: impact.get(task.id) ?? { direct: 0, total: 0 },
             cycleDetected: cycleMembers.has(task.id) || undefined,
             metadata: task.metadata,
         }));
-        const blocked = result.filter((t) => t.blocked);
-        return { ordered: result, blocked };
+        return { ordered: result };
     }
     async orderTasks(request) {
         if (!request.projectKey) {
@@ -469,6 +882,9 @@ export class TaskOrderingService {
         }
         const statuses = normalizeStatuses(request.statusFilter);
         const warnings = [];
+        if (request.statusFilter?.some((status) => status.toLowerCase().trim() === "blocked")) {
+            warnings.push("Status 'blocked' is no longer supported; ignoring it in order-tasks.");
+        }
         const commandRun = this.recordTelemetry
             ? await this.jobService.startCommandRun("order-tasks", request.projectKey, {
                 taskIds: undefined,
@@ -486,7 +902,6 @@ export class TaskOrderingService {
                     storyKey: request.storyKey,
                     assignee: request.assignee,
                     statuses,
-                    includeBlocked: request.includeBlocked === true,
                     agent: request.agentName,
                 },
             })
@@ -506,42 +921,89 @@ export class TaskOrderingService {
             }
             const tasks = await this.fetchTasks(project.id, epic?.id, statuses, story?.id, request.assignee);
             const deps = await this.fetchDependencies(tasks.map((t) => t.id));
-            const { nodes, dependents, missingRefs } = this.buildNodes(tasks, deps);
+            if (request.injectFoundationDeps !== false) {
+                await this.injectFoundationDependencies(tasks, deps, warnings);
+            }
+            let { nodes, dependents, missingRefs } = this.buildNodes(tasks, deps);
+            const enableAgentRanking = Boolean(request.agentName);
+            const enableInference = request.inferDependencies === true;
+            const useAgent = enableAgentRanking || enableInference;
+            const agentStream = request.agentStream !== false;
+            let docContext;
+            if (useAgent) {
+                docContext = await this.buildDocContext(project.key, warnings);
+                if (docContext && commandRun && this.recordTelemetry) {
+                    const contextTokens = estimateTokens(docContext.content);
+                    await this.jobService.recordTokenUsage({
+                        workspaceId: this.workspace.workspaceId,
+                        projectId: project.id,
+                        commandRunId: commandRun.id,
+                        jobId: job?.id,
+                        timestamp: new Date().toISOString(),
+                        commandName: "order-tasks",
+                        action: "docdex_context",
+                        tokensPrompt: contextTokens,
+                        tokensTotal: contextTokens,
+                        metadata: { source: docContext.source },
+                    });
+                }
+            }
+            let resolvedAgent;
+            if (useAgent) {
+                try {
+                    resolvedAgent = await this.resolveAgent(request.agentName);
+                }
+                catch (error) {
+                    warnings.push(`Agent resolution failed: ${error.message}`);
+                }
+            }
+            if (enableInference && resolvedAgent) {
+                try {
+                    const inferred = await this.inferDependenciesWithAgent(resolvedAgent, nodes, {
+                        project,
+                        epic,
+                        story,
+                        docContext,
+                        stream: agentStream,
+                        warnings,
+                    });
+                    await this.applyInferredDependencies(tasks, deps, inferred, warnings);
+                    ({ nodes, dependents, missingRefs } = this.buildNodes(tasks, deps));
+                }
+                catch (error) {
+                    warnings.push(`Dependency inference skipped: ${error.message}`);
+                }
+            }
+            else if (enableInference && !resolvedAgent) {
+                warnings.push("Dependency inference skipped: no agent resolved.");
+            }
             if (missingRefs.size > 0) {
                 warnings.push(`Missing dependencies referenced: ${Array.from(missingRefs).join(", ")}`);
             }
-            const blockedSet = new Set();
-            for (const node of nodes) {
-                if (node.blockedBy.length > 0 || node.status.toLowerCase() === "blocked") {
-                    blockedSet.add(node.id);
+            const missingContext = await this.loadMissingContext(nodes.map((node) => node.id));
+            if (missingContext.size > 0) {
+                warnings.push(`Tasks with open missing_context comments: ${Array.from(missingContext).length}`);
+            }
+            const stageOrder = (request.stageOrder && request.stageOrder.length > 0
+                ? request.stageOrder
+                : DEFAULT_STAGE_ORDER);
+            const stageOrderMap = new Map();
+            for (const [idx, stage] of stageOrder.entries()) {
+                if (["foundation", "backend", "frontend", "other"].includes(stage)) {
+                    stageOrderMap.set(stage, idx);
                 }
             }
+            if (stageOrderMap.size === 0) {
+                DEFAULT_STAGE_ORDER.forEach((stage, idx) => stageOrderMap.set(stage, idx));
+            }
             const impact = this.dependencyImpactMap(dependents);
-            const { ordered: initialOrder, cycle, cycleMembers } = this.topologicalSort(nodes, dependents, impact);
+            const { ordered: initialOrder, cycle, cycleMembers } = this.topologicalSort(nodes, dependents, impact, undefined, stageOrderMap);
             if (cycle) {
                 warnings.push("Dependency cycle detected; ordering may be partial.");
             }
             let agentRank;
-            const docContext = await this.buildDocContext(project.key, warnings);
-            if (docContext && commandRun && this.recordTelemetry) {
-                const contextTokens = estimateTokens(docContext.content);
-                await this.jobService.recordTokenUsage({
-                    workspaceId: this.workspace.workspaceId,
-                    projectId: project.id,
-                    commandRunId: commandRun.id,
-                    jobId: job?.id,
-                    timestamp: new Date().toISOString(),
-                    commandName: "order-tasks",
-                    action: "docdex_context",
-                    tokensPrompt: contextTokens,
-                    tokensTotal: contextTokens,
-                    metadata: { source: docContext.source },
-                });
-            }
-            const enableAgent = request.agentName !== undefined || this.recordTelemetry;
-            if (enableAgent) {
+            if (enableAgentRanking && resolvedAgent) {
                 try {
-                    const agent = await this.resolveAgent(request.agentName);
                     const summary = {
                         project: project.key,
                         epic: epic?.key,
@@ -570,13 +1032,12 @@ export class TaskOrderingService {
                     ]
                         .filter(Boolean)
                         .join("\n\n");
-                    const { output } = await this.invokeAgent(agent, prompt, request.agentStream !== false, {
+                    const { output } = await this.invokeAgent(resolvedAgent, prompt, agentStream, {
                         command: "order-tasks",
                         project: project.key,
                         epic: epic?.key,
                         story: story?.key,
                         statuses,
-                        includeBlocked: request.includeBlocked === true,
                     });
                     const promptTokens = estimateTokens(prompt);
                     const completionTokens = estimateTokens(output);
@@ -586,8 +1047,8 @@ export class TaskOrderingService {
                             projectId: project.id,
                             commandRunId: commandRun.id,
                             jobId: job?.id,
-                            agentId: agent.id,
-                            modelName: agent.defaultModel,
+                            agentId: resolvedAgent.id,
+                            modelName: resolvedAgent.defaultModel,
                             timestamp: new Date().toISOString(),
                             commandName: "order-tasks",
                             action: "ordering_tasks",
@@ -597,13 +1058,14 @@ export class TaskOrderingService {
                             tokensCompletion: completionTokens,
                             tokensTotal: promptTokens + completionTokens,
                             metadata: {
-                                adapter: agent.adapter,
+                                adapter: resolvedAgent.adapter,
                                 epicKey: epic?.key,
                                 storyKey: story?.key,
-                                includeBlocked: request.includeBlocked === true,
                                 statusFilter: statuses,
-                                agentSlug: agent.slug,
-                                modelName: agent.defaultModel,
+                                agentSlug: resolvedAgent.slug,
+                                modelName: resolvedAgent.defaultModel,
+                                phase: "agent_ordering",
+                                attempt: 1,
                             },
                         });
                     }
@@ -613,14 +1075,15 @@ export class TaskOrderingService {
                     warnings.push(`Agent refinement skipped: ${error.message}`);
                 }
             }
-            const { ordered, cycle: cycleAfterAgent, cycleMembers: agentCycleMembers } = this.topologicalSort(nodes, dependents, impact, agentRank);
+            else if (enableAgentRanking && !resolvedAgent) {
+                warnings.push("Agent refinement skipped: no agent resolved.");
+            }
+            const { ordered, cycle: cycleAfterAgent, cycleMembers: agentCycleMembers } = this.topologicalSort(nodes, dependents, impact, agentRank, stageOrderMap);
             const finalCycleMembers = new Set([...cycleMembers, ...agentCycleMembers]);
             if (cycleAfterAgent && !cycle) {
                 warnings.push("Agent-influenced ordering encountered a cycle; used partial order.");
             }
-            const blockedTasks = ordered.filter((t) => blockedSet.has(t.id));
-            const unblockedTasks = ordered.filter((t) => !blockedSet.has(t.id));
-            const prioritized = [...unblockedTasks, ...blockedTasks];
+            const prioritized = ordered;
             const epicMap = new Map();
             const storyMap = new Map();
             prioritized.forEach((task, idx) => {
@@ -633,16 +1096,13 @@ export class TaskOrderingService {
                 storyMap.set(task.story_id, storyTasks);
             });
             await this.persistPriorities(prioritized, epicMap, storyMap);
-            const mapped = this.mapResult(prioritized, blockedSet, impact, finalCycleMembers);
-            const visibleOrdered = request.includeBlocked ? mapped.ordered : mapped.ordered.filter((t) => !t.blocked);
-            const visibleBlocked = request.includeBlocked ? [] : mapped.blocked;
+            const mapped = this.mapResult(prioritized, impact, finalCycleMembers);
             if (job) {
                 await this.jobService.updateJobStatus(job.id, "completed", {
                     processedItems: mapped.ordered.length,
                     payload: {
                         warnings,
                         statuses,
-                        includeBlocked: request.includeBlocked === true,
                         epicKey: epic?.key,
                         storyKey: story?.key,
                     },
@@ -654,8 +1114,7 @@ export class TaskOrderingService {
             return {
                 project,
                 epic,
-                ordered: visibleOrdered,
-                blocked: visibleBlocked,
+                ordered: mapped.ordered,
                 warnings,
                 jobId: job?.id,
                 commandRunId: commandRun?.id,