spec-ctx 0.1.1 → 0.2.0

package/dist/loop/next.js

@@ -0,0 +1,173 @@
+// REQ-LOOP-001 specctx next: the next action from the files on disk, with a closed enum (024/D1, 024/D2, ADR-006 item 2).
+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 { 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 { 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"];
+/** 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"]);
+/** 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");
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const n of readdirSync(dir)) {
+        if (n === "archive" || n.startsWith("."))
+            continue;
+        try {
+            if (statSync(join(dir, n)).isDirectory())
+                out.push(n);
+        }
+        catch {
+            // a vanished entry is not a change
+        }
+    }
+    return out.sort(cmpStr);
+}
+function questions(root) {
+    try {
+        return readQuestions(root);
+    }
+    catch {
+        return [];
+    }
+}
+/** The last line of the gate log, or null. */
+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;
+    }
+}
+/** The `at` of the newest live evidence file of a change key, or "" with none. */
+function newestEvidenceAt(root, key) {
+    let newest = "";
+    for (const rel of listEvidence(root)) {
+        if (rel.split("/")[2] !== key)
+            continue;
+        try {
+            const ev = JSON.parse(readFileSync(join(root, rel), "utf8"));
+            if (typeof ev.at === "string" && cmpStr(ev.at, newest) > 0)
+                newest = ev.at;
+        }
+        catch {
+            // a damaged evidence file is a check finding
+        }
+    }
+    return newest;
+}
+function readCurrent(root) {
+    try {
+        return JSON.parse(readFileSync(join(root, ".ctx/current.json"), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** 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 });
+    // 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));
+    if (folder === undefined) {
+        const name = want ?? "<name>";
+        return done({ action: "plan", change: want ?? null, command: `${openspec} new change ${name}`, human: true, reason: want === undefined ? "no active change" : `no change ${want}`, state: "no_change" });
+    }
+    d.change = folder;
+    const key = changeKey(folder);
+    const entries = data.entries;
+    const ofChange = (t) => t.change === folder && !t.file.includes("/archive/");
+    const qs = questions(root);
+    // step 2: an open question for the change blocks it
+    const blocking = qs.find((q) => q.status === "open" && (q.task === folder || q.task === key || q.task.startsWith(`${key}/`)));
+    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 });
+    }
+    // step 3: planning state from OpenSpec
+    const st = openspecStatus(root, openspec, folder);
+    if (!st.ok)
+        return done({ action: "stop", reason: st.reason, state: "openspec_failed" });
+    if (!st.state.isPlanningComplete) {
+        return done({ action: "plan", command: st.state.nextStep ?? `${openspec} status --change ${folder}`, human: true, reason: "planning is not complete", state: "planning" });
+    }
+    // step 4: a citation gap in the files of the change
+    const prefix = `openspec/changes/${folder}/`;
+    const found = applyBaseline(root, check(root, cfg, data, true), []).findings
+        .filter((f) => CITE_RULES.has(f.rule) && f.file.startsWith(prefix))
+        .sort((a, b) => cmpTuple([a.file, a.line, a.rule], [b.file, b.line, b.rule]));
+    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 });
+    }
+    // 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));
+    if (ticked)
+        return done({ action: "repair", command: `specctx task done ${ticked.id}`, state: "done_without_evidence", task: ticked.id });
+    // 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;
+        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 });
+    }
+    // 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 });
+    // 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" });
+    }
+    // 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" });
+}
+/** 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));
+    const lines = [`action: ${d.action}`];
+    for (const k of KEYS) {
+        if (k === "action" || k === "command")
+            continue;
+        lines.push(`${k}: ${show(d[k])}`);
+    }
+    lines.push(`next: ${show(d.command)}`);
+    return lines.join("\n") + "\n";
+}

package/dist/loop/openspec.js

@@ -0,0 +1,41 @@
+// REQ-LOOP-001 the one OpenSpec call of next: status --change <c> --json, two keys read (024/D3, ADR-006 item 2).
+import { spawnSync } from "node:child_process";
+const TIMEOUT_MS = 60_000;
+/** REQ-LOOP-001 the command that gate and next run for OpenSpec. The env var wins over [gate] openspec (018/D2). */
+export function openspecCommand(configured) {
+    return process.env.SPECCTX_OPENSPEC ?? configured;
+}
+const firstLine = (text) => text.split("\n").map((l) => l.trim()).find(Boolean) ?? "";
+/** OpenSpec reports an error as JSON `{ status: [{ message }] }` on stdout. The first message is the reason. */
+function errorMessage(stdout) {
+    try {
+        const o = JSON.parse(stdout);
+        const m = o.status?.find((s) => typeof s.message === "string")?.message;
+        return typeof m === "string" ? firstLine(m) : "";
+    }
+    catch {
+        return "";
+    }
+}
+/** Run `<openspec> status --change <folder> --json` in the root. A failure of any kind is a reason, never a throw. */
+export function openspecStatus(root, openspec, folder) {
+    const r = spawnSync("/bin/sh", ["-c", `${openspec} status --change ${folder} --json`], { cwd: root, encoding: "utf8", timeout: TIMEOUT_MS });
+    if (r.error && r.error.code === "ETIMEDOUT") {
+        return { ok: false, reason: `openspec status timed out after ${TIMEOUT_MS / 1000}s` };
+    }
+    const head = errorMessage(r.stdout ?? "") || firstLine(r.stderr ?? "") || firstLine(r.stdout ?? "") || "no output";
+    if (r.status !== 0)
+        return { ok: false, reason: `openspec status failed (exit ${r.status ?? "none"}): ${head}` };
+    let raw;
+    try {
+        raw = JSON.parse(r.stdout);
+    }
+    catch {
+        return { ok: false, reason: `openspec status printed no JSON: ${head}` };
+    }
+    if (raw === null || typeof raw !== "object")
+        return { ok: false, reason: "openspec status printed no JSON object" };
+    const o = raw;
+    const steps = Array.isArray(o.nextSteps) ? o.nextSteps.filter((s) => typeof s === "string") : [];
+    return { ok: true, state: { isPlanningComplete: o.isPlanningComplete === true, nextStep: steps[0] ?? null } };
+}

