xcoder-dna 0.0.0-stage → 1.3.0

package/dist/orchestrator/lesson-manager.js

@@ -0,0 +1,122 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+/**
+ * Resolve whether lesson-learned is enabled from CLI option + env var.
+ * CLI flag "--lesson-learned" → true; "--no-lesson-learned" → false.
+ * If neither is passed, check XCODER_LESSON_LEARNED ("true" → true).
+ * Default: false.
+ */
+export function resolveLessonFlag(cliFlag, env) {
+    if (cliFlag === true)
+        return true;
+    if (cliFlag === false)
+        return false;
+    const envVal = env.XCODER_LESSON_LEARNED;
+    if (envVal !== undefined)
+        return envVal.toLowerCase() === "true";
+    return false;
+}
+const LESSON_FILE = ".xcoder/lesson.md";
+const MAX_FILE_SIZE = 64 * 1024; // 64 KB
+/**
+ * Read the full contents of .xcoder/lesson.md.
+ * Returns the raw Markdown string (empty string if the file doesn't exist).
+ */
+export async function loadLessons(workspaceRoot) {
+    const filePath = path.join(workspaceRoot, LESSON_FILE);
+    try {
+        return await fs.readFile(filePath, "utf8");
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === "ENOENT")
+            return "";
+        throw e;
+    }
+}
+/**
+ * Check if the lessons file exceeds 64 KB.
+ * Returns a warning string if it does, or null if it's within bounds.
+ */
+export async function checkLessonFileSize(workspaceRoot) {
+    const filePath = path.join(workspaceRoot, LESSON_FILE);
+    try {
+        const stat = await fs.stat(filePath);
+        if (stat.size > MAX_FILE_SIZE) {
+            const kb = Math.round(stat.size / 1024);
+            return (`.xcoder/lesson.md is ${kb} KB (limit: 64 KB). ` +
+                `Lessons beyond 64 KB are NOT injected into Sub Agent prompts. ` +
+                `Consider pruning older entries manually.`);
+        }
+    }
+    catch {
+        // File doesn't exist — nothing to warn about.
+    }
+    return null;
+}
+/**
+ * Record a lesson into .xcoder/lesson.md with an atomic write.
+ * Uses temp-file + rename for concurrency safety.
+ * Creates .xcoder/ dir and lesson.md on first write.
+ * Non-fatal: if the write fails, the caller logs a warning and continues.
+ */
+export async function recordLesson(workspaceRoot, entry) {
+    const dir = path.join(workspaceRoot, ".xcoder");
+    await fs.mkdir(dir, { recursive: true });
+    const filePath = path.join(workspaceRoot, LESSON_FILE);
+    const ts = new Date().toISOString();
+    const tagsFormatted = `[${entry.tags.join(", ")}]`;
+    const block = [
+        `## Lesson — ${ts}`,
+        `- **source:** \`${entry.source}\``,
+        `- **taskId:** \`${entry.taskId}\``,
+        `- **tags:** \`${tagsFormatted}\``,
+        `- **context:** ${entry.context}`,
+        `- **lesson:** ${entry.lesson}`,
+        "",
+    ].join("\n");
+    let oldContent = "";
+    try {
+        oldContent = await fs.readFile(filePath, "utf8");
+    }
+    catch (e) {
+        const code = e.code;
+        if (code !== "ENOENT")
+            throw e;
+    }
+    const newContent = oldContent ? `${oldContent}${block}` : block;
+    const tmpPath = `${filePath}.tmp-${randomUUID()}`;
+    try {
+        await fs.writeFile(tmpPath, newContent, "utf8");
+        await fs.rename(tmpPath, filePath);
+    }
+    catch (e) {
+        // If rename fails (e.g. another process wrote concurrently),
+        // retry once: re-read current content and try again.
+        try {
+            let currentContent = "";
+            try {
+                currentContent = await fs.readFile(filePath, "utf8");
+            }
+            catch {
+                // file might have been deleted — that's fine
+            }
+            const retryContent = currentContent ? `${currentContent}${block}` : block;
+            const retryTmp = `${filePath}.tmp-${randomUUID()}`;
+            await fs.writeFile(retryTmp, retryContent, "utf8");
+            await fs.rename(retryTmp, filePath);
+        }
+        catch {
+            // Swallow — never crash the orchestrator on a lesson write failure.
+            // The lesson is lost, but the run continues.
+        }
+        // Clean up the original temp file if it still exists.
+        try {
+            await fs.unlink(tmpPath);
+        }
+        catch {
+            // Best effort.
+        }
+    }
+}

