xcoder-dna 0.0.0-stage → 1.3.1

package/dist/task-ingest/detailed-run.d.ts

@@ -0,0 +1,36 @@
+import type { SubtaskNode, TaskRun } from "../types.js";
+import type { ArchitectDetail } from "./architect-detailer.js";
+import type { PendingItem } from "./pending-filter.js";
+export interface DetailedRunInput {
+    item: PendingItem;
+    detail: ArchitectDetail;
+    source: {
+        relPathPosix: string;
+        sha256: string;
+    };
+    wbsTitle: string;
+    wbsGoal: string;
+    /** From C8, never from model output. */
+    taskId: string;
+    /** Supplied by C3 so this function stays pure. */
+    createdAt: string;
+    concurrency: number;
+    /** Default 2, same as `ingest.ts`. */
+    maxHealingAttempts?: number;
+    /** Rendered `[after: n]` hint, advisory only. */
+    sequencingNote?: string;
+    tokenUsage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+/** Deterministic node id: `<stage>-<first 6 hex of sha256(taskId + "#" + i)>`. */
+export declare function detailedNodeId(stage: string, taskId: string, index: number): string;
+/**
+ * Build the TaskSpec and the DAG. `dag[0].status === "ready"`, all others
+ * `"pending"` — exactly what `findResumableTasks()` accepts for an unstarted run.
+ */
+export declare function buildDetailedRun(input: DetailedRunInput): {
+    spec: TaskRun["spec"];
+    dag: SubtaskNode[];
+};

package/dist/task-ingest/detailed-run.js

@@ -0,0 +1,108 @@
+// xcoder:version 1 | xcoder:task task-7a4850 | xcoder:updated 2026-10-25T16:25:29.383Z | xcoder:subtask code-st-892a22
+// C7 — PURE mapping from (pending item + architect detail) to a multi-node
+// TaskRun body. Mirrors `buildIngestedRun` but produces one node per architect
+// stage instead of one node per bullet.
+//
+// No I/O, no clock, no randomness, no LLM. Everything that varies (taskId,
+// createdAt) is supplied by C3, so identical inputs produce byte-identical JSON.
+//
+// The enforceable meaning of "use the architect to define the content of each
+// task": the architect contributes PROSE ONLY. Ids, roles, dependencies,
+// statuses and the canonical deliverable/acceptance vocabulary are all computed
+// here in code. A criterion produced from model text is always `type: "rubric"`,
+// never `"command"` — no model string can ever become something that executes.
+import crypto from "node:crypto";
+import { getStageRole } from "../sdlc-runtime/sdlc-skill.js";
+import { deliverableFor, acceptanceCriteriaFor } from "../orchestrator/task-factory.js";
+/** Deterministic node id: `<stage>-<first 6 hex of sha256(taskId + "#" + i)>`. */
+export function detailedNodeId(stage, taskId, index) {
+    const digest = crypto.createHash("sha256").update(`${taskId}#${index}`).digest("hex");
+    return `${stage}-${digest.slice(0, 6)}`;
+}
+/** One line, whitespace collapsed, length-capped. */
+function oneLine(text, max) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length > max ? `${flat.slice(0, max - 1).trimEnd()}…` : flat;
+}
+/**
+ * Canonical criteria for the stage, then the architect's rubrics.
+ *
+ * Canonical entries are preserved (description included) but any `command`-typed
+ * one is downgraded to a rubric that names the command as informational text:
+ * an extracted task is data on disk, and the design forbids a command-typed
+ * criterion anywhere in it. Model-supplied rubrics are ALWAYS `type: "rubric"`.
+ */
+function criteriaFrom(stage, rubrics) {
+    const canonical = acceptanceCriteriaFor(stage).map((c) => c.type === "command"
+        ? {
+            id: c.id,
+            type: "rubric",
+            description: c.command ? `${c.description} (verify by running: ${c.command})` : c.description,
+        }
+        : { ...c });
+    const mapped = rubrics.map((description, i) => ({
+        id: `ac-${i + 1}`,
+        type: "rubric",
+        description,
+    }));
+    return [...canonical, ...mapped];
+}
+function finalNodeAppendix(detail) {
+    const parts = [];
+    parts.push(`Verification: ${oneLine(detail.verification, 600)}`);
+    if (detail.risks && detail.risks.length > 0) {
+        parts.push(`Risks: ${detail.risks.map((r) => oneLine(r, 400)).join("; ")}`);
+    }
+    return parts.join("\n");
+}
+/**
+ * Build the TaskSpec and the DAG. `dag[0].status === "ready"`, all others
+ * `"pending"` — exactly what `findResumableTasks()` accepts for an unstarted run.
+ */
+export function buildDetailedRun(input) {
+    const { item, detail, source, taskId, createdAt, concurrency } = input;
+    const maxHealingAttempts = input.maxHealingAttempts ?? 2;
+    const spec = {
+        taskId,
+        goal: oneLine(detail.objective, 200),
+        // Deliberately EXACTLY freeText + sourcePath. code / design / url /
+        // defectDetail / credentialRef are never populated from file or model
+        // content — that is what would let a hostile document steer intake
+        // classification or a credential lookup.
+        inputs: { freeText: item.normalized, sourcePath: source.relPathPosix },
+        constraints: { maxHealingAttempts, concurrency },
+        createdAt,
+        provenance: {
+            sourcePath: source.relPathPosix,
+            sourceSha256: source.sha256,
+            ingestedAt: createdAt,
+            ingestVersion: 1,
+        },
+    };
+    const dag = [];
+    const lastIndex = detail.stages.length - 1;
+    for (const [i, stageDetail] of detail.stages.entries()) {
+        const stage = stageDetail.stage;
+        const id = detailedNodeId(stage, taskId, i);
+        const goalLines = [`${oneLine(detail.objective, 200)}\nSource item: "${item.normalized}"`];
+        if (i === 0 && input.sequencingNote)
+            goalLines.push(`Sequencing hint: ${input.sequencingNote}`);
+        let deliverableSpec = `${deliverableFor(stage)}\n\n${oneLine(stageDetail.deliverable, 600)}`;
+        if (i === lastIndex)
+            deliverableSpec += `\n\n${finalNodeAppendix(detail)}`;
+        dag.push({
+            id,
+            stage,
+            role: getStageRole(stage, spec.inputs),
+            engine: "react-v1",
+            dependsOn: i === 0 ? [] : [dag[i - 1].id],
+            goal: goalLines.join("\n"),
+            upstreamContext: {},
+            deliverableSpec,
+            acceptanceCriteria: criteriaFrom(stage, stageDetail.acceptanceCriteria),
+            status: i === 0 ? "ready" : "pending",
+            healing: { attempts: 0, maxAttempts: maxHealingAttempts, log: [] },
+        });
+    }
+    return { spec, dag };
+}

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

