xcoder-dna 0.0.0-stage → 1.3.1

package/dist/backlog/po-agent.js

@@ -0,0 +1,121 @@
+// xcoder:version 2 | xcoder:task task-c49600 | xcoder:updated 2026-08-13T13:52:10.297Z | xcoder:subtask code-st-6d79ef
+import { shortId } from "../util/ids.js";
+import { log } from "../util/logger.js";
+import { SubAgent } from "../agents/sub-agent.js";
+import { createLlmClient } from "../llm/factory.js";
+import { BA_REQUIREMENTS_DIRECTIVE } from "../skills/directives.js";
+// ---------------------------------------------------------------------------
+// PO Agent — thin SubAgent wrapper for backlog pick
+// ---------------------------------------------------------------------------
+/**
+ * Runs a one-shot business-analyst Sub Agent (Product Owner) to select
+ * the highest-priority item from the provided backlog list.
+ *
+ * Follows the exact pattern of `src/ba-runner.ts`: creates a standalone
+ * SubAgent (no SdlcOrchestrator DAG), runs a single subtask, parses the
+ * deliverable. On LLM failure, falls back to deterministic
+ * oldest-open-item selection and logs a warning.
+ */
+export async function runPoPick(root, items, model) {
+    // Guard: only consider open items not already in a sprint.
+    const eligibleItems = items.filter((it) => it.status === "open" && it.sprintId === null);
+    if (eligibleItems.length === 0) {
+        throw new Error("No eligible backlog items — all open items are either in a sprint or have a different status.");
+    }
+    // Build a concise table for the LLM.
+    const itemTable = eligibleItems
+        .map((it) => `- id: ${it.id} | priority: ${it.priority ?? "(none)"} | title: ${it.title}`)
+        .join("\n");
+    const goal = `Select the highest-priority backlog item from the list below for the next implementation sprint. ` +
+        `Consider explicit priority labels, title urgency, and implicit risk/dependency signals. ` +
+        `Return ONLY a JSON object with keys: selectedId, title, reasoning (one sentence). ` +
+        `Backlog items:\n${itemTable}`;
+    // Create an LlmClient.
+    let llm;
+    try {
+        llm = createLlmClient("sub_agent", { model });
+    }
+    catch (e) {
+        log.fail(`PO Agent: failed to create LLM client: ${e.message}`);
+        return deterministicFallback(eligibleItems);
+    }
+    // Build a one-node SubtaskNode for the business analyst.
+    const nodeId = `po-${shortId("st")}`;
+    const subtaskNode = {
+        id: nodeId,
+        stage: "requirements",
+        role: "business-analyst",
+        engine: "react-v1",
+        dependsOn: [],
+        goal,
+        upstreamContext: {
+            backlogItems: eligibleItems.map(({ id, title, priority, status }) => ({
+                id,
+                title,
+                priority,
+                status,
+            })),
+        },
+        deliverableSpec: "A JSON object: { selectedId: string, title: string, reasoning: string }.",
+        acceptanceCriteria: [
+            {
+                id: "AC1",
+                type: "schema",
+                description: "selectedId matches one of the provided backlog item ids.",
+            },
+            {
+                id: "AC2",
+                type: "schema",
+                description: "reasoning is a non-empty string explaining the choice.",
+            },
+        ],
+        status: "ready",
+        healing: { attempts: 0, maxAttempts: 1, log: [] },
+    };
+    // Create the SubAgent with the BA requirements directive.
+    const taskId = shortId("task");
+    const agent = new SubAgent({
+        taskId,
+        workspaceRoot: root,
+        llm,
+        directiveOverride: BA_REQUIREMENTS_DIRECTIVE,
+    });
+    // Run the agent and parse the result.
+    try {
+        const result = await agent.run(subtaskNode);
+        const delivered = typeof result.deliverable === "string"
+            ? JSON.parse(result.deliverable)
+            : result.deliverable;
+        if (delivered &&
+            typeof delivered === "object" &&
+            "selectedId" in delivered &&
+            "title" in delivered &&
+            "reasoning" in delivered) {
+            const d = delivered;
+            // Validate that selectedId actually exists in the provided items.
+            if (eligibleItems.some((it) => it.id === d.selectedId)) {
+                return d;
+            }
+            log.fail(`PO Agent selected id "${d.selectedId}" which is not in the provided list — falling back to deterministic.`);
+            return deterministicFallback(eligibleItems);
+        }
+        log.fail("PO Agent returned an unrecognised deliverable shape — falling back to deterministic.");
+        return deterministicFallback(eligibleItems);
+    }
+    catch (e) {
+        log.fail(`PO Agent run threw unexpectedly: ${e.message}`);
+        return deterministicFallback(eligibleItems);
+    }
+}
+// ---------------------------------------------------------------------------
+// Deterministic fallback — oldest open item
+// ---------------------------------------------------------------------------
+function deterministicFallback(items) {
+    log.dim("PO Agent: using deterministic oldest-first fallback.");
+    const oldest = items[0]; // items are already sorted by createdAt asc.
+    return {
+        selectedId: oldest.id,
+        title: oldest.title,
+        reasoning: `Deterministic fallback: selected oldest open item (${oldest.id}).`,
+    };
+}

