spec-ctx 0.1.2 → 0.2.0

package/dist/handoff/questions.js

@@ -0,0 +1,99 @@
+// REQ-HND-002 the open and resolved questions in .ctx/questions.json (022/D6, ADR-006 item 1).
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { UsageExit } from "../cli/errors.js";
+import { isoNow } from "../util/time.js";
+export const QUESTIONS_PATH = ".ctx/questions.json";
+/** The questions sorted by n. An absent file is an empty list. A damaged file is a usage error, not a crash. */
+export function readQuestions(root) {
+    const p = join(root, QUESTIONS_PATH);
+    if (!existsSync(p))
+        return [];
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(p, "utf8"));
+    }
+    catch {
+        throw new UsageExit(`${QUESTIONS_PATH} is not valid JSON`);
+    }
+    if (!Array.isArray(raw))
+        throw new UsageExit(`${QUESTIONS_PATH} must hold a JSON list`);
+    return raw.slice().sort((a, b) => a.n - b.n);
+}
+export function hasQuestions(root) {
+    return existsSync(join(root, QUESTIONS_PATH));
+}
+export function writeQuestions(root, qs) {
+    mkdirSync(join(root, ".ctx"), { recursive: true });
+    const sorted = qs.slice().sort((a, b) => a.n - b.n);
+    writeFileSync(join(root, QUESTIONS_PATH), JSON.stringify(sorted, null, 2) + "\n");
+}
+/** One line of text. A question or an answer never spans lines in the file. */
+export function oneLine(text) {
+    return text.replace(/\s*\n\s*/g, " ").trim();
+}
+/** REQ-HND-002 append an open question with the next n. Returns the new question. */
+export function addQuestion(root, task, text) {
+    const q = oneLine(text);
+    if (!q)
+        throw new UsageExit("handoff ask needs a question");
+    const qs = readQuestions(root);
+    const n = qs.reduce((m, x) => Math.max(m, x.n), 0) + 1;
+    const item = { n, asked_at: isoNow(), task, text: q, status: "open" };
+    qs.push(item);
+    writeQuestions(root, qs);
+    return item;
+}
+/** REQ-HND-002 resolve the open question n with an answer. Exit 2 when n is not an open question. */
+export function resolveQuestion(root, n, answer) {
+    const qs = readQuestions(root);
+    const item = qs.find((x) => x.n === n && x.status === "open");
+    if (!Number.isInteger(n) || !item) {
+        const open = qs.filter((x) => x.status === "open").length;
+        throw new UsageExit(`no open question ${n}. The file has ${open} open question(s)`);
+    }
+    const a = oneLine(answer);
+    if (!a)
+        throw new UsageExit("handoff resolve needs an answer");
+    item.status = "resolved";
+    item.answer = a;
+    item.resolved_at = isoNow();
+    writeQuestions(root, qs);
+    return item;
+}
+const ITEM = /^(.*) \(task (\S+), (\d{4}-\d{2}-\d{2})\)(?: answer: (.*))?$/s;
+/**
+ * REQ-HND-002 the questions of an old handoff.md as objects (022/D8). Resolved items come first, then open ones,
+ * with n from 1 in that order. An item that does not match the old pattern keeps its whole text and task none.
+ */
+export function fromHandoffItems(open, resolved) {
+    const out = [];
+    const push = (item, status) => {
+        const m = ITEM.exec(item);
+        const q = m
+            ? { n: out.length + 1, asked_at: m[3], task: m[2], text: oneLine(m[1]), status }
+            : { n: out.length + 1, asked_at: "none", task: "none", text: oneLine(item), status };
+        if (status === "resolved")
+            q.answer = m?.[4] !== undefined ? oneLine(m[4]) : "";
+        out.push(q);
+    };
+    for (const item of resolved)
+        push(item, "resolved");
+    for (const item of open)
+        push(item, "open");
+    return out;
+}
+/** The last 10 resolved entries render. The rest stay in the file. */
+export const RESOLVED_SHOWN = 10;
+/** REQ-HND-001 the two lists of handoff.md as rendered item text (022/D7). */
+export function renderQuestions(qs) {
+    const date = (q) => q.asked_at.slice(0, 10);
+    const head = (q) => `Q${q.n} ${q.text} (task ${q.task}, ${date(q)})`;
+    const open = qs.filter((q) => q.status === "open").map(head);
+    const done = qs.filter((q) => q.status === "resolved");
+    const shown = done.slice(-RESOLVED_SHOWN).map((q) => `${head(q)} answer: ${q.answer ?? ""}`);
+    const more = done.length - Math.min(done.length, RESOLVED_SHOWN);
+    if (more > 0)
+        shown.push(`and ${more} more in ${QUESTIONS_PATH}`);
+    return { open_questions: open, resolved: shown };
+}

package/dist/ids/ids.js

