spec-ctx 0.0.0-stage → 0.1.0

package/dist/cli/help.js

@@ -0,0 +1,230 @@
+// REQ-CLI-001 REQ-CLI-002 REQ-CLI-006 help text from one table of command records.
+// `specctx --help` renders the three groups. `specctx <cmd> --help` renders one page.
+// Every page passes `specctx lint ste --baseline 0`. Command names stay in backticks, so the lint reads them as code.
+import { COMMANDS, GROUPS } from "./args.js";
+const OK = ["0", "Success."];
+const USAGE = ["2", "A usage error."];
+const INTERNAL = ["3", "An internal error."];
+const PLAIN = [OK, USAGE, INTERNAL];
+const GLOBAL = [
+    ["--root <path>", "Use this project root."],
+    ["--json", "Print one JSON document."],
+    ["--help", "Show this help."],
+];
+const LINT_FLAGS = [
+    ["--baseline <n>", "Exit 0 when the hard findings are n or fewer. The default is 0."],
+    ["--disable <rules>", "Ignore these rules. Separate them with commas."],
+    ["--json", "Print the findings as JSON."],
+    ["--selftest", "Run the built in tests of the linter."],
+    ["--help", "Show this help."],
+];
+const LINT_EXIT = [["0", "The hard findings are at the baseline or below."], ["1", "The hard findings are over the baseline."], USAGE];
+export const TABLE = [
+    // Read
+    { name: "status", group: "Read", args: "", summary: "Show the active changes, the current task, and the open questions.", flags: [], exit: PLAIN, example: "specctx status" },
+    {
+        name: "query", group: "Read", args: "<term...>", summary: "Find the entries that contain all terms.",
+        flags: [
+            ["--kind <kind>", "Show only entries of this kind."],
+            ["--change <name>", "Show only entries of this change. The key or the full folder name works."],
+            ["--limit <n>", "Show n lines at most. The default is 20. Use 0 for no limit."],
+            ["--all", "Show all copies of an ID."],
+        ],
+        exit: PLAIN, example: "specctx query lockfile --kind req",
+    },
+    {
+        name: "related", group: "Read", args: "<ID>", summary: "Show the entries that link to an ID.",
+        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",
+    },
+    {
+        name: "bundle", group: "Read", args: "<ID...>", summary: "Print the spec text for the IDs 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."],
+        ],
+        exit: [OK, ["2", "A usage error or an unknown ID."], INTERNAL], example: "specctx bundle REQ-IDX-001 --budget 3000",
+    },
+    {
+        name: "check", group: "Read", args: "", summary: "Find ID and link errors.",
+        flags: [["--strict", "Also find gaps in tests and evidence."]],
+        exit: [["0", "No finding."], ["1", "One finding or more."], USAGE, INTERNAL], example: "specctx check --strict",
+    },
+    {
+        name: "gate", group: "Read", args: "",
+        summary: "Run `check`, the markdown linters, `openspec validate`, and the length check. Stop at the first failure.",
+        flags: [
+            ["--strict", "Run `check` and `openspec validate` in strict mode."],
+            ["--markdown <globs>", "Lint these markdown globs. Separate them with spaces."],
+        ],
+        exit: [["0", "Every step passed."], ["1", "A step failed."], USAGE, INTERNAL], example: "specctx gate --strict",
+    },
+    {
+        name: "task next", group: "Read", args: "", summary: "Show the next open task.",
+        flags: [["--change <name>", "Look only in this change. The key or the full folder name works."]],
+        exit: [["0", "An open task."], ["1", "No open task."], USAGE, INTERNAL], example: "specctx task next --change 008",
+    },
+    {
+        name: "task verify", group: "Read", args: "<task>", summary: "Run the `Verify:` command of a task. Write nothing.",
+        flags: [], exit: [["0", "The command passed."], ["1", "The command failed."], USAGE, INTERNAL], example: "specctx task verify 008/1.1",
+    },
+    {
+        name: "stats", group: "Read", args: "", summary: "Show five metrics for each change and the gate runs.",
+        flags: [["--change <name>", "Show only this change."], ["--write", "Also write docs/metrics/<date>.md."]],
+        exit: PLAIN, example: "specctx stats --write",
+    },
+    {
+        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",
+    },
+    {
+        name: "lint ste", group: "Read", args: "<file...>", summary: "Find the breaks of the structural STE rules in markdown files. Read stdin when no file is given.",
+        flags: LINT_FLAGS, exit: LINT_EXIT, example: "specctx lint ste --baseline 0 README.md",
+    },
+    // Write
+    { name: "build", group: "Write", args: "", summary: "Write the index to .ctx/index.json.", flags: [], exit: PLAIN, example: "specctx build" },
+    {
+        name: "id new", group: "Write", args: "<kind> <code>", summary: "Print the next free ID. The kind is REQ, SCN, ADR, or DEC.",
+        flags: [["--for <REQ-ID>", "Give the requirement of a new scenario."], ["--count <n>", "Print n IDs in sequence."]],
+        exit: [OK, ["2", "A usage error or an unknown code."], INTERNAL], example: "specctx id new REQ IDX",
+    },
+    {
+        name: "id retire", group: "Write", args: "<ID> <reason>", summary: "Add an ID to decisions/retired-ids.md.",
+        flags: [], exit: [OK, ["2", "A usage error, or the ID is still in use."], INTERNAL], example: "specctx id retire REQ-IDX-009 merged into REQ-IDX-001",
+    },
+    {
+        name: "task start", group: "Write", args: "<task>", summary: "Print the bundle of a task and set it as the current task.",
+        flags: [], exit: [OK, ["2", "A usage error, or the task is done or unknown."], INTERNAL], example: "specctx task start 008/1.1",
+    },
+    {
+        name: "task done", group: "Write", args: "<task>", summary: "Run the `Verify:` command. On success, write the evidence and set the checkbox.",
+        flags: [["--manual <note>", "Record a manual note. A task with no `Verify:` command needs this flag."]],
+        exit: [OK, ["1", "The `Verify:` command failed. The task stays open."], USAGE, INTERNAL], example: "specctx task done 008/1.1",
+    },
+    {
+        name: "task reopen", group: "Write", args: "<task> <why>", summary: "Clear the checkbox and keep the old evidence.",
+        flags: [], exit: PLAIN, example: "specctx task reopen 008/1.1 the spec changed",
+    },
+    { 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?\"",
+    },
+    {
+        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\"",
+    },
+    // Setup
+    {
+        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."],
+            ["--all", "Do all three."],
+            ["--force", "Install over files that exist. An existing spec-ctx.toml stays."],
+        ],
+        exit: PLAIN, example: "specctx init --all",
+    },
+    {
+        name: "adopt", group: "Setup", args: "", summary: "Write IDs into the headers of the main specs and the active deltas. Undo on a new finding.",
+        flags: [["--dry-run", "Show the ID that each header without an ID gets. Write nothing."]],
+        exit: [["0", "The IDs are written, or nothing is left to adopt."], ["1", "The dry run found headers to adopt, or a new finding undid the write."], USAGE, INTERNAL],
+        example: "specctx adopt --dry-run",
+    },
+    {
+        name: "task backfill", group: "Setup", args: "--manual <note>", summary: "Write manual evidence for every ticked task that has none.",
+        flags: [["--manual <note>", "The note for the evidence. The flag is required."], ["--change <name>", "Look only in this change."]],
+        exit: PLAIN, example: "specctx task backfill --manual \"done before spec-ctx\"",
+    },
+    {
+        name: "baseline write", group: "Setup", args: "", summary: "Record the current debt in .ctx/baseline.json. `check` then hides it.",
+        flags: [], exit: PLAIN, example: "specctx baseline write",
+    },
+    { name: "baseline prune", group: "Setup", args: "", summary: "Remove the entries that no longer apply.", flags: [], exit: PLAIN, example: "specctx baseline prune" },
+    {
+        name: "help", group: "Setup", args: "<command>", summary: "Show the help page of one command.",
+        flags: [], exit: [OK, ["2", "An unknown command."]], example: "specctx help task start",
+    },
+];
+const WIDTH = 29;
+/** One label line: two spaces, the label in backticks, padded. A long label puts the text on the next line. */
+function row(label, text) {
+    const cell = `\`${label}\``;
+    if (cell.length < WIDTH)
+        return `  ${cell.padEnd(WIDTH)}${text}`;
+    return `  ${cell}\n  ${" ".repeat(WIDTH)}${text}`;
+}
+const usageOf = (c) => `${c.name}${c.args ? " " + c.args : ""}`;
+function overview() {
+    const out = ["specctx: a context engine and task workflow for OpenSpec projects.", "", "Usage: specctx <command> [flags]", ""];
+    for (const g of ["Read", "Write", "Setup"]) {
+        out.push(`${g}:`);
+        for (const c of TABLE.filter((x) => x.group === g))
+            out.push(row(c.label ?? usageOf(c), c.summary));
+        out.push("");
+    }
+    out.push("Command flags:");
+    for (const c of TABLE) {
+        if (c.name.startsWith("lint "))
+            continue;
+        for (const [flag, text] of c.flags)
+            out.push(row(`${c.name} ${flag}`, text));
+    }
+    for (const [flag, text] of LINT_FLAGS.filter(([f]) => f !== "--help"))
+        out.push(row(`lint ${flag}`, text));
+    out.push("");
+    out.push("Global flags:");
+    for (const [flag, text] of GLOBAL)
+        out.push(row(flag, text));
+    out.push(row("--version", "Show the version."));
+    out.push("");
+    out.push("Exit codes: 0 for success, 1 for findings or a failed `Verify:` command, 2 for a usage error, 3 for an internal error.");
+    out.push("Run `specctx help <command>` or `specctx <command> --help` for the page of one command.");
+    return out.join("\n") + "\n";
+}
+export const HELP = overview();
+/** REQ-CLI-006 the page of one command: Usage, Flags, Exit codes, Example. */
+export function commandPage(c) {
+    const lint = c.name.startsWith("lint ");
+    const flags = lint ? c.flags : [...c.flags, ...GLOBAL];
+    const out = [
+        `specctx ${c.name}: ${c.summary}`,
+        "",
+        "Usage:",
+        `  \`specctx ${usageOf(c)}${flags.length ? " [flags]" : ""}\``,
+        "",
+        "Flags:",
+        ...flags.map(([f, t]) => row(f, t)),
+        "",
+        "Exit codes:",
+        ...c.exit.map(([code, t]) => `  \`${code}\` ${t}`),
+        "",
+        "Example:",
+        `  \`${c.example}\``,
+    ];
+    return out.join("\n") + "\n";
+}
+export function findHelp(name) {
+    return TABLE.find((c) => c.name === name);
+}
+/**
+ * The help for `specctx help <words>` or `specctx <words> --help`. A group name such as `task`
+ * prints the pages of its subcommands. Unknown words return null.
+ */
+export function helpFor(name) {
+    const one = findHelp(name);
+    if (one)
+        return commandPage(one);
+    if (GROUPS.includes(name) || name === "lint") {
+        const subs = TABLE.filter((c) => c.name.startsWith(name + " "));
+        if (subs.length)
+            return subs.map(commandPage).join("\n");
+    }
+    return null;
+}
+/** REQ-CLI-002 REQ-CLI-006 the command list of the unknown command error. `help` and `lint` are in it. */
+export function commandList() {
+    const names = [...COMMANDS, "lint", "help"];
+    return `commands: ${names.join(", ")}\n`;
+}

