spec-ctx 0.3.0 → 0.4.1

package/dist/cli/commands.js

@@ -2,8 +2,10 @@
 import { resolve } from "node:path";
 import { UsageExit } from "./errors.js";
 import { findRoot, requireOpenSpec } from "./root.js";
+import { defaults } from "../config.js";
 import { hintOf } from "../check/hints.js";
 import { paint } from "./color.js";
+import { runCommand } from "../runcmd.js";
 /** check with warnings and the baseline filter. Strict mode adds the strict rules and the warnings. */
 async function runCheck(root, cfg, data, strict) {
     const { check } = await import("../check/check.js");
@@ -26,7 +28,7 @@ async function runCheck(root, cfg, data, strict) {
  * REQ-CHK-004 the findings, then a blank line, the summary line, and one line per rule with its hint.
  * A warning counts as advisory. The `baselined` line stays last (REQ-CHK-002).
  */
-export function checkText(r, tty) {
+export function checkText(r, tty, run = "specctx") {
     // REQ-CLI-008 every finding of check is hard, so every finding line is red. stale-evidence is one of them.
     // 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("")
@@ -62,7 +64,7 @@ export function checkText(r, tty) {
     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)}  ${own.get(rule)?.join("\n") ?? hintOf(rule)}\n`).join("")
+        + rules.map((rule) => `${rule}  ${count.get(rule)}  ${own.get(rule)?.join("\n") ?? hintOf(rule, run)}\n`).join("")
         + base;
 }
 export async function run(p, io) {
@@ -73,16 +75,8 @@ export async function run(p, io) {
         return init(p, io);
     const root = findRoot(io.cwd, f.root);
     requireOpenSpec(root);
-    const { loadConfig, ConfigError } = await import("../config.js");
-    let cfg;
-    try {
-        cfg = loadConfig(root);
-    }
-    catch (e) {
-        if (e instanceof ConfigError)
-            throw new UsageExit(e.message);
-        throw e;
-    }
+    const { loadConfigOrExit } = await import("./config.js");
+    const cfg = loadConfigOrExit(root);
     const { dumps } = await import("../util/json.js");
     const print = (v) => io.out(dumps(v) + "\n");
     if (cmd === "build") {
@@ -111,7 +105,7 @@ export async function run(p, io) {
             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. REQ-ADOPT-001 the exit code stays 1 and the last line says why (017/D5).
         else
-            io.out(planLines(plan).join("\n") + `\nexit 1: ${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: ${runCommand(cfg.cli.run, "adopt")}\n`);
         return plan.edits.length ? 1 : 0;
     }
     if (cmd === "baseline write" || cmd === "baseline prune") {
@@ -147,6 +141,13 @@ export async function run(p, io) {
     if (cmd === "gate") {
         if (p.positional.length)
             throw new UsageExit("gate takes no arguments");
+        // REQ-CLI-009 the rerun mode runs only the rerun step
+        if (f.base !== undefined && !f.rerun)
+            throw new UsageExit("--base needs --rerun");
+        if (f.rerun) {
+            const { runRerun } = await import("./gate.js");
+            return runRerun(root, cfg, { strict: !!f.strict, base: f.base || cfg.gate.base, json }, io);
+        }
         const { runGate } = await import("./gate.js");
         const strict = !!f.strict;
         return runGate(root, {
@@ -164,7 +165,7 @@ export async function run(p, io) {
                 void check;
                 const data = buildIndex(root, cfg);
                 const r = await runCheck(root, cfg, data, strict);
-                return { code: r.findings.length ? 1 : 0, out: checkText(r, io.tty) };
+                return { code: r.findings.length ? 1 : 0, out: checkText(r, io.tty, cfg.cli.run) };
             },
         }, io);
     }
@@ -177,12 +178,17 @@ export async function run(p, io) {
     if (cmd === "query" && !f.change)
         need(1, "at least one term");
     if (cmd === "related") {
-        need(1, "one ID");
+        need(1, "one ID, path, or change");
         if (p.positional.length > 1)
-            throw new UsageExit("related takes one ID");
+            throw new UsageExit("related takes one ID, path, or change");
     }
     if (cmd === "bundle")
-        need(1, "at least one ID");
+        need(1, "at least one ID, path, or change");
+    if (cmd === "context") {
+        need(1, "one task, ID, path, or change");
+        if (p.positional.length > 1)
+            throw new UsageExit("context takes one task, ID, path, or change");
+    }
     if ((cmd === "status" || cmd === "check" || cmd === "next") && p.positional.length)
         throw new UsageExit(`${cmd} takes no arguments`);
     const { data, rebuilt } = loadIndex(root, cfg);
@@ -232,15 +238,35 @@ export async function run(p, io) {
         }
         case "related": {
             const { canon } = await import("../index/canonical.js");
-            const { related } = await import("../graph/related.js");
-            const id = p.positional[0];
+            const { related, mainVersion } = await import("../graph/related.js");
             const ids = canon(entries);
+            let id = p.positional[0];
+            let isPath = false;
             if (!ids.has(id) && !(all && entries.some((e) => e.id === id))) {
-                io.err(`unknown id ${id}\n`);
-                return 2;
+                // REQ-QRY-011 a change key or folder name is a change. REQ-QRY-005 any other input is a path in the repository.
+                const { resolveFileInput, changeInput } = await import("../graph/path.js");
+                const ch = changeInput(entries, id);
+                if (ch)
+                    id = ch;
+                else {
+                    const r = resolveFileInput(root, io.cwd, id);
+                    if ("error" in r) {
+                        io.err(`${r.error}\n`);
+                        return 2;
+                    }
+                    id = r.rel;
+                    isPath = true;
+                }
             }
             const rows = [];
             for (const [i, reason] of related(entries, id, f.depth ?? 1, all)) {
+                // REQ-QRY-010 the pair of a main version stands for the non-canonical copy in the main spec
+                if (!all && reason === `main version of ${i}`) {
+                    const m = mainVersion(entries, i);
+                    if (m)
+                        rows.push([m, reason]);
+                    continue;
+                }
                 const copies = all ? entries.filter((e) => e.id === i) : ids.has(i) ? [ids.get(i)] : [];
                 // canonical copy first, the rest in index order
                 copies.sort((a, b) => Number(!a.canonical) - Number(!b.canonical));
@@ -249,22 +275,46 @@ export async function run(p, io) {
             }
             if (json)
                 print(rows.map(([e, reason]) => ({ ...e, reason })));
+            else if (isPath && rows.length === 0)
+                io.out(`no links: ${id}\n`);
             else
                 io.out(rows.map(([e, r]) => `${e.kind}  ${e.id}  ${e.status}  ${e.file}:${e.line}  ${r}\n`).join(""));
             return 0;
         }
+        case "context":
         case "bundle": {
             const { canon } = await import("../index/canonical.js");
             const { bundle } = await import("../graph/bundle.js");
+            const { resolveInputs } = await import("../graph/input.js");
             const ids = canon(entries);
-            const unknown = p.positional.filter((i) => !ids.has(i));
-            if (unknown.length) {
-                io.err(`unknown id(s): ${unknown.join(", ")}\n`);
+            // REQ-QRY-005 an input that is no known ID is a path in the repository
+            const { wanted, paths, errors, taskId } = resolveInputs(root, io.cwd, entries, p.positional);
+            if (errors.length) {
+                io.err(errors.map((l) => l + "\n").join(""));
                 return 2;
             }
-            const b = bundle(root, entries, p.positional, f.budget ?? cfg.bundle.budget, f.depth ?? cfg.bundle.depth, all);
+            // REQ-QRY-004 --block prints the requirement blocks verbatim and nothing else (034/D2)
+            if (f.block) {
+                const notReq = p.positional.filter((i) => ids.get(i)?.kind !== "req");
+                if (notReq.length) {
+                    io.err(`not a requirement: ${notReq.join(", ")}\n`);
+                    return 2;
+                }
+                const { reqBlocks } = await import("../graph/bundle.js");
+                const text = reqBlocks(root, p.positional.map((i) => ids.get(i)));
+                if (json)
+                    print({ text, omitted: [] });
+                else
+                    io.out(text);
+                return 0;
+            }
+            // 047/D5 a task input passes the entry that findTask picks, so an active task wins over an archived one
+            const task = taskId === undefined ? undefined : (await import("../tasks/tasks.js")).findTask(root, entries, taskId).entry;
+            const b = bundle(root, entries, wanted, f.budget ?? cfg.bundle.budget, f.depth ?? cfg.bundle.depth, { all, task });
             if (json)
                 print(b);
+            else if (b.text === "" && wanted.every((w) => paths.has(w)))
+                io.out(wanted.map((w) => `no links: ${w}\n`).join(""));
             else
                 io.out(b.text);
             return 0;
@@ -296,7 +346,7 @@ export async function run(p, io) {
             if (json)
                 print({ baselined: r.baselined, count: findings.length, findings, warnings: r.warnings });
             else
-                io.out(checkText(r, io.tty));
+                io.out(checkText(r, io.tty, cfg.cli.run));
             return r.findings.length ? 1 : 0;
         }
     }
@@ -309,18 +359,28 @@ async function init(p, io) {
     const root = resolve(io.cwd, p.flags.root ?? ".");
     const all = !!p.flags.all;
     const r = runInit(root, { schema: all || !!p.flags.schema, skills: all || !!p.flags.skills, force: !!p.flags.force });
+    // REQ-CLI-010 init prints its next step with the run prefix of the config it wrote or kept (043/D1)
+    const { loadConfigOrExit } = await import("./config.js");
+    const run = (() => {
+        try {
+            return loadConfigOrExit(root).cli.run;
+        }
+        catch {
+            return defaults().cli.run;
+        }
+    })();
     if (p.flags.json)
         io.out(JSON.stringify(r, null, 2) + "\n");
     else if (r.nothing)
-        io.out("nothing to do\n" + r.notes.map((n) => `${n}\n`).join("") + paint("dim", "next: specctx status\n", io.tty));
+        io.out("nothing to do\n" + r.notes.map((n) => `${n}\n`).join("") + paint("dim", `next: ${runCommand(run, "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).
-        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));
+        const again = [runCommand(run, "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 : runCommand(run, "status")}\n`, io.tty));
     }
     return 0;
 }

package/dist/cli/config.js

@@ -0,0 +1,14 @@
+// REQ-DIST-009 the one function that every command uses to read spec-ctx.toml (033/D4).
+import { ConfigError, loadConfig } from "../config.js";
+import { UsageExit } from "./errors.js";
+/** Read the config. A config error becomes a usage error: one line on stderr and exit 2, never a stack. */
+export function loadConfigOrExit(root) {
+    try {
+        return loadConfig(root);
+    }
+    catch (e) {
+        if (e instanceof ConfigError)
+            throw new UsageExit(e.message);
+        throw e;
+    }
+}

package/dist/cli/gate.js

@@ -1,7 +1,7 @@
-// REQ-CLI-004 specctx gate: check, the baseline against the merge base, both linters, openspec validate, spec length. Stops at the first failure.
+// REQ-LOOP-011 REQ-STAT-005 REQ-CLI-009 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 { join, resolve, sep } from "node:path";
 import { anyMatch, globRe } from "../util/glob.js";
 import { cmpStr } from "../util/pystr.js";
 const SKIP = new Set(["node_modules", ".git", ".ctx", "dist", "build"]);
@@ -45,7 +45,7 @@ export const GATE_STEPS = ["check", "baseline", "lint tells", "lint ste", "valid
 /** 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 });
-    const sorted = { at: line.at, duration_s: line.duration_s, failed_step: line.failed_step, ok: line.ok, steps: line.steps };
+    const sorted = { at: line.at, duration_s: line.duration_s, failed_step: line.failed_step, ok: line.ok, steps: line.steps, strict: line.strict };
     appendFileSync(join(root, GATE_LOG), JSON.stringify(sorted) + "\n");
 }
 export async function runGate(root, o, io) {
@@ -53,7 +53,7 @@ export async function runGate(root, o, io) {
     const ran = [];
     const r = await gateSteps(root, o, io, ran);
     const { isoNow } = await import("../util/time.js");
-    appendGateLog(root, { at: isoNow(), ok: r === null, failed_step: r, duration_s: Math.round((Date.now() - start) / 1000), steps: [...ran] });
+    appendGateLog(root, { at: isoNow(), ok: r === null, failed_step: r, duration_s: Math.round((Date.now() - start) / 1000), steps: [...ran], strict: o.strict });
     return r === null ? 0 : 1;
 }
 /** The gate steps. Returns null when every step passed, else the name of the failed step. */
@@ -203,3 +203,132 @@ export function longRequirements(root) {
     }
     return out;
 }
+/** REQ-CLI-009 the recursion guard: a rerun that a rerun started stops at once. */
+export const RERUN_GUARD = "SPECCTX_RERUN";
+/**
+ * REQ-CLI-009 REQ-VER-005 REQ-VER-006 REQ-VER-007 `gate --rerun`. It runs the Verify command of each task that the range
+ * closed, one group at a time, and compares the exit code with the evidence. It writes no evidence.
+ */
+export async function runRerun(root, cfg, o, io) {
+    if (process.env[RERUN_GUARD]) {
+        io.out(o.json ? JSON.stringify({ ok: true, skipped: `${RERUN_GUARD} is set` }) + "\n" : `rerun: skipped, ${RERUN_GUARD} is set\n`);
+        return 0;
+    }
+    const start = Date.now();
+    const { dumps } = await import("../util/json.js");
+    const { loadIndex } = await import("../index/build.js");
+    const { scanner } = await import("../index/scan.js");
+    const { closedTasks, compare, groupRuns, judge, formatMismatch } = await import("../gate/rerun.js");
+    const { isWeakVerify, parseVerify } = await import("../verify/parse.js");
+    const { evidenceRel } = await import("../tasks/tasks.js");
+    const { runVerify } = await import("../verify/run.js");
+    const { isoNow } = await import("../util/time.js");
+    const finish = (ok) => {
+        appendGateLog(root, { at: isoNow(), ok, failed_step: ok ? null : "rerun", duration_s: Math.round((Date.now() - start) / 1000), steps: ["rerun"], strict: o.strict });
+        return ok ? 0 : 1;
+    };
+    // REQ-VER-013 a zero base passes and a base that this clone lacks fails, before any merge base (042/D3)
+    const { baseProblem } = await import("../gate/rerun.js");
+    const bp = baseProblem(root, o.base);
+    if (bp) {
+        io.out(o.json ? dumps({ base: o.base, ...(bp.ok ? { warning: bp.line } : { error: bp.line }), merge_base: null, ok: bp.ok, tasks: [] }) + "\n" : bp.line + "\n");
+        return finish(bp.ok);
+    }
+    const { data } = loadIndex(root, cfg);
+    const closed = closedTasks(root, o.base, data.entries, scanner(root, cfg).taskRe);
+    if (!closed.ok) {
+        io.out(o.json ? dumps({ base: o.base, error: closed.line, merge_base: null, ok: false, tasks: [] }) + "\n" : closed.line + "\n");
+        return finish(false);
+    }
+    // REQ-VER-010 a merge base at HEAD compares nothing. Say so and pass (041/D4).
+    const { headSha, HEAD_BASE_LINE } = await import("../gate/rerun.js");
+    if (closed.mergeBase === headSha(root)) {
+        io.out(o.json ? dumps({ base: o.base, merge_base: closed.mergeBase, ok: true, tasks: [], warning: HEAD_BASE_LINE }) + "\n" : HEAD_BASE_LINE + "\n");
+        return finish(true);
+    }
+    const lines = [];
+    const pending = [];
+    for (const e of closed.tasks) {
+        const evPath = evidenceRel(e);
+        let ev = null;
+        try {
+            const j = JSON.parse(readFileSync(join(root, evPath), "utf8"));
+            ev = { kind: j.kind, command: j.verify?.command ?? null, exit: j.verify?.exit ?? null, ...(j.cwd !== undefined ? { cwd: j.cwd } : {}) };
+        }
+        catch {
+            ev = null;
+        }
+        const tl = readFileSync(join(root, e.file), "utf8").split(/\r?\n/)[e.line - 1] ?? "";
+        const spec = parseVerify(tl);
+        const v = compare({ command: spec.command, ...(spec.cwd !== undefined ? { cwd: spec.cwd } : {}) }, ev, o.strict, isWeakVerify);
+        const base = { id: e.id, status: "", kind: "ok", file: e.file, line: e.line, evidence: evPath };
+        if (v.act === "warn")
+            lines.push({ ...base, status: "warn manual", kind: "warn" });
+        else if (v.act === "fail")
+            lines.push({ ...base, status: v.kind, kind: "fail", ...(v.detail ? { detail: v.detail } : {}) });
+        else {
+            const l = { ...base, status: "ok" };
+            lines.push(l);
+            pending.push({ id: e.id, command: v.command, cwd: v.cwd, expected: v.expected, line: l });
+        }
+    }
+    // REQ-VER-007 one run per frozen command and cwd. Groups run one at a time.
+    const env = { ...process.env, CI: "1", [RERUN_GUARD]: "1" };
+    for (const g of groupRuns(pending)) {
+        const dir = resolve(root, g.cwd);
+        let out;
+        if (dir !== resolve(root) && !dir.startsWith(resolve(root) + sep))
+            out = { exit: null, timedOut: false, output: `cwd ${g.cwd} is outside the project root\n` };
+        // REQ-VER-009 a missing cwd and a spawn error are a mismatch of the group, not a crash (041/D3)
+        else if (!existsSync(dir))
+            out = { exit: null, timedOut: false, output: `cwd does not exist: ${g.cwd}\n` };
+        else {
+            try {
+                const r = await runVerify(g.command, dir, cfg.verify.timeout_s, env);
+                out = { exit: r.exit, timedOut: r.timedOut, output: r.output };
+            }
+            catch (e) {
+                out = { exit: null, timedOut: false, output: `spawn failed: ${e instanceof Error ? e.message : String(e)}\n` };
+            }
+        }
+        for (const m of g.members) {
+            if (judge(m.expected, out) === "ok")
+                continue;
+            m.line.status = "mismatch";
+            m.line.kind = "fail";
+            m.line.expected_exit = m.expected;
+            m.line.actual_exit = out.exit;
+            m.line.timed_out = out.timedOut;
+            if (out.exit === null && !out.timedOut)
+                m.line.detail = out.output.trim().split("\n")[0] ?? "";
+            m.line.report = formatMismatch({ id: m.id, file: m.line.file, line: m.line.line, evidence: m.line.evidence, expected: m.expected, outcome: out, command: g.command, cwd: g.cwd, timeoutS: cfg.verify.timeout_s });
+        }
+    }
+    const failed = lines.filter((l) => l.kind === "fail");
+    const ok = failed.length === 0;
+    if (o.json) {
+        io.out(dumps({
+            base: o.base,
+            merge_base: closed.mergeBase,
+            ok,
+            tasks: lines.map((l) => {
+                const { report, ...rest } = l;
+                void report;
+                return rest;
+            }),
+        }) + "\n");
+    }
+    else {
+        if (!lines.length)
+            io.out("rerun: no closed tasks\n");
+        for (const l of lines) {
+            if (l.report)
+                io.out(l.report);
+            else
+                io.out(`${l.id}: ${l.status}${l.detail ? ` (${l.detail})` : ""}\n`);
+        }
+        if (lines.length)
+            io.out(`rerun: ${lines.length} task(s), ${failed.length} failure(s)\n`);
+    }
+    return finish(ok);
+}

package/dist/cli/help.js

@@ -38,18 +38,27 @@ export const TABLE = [
         exit: PLAIN, example: "specctx query lockfile --kind req",
     },
     {
-        name: "related", group: "Read", args: "<ID>", summary: "Show the entries that link to an ID.",
+        name: "context", group: "Read", args: "<task|ID|path|change>", summary: "Print what an agent needs before it edits a task, an ID, a file, or a change.",
+        flags: [
+            ["--budget <n>", "Stop at n characters. The default is 8000."],
+            ["--depth <n>", "Follow links n steps. The default is 1."],
+        ],
+        exit: [OK, ["2", "A usage error, an unknown ID, or a bad path. It takes one input. Use `bundle` for several inputs or for `--block`."], INTERNAL], example: "specctx context 045/2.1",
+    },
+    {
+        name: "related", group: "Read", args: "<ID|path|change>", summary: "Show the entries that link to an ID, a file, or a change.",
         flags: [["--depth <n>", "Follow links n steps. The default is 1."], ["--all", "Show all copies of an ID."]],
-        exit: [OK, ["2", "A usage error or an unknown ID."], INTERNAL], example: "specctx related REQ-IDX-001",
+        exit: [OK, ["2", "A usage error, an unknown ID, or a path that is not a file in the repository."], INTERNAL], example: "specctx related src/graph/bundle.ts",
     },
     {
-        name: "bundle", group: "Read", args: "<ID...>", summary: "Print the spec text for the IDs and their links.",
+        name: "bundle", group: "Read", args: "<ID|path|change...>", summary: "Print the spec text for the IDs, files, or changes and their links.",
         flags: [
             ["--budget <n>", "Stop at n characters. The default is 8000."],
             ["--depth <n>", "Follow links n steps. The default is 1."],
             ["--all", "Show all copies of an ID."],
+            ["--block", "Print only the requirement block, as it sits in the spec file. Each ID must be a requirement."],
         ],
-        exit: [OK, ["2", "A usage error or an unknown ID."], INTERNAL], example: "specctx bundle REQ-IDX-001 --budget 3000",
+        exit: [OK, ["2", "A usage error, an unknown ID, a bad path, or an ID that is not a requirement."], INTERNAL], example: "specctx bundle REQ-IDX-001 --budget 3000",
     },
     {
         name: "check", group: "Read", args: "", summary: "Find ID and link errors.",
@@ -62,6 +71,8 @@ export const TABLE = [
         flags: [
             ["--strict", "Run `check` and `openspec validate` in strict mode."],
             ["--markdown <globs>", "Lint these markdown globs instead of [gate] markdown. Separate them with spaces."],
+            ["--rerun", "Run only the rerun step. Run the command of each task that the range closed. Compare its exit code with the evidence."],
+            ["--base <ref>", "With --rerun, take the merge base with this ref. The default is [gate] base."],
         ],
         exit: [["0", "Every step passed."], ["1", "A step failed."], USAGE, INTERNAL], example: "specctx gate --strict",
     },
@@ -114,12 +125,19 @@ 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: [["--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?\"",
+        flags: [
+            ["--change <name>", "Give the question to this change, not to the current task. The key or the full folder name works."],
+            ["--plan", "Mark the question as the plan approval. Only this mark ends the plan stop. It needs --change."],
+        ],
+        exit: PLAIN, example: "specctx handoff ask --change 008 --plan \"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.",
-        flags: [], exit: PLAIN, example: "specctx handoff resolve 1 \"yes, for one release\"",
+        flags: [
+            ["--approve", "Approve a plan or archive question. A plan or archive question needs this or --reject."],
+            ["--reject", "Reject a plan or archive question. The stop stays."],
+        ],
+        exit: PLAIN, example: "specctx handoff resolve 1 --approve \"yes, for one release\"",
     },
     // Setup
     {

package/dist/cli/workflow.js

@@ -1,9 +1,12 @@
-// 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.
+// REQ-IDS-001 REQ-TASK-001 REQ-TASK-002 REQ-TASK-007 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";
 import { paint } from "./color.js";
 import { UsageExit } from "./errors.js";
+import { runCommand } from "../runcmd.js";
+/** REQ-CLI-010 a command to print, with the run prefix of the config (043/D1). */
+const rc = (c, args) => runCommand(c.cfg.cli.run, args);
 const arg = (c, n, what) => {
     const v = c.p.positional[n];
     if (v === undefined)
@@ -62,7 +65,8 @@ export async function runWorkflow(c) {
                 }
                 return 1;
             }
-            const bundleCommand = `specctx bundle ${t.reqs.join(" ")} --budget ${c.cfg.bundle.budget}`;
+            // REQ-TASK-007 the command names the answer that task start prints
+            const bundleCommand = rc(c, `context ${t.id} --budget ${c.cfg.bundle.budget}`);
             if (c.json) {
                 print(c, { bundle_command: bundleCommand, change: t.change, id: t.id, reqs: t.reqs, text: t.text, verify: t.verify.command });
             }
@@ -82,10 +86,10 @@ export async function runWorkflow(c) {
             const { canon } = await import("../index/canonical.js");
             const { bundle } = await import("../graph/bundle.js");
             const ids = canon(entries);
-            const known = t.reqs.filter((r) => ids.has(r));
             for (const r of t.reqs.filter((x) => !ids.has(x)))
                 c.io.err(`warning: task ${t.id} cites ${r}, which the index does not hold\n`);
-            const b = bundle(c.root, entries, known, c.cfg.bundle.budget, c.cfg.bundle.depth);
+            // 047/D5 the entry that findTask found goes in, so an active task wins over an archived one with its number
+            const b = bundle(c.root, entries, [t.id], c.cfg.bundle.budget, c.cfg.bundle.depth, { task: t.entry });
             const { isoNow } = await import("../util/time.js");
             const { CURRENT_PATH } = await import("../handoff/handoff.js");
             mkdirSync(join(c.root, ".ctx"), { recursive: true });
@@ -94,7 +98,7 @@ export async function runWorkflow(c) {
             // 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.`;
+            const hint = t.reqs.length ? null : `task ${t.id} cites no REQ. Run ${rc(c, `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, hint, task: t.id });
             else
@@ -113,7 +117,7 @@ export async function runWorkflow(c) {
                     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}.`);
+                    throw new UsageExit(`task ${t.id} has a Verify command. Run it with ${rc(c, `task done ${t.id}`)}.`);
                 if (t.done && hasEvidence(c.root, t))
                     throw new UsageExit(`task ${t.id} is done`);
                 const { writeEvidence } = await import("../tasks/evidence.js");
@@ -137,7 +141,7 @@ export async function runWorkflow(c) {
             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.`);
+                    throw new UsageExit(`task ${t.id}: the Verify command changed since task start. Run ${rc(c, `task start ${t.id}`)} again.`);
                 }
             }
             const { runVerify, tail } = await import("../verify/run.js");
@@ -170,7 +174,7 @@ export async function runWorkflow(c) {
                 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;
+                    question = addQuestion(c.root, t.id, capQuestion(t.id, fail.file.attempt, outTail), "cap").n;
                 }
                 if (c.json)
                     print(c, { attempt: fail.file.attempt, command: t.verify.command, error: msg, exit: r.exit, fail: fail.rel, question, tail: outTail, task: t.id });
@@ -184,7 +188,7 @@ export async function runWorkflow(c) {
                     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");
+                    c.io.out(blockedLine(question, c.cfg.cli.run) + "\n");
                 return 1;
             }
             const { sha256 } = await import("../util/hash.js");
@@ -197,6 +201,13 @@ export async function runWorkflow(c) {
             }, "command", undefined, t.verify.cwd);
             setBox(c.root, t, true);
             clearCurrent(c.root, t.id);
+            // REQ-LOOP-014 a pass closes the attempt-cap question of the task. Plan, design, and archive questions stay (044/D3).
+            const { isCapQuestion } = await import("../loop/fails.js");
+            const { readQuestions, resolveQuestion } = await import("../handoff/questions.js");
+            for (const q of readQuestions(c.root)) {
+                if (isCapQuestion(q, t.id))
+                    resolveQuestion(c.root, q.n, "Verify passed. Resolved by task done.");
+            }
             if (c.json)
                 print(c, { evidence: rel, kind: "command", task: t.id });
             else
@@ -240,7 +251,10 @@ export async function runWorkflow(c) {
         }
         case "handoff ask": {
             const { ask } = await import("../handoff/handoff.js");
-            const h = ask(c.root, entries, c.p.positional.join(" "), c.p.flags.change);
+            const plan = c.p.flags.plan === true;
+            if (plan && c.p.flags.change === undefined)
+                throw new UsageExit("--plan needs --change");
+            const h = ask(c.root, entries, c.p.positional.join(" "), c.p.flags.change, plan);
             if (c.json)
                 print(c, { open_questions: h.open_questions });
             else
@@ -252,7 +266,10 @@ export async function runWorkflow(c) {
             const n = arg(c, 0, "a question number");
             if (!/^\d+$/.test(n))
                 throw new UsageExit("handoff resolve needs a question number");
-            const h = resolve(c.root, entries, Number(n), c.p.positional.slice(1).join(" "));
+            const approve = c.p.flags.approve === true;
+            const reject = c.p.flags.reject === true;
+            const verdict = approve && reject ? "both" : approve ? "approved" : reject ? "rejected" : undefined;
+            const h = resolve(c.root, entries, Number(n), c.p.positional.slice(1).join(" "), verdict);
             if (c.json)
                 print(c, { open_questions: h.open_questions, resolved: h.resolved });
             else

package/dist/config.js

@@ -21,6 +21,7 @@ export function defaults() {
         // 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" },
+        cli: { run: "specctx" },
     };
 }
 export class ConfigError extends Error {
@@ -43,7 +44,7 @@ export function loadConfig(root) {
         raw = parse(readFileSync(p, "utf8"));
     }
     catch (e) {
-        throw new ConfigError(`${CONFIG_FILE}: the file is not valid TOML. ${e.message.split("\n")[0]}`);
+        throw new ConfigError(`${p}: the file is not valid TOML. ${e.message.split("\n")[0]}`);
     }
     const sec = (name) => {
         const v = raw[name];
@@ -122,6 +123,13 @@ export function loadConfig(root) {
             throw new ConfigError(`${CONFIG_FILE}: loop.archive must be "ask" or "auto".`);
         cfg.loop.archive = v;
     }
+    // REQ-CLI-010 the run prefix of printed commands (043/D1)
+    const cli = sec("cli");
+    if ("run" in cli) {
+        if (typeof cli.run !== "string" || !cli.run.trim())
+            throw new ConfigError(`${CONFIG_FILE}: cli.run must be a string that is not empty.`);
+        cfg.cli.run = cli.run.trim();
+    }
     return cfg;
 }
 /** The file that `specctx init` writes. Each key has a comment above it. */