spec-ctx 0.0.0-stage → 0.1.0

package/dist/config.js

@@ -0,0 +1,119 @@
+// REQ-DIST-002 spec-ctx.toml with defaults from REQ-IDX-001 and REQ-QRY-003.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "smol-toml";
+export const CONFIG_FILE = "spec-ctx.toml";
+export function defaults() {
+    return {
+        scan: {
+            specs: ["openspec/specs/**/*.md"],
+            changes: ["openspec/changes/**/*.md"],
+            decisions: ["decisions/*.md"],
+            code: ["src/**"],
+            tests: ["tests/**"],
+            ignore: [],
+        },
+        ids: { caps: [], task_pattern: "\\d+\\.\\d+", paths: {} },
+        bundle: { budget: 8000, depth: 1 },
+        verify: { timeout_s: 600 },
+    };
+}
+export class ConfigError extends Error {
+}
+function strList(v, key) {
+    if (typeof v === "string")
+        return [v];
+    if (Array.isArray(v) && v.every((x) => typeof x === "string"))
+        return v;
+    throw new ConfigError(`${CONFIG_FILE}: ${key} must be a string or a list of strings.`);
+}
+/** Read the config of a project root. A missing file gives all defaults. */
+export function loadConfig(root) {
+    const cfg = defaults();
+    const p = join(root, CONFIG_FILE);
+    if (!existsSync(p))
+        return cfg;
+    let raw;
+    try {
+        raw = parse(readFileSync(p, "utf8"));
+    }
+    catch (e) {
+        throw new ConfigError(`${CONFIG_FILE}: the file is not valid TOML. ${e.message.split("\n")[0]}`);
+    }
+    const sec = (name) => {
+        const v = raw[name];
+        return v !== null && typeof v === "object" && !Array.isArray(v) ? v : {};
+    };
+    const scan = sec("scan");
+    for (const k of Object.keys(cfg.scan)) {
+        if (k in scan)
+            cfg.scan[k] = strList(scan[k], `scan.${k}`);
+    }
+    const ids = sec("ids");
+    if ("caps" in ids)
+        cfg.ids.caps = strList(ids.caps, "ids.caps");
+    if ("task_pattern" in ids) {
+        if (typeof ids.task_pattern !== "string")
+            throw new ConfigError(`${CONFIG_FILE}: ids.task_pattern must be a string.`);
+        cfg.ids.task_pattern = ids.task_pattern;
+    }
+    if ("paths" in ids) {
+        const v = ids.paths;
+        if (v === null || typeof v !== "object" || Array.isArray(v) || !Object.values(v).every((x) => typeof x === "string")) {
+            throw new ConfigError(`${CONFIG_FILE}: ids.paths must be a table of code = "capability path".`);
+        }
+        cfg.ids.paths = { ...v };
+    }
+    const bundle = sec("bundle");
+    for (const k of ["budget", "depth"]) {
+        if (k in bundle) {
+            const v = bundle[k];
+            if (typeof v !== "number" || !Number.isInteger(v) || v < 0) {
+                throw new ConfigError(`${CONFIG_FILE}: bundle.${k} must be an integer of 0 or more.`);
+            }
+            cfg.bundle[k] = v;
+        }
+    }
+    const verify = sec("verify");
+    if ("timeout_s" in verify) {
+        const v = verify.timeout_s;
+        if (typeof v !== "number" || !(v > 0))
+            throw new ConfigError(`${CONFIG_FILE}: verify.timeout_s must be a number above 0.`);
+        cfg.verify.timeout_s = v;
+    }
+    return cfg;
+}
+/** The file that `specctx init` writes. Each key has a comment above it. */
+export const INIT_TEXT = `# spec-ctx configuration. Every key is optional. A missing key takes its default.
+
+[scan]
+# Main specs. Markdown files with requirement and scenario headers.
+specs = ["openspec/specs/**/*.md"]
+# Active and archived OpenSpec changes.
+changes = ["openspec/changes/**/*.md"]
+# Decision records.
+decisions = ["decisions/*.md"]
+# Source files that carry code tags. A code tag is a comment with a REQ ID.
+code = ["src/**"]
+# Test files that carry Covers tags and scenario IDs.
+tests = ["tests/**"]
+# Paths that the scan skips.
+ignore = []
+
+[ids]
+# Capability codes. check reports a REQ whose code is not in this list. id new accepts only these codes.
+# An empty list turns the rule off, and id new accepts any code of 2 to 6 upper case letters.
+caps = []
+# Pattern of the task number in a tasks.md checkbox.
+task_pattern = '\\d+\\.\\d+'
+
+[bundle]
+# Default character budget of a bundle.
+budget = 8000
+# Default depth of related entries in a bundle.
+depth = 1
+
+[verify]
+# Seconds before task done stops a Verify command.
+timeout_s = 600
+`;

