xcoder-dna 0.0.0-stage → 1.3.1

package/dist/util/terminal.js

@@ -0,0 +1,124 @@
+// xcoder:version 4 | xcoder:task task-4f2baf | xcoder:updated 2026-08-05T05:48:55.314Z | xcoder:subtask code-st-11b531
+import * as clack from "@clack/prompts";
+import { createSpinner } from "./spinner.js";
+import { FooterManager } from "./footer-manager.js";
+const C = {
+    reset: "\x1b[0m",
+    dim: "\x1b[2m",
+    bold: "\x1b[1m",
+    amber: "\x1b[38;5;214m",
+    cyan: "\x1b[38;5;80m",
+    green: "\x1b[38;5;78m",
+    coral: "\x1b[38;5;203m",
+    violet: "\x1b[38;5;140m",
+};
+function useColor() {
+    return process.stdout.isTTY === true && process.env.NO_COLOR === undefined;
+}
+function paint(code, text) {
+    return useColor() ? `${code}${text}${C.reset}` : text;
+}
+/**
+ * One spinner per Sub Agent turn — "thinking" while the LLM call is in
+ * flight. This is the piece that makes a long silent wait (previously
+ * indistinguishable from a hang, which is part of what made a crash look
+ * like nothing was happening) visibly alive. Backend/style is selectable
+ * via `--spinner` — see `util/spinner.ts`.
+ */
+export function startThinking(agentId) {
+    const s = createSpinner(paint(C.dim, `[${agentId}] thinking…`));
+    FooterManager.instance()?.updateThinkingStart(agentId);
+    return {
+        stop: (thought) => {
+            const preview = thought.length > 100 ? thought.slice(0, 97) + "..." : thought;
+            s.stop(`${paint(C.violet, `[${agentId}] Thought`)} ${preview}`);
+            FooterManager.instance()?.updateThinkingStop();
+        },
+        fail: (message) => {
+            s.fail(paint(C.coral, `[${agentId}] ${message}`));
+            FooterManager.instance()?.updateThinkingStop();
+        },
+    };
+}
+export function printAction(agentId, tool, input) {
+    const inputPreview = JSON.stringify(input);
+    const truncated = inputPreview && inputPreview.length > 160 ? inputPreview.slice(0, 157) + "..." : inputPreview;
+    clack.log.info(`${paint(C.amber, `[${agentId}] Action`)} ${paint(C.bold, tool)} ${paint(C.dim, truncated ?? "")}`);
+    FooterManager.instance()?.updateAction(tool);
+}
+export function printObservation(agentId, ok, text) {
+    const preview = text.length > 220 ? text.slice(0, 217) + "..." : text;
+    const label = ok ? paint(C.green, `[${agentId}] Observation ✓`) : paint(C.coral, `[${agentId}] Observation ✗`);
+    (ok ? clack.log.success : clack.log.error)(`${label} ${preview}`);
+    FooterManager.instance()?.updateObservation(ok, text);
+}
+export function printTokens(agentId, turn, cumulative) {
+    clack.log.message(paint(C.dim, `  ↳ tokens: +${turn.inputTokens} in / +${turn.outputTokens} out` +
+        `  (task total: ${cumulative.inputTokens} in / ${cumulative.outputTokens} out)`));
+    FooterManager.instance()?.updateTokens(cumulative.inputTokens, cumulative.outputTokens);
+}
+export function printProtocolError(agentId, message) {
+    clack.log.warn(paint(C.coral, `[${agentId}] protocol_error: ${message}`));
+}
+export function printDuplicateWarning(agentId, message) {
+    clack.log.warn(paint(C.amber, `[${agentId}] ⟲ ${message}`));
+}
+export function printCrash(agentId, message) {
+    clack.log.error(paint(C.coral, `[${agentId}] CRASHED (isolated — orchestrator continues): ${message}`));
+}
+export function printFinalAnswer(agentId, summary) {
+    clack.log.success(paint(C.green, `[${agentId}] final_answer`) + ` ${summary}`);
+}
+export function taskIntro(taskId, goal) {
+    clack.intro(paint(C.bold, `xcoder · ${taskId}`));
+    clack.log.step(goal);
+}
+export function taskOutro(status) {
+    const color = status === "done" ? C.green : status === "escalated" ? C.coral : C.amber;
+    clack.outro(paint(color, `run finished: ${status}`));
+}
+export function orchestratorNote(message) {
+    clack.log.step(paint(C.amber, "[orchestrator] ") + message);
+}
+/**
+ * Printed exactly once per interrupt, after state is flushed to disk.
+ * Shows task ID, done/total count, exact --resume command, and file path.
+ */
+export function printInterruptSummary(summary) {
+    clack.log.message(paint(C.bold, `\nInterrupted — progress saved.`) +
+        `\n  Task:         ${summary.taskId}` +
+        `\n  Done:         ${summary.doneCount}/${summary.totalCount} subtasks` +
+        `\n  Resume with:  ${paint(C.cyan, summary.resumeCommand)}` +
+        `\n  Task file:    ${paint(C.dim, summary.taskFilePath)}`);
+}
+/**
+ * Print a color-coded summary of an Instance Swarm run.
+ * Uses the same palette as the rest of the terminal module:
+ * - green for completed workers
+ * - coral for crashed/failed workers
+ * - amber for the swarm-level status line
+ * - dim for metadata (tokens, output dir)
+ */
+export function printSwarmSummary(result) {
+    const statusColor = result.status === "completed" ? C.green : result.status === "timeout" ? C.amber : C.coral;
+    const statusIcon = result.status === "completed" ? "✓" : result.status === "timeout" ? "⏱" : "✗";
+    clack.log.message(paint(C.bold, `\nSwarm finished`) +
+        `  ${paint(statusColor, `${statusIcon} ${result.status}`)}`);
+    clack.log.message(`  ${paint(C.cyan, "instanceId:")} ${paint(C.dim, result.instanceId)}`);
+    const workerLine = `  ${paint(C.cyan, "workers:")} ` +
+        `${paint(C.green, String(result.workerCount - result.crashedCount))} completed`;
+    if (result.crashedCount > 0) {
+        clack.log.message(workerLine + `, ${paint(C.coral, String(result.crashedCount))} crashed`);
+    }
+    else {
+        clack.log.message(workerLine);
+    }
+    clack.log.message(`  ${paint(C.cyan, "tokens:")} ${paint(C.dim, `${result.totalInputTokens} in / ${result.totalOutputTokens} out`)}`);
+    clack.log.message(`  ${paint(C.cyan, "outputDir:")} ${paint(C.dim, result.outputDir)}`);
+    if (result.errors.length > 0) {
+        clack.log.message(paint(C.bold, `\n  Errors:`));
+        for (const err of result.errors) {
+            clack.log.error(paint(C.coral, `    ✗ ${err}`));
+        }
+    }
+}