@@ -0,0 +1,9 @@
+/** Version-salted like INGEST_VERSION_SALT so the scheme can evolve safely. */
+export declare const EXTRACT_VERSION_SALT = "wbc-extract:v1";
+/**
+ * task-<first N hex of sha256(salt \0 relPathPosix \0 normalizedItemText)>
+ *
+ * Deterministic across runs and machines; independent of line number, index,
+ * clock, and every byte of model output.
+ */
+export declare function deriveItemTaskId(relPathPosix: string, normalizedItemText: string, hexLength?: 8 | 12): string;

package/dist/task-ingest/extract-id.js

@@ -0,0 +1,24 @@
+// xcoder:version 1 | xcoder:task task-7a4850 | xcoder:updated 2026-10-25T16:24:31.487Z | xcoder:subtask code-st-892a22
+// C8 — item-scoped task id derivation for `--wbc` extraction.
+//
+// `deriveTaskId(relPathPosix)` in `ingest.ts` hashes ONLY the source path,
+// because there one file means one task. Here one file means *n* tasks, so the
+// id must also cover the item. The hash never sees model output, a line
+// number, an index, or the clock — only the workspace-relative source path and
+// the normalised item text (PRM-08: model output never determines a file name).
+import crypto from "node:crypto";
+/** Version-salted like INGEST_VERSION_SALT so the scheme can evolve safely. */
+export const EXTRACT_VERSION_SALT = "wbc-extract:v1";
+/**
+ * task-<first N hex of sha256(salt \0 relPathPosix \0 normalizedItemText)>
+ *
+ * Deterministic across runs and machines; independent of line number, index,
+ * clock, and every byte of model output.
+ */
+export function deriveItemTaskId(relPathPosix, normalizedItemText, hexLength = 8) {
+    const digest = crypto
+        .createHash("sha256")
+        .update(`${EXTRACT_VERSION_SALT}\u0000${relPathPosix}\u0000${normalizedItemText}`)
+        .digest("hex");
+    return `task-${digest.slice(0, hexLength)}`;
+}

