spec-ctx 0.1.2 → 0.3.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.
+// 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, loadConfig } 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,25 +16,69 @@ 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) {
+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;
 }
+/**
+ * REQ-SCH-006 wrap the ID after a requirement or scenario header prefix in square brackets (032/D1).
+ * An ID in brackets already stays. Task citations, Refs lines, and tags have no header prefix, so they stay bare.
+ */
+export function bracketForm(text) {
+    return text.replace(/(### Requirement: |#### Scenario: )((?:REQ|SCN)-[^\s\]"'`]+)/g, "$1[$2]");
+}
+/** REQ-SCH-006 the bytes of one template in the form that `brackets` names (032/D1). */
+export function templateBytes(rel, brackets) {
+    const b = asset(rel);
+    return brackets ? Buffer.from(bracketForm(b.toString("utf8"))) : b;
+}
+/** REQ-SCH-006 the config fragment in the form that `brackets` names (032/D1). */
+export function fragmentText(brackets) {
+    const t = asset(`schemas/${SCHEMA}/config-fragment.yaml`).toString("utf8");
+    return brackets ? bracketForm(t) : t;
+}
+/** REQ-SCH-006 the value of [ids] brackets, false when spec-ctx.toml is absent (032/D2). */
+export function bracketsOf(root) {
+    return existsSync(join(root, CONFIG_FILE)) ? loadConfig(root).ids.brackets : false;
+}
 /** Target path relative to the project root for every file that init installs, with its bytes. */
-export function plan(o, root) {
-    const out = [[CONFIG_FILE, Buffer.from(configText(root))]];
+export function plan(o, root, openspec = DEFAULT_OPENSPEC, brackets = false) {
+    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)}`, templateBytes(rel, brackets)]);
         }
         if (o.skills && rel.startsWith("skills/")) {
             for (const d of SKILL_DIRS)
@@ -100,32 +148,172 @@ 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) {
+export function mergeConfig(current, fragment, other) {
     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)) {
+    const blocks = topBlocks(fragment);
+    // REQ-SCH-007 an item that holds the other bracket form gets the current form in place (032/D4)
+    const swapped = other === undefined ? { text, size: 0, get: (_k) => undefined } : swapItems(text, blocks, topBlocks(other));
+    if (swapped.size)
+        text = swapped.text;
+    for (const [key, block] of blocks) {
         if (have.has(key)) {
-            kept.push(key);
+            const lines = text.split("\n");
+            const n = mergeItems(lines, key, block);
+            const r = swapped.get(key) ?? 0;
+            if (n)
+                text = lines.join("\n");
+            if (n || r)
+                merged.push(r ? { key, added: n, replaced: r } : { 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);
@@ -133,10 +321,50 @@ export function mergeConfig(current, fragment) {
         text = r.text;
         added.push("repaired items");
     }
-    return { text, added, kept };
+    return { text, added, kept, merged };
+}
+/**
+ * REQ-SCH-007 replace each project item whose value equals an item of the other form with the line of the current form (032/D4).
+ * The two fragments have the same lists in the same order, so items pair by position. The indent of the project line stays.
+ * Returns the new text and the count per top key.
+ */
+function swapItems(text, cur, other) {
+    const swap = new Map();
+    for (const [key, block] of cur) {
+        const a = fragmentLists(block);
+        const b = fragmentLists(other.get(key) ?? "");
+        a.forEach((list, i) => list.items.forEach((item, j) => {
+            const o = b[i]?.items[j];
+            if (o !== undefined && itemValue(o) !== itemValue(item))
+                swap.set(`${key}\0${itemValue(o)}`, item.trim());
+        }));
+    }
+    const counts = new Map();
+    if (!swap.size)
+        return { text, size: 0, get: (k) => counts.get(k) };
+    let top = null;
+    const lines = text.split("\n").map((line) => {
+        const m = TOP_KEY.exec(line);
+        if (m)
+            top = m[1];
+        if (!top || !/^[ \t]+- /.test(line))
+            return line;
+        const to = swap.get(`${top}\0${itemValue(line)}`);
+        if (to === undefined)
+            return line;
+        counts.set(top, (counts.get(top) ?? 0) + 1);
+        return " ".repeat(indentOf(line)) + to;
+    });
+    return { text: lines.join("\n"), size: counts.size, get: (k) => counts.get(k) };
+}
+/** REQ-SCH-007 the text of the `merged` count: added, replaced, or both (032/D4). */
+export function mergedCount(x) {
+    if (!x.replaced)
+        return `${x.added} added`;
+    return x.added ? `${x.added} added, ${x.replaced} replaced` : `${x.replaced} replaced`;
 }
-/** REQ-DIST-002 the two lines init owns in .gitignore (017/D2). */
-export const GITIGNORE_LINES = [".ctx/index.json", "adopt-report.md"];
+/** 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) {
@@ -144,7 +372,7 @@ function ignoreLines(text) {
 }
 /**
  * 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 both are present.
+ * Returns the number of lines added, 0 when all four are present.
  */
 export function writeGitignore(root) {
     const p = join(root, GITIGNORE);
@@ -170,10 +398,24 @@ export function ignoresClaude(root) {
     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: [], changed: [], notes: [] };
-    let files = plan(o, root);
+    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);
+    }
+    // REQ-SCH-006 the form of the templates and the rules follows [ids] brackets (032/D2)
+    const brackets = bracketsOf(root);
+    const fragment = fragmentText(brackets);
+    const otherFragment = fragmentText(!brackets);
+    let files = plan(o, root, openspec, brackets);
     // REQ-CLI-007 every file present with the same bytes and no config key to add: nothing to do
     // 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)));
@@ -181,10 +423,15 @@ export function runInit(root, o) {
     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, fragment, otherFragment) : 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;
         }
     }
@@ -194,11 +441,16 @@ export function runInit(root, o) {
         res.kept.push(CONFIG_FILE);
     }
     if (!o.force) {
-        const differs = (rel, data) => !readFileSync(join(root, rel)).equals(data);
+        // REQ-SCH-007 a template that holds the other bracket form is unchanged, so it gets the current form (032/D3)
+        const other = new Map(plan(o, root, openspec, !brackets).filter(([rel]) => rel.startsWith(`${TEMPLATES_DIR}/`)));
+        const differs = (rel, data) => {
+            const have = readFileSync(join(root, rel));
+            return !have.equals(data) && !(other.get(rel)?.equals(have) ?? false);
+        };
         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)));
+        files = files.filter(([rel, data]) => !existsSync(join(root, rel)) || (!readFileSync(join(root, rel)).equals(data) && !differs(rel, data)));
     }
     for (const [rel, data] of files) {
         const p = join(root, rel);
@@ -209,16 +461,23 @@ export function runInit(root, o) {
     if (o.schema) {
         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) {
+        const m = mergeConfig(cur, fragment, otherFragment);
+        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} (${mergedCount(x)})`);
         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 two .gitignore lines (017/D2)
+    // 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"})`);
@@ -227,5 +486,8 @@ export function runInit(root, o) {
     // 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/loop/fails.js

@@ -0,0 +1,102 @@
+// 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.`;
+}
+/**
+ * REQ-LOOP-006 the reason line of a Verify tail (029/D3): the last line that starts with `fail:` or `FAIL` after
+ * leading spaces, else the last non-empty line, else `no output`. The match is case sensitive.
+ */
+export function failLine(tail) {
+    const lines = tail.split("\n").map((l) => l.trimEnd());
+    const hit = lines.filter((l) => /^\s*(?:fail:|FAIL)/.test(l)).at(-1);
+    if (hit !== undefined)
+        return hit.trim();
+    return lines.filter((l) => l.trim()).at(-1)?.trim() ?? "no output";
+}