package/dist/graph/bundle.js

@@ -0,0 +1,94 @@
+// REQ-QRY-003 canonical text with one provenance line per block, in a fixed order, within a budget.
+import { join } from "node:path";
+import { canon } from "../index/canonical.js";
+import { blockRange, readText } from "../index/scan.js";
+import { cmpTuple, cpLen, pyStrip, splitLines } from "../util/pystr.js";
+import { KIND_RANK, related } from "./related.js";
+export class Lines {
+    cache = new Map();
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    get(rpath) {
+        let l = this.cache.get(rpath);
+        if (!l)
+            this.cache.set(rpath, (l = splitLines(readText(join(this.root, rpath)))));
+        return l;
+    }
+}
+/** Markdown text of an entry. Code and test entries print no body, only their provenance line. */
+export function blockText(e, files) {
+    if (e.kind === "code" || e.kind === "test")
+        return "";
+    const lines = files.get(e.file);
+    const start = e.line - 1;
+    if (e.kind === "task")
+        return pyStrip(lines[start] ?? "") + "\n";
+    if (e.kind === "decision") {
+        const out = [lines[start] ?? ""];
+        for (const line of lines.slice(start + 1)) {
+            if (!pyStrip(line) || line.startsWith("- ") || line.startsWith("#"))
+                break;
+            out.push(line);
+        }
+        return rstrip(out.join("\n")) + "\n";
+    }
+    const [s, end] = blockRange(lines, start);
+    return rstrip(lines.slice(s, end).join("\n")) + "\n";
+}
+function rstrip(s) {
+    const t = pyStrip("x" + s);
+    return t.slice(1);
+}
+export function provenance(e, reason) {
+    return `-- ${e.id} | ${e.file}:${e.line} | ${e.status} | ${reason}\n`;
+}
+export function bundle(root, entries, wanted, budget, depth, all = false) {
+    const ids = canon(entries);
+    const blocks = [];
+    for (const i of wanted) {
+        const copies = [ids.get(i)];
+        if (all)
+            copies.push(...entries.filter((e) => e.id === i && !e.canonical));
+        for (const e of copies)
+            blocks.push([e, "requested"]);
+    }
+    const found = new Map();
+    for (const i of wanted) {
+        // decisions that reference a requested ID are included at every depth
+        for (const e of entries) {
+            if (e.kind === "decision" && e.refs.includes(i) && !found.has(e.id))
+                found.set(e.id, `decision for ${i}`);
+        }
+        for (const [r, reason] of related(entries, i, depth, all)) {
+            if (!wanted.includes(r) && !found.has(r))
+                found.set(r, reason);
+        }
+    }
+    // scenarios print inside their requirement
+    const tail = [...found.keys()].filter((r) => ids.has(r) && ids.get(r).kind !== "scn");
+    tail.sort((a, b) => cmpTuple([KIND_RANK[ids.get(a).kind] ?? 9, a], [KIND_RANK[ids.get(b).kind] ?? 9, b]));
+    for (const r of tail)
+        blocks.push([ids.get(r), found.get(r)]);
+    const files = new Lines(root);
+    const out = [];
+    const omitted = [];
+    let used = 0;
+    for (const [e, reason] of blocks) {
+        const body = blockText(e, files);
+        // a blank line closes a block with a body. Code and test paths stay one line each.
+        const t = provenance(e, reason) + body + (body ? "\n" : "");
+        const n = cpLen(t);
+        if (used + n > budget) {
+            omitted.push(e.id);
+            continue;
+        }
+        out.push(t);
+        used += n;
+    }
+    let text = out.join("");
+    if (omitted.length)
+        text += `truncated: ${omitted.length} entries omitted: ${omitted.join(", ")}\n`;
+    return { text, omitted };
+}