package/dist/util/text-sanitize.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Strip terminal control sequences and invisible characters, collapse CR/LF
+ * to a single space, and truncate to `maxLen` (default 60 — the column width
+ * `statusList` already uses).
+ *
+ * Never used on data that is persisted; call it on the way to `log.raw`.
+ */
+export declare function sanitizeForTerminal(input: string, maxLen?: number): string;

package/dist/util/text-sanitize.js

@@ -0,0 +1,45 @@
+// xcoder:version 1 | xcoder:task task-a91099 | xcoder:updated 2026-10-23T10:52:28.927Z | xcoder:subtask code-st-03748c
+// Terminal render-time neutralization.
+//
+// Task goals and provenance paths are attacker-influenced data: a markdown/WBS
+// source a user ingests can contain ANSI escape sequences, OSC hyperlink
+// payloads, zero-width characters or bidi overrides. Anything printed straight
+// from such a record to a terminal can repaint the screen, forge log lines, or
+// misrepresent what was written. This module neutralizes those characters at
+// the point of display ONLY — the stored JSON keeps the verbatim text.
+const CSI_AND_OSC = new RegExp([
+    // CSI: ESC [ ... final byte (@-~)
+    "\\u001b\\[[0-?]*[ -/]*[@-~]",
+    // OSC: ESC ] ... terminated by BEL or ST
+    "\\u001b\\][^\\u0007\\u001b]*(?:\\u0007|\\u001b\\\\)",
+    // Any other ESC-introduced two/three byte sequence
+    "\\u001b[@-Z\\\\-_]",
+    // 8-bit CSI (C1)
+    "\\u009b[0-?]*[ -/]*[@-~]",
+    // 8-bit OSC (C1)
+    "\\u009d[^\\u0007\\u009c]*(?:\\u0007|\\u009c)",
+].join("|"), "g");
+const C0_C1_CONTROLS = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g;
+const ZERO_WIDTH = /[\u200b-\u200d\ufeff]/g;
+const BIDI = /[\u202a-\u202e\u2066-\u2069]/g;
+/**
+ * Strip terminal control sequences and invisible characters, collapse CR/LF
+ * to a single space, and truncate to `maxLen` (default 60 — the column width
+ * `statusList` already uses).
+ *
+ * Never used on data that is persisted; call it on the way to `log.raw`.
+ */
+export function sanitizeForTerminal(input, maxLen = 60) {
+    if (typeof input !== "string")
+        return "";
+    let out = input.replace(CSI_AND_OSC, "");
+    out = out.replace(C0_C1_CONTROLS, "");
+    out = out.replace(ZERO_WIDTH, "");
+    out = out.replace(BIDI, "");
+    // Tabs are permitted in the control strip above; flatten all line breaks.
+    out = out.replace(/[\r\n]+/g, " ").replace(/\t/g, " ");
+    out = out.replace(/\s{2,}/g, " ").trim();
+    if (maxLen >= 0 && out.length > maxLen)
+        out = out.slice(0, maxLen);
+    return out;
+}

