spec-ctx 0.4.0 → 0.4.1

package/dist/loop/next.js

@@ -10,6 +10,8 @@ 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"];
@@ -94,6 +96,8 @@ 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);
+    // 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 };
@@ -118,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);
@@ -135,20 +141,26 @@ 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]));
     // 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" });
+    // 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" });
     }
-    const ticked = tasks.find((t) => t.status === "done" && !hasEvidence(root, t));
+    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) {
@@ -171,18 +183,18 @@ export function decideNext(root, cfg, data, want) {
         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}`, reason, state: "task_started", task: current.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) => `specctx task reopen ${s.id} "stale evidence: ${s.path}" && specctx task done ${s.id}`).join(" && "),
+            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,
@@ -192,11 +204,11 @@ export function decideNext(root, cfg, data, want) {
     // 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`;
@@ -204,10 +216,19 @@ 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) {

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-ctx",
-  "version": "0.4.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,15 +16,15 @@ 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 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.
+- `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. 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>"`.
+- `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