@@ -1,4 +1,4 @@
-// REQ-IDS-001 REQ-IDS-002 REQ-IDS-003 ID allocation and retirement.
+// REQ-IDS-001 REQ-IDS-002 REQ-IDS-003 REQ-IDS-004 ID allocation and retirement.
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { UsageExit } from "../cli/errors.js";
@@ -48,23 +48,28 @@ export function newIds(root, cfg, entries, o) {
         return cap;
     };
     const seq = (start, fmt) => Array.from({ length: o.count }, (_, i) => fmt(start + i));
+    // REQ-IDS-004 a REQ or SCN ID goes into a header, so it takes the configured form (027/D5)
+    const form = (ids) => (cfg.ids.brackets ? ids.map((id) => `[${id}]`) : ids);
     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)}`);
+            return form(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)
+            // REQ-IDS-004 --for takes the bare or the bracketed form
+            const m = /^(?:REQ-([A-Z]{2,6})-(\d{3})|\[REQ-([A-Z]{2,6})-(\d{3})\])$/.exec(o.forReq);
+            const forCap = m?.[1] ?? m?.[3];
+            const forNum = m?.[2] ?? m?.[4];
+            if (!m || forCap !== 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}`);
+            const start = next(new RegExp(`^SCN-${cap}-${forNum}-(\\d+)$`));
+            return form(seq(start, (n) => `SCN-${cap}-${forNum}-${n}`));
         }
         case "ADR": {
             const start = next(/^ADR-(\d{3})$/);

package/dist/index/scan.js

@@ -8,8 +8,10 @@ const S = "[ \\t\\n\\r\\f\\v]";
 export const ID_RE = /\b(REQ-[A-Z]{2,6}-\d{3}|SCN-[A-Z]{2,6}-\d{3}-\d+|ADR-\d{3})\b/g;
 const ID_FULL = /^(?:REQ-[A-Z]{2,6}-\d{3}|SCN-[A-Z]{2,6}-\d{3}-\d+|ADR-\d{3})$/;
 const SCN_RE = /\bSCN-[A-Z]{2,6}-\d{3}-\d+\b/g;
-const REQ_HDR = new RegExp(`^### Requirement:${S}*(REQ-[A-Z]{2,6}-\\d{3})?${S}*(.*)$`, "s");
-const SCN_HDR = new RegExp(`^#### Scenario:${S}*(SCN-[A-Z]{2,6}-\\d{3}-\\d+)?${S}*(.*)$`, "s");
+// REQ-IDX-006 the ID is bare or in square brackets, the form OpenSpec reads since PR #1979 (027/D1).
+// Group 1 is the bare ID, group 2 the bracketed ID, group 3 the title.
+const REQ_HDR = new RegExp(`^### Requirement:${S}*(?:(REQ-[A-Z]{2,6}-\\d{3})|\\[(REQ-[A-Z]{2,6}-\\d{3})\\](?=${S}|$))?${S}*(.*)$`, "s");
+const SCN_HDR = new RegExp(`^#### Scenario:${S}*(?:(SCN-[A-Z]{2,6}-\\d{3}-\\d+)|\\[(SCN-[A-Z]{2,6}-\\d{3}-\\d+)\\](?=${S}|$))?${S}*(.*)$`, "s");
 const ADR_HDR = new RegExp(`^# (ADR-\\d{3})${S}+(.*)$`, "s");
 const REFS_RE = new RegExp(`^Refs:${S}*(.+)$`, "s");
 const TASK_REQ = new RegExp(`\\[(REQ-[A-Z]{2,6}-\\d{3}(?:${S}*,${S}*REQ-[A-Z]{2,6}-\\d{3})*)\\]`, "g");
@@ -219,8 +221,8 @@ export function scanMarkdown(sc, rpath, entries, problems) {
         }
         let m = REQ_HDR.exec(line);
         if (m) {
-            const rid = m[1];
-            const title = pyStrip(m[2]);
+            const rid = m[1] ?? m[2];
+            const title = pyStrip(m[3]);
             if (!rid) {
                 // REQ-CHK-001 an archived header without an ID is history. adopt never writes it.
                 if (status !== "archived")
@@ -245,8 +247,8 @@ export function scanMarkdown(sc, rpath, entries, problems) {
         }
         m = SCN_HDR.exec(line);
         if (m) {
-            const sid = m[1];
-            const title = pyStrip(m[2]);
+            const sid = m[1] ?? m[2];
+            const title = pyStrip(m[3]);
             if (!sid) {
                 if (status !== "archived")
                     problems.push([rpath, i, "missing-id", title]);

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 } 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,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) {
+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, root) {
-    const out = [[CONFIG_FILE, Buffer.from(configText(root))]];
+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)
@@ -100,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);
@@ -133,10 +294,10 @@ 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 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 +305,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 +331,20 @@ 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);
+    }
+    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
     // 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 +352,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, 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;
         }
     }
@@ -210,15 +386,22 @@ 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 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 +410,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,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.`;
+}