package/dist/util/thinking-spinner.d.ts

@@ -0,0 +1,27 @@
+export interface ThinkingHandle {
+    /** Stop the spinner and replace it with a success message (erases the spinner line). */
+    stop(message: string): void;
+    /** Stop the spinner and replace it with a failure message (erases the spinner line). */
+    fail(message: string): void;
+    /** Pause the spinner animation and clear its line so other log output can
+     *  be printed without mangling. Call resume() to restart. */
+    pause(): void;
+    /** Resume the spinner animation after a pause(). */
+    resume(): void;
+}
+/**
+ * Start a colorful animated thinking spinner on stdout.
+ *
+ * When stdout is a TTY and NO_COLOR is not set:
+ *   - Renders a rotating glyph (Unicode Braille or ASCII fallback on cp1252
+ *     terminals) with a color-cycling label on a single line.
+ *   - Updates every ~100ms via setInterval (non-blocking to the event loop).
+ *   - Hides the cursor while active.
+ *
+ * When stdout is NOT a TTY or NO_COLOR is set:
+ *   - Emits one static "Thinking…" line, then appends a dot every ~2s.
+ *   - No ANSI codes, no animation, no cursor control.
+ *
+ * @param label - A short identifier shown next to the spinner (e.g. "samurai").
+ */
+export declare function startThinking(label: string): ThinkingHandle;

package/dist/util/thinking-spinner.js

