spec-ctx 0.2.0 → 0.4.0

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

@@ -48,8 +48,9 @@ export const TABLE = [
             ["--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, 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 +63,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,7 +117,11 @@ export const TABLE = [
     { name: "handoff write", group: "Write", args: "", summary: "Write .ctx/handoff.md from the index and the evidence.", flags: [], exit: PLAIN, example: "specctx handoff write" },
     {
         name: "handoff ask", group: "Write", args: "<question>", summary: "Add an open question to the handoff.",
-        flags: [], exit: PLAIN, example: "specctx handoff ask \"Keep the old flag?\"",
+        flags: [
+            ["--change <name>", "Give the question to this change, not to the current task. The key or the full folder name works."],
+            ["--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.",

package/dist/cli/status.js

@@ -64,7 +64,11 @@ export function statusReport(root, entries) {
         open_questions: openQuestions(root),
     };
 }
-export function statusLines(r) {
+/**
+ * REQ-CLI-007 the status lines. The last line is always `next: ` and the command of the decision
+ * of `specctx next`, or `none` when the decision has no command (030/D1, 030/D2).
+ */
+export function statusLines(r, next) {
     const out = r.changes.map((c) => `${c.change}  done ${c.done}  open ${c.open}`);
     if (!r.changes.length) {
         out.push("no active change");
@@ -82,19 +86,6 @@ export function statusLines(r) {
             for (const q of r.open_questions)
                 out.push(`- ${q}`);
     }
-    const next = nextStep(r);
-    if (next)
-        out.push(`next: ${next}`);
+    out.push(`next: ${next ?? "none"}`);
     return out;
 }
-/** REQ-CLI-007 the next step by state: an open task, then a change with every task done, then uncovered REQs. */
-export function nextStep(r) {
-    if (r.changes.some((c) => c.open > 0))
-        return "specctx task next";
-    const ready = r.changes.find((c) => c.done > 0 && c.open === 0);
-    if (ready)
-        return `archive ${ready.change}`;
-    if (r.uncovered > 0)
-        return "specctx check";
-    return null;
-}

package/dist/cli/workflow.js

@@ -240,7 +240,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(" "));
+            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

package/dist/config.js

@@ -43,7 +43,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];

package/dist/gate/rerun.js

@@ -0,0 +1,169 @@
+// REQ-VER-013 REQ-VER-005 REQ-VER-006 REQ-VER-007 the rerun step: the tasks a range closed, the compare, the groups (036/D1).
+import { spawnSync } from "node:child_process";
+import { changeKey, changeOf } from "../index/scan.js";
+import { cmpStr } from "../util/pystr.js";
+function git(root, args) {
+    const r = spawnSync("git", args, { cwd: root, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    return { ok: r.status === 0, out: (r.stdout ?? "").trim() };
+}
+/** REQ-VER-005 the one line of a failed merge base. A shallow clone gets a second sentence. */
+export function noMergeBaseLine(root, base) {
+    const shallow = git(root, ["rev-parse", "--is-shallow-repository"]);
+    const tail = shallow.ok && shallow.out === "true" ? ". This clone is shallow" : "";
+    return `rerun: no merge base with ${base}, fetch full history (fetch-depth: 0)${tail}`;
+}
+/** REQ-VER-005 the task ID order: the change key, then the group and the number as integers. */
+export function cmpTaskId(a, b) {
+    const [ka, na = ""] = a.split("/");
+    const [kb, nb = ""] = b.split("/");
+    const k = cmpStr(ka, kb);
+    if (k !== 0)
+        return k;
+    const pa = na.split(".").map(Number);
+    const pb = nb.split(".").map(Number);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const d = (pa[i] ?? -1) - (pb[i] ?? -1);
+        if (d !== 0)
+            return d < 0 ? -1 : 1;
+    }
+    return 0;
+}
+/** REQ-VER-005 the task lines of one tasks.md text, with the key that the index would give them. */
+export function parseTasksFile(path, text, taskRe) {
+    const key = changeKey(changeOf(path));
+    const archived = path.includes("/archive/");
+    const out = [];
+    for (const line of text.split(/\r?\n/)) {
+        const m = taskRe.exec(line);
+        if (m)
+            out.push({ id: `${key}/${m[2]}`, done: m[1].toLowerCase() === "x", archived });
+    }
+    return out;
+}
+/** REQ-VER-005 one state per ID. An active copy wins over an archived copy, as findTask does. */
+export function mergeStates(states) {
+    const out = new Map();
+    for (const s of states) {
+        const had = out.get(s.id);
+        if (!had || (had.archived && !s.archived))
+            out.set(s.id, s);
+    }
+    return out;
+}
+/** REQ-VER-005 the state of every task in the tasks.md files at a commit. */
+export function tasksAt(root, sha, taskRe) {
+    const ls = git(root, ["ls-tree", "-z", "-r", "--name-only", sha, "--", "openspec/changes"]);
+    const all = [];
+    if (!ls.ok)
+        return new Map();
+    for (const p of ls.out.split("\0").filter((x) => x.endsWith("/tasks.md")).sort(cmpStr)) {
+        const show = spawnSync("git", ["show", `${sha}:${p}`], { cwd: root, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+        if (show.status === 0)
+            all.push(...parseTasksFile(p, show.stdout, taskRe));
+    }
+    return mergeStates(all);
+}
+/** REQ-VER-005 the index entries of tasks, one per ID. The active copy wins. */
+export function headStates(entries) {
+    const out = new Map();
+    for (const e of entries) {
+        if (e.kind !== "task")
+            continue;
+        const archived = e.file.includes("/archive/");
+        const had = out.get(e.id);
+        if (!had || (had.state.archived && !archived))
+            out.set(e.id, { state: { id: e.id, done: e.status === "done", archived }, entry: e });
+    }
+    return out;
+}
+/** REQ-VER-010 the commit that HEAD names, or "" when git fails. */
+export function headSha(root) {
+    const h = git(root, ["rev-parse", "HEAD"]);
+    return h.ok ? h.out : "";
+}
+/** REQ-VER-010 the line for a merge base equal to HEAD. */
+export const HEAD_BASE_LINE = "rerun: merge base is HEAD, nothing to compare. On push, pass --base <the commit before the push>";
+/** REQ-VER-013 the line for a base of forty zeros, the `before` of a push that creates a branch. */
+export const ZERO_BASE_LINE = "rerun: base is the zero commit (a new branch), nothing to compare";
+/** REQ-VER-013 a base that ends the rerun before the merge base: the zero commit passes, an unknown commit fails. */
+export function baseProblem(root, base) {
+    if (/^0{40}$/.test(base))
+        return { ok: true, line: ZERO_BASE_LINE };
+    const known = !base.startsWith("-") && git(root, ["rev-parse", "--verify", "--quiet", `${base}^{commit}`]).ok;
+    if (known)
+        return null;
+    return { ok: false, line: `rerun: base ${base} is not in this clone. Fetch it or use fetch-depth: 0` };
+}
+/**
+ * REQ-VER-005 the tasks that are done at HEAD and open or absent at the merge base, in ID order.
+ * `entries` is the live index. `taskRe` is the task regex of the scanner.
+ */
+export function closedTasks(root, base, entries, taskRe) {
+    const mb = git(root, ["merge-base", "HEAD", base]);
+    if (!mb.ok || !mb.out)
+        return { ok: false, line: noMergeBaseLine(root, base) };
+    const before = tasksAt(root, mb.out, taskRe);
+    const tasks = [];
+    for (const [id, { state, entry }] of headStates(entries)) {
+        if (state.done && !before.get(id)?.done)
+            tasks.push(entry);
+    }
+    tasks.sort((a, b) => cmpTaskId(a.id, b.id));
+    return { ok: true, mergeBase: mb.out, tasks };
+}
+/** REQ-VER-006 compare one closed task with its evidence, in the fixed order of 036/D4. */
+export function compare(verify, evidence, strict, weak) {
+    if (evidence !== null && evidence.kind === "manual")
+        return strict ? { act: "fail", kind: "manual" } : { act: "warn", why: "manual" };
+    if (evidence === null)
+        return { act: "fail", kind: "no-evidence" };
+    const cwd = evidence.cwd ?? ".";
+    if (verify.command !== evidence.command || (verify.cwd ?? ".") !== cwd) {
+        return { act: "fail", kind: "verify-drift", detail: `tasks.md has ${verify.command ?? "no command"}${verify.cwd ? ` (cwd ${verify.cwd})` : ""}, evidence has ${evidence.command ?? "no command"}${evidence.cwd ? ` (cwd ${evidence.cwd})` : ""}` };
+    }
+    if (evidence.command === null)
+        return { act: "fail", kind: "no-evidence" };
+    if (strict && weak(evidence.command))
+        return { act: "fail", kind: "weak-verify" };
+    return { act: "run", command: evidence.command, cwd, expected: evidence.exit };
+}
+/** REQ-VER-007 the key that makes two runs the same run. */
+export const runKey = (v) => `${v.cwd}\u0000${v.command}`;
+/** REQ-VER-007 one group per frozen command and cwd, in the ID order of the first task. */
+export function groupRuns(items) {
+    const sorted = [...items].sort((a, b) => cmpTaskId(a.id, b.id));
+    const groups = new Map();
+    for (const it of sorted) {
+        const key = runKey(it);
+        const g = groups.get(key);
+        if (g)
+            g.members.push(it);
+        else
+            groups.set(key, { key, command: it.command, cwd: it.cwd, members: [it] });
+    }
+    return [...groups.values()];
+}
+/** REQ-VER-006 ok when the exit code equals the evidence. A timeout or a different code is a mismatch. */
+export function judge(expected, o) {
+    return !o.timedOut && o.exit !== null && o.exit === expected ? "ok" : "mismatch";
+}
+const shq = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+/** REQ-VER-007 the line that runs the frozen command on a developer machine as the rerun runs it. */
+export function reproduceLine(command, cwd) {
+    return `reproduce: cd ${shq(cwd)} && env CI=1 SPECCTX_RERUN=1 sh -c ${shq(command)}`;
+}
+/** REQ-VER-007 the report of a mismatch. The output tail is the last 20 lines. */
+export function formatMismatch(m) {
+    const tailLines = m.outcome.output.replace(/\n$/, "") === "" ? [] : m.outcome.output.replace(/\n$/, "").split("\n").slice(-20);
+    const actual = m.outcome.timedOut ? `timed out after ${m.timeoutS}s` : `exit ${m.outcome.exit}`;
+    return [
+        `${m.id}: mismatch`,
+        `  at ${m.file}:${m.line}`,
+        `  evidence ${m.evidence}`,
+        `  expected exit ${m.expected}`,
+        `  actual ${actual}`,
+        "  output (last 20 lines):",
+        ...tailLines.map((l) => `    ${l}`),
+        `  ${reproduceLine(m.command, m.cwd)}`,
+    ].join("\n") + "\n";
+}

package/dist/graph/bundle.js

@@ -44,6 +44,11 @@ function rstrip(s) {
 export function provenance(e, reason) {
     return `-- ${e.id} | ${e.file}:${e.line} | ${e.status} | ${reason}\n`;
 }
+/** REQ-QRY-004 the canonical blocks of requirements, joined by one blank line, with no provenance line. */
+export function reqBlocks(root, reqs) {
+    const files = new Lines(root);
+    return reqs.map((e) => blockText(e, files)).join("\n");
+}
 export function bundle(root, entries, wanted, budget, depth, all = false) {
     const ids = canon(entries);
     const blocks = [];

package/dist/handoff/handoff.js

@@ -2,7 +2,8 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { UsageExit } from "../cli/errors.js";
-import { changeKey } from "../index/scan.js";
+import { changeKey, matchesChange } from "../index/scan.js";
+import { activeFolders } from "../loop/next.js";
 import { listEvidence } from "../tasks/evidence.js";
 import { activeChanges, nextTask } from "../tasks/tasks.js";
 import { cmpStr, splitLines } from "../util/pystr.js";
@@ -144,13 +145,32 @@ function refresh(root, entries) {
     save(root, h);
     return h;
 }
-/** REQ-HND-002 append an open question to questions.json and render the handoff again (022/D6). */
-export function ask(root, entries, text) {
-    const q = addQuestion(root, currentTask(root), text);
+/**
+ * REQ-HND-002 append an open question to questions.json and render the handoff again (022/D6).
+ * REQ-LOOP-005 with a change, the question carries the active change folder, so next blocks the change (029/D1).
+ */
+export function ask(root, entries, text, change, plan = false) {
+    let task = currentTask(root);
+    let stage;
+    if (change !== undefined) {
+        const folder = activeFolders(root).find((f) => matchesChange(f, change));
+        if (folder === undefined)
+            throw new UsageExit(`no active change ${change}`);
+        task = folder;
+        stage = stageOf(entries, folder, plan);
+    }
+    const q = addQuestion(root, task, text, stage);
     const h = refresh(root, entries);
     h.asked = q.n;
     return h;
 }
+/** REQ-LOOP-007 archive when the change has a task and every task is [x]. Else plan with the flag and design without it. The text plays no part (041/D2). */
+export function stageOf(entries, folder, plan = false) {
+    const tasks = entries.filter((e) => e.kind === "task" && e.change === folder && !e.file.includes("/archive/"));
+    if (tasks.length > 0 && tasks.every((t) => t.status === "done"))
+        return "archive";
+    return plan ? "plan" : "design";
+}
 /** REQ-HND-002 resolve question n in questions.json and render the handoff again (022/D6). */
 export function resolve(root, entries, n, answer) {
     resolveQuestion(root, n, answer);

package/dist/handoff/questions.js

@@ -33,13 +33,15 @@ export function oneLine(text) {
     return text.replace(/\s*\n\s*/g, " ").trim();
 }
 /** REQ-HND-002 append an open question with the next n. Returns the new question. */
-export function addQuestion(root, task, text) {
+export function addQuestion(root, task, text, stage) {
     const q = oneLine(text);
     if (!q)
         throw new UsageExit("handoff ask needs a question");
     const qs = readQuestions(root);
     const n = qs.reduce((m, x) => Math.max(m, x.n), 0) + 1;
     const item = { n, asked_at: isoNow(), task, text: q, status: "open" };
+    if (stage !== undefined)
+        item.stage = stage;
     qs.push(item);
     writeQuestions(root, qs);
     return item;

package/dist/ids/ids.js

@@ -39,6 +39,10 @@ export function newIds(root, cfg, entries, o) {
     const checkCap = (cap) => {
         if (!cap)
             throw new UsageExit(`id new ${kind} needs a capability code`);
+        // REQ-IDS-005 a code with a number is a scenario number typed in the code slot (038/D4)
+        const num = /^([A-Z]{2,6})-\d+$/.exec(cap);
+        if (num)
+            throw new UsageExit(`the capability code ${cap} holds a number. ${kind === "SCN" ? `Use id new SCN ${num[1]} --for REQ-${num[1]}-<NNN>.` : `Use id new ${kind} ${num[1]}.`}`);
         if (!/^[A-Z]{2,6}$/.test(cap))
             throw new UsageExit(`the capability code ${cap} must be 2 to 6 upper case letters`);
         // REQ-IDS-001 an empty caps list accepts any code. A non-empty list must hold the code.

package/dist/index/scan.js

@@ -16,7 +16,9 @@ const ADR_HDR = new RegExp(`^# (ADR-\\d{3})${S}+(.*)$`, "s");
 const REFS_RE = new RegExp(`^Refs:${S}*(.+)$`, "s");
 const TASK_REQ = new RegExp(`\\[(REQ-[A-Z]{2,6}-\\d{3}(?:${S}*,${S}*REQ-[A-Z]{2,6}-\\d{3})*)\\]`, "g");
 const CODE_TAG = new RegExp(`(?://|#|/\\*|\\*)${S}*(REQ-[A-Z]{2,6}-\\d{3})`);
-const COVER_TAG = new RegExp(`Covers:${S}*(REQ-[A-Z]{2,6}-\\d{3}(?:${S}*,${S}*REQ-[A-Z]{2,6}-\\d{3})*)`);
+// REQ-IDX-007 the rest of the line after Covers:, and each REQ ID in it with word boundaries (042/D4)
+const COVER_TAG = /Covers:(.*)$/s;
+const REQ_ID = /\bREQ-[A-Z]{2,6}-\d{3}\b/g;
 const SENTENCE_END = new RegExp(`(?<=[.!?])${S}`);
 const COMMA = new RegExp(`${S}*,${S}*`);
 const SKIP_DIRS = new Set(["node_modules", ".git"]);
@@ -348,7 +350,9 @@ export function scanSource(sc, rpath, entries, scnNamed) {
         if (isTest) {
             const m = COVER_TAG.exec(line);
             if (m) {
-                for (const rid of m[1].split(COMMA)) {
+                // a Covers line never counts as a code tag, with or without a REQ ID
+                const ids = [...new Set(m[1].match(REQ_ID) ?? [])];
+                for (const rid of ids) {
                     entries.push(entry({ id: `${rpath}:${i}`, kind: "test", file: rpath, line: i, title: pyStrip(line), change: "main", status: "active", refs: [rid] }));
                 }
                 continue;