package/dist/graph/query.js

@@ -0,0 +1,31 @@
+// REQ-QRY-001 token AND over id, title, text. Score 3 for id, 2 for title, 1 for text, per term.
+import { poolOf } from "../index/canonical.js";
+import { matchesChange } from "../index/scan.js";
+import { cmpTuple, pySplit } from "../util/pystr.js";
+export function query(entries, args, o = {}) {
+    const terms = args.flatMap((a) => pySplit(a.toLowerCase()));
+    const hits = [];
+    for (const e of poolOf(entries, !!o.all)) {
+        if ((o.kind && e.kind !== o.kind) || (o.change && !matchesChange(e.change, o.change)))
+            continue;
+        // REQ-IDX-005 --change takes a key or a full folder name
+        const idl = e.id.toLowerCase();
+        const tl = e.title.toLowerCase();
+        const xl = e.text ?? "";
+        if (!terms.every((t) => idl.includes(t) || tl.includes(t) || xl.includes(t)))
+            continue;
+        let score = 0;
+        for (const t of terms)
+            score += 3 * +idl.includes(t) + 2 * +tl.includes(t) + +xl.includes(t);
+        hits.push([-score, e.id, e.file, e.line, e]);
+    }
+    hits.sort((a, b) => cmpTuple(a.slice(0, 4), b.slice(0, 4)));
+    let out = hits.map((h) => h[4]);
+    const limit = o.limit ?? 20;
+    if (limit > 0)
+        out = out.slice(0, limit);
+    return out;
+}
+export function queryLine(e) {
+    return `${e.id}  ${e.kind}  ${e.status}  ${e.file}:${e.line}  ${e.title}`;
+}

package/dist/graph/related.js

@@ -0,0 +1,76 @@
+// REQ-QRY-002 IDs reachable from a start ID, with the reason each one was included.
+import { canon, poolOf } from "../index/canonical.js";
+import { cmpStr, cmpTuple } from "../util/pystr.js";
+// REQ-QRY-003 fixed block order after the requested IDs
+export const KIND_RANK = { adr: 0, decision: 1, req: 2, scn: 2, task: 3, code: 4, test: 5 };
+export const REASONS = ["scenario of", "ref from", "ref to", "decision for", "task cites", "implements", "covers"];
+export function related(entries, start, depth, all = false) {
+    const pool = poolOf(entries, all);
+    const ids = canon(entries);
+    for (const e of pool)
+        if (!ids.has(e.id))
+            ids.set(e.id, e);
+    const back = new Map();
+    for (const e of pool) {
+        for (const r of e.refs) {
+            let s = back.get(r);
+            if (!s)
+                back.set(r, (s = new Set()));
+            s.add(e.id);
+        }
+    }
+    const found = new Map();
+    const add = (i, reason) => {
+        if (i !== start && !found.has(i)) {
+            found.set(i, reason);
+            return true;
+        }
+        return false;
+    };
+    const s = ids.get(start);
+    if (s && s.kind === "req")
+        for (const sid of s.scenarios ?? [])
+            add(sid, `scenario of ${start}`);
+    let frontier = [start];
+    for (let d = 0; d < depth; d++) {
+        const nxt = [];
+        for (const x of frontier) {
+            const ex = ids.get(x);
+            if (ex) {
+                for (const r of ex.refs)
+                    if (add(r, `ref from ${x}`))
+                        nxt.push(r);
+                if (ex.kind === "req") {
+                    for (const sid of ex.scenarios ?? [])
+                        if (add(sid, `scenario of ${x}`))
+                            nxt.push(sid);
+                }
+            }
+            for (const y of [...(back.get(x) ?? [])].sort(cmpStr)) {
+                const ey = ids.get(y);
+                const k = ey ? ey.kind : "?";
+                let reason;
+                if (k === "scn" && ex && (ex.scenarios ?? []).includes(y))
+                    reason = `scenario of ${x}`;
+                else if (k === "decision")
+                    reason = `decision for ${x}`;
+                else if (k === "task")
+                    reason = `task cites ${x}`;
+                else if (k === "code")
+                    reason = `implements ${x}`;
+                else if (k === "test")
+                    reason = `covers ${x}`;
+                else
+                    reason = `ref to ${x}`;
+                if (add(y, reason))
+                    nxt.push(y);
+            }
+        }
+        frontier = nxt;
+    }
+    const rank = (i) => {
+        const e = ids.get(i);
+        return [e ? (KIND_RANK[e.kind] ?? 9) : 9, i];
+    };
+    return [...found.keys()].sort((a, b) => cmpTuple(rank(a), rank(b))).map((i) => [i, found.get(i)]);
+}

