xcoder-dna 0.0.0-stage → 1.3.0

package/dist/sdlc-runtime/lesson-recorder.d.ts

@@ -0,0 +1,9 @@
+import type { SubtaskResult, TaskRun } from "../types.js";
+/**
+ * Records a lesson learned from a subtask result into .xcoder/lesson.md
+ * if the result passed validation and subtask.role is not "conversation".
+ * Checks file size before appending to prevent unbounded growth.
+ */
+export declare function recordTaskLesson(workspaceRoot: string, result: SubtaskResult, run: TaskRun, nodeId: string): Promise<void>;
+/** Re-export for convenience */
+export { checkLessonFileSize } from "../orchestrator/lesson-manager.js";

package/dist/sdlc-runtime/lesson-recorder.js

@@ -0,0 +1,27 @@
+import { checkLessonFileSize, recordLesson } from "../orchestrator/lesson-manager.js";
+/**
+ * Records a lesson learned from a subtask result into .xcoder/lesson.md
+ * if the result passed validation and subtask.role is not "conversation".
+ * Checks file size before appending to prevent unbounded growth.
+ */
+export async function recordTaskLesson(workspaceRoot, result, run, nodeId) {
+    if (result.crashed)
+        return;
+    // Only record for non-conversation roles with a valid self-check.
+    if (!result.selfCheck?.passed)
+        return;
+    // Check file size before recording.
+    const ok = await checkLessonFileSize(workspaceRoot);
+    if (typeof ok === "string")
+        return; // warning string returned, skip
+    const entry = {
+        source: `sub-agent:${nodeId}`,
+        taskId: run.spec.taskId,
+        tags: ["lesson"],
+        context: result.summary.slice(0, 200),
+        lesson: result.summary,
+    };
+    await recordLesson(workspaceRoot, entry);
+}
+/** Re-export for convenience */
+export { checkLessonFileSize } from "../orchestrator/lesson-manager.js";

package/dist/sdlc-runtime/plan-initializer.d.ts

@@ -0,0 +1,47 @@
+import type { SubtaskNode, SubtaskStatus, TaskRun, TaskSpec } from "../types.js";
+import type { WksProtocolMap } from "../protocol/wks-protocol-manager.js";
+import type { OrchestratorOptions } from "./sdlc-orchestrator.js";
+/** Shared result from initialization. */
+export interface InitializationResult {
+    run: TaskRun;
+    isConversation: boolean;
+    lessonContext: string | undefined;
+}
+/**
+ * Builds or loads the initial DAG for a task run.
+ * - For new tasks: builds the initial plan via task-factory
+ * - For resume tasks: loads the existing TaskRun from disk
+ * - Migrates legacy defects
+ * - Reconciles orphaned tasks
+ * - Runs initial lesson loading if lessonLearned
+ */
+export declare function initializeRun(spec: TaskSpec, opts: OrchestratorOptions, protocolMap: WksProtocolMap, masterProtocolSection: string | undefined, customDag?: SubtaskNode[]): Promise<InitializationResult>;
+/**
+ * Resumes an existing TaskRun from disk, resetting healing budgets
+ * on escalated/healing nodes while preserving healing.log.
+ */
+export declare function resumeRun(taskId: string, opts: OrchestratorOptions, protocolMap: WksProtocolMap, masterProtocolSection: string | undefined): Promise<InitializationResult>;
+/**
+ * Node statuses that must be returned to an executable state before a resumed
+ * run can pick them up. A process that died mid-flight leaves nodes at
+ * `in_progress`/`validating`; a blocked dependency leaves `blocked`/`failed`.
+ * `recomputeReady()` only ever promotes `pending`, so nothing re-arms these by
+ * itself — the execution loop would find zero ready nodes and exit silently.
+ */
+export declare const REARM_ON_RESUME: readonly SubtaskStatus[];
+/**
+ * Returns nodes to an executable state for a resumed run. Mutates in place.
+ *
+ * Rules (by precedence):
+ *   1. "done"                 → untouched. Never re-executed, results kept.
+ *   2. "pending"/"ready"     → untouched; recomputeReady() promotes pending
+ *                              once its dependencies land.
+ *   3. escalated/healing/failed/blocked
+ *   4. in_progress/validating (crash-orphaned)
+ *                             → status="ready", healing.attempts=0, healing.log
+ *                               kept so the failure history is not lost.
+ *   5. unknown status         → left alone (fail-safe; never guessed into ready).
+ *
+ * @returns number of nodes re-armed.
+ */
+export declare function rearmForResume(dag: SubtaskNode[]): number;

