xcoder-dna 0.0.0-stage → 1.3.0

package/dist/llm/factory.js

@@ -0,0 +1,32 @@
+// xcoder:version 1 | xcoder:task task-c49600 | xcoder:updated 2026-08-13T13:51:25.757Z | xcoder:subtask code-st-6d79ef
+import { LlmClient } from "./client.js";
+import { loadLlmConfigFile, resolveLlmConfig, } from "../config/loadConfig.js";
+/**
+ * Sole production constructor path for LLM clients. Resolves the effective
+ * per-role configuration from `.xcoder/config/llm.yaml` (or built-in
+ * DeepSeek defaults) and returns a transport ready for that role.
+ *
+ * Precedence in `resolveLlmConfig`: role block → `default` block → built-in
+ * DeepSeek; `XCODER_MODEL` applies to `model` only.
+ */
+export function createLlmClient(role, overrides = {}) {
+    const file = loadLlmConfigFile();
+    const config = resolveLlmConfig(role, file);
+    const opts = configToClientOptions(config);
+    return new LlmClient({
+        ...opts,
+        model: overrides.model ?? opts.model,
+        maxTokens: overrides.maxTokens ?? opts.maxTokens,
+    });
+}
+function configToClientOptions(config) {
+    return {
+        provider: config.provider ?? "deepseek",
+        baseUrl: config.base_url,
+        endpoint: config.endpoint,
+        model: config.model,
+        maxTokens: config.max_tokens,
+        temperature: config.temperature,
+        apiKeyEnv: config.api_key_env,
+    };
+}

package/dist/orchestrator/defect-logger.d.ts

@@ -0,0 +1,31 @@
+export interface DefectLogEntry {
+    timestamp: string;
+    defectId: string;
+    event: "discovered" | "fix_attempt_start" | "fix_attempt_result" | "resolved" | "closed" | "reopened";
+    detail: string;
+    metadata?: Record<string, unknown>;
+}
+export interface MigrationEntry {
+    timestamp: string;
+    oldPath: string;
+    newPath: string;
+    defectId: string;
+    status: "migrated" | "skipped" | "failed";
+    reason: string;
+}
+/**
+ * Appends one JSON line to `.log/defect-rca-check.log`. Creates the
+ * directory and file if they don't exist. Follows the 1MB rollover
+ * pattern from `logs.ts`.
+ */
+export declare function logDefectEvent(workspaceRoot: string, entry: DefectLogEntry): Promise<void>;
+/**
+ * Reads and parses the NDJSON log file. If `defectId` is provided,
+ * filters to events for that defect only. Used by the orchestrator to
+ * reconstruct the RCA check status.
+ */
+export declare function readDefectLog(workspaceRoot: string, defectId?: string): Promise<DefectLogEntry[]>;
+/**
+ * Writes migration audit records to `.log/migration.log` in NDJSON format.
+ */
+export declare function logMigration(workspaceRoot: string, entries: MigrationEntry[]): Promise<void>;

package/dist/orchestrator/defect-logger.js