package/dist/handoff/handoff.js

@@ -0,0 +1,148 @@
+// REQ-HND-001 REQ-HND-002 the generated session handoff in .ctx/handoff.md.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { UsageExit } from "../cli/errors.js";
+import { changeKey } from "../index/scan.js";
+import { listEvidence } from "../tasks/evidence.js";
+import { activeChanges, nextTask } from "../tasks/tasks.js";
+import { cmpStr, splitLines } from "../util/pystr.js";
+import { isoNow, today } from "../util/time.js";
+export const HANDOFF_PATH = ".ctx/handoff.md";
+export const CURRENT_PATH = ".ctx/current.json";
+const SCALARS = ["change", "current", "base", "as_of"];
+const LISTS = ["done", "reopened", "open_questions", "resolved"];
+function empty() {
+    return { change: "none", current: "none", base: "none", as_of: "none", done: [], reopened: [], open_questions: [], resolved: [], next: "", evidence: "" };
+}
+/** Parse a handoff file. A list item keeps its indented continuation lines. */
+export function parseHandoff(text) {
+    const h = empty();
+    let list = null;
+    for (const line of splitLines(text)) {
+        if (list && line.startsWith("- ")) {
+            list.push(line.slice(2));
+            continue;
+        }
+        if (list && /^[ \t]/.test(line) && line.trim() && list.length) {
+            list[list.length - 1] += "\n" + line;
+            continue;
+        }
+        list = null;
+        const m = /^([a-z_]+):(?: (.*))?$/.exec(line);
+        if (!m)
+            continue;
+        const key = m[1];
+        if (LISTS.includes(key))
+            list = h[key];
+        else if (SCALARS.includes(key) || key === "next" || key === "evidence") {
+            h[key] = (m[2] ?? "").trim();
+        }
+    }
+    return h;
+}
+export function renderHandoff(h) {
+    const out = ["# Handoff"];
+    for (const k of SCALARS)
+        out.push(`${k}: ${h[k]}`);
+    for (const k of LISTS) {
+        out.push(`${k}:`);
+        for (const item of h[k])
+            out.push(`- ${item}`);
+    }
+    out.push(`next: ${h.next}`, `evidence: ${h.evidence}`);
+    return out.join("\n") + "\n";
+}
+export function readHandoff(root) {
+    const p = join(root, HANDOFF_PATH);
+    return existsSync(p) ? parseHandoff(readFileSync(p).toString("utf8")) : null;
+}
+function save(root, h) {
+    mkdirSync(join(root, ".ctx"), { recursive: true });
+    writeFileSync(join(root, HANDOFF_PATH), renderHandoff(h));
+}
+export function currentTask(root) {
+    try {
+        const c = JSON.parse(readFileSync(join(root, CURRENT_PATH), "utf8"));
+        return c.task ?? "none";
+    }
+    catch {
+        return "none";
+    }
+}
+function evidenceRows(root, active) {
+    // REQ-IDX-005 evidence files name the change by its key
+    const nums = new Set(active.map(changeKey));
+    const rows = [];
+    for (const rel of listEvidence(root)) {
+        try {
+            const ev = JSON.parse(readFileSync(join(root, rel), "utf8"));
+            if (typeof ev.task === "string" && nums.has(ev.task.split("/")[0]))
+                rows.push({ task: ev.task, at: String(ev.at), kind: String(ev.kind) });
+        }
+        catch {
+            // a damaged evidence file is a check finding, not a handoff error
+        }
+    }
+    return rows;
+}
+const AT = / \(at (\S+)\)$/;
+/** Generate the handoff. Two runs with no change in between write the same bytes. */
+export function writeHandoff(root, entries) {
+    const prev = readHandoff(root);
+    const active = activeChanges(entries);
+    const next = nextTask(root, entries);
+    const rows = evidenceRows(root, active);
+    const asOf = rows.length ? rows.map((r) => r.at).sort(cmpStr).pop() : "none";
+    // the done window starts where the previous handoff ended, unless no new evidence came since
+    let base = "none";
+    if (prev)
+        base = prev.as_of === asOf ? prev.base : prev.as_of;
+    const after = (at) => base === "none" || cmpStr(at, base) > 0;
+    const h = {
+        change: next ? next.change : active[0] ?? "none",
+        current: currentTask(root),
+        base,
+        as_of: asOf,
+        done: rows.filter((r) => after(r.at)).map((r) => r.task).sort(cmpStr),
+        reopened: (prev?.reopened ?? []).filter((item) => {
+            const m = AT.exec(item.split("\n")[0]);
+            return !m || after(m[1]);
+        }),
+        open_questions: prev?.open_questions ?? [],
+        resolved: prev?.resolved ?? [],
+        next: next ? `${next.id}  ${next.text}` : "no open task",
+        evidence: `${rows.length} task(s), ${rows.filter((r) => r.kind === "command").length} command, ${rows.filter((r) => r.kind === "manual").length} manual`,
+    };
+    save(root, h);
+    return h;
+}
+function ensure(root, entries) {
+    return readHandoff(root) ?? writeHandoff(root, entries);
+}
+export function ask(root, entries, text) {
+    const q = text.replace(/\s*\n\s*/g, " ").trim();
+    if (!q)
+        throw new UsageExit("handoff ask needs a question");
+    const h = ensure(root, entries);
+    h.open_questions.push(`${q} (task ${currentTask(root)}, ${today()})`);
+    save(root, h);
+    return h;
+}
+export function resolve(root, entries, n, answer) {
+    const h = ensure(root, entries);
+    if (!Number.isInteger(n) || n < 1 || n > h.open_questions.length) {
+        throw new UsageExit(`no open question ${n}. The handoff has ${h.open_questions.length}`);
+    }
+    const a = answer.replace(/\s*\n\s*/g, " ").trim();
+    if (!a)
+        throw new UsageExit("handoff resolve needs an answer");
+    const [item] = h.open_questions.splice(n - 1, 1);
+    h.resolved.push(`${item.split("\n")[0]} answer: ${a}`);
+    save(root, h);
+    return h;
+}
+export function addReopened(root, entries, task, reason) {
+    const h = ensure(root, entries);
+    h.reopened.push(`${task} ${reason.replace(/\s*\n\s*/g, " ").trim()} (at ${isoNow()})`);
+    save(root, h);
+}

