xcoder-dna 0.0.0-stage → 1.3.0

package/dist/agents/sub-agent.js

@@ -0,0 +1,353 @@
+import { buildAgentSystemPrompt, parseReactMessage } from "../protocol/react-contract.js";
+import { buildToolManifest, dispatchTool } from "../tools/tool-registry.js";
+import { ROLE_DIRECTIVES } from "../skills/directives.js";
+import { buildBylawContext } from "../skills/bylaw-context.js";
+import { getRoutedExternalSkills } from "../skills/skillRouter.js";
+import { isExternalSkillsEnabled } from "../skills/externalSkillLoader.js";
+import { getOrBuildIndex } from "../tools/workspace-index.js";
+import { detectProjectCommands } from "../tools/project-detect.js";
+import { getEnvironmentInfo } from "../util/env-info.js";
+import { appendThink, appendSys, appendLlm, appendToken } from "../util/logs.js";
+import { emitXcoderEvent } from "../events/bus.js";
+import { DuplicateActionDetector } from "./duplicate-detector.js";
+import * as term from "../util/terminal.js";
+import { silentTerminal } from "../util/terminal-silent.js";
+import { isProtocolErrorLoggingEnabled, logProtocolError } from "../util/protocol-error-logger.js";
+import { isToolErrorLoggingEnabled, logToolError } from "../util/tool-error-logger.js";
+import { recordLesson } from "../orchestrator/lesson-manager.js";
+/**
+ * The "Instance Agent" of the design brief, mapped 1:1 onto Xcoder SDLC's Sub
+ * Agent: role and engine are config on the subtask node (`role`, `engine`),
+ * not baked into a special-purpose class.
+ *
+ * Isolation contract: `run()` NEVER throws. Every failure mode inside the
+ * loop — an LLM API error, a tool exception that somehow escaped
+ * `dispatchTool`'s own try/catch, an unparseable response — is caught,
+ * logged to `sys.log`, surfaced to the terminal, and turned into either a
+ * recoverable observation (the loop continues) or, if truly fatal, a
+ * `crashed: true` result the Master Orchestrator can route through its
+ * normal bounded healing/escalation path. The caller in `orchestrator/
+ * swarm.ts` still wraps this in its own try/catch as defense in depth, but
+ * this class is designed not to need that safety net.
+ */
+export class SubAgent {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    get term() {
+        return this.opts.quiet ? silentTerminal : term;
+    }
+    async run(subtask) {
+        const { taskId, workspaceRoot } = this.opts;
+        if (subtask.engine !== "react-v1") {
+            return this.crashResult(subtask, `Sub Agent engine "${subtask.engine}" is not implemented yet — only "react-v1" runs today.`);
+        }
+        let systemPrompt;
+        try {
+            const index = await getOrBuildIndex(workspaceRoot);
+            const detectedCommands = await detectProjectCommands(workspaceRoot, index);
+            const environment = getEnvironmentInfo();
+            const directive = ROLE_DIRECTIVES[subtask.role];
+            const override = this.opts.directiveOverride;
+            const effectiveDirective = typeof override === 'string' ? override : (override?.directive ?? directive.directive);
+            let effectiveSkills = typeof override === 'object' && override?.skills
+                ? override.skills
+                : (directive.skills ?? []);
+            // Append external skills relevant to this specific role (from
+            // skills/<name>/SKILL.md files) when XCODER_EXTERNAL_SKILLS is on.
+            // getRoutedExternalSkills() internally no-ops for 'conversation' (no
+            // allowlist entry) and returns [] when the flag is off, so this call
+            // is always safe to make unconditionally.
+            if (subtask.role !== "conversation" && isExternalSkillsEnabled()) {
+                effectiveSkills = [...effectiveSkills, ...getRoutedExternalSkills(subtask.role)];
+            }
+            const goal = this.opts.healingHint ? `${subtask.goal}\n\nHEALING HINT: ${this.opts.healingHint}` : subtask.goal;
+            const effectiveSubtask = { ...subtask, goal };
+            const protocolSection = this.opts.protocolOverrides?.[subtask.role];
+            const upstreamCtx = Object.keys(effectiveSubtask.upstreamContext).length
+                ? JSON.stringify(effectiveSubtask.upstreamContext, null, 2)
+                : undefined;
+            const goalText = [
+                `- id: ${effectiveSubtask.id}`,
+                `- stage: ${effectiveSubtask.stage}`,
+                `- goal: ${effectiveSubtask.goal}`,
+                `- what you must deliver back to the Master Orchestrator: ${effectiveSubtask.deliverableSpec}`,
+                `- acceptance criteria (the Validation Gate checks these independently — you`,
+                `  are not the one who decides you passed):`,
+                ...effectiveSubtask.acceptanceCriteria.map((ac) => `  - [${ac.id}] (${ac.type}) ${ac.description}`),
+            ].join("\n");
+            const bylaw = buildBylawContext({
+                stage: effectiveSubtask.stage,
+                role: effectiveSubtask.role,
+                goal: effectiveSubtask.goal,
+            });
+            systemPrompt = buildAgentSystemPrompt({
+                agentName: subtask.role,
+                roleDescription: effectiveDirective,
+                directive: effectiveDirective,
+                skills: effectiveSkills,
+                tools: buildToolManifest({ lessonLearned: this.opts.lessonLearned ?? false }),
+                environment,
+                detectedCommands,
+                goal: goalText,
+                upstreamContext: upstreamCtx,
+                protocolOverride: protocolSection,
+                isStandalone: false,
+                lessonContext: this.opts.lessonContext,
+                bylawContext: bylaw?.text,
+            });
+        }
+        catch (e) {
+            // Setup itself failing (e.g. can't read the workspace at all) is still
+            // not allowed to crash the orchestrator — surface it as a crash result.
+            return this.crashResult(subtask, `failed to prepare subtask: ${e.message}`);
+        }
+        const transcript = [
+            { role: "user", content: "Begin. Respond with your first contract message now." },
+        ];
+        const raoTrace = [];
+        const filesTouched = new Set();
+        const filesTouchedMeta = [];
+        const maxIterations = this.opts.maxIterations ?? 200;
+        const cumulative = { inputTokens: 0, outputTokens: 0 };
+        const dupDetector = new DuplicateActionDetector();
+        const ctx = { taskId, subtaskId: subtask.id };
+        // Fail fast on a deterministic LLM failure (same error N times in a row)
+        // instead of burning every iteration on a call that can never succeed.
+        const MAX_CONSECUTIVE_LLM_ERRORS = 3;
+        let lastLlmError = "";
+        let consecutiveLlmErrors = 0;
+        for (let i = 0; i < maxIterations; i++) {
+            await appendLlm(workspaceRoot, taskId, subtask.id, {
+                direction: "request",
+                content: transcript.at(-1)?.content ?? "",
+            });
+            const spinner = this.term.startThinking(subtask.id);
+            emitXcoderEvent({ type: "agent:thinking-start", taskId, subtaskId: subtask.id });
+            let raw;
+            let completion;
+            try {
+                completion = await this.opts.llm.complete(systemPrompt, transcript);
+                raw = completion.text;
+                cumulative.inputTokens += completion.usage.inputTokens;
+                cumulative.outputTokens += completion.usage.outputTokens;
+                await appendToken(workspaceRoot, taskId, subtask.id, {
+                    inputTokens: completion.usage.inputTokens,
+                    outputTokens: completion.usage.outputTokens,
+                    cumulativeInput: cumulative.inputTokens,
+                    cumulativeOutput: cumulative.outputTokens,
+                });
+                this.term.printTokens(subtask.id, completion.usage, cumulative);
+                emitXcoderEvent({
+                    type: "agent:tokens",
+                    taskId,
+                    subtaskId: subtask.id,
+                    data: { turn: completion.usage, cumulative },
+                });
+                await appendLlm(workspaceRoot, taskId, subtask.id, { direction: "response", content: raw, stopReason: completion.stopReason });
+                consecutiveLlmErrors = 0;
+                lastLlmError = "";
+            }
+            catch (e) {
+                // An LLM API failure (network, rate limit, auth) is exactly the
+                // kind of thing that used to take the whole process down with it.
+                // It's now a recoverable observation: log it, tell the model, let
+                // it try again — still bounded by maxIterations either way.
+                const message = e.message;
+                spinner.fail(`llm_error: ${message}`);
+                emitXcoderEvent({ type: "agent:crash", taskId, subtaskId: subtask.id, data: { message: `llm_error: ${message}`, recoverable: true } });
+                await appendSys(workspaceRoot, taskId, `[${subtask.id}] LLM call failed: ${message}`);
+                await appendThink(workspaceRoot, taskId, subtask.id, `(llm_error) ${message}`);
+                raoTrace.push({ thought: "(llm call failed)", action: null, observation: `llm_error: ${message}` });
+                consecutiveLlmErrors = message === lastLlmError ? consecutiveLlmErrors + 1 : 1;
+                lastLlmError = message;
+                if (consecutiveLlmErrors >= MAX_CONSECUTIVE_LLM_ERRORS) {
+                    return this.crashResult(subtask, `LLM call failed ${consecutiveLlmErrors} times in a row with the same error: ${message}`);
+                }
+                transcript.push({ role: "user", content: `Observation: llm_error: ${message}\nTry again.` });
+                continue;
+            }
+            transcript.push({ role: "assistant", content: raw });
+            const parsed = parseReactMessage(raw);
+            if (!parsed.ok) {
+                spinner.stop("(unparseable response)");
+                this.term.printProtocolError(subtask.id, parsed.error);
+                emitXcoderEvent({ type: "agent:protocol-error", taskId, subtaskId: subtask.id, data: { message: parsed.error } });
+                if (this.opts.protocolErrorLog || isProtocolErrorLoggingEnabled()) {
+                    logProtocolError({
+                        ts: new Date().toISOString(),
+                        taskId,
+                        agentId: subtask.id,
+                        iteration: i,
+                        error: parsed.error,
+                        raw,
+                        model: completion.model ?? "unknown",
+                        stopReason: completion.stopReason,
+                        inputTokens: completion.usage.inputTokens,
+                        outputTokens: completion.usage.outputTokens,
+                    });
+                }
+                const isTruncated = completion.stopReason === 'max_tokens' || completion.stopReason === 'length';
+                const errObservation = isTruncated
+                    ? `protocol_error: response was not valid JSON — your output was truncated because the token limit was reached (stop_reason: ${completion.stopReason}). The JSON was cut off mid-generation. Shorten your response — use fewer tools per turn, be more concise in your thought/action, and avoid including large file contents in your output. Parse error: ${parsed.error}`
+                    : `protocol_error: ${parsed.error}`;
+                await appendThink(workspaceRoot, taskId, subtask.id, `(unparseable) ${errObservation}`);
+                raoTrace.push({ thought: "(unparseable response)", action: null, observation: errObservation });
+                transcript.push({ role: "user", content: `Observation: ${errObservation}\nRe-read the contract and try again.` });
+                continue;
+            }
+            const { thought, action, final_answer } = parsed.message;
+            spinner.stop(thought);
+            emitXcoderEvent({ type: "agent:thought", taskId, subtaskId: subtask.id, data: { thought } });
+            await appendThink(workspaceRoot, taskId, subtask.id, `Thought: ${thought}`);
+            if (final_answer) {
+                this.term.printFinalAnswer(subtask.id, final_answer.summary);
+                emitXcoderEvent({ type: "agent:final", taskId, subtaskId: subtask.id, data: { summary: final_answer.summary } });
+                await appendThink(workspaceRoot, taskId, subtask.id, `final_answer: ${final_answer.summary}`);
+                raoTrace.push({ thought, action: null, observation: "final_answer submitted" });
+                return {
+                    summary: final_answer.summary,
+                    deliverable: final_answer.deliverable,
+                    filesTouched: [...filesTouched, ...final_answer.files_touched],
+                    _filesTouchedMeta: filesTouchedMeta.length > 0 ? [...filesTouchedMeta] : undefined,
+                    selfCheck: final_answer.self_check,
+                    raoTrace,
+                    tokenUsage: cumulative,
+                    iterations: i + 1,
+                };
+            }
+            // Prose-only recovery: parseReactMessage's Layer 4a/4b can return
+            // { action: null, final_answer: null } when the model sends pure
+            // reasoning prose. Treat the thought as an observation and continue.
+            if (!action) {
+                const obs = `prose_recovery: no action or final_answer in response — model sent reasoning prose only. Thought: ${thought}`;
+                spinner.stop(`(prose-only: ${thought.slice(0, 80)}...)`);
+                emitXcoderEvent({ type: "agent:observation", taskId, subtaskId: subtask.id, data: { ok: true, tool: "prose_recovery", observation: obs } });
+                await appendThink(workspaceRoot, taskId, subtask.id, `Observation: ${obs}`);
+                raoTrace.push({ thought, action: null, observation: obs });
+                transcript.push({ role: "user", content: `Observation: ${obs}\nYou must respond with either an action or a final_answer.` });
+                continue;
+            }
+            const { tool, input } = action;
+            this.term.printAction(subtask.id, tool, input);
+            emitXcoderEvent({ type: "agent:action", taskId, subtaskId: subtask.id, data: { tool, input } });
+            await appendThink(workspaceRoot, taskId, subtask.id, `Action: ${tool} ${JSON.stringify(input)}`);
+            const dup = dupDetector.check(thought, tool, input, i + 1);
+            if (dup.isDuplicate) {
+                this.term.printDuplicateWarning(subtask.id, dup.warning);
+                emitXcoderEvent({ type: "agent:duplicate", taskId, subtaskId: subtask.id, data: { tool, priorIterations: dup.priorIterations, stuck: dup.stuck } });
+                await appendThink(workspaceRoot, taskId, subtask.id, `(duplicate) ${dup.warning}`);
+            }
+            if (dup.stuck) {
+                const message = `stuck in a repeated action loop: ${dupDetector.duplicateCount} duplicate actions detected — aborted after ${i + 1} iterations instead of running to the full ${maxIterations}-iteration cap.`;
+                await appendSys(workspaceRoot, taskId, `[${subtask.id}] ${message}`);
+                // Programmatic lesson recording (orchestrator-driven): when a Sub
+                // Agent gets stuck, record the pattern so the next run benefits.
+                if (this.opts.lessonLearned) {
+                    recordLesson(workspaceRoot, {
+                        source: `sub-agent:${subtask.role}`,
+                        taskId,
+                        tags: ["stuck-loop", subtask.role, subtask.stage],
+                        context: `Agent got stuck in a repeated action loop after ${i + 1} iterations. The duplicate detector flagged ${dupDetector.duplicateCount} duplicate actions.`,
+                        lesson: `When a Sub Agent gets stuck in a loop: check the observation text for actionable hints, reduce the max iterations, and consider re-planning with a clearer directive. The agent was ${subtask.role} running stage ${subtask.stage}.`,
+                    }).catch(() => {
+                        // Swallow — lesson recording is best-effort.
+                    });
+                }
+                return {
+                    summary: message,
+                    deliverable: null,
+                    filesTouched: [...filesTouched],
+                    _filesTouchedMeta: filesTouchedMeta.length > 0 ? [...filesTouchedMeta] : undefined,
+                    raoTrace,
+                    tokenUsage: cumulative,
+                    iterations: i + 1,
+                    stuckLoop: true,
+                };
+            }
+            let result;
+            try {
+                result = await dispatchTool(workspaceRoot, tool, input, ctx);
+            }
+            catch (e) {
+                // dispatchTool already catches internally — this is a second net in
+                // case a future tool addition forgets to. Never let a tool crash
+                // the loop.
+                const message = e.message;
+                await appendSys(workspaceRoot, taskId, `[${subtask.id}] tool "${tool}" threw unexpectedly: ${message}`);
+                result = { tool, ok: false, output: { error: `unexpected tool failure: ${message}` } };
+            }
+            // log tool errors when --debug-tools is active
+            if (!result.ok && isToolErrorLoggingEnabled()) {
+                logToolError({
+                    ts: new Date().toISOString(),
+                    tool,
+                    error: result.output?.error ?? "unknown",
+                    ok: false,
+                    taskId,
+                    subtaskId: subtask.id,
+                    input: JSON.stringify(input),
+                    iteration: i + 1,
+                });
+            }
+            if (tool === "write_file" && result.ok) {
+                const out = result.output;
+                filesTouched.add(out.relPath);
+                filesTouchedMeta.push({ path: out.relPath, operation: "created" });
+            }
+            if (tool === "edit_file" && result.ok) {
+                const out = result.output;
+                filesTouched.add(out.relPath);
+                filesTouchedMeta.push({ path: out.relPath, operation: "modified" });
+            }
+            if (tool === "sed_tool" && result.ok) {
+                const out = result.output;
+                if (out.results) {
+                    for (const r of out.results) {
+                        if (r.matched) {
+                            filesTouched.add(r.relPath);
+                            filesTouchedMeta.push({ path: r.relPath, operation: "modified" });
+                        }
+                    }
+                }
+            }
+            let observation = JSON.stringify(result.output).slice(0, 4000); // keep the transcript bounded
+            if (dup.isDuplicate)
+                observation = `[DUPLICATE — see warning above] ${observation}`;
+            this.term.printObservation(subtask.id, result.ok, observation);
+            emitXcoderEvent({ type: "agent:observation", taskId, subtaskId: subtask.id, data: { ok: result.ok, tool, observation } });
+            await appendThink(workspaceRoot, taskId, subtask.id, `Observation: ${observation}`);
+            raoTrace.push({ thought, action: { tool, input }, observation });
+            transcript.push({
+                role: "user",
+                content: dup.warning ? `Observation: ${observation}\n\n${dup.warning}` : `Observation: ${observation}`,
+            });
+        }
+        await appendSys(workspaceRoot, taskId, `[${subtask.id}] exhausted ${maxIterations} iterations without a final_answer`);
+        return {
+            summary: `did not reach a final_answer within ${maxIterations} iterations`,
+            deliverable: null,
+            filesTouched: [...filesTouched],
+            _filesTouchedMeta: filesTouchedMeta.length > 0 ? [...filesTouchedMeta] : undefined,
+            raoTrace,
+            tokenUsage: cumulative,
+            iterations: maxIterations,
+            iterationsExhausted: true,
+        };
+    }
+    async crashResult(subtask, message) {
+        await appendSys(this.opts.workspaceRoot, this.opts.taskId, `[${subtask.id}] ${message}`);
+        this.term.printCrash(subtask.id, message);
+        emitXcoderEvent({ type: "agent:crash", taskId: this.opts.taskId, subtaskId: subtask.id, data: { message, recoverable: false } });
+        return {
+            summary: message,
+            deliverable: null,
+            filesTouched: [],
+            raoTrace: [],
+            tokenUsage: { inputTokens: 0, outputTokens: 0 },
+            iterations: 0,
+            crashed: true,
+        };
+    }
+}

