xcoder-dna 0.0.0-stage → 1.3.0

package/dist/protocol/wks-protocol-manager.d.ts

@@ -0,0 +1,22 @@
+import type { Role } from "../types.js";
+/**
+ * The set of keys that can appear as a top-level section heading in
+ * `wks_protocol.md`. Every known `Role` is valid, plus `master-orchestrator`
+ * for the orchestrator's own protocol section.
+ */
+export type WksProtocolKey = Role | "master-orchestrator";
+/**
+ * A map from protocol key to its section body text. Keys not present in the
+ * file are undefined; keys with an empty section produce an empty string.
+ */
+export type WksProtocolMap = Partial<Record<WksProtocolKey, string>>;
+/**
+ * Parses the full text of `wks_protocol.md` and returns a map from
+ * section heading (Role name or `master-orchestrator`) to that section's
+ * verbatim body. Headings are identified by lines that match
+ * `# role_name:` (hash, space, identifier, colon). Everything between one
+ * heading and the next (or EOF) is the section body. Unknown headings are
+ * silently skipped. Trailing blank lines in each body are trimmed.
+ * An empty file or one with no recognised headings returns an empty map.
+ */
+export declare function parseWksProtocol(markdown: string): WksProtocolMap;

package/dist/protocol/wks-protocol-manager.js

@@ -0,0 +1,72 @@
+/**
+ * Parses the full text of `wks_protocol.md` and returns a map from
+ * section heading (Role name or `master-orchestrator`) to that section's
+ * verbatim body. Headings are identified by lines that match
+ * `# role_name:` (hash, space, identifier, colon). Everything between one
+ * heading and the next (or EOF) is the section body. Unknown headings are
+ * silently skipped. Trailing blank lines in each body are trimmed.
+ * An empty file or one with no recognised headings returns an empty map.
+ */
+export function parseWksProtocol(markdown) {
+    const map = {};
+    if (!markdown)
+        return map;
+    const lines = markdown.split("\n");
+    // Only lines matching exactly "# <key>:" are section boundaries.
+    const headingRegex = /^#\s+([a-z][a-z-]*):\s*$/;
+    let currentKey = null;
+    let currentBody = [];
+    function flushSection() {
+        if (currentKey) {
+            // Trim trailing blank lines.
+            while (currentBody.length && currentBody[currentBody.length - 1].trim() === "") {
+                currentBody.pop();
+            }
+            map[currentKey] = currentBody.join("\n");
+        }
+        currentBody = [];
+    }
+    for (const line of lines) {
+        const match = headingRegex.exec(line);
+        if (match) {
+            flushSection();
+            const key = match[1];
+            // Only accept recognised Role names or 'master-orchestrator'.
+            if (isRecognisedKey(key)) {
+                currentKey = key;
+            }
+            else {
+                // Unknown heading — skip until the next recognised heading.
+                currentKey = null;
+            }
+        }
+        else if (currentKey) {
+            currentBody.push(line);
+        }
+        // If we don't have a currentKey, we skip the line (between unknown headings).
+    }
+    flushSection();
+    return map;
+}
+/**
+ * All known Role values plus `master-orchestrator`. We inline this list
+ * rather than importing every directive so the protocol manager stays
+ * decoupled from the role registry — it just validates against a fixed
+ * set of strings that happen to match the Role union.
+ */
+const RECOGNISED_KEYS = new Set([
+    "requirements-analyst",
+    "architect",
+    "programmer",
+    "refactorer",
+    "tester",
+    "ui-api-tester",
+    "technical-writer",
+    "devops",
+    "conversation",
+    "business-analyst",
+    "master-orchestrator",
+]);
+function isRecognisedKey(key) {
+    return RECOGNISED_KEYS.has(key);
+}

package/dist/sdlc-runtime/conversation-runner.d.ts

@@ -0,0 +1,8 @@
+import type { TaskRun, TaskSpec } from "../types.js";
+import type { WksProtocolMap } from "../protocol/wks-protocol-manager.js";
+import type { OrchestratorOptions } from "./sdlc-orchestrator.js";
+/**
+ * Lightweight single-subagent dispatch for conversation tasks.
+ * Returns the completed TaskRun.
+ */
+export declare function runConversation(spec: TaskSpec, opts: OrchestratorOptions, protocolMap: WksProtocolMap, masterProtocolSection: string | undefined): Promise<TaskRun>;