package/dist/ids/ids.js

@@ -0,0 +1,115 @@
+// REQ-IDS-001 REQ-IDS-002 REQ-IDS-003 ID allocation and retirement.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { UsageExit } from "../cli/errors.js";
+import { canon } from "../index/canonical.js";
+import { changeKey, resolveChange } from "../index/scan.js";
+import { today } from "../util/time.js";
+export const RETIRED_FILE = "decisions/retired-ids.md";
+const ANY_ID = /\b(REQ-[A-Z]{2,6}-\d{3}|SCN-[A-Z]{2,6}-\d{3}-\d+|ADR-\d{3})\b/g;
+export function retiredAll(root) {
+    const p = join(root, RETIRED_FILE);
+    if (!existsSync(p))
+        return new Set();
+    // the retired ID is the first ID of a line. A reason may name a live replacement ID.
+    const out = new Set();
+    for (const line of readFileSync(p, "utf8").split("\n")) {
+        const m = new RegExp(ANY_ID.source).exec(line);
+        if (m)
+            out.add(m[1]);
+    }
+    return out;
+}
+const pad = (n, w = 3) => String(n).padStart(w, "0");
+/** Next unused IDs. Next is one more than the highest number among all index entries and retired IDs. */
+export function newIds(root, cfg, entries, o) {
+    const kind = o.kind.toUpperCase();
+    if (!Number.isInteger(o.count) || o.count < 1)
+        throw new UsageExit("--count needs an integer of 1 or more");
+    const known = [...entries.map((e) => e.id), ...retiredAll(root)];
+    const next = (re) => {
+        let max = 0;
+        for (const id of known) {
+            const m = re.exec(id);
+            if (m)
+                max = Math.max(max, Number(m[1]));
+        }
+        return max + 1;
+    };
+    const checkCap = (cap) => {
+        if (!cap)
+            throw new UsageExit(`id new ${kind} needs a capability code`);
+        if (!/^[A-Z]{2,6}$/.test(cap))
+            throw new UsageExit(`the capability code ${cap} must be 2 to 6 upper case letters`);
+        // REQ-IDS-001 an empty caps list accepts any code. A non-empty list must hold the code.
+        if (cfg.ids.caps.length && !cfg.ids.caps.includes(cap)) {
+            throw new UsageExit(`unknown-cap ${cap}. Configured codes: ${cfg.ids.caps.join(", ")}. Add "${cap}" to caps under [ids] in spec-ctx.toml.`);
+        }
+        return cap;
+    };
+    const seq = (start, fmt) => Array.from({ length: o.count }, (_, i) => fmt(start + i));
+    switch (kind) {
+        case "REQ": {
+            const cap = checkCap(o.cap);
+            const start = next(new RegExp(`^REQ-${cap}-(\\d{3})$`));
+            if (start + o.count - 1 > 999)
+                throw new UsageExit(`no free REQ number for ${cap}`);
+            return seq(start, (n) => `REQ-${cap}-${pad(n)}`);
+        }
+        case "SCN": {
+            const cap = checkCap(o.cap);
+            if (!o.forReq)
+                throw new UsageExit("id new SCN needs --for <REQ-ID>");
+            const m = /^REQ-([A-Z]{2,6})-(\d{3})$/.exec(o.forReq);
+            if (!m || m[1] !== cap)
+                throw new UsageExit(`--for ${o.forReq} is not a REQ ID of ${cap}`);
+            const start = next(new RegExp(`^SCN-${cap}-${m[2]}-(\\d+)$`));
+            return seq(start, (n) => `SCN-${cap}-${m[2]}-${n}`);
+        }
+        case "ADR": {
+            const start = next(/^ADR-(\d{3})$/);
+            if (start + o.count - 1 > 999)
+                throw new UsageExit("no free ADR number");
+            return seq(start, (n) => `ADR-${pad(n)}`);
+        }
+        case "DEC": {
+            // REQ-IDX-005 a design decision ID is <change key>/D<n>. The CAP argument names the change by key or folder.
+            if (!o.cap)
+                throw new UsageExit("id new DEC needs a change name or key");
+            const folder = resolveChange(entries, o.cap);
+            if (folder === undefined)
+                throw new UsageExit(`no change with the key ${changeKey(o.cap)}`);
+            const num = changeKey(folder);
+            const start = next(new RegExp(`^${num.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/D(\\d+)$`));
+            return seq(start, (n) => `${num}/D${n}`);
+        }
+    }
+    throw new UsageExit(`id new needs REQ, SCN, ADR, or DEC, not ${o.kind}`);
+}
+/** Append a row to decisions/retired-ids.md. A canonical ID is still in use and stays. */
+export function retire(root, entries, id, reason) {
+    if (!/^(REQ-[A-Z]{2,6}-\d{3}|SCN-[A-Z]{2,6}-\d{3}-\d+|ADR-\d{3})$/.test(id))
+        throw new UsageExit(`${id} is not a REQ, SCN, or ADR ID`);
+    if (!reason.trim())
+        throw new UsageExit("id retire needs a reason");
+    // an archived copy is history. Only a copy in openspec/specs/ or an active change keeps the ID in use.
+    const live = canon(entries).get(id);
+    if (live && live.status !== "archived")
+        throw new UsageExit(`${id} is still in use at ${live.file}:${live.line}`);
+    if (retiredAll(root).has(id))
+        throw new UsageExit(`${id} is already retired`);
+    const p = join(root, RETIRED_FILE);
+    let text = existsSync(p) ? readFileSync(p, "utf8") : "";
+    if (!/^\| ID \| Date \| Reason \|$/m.test(text)) {
+        if (!text.trim())
+            text = "# Retired IDs\n\nIDs that were removed. Never reuse them.\n";
+        text = text.replace(/\n*$/, "\n\n") + "| ID | Date | Reason |\n| --- | --- | --- |\n";
+    }
+    else if (!text.endsWith("\n"))
+        text += "\n";
+    const row = `| ${id} | ${today()} | ${reason.trim().replace(/\|/g, "\\|").replace(/\s*\n\s*/g, " ")} |`;
+    mkdirSync(join(root, "decisions"), { recursive: true });
+    writeFileSync(p, text + row + "\n");
+    rmSync(join(root, ".ctx/index.json"), { force: true });
+    return row;
+}