@@ -0,0 +1,101 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+// ---------------------------------------------------------------------------
+// Path resolution
+// ---------------------------------------------------------------------------
+const MAX_BYTES = 1_000_000; // 1MB rollover threshold
+function logFilePath(workspaceRoot) {
+    const logDir = process.env.XCODER_LOG_DIR ?? ".log";
+    return path.join(workspaceRoot, logDir, "defect-rca-check.log");
+}
+function migrationLogPath(workspaceRoot) {
+    const logDir = process.env.XCODER_LOG_DIR ?? ".log";
+    return path.join(workspaceRoot, logDir, "migration.log");
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Appends a line to a file, with a 1MB rollover pattern matching `logs.ts`.
+ */
+async function appendWithRollover(filePath, line) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    const entry = line.endsWith("\n") ? line : line + "\n";
+    let currentSize = 0;
+    try {
+        currentSize = (await fs.stat(filePath)).size;
+    }
+    catch {
+        currentSize = 0;
+    }
+    if (currentSize + Buffer.byteLength(entry, "utf8") > MAX_BYTES) {
+        const rolled = filePath.replace(/(\.[^.]+)$/, ".1$1");
+        try {
+            await fs.rm(rolled, { force: true });
+            await fs.rename(filePath, rolled);
+        }
+        catch {
+            // best-effort; if the rename fails just keep appending to the current file
+        }
+    }
+    await fs.appendFile(filePath, entry, "utf8");
+}
+function ts() {
+    return new Date().toISOString();
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Appends one JSON line to `.log/defect-rca-check.log`. Creates the
+ * directory and file if they don't exist. Follows the 1MB rollover
+ * pattern from `logs.ts`.
+ */
+export async function logDefectEvent(workspaceRoot, entry) {
+    await appendWithRollover(logFilePath(workspaceRoot), JSON.stringify(entry));
+}
+/**
+ * Reads and parses the NDJSON log file. If `defectId` is provided,
+ * filters to events for that defect only. Used by the orchestrator to
+ * reconstruct the RCA check status.
+ */
+export async function readDefectLog(workspaceRoot, defectId) {
+    const file = logFilePath(workspaceRoot);
+    let raw = "";
+    try {
+        raw = await fs.readFile(file, "utf-8");
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed &&
+                typeof parsed === "object" &&
+                typeof parsed.timestamp === "string" &&
+                typeof parsed.defectId === "string" &&
+                typeof parsed.event === "string") {
+                if (!defectId || parsed.defectId === defectId) {
+                    entries.push(parsed);
+                }
+            }
+        }
+        catch {
+            // Skip malformed lines.
+        }
+    }
+    return entries;
+}
+/**
+ * Writes migration audit records to `.log/migration.log` in NDJSON format.
+ */
+export async function logMigration(workspaceRoot, entries) {
+    for (const entry of entries) {
+        await appendWithRollover(migrationLogPath(workspaceRoot), JSON.stringify(entry));
+    }
+}

package/dist/orchestrator/defect-manager.d.ts