package/dist/task-ingest/index.d.ts

@@ -0,0 +1,23 @@
+export { readSource, MAX_SOURCE_BYTES } from "./source-reader.js";
+export type { SourceFile, ReadSourceResult, ReadSourceErrorCode } from "./source-reader.js";
+export { parseWbs, ALLOWED_FRONT_MATTER_KEYS, MAX_ITEMS } from "./wbs-parser.js";
+export type { ParsedWbs, WbsItem, ParseResult, ParseErrorCode } from "./wbs-parser.js";
+export { buildIngestedRun, stageForItem, KEYWORD_STAGE_TABLE } from "./spec-builder.js";
+export type { BuildInput } from "./spec-builder.js";
+export { ingestTask, deriveTaskId, INGEST_VERSION_SALT } from "./ingest.js";
+export type { IngestOptions, IngestResult, IngestErrorCode } from "./ingest.js";
+export { listIngestedTasks } from "./list-ingested.js";
+export type { IngestedTaskInfo } from "./list-ingested.js";
+export { scanMarkdownTasks } from "./scanner.js";
+export type { ScanOptions, ScanResult, ScanOutcome, ScanSkipReason } from "./scanner.js";
+export { selectPendingItems, normalizeItemText } from "./pending-filter.js";
+export type { PendingItem, Selection, SelectOptions } from "./pending-filter.js";
+export { deriveItemTaskId, EXTRACT_VERSION_SALT } from "./extract-id.js";
+export { createDeterministicDetailer, createLlmDetailer } from "./architect-detailer.js";
+export type { ArchitectDetail, ArchitectDetailer, ArchitectRequest } from "./architect-detailer.js";
+export { validateArchitectDetail } from "./detail-schema.js";
+export type { DetailValidation } from "./detail-schema.js";
+export { buildDetailedRun, detailedNodeId } from "./detailed-run.js";
+export type { DetailedRunInput } from "./detailed-run.js";
+export { extractWbsTasks } from "./wbs-extract.js";
+export type { ExtractOptions, ExtractResult, ExtractErrorCode, ExtractedTask } from "./wbs-extract.js";

package/dist/task-ingest/index.js

@@ -0,0 +1,14 @@
+// xcoder:version 3 | xcoder:task task-7a4850 | xcoder:updated 2026-10-25T16:27:07.349Z | xcoder:subtask code-st-892a22
+// Public surface of the task-ingestion module, consumed by the CLI.
+export { readSource, MAX_SOURCE_BYTES } from "./source-reader.js";
+export { parseWbs, ALLOWED_FRONT_MATTER_KEYS, MAX_ITEMS } from "./wbs-parser.js";
+export { buildIngestedRun, stageForItem, KEYWORD_STAGE_TABLE } from "./spec-builder.js";
+export { ingestTask, deriveTaskId, INGEST_VERSION_SALT } from "./ingest.js";
+export { listIngestedTasks } from "./list-ingested.js";
+export { scanMarkdownTasks } from "./scanner.js";
+export { selectPendingItems, normalizeItemText } from "./pending-filter.js";
+export { deriveItemTaskId, EXTRACT_VERSION_SALT } from "./extract-id.js";
+export { createDeterministicDetailer, createLlmDetailer } from "./architect-detailer.js";
+export { validateArchitectDetail } from "./detail-schema.js";
+export { buildDetailedRun, detailedNodeId } from "./detailed-run.js";
+export { extractWbsTasks } from "./wbs-extract.js";

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