package/dist/index/build.js

@@ -0,0 +1,57 @@
+// REQ-IDX-001 REQ-IDX-002 REQ-IDX-004 build, write, and load .ctx/index.json.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { dumps } from "../util/json.js";
+import { cmpStr, cmpTuple } from "../util/pystr.js";
+import { markCanonical } from "./canonical.js";
+import { scanMarkdown, scannedOf, scanner, scanSource, walk } from "./scan.js";
+export const INDEX_PATH = ".ctx/index.json";
+export function buildIndex(root, cfg, files, sc) {
+    const s = sc ?? scanner(root, cfg);
+    const list = files ?? walk(s);
+    const entries = [];
+    const problems = [];
+    const scnNamed = new Set();
+    for (const f of list) {
+        if (f.kind === "md")
+            scanMarkdown(s, f.path, entries, problems);
+        else
+            scanSource(s, f.path, entries, scnNamed);
+    }
+    markCanonical(entries);
+    entries.sort((a, b) => cmpTuple([a.id, a.file, a.line], [b.id, b.file, b.line]));
+    const uniq = new Map();
+    for (const p of problems)
+        uniq.set(JSON.stringify(p), p);
+    const probs = [...uniq.values()].sort((a, b) => cmpTuple(a, b));
+    const data = {
+        entries,
+        problems: probs,
+        scanned: scannedOf(root, list),
+        scn_named: [...scnNamed].sort(cmpStr),
+    };
+    mkdirSync(join(root, ".ctx"), { recursive: true });
+    writeFileSync(join(root, INDEX_PATH), dumps(data) + "\n");
+    return data;
+}
+/** REQ-IDX-004 compare the stored scan record with a fresh stat walk. Rebuild on a mismatch. */
+export function loadIndex(root, cfg) {
+    const sc = scanner(root, cfg);
+    const files = walk(sc);
+    const p = join(root, INDEX_PATH);
+    let data = null;
+    if (existsSync(p)) {
+        try {
+            data = JSON.parse(readFileSync(p, "utf8"));
+        }
+        catch {
+            data = null;
+        }
+    }
+    const fresh = scannedOf(root, files);
+    if (data === null || !data.scanned || data.scanned.count !== fresh.count
+        || data.scanned.newest_mtime_ms !== fresh.newest_mtime_ms || Object.keys(data.scanned).length !== 2) {
+        return { data: buildIndex(root, cfg, files, sc), rebuilt: true };
+    }
+    return { data, rebuilt: false };
+}