spec-ctx 0.1.2 → 0.2.0

package/dist/cli/commands.js

@@ -23,7 +23,8 @@ async function runCheck(root, cfg, data, strict) {
  */
 export function checkText(r, tty) {
     // REQ-CLI-008 every finding of check is hard, so every finding line is red. stale-evidence is one of them.
-    const body = r.findings.map((x) => paint("fail", `${x.file}:${x.line}  ${x.rule}  ${x.id}\n`, tty)).join("")
+    // REQ-CHK-001 a finding with a detail, such as a retitle, carries it after the ID (021/D2)
+    const body = r.findings.map((x) => paint("fail", `${x.file}:${x.line}  ${x.rule}  ${x.id}${x.detail ? `  ${x.detail}` : ""}\n`, tty)).join("")
         + r.warnings.map((w) => `warning: ${w}\n`).join("");
     const base = r.baselined ? `baselined: ${r.baselined}\n` : "";
     const n = r.findings.length + r.warnings.length;
@@ -133,6 +134,11 @@ export async function run(p, io) {
         return runGate(root, {
             strict,
             markdown: f.markdown ?? cfg.gate.markdown.join(" "),
+            // REQ-DIST-002 the env var wins over [gate] openspec, for tests and one-off runs (018/D2)
+            openspec: process.env.SPECCTX_OPENSPEC ?? cfg.gate.openspec,
+            // REQ-ADOPT-008 the ref for the merge base, and the subject override for tests (020/D4)
+            base: cfg.gate.base,
+            baselineSubject: process.env.SPECCTX_BASELINE_SUBJECT,
             json,
             check: async () => {
                 const { buildIndex } = await import("../index/build.js");
@@ -159,7 +165,7 @@ export async function run(p, io) {
     }
     if (cmd === "bundle")
         need(1, "at least one ID");
-    if ((cmd === "status" || cmd === "check") && p.positional.length)
+    if ((cmd === "status" || cmd === "check" || cmd === "next") && p.positional.length)
         throw new UsageExit(`${cmd} takes no arguments`);
     const { data, rebuilt } = loadIndex(root, cfg);
     if (rebuilt)
@@ -181,6 +187,16 @@ export async function run(p, io) {
                 io.out(statusLines(r).map((l) => (l.startsWith("next: ") ? paint("dim", l, io.tty) : l) + "\n").join(""));
             return 0;
         }
+        case "next": {
+            // REQ-LOOP-001 the decision is a pure function of the files. --json prints the object, else the lines with next: last (024/D1).
+            const { decideNext, renderNext } = await import("../loop/next.js");
+            const d = decideNext(root, cfg, data, f.change);
+            if (json)
+                print(d);
+            else
+                io.out(renderNext(d).split("\n").map((l) => (l.startsWith("next: ") ? paint("dim", l, io.tty) : l)).join("\n"));
+            return 0;
+        }
         case "query": {
             const { query, queryLine } = await import("../graph/query.js");
             const hits = query(entries, p.positional, {
@@ -275,6 +291,7 @@ async function init(p, io) {
         io.out("nothing to do\n" + r.notes.map((n) => `${n}\n`).join("") + paint("dim", "next: specctx status\n", io.tty));
     else {
         io.out(r.written.map((w) => `wrote ${w}\n`).join(""));
+        io.out(r.merged.map((m) => `merged ${m}\n`).join(""));
         io.out(r.kept.map((k) => `kept ${k}\n`).join(""));
         io.out(r.notes.map((n) => `${n}\n`).join(""));
         // REQ-CLI-007 init ends with the next step. REQ-DIST-002 a kept changed file points to --force (014/D2).

package/dist/cli/gate.js

@@ -1,10 +1,9 @@
-// REQ-CLI-004 specctx gate: check, both linters, openspec validate, spec length. Stops at the first failure.
+// REQ-CLI-004 specctx gate: check, the baseline against the merge base, both linters, openspec validate, spec length. Stops at the first failure.
 import { spawnSync } from "node:child_process";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { anyMatch, globRe } from "../util/glob.js";
 import { cmpStr } from "../util/pystr.js";
-export const DEFAULT_MARKDOWN = "openspec/**/*.md decisions/*.md docs/**/*.md *.md";
 const SKIP = new Set(["node_modules", ".git", ".ctx", "dist", "build"]);
 export function markdownFiles(root, globs) {
     const res = globs.split(/\s+/).filter(Boolean).map(globRe);
@@ -42,7 +41,7 @@ export const GATE_LOG = ".ctx/gate-log.jsonl";
 /** REQ-STAT-005 the gate steps in order. The log names the step that failed. */
 /** REQ-CLI-004 the lint detail stops here unless --json asks for every line. */
 export const LINT_DETAIL_CAP = 50;
-export const GATE_STEPS = ["check", "lint tells", "lint ste", "validate", "spec-length"];
+export const GATE_STEPS = ["check", "baseline", "lint tells", "lint ste", "validate", "spec-length"];
 /** REQ-STAT-005 one JSON line per gate run, after the last step or at the first failure. */
 export function appendGateLog(root, line) {
     mkdirSync(join(root, ".ctx"), { recursive: true });
@@ -67,7 +66,13 @@ async function gateSteps(root, o, io, ran) {
         return "check";
     }
     io.out(`check: ok${o.strict ? " (strict)" : ""}\n`);
-    // gate 2: REQ-LINT-003 both linters of this package on the markdown globs. No python3.
+    // gate 2: REQ-ADOPT-008 the baseline may not gain entries against the merge base (020/D1 to D4)
+    ran.push("baseline");
+    const b = await baselineStep(root, o);
+    io.out(b.text);
+    if (!b.ok)
+        return "baseline";
+    // gate 3: REQ-LINT-003 both linters of this package on the markdown globs. No python3.
     // REQ-ADOPT-007 the step fails only on a count above its baseline line.
     const { lintCounts, lintRises } = await import("../lint/counts.js");
     const { readBaseline } = await import("../baseline/baseline.js");
@@ -87,16 +92,15 @@ async function gateSteps(root, o, io, ran) {
     }
     io.out(`linters: ok (${files} file(s)${baselined ? `, ${baselined} baselined` : ""})\n`);
     ran.push("validate");
-    // gate 3: openspec validate. SPECCTX_OPENSPEC replaces the command, for tests and offline use.
-    const cmd = process.env.SPECCTX_OPENSPEC ?? "npx -y @fission-ai/openspec@latest";
-    const v = spawnSync("/bin/sh", ["-c", `${cmd} validate --all${o.strict ? " --strict" : ""} --no-interactive`], { cwd: root, encoding: "utf8" });
+    // gate 4: openspec validate with the command the caller resolved (018/D2)
+    const v = spawnSync("/bin/sh", ["-c", `${o.openspec} validate --all${o.strict ? " --strict" : ""} --no-interactive`], { cwd: root, encoding: "utf8" });
     if (v.status !== 0) {
         io.out("validate: fail\n" + (v.stdout ?? "") + (v.stderr ?? ""));
         return "validate";
     }
     io.out(`validate: ok${o.strict ? " (strict)" : ""}\n`);
     ran.push("spec-length");
-    // gate 4: the length of every requirement in the deltas of active changes
+    // gate 5: the length of every requirement in the deltas of active changes
     const long = longRequirements(root);
     if (long.length) {
         io.out(long.map((l) => `spec-length: fail ${l.id} ${l.chars} chars\n`).join(""));
@@ -105,6 +109,27 @@ async function gateSteps(root, o, io, ran) {
     io.out("spec-length: ok\n");
     return null;
 }
+/** REQ-ADOPT-008 the baseline step: skipped, ok, or fail with the new entries (020/D3). */
+async function baselineStep(root, o) {
+    const { baseAtMergeBase, headSubjects, isBaselineSubject, newEntries } = await import("../baseline/ratchet.js");
+    const { readBaseline } = await import("../baseline/baseline.js");
+    const subjects = o.baselineSubject !== undefined ? [o.baselineSubject] : headSubjects(root);
+    if (subjects.some(isBaselineSubject))
+        return { ok: true, text: "baseline: ok (baseline: commit)\n" };
+    const base = baseAtMergeBase(root, o.base);
+    if ("skip" in base)
+        return { ok: true, text: `baseline: skipped (${base.skip})\n` };
+    const current = [...readBaseline(root) ?? []];
+    const fresh = newEntries(current, base.lines);
+    if (!fresh.length)
+        return { ok: true, text: "baseline: ok\n" };
+    const shown = o.json ? fresh : fresh.slice(0, LINT_DETAIL_CAP);
+    const more = fresh.length - shown.length;
+    return {
+        ok: false,
+        text: `baseline: fail, ${fresh.length} new entr${fresh.length === 1 ? "y" : "ies"}\n` + shown.map((l) => l + "\n").join("") + (more ? `... ${more} more line(s)\n` : ""),
+    };
+}
 // REQ-CLI-005 the limit strict validate applies to a requirement after archive
 export const MAX_REQUIREMENT_CHARS = 500;
 /** Lines inside a fenced code block, fence lines included. Same rule as OpenSpec. */

package/dist/cli/help.js

@@ -22,6 +22,11 @@ const LINT_EXIT = [["0", "The hard findings are at the baseline or below."], ["1
 export const TABLE = [
     // Read
     { name: "status", group: "Read", args: "", summary: "Show the active changes, the current task, and the open questions.", flags: [], exit: PLAIN, example: "specctx status" },
+    {
+        name: "next", group: "Read", args: "", summary: "Name the next action of the loop from the files on disk. Write nothing.",
+        flags: [["--change <name>", "Decide for this change. The key or the full folder name works."]],
+        exit: PLAIN, example: "specctx next --json",
+    },
     {
         name: "query", group: "Read", args: "[term...]", summary: "Find the entries that contain all terms. With --change and no term, list every entry of that change.",
         flags: [
@@ -53,7 +58,7 @@ export const TABLE = [
     },
     {
         name: "gate", group: "Read", args: "",
-        summary: "Run `check`, the markdown linters, `openspec validate`, and the length check. Stop at the first failure.",
+        summary: "Run `check`, the baseline against the merge base of [gate] base, the markdown linters, `openspec validate` with the command in [gate] openspec, and the length check. Stop at the first failure.",
         flags: [
             ["--strict", "Run `check` and `openspec validate` in strict mode."],
             ["--markdown <globs>", "Lint these markdown globs instead of [gate] markdown. Separate them with spaces."],
@@ -119,8 +124,8 @@ export const TABLE = [
     {
         name: "init", group: "Setup", args: "", summary: "Write a default spec-ctx.toml file.",
         flags: [
-            ["--schema", "Also install the spec-driven-ids schema and add its rules to openspec/config.yaml."],
-            ["--skills", "Also install the three skills in .claude/skills and .agents/skills."],
+            ["--schema", "Also install the ID templates and add the spec-ctx rules to openspec/config.yaml."],
+            ["--skills", "Also install the specctx-run skill and its aliases in .claude/skills and .agents/skills."],
             ["--all", "Do all three."],
             ["--force", "Replace the files that have other content. spec-ctx.toml stays."],
         ],
@@ -132,11 +137,6 @@ export const TABLE = [
         exit: [["0", "The IDs are written, or nothing is left to adopt."], ["1", "The dry run found headers to adopt, or a new finding undid the write."], USAGE, INTERNAL],
         example: "specctx adopt --dry-run",
     },
-    {
-        name: "task backfill", group: "Setup", args: "--manual <note>", summary: "Write manual evidence for every ticked task of an active change that has none.",
-        flags: [["--manual <note>", "The note for the evidence. The flag is required."], ["--change <name>", "Look only in this change."]],
-        exit: PLAIN, example: "specctx task backfill --manual \"done before spec-ctx\"",
-    },
     {
         name: "baseline write", group: "Setup", args: "", summary: "Record the current debt in .ctx/baseline.json. `check` then hides it.",
         flags: [], exit: PLAIN, example: "specctx baseline write",

package/dist/cli/status.js

@@ -1,29 +1,13 @@
-// REQ-CLI-001 status reads the index, the handoff file, and the .openspec.yaml of each archive folder.
+// REQ-CLI-001 status reads the index, the handoff file, questions.json, and the .openspec.yaml of each archive folder.
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { changeOf } from "../index/scan.js";
+import { readQuestions, renderQuestions } from "../handoff/questions.js";
 import { cmpStr, pyStrip, splitLines } from "../util/pystr.js";
 export const HANDOFF_PATH = ".ctx/handoff.md";
-/** First line of each open_questions item in the handoff file. */
+/** REQ-HND-003 the open questions as handoff.md renders them, read from .ctx/questions.json (022/D7). */
 export function openQuestions(root) {
-    const p = join(root, HANDOFF_PATH);
-    if (!existsSync(p))
-        return [];
-    const items = [];
-    let inside = false;
-    for (const line of splitLines(readFileSync(p).toString("utf8"))) {
-        if (line.startsWith("open_questions:")) {
-            inside = true;
-            continue;
-        }
-        if (!inside)
-            continue;
-        if (line.startsWith("- "))
-            items.push(pyStrip(line.slice(2)));
-        else if (pyStrip(line) && !line.startsWith(" ") && !line.startsWith("\t"))
-            break;
-    }
-    return items;
+    return renderQuestions(readQuestions(root)).open_questions;
 }
 /** REQ-HND-003 the current task from the handoff file. */
 function handoffCurrent(root) {
@@ -77,7 +61,7 @@ export function statusReport(root, entries) {
         uncovered: uncovered.length,
         handoff,
         current: handoff ? handoffCurrent(root) : null,
-        open_questions: handoff ? openQuestions(root) : [],
+        open_questions: openQuestions(root),
     };
 }
 export function statusLines(r) {

package/dist/cli/workflow.js

@@ -1,4 +1,4 @@
-// REQ-IDS-001 REQ-TASK-001 REQ-TASK-002 REQ-TASK-003 REQ-TASK-005 REQ-VER-002 REQ-HND-001 write commands.
+// REQ-IDS-001 REQ-TASK-001 REQ-TASK-002 REQ-TASK-003 REQ-TASK-005 REQ-VER-002 REQ-HND-001 REQ-LOOP-002 write commands.
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { dumps } from "../util/json.js";
@@ -91,7 +91,8 @@ export async function runWorkflow(c) {
             mkdirSync(join(c.root, ".ctx"), { recursive: true });
             const { cpLen } = await import("../util/pystr.js");
             // REQ-STAT-002 the bundle size goes next to the current task, so stats can compute the context ratio
-            writeFileSync(join(c.root, CURRENT_PATH), dumps({ bundle_chars: cpLen(b.text), started_at: isoNow(), task: t.id }) + "\n");
+            // REQ-TASK-002 the Verify command is frozen here, so task done can refuse a changed one (019/D3)
+            writeFileSync(join(c.root, CURRENT_PATH), dumps({ bundle_chars: cpLen(b.text), started_at: isoNow(), task: t.id, verify: t.verify.command }) + "\n");
             // REQ-TASK-002 a task that cites no REQ gets one hint line, so the agent knows what to add
             const hint = t.reqs.length ? null : `task ${t.id} cites no REQ. Run specctx query --change ${t.change} --kind req to list its requirements, then add [REQ-<CAP>-NNN] to the task line.`;
             if (c.json)
@@ -110,11 +111,13 @@ export async function runWorkflow(c) {
             if (!dry && manual !== undefined) {
                 if (!manual.trim())
                     throw new UsageExit("--manual needs a note");
+                // REQ-TASK-003 a task with a Verify command gets no manual note (019/D1, ADR-004)
+                if (t.verify.command !== null)
+                    throw new UsageExit(`task ${t.id} has a Verify command. Run it with specctx task done ${t.id}.`);
                 if (t.done && hasEvidence(c.root, t))
                     throw new UsageExit(`task ${t.id} is done`);
-                // a manual note records evidence without a run. On a task done by hand it backfills the evidence.
                 const { writeEvidence } = await import("../tasks/evidence.js");
-                const rel = writeEvidence(c.root, t, entries, { command: t.verify.command, exit: null, stdout_sha256: null, stderr_tail: "" }, "manual", manual.trim());
+                const rel = writeEvidence(c.root, t, entries, { command: null, exit: null, stdout_sha256: null, stderr_tail: "" }, "manual", manual.trim());
                 if (!t.done)
                     setBox(c.root, t, true);
                 clearCurrent(c.root, t.id);
@@ -124,11 +127,19 @@ export async function runWorkflow(c) {
                     c.io.out(paint("ok", `done ${t.id} (manual). Evidence: ${rel}\n`, c.io.tty));
                 return 0;
             }
-            if (!dry && t.done)
+            // REQ-TASK-003 a ticked task with evidence is done. One without evidence gets the repair run (019/D2).
+            if (!dry && t.done && hasEvidence(c.root, t))
                 throw new UsageExit(`task ${t.id} is done`);
             if (t.verify.command === null) {
                 throw new UsageExit(`task ${t.id} has no Verify command. ${dry ? "Nothing to run" : 'A --manual "<note>" is required'}`);
             }
+            // REQ-TASK-003 the Verify command that task start froze must still be the one on the task line (019/D3)
+            if (!dry) {
+                const frozen = readCurrent(c.root);
+                if (frozen && frozen.task === t.id && typeof frozen.verify === "string" && frozen.verify !== t.verify.command) {
+                    throw new UsageExit(`task ${t.id}: the Verify command changed since task start. Run specctx task start ${t.id} again.`);
+                }
+            }
             const { runVerify, tail } = await import("../verify/run.js");
             const { resolve: resolvePath, relative, isAbsolute } = await import("node:path");
             let dir = c.root;
@@ -153,8 +164,16 @@ export async function runWorkflow(c) {
             }
             if (r.timedOut || r.exit !== 0) {
                 const msg = r.timedOut ? `verify timed out after ${c.cfg.verify.timeout_s}s` : `verify failed with exit ${r.exit}`;
+                // REQ-LOOP-002 the fail file is the retry record. At the cap, one question stops the loop (024/D4, 024/D5).
+                const { writeFail, openQuestionFor, capQuestion, blockedLine } = await import("../loop/fails.js");
+                const { addQuestion } = await import("../handoff/questions.js");
+                const fail = writeFail(c.root, t.id, { command: t.verify.command, exit: r.timedOut ? null : r.exit }, outTail);
+                let question = openQuestionFor(c.root, t.id)?.n ?? null;
+                if (question === null && fail.file.attempt >= c.cfg.loop.max_attempts) {
+                    question = addQuestion(c.root, t.id, capQuestion(t.id, fail.file.attempt, outTail)).n;
+                }
                 if (c.json)
-                    print(c, { command: t.verify.command, error: msg, exit: r.exit, tail: outTail, task: t.id });
+                    print(c, { attempt: fail.file.attempt, command: t.verify.command, error: msg, exit: r.exit, fail: fail.rel, question, tail: outTail, task: t.id });
                 else
                     c.io.out(outTail ? outTail + "\n" : "");
                 // REQ-VER-003 a timeout keeps its own line on stderr
@@ -163,6 +182,9 @@ export async function runWorkflow(c) {
                 // REQ-TASK-003 the refusal is the last line of the output. REQ-CLI-008 it is red on a TTY.
                 else if (!c.json)
                     c.io.out(paint("fail", `Verify failed (exit ${r.exit}). The task stays open.\n`, c.io.tty));
+                // REQ-LOOP-002 the blocked line comes after the failure text, so the last line names the way out
+                if (!c.json && question !== null)
+                    c.io.out(blockedLine(question) + "\n");
                 return 1;
             }
             const { sha256 } = await import("../util/hash.js");
@@ -181,38 +203,6 @@ export async function runWorkflow(c) {
                 c.io.out(paint("ok", `done ${t.id}. Evidence: ${rel}\n`, c.io.tty)); // REQ-CLI-008
             return 0;
         }
-        case "task backfill": {
-            // REQ-TASK-006 manual evidence for every ticked task of an active change that has none, through the task done --manual path.
-            // Archived changes stay untouched (017/D1).
-            noMore(c, 0);
-            const note = f.manual?.trim();
-            if (!note)
-                throw new UsageExit('task backfill needs --manual "<note>"');
-            const { tasksOf, toTask, hasEvidence } = await import("../tasks/tasks.js");
-            const { matchesChange } = await import("../index/scan.js");
-            const { writeEvidence } = await import("../tasks/evidence.js");
-            const want = f.change;
-            const counts = new Map();
-            for (const e of tasksOf(entries)) {
-                if (e.status !== "done" || e.file.includes("/archive/"))
-                    continue;
-                if (want && !matchesChange(e.change, want))
-                    continue;
-                if (hasEvidence(c.root, e))
-                    continue;
-                const t = toTask(c.root, e);
-                writeEvidence(c.root, t, entries, { command: t.verify.command, exit: null, stdout_sha256: null, stderr_tail: "" }, "manual", note);
-                counts.set(e.change, (counts.get(e.change) ?? 0) + 1);
-            }
-            const { cmpStr } = await import("../util/pystr.js");
-            const rows = [...counts.keys()].sort(cmpStr).map((k) => ({ change: k, count: counts.get(k) }));
-            const total = rows.reduce((n, r) => n + r.count, 0);
-            if (c.json)
-                print(c, { changes: rows, total });
-            else
-                c.io.out(rows.map((r) => `${r.change}: ${r.count}\n`).join("") + `backfilled ${total} task(s)\n`);
-            return 0;
-        }
         case "task reopen": {
             const { findTask, setBox } = await import("../tasks/tasks.js");
             const t = findTask(c.root, entries, arg(c, 0, "a task ID"));
@@ -240,8 +230,12 @@ export async function runWorkflow(c) {
             const h = writeHandoff(c.root, entries);
             if (c.json)
                 print(c, h);
-            else
+            else {
+                // REQ-HND-002 the one time move of old questions into questions.json (022/D8)
+                if (h.migrated)
+                    c.io.out(`migrated ${h.migrated} question(s) to .ctx/questions.json\n`);
                 c.io.out(`wrote ${HANDOFF_PATH}\n`);
+            }
             return 0;
         }
         case "handoff ask": {
@@ -250,7 +244,7 @@ export async function runWorkflow(c) {
             if (c.json)
                 print(c, { open_questions: h.open_questions });
             else
-                c.io.out(`open question ${h.open_questions.length} added\n`);
+                c.io.out(`open question ${h.asked ?? h.open_questions.length} added\n`);
             return 0;
         }
         case "handoff resolve": {
@@ -268,6 +262,18 @@ export async function runWorkflow(c) {
     }
     throw new UsageExit(`unknown command: ${c.p.command}`);
 }
+/** The current task file, or null when it is absent or damaged. */
+function readCurrent(root) {
+    const p = join(root, ".ctx/current.json");
+    if (!existsSync(p))
+        return null;
+    try {
+        return JSON.parse(readFileSync(p, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
 function clearCurrent(root, task) {
     const p = join(root, ".ctx/current.json");
     if (!existsSync(p))

package/dist/config.js

@@ -2,6 +2,8 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { parse } from "smol-toml";
+/** REQ-DIST-002 the command that gate runs for openspec validate (018/D1). */
+export const DEFAULT_OPENSPEC = "npx -y @fission-ai/openspec@latest";
 export const CONFIG_FILE = "spec-ctx.toml";
 export function defaults() {
     return {
@@ -13,10 +15,12 @@ export function defaults() {
             tests: ["tests/**"],
             ignore: [],
         },
-        ids: { caps: [], task_pattern: "\\d+\\.\\d+", paths: {} },
+        ids: { caps: [], task_pattern: "\\d+\\.\\d+", paths: {}, brackets: false },
         bundle: { budget: 8000, depth: 1 },
         verify: { timeout_s: 600 },
-        gate: { markdown: ["openspec/**/*.md", "decisions/*.md", "docs/**/*.md", "*.md"] },
+        // REQ-DIST-002 the gate lints nothing unless the project opts in (022/D1, ADR-006 item 9)
+        gate: { markdown: [], openspec: DEFAULT_OPENSPEC, base: "origin/main" },
+        loop: { max_attempts: 3, archive: "ask" },
     };
 }
 export class ConfigError extends Error {
@@ -65,6 +69,12 @@ export function loadConfig(root) {
         }
         cfg.ids.paths = { ...v };
     }
+    // REQ-ADOPT-010 the header form that adopt and id new write (027/D2)
+    if ("brackets" in ids) {
+        if (typeof ids.brackets !== "boolean")
+            throw new ConfigError(`${CONFIG_FILE}: ids.brackets must be true or false.`);
+        cfg.ids.brackets = ids.brackets;
+    }
     const bundle = sec("bundle");
     for (const k of ["budget", "depth"]) {
         if (k in bundle) {
@@ -86,6 +96,32 @@ export function loadConfig(root) {
     const gate = sec("gate");
     if ("markdown" in gate)
         cfg.gate.markdown = strList(gate.markdown, "gate.markdown");
+    // REQ-DIST-002 the OpenSpec command. An empty string would run " validate", so it is an error too (018/D1).
+    if ("openspec" in gate) {
+        if (typeof gate.openspec !== "string" || !gate.openspec.trim())
+            throw new ConfigError(`${CONFIG_FILE}: gate.openspec must be a string that is not empty.`);
+        cfg.gate.openspec = gate.openspec;
+    }
+    // REQ-ADOPT-008 the ref whose merge base with HEAD holds the baseline that gate compares with (020/D5)
+    if ("base" in gate) {
+        if (typeof gate.base !== "string" || !gate.base.trim())
+            throw new ConfigError(`${CONFIG_FILE}: gate.base must be a string that is not empty.`);
+        cfg.gate.base = gate.base;
+    }
+    // REQ-LOOP-003 the loop keys (024/D6)
+    const loop = sec("loop");
+    if ("max_attempts" in loop) {
+        const v = loop.max_attempts;
+        if (typeof v !== "number" || !Number.isInteger(v) || v < 1)
+            throw new ConfigError(`${CONFIG_FILE}: loop.max_attempts must be an integer of 1 or more.`);
+        cfg.loop.max_attempts = v;
+    }
+    if ("archive" in loop) {
+        const v = loop.archive;
+        if (v !== "ask" && v !== "auto")
+            throw new ConfigError(`${CONFIG_FILE}: loop.archive must be "ask" or "auto".`);
+        cfg.loop.archive = v;
+    }
     return cfg;
 }
 /** The file that `specctx init` writes. Each key has a comment above it. */
@@ -111,6 +147,9 @@ ignore = []
 caps = []
 # Pattern of the task number in a tasks.md checkbox.
 task_pattern = '\\d+\\.\\d+'
+# true makes adopt and id new write the ID in square brackets, [REQ-UA-001], as OpenSpec PR #1979 reads it.
+# false writes the bare form, REQ-UA-001. The scan reads both forms.
+brackets = false
 
 [bundle]
 # Default character budget of a bundle.
@@ -123,6 +162,18 @@ depth = 1
 timeout_s = 600
 
 [gate]
-# Markdown globs that gate lints. The baseline holds the lint debt of these files.
-markdown = ["openspec/**/*.md", "decisions/*.md", "docs/**/*.md", "*.md"]
+# Markdown globs that gate lints with the tells and STE linters. Empty means no lint.
+# To turn it on, set markdown = ["openspec/**/*.md", "decisions/*.md", "docs/**/*.md", "*.md"]. The spec-ctx repository opts in.
+markdown = []
+# The command that gate runs for openspec validate. Set it to "openspec" for a global install or a fork,
+# or pin a version. The env var SPECCTX_OPENSPEC overrides it for one run.
+openspec = "npx -y @fission-ai/openspec@latest"
+# The ref whose merge base with HEAD holds the baseline that gate compares with. New entries fail the gate.
+base = "origin/main"
+
+[loop]
+# Verify failures on one task before task done writes a question and the loop stops.
+max_attempts = 3
+# "ask" stops before archive for a human. "auto" lets the loop archive when the gate passes.
+archive = "ask"
 `;

package/dist/handoff/handoff.js

@@ -6,7 +6,8 @@ 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";
+import { isoNow } from "../util/time.js";
+import { addQuestion, fromHandoffItems, hasQuestions, readQuestions, renderQuestions, resolveQuestion, writeQuestions } from "./questions.js";
 export const HANDOFF_PATH = ".ctx/handoff.md";
 export const CURRENT_PATH = ".ctx/current.json";
 const SCALARS = ["change", "current", "base", "as_of"];
@@ -86,9 +87,24 @@ function evidenceRows(root, active) {
     return rows;
 }
 const AT = / \(at (\S+)\)$/;
+/**
+ * REQ-HND-002 move the questions of an old handoff.md into questions.json once (022/D8).
+ * Returns the count, 0 when the file exists or the handoff has no question.
+ */
+function migrateQuestions(root, prev) {
+    if (!prev || hasQuestions(root))
+        return 0;
+    if (!prev.open_questions.length && !prev.resolved.length)
+        return 0;
+    const qs = fromHandoffItems(prev.open_questions, prev.resolved);
+    writeQuestions(root, qs);
+    return qs.length;
+}
 /** Generate the handoff. Two runs with no change in between write the same bytes. */
 export function writeHandoff(root, entries) {
     const prev = readHandoff(root);
+    const migrated = migrateQuestions(root, prev);
+    const lists = renderQuestions(readQuestions(root));
     const active = activeChanges(entries);
     const next = nextTask(root, entries);
     const rows = evidenceRows(root, active);
@@ -108,41 +124,40 @@ export function writeHandoff(root, entries) {
             const m = AT.exec(item.split("\n")[0]);
             return !m || after(m[1]);
         }),
-        open_questions: prev?.open_questions ?? [],
-        resolved: prev?.resolved ?? [],
+        // REQ-HND-001 both lists come from questions.json, never from the previous file (022/D7)
+        open_questions: lists.open_questions,
+        resolved: lists.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);
+    if (migrated)
+        h.migrated = migrated;
     return h;
 }
-function ensure(root, entries) {
-    return readHandoff(root) ?? writeHandoff(root, entries);
+/** The handoff with its two question lists rendered again from questions.json. The other sections stay. */
+function refresh(root, entries) {
+    const h = readHandoff(root) ?? writeHandoff(root, entries);
+    const lists = renderQuestions(readQuestions(root));
+    h.open_questions = lists.open_questions;
+    h.resolved = lists.resolved;
+    save(root, h);
+    return h;
 }
+/** REQ-HND-002 append an open question to questions.json and render the handoff again (022/D6). */
 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);
+    const q = addQuestion(root, currentTask(root), text);
+    const h = refresh(root, entries);
+    h.asked = q.n;
     return h;
 }
+/** REQ-HND-002 resolve question n in questions.json and render the handoff again (022/D6). */
 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;
+    resolveQuestion(root, n, answer);
+    return refresh(root, entries);
 }
 export function addReopened(root, entries, task, reason) {
-    const h = ensure(root, entries);
+    const h = readHandoff(root) ?? writeHandoff(root, entries);
     h.reopened.push(`${task} ${reason.replace(/\s*\n\s*/g, " ").trim()} (at ${isoNow()})`);
     save(root, h);
 }