@@ -0,0 +1,45 @@
+import type { TaskRun } from "../types.js";
+export interface IngestOptions {
+    workspaceRoot: string;
+    /** User-supplied, workspace-relative or absolute-inside-workspace. */
+    from: string;
+    /** Explicit opt-in to replace a record that already has progress. */
+    force?: boolean;
+    /** Injected for tests. */
+    now?: () => Date;
+    /** Default concurrency (the CLI's `--concurrency`, default 3). */
+    concurrency?: number;
+}
+export type IngestErrorCode = "not-found" | "outside-workspace" | "too-large" | "not-a-file" | "bad-front-matter" | "no-items" | "too-many-items" | "has-progress" | "id-collision";
+export type IngestResult = {
+    ok: true;
+    taskId: string;
+    created: boolean;
+    /** Absolute path of the written record. */
+    path: string;
+    /** Workspace-relative POSIX path of the source — what the user typed. */
+    sourcePath: string;
+    /** Stage of node 0, for the one-line summary. */
+    firstStage: string;
+    goal: string;
+    nodeCount: number;
+    nextCommand: string;
+} | {
+    ok: false;
+    exitCode: 1;
+    code: IngestErrorCode;
+    message: string;
+};
+export declare const INGEST_VERSION_SALT = "task-ingest:v1";
+/** task- plus the first 8 (or 12, on collision) hex of the salted source path. */
+export declare function deriveTaskId(relPathPosix: string, hexLength?: 8 | 12): string;
+/**
+ * Final shape assertion (enforced in code, not in a prompt). Throws on a
+ * programming error — nothing is on disk yet at this point.
+ */
+export declare function assertValidRun(run: TaskRun): void;
+/**
+ * Ingest one source file into a scannable `.xcoder/tasks/<taskId>.json`.
+ * Records intent only — it never runs the task and never spends tokens.
+ */
+export declare function ingestTask(opts: IngestOptions): Promise<IngestResult>;

package/dist/task-ingest/ingest.js