@@ -0,0 +1,118 @@
+import type { Role, SdlcStage, SubtaskNode, TaskSpec } from "../types.js";
+import type { DefectsIndex } from "./defect-store.js";
+/**
+ * Parsed representation of a defect RCA file written by a tester.
+ * The file format must follow the Markdown contract defined in the
+ * design: a `# DEFECT-NNNN` title line followed by `## Observed
+ * Behaviour`, `## Expected Behaviour`, `## Reproduction Steps`,
+ * `## Root Cause Hypothesis`, `## Affected Files`, and `## Severity`.
+ */
+export interface DefectFile {
+    id: string;
+    path: string;
+    discoveredBy: string;
+    observedBehaviour: string;
+    expectedBehaviour: string;
+    reproductionSteps: string;
+    rootCauseHypothesis: string;
+    affectedFiles: string[];
+    severity: "low" | "medium" | "high" | "critical";
+}
+/**
+ * The shape of `upstreamContext.defect` that a `fix_defect` node carries.
+ */
+export interface DefectContext {
+    defectId: string;
+    defectPath: string;
+    rca: {
+        observedBehaviour: string;
+        expectedBehaviour: string;
+        rootCauseHypothesis: string;
+        affectedFiles: string[];
+        severity: "low" | "medium" | "high" | "critical";
+    };
+}
+/**
+ * Context passed to `defectManagerDecide` — this interface is retained
+ * for backwards compatibility but the decision logic now lives in
+ * `SdlcOrchestrator.handleResult`.
+ * @deprecated Use direct store/logger operations instead.
+ */
+export interface DefectActionContext {
+    dag: SubtaskNode[];
+    newDefects: DefectFile[];
+    /** Any fix_defect node in the DAG that was tasked with this defect
+     *  and has now completed (passed or failed). */
+    completedFixNodes: {
+        nodeId: string;
+        defectPath: string;
+        passed: boolean;
+    }[];
+    /** The workspace root, needed for file-existence checks. */
+    workspaceRoot: string;
+}
+/**
+ * Scans the defects directory for files matching `defect[0-9]{4}.md`.
+ * The directory is resolved via `createXcoderPaths` (respects XCODER_DIR),
+ * or `XCODER_DEFECT_DIR` env var as override. A file is "new" if its id
+ * is not in the index at all, OR if the index entry has `status: 'closed'`
+ * and the file has been modified since `lastUpdated` (reopened). Returns
+ * parsed DefectFile array sorted by ID ascending.
+ */
+export declare function scanForDefects(workspaceRoot: string, index: DefectsIndex): Promise<DefectFile[]>;
+/**
+ * Determines which role should receive a `fix_defect` node for the given
+ * defect. The v1 rule is simple: look at the tester's immediate upstream
+ * node in the DAG. If it was a `code` stage, route to `programmer`; if it
+ * was a `refactor` stage, route to `refactorer`.
+ *
+ * In the orchestrator integration, the caller (handleResult) knows which
+ * tester node discovered the defect, so it can look up that node's
+ * `dependsOn` and pass the upstream stage directly.
+ */
+export declare function classifyDefectRouting(upstreamStage: SdlcStage | undefined): Role;
+/**
+ * Constructs a self-contained `fix_defect` `SubtaskNode` with the defect
+ * path and RCA inlined into `upstreamContext`, ready to be injected into
+ * the DAG.
+ */
+export declare function buildFixDefectNode(defect: DefectFile, role: Role, spec: TaskSpec, dependsOn: string[]): SubtaskNode;
+/**
+ * Builds the goal text for a `fix_defect` node. When a defect path is
+ * present in upstreamContext, the goal becomes: "Confirm the defect
+ * described in {defectPath} no longer reproduces, via a real test run."
+ *
+ * Exported so task-factory.ts can reuse it for its own `buildGoalText`.
+ */
+export declare function buildFixDefectGoal(defectPath: string): string;
+/**
+ * Called by the orchestrator when a fix_defect passes verification.
+ * Updates the `_defects.json` entry status to "resolved", sets
+ * `resolvedAt` and `resolvedBy`, logs the lifecycle event, and
+ * optionally archives the RCA file to `.xcoder/defects/archive/`.
+ */
+export declare function resolveDefect(workspaceRoot: string, defectId: string, nodeId: string): Promise<void>;
+/**
+ * Called by the orchestrator when a fix_defect node is created. Updates
+ * the `_defects.json` entry to add a `FixAttempt` record and sets status
+ * to `in_progress`. Logs the lifecycle event.
+ */
+export declare function recordFixAttempt(workspaceRoot: string, defectId: string, nodeId: string, attemptNumber: number): Promise<void>;
+/**
+ * The Defect Manager's main entry point — retains the original signature
+ * for backwards compatibility. The orchestrator now handles the decision
+ * logic directly in `handleResult` since it has direct access to the
+ * store and logger.
+ *
+ * @deprecated Decision logic is now inlined in `SdlcOrchestrator.handleResult`.
+ */
+export declare function defectManagerDecide(ctx: DefectActionContext): {
+    type: "replan";
+    patch: {
+        addNodes: SubtaskNode[];
+    };
+} | {
+    type: "escalate";
+    subtaskId: string;
+    reason: string;
+} | null;

package/dist/orchestrator/defect-manager.js