package/dist/backlog/backlog-requirement-validator.d.ts

@@ -0,0 +1,10 @@
+export interface BacklogRequirementCheck {
+    passed: boolean;
+    detail: string;
+    foundFiles: string[];
+}
+/**
+ * Checks whether any requirement markdown files exist under .xcoder/backlog/.
+ * Pure filesystem check — no LLM involvement, no backlog JSON parsing needed.
+ */
+export declare function validateBacklogHasRequirements(workspaceRoot: string): Promise<BacklogRequirementCheck>;

package/dist/backlog/backlog-requirement-validator.js

@@ -0,0 +1,60 @@
+// xcoder:version 1 | xcoder:task task-12fb57 | xcoder:updated 2026-08-04T12:24:23.969Z | xcoder:subtask code-st-33c7d1
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { createXcoderPaths } from "../util/xcoder-paths.js";
+/**
+ * Checks whether any requirement markdown files exist under .xcoder/backlog/.
+ * Pure filesystem check — no LLM involvement, no backlog JSON parsing needed.
+ */
+export async function validateBacklogHasRequirements(workspaceRoot) {
+    const paths = createXcoderPaths(workspaceRoot);
+    const backlogDir = paths.backlogDir();
+    let entries;
+    try {
+        entries = await fs.readdir(backlogDir);
+    }
+    catch {
+        return {
+            passed: false,
+            detail: `Backlog directory not found: ${backlogDir}`,
+            foundFiles: [],
+        };
+    }
+    if (entries.length === 0) {
+        return {
+            passed: false,
+            detail: `Backlog directory is empty: ${backlogDir}`,
+            foundFiles: [],
+        };
+    }
+    const re = /requirements/i;
+    const matches = [];
+    for (const entry of entries) {
+        if (entry.endsWith(".md") && re.test(entry)) {
+            try {
+                const full = path.join(backlogDir, entry);
+                const stat = await fs.stat(full);
+                if (stat.isFile()) {
+                    matches.push(full);
+                }
+            }
+            catch {
+                // skip unreadable entries
+            }
+        }
+    }
+    if (matches.length > 0) {
+        // Use .xcoder relative path in detail message
+        const xcoderBacklog = path.relative(workspaceRoot, backlogDir);
+        return {
+            passed: true,
+            detail: `Found ${matches.length} requirement file(s) in ${xcoderBacklog}/: ${path.basename(matches[0])}`,
+            foundFiles: matches,
+        };
+    }
+    return {
+        passed: false,
+        detail: `No requirement markdown files found in ${backlogDir}`,
+        foundFiles: [],
+    };
+}