@@ -0,0 +1,163 @@
+// xcoder:version 5 | xcoder:task task-7a4850 | xcoder:updated 2026-10-25T16:25:47.979Z | xcoder:subtask code-st-892a22
+// C4 — orchestrate ingestion: derive id, enforce idempotency, persist.
+//
+// Failure model: every step can fail, none can half-write. The record only
+// touches disk at the very end, via the existing atomic tmp+rename writer in
+// `store/task-store.ts` — no new writer is introduced.
+import crypto from "node:crypto";
+import path from "node:path";
+import { loadTaskRun, saveTaskRun } from "../store/task-store.js";
+import { createXcoderPaths } from "../util/xcoder-paths.js";
+import { readSource } from "./source-reader.js";
+import { parseWbs } from "./wbs-parser.js";
+import { buildIngestedRun } from "./spec-builder.js";
+export const INGEST_VERSION_SALT = "task-ingest:v1";
+/** task- plus the first 8 (or 12, on collision) hex of the salted source path. */
+export function deriveTaskId(relPathPosix, hexLength = 8) {
+    const digest = crypto
+        .createHash("sha256")
+        .update(`${INGEST_VERSION_SALT}\u0000${relPathPosix}`)
+        .digest("hex");
+    return `task-${digest.slice(0, hexLength)}`;
+}
+const PROGRESS_STATUSES = new Set(["done", "in_progress", "validating", "healing"]);
+function hasProgress(run) {
+    return run.dag.some((n) => PROGRESS_STATUSES.has(n.status));
+}
+const SDLC_STAGES = [
+    "requirements",
+    "design",
+    "code",
+    "refactor",
+    "test",
+    "ui_api_test",
+    "fix_defect",
+    "document",
+    "deploy",
+    "conversation",
+    "quality_gate",
+];
+const ROLES = [
+    "requirements-analyst",
+    "architect",
+    "programmer",
+    "refactorer",
+    "tester",
+    "ui-api-tester",
+    "technical-writer",
+    "devops",
+    "conversation",
+    "business-analyst",
+    "defect-manager",
+    "scrum-master",
+    "system-architect",
+    "security-lead",
+];
+/**
+ * Final shape assertion (enforced in code, not in a prompt). Throws on a
+ * programming error — nothing is on disk yet at this point.
+ */
+export function assertValidRun(run) {
+    if (!run.spec.taskId)
+        throw new Error("ingest: taskId missing");
+    if (run.dag.length < 1)
+        throw new Error("ingest: dag must have at least one node");
+    for (const node of run.dag) {
+        for (const key of [
+            "id",
+            "stage",
+            "role",
+            "engine",
+            "dependsOn",
+            "goal",
+            "deliverableSpec",
+            "acceptanceCriteria",
+            "status",
+        ]) {
+            if (node[key] === undefined)
+                throw new Error(`ingest: node ${node.id} is missing "${key}"`);
+        }
+        if (!SDLC_STAGES.includes(node.stage))
+            throw new Error(`ingest: node ${node.id} has invalid stage "${node.stage}"`);
+        if (!ROLES.includes(node.role))
+            throw new Error(`ingest: node ${node.id} has invalid role "${node.role}"`);
+    }
+}
+function fail(code, message) {
+    return { ok: false, exitCode: 1, code, message };
+}
+/**
+ * Ingest one source file into a scannable `.xcoder/tasks/<taskId>.json`.
+ * Records intent only — it never runs the task and never spends tokens.
+ */
+export async function ingestTask(opts) {
+    const root = path.resolve(opts.workspaceRoot);
+    // 1. Read + confine.
+    const source = await readSource(root, opts.from);
+    if (!source.ok)
+        return fail(source.code, source.message);
+    const src = source.value;
+    // 2. Parse.
+    const fileStem = path.basename(src.relPathPosix, path.extname(src.relPathPosix));
+    const parsed = parseWbs(src.bytes.toString("utf8"), fileStem);
+    if (!parsed.ok)
+        return fail(parsed.code, parsed.message);
+    // 3. Derive the id, with a documented collision fallback.
+    let taskId = deriveTaskId(src.relPathPosix, 8);
+    const existingPrimary = await loadTaskRun(root, taskId);
+    if (existingPrimary && existingPrimary.spec.inputs.sourcePath !== src.relPathPosix) {
+        taskId = deriveTaskId(src.relPathPosix, 12);
+    }
+    // 4. Idempotency / progress guard.
+    const existing = await loadTaskRun(root, taskId);
+    let createdAt = (opts.now ?? (() => new Date()))().toISOString();
+    let created = true;
+    if (existing) {
+        if (existing.spec.inputs.sourcePath !== src.relPathPosix) {
+            return fail("id-collision", `derived id ${taskId} already belongs to a different source (${existing.spec.inputs.sourcePath ?? "<free-text>"})`);
+        }
+        if (hasProgress(existing) && !opts.force) {
+            return fail("has-progress", `${taskId} already has completed or in-flight subtasks — re-run with --force to replace it`);
+        }
+        created = false;
+        // Preserve the original timestamp so an unchanged source re-ingests to a
+        // byte-identical file.
+        if (existing.spec.createdAt)
+            createdAt = existing.spec.createdAt;
+    }
+    // 5. Pure build.
+    const { spec, dag } = buildIngestedRun({
+        parsed: parsed.value,
+        source: { relPathPosix: src.relPathPosix, sha256: src.sha256 },
+        taskId,
+        createdAt,
+        concurrency: opts.concurrency ?? 3,
+    });
+    const run = {
+        spec,
+        dag,
+        // `halted` is the only status `findResumableTasks()` accepts for a task
+        // that has not run yet; `running` would be reconciled away on next start
+        // and `done` would have nothing to resume.
+        status: "halted",
+        escalations: [],
+        orchestratorTrace: [],
+        finalDeliverable: `Ingested from ${src.relPathPosix} — ${dag.length} subtask${dag.length === 1 ? "" : "s"}, not yet started. Resume with: xcoder resume ${taskId}`,
+        totalTokenUsage: { inputTokens: 0, outputTokens: 0 },
+    };
+    // 6. Shape assertion — throws before anything is written.
+    assertValidRun(run);
+    // 7-8. Persist + report.
+    await saveTaskRun(root, run);
+    return {
+        ok: true,
+        taskId,
+        created,
+        path: createXcoderPaths(root).taskFile(taskId),
+        sourcePath: src.relPathPosix,
+        firstStage: dag[0].stage,
+        goal: spec.goal,
+        nodeCount: dag.length,
+        nextCommand: `xcoder resume ${taskId}`,
+    };
+}