package/dist/sdlc-runtime/plan-initializer.js

@@ -0,0 +1,135 @@
+import { buildInitialPlan, isConversation } from "../orchestrator/task-factory.js";
+import { loadTaskRun, reconcileOrphanedTasks } from "../store/task-store.js";
+import { getOrBuildIndex } from "../tools/workspace-index.js";
+import { migrateLegacyDefects } from "../orchestrator/defect-migration.js";
+import { loadLessons, checkLessonFileSize } from "../orchestrator/lesson-manager.js";
+import * as term from "../util/terminal.js";
+import { emitXcoderEvent } from "../events/bus.js";
+import { dagSnapshot } from "./dag-utils.js";
+/**
+ * Builds or loads the initial DAG for a task run.
+ * - For new tasks: builds the initial plan via task-factory
+ * - For resume tasks: loads the existing TaskRun from disk
+ * - Migrates legacy defects
+ * - Reconciles orphaned tasks
+ * - Runs initial lesson loading if lessonLearned
+ */
+export async function initializeRun(spec, opts, protocolMap, masterProtocolSection, customDag) {
+    await getOrBuildIndex(opts.workspaceRoot);
+    // One-time migration of legacy defects/ -> .xcoder/defects/
+    try {
+        await migrateLegacyDefects(opts.workspaceRoot);
+    }
+    catch (e) {
+        term.orchestratorNote(`defect migration warning: ${e.message}`);
+    }
+    const orphaned = await reconcileOrphanedTasks(opts.workspaceRoot);
+    for (const o of orphaned) {
+        term.orchestratorNote(`reconciled orphaned task ${o.taskId} ("${o.goal.slice(0, 50)}...") — was stuck at "running" from a prior process, marked halted`);
+    }
+    // Load lessons learned if enabled.
+    let lessonContext;
+    if (opts.lessonLearned) {
+        const warning = await checkLessonFileSize(opts.workspaceRoot);
+        if (warning) {
+            term.orchestratorNote(warning);
+        }
+        lessonContext = await loadLessons(opts.workspaceRoot);
+    }
+    if (isConversation(spec)) {
+        return { run: null, isConversation: true, lessonContext };
+    }
+    const dag = customDag ?? buildInitialPlan(spec);
+    const run = {
+        spec,
+        dag,
+        status: "running",
+        escalations: [],
+        orchestratorTrace: [],
+        finalDeliverable: undefined,
+        totalTokenUsage: { inputTokens: 0, outputTokens: 0 },
+    };
+    term.taskIntro(spec.taskId, spec.goal);
+    emitXcoderEvent({ type: "task:intro", taskId: spec.taskId, data: { goal: spec.goal } });
+    term.orchestratorNote(`plan built: ${dag.map((n) => n.id).join(" → ")}`);
+    term.orchestratorNote(`logs: ${spec.taskId}`);
+    emitXcoderEvent({ type: "task:dag", taskId: spec.taskId, data: dagSnapshot(dag) });
+    return { run, isConversation: false, lessonContext };
+}
+/**
+ * Resumes an existing TaskRun from disk, resetting healing budgets
+ * on escalated/healing nodes while preserving healing.log.
+ */
+export async function resumeRun(taskId, opts, protocolMap, masterProtocolSection) {
+    const run = await loadTaskRun(opts.workspaceRoot, taskId);
+    if (!run) {
+        throw new Error(`no task "${taskId}" found in ${opts.workspaceRoot} to resume.`);
+    }
+    if (run.status === "done") {
+        term.orchestratorNote(`${taskId} is already done — nothing to resume.`);
+        return { run, isConversation: false, lessonContext: undefined };
+    }
+    await getOrBuildIndex(opts.workspaceRoot);
+    const orphaned = await reconcileOrphanedTasks(opts.workspaceRoot);
+    for (const o of orphaned) {
+        if (o.taskId !== taskId)
+            term.orchestratorNote(`also reconciled orphaned task ${o.taskId}`);
+        else
+            term.orchestratorNote(`${taskId} was still marked "running" (a prior process died) — reconciled to "halted" and resuming.`);
+    }
+    const resumeCount = rearmForResume(run.dag);
+    term.taskIntro(run.spec.taskId, `[resume] ${run.spec.goal}`);
+    emitXcoderEvent({ type: "task:intro", taskId: run.spec.taskId, data: { goal: run.spec.goal, resumed: true } });
+    term.orchestratorNote(`resuming ${taskId}: ${resumeCount} subtask(s) reset to ready with a fresh healing budget, ${run.dag.filter((n) => n.status === "done").length}/${run.dag.length} already done`);
+    run.status = "running";
+    run.orchestratorTrace.push({
+        thought: "resumed by user request",
+        action: null,
+        observation: `${resumeCount} subtask(s) re-armed for another attempt; already-done subtasks and their outputs were kept as-is.`,
+    });
+    emitXcoderEvent({ type: "task:dag", taskId: run.spec.taskId, data: dagSnapshot(run.dag) });
+    return { run, isConversation: false, lessonContext: undefined };
+}
+/**
+ * Node statuses that must be returned to an executable state before a resumed
+ * run can pick them up. A process that died mid-flight leaves nodes at
+ * `in_progress`/`validating`; a blocked dependency leaves `blocked`/`failed`.
+ * `recomputeReady()` only ever promotes `pending`, so nothing re-arms these by
+ * itself — the execution loop would find zero ready nodes and exit silently.
+ */
+export const REARM_ON_RESUME = [
+    "escalated",
+    "healing",
+    "failed",
+    "blocked",
+    "in_progress",
+    "validating",
+];
+/**
+ * Returns nodes to an executable state for a resumed run. Mutates in place.
+ *
+ * Rules (by precedence):
+ *   1. "done"                 → untouched. Never re-executed, results kept.
+ *   2. "pending"/"ready"     → untouched; recomputeReady() promotes pending
+ *                              once its dependencies land.
+ *   3. escalated/healing/failed/blocked
+ *   4. in_progress/validating (crash-orphaned)
+ *                             → status="ready", healing.attempts=0, healing.log
+ *                               kept so the failure history is not lost.
+ *   5. unknown status         → left alone (fail-safe; never guessed into ready).
+ *
+ * @returns number of nodes re-armed.
+ */
+export function rearmForResume(dag) {
+    let rearmed = 0;
+    for (const node of dag) {
+        if (node.status === "done" || node.status === "pending" || node.status === "ready")
+            continue;
+        if (!REARM_ON_RESUME.includes(node.status))
+            continue;
+        node.status = "ready";
+        node.healing.attempts = 0;
+        rearmed++;
+    }
+    return rearmed;
+}