package/dist/orchestrator/progress-summary.d.ts

@@ -0,0 +1,15 @@
+import type { TaskRun } from "../types.js";
+/**
+ * Written to `.xcoder/tasks/<taskId>.md` at every terminal state (done,
+ * escalated, or halted) and refreshed again after a resume. Two audiences:
+ *
+ * 1. A human re-opening this task later — a readable "what happened"
+ *    without digging through think.log/sys.log/score.log by hand.
+ * 2. A resumed Sub Agent — its `healing.log` (persisted per-node) already
+ *    carries what it needs to continue without re-discovery, but this
+ *    file is what `--resume` points a human at, and its file-list section
+ *    is exactly the "don't re-query every file to understand everything"
+ *    ask: a resumed subtask's healing hint references it directly rather
+ *      than making the model glob the whole workspace again.
+ */
+export declare function buildProgressSummaryMarkdown(run: TaskRun): string;

package/dist/orchestrator/progress-summary.js

@@ -0,0 +1,106 @@
+/**
+ * Written to `.xcoder/tasks/<taskId>.md` at every terminal state (done,
+ * escalated, or halted) and refreshed again after a resume. Two audiences:
+ *
+ * 1. A human re-opening this task later — a readable "what happened"
+ *    without digging through think.log/sys.log/score.log by hand.
+ * 2. A resumed Sub Agent — its `healing.log` (persisted per-node) already
+ *    carries what it needs to continue without re-discovery, but this
+ *    file is what `--resume` points a human at, and its file-list section
+ *    is exactly the "don't re-query every file to understand everything"
+ *    ask: a resumed subtask's healing hint references it directly rather
+ *      than making the model glob the whole workspace again.
+ */
+export function buildProgressSummaryMarkdown(run) {
+    const { spec, dag, status, escalations, totalTokenUsage } = run;
+    const lines = [];
+    lines.push(`# Progress Summary — ${spec.taskId}`);
+    lines.push("");
+    lines.push(`**Goal:** ${spec.goal}`);
+    lines.push(`**Status:** ${status}`);
+    lines.push(`**Last updated:** ${new Date().toISOString()}`);
+    lines.push(`**Tokens spent so far:** ${totalTokenUsage.inputTokens} in / ${totalTokenUsage.outputTokens} out`);
+    lines.push("");
+    lines.push("## Plan");
+    for (const n of dag) {
+        const box = n.status === "done" ? "[x]" : "[ ]";
+        const healingNote = n.healing.attempts > 0 ? ` (healing ${n.healing.attempts}/${n.healing.maxAttempts})` : "";
+        lines.push(`- ${box} \`${n.id}\` (${n.role}) — ${n.status}${healingNote}`);
+    }
+    lines.push("");
+    const done = dag.filter((n) => n.status === "done");
+    if (done.length) {
+        lines.push("## What's already done");
+        for (const n of done) {
+            lines.push(`### \`${n.id}\` (${n.role}) — done`);
+            lines.push(n.result?.summary ?? "(no summary recorded)");
+            lines.push("");
+        }
+    }
+    const allFiles = new Set();
+    for (const n of dag) {
+        for (const f of n.result?.filesTouched ?? [])
+            allFiles.add(f);
+    }
+    if (allFiles.size) {
+        lines.push("## Files created or modified (by subtask)");
+        lines.push("A resumed subtask should check these with `read_file`/`glob` before writing anything new — " +
+            "most of what's needed to continue is already in this list, not in the original design doc.");
+        for (const n of dag) {
+            const meta = n.result?._filesTouchedMeta;
+            const files = n.result?.filesTouched;
+            if ((!meta || meta.length === 0) && (!files || files.length === 0))
+                continue;
+            lines.push(`### \`${n.id}\` (${n.role})`);
+            if (meta && meta.length > 0) {
+                for (const entry of meta) {
+                    const label = entry.operation === "created" ? "[created]" : entry.operation === "modified" ? "[modified]" : "[touched]";
+                    lines.push(`- \`${entry.path}\` ${label}`);
+                }
+            }
+            else if (files) {
+                for (const f of [...files].sort()) {
+                    lines.push(`- \`${f}\` [touched]`);
+                }
+            }
+            lines.push("");
+        }
+        lines.push("");
+    }
+    const blocked = dag.filter((n) => n.status === "escalated" || n.status === "failed");
+    if (blocked.length) {
+        lines.push("## What's blocking");
+        for (const n of blocked) {
+            const esc = escalations.find((e) => e.subtaskId === n.id);
+            lines.push(`### \`${n.id}\` (${n.role}) — ${n.status}`);
+            lines.push(`Reason: ${esc?.reason ?? n.healing.log.at(-1) ?? "(no reason recorded)"}`);
+            lines.push(`Healing attempts used: ${n.healing.attempts}/${n.healing.maxAttempts}`);
+            lines.push("");
+        }
+    }
+    const remaining = dag.filter((n) => n.status !== "done");
+    if (remaining.length && status !== "done") {
+        lines.push("## Next steps when resumed");
+        for (const n of remaining) {
+            lines.push(`- \`${n.id}\` (${n.role}, ${n.status}) — ${nextStepNote(n)}`);
+        }
+        lines.push("");
+    }
+    if (status === "done") {
+        lines.push("## Result");
+        lines.push("This task completed successfully — nothing left to resume.");
+    }
+    return lines.join("\n");
+}
+function nextStepNote(n) {
+    if (n.status === "escalated") {
+        return "will be retried with a fresh healing budget on resume; its healing log (what was already tried) carries forward.";
+    }
+    if (n.status === "pending") {
+        return "blocked on an upstream dependency finishing first.";
+    }
+    if (n.status === "ready" || n.status === "healing") {
+        return "will be (re-)dispatched on resume.";
+    }
+    return "no action needed.";
+}

