spec-ctx 0.2.0 → 0.4.0

package/dist/init/init.js

@@ -5,6 +5,7 @@ import { dirname, join } from "node:path";
 import { ASSETS } from "../assets.generated.js";
 import { UsageExit } from "../cli/errors.js";
 import { CONFIG_FILE, DEFAULT_OPENSPEC, INIT_TEXT } from "../config.js";
+import { loadConfigOrExit } from "../cli/config.js";
 export const SCHEMA = "spec-driven-ids";
 /** REQ-SCH-003 where the templates land in a project. Upstream reads no project override for the stock templates, so this is a reference path (025/D4). */
 export const TEMPLATES_DIR = `openspec/templates/${SCHEMA}`;
@@ -51,13 +52,34 @@ export function configText(root, openspec = DEFAULT_OPENSPEC) {
         text = text.replace(`\nopenspec = "${DEFAULT_OPENSPEC}"\n`, `\nopenspec = ${JSON.stringify(openspec)}\n`);
     return text;
 }
+/**
+ * REQ-SCH-006 wrap the ID after a requirement or scenario header prefix in square brackets (032/D1).
+ * An ID in brackets already stays. Task citations, Refs lines, and tags have no header prefix, so they stay bare.
+ */
+export function bracketForm(text) {
+    return text.replace(/(### Requirement: |#### Scenario: )((?:REQ|SCN)-[^\s\]"'`]+)/g, "$1[$2]");
+}
+/** REQ-SCH-006 the bytes of one template in the form that `brackets` names (032/D1). */
+export function templateBytes(rel, brackets) {
+    const b = asset(rel);
+    return brackets ? Buffer.from(bracketForm(b.toString("utf8"))) : b;
+}
+/** REQ-SCH-006 the config fragment in the form that `brackets` names (032/D1). */
+export function fragmentText(brackets) {
+    const t = asset(`schemas/${SCHEMA}/config-fragment.yaml`).toString("utf8");
+    return brackets ? bracketForm(t) : t;
+}
+/** REQ-SCH-006 the value of [ids] brackets, false when spec-ctx.toml is absent (032/D2). */
+export function bracketsOf(root) {
+    return existsSync(join(root, CONFIG_FILE)) ? loadConfigOrExit(root).ids.brackets : false;
+}
 /** Target path relative to the project root for every file that init installs, with its bytes. */
-export function plan(o, root, openspec = DEFAULT_OPENSPEC) {
+export function plan(o, root, openspec = DEFAULT_OPENSPEC, brackets = false) {
     const out = [[CONFIG_FILE, Buffer.from(configText(root, openspec))]];
     for (const rel of Object.keys(ASSETS).sort()) {
         // REQ-SCH-003 only the four templates land in the project. The fragment merges into config.yaml. No schema folder (025/D3)
         if (o.schema && rel.startsWith(TEMPLATES_SRC)) {
-            out.push([`${TEMPLATES_DIR}/${rel.slice(TEMPLATES_SRC.length)}`, asset(rel)]);
+            out.push([`${TEMPLATES_DIR}/${rel.slice(TEMPLATES_SRC.length)}`, templateBytes(rel, brackets)]);
         }
         if (o.skills && rel.startsWith("skills/")) {
             for (const d of SKILL_DIRS)
@@ -268,20 +290,26 @@ export const LEGACY_SCHEMA_NOTE = `note: schema ${SCHEMA} is no longer installed
  * REQ-SCH-003 add each top-level key of the fragment that the project config lacks.
  * A key that exists gets the fragment items it lacks (022/D4). The schema key stays as the project wrote it (025/D5).
  */
-export function mergeConfig(current, fragment) {
+export function mergeConfig(current, fragment, other) {
     let text = current ?? "";
     const added = [];
     const kept = [];
     const merged = [];
     const have = topKeys(text);
-    for (const [key, block] of topBlocks(fragment)) {
+    const blocks = topBlocks(fragment);
+    // REQ-SCH-007 an item that holds the other bracket form gets the current form in place (032/D4)
+    const swapped = other === undefined ? { text, size: 0, get: (_k) => undefined } : swapItems(text, blocks, topBlocks(other));
+    if (swapped.size)
+        text = swapped.text;
+    for (const [key, block] of blocks) {
         if (have.has(key)) {
             const lines = text.split("\n");
             const n = mergeItems(lines, key, block);
-            if (n) {
+            const r = swapped.get(key) ?? 0;
+            if (n)
                 text = lines.join("\n");
-                merged.push({ key, added: n });
-            }
+            if (n || r)
+                merged.push(r ? { key, added: n, replaced: r } : { key, added: n });
             else
                 kept.push(key);
             continue;
@@ -296,6 +324,46 @@ export function mergeConfig(current, fragment) {
     }
     return { text, added, kept, merged };
 }
+/**
+ * REQ-SCH-007 replace each project item whose value equals an item of the other form with the line of the current form (032/D4).
+ * The two fragments have the same lists in the same order, so items pair by position. The indent of the project line stays.
+ * Returns the new text and the count per top key.
+ */
+function swapItems(text, cur, other) {
+    const swap = new Map();
+    for (const [key, block] of cur) {
+        const a = fragmentLists(block);
+        const b = fragmentLists(other.get(key) ?? "");
+        a.forEach((list, i) => list.items.forEach((item, j) => {
+            const o = b[i]?.items[j];
+            if (o !== undefined && itemValue(o) !== itemValue(item))
+                swap.set(`${key}\0${itemValue(o)}`, item.trim());
+        }));
+    }
+    const counts = new Map();
+    if (!swap.size)
+        return { text, size: 0, get: (k) => counts.get(k) };
+    let top = null;
+    const lines = text.split("\n").map((line) => {
+        const m = TOP_KEY.exec(line);
+        if (m)
+            top = m[1];
+        if (!top || !/^[ \t]+- /.test(line))
+            return line;
+        const to = swap.get(`${top}\0${itemValue(line)}`);
+        if (to === undefined)
+            return line;
+        counts.set(top, (counts.get(top) ?? 0) + 1);
+        return " ".repeat(indentOf(line)) + to;
+    });
+    return { text: lines.join("\n"), size: counts.size, get: (k) => counts.get(k) };
+}
+/** REQ-SCH-007 the text of the `merged` count: added, replaced, or both (032/D4). */
+export function mergedCount(x) {
+    if (!x.replaced)
+        return `${x.added} added`;
+    return x.added ? `${x.added} added, ${x.replaced} replaced` : `${x.replaced} replaced`;
+}
 /** REQ-DIST-002 the four lines init owns in .gitignore (017/D2, 022/D5). current.json and gate-log.jsonl are per session. */
 export const GITIGNORE_LINES = [".ctx/index.json", "adopt-report.md", ".ctx/current.json", ".ctx/gate-log.jsonl"];
 const GITIGNORE = ".gitignore";
@@ -344,15 +412,21 @@ export function runInit(root, o) {
         if (d.note)
             res.notes.push(d.note);
     }
-    let files = plan(o, root, openspec);
+    // REQ-SCH-006 the form of the templates and the rules follows [ids] brackets (032/D2)
+    const brackets = bracketsOf(root);
+    const fragment = fragmentText(brackets);
+    const otherFragment = fragmentText(!brackets);
+    let files = plan(o, root, openspec, brackets);
     // REQ-CLI-007 every file present with the same bytes and no config key to add: nothing to do
     // an existing spec-ctx.toml counts as present, because the user owns it (014/D4)
     const same = files.every(([rel, data]) => existsSync(join(root, rel)) && (rel === CONFIG_FILE || readFileSync(join(root, rel)).equals(data)));
-    const ignoreDone = existsSync(join(root, GITIGNORE)) && GITIGNORE_LINES.every((l) => ignoreLines(readFileSync(join(root, GITIGNORE), "utf8")).has(l));
+    // REQ-DIST-013 a skills refresh in a project with spec-ctx.toml touches only the skill folders (038/D3)
+    const skillsOnly = o.skills && !o.schema && existsSync(join(root, CONFIG_FILE));
+    const ignoreDone = skillsOnly || existsSync(join(root, GITIGNORE)) && GITIGNORE_LINES.every((l) => ignoreLines(readFileSync(join(root, GITIGNORE), "utf8")).has(l));
     if (same && ignoreDone && !o.force) {
         const cfgPath = join(root, "openspec/config.yaml");
         const cur = existsSync(cfgPath) ? readFileSync(cfgPath, "utf8") : null;
-        const m = o.schema ? mergeConfig(cur, asset(`schemas/${SCHEMA}/config-fragment.yaml`).toString("utf8")) : null;
+        const m = o.schema ? mergeConfig(cur, fragment, otherFragment) : null;
         if (!m || (!m.added.length && !m.merged.length)) {
             res.nothing = true;
             if (o.skills && ignoresClaude(root))
@@ -370,11 +444,16 @@ export function runInit(root, o) {
         res.kept.push(CONFIG_FILE);
     }
     if (!o.force) {
-        const differs = (rel, data) => !readFileSync(join(root, rel)).equals(data);
+        // REQ-SCH-007 a template that holds the other bracket form is unchanged, so it gets the current form (032/D3)
+        const other = new Map(plan(o, root, openspec, !brackets).filter(([rel]) => rel.startsWith(`${TEMPLATES_DIR}/`)));
+        const differs = (rel, data) => {
+            const have = readFileSync(join(root, rel));
+            return !have.equals(data) && !(other.get(rel)?.equals(have) ?? false);
+        };
         res.changed = files.filter(([rel, data]) => existsSync(join(root, rel)) && differs(rel, data)).map(([rel]) => rel);
         for (const rel of res.changed)
             res.kept.push(`${rel} (other content)`);
-        files = files.filter(([rel]) => !existsSync(join(root, rel)));
+        files = files.filter(([rel, data]) => !existsSync(join(root, rel)) || (!readFileSync(join(root, rel)).equals(data) && !differs(rel, data)));
     }
     for (const [rel, data] of files) {
         const p = join(root, rel);
@@ -385,7 +464,7 @@ export function runInit(root, o) {
     if (o.schema) {
         const cfgPath = join(root, "openspec/config.yaml");
         const cur = existsSync(cfgPath) ? readFileSync(cfgPath, "utf8") : null;
-        const m = mergeConfig(cur, asset(`schemas/${SCHEMA}/config-fragment.yaml`).toString("utf8"));
+        const m = mergeConfig(cur, fragment, otherFragment);
         if (m.added.length || m.merged.length) {
             mkdirSync(dirname(cfgPath), { recursive: true });
             writeFileSync(cfgPath, m.text);
@@ -394,7 +473,7 @@ export function runInit(root, o) {
         }
         // REQ-SCH-003 one line per key that gained items (022/D4)
         for (const x of m.merged)
-            res.merged.push(`openspec/config.yaml ${x.key} (${x.added} added)`);
+            res.merged.push(`openspec/config.yaml ${x.key} (${mergedCount(x)})`);
         for (const k of m.kept)
             res.kept.push(`openspec/config.yaml ${k}`);
         // REQ-SCH-003 the schema line is the user's. A legacy value gets a note and stays (025/D5)
@@ -402,11 +481,13 @@ export function runInit(root, o) {
             res.notes.push(LEGACY_SCHEMA_NOTE);
     }
     // REQ-DIST-002 the four .gitignore lines (017/D2, 022/D5)
-    const added = writeGitignore(root);
-    if (added)
-        res.written.push(`${GITIGNORE} (${added} line${added === 1 ? "" : "s"})`);
-    else
-        res.kept.push(GITIGNORE);
+    if (!skillsOnly) {
+        const added = writeGitignore(root);
+        if (added)
+            res.written.push(`${GITIGNORE} (${added} line${added === 1 ? "" : "s"})`);
+        else
+            res.kept.push(GITIGNORE);
+    }
     // REQ-DIST-002 skills under an ignored .claude/ never reach git (017/D3)
     if (o.skills && ignoresClaude(root))
         res.notes.push(CLAUDE_NOTE);

package/dist/loop/fails.js

@@ -80,12 +80,22 @@ export function writeFail(root, task, verify, tail) {
     writeFileSync(join(root, target), dumps(file) + "\n");
     return { rel: target, file };
 }
-/** REQ-LOOP-002 the question text at the cap. Strict mode. */
+/** REQ-LOOP-002 the question text at the cap. It quotes the failing line (033/D2). Strict mode. */
 export function capQuestion(task, attempts, tail) {
-    const first = tail.split("\n")[0]?.trim() || "no output";
-    return `task ${task} failed Verify ${attempts} times. Last: ${first}. What should change?`;
+    return `task ${task} failed Verify ${attempts} times. Last: ${failLine(tail)}. What should change?`;
 }
 /** REQ-LOOP-002 the last line of a failed `task done` at the cap. Strict mode. */
 export function blockedLine(n) {
     return `blocked: question ${n} written. Run specctx handoff resolve ${n} "<answer>" to continue.`;
 }
+/**
+ * REQ-LOOP-006 the reason line of a Verify tail (029/D3): the last line that starts with `fail:`, `FAIL`, or `(fail)`
+ * after trimming (039/D1), else the last non-empty line, else `no output`. The match is case sensitive.
+ */
+export function failLine(tail) {
+    const lines = tail.split("\n").map((l) => l.trimEnd());
+    const hit = lines.filter((l) => /^\s*(?:fail:|FAIL|\(fail\))/.test(l)).at(-1);
+    if (hit !== undefined)
+        return hit.trim();
+    return lines.filter((l) => l.trim()).at(-1)?.trim() ?? "no output";
+}

package/dist/loop/next.js

@@ -3,20 +3,22 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { applyBaseline } from "../baseline/baseline.js";
 import { check } from "../check/check.js";
+import { staleOf } from "../check/evidence.js";
 import { readQuestions } from "../handoff/questions.js";
 import { changeKey, matchesChange } from "../index/scan.js";
 import { listEvidence } from "../tasks/evidence.js";
 import { hasEvidence, nextTask, tasksOf } from "../tasks/tasks.js";
 import { cmpStr, cmpTuple } from "../util/pystr.js";
-import { capQuestion, failsInWindow, openQuestionFor } from "./fails.js";
+import { capQuestion, failLine, failsInWindow, openQuestionFor } from "./fails.js";
 import { openspecCommand, openspecStatus } from "./openspec.js";
 /** The closed action list. A skill stops on any value outside it. */
 export const ACTIONS = ["plan", "cite", "start", "work", "fix", "repair", "gate", "archive", "ask", "stop"];
 /** The keys of the object, sorted. Every state prints all of them. */
-export const KEYS = ["action", "attempt", "change", "command", "human", "max_attempts", "reason", "state", "task"];
+export const KEYS = ["action", "attempt", "change", "command", "human", "max_attempts", "reason", "state", "task", "tasks"];
 /** The rules of check whose finding means a task or a header lacks its citation (024/D2 step 4). */
-const CITE_RULES = new Set(["missing-id", "task-without-req", "task-without-verify", "unknown-task-req"]);
-const TASK_RULES = new Set(["task-without-req", "task-without-verify", "unknown-task-req"]);
+// REQ-LOOP-004 a weak Verify command is a citation gap too (028/D7)
+const CITE_RULES = new Set(["missing-id", "task-without-req", "task-without-verify", "unknown-task-req", "weak-verify"]);
+const TASK_RULES = new Set(["task-without-req", "task-without-verify", "unknown-task-req", "weak-verify"]);
 /** The active change folders under openspec/changes/, sorted. The file system decides, so a change with no tasks.md counts. */
 export function activeFolders(root) {
     const dir = join(root, "openspec", "changes");
@@ -44,22 +46,25 @@ function questions(root) {
         return [];
     }
 }
-/** The last line of the gate log, or null. */
+/** REQ-LOOP-011 the last line of the gate log that is not a rerun line, or null. A line with steps exactly ["rerun"] never counts (041/D1). Only `ok` with `strict: true` passes (042/D2). */
 function lastGate(root) {
     const p = join(root, ".ctx/gate-log.jsonl");
     if (!existsSync(p))
         return null;
     const lines = readFileSync(p, "utf8").split("\n").filter((l) => l.trim());
-    const last = lines.at(-1);
-    if (!last)
-        return null;
-    try {
-        const o = JSON.parse(last);
-        return { at: typeof o.at === "string" ? o.at : "", ok: o.ok === true };
-    }
-    catch {
-        return null;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        try {
+            const o = JSON.parse(lines[i]);
+            const rerun = Array.isArray(o.steps) && o.steps.length === 1 && o.steps[0] === "rerun";
+            if (rerun)
+                continue;
+            return { at: typeof o.at === "string" ? o.at : "", ok: o.ok === true && o.strict === true };
+        }
+        catch {
+            return null;
+        }
     }
+    return null;
 }
 /** The `at` of the newest live evidence file of a change key, or "" with none. */
 function newestEvidenceAt(root, key) {
@@ -89,8 +94,13 @@ function readCurrent(root) {
 /** REQ-LOOP-001 the decision of 024/D2. A pure function of the files. It writes nothing. */
 export function decideNext(root, cfg, data, want) {
     const openspec = openspecCommand(cfg.gate.openspec);
-    const d = { action: "stop", attempt: 0, change: null, command: null, human: false, max_attempts: cfg.loop.max_attempts, reason: null, state: "unknown", task: null };
-    const done = (o) => ({ ...d, ...o });
+    const d = { action: "stop", attempt: 0, change: null, command: null, human: false, max_attempts: cfg.loop.max_attempts, reason: null, state: "unknown", task: null, tasks: [] };
+    const done = (o) => {
+        const r = { ...d, ...o };
+        if (!o.tasks)
+            r.tasks = r.task === null ? [] : [r.task];
+        return r;
+    };
     // step 0 and step 1: the change under consideration, or the plan stop with no change
     const folders = activeFolders(root);
     const folder = want === undefined ? folders[0] : folders.find((f) => matchesChange(f, want));
@@ -129,23 +139,55 @@ export function decideNext(root, cfg, data, want) {
     }
     // step 5: a hand tick without evidence gets the repair run
     const tasks = tasksOf(entries).filter(ofChange).sort((a, b) => cmpTuple([a.file, a.line], [b.file, b.line]));
+    // REQ-LOOP-009 step 4b: the plan stop. It needs no [x] task, no current task, and no question with stage plan, open or resolved. Only --plan sets that stage (034/D1, 041/D2).
+    const cur0 = readCurrent(root);
+    const started = tasks.some((t) => t.status === "done") || (cur0?.task !== undefined && cur0.task.split("/")[0] === key);
+    if (!started && !qs.some((q) => q.stage === "plan" && q.task === folder)) {
+        const text = `plan ready for ${folder}. Approve to start the tasks?`;
+        return done({ action: "ask", command: `specctx handoff ask --change ${folder} --plan "${text}"`, human: true, reason: text, state: "plan_stop" });
+    }
     const ticked = tasks.find((t) => t.status === "done" && !hasEvidence(root, t));
     if (ticked)
         return done({ action: "repair", command: `specctx task done ${ticked.id}`, state: "done_without_evidence", task: ticked.id });
+    // REQ-LOOP-008 the done tasks whose evidence went stale, earliest first (031/D4, 031/D5)
+    const stale = [];
+    for (const t of tasks) {
+        if (t.status !== "done")
+            continue;
+        const path = staleOf(root, t.id);
+        if (path !== null)
+            stale.push({ id: t.id, path });
+    }
+    // REQ-LOOP-010 a current task keeps its action. The reason names the stale tasks that wait (034/D4).
+    const waiting = stale.length ? `stale waiting: ${stale.map((x) => x.id).join(", ")}` : null;
+    const withWaiting = (r) => (waiting === null ? r : r === null ? waiting : `${r}. ${waiting}`);
     // step 6: the current task of this change
     const cur = readCurrent(root);
     const current = cur?.task && cur.task.split("/")[0] === key ? tasks.find((t) => t.id === cur.task && t.status === "open") : undefined;
     if (current) {
         const fails = failsInWindow(root, current.id, qs);
         const last = fails.at(-1);
-        const reason = last ? `Verify failed (exit ${last.file.verify.exit ?? "timeout"}): ${last.file.stderr_tail.split("\n")[0]?.trim() || "no output"}` : null;
+        // REQ-LOOP-006 the reason names the last fail line of the tail (029/D3)
+        const reason = withWaiting(last ? `Verify failed (exit ${last.file.verify.exit ?? "timeout"}): ${failLine(last.file.stderr_tail)}` : null);
         if (fails.length >= cfg.loop.max_attempts && !openQuestionFor(root, current.id, qs)) {
             const q = capQuestion(current.id, fails.length, last?.file.stderr_tail ?? "");
             return done({ action: "ask", attempt: fails.length, command: `specctx handoff ask "${q}"`, human: true, reason, state: "attempts_exhausted", task: current.id });
         }
         if (fails.length)
             return done({ action: "fix", attempt: fails.length, command: `specctx task done ${current.id}`, reason, state: "task_failed", task: current.id });
-        return done({ action: "work", command: `specctx task done ${current.id}`, state: "task_started", task: current.id });
+        return done({ action: "work", command: `specctx task done ${current.id}`, reason, state: "task_started", task: current.id });
+    }
+    // REQ-LOOP-008 step 6b: the stale tasks repair after the current task (031/D4, 031/D5)
+    if (stale.length) {
+        // REQ-LOOP-008 one turn repairs every stale task (033/D1)
+        return done({
+            action: "repair",
+            command: stale.map((s) => `specctx task reopen ${s.id} "stale evidence: ${s.path}" && specctx task done ${s.id}`).join(" && "),
+            reason: stale.map((s) => `stale-evidence ${s.id} ${s.path}`).join(", "),
+            state: "evidence_stale",
+            task: stale[0].id,
+            tasks: stale.map((s) => s.id),
+        });
     }
     // step 7: the next open task
     const open = nextTask(root, entries, folder);
@@ -157,11 +199,20 @@ export function decideNext(root, cfg, data, want) {
         return done({ action: "gate", command: "specctx gate --strict", state: "gate_due" });
     }
     // step 9: archive, with the human stop from [loop] archive
-    return done({ action: "archive", command: `${openspec} archive ${folder} -y`, human: cfg.loop.archive === "ask", state: "gate_passed" });
+    const archive = `${openspec} archive ${folder} -y`;
+    if (cfg.loop.archive !== "ask")
+        return done({ action: "archive", command: archive, human: false, state: "gate_passed" });
+    // REQ-LOOP-007 a resolved archive question after the newest evidence is the approval. The stage field decides, not the text (031/D2).
+    const newest = newestEvidenceAt(root, key);
+    const approved = qs.filter((q) => q.status === "resolved" && q.task === folder && q.stage === "archive" && typeof q.resolved_at === "string" && cmpStr(q.resolved_at, newest) > 0).at(-1);
+    if (approved)
+        return done({ action: "archive", command: archive, human: false, reason: `archive approved in question ${approved.n}`, state: "gate_passed" });
+    return done({ action: "archive", command: `specctx handoff ask --change ${folder} "archive ${folder}?"`, human: true, state: "gate_passed" });
 }
 /** REQ-LOOP-001 REQ-CLI-007 the human form: action first, one line per key, next last (024/D1). Strict mode. */
 export function renderNext(d) {
-    const show = (v) => (v === null ? "none" : String(v));
+    // REQ-LOOP-012 an empty list prints none, a list joins with a comma and a space
+    const show = (v) => (v === null ? "none" : Array.isArray(v) ? (v.length ? v.join(", ") : "none") : String(v));
     const lines = [`action: ${d.action}`];
     for (const k of KEYS) {
         if (k === "action" || k === "command")

package/dist/stats/stats.js

@@ -5,7 +5,10 @@ import { readBaseline } from "../baseline/baseline.js";
 import { changeKey, matchesChange } from "../index/scan.js";
 import { isFailFile } from "../tasks/evidence.js";
 import { cmpStr, cpLen } from "../util/pystr.js";
-export const DEBT_RULES = ["uncovered", "scenario-untested", "done-without-evidence", "manual-evidence"];
+// REQ-STAT-004 the two Verify rules count as debt too, the same rules the baseline can hold (029/D5)
+export const DEBT_RULES = ["uncovered", "scenario-untested", "done-without-evidence", "manual-evidence", "task-without-verify", "weak-verify"];
+/** The debt rules whose ID is a task. A change row counts them. */
+const TASK_DEBT_RULES = ["done-without-evidence", "manual-evidence", "task-without-verify", "weak-verify"];
 const NA = (n = 0) => ({ value: null, n, text: "n/a" });
 function readEvidence(root) {
     const dir = join(root, ".ctx/evidence");
@@ -120,11 +123,11 @@ export function computeStats(root, entries, strictFindings, warnings, only) {
     ];
     const fresh = [...new Set(current)].filter((k) => !base.has(k));
     const debtAll = { value: base.size + fresh.length, n: base.size + fresh.length, text: `${base.size + fresh.length} (${base.size} baselined + ${fresh.length} new)` };
-    // a change row counts the task scoped debt: tasks without evidence and tasks with manual evidence
+    // a change row counts the task scoped debt: no evidence, manual evidence, no Verify, and a weak Verify (029/D5)
     const taskDebt = (change) => {
         const keys = [...base, ...fresh].filter((k) => {
             const [rule, id] = k.split(" ");
-            return (rule === "done-without-evidence" || rule === "manual-evidence") && nameOf(id ?? "") === change;
+            return TASK_DEBT_RULES.includes(rule ?? "") && nameOf(id ?? "") === change;
         });
         return { value: keys.length, n: keys.length, text: String(keys.length) };
     };

package/dist/util/time.js

@@ -6,6 +6,7 @@ export function now() {
 export function isoNow() {
     return now().toISOString();
 }
+/** REQ-STAT-005 the UTC date, so CI and a local run name a metrics file alike (033/D5). */
 export function today() {
     return isoNow().slice(0, 10);
 }

package/dist/verify/parse.js

@@ -56,3 +56,9 @@ export function parseVerify(taskLine) {
     }
     return { kind: "command", command: spans.join(" && ") };
 }
+// REQ-CHK-005 a Verify command that always exits 0: `true`, `:`, `exit 0`, or one `echo` with no `;`, `&`, `|` (028/D1)
+const WEAK_VERIFY = /^(?:true|:|exit\s+0|echo(?:\s[^;&|\n]*)?)$/;
+/** REQ-CHK-005 true when the command, trimmed, is one of the weak forms. */
+export function isWeakVerify(command) {
+    return WEAK_VERIFY.test(command.trim());
+}

package/dist/verify/run.js

@@ -5,10 +5,11 @@ export function tail(text, n = TAIL_LINES) {
     const lines = text.replace(/\n$/, "").split("\n");
     return text === "" ? "" : lines.slice(-n).join("\n");
 }
-export function runVerify(command, cwd, timeoutS) {
+/** REQ-VER-007 `env` replaces the environment of the child. The rerun passes the current env plus CI and SPECCTX_RERUN. */
+export function runVerify(command, cwd, timeoutS, env) {
     return new Promise((resolve, reject) => {
         // a new process group, so the timeout stops the children of sh too
-        const child = spawn("sh", ["-c", command], { cwd, detached: true, stdio: ["ignore", "pipe", "pipe"] });
+        const child = spawn("sh", ["-c", command], { cwd, detached: true, ...(env ? { env } : {}), stdio: ["ignore", "pipe", "pipe"] });
         const out = [];
         const err = [];
         let output = "";

package/dist/version.js

@@ -1,2 +1,2 @@
 // REQ-CLI-001 version string. tests/cli/version.test.ts keeps it equal to package.json.
-export const VERSION = "0.2.0";
+export const VERSION = "0.4.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-ctx",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Deterministic context engine and task workflow for OpenSpec projects.",
   "type": "module",
   "license": "MIT",

package/skills/specctx-run/SKILL.md

@@ -5,7 +5,7 @@ description: Run the spec-ctx loop in an OpenSpec project. Use on "run", "contin
 
 # specctx-run
 
-Run `specctx` as `npx spec-ctx` when it is not installed. `openspec` is the command in `[gate] openspec` of `spec-ctx.toml`.
+Run `specctx` as `npx spec-ctx` when it is not installed. `openspec` is the command in `[gate] openspec` of `spec-ctx.toml`. When that key is absent, `openspec` is `npx -y @fission-ai/openspec@latest`.
 
 ## The loop
 
@@ -16,22 +16,27 @@ Run `specctx` as `npx spec-ctx` when it is not installed. `openspec` is the comm
 
 ## Actions
 
-- `plan`: follow the upstream `openspec-propose` skill for the change in `command`. Take every ID from `specctx id new REQ <CAP>` and `specctx id new SCN <CAP> --for <REQ>`. Give every task a `[REQ-...]` citation and a `Verify:` code span. Then run `specctx check --strict` and `openspec validate <c> --strict`. Fix every finding. Stop and show the plan to the user. This is the plan stop.
+- `plan`: take the change name from the request of the user in kebab case. That name is `<c>`. Follow the upstream `openspec-propose` skill for `<c>`. Read existing requirements with `specctx bundle <id>` or `specctx query`, never `openspec show`. Take every ID from `specctx id new REQ <CAP>` and `specctx id new SCN <CAP> --for <REQ>`. When the change needs several IDs of one kind, run `specctx id new --count <n>` once. Give every task a `[REQ-...]` citation and a `Verify:` code span. Then run `specctx check --strict` and `specctx gate --strict`. The gate runs the OpenSpec validate and the spec-length check. Fix every finding. Then run `specctx next --json` and run the command it prints. This is the plan stop. `next` returns `ask` with `human: true` until the user resolves the question.
 - `cite`: run `specctx query --change <c> --kind req`. Add the `[REQ-...]` citation and a `Verify:` code span to the task line named in `task`. Run `specctx check`. Continue.
 - `start`: run `specctx task start <t>`. Read the bundle it prints. Continue.
 - `work`: implement the task. Tag code with `// REQ-...`. Tag tests with `// Covers: REQ-...`. Then run `specctx task done <t>`.
 - `fix`: read `reason`. It holds the tail of the failed Verify output. Fix the cause. Run `specctx task done <t>` again.
-- `repair`: run `specctx task done <t>`. It runs Verify for a ticked task that has no evidence.
-- `gate`: run `specctx gate --strict`. Fix every finding. Run it again until it exits 0.
-- `archive`: when `human` is true, stop and ask the user in one line whether to archive `<c>`. When `human` is false, follow the upstream `openspec-archive-change` skill. Then run `openspec validate --all --strict`, `specctx check --strict`, and `specctx handoff write`.
+- `repair`: run the command in the `command` field. It runs Verify again for a ticked task whose evidence is absent or stale.
+- `gate`: run `specctx gate --strict`. Fix every finding. For a `stale-evidence` finding, go back to step 1. `next` returns `repair` and its command repairs every stale task. Run the gate again until it exits 0.
+- `archive`: when `human` is true, run `specctx handoff ask --change <c> "archive <c>?"` and stop. This is the archive stop. `next` returns `ask` until the user resolves the question. When `human` is false, the user approved or `[loop] archive` is `auto`. Then run each step under `operations.archive.guidance` in `openspec/config.yaml`. Then run the command in the `command` field. Then run `openspec validate --all --strict`, `specctx check --strict`, and `specctx handoff write`.
 - `ask`: print `reason`. It is the open question. Stop. The user answers with `specctx handoff resolve <n> "<answer>"`.
 - `stop`: print `reason`. Stop.
 
 ## Rules
 
+- This skill overrides two steps of the upstream `openspec-propose` skill. It reads specs with `specctx bundle` or `specctx query`, not `openspec show`. It never runs the closing `/opsx:apply`.
 - Never tick a checkbox by hand. `specctx task done` is the only way a task closes.
 - Never use `--manual` on a task with a Verify command.
 - Never call `/opsx:apply`. This skill replaces it.
+- To write a MODIFIED block, run `specctx bundle <REQ> --block`. It prints the block as it sits in the spec file. A MODIFIED block keeps every scenario title unchanged.
+- `gate` counts the Refs line in the 500 characters of a requirement.
+- The CHANGELOG entry goes under `## Unreleased`, never under a released version.
+- After an edit under `skills/`, run `bun run build && node dist/cli.js init --skills --force` to refresh the copies.
 - Never read `openspec/specs/` or `openspec/changes/*/specs/` directly. Use the bundle from `task start` or `specctx bundle <id>`.
 - Stop on any `action` not in the list above. Print the object and ask the user.
 - Keep no state in your context. A new session starts the same loop again with step 1.