package/dist/task-ingest/list-ingested.d.ts

@@ -0,0 +1,13 @@
+export interface IngestedTaskInfo {
+    taskId: string;
+    status: string;
+    goal: string;
+    sourcePath: string | null;
+    nodeCount: number;
+    createdAt: string;
+}
+/**
+ * Every task run on disk, newest first. `sourcePath` is non-null only for
+ * records created by `task add --from`.
+ */
+export declare function listIngestedTasks(root: string): Promise<IngestedTaskInfo[]>;

package/dist/task-ingest/list-ingested.js

@@ -0,0 +1,30 @@
+// xcoder:version 1 | xcoder:task task-a91099 | xcoder:updated 2026-10-23T10:53:15.310Z | xcoder:subtask code-st-03748c
+// Read-side helper for `xcoder task list`.
+//
+// Deliberately built on the existing `listTaskRuns()` + `loadTaskRun()` — the
+// exact functions `status`/`incomplete`/`resume` use — so "what `task list`
+// shows" and "what resume can pick up" can never disagree.
+import { listTaskRuns, loadTaskRun } from "../store/task-store.js";
+/**
+ * Every task run on disk, newest first. `sourcePath` is non-null only for
+ * records created by `task add --from`.
+ */
+export async function listIngestedTasks(root) {
+    const ids = await listTaskRuns(root);
+    const out = [];
+    for (const id of ids) {
+        const run = await loadTaskRun(root, id);
+        if (!run)
+            continue;
+        out.push({
+            taskId: id,
+            status: run.status,
+            goal: run.spec.goal ?? "",
+            sourcePath: run.spec.provenance?.sourcePath ?? run.spec.inputs.sourcePath ?? null,
+            nodeCount: run.dag?.length ?? 0,
+            createdAt: run.spec.createdAt ?? "",
+        });
+    }
+    out.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+    return out;
+}

package/dist/task-ingest/pending-filter.d.ts

@@ -0,0 +1,30 @@
+import type { ParsedWbs, WbsItem } from "./wbs-parser.js";
+export interface PendingItem extends WbsItem {
+    /** Normalised, length-capped text — the ONLY text used for ids and prompts. */
+    normalized: string;
+}
+export interface SelectOptions {
+    /** Upper bound on returned items, default MAX_ITEMS from wbs-parser. */
+    maxItems?: number;
+    /** Characters kept per item, default 400. Longer text is truncated, never rejected. */
+    maxChars?: number;
+}
+export interface Selection {
+    /** Unchecked items only, in source order. `checked === true` is excluded. */
+    pending: PendingItem[];
+    /** Count only — checked item TEXT is never echoed, logged or prompted. */
+    checkedCount: number;
+}
+/** Default per-item character budget. */
+export declare const DEFAULT_MAX_CHARS = 400;
+/**
+ * Pure. Strip invisible/terminal-control code points, collapse all whitespace
+ * runs to a single space, trim, then truncate to `maxChars`.
+ */
+export declare function normalizeItemText(text: string, maxChars?: number): string;
+/**
+ * Pure. Normalise every item, drop `checked === true`, and preserve source
+ * order. Checked items contribute to the count only — their text never leaves
+ * this function.
+ */
+export declare function selectPendingItems(parsed: ParsedWbs, opts?: SelectOptions): Selection;

package/dist/task-ingest/pending-filter.js

