spec-ctx 0.1.2 → 0.3.0

package/dist/check/evidence.js

@@ -1,7 +1,30 @@
 // REQ-CHK-003 evidence rules of check --strict.
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileSha256 } from "../util/hash.js";
+import { evidenceRel } from "../tasks/tasks.js";
+/**
+ * REQ-CHK-003 REQ-LOOP-008 the stale paths of one evidence file, sorted. A damaged file is stale as a whole and
+ * returns its own path. check and next both read this, so the two never differ (031/D5).
+ */
+export function staleFiles(root, rel) {
+    let files = {};
+    try {
+        const ev = JSON.parse(readFileSync(join(root, rel), "utf8"));
+        files = ev.files ?? {};
+    }
+    catch {
+        return [rel];
+    }
+    return Object.keys(files).filter((p) => fileSha256(join(root, p)) !== files[p]).sort();
+}
+/** REQ-LOOP-008 the first stale path of the evidence of a task, or null when it is fresh or absent (031/D5). */
+export function staleOf(root, task) {
+    const rel = evidenceRel({ id: task });
+    if (!existsSync(join(root, rel)))
+        return null;
+    return staleFiles(root, rel)[0] ?? null;
+}
 export function evidenceFindings(root, entries, evidence) {
     const out = [];
     const tasks = new Map();
@@ -27,19 +50,8 @@ export function evidenceFindings(root, entries, evidence) {
         // archived changes are exempt from stale-evidence
         if (!active)
             continue;
-        let files = {};
-        try {
-            const ev = JSON.parse(readFileSync(join(root, rel), "utf8"));
-            files = ev.files ?? {};
-        }
-        catch {
-            out.push([rel, 1, "stale-evidence", `${id} ${rel}`]);
-            continue;
-        }
-        for (const [path, digest] of Object.entries(files)) {
-            if (fileSha256(join(root, path)) !== digest)
-                out.push([rel, 1, "stale-evidence", `${id} ${path}`]);
-        }
+        for (const path of staleFiles(root, rel))
+            out.push([rel, 1, "stale-evidence", `${id} ${path}`]);
     }
     for (const e of entries) {
         if (e.kind === "task" && e.status === "done" && !e.file.includes("/archive/") && !have.has(e.id)) {

package/dist/check/hints.js

@@ -16,10 +16,19 @@ 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." },
-    "stale-evidence": { level: "hard", hint: "Run specctx task reopen and then specctx task done." },
+    "done-without-evidence": { level: "hard", hint: "Run specctx task done. It runs the Verify command and writes the evidence." },
+    // REQ-CHK-006 the hint names the why argument of task reopen (031/D8)
+    "stale-evidence": { level: "hard", hint: "Run specctx task reopen <task> <why>, then specctx task done <task>." },
     "evidence-without-done": { level: "hard", hint: "Run specctx task done, or remove the evidence file." },
+    // REQ-CHK-005 advisory in plain check. check --strict reports it as a hard finding (028/D5).
+    "weak-verify": { level: "advisory", hint: "Name a test file or a command whose exit code proves the task." },
     "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,9 +18,8 @@ export const COMMAND_FLAGS = {
     "task verify": {},
     "task done": { manual: "string" },
     "task reopen": {},
-    "task backfill": { manual: "string", change: "string" },
     "handoff write": {},
-    "handoff ask": {},
+    "handoff ask": { change: "string" },
     "handoff resolve": {},
     adopt: { "dry-run": "bool" },
     "baseline write": {},

package/dist/cli/commands.js

@@ -10,7 +10,12 @@ async function runCheck(root, cfg, data, strict) {
     const { applyBaseline } = await import("../baseline/baseline.js");
     const findings = check(root, cfg, data, strict);
     let warnings = [];
-    if (strict) {
+    if (!strict) {
+        // REQ-CHK-005 plain check prints weak-verify as an advisory warning (028/D3)
+        const { weakVerifyWarnings } = await import("../check/check.js");
+        warnings = weakVerifyWarnings(data.entries);
+    }
+    else {
         const { manualWarnings } = await import("../check/evidence.js");
         const { listEvidence } = await import("../tasks/evidence.js");
         warnings = manualWarnings(root, data.entries, listEvidence(root));
@@ -23,7 +28,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;
@@ -34,16 +40,29 @@ export function checkText(r, tty) {
     for (const x of r.findings)
         count.set(x.rule, (count.get(x.rule) ?? 0) + 1);
     for (const w of r.warnings) {
-        const [rule, task] = w.split(" ");
+        const [rule, task, at] = w.split(" ");
         count.set(rule, (count.get(rule) ?? 0) + 1);
+        // REQ-CHK-005 a weak-verify warning ends with <file>:<line> of the task line (028/D4)
+        if (rule === "weak-verify" && at)
+            files.add(at.replace(/:\d+$/, ""));
         // a manual-evidence warning names a task. Its file is the evidence file of the task.
-        if (task?.includes("/"))
+        else if (task?.includes("/"))
             files.add(`.ctx/evidence/${task}.json`);
     }
+    // REQ-CHK-006 the distinct hints that findings carry, in finding order. A rule with none prints the table hint (031/D6).
+    const own = new Map();
+    for (const x of r.findings) {
+        if (x.hint === undefined)
+            continue;
+        const l = own.get(x.rule) ?? [];
+        if (!l.includes(x.hint))
+            l.push(x.hint);
+        own.set(x.rule, l);
+    }
     const rules = [...count.keys()].sort();
     return body
         + "\n" + paint("dim", `${n} finding${n === 1 ? "" : "s"} in ${files.size} file${files.size === 1 ? "" : "s"} (${r.findings.length} hard, ${r.warnings.length} advisory)\n`, tty)
-        + rules.map((rule) => `${rule}  ${count.get(rule)}  ${hintOf(rule)}\n`).join("")
+        + rules.map((rule) => `${rule}  ${count.get(rule)}  ${own.get(rule)?.join("\n") ?? hintOf(rule)}\n`).join("")
         + base;
 }
 export async function run(p, io) {
@@ -133,6 +152,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 +183,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,9 +200,23 @@ export async function run(p, io) {
             const r = statusReport(root, entries);
             if (json)
                 print(r);
-            // REQ-CLI-008 the next: line is dim
+            else {
+                // REQ-CLI-007 the next: line is the command of the decision of specctx next, so the two never disagree (030/D1)
+                const { decideNext } = await import("../loop/next.js");
+                const d = decideNext(root, cfg, data);
+                // REQ-CLI-008 the next: line is dim
+                io.out(statusLines(r, d.command).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(statusLines(r).map((l) => (l.startsWith("next: ") ? paint("dim", l, io.tty) : l) + "\n").join(""));
+                io.out(renderNext(d).split("\n").map((l) => (l.startsWith("next: ") ? paint("dim", l, io.tty) : l)).join("\n"));
             return 0;
         }
         case "query": {
@@ -253,8 +291,10 @@ export async function run(p, io) {
         }
         case "check": {
             const r = await runCheck(root, cfg, data, !!f.strict);
+            // REQ-CHK-004 REQ-CHK-006 the JSON keeps its shape. A finding hint is for the human form only (031/D6).
+            const findings = r.findings.map(({ hint: _hint, ...rest }) => rest);
             if (json)
-                print({ baselined: r.baselined, count: r.findings.length, findings: r.findings, warnings: r.warnings });
+                print({ baselined: r.baselined, count: findings.length, findings, warnings: r.warnings });
             else
                 io.out(checkText(r, io.tty));
             return r.findings.length ? 1 : 0;
@@ -275,6 +315,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."],
@@ -109,7 +114,8 @@ export const TABLE = [
     { name: "handoff write", group: "Write", args: "", summary: "Write .ctx/handoff.md from the index and the evidence.", flags: [], exit: PLAIN, example: "specctx handoff write" },
     {
         name: "handoff ask", group: "Write", args: "<question>", summary: "Add an open question to the handoff.",
-        flags: [], exit: PLAIN, example: "specctx handoff ask \"Keep the old flag?\"",
+        flags: [["--change <name>", "Give the question to this change, not to the current task. The key or the full folder name works."]],
+        exit: PLAIN, example: "specctx handoff ask --change 008 \"plan ready for 008-tasks. Approve to start the tasks?\"",
     },
     {
         name: "handoff resolve", group: "Write", args: "<n> <answer>", summary: "Move open question n to the resolved list.",
@@ -119,8 +125,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 +138,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,10 +61,14 @@ 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) {
+/**
+ * REQ-CLI-007 the status lines. The last line is always `next: ` and the command of the decision
+ * of `specctx next`, or `none` when the decision has no command (030/D1, 030/D2).
+ */
+export function statusLines(r, next) {
     const out = r.changes.map((c) => `${c.change}  done ${c.done}  open ${c.open}`);
     if (!r.changes.length) {
         out.push("no active change");
@@ -98,19 +86,6 @@ export function statusLines(r) {
             for (const q of r.open_questions)
                 out.push(`- ${q}`);
     }
-    const next = nextStep(r);
-    if (next)
-        out.push(`next: ${next}`);
+    out.push(`next: ${next ?? "none"}`);
     return out;
 }
-/** REQ-CLI-007 the next step by state: an open task, then a change with every task done, then uncovered REQs. */
-export function nextStep(r) {
-    if (r.changes.some((c) => c.open > 0))
-        return "specctx task next";
-    const ready = r.changes.find((c) => c.done > 0 && c.open === 0);
-    if (ready)
-        return `archive ${ready.change}`;
-    if (r.uncovered > 0)
-        return "specctx check";
-    return null;
-}

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,17 +230,21 @@ 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": {
             const { ask } = await import("../handoff/handoff.js");
-            const h = ask(c.root, entries, c.p.positional.join(" "));
+            const h = ask(c.root, entries, c.p.positional.join(" "), c.p.flags.change);
             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))