package/dist/cli/root.js

@@ -0,0 +1,32 @@
+// REQ-CLI-001 root discovery: --root, else the nearest parent with spec-ctx.toml or openspec/.
+// REQ-CLI-007 a root without openspec/ is no OpenSpec project. The command stops before it writes.
+import { existsSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { UsageExit } from "./errors.js";
+/** REQ-CLI-007 exit 2 with the fixed message when the root has no openspec/ folder. */
+export function requireOpenSpec(root) {
+    const os = join(root, "openspec");
+    if (existsSync(os) && statSync(os).isDirectory())
+        return;
+    throw new UsageExit(`not an OpenSpec project (no openspec/ under ${root}). Run npx -y @fission-ai/openspec@latest init first.`);
+}
+export function findRoot(cwd, explicit) {
+    if (explicit !== undefined) {
+        const r = resolve(cwd, explicit);
+        if (!existsSync(r) || !statSync(r).isDirectory())
+            throw new UsageExit(`the root ${explicit} is not a directory`);
+        return r;
+    }
+    let dir = resolve(cwd);
+    for (;;) {
+        if (existsSync(join(dir, "spec-ctx.toml")))
+            return dir;
+        const os = join(dir, "openspec");
+        if (existsSync(os) && statSync(os).isDirectory())
+            return dir;
+        const up = dirname(dir);
+        if (up === dir)
+            return resolve(cwd);
+        dir = up;
+    }
+}

package/dist/cli/status.js

@@ -0,0 +1,116 @@
+// REQ-CLI-001 status reads the index, the handoff file, 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 { 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. */
+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;
+}
+/** REQ-HND-003 the current task from the handoff file. */
+function handoffCurrent(root) {
+    const p = join(root, HANDOFF_PATH);
+    if (!existsSync(p))
+        return null;
+    for (const line of splitLines(readFileSync(p).toString("utf8"))) {
+        const m = /^current: (.*)$/s.exec(line);
+        if (m)
+            return pyStrip(m[1]);
+    }
+    return null;
+}
+/**
+ * The `archived` value of an archive folder. OpenSpec does not write it today,
+ * so the date at the start of the folder name is the fallback.
+ */
+export function archivedAt(root, folder) {
+    const p = join(root, "openspec", "changes", "archive", folder, ".openspec.yaml");
+    if (existsSync(p)) {
+        const m = /^archived:[ \t]*["']?([^"'\s#]+)/m.exec(readFileSync(p, "utf8"));
+        if (m)
+            return m[1];
+    }
+    return /^\d{4}-\d{2}-\d{2}/.exec(folder)?.[0] ?? "";
+}
+export function statusReport(root, entries) {
+    const changes = new Map();
+    const archived = new Set();
+    for (const e of entries) {
+        const m = /^openspec\/changes\/archive\/([^/]+)\//.exec(e.file);
+        if (m) {
+            archived.add(m[1]);
+            continue;
+        }
+        if (e.kind === "task" && (e.status === "done" || e.status === "open") && e.change !== "main") {
+            let c = changes.get(e.change);
+            if (!c)
+                changes.set(e.change, (c = { done: 0, open: 0 }));
+            c[e.status]++;
+        }
+    }
+    const covered = new Set(entries.filter((e) => e.kind === "test").flatMap((e) => e.refs));
+    const uncovered = entries.filter((e) => e.kind === "req" && e.change === "main" && e.status === "active" && !covered.has(e.id));
+    // REQ-CLI-001 order by the archived time in .openspec.yaml, then by folder name
+    const last = [...archived].map((n) => ({ n, at: archivedAt(root, n) })).sort((a, b) => cmpStr(a.at, b.at) || cmpStr(a.n, b.n)).pop()?.n;
+    const handoff = existsSync(join(root, HANDOFF_PATH));
+    return {
+        changes: [...changes.keys()].sort(cmpStr).map((c) => ({ change: c, ...changes.get(c) })),
+        last_archived: last ? changeOf(`openspec/changes/archive/${last}/`) : null,
+        uncovered: uncovered.length,
+        handoff,
+        current: handoff ? handoffCurrent(root) : null,
+        open_questions: handoff ? openQuestions(root) : [],
+    };
+}
+export function statusLines(r) {
+    const out = r.changes.map((c) => `${c.change}  done ${c.done}  open ${c.open}`);
+    if (!r.changes.length) {
+        out.push("no active change");
+        if (r.last_archived !== null)
+            out.push(`last archived: ${r.last_archived}`);
+    }
+    out.push(`uncovered active REQs in main: ${r.uncovered}`);
+    if (r.handoff) {
+        out.push(`handoff: ${HANDOFF_PATH} (read it first)`);
+        if (r.current !== null)
+            out.push(`current: ${r.current}`);
+        out.push(`open_questions: ${r.open_questions.length}`);
+        // with no active change the questions are the agenda, so status prints them
+        if (!r.changes.length)
+            for (const q of r.open_questions)
+                out.push(`- ${q}`);
+    }
+    const next = nextStep(r);
+    if (next)
+        out.push(`next: ${next}`);
+    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

@@ -0,0 +1,274 @@
+// REQ-IDS-001 REQ-TASK-001 REQ-TASK-002 REQ-TASK-003 REQ-TASK-005 REQ-VER-002 REQ-HND-001 write commands.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { dumps } from "../util/json.js";
+import { UsageExit } from "./errors.js";
+const arg = (c, n, what) => {
+    const v = c.p.positional[n];
+    if (v === undefined)
+        throw new UsageExit(`${c.p.command} needs ${what}`);
+    return v;
+};
+const noMore = (c, n) => {
+    if (c.p.positional.length > n)
+        throw new UsageExit(`${c.p.command} takes ${n} argument(s)`);
+};
+const print = (c, v) => c.io.out(dumps(v) + "\n");
+export async function runWorkflow(c) {
+    const entries = c.data.entries;
+    const f = c.p.flags;
+    switch (c.p.command) {
+        case "id new": {
+            const { newIds } = await import("../ids/ids.js");
+            const kind = arg(c, 0, "a kind: REQ, SCN, ADR, or DEC");
+            noMore(c, 2);
+            const ids = newIds(c.root, c.cfg, entries, {
+                kind, cap: c.p.positional[1], forReq: f.for, count: f.count ?? 1,
+            });
+            if (c.json)
+                print(c, ids);
+            else
+                c.io.out(ids.map((i) => i + "\n").join(""));
+            return 0;
+        }
+        case "id retire": {
+            const { retire } = await import("../ids/ids.js");
+            const id = arg(c, 0, "an ID");
+            const reason = c.p.positional.slice(1).join(" ");
+            const row = retire(c.root, entries, id, reason);
+            if (c.json)
+                print(c, { retired: id, row });
+            else
+                c.io.out(`retired ${id} in decisions/retired-ids.md\n`);
+            return 0;
+        }
+        case "task next": {
+            noMore(c, 0);
+            const { nextTask } = await import("../tasks/tasks.js");
+            const t = nextTask(c.root, entries, f.change);
+            if (!t) {
+                if (c.json)
+                    print(c, null);
+                else {
+                    // REQ-TASK-001 name the next step. The exit code stays 1.
+                    const { activeChanges } = await import("../tasks/tasks.js");
+                    const { matchesChange } = await import("../index/scan.js");
+                    const want = f.change;
+                    const ready = activeChanges(entries).filter((x) => !want || matchesChange(x, want));
+                    c.io.out(ready.length
+                        ? `no open task. Every task in the active changes is done. Next: archive ${ready.join(", ")}.\n`
+                        : "no open task. No active change has a task.\n");
+                }
+                return 1;
+            }
+            const bundleCommand = `specctx bundle ${t.reqs.join(" ")} --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 });
+            }
+            else {
+                c.io.out(`${t.id}  ${t.text}\nreqs: ${t.reqs.join(", ") || "none"}\nverify: ${t.verify.command ?? "manual"}\n`);
+            }
+            return 0;
+        }
+        case "task start": {
+            const { findTask } = await import("../tasks/tasks.js");
+            const t = findTask(c.root, entries, arg(c, 0, "a task ID"));
+            noMore(c, 1);
+            if (t.done)
+                throw new UsageExit(`task ${t.id} is done`);
+            if (t.archived)
+                throw new UsageExit(`task ${t.id} is in an archived change`);
+            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);
+            const { isoNow } = await import("../util/time.js");
+            const { CURRENT_PATH } = await import("../handoff/handoff.js");
+            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");
+            if (c.json)
+                print(c, { bundle: b, task: t.id });
+            else
+                c.io.out(b.text);
+            return 0;
+        }
+        case "task verify":
+        case "task done": {
+            const { findTask, setBox, hasEvidence } = await import("../tasks/tasks.js");
+            const t = findTask(c.root, entries, arg(c, 0, "a task ID"));
+            noMore(c, 1);
+            const dry = c.p.command === "task verify";
+            const manual = f.manual;
+            if (!dry && manual !== undefined) {
+                if (!manual.trim())
+                    throw new UsageExit("--manual needs a note");
+                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());
+                if (!t.done)
+                    setBox(c.root, t, true);
+                clearCurrent(c.root, t.id);
+                if (c.json)
+                    print(c, { evidence: rel, kind: "manual", task: t.id });
+                else
+                    c.io.out(`done ${t.id} (manual). Evidence: ${rel}\n`);
+                return 0;
+            }
+            if (!dry && t.done)
+                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'}`);
+            }
+            const { runVerify, tail } = await import("../verify/run.js");
+            const { resolve: resolvePath, relative, isAbsolute } = await import("node:path");
+            let dir = c.root;
+            if (t.verify.cwd !== undefined) {
+                // REQ-VER-004 the cwd prefix must stay inside the project root
+                dir = resolvePath(c.root, t.verify.cwd);
+                const rel = relative(c.root, dir);
+                if (rel.startsWith("..") || isAbsolute(rel))
+                    throw new UsageExit(`the Verify cwd ${t.verify.cwd} is outside the project root`);
+                const { existsSync: exists } = await import("node:fs");
+                if (!exists(dir))
+                    throw new UsageExit(`the Verify cwd ${t.verify.cwd} does not exist`);
+            }
+            const r = await runVerify(t.verify.command, dir, c.cfg.verify.timeout_s);
+            const outTail = tail(r.output);
+            if (dry) {
+                if (c.json)
+                    print(c, { command: t.verify.command, exit: r.exit, tail: outTail, timed_out: r.timedOut });
+                else
+                    c.io.out(`${outTail ? outTail + "\n" : ""}exit ${r.timedOut ? "timeout" : r.exit}\n`);
+                return r.exit === 0 ? 0 : 1;
+            }
+            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}`;
+                if (c.json)
+                    print(c, { command: t.verify.command, error: msg, exit: r.exit, tail: outTail, task: t.id });
+                else
+                    c.io.out(outTail ? outTail + "\n" : "");
+                c.io.err(`specctx: ${msg}. Task ${t.id} stays open.\n`);
+                return 1;
+            }
+            const { sha256 } = await import("../util/hash.js");
+            const { writeEvidence } = await import("../tasks/evidence.js");
+            // 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;
+            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", undefined, t.verify.cwd);
+            setBox(c.root, t, true);
+            clearCurrent(c.root, t.id);
+            if (c.json)
+                print(c, { evidence: rel, kind: "command", task: t.id });
+            else
+                c.io.out(`done ${t.id}. Evidence: ${rel}\n`);
+            return 0;
+        }
+        case "task backfill": {
+            // REQ-TASK-006 manual evidence for every ticked task that has none, through the task done --manual path
+            noMore(c, 0);
+            const note = f.manual?.trim();
+            if (!note)
+                throw new UsageExit('task backfill needs --manual "<note>"');
+            const { tasksOf, toTask, hasEvidence } = await import("../tasks/tasks.js");
+            const { matchesChange } = await import("../index/scan.js");
+            const { writeEvidence } = await import("../tasks/evidence.js");
+            const want = f.change;
+            const counts = new Map();
+            for (const e of tasksOf(entries)) {
+                if (e.status !== "done")
+                    continue;
+                if (want && !matchesChange(e.change, want))
+                    continue;
+                if (hasEvidence(c.root, e))
+                    continue;
+                const t = toTask(c.root, e);
+                writeEvidence(c.root, t, entries, { command: t.verify.command, exit: null, stdout_sha256: null, stderr_tail: "" }, "manual", note);
+                counts.set(e.change, (counts.get(e.change) ?? 0) + 1);
+            }
+            const { cmpStr } = await import("../util/pystr.js");
+            const rows = [...counts.keys()].sort(cmpStr).map((k) => ({ change: k, count: counts.get(k) }));
+            const total = rows.reduce((n, r) => n + r.count, 0);
+            if (c.json)
+                print(c, { changes: rows, total });
+            else
+                c.io.out(rows.map((r) => `${r.change}: ${r.count}\n`).join("") + `backfilled ${total} task(s)\n`);
+            return 0;
+        }
+        case "task reopen": {
+            const { findTask, setBox } = await import("../tasks/tasks.js");
+            const t = findTask(c.root, entries, arg(c, 0, "a task ID"));
+            const reason = c.p.positional.slice(1).join(" ").trim();
+            if (!reason)
+                throw new UsageExit("task reopen needs a reason");
+            if (!t.done)
+                throw new UsageExit(`task ${t.id} is open`);
+            if (t.archived)
+                throw new UsageExit(`task ${t.id} is in an archived change`);
+            const { retireEvidence } = await import("../tasks/evidence.js");
+            const { addReopened } = await import("../handoff/handoff.js");
+            setBox(c.root, t, false);
+            const moved = retireEvidence(c.root, t, reason);
+            addReopened(c.root, entries, t.id, reason);
+            if (c.json)
+                print(c, { evidence: moved, task: t.id });
+            else
+                c.io.out(`reopened ${t.id}.${moved ? ` Old evidence: ${moved}` : ""}\n`);
+            return 0;
+        }
+        case "handoff write": {
+            noMore(c, 0);
+            const { writeHandoff, HANDOFF_PATH } = await import("../handoff/handoff.js");
+            const h = writeHandoff(c.root, entries);
+            if (c.json)
+                print(c, h);
+            else
+                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(" "));
+            if (c.json)
+                print(c, { open_questions: h.open_questions });
+            else
+                c.io.out(`open question ${h.open_questions.length} added\n`);
+            return 0;
+        }
+        case "handoff resolve": {
+            const { resolve } = await import("../handoff/handoff.js");
+            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(" "));
+            if (c.json)
+                print(c, { open_questions: h.open_questions, resolved: h.resolved });
+            else
+                c.io.out(`resolved question ${n}\n`);
+            return 0;
+        }
+    }
+    throw new UsageExit(`unknown command: ${c.p.command}`);
+}
+function clearCurrent(root, task) {
+    const p = join(root, ".ctx/current.json");
+    if (!existsSync(p))
+        return;
+    try {
+        const cur = JSON.parse(readFileSync(p, "utf8"));
+        if (cur.task === task)
+            rmSync(p);
+    }
+    catch {
+        // a damaged current.json stays for the user to read
+    }
+}

package/dist/cli.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// REQ-CLI-001 bin entry. tests call main() from src/main.ts in process.
+import { main } from "./main.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),
+});
+process.exitCode = code;