spec-ctx 0.1.1 → 0.2.0

package/dist/init/init.js

@@ -1,10 +1,14 @@
-// REQ-DIST-002 REQ-SCH-003 REQ-SKL-002 specctx init: config file, schema bundle, skills.
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+// REQ-DIST-002 REQ-SCH-003 REQ-SKL-002 specctx init: config file, ID templates and config rules, skills.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { ASSETS } from "../assets.generated.js";
 import { UsageExit } from "../cli/errors.js";
-import { CONFIG_FILE, INIT_TEXT } from "../config.js";
+import { CONFIG_FILE, DEFAULT_OPENSPEC, INIT_TEXT } from "../config.js";
 export const SCHEMA = "spec-driven-ids";
+/** REQ-SCH-003 where the templates land in a project. Upstream reads no project override for the stock templates, so this is a reference path (025/D4). */
+export const TEMPLATES_DIR = `openspec/templates/${SCHEMA}`;
+const TEMPLATES_SRC = `schemas/${SCHEMA}/templates/`;
 export const SKILL_DIRS = [".claude/skills", ".agents/skills"];
 function asset(rel) {
     const b64 = ASSETS[rel];
@@ -12,12 +16,48 @@ function asset(rel) {
         throw new Error(`asset ${rel} is missing from the package`);
     return Buffer.from(b64, "base64");
 }
+/** REQ-DIST-002 the note when the OpenSpec version is unknown (022/D2). Strict mode. */
+export const OPENSPEC_NOTE = "note: could not read the OpenSpec version. [gate] openspec uses @latest.";
+export const DETECT_TIMEOUT_MS = 60_000;
+/**
+ * REQ-DIST-002 the OpenSpec command that init writes into [gate] openspec (022/D2, ADR-006 item 10).
+ * The env var SPECCTX_OPENSPEC wins. Else `npx -y @fission-ai/openspec@latest --version` gives the pin.
+ * A failure, a timeout, or output without a version keeps @latest and adds the note.
+ */
+export function detectOpenspec(timeoutMs = DETECT_TIMEOUT_MS) {
+    const env = process.env.SPECCTX_OPENSPEC;
+    if (env !== undefined && env.trim())
+        return { command: env };
+    const [cmd, ...args] = DEFAULT_OPENSPEC.split(" ");
+    const r = spawnSync(cmd, [...args, "--version"], { encoding: "utf8", timeout: timeoutMs, stdio: ["ignore", "pipe", "ignore"] });
+    const m = r.status === 0 && !r.error ? /\d+\.\d+\.\d+/.exec(r.stdout ?? "") : null;
+    if (!m)
+        return { command: DEFAULT_OPENSPEC, note: OPENSPEC_NOTE };
+    return { command: `npx -y @fission-ai/openspec@${m[0]}` };
+}
+/**
+ * REQ-DIST-002 the config text for one project (017/D4). `tests/**` becomes `test/**` when only `test/`
+ * exists at the root. `src/**` becomes `lib/**` when only `lib/` exists. The comments stay.
+ * `openspec` replaces the default command on the `openspec = ` line (022/D2).
+ */
+export function configText(root, openspec = DEFAULT_OPENSPEC) {
+    const isDir = (d) => existsSync(join(root, d)) && statSync(join(root, d)).isDirectory();
+    let text = INIT_TEXT;
+    if (!isDir("tests") && isDir("test"))
+        text = text.replace('\ntests = ["tests/**"]\n', '\ntests = ["test/**"]\n');
+    if (!isDir("src") && isDir("lib"))
+        text = text.replace('\ncode = ["src/**"]\n', '\ncode = ["lib/**"]\n');
+    if (openspec !== DEFAULT_OPENSPEC)
+        text = text.replace(`\nopenspec = "${DEFAULT_OPENSPEC}"\n`, `\nopenspec = ${JSON.stringify(openspec)}\n`);
+    return text;
+}
 /** Target path relative to the project root for every file that init installs, with its bytes. */
-export function plan(o) {
-    const out = [[CONFIG_FILE, Buffer.from(INIT_TEXT)]];
+export function plan(o, root, openspec = DEFAULT_OPENSPEC) {
+    const out = [[CONFIG_FILE, Buffer.from(configText(root, openspec))]];
     for (const rel of Object.keys(ASSETS).sort()) {
-        if (o.schema && rel.startsWith(`schemas/${SCHEMA}/`) && !rel.endsWith("/config-fragment.yaml")) {
-            out.push([`openspec/${rel}`, asset(rel)]);
+        // REQ-SCH-003 only the four templates land in the project. The fragment merges into config.yaml. No schema folder (025/D3)
+        if (o.schema && rel.startsWith(TEMPLATES_SRC)) {
+            out.push([`${TEMPLATES_DIR}/${rel.slice(TEMPLATES_SRC.length)}`, asset(rel)]);
         }
         if (o.skills && rel.startsWith("skills/")) {
             for (const d of SKILL_DIRS)
@@ -87,32 +127,166 @@ export function repairItems(text) {
     });
     return { text: out.join("\n"), fixed };
 }
+const indentOf = (line) => /^[ \t]*/.exec(line)[0].length;
+/** The value of a YAML list item without its single or double quotes, so two spellings of one rule compare equal. */
+function itemValue(line) {
+    const v = line.replace(/^\s*- /, "").trim();
+    const m = /^'(.*)'$/s.exec(v);
+    if (m)
+        return m[1].replace(/''/g, "'");
+    const d = /^"(.*)"$/s.exec(v);
+    return d ? d[1] : v;
+}
+/**
+ * The line range of a nested key inside `lines[start, end)`, where every line has an indent above `parent`.
+ * Returns the key line, the end of its range, and its indent. Null when the key is absent.
+ */
+function findChild(lines, start, end, parent, key) {
+    for (let i = start; i < end; i++) {
+        const line = lines[i];
+        if (!line.trim())
+            continue;
+        const ind = indentOf(line);
+        if (ind <= parent)
+            break;
+        const m = new RegExp(`^[ \\t]*${key.replace(/[.*+?^${}()|[\\]\\\\]/g, "\\\\$&")}:\\s*$`).exec(line);
+        if (m) {
+            let j = i + 1;
+            while (j < end && (!lines[j].trim() || indentOf(lines[j]) > ind))
+                j++;
+            // trailing blank lines belong to the next block
+            while (j > i + 1 && !lines[j - 1].trim())
+                j--;
+            return { at: i, end: j, indent: ind };
+        }
+    }
+    return null;
+}
+/** Lists of a fragment block: path segments under the top key and the item lines of each list, in order. */
+function fragmentLists(block) {
+    const out = [];
+    const stack = [];
+    let cur = null;
+    for (const line of block.split("\n").slice(1)) {
+        if (!line.trim())
+            continue;
+        const ind = indentOf(line);
+        const key = /^[ \t]*([\w-]+):\s*$/.exec(line);
+        if (key) {
+            while (stack.length && stack[stack.length - 1].indent >= ind)
+                stack.pop();
+            stack.push({ indent: ind, key: key[1] });
+            cur = null;
+        }
+        else if (/^[ \t]*- /.test(line)) {
+            if (!cur) {
+                cur = { path: stack.map((s) => s.key), items: [] };
+                out.push(cur);
+            }
+            cur.items.push(line);
+        }
+    }
+    return out;
+}
+/**
+ * REQ-SCH-003 merge the lists of one fragment block into the same top key of the project text, item by item (022/D4).
+ * An item whose value exists is skipped. A missing nested key is added with its items. Returns the count of items added.
+ */
+export function mergeItems(lines, key, block) {
+    const top = lines.findIndex((l) => new RegExp(`^${key}:`).test(l));
+    if (top < 0)
+        return 0;
+    let topEnd = top + 1;
+    while (topEnd < lines.length && (!lines[topEnd].trim() || /^[ \t]/.test(lines[topEnd]) || lines[topEnd].startsWith("#")))
+        topEnd++;
+    while (topEnd > top + 1 && !lines[topEnd - 1].trim())
+        topEnd--;
+    let added = 0;
+    for (const list of fragmentLists(block)) {
+        // walk the path. A step that is absent is appended under its parent with the items that follow it.
+        let start = top + 1;
+        let end = topEnd;
+        let parent = 0;
+        let missingFrom = -1;
+        for (let d = 0; d < list.path.length; d++) {
+            const c = findChild(lines, start, end, parent, list.path[d]);
+            if (!c) {
+                missingFrom = d;
+                break;
+            }
+            start = c.at + 1;
+            end = c.end;
+            parent = c.indent;
+        }
+        if (missingFrom >= 0) {
+            // the indent of the siblings at this level, or two more than the parent
+            let child = parent + 2;
+            for (let i = start; i < end; i++)
+                if (lines[i].trim() && !/^[ \t]*- /.test(lines[i])) {
+                    child = indentOf(lines[i]);
+                    break;
+                }
+            const ins = [];
+            let ind = child;
+            for (let d = missingFrom; d < list.path.length; d++) {
+                ins.push(" ".repeat(ind) + list.path[d] + ":");
+                ind += 2;
+            }
+            for (const item of list.items)
+                ins.push(" ".repeat(ind) + item.trim());
+            lines.splice(end, 0, ...ins);
+            topEnd += ins.length;
+            added += list.items.length;
+            continue;
+        }
+        const have = new Set();
+        let last = start - 1;
+        let itemIndent = parent + 2;
+        for (let i = start; i < end; i++) {
+            if (/^[ \t]*- /.test(lines[i])) {
+                have.add(itemValue(lines[i]));
+                last = i;
+                itemIndent = indentOf(lines[i]);
+            }
+        }
+        const ins = list.items.filter((it) => !have.has(itemValue(it))).map((it) => " ".repeat(itemIndent) + it.trim());
+        if (!ins.length)
+            continue;
+        lines.splice(last + 1, 0, ...ins);
+        topEnd += ins.length;
+        added += ins.length;
+    }
+    return added;
+}
+/** REQ-SCH-003 true when the project config still names the schema copy that 025 removed (025/D5). */
+export function hasLegacySchema(text) {
+    return text !== null && new RegExp(`^schema:\\s*${SCHEMA}\\s*$`, "m").test(text);
+}
+/** REQ-SCH-003 the note for a project that still says schema: spec-driven-ids (025/D5). Strict mode. */
+export const LEGACY_SCHEMA_NOTE = `note: schema ${SCHEMA} is no longer installed. Set schema: spec-driven in openspec/config.yaml. The rules now carry the ID instructions.`;
 /**
  * REQ-SCH-003 add each top-level key of the fragment that the project config lacks.
- * Keys that exist stay as they are. The schema key names the installed bundle.
+ * A key that exists gets the fragment items it lacks (022/D4). The schema key stays as the project wrote it (025/D5).
  */
 export function mergeConfig(current, fragment) {
     let text = current ?? "";
     const added = [];
     const kept = [];
-    const schemaLine = `schema: ${SCHEMA}`;
-    if (/^schema:.*$/m.test(text)) {
-        if (!new RegExp(`^${schemaLine}\\s*$`, "m").test(text)) {
-            text = text.replace(/^schema:.*$/m, schemaLine);
-            added.push("schema");
-        }
-    }
-    else {
-        text = schemaLine + "\n" + (text ? "\n" + text : "");
-        added.push("schema");
-    }
+    const merged = [];
     const have = topKeys(text);
     for (const [key, block] of topBlocks(fragment)) {
         if (have.has(key)) {
-            kept.push(key);
+            const lines = text.split("\n");
+            const n = mergeItems(lines, key, block);
+            if (n) {
+                text = lines.join("\n");
+                merged.push({ key, added: n });
+            }
+            else
+                kept.push(key);
             continue;
         }
-        text = text.replace(/\n*$/, "\n\n") + block;
+        text = text.trim() ? text.replace(/\n*$/, "\n\n") + block : block;
         added.push(key);
     }
     const r = repairItems(text);
@@ -120,32 +294,87 @@ export function mergeConfig(current, fragment) {
         text = r.text;
         added.push("repaired items");
     }
-    return { text, added, kept };
+    return { text, added, kept, merged };
 }
+/** REQ-DIST-002 the four lines init owns in .gitignore (017/D2, 022/D5). current.json and gate-log.jsonl are per session. */
+export const GITIGNORE_LINES = [".ctx/index.json", "adopt-report.md", ".ctx/current.json", ".ctx/gate-log.jsonl"];
+const GITIGNORE = ".gitignore";
+/** The lines of a .gitignore, trimmed, with a leading slash dropped, so `/x` and `x` compare equal. */
+function ignoreLines(text) {
+    return new Set(text.split(/\r?\n/).map((l) => l.trim().replace(/^\//, "")));
+}
+/**
+ * REQ-DIST-002 add the absent lines under a `# spec-ctx` comment. Create the file when it is missing.
+ * Returns the number of lines added, 0 when all four are present.
+ */
+export function writeGitignore(root) {
+    const p = join(root, GITIGNORE);
+    const cur = existsSync(p) ? readFileSync(p, "utf8") : null;
+    const have = cur === null ? new Set() : ignoreLines(cur);
+    const add = GITIGNORE_LINES.filter((l) => !have.has(l));
+    if (!add.length)
+        return 0;
+    const block = `# spec-ctx\n${add.join("\n")}\n`;
+    let text;
+    if (cur === null || cur === "")
+        text = block;
+    else
+        text = cur.replace(/\n*$/, "\n") + "\n" + block;
+    writeFileSync(p, text);
+    return add.length;
+}
+/** REQ-DIST-002 true when .gitignore has a line that ignores the whole .claude directory (017/D3). */
+export function ignoresClaude(root) {
+    const p = join(root, GITIGNORE);
+    if (!existsSync(p))
+        return false;
+    const lines = ignoreLines(readFileSync(p, "utf8"));
+    return lines.has(".claude") || lines.has(".claude/");
+}
+/** REQ-SCH-003 where the templates with the ID placeholders are. Printed after the schema step (018/D5, 025/D4). */
+export const TEMPLATES_NOTE = `templates: ${TEMPLATES_DIR}/ (spec.md, tasks.md hold the ID placeholders)`;
+export const CLAUDE_NOTE = "note: .gitignore ignores .claude/. The skills under .claude/skills/ stay out of git. The copies under .agents/skills/ are tracked.";
 export function runInit(root, o) {
-    const res = { written: [], kept: [], notes: [] };
-    let files = plan(o);
+    const res = { written: [], kept: [], changed: [], merged: [], notes: [] };
+    // REQ-DIST-002 the detection runs only when init writes spec-ctx.toml. An existing file stays (022/D2).
+    let openspec = DEFAULT_OPENSPEC;
+    if (!existsSync(join(root, CONFIG_FILE))) {
+        const d = detectOpenspec();
+        openspec = d.command;
+        if (d.note)
+            res.notes.push(d.note);
+    }
+    let files = plan(o, root, openspec);
     // REQ-CLI-007 every file present with the same bytes and no config key to add: nothing to do
-    const same = files.every(([rel, data]) => existsSync(join(root, rel)) && readFileSync(join(root, rel)).equals(data));
-    if (same && !o.force) {
+    // an existing spec-ctx.toml counts as present, because the user owns it (014/D4)
+    const same = files.every(([rel, data]) => existsSync(join(root, rel)) && (rel === CONFIG_FILE || readFileSync(join(root, rel)).equals(data)));
+    const ignoreDone = existsSync(join(root, GITIGNORE)) && GITIGNORE_LINES.every((l) => ignoreLines(readFileSync(join(root, GITIGNORE), "utf8")).has(l));
+    if (same && ignoreDone && !o.force) {
         const cfgPath = join(root, "openspec/config.yaml");
         const cur = existsSync(cfgPath) ? readFileSync(cfgPath, "utf8") : null;
-        if (!o.schema || !mergeConfig(cur, asset(`schemas/${SCHEMA}/config-fragment.yaml`).toString("utf8")).added.length) {
+        const m = o.schema ? mergeConfig(cur, asset(`schemas/${SCHEMA}/config-fragment.yaml`).toString("utf8")) : null;
+        if (!m || (!m.added.length && !m.merged.length)) {
             res.nothing = true;
+            if (o.skills && ignoresClaude(root))
+                res.notes.push(CLAUDE_NOTE);
+            if (o.schema && hasLegacySchema(cur))
+                res.notes.push(LEGACY_SCHEMA_NOTE);
+            if (o.schema)
+                res.notes.push(TEMPLATES_NOTE);
             return res;
         }
     }
+    // REQ-DIST-002 init never replaces spec-ctx.toml, and never fails because a file exists (014/D1)
     if (existsSync(join(root, CONFIG_FILE))) {
-        if (!o.force)
-            throw new UsageExit(`${CONFIG_FILE} exists. Use --force to install the other files over it`);
-        // --force never replaces a config that the user wrote
         files = files.filter(([rel]) => rel !== CONFIG_FILE);
         res.kept.push(CONFIG_FILE);
     }
     if (!o.force) {
-        const clash = files.filter(([rel, data]) => existsSync(join(root, rel)) && !readFileSync(join(root, rel)).equals(data));
-        if (clash.length)
-            throw new UsageExit(`these files exist with other content: ${clash.map(([r]) => r).join(", ")}. Use --force to replace them`);
+        const differs = (rel, data) => !readFileSync(join(root, rel)).equals(data);
+        res.changed = files.filter(([rel, data]) => existsSync(join(root, rel)) && differs(rel, data)).map(([rel]) => rel);
+        for (const rel of res.changed)
+            res.kept.push(`${rel} (other content)`);
+        files = files.filter(([rel]) => !existsSync(join(root, rel)));
     }
     for (const [rel, data] of files) {
         const p = join(root, rel);
@@ -157,13 +386,32 @@ export function runInit(root, o) {
         const cfgPath = join(root, "openspec/config.yaml");
         const cur = existsSync(cfgPath) ? readFileSync(cfgPath, "utf8") : null;
         const m = mergeConfig(cur, asset(`schemas/${SCHEMA}/config-fragment.yaml`).toString("utf8"));
-        if (m.added.length) {
+        if (m.added.length || m.merged.length) {
             mkdirSync(dirname(cfgPath), { recursive: true });
             writeFileSync(cfgPath, m.text);
-            res.written.push(`openspec/config.yaml (${m.added.join(", ")})`);
+            if (m.added.length)
+                res.written.push(`openspec/config.yaml (${m.added.join(", ")})`);
         }
+        // REQ-SCH-003 one line per key that gained items (022/D4)
+        for (const x of m.merged)
+            res.merged.push(`openspec/config.yaml ${x.key} (${x.added} added)`);
         for (const k of m.kept)
             res.kept.push(`openspec/config.yaml ${k}`);
+        // REQ-SCH-003 the schema line is the user's. A legacy value gets a note and stays (025/D5)
+        if (hasLegacySchema(cur))
+            res.notes.push(LEGACY_SCHEMA_NOTE);
     }
+    // REQ-DIST-002 the four .gitignore lines (017/D2, 022/D5)
+    const added = writeGitignore(root);
+    if (added)
+        res.written.push(`${GITIGNORE} (${added} line${added === 1 ? "" : "s"})`);
+    else
+        res.kept.push(GITIGNORE);
+    // REQ-DIST-002 skills under an ignored .claude/ never reach git (017/D3)
+    if (o.skills && ignoresClaude(root))
+        res.notes.push(CLAUDE_NOTE);
+    // REQ-SCH-003 the templates line comes last, right before next: (018/D5)
+    if (o.schema)
+        res.notes.push(TEMPLATES_NOTE);
     return res;
 }

package/dist/lint/counts.js

@@ -0,0 +1,60 @@
+// REQ-ADOPT-007 hard lint findings per file and rule on the gate globs. One count per key, so the baseline survives line shifts.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { markdownFiles } from "../cli/gate.js";
+import { lintSte } from "./ste.js";
+import { lintTells } from "./tells.js";
+/** Rules that the gate never counts. The repo lints by hand with the same disable. */
+const SKIP = new Set(["synonym-rotation"]);
+export const LINT_PREFIX = "lint ";
+/** Key of one lint count: `lint <file> <linter>:<rule>`. */
+export const lintKey = (file, linter, rule) => `${LINT_PREFIX}${file} ${linter}:${rule}`;
+/** Hard findings per `lint <file> <linter>:<rule>` for the markdown globs. Files with no hard finding give no key. */
+export function lintCounts(root, globs) {
+    const counts = new Map();
+    const files = markdownFiles(root, globs);
+    for (const f of files) {
+        const text = readFileSync(join(root, f), "utf8").replace(/\r\n?/g, "\n");
+        for (const x of lintTells(text)) {
+            if (x.level !== "hard")
+                continue;
+            const k = lintKey(f, "tells", x.rule);
+            counts.set(k, (counts.get(k) ?? 0) + 1);
+        }
+        for (const x of lintSte(text, f).findings) {
+            if (x.level !== "advisory-free" || SKIP.has(x.rule))
+                continue;
+            const k = lintKey(f, "ste", x.rule);
+            counts.set(k, (counts.get(k) ?? 0) + 1);
+        }
+    }
+    return { counts, files: files.length };
+}
+/** Parse a baseline line `lint <file> <rule> <count>`. Returns null for any other line. */
+export function parseLintLine(line) {
+    if (!line.startsWith(LINT_PREFIX))
+        return null;
+    const i = line.lastIndexOf(" ");
+    const n = Number(line.slice(i + 1));
+    if (i < 0 || !Number.isInteger(n) || n < 0)
+        return null;
+    return { key: line.slice(0, i), count: n };
+}
+export const lintLine = (key, count) => `${key} ${count}`;
+/** REQ-CLI-004 the keys whose count rose above the baseline, worst first. A key with no line has a baseline of 0. */
+export function lintRises(counts, baseline) {
+    const base = new Map();
+    for (const line of baseline ?? []) {
+        const p = parseLintLine(line);
+        if (p)
+            base.set(p.key, p.count);
+    }
+    const out = [];
+    for (const [key, current] of counts) {
+        const b = base.get(key) ?? 0;
+        if (current > b)
+            out.push({ key, current, baseline: b });
+    }
+    out.sort((a, b) => b.current - b.baseline - (a.current - a.baseline) || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+    return out;
+}

package/dist/loop/fails.js

@@ -0,0 +1,91 @@
+// REQ-LOOP-002 fail files under .ctx/evidence/<change>/<task>.fail-<n>.json and the attempt window (024/D4, 024/D5).
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { readQuestions } from "../handoff/questions.js";
+import { isFailFile } from "../tasks/evidence.js";
+import { evidenceRel } from "../tasks/tasks.js";
+import { dumps } from "../util/json.js";
+import { cmpStr } from "../util/pystr.js";
+import { isoNow } from "../util/time.js";
+/** Every fail file of a task, parsed, in `at` order. A damaged file is skipped. */
+export function readFails(root, task) {
+    const rel = evidenceRel({ id: task });
+    const dir = dirname(join(root, rel));
+    const base = rel.slice(rel.lastIndexOf("/") + 1, -".json".length);
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const n of readdirSync(dir)) {
+        if (!n.startsWith(`${base}.fail-`) || !isFailFile(n))
+            continue;
+        try {
+            const file = JSON.parse(readFileSync(join(dir, n), "utf8"));
+            if (file.task === task && typeof file.at === "string")
+                out.push({ rel: `${dirname(rel)}/${n}`, file });
+        }
+        catch {
+            // a damaged fail file counts for nothing
+        }
+    }
+    return out.sort((a, b) => cmpStr(a.file.at, b.file.at) || cmpStr(a.rel, b.rel));
+}
+/**
+ * The start of the attempt window of a task: `current.json.started_at` when the file names the task, else the
+ * start of time. A resolved question for the task moves the start to its `resolved_at`, so a resolve resets the count.
+ */
+export function windowStart(root, task, questions) {
+    let start = "";
+    try {
+        const cur = JSON.parse(readFileSync(join(root, ".ctx/current.json"), "utf8"));
+        if (cur.task === task && typeof cur.started_at === "string")
+            start = cur.started_at;
+    }
+    catch {
+        // no current task
+    }
+    for (const q of questions ?? safeQuestions(root)) {
+        if (q.task === task && q.status === "resolved" && typeof q.resolved_at === "string" && cmpStr(q.resolved_at, start) > 0)
+            start = q.resolved_at;
+    }
+    return start;
+}
+function safeQuestions(root) {
+    try {
+        return readQuestions(root);
+    }
+    catch {
+        return [];
+    }
+}
+/** The fail files of a task inside its window, in `at` order. */
+export function failsInWindow(root, task, questions) {
+    const start = windowStart(root, task, questions);
+    return readFails(root, task).filter((f) => cmpStr(f.file.at, start) >= 0);
+}
+/** The open question that names the task, if any. */
+export function openQuestionFor(root, task, questions) {
+    return (questions ?? safeQuestions(root)).find((q) => q.task === task && q.status === "open");
+}
+/** Write the next fail file of a task. The attempt counts the window, the file number counts every fail file. */
+export function writeFail(root, task, verify, tail) {
+    const attempt = failsInWindow(root, task).length + 1;
+    const rel = evidenceRel({ id: task });
+    const base = rel.slice(0, -".json".length);
+    let n = 1;
+    while (existsSync(join(root, `${base}.fail-${n}.json`)))
+        n++;
+    const target = `${base}.fail-${n}.json`;
+    const file = { at: isoNow(), attempt, stderr_tail: tail, task, verify };
+    mkdirSync(dirname(join(root, target)), { recursive: true });
+    writeFileSync(join(root, target), dumps(file) + "\n");
+    return { rel: target, file };
+}
+/** REQ-LOOP-002 the question text at the cap. Strict mode. */
+export function capQuestion(task, attempts, tail) {
+    const first = tail.split("\n")[0]?.trim() || "no output";
+    return `task ${task} failed Verify ${attempts} times. Last: ${first}. What should change?`;
+}
+/** REQ-LOOP-002 the last line of a failed `task done` at the cap. Strict mode. */
+export function blockedLine(n) {
+    return `blocked: question ${n} written. Run specctx handoff resolve ${n} "<answer>" to continue.`;
+}