spec-ctx 0.4.0 → 0.5.0

package/dist/check/hints.js

@@ -1,14 +1,14 @@
 // REQ-CHK-004 the rules of check and one fix hint per rule. The check summary prints the hint of each rule it found.
 /** `hard` rules set exit 1. `advisory` rules print a warning and keep exit 0. */
 export const RULES = {
-    "missing-id": { level: "hard", hint: "Add an ID to the header. Run specctx adopt --dry-run to see the plan." },
+    "missing-id": { level: "hard", hint: "Add an ID to the header. Run {run} adopt --dry-run to see the plan." },
     "scenario-id-mismatch": { level: "hard", hint: "Give the scenario the number of its requirement." },
     "bad-ref": { level: "hard", hint: "Write only IDs on the Refs line, separated by commas." },
     "task-without-req": { level: "hard", hint: "Cite a requirement in brackets on the task line, for example [REQ-ABC-001]." },
     "task-without-verify": { level: "hard", hint: "Add Verify: and a command in backticks to the task line." },
-    "duplicate-id": { level: "hard", hint: "Give one of the two entries a new ID from specctx id new." },
+    "duplicate-id": { level: "hard", hint: "Give one of the two entries a new ID from {run} id new." },
     "duplicate-change-key": { level: "hard", hint: "Rename one change folder, so that each key names one change." },
-    "reused-id": { level: "hard", hint: "The ID is retired. Get a new ID from specctx id new." },
+    "reused-id": { level: "hard", hint: "The ID is retired. Get a new ID from {run} id new." },
     // REQ-CHK-007 the hint names the string literal cause and the fix (033/D3)
     "dangling-ref": {
         level: "hard",
@@ -20,13 +20,13 @@ 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 with a // Covers: <SCN> tag." },
-    "done-without-evidence": { level: "hard", hint: "Run specctx task done. It runs the Verify command and writes the evidence." },
+    "done-without-evidence": { level: "hard", hint: "Run {run} 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." },
+    "stale-evidence": { level: "hard", hint: "Run {run} task reopen <task> <why>, then {run} task done <task>." },
+    "evidence-without-done": { level: "hard", hint: "Run {run} 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." },
+    "manual-evidence": { level: "advisory", hint: "Give the task a Verify command and run {run} 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": {
@@ -34,6 +34,7 @@ export const RULES = {
         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.";
+/** REQ-CLI-010 `{run}` in a hint stands for the run prefix of `[cli] run` (043/D1). */
+export function hintOf(rule, run = "specctx") {
+    return (RULES[rule]?.hint ?? "Read the check rules in the check spec.").replaceAll("{run}", run);
 }

package/dist/cli/args.js

@@ -8,7 +8,9 @@ export const COMMAND_FLAGS = {
     query: { kind: "string", change: "string", all: "bool", limit: "int" },
     related: { depth: "int", all: "bool" },
     bundle: { budget: "int", depth: "int", all: "bool", block: "bool" },
+    context: { budget: "int", depth: "int" },
     check: { strict: "bool" },
+    report: {},
     stats: { change: "string", write: "bool" },
     gate: { strict: "bool", markdown: "string", rerun: "bool", base: "string" },
     "id new": { for: "string", count: "int" },
@@ -20,7 +22,7 @@ export const COMMAND_FLAGS = {
     "task reopen": {},
     "handoff write": {},
     "handoff ask": { change: "string", plan: "bool" },
-    "handoff resolve": {},
+    "handoff resolve": { approve: "bool", reject: "bool" },
     adopt: { "dry-run": "bool" },
     "baseline write": {},
     "baseline prune": {},

package/dist/cli/commands.js

@@ -2,8 +2,11 @@
 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";
+import { note } from "../journal/note.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,12 +29,13 @@ 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", deferred = []) {
     // 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("")
         + r.warnings.map((w) => `warning: ${w}\n`).join("");
-    const base = r.baselined ? `baselined: ${r.baselined}\n` : "";
+    // REQ-CHK-010 a deferred line is not a finding. It comes before the baselined line, which stays last (052/D3).
+    const base = deferred.map((d) => `deferred: ${d.change}  ${d.untested} untested delta item${d.untested === 1 ? "" : "s"}, ${d.open} open task${d.open === 1 ? "" : "s"}\n`).join("") + (r.baselined ? `baselined: ${r.baselined}\n` : "");
     const n = r.findings.length + r.warnings.length;
     if (!n)
         return paint("dim", "0 findings\n", tty) + base;
@@ -62,7 +66,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,8 +77,21 @@ export async function run(p, io) {
         return init(p, io);
     const root = findRoot(io.cwd, f.root);
     requireOpenSpec(root);
+    // REQ-JRN-001 the root is known now, so the bin entry may write the journal
+    note(io, { root });
+    // REQ-JRN-004 report runs before the config load, so a broken config still reports
+    if (cmd === "report") {
+        if (p.positional.length)
+            throw new UsageExit("report takes no arguments");
+        const { buildReport } = await import("../journal/report.js");
+        const { VERSION } = await import("../version.js");
+        io.out(buildReport(root, new Date(), { version: VERSION, node: process.version, platform: process.platform, arch: process.arch }).text);
+        return 0;
+    }
     const { loadConfigOrExit } = await import("./config.js");
     const cfg = loadConfigOrExit(root);
+    // REQ-JRN-006 the exit 3 line names the report command with this prefix
+    note(io, { run: cfg.cli.run });
     const { dumps } = await import("../util/json.js");
     const print = (v) => io.out(dumps(v) + "\n");
     if (cmd === "build") {
@@ -103,7 +120,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") {
@@ -163,7 +180,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);
     }
@@ -176,12 +193,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);
@@ -231,15 +253,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));
@@ -248,37 +290,56 @@ 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-018 a negative budget is a usage error (050/D11)
+            if (f.budget !== undefined && f.budget < 0)
+                throw new UsageExit("--budget must be 0 or more");
+            // 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;
             }
             // 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");
+                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)));
+                // REQ-QRY-019 block mode has no budget, so budget is null and the text is complete (050/D6)
                 if (json)