package/dist/sdlc-runtime/progress-persister.d.ts

@@ -0,0 +1,10 @@
+import type { TaskRun } from "../types.js";
+/**
+ * Persists the current DAG state and progress summary to disk.
+ * Emits task:dag event, saves TaskRun atomically, and writes progress summary markdown.
+ */
+export declare function saveProgress(workspaceRoot: string, run: TaskRun): Promise<void>;
+/**
+ * Persists the DAG state (synchronous fallback when event loop may be draining).
+ */
+export declare function saveProgressWithFallback(workspaceRoot: string, run: TaskRun, saveTaskRunSync: (root: string, run: TaskRun) => void): Promise<void>;

package/dist/sdlc-runtime/progress-persister.js

@@ -0,0 +1,34 @@
+import { saveTaskRun } from "../store/task-store.js";
+import { saveProgressSummary } from "../store/task-store.js";
+import { buildProgressSummaryMarkdown } from "../orchestrator/progress-summary.js";
+import { emitXcoderEvent } from "../events/bus.js";
+import { dagSnapshot } from "./dag-utils.js";
+import * as term from "../util/terminal.js";
+/**
+ * Persists the current DAG state and progress summary to disk.
+ * Emits task:dag event, saves TaskRun atomically, and writes progress summary markdown.
+ */
+export async function saveProgress(workspaceRoot, run) {
+    await saveTaskRun(workspaceRoot, run);
+    emitXcoderEvent({ type: "task:dag", taskId: run.spec.taskId, data: dagSnapshot(run.dag) });
+    const progressMd = buildProgressSummaryMarkdown(run);
+    await saveProgressSummary(workspaceRoot, run.spec.taskId, progressMd);
+    term.orchestratorNote(`progress summary written: .xcoder/tasks/${run.spec.taskId}.md`);
+}
+/**
+ * Persists the DAG state (synchronous fallback when event loop may be draining).
+ */
+export async function saveProgressWithFallback(workspaceRoot, run, saveTaskRunSync) {
+    try {
+        await Promise.race([
+            saveTaskRun(workspaceRoot, run),
+            new Promise((_, reject) => setTimeout(() => reject(new Error("save timed out")), 500)),
+        ]);
+    }
+    catch {
+        saveTaskRunSync(workspaceRoot, run);
+    }
+    emitXcoderEvent({ type: "task:dag", taskId: run.spec.taskId, data: dagSnapshot(run.dag) });
+    const progressMd = buildProgressSummaryMarkdown(run);
+    await saveProgressSummary(workspaceRoot, run.spec.taskId, progressMd);
+}