package/dist/backlog/backlog-store.d.ts

@@ -0,0 +1,29 @@
+import type { BacklogFile, BacklogItem, BacklogStatus } from "./types.js";
+/**
+ * Loads `.xcoder/backlog/_backlog.json`. Creates the directory and
+ * initializes with an empty file if it doesn't exist (idempotent).
+ */
+export declare function loadBacklog(root: string): Promise<BacklogFile>;
+/**
+ * Atomic write: tmp file → rename. Follows the task-store.ts pattern.
+ */
+export declare function saveBacklog(root: string, data: BacklogFile): Promise<void>;
+/**
+ * Add a new backlog item with status "open", assign the next sequential
+ * id (BL-001, BL-002, …), increment nextId, save, and return the item.
+ */
+export declare function addBacklogItem(root: string, title: string, description?: string, priority?: string): Promise<BacklogItem>;
+/**
+ * PATCH an existing item by id. Merges allowed fields, refreshes
+ * updatedAt. Returns the updated item or null if not found.
+ */
+export declare function updateBacklogItem(root: string, id: string, patch: Partial<Pick<BacklogItem, "status" | "taskId" | "description" | "priority" | "sprintId" | "blockedReason" | "sprintRunAt">>): Promise<BacklogItem | null>;
+/**
+ * Look up a single item by id. Returns null if not found.
+ */
+export declare function getBacklogItem(root: string, id: string): Promise<BacklogItem | null>;
+/**
+ * List items, optionally filtered by status. Sorted by createdAt
+ * ascending (oldest first).
+ */
+export declare function listBacklogItems(root: string, statusFilter?: BacklogStatus): Promise<BacklogItem[]>;

