spec-ctx 0.3.0 → 0.4.1

package/dist/loop/fails.js

@@ -4,6 +4,7 @@ import { dirname, join } from "node:path";
 import { readQuestions } from "../handoff/questions.js";
 import { isFailFile } from "../tasks/evidence.js";
 import { evidenceRel } from "../tasks/tasks.js";
+import { runCommand } from "../runcmd.js";
 import { dumps } from "../util/json.js";
 import { cmpStr } from "../util/pystr.js";
 import { isoNow } from "../util/time.js";
@@ -66,6 +67,13 @@ export function failsInWindow(root, task, questions) {
 export function openQuestionFor(root, task, questions) {
     return (questions ?? safeQuestions(root)).find((q) => q.task === task && q.status === "open");
 }
+/**
+ * REQ-LOOP-014 an open attempt-cap question of the task: stage cap only. A question with no stage is a person's (044/D3).
+ * The text plays no part (044/D3).
+ */
+export function isCapQuestion(q, task) {
+    return q.status === "open" && q.task === task && q.stage === "cap";
+}
 /** Write the next fail file of a task. The attempt counts the window, the file number counts every fail file. */
 export function writeFail(root, task, verify, tail) {
     const attempt = failsInWindow(root, task).length + 1;
@@ -80,22 +88,21 @@ 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.`;
+export function blockedLine(n, run = "specctx") {
+    return `blocked: question ${n} written. Run ${runCommand(run, `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:` or `FAIL` after
- * leading spaces, else the last non-empty line, else `no output`. The match is case sensitive.
+ * 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)/.test(l)).at(-1);
+    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

@@ -10,11 +10,13 @@ import { listEvidence } from "../tasks/evidence.js";
 import { hasEvidence, nextTask, tasksOf } from "../tasks/tasks.js";
 import { cmpStr, cmpTuple } from "../util/pystr.js";
 import { capQuestion, failLine, failsInWindow, openQuestionFor } from "./fails.js";
+import { runCommand } from "../runcmd.js";
+import { parseVerify } from "../verify/parse.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). */
 // 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"]);
@@ -46,22 +48,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) {
@@ -91,8 +96,15 @@ 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 });
+    // REQ-CLI-010 every printed command goes through the run prefix (043/D1)
+    const rc = (args) => runCommand(cfg.cli.run, args);
+    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));
@@ -110,7 +122,9 @@ export function decideNext(root, cfg, data, want) {
     if (blocking) {
         const task = blocking.task.includes("/") ? blocking.task : null;
         const attempt = task ? failsInWindow(root, task, qs).length : 0;
-        return done({ action: "ask", attempt, command: `specctx handoff resolve ${blocking.n} "<answer>"`, human: true, reason: blocking.text, state: "question_open", task });
+        // REQ-LOOP-015 a plan or archive question shows the verdict form (048/D6)
+        const form = blocking.stage === "plan" || blocking.stage === "archive" ? "<--approve|--reject> " : "";
+        return done({ action: "ask", attempt, command: rc(`handoff resolve ${blocking.n} ${form}"<answer>"`), human: true, reason: blocking.text, state: "question_open", task });
     }
     // step 3: planning state from OpenSpec
     const st = openspecStatus(root, openspec, folder);
@@ -127,13 +141,38 @@ export function decideNext(root, cfg, data, want) {
     if (found.length) {
         const first = found[0];
         const task = found.find((f) => TASK_RULES.has(f.rule))?.id ?? null;
-        return done({ action: "cite", command: `specctx query --change ${folder} --kind req`, reason: `${first.rule} ${first.id} at ${first.file}:${first.line}`, state: "citation_missing", task });
+        return done({ action: "cite", command: rc(`query --change ${folder} --kind req`), reason: `${first.rule} ${first.id} at ${first.file}:${first.line}`, state: "citation_missing", task });
     }
     // 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]));
-    const ticked = tasks.find((t) => t.status === "done" && !hasEvidence(root, t));
+    // 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);
+    // REQ-LOOP-015 REQ-LOOP-016 the newest plan question decides, the one with the highest n. A rejection holds the stop before the started guard. Only an approval ends it. No verdict is no approval (048/D4).
+    const newestPlan = newestOf(qs.filter((q) => q.stage === "plan" && q.task === folder && q.status === "resolved"));
+    const planText = `plan ready for ${folder}. Approve to start the tasks?`;
+    if (newestPlan?.verdict === "rejected") {
+        return done({ action: "ask", command: rc(`handoff ask --change ${folder} --plan "${planText}"`), human: true, reason: `plan rejected in question ${newestPlan.n}: ${newestPlan.answer ?? ""}`, state: "plan_stop" });
+    }
+    if (!started && newestPlan?.verdict !== "approved") {
+        return done({ action: "ask", command: rc(`handoff ask --change ${folder} --plan "${planText}"`), human: true, reason: planText, state: "plan_stop" });
+    }
+    // REQ-LOOP-013 repair runs Verify, so a ticked task with no Verify command never gets it (044/D2)
+    const ticked = tasks.find((t) => t.status === "done" && parseVerify(t.title).command !== null && !hasEvidence(root, t));
     if (ticked)
-        return done({ action: "repair", command: `specctx task done ${ticked.id}`, state: "done_without_evidence", task: ticked.id });
+        return done({ action: "repair", command: rc(`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;
@@ -141,32 +180,35 @@ export function decideNext(root, cfg, data, want) {
         const fails = failsInWindow(root, current.id, qs);
         const last = fails.at(-1);
         // REQ-LOOP-006 the reason names the last fail line of the tail (029/D3)
-        const reason = last ? `Verify failed (exit ${last.file.verify.exit ?? "timeout"}): ${failLine(last.file.stderr_tail)}` : null;
+        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 });
+            return done({ action: "ask", attempt: fails.length, command: rc(`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 });
-    }
-    // REQ-LOOP-008 step 6b: the earliest done task whose evidence went stale gets the repair run, after the current task (031/D4, 031/D5)
-    for (const t of tasks) {
-        if (t.status !== "done")
-            continue;
-        const path = staleOf(root, t.id);
-        if (path === null)
-            continue;
-        return done({ action: "repair", command: `specctx task reopen ${t.id} "stale evidence: ${path}" && specctx task done ${t.id}`, reason: `stale-evidence ${t.id} ${path}`, state: "evidence_stale", task: t.id });
+            return done({ action: "fix", attempt: fails.length, command: rc(`task done ${current.id}`), reason, state: "task_failed", task: current.id });
+        return done({ action: "work", command: rc(`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) => `${rc(`task reopen ${s.id} "stale evidence: ${s.path}"`)} && ${rc(`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);
     if (open)
-        return done({ action: "start", command: `specctx task start ${open.id}`, state: "task_open", task: open.id });
+        return done({ action: "start", command: rc(`task start ${open.id}`), state: "task_open", task: open.id });
     // step 8: the gate must pass after the newest evidence
     const gate = lastGate(root);
     if (!gate || !gate.ok || cmpStr(gate.at, newestEvidenceAt(root, key)) < 0) {
-        return done({ action: "gate", command: "specctx gate --strict", state: "gate_due" });
+        return done({ action: "gate", command: rc("gate --strict"), state: "gate_due" });
     }
     // step 9: archive, with the human stop from [loop] archive
     const archive = `${openspec} archive ${folder} -y`;
@@ -174,14 +216,24 @@ export function decideNext(root, cfg, data, want) {
         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-015 REQ-LOOP-016 the newest archive question after the newest evidence decides. Only an approval counts (048/D5).
+    const decided = newestOf(qs.filter((q) => q.status === "resolved" && q.task === folder && q.stage === "archive" && typeof q.resolved_at === "string" && cmpStr(q.resolved_at, newest) > 0));
+    if (decided?.verdict === "approved")
+        return done({ action: "archive", command: archive, human: false, reason: `archive approved in question ${decided.n}`, state: "gate_passed" });
+    const askArchive = rc(`handoff ask --change ${folder} "archive ${folder}?"`);
+    if (decided?.verdict === "rejected") {
+        return done({ action: "archive", command: askArchive, human: true, reason: `archive rejected in question ${decided.n}: ${decided.answer ?? ""}`, state: "gate_passed" });
+    }
+    return done({ action: "archive", command: askArchive, human: true, state: "gate_passed" });
+}
+/** The question with the highest n, or undefined (048/D4). */
+function newestOf(qs) {
+    return qs.reduce((a, q) => (a === undefined || q.n > a.n ? q : a), undefined);
 }
 /** 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/runcmd.js

@@ -0,0 +1,5 @@
+// REQ-CLI-010 the one function that builds a command for a person or agent to run (043/D1).
+/** The prefix, a space, and the arguments. Every printed command goes through here. */
+export function runCommand(run, args) {
+    return `${run} ${args}`;
+}

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/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.3.0";
+export const VERSION = "0.4.1";

package/package.json

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

package/skills/specctx-run/SKILL.md

@@ -16,22 +16,27 @@ Run `specctx` as `npx spec-ctx` when it is not installed. `openspec` is the comm
 
 ## Actions
 
-- `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 handoff ask --change <c> "plan ready for <c>. Approve to start the tasks?"`. This is the plan stop. `next` returns `ask` until the user resolves the question.
+- `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 human approves the question. You never resolve a plan question yourself.
 - `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 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. Run it 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>"`.
+- `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 human approves the question. You never resolve an archive question yourself. After a rejection, `next` returns `archive` with `human: true` again. 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. You never resolve a plan or archive question yourself. The human does, with `specctx handoff resolve <n> --approve "<answer>"` or `--reject "<answer>"`. A rejection keeps the stop. Any other question takes `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.