package/dist/sdlc-runtime/protocol-loader.d.ts

@@ -0,0 +1,10 @@
+import type { WksProtocolMap } from "../protocol/wks-protocol-manager.js";
+/**
+ * Reads and parses wks_protocol.md from the workspace root.
+ * Returns the parsed map and the optional masterProtocolSection.
+ * If the file is missing or empty, returns empty map/undefined.
+ */
+export declare function loadProtocol(workspaceRoot: string): Promise<{
+    protocolMap: WksProtocolMap;
+    masterProtocolSection: string | undefined;
+}>;

package/dist/sdlc-runtime/protocol-loader.js

@@ -0,0 +1,21 @@
+import { parseWksProtocol } from "../protocol/wks-protocol-manager.js";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+/**
+ * Reads and parses wks_protocol.md from the workspace root.
+ * Returns the parsed map and the optional masterProtocolSection.
+ * If the file is missing or empty, returns empty map/undefined.
+ */
+export async function loadProtocol(workspaceRoot) {
+    try {
+        const filePath = path.join(workspaceRoot, "wks_protocol.md");
+        const content = await fs.readFile(filePath, "utf-8");
+        const protocolMap = parseWksProtocol(content);
+        // "sdlc-orchestrator" is reserved for future LLM-driven orchestrator engines.
+        const masterProtocolSection = protocolMap["sdlc-orchestrator"];
+        return { protocolMap, masterProtocolSection };
+    }
+    catch {
+        return { protocolMap: {}, masterProtocolSection: undefined };
+    }
+}

package/dist/sdlc-runtime/reporting.d.ts

@@ -0,0 +1,24 @@
+import type { SubtaskNode, SubtaskResult, TaskRun, TaskSpec } from "../types.js";
+/**
+ * Pure function: computes the orchestration trace entry, event data, and
+ * idempotent defect ID for an iteration-exhausted SubtaskResult.  Called
+ * by handleResult() during the orchestrator loop; also exported for test.
+ */
+export declare function buildExhaustionTrace(nodeId: string, taskId: string, result: SubtaskResult): {
+    trace: {
+        thought: string;
+        action: null;
+        observation: string;
+    };
+    event: {
+        type: "agent:exhausted";
+        taskId: string;
+        subtaskId: string;
+        data: {
+            maxIterations: number;
+            iterationsUsed: number;
+        };
+    };
+    defectId: string;
+};
+export declare function summarize(dag: SubtaskNode[], run: TaskRun, spec: TaskSpec, workspaceRoot: string): string;

package/dist/sdlc-runtime/reporting.js

