xcoder-dna 0.0.0-stage → 1.3.1

package/dist/task-ingest/scanner.js

@@ -0,0 +1,216 @@
+// xcoder:version 1 | xcoder:task task-cee5a1 | xcoder:updated 2026-10-23T12:52:47.742Z | xcoder:subtask code-st-f13216
+// C1 — discover `.md` task sources in a directory and hand each survivor to
+// `ingestTask()`.
+//
+// This module is orchestration only: it never parses markdown, never derives an
+// id, and never writes. Taskhood is delegated to `parseWbs` (at least one work
+// item) so the rule cannot drift from `task add --from`; every byte on disk
+// still goes through the single already-tested ingest path.
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { loadTaskRun } from "../store/task-store.js";
+import { createXcoderPaths } from "../util/xcoder-paths.js";
+import { deriveTaskId, ingestTask } from "./ingest.js";
+import { parseWbs } from "./wbs-parser.js";
+import { readSource } from "./source-reader.js";
+/**
+ * Mirrors `ingest.ts`'s private `PROGRESS_STATUSES`.
+ *
+ * Duplicated rather than exported so `ingest.ts` (on the design's no-change
+ * list) stays untouched. `scanner.test.ts` locks the two together by
+ * asserting that a dry run agrees with the real, persisted outcome for the
+ * same directory.
+ */
+const PROGRESS_STATUSES = new Set(["done", "in_progress", "validating", "healing"]);
+function hasProgress(run) {
+    return (run.dag ?? []).some((n) => PROGRESS_STATUSES.has(n.status));
+}
+function toPosix(p) {
+    return p.split(path.sep).join("/");
+}
+function isMarkdownCandidate(name) {
+    return name.length > 3 && !name.startsWith(".") && /\.md$/i.test(name);
+}
+function skipped(sourcePath, reason, code, message) {
+    return { sourcePath, status: "skipped", reason, code, message };
+}
+function failed(sourcePath, code, message) {
+    return { sourcePath, status: "failed", code, message };
+}
+function dirFailure(relDir, code, message) {
+    return {
+        ok: false,
+        result: {
+            dir: relDir,
+            scanned: 0,
+            created: [],
+            unchanged: [],
+            skipped: [],
+            failed: [],
+            dirError: { code, message },
+        },
+    };
+}
+/**
+ * Confine the requested directory to the workspace (lexically *and* through
+ * symlinks), then confirm it is a directory. This is a second layer of defence
+ * over `readSource`, which independently confines every individual file.
+ */
+async function resolveScanDir(root, dir) {
+    const absDir = path.resolve(root, dir ?? createXcoderPaths(root).tasksDir());
+    const rel = path.relative(root, absDir);
+    const escapes = path.isAbsolute(rel) || rel === ".." || rel.startsWith(`..${path.sep}`) || rel.startsWith("..");
+    const relDir = toPosix(rel);
+    if (escapes) {
+        return dirFailure(relDir, "outside-workspace", `scan directory resolves outside the workspace (${absDir})`);
+    }
+    const realRoot = (await fs.realpath(root).catch(() => root)) ?? root;
+    const realDir = await fs.realpath(absDir).catch(() => null);
+    if (realDir === null) {
+        return dirFailure(relDir, "not-found", `scan directory not found: ${absDir}`);
+    }
+    const relFromRoot = path.relative(realRoot, realDir);
+    if (path.isAbsolute(relFromRoot) ||
+        relFromRoot === ".." ||
+        relFromRoot.startsWith(`..${path.sep}`)) {
+        return dirFailure(relDir, "outside-workspace", `scan directory resolves outside the workspace via a symlink (${realDir})`);
+    }
+    const stat = await fs.stat(realDir).catch(() => null);
+    if (!stat || !stat.isDirectory()) {
+        return dirFailure(relDir, "not-a-directory", `not a directory: ${absDir}`);
+    }
+    return { ok: true, absDir, relDir };
+}
+/** Map a real `ingestTask` result onto a scan outcome. */
+function fromIngest(sourcePath, result) {
+    if (result.ok) {
+        return {
+            sourcePath,
+            taskId: result.taskId,
+            status: result.created ? "created" : "unchanged",
+        };
+    }
+    switch (result.code) {
+        case "no-items":
+            return skipped(sourcePath, "not-a-task", result.code, result.message);
+        case "has-progress":
+            return skipped(sourcePath, "has-progress", result.code, result.message);
+        case "id-collision":
+            return skipped(sourcePath, "id-collision", result.code, result.message);
+        default:
+            return failed(sourcePath, result.code, result.message);
+    }
+}
+/**
+ * Predict what `ingestTask` would do, without writing.
+ *
+ * Reuses `readSource`, `parseWbs` and `deriveTaskId` so the discovery rules are
+ * identical to the real path; only the persistence step is elided.
+ */
+async function predict(sourcePath, root, force) {
+    const source = await readSource(root, sourcePath);
+    if (!source.ok)
+        return failed(sourcePath, source.code, source.message);
+    const stem = path.basename(sourcePath, path.extname(sourcePath));
+    const parsed = parseWbs(source.value.bytes.toString("utf8"), stem);
+    if (!parsed.ok) {
+        if (parsed.code === "no-items")
+            return skipped(sourcePath, "not-a-task", parsed.code, parsed.message);
+        return failed(sourcePath, parsed.code, parsed.message);
+    }
+    // Same collision fallback as `ingestTask`.
+    let taskId = deriveTaskId(sourcePath, 8);
+    const primary = await loadTaskRun(root, taskId);
+    if (primary && primary.spec.inputs.sourcePath !== sourcePath) {
+        taskId = deriveTaskId(sourcePath, 12);
+    }
+    const existing = await loadTaskRun(root, taskId);
+    if (!existing)
+        return { sourcePath, taskId, status: "created" };
+    if (existing.spec.inputs.sourcePath !== sourcePath) {
+        return skipped(sourcePath, "id-collision", "id-collision", `derived id ${taskId} already belongs to a different source`);
+    }
+    if (hasProgress(existing) && !force) {
+        return skipped(sourcePath, "has-progress", "has-progress", `${taskId} already has completed or in-flight subtasks — re-run with --force to replace it`);
+    }
+    return { sourcePath, taskId, status: "unchanged" };
+}
+/**
+ * Scan `dir` (default: the task store directory) for `.md` task sources and
+ * ingest each one.
+ *
+ * Never throws for a single bad file — every per-file problem is isolated into
+ * `failed` so one unreadable source cannot abort the batch.
+ */
+export async function scanMarkdownTasks(opts) {
+    const root = path.resolve(opts.workspaceRoot);
+    const resolved = await resolveScanDir(root, opts.dir);
+    if (!resolved.ok)
+        return resolved.result;
+    const { absDir, relDir } = resolved;
+    let entries;
+    try {
+        entries = await fs.readdir(absDir, { withFileTypes: true });
+    }
+    catch (e) {
+        return {
+            dir: relDir,
+            scanned: 0,
+            created: [],
+            unchanged: [],
+            skipped: [],
+            failed: [],
+            dirError: { code: "not-found", message: `could not read ${absDir}: ${e.message}` },
+        };
+    }
+    // Any `<stem>.json` beside a `<stem>.md` makes that markdown a derived
+    // progress summary, not a task source (D2). This guard runs before anything
+    // is read, so a progress mirror can never be re-ingested as a phantom task.
+    const present = new Set(entries.map((e) => e.name));
+    const candidates = entries
+        .filter((e) => (e.isFile() || e.isSymbolicLink()) && isMarkdownCandidate(e.name))
+        .map((e) => e.name)
+        .sort();
+    const result = {
+        dir: relDir,
+        scanned: candidates.length,
+        created: [],
+        unchanged: [],
+        skipped: [],
+        failed: [],
+    };
+    const force = opts.force === true;
+    for (const name of candidates) {
+        const stem = name.slice(0, -3);
+        const sourcePath = toPosix(path.relative(root, path.join(absDir, name)));
+        if (present.has(`${stem}.json`)) {
+            result.skipped.push(skipped(sourcePath, "progress-summary", "progress-summary", `${stem}.json sits beside it in the same directory — derived progress summary, not a task source`));
+            continue;
+        }
+        try {
+            const outcome = opts.dryRun
+                ? await predict(sourcePath, root, force)
+                : fromIngest(sourcePath, await ingestTask({
+                    workspaceRoot: root,
+                    from: sourcePath,
+                    force,
+                    now: opts.now,
+                    concurrency: opts.concurrency,
+                }));
+            if (outcome.status === "created")
+                result.created.push(outcome);
+            else if (outcome.status === "unchanged")
+                result.unchanged.push(outcome);
+            else if (outcome.status === "skipped")
+                result.skipped.push(outcome);
+            else
+                result.failed.push(outcome);
+        }
+        catch (e) {
+            // Per-file failure isolation (D7): one unexpected throw never aborts the
+            // batch. `saveTaskRun` is atomic, so no partial `.tmp` survives either.
+            result.failed.push(failed(sourcePath, "internal-error", e.message));
+        }
+    }
+    return result;
+}