package/dist/orchestrator/reasoning-score.d.ts

@@ -0,0 +1,49 @@
+import type { SubtaskNode, SubtaskResult } from "../types.js";
+import type { ValidationOutcome } from "./validation-gate.js";
+export interface ReasoningScore {
+    score: number;
+    breakdown: string[];
+}
+/**
+ * WHAT THIS IS: a transparent, additive rubric over one subtask attempt —
+ * acceptance-criteria pass rate, iteration efficiency, error rate, and
+ * self-check discipline. Every point gained or lost has a one-line reason
+ * in `breakdown`, on purpose: a score nobody can audit is a score nobody
+ * should trust enough to act on.
+ *
+ * WHAT THIS IS NOT: a gate. Validation Gate (`validation-gate.ts`) already
+ * decides pass/fail from acceptance criteria alone — that decision is
+ * final and this score never overrides it. This is a SEPARATE signal for
+ * two specific, bounded uses:
+ *
+ *   1. Within a single task run: a low-efficiency score on a failed
+ *      attempt (many iterations, repeated errors) gets folded into the
+ *      next healing retry's hint — see `sdlc-orchestrator.ts`'s
+ *      `routeFailure` — so the retry gets a concrete nudge ("you spent 18
+ *      iterations and repeated the same failed edit_file call 4 times")
+ *      instead of just "try again." That's a real, bounded improvement
+ *      inside one run's healing loop.
+ *
+ *   2. Across benchmark runs over time: `bench/run.ts` reports the average
+ *      score per fixture per run. A maintainer comparing this week's
+ *      average against last week's is the actual feedback loop for "does
+ *      this directive/skill/prompt change help" — a human decision
+ *      informed by a trend, not an automatic one.
+ *
+ * What this deliberately does NOT claim to do: make the model itself
+ * smarter mid-conversation. Claude isn't fine-tuned by this score, and
+ * feeding a bare number back into the model's own context is a Goodhart's-
+ * law risk (a model that can see its score can learn to game the score's
+ * proxies — fewer tool calls, a confident-sounding self_check — rather
+ * than the actual acceptance criteria). That's why the score itself is
+ * never shown to the Sub Agent; only the specific, concrete FAILURE REASON
+ * (already the existing healing-hint mechanism) is.
+ */
+export declare function computeReasoningScore(node: SubtaskNode, result: SubtaskResult, validation: ValidationOutcome): ReasoningScore;
+/**
+ * The one place a score's breakdown is allowed to influence the model: a
+ * short, concrete efficiency note appended to the NEXT healing attempt's
+ * hint — never the raw number, never phrased as "your score was X."
+ * Silent no-op if the attempt wasn't actually inefficient.
+ */
+export declare function efficiencyHint(result: SubtaskResult): string | null;

package/dist/orchestrator/reasoning-score.js