@@ -0,0 +1,68 @@
+import { taskLogDir } from "../util/logs.js";
+/**
+ * Pure function: computes the orchestration trace entry, event data, and
+ * idempotent defect ID for an iteration-exhausted SubtaskResult.  Called
+ * by handleResult() during the orchestrator loop; also exported for test.
+ */
+export function buildExhaustionTrace(nodeId, taskId, result) {
+    const maxIterations = result.iterations || 200;
+    return {
+        trace: {
+            thought: `${nodeId} exhausted its ${maxIterations} iterations without a final_answer`,
+            action: null,
+            observation: result.summary,
+        },
+        event: {
+            type: "agent:exhausted",
+            taskId,
+            subtaskId: nodeId,
+            data: { maxIterations, iterationsUsed: result.iterations },
+        },
+        defectId: `DEFECT-EXH-${nodeId}`,
+    };
+}
+export function summarize(dag, run, spec, workspaceRoot) {
+    const lines = [
+        `# ${spec.goal}`,
+        "",
+        `Status: ${run.status}`,
+        `Tokens: ${run.totalTokenUsage.inputTokens} in / ${run.totalTokenUsage.outputTokens} out`,
+        `Logs: ${taskLogDir(workspaceRoot, spec.taskId)}`,
+        "",
+    ];
+    for (const node of dag) {
+        lines.push(`## ${node.id} (${node.role}) — ${node.status}`);
+        if (node.result)
+            lines.push(node.result.summary);
+        if (node.result?.crashed)
+            lines.push(`**Crashed** — see sys.log for the stack trace.`);
+        if (node.status === "escalated") {
+            const esc = run.escalations.find((e) => e.subtaskId === node.id);
+            lines.push(`**Escalated:** ${esc?.reason}`);
+        }
+        lines.push("");
+    }
+    // --- Files touched section
+    const nodesWithFiles = dag.filter((n) => n.result && ((n.result._filesTouchedMeta?.length ?? 0) > 0 || n.result.filesTouched.length > 0));
+    if (nodesWithFiles.length > 0) {
+        lines.push("## Files touched");
+        lines.push("");
+        for (const node of nodesWithFiles) {
+            lines.push(`### ${node.id}`);
+            const meta = node.result._filesTouchedMeta;
+            if (meta && meta.length > 0) {
+                for (const entry of meta) {
+                    const label = entry.operation === "created" ? "[created]" : "[modified]";
+                    lines.push(`- \`${entry.path}\` ${label}`);
+                }
+            }
+            else {
+                for (const f of node.result.filesTouched) {
+                    lines.push(`- \`${f}\` [touched]`);
+                }
+            }
+            lines.push("");
+        }
+    }
+    return lines.join("\n");
+}

package/dist/sdlc-runtime/sdlc-orchestrator.d.ts

@@ -0,0 +1,59 @@
+import type { SubtaskNode, TaskRun, TaskSpec } from "../types.js";
+import type { InterruptAction } from "../orchestrator/interrupt-handler.js";
+import { LlmClient } from "../llm/client.js";
+import { InteractiveSteeringManager } from "../orchestrator/interactive-steering.js";
+export { dagSnapshot, recomputeReady, inlineIntoDependents } from "./dag-utils.js";
+export { summarize, buildExhaustionTrace } from "./reporting.js";
+export interface OrchestratorOptions {
+    workspaceRoot: string;
+    /** Orchestrator role client — used by the coordinator/conversation loops. */
+    llm: LlmClient;
+    /** Swarm/Sub Agent role client — used by dispatchSwarm workers. Defaults to `llm`. */
+    subAgentLlm?: LlmClient;
+    /** Explicit per-role clients — highest priority when all are provided. */
+    roleLlm?: Partial<Record<import("../config/loadConfig.js").AgentRole, LlmClient>>;
+    concurrency: number;
+    maxRounds?: number;
+    lessonLearned?: boolean;
+    signal?: AbortSignal;
+    quiet?: boolean;
+    /**
+     * Force a full index rebuild before the run instead of probing it first.
+     * Backs the `--reindex` flag; freshness is otherwise automatic, so this is
+     * an override rather than the only route to an up-to-date index.
+     */
+    reindex?: boolean;
+}
+export declare class SdlcOrchestrator {
+    private opts;
+    private protocolMap;
+    private masterProtocolSection;
+    private lessonContext;
+    private _abortController;
+    private _steering;
+    private _currentRun;
+    private _haltDeferred;
+    private _index?;
+    constructor(opts: OrchestratorOptions);
+    /**
+     * Gate the workspace index once per task run.
+     *
+     * Every ingress path needs this: the index is the source of truth for which
+     * files exist, and it used to be reused no matter how stale it was. The gate
+     * is stat-only while the index is still accurate, so the price of
+     * correctness here is one filesystem walk, not a full re-hash.
+     *
+     * It never throws. A cache refresh failure degrades to the best index
+     * available rather than aborting the run — the authorization boundary is
+     * `resolveInWorkspace()`, which is untouched and still fails closed.
+     */
+    private gateIndex;
+    /** The index gated for the current run, if a run has started. */
+    get index(): import("../tools/workspace-index.js").WorkspaceIndex | undefined;
+    get currentRun(): TaskRun | null;
+    get steering(): InteractiveSteeringManager;
+    run(spec: TaskSpec, customDag?: SubtaskNode[]): Promise<TaskRun>;
+    resume(taskId: string): Promise<TaskRun>;
+    halt(currentRun: TaskRun): Promise<InterruptAction["summary"]>;
+    private _runLoop;
+}

package/dist/sdlc-runtime/sdlc-orchestrator.js