package/dist/sdlc-runtime/conversation-runner.js

@@ -0,0 +1,64 @@
+import { SubAgent } from "../agents/sub-agent.js";
+import { saveTaskRun } from "../store/task-store.js";
+import { emitXcoderEvent } from "../events/bus.js";
+import * as term from "../util/terminal.js";
+import { dagSnapshot } from "./dag-utils.js";
+/**
+ * Lightweight single-subagent dispatch for conversation tasks.
+ * Returns the completed TaskRun.
+ */
+export async function runConversation(spec, opts, protocolMap, masterProtocolSection) {
+    term.taskIntro(spec.taskId, spec.goal);
+    emitXcoderEvent({ type: "task:intro", taskId: spec.taskId, data: { goal: spec.goal, conversation: true } });
+    const node = {
+        id: "conversation",
+        stage: "conversation",
+        role: "conversation",
+        engine: "react-v1",
+        dependsOn: [],
+        goal: spec.goal,
+        upstreamContext: {},
+        deliverableSpec: "A direct answer.",
+        acceptanceCriteria: [],
+        status: "ready",
+        healing: { attempts: 0, maxAttempts: 0, log: [] },
+    };
+    const agent = new SubAgent({
+        taskId: spec.taskId,
+        workspaceRoot: opts.workspaceRoot,
+        llm: opts.llm,
+    });
+    const result = await agent.run(node);
+    node.status = result.crashed ? "failed" : "done";
+    node.result = result;
+    const run = {
+        spec,
+        dag: [node],
+        status: result.crashed ? "escalated" : "done",
+        escalations: result.crashed
+            ? [{ subtaskId: node.id, reason: result.summary }]
+            : [],
+        orchestratorTrace: [
+            {
+                thought: "classified as conversation — lightweight path, no plan",
+                action: null,
+                observation: result.summary,
+            },
+        ],
+        finalDeliverable: result.summary,
+        totalTokenUsage: result.tokenUsage,
+    };
+    await saveTaskRun(opts.workspaceRoot, run);
+    emitXcoderEvent({ type: "task:dag", taskId: spec.taskId, data: dagSnapshot(run.dag) });
+    term.taskOutro(run.status);
+    emitXcoderEvent({
+        type: "task:outro",
+        taskId: spec.taskId,
+        data: {
+            status: run.status,
+            finalDeliverable: run.finalDeliverable,
+            totalTokenUsage: run.totalTokenUsage,
+        },
+    });
+    return run;
+}

package/dist/sdlc-runtime/dag-utils.d.ts

@@ -0,0 +1,15 @@
+import type { SubtaskNode } from "../types.js";
+/** A UI-friendly projection of the DAG — just enough for a live status board, no full RAO trace duplicated here (that streams separately as agent:* events). */
+export declare function dagSnapshot(dag: SubtaskNode[]): {
+    id: string;
+    stage: string;
+    role: string;
+    status: string;
+    healingAttempts: number;
+    healingMax: number;
+    reasoningScore?: number;
+}[];
+/** Frontier computation: a node is `ready` once every dependency is `done`. */
+export declare function recomputeReady(dag: SubtaskNode[]): void;
+/** Inlines a finished node's deliverable into every direct dependent — by value, never a lookup id. */
+export declare function inlineIntoDependents(dag: SubtaskNode[], done: SubtaskNode): void;

package/dist/sdlc-runtime/dag-utils.js