@@ -0,0 +1,117 @@
+const SELF_CHECK_EXPECTED_ROLES = new Set(["programmer", "refactorer", "tester", "devops", "ui-api-tester"]);
+/**
+ * WHAT THIS IS: a transparent, additive rubric over one subtask attempt —
+ * acceptance-criteria pass rate, iteration efficiency, error rate, and
+ * self-check discipline. Every point gained or lost has a one-line reason
+ * in `breakdown`, on purpose: a score nobody can audit is a score nobody
+ * should trust enough to act on.
+ *
+ * WHAT THIS IS NOT: a gate. Validation Gate (`validation-gate.ts`) already
+ * decides pass/fail from acceptance criteria alone — that decision is
+ * final and this score never overrides it. This is a SEPARATE signal for
+ * two specific, bounded uses:
+ *
+ *   1. Within a single task run: a low-efficiency score on a failed
+ *      attempt (many iterations, repeated errors) gets folded into the
+ *      next healing retry's hint — see `sdlc-orchestrator.ts`'s
+ *      `routeFailure` — so the retry gets a concrete nudge ("you spent 18
+ *      iterations and repeated the same failed edit_file call 4 times")
+ *      instead of just "try again." That's a real, bounded improvement
+ *      inside one run's healing loop.
+ *
+ *   2. Across benchmark runs over time: `bench/run.ts` reports the average
+ *      score per fixture per run. A maintainer comparing this week's
+ *      average against last week's is the actual feedback loop for "does
+ *      this directive/skill/prompt change help" — a human decision
+ *      informed by a trend, not an automatic one.
+ *
+ * What this deliberately does NOT claim to do: make the model itself
+ * smarter mid-conversation. Claude isn't fine-tuned by this score, and
+ * feeding a bare number back into the model's own context is a Goodhart's-
+ * law risk (a model that can see its score can learn to game the score's
+ * proxies — fewer tool calls, a confident-sounding self_check — rather
+ * than the actual acceptance criteria). That's why the score itself is
+ * never shown to the Sub Agent; only the specific, concrete FAILURE REASON
+ * (already the existing healing-hint mechanism) is.
+ */
+export function computeReasoningScore(node, result, validation) {
+    const breakdown = [];
+    let score = 0;
+    // --- Acceptance criteria: up to 60 points -------------------------------
+    const totalAC = node.acceptanceCriteria.length;
+    if (totalAC === 0) {
+        score += 60;
+        breakdown.push("+60 no acceptance criteria defined for this stage (e.g. conversation) — full credit");
+    }
+    else {
+        const passedAC = validation.perCriterion.filter((c) => c.passed).length;
+        const points = Math.round((60 * passedAC) / totalAC);
+        score += points;
+        breakdown.push(`+${points} acceptance criteria: ${passedAC}/${totalAC} passed`);
+    }
+    // --- Iteration efficiency: up to 25 points ------------------------------
+    const iterations = result.iterations;
+    if (iterations <= 8) {
+        score += 25;
+        breakdown.push(`+25 efficient: reached a result in ${iterations} iteration(s) (≤8 baseline)`);
+    }
+    else {
+        const penalty = Math.min(25, (iterations - 8) * 2);
+        const points = 25 - penalty;
+        score += points;
+        breakdown.push(`+${points} took ${iterations} iterations, ${penalty} points off for exceeding the 8-iteration baseline`);
+    }
+    // --- Error rate: down to -20 points -------------------------------------
+    const errorCount = result.raoTrace.filter((s) => s.observation.startsWith("protocol_error") || s.observation.startsWith("llm_error")).length;
+    if (errorCount > 0) {
+        const penalty = Math.min(20, errorCount * 4);
+        score -= penalty;
+        breakdown.push(`-${penalty} ${errorCount} protocol/LLM error(s) during the attempt`);
+    }
+    else {
+        breakdown.push("+0 no protocol/LLM errors");
+    }
+    // --- Self-check discipline: ±15 points -----------------------------------
+    const expectsSelfCheck = SELF_CHECK_EXPECTED_ROLES.has(node.role);
+    if (result.selfCheck?.ran && result.selfCheck.passed) {
+        score += 15;
+        breakdown.push("+15 self_check ran and passed");
+    }
+    else if (result.selfCheck?.ran && !result.selfCheck.passed) {
+        breakdown.push("+0 self_check ran but did not pass (consistent with a failed validation, not double-penalized)");
+    }
+    else if (expectsSelfCheck) {
+        score -= 5;
+        breakdown.push(`-5 role "${node.role}" is expected to self-check mechanically-verifiable work, but self_check was never reported`);
+    }
+    else {
+        breakdown.push("+0 self_check not expected for this role");
+    }
+    // --- Healing cost: -5 per attempt already spent getting here -----------
+    if (node.healing.attempts > 0) {
+        const penalty = node.healing.attempts * 5;
+        score -= penalty;
+        breakdown.push(`-${penalty} this is healing attempt ${node.healing.attempts}/${node.healing.maxAttempts} — it took retries to get here`);
+    }
+    const clamped = Math.max(0, Math.min(100, score));
+    if (clamped !== score)
+        breakdown.push(`(raw ${score}, clamped to ${clamped})`);
+    return { score: clamped, breakdown };
+}
+/**
+ * The one place a score's breakdown is allowed to influence the model: a
+ * short, concrete efficiency note appended to the NEXT healing attempt's
+ * hint — never the raw number, never phrased as "your score was X."
+ * Silent no-op if the attempt wasn't actually inefficient.
+ */
+export function efficiencyHint(result) {
+    const notes = [];
+    if (result.iterations > 12) {
+        notes.push(`the previous attempt took ${result.iterations} iterations — read each observation fully before deciding the next action, rather than re-checking the same thing repeatedly`);
+    }
+    const errorCount = result.raoTrace.filter((s) => s.observation.startsWith("protocol_error") || s.observation.startsWith("llm_error")).length;
+    if (errorCount >= 2) {
+        notes.push(`the previous attempt hit ${errorCount} protocol/tool errors — re-read the response contract and each tool's input shape carefully before calling it again`);
+    }
+    return notes.length ? notes.join("; ") : null;
+}