package/dist/stats/stats.js

@@ -3,6 +3,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 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"];
 const NA = (n = 0) => ({ value: null, n, text: "n/a" });
@@ -21,7 +22,8 @@ function readEvidence(root) {
             continue;
         }
         for (const n of names) {
-            if (!n.endsWith(".json"))
+            // REQ-LOOP-002 a fail file is the retry record, not evidence (024/D4)
+            if (!n.endsWith(".json") || isFailFile(n))
                 continue;
             try {
                 const ev = JSON.parse(readFileSync(join(dir, c, n), "utf8"));

package/dist/tasks/evidence.js

@@ -79,7 +79,10 @@ export function retireEvidence(root, t, reason) {
     }
     return target;
 }
-/** Every live evidence file, as a path relative to the root. Reopened copies are history and stay out. */
+/** REQ-LOOP-002 the file name pattern of a fail file. Every evidence reader skips it (024/D4). */
+export const FAIL_RE = /\.fail-\d+\.json$/;
+export const isFailFile = (name) => FAIL_RE.test(name);
+/** Every live evidence file, as a path relative to the root. Reopened copies and fail files are history and stay out. */
 export function listEvidence(root) {
     const dir = join(root, ".ctx/evidence");
     if (!existsSync(dir))
@@ -94,7 +97,7 @@ export function listEvidence(root) {
             continue;
         }
         for (const n of names.sort()) {
-            if (n.endsWith(".json") && !n.includes(".reopened-"))
+            if (n.endsWith(".json") && !n.includes(".reopened-") && !isFailFile(n))
                 out.push(`.ctx/evidence/${c}/${n}`);
         }
     }

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.1.1";
+export const VERSION = "0.2.0";

package/package.json

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

package/schemas/spec-driven-ids/README.md

@@ -1,19 +1,19 @@
 # spec-driven-ids
 
-A fork of the OpenSpec `spec-driven` schema. It adds stable IDs from spec-ctx to every artifact.
+Templates and config rules that add stable IDs from spec-ctx to the OpenSpec `spec-driven` workflow. The project keeps `schema: spec-driven` in `openspec/config.yaml`. Upstream OpenSpec injects the `rules` and `operations` below into every artifact instruction, so the agent learns the ID commands from there.
 
-- The spec template starts each requirement with `REQ-<CAP>-NNN` and each scenario with `SCN-<CAP>-NNN-<n>`.
-- The instructions tell the agent to get IDs from `specctx id new` and to link IDs with `Refs:` lines.
-- The tasks template cites REQ IDs and puts the `Verify:` command in a code span, so `specctx task done` can run it.
-- `config-fragment.yaml` holds the `rules` and `operations` for `openspec/config.yaml`.
+- `templates/spec.md` starts each requirement with `REQ-<CAP>-NNN` and each scenario with `SCN-<CAP>-NNN-<n>`.
+- `templates/tasks.md` cites REQ IDs and puts the `Verify:` command in a code span, so `specctx task done` can run it.
+- `templates/design.md` ends each decision with a `Refs:` line.
+- `config-fragment.yaml` holds the `rules` and `operations` for `openspec/config.yaml`. The rules tell the agent to get IDs from `specctx id new` and name the templates path. The `apply` guidance says that a task closes only with `specctx task done <id>` and that the agent runs the `specctx-run` skill, never `/opsx:apply`.
 
 ## Install by copy
 
 - Clone the repository: `git clone https://github.com/sonqh/spec-ctx`.
-- Copy `schemas/spec-driven-ids` to `openspec/schemas/spec-driven-ids` in your project.
-- Set `schema: spec-driven-ids` in `openspec/config.yaml`.
+- Copy `schemas/spec-driven-ids/templates` to `openspec/templates/spec-driven-ids` in your project.
+- Keep `schema: spec-driven` in `openspec/config.yaml`.
 - Merge `config-fragment.yaml` into `openspec/config.yaml` by hand. Add its `rules` and `operations` keys. Keep every item quoted.
-- Run `openspec schema validate spec-driven-ids`.
+- Run `openspec validate --all`.
 
 ## Install with init --schema
 
@@ -21,11 +21,11 @@ A fork of the OpenSpec `spec-driven` schema. It adds stable IDs from spec-ctx to
 npx -y spec-ctx init --schema
 ```
 
-- The command copies this folder to `openspec/schemas/spec-driven-ids/`.
-- It sets `schema: spec-driven-ids` in `openspec/config.yaml`.
-- It adds the `rules` and `operations` keys that the config does not have yet. It leaves other keys as they are.
+- The command copies the four templates to `openspec/templates/spec-driven-ids/`.
+- It adds the `rules` and `operations` keys that the config does not have yet. A key that exists gets the items it lacks. Other keys stay as they are.
 - It quotes a list item that YAML would read as a mapping.
+- It does not touch the `schema` key. A project that still says `schema: spec-driven-ids` gets a note. Set `schema: spec-driven` by hand and delete `openspec/schemas/spec-driven-ids/`.
 
 ## Version
 
-Forked from OpenSpec 1.14.3 with `openspec schema fork spec-driven spec-driven-ids`. CI validates it against that version.
+The templates follow the `spec-driven` templates of OpenSpec 1.14.3 with the ID placeholders added. `tests/schema/validate.sh` checks them on upstream OpenSpec in CI.

package/schemas/spec-driven-ids/config-fragment.yaml

@@ -1,11 +1,12 @@
 # spec-ctx fragment for openspec/config.yaml. specctx init --schema adds each top-level key
-# that the project config does not have yet. It never changes a key that exists.
+# that the project config does not have yet. A key that exists gets the items it lacks.
 rules:
   specs:
     - 'Every requirement header starts with its ID, e.g. "### Requirement: REQ-ABC-001 Name". Get the ID from `specctx id new REQ ABC`.'
     - 'Every scenario header starts with its ID, e.g. "#### Scenario: SCN-ABC-001-1 Name".'
     - 'A requirement may end with a line "Refs: REQ-ABC-002, ADR-001" to link related IDs.'
     - 'Requirement text stays under 500 characters. Move detail into scenarios.'
+    - 'The templates with the ID placeholders are in openspec/templates/spec-driven-ids/. Start a spec from spec.md and a task list from tasks.md there.'
   design:
     - 'Each decision is one bullet under "## Decisions". Add new decisions at the end.'
   tasks:
@@ -17,7 +18,7 @@ operations:
     guidance:
       - 'Start each task with `specctx task start <id>` and read the bundle it prints before you read specs.'
       - 'Tag code with the REQ ID it implements (a comment `// REQ-ABC-001`). Tag tests with `// Covers: REQ-ABC-001`.'
-      - 'Close each task with `specctx task done <id>`. Never tick a checkbox by hand.'
+      - 'Close each task only with `specctx task done <id>`. Never edit a checkbox. Never run `/opsx:apply`; run the `specctx-run` skill.'
       - 'Run `specctx check --strict` after each task group.'
   archive:
     guidance:

package/skills/specctx-bootstrap/SKILL.md

@@ -3,25 +3,4 @@ name: specctx-bootstrap
 description: Start a session in an OpenSpec project that uses spec-ctx. Use at the start of every session, and on "start", "bootstrap", or "what should I work on". Loads only the spec text that the next task needs.
 ---
 
-# specctx-bootstrap
-
-Load the minimum context for one task. Run `specctx` as `npx spec-ctx` when it is not installed.
-
-## Steps
-
-1. Run `specctx status`. It rebuilds a stale index first. Note the active change, the current task, and the count of open questions. The last line `next: <step>` names the next step. Exit 2 with `not an OpenSpec project` means the folder has no `openspec/`. Tell the user to run `npx -y @fission-ai/openspec@latest init` and stop.
-2. Read `.ctx/handoff.md` if it exists. Note `current`, `reopened`, and `open_questions`.
-3. If `status` prints `no active change`, show the open questions to the user. Ask which change to start. Stop here.
-4. Pick the task. Use `current` from the handoff, then the user's message, then the output of `specctx task next`.
-5. Run `specctx task start <task>`. It prints the bundle for the REQ IDs of the task and sets the current task.
-6. Read the bundle. Each block starts with `-- <id> | <file>:<line> | <status> | <reason>`. A `modified` block is the pending text of an active change. Trust it over the main spec.
-7. If the bundle ends with `truncated: N entries omitted: <ids>`, run `specctx bundle <id>` for each ID that the task needs.
-8. Say in one line which task you are on and which IDs you loaded. Then start the work.
-
-## Rules
-
-- Do not open `openspec/specs/` or `openspec/changes/*/specs/` by hand. Use `specctx bundle` or `specctx task start`.
-- Read at most 10,000 characters of spec text before the first code edit.
-- Tag code with `// REQ-ABC-001` and tests with `// Covers: REQ-ABC-001`.
-- Get a new ID from `specctx id new REQ <CAP>`. Never count numbers by hand.
-- Close the task with the `specctx-done` skill.
+This skill is now `specctx-run`. Run it.

package/skills/specctx-done/SKILL.md

@@ -3,23 +3,4 @@ name: specctx-done
 description: Close a task in an OpenSpec project that uses spec-ctx. Runs the Verify command, writes evidence, sets the checkbox, writes the handoff, and shows the metrics. Use when the work of a task is complete, or on "done", "close the task", and "end the session".
 ---
 
-# specctx-done
-
-Close the current task with evidence. Run `specctx` as `npx spec-ctx` when it is not installed.
-
-## Steps
-
-1. Run `specctx task done <task>`. It runs the `Verify:` command of the task in the project root.
-2. On exit 0 it writes `.ctx/evidence/<change>/<task>.json` and sets `[x]` on the task line. Nothing else in `tasks.md` changes.
-3. On a failure it prints the last 20 lines of output and then the line `Verify failed (exit <n>). The task stays open.` It exits 1. Fix the cause and run step 1 again.
-4. If the task has prose after `Verify:` and no command, run `specctx task done <task> --manual "<what you checked>"`.
-5. After the last task of a group, run `specctx check --strict`. Fix every finding before the next group.
-6. Run `specctx handoff write`. It writes `.ctx/handoff.md` from the index, the evidence, and the open questions.
-7. Run `specctx stats --change <change>`. Report the five metrics of the change in one line each.
-8. Commit the work together with `.ctx/`. Leave `.ctx/index.json` out of git.
-
-## Rules
-
-- Never tick a checkbox by hand. `check --strict` reports a ticked task with no evidence as `done-without-evidence`.
-- If a spec changed after you closed a task, run `specctx task reopen <task> "<reason>"`.
-- To leave a question for the next session, run `specctx handoff ask "<question>"` before step 6.
+This skill is now `specctx-run`. Run it.

package/skills/specctx-next/SKILL.md

@@ -3,21 +3,4 @@ name: specctx-next
 description: Pick and start the next task in the middle of a session in an OpenSpec project that uses spec-ctx. Use after you close a task, or on "next task" and "what is next".
 ---
 
-# specctx-next
-
-Move to the next open task. Run `specctx` as `npx spec-ctx` when it is not installed.
-
-## Steps
-
-1. Run `specctx task next`. It prints the task ID and text, then `reqs:` and `verify:`.
-2. If it prints `no open task. Every task in the active changes is done. Next: archive <change>.`, every task of the active changes has its checkbox set. Run `specctx status`. Its last line is `next: archive <change>`. Tell the user that the change is ready for `specctx check --strict` and archive. Stop here.
-3. Run `specctx task start <task>`. It prints the bundle for the REQ IDs of the task and sets the current task in `.ctx/current.json`.
-4. Read the bundle. Request an omitted ID with `specctx bundle <id>` only when the task needs it.
-5. Run `specctx task verify <task>` once before the work. It runs the `Verify:` command and writes nothing. A failure now shows what the work must fix.
-6. Say in one line which task you are on. Then start the work.
-
-## Rules
-
-- Take the tasks in the order that `specctx task next` gives. Earlier tasks in a group come first.
-- A question that blocks you goes to `specctx handoff ask "<question>"`. Then continue with what you can do.
-- Close the task with the `specctx-done` skill.
+This skill is now `specctx-run`. Run it.

package/skills/specctx-run/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: specctx-run
+description: Run the spec-ctx loop in an OpenSpec project. Use on "run", "continue", "next task", "build this", "carry on", and on a first message that describes a change to build. The engine picks the next action. The skill acts on it until the change reaches the archive or a human must decide.
+---
+
+# specctx-run
+
+Run `specctx` as `npx spec-ctx` when it is not installed. `openspec` is the command in `[gate] openspec` of `spec-ctx.toml`.
+
+## The loop
+
+1. Run `specctx next --json`. Read `action`, `change` (`<c>`), `task` (`<t>`), `command`, `reason`, and `human`.
+2. Act on `action` as the table below says.
+3. Run `specctx handoff write`.
+4. Repeat from step 1 until `action` is `stop` or `human` is true.
+
+## 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.
+- `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`.
+- `ask`: print `reason`. It is the open question. Stop. The user answers with `specctx handoff resolve <n> "<answer>"`.
+- `stop`: print `reason`. Stop.
+
+## Rules
+
+- 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.
+- 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.