xcoder-dna 0.0.0-stage → 1.3.0

package/dist/sprint/controller.js

@@ -0,0 +1,220 @@
+// xcoder:version 1 | xcoder:task task-8c3c2b | xcoder:updated 2026-08-04T08:26:22.973Z | xcoder:subtask code-st-71e0aa
+/**
+ * Sprint Controller — coordinates the full sprint lifecycle.
+ *
+ * Design contract: `.xcoder/design/sprint-framework-design.md` §4.1
+ */
+import { promises as fs } from "node:fs";
+import { SdlcOrchestrator } from "../sdlc-runtime/sdlc-orchestrator.js";
+import { buildTaskSpec } from "../orchestrator/task-factory.js";
+import { listBacklogItems, updateBacklogItem } from "../backlog/backlog-store.js";
+import { runPoPick } from "../backlog/po-agent.js";
+import { shortId } from "../util/ids.js";
+import { log } from "../util/logger.js";
+import { buildSprintDag } from "./dag-builder.js";
+import { saveSprintRun, loadActiveSprintRun, loadSprintRun, deleteSprintRun, listSprintRuns, } from "./state-store.js";
+import { writeGateRejectionReport, writeRetroReport, } from "./reporter.js";
+// ---------------------------------------------------------------------------
+// sprintStart
+// ---------------------------------------------------------------------------
+export async function sprintStart(opts) {
+    const { workspaceRoot: root, llm, concurrency } = opts;
+    // 1. Load open backlog items.
+    const openItems = await listBacklogItems(root, "open");
+    if (openItems.length === 0) {
+        throw new Error("No open backlog items available for a sprint.");
+    }
+    // 2. Use PO Agent to pick the highest-priority eligible item.
+    const pickResult = await runPoPick(root, openItems);
+    const sprintRunId = `${pickResult.selectedId}-sprint-${shortId("sr")}`;
+    log.ok(`PO picked: ${pickResult.selectedId} — ${pickResult.title}`);
+    log.dim(`Reasoning: ${pickResult.reasoning}`);
+    // 3. Update the item: sprintId, status=in-progress, sprintRunAt.
+    const now = new Date().toISOString();
+    await updateBacklogItem(root, pickResult.selectedId, {
+        sprintId: sprintRunId,
+        status: "in-progress",
+        sprintRunAt: now,
+    });
+    log.ok(`${pickResult.selectedId} → in-progress (sprint: ${sprintRunId})`);
+    // 4. Build a TaskSpec from the backlog item.
+    const taskText = pickResult.title;
+    const spec = buildTaskSpec(taskText, {}, {
+        budgetUsd: undefined,
+        maxHealingAttempts: 2,
+        concurrency,
+    });
+    log.orchestrator(`task ${spec.taskId}: ${spec.goal}`);
+    // 5. Build sprint DAG with quality-gate nodes.
+    const dag = buildSprintDag(spec);
+    // 6. Create and save SprintRun.
+    const sprintRun = {
+        sprintRunId,
+        backlogItemId: pickResult.selectedId,
+        taskId: spec.taskId,
+        status: "running",
+        dag,
+        currentStage: "requirements",
+        gateResults: [],
+        startedAt: now,
+        completedAt: null,
+        totalTokenUsage: { inputTokens: 0, outputTokens: 0 },
+    };
+    await saveSprintRun(root, sprintRun);
+    // 7. Run via the SdlcOrchestrator with the augmented DAG.
+    const orchestrator = new SdlcOrchestrator({
+        workspaceRoot: root,
+        llm,
+        concurrency,
+    });
+    const taskRun = await orchestrator.run(spec, dag);
+    // Accumulate token usage.
+    sprintRun.totalTokenUsage = taskRun.totalTokenUsage;
+    // 8. Post-orchestrator: check each gate node's result from the orchestrator's DAG.
+    const gateFailures = extractGateFailures(taskRun.dag);
+    sprintRun.gateResults = gateFailures;
+    if (gateFailures.some((g) => !g.passed)) {
+        // At least one gate failed — mark item as blocked.
+        const firstFailure = gateFailures.find((g) => !g.passed);
+        sprintRun.status = "blocked";
+        sprintRun.completedAt = new Date().toISOString();
+        await saveSprintRun(root, sprintRun);
+        await updateBacklogItem(root, pickResult.selectedId, {
+            blockedReason: `${firstFailure.role}: ${firstFailure.reason}`,
+        });
+        await writeGateRejectionReport(root, pickResult.selectedId, sprintRunId, firstFailure);
+        log.fail(`Sprint ${sprintRunId} blocked by ${firstFailure.role} gate: ${firstFailure.reason}`);
+        return {
+            sprintRunId,
+            backlogItemId: pickResult.selectedId,
+            taskId: spec.taskId,
+            outcome: "blocked",
+            gateFailures,
+        };
+    }
+    // All gates passed — mark item as done.
+    sprintRun.status = "done";
+    sprintRun.completedAt = new Date().toISOString();
+    await saveSprintRun(root, sprintRun);
+    await updateBacklogItem(root, pickResult.selectedId, {
+        status: "done",
+        taskId: spec.taskId,
+        sprintId: null,
+        blockedReason: null,
+    });
+    // Write retrospective.
+    await writeRetroReport(root, sprintRun);
+    log.ok(`Sprint ${sprintRunId} completed successfully — ${pickResult.selectedId} marked done.`);
+    return {
+        sprintRunId,
+        backlogItemId: pickResult.selectedId,
+        taskId: spec.taskId,
+        outcome: "done",
+        gateFailures,
+    };
+}
+// ---------------------------------------------------------------------------
+// sprintStatus
+// ---------------------------------------------------------------------------
+export async function sprintStatus(root) {
+    const active = await loadActiveSprintRun(root);
+    if (!active) {
+        log.dim("No active sprint found.");
+        return { active: false };
+    }
+    return {
+        active: true,
+        sprintRunId: active.sprintRunId,
+        backlogItemId: active.backlogItemId,
+        currentStage: active.currentStage,
+        taskStatus: active.status,
+        gateResults: active.gateResults,
+    };
+}
+// ---------------------------------------------------------------------------
+// sprintRetro
+// ---------------------------------------------------------------------------
+export async function sprintRetro(root, sprintRunId) {
+    let run = null;
+    if (sprintRunId) {
+        run = await loadSprintRun(root, sprintRunId);
+    }
+    else {
+        // Default: most recent non-running sprint.
+        const all = await listSprintRuns(root);
+        const completed = all.filter((r) => r.status === "done" || r.status === "aborted" || r.status === "blocked");
+        if (completed.length > 0) {
+            completed.sort((a, b) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime());
+            run = completed[0];
+        }
+    }
+    if (!run) {
+        throw new Error(sprintRunId
+            ? `Sprint run "${sprintRunId}" not found.`
+            : "No completed sprint runs found for retrospective.");
+    }
+    const reportPath = await writeRetroReport(root, run);
+    // Read back the contents.
+    try {
+        const contents = await fs.readFile(reportPath, "utf-8");
+        return { reportPath, contents };
+    }
+    catch {
+        return { reportPath, contents: "" };
+    }
+}
+// ---------------------------------------------------------------------------
+// sprintAbort
+// ---------------------------------------------------------------------------
+export async function sprintAbort(root) {
+    const active = await loadActiveSprintRun(root);
+    if (!active) {
+        throw new Error("No active sprint to abort.");
+    }
+    // Reset the item.
+    await updateBacklogItem(root, active.backlogItemId, {
+        sprintId: null,
+        blockedReason: null,
+        status: "open",
+    });
+    // Remove the sprint run file.
+    await deleteSprintRun(root, active.sprintRunId);
+    log.ok(`Sprint ${active.sprintRunId} aborted — ${active.backlogItemId} reverted to open.`);
+    return { revertedItemId: active.backlogItemId };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Walk the DAG and extract pass/fail results from quality-gate nodes.
+ */
+function extractGateFailures(dag) {
+    const results = [];
+    for (const node of dag) {
+        if (node.stage === "quality_gate" &&
+            (node.role === "scrum-master" ||
+                node.role === "system-architect" ||
+                node.role === "security-lead")) {
+            const role = node.role;
+            if (node.result?.deliverable) {
+                const d = node.result.deliverable;
+                results.push({
+                    role,
+                    passed: Boolean(d.passed),
+                    reason: String(d.reason ?? "No reason provided"),
+                    subtaskId: node.id,
+                });
+            }
+            else {
+                // Node didn't produce a result — likely never ran or crashed.
+                results.push({
+                    role,
+                    passed: false,
+                    reason: `Gate node ${node.id} did not produce a result (status: ${node.status})`,
+                    subtaskId: node.id,
+                });
+            }
+        }
+    }
+    return results;
+}

package/dist/sprint/dag-builder.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Sprint DAG Builder — extends the default linear SDLC DAG by inserting
+ * quality‑gate SubtaskNodes after specific stages.
+ *
+ * Pipeline:
+ *   requirements → [Scrum Master gate] → design → [System Architect gate]
+ *   → code → test → [Security Lead gate] → done
+ */
+import type { SubtaskNode, TaskSpec } from "../types.js";
+/**
+ * Build a sprint DAG from a TaskSpec by inserting quality-gate nodes
+ * into the default linear plan at specific checkpoints.
+ */
+export declare function buildSprintDag(spec: TaskSpec): SubtaskNode[];

package/dist/sprint/dag-builder.js

@@ -0,0 +1,105 @@
+// xcoder:version 4 | xcoder:task task-f1ac77 | xcoder:updated 2026-10-17T04:10:51.927Z | xcoder:subtask code-st-1d0003
+/**
+ * Sprint DAG Builder — extends the default linear SDLC DAG by inserting
+ * quality‑gate SubtaskNodes after specific stages.
+ *
+ * Pipeline:
+ *   requirements → [Scrum Master gate] → design → [System Architect gate]
+ *   → code → test → [Security Lead gate] → done
+ */
+import { buildInitialPlan } from "../orchestrator/task-factory.js";
+import { shortId } from "../util/ids.js";
+import { inferLayers } from "../skills/secure-architect.bylaws.js";
+/**
+ * Build a sprint DAG from a TaskSpec by inserting quality-gate nodes
+ * into the default linear plan at specific checkpoints.
+ */
+export function buildSprintDag(spec) {
+    const baseDag = buildInitialPlan(spec);
+    return insertQualityGates(baseDag);
+}
+function insertQualityGates(nodes) {
+    const result = [];
+    for (const node of nodes) {
+        result.push(node);
+        // Insert quality gates after specific stages.
+        if (node.stage === "requirements") {
+            result.push(buildGateNode("scrum-master", node, gateDirectives.scrumMaster));
+        }
+        else if (node.stage === "design") {
+            result.push(buildGateNode("system-architect", node, gateDirectives.systemArchitect));
+        }
+        else if (node.stage === "test") {
+            result.push(buildGateNode("security-lead", node, gateDirectives.securityLead));
+        }
+    }
+    return result;
+}
+function buildGateNode(role, reviewed, goal) {
+    const id = `gate-${role.replace(/-/g, "-")}-${shortId("st")}`;
+    const acceptanceCriteria = [
+        {
+            id: "AC1",
+            type: "schema",
+            description: "deliverable contains passed: boolean and reason: string",
+        },
+    ];
+    if (role === "security-lead") {
+        // Second, independent check: the agent's own `passed` claim is AC1, the
+        // bylaws module's verdict over its own findings is AC2. Disagreement
+        // between them fails the gate. Scope is frozen here, at build time,
+        // because the gate's own goal is static boilerplate and re-inferring it
+        // later would silently narrow scope to core + cross-cutting.
+        acceptanceCriteria.push({
+            id: "AC2",
+            type: "bylaw-review",
+            description: "every in-scope bylaw has a finding; no failed MUST/MUST_NOT; " +
+                "SHOULD deviations carry a named riskOwner",
+            bylawLayers: [...inferLayers(reviewed.goal)],
+        });
+    }
+    return {
+        id,
+        stage: "quality_gate",
+        role,
+        engine: "react-v1",
+        dependsOn: [reviewed.id],
+        goal,
+        upstreamContext: { reviewedNodeId: reviewed.id, reviewedGoal: reviewed.goal },
+        deliverableSpec: role === "security-lead"
+            ? "A verdict — must be a JSON object { passed: boolean, reason: string, findings: [{ bylawId, status, note?, riskOwner? }] } in the final_answer deliverable, with exactly one finding per in-scope bylaw."
+            : "A pass/fail verdict with a reason — must be a JSON object { passed: boolean, reason: string } in the final_answer deliverable.",
+        acceptanceCriteria,
+        status: "pending",
+        healing: { attempts: 0, maxAttempts: 1, log: [] },
+    };
+}
+const gateDirectives = {
+    scrumMaster: `
+Review the requirements document produced by the requirements-analyst stage
+immediately before this gate. Validate:
+1. The document exists and is well‑formed (has Goal, Non‑Goals, Constraints,
+   Acceptance Criteria sections).
+2. All acceptance criteria are concrete and testable — not hand‑wavy.
+3. Every open question from the requirements stage is either answered or
+   explicitly deferred with a stakeholder note.
+Return a JSON object: { "passed": true/false, "reason": "..." }.`.trim(),
+    systemArchitect: `
+Review the design document produced by the architect stage immediately
+before this gate. Validate:
+1. Every component named in the requirements has a defined interface.
+2. Every import/reference points to a file that actually exists in the workspace
+   index (use the glob tool to verify).
+3. No new pattern‑breaking dependency is introduced — the design must conform
+   to existing workspace conventions (check the workspace index for a
+   package.json, tsconfig, eslint config, etc.).
+Return a JSON object: { "passed": true/false, "reason": "..." }.`.trim(),
+    securityLead: `
+Run the project's security checks:
+1. Execute "npm audit" (or appropriate command from the project's tooling)
+   and parse its output. The default threshold for blocking is: any "critical"
+   or "high" severity finding blocks the sprint.
+2. Search the workspace for common vulnerability patterns: hard‑coded secrets,
+   unvalidated user input reaching eval/system calls, missing auth guards.
+Return a JSON object: { "passed": true/false, "reason": "..." }.`.trim(),
+};

package/dist/sprint/reporter.d.ts

@@ -0,0 +1,11 @@
+import type { GateResult, SprintRun } from "./types.js";
+/**
+ * Write a gate rejection report for a specific failed gate.
+ * Returns the absolute path to the written file.
+ */
+export declare function writeGateRejectionReport(root: string, backlogItemId: string, sprintRunId: string, gate: GateResult): Promise<string>;
+/**
+ * Write a sprint retrospective report from a completed or aborted SprintRun.
+ * Returns the absolute path to the written file.
+ */
+export declare function writeRetroReport(root: string, run: SprintRun): Promise<string>;

package/dist/sprint/reporter.js

@@ -0,0 +1,97 @@
+// xcoder:version 1 | xcoder:task task-b190f1 | xcoder:updated 2026-08-03T10:31:20.691Z | xcoder:subtask code-st-167a5d
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { getOutputPaths } from "../util/output-paths.js";
+// ---------------------------------------------------------------------------
+// Path resolution
+// ---------------------------------------------------------------------------
+function reportsDir(root) {
+    // The root parameter is preserved for backward compatibility but no longer
+    // drives the path — OutputPaths singleton is the single source of truth.
+    return getOutputPaths({ cwd: root }).sprintReportsDir();
+}
+// ---------------------------------------------------------------------------
+// Gate rejection report
+// ---------------------------------------------------------------------------
+/**
+ * Write a gate rejection report for a specific failed gate.
+ * Returns the absolute path to the written file.
+ */
+export async function writeGateRejectionReport(root, backlogItemId, sprintRunId, gate) {
+    const dir = reportsDir(root);
+    await fs.mkdir(dir, { recursive: true });
+    const fileName = `sprint-${backlogItemId}.md`;
+    const filePath = path.join(dir, fileName);
+    const content = [
+        `# Sprint Gate Rejection — ${backlogItemId}`,
+        "",
+        `- **Gate:** ${gate.role}`,
+        `- **Timestamp:** ${new Date().toISOString()}`,
+        `- **Rejection Reason:** ${gate.reason}`,
+        `- **Sprint Run ID:** ${sprintRunId}`,
+        "",
+    ].join("\n");
+    await fs.writeFile(filePath, content, "utf-8");
+    return filePath;
+}
+// ---------------------------------------------------------------------------
+// Retrospective report
+// ---------------------------------------------------------------------------
+/**
+ * Write a sprint retrospective report from a completed or aborted SprintRun.
+ * Returns the absolute path to the written file.
+ */
+export async function writeRetroReport(root, run) {
+    const dir = reportsDir(root);
+    await fs.mkdir(dir, { recursive: true });
+    const fileName = `sprint-${run.backlogItemId}-retro.md`;
+    const filePath = path.join(dir, fileName);
+    const started = new Date(run.startedAt);
+    const completed = run.completedAt ? new Date(run.completedAt) : new Date();
+    const durationMs = completed.getTime() - started.getTime();
+    const duration = humanReadableDuration(durationMs);
+    const rows = [
+        `# Sprint Retrospective — ${run.backlogItemId}`,
+        "",
+        `- **Completed Item(s):** ${run.backlogItemId}`,
+        `- **Started:** ${run.startedAt}`,
+        `- **Completed:** ${run.completedAt ?? "N/A"}`,
+        `- **Duration:** ${duration}`,
+        `- **Status:** ${run.status}`,
+        "",
+        "## Gate Results",
+        "",
+        "| Gate | Passed | Reason |",
+        "|------|--------|--------|",
+    ];
+    if (run.gateResults.length > 0) {
+        for (const g of run.gateResults) {
+            rows.push(`| ${g.role} | ${g.passed ? "✅" : "❌"} | ${g.reason.slice(0, 80)} |`);
+        }
+    }
+    else {
+        rows.push("| (no gates run) | — | — |");
+    }
+    rows.push("", "## Token Usage", "");
+    rows.push(`- **Input tokens:** ${run.totalTokenUsage.inputTokens}`);
+    rows.push(`- **Output tokens:** ${run.totalTokenUsage.outputTokens}`);
+    rows.push("");
+    const content = rows.join("\n");
+    await fs.writeFile(filePath, content, "utf-8");
+    return filePath;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function humanReadableDuration(ms) {
+    const seconds = Math.floor(ms / 1000);
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    const remainingSeconds = seconds % 60;
+    if (minutes < 60)
+        return `${minutes}m ${remainingSeconds}s`;
+    const hours = Math.floor(minutes / 60);
+    const remainingMinutes = minutes % 60;
+    return `${hours}h ${remainingMinutes}m ${remainingSeconds}s`;
+}

package/dist/sprint/state-store.d.ts

@@ -0,0 +1,10 @@
+import type { SprintRun } from "./types.js";
+export declare function saveSprintRun(root: string, run: SprintRun): Promise<void>;
+export declare function loadSprintRun(root: string, sprintRunId: string): Promise<SprintRun | null>;
+/**
+ * Loads the most recently started SprintRun that is still active
+ * (status "running" or "blocked"), sorted by startedAt descending.
+ */
+export declare function loadActiveSprintRun(root: string): Promise<SprintRun | null>;
+export declare function deleteSprintRun(root: string, sprintRunId: string): Promise<void>;
+export declare function listSprintRuns(root: string): Promise<SprintRun[]>;

package/dist/sprint/state-store.js

@@ -0,0 +1,71 @@
+// xcoder:version 1 | xcoder:task swarm-swarm-is-b22287 | xcoder:updated 2026-08-04T12:10:29.441Z | xcoder:subtask swarm-swarm-is-b22287/0
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { createXcoderPaths } from "../util/xcoder-paths.js";
+// ---------------------------------------------------------------------------
+// CRUD operations
+// ---------------------------------------------------------------------------
+export async function saveSprintRun(root, run) {
+    const paths = createXcoderPaths(root);
+    const dir = paths.sprintRunsDir();
+    await fs.mkdir(dir, { recursive: true });
+    const file = paths.sprintRunFile(run.sprintRunId);
+    const tmp = `${file}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify(run, null, 2), "utf8");
+    await fs.rename(tmp, file);
+}
+export async function loadSprintRun(root, sprintRunId) {
+    const file = createXcoderPaths(root).sprintRunFile(sprintRunId);
+    try {
+        const raw = await fs.readFile(file, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Loads the most recently started SprintRun that is still active
+ * (status "running" or "blocked"), sorted by startedAt descending.
+ */
+export async function loadActiveSprintRun(root) {
+    const runs = await listSprintRuns(root);
+    const active = runs.filter((r) => r.status === "running" || r.status === "blocked");
+    if (active.length === 0)
+        return null;
+    active.sort((a, b) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime());
+    return active[0];
+}
+export async function deleteSprintRun(root, sprintRunId) {
+    const file = createXcoderPaths(root).sprintRunFile(sprintRunId);
+    try {
+        await fs.unlink(file);
+    }
+    catch {
+        // File doesn't exist — that's fine.
+    }
+}
+export async function listSprintRuns(root) {
+    const dir = createXcoderPaths(root).sprintRunsDir();
+    let entries;
+    try {
+        entries = await fs.readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const runs = [];
+    for (const entry of entries) {
+        if (!entry.endsWith(".json"))
+            continue;
+        const filePath = path.join(dir, entry);
+        try {
+            const raw = await fs.readFile(filePath, "utf-8");
+            runs.push(JSON.parse(raw));
+        }
+        catch {
+            // Skip malformed files.
+        }
+    }
+    return runs;
+}

package/dist/sprint/types.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Sprint framework data model types — see `.xcoder/design/sprint-framework-design.md`.
+ */
+import type { SubtaskNode, TokenUsage } from "../types.js";
+export type SprintRunStatus = "running" | "done" | "aborted" | "blocked";
+export interface GateResult {
+    role: "scrum-master" | "system-architect" | "security-lead";
+    passed: boolean;
+    reason: string;
+    /** The subtask node id that ran this gate, for traceability. */
+    subtaskId?: string;
+}
+export interface SprintRun {
+    sprintRunId: string;
+    backlogItemId: string;
+    taskId: string;
+    status: SprintRunStatus;
+    dag: SubtaskNode[];
+    currentStage: string;
+    gateResults: GateResult[];
+    startedAt: string;
+    completedAt: string | null;
+    totalTokenUsage: TokenUsage;
+}

package/dist/sprint/types.js

@@ -0,0 +1,4 @@
+/**
+ * Sprint framework data model types — see `.xcoder/design/sprint-framework-design.md`.
+ */
+export {};

package/dist/store/file-version-store.d.ts

@@ -0,0 +1,24 @@
+/** Keyed by workspace-relative posix path. Timestamps in ISO 8601. */
+export type FileVersionsIndex = Record<string, {
+    version: number;
+    lastTask: string;
+    lastSubtask: string;
+    lastUpdated: string;
+}>;
+export interface HeaderMeta {
+    version: number;
+    taskId: string;
+    subtaskId: string;
+    timestamp: string;
+}
+/**
+ * Reads .xcoder/file-versions.json, parses it, returns the index.
+ * Returns an empty index if the file doesn't exist or is malformed.
+ */
+export declare function loadFileVersions(workspaceRoot: string): Promise<FileVersionsIndex>;
+/**
+ * Loads the index, looks up relPath, increments version by 1 (or sets to 1
+ * if new), updates lastTask/lastSubtask/lastUpdated, saves the index
+ * atomically (temp + rename), returns the new HeaderMeta.
+ */
+export declare function incrementFileVersion(workspaceRoot: string, relPath: string, taskId: string, subtaskId: string): Promise<HeaderMeta>;

package/dist/store/file-version-store.js

@@ -0,0 +1,73 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+function versionsPath(workspaceRoot) {
+    return path.join(workspaceRoot, ".xcoder", "file-versions.json");
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Reads .xcoder/file-versions.json, parses it, returns the index.
+ * Returns an empty index if the file doesn't exist or is malformed.
+ */
+export async function loadFileVersions(workspaceRoot) {
+    try {
+        const raw = await fs.readFile(versionsPath(workspaceRoot), "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            return {};
+        }
+        // Validate entries have the expected shape
+        const sanitized = {};
+        for (const [k, v] of Object.entries(parsed)) {
+            const entry = v;
+            if (typeof entry?.version === "number" &&
+                typeof entry?.lastTask === "string" &&
+                typeof entry?.lastSubtask === "string") {
+                sanitized[k] = {
+                    version: entry.version,
+                    lastTask: entry.lastTask,
+                    lastSubtask: entry.lastSubtask,
+                    lastUpdated: typeof entry.lastUpdated === "string" ? entry.lastUpdated : new Date().toISOString(),
+                };
+            }
+        }
+        return sanitized;
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Loads the index, looks up relPath, increments version by 1 (or sets to 1
+ * if new), updates lastTask/lastSubtask/lastUpdated, saves the index
+ * atomically (temp + rename), returns the new HeaderMeta.
+ */
+export async function incrementFileVersion(workspaceRoot, relPath, taskId, subtaskId) {
+    const index = await loadFileVersions(workspaceRoot);
+    const posix = relPath.replace(/\\/g, "/");
+    const existing = index[posix];
+    const newVersion = existing ? existing.version + 1 : 1;
+    const timestamp = new Date().toISOString();
+    index[posix] = {
+        version: newVersion,
+        lastTask: taskId,
+        lastSubtask: subtaskId,
+        lastUpdated: timestamp,
+    };
+    await atomicWrite(workspaceRoot, index);
+    return { version: newVersion, taskId, subtaskId, timestamp };
+}
+// ---------------------------------------------------------------------------
+// Internal: atomic write
+// ---------------------------------------------------------------------------
+async function atomicWrite(workspaceRoot, index) {
+    const target = versionsPath(workspaceRoot);
+    const tmp = target + ".tmp." + Date.now();
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    await fs.writeFile(tmp, JSON.stringify(index, null, 2), "utf8");
+    await fs.rename(tmp, target);
+}