package/dist/task-ingest/source-reader.d.ts

@@ -0,0 +1,25 @@
+export interface SourceFile {
+    /** Resolved path, guaranteed to be inside the workspace. */
+    absPath: string;
+    /** Workspace-relative POSIX path — the idempotency key. */
+    relPathPosix: string;
+    bytes: Buffer;
+    /** Hex sha256 of the exact bytes ingested. */
+    sha256: string;
+}
+export type ReadSourceErrorCode = "not-found" | "outside-workspace" | "too-large" | "not-a-file";
+export type ReadSourceResult = {
+    ok: true;
+    value: SourceFile;
+} | {
+    ok: false;
+    code: ReadSourceErrorCode;
+    message: string;
+};
+/** Hard cap so ingestion can't be used to read a giant file into memory. */
+export declare const MAX_SOURCE_BYTES: number;
+/**
+ * Resolve `from` against `workspaceRoot`, refuse anything that escapes the
+ * workspace (including through a symlink), enforce the size cap, and read.
+ */
+export declare function readSource(workspaceRoot: string, from: string): Promise<ReadSourceResult>;

package/dist/task-ingest/source-reader.js

@@ -0,0 +1,93 @@
+// xcoder:version 1 | xcoder:task task-a91099 | xcoder:updated 2026-10-23T10:52:34.657Z | xcoder:subtask code-st-03748c
+// C1 — resolve, confine, and read a user-supplied markdown/WBS source file.
+//
+// The source file is HOSTILE input (prompt-injection bylaw PRM-01): it may
+// carry ANSI escapes, bidi overrides, or instructions aimed at a future model
+// turn. This module's only job is to hand back bounded, path-confined bytes;
+// nothing downstream may ever treat those bytes as an instruction.
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+/** Hard cap so ingestion can't be used to read a giant file into memory. */
+export const MAX_SOURCE_BYTES = 1024 * 1024; // 1 MiB
+function within(child, parent) {
+    const rel = path.relative(parent, child);
+    return rel.length > 0 && !rel.startsWith(".." + path.sep) && rel !== ".." && !path.isAbsolute(rel);
+}
+async function realpathOrNull(p) {
+    try {
+        return await fs.realpath(p);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve `from` against `workspaceRoot`, refuse anything that escapes the
+ * workspace (including through a symlink), enforce the size cap, and read.
+ */
+export async function readSource(workspaceRoot, from) {
+    const root = path.resolve(workspaceRoot);
+    const abs = path.resolve(root, from);
+    // 1. Lexical confinement: reject absolute escapes, `..`, and the root itself.
+    const rel = path.relative(root, abs);
+    if (rel.length === 0) {
+        return { ok: false, code: "not-a-file", message: `"${from}" resolves to the workspace root, not a file` };
+    }
+    if (path.isAbsolute(rel) || rel.startsWith("..")) {
+        return {
+            ok: false,
+            code: "outside-workspace",
+            message: `"${from}" resolves outside the workspace (${abs})`,
+        };
+    }
+    // 2. Physical confinement: a symlink inside the workspace may still point out.
+    const realRoot = (await realpathOrNull(root)) ?? root;
+    const realAbs = await realpathOrNull(abs);
+    if (realAbs === null) {
+        return { ok: false, code: "not-found", message: `source file not found: ${abs}` };
+    }
+    if (!within(realAbs, realRoot)) {
+        return {
+            ok: false,
+            code: "outside-workspace",
+            message: `"${from}" resolves outside the workspace via a symlink (${realAbs})`,
+        };
+    }
+    // 3. Must be a regular file; size checked BEFORE reading.
+    let stat;
+    try {
+        stat = await fs.stat(realAbs);
+    }
+    catch {
+        return { ok: false, code: "not-found", message: `source file not found: ${abs}` };
+    }
+    if (!stat.isFile()) {
+        return { ok: false, code: "not-a-file", message: `not a regular file: ${abs}` };
+    }
+    if (stat.size > MAX_SOURCE_BYTES) {
+        return {
+            ok: false,
+            code: "too-large",
+            message: `source file is ${stat.size} bytes, over the ${MAX_SOURCE_BYTES}-byte limit: ${abs}`,
+        };
+    }
+    let bytes;
+    try {
+        bytes = await fs.readFile(realAbs);
+    }
+    catch (e) {
+        return { ok: false, code: "not-found", message: `could not read ${abs}: ${e.message}` };
+    }
+    // 4. Re-check after read — the file may have grown between stat and read.
+    if (bytes.length > MAX_SOURCE_BYTES) {
+        return {
+            ok: false,
+            code: "too-large",
+            message: `source file is ${bytes.length} bytes, over the ${MAX_SOURCE_BYTES}-byte limit: ${abs}`,
+        };
+    }
+    const sha256 = crypto.createHash("sha256").update(bytes).digest("hex");
+    const relPathPosix = rel.split(path.sep).join("/");
+    return { ok: true, value: { absPath: abs, relPathPosix, bytes, sha256 } };
+}

package/dist/task-ingest/spec-builder.d.ts

@@ -0,0 +1,34 @@
+import type { SdlcStage, SubtaskNode, TaskSpec } from "../types.js";
+import type { ParsedWbs, WbsItem } from "./wbs-parser.js";
+export interface BuildInput {
+    parsed: ParsedWbs;
+    source: {
+        relPathPosix: string;
+        sha256: string;
+    };
+    /** Supplied by C4 so this function stays pure. */
+    taskId: string;
+    /** Supplied by C4 so re-ingest can preserve the original timestamp. */
+    createdAt: string;
+    /** Default concurrency, from the CLI. */
+    concurrency: number;
+    maxHealingAttempts?: number;
+}
+/**
+ * Keyword-to-stage table. Data, not logic — first match wins, applied to the
+ * lower-cased item text. Extend here without touching the builder.
+ */
+export declare const KEYWORD_STAGE_TABLE: ReadonlyArray<{
+    pattern: RegExp;
+    stage: SdlcStage;
+}>;
+export declare function stageForItem(item: WbsItem): SdlcStage;
+/**
+ * Build the TaskSpec and the DAG. Uses the existing `getStageRole`,
+ * `deliverableFor` and `acceptanceCriteriaFor` helpers so the ingested task
+ * speaks exactly the same vocabulary as a free-text one.
+ */
+export declare function buildIngestedRun(input: BuildInput): {
+    spec: TaskSpec;
+    dag: SubtaskNode[];
+};

package/dist/task-ingest/spec-builder.js

@@ -0,0 +1,89 @@
+// xcoder:version 2 | xcoder:task task-a91099 | xcoder:updated 2026-10-23T10:55:14.056Z | xcoder:subtask code-st-03748c
+// C3 — deterministic, PURE mapping from a parsed WBS to a valid TaskRun.
+//
+// No I/O, no clock, no randomness, no LLM. Every input that varies (taskId,
+// createdAt) is supplied by C4 so re-ingesting an unchanged source produces a
+// byte-identical record.
+import crypto from "node:crypto";
+import { getStageRole } from "../sdlc-runtime/sdlc-skill.js";
+import { deliverableFor, acceptanceCriteriaFor } from "../orchestrator/task-factory.js";
+/**
+ * Keyword-to-stage table. Data, not logic — first match wins, applied to the
+ * lower-cased item text. Extend here without touching the builder.
+ */
+export const KEYWORD_STAGE_TABLE = [
+    { pattern: /\b(requirements?|specs?|acceptance criteri(?:on|a)|user stor(?:y|ies))\b/i, stage: "requirements" },
+    { pattern: /\b(designs?|architects?|architectural|blueprints?|schemas?|contracts?)\b/i, stage: "design" },
+    { pattern: /\b(tests?|suites?|coverage|vitest|playwright)\b/i, stage: "test" },
+    { pattern: /\b(docs?|readme|readmes?|guides?|changelogs?|document(?:s|ation)?|documenting)\b/i, stage: "document" },
+    { pattern: /\b(deploys?|deploying|deployment|releases?|installers?|publish(?:es|ing)?)\b/i, stage: "deploy" },
+    { pattern: /\b(fix(?:es|ing)?|bugs?|defects?|regressions?|crashes?|crash)\b/i, stage: "fix_defect" },
+];
+export function stageForItem(item) {
+    if (item.stage)
+        return item.stage;
+    for (const entry of KEYWORD_STAGE_TABLE) {
+        if (entry.pattern.test(item.text))
+            return entry.stage;
+    }
+    return "requirements";
+}
+/** stage-<first 6 hex of sha256(relPath + "#" + index)> — stable across runs. */
+function deterministicNodeId(stage, relPathPosix, index) {
+    const digest = crypto.createHash("sha256").update(`${relPathPosix}#${index}`).digest("hex");
+    return `${stage}-${digest.slice(0, 6)}`;
+}
+/**
+ * Build the TaskSpec and the DAG. Uses the existing `getStageRole`,
+ * `deliverableFor` and `acceptanceCriteriaFor` helpers so the ingested task
+ * speaks exactly the same vocabulary as a free-text one.
+ */
+export function buildIngestedRun(input) {
+    const { parsed, source, taskId, createdAt, concurrency } = input;
+    const maxHealingAttempts = input.maxHealingAttempts ?? 2;
+    const spec = {
+        taskId,
+        goal: parsed.goal,
+        // Deliberately ONLY freeText + sourcePath. code / design / url /
+        // defectDetail / credentialRef are never populated from file content —
+        // that is what would let a hostile document steer intake classification
+        // or a credential lookup.
+        inputs: { freeText: parsed.goal, sourcePath: source.relPathPosix },
+        constraints: { maxHealingAttempts, concurrency },
+        createdAt,
+        provenance: {
+            sourcePath: source.relPathPosix,
+            sourceSha256: source.sha256,
+            ingestedAt: createdAt,
+            ingestVersion: 1,
+        },
+    };
+    const dag = [];
+    let previousId = null;
+    for (const item of parsed.items) {
+        const stage = stageForItem(item);
+        const id = deterministicNodeId(stage, source.relPathPosix, item.index);
+        let dependsOn;
+        if (typeof item.after === "number" && item.after >= 1 && item.after <= dag.length) {
+            dependsOn = [dag[item.after - 1].id];
+        }
+        else {
+            dependsOn = previousId ? [previousId] : [];
+        }
+        dag.push({
+            id,
+            stage,
+            role: getStageRole(stage, spec.inputs),
+            engine: "react-v1",
+            dependsOn,
+            goal: item.text,
+            upstreamContext: {},
+            deliverableSpec: deliverableFor(stage),
+            acceptanceCriteria: acceptanceCriteriaFor(stage),
+            status: dag.length === 0 ? "ready" : "pending",
+            healing: { attempts: 0, maxAttempts: maxHealingAttempts, log: [] },
+        });
+        previousId = id;
+    }
+    return { spec, dag };
+}

package/dist/task-ingest/wbs-extract.d.ts

@@ -0,0 +1,50 @@
+import type { SdlcStage } from "../types.js";
+import { type ArchitectDetailer } from "./architect-detailer.js";
+export interface ExtractOptions {
+    workspaceRoot: string;
+    /** Exactly what the user typed after --wbc. Confined by readSource(). */
+    from: string;
+    dryRun?: boolean;
+    force?: boolean;
+    /** Omit for the LLM detailer; pass null for deterministic content. */
+    detailer?: ArchitectDetailer | null;
+    /** Default 50, hard max MAX_ITEMS (200). */
+    maxItems?: number;
+    /** Default 3, clamped 1..8. */
+    concurrency?: number;
+    now?: () => Date;
+}
+export type ExtractErrorCode = "not-found" | "outside-workspace" | "too-large" | "not-a-file" | "bad-front-matter" | "no-items" | "too-many-items" | "bad-options" | "too-many-pending" | "architect-failed" | "architect-schema-invalid" | "has-progress" | "id-collision" | "write-failed";
+export interface ExtractedTask {
+    taskId: string;
+    line: number;
+    order: number;
+    /** false => an identical record was already on disk ("unchanged"). */
+    created: boolean;
+    supersededBy?: string;
+    nodeCount: number;
+    stages: SdlcStage[];
+    nextCommand: string;
+}
+export type ExtractResult = {
+    ok: true;
+    sourcePath: string;
+    sourceSha256: string;
+    dryRun: boolean;
+    counts: {
+        pending: number;
+        checked: number;
+        created: number;
+        unchanged: number;
+        superseded: number;
+    };
+    tasks: ExtractedTask[];
+} | {
+    ok: false;
+    exitCode: 1;
+    code: ExtractErrorCode;
+    message: string;
+    line?: number;
+    taskId?: string;
+};
+export declare function extractWbsTasks(opts: ExtractOptions): Promise<ExtractResult>;