package/dist/orchestrator/swarm.d.ts

@@ -0,0 +1,36 @@
+import type { SubtaskNode, SubtaskResult } from "../types.js";
+import type { WksProtocolMap } from "../protocol/wks-protocol-manager.js";
+import { LlmClient } from "../llm/client.js";
+export interface SwarmDispatchResult {
+    subtaskId: string;
+    result: SubtaskResult;
+}
+/**
+ * The "swarm" the brief asked for: when more than one subtask is `ready`
+ * at once, Xcoder SDLC runs a Sub Agent for each concurrently rather than one at
+ * a time, bounded by `concurrency`.
+ *
+ * ISOLATION CONTRACT: this function itself never throws because of
+ * anything a single Sub Agent does. `SubAgent.run()` is already designed
+ * not to throw (see `agents/sub-agent.ts`), but the `try/catch` below is a
+ * deliberate second layer — if a future change to `SubAgent` or a Node-
+ * level failure (e.g. an out-of-memory kill translated into a rejected
+ * promise) ever does throw, this is where it's caught, logged, and turned
+ * into a `crashed: true` result that flows through the SAME validate →
+ * heal → escalate pipeline as any other failed subtask, rather than
+ * aborting the whole `Promise.all` and taking every other in-flight Sub
+ * Agent — and the Master Orchestrator itself — down with it.
+ */
+export declare function dispatchSwarm(ready: SubtaskNode[], opts: {
+    taskId: string;
+    workspaceRoot: string;
+    llm: LlmClient;
+    subAgentLlm?: LlmClient;
+    concurrency: number;
+    healingHints?: Record<string, string>;
+    protocolOverrides?: WksProtocolMap;
+    lessonLearned?: boolean;
+    lessonContext?: string;
+    signal?: AbortSignal;
+    quiet?: boolean;
+}): Promise<SwarmDispatchResult[]>;

package/dist/orchestrator/swarm.js