@@ -0,0 +1,170 @@
+import { ensureFreshIndex } from "../tools/index-freshness.js";
+import { logIndexRefresh } from "../util/file-access-log.js";
+import { saveTaskRunSync } from "../store/task-store.js";
+import { FooterManager } from "../util/footer-manager.js";
+import { isInteractiveStdout } from "../util/tty.js";
+import { InteractiveSteeringManager } from "../orchestrator/interactive-steering.js";
+// Helper modules
+import { loadProtocol } from "./protocol-loader.js";
+import { initializeRun, resumeRun } from "./plan-initializer.js";
+import { runConversation } from "./conversation-runner.js";
+import { executeLoop } from "./execution-loop.js";
+import { saveProgress } from "./progress-persister.js";
+import { haltInternal, checkSteeringInjection } from "./steering-handler.js";
+// Re-exported for consumer compatibility
+export { dagSnapshot, recomputeReady, inlineIntoDependents } from "./dag-utils.js";
+export { summarize, buildExhaustionTrace } from "./reporting.js";
+export class SdlcOrchestrator {
+    opts;
+    protocolMap = {};
+    masterProtocolSection = undefined;
+    lessonContext = undefined;
+    _abortController = null;
+    _steering = new InteractiveSteeringManager();
+    _currentRun = null;
+    _haltDeferred = null;
+    _index;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /**
+     * Gate the workspace index once per task run.
+     *
+     * Every ingress path needs this: the index is the source of truth for which
+     * files exist, and it used to be reused no matter how stale it was. The gate
+     * is stat-only while the index is still accurate, so the price of
+     * correctness here is one filesystem walk, not a full re-hash.
+     *
+     * It never throws. A cache refresh failure degrades to the best index
+     * available rather than aborting the run — the authorization boundary is
+     * `resolveInWorkspace()`, which is untouched and still fails closed.
+     */
+    async gateIndex(taskId) {
+        const result = await ensureFreshIndex(this.opts.workspaceRoot, {
+            force: this.opts.reindex === true,
+        });
+        this._index = result.index;
+        if (!this.opts.quiet) {
+            try {
+                await logIndexRefresh(this.opts.workspaceRoot, result, {
+                    taskId: taskId ?? "session",
+                    subtaskId: "-",
+                });
+            }
+            catch {
+                // observability must never break a run
+            }
+        }
+    }
+    /** The index gated for the current run, if a run has started. */
+    get index() {
+        return this._index;
+    }
+    get currentRun() {
+        return this._currentRun;
+    }
+    get steering() {
+        return this._steering;
+    }
+    // ── run ──────────────────────────────────────────────────────────
+    async run(spec, customDag) {
+        await this.gateIndex();
+        // Load protocol.
+        const { protocolMap, masterProtocolSection } = await loadProtocol(this.opts.workspaceRoot);
+        this.protocolMap = protocolMap;
+        this.masterProtocolSection = masterProtocolSection;
+        const init = await initializeRun(spec, this.opts, protocolMap, masterProtocolSection, customDag);
+        this.lessonContext = init.lessonContext;
+        if (init.isConversation) {
+            return runConversation(spec, this.opts, protocolMap, masterProtocolSection);
+        }
+        const run = init.run;
+        await saveProgress(this.opts.workspaceRoot, run);
+        return this._runLoop(run);
+    }
+    // ── resume ───────────────────────────────────────────────────────
+    async resume(taskId) {
+        await this.gateIndex();
+        const { protocolMap, masterProtocolSection } = await loadProtocol(this.opts.workspaceRoot);
+        this.protocolMap = protocolMap;
+        this.masterProtocolSection = masterProtocolSection;
+        const init = await resumeRun(taskId, this.opts, protocolMap, masterProtocolSection);
+        if (init.run.status === "done")
+            return init.run;
+        const run = init.run;
+        await saveProgress(this.opts.workspaceRoot, run);
+        return this._runLoop(run);
+    }
+    // ── halt ─────────────────────────────────────────────────────────
+    async halt(currentRun) {
+        if (!this._abortController) {
+            this._abortController = new AbortController();
+        }
+        this._abortController.abort();
+        if (this._currentRun) {
+            return new Promise((resolve, reject) => {
+                this._haltDeferred = { resolve, reject };
+            });
+        }
+        // Not running — compute halt inline.
+        const summary = await haltInternal(currentRun, this.opts, saveTaskRunSync);
+        return summary;
+    }
+    // ── Private: wraps executeLoop with halt/abort lifecycle ────────
+    async _runLoop(run) {
+        this._currentRun = run;
+        this._abortController = new AbortController();
+        const signal = this.opts.signal ?? this._abortController.signal;
+        // Wire up the orchestration context with callbacks.
+        const ctx = {
+            opts: this.opts,
+            protocolMap: this.protocolMap,
+            masterProtocolSection: this.masterProtocolSection,
+            lessonContext: this.lessonContext,
+            signal,
+            steering: this._steering,
+            quiet: this.opts.quiet ?? false,
+            onSteeringInjection: async (r) => {
+                return checkSteeringInjection(r, this.opts, this._steering);
+            },
+            onSaveProgress: async (r) => {
+                await saveProgress(this.opts.workspaceRoot, r);
+            },
+        };
+        try {
+            // Initialize footer iff the interactive gate passes.
+            // Availability matrix (single source of truth in src/util/tty.ts):
+            //   TTY attached AND NO_COLOR unset. Quiet run mode mutes painting.
+            FooterManager.init({
+                tty: isInteractiveStdout(),
+                // Raw goal — the renderer owns the ≤50-char title field (footer-text.ts).
+                taskTitle: run.spec.goal,
+                quiet: this.opts.quiet ?? false,
+            });
+            const result = await executeLoop(run, ctx);
+            // Cleanup.
+            this._currentRun = null;
+            this._abortController = null;
+            // If halt() was called but the task finished before the abort check,
+            // still provide a summary.
+            if (this._haltDeferred) {
+                const dag = result.dag;
+                const summary = {
+                    taskId: result.spec.taskId,
+                    doneCount: dag.filter((n) => n.status === "done").length,
+                    totalCount: dag.length,
+                    resumeCommand: `xcoder resume ${result.spec.taskId}`,
+                    taskFilePath: `.xcoder/tasks/${result.spec.taskId}.json`,
+                };
+                this._haltDeferred.resolve(summary);
+                this._haltDeferred = null;
+            }
+            return result;
+        }
+        catch (e) {
+            this._currentRun = null;
+            this._abortController = null;
+            throw e;
+        }
+    }
+}