package/dist/backlog/backlog-store.js

@@ -0,0 +1,148 @@
+// xcoder:version 5 | xcoder:task task-12fb57 | xcoder:updated 2026-08-04T12:26:19.567Z | xcoder:subtask code-st-33c7d1
+import { promises as fs } from "node:fs";
+import { createXcoderPaths } from "../util/xcoder-paths.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function pad(num, size = 3) {
+    return String(num).padStart(size, "0");
+}
+/**
+ * Normalize a raw item from disk into a fully-typed BacklogItem.
+ * Supplies defaults for fields that may be absent in older _backlog.json
+ * files (backward-compatibility).
+ */
+function normalizeItem(raw) {
+    return {
+        id: String(raw.id ?? ""),
+        title: String(raw.title ?? ""),
+        description: String(raw.description ?? ""),
+        status: raw.status ?? "open",
+        priority: typeof raw.priority === "string" ? raw.priority : undefined,
+        taskId: typeof raw.taskId === "string" ? raw.taskId : undefined,
+        sprintId: typeof raw.sprintId === "string" ? raw.sprintId : null,
+        blockedReason: typeof raw.blockedReason === "string" ? raw.blockedReason : null,
+        sprintRunAt: typeof raw.sprintRunAt === "string" ? raw.sprintRunAt : null,
+        createdAt: String(raw.createdAt ?? new Date().toISOString()),
+        updatedAt: String(raw.updatedAt ?? new Date().toISOString()),
+    };
+}
+// ---------------------------------------------------------------------------
+// Core load / save (atomic)
+// ---------------------------------------------------------------------------
+/**
+ * Loads `.xcoder/backlog/_backlog.json`. Creates the directory and
+ * initializes with an empty file if it doesn't exist (idempotent).
+ */
+export async function loadBacklog(root) {
+    const paths = createXcoderPaths(root);
+    const file = paths.backlogFile();
+    try {
+        const raw = await fs.readFile(file, "utf-8");
+        const parsed = JSON.parse(raw);
+        // Basic structural validation.
+        if (parsed &&
+            typeof parsed === "object" &&
+            !Array.isArray(parsed) &&
+            Array.isArray(parsed.items) &&
+            parsed.meta &&
+            typeof parsed.meta === "object" &&
+            typeof parsed.meta.nextId === "number") {
+            return { meta: parsed.meta, items: parsed.items.map(normalizeItem) };
+        }
+    }
+    catch {
+        // File doesn't exist or is malformed — bootstrap below.
+    }
+    // Bootstrap: create dir + empty backlog.
+    const fresh = { meta: { nextId: 1 }, items: [] };
+    try {
+        await fs.mkdir(paths.backlogDir(), { recursive: true });
+        const tmp = `${file}.tmp`;
+        await fs.writeFile(tmp, JSON.stringify(fresh, null, 2), "utf8");
+        await fs.rename(tmp, file);
+    }
+    catch {
+        // If the dir already exists and we can't write, the save* functions will
+        // fail with a clearer error later.
+    }
+    return fresh;
+}
+/**
+ * Atomic write: tmp file → rename. Follows the task-store.ts pattern.
+ */
+export async function saveBacklog(root, data) {
+    const paths = createXcoderPaths(root);
+    const file = paths.backlogFile();
+    await fs.mkdir(paths.backlogDir(), { recursive: true });
+    const tmp = `${file}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify(data, null, 2), "utf8");
+    await fs.rename(tmp, file);
+}
+// ---------------------------------------------------------------------------
+// CRUD operations
+// ---------------------------------------------------------------------------
+/**
+ * Add a new backlog item with status "open", assign the next sequential
+ * id (BL-001, BL-002, …), increment nextId, save, and return the item.
+ */
+export async function addBacklogItem(root, title, description, priority) {
+    const data = await loadBacklog(root);
+    const id = `BL-${pad(data.meta.nextId)}`;
+    const now = new Date().toISOString();
+    const item = {
+        id,
+        title,
+        description: description ?? "",
+        status: "open",
+        priority,
+        sprintId: null,
+        blockedReason: null,
+        sprintRunAt: null,
+        createdAt: now,
+        updatedAt: now,
+    };
+    data.items.push(item);
+    data.meta.nextId += 1;
+    await saveBacklog(root, data);
+    return item;
+}
+/**
+ * PATCH an existing item by id. Merges allowed fields, refreshes
+ * updatedAt. Returns the updated item or null if not found.
+ */
+export async function updateBacklogItem(root, id, patch) {
+    const data = await loadBacklog(root);
+    const idx = data.items.findIndex((it) => it.id === id);
+    if (idx === -1)
+        return null;
+    const existing = data.items[idx];
+    const updated = {
+        ...existing,
+        ...patch,
+        updatedAt: new Date().toISOString(),
+    };
+    data.items[idx] = updated;
+    await saveBacklog(root, data);
+    return updated;
+}
+/**
+ * Look up a single item by id. Returns null if not found.
+ */
+export async function getBacklogItem(root, id) {
+    const data = await loadBacklog(root);
+    return data.items.find((it) => it.id === id) ?? null;
+}
+/**
+ * List items, optionally filtered by status. Sorted by createdAt
+ * ascending (oldest first).
+ */
+export async function listBacklogItems(root, statusFilter) {
+    const data = await loadBacklog(root);
+    let items = data.items;
+    if (statusFilter) {
+        items = items.filter((it) => it.status === statusFilter);
+    }
+    // Sort by createdAt ascending.
+    return items.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}

package/dist/backlog/po-agent.d.ts

@@ -0,0 +1,16 @@
+import type { BacklogItem } from "./types.js";
+export interface PoPickResult {
+    selectedId: string;
+    title: string;
+    reasoning: string;
+}
+/**
+ * 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 declare function runPoPick(root: string, items: BacklogItem[], model?: string): Promise<PoPickResult>;