@@ -0,0 +1,338 @@
+import { shortId } from "../util/ids.js";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { loadDefectsIndex, upsertDefect } from "./defect-store.js";
+import { logDefectEvent } from "./defect-logger.js";
+import { createXcoderPaths } from "../util/xcoder-paths.js";
+// ---------------------------------------------------------------------------
+// Scanning
+// ---------------------------------------------------------------------------
+/** Pattern that defect files must match: defect followed by exactly four digits, then .md. */
+const DEFECT_FILE_RE = /^defect(\d{4})\.md$/;
+/**
+ * Scans the defects directory for files matching `defect[0-9]{4}.md`.
+ * The directory is resolved via `createXcoderPaths` (respects XCODER_DIR),
+ * or `XCODER_DEFECT_DIR` env var as override. A file is "new" if its id
+ * is not in the index at all, OR if the index entry has `status: 'closed'`
+ * and the file has been modified since `lastUpdated` (reopened). Returns
+ * parsed DefectFile array sorted by ID ascending.
+ */
+export async function scanForDefects(workspaceRoot, index) {
+    const scanDir = process.env.XCODER_DEFECT_DIR ?? createXcoderPaths(workspaceRoot).defectsDir();
+    const defectsDir = path.resolve(workspaceRoot, scanDir);
+    let entries = [];
+    try {
+        entries = await fs.readdir(defectsDir);
+    }
+    catch {
+        // No defects directory or it's unreadable — nothing to scan.
+        return [];
+    }
+    const newDefects = [];
+    for (const entry of entries) {
+        const match = entry.match(DEFECT_FILE_RE);
+        if (!match)
+            continue;
+        const numericId = match[1];
+        const defectId = `DEFECT-${numericId}`;
+        const fullPath = path.join(defectsDir, entry);
+        const relativePath = path.relative(workspaceRoot, fullPath).replace(/\\/g, "/");
+        // Check index: skip if already known and not reopened.
+        const existing = index[defectId];
+        if (existing && existing.status !== "closed") {
+            // Already tracked and not closed — skip.
+            continue;
+        }
+        if (existing && existing.status === "closed") {
+            // Check if file was modified since it was resolved (reopened).
+            try {
+                const stat = await fs.stat(fullPath);
+                const fileMtime = stat.mtime.toISOString();
+                if (fileMtime <= existing.lastUpdated) {
+                    // File hasn't been touched since resolution — still closed.
+                    continue;
+                }
+                // File modified after resolution — treat as reopened.
+            }
+            catch {
+                // File unreadable — skip.
+                continue;
+            }
+        }
+        try {
+            const content = await fs.readFile(fullPath, "utf-8");
+            const defect = parseDefectFile(content, relativePath, numericId);
+            if (defect)
+                newDefects.push(defect);
+        }
+        catch {
+            // File unreadable — skip it.
+        }
+    }
+    newDefects.sort((a, b) => a.id.localeCompare(b.id));
+    return newDefects;
+}
+/**
+ * Parses the contents of a single defect Markdown file into a `DefectFile`.
+ * Returns `null` if the file doesn't conform to the minimum required
+ * structure (a `# DEFECT-` title and at least one recognised section).
+ */
+function parseDefectFile(content, relativePath, numericId) {
+    const titleMatch = content.match(/^#\s+DEFECT-(\d+)/m);
+    const id = titleMatch ? `DEFECT-${titleMatch[1]}` : `DEFECT-${numericId}`;
+    // Extract sections by heading — case-insensitive, `##` prefix.
+    const sections = extractSections(content);
+    const discoveredBy = sections["discovered by"] ??
+        sections["**discovered by:**"] ??
+        extractInlineMeta(content, /\*\*Discovered by:\*\*\s*(.*)/i) ??
+        "unknown";
+    const severityRaw = (sections["severity"] ??
+        extractInlineMeta(content, /\*\*Severity:\*\*\s*(.*)/i) ??
+        "medium").trim().toLowerCase();
+    const severity = ["low", "medium", "high", "critical"].includes(severityRaw)
+        ? severityRaw
+        : "medium";
+    const observedBehaviour = sections["observed behaviour"] ?? sections["observed behavior"] ?? "";
+    const expectedBehaviour = sections["expected behaviour"] ?? sections["expected behavior"] ?? "";
+    const reproductionSteps = sections["reproduction steps"] ?? "";
+    const rootCauseHypothesis = sections["root cause hypothesis"] ?? "";
+    const affectedFilesRaw = sections["affected files"] ?? "";
+    const affectedFiles = affectedFilesRaw
+        .split(/\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith("- ") || line.startsWith("*"))
+        .map((line) => line.replace(/^[-*]\s+/, "").replace(/`/g, "").trim())
+        .filter(Boolean);
+    // Must have at least the core RCA fields populated.
+    if (!observedBehaviour && !expectedBehaviour && !rootCauseHypothesis)
+        return null;
+    return {
+        id,
+        path: relativePath,
+        discoveredBy,
+        observedBehaviour,
+        expectedBehaviour,
+        reproductionSteps,
+        rootCauseHypothesis,
+        affectedFiles,
+        severity,
+    };
+}
+/**
+ * Extracts sections from Markdown content keyed by `## Heading` lines.
+ * Headings are normalised to lowercase for lookup. Body runs until the
+ * next `##` heading or EOF.
+ */
+function extractSections(content) {
+    const result = {};
+    const lines = content.split("\n");
+    let currentHeading = null;
+    let currentBody = [];
+    for (const line of lines) {
+        const headingMatch = line.match(/^##\s+(.+)/);
+        if (headingMatch) {
+            if (currentHeading) {
+                result[currentHeading.toLowerCase()] = currentBody.join("\n").trim();
+            }
+            currentHeading = headingMatch[1].trim();
+            currentBody = [];
+        }
+        else if (currentHeading) {
+            currentBody.push(line);
+        }
+    }
+    if (currentHeading) {
+        result[currentHeading.toLowerCase()] = currentBody.join("\n").trim();
+    }
+    return result;
+}
+/** Extracts a value from an inline bold-meta line like `**Key:** value`. */
+function extractInlineMeta(content, regex) {
+    const match = content.match(regex);
+    return match ? match[1].trim() : null;
+}
+// ---------------------------------------------------------------------------
+// Routing
+// ---------------------------------------------------------------------------
+/**
+ * Determines which role should receive a `fix_defect` node for the given
+ * defect. The v1 rule is simple: look at the tester's immediate upstream
+ * node in the DAG. If it was a `code` stage, route to `programmer`; if it
+ * was a `refactor` stage, route to `refactorer`.
+ *
+ * In the orchestrator integration, the caller (handleResult) knows which
+ * tester node discovered the defect, so it can look up that node's
+ * `dependsOn` and pass the upstream stage directly.
+ */
+export function classifyDefectRouting(upstreamStage) {
+    if (upstreamStage === "code")
+        return "programmer";
+    if (upstreamStage === "refactor")
+        return "refactorer";
+    // Fallback: if unsure, route to programmer (the safer default — new code is more likely).
+    return "programmer";
+}
+// ---------------------------------------------------------------------------
+// Node construction
+// ---------------------------------------------------------------------------
+/**
+ * Constructs a self-contained `fix_defect` `SubtaskNode` with the defect
+ * path and RCA inlined into `upstreamContext`, ready to be injected into
+ * the DAG.
+ */
+export function buildFixDefectNode(defect, role, spec, dependsOn) {
+    const nodeId = `fix_defect-${shortId("df")}`;
+    const defectContext = {
+        defectId: defect.id,
+        defectPath: defect.path,
+        rca: {
+            observedBehaviour: defect.observedBehaviour,
+            expectedBehaviour: defect.expectedBehaviour,
+            rootCauseHypothesis: defect.rootCauseHypothesis,
+            affectedFiles: defect.affectedFiles,
+            severity: defect.severity,
+        },
+    };
+    const goal = buildFixDefectGoal(defect.path);
+    return {
+        id: nodeId,
+        stage: "fix_defect",
+        role,
+        engine: "react-v1",
+        dependsOn,
+        goal,
+        upstreamContext: { defect: defectContext },
+        deliverableSpec: "Confirmation the original defect no longer reproduces, via a real test run.",
+        acceptanceCriteria: [
+            {
+                id: "AC1",
+                type: "command",
+                description: "A targeted re-run confirms the original defect no longer reproduces.",
+            },
+        ],
+        status: "pending",
+        healing: {
+            attempts: 0,
+            maxAttempts: spec.constraints.maxHealingAttempts,
+            log: [],
+        },
+    };
+}
+/**
+ * Builds the goal text for a `fix_defect` node. When a defect path is
+ * present in upstreamContext, the goal becomes: "Confirm the defect
+ * described in {defectPath} no longer reproduces, via a real test run."
+ *
+ * Exported so task-factory.ts can reuse it for its own `buildGoalText`.
+ */
+export function buildFixDefectGoal(defectPath) {
+    return `Confirm the defect described in ${defectPath} no longer reproduces, via a real test run.`;
+}
+// ---------------------------------------------------------------------------
+// Defect lifecycle helpers
+// ---------------------------------------------------------------------------
+/**
+ * Called by the orchestrator when a fix_defect passes verification.
+ * Updates the `_defects.json` entry status to "resolved", sets
+ * `resolvedAt` and `resolvedBy`, logs the lifecycle event, and
+ * optionally archives the RCA file to `.xcoder/defects/archive/`.
+ */
+export async function resolveDefect(workspaceRoot, defectId, nodeId) {
+    const index = await loadDefectsIndex(workspaceRoot);
+    const record = index[defectId];
+    if (!record)
+        return;
+    const now = new Date().toISOString();
+    record.status = "resolved";
+    record.resolvedAt = now;
+    record.resolvedBy = nodeId;
+    record.lastUpdated = now;
+    // Mark the latest fix attempt as passed.
+    if (record.fixAttempts.length > 0) {
+        const last = record.fixAttempts[record.fixAttempts.length - 1];
+        last.completedAt = now;
+        last.passed = true;
+        last.notes = `Resolved by ${nodeId}`;
+    }
+    await upsertDefect(workspaceRoot, record);
+    // Log lifecycle event.
+    await logDefectEvent(workspaceRoot, {
+        timestamp: now,
+        defectId,
+        event: "resolved",
+        detail: `Defect ${defectId} resolved by ${nodeId}`,
+        metadata: { fixNodeId: nodeId },
+    });
+    // Optionally archive the RCA file.
+    try {
+        const scanDir = process.env.XCODER_DEFECT_DIR ?? createXcoderPaths(workspaceRoot).defectsDir();
+        const archiveDir = path.join(path.resolve(workspaceRoot, scanDir), "archive");
+        const srcPath = path.join(workspaceRoot, record.path);
+        const basename = path.basename(record.path);
+        const destPath = path.join(archiveDir, basename);
+        await fs.mkdir(archiveDir, { recursive: true });
+        await fs.rename(srcPath, destPath);
+    }
+    catch {
+        // Archive is best-effort — file may already have been moved or deleted.
+    }
+}
+/**
+ * Called by the orchestrator when a fix_defect node is created. Updates
+ * the `_defects.json` entry to add a `FixAttempt` record and sets status
+ * to `in_progress`. Logs the lifecycle event.
+ */
+export async function recordFixAttempt(workspaceRoot, defectId, nodeId, attemptNumber) {
+    const index = await loadDefectsIndex(workspaceRoot);
+    const record = index[defectId];
+    if (!record)
+        return;
+    const now = new Date().toISOString();
+    record.status = "in_progress";
+    record.lastUpdated = now;
+    record.fixAttempts.push({
+        attemptNumber,
+        fixNodeId: nodeId,
+        startedAt: now,
+        completedAt: undefined,
+        passed: false,
+        notes: undefined,
+    });
+    await upsertDefect(workspaceRoot, record);
+    // Log lifecycle event.
+    await logDefectEvent(workspaceRoot, {
+        timestamp: now,
+        defectId,
+        event: "fix_attempt_start",
+        detail: `Fix attempt ${attemptNumber} started by ${nodeId}`,
+        metadata: { fixNodeId: nodeId, attemptNumber },
+    });
+}
+// ---------------------------------------------------------------------------
+// Decision function
+// ---------------------------------------------------------------------------
+/**
+ * The Defect Manager's main entry point — retains the original signature
+ * for backwards compatibility. The orchestrator now handles the decision
+ * logic directly in `handleResult` since it has direct access to the
+ * store and logger.
+ *
+ * @deprecated Decision logic is now inlined in `SdlcOrchestrator.handleResult`.
+ */
+export function defectManagerDecide(ctx) {
+    for (const completed of ctx.completedFixNodes) {
+        if (!completed.passed) {
+            return {
+                type: "escalate",
+                subtaskId: completed.nodeId,
+                reason: `Unresolved defect ${completed.defectPath} after healing exhaustion`,
+            };
+        }
+    }
+    if (ctx.newDefects.length === 0)
+        return null;
+    return {
+        type: "replan",
+        patch: { addNodes: [] },
+    };
+}

package/dist/orchestrator/defect-migration.d.ts

@@ -0,0 +1,14 @@
+import type { DefectRecord } from "./defect-store.js";
+/**
+ * One-time auto-detection and migration of a legacy `defects/` directory
+ * into `.xcoder/defects/`. Runs once per workspace lifetime (guarded by a
+ * `.xcoder/.migrated` sentinel file).
+ *
+ * If the sentinel is absent, checks for a `defects/` directory. If found,
+ * moves all `defect*.md` files to `.xcoder/defects/`, writes a
+ * `_defects.json` with `status: 'open'` for each, writes
+ * `.log/migration.log`, creates the sentinel, and returns the migrated
+ * records. If `defects/` doesn't exist, still creates the sentinel to
+ * avoid future checks.
+ */
+export declare function migrateLegacyDefects(workspaceRoot: string): Promise<DefectRecord[]>;