package/dist/sdlc-runtime/sdlc-skill.d.ts

@@ -0,0 +1,44 @@
+import type { Role, SdlcStage, TaskInputs } from "../types.js";
+export declare const SDLC_STAGES: {
+    stage: SdlcStage;
+    description: string;
+}[];
+export declare const STAGE_ROLE: Record<SdlcStage, Role>;
+/**
+ * Internal roles that exist for traceability and system functions but are
+ * not mapped to any DAG stage — they are invoked inline by the orchestrator
+ * rather than dispatched as standalone Sub Agents.
+ */
+export declare const INTERNAL_ROLES: Role[];
+/**
+ * Explicit intake classification. This exists specifically because "the
+ * orchestrator infers where to start" was a hidden judgment call in the
+ * original sketch — inconsistent behavior waiting to happen. Every rule
+ * here is a plain, inspectable predicate over what inputs are actually
+ * present, checked top to bottom, first match wins.
+ */
+export interface IntakeRule {
+    name: string;
+    when: (inputs: TaskInputs) => boolean;
+    startStage: SdlcStage;
+    /** The stage sequence this kind of task walks, in order. */
+    sequence: SdlcStage[];
+}
+export declare const INTAKE_RULES: IntakeRule[];
+export declare const CONVERSATION_RULE: IntakeRule;
+export declare function classifyIntake(inputs: TaskInputs): IntakeRule;
+export declare function classifyDesignRole(inputs: TaskInputs): Role;
+/**
+ * Returns the Role for a given SdlcStage. For the `design` stage, when
+ * `inputs` is provided, this delegates to `classifyDesignRole` to decide
+ * between `architect` and `business-analyst`. All other stages — and the
+ * `design` stage when `inputs` is omitted — use the static default mapping
+ * below, preserving backward compatibility with every existing call site.
+ */
+export declare function getStageRole(stage: SdlcStage, inputs?: TaskInputs): Role;
+/**
+ * Returns true when the given role is one of the internal (non-DAG-stage)
+ * roles such as `defect-manager`. These roles are never dispatched as Sub
+ * Agents — they exist for traceability and orchestrator-inline decisions.
+ */
+export declare function isInternalRole(role: Role): boolean;