spec-ctx 0.4.0 → 0.5.0

package/dist/loop/fails.js

@@ -1,12 +1,14 @@
-// REQ-LOOP-002 fail files under .ctx/evidence/<change>/<task>.fail-<n>.json and the attempt window (024/D4, 024/D5).
+// REQ-LOOP-002 REQ-LOOP-017 REQ-LOOP-018 fail files under .ctx/evidence/<change>/<task>.fail-<n>.json and the attempt window (024/D4, 024/D5).
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 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";
+const CURRENT = ".ctx/current.json";
 /** Every fail file of a task, parsed, in `at` order. A damaged file is skipped. */
 export function readFails(root, task) {
     const rel = evidenceRel({ id: task });
@@ -30,19 +32,22 @@ export function readFails(root, task) {
     return out.sort((a, b) => cmpStr(a.file.at, b.file.at) || cmpStr(a.rel, b.rel));
 }
 /**
- * The start of the attempt window of a task: `current.json.started_at` when the file names the task, else the
- * start of time. A resolved question for the task moves the start to its `resolved_at`, so a resolve resets the count.
+ * REQ-LOOP-018 the start of the attempt window of a task: `current.json.started_at` when the file names the task, else
+ * null, and no fail file counts (056/D4). A resolved question for the task moves the start to its `resolved_at`, so a
+ * resolve resets the count. `fallback` gives the start of time instead of null, for a current.json that could not be written.
  */
-export function windowStart(root, task, questions) {
-    let start = "";
+export function windowStart(root, task, questions, fallback = false) {
+    let start = fallback ? "" : null;
     try {
-        const cur = JSON.parse(readFileSync(join(root, ".ctx/current.json"), "utf8"));
+        const cur = JSON.parse(readFileSync(join(root, CURRENT), "utf8"));
         if (cur.task === task && typeof cur.started_at === "string")
             start = cur.started_at;
     }
     catch {
         // no current task
     }
+    if (start === null)
+        return null;
     for (const q of questions ?? safeQuestions(root)) {
         if (q.task === task && q.status === "resolved" && typeof q.resolved_at === "string" && cmpStr(q.resolved_at, start) > 0)
             start = q.resolved_at;
@@ -57,18 +62,71 @@ function safeQuestions(root) {
         return [];
     }
 }
-/** The fail files of a task inside its window, in `at` order. */
-export function failsInWindow(root, task, questions) {
-    const start = windowStart(root, task, questions);
+/** REQ-LOOP-018 the fail files of a task inside its window, in `at` order. None without a window. */
+export function failsInWindow(root, task, questions, fallback = false) {
+    const start = windowStart(root, task, questions, fallback);
+    if (start === null)
+        return [];
     return readFails(root, task).filter((f) => cmpStr(f.file.at, start) >= 0);
 }
 /** The open question that names the task, if any. */
 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";
+}
+/**
+ * REQ-LOOP-018 a failed run with no current.json for the task opens its window first (056/D4). The file has only
+ * `started_at` and `task`: no `verify`, so a later Verify edit is not refused, and no `bundle_chars`, so stats keeps
+ * cycle time for runs that began with task start. Returns false when the write fails.
+ */
+export function openWindow(root, task) {
+    try {
+        const cur = JSON.parse(readFileSync(join(root, CURRENT), "utf8"));
+        if (cur.task === task && typeof cur.started_at === "string")
+            return true;
+    }
+    catch {
+        // absent or damaged: write a new one
+    }
+    try {
+        mkdirSync(join(root, ".ctx"), { recursive: true });
+        writeFileSync(join(root, CURRENT), dumps({ started_at: isoNow(), task }) + "\n");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** REQ-LOOP-017 the line that keeps fail files out of git, in `.ctx/evidence/.gitignore` (056/D1). */
+export const FAIL_IGNORE = "*.fail-*.json";
+/**
+ * REQ-LOOP-017 make sure `.ctx/evidence/.gitignore` has the fail file line. Create the file or append the line. Other
+ * lines keep their bytes and order. A write error changes nothing (056/D1).
+ */
+export function ensureFailIgnore(root) {
+    const p = join(root, ".ctx/evidence/.gitignore");
+    try {
+        const cur = existsSync(p) ? readFileSync(p, "utf8") : "";
+        if (cur.split(/\r?\n/).some((l) => l.trim() === FAIL_IGNORE))
+            return;
+        mkdirSync(dirname(p), { recursive: true });
+        writeFileSync(p, (cur === "" || cur.endsWith("\n") ? cur : cur + "\n") + FAIL_IGNORE + "\n");
+    }
+    catch {
+        // a read-only tree keeps its fail files tracked
+    }
+}
 /** 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;
+    // REQ-LOOP-018 when current.json cannot be written, count as before (056/D4)
+    const opened = openWindow(root, task);
+    const attempt = failsInWindow(root, task, undefined, !opened).length + 1;
     const rel = evidenceRel({ id: task });
     const base = rel.slice(0, -".json".length);
     let n = 1;
@@ -78,6 +136,7 @@ export function writeFail(root, task, verify, tail) {
     const file = { at: isoNow(), attempt, stderr_tail: tail, task, verify };
     mkdirSync(dirname(join(root, target)), { recursive: true });
     writeFileSync(join(root, target), dumps(file) + "\n");
+    ensureFailIgnore(root);
     return { rel: target, file };
 }
 /** REQ-LOOP-002 the question text at the cap. It quotes the failing line (033/D2). Strict mode. */
@@ -85,8 +144,8 @@ export function capQuestion(task, attempts, tail) {
     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:`, `FAIL`, or `(fail)`

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/main.js

@@ -1,6 +1,9 @@
 // REQ-CLI-001 REQ-CLI-002 REQ-CLI-003 command dispatch. Each command loads its modules inside its action.
+import { resolve } from "node:path";
 import { COMMANDS, GROUPS, parseArgs, UsageError } from "./cli/args.js";
 import { VERSION } from "./version.js";
+import { errInfo, note } from "./journal/note.js";
+import { runCommand } from "./runcmd.js";
 export async function main(argv, io) {
     // REQ-LINT-001 the linters keep the argument rules of the Python scripts, so they skip this parser
     // REQ-CLI-006 `specctx help <cmd>` prints the page of one command
@@ -29,6 +32,7 @@ export async function main(argv, io) {
     }
     catch (e) {
         if (e instanceof UsageError) {
+            note(io, { cmd: "?" });
             io.err(`specctx: ${e.message}\n`);
             return 2;
         }
@@ -49,18 +53,26 @@ export async function main(argv, io) {
         return 0;
     }
     if (GROUPS.includes(parsed.command)) {
+        note(io, { cmd: "?" });
         const subs = COMMANDS.filter((c) => c.startsWith(parsed.command + " ")).map((c) => c.split(" ")[1]);
         io.err(`specctx: ${parsed.command} needs a subcommand: ${subs.join(", ")}\n`);
         return 2;
     }
     if (!COMMANDS.includes(parsed.command)) {
+        note(io, { cmd: "?" });
         const { commandList } = await import("./cli/help.js");
         io.err(`specctx: unknown command: ${parsed.command}\n${commandList()}`);
         return 2;
     }
+    note(io, { cmd: parsed.command });
     try {
         const { run } = await import("./cli/commands.js");
-        return await run(parsed, io);
+        const code = await run(parsed, io);
+        // REQ-JRN-002 init has no OpenSpec root check. Its root is the one it wrote to.
+        if (code === 0 && parsed.command === "init") {
+            note(io, { root: resolve(io.cwd, parsed.flags.root ?? "."), signal: "init-ok" });
+        }
+        return code;
     }
     catch (e) {
         const { UsageExit } = await import("./cli/errors.js");
@@ -69,6 +81,9 @@ export async function main(argv, io) {
             return 2;
         }
         io.err(`specctx: internal error: ${e.stack ?? String(e)}\n`);
+        // REQ-JRN-006 one Strict line that points to the report command and the issues page
+        io.err(`Run ${runCommand(io.journal?.run ?? "specctx", "report")} and file the output at https://github.com/sonqh/spec-ctx/issues.\n`);
+        note(io, { err: errInfo(e) });
         return 3;
     }
 }

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/tasks/evidence.js

@@ -39,9 +39,9 @@ export function writeEvidence(root, t, entries, verify, kind, note, cwd) {
     // REQ-STAT-002 copy the bundle size and the start time that task start wrote for this task
     try {
         const cur = JSON.parse(readFileSync(join(root, ".ctx/current.json"), "utf8"));
-        if (cur.task === t.id) {
-            if (typeof cur.bundle_chars === "number")
-                ev.bundle_chars = cur.bundle_chars;
+        // REQ-LOOP-018 started_at only with bundle_chars, so a window that a failed run opened gives no cycle time (056/D4)
+        if (cur.task === t.id && typeof cur.bundle_chars === "number") {
+            ev.bundle_chars = cur.bundle_chars;
             if (typeof cur.started_at === "string")
                 ev.started_at = cur.started_at;
         }

package/dist/util/redact.js

@@ -0,0 +1,57 @@
+// REQ-TASK-008 machine paths out of evidence (056/D5). Windows paths are out of scope: Verify runs through sh.
+import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
+const WORD = /[A-Za-z0-9._-]/;
+function trimSlash(p) {
+    return p.length > 1 && p.endsWith("/") ? p.slice(0, -1) : p;
+}
+function realOf(root) {
+    try {
+        return realpathSync(root);
+    }
+    catch {
+        return null;
+    }
+}
+/** The home directory: HOME at call time when set, else the OS answer. Bun caches homedir(), so HOME goes first. */
+function homeNow() {
+    return process.env.HOME || homedir();
+}
+/**
+ * REQ-TASK-008 replace the project root and its real path with `.`, and the home directory with `~`. The longest path
+ * goes first, and the root wins a tie. A match needs a start of text or a non word character before it and a non word
+ * character or the end after it. A root or home of `/` or the empty string is skipped. `real` defaults to the real path
+ * of `root`, so a test can pin the macOS `/tmp` case.
+ */
+export function redactPaths(text, root, home = homeNow(), real = realOf(root)) {
+    const pairs = [];
+    const add = (from, to) => {
+        if (from === null)
+            return;
+        const p = trimSlash(from);
+        if (p === "" || p === "/" || pairs.some(([f]) => f === p))
+            return;
+        pairs.push([p, to]);
+    };
+    add(root, ".");
+    add(real, ".");
+    add(home, "~");
+    if (!pairs.length || text === "")
+        return text;
+    // the longest path first, the root before the home on a tie (a stable sort keeps the push order)
+    pairs.sort((a, b) => b[0].length - a[0].length);
+    let out = "";
+    let i = 0;
+    while (i < text.length) {
+        const hit = pairs.find(([from]) => text.startsWith(from, i) && (i === 0 || !WORD.test(text[i - 1])) && (i + from.length === text.length || !WORD.test(text[i + from.length])));
+        if (hit) {
+            out += hit[1];
+            i += hit[0].length;
+        }
+        else {
+            out += text[i];
+            i++;
+        }
+    }
+    return out;
+}

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.5.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-ctx",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "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