spec-ctx 0.1.1 → 0.2.0

package/dist/check/check.js

@@ -6,7 +6,8 @@ import { changeKey } from "../index/scan.js";
 import { listEvidence } from "../tasks/evidence.js";
 import { cmpTuple } from "../util/pystr.js";
 import { evidenceFindings } from "./evidence.js";
-const RETIRED_RE = /\b(REQ-[A-Z]{2,6}-\d{3}|ADR-\d{3})\b/g;
+// the first ID of a retired row can be a scenario. Only a REQ or ADR can be reused, but the SCN still counts as the row ID.
+const RETIRED_RE = /\b(REQ-[A-Z]{2,6}-\d{3}|SCN-[A-Z]{2,6}-\d{3}-\d+|ADR-\d{3})\b/g;
 const REQ_CAP = /^REQ-([A-Z]{2,6})-/;
 export function retiredIds(root) {
     const p = join(root, "decisions", "retired-ids.md");
@@ -49,6 +50,51 @@ export function duplicateChangeKeys(root) {
     }
     return out;
 }
+// REQ-ADOPT-010 the ID of a TO line is bare or in square brackets (027/D4)
+const TO_LINE = /^-\s*TO:\s*`###\s+Requirement:\s*(?:(REQ-[A-Z]{2,6}-\d{3})|\[(REQ-[A-Z]{2,6}-\d{3})\](?=\s|`))?\s*(.*?)`\s*$/;
+/** The headers that the TO lines of the RENAMED blocks of one delta file name: [id or null, title]. */
+function renamedTargets(root, file) {
+    const out = [];
+    let section = "";
+    for (const line of readFileSync(join(root, file), "utf8").split(/\r?\n/)) {
+        if (line.startsWith("## ")) {
+            section = line.slice(3).trim().split(" ")[0].toUpperCase();
+            continue;
+        }
+        if (section !== "RENAMED")
+            continue;
+        const m = TO_LINE.exec(line.trim());
+        if (m)
+            out.push([m[1] ?? m[2] ?? null, m[3].trim()]);
+    }
+    return out;
+}
+/**
+ * REQ-CHK-001 retitle-needs-renamed: a MODIFIED or REMOVED header of an active change whose ID exists in main
+ * with another title, and whose delta file has no RENAMED TO line with that header. Upstream OpenSpec matches
+ * delta headers by text, so the archive needs the RENAMED pair (021/D1, ADR-006 item 7).
+ */
+export function retitleFindings(root, entries) {
+    const main = new Map();
+    for (const e of entries)
+        if (e.kind === "req" && e.change === "main" && e.status === "active")
+            main.set(e.id, e);
+    const targets = new Map();
+    const out = [];
+    for (const e of entries) {
+        if (e.kind !== "req" || (e.status !== "modified" && e.status !== "removed") || e.file.includes("/archive/"))
+            continue;
+        const m = main.get(e.id);
+        if (!m || m.title === e.title)
+            continue;
+        if (!targets.has(e.file))
+            targets.set(e.file, renamedTargets(root, e.file));
+        if (targets.get(e.file).some(([id, title]) => title === e.title && (id === null || id === e.id)))
+            continue;
+        out.push({ file: e.file, line: e.line, rule: "retitle-needs-renamed", id: e.id, detail: `"${m.title}" -> "${e.title}"` });
+    }
+    return out;
+}
 /** Sorted, unique findings. The scan never reads .ctx/, so evidence adds no index entry. */
 export function check(root, cfg, data, strict) {
     const entries = data.entries;
@@ -122,5 +168,7 @@ export function check(root, cfg, data, strict) {
     const uniq = new Map();
     for (const f of findings)
         uniq.set(JSON.stringify(f), f);
-    return [...uniq.values()].sort((a, b) => cmpTuple(a, b)).map(([file, line, rule, id]) => ({ file, line, rule, id }));
+    const plain = [...uniq.values()].map(([file, line, rule, id]) => ({ file, line, rule, id }));
+    const all = [...plain, ...retitleFindings(root, entries)];
+    return all.sort((a, b) => cmpTuple([a.file, a.line, a.rule, a.id], [b.file, b.line, b.rule, b.id]));
 }

package/dist/check/hints.js

@@ -16,10 +16,16 @@ export const RULES = {
     "unknown-cap": { level: "hard", hint: "Add the code to caps under [ids] in spec-ctx.toml." },
     uncovered: { level: "hard", hint: "Add a test with a Covers tag for the requirement." },
     "scenario-untested": { level: "hard", hint: "Name the scenario ID in a test." },
-    "done-without-evidence": { level: "hard", hint: "Run specctx task done, or specctx task backfill for old tasks." },
+    "done-without-evidence": { level: "hard", hint: "Run specctx task done. It runs the Verify command and writes the evidence." },
     "stale-evidence": { level: "hard", hint: "Run specctx task reopen and then specctx task done." },
     "evidence-without-done": { level: "hard", hint: "Run specctx task done, or remove the evidence file." },
     "manual-evidence": { level: "advisory", hint: "Give the task a Verify command and run specctx task done again." },
+    // REQ-CHK-001 the hint is the block to paste. The finding line carries the ID and both titles (021/D3).
+    // REQ-ADOPT-010 FROM copies the main header and TO copies the delta header, each in its own form (027/D4).
+    "retitle-needs-renamed": {
+        level: "hard",
+        hint: "Add to the delta before the MODIFIED block. Write each ID as its header writes it, bare or in brackets:\n## RENAMED Requirements\n- FROM: `### Requirement: <ID> <old title>`\n- TO: `### Requirement: <ID> <new title>`",
+    },
 };
 export function hintOf(rule) {
     return RULES[rule]?.hint ?? "Read the check rules in the check spec.";

package/dist/cli/args.js

@@ -4,6 +4,7 @@ export const GLOBAL_FLAGS = { root: "string", json: "bool", help: "bool", versio
 export const COMMAND_FLAGS = {
     build: {},
     status: {},
+    next: { change: "string" },
     query: { kind: "string", change: "string", all: "bool", limit: "int" },
     related: { depth: "int", all: "bool" },
     bundle: { budget: "int", depth: "int", all: "bool" },
@@ -17,7 +18,6 @@ export const COMMAND_FLAGS = {
     "task verify": {},
     "task done": { manual: "string" },
     "task reopen": {},
-    "task backfill": { manual: "string", change: "string" },
     "handoff write": {},
     "handoff ask": {},
     "handoff resolve": {},

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;
@@ -90,9 +91,9 @@ export async function run(p, io) {
             print(plan);
         else if (!plan.edits.length)
             io.out(plan.unmatched.length ? planLines(plan).join("\n") + "\nnothing to adopt\n" : "nothing to adopt\n");
-        // REQ-CLI-007 the dry run ends with the next step. The exit code stays 1.
+        // REQ-CLI-007 the dry run ends with the next step. REQ-ADOPT-001 the exit code stays 1 and the last line says why (017/D5).
         else
-            io.out(planLines(plan).join("\n") + `\n${plan.edits.length} headers need an ID. Next: specctx adopt\n`);
+            io.out(planLines(plan).join("\n") + `\nexit 1: ${plan.edits.length} headers need an ID. Next: specctx adopt\n`);
         return plan.edits.length ? 1 : 0;
     }
     if (cmd === "baseline write" || cmd === "baseline prune") {
@@ -106,15 +107,18 @@ export async function run(p, io) {
         const data = buildIndex(root, cfg);
         const findings = check(root, cfg, data, true);
         const warnings = manualWarnings(root, data.entries, listEvidence(root));
+        // REQ-ADOPT-007 the lint debt of the gate globs joins the baseline
+        const { lintCounts } = await import("../lint/counts.js");
+        const lint = lintCounts(root, cfg.gate.markdown.join(" ")).counts;
         if (cmd === "baseline write") {
-            const list = writeBaseline(root, findings, warnings);
+            const list = writeBaseline(root, findings, warnings, lint);
             if (json)
                 print({ baseline: BASELINE_PATH, entries: list.length });
             else
                 io.out(`wrote ${BASELINE_PATH} with ${list.length} entr${list.length === 1 ? "y" : "ies"}\n`);
         }
         else {
-            const n = pruneBaseline(root, findings, warnings);
+            const n = pruneBaseline(root, findings, warnings, lint);
             if (json)
                 print({ pruned: n });
             else
@@ -125,11 +129,17 @@ export async function run(p, io) {
     if (cmd === "gate") {
         if (p.positional.length)
             throw new UsageExit("gate takes no arguments");
-        const { runGate, DEFAULT_MARKDOWN } = await import("./gate.js");
+        const { runGate } = await import("./gate.js");
         const strict = !!f.strict;
         return runGate(root, {
             strict,
-            markdown: f.markdown ?? DEFAULT_MARKDOWN,
+            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");
                 const { check } = await import("../check/check.js");
@@ -145,7 +155,8 @@ export async function run(p, io) {
         if (p.positional.length < n)
             throw new UsageExit(`${cmd} needs ${what}`);
     };
-    if (cmd === "query")
+    // REQ-QRY-001 no term lists a whole change. Without --change a term is required (017/D6).
+    if (cmd === "query" && !f.change)
         need(1, "at least one term");
     if (cmd === "related") {
         need(1, "one ID");
@@ -154,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)
@@ -176,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, {
@@ -267,12 +288,15 @@ async function init(p, io) {
     if (p.flags.json)
         io.out(JSON.stringify(r, null, 2) + "\n");
     else if (r.nothing)
-        io.out("nothing to do\n" + paint("dim", "next: specctx status\n", io.tty));
+        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(""));
-        // REQ-CLI-007 init ends with the next step
-        io.out(paint("dim", "next: specctx status\n", io.tty));
+        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).
+        const again = ["specctx init", all ? "--all" : [p.flags.schema ? "--schema" : "", p.flags.skills ? "--skills" : ""].filter(Boolean).join(" "), "--force"].filter(Boolean).join(" ");
+        io.out(paint("dim", `next: ${r.changed.length ? again : "specctx status"}\n`, io.tty));
     }
     return 0;
 }

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);
@@ -40,7 +39,9 @@ export function markdownFiles(root, globs) {
 }
 export const GATE_LOG = ".ctx/gate-log.jsonl";
 /** REQ-STAT-005 the gate steps in order. The log names the step that failed. */
-export const GATE_STEPS = ["check", "lint tells", "lint ste", "validate", "spec-length"];
+/** 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", "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 });
@@ -65,45 +66,41 @@ 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.
-    const { lintSte } = await import("../lint/ste.js");
-    const { lintTells } = await import("../lint/tells.js");
-    const { steReport } = await import("../lint/cli.js");
-    const files = markdownFiles(root, o.markdown);
-    const bad = [];
-    let tellsFailed = false;
+    // 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");
     ran.push("lint tells", "lint ste");
-    const noRotation = new Set(["synonym-rotation"]);
-    for (const f of files) {
-        const text = readFileSync(join(root, f), "utf8").replace(/\r\n?/g, "\n");
-        const tells = lintTells(text);
-        const hard = tells.filter((x) => x.level === "hard");
-        if (hard.length)
-            tellsFailed = true;
-        if (hard.length)
-            bad.push(`${f}\n` + tells.map((x) => `${f}:${x.line}: [${x.level}] ${x.rule}: ${x.match}\n`).join("") + `${hard.length} hard finding(s), baseline 0\n`);
-        const r = lintSte(text, f);
-        const ste = r.findings.filter((x) => !noRotation.has(x.rule));
-        const steHard = ste.filter((x) => x.level === "advisory-free").length;
-        if (steHard)
-            bad.push(`${f}\n` + steReport(ste, r.words, false, steHard, 0));
+    const { counts, files } = lintCounts(root, o.markdown);
+    const base = readBaseline(root);
+    const rises = lintRises(counts, base);
+    const baselined = [...base ?? []].filter((l) => l.startsWith("lint ")).length;
+    if (rises.length) {
+        const newFindings = rises.reduce((a, r) => a + r.current - r.baseline, 0);
+        const inFiles = new Set(rises.map((r) => r.key.split(" ")[1])).size;
+        const lines = rises.map((r) => `${r.key.slice(5).replace(" ", "  ")}  ${r.current} (baseline ${r.baseline})`);
+        const shown = o.json ? lines : lines.slice(0, LINT_DETAIL_CAP);
+        const more = lines.length - shown.length;
+        io.out(`linters: fail, ${newFindings} new finding(s) in ${inFiles} file(s)\n` + shown.map((l) => l + "\n").join("") + (more ? `... ${more} more line(s)\n` : ""));
+        return rises.some((r) => r.key.includes(" tells:")) ? "lint tells" : "lint ste";
     }
-    if (bad.length) {
-        io.out("linters: fail\n" + bad.join(""));
-        return tellsFailed ? "lint tells" : "lint ste";
-    }
-    io.out(`linters: ok (${files.length} file(s))\n`);
+    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(""));
@@ -112,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

@@ -23,9 +23,14 @@ 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: "query", group: "Read", args: "<term...>", summary: "Find the entries that contain all terms.",
+        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: [
-            ["--kind <kind>", "Show only entries of this kind."],
+            ["--kind <kind>", "Show only entries of this kind. Any case works."],
             ["--change <name>", "Show only entries of this change. The key or the full folder name works."],
             ["--limit <n>", "Show n lines at most. The default is 20. Use 0 for no limit."],
             ["--all", "Show all copies of an ID."],
@@ -53,10 +58,10 @@ 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. Separate them with spaces."],
+            ["--markdown <globs>", "Lint these markdown globs instead of [gate] markdown. Separate them with spaces."],
         ],
         exit: [["0", "Every step passed."], ["1", "A step failed."], USAGE, INTERNAL], example: "specctx gate --strict",
     },
@@ -119,10 +124,10 @@ 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", "Install over files that exist. An existing spec-ctx.toml stays."],
+            ["--force", "Replace the files that have other content. spec-ctx.toml stays."],
         ],
         exit: PLAIN, example: "specctx init --all",
     },
@@ -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 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,11 +91,14 @@ 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)
-                print(c, { bundle: b, task: t.id });
+                print(c, { bundle: b, hint, task: t.id });
             else
-                c.io.out(b.text + footer(cpLen(b.text), (await import("../stats/stats.js")).specCharsOf(entries)));
+                c.io.out(b.text + (hint ? hint + "\n" : "") + footer(cpLen(b.text), (await import("../stats/stats.js")).specCharsOf(entries)));
             return 0;
         }
         case "task verify":
@@ -108,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);
@@ -122,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;
@@ -151,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
@@ -161,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");
@@ -179,37 +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 that has none, through the task done --manual path
-            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")
-                    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"));
@@ -237,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": {
@@ -247,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": {
@@ -265,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))