@@ -0,0 +1,67 @@
+/** A UI-friendly projection of the DAG — just enough for a live status board, no full RAO trace duplicated here (that streams separately as agent:* events). */
+export function dagSnapshot(dag) {
+    return dag.map((n) => ({
+        id: n.id,
+        stage: n.stage,
+        role: n.role,
+        status: n.status,
+        healingAttempts: n.healing.attempts,
+        healingMax: n.healing.maxAttempts,
+        reasoningScore: n.reasoningScore?.score,
+    }));
+}
+/** Frontier computation: a node is `ready` once every dependency is `done`. */
+export function recomputeReady(dag) {
+    const byId = new Map(dag.map((n) => [n.id, n]));
+    for (const node of dag) {
+        if (node.status !== "pending")
+            continue;
+        const depsDone = node.dependsOn.every((d) => byId.get(d)?.status === "done");
+        if (depsDone)
+            node.status = "ready";
+    }
+}
+/** Inlines a finished node's deliverable into every direct dependent — by value, never a lookup id. */
+export function inlineIntoDependents(dag, done) {
+    const filesTouched = done.result?.filesTouched ?? [];
+    const topLevelFolders = deriveTopLevelFolders(filesTouched);
+    for (const node of dag) {
+        if (node.dependsOn.includes(done.id)) {
+            node.upstreamContext[done.id] = {
+                summary: done.result?.summary,
+                deliverable: done.result?.deliverable,
+                filesTouched,
+                topLevelFolders,
+            };
+            // If a test node depends on a code/refactor node, inject folder-scoped
+            // test instructions into the goal so the tester runs only affected folders.
+            if (node.stage === "test" && topLevelFolders.length > 0) {
+                const scopeLine = buildFolderScopeLine(topLevelFolders);
+                if (!node.goal.includes("FOLDER_SCOPE:")) {
+                    node.goal = `${scopeLine}\n\n${node.goal}`;
+                }
+            }
+        }
+    }
+}
+function deriveTopLevelFolders(paths) {
+    const folders = new Set();
+    for (const p of paths) {
+        // Normalize: strip leading ./ if present, then extract top-level folder under src/
+        let normalized = p.replace(/^\.\//, "");
+        const srcIdx = normalized.indexOf("src/");
+        if (srcIdx === 0 || (srcIdx > 0 && normalized[srcIdx - 1] === "/")) {
+            const afterSrc = normalized.slice(srcIdx + 4); // length of "src/"
+            const topFolder = afterSrc.split("/")[0];
+            if (topFolder)
+                folders.add(topFolder);
+        }
+    }
+    return [...folders].sort();
+}
+function buildFolderScopeLine(folders) {
+    const vitestArgs = folders
+        .map((f) => `"src/${f}/**/*.test.ts"`)
+        .join(" ");
+    return `FOLDER_SCOPE: Run tests only for these top-level src/ folders: ${folders.join(", ")}. Use npx vitest with per-folder file paths: npx vitest run --config vitest.config.ts ${vitestArgs}. Per-folder timeout 60s.`;
+}

package/dist/sdlc-runtime/defect-integration.d.ts

@@ -0,0 +1,7 @@
+import type { SubtaskNode, SubtaskResult, TaskRun } from "../types.js";
+/**
+ * Post-validation defect management:
+ * - After test/ui_api_test: scans for new defect RCA files, injects fix_defect nodes
+ * - After fix_defect: checks _defects.json status, resolves defect if passed
+ */
+export declare function integrateDefectManagement(dag: SubtaskNode[], run: TaskRun, node: SubtaskNode, result: SubtaskResult, workspaceRoot: string): Promise<void>;

package/dist/sdlc-runtime/defect-integration.js

@@ -0,0 +1,99 @@
+import { scanForDefects, classifyDefectRouting, buildFixDefectNode, resolveDefect, recordFixAttempt, } from "../orchestrator/defect-manager.js";
+import { loadDefectsIndex, upsertDefect } from "../orchestrator/defect-store.js";
+import { logDefectEvent } from "../orchestrator/defect-logger.js";
+import * as term from "../util/terminal.js";
+/**
+ * Post-validation defect management:
+ * - After test/ui_api_test: scans for new defect RCA files, injects fix_defect nodes
+ * - After fix_defect: checks _defects.json status, resolves defect if passed
+ */
+export async function integrateDefectManagement(dag, run, node, result, workspaceRoot) {
+    // ── fix_defect resolution check (status-driven) ────────────
+    if (node.stage === "fix_defect") {
+        const defectCtx = node.upstreamContext?.defect;
+        if (defectCtx?.defectId) {
+            const index = await loadDefectsIndex(workspaceRoot);
+            const record = index[defectCtx.defectId];
+            if (record && record.status === "in_progress") {
+                await resolveDefect(workspaceRoot, defectCtx.defectId, node.id);
+                run.orchestratorTrace.push({
+                    thought: `${node.id} resolved defect ${defectCtx.defectId}`,
+                    action: null,
+                    observation: "defect status updated to resolved — RCA archived",
+                });
+                term.orchestratorNote(`${node.id} resolved defect ${defectCtx.defectId}`);
+                return;
+            }
+            if (record && record.status !== "in_progress") {
+                run.orchestratorTrace.push({
+                    thought: `${node.id} fix_defect passed but defect ${defectCtx.defectId} is already ${record.status}`,
+                    action: null,
+                    observation: `defect status: ${record.status}`,
+                });
+                return;
+            }
+            // Defect not in index at all — treat as unresolved.
+            const unresolvedReason = `Defect ${defectCtx.defectId} not found in _defects.json after fix_defect — unable to verify resolution.`;
+            run.orchestratorTrace.push({
+                thought: `${node.id} marked done but defect ${defectCtx.defectId} missing from index — forcing healing`,
+                action: null,
+                observation: unresolvedReason,
+            });
+            term.orchestratorNote(`${node.id} defect missing from index, re-routing to healing`);
+            return; // caller handles the healer re-route
+        }
+        return;
+    }
+    // ── New defect discovery ────────────────────────────────────
+    if (node.stage === "test" || node.stage === "ui_api_test") {
+        const index = await loadDefectsIndex(workspaceRoot);
+        const newDefects = await scanForDefects(workspaceRoot, index);
+        if (newDefects.length === 0)
+            return;
+        const upstreamStages = new Set();
+        for (const depId of node.dependsOn) {
+            const dep = dag.find((n) => n.id === depId);
+            if (dep)
+                upstreamStages.add(dep.stage);
+        }
+        const primaryUpstreamStage = upstreamStages.has("code")
+            ? "code"
+            : upstreamStages.has("refactor")
+                ? "refactor"
+                : undefined;
+        const addNodes = [];
+        for (const defect of newDefects) {
+            const role = classifyDefectRouting(primaryUpstreamStage);
+            const fixNode = buildFixDefectNode(defect, role, run.spec, [node.id]);
+            addNodes.push(fixNode);
+            const now = new Date().toISOString();
+            await upsertDefect(workspaceRoot, {
+                id: defect.id,
+                path: defect.path,
+                status: "open",
+                discoveredAt: now,
+                lastUpdated: now,
+                severity: defect.severity,
+                fixAttempts: [],
+            });
+            await logDefectEvent(workspaceRoot, {
+                timestamp: now,
+                defectId: defect.id,
+                event: "discovered",
+                detail: `New defect discovered in ${defect.path}`,
+                metadata: { path: defect.path, severity: defect.severity },
+            });
+            await recordFixAttempt(workspaceRoot, defect.id, fixNode.id, 1);
+        }
+        dag.push(...addNodes);
+        run.orchestratorTrace.push({
+            thought: `injected ${addNodes.length} fix_defect node(s) for newly discovered defects`,
+            action: {
+                tool: "orchestrator_action",
+                input: { type: "replan", patch: { addNodes: addNodes.map((n) => n.id) } },
+            },
+            observation: `New defects: ${newDefects.map((d) => d.path).join(", ")}`,
+        });
+        term.orchestratorNote(`${addNodes.length} defect(s) discovered after ${node.id}, injecting fix_defect node(s): ${addNodes.map((n) => n.id).join(", ")}`);
+    }
+}

package/dist/sdlc-runtime/execution-loop.d.ts

@@ -0,0 +1,38 @@
+import type { SubtaskNode, SubtaskResult, TaskRun } from "../types.js";
+import type { WksProtocolMap } from "../protocol/wks-protocol-manager.js";
+import type { OrchestratorOptions } from "./sdlc-orchestrator.js";
+import { type ValidationOutcome } from "../orchestrator/validation-gate.js";
+import type { InteractiveSteeringManager } from "../orchestrator/interactive-steering.js";
+/**
+ * Shared context object passed through the loop to avoid parameter explosion.
+ * Callbacks replace methods that would have been on the orchestrator class.
+ */
+export interface OrchestrationContext {
+    opts: OrchestratorOptions;
+    protocolMap: WksProtocolMap;
+    masterProtocolSection: string | undefined;
+    lessonContext: string | undefined;
+    signal: AbortSignal;
+    steering: InteractiveSteeringManager;
+    quiet: boolean;
+    /** Called per round and per result to check for steering input — returns true if injection was applied. */
+    onSteeringInjection: (run: TaskRun) => Promise<boolean>;
+    /** Called after each round to persist progress. */
+    onSaveProgress: (run: TaskRun) => Promise<void>;
+}
+/**
+ * The main orchestration loop — rounds of dispatching, result collection,
+ * and processing until the DAG is complete, escalated, or halted.
+ * Includes the abort signal polling and steering check integration.
+ */
+export declare function executeLoop(run: TaskRun, ctx: OrchestrationContext): Promise<TaskRun>;
+/**
+ * Processes a single subtask result:
+ * - Logs the trace entry
+ * - Computes reasoning score
+ * - Handles crashes, iteration exhaustion, and validation routing
+ * - Dispatches success or failure routes
+ */
+export declare function handleResult(dag: SubtaskNode[], run: TaskRun, subtaskId: string, result: SubtaskResult, ctx: OrchestrationContext): Promise<void>;
+/** Shared by both a validation failure and a crash — same bounded healing pipeline either way. */
+export declare function routeFailure(dag: SubtaskNode[], run: TaskRun, node: SubtaskNode, result: SubtaskResult | null, outcome: ValidationOutcome, reason: string, ctx: OrchestrationContext): Promise<void>;

package/dist/sdlc-runtime/execution-loop.js

@@ -0,0 +1,274 @@
+import { validateSubtask } from "../orchestrator/validation-gate.js";
+import { decideHealing } from "../orchestrator/healing.js";
+import { dispatchSwarm } from "../orchestrator/swarm.js";
+import { getOrchestratorEngine } from "../engine/reasoning-engine.js";
+import { appendSys, appendScore } from "../util/logs.js";
+import { computeReasoningScore, efficiencyHint } from "../orchestrator/reasoning-score.js";
+import { emitXcoderEvent } from "../events/bus.js";
+import { loadDefectsIndex, upsertDefect } from "../orchestrator/defect-store.js";
+import { logDefectEvent } from "../orchestrator/defect-logger.js";
+import * as term from "../util/terminal.js";
+import { FooterManager } from "../util/footer-manager.js";
+import { recomputeReady, inlineIntoDependents } from "./dag-utils.js";
+import { summarize, buildExhaustionTrace } from "./reporting.js";
+import { recordTaskLesson } from "./lesson-recorder.js";
+import { integrateDefectManagement } from "./defect-integration.js";
+/**
+ * The main orchestration loop — rounds of dispatching, result collection,
+ * and processing until the DAG is complete, escalated, or halted.
+ * Includes the abort signal polling and steering check integration.
+ */
+export async function executeLoop(run, ctx) {
+    const dag = run.dag;
+    const taskId = run.spec.taskId;
+    const maxRounds = ctx.opts.maxRounds ?? 40;
+    let round = 0;
+    while (round++ < maxRounds) {
+        recomputeReady(dag);
+        const ready = dag.filter((n) => n.status === "ready");
+        if (ready.length === 0) {
+            const stillPending = dag.some((n) => n.status === "pending" || n.status === "healing");
+            if (!stillPending)
+                break;
+        }
+        const healingHints = {};
+        for (const n of dag) {
+            if (n.status === "ready" && n.healing.attempts > 0) {
+                healingHints[n.id] = n.healing.log.at(-1) ?? "";
+            }
+        }
+        try {
+            const swarmResults = await dispatchSwarm(ready, {
+                taskId,
+                workspaceRoot: ctx.opts.workspaceRoot,
+                llm: ctx.opts.llm,
+                subAgentLlm: ctx.opts.subAgentLlm ?? ctx.opts.roleLlm?.swarm_agent ?? ctx.opts.llm,
+                concurrency: ctx.opts.concurrency,
+                healingHints,
+                protocolOverrides: ctx.protocolMap,
+                lessonLearned: ctx.opts.lessonLearned,
+                lessonContext: ctx.lessonContext,
+                signal: ctx.signal,
+                quiet: ctx.quiet,
+            });
+            for (const { subtaskId, result } of swarmResults) {
+                run.totalTokenUsage.inputTokens += result.tokenUsage.inputTokens;
+                run.totalTokenUsage.outputTokens += result.tokenUsage.outputTokens;
+                await handleResult(dag, run, subtaskId, result, ctx);
+                // Derive current SDLC stage from DAG and update footer.
+                updateFooterStage(dag);
+            }
+        }
+        catch (e) {
+            const message = e.stack ?? String(e);
+            await appendSys(ctx.opts.workspaceRoot, taskId, `round ${round} failed: ${message}`);
+            run.orchestratorTrace.push({
+                thought: `round ${round} failed unexpectedly`,
+                action: null,
+                observation: e.message,
+            });
+            term.printCrash("orchestrator", `round ${round} failed, continuing: ${e.message}`);
+        }
+        await ctx.onSaveProgress(run);
+        // Check abort signal between rounds.
+        if (ctx.signal.aborted) {
+            run.status = "halted";
+            break;
+        }
+        // Interactive steering check.
+        const injected = await ctx.onSteeringInjection(run);
+        if (injected) {
+            await ctx.onSaveProgress(run);
+        }
+        if (run.status === "halted")
+            break;
+    }
+    const allDone = dag.every((n) => n.status === "done");
+    run.status = allDone ? "done" : run.escalations.length ? "escalated" : run.status;
+    run.finalDeliverable = summarize(dag, run, run.spec, ctx.opts.workspaceRoot);
+    await ctx.onSaveProgress(run);
+    FooterManager.instance()?.shutdown();
+    term.taskOutro(run.status);
+    emitXcoderEvent({
+        type: "task:outro",
+        taskId,
+        data: {
+            status: run.status,
+            finalDeliverable: run.finalDeliverable,
+            totalTokenUsage: run.totalTokenUsage,
+        },
+    });
+    return run;
+}
+/**
+ * Processes a single subtask result:
+ * - Logs the trace entry
+ * - Computes reasoning score
+ * - Handles crashes, iteration exhaustion, and validation routing
+ * - Dispatches success or failure routes
+ */
+export async function handleResult(dag, run, subtaskId, result, ctx) {
+    const node = dag.find((n) => n.id === subtaskId);
+    node.status = "validating";
+    node.result = result;
+    if (result.crashed) {
+        run.orchestratorTrace.push({
+            thought: `${node.id} crashed rather than producing a result`,
+            action: null,
+            observation: result.summary,
+        });
+        const syntheticOutcome = {
+            passed: false,
+            report: result.summary,
+            perCriterion: [],
+        };
+        await routeFailure(dag, run, node, result, syntheticOutcome, `crashed: ${result.summary}`, ctx);
+        return;
+    }
+    // ── Iteration exhaustion signal ─────────────────────────────
+    if (result.iterationsExhausted === true) {
+        const ex = buildExhaustionTrace(node.id, run.spec.taskId, result);
+        run.orchestratorTrace.push(ex.trace);
+        emitXcoderEvent(ex.event);
+        const index = await loadDefectsIndex(ctx.opts.workspaceRoot);
+        if (!(ex.defectId in index)) {
+            const now = new Date().toISOString();
+            await upsertDefect(ctx.opts.workspaceRoot, {
+                id: ex.defectId,
+                path: `.xcoder/exhaustion/${node.id}.md`,
+                status: "open",
+                severity: "high",
+                discoveredAt: now,
+                lastUpdated: now,
+                fixAttempts: [],
+            });
+            await logDefectEvent(ctx.opts.workspaceRoot, {
+                defectId: ex.defectId,
+                event: "discovered",
+                detail: "SubAgent exhausted iterations without final_answer",
+                timestamp: now,
+            });
+        }
+    }
+    const outcome = await validateSubtask(node, result, ctx.opts.workspaceRoot);
+    run.orchestratorTrace.push({
+        thought: `validating ${node.id} against its own acceptance criteria (not the overall task goal)`,
+        action: null,
+        observation: outcome.report,
+    });
+    if (outcome.passed) {
+        node.status = "done";
+        await recordScore(run, node, result, outcome, ctx.opts.workspaceRoot);
+        inlineIntoDependents(dag, node);
+        await integrateDefectManagement(dag, run, node, result, ctx.opts.workspaceRoot);
+        const engine = getOrchestratorEngine("react-v1");
+        const decision = await engine.decide({ dag, triggeringEvent: "subtask_done" });
+        run.orchestratorTrace.push({
+            thought: `${node.id} passed validation`,
+            action: { tool: "orchestrator_action", input: decision },
+            observation: "dispatch recomputed on next round",
+        });
+        term.orchestratorNote(`${node.id} done`);
+        // Record lesson if applicable.
+        try {
+            await recordTaskLesson(ctx.opts.workspaceRoot, result, run, node.id);
+        }
+        catch {
+            // lesson recording is best-effort
+        }
+        return;
+    }
+    await routeFailure(dag, run, node, result, outcome, outcome.report, ctx);
+}
+/** Computes, attaches, logs, and broadcasts the reasoning-effectiveness score. */
+async function recordScore(run, node, result, outcome, workspaceRoot) {
+    const reasoningScore = computeReasoningScore(node, result, outcome);
+    node.reasoningScore = reasoningScore;
+    await appendScore(workspaceRoot, run.spec.taskId, node.id, reasoningScore);
+    emitXcoderEvent({
+        type: "agent:score",
+        taskId: run.spec.taskId,
+        subtaskId: node.id,
+        data: reasoningScore,
+    });
+}
+/** Shared by both a validation failure and a crash — same bounded healing pipeline either way. */
+export async function routeFailure(dag, run, node, result, outcome, reason, ctx) {
+    if (result) {
+        await recordScore(run, node, result, outcome, ctx.opts.workspaceRoot);
+    }
+    const efficiency = result ? efficiencyHint(result) : undefined;
+    const filesNote = result && result.filesTouched.length > 0
+        ? `IMPORTANT: the previous attempt already created ${result.filesTouched.length} file(s) before failing: ` +
+            `${result.filesTouched.slice(0, 25).join(", ")}${result.filesTouched.length > 25 ? ", ..." : ""}. ` +
+            `Check what already exists (search_workspace/glob/read_file) before writing — extend or fix it, don't recreate it from scratch.`
+        : null;
+    const reasonWithEfficiency = [reason, efficiency, filesNote]
+        .filter(Boolean)
+        .join(" Also: ");
+    node.status = "healing";
+    const healing = decideHealing(node, reasonWithEfficiency);
+    if (healing.action === "escalate") {
+        node.status = "escalated";
+        run.escalations.push({ subtaskId: node.id, reason });
+        run.orchestratorTrace.push({
+            thought: `${node.id} exhausted healing attempts`,
+            action: { tool: "orchestrator_action", input: { type: "escalate" } },
+            observation: reason,
+        });
+        term.printCrash(node.id, `escalated: ${reason}`);
+        if (node.upstreamContext?.defect != null) {
+            run.status = "halted";
+            run.orchestratorTrace.push({
+                thought: `unresolved defect escalation halted the task run (${node.id})`,
+                action: null,
+                observation: `Defect: ${JSON.stringify(node.upstreamContext.defect)}`,
+            });
+            term.orchestratorNote(`${node.id} defect escalation halted the run: ${reason}`);
+        }
+        return;
+    }
+    node.status = "ready";
+    run.orchestratorTrace.push({
+        thought: `retrying ${node.id}, forcing react-v1 healing per design (a specific deviation is an observe→act→observe problem)`,
+        action: { tool: "orchestrator_action", input: { type: "retry", hint: healing.hint } },
+        observation: `attempt ${node.healing.attempts}/${node.healing.maxAttempts}`,
+    });
+    term.orchestratorNote(`${node.id} healing (attempt ${node.healing.attempts}/${node.healing.maxAttempts})`);
+}
+/**
+ * Derive the current SDLC stage from the DAG by finding the most common
+ * stage among in-progress/validating/ready nodes, falling back to the
+ * stage of the last done node, then falling back to null.
+ */
+function updateFooterStage(dag) {
+    const active = dag.filter((n) => n.status === "in_progress" || n.status === "validating" || n.status === "ready");
+    if (active.length > 0) {
+        // Pick the most common stage among active nodes.
+        const counts = new Map();
+        for (const n of active) {
+            counts.set(n.stage, (counts.get(n.stage) ?? 0) + 1);
+        }
+        let bestStage = null;
+        let bestCount = 0;
+        for (const [stage, count] of counts) {
+            if (count > bestCount) {
+                bestCount = count;
+                bestStage = stage;
+            }
+        }
+        if (bestStage) {
+            FooterManager.instance()?.updateStage(bestStage);
+            return;
+        }
+    }
+    // Fallback: last done node's stage.
+    const doneNodes = dag.filter((n) => n.status === "done");
+    if (doneNodes.length > 0) {
+        const lastDone = doneNodes[doneNodes.length - 1];
+        FooterManager.instance()?.updateStage(lastDone.stage);
+        return;
+    }
+    // No activity yet — clear stage.
+    FooterManager.instance()?.updateStage(dag[0]?.stage ?? "requirements");
+}