-                    print({ text, omitted: [] });
+                    print({ text, omitted: [], chars: (await import("../util/pystr.js")).cpLen(text), budget: null, complete: true });
                 else
                     io.out(text);
                 return 0;
             }
-            const b = bundle(root, entries, p.positional, f.budget ?? cfg.bundle.budget, f.depth ?? cfg.bundle.depth, all);
+            // 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 });
+            // REQ-JRN-002 only context emits the block signals. The sink is set only for the bin entry.
+            if (cmd === "context" && io.journal) {
+                const { contextSignals } = await import("../journal/signals.js");
+                for (const signal of contextSignals(entries, b))
+                    note(io, { signal });
+            }
             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;
@@ -307,10 +368,12 @@ export async function run(p, io) {
             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);
+            // REQ-CHK-010 only this case computes the deferred notice. runCheck and gate stay as they are (052/D5).
+            const deferred = f.strict ? (await import("../check/check.js")).deferredOf(entries, data) : [];
             if (json)
-                print({ baselined: r.baselined, count: findings.length, findings, warnings: r.warnings });
+                print({ baselined: r.baselined, count: findings.length, findings, warnings: r.warnings, ...(f.strict ? { deferred } : {}) });
             else
-                io.out(checkText(r, io.tty));
+                io.out(checkText(r, io.tty, cfg.cli.run, deferred));
             return r.findings.length ? 1 : 0;
         }
     }
@@ -323,18 +386,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/help.js

@@ -38,19 +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>", "Keep the blocks to n characters. A requested block always prints, also when it is longer. Then the over budget line gives the size. The truncated line is not in this limit. 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."],
+            ["--budget <n>", "Keep the blocks to n characters. A requested block always prints, also when it is longer. Then the over budget line gives the size. The truncated line is not in this limit. 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, an unknown ID, or an ID that is not a requirement."], 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.",
@@ -82,6 +90,11 @@ export const TABLE = [
         flags: [["--change <name>", "Show only this change."], ["--write", "Also write docs/metrics/<date>.md."]],
         exit: PLAIN, example: "specctx stats --write",
     },