@@ -0,0 +1,77 @@
+import { SubAgent } from "../agents/sub-agent.js";
+import { appendSys } from "../util/logs.js";
+import { emitXcoderEvent } from "../events/bus.js";
+import * as term from "../util/terminal.js";
+import { silentTerminal } from "../util/terminal-silent.js";
+/**
+ * The "swarm" the brief asked for: when more than one subtask is `ready`
+ * at once, Xcoder SDLC runs a Sub Agent for each concurrently rather than one at
+ * a time, bounded by `concurrency`.
+ *
+ * ISOLATION CONTRACT: this function itself never throws because of
+ * anything a single Sub Agent does. `SubAgent.run()` is already designed
+ * not to throw (see `agents/sub-agent.ts`), but the `try/catch` below is a
+ * deliberate second layer — if a future change to `SubAgent` or a Node-
+ * level failure (e.g. an out-of-memory kill translated into a rejected
+ * promise) ever does throw, this is where it's caught, logged, and turned
+ * into a `crashed: true` result that flows through the SAME validate →
+ * heal → escalate pipeline as any other failed subtask, rather than
+ * aborting the whole `Promise.all` and taking every other in-flight Sub
+ * Agent — and the Master Orchestrator itself — down with it.
+ */
+export async function dispatchSwarm(ready, opts) {
+    const results = [];
+    const queue = [...ready];
+    const concurrency = Math.max(1, opts.concurrency);
+    const resolvedTerm = opts.quiet ? silentTerminal : term;
+    async function worker() {
+        while (queue.length) {
+            // Stop pulling new nodes from the queue when the abort signal fires.
+            // In-flight agents complete naturally — no real-time cancellation of
+            // in-progress LLM calls (explicit non-goal).
+            if (opts.signal?.aborted)
+                return;
+            const node = queue.shift();
+            if (!node)
+                return;
+            resolvedTerm.orchestratorNote(`dispatching ${node.id} (${node.role} / ${node.engine})`);
+            emitXcoderEvent({ type: "orchestrator:note", taskId: opts.taskId, subtaskId: node.id, data: { message: `dispatching ${node.id} (${node.role} / ${node.engine})` } });
+            const agent = new SubAgent({
+                taskId: opts.taskId,
+                workspaceRoot: opts.workspaceRoot,
+                llm: opts.subAgentLlm ?? opts.llm,
+                healingHint: opts.healingHints?.[node.id],
+                protocolOverrides: opts.protocolOverrides,
+                lessonLearned: opts.lessonLearned,
+                lessonContext: opts.lessonContext,
+                quiet: opts.quiet,
+            });
+            let result;
+            try {
+                result = await agent.run(node);
+            }
+            catch (e) {
+                // The safety net described above. This branch existing at all means
+                // a bug somewhere else — it should never fire in practice — but if
+                // it does, the orchestrator keeps running instead of the whole CLI
+                // process dying with no report.
+                const message = e.stack ?? String(e);
+                await appendSys(opts.workspaceRoot, opts.taskId, `[${node.id}] UNCAUGHT crash in swarm worker: ${message}`);
+                resolvedTerm.printCrash(node.id, `uncaught exception, isolated at the swarm boundary: ${e.message}`);
+                emitXcoderEvent({ type: "agent:crash", taskId: opts.taskId, subtaskId: node.id, data: { message: e.message, recoverable: false } });
+                result = {
+                    summary: `Sub Agent crashed unexpectedly: ${e.message}`,
+                    deliverable: null,
+                    filesTouched: [],
+                    raoTrace: [],
+                    tokenUsage: { inputTokens: 0, outputTokens: 0 },
+                    iterations: 0,
+                    crashed: true,
+                };
+            }
+            results.push({ subtaskId: node.id, result });
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(concurrency, queue.length) }, () => worker()));
+    return results;
+}

package/dist/orchestrator/task-factory.d.ts

@@ -0,0 +1,15 @@
+import type { AcceptanceCriterion, SdlcStage, SubtaskNode, TaskInputs, TaskSpec } from "../types.js";
+export declare function deliverableFor(stage: SdlcStage): string;
+export declare function acceptanceCriteriaFor(stage: SdlcStage): AcceptanceCriterion[];
+/**
+ * Builds the initial DAG for a non-conversation task. Deliberately linear
+ * for v1 (matching the brief's stage sequences) rather than inventing
+ * parallel branches Xcoder SDLC has no evidence justify — the swarm dispatcher
+ * (see `orchestrator/swarm.ts`) is what actually gives you fan-out, once a
+ * `replan` action splits a stage into independent nodes (e.g. multiple
+ * files to implement in parallel). Nodes are fully self-contained: a Sub
+ * Agent needs nothing beyond the node it's handed.
+ */
+export declare function buildInitialPlan(spec: TaskSpec): SubtaskNode[];
+export declare function isConversation(spec: TaskSpec): boolean;
+export declare function buildTaskSpec(rawTask: string, cliInputs: Partial<TaskInputs>, constraints: TaskSpec["constraints"]): TaskSpec;