@@ -0,0 +1,189 @@
+// ── Colorful animated thinking spinner for the samurai agent (and eventually beyond). ──
+//
+// When stdout is a TTY and NO_COLOR is not set:
+//   - Color-cycling label + rotating glyph (Unicode Braille, ASCII fallback on
+//     non-UTF-8 Windows consoles).
+//   - Updates every ~100ms via setInterval (non-blocking).
+//   - Hides/shows the cursor around the animation.
+//   - Supports pause() / resume() so interleaved log messages don't mangle
+//     the spinner line.
+//
+// When stdout is NOT a TTY or NO_COLOR is set:
+//   - Emits one static "Thinking…" line, then appends dots periodically.
+//   - No ANSI, no animation, no cursor control.
+// ── Internal constants ──
+const COLOR_PALETTE = [
+    "\x1b[38;5;78m", // green
+    "\x1b[38;5;80m", // cyan
+    "\x1b[38;5;141m", // magenta
+    "\x1b[38;5;220m", // yellow
+];
+const COLOR_RESET = "\x1b[0m";
+// Unicode Braille spinner (works on Windows Terminal, WSL, macOS, most Linux)
+const BRAILLE_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+// ASCII fallback for legacy Windows console (cp1252, cmd.exe without modern Terminal)
+const ASCII_FRAMES = ["|", "/", "-", "\\"];
+// ── Platform detection ──
+function isInteractive() {
+    return process.stdout.isTTY === true && process.env.NO_COLOR === undefined;
+}
+function shouldUseAscii() {
+    // On Windows, check if the console encoding supports Unicode.
+    // process.stdout.encoding is the most reliable signal (added in Node 20+).
+    if (process.platform === "win32") {
+        const enc = process.stdout.encoding;
+        // encoding is typically "utf8" on modern terminals (Windows Terminal, VSCode, etc.)
+        // and "buffer" or absent on legacy cmd.exe.
+        if (enc !== "utf8" && enc !== "utf-8") {
+            // Additional check: WT_SESSION indicates Windows Terminal, which handles Braille fine.
+            if (!process.env.WT_SESSION && !process.env.TERMINAL_EMULATOR) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function getFrames() {
+    return shouldUseAscii() ? ASCII_FRAMES : BRAILLE_FRAMES;
+}
+// ── ANSI helpers ──
+const HIDE_CURSOR = "\x1b[?25l";
+const SHOW_CURSOR = "\x1b[?25h";
+const CLEAR_LINE = "\x1b[2K";
+const CARRIAGE_RETURN = "\r";
+function writeToStdout(text) {
+    process.stdout.write(text);
+}
+// ── Implementation ──
+/**
+ * Start a colorful animated thinking spinner on stdout.
+ *
+ * When stdout is a TTY and NO_COLOR is not set:
+ *   - Renders a rotating glyph (Unicode Braille or ASCII fallback on cp1252
+ *     terminals) with a color-cycling label on a single line.
+ *   - Updates every ~100ms via setInterval (non-blocking to the event loop).
+ *   - Hides the cursor while active.
+ *
+ * When stdout is NOT a TTY or NO_COLOR is set:
+ *   - Emits one static "Thinking…" line, then appends a dot every ~2s.
+ *   - No ANSI codes, no animation, no cursor control.
+ *
+ * @param label - A short identifier shown next to the spinner (e.g. "samurai").
+ */
+export function startThinking(label) {
+    const interactive = isInteractive();
+    if (!interactive) {
+        return createStaticSpinner(label);
+    }
+    return createAnimatedSpinner(label);
+}
+// ── Non-interactive (static) spinner ──
+function createStaticSpinner(label) {
+    let stopped = false;
+    let dots = 0;
+    let interval = null;
+    writeToStdout(`Thinking… [${label}]`);
+    interval = setInterval(() => {
+        if (stopped)
+            return;
+        dots = (dots + 1) % 4;
+        writeToStdout(".");
+    }, 2000);
+    function cleanup(finalMessage) {
+        if (stopped)
+            return;
+        stopped = true;
+        if (interval !== null) {
+            clearInterval(interval);
+            interval = null;
+        }
+        writeToStdout(`\n${finalMessage}\n`);
+    }
+    return {
+        stop(message) {
+            cleanup(message);
+        },
+        fail(message) {
+            cleanup(`✗ ${message}`);
+        },
+        pause() {
+            // No-op in static mode — dots are harmless and interleaved logs
+            // won't mangle because we append dots in-place without carriage-return.
+        },
+        resume() {
+            // No-op.
+        },
+    };
+}
+// ── Animated (TTY) spinner ──
+function createAnimatedSpinner(label) {
+    let tick = 0;
+    let stopped = false;
+    let paused = false;
+    let interval = null;
+    const frames = getFrames();
+    // Hide cursor
+    writeToStdout(HIDE_CURSOR);
+    function render() {
+        if (stopped || paused)
+            return;
+        const colorCode = COLOR_PALETTE[tick % COLOR_PALETTE.length];
+        const glyph = frames[tick % frames.length];
+        // Format: <CR><clear-line><color><glyph> <label> thinking…<reset>
+        writeToStdout(`${CARRIAGE_RETURN}${CLEAR_LINE}${colorCode}${glyph} ${label} thinking…${COLOR_RESET}`);
+    }
+    // First frame immediately
+    render();
+    tick++;
+    interval = setInterval(() => {
+        render();
+        tick++;
+    }, 100);
+    function eraseLine() {
+        writeToStdout(`${CARRIAGE_RETURN}${CLEAR_LINE}`);
+    }
+    function cleanup(finalMessage) {
+        if (stopped)
+            return;
+        stopped = true;
+        if (interval !== null) {
+            clearInterval(interval);
+            interval = null;
+        }
+        eraseLine();
+        writeToStdout(`${finalMessage}\n`);
+        // Show cursor
+        writeToStdout(SHOW_CURSOR);
+    }
+    return {
+        stop(message) {
+            cleanup(`✓ ${message}`);
+        },
+        fail(message) {
+            cleanup(`✗ ${message}`);
+        },
+        pause() {
+            if (stopped || paused)
+                return;
+            paused = true;
+            if (interval !== null) {
+                clearInterval(interval);
+                interval = null;
+            }
+            eraseLine();
+            writeToStdout(SHOW_CURSOR);
+        },
+        resume() {
+            if (stopped || !paused)
+                return;
+            paused = false;
+            writeToStdout(HIDE_CURSOR);
+            render();
+            tick++;
+            interval = setInterval(() => {
+                render();
+                tick++;
+            }, 100);
+        },
+    };
+}

package/dist/util/tool-error-logger.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Called once at startup by the CLI preAction hook when --debug-tools
+ * or DEBUG_TOOLS is active. Sets module-level enabled flag. If customPath
+ * is provided, uses it; otherwise defaults to <cwd>/tools.log.
+ */
+export declare function enableToolErrorLogging(customPath?: string, opts?: {
+    silent?: boolean;
+}): void;
+/** Read-only guard so call sites can skip data collection when disabled. */
+export declare function isToolErrorLoggingEnabled(): boolean;
+/** The data contract for each ndjson line. */
+export interface ToolErrorLogEntry {
+    ts: string;
+    tool: string;
+    error: string;
+    ok: false;
+    taskId?: string;
+    subtaskId?: string;
+    input?: string;
+    iteration?: number;
+}
+/**
+ * Appends one ndjson line to the log file. Never throws — all write
+ * failures are silently swallowed. Uses an internal promise-chain mutex to
+ * serialise appends without blocking the caller.
+ *
+ * On the FIRST call, writes a `#`-prefixed header block if the file
+ * doesn't already exist (checked via synchronous existsSync — cheap,
+ * and only happens on the first error which is rare).
+ *
+ * Truncates entry.input to MAX_INPUT_LENGTH + "...[truncated]" suffix.
+ */
+export declare function logToolError(entry: ToolErrorLogEntry): void;

package/dist/util/tool-error-logger.js

@@ -0,0 +1,77 @@
+// xcoder:version 1 | xcoder:task task-54c54e | xcoder:updated 2026-08-04T15:30:04.218Z | xcoder:subtask code-st-43fc58
+import fs from "node:fs";
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { log } from "./logger.js";
+// ── Module-level state ──
+let enabled = false;
+let logPath = null;
+/** Serialises writes so parallel agents don't interleave lines. */
+let writeChain = Promise.resolve();
+let headerWritten = false;
+// ── Public API ──
+/**
+ * Called once at startup by the CLI preAction hook when --debug-tools
+ * or DEBUG_TOOLS is active. Sets module-level enabled flag. If customPath
+ * is provided, uses it; otherwise defaults to <cwd>/tools.log.
+ */
+export function enableToolErrorLogging(customPath, opts) {
+    enabled = true;
+    logPath = customPath
+        ? path.resolve(customPath)
+        : path.join(process.cwd(), "tools.log");
+    if (!opts?.silent) {
+        log.dim(`tool_error diagnostic log: ${logPath}`);
+    }
+}
+/** Read-only guard so call sites can skip data collection when disabled. */
+export function isToolErrorLoggingEnabled() {
+    return enabled;
+}
+/** Maximum length of input before truncation. */
+const MAX_INPUT_LENGTH = 2000;
+/**
+ * Appends one ndjson line to the log file. Never throws — all write
+ * failures are silently swallowed. Uses an internal promise-chain mutex to
+ * serialise appends without blocking the caller.
+ *
+ * On the FIRST call, writes a `#`-prefixed header block if the file
+ * doesn't already exist (checked via synchronous existsSync — cheap,
+ * and only happens on the first error which is rare).
+ *
+ * Truncates entry.input to MAX_INPUT_LENGTH + "...[truncated]" suffix.
+ */
+export function logToolError(entry) {
+    if (!enabled || !logPath)
+        return;
+    writeChain = writeChain.then(async () => {
+        try {
+            // Write header once, before the first entry.
+            if (!headerWritten) {
+                const fileExists = fs.existsSync(logPath);
+                if (!fileExists) {
+                    const header = [
+                        "# Xcoder SDLC tool_error diagnostic log",
+                        `# Created: ${new Date().toISOString()}`,
+                        "# Fields: ts, tool, error, ok, taskId, subtaskId, input, iteration",
+                        "# Enabled by: --debug-tools flag | DEBUG_TOOLS env var",
+                        "# Only tool errors (ok=false) are logged — successful calls are omitted.",
+                        "",
+                    ].join("\n");
+                    await fsp.appendFile(logPath, header, "utf-8");
+                }
+                headerWritten = true;
+            }
+            // Truncate input if necessary
+            const entryToWrite = { ...entry };
+            if (entryToWrite.input && entryToWrite.input.length > MAX_INPUT_LENGTH) {
+                entryToWrite.input = entryToWrite.input.slice(0, MAX_INPUT_LENGTH) + "...[truncated]";
+            }
+            const line = JSON.stringify(entryToWrite) + "\n";
+            await fsp.appendFile(logPath, line, "utf-8");
+        }
+        catch {
+            // Silently swallow — diagnostic logging must never break the agent loop.
+        }
+    });
+}

package/dist/util/tty.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Centralized TTY detection for interactive CLI surfaces.
+ *
+ * The footer (and any ANSI-driven UI) is only safe when stdout is attached
+ * to a real terminal AND NO_COLOR is unset. Piped output and NO_COLOR runs
+ * must stay raw so downstream tooling and redirected logs never see escape
+ * sequences.
+ *
+ * This is the single source of truth for the gate; SdlcOrchestrator._runLoop
+ * calls it when initializing FooterManager, and tests use it to simulate the
+ * orchestrator's availability decision.
+ */
+export declare function isInteractiveStdout(): boolean;

package/dist/util/tty.js

@@ -0,0 +1,16 @@
+// xcoder:version 1 | xcoder:task task-e53af9 | xcoder:updated 2026-08-13T13:58:49.496Z | xcoder:subtask code-st-a2df76
+/**
+ * Centralized TTY detection for interactive CLI surfaces.
+ *
+ * The footer (and any ANSI-driven UI) is only safe when stdout is attached
+ * to a real terminal AND NO_COLOR is unset. Piped output and NO_COLOR runs
+ * must stay raw so downstream tooling and redirected logs never see escape
+ * sequences.
+ *
+ * This is the single source of truth for the gate; SdlcOrchestrator._runLoop
+ * calls it when initializing FooterManager, and tests use it to simulate the
+ * orchestrator's availability decision.
+ */
+export function isInteractiveStdout() {
+    return process.stdout.isTTY === true && process.env.NO_COLOR === undefined;
+}

package/dist/util/xcoder-paths.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Resolves the base directory name for Xcoder SDLC's runtime data.
+ * Controlled by XCODER_DIR env var; defaults to ".xcoder".
+ *
+ * Workspace-relative by default. If XCODER_DIR starts with `/`, `\\`,
+ * `C:`, or is otherwise an absolute path, treat it as absolute.
+ */
+export declare function xcoderBaseName(): string;
+/**
+ * Resolve the full .xcoder directory path given a workspace root.
+ * If XCODER_DIR is an absolute path, uses it directly; otherwise
+ * joins it with the workspace root.
+ */
+export declare function resolveXcoderDir(workspaceRoot: string): string;
+/**
+ * Canonical sub-paths — every module that reads/writes Xcoder SDLC data
+ * MUST go through these functions, never hardcode "scrum" or "xcoder".
+ */
+export interface XcoderPaths {
+    /** Root: <workspace>/.xcoder/ */
+    readonly root: string;
+    /** Task run JSON file: <root>/tasks/<taskId>.json */
+    taskFile(taskId: string): string;
+    /** Progress markdown: <root>/tasks/<taskId>.md */
+    taskProgressFile(taskId: string): string;
+    /** Tasks directory: <root>/tasks/ */
+    tasksDir(): string;
+    /** Backlog directory: <root>/backlog/ */
+    backlogDir(): string;
+    /** Backlog JSON: <root>/backlog/_backlog.json */
+    backlogFile(): string;
+    /** Individual requirement doc: <root>/backlog/<id>.md */
+    backlogDoc(id: string): string;
+    /** Sprint runs directory: <root>/sprint/runs/ */
+    sprintRunsDir(): string;
+    /** Individual sprint run: <root>/sprint/runs/<id>.json */
+    sprintRunFile(sprintRunId: string): string;
+    /** Defects directory: <root>/defects/ */
+    defectsDir(): string;
+    /** Config directory: <root>/config/ */
+    configDir(): string;
+    /** LLM config: <root>/config/llm.yaml */
+    llmConfigPath(): string;
+    /** Architecture blueprint: <root>/blueprint.md */
+    blueprintPath(): string;
+    /** Release/installer output: <root>/release/ */
+    releaseDir(): string;
+    /** Lessons file: <root>/lessons/learned.md */
+    lessonsPath(): string;
+}
+/**
+ * Create a XcoderPaths instance bound to a workspace root.
+ * This is the single factory — every consumer calls this once and
+ * passes the instance down.
+ */
+export declare function createXcoderPaths(workspaceRoot: string): XcoderPaths;

package/dist/util/xcoder-paths.js

@@ -0,0 +1,63 @@
+// xcoder:version 1 | xcoder:task task-12fb57 | xcoder:updated 2026-08-04T12:06:13.381Z | xcoder:subtask code-st-33c7d1
+import path from "node:path";
+// ---------------------------------------------------------------------------
+// XCODER_DIR resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolves the base directory name for Xcoder SDLC's runtime data.
+ * Controlled by XCODER_DIR env var; defaults to ".xcoder".
+ *
+ * Workspace-relative by default. If XCODER_DIR starts with `/`, `\\`,
+ * `C:`, or is otherwise an absolute path, treat it as absolute.
+ */
+export function xcoderBaseName() {
+    return process.env.XCODER_DIR || ".xcoder";
+}
+/**
+ * Resolve the full .xcoder directory path given a workspace root.
+ * If XCODER_DIR is an absolute path, uses it directly; otherwise
+ * joins it with the workspace root.
+ */
+export function resolveXcoderDir(workspaceRoot) {
+    const base = xcoderBaseName();
+    if (path.isAbsolute(base)) {
+        return base;
+    }
+    return path.resolve(workspaceRoot, base);
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a XcoderPaths instance bound to a workspace root.
+ * This is the single factory — every consumer calls this once and
+ * passes the instance down.
+ */
+export function createXcoderPaths(workspaceRoot) {
+    const root = resolveXcoderDir(workspaceRoot);
+    return {
+        root,
+        // ── Task data ───────────────────────────────────────────
+        tasksDir: () => path.join(root, "tasks"),
+        taskFile: (taskId) => path.join(root, "tasks", `${taskId}.json`),
+        taskProgressFile: (taskId) => path.join(root, "tasks", `${taskId}.md`),
+        // ── Backlog ─────────────────────────────────────────────
+        backlogDir: () => path.join(root, "backlog"),
+        backlogFile: () => path.join(root, "backlog", "_backlog.json"),
+        backlogDoc: (id) => path.join(root, "backlog", `${id}.md`),
+        // ── Sprint ──────────────────────────────────────────────
+        sprintRunsDir: () => path.join(root, "sprint", "runs"),
+        sprintRunFile: (sprintRunId) => path.join(root, "sprint", "runs", `${sprintRunId}.json`),
+        // ── Defects ─────────────────────────────────────────────
+        defectsDir: () => path.join(root, "defects"),
+        // ── Config ──────────────────────────────────────────────
+        configDir: () => path.join(root, "config"),
+        llmConfigPath: () => path.join(root, "config", "llm.yaml"),
+        // ── Blueprint ───────────────────────────────────────────
+        blueprintPath: () => path.join(root, "blueprint.md"),
+        // ── Release ─────────────────────────────────────────────
+        releaseDir: () => path.join(root, "release"),
+        // ── Lessons ─────────────────────────────────────────────
+        lessonsPath: () => path.join(root, "lessons", "learned.md"),
+    };
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const XCODER_VERSION = "1.3.0";
+export declare const XCODER_BUILD_TIMESTAMP = "2026-10-26T00:00:00.000Z";

package/dist/version.js

@@ -0,0 +1,4 @@
+// AUTO-GENERATED by scripts/inject-version.mjs — DO NOT EDIT
+// Regenerate: npm run build (or: node scripts/inject-version.mjs)
+export const XCODER_VERSION = "1.3.0";
+export const XCODER_BUILD_TIMESTAMP = "2026-10-26T00:00:00.000Z";