+    {
+        name: "report", group: "Read", args: "", summary: "Print a bug report from the run journal in .ctx/local. Review it, then file it with `gh issue create`. Write nothing.",
+        flags: [],
+        exit: [OK, ["2", "A usage error."], INTERNAL], example: "specctx report > report.md",
+    },
     {
         name: "lint tells", group: "Read", args: "<file...>", summary: "Find the AI writing tells in markdown files. Read stdin when no file is given.",
         flags: LINT_FLAGS, exit: LINT_EXIT, example: "specctx lint tells --baseline 0 README.md",
@@ -125,7 +138,11 @@ export const TABLE = [
     },
     {
         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");
@@ -167,10 +171,13 @@ export async function runWorkflow(c) {
                 // 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);
+                // REQ-TASK-008 the fail file and the cap question hold no machine path. The printed tail stays as it is (056/D5).
+                const { redactPaths } = await import("../util/redact.js");
+                const kept = redactPaths(outTail, c.root);
+                const fail = writeFail(c.root, t.id, { command: t.verify.command, exit: r.timedOut ? null : r.exit }, kept);
                 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, kept), "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 +191,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");
@@ -192,11 +199,20 @@ export async function runWorkflow(c) {
             // the Verify command can change tagged files, so the digests come from the tree after the run
             const { loadIndex } = await import("../index/build.js");
             const after = loadIndex(c.root, c.cfg).data.entries;
+            // REQ-TASK-008 the stderr tail holds no machine path. verify.command stays as the task line has it (056/D5, 056/D6).
+            const { redactPaths } = await import("../util/redact.js");
             const rel = writeEvidence(c.root, t, after, {
-                command: t.verify.command, exit: 0, stdout_sha256: sha256(r.stdout), stderr_tail: tail(r.stderr.toString("utf8")),
+                command: t.verify.command, exit: 0, stdout_sha256: sha256(r.stdout), stderr_tail: redactPaths(tail(r.stderr.toString("utf8")), c.root),
             }, "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
@@ -255,7 +271,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/cli.js

@@ -1,14 +1,53 @@
 #!/usr/bin/env node
 // REQ-CLI-001 bin entry. tests call main() from src/main.ts in process.
+// REQ-JRN-001 this entry writes the run journal after main() returns. main() only fills the sink (057/D1).
 import { main } from "./main.js";
+import { VERSION } from "./version.js";
 process.stdout.on("error", (e) => {
     if (e.code === "EPIPE")
         process.exit(0);
 });
-const code = await main(process.argv.slice(2), {
-    cwd: process.cwd(),
-    out: (s) => process.stdout.write(s),
-    err: (s) => process.stderr.write(s),
-    tty: process.stdout.isTTY === true,
-});
+const argv = process.argv.slice(2);
+const sink = { signals: new Set() };
+const t0 = performance.now();
+let code;
+let thrown;
+let failed = false;
+try {
+    code = await main(argv, {
+        cwd: process.cwd(),
+        out: (s) => process.stdout.write(s),
+        err: (s) => process.stderr.write(s),
+        tty: process.stdout.isTTY === true,
+        journal: sink,
+    });
+}
+catch (e) {
+    failed = true;
+    thrown = e;
+    code = 3;
+    try {
+        const { errInfo } = await import("./journal/note.js");
+        sink.err = errInfo(e);
+    }
+    catch {
+        // no journal detail
+    }
+}
+try {
+    // REQ-JRN-001 a usage error before the root check keeps no root. Only the "?" command with no --root looks for one (057/D2).
+    if (sink.root === undefined && sink.cmd === "?" && !argv.some((a) => a === "--root" || a.startsWith("--root="))) {
+        const { findRoot } = await import("./cli/root.js");
+        sink.root = findRoot(process.cwd());
+    }
+    if (sink.root !== undefined && process.env.SPECCTX_JOURNAL !== "0") {
+        const { appendRun } = await import("./journal/journal.js");
+        appendRun(sink, { exit: code, ms: performance.now() - t0, version: VERSION });
+    }
+}
+catch {
+    // the journal never changes the exit code or the output
+}
+if (failed)
+    throw thrown;
 process.exitCode = code;

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 {
@@ -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. */