package/dist/backlog/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Backlog data model types — see `.xcoder/design/backlog-management-design.md`.
+ */
+export type BacklogStatus = "open" | "in-progress" | "done";
+export interface BacklogItem {
+    id: string;
+    title: string;
+    description: string;
+    status: BacklogStatus;
+    priority?: string;
+    taskId?: string;
+    sprintId: string | null;
+    blockedReason: string | null;
+    sprintRunAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface BacklogStoreMeta {
+    nextId: number;
+}
+/** Full shape of _backlog.json on disk */
+export interface BacklogFile {
+    meta: BacklogStoreMeta;
+    items: BacklogItem[];
+}

package/dist/backlog/types.js

@@ -0,0 +1,4 @@
+/**
+ * Backlog data model types — see `.xcoder/design/backlog-management-design.md`.
+ */
+export {};

package/dist/bench/run.d.ts

@@ -0,0 +1,11 @@
+import type { BenchReport } from "./types.js";
+export interface RunBenchmarkOptions {
+    fixturesDir: string;
+    outFile: string;
+    concurrency: number;
+    model?: string;
+    keepWorkspaces: boolean;
+}
+export declare function runBenchmark(opts: RunBenchmarkOptions): Promise<BenchReport>;
+/** Compares this report's average reasoning score per fixture against a previous report — the actual "is this getting better over time" signal. */
+export declare function compareReports(currentFile: string, previousFile: string): Promise<void>;

package/dist/bench/run.js

@@ -0,0 +1,185 @@
+// xcoder:version 2 | xcoder:task task-c49600 | xcoder:updated 2026-08-13T13:52:44.290Z | xcoder:subtask code-st-6d79ef
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { SdlcOrchestrator } from "../sdlc-runtime/sdlc-orchestrator.js";
+import { buildTaskSpec } from "../orchestrator/task-factory.js";
+import { buildIndex } from "../tools/workspace-index.js";
+import { createLlmClient } from "../llm/factory.js";
+/**
+ * WHY THIS EXISTS: "does this directive/skill/prompt change actually help"
+ * is otherwise a question you can only answer by vibes after running a
+ * task by hand a few times. This runs the same fixture set against the
+ * real orchestrator and the real model, and reports the four numbers that
+ * matter for comparing runs over time: how long it took (wall clock), how
+ * much it cost (tokens), how much back-and-forth it took (iterations), and
+ * whether it actually passed (status + reasoning score).
+ *
+ * COST WARNING: every fixture is a real Anthropic API call sequence, same
+ * as running `xcoder` normally. This is not free or instant to run.
+ */
+async function loadFixtures(dir) {
+    const files = (await fs.readdir(dir)).filter((f) => f.endsWith(".json"));
+    const fixtures = [];
+    for (const file of files) {
+        const raw = await fs.readFile(path.join(dir, file), "utf8");
+        fixtures.push(JSON.parse(raw));
+    }
+    return fixtures;
+}
+async function seedWorkspace(root, seedFiles) {
+    if (!seedFiles)
+        return;
+    for (const [relPath, content] of Object.entries(seedFiles)) {
+        const full = path.join(root, relPath);
+        await fs.mkdir(path.dirname(full), { recursive: true });
+        await fs.writeFile(full, content, "utf8");
+    }
+}
+function sumTokens(a, b) {
+    return { inputTokens: a.inputTokens + b.inputTokens, outputTokens: a.outputTokens + b.outputTokens };
+}
+function summarizeRun(run, wallTimeMs, fixtureName, workspace) {
+    const subtasks = run.dag.map((n) => ({
+        subtaskId: n.id,
+        role: n.role,
+        status: n.status,
+        iterations: n.result?.iterations ?? 0,
+        tokenUsage: n.result?.tokenUsage ?? { inputTokens: 0, outputTokens: 0 },
+        reasoningScore: n.reasoningScore?.score ?? null,
+        healingAttempts: n.healing.attempts,
+    }));
+    const totalIterations = subtasks.reduce((sum, s) => sum + s.iterations, 0);
+    const scored = subtasks.filter((s) => s.reasoningScore !== null);
+    const avgReasoningScore = scored.length ? scored.reduce((sum, s) => sum + (s.reasoningScore ?? 0), 0) / scored.length : null;
+    return {
+        fixture: fixtureName,
+        workspace,
+        wallTimeMs,
+        status: run.status,
+        totalTokenUsage: run.totalTokenUsage,
+        totalIterations,
+        subtaskCount: subtasks.length,
+        escalationCount: run.escalations.length,
+        avgReasoningScore,
+        subtasks,
+    };
+}
+export async function runBenchmark(opts) {
+    const fixtures = await loadFixtures(opts.fixturesDir);
+    if (fixtures.length === 0) {
+        throw new Error(`no fixtures found in ${opts.fixturesDir} (expected *.json files matching BenchFixture)`);
+    }
+    const results = [];
+    let tokenTotal = { inputTokens: 0, outputTokens: 0 };
+    for (const fixture of fixtures) {
+        console.log(`\n=== ${fixture.name} ===`);
+        const scratchRoot = await fs.mkdtemp(path.join(os.tmpdir(), `xcoder-bench-${fixture.name}-`));
+        try {
+            await seedWorkspace(scratchRoot, fixture.seedFiles);
+            await buildIndex(scratchRoot);
+            let llm;
+            try {
+                llm = createLlmClient("orchestrator", { model: opts.model });
+            }
+            catch (e) {
+                results.push({
+                    fixture: fixture.name,
+                    workspace: scratchRoot,
+                    wallTimeMs: 0,
+                    status: "error",
+                    totalTokenUsage: { inputTokens: 0, outputTokens: 0 },
+                    totalIterations: 0,
+                    subtaskCount: 0,
+                    escalationCount: 0,
+                    avgReasoningScore: null,
+                    subtasks: [],
+                    error: e.message,
+                });
+                continue;
+            }
+            const spec = buildTaskSpec(fixture.task, { code: fixture.code, design: fixture.design, defectDetail: fixture.defect, url: fixture.url, credentialRef: fixture.credentialRef }, { maxHealingAttempts: fixture.maxHealing ?? 2, concurrency: fixture.concurrency ?? opts.concurrency });
+            const orchestrator = new SdlcOrchestrator({
+                workspaceRoot: scratchRoot,
+                llm,
+                concurrency: fixture.concurrency ?? opts.concurrency,
+            });
+            const start = Date.now();
+            const run = await orchestrator.run(spec);
+            const wallTimeMs = Date.now() - start;
+            const result = summarizeRun(run, wallTimeMs, fixture.name, scratchRoot);
+            results.push(result);
+            tokenTotal = sumTokens(tokenTotal, result.totalTokenUsage);
+        }
+        catch (e) {
+            results.push({
+                fixture: fixture.name,
+                workspace: scratchRoot,
+                wallTimeMs: 0,
+                status: "error",
+                totalTokenUsage: { inputTokens: 0, outputTokens: 0 },
+                totalIterations: 0,
+                subtaskCount: 0,
+                escalationCount: 0,
+                avgReasoningScore: null,
+                subtasks: [],
+                error: e.message,
+            });
+        }
+        finally {
+            if (!opts.keepWorkspaces) {
+                await fs.rm(scratchRoot, { recursive: true, force: true });
+            }
+            else {
+                console.log(`  workspace kept at: ${scratchRoot}`);
+            }
+        }
+    }
+    const report = {
+        runAt: new Date().toISOString(),
+        model: opts.model ?? process.env.XCODER_MODEL ?? "claude-sonnet-5",
+        results,
+    };
+    await fs.mkdir(path.dirname(opts.outFile), { recursive: true });
+    await fs.writeFile(opts.outFile, JSON.stringify(report, null, 2), "utf8");
+    printReportTable(report);
+    console.log(`\nTotal tokens this run: ${tokenTotal.inputTokens} in / ${tokenTotal.outputTokens} out`);
+    console.log(`Report written to: ${opts.outFile}`);
+    return report;
+}
+function printReportTable(report) {
+    console.log("\n" + "Task".padEnd(28) + "Status".padEnd(12) + "Time".padEnd(10) + "Tokens (in/out)".padEnd(20) + "Iters".padEnd(8) + "Score");
+    console.log("-".repeat(90));
+    for (const r of report.results) {
+        const time = r.error ? "—" : `${(r.wallTimeMs / 1000).toFixed(1)}s`;
+        const tokens = r.error ? "—" : `${r.totalTokenUsage.inputTokens}/${r.totalTokenUsage.outputTokens}`;
+        const score = r.avgReasoningScore !== null ? r.avgReasoningScore.toFixed(0) : "—";
+        console.log(r.fixture.padEnd(28) +
+            (r.error ? "error" : r.status).padEnd(12) +
+            time.padEnd(10) +
+            tokens.padEnd(20) +
+            String(r.totalIterations).padEnd(8) +
+            score);
+        if (r.error)
+            console.log(`  ! ${r.error}`);
+    }
+}
+/** Compares this report's average reasoning score per fixture against a previous report — the actual "is this getting better over time" signal. */
+export async function compareReports(currentFile, previousFile) {
+    const current = JSON.parse(await fs.readFile(currentFile, "utf8"));
+    const previous = JSON.parse(await fs.readFile(previousFile, "utf8"));
+    console.log(`\nComparing ${path.basename(currentFile)} vs ${path.basename(previousFile)}:\n`);
+    for (const cur of current.results) {
+        const prev = previous.results.find((p) => p.fixture === cur.fixture);
+        if (!prev) {
+            console.log(`${cur.fixture.padEnd(28)} (no previous run to compare)`);
+            continue;
+        }
+        const scoreDelta = (cur.avgReasoningScore ?? 0) - (prev.avgReasoningScore ?? 0);
+        const tokenDelta = cur.totalTokenUsage.inputTokens + cur.totalTokenUsage.outputTokens - (prev.totalTokenUsage.inputTokens + prev.totalTokenUsage.outputTokens);
+        const iterDelta = cur.totalIterations - prev.totalIterations;
+        const arrow = (n) => (n > 0 ? "▲" : n < 0 ? "▼" : "=");
+        console.log(`${cur.fixture.padEnd(28)} score ${arrow(scoreDelta)}${Math.abs(scoreDelta).toFixed(0)}  ` +
+            `tokens ${arrow(tokenDelta)}${Math.abs(tokenDelta)}  iterations ${arrow(iterDelta)}${Math.abs(iterDelta)}`);
+    }
+}

package/dist/bench/types.d.ts

@@ -0,0 +1,50 @@
+import type { TokenUsage } from "../types.js";
+/**
+ * A benchmark fixture is a self-contained, reproducible task: an optional
+ * set of seed files written into a fresh scratch workspace before the run,
+ * plus the same inputs `xcoder`'s CLI would take. Fixtures are checked into
+ * `src/bench/fixtures/*.json` so a benchmark run is exactly reproducible
+ * run to run — the only thing that varies is the model's behavior, which
+ * is the whole point of running it repeatedly over time.
+ */
+export interface BenchFixture {
+    name: string;
+    description: string;
+    /** relPath -> file content, written into the scratch workspace before the run */
+    seedFiles?: Record<string, string>;
+    task: string;
+    code?: string;
+    design?: string;
+    defect?: string;
+    url?: string;
+    credentialRef?: string;
+    concurrency?: number;
+    maxHealing?: number;
+}
+export interface SubtaskBenchResult {
+    subtaskId: string;
+    role: string;
+    status: string;
+    iterations: number;
+    tokenUsage: TokenUsage;
+    reasoningScore: number | null;
+    healingAttempts: number;
+}
+export interface BenchResult {
+    fixture: string;
+    workspace: string;
+    wallTimeMs: number;
+    status: string;
+    totalTokenUsage: TokenUsage;
+    totalIterations: number;
+    subtaskCount: number;
+    escalationCount: number;
+    avgReasoningScore: number | null;
+    subtasks: SubtaskBenchResult[];
+    error?: string;
+}
+export interface BenchReport {
+    runAt: string;
+    model: string;
+    results: BenchResult[];
+}

package/dist/bench/types.js

@@ -0,0 +1 @@
+export {};

package/dist/cli/swarm.d.ts

@@ -0,0 +1,10 @@
+import { Command } from "commander";
+/**
+ * Register the `xcoder swarm` subcommand.
+ *
+ * Runs an instance swarm: multiple SubAgents dispatched concurrently
+ * against a goal, with a protocol section injected from wks_protocol.md.
+ * Includes a master spinner for the overall run, per-worker lifecycle
+ * callbacks, and a color-coded summary printed on completion.
+ */
+export declare function registerSwarmCommand(parent: Command): void;

package/dist/cli/swarm.js

@@ -0,0 +1,100 @@
+import path from "node:path";
+import { createLlmClient } from "../llm/factory.js";
+import { InstanceSwarmOrchestrator, } from "../instance-swarm/instance-swarm-orchestrator.js";
+import { getOrBuildIndex } from "../tools/workspace-index.js";
+import { log } from "../util/logger.js";
+import { createSpinner } from "../util/spinner.js";
+import { printSwarmSummary } from "../util/terminal.js";
+/**
+ * Register the `xcoder swarm` subcommand.
+ *
+ * Runs an instance swarm: multiple SubAgents dispatched concurrently
+ * against a goal, with a protocol section injected from wks_protocol.md.
+ * Includes a master spinner for the overall run, per-worker lifecycle
+ * callbacks, and a color-coded summary printed on completion.
+ */
+export function registerSwarmCommand(parent) {
+    parent
+        .command("swarm <goal...>")
+        .description("Run an instance swarm: multiple SubAgents dispatched concurrently against a goal, with a protocol section injected.")
+        .option("--protocol <name>", "protocol name (coder, tester, architect, ui-ux, secops, devops)")
+        .option("-m, --model <name>", "override the LLM model (default: env XCODER_MODEL or deepseek-chat)")
+        .option("-w, --workspace <dir>", "workspace root", process.cwd())
+        .option("--concurrency <n>", "number of concurrent SubAgents", "1")
+        .option("--max-iterations <n>", "max iterations per SubAgent", "200")
+        .action(async (goalParts, opts) => {
+        const root = path.resolve(opts.workspace);
+        const goal = goalParts.join(" ");
+        if (!opts.protocol) {
+            log.fail("--protocol is required (coder, tester, architect, ui-ux, secops, devops)");
+            process.exitCode = 1;
+            return;
+        }
+        await getOrBuildIndex(root);
+        let llm;
+        try {
+            llm = createLlmClient("instance_agent", { model: opts.model });
+        }
+        catch (e) {
+            log.fail(e.message);
+            process.exitCode = 1;
+            return;
+        }
+        const concurrency = parseInt(opts.concurrency, 10);
+        const maxIterations = parseInt(opts.maxIterations, 10);
+        log.dim(`swarm goal: ${goal}`);
+        log.dim(`protocol: ${opts.protocol}  concurrency: ${concurrency}`);
+        // ── Master spinner: keeps the CLI alive while workers run ──
+        const spinner = createSpinner(`Dispatching swarm (${concurrency} worker${concurrency > 1 ? "s" : ""})…`);
+        const orchestrator = new InstanceSwarmOrchestrator({
+            workspaceRoot: root,
+            llm,
+            concurrency,
+            maxIterations,
+            hooks: {
+                onWorkerStart: (_wi, workerId) => {
+                    spinner.stop(`Worker started: ${workerId}`);
+                    // Re-start the spinner for the next wait
+                    spinner.stop(`Dispatching swarm (${concurrency} worker${concurrency > 1 ? "s" : ""})…`);
+                },
+                onWorkerFinish: (_wi, workerId, crashed, summary) => {
+                    const preview = summary.length > 80 ? summary.slice(0, 77) + "..." : summary;
+                    const icon = crashed ? "✗" : "✓";
+                    const color = crashed
+                        ? log.fail.bind(log)
+                        : log.ok.bind(log);
+                    // Temporarily stop the spinner to print the worker result,
+                    // then we'll print a final summary at the end.
+                    spinner.stop(`${icon} ${workerId}: ${preview}`);
+                },
+                onWorkerError: (_wi, workerId, error) => {
+                    log.fail(`Worker ${workerId} error: ${error}`);
+                },
+            },
+        });
+        let swarmResult;
+        try {
+            swarmResult = await orchestrator.run(goal, opts.protocol);
+        }
+        catch (e) {
+            spinner.fail(`swarm orchestration failed: ${e.message}`);
+            process.exitCode = 1;
+            return;
+        }
+        spinner.stop("Swarm complete.");
+        // ── Color-coded summary ──
+        printSwarmSummary({
+            instanceId: swarmResult.instanceId,
+            status: swarmResult.status,
+            errors: swarmResult.errors,
+            workerCount: swarmResult.results.length,
+            crashedCount: swarmResult.results.filter((r) => r.result.crashed).length,
+            totalInputTokens: swarmResult.totalTokenUsage.inputTokens,
+            totalOutputTokens: swarmResult.totalTokenUsage.outputTokens,
+            outputDir: swarmResult.outputDir,
+        });
+        if (swarmResult.status === "failed") {
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/task.d.ts

@@ -0,0 +1,14 @@
+import type { Command } from "commander";
+/**
+ * Register the `xcoder task` subcommand tree:
+ *
+ *   xcoder task add --from <path> [--force]
+ *   xcoder task list
+ *   xcoder task scan [--dir <path>] [--dry-run] [--json] [--force]
+ *
+ * `add` and `scan` record intent and exit 0 without running anything or
+ * spending a single token. For both, exit 1 is a hard failure; 2 and 3 stay
+ * reserved for escalated and halted *runs*, which ingestion never produces.
+ * Skips and unchanged files are a successful scan, not a failure.
+ */
+export declare function registerTaskCommand(parent: Command): void;

package/dist/cli/task.js

@@ -0,0 +1,121 @@
+// xcoder:version 5 | xcoder:task task-cee5a1 | xcoder:updated 2026-10-23T12:58:17.067Z | xcoder:subtask code-st-f13216
+// `xcoder task` — ingest scannable task runs from markdown/WBS sources.
+//
+// Registered the same way as `swarm` and `test`: one exported
+// `register...Command(parent)` so `sdlc-cli.ts` stays a thin composition root.
+// All real work lives in `src/task-ingest/` — these actions only translate
+// results into exit codes and sanitized terminal output.
+import path from "node:path";
+import { ingestTask, listIngestedTasks, scanMarkdownTasks } from "../task-ingest/index.js";
+import { sanitizeForTerminal } from "../util/text-sanitize.js";
+import { log } from "../util/logger.js";
+function workspaceRoot(parent) {
+    return path.resolve(parent.opts().workspace ?? process.cwd());
+}
+/**
+ * Register the `xcoder task` subcommand tree:
+ *
+ *   xcoder task add --from <path> [--force]
+ *   xcoder task list
+ *   xcoder task scan [--dir <path>] [--dry-run] [--json] [--force]
+ *
+ * `add` and `scan` record intent and exit 0 without running anything or
+ * spending a single token. For both, exit 1 is a hard failure; 2 and 3 stay
+ * reserved for escalated and halted *runs*, which ingestion never produces.
+ * Skips and unchanged files are a successful scan, not a failure.
+ */
+export function registerTaskCommand(parent) {
+    const taskCmd = parent
+        .command("task")
+        .description("Manage task runs that are scannable by status/incomplete/resume.");
+    taskCmd
+        .command("add")
+        .description("Create a scannable task run from a markdown/WBS source file. Records intent only — it does not run the task.")
+        .requiredOption("--from <path>", "workspace-relative path to the source file")
+        .option("--force", "replace a task that already has completed or in-flight subtasks", false)
+        .action(async (opts) => {
+        const root = workspaceRoot(parent);
+        const result = await ingestTask({
+            workspaceRoot: root,
+            from: opts.from,
+            force: opts.force === true,
+        });
+        if (!result.ok) {
+            log.fail(`${result.code}: ${sanitizeForTerminal(result.message, 300)}`);
+            process.exitCode = 1;
+            return;
+        }
+        const verb = result.created ? "created" : "unchanged";
+        const source = sanitizeForTerminal(result.sourcePath, 80);
+        const count = `${result.nodeCount} subtask${result.nodeCount === 1 ? "" : "s"}, first: ${result.firstStage}`;
+        log.ok(`${verb} ${result.taskId}  from ${source}  (${count})`);
+        log.raw(`next: ${result.nextCommand}`);
+    });
+    taskCmd
+        .command("list")
+        .description("List task runs and the source file each was ingested from.")
+        .action(async () => {
+        const root = workspaceRoot(parent);
+        const tasks = await listIngestedTasks(root);
+        if (!tasks.length) {
+            log.ok(`no task runs found in ${root}`);
+            return;
+        }
+        const header = `${"TASK ID".padEnd(16)} ${"STATUS".padEnd(12)} ${"N".padEnd(4)} ${"SOURCE".padEnd(32)} GOAL`;
+        log.raw(header);
+        log.raw("-".repeat(header.length));
+        for (const t of tasks) {
+            const source = t.sourcePath ?? "(free-text)";
+            log.raw(`${t.taskId.padEnd(16)} ${t.status.padEnd(12)} ${String(t.nodeCount).padEnd(4)} ${sanitizeForTerminal(source, 32).padEnd(32)} ${sanitizeForTerminal(t.goal, 48)}`);
+        }
+    });
+    taskCmd
+        .command("scan")
+        .description("Discover .md task files in a directory and ingest each one. Skips progress summaries and non-task files.")
+        .option("--dir <path>", "directory to scan (defaults to the task store directory)")
+        .option("--dry-run", "report what would be ingested without writing anything", false)
+        .option("--force", "replace tasks that already have completed or in-flight subtasks", false)
+        .option("--json", "machine output: the scan report only, no prose", false)
+        .action(async (opts) => {
+        const root = workspaceRoot(parent);
+        const result = await scanMarkdownTasks({
+            workspaceRoot: root,
+            dir: opts.dir,
+            dryRun: opts.dryRun === true,
+            force: opts.force === true,
+        });
+        if (opts.json === true) {
+            log.raw(JSON.stringify(result, null, 2));
+        }
+        else {
+            const mode = opts.dryRun === true ? " (dry run)" : "";
+            log.raw(`scanned ${sanitizeForTerminal(result.dir, 120)}${mode} — ${result.scanned} markdown file(s)`);
+            for (const o of result.created) {
+                log.ok(`would create/created ${o.taskId ?? "?"}  from ${sanitizeForTerminal(o.sourcePath, 100)}`);
+            }
+            for (const o of result.unchanged) {
+                log.dim(`unchanged ${o.taskId ?? "?"}  from ${sanitizeForTerminal(o.sourcePath, 100)}`);
+            }
+            for (const o of result.skipped) {
+                log.dim(`skipped ${sanitizeForTerminal(o.sourcePath, 100)}  (${o.reason ?? "skipped"})`);
+            }
+            for (const o of result.failed) {
+                log.fail(`failed ${sanitizeForTerminal(o.sourcePath, 100)}  ${o.code ?? "error"}: ${sanitizeForTerminal(o.message ?? "", 200)}`);
+            }
+            if (result.dirError) {
+                log.fail(`${result.dirError.code}: ${sanitizeForTerminal(result.dirError.message, 300)}`);
+            }
+        }
+        // Exit 1 only for a hard failure: the directory itself was unusable, or
+        // every candidate that looked like a task failed. Skips and unchanged
+        // files are a successful scan. 2 and 3 stay reserved for escalated and
+        // halted *runs*.
+        if (result.dirError) {
+            process.exitCode = 1;
+            return;
+        }
+        if (result.failed.length > 0 && result.created.length === 0 && result.unchanged.length === 0) {
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/wbc-arg.d.ts

@@ -0,0 +1,6 @@
+export interface WbcArg {
+    value?: string;
+    argv: string[];
+    error?: string;
+}
+export declare function extractWbcArg(argv: string[]): WbcArg;