@@ -0,0 +1,59 @@
+// xcoder:version 1 | xcoder:task task-7a4850 | xcoder:updated 2026-10-25T16:24:39.159Z | xcoder:subtask code-st-892a22
+// C4 — pure selector that turns a parsed WBS into the list of PENDING items.
+//
+// `WbsItem.checked` is already produced by the parser and was previously
+// ignored by `buildIngestedRun`. Honouring it here — in one small pure function
+// with its own tests — is cheaper and safer than threading a filter flag
+// through the existing builder, which `task add --from` must keep calling
+// unchanged.
+//
+// Normalisation is the security-relevant half: item text is untrusted (PRM-01)
+// and is the ONLY text used for ids and prompts, so it is stripped of terminal
+// controls, zero-width and bidi characters and length-capped before it can
+// reach a hash or a model.
+import { MAX_ITEMS } from "./wbs-parser.js";
+/** Default per-item character budget. */
+export const DEFAULT_MAX_CHARS = 400;
+const ZERO_WIDTH = /[\u200b-\u200d\u2060\ufeff]/g;
+const BIDI = /[\u202a-\u202e\u2066-\u2069]/g;
+// All C0/C1 controls including tab/CR/LF — they are collapsed to a space below.
+const CONTROLS = /[\u0000-\u001f\u007f-\u009f]/g;
+/**
+ * Pure. Strip invisible/terminal-control code points, collapse all whitespace
+ * runs to a single space, trim, then truncate to `maxChars`.
+ */
+export function normalizeItemText(text, maxChars = DEFAULT_MAX_CHARS) {
+    if (typeof text !== "string")
+        return "";
+    let out = text.replace(ZERO_WIDTH, "").replace(BIDI, "");
+    out = out.replace(CONTROLS, " ");
+    out = out.replace(/\s+/g, " ").trim();
+    const cap = Number.isFinite(maxChars) && maxChars > 0 ? Math.floor(maxChars) : DEFAULT_MAX_CHARS;
+    return out.length > cap ? out.slice(0, cap).trimEnd() : out;
+}
+/**
+ * Pure. Normalise every item, drop `checked === true`, and preserve source
+ * order. Checked items contribute to the count only — their text never leaves
+ * this function.
+ */
+export function selectPendingItems(parsed, opts = {}) {
+    const maxChars = opts.maxChars ?? DEFAULT_MAX_CHARS;
+    const maxItems = Number.isFinite(opts.maxItems) && opts.maxItems > 0
+        ? Math.floor(opts.maxItems)
+        : MAX_ITEMS;
+    const pending = [];
+    let checkedCount = 0;
+    for (const item of parsed.items) {
+        if (item.checked) {
+            checkedCount += 1;
+            continue;
+        }
+        const normalized = normalizeItemText(item.text, maxChars);
+        if (normalized.length === 0)
+            continue;
+        if (pending.length >= maxItems)
+            continue;
+        pending.push({ ...item, normalized });
+    }
+    return { pending, checkedCount };
+}

package/dist/task-ingest/scanner.d.ts

@@ -0,0 +1,56 @@
+/** Why a candidate `.md` was deliberately not turned into a task run. */
+export type ScanSkipReason = "progress-summary" | "not-a-task" | "has-progress" | "id-collision" | "bad-source";
+export interface ScanOutcome {
+    /** Workspace-relative POSIX path of the candidate. */
+    sourcePath: string;
+    /** Present once an id could be derived (created/unchanged and some skips). */
+    taskId?: string;
+    status: "created" | "unchanged" | "skipped" | "failed";
+    reason?: ScanSkipReason;
+    /** `IngestErrorCode` (or parse/read code) for skipped and failed outcomes. */
+    code?: string;
+    message?: string;
+}
+export interface ScanResult {
+    /** Workspace-relative POSIX path of the directory that was scanned. */
+    dir: string;
+    /** Number of `.md` candidates considered (excludes ignored names). */
+    scanned: number;
+    created: ScanOutcome[];
+    unchanged: ScanOutcome[];
+    skipped: ScanOutcome[];
+    failed: ScanOutcome[];
+    /**
+     * Set when the directory itself could not be scanned (missing, not a
+     * directory, or outside the workspace). Per-file problems never land here —
+     * those are isolated into `failed`.
+     */
+    dirError?: {
+        code: "not-found" | "not-a-directory" | "outside-workspace";
+        message: string;
+    };
+}
+export interface ScanOptions {
+    workspaceRoot: string;
+    /**
+     * Directory to scan, workspace-relative or absolute-inside-workspace.
+     * Defaults to the task store's directory (`<.xcoder>/tasks/`).
+     */
+    dir?: string;
+    /** Report what would happen without writing anything. */
+    dryRun?: boolean;
+    /** Forwarded to `ingestTask` — never implied. */
+    force?: boolean;
+    /** Forwarded to `ingestTask`. */
+    concurrency?: number;
+    /** Injected for tests. */
+    now?: () => Date;
+}
+/**
+ * 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 declare function scanMarkdownTasks(opts: ScanOptions): Promise<ScanResult>;