spec-ctx 0.3.0 → 0.4.0

package/README.md

@@ -284,10 +284,41 @@ npx spec-ctx lint ste --baseline 0 --disable synonym-rotation README.md
 
 The action runs `specctx gate`: `check --strict`, both markdown linters, `openspec validate --all --strict`, and the length check.
 
+### Rerun
+
+```yaml
+on: pull_request
+permissions:
+  contents: read
+jobs:
+  rerun:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: sonqh/spec-ctx@v0
+        with:
+          rerun: true
+          base: origin/${{ github.base_ref }}
+```
+
+With `rerun: true` the action runs `specctx gate --rerun` and no other step. It runs the Verify command of each task that the pull request closed and compares the exit code with the evidence. `base` is the ref for the merge base. Without `rerun`, the action ignores `base`.
+
+On `push`, the default base gives a merge base equal to HEAD, so the rerun compares nothing. It prints one line and passes. Pass `base: ${{ github.event.before }}` on push. A push that creates a branch gives forty zeros. The rerun prints `rerun: base is the zero commit (a new branch), nothing to compare` and passes. After a force push the old commit may be missing from the clone. The rerun then prints `rerun: base <ref> is not in this clone. Fetch it or use fetch-depth: 0` and exits 1.
+
+A Verify command is code from the pull request. The boundary:
+
+- Use the `pull_request` and `push` events only. The action exits 1 on any other event.
+- Never use `pull_request_target` or `workflow_run` with code from a pull request. The action exits 1 on `pull_request_target`.
+- Set `permissions: contents: read`.
+- Give the job no secrets.
+- For fork pull requests, turn on the repository setting that asks for approval before a workflow runs.
+- Check out with `fetch-depth: 0`. The merge base needs full history.
+
 ## Status
 
-- Published: `spec-ctx@0.3.0` on npm, with tags `v0.3.0` and `v0` and binaries on the GitHub release.
-- Archived: 001 to 025 and 027 to 032. No change is open. See `CHANGELOG.md` for each release.
+- Published: `spec-ctx@0.4.0` on npm, with tags `v0.4.0` and `v0` and binaries on the GitHub release.
+- Archived: 001 to 025, 027 to 034, and 036 to 042. No change is open. See `CHANGELOG.md` for each release.
 - A version bump on `main` publishes the next release. See `docs/CONTRIBUTING.md`.
 - Upstream: the ID scheme is proposed as a comment on [OpenSpec#1967](https://github.com/Fission-AI/OpenSpec/issues/1967#issuecomment-6414314730). The schema bundle is submitted to the community table in [OpenSpec#2157](https://github.com/Fission-AI/OpenSpec/issues/2157). No pull request until a maintainer asks.
 
@@ -297,7 +328,7 @@ The action runs `specctx gate`: `check --strict`, both markdown linters, `opensp
 
 | change | context_ratio | evidence_ratio | stale_catches | cycle_time_median_s | debt |
 | --- | --- | --- | --- | --- | --- |
-| total | 0.0281 (n=93) | 0.91 (166/182) | 43 (of 90 reopens) | 76 (n=93) | 0 (0 baselined + 0 new) |
+| total | 0.0228 (n=116) | 0.93 (204/220) | 56 (of 106 reopens) | 61 (n=116) | 0 (0 baselined + 0 new) |
 
 - `context_ratio`: the size of one task bundle divided by the size of all spec text. Lower is better.
 - `evidence_ratio`: done tasks with a passed Verify command, divided by all done tasks. The rest have a manual note. Higher is better.

package/action.yml

@@ -16,6 +16,12 @@ inputs:
   specctx:
     description: Command that runs specctx. Empty means npx with the version input.
     default: ""
+  rerun:
+    description: Run only gate --rerun. It reruns the Verify command of each task that the pull request closed. Use it on pull_request or push only. On push, pass the commit before the push (github.event.before) as base.
+    default: "false"
+  base:
+    description: With rerun, the ref for the merge base, such as origin/main. On push, use the commit before the push (github.event.before). Empty uses the default of spec-ctx.toml. Without rerun, the action ignores it.
+    default: ""
 runs:
   using: composite
   steps:
@@ -30,4 +36,6 @@ runs:
         INPUT_STRICT: ${{ inputs.strict }}
         INPUT_MARKDOWN: ${{ inputs.markdown }}
         INPUT_SPECCTX: ${{ inputs.specctx }}
+        INPUT_RERUN: ${{ inputs.rerun }}
+        INPUT_BASE: ${{ inputs.base }}
         SPECCTX_ACTION_PATH: ${{ github.action_path }}

package/dist/adopt/write.js

@@ -2,14 +2,15 @@
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { UsageExit } from "../cli/errors.js";
-import { CONFIG_FILE, loadConfig } from "../config.js";
+import { CONFIG_FILE } from "../config.js";
+import { loadConfigOrExit } from "../cli/config.js";
 import { dumps } from "../util/json.js";
 import { configText, withCaps } from "./config-write.js";
 export const REPORT_FILE = "adopt-report.md";
 async function findings(root) {
     const { buildIndex } = await import("../index/build.js");
     const { check } = await import("../check/check.js");
-    const cfg = loadConfig(root);
+    const cfg = loadConfigOrExit(root);
     const data = buildIndex(root, cfg);
     return new Set(check(root, cfg, data, false).map((f) => `${f.file}:${f.line}  ${f.rule}  ${f.id}`));
 }

package/dist/assets.generated.js

@@ -10,5 +10,5 @@ export const ASSETS = {
     "skills/specctx-bootstrap/SKILL.md": "LS0tCm5hbWU6IHNwZWNjdHgtYm9vdHN0cmFwCmRlc2NyaXB0aW9uOiBTdGFydCBhIHNlc3Npb24gaW4gYW4gT3BlblNwZWMgcHJvamVjdCB0aGF0IHVzZXMgc3BlYy1jdHguIFVzZSBhdCB0aGUgc3RhcnQgb2YgZXZlcnkgc2Vzc2lvbiwgYW5kIG9uICJzdGFydCIsICJib290c3RyYXAiLCBvciAid2hhdCBzaG91bGQgSSB3b3JrIG9uIi4gTG9hZHMgb25seSB0aGUgc3BlYyB0ZXh0IHRoYXQgdGhlIG5leHQgdGFzayBuZWVkcy4KLS0tCgpUaGlzIHNraWxsIGlzIG5vdyBgc3BlY2N0eC1ydW5gLiBSdW4gaXQuCg==",
     "skills/specctx-done/SKILL.md": "LS0tCm5hbWU6IHNwZWNjdHgtZG9uZQpkZXNjcmlwdGlvbjogQ2xvc2UgYSB0YXNrIGluIGFuIE9wZW5TcGVjIHByb2plY3QgdGhhdCB1c2VzIHNwZWMtY3R4LiBSdW5zIHRoZSBWZXJpZnkgY29tbWFuZCwgd3JpdGVzIGV2aWRlbmNlLCBzZXRzIHRoZSBjaGVja2JveCwgd3JpdGVzIHRoZSBoYW5kb2ZmLCBhbmQgc2hvd3MgdGhlIG1ldHJpY3MuIFVzZSB3aGVuIHRoZSB3b3JrIG9mIGEgdGFzayBpcyBjb21wbGV0ZSwgb3Igb24gImRvbmUiLCAiY2xvc2UgdGhlIHRhc2siLCBhbmQgImVuZCB0aGUgc2Vzc2lvbiIuCi0tLQoKVGhpcyBza2lsbCBpcyBub3cgYHNwZWNjdHgtcnVuYC4gUnVuIGl0Lgo=",
     "skills/specctx-next/SKILL.md": "LS0tCm5hbWU6IHNwZWNjdHgtbmV4dApkZXNjcmlwdGlvbjogUGljayBhbmQgc3RhcnQgdGhlIG5leHQgdGFzayBpbiB0aGUgbWlkZGxlIG9mIGEgc2Vzc2lvbiBpbiBhbiBPcGVuU3BlYyBwcm9qZWN0IHRoYXQgdXNlcyBzcGVjLWN0eC4gVXNlIGFmdGVyIHlvdSBjbG9zZSBhIHRhc2ssIG9yIG9uICJuZXh0IHRhc2siIGFuZCAid2hhdCBpcyBuZXh0Ii4KLS0tCgpUaGlzIHNraWxsIGlzIG5vdyBgc3BlY2N0eC1ydW5gLiBSdW4gaXQuCg==",
-    "skills/specctx-run/SKILL.md": "LS0tCm5hbWU6IHNwZWNjdHgtcnVuCmRlc2NyaXB0aW9uOiBSdW4gdGhlIHNwZWMtY3R4IGxvb3AgaW4gYW4gT3BlblNwZWMgcHJvamVjdC4gVXNlIG9uICJydW4iLCAiY29udGludWUiLCAibmV4dCB0YXNrIiwgImJ1aWxkIHRoaXMiLCAiY2Fycnkgb24iLCBhbmQgb24gYSBmaXJzdCBtZXNzYWdlIHRoYXQgZGVzY3JpYmVzIGEgY2hhbmdlIHRvIGJ1aWxkLiBUaGUgZW5naW5lIHBpY2tzIHRoZSBuZXh0IGFjdGlvbi4gVGhlIHNraWxsIGFjdHMgb24gaXQgdW50aWwgdGhlIGNoYW5nZSByZWFjaGVzIHRoZSBhcmNoaXZlIG9yIGEgaHVtYW4gbXVzdCBkZWNpZGUuCi0tLQoKIyBzcGVjY3R4LXJ1bgoKUnVuIGBzcGVjY3R4YCBhcyBgbnB4IHNwZWMtY3R4YCB3aGVuIGl0IGlzIG5vdCBpbnN0YWxsZWQuIGBvcGVuc3BlY2AgaXMgdGhlIGNvbW1hbmQgaW4gYFtnYXRlXSBvcGVuc3BlY2Agb2YgYHNwZWMtY3R4LnRvbWxgLiBXaGVuIHRoYXQga2V5IGlzIGFic2VudCwgYG9wZW5zcGVjYCBpcyBgbnB4IC15IEBmaXNzaW9uLWFpL29wZW5zcGVjQGxhdGVzdGAuCgojIyBUaGUgbG9vcAoKMS4gUnVuIGBzcGVjY3R4IG5leHQgLS1qc29uYC4gUmVhZCBgYWN0aW9uYCwgYGNoYW5nZWAgKGA8Yz5gKSwgYHRhc2tgIChgPHQ+YCksIGBjb21tYW5kYCwgYHJlYXNvbmAsIGFuZCBgaHVtYW5gLgoyLiBBY3Qgb24gYGFjdGlvbmAgYXMgdGhlIHRhYmxlIGJlbG93IHNheXMuCjMuIFJ1biBgc3BlY2N0eCBoYW5kb2ZmIHdyaXRlYC4KNC4gUmVwZWF0IGZyb20gc3RlcCAxIHVudGlsIGBhY3Rpb25gIGlzIGBzdG9wYCBvciBgaHVtYW5gIGlzIHRydWUuCgojIyBBY3Rpb25zCgotIGBwbGFuYDogdGFrZSB0aGUgY2hhbmdlIG5hbWUgZnJvbSB0aGUgcmVxdWVzdCBvZiB0aGUgdXNlciBpbiBrZWJhYiBjYXNlLiBUaGF0IG5hbWUgaXMgYDxjPmAuIEZvbGxvdyB0aGUgdXBzdHJlYW0gYG9wZW5zcGVjLXByb3Bvc2VgIHNraWxsIGZvciBgPGM+YC4gUmVhZCBleGlzdGluZyByZXF1aXJlbWVudHMgd2l0aCBgc3BlY2N0eCBidW5kbGUgPGlkPmAgb3IgYHNwZWNjdHggcXVlcnlgLCBuZXZlciBgb3BlbnNwZWMgc2hvd2AuIFRha2UgZXZlcnkgSUQgZnJvbSBgc3BlY2N0eCBpZCBuZXcgUkVRIDxDQVA+YCBhbmQgYHNwZWNjdHggaWQgbmV3IFNDTiA8Q0FQPiAtLWZvciA8UkVRPmAuIFdoZW4gdGhlIGNoYW5nZSBuZWVkcyBzZXZlcmFsIElEcyBvZiBvbmUga2luZCwgcnVuIGBzcGVjY3R4IGlkIG5ldyAtLWNvdW50IDxuPmAgb25jZS4gR2l2ZSBldmVyeSB0YXNrIGEgYFtSRVEtLi4uXWAgY2l0YXRpb24gYW5kIGEgYFZlcmlmeTpgIGNvZGUgc3Bhbi4gVGhlbiBydW4gYHNwZWNjdHggY2hlY2sgLS1zdHJpY3RgIGFuZCBgc3BlY2N0eCBnYXRlIC0tc3RyaWN0YC4gVGhlIGdhdGUgcnVucyB0aGUgT3BlblNwZWMgdmFsaWRhdGUgYW5kIHRoZSBzcGVjLWxlbmd0aCBjaGVjay4gRml4IGV2ZXJ5IGZpbmRpbmcuIFRoZW4gcnVuIGBzcGVjY3R4IGhhbmRvZmYgYXNrIC0tY2hhbmdlIDxjPiAicGxhbiByZWFkeSBmb3IgPGM+LiBBcHByb3ZlIHRvIHN0YXJ0IHRoZSB0YXNrcz8iYC4gVGhpcyBpcyB0aGUgcGxhbiBzdG9wLiBgbmV4dGAgcmV0dXJucyBgYXNrYCB1bnRpbCB0aGUgdXNlciByZXNvbHZlcyB0aGUgcXVlc3Rpb24uCi0gYGNpdGVgOiBydW4gYHNwZWNjdHggcXVlcnkgLS1jaGFuZ2UgPGM+IC0ta2luZCByZXFgLiBBZGQgdGhlIGBbUkVRLS4uLl1gIGNpdGF0aW9uIGFuZCBhIGBWZXJpZnk6YCBjb2RlIHNwYW4gdG8gdGhlIHRhc2sgbGluZSBuYW1lZCBpbiBgdGFza2AuIFJ1biBgc3BlY2N0eCBjaGVja2AuIENvbnRpbnVlLgotIGBzdGFydGA6IHJ1biBgc3BlY2N0eCB0YXNrIHN0YXJ0IDx0PmAuIFJlYWQgdGhlIGJ1bmRsZSBpdCBwcmludHMuIENvbnRpbnVlLgotIGB3b3JrYDogaW1wbGVtZW50IHRoZSB0YXNrLiBUYWcgY29kZSB3aXRoIGAvLyBSRVEtLi4uYC4gVGFnIHRlc3RzIHdpdGggYC8vIENvdmVyczogUkVRLS4uLmAuIFRoZW4gcnVuIGBzcGVjY3R4IHRhc2sgZG9uZSA8dD5gLgotIGBmaXhgOiByZWFkIGByZWFzb25gLiBJdCBob2xkcyB0aGUgdGFpbCBvZiB0aGUgZmFpbGVkIFZlcmlmeSBvdXRwdXQuIEZpeCB0aGUgY2F1c2UuIFJ1biBgc3BlY2N0eCB0YXNrIGRvbmUgPHQ+YCBhZ2Fpbi4KLSBgcmVwYWlyYDogcnVuIHRoZSBjb21tYW5kIGluIHRoZSBgY29tbWFuZGAgZmllbGQuIEl0IHJ1bnMgVmVyaWZ5IGFnYWluIGZvciBhIHRpY2tlZCB0YXNrIHdob3NlIGV2aWRlbmNlIGlzIGFic2VudCBvciBzdGFsZS4KLSBgZ2F0ZWA6IHJ1biBgc3BlY2N0eCBnYXRlIC0tc3RyaWN0YC4gRml4IGV2ZXJ5IGZpbmRpbmcuIFJ1biBpdCBhZ2FpbiB1bnRpbCBpdCBleGl0cyAwLgotIGBhcmNoaXZlYDogd2hlbiBgaHVtYW5gIGlzIHRydWUsIHJ1biBgc3BlY2N0eCBoYW5kb2ZmIGFzayAtLWNoYW5nZSA8Yz4gImFyY2hpdmUgPGM+PyJgIGFuZCBzdG9wLiBUaGlzIGlzIHRoZSBhcmNoaXZlIHN0b3AuIGBuZXh0YCByZXR1cm5zIGBhc2tgIHVudGlsIHRoZSB1c2VyIHJlc29sdmVzIHRoZSBxdWVzdGlvbi4gV2hlbiBgaHVtYW5gIGlzIGZhbHNlLCB0aGUgdXNlciBhcHByb3ZlZCBvciBgW2xvb3BdIGFyY2hpdmVgIGlzIGBhdXRvYC4gVGhlbiBydW4gZWFjaCBzdGVwIHVuZGVyIGBvcGVyYXRpb25zLmFyY2hpdmUuZ3VpZGFuY2VgIGluIGBvcGVuc3BlYy9jb25maWcueWFtbGAuIFRoZW4gcnVuIHRoZSBjb21tYW5kIGluIHRoZSBgY29tbWFuZGAgZmllbGQuIFRoZW4gcnVuIGBvcGVuc3BlYyB2YWxpZGF0ZSAtLWFsbCAtLXN0cmljdGAsIGBzcGVjY3R4IGNoZWNrIC0tc3RyaWN0YCwgYW5kIGBzcGVjY3R4IGhhbmRvZmYgd3JpdGVgLgotIGBhc2tgOiBwcmludCBgcmVhc29uYC4gSXQgaXMgdGhlIG9wZW4gcXVlc3Rpb24uIFN0b3AuIFRoZSB1c2VyIGFuc3dlcnMgd2l0aCBgc3BlY2N0eCBoYW5kb2ZmIHJlc29sdmUgPG4+ICI8YW5zd2VyPiJgLgotIGBzdG9wYDogcHJpbnQgYHJlYXNvbmAuIFN0b3AuCgojIyBSdWxlcwoKLSBOZXZlciB0aWNrIGEgY2hlY2tib3ggYnkgaGFuZC4gYHNwZWNjdHggdGFzayBkb25lYCBpcyB0aGUgb25seSB3YXkgYSB0YXNrIGNsb3Nlcy4KLSBOZXZlciB1c2UgYC0tbWFudWFsYCBvbiBhIHRhc2sgd2l0aCBhIFZlcmlmeSBjb21tYW5kLgotIE5ldmVyIGNhbGwgYC9vcHN4OmFwcGx5YC4gVGhpcyBza2lsbCByZXBsYWNlcyBpdC4KLSBOZXZlciByZWFkIGBvcGVuc3BlYy9zcGVjcy9gIG9yIGBvcGVuc3BlYy9jaGFuZ2VzLyovc3BlY3MvYCBkaXJlY3RseS4gVXNlIHRoZSBidW5kbGUgZnJvbSBgdGFzayBzdGFydGAgb3IgYHNwZWNjdHggYnVuZGxlIDxpZD5gLgotIFN0b3Agb24gYW55IGBhY3Rpb25gIG5vdCBpbiB0aGUgbGlzdCBhYm92ZS4gUHJpbnQgdGhlIG9iamVjdCBhbmQgYXNrIHRoZSB1c2VyLgotIEtlZXAgbm8gc3RhdGUgaW4geW91ciBjb250ZXh0LiBBIG5ldyBzZXNzaW9uIHN0YXJ0cyB0aGUgc2FtZSBsb29wIGFnYWluIHdpdGggc3RlcCAxLgo=",
+    "skills/specctx-run/SKILL.md": "LS0tCm5hbWU6IHNwZWNjdHgtcnVuCmRlc2NyaXB0aW9uOiBSdW4gdGhlIHNwZWMtY3R4IGxvb3AgaW4gYW4gT3BlblNwZWMgcHJvamVjdC4gVXNlIG9uICJydW4iLCAiY29udGludWUiLCAibmV4dCB0YXNrIiwgImJ1aWxkIHRoaXMiLCAiY2Fycnkgb24iLCBhbmQgb24gYSBmaXJzdCBtZXNzYWdlIHRoYXQgZGVzY3JpYmVzIGEgY2hhbmdlIHRvIGJ1aWxkLiBUaGUgZW5naW5lIHBpY2tzIHRoZSBuZXh0IGFjdGlvbi4gVGhlIHNraWxsIGFjdHMgb24gaXQgdW50aWwgdGhlIGNoYW5nZSByZWFjaGVzIHRoZSBhcmNoaXZlIG9yIGEgaHVtYW4gbXVzdCBkZWNpZGUuCi0tLQoKIyBzcGVjY3R4LXJ1bgoKUnVuIGBzcGVjY3R4YCBhcyBgbnB4IHNwZWMtY3R4YCB3aGVuIGl0IGlzIG5vdCBpbnN0YWxsZWQuIGBvcGVuc3BlY2AgaXMgdGhlIGNvbW1hbmQgaW4gYFtnYXRlXSBvcGVuc3BlY2Agb2YgYHNwZWMtY3R4LnRvbWxgLiBXaGVuIHRoYXQga2V5IGlzIGFic2VudCwgYG9wZW5zcGVjYCBpcyBgbnB4IC15IEBmaXNzaW9uLWFpL29wZW5zcGVjQGxhdGVzdGAuCgojIyBUaGUgbG9vcAoKMS4gUnVuIGBzcGVjY3R4IG5leHQgLS1qc29uYC4gUmVhZCBgYWN0aW9uYCwgYGNoYW5nZWAgKGA8Yz5gKSwgYHRhc2tgIChgPHQ+YCksIGBjb21tYW5kYCwgYHJlYXNvbmAsIGFuZCBgaHVtYW5gLgoyLiBBY3Qgb24gYGFjdGlvbmAgYXMgdGhlIHRhYmxlIGJlbG93IHNheXMuCjMuIFJ1biBgc3BlY2N0eCBoYW5kb2ZmIHdyaXRlYC4KNC4gUmVwZWF0IGZyb20gc3RlcCAxIHVudGlsIGBhY3Rpb25gIGlzIGBzdG9wYCBvciBgaHVtYW5gIGlzIHRydWUuCgojIyBBY3Rpb25zCgotIGBwbGFuYDogdGFrZSB0aGUgY2hhbmdlIG5hbWUgZnJvbSB0aGUgcmVxdWVzdCBvZiB0aGUgdXNlciBpbiBrZWJhYiBjYXNlLiBUaGF0IG5hbWUgaXMgYDxjPmAuIEZvbGxvdyB0aGUgdXBzdHJlYW0gYG9wZW5zcGVjLXByb3Bvc2VgIHNraWxsIGZvciBgPGM+YC4gUmVhZCBleGlzdGluZyByZXF1aXJlbWVudHMgd2l0aCBgc3BlY2N0eCBidW5kbGUgPGlkPmAgb3IgYHNwZWNjdHggcXVlcnlgLCBuZXZlciBgb3BlbnNwZWMgc2hvd2AuIFRha2UgZXZlcnkgSUQgZnJvbSBgc3BlY2N0eCBpZCBuZXcgUkVRIDxDQVA+YCBhbmQgYHNwZWNjdHggaWQgbmV3IFNDTiA8Q0FQPiAtLWZvciA8UkVRPmAuIFdoZW4gdGhlIGNoYW5nZSBuZWVkcyBzZXZlcmFsIElEcyBvZiBvbmUga2luZCwgcnVuIGBzcGVjY3R4IGlkIG5ldyAtLWNvdW50IDxuPmAgb25jZS4gR2l2ZSBldmVyeSB0YXNrIGEgYFtSRVEtLi4uXWAgY2l0YXRpb24gYW5kIGEgYFZlcmlmeTpgIGNvZGUgc3Bhbi4gVGhlbiBydW4gYHNwZWNjdHggY2hlY2sgLS1zdHJpY3RgIGFuZCBgc3BlY2N0eCBnYXRlIC0tc3RyaWN0YC4gVGhlIGdhdGUgcnVucyB0aGUgT3BlblNwZWMgdmFsaWRhdGUgYW5kIHRoZSBzcGVjLWxlbmd0aCBjaGVjay4gRml4IGV2ZXJ5IGZpbmRpbmcuIFRoZW4gcnVuIGBzcGVjY3R4IG5leHQgLS1qc29uYCBhbmQgcnVuIHRoZSBjb21tYW5kIGl0IHByaW50cy4gVGhpcyBpcyB0aGUgcGxhbiBzdG9wLiBgbmV4dGAgcmV0dXJucyBgYXNrYCB3aXRoIGBodW1hbjogdHJ1ZWAgdW50aWwgdGhlIHVzZXIgcmVzb2x2ZXMgdGhlIHF1ZXN0aW9uLgotIGBjaXRlYDogcnVuIGBzcGVjY3R4IHF1ZXJ5IC0tY2hhbmdlIDxjPiAtLWtpbmQgcmVxYC4gQWRkIHRoZSBgW1JFUS0uLi5dYCBjaXRhdGlvbiBhbmQgYSBgVmVyaWZ5OmAgY29kZSBzcGFuIHRvIHRoZSB0YXNrIGxpbmUgbmFtZWQgaW4gYHRhc2tgLiBSdW4gYHNwZWNjdHggY2hlY2tgLiBDb250aW51ZS4KLSBgc3RhcnRgOiBydW4gYHNwZWNjdHggdGFzayBzdGFydCA8dD5gLiBSZWFkIHRoZSBidW5kbGUgaXQgcHJpbnRzLiBDb250aW51ZS4KLSBgd29ya2A6IGltcGxlbWVudCB0aGUgdGFzay4gVGFnIGNvZGUgd2l0aCBgLy8gUkVRLS4uLmAuIFRhZyB0ZXN0cyB3aXRoIGAvLyBDb3ZlcnM6IFJFUS0uLi5gLiBUaGVuIHJ1biBgc3BlY2N0eCB0YXNrIGRvbmUgPHQ+YC4KLSBgZml4YDogcmVhZCBgcmVhc29uYC4gSXQgaG9sZHMgdGhlIHRhaWwgb2YgdGhlIGZhaWxlZCBWZXJpZnkgb3V0cHV0LiBGaXggdGhlIGNhdXNlLiBSdW4gYHNwZWNjdHggdGFzayBkb25lIDx0PmAgYWdhaW4uCi0gYHJlcGFpcmA6IHJ1biB0aGUgY29tbWFuZCBpbiB0aGUgYGNvbW1hbmRgIGZpZWxkLiBJdCBydW5zIFZlcmlmeSBhZ2FpbiBmb3IgYSB0aWNrZWQgdGFzayB3aG9zZSBldmlkZW5jZSBpcyBhYnNlbnQgb3Igc3RhbGUuCi0gYGdhdGVgOiBydW4gYHNwZWNjdHggZ2F0ZSAtLXN0cmljdGAuIEZpeCBldmVyeSBmaW5kaW5nLiBGb3IgYSBgc3RhbGUtZXZpZGVuY2VgIGZpbmRpbmcsIGdvIGJhY2sgdG8gc3RlcCAxLiBgbmV4dGAgcmV0dXJucyBgcmVwYWlyYCBhbmQgaXRzIGNvbW1hbmQgcmVwYWlycyBldmVyeSBzdGFsZSB0YXNrLiBSdW4gdGhlIGdhdGUgYWdhaW4gdW50aWwgaXQgZXhpdHMgMC4KLSBgYXJjaGl2ZWA6IHdoZW4gYGh1bWFuYCBpcyB0cnVlLCBydW4gYHNwZWNjdHggaGFuZG9mZiBhc2sgLS1jaGFuZ2UgPGM+ICJhcmNoaXZlIDxjPj8iYCBhbmQgc3RvcC4gVGhpcyBpcyB0aGUgYXJjaGl2ZSBzdG9wLiBgbmV4dGAgcmV0dXJucyBgYXNrYCB1bnRpbCB0aGUgdXNlciByZXNvbHZlcyB0aGUgcXVlc3Rpb24uIFdoZW4gYGh1bWFuYCBpcyBmYWxzZSwgdGhlIHVzZXIgYXBwcm92ZWQgb3IgYFtsb29wXSBhcmNoaXZlYCBpcyBgYXV0b2AuIFRoZW4gcnVuIGVhY2ggc3RlcCB1bmRlciBgb3BlcmF0aW9ucy5hcmNoaXZlLmd1aWRhbmNlYCBpbiBgb3BlbnNwZWMvY29uZmlnLnlhbWxgLiBUaGVuIHJ1biB0aGUgY29tbWFuZCBpbiB0aGUgYGNvbW1hbmRgIGZpZWxkLiBUaGVuIHJ1biBgb3BlbnNwZWMgdmFsaWRhdGUgLS1hbGwgLS1zdHJpY3RgLCBgc3BlY2N0eCBjaGVjayAtLXN0cmljdGAsIGFuZCBgc3BlY2N0eCBoYW5kb2ZmIHdyaXRlYC4KLSBgYXNrYDogcHJpbnQgYHJlYXNvbmAuIEl0IGlzIHRoZSBvcGVuIHF1ZXN0aW9uLiBTdG9wLiBUaGUgdXNlciBhbnN3ZXJzIHdpdGggYHNwZWNjdHggaGFuZG9mZiByZXNvbHZlIDxuPiAiPGFuc3dlcj4iYC4KLSBgc3RvcGA6IHByaW50IGByZWFzb25gLiBTdG9wLgoKIyMgUnVsZXMKCi0gVGhpcyBza2lsbCBvdmVycmlkZXMgdHdvIHN0ZXBzIG9mIHRoZSB1cHN0cmVhbSBgb3BlbnNwZWMtcHJvcG9zZWAgc2tpbGwuIEl0IHJlYWRzIHNwZWNzIHdpdGggYHNwZWNjdHggYnVuZGxlYCBvciBgc3BlY2N0eCBxdWVyeWAsIG5vdCBgb3BlbnNwZWMgc2hvd2AuIEl0IG5ldmVyIHJ1bnMgdGhlIGNsb3NpbmcgYC9vcHN4OmFwcGx5YC4KLSBOZXZlciB0aWNrIGEgY2hlY2tib3ggYnkgaGFuZC4gYHNwZWNjdHggdGFzayBkb25lYCBpcyB0aGUgb25seSB3YXkgYSB0YXNrIGNsb3Nlcy4KLSBOZXZlciB1c2UgYC0tbWFudWFsYCBvbiBhIHRhc2sgd2l0aCBhIFZlcmlmeSBjb21tYW5kLgotIE5ldmVyIGNhbGwgYC9vcHN4OmFwcGx5YC4gVGhpcyBza2lsbCByZXBsYWNlcyBpdC4KLSBUbyB3cml0ZSBhIE1PRElGSUVEIGJsb2NrLCBydW4gYHNwZWNjdHggYnVuZGxlIDxSRVE+IC0tYmxvY2tgLiBJdCBwcmludHMgdGhlIGJsb2NrIGFzIGl0IHNpdHMgaW4gdGhlIHNwZWMgZmlsZS4gQSBNT0RJRklFRCBibG9jayBrZWVwcyBldmVyeSBzY2VuYXJpbyB0aXRsZSB1bmNoYW5nZWQuCi0gYGdhdGVgIGNvdW50cyB0aGUgUmVmcyBsaW5lIGluIHRoZSA1MDAgY2hhcmFjdGVycyBvZiBhIHJlcXVpcmVtZW50LgotIFRoZSBDSEFOR0VMT0cgZW50cnkgZ29lcyB1bmRlciBgIyMgVW5yZWxlYXNlZGAsIG5ldmVyIHVuZGVyIGEgcmVsZWFzZWQgdmVyc2lvbi4KLSBBZnRlciBhbiBlZGl0IHVuZGVyIGBza2lsbHMvYCwgcnVuIGBidW4gcnVuIGJ1aWxkICYmIG5vZGUgZGlzdC9jbGkuanMgaW5pdCAtLXNraWxscyAtLWZvcmNlYCB0byByZWZyZXNoIHRoZSBjb3BpZXMuCi0gTmV2ZXIgcmVhZCBgb3BlbnNwZWMvc3BlY3MvYCBvciBgb3BlbnNwZWMvY2hhbmdlcy8qL3NwZWNzL2AgZGlyZWN0bHkuIFVzZSB0aGUgYnVuZGxlIGZyb20gYHRhc2sgc3RhcnRgIG9yIGBzcGVjY3R4IGJ1bmRsZSA8aWQ+YC4KLSBTdG9wIG9uIGFueSBgYWN0aW9uYCBub3QgaW4gdGhlIGxpc3QgYWJvdmUuIFByaW50IHRoZSBvYmplY3QgYW5kIGFzayB0aGUgdXNlci4KLSBLZWVwIG5vIHN0YXRlIGluIHlvdXIgY29udGV4dC4gQSBuZXcgc2Vzc2lvbiBzdGFydHMgdGhlIHNhbWUgbG9vcCBhZ2FpbiB3aXRoIHN0ZXAgMS4K",
 };

package/dist/check/check.js

@@ -190,6 +190,29 @@ export function check(root, cfg, data, strict) {
             if (e.kind === "scn" && !named.has(e.id))
                 findings.push([e.file, e.line, "scenario-untested", e.id]);
         }
+        // REQ-CHK-008 a delta scenario needs a test once its change has no open task (038/D1, D2)
+        const tasksOf = new Map();
+        for (const e of entries) {
+            if (e.kind !== "task" || e.change === "main" || e.file.includes("/archive/"))
+                continue;
+            const t = tasksOf.get(e.change) ?? { open: 0, all: 0 };
+            t.all++;
+            if (e.status !== "done")
+                t.open++;
+            tasksOf.set(e.change, t);
+        }
+        for (const e of entries) {
+            if ((e.kind !== "scn" && e.kind !== "req") || e.change === "main" || (e.status !== "active" && e.status !== "modified"))
+                continue;
+            const t = tasksOf.get(e.change);
+            if (!t || t.open > 0 || pending.has(e.id))
+                continue;
+            // REQ-CHK-009 a delta requirement needs a Covers tag on the same terms (039/D2)
+            if (e.kind === "req" && !covered.has(e.id))
+                findings.push([e.file, e.line, "uncovered", e.id]);
+            if (e.kind === "scn" && !named.has(e.id))
+                findings.push([e.file, e.line, "scenario-untested", e.id]);
+        }
         findings.push(...evidenceFindings(root, entries, listEvidence(root)));
     }
     const uniq = new Map();

package/dist/check/hints.js

@@ -9,13 +9,17 @@ export const RULES = {
     "duplicate-id": { level: "hard", hint: "Give one of the two entries a new ID from specctx id new." },
     "duplicate-change-key": { level: "hard", hint: "Rename one change folder, so that each key names one change." },
     "reused-id": { level: "hard", hint: "The ID is retired. Get a new ID from specctx id new." },
-    "dangling-ref": { level: "hard", hint: "Fix the ID or remove the link. No entry has this ID." },
+    // REQ-CHK-007 the hint names the string literal cause and the fix (033/D3)
+    "dangling-ref": {
+        level: "hard",
+        hint: "No entry has this ID. Fix the ID or remove the link. A tag inside a string literal or fixture text also reads as a link. Build that text at run time, or move the file under a path in [scan] ignore.",
+    },
     "unknown-task-req": { level: "hard", hint: "The task cites an ID that the index does not hold. Fix the ID on the task line." },
     "req-without-scn": { level: "hard", hint: "Add a scenario under the requirement." },
     "code-tag-no-canonical": { level: "hard", hint: "The tag names an archived requirement. Tag the current requirement." },
     "unknown-cap": { level: "hard", hint: "Add the code to caps under [ids] in spec-ctx.toml." },
     uncovered: { level: "hard", hint: "Add a test with a Covers tag for the requirement." },
-    "scenario-untested": { level: "hard", hint: "Name the scenario ID in a test." },
+    "scenario-untested": { level: "hard", hint: "Name the scenario ID in a test with a // Covers: <SCN> tag." },
     "done-without-evidence": { level: "hard", hint: "Run specctx task done. It runs the Verify command and writes the evidence." },
     // REQ-CHK-006 the hint names the why argument of task reopen (031/D8)
     "stale-evidence": { level: "hard", hint: "Run specctx task reopen <task> <why>, then specctx task done <task>." },

package/dist/cli/args.js

@@ -7,10 +7,10 @@ export const COMMAND_FLAGS = {
     next: { change: "string" },
     query: { kind: "string", change: "string", all: "bool", limit: "int" },
     related: { depth: "int", all: "bool" },
-    bundle: { budget: "int", depth: "int", all: "bool" },
+    bundle: { budget: "int", depth: "int", all: "bool", block: "bool" },
     check: { strict: "bool" },
     stats: { change: "string", write: "bool" },
-    gate: { strict: "bool", markdown: "string" },
+    gate: { strict: "bool", markdown: "string", rerun: "bool", base: "string" },
     "id new": { for: "string", count: "int" },
     "id retire": {},
     "task next": { change: "string" },
@@ -19,7 +19,7 @@ export const COMMAND_FLAGS = {
     "task done": { manual: "string" },
     "task reopen": {},
     "handoff write": {},
-    "handoff ask": { change: "string" },
+    "handoff ask": { change: "string", plan: "bool" },
     "handoff resolve": {},
     adopt: { "dry-run": "bool" },
     "baseline write": {},

package/dist/cli/commands.js

@@ -73,16 +73,8 @@ export async function run(p, io) {
         return init(p, io);
     const root = findRoot(io.cwd, f.root);
     requireOpenSpec(root);
-    const { loadConfig, ConfigError } = await import("../config.js");
-    let cfg;
-    try {
-        cfg = loadConfig(root);
-    }
-    catch (e) {
-        if (e instanceof ConfigError)
-            throw new UsageExit(e.message);
-        throw e;
-    }
+    const { loadConfigOrExit } = await import("./config.js");
+    const cfg = loadConfigOrExit(root);
     const { dumps } = await import("../util/json.js");
     const print = (v) => io.out(dumps(v) + "\n");
     if (cmd === "build") {
@@ -147,6 +139,13 @@ export async function run(p, io) {
     if (cmd === "gate") {
         if (p.positional.length)
             throw new UsageExit("gate takes no arguments");
+        // REQ-CLI-009 the rerun mode runs only the rerun step
+        if (f.base !== undefined && !f.rerun)
+            throw new UsageExit("--base needs --rerun");
+        if (f.rerun) {
+            const { runRerun } = await import("./gate.js");
+            return runRerun(root, cfg, { strict: !!f.strict, base: f.base || cfg.gate.base, json }, io);
+        }
         const { runGate } = await import("./gate.js");
         const strict = !!f.strict;
         return runGate(root, {
@@ -262,6 +261,21 @@ export async function run(p, io) {
                 io.err(`unknown id(s): ${unknown.join(", ")}\n`);
                 return 2;
             }
+            // REQ-QRY-004 --block prints the requirement blocks verbatim and nothing else (034/D2)
+            if (f.block) {
+                const notReq = p.positional.filter((i) => ids.get(i).kind !== "req");
+                if (notReq.length) {
+                    io.err(`not a requirement: ${notReq.join(", ")}\n`);
+                    return 2;
+                }
+                const { reqBlocks } = await import("../graph/bundle.js");
+                const text = reqBlocks(root, p.positional.map((i) => ids.get(i)));
+                if (json)
+                    print({ text, omitted: [] });
+                else
+                    io.out(text);
+                return 0;
+            }
             const b = bundle(root, entries, p.positional, f.budget ?? cfg.bundle.budget, f.depth ?? cfg.bundle.depth, all);
             if (json)
                 print(b);

package/dist/cli/config.js

@@ -0,0 +1,14 @@
+// REQ-DIST-009 the one function that every command uses to read spec-ctx.toml (033/D4).
+import { ConfigError, loadConfig } from "../config.js";
+import { UsageExit } from "./errors.js";
+/** Read the config. A config error becomes a usage error: one line on stderr and exit 2, never a stack. */
+export function loadConfigOrExit(root) {
+    try {
+        return loadConfig(root);
+    }
+    catch (e) {
+        if (e instanceof ConfigError)
+            throw new UsageExit(e.message);
+        throw e;
+    }
+}

package/dist/cli/gate.js

@@ -1,7 +1,7 @@
-// REQ-CLI-004 specctx gate: check, the baseline against the merge base, both linters, openspec validate, spec length. Stops at the first failure.
+// REQ-LOOP-011 REQ-STAT-005 REQ-CLI-009 REQ-CLI-004 specctx gate: check, the baseline against the merge base, both linters, openspec validate, spec length. Stops at the first failure.
 import { spawnSync } from "node:child_process";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve, sep } from "node:path";
 import { anyMatch, globRe } from "../util/glob.js";
 import { cmpStr } from "../util/pystr.js";
 const SKIP = new Set(["node_modules", ".git", ".ctx", "dist", "build"]);
@@ -45,7 +45,7 @@ export const GATE_STEPS = ["check", "baseline", "lint tells", "lint ste", "valid
 /** REQ-STAT-005 one JSON line per gate run, after the last step or at the first failure. */
 export function appendGateLog(root, line) {
     mkdirSync(join(root, ".ctx"), { recursive: true });
-    const sorted = { at: line.at, duration_s: line.duration_s, failed_step: line.failed_step, ok: line.ok, steps: line.steps };
+    const sorted = { at: line.at, duration_s: line.duration_s, failed_step: line.failed_step, ok: line.ok, steps: line.steps, strict: line.strict };
     appendFileSync(join(root, GATE_LOG), JSON.stringify(sorted) + "\n");
 }
 export async function runGate(root, o, io) {
@@ -53,7 +53,7 @@ export async function runGate(root, o, io) {
     const ran = [];
     const r = await gateSteps(root, o, io, ran);
     const { isoNow } = await import("../util/time.js");
-    appendGateLog(root, { at: isoNow(), ok: r === null, failed_step: r, duration_s: Math.round((Date.now() - start) / 1000), steps: [...ran] });
+    appendGateLog(root, { at: isoNow(), ok: r === null, failed_step: r, duration_s: Math.round((Date.now() - start) / 1000), steps: [...ran], strict: o.strict });
     return r === null ? 0 : 1;
 }
 /** The gate steps. Returns null when every step passed, else the name of the failed step. */
@@ -203,3 +203,132 @@ export function longRequirements(root) {
     }
     return out;
 }
+/** REQ-CLI-009 the recursion guard: a rerun that a rerun started stops at once. */
+export const RERUN_GUARD = "SPECCTX_RERUN";
+/**
+ * REQ-CLI-009 REQ-VER-005 REQ-VER-006 REQ-VER-007 `gate --rerun`. It runs the Verify command of each task that the range
+ * closed, one group at a time, and compares the exit code with the evidence. It writes no evidence.
+ */
+export async function runRerun(root, cfg, o, io) {
+    if (process.env[RERUN_GUARD]) {
+        io.out(o.json ? JSON.stringify({ ok: true, skipped: `${RERUN_GUARD} is set` }) + "\n" : `rerun: skipped, ${RERUN_GUARD} is set\n`);
+        return 0;
+    }
+    const start = Date.now();
+    const { dumps } = await import("../util/json.js");
+    const { loadIndex } = await import("../index/build.js");
+    const { scanner } = await import("../index/scan.js");
+    const { closedTasks, compare, groupRuns, judge, formatMismatch } = await import("../gate/rerun.js");
+    const { isWeakVerify, parseVerify } = await import("../verify/parse.js");
+    const { evidenceRel } = await import("../tasks/tasks.js");
+    const { runVerify } = await import("../verify/run.js");
+    const { isoNow } = await import("../util/time.js");
+    const finish = (ok) => {
+        appendGateLog(root, { at: isoNow(), ok, failed_step: ok ? null : "rerun", duration_s: Math.round((Date.now() - start) / 1000), steps: ["rerun"], strict: o.strict });
+        return ok ? 0 : 1;
+    };
+    // REQ-VER-013 a zero base passes and a base that this clone lacks fails, before any merge base (042/D3)
+    const { baseProblem } = await import("../gate/rerun.js");
+    const bp = baseProblem(root, o.base);
+    if (bp) {
+        io.out(o.json ? dumps({ base: o.base, ...(bp.ok ? { warning: bp.line } : { error: bp.line }), merge_base: null, ok: bp.ok, tasks: [] }) + "\n" : bp.line + "\n");
+        return finish(bp.ok);
+    }
+    const { data } = loadIndex(root, cfg);
+    const closed = closedTasks(root, o.base, data.entries, scanner(root, cfg).taskRe);
+    if (!closed.ok) {
+        io.out(o.json ? dumps({ base: o.base, error: closed.line, merge_base: null, ok: false, tasks: [] }) + "\n" : closed.line + "\n");
+        return finish(false);
+    }
+    // REQ-VER-010 a merge base at HEAD compares nothing. Say so and pass (041/D4).
+    const { headSha, HEAD_BASE_LINE } = await import("../gate/rerun.js");
+    if (closed.mergeBase === headSha(root)) {
+        io.out(o.json ? dumps({ base: o.base, merge_base: closed.mergeBase, ok: true, tasks: [], warning: HEAD_BASE_LINE }) + "\n" : HEAD_BASE_LINE + "\n");
+        return finish(true);
+    }
+    const lines = [];
+    const pending = [];
+    for (const e of closed.tasks) {
+        const evPath = evidenceRel(e);
+        let ev = null;
+        try {
+            const j = JSON.parse(readFileSync(join(root, evPath), "utf8"));
+            ev = { kind: j.kind, command: j.verify?.command ?? null, exit: j.verify?.exit ?? null, ...(j.cwd !== undefined ? { cwd: j.cwd } : {}) };
+        }
+        catch {
+            ev = null;
+        }
+        const tl = readFileSync(join(root, e.file), "utf8").split(/\r?\n/)[e.line - 1] ?? "";
+        const spec = parseVerify(tl);
+        const v = compare({ command: spec.command, ...(spec.cwd !== undefined ? { cwd: spec.cwd } : {}) }, ev, o.strict, isWeakVerify);
+        const base = { id: e.id, status: "", kind: "ok", file: e.file, line: e.line, evidence: evPath };
+        if (v.act === "warn")
+            lines.push({ ...base, status: "warn manual", kind: "warn" });
+        else if (v.act === "fail")
+            lines.push({ ...base, status: v.kind, kind: "fail", ...(v.detail ? { detail: v.detail } : {}) });
+        else {
+            const l = { ...base, status: "ok" };
+            lines.push(l);
+            pending.push({ id: e.id, command: v.command, cwd: v.cwd, expected: v.expected, line: l });
+        }
+    }
+    // REQ-VER-007 one run per frozen command and cwd. Groups run one at a time.
+    const env = { ...process.env, CI: "1", [RERUN_GUARD]: "1" };
+    for (const g of groupRuns(pending)) {
+        const dir = resolve(root, g.cwd);
+        let out;
+        if (dir !== resolve(root) && !dir.startsWith(resolve(root) + sep))
+            out = { exit: null, timedOut: false, output: `cwd ${g.cwd} is outside the project root\n` };
+        // REQ-VER-009 a missing cwd and a spawn error are a mismatch of the group, not a crash (041/D3)
+        else if (!existsSync(dir))
+            out = { exit: null, timedOut: false, output: `cwd does not exist: ${g.cwd}\n` };
+        else {
+            try {
+                const r = await runVerify(g.command, dir, cfg.verify.timeout_s, env);
+                out = { exit: r.exit, timedOut: r.timedOut, output: r.output };
+            }
+            catch (e) {
+                out = { exit: null, timedOut: false, output: `spawn failed: ${e instanceof Error ? e.message : String(e)}\n` };
+            }
+        }
+        for (const m of g.members) {
+            if (judge(m.expected, out) === "ok")
+                continue;
+            m.line.status = "mismatch";
+            m.line.kind = "fail";
+            m.line.expected_exit = m.expected;
+            m.line.actual_exit = out.exit;
+            m.line.timed_out = out.timedOut;
+            if (out.exit === null && !out.timedOut)
+                m.line.detail = out.output.trim().split("\n")[0] ?? "";
+            m.line.report = formatMismatch({ id: m.id, file: m.line.file, line: m.line.line, evidence: m.line.evidence, expected: m.expected, outcome: out, command: g.command, cwd: g.cwd, timeoutS: cfg.verify.timeout_s });
+        }
+    }
+    const failed = lines.filter((l) => l.kind === "fail");
+    const ok = failed.length === 0;
+    if (o.json) {
+        io.out(dumps({
+            base: o.base,
+            merge_base: closed.mergeBase,
+            ok,
+            tasks: lines.map((l) => {
+                const { report, ...rest } = l;
+                void report;
+                return rest;
+            }),
+        }) + "\n");
+    }
+    else {
+        if (!lines.length)
+            io.out("rerun: no closed tasks\n");
+        for (const l of lines) {
+            if (l.report)
+                io.out(l.report);
+            else
+                io.out(`${l.id}: ${l.status}${l.detail ? ` (${l.detail})` : ""}\n`);
+        }
+        if (lines.length)
+            io.out(`rerun: ${lines.length} task(s), ${failed.length} failure(s)\n`);
+    }
+    return finish(ok);
+}

package/dist/cli/help.js

@@ -48,8 +48,9 @@ export const TABLE = [
             ["--budget <n>", "Stop at n characters. The default is 8000."],
             ["--depth <n>", "Follow links n steps. The default is 1."],
             ["--all", "Show all copies of an ID."],
+            ["--block", "Print only the requirement block, as it sits in the spec file. Each ID must be a requirement."],
         ],
-        exit: [OK, ["2", "A usage error or an unknown ID."], INTERNAL], example: "specctx bundle REQ-IDX-001 --budget 3000",
+        exit: [OK, ["2", "A usage error, an unknown ID, or an ID that is not a requirement."], INTERNAL], example: "specctx bundle REQ-IDX-001 --budget 3000",
     },
     {
         name: "check", group: "Read", args: "", summary: "Find ID and link errors.",
@@ -62,6 +63,8 @@ export const TABLE = [
         flags: [
             ["--strict", "Run `check` and `openspec validate` in strict mode."],
             ["--markdown <globs>", "Lint these markdown globs instead of [gate] markdown. Separate them with spaces."],
+            ["--rerun", "Run only the rerun step. Run the command of each task that the range closed. Compare its exit code with the evidence."],
+            ["--base <ref>", "With --rerun, take the merge base with this ref. The default is [gate] base."],
         ],
         exit: [["0", "Every step passed."], ["1", "A step failed."], USAGE, INTERNAL], example: "specctx gate --strict",
     },
@@ -114,8 +117,11 @@ export const TABLE = [
     { name: "handoff write", group: "Write", args: "", summary: "Write .ctx/handoff.md from the index and the evidence.", flags: [], exit: PLAIN, example: "specctx handoff write" },
     {
         name: "handoff ask", group: "Write", args: "<question>", summary: "Add an open question to the handoff.",
-        flags: [["--change <name>", "Give the question to this change, not to the current task. The key or the full folder name works."]],
-        exit: PLAIN, example: "specctx handoff ask --change 008 \"plan ready for 008-tasks. Approve to start the tasks?\"",
+        flags: [
+            ["--change <name>", "Give the question to this change, not to the current task. The key or the full folder name works."],
+            ["--plan", "Mark the question as the plan approval. Only this mark ends the plan stop. It needs --change."],
+        ],
+        exit: PLAIN, example: "specctx handoff ask --change 008 --plan \"plan ready for 008-tasks. Approve to start the tasks?\"",
     },
     {
         name: "handoff resolve", group: "Write", args: "<n> <answer>", summary: "Move open question n to the resolved list.",

package/dist/cli/workflow.js

@@ -240,7 +240,10 @@ export async function runWorkflow(c) {
         }
         case "handoff ask": {
             const { ask } = await import("../handoff/handoff.js");
-            const h = ask(c.root, entries, c.p.positional.join(" "), c.p.flags.change);
+            const plan = c.p.flags.plan === true;
+            if (plan && c.p.flags.change === undefined)
+                throw new UsageExit("--plan needs --change");
+            const h = ask(c.root, entries, c.p.positional.join(" "), c.p.flags.change, plan);
             if (c.json)
                 print(c, { open_questions: h.open_questions });
             else

package/dist/config.js

@@ -43,7 +43,7 @@ export function loadConfig(root) {
         raw = parse(readFileSync(p, "utf8"));
     }
     catch (e) {
-        throw new ConfigError(`${CONFIG_FILE}: the file is not valid TOML. ${e.message.split("\n")[0]}`);
+        throw new ConfigError(`${p}: the file is not valid TOML. ${e.message.split("\n")[0]}`);
     }
     const sec = (name) => {
         const v = raw[name];

package/dist/gate/rerun.js

@@ -0,0 +1,169 @@
+// REQ-VER-013 REQ-VER-005 REQ-VER-006 REQ-VER-007 the rerun step: the tasks a range closed, the compare, the groups (036/D1).
+import { spawnSync } from "node:child_process";
+import { changeKey, changeOf } from "../index/scan.js";
+import { cmpStr } from "../util/pystr.js";
+function git(root, args) {
+    const r = spawnSync("git", args, { cwd: root, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    return { ok: r.status === 0, out: (r.stdout ?? "").trim() };
+}
+/** REQ-VER-005 the one line of a failed merge base. A shallow clone gets a second sentence. */
+export function noMergeBaseLine(root, base) {
+    const shallow = git(root, ["rev-parse", "--is-shallow-repository"]);
+    const tail = shallow.ok && shallow.out === "true" ? ". This clone is shallow" : "";
+    return `rerun: no merge base with ${base}, fetch full history (fetch-depth: 0)${tail}`;
+}
+/** REQ-VER-005 the task ID order: the change key, then the group and the number as integers. */
+export function cmpTaskId(a, b) {
+    const [ka, na = ""] = a.split("/");
+    const [kb, nb = ""] = b.split("/");
+    const k = cmpStr(ka, kb);
+    if (k !== 0)
+        return k;
+    const pa = na.split(".").map(Number);
+    const pb = nb.split(".").map(Number);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const d = (pa[i] ?? -1) - (pb[i] ?? -1);
+        if (d !== 0)
+            return d < 0 ? -1 : 1;
+    }
+    return 0;
+}
+/** REQ-VER-005 the task lines of one tasks.md text, with the key that the index would give them. */
+export function parseTasksFile(path, text, taskRe) {
+    const key = changeKey(changeOf(path));
+    const archived = path.includes("/archive/");
+    const out = [];
+    for (const line of text.split(/\r?\n/)) {
+        const m = taskRe.exec(line);
+        if (m)
+            out.push({ id: `${key}/${m[2]}`, done: m[1].toLowerCase() === "x", archived });
+    }
+    return out;
+}
+/** REQ-VER-005 one state per ID. An active copy wins over an archived copy, as findTask does. */
+export function mergeStates(states) {
+    const out = new Map();
+    for (const s of states) {
+        const had = out.get(s.id);
+        if (!had || (had.archived && !s.archived))
+            out.set(s.id, s);
+    }
+    return out;
+}
+/** REQ-VER-005 the state of every task in the tasks.md files at a commit. */
+export function tasksAt(root, sha, taskRe) {
+    const ls = git(root, ["ls-tree", "-z", "-r", "--name-only", sha, "--", "openspec/changes"]);
+    const all = [];
+    if (!ls.ok)
+        return new Map();
+    for (const p of ls.out.split("\0").filter((x) => x.endsWith("/tasks.md")).sort(cmpStr)) {
+        const show = spawnSync("git", ["show", `${sha}:${p}`], { cwd: root, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+        if (show.status === 0)
+            all.push(...parseTasksFile(p, show.stdout, taskRe));
+    }
+    return mergeStates(all);
+}
+/** REQ-VER-005 the index entries of tasks, one per ID. The active copy wins. */
+export function headStates(entries) {
+    const out = new Map();
+    for (const e of entries) {
+        if (e.kind !== "task")
+            continue;
+        const archived = e.file.includes("/archive/");
+        const had = out.get(e.id);
+        if (!had || (had.state.archived && !archived))
+            out.set(e.id, { state: { id: e.id, done: e.status === "done", archived }, entry: e });
+    }
+    return out;
+}
+/** REQ-VER-010 the commit that HEAD names, or "" when git fails. */
+export function headSha(root) {
+    const h = git(root, ["rev-parse", "HEAD"]);
+    return h.ok ? h.out : "";
+}
+/** REQ-VER-010 the line for a merge base equal to HEAD. */
+export const HEAD_BASE_LINE = "rerun: merge base is HEAD, nothing to compare. On push, pass --base <the commit before the push>";
+/** REQ-VER-013 the line for a base of forty zeros, the `before` of a push that creates a branch. */
+export const ZERO_BASE_LINE = "rerun: base is the zero commit (a new branch), nothing to compare";
+/** REQ-VER-013 a base that ends the rerun before the merge base: the zero commit passes, an unknown commit fails. */
+export function baseProblem(root, base) {
+    if (/^0{40}$/.test(base))
+        return { ok: true, line: ZERO_BASE_LINE };
+    const known = !base.startsWith("-") && git(root, ["rev-parse", "--verify", "--quiet", `${base}^{commit}`]).ok;
+    if (known)
+        return null;
+    return { ok: false, line: `rerun: base ${base} is not in this clone. Fetch it or use fetch-depth: 0` };
+}
+/**
+ * REQ-VER-005 the tasks that are done at HEAD and open or absent at the merge base, in ID order.
+ * `entries` is the live index. `taskRe` is the task regex of the scanner.
+ */
+export function closedTasks(root, base, entries, taskRe) {
+    const mb = git(root, ["merge-base", "HEAD", base]);
+    if (!mb.ok || !mb.out)
+        return { ok: false, line: noMergeBaseLine(root, base) };
+    const before = tasksAt(root, mb.out, taskRe);
+    const tasks = [];
+    for (const [id, { state, entry }] of headStates(entries)) {
+        if (state.done && !before.get(id)?.done)
+            tasks.push(entry);
+    }
+    tasks.sort((a, b) => cmpTaskId(a.id, b.id));
+    return { ok: true, mergeBase: mb.out, tasks };
+}
+/** REQ-VER-006 compare one closed task with its evidence, in the fixed order of 036/D4. */
+export function compare(verify, evidence, strict, weak) {
+    if (evidence !== null && evidence.kind === "manual")
+        return strict ? { act: "fail", kind: "manual" } : { act: "warn", why: "manual" };
+    if (evidence === null)
+        return { act: "fail", kind: "no-evidence" };
+    const cwd = evidence.cwd ?? ".";
+    if (verify.command !== evidence.command || (verify.cwd ?? ".") !== cwd) {
+        return { act: "fail", kind: "verify-drift", detail: `tasks.md has ${verify.command ?? "no command"}${verify.cwd ? ` (cwd ${verify.cwd})` : ""}, evidence has ${evidence.command ?? "no command"}${evidence.cwd ? ` (cwd ${evidence.cwd})` : ""}` };
+    }
+    if (evidence.command === null)
+        return { act: "fail", kind: "no-evidence" };
+    if (strict && weak(evidence.command))
+        return { act: "fail", kind: "weak-verify" };
+    return { act: "run", command: evidence.command, cwd, expected: evidence.exit };
+}
+/** REQ-VER-007 the key that makes two runs the same run. */
+export const runKey = (v) => `${v.cwd}\u0000${v.command}`;
+/** REQ-VER-007 one group per frozen command and cwd, in the ID order of the first task. */
+export function groupRuns(items) {
+    const sorted = [...items].sort((a, b) => cmpTaskId(a.id, b.id));
+    const groups = new Map();
+    for (const it of sorted) {
+        const key = runKey(it);
+        const g = groups.get(key);
+        if (g)
+            g.members.push(it);
+        else
+            groups.set(key, { key, command: it.command, cwd: it.cwd, members: [it] });
+    }
+    return [...groups.values()];
+}
+/** REQ-VER-006 ok when the exit code equals the evidence. A timeout or a different code is a mismatch. */
+export function judge(expected, o) {
+    return !o.timedOut && o.exit !== null && o.exit === expected ? "ok" : "mismatch";
+}
+const shq = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+/** REQ-VER-007 the line that runs the frozen command on a developer machine as the rerun runs it. */
+export function reproduceLine(command, cwd) {
+    return `reproduce: cd ${shq(cwd)} && env CI=1 SPECCTX_RERUN=1 sh -c ${shq(command)}`;
+}
+/** REQ-VER-007 the report of a mismatch. The output tail is the last 20 lines. */
+export function formatMismatch(m) {
+    const tailLines = m.outcome.output.replace(/\n$/, "") === "" ? [] : m.outcome.output.replace(/\n$/, "").split("\n").slice(-20);
+    const actual = m.outcome.timedOut ? `timed out after ${m.timeoutS}s` : `exit ${m.outcome.exit}`;
+    return [
+        `${m.id}: mismatch`,
+        `  at ${m.file}:${m.line}`,
+        `  evidence ${m.evidence}`,
+        `  expected exit ${m.expected}`,
+        `  actual ${actual}`,
+        "  output (last 20 lines):",
+        ...tailLines.map((l) => `    ${l}`),
+        `  ${reproduceLine(m.command, m.cwd)}`,
+    ].join("\n") + "\n";
+}

package/dist/graph/bundle.js

@@ -44,6 +44,11 @@ function rstrip(s) {
 export function provenance(e, reason) {
     return `-- ${e.id} | ${e.file}:${e.line} | ${e.status} | ${reason}\n`;
 }
+/** REQ-QRY-004 the canonical blocks of requirements, joined by one blank line, with no provenance line. */
+export function reqBlocks(root, reqs) {
+    const files = new Lines(root);
+    return reqs.map((e) => blockText(e, files)).join("\n");
+}
 export function bundle(root, entries, wanted, budget, depth, all = false) {
     const ids = canon(entries);
     const blocks = [];

package/dist/handoff/handoff.js

@@ -149,7 +149,7 @@ function refresh(root, entries) {
  * REQ-HND-002 append an open question to questions.json and render the handoff again (022/D6).
  * REQ-LOOP-005 with a change, the question carries the active change folder, so next blocks the change (029/D1).
  */
-export function ask(root, entries, text, change) {
+export function ask(root, entries, text, change, plan = false) {
     let task = currentTask(root);
     let stage;
     if (change !== undefined) {
@@ -157,17 +157,19 @@ export function ask(root, entries, text, change) {
         if (folder === undefined)
             throw new UsageExit(`no active change ${change}`);
         task = folder;
-        stage = stageOf(entries, folder);
+        stage = stageOf(entries, folder, plan);
     }
     const q = addQuestion(root, task, text, stage);
     const h = refresh(root, entries);
     h.asked = q.n;
     return h;
 }
-/** REQ-LOOP-007 archive when the change has a task and every task is [x], plan otherwise. The text plays no part (031/D1). */
-export function stageOf(entries, folder) {
+/** REQ-LOOP-007 archive when the change has a task and every task is [x]. Else plan with the flag and design without it. The text plays no part (041/D2). */
+export function stageOf(entries, folder, plan = false) {
     const tasks = entries.filter((e) => e.kind === "task" && e.change === folder && !e.file.includes("/archive/"));
-    return tasks.length > 0 && tasks.every((t) => t.status === "done") ? "archive" : "plan";
+    if (tasks.length > 0 && tasks.every((t) => t.status === "done"))
+        return "archive";
+    return plan ? "plan" : "design";
 }
 /** REQ-HND-002 resolve question n in questions.json and render the handoff again (022/D6). */
 export function resolve(root, entries, n, answer) {

package/dist/ids/ids.js

@@ -39,6 +39,10 @@ export function newIds(root, cfg, entries, o) {
     const checkCap = (cap) => {
         if (!cap)
             throw new UsageExit(`id new ${kind} needs a capability code`);
+        // REQ-IDS-005 a code with a number is a scenario number typed in the code slot (038/D4)
+        const num = /^([A-Z]{2,6})-\d+$/.exec(cap);
+        if (num)
+            throw new UsageExit(`the capability code ${cap} holds a number. ${kind === "SCN" ? `Use id new SCN ${num[1]} --for REQ-${num[1]}-<NNN>.` : `Use id new ${kind} ${num[1]}.`}`);
         if (!/^[A-Z]{2,6}$/.test(cap))
             throw new UsageExit(`the capability code ${cap} must be 2 to 6 upper case letters`);
         // REQ-IDS-001 an empty caps list accepts any code. A non-empty list must hold the code.

package/dist/index/scan.js

@@ -16,7 +16,9 @@ const ADR_HDR = new RegExp(`^# (ADR-\\d{3})${S}+(.*)$`, "s");
 const REFS_RE = new RegExp(`^Refs:${S}*(.+)$`, "s");
 const TASK_REQ = new RegExp(`\\[(REQ-[A-Z]{2,6}-\\d{3}(?:${S}*,${S}*REQ-[A-Z]{2,6}-\\d{3})*)\\]`, "g");
 const CODE_TAG = new RegExp(`(?://|#|/\\*|\\*)${S}*(REQ-[A-Z]{2,6}-\\d{3})`);
-const COVER_TAG = new RegExp(`Covers:${S}*(REQ-[A-Z]{2,6}-\\d{3}(?:${S}*,${S}*REQ-[A-Z]{2,6}-\\d{3})*)`);
+// REQ-IDX-007 the rest of the line after Covers:, and each REQ ID in it with word boundaries (042/D4)
+const COVER_TAG = /Covers:(.*)$/s;
+const REQ_ID = /\bREQ-[A-Z]{2,6}-\d{3}\b/g;
 const SENTENCE_END = new RegExp(`(?<=[.!?])${S}`);
 const COMMA = new RegExp(`${S}*,${S}*`);
 const SKIP_DIRS = new Set(["node_modules", ".git"]);
@@ -348,7 +350,9 @@ export function scanSource(sc, rpath, entries, scnNamed) {
         if (isTest) {
             const m = COVER_TAG.exec(line);
             if (m) {
-                for (const rid of m[1].split(COMMA)) {
+                // a Covers line never counts as a code tag, with or without a REQ ID
+                const ids = [...new Set(m[1].match(REQ_ID) ?? [])];
+                for (const rid of ids) {
                     entries.push(entry({ id: `${rpath}:${i}`, kind: "test", file: rpath, line: i, title: pyStrip(line), change: "main", status: "active", refs: [rid] }));
                 }
                 continue;

package/dist/init/init.js

@@ -4,7 +4,8 @@ import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "no
 import { dirname, join } from "node:path";
 import { ASSETS } from "../assets.generated.js";
 import { UsageExit } from "../cli/errors.js";
-import { CONFIG_FILE, DEFAULT_OPENSPEC, INIT_TEXT, loadConfig } from "../config.js";
+import { CONFIG_FILE, DEFAULT_OPENSPEC, INIT_TEXT } from "../config.js";
+import { loadConfigOrExit } from "../cli/config.js";
 export const SCHEMA = "spec-driven-ids";
 /** REQ-SCH-003 where the templates land in a project. Upstream reads no project override for the stock templates, so this is a reference path (025/D4). */
 export const TEMPLATES_DIR = `openspec/templates/${SCHEMA}`;
@@ -70,7 +71,7 @@ export function fragmentText(brackets) {
 }
 /** REQ-SCH-006 the value of [ids] brackets, false when spec-ctx.toml is absent (032/D2). */
 export function bracketsOf(root) {
-    return existsSync(join(root, CONFIG_FILE)) ? loadConfig(root).ids.brackets : false;
+    return existsSync(join(root, CONFIG_FILE)) ? loadConfigOrExit(root).ids.brackets : false;
 }
 /** Target path relative to the project root for every file that init installs, with its bytes. */
 export function plan(o, root, openspec = DEFAULT_OPENSPEC, brackets = false) {
@@ -419,7 +420,9 @@ export function runInit(root, o) {
     // REQ-CLI-007 every file present with the same bytes and no config key to add: nothing to do
     // an existing spec-ctx.toml counts as present, because the user owns it (014/D4)
     const same = files.every(([rel, data]) => existsSync(join(root, rel)) && (rel === CONFIG_FILE || readFileSync(join(root, rel)).equals(data)));
-    const ignoreDone = existsSync(join(root, GITIGNORE)) && GITIGNORE_LINES.every((l) => ignoreLines(readFileSync(join(root, GITIGNORE), "utf8")).has(l));
+    // REQ-DIST-013 a skills refresh in a project with spec-ctx.toml touches only the skill folders (038/D3)
+    const skillsOnly = o.skills && !o.schema && existsSync(join(root, CONFIG_FILE));
+    const ignoreDone = skillsOnly || existsSync(join(root, GITIGNORE)) && GITIGNORE_LINES.every((l) => ignoreLines(readFileSync(join(root, GITIGNORE), "utf8")).has(l));
     if (same && ignoreDone && !o.force) {
         const cfgPath = join(root, "openspec/config.yaml");
         const cur = existsSync(cfgPath) ? readFileSync(cfgPath, "utf8") : null;
@@ -478,11 +481,13 @@ export function runInit(root, o) {
             res.notes.push(LEGACY_SCHEMA_NOTE);
     }
     // REQ-DIST-002 the four .gitignore lines (017/D2, 022/D5)
-    const added = writeGitignore(root);
-    if (added)
-        res.written.push(`${GITIGNORE} (${added} line${added === 1 ? "" : "s"})`);
-    else
-        res.kept.push(GITIGNORE);
+    if (!skillsOnly) {
+        const added = writeGitignore(root);
+        if (added)
+            res.written.push(`${GITIGNORE} (${added} line${added === 1 ? "" : "s"})`);
+        else
+            res.kept.push(GITIGNORE);
+    }
     // REQ-DIST-002 skills under an ignored .claude/ never reach git (017/D3)
     if (o.skills && ignoresClaude(root))
         res.notes.push(CLAUDE_NOTE);

package/dist/loop/fails.js

@@ -80,22 +80,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.`;
 }
 /**
- * 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

@@ -14,7 +14,7 @@ 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 +46,25 @@ function questions(root) {
         return [];
     }
 }
-/** The last line of the gate log, or null. */
+/** REQ-LOOP-011 the last line of the gate log that is not a rerun line, or null. A line with steps exactly ["rerun"] never counts (041/D1). Only `ok` with `strict: true` passes (042/D2). */
 function lastGate(root) {
     const p = join(root, ".ctx/gate-log.jsonl");
     if (!existsSync(p))
         return null;
     const lines = readFileSync(p, "utf8").split("\n").filter((l) => l.trim());
-    const last = lines.at(-1);
-    if (!last)
-        return null;
-    try {
-        const o = JSON.parse(last);
-        return { at: typeof o.at === "string" ? o.at : "", ok: o.ok === true };
-    }
-    catch {
-        return null;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        try {
+            const o = JSON.parse(lines[i]);
+            const rerun = Array.isArray(o.steps) && o.steps.length === 1 && o.steps[0] === "rerun";
+            if (rerun)
+                continue;
+            return { at: typeof o.at === "string" ? o.at : "", ok: o.ok === true && o.strict === true };
+        }
+        catch {
+            return null;
+        }
     }
+    return null;
 }
 /** The `at` of the newest live evidence file of a change key, or "" with none. */
 function newestEvidenceAt(root, key) {
@@ -91,8 +94,13 @@ function readCurrent(root) {
 /** REQ-LOOP-001 the decision of 024/D2. A pure function of the files. It writes nothing. */
 export function decideNext(root, cfg, data, want) {
     const openspec = openspecCommand(cfg.gate.openspec);
-    const d = { action: "stop", attempt: 0, change: null, command: null, human: false, max_attempts: cfg.loop.max_attempts, reason: null, state: "unknown", task: null };
-    const done = (o) => ({ ...d, ...o });
+    const d = { action: "stop", attempt: 0, change: null, command: null, human: false, max_attempts: cfg.loop.max_attempts, reason: null, state: "unknown", task: null, tasks: [] };
+    const done = (o) => {
+        const r = { ...d, ...o };
+        if (!o.tasks)
+            r.tasks = r.task === null ? [] : [r.task];
+        return r;
+    };
     // step 0 and step 1: the change under consideration, or the plan stop with no change
     const folders = activeFolders(root);
     const folder = want === undefined ? folders[0] : folders.find((f) => matchesChange(f, want));
@@ -131,9 +139,28 @@ export function decideNext(root, cfg, data, want) {
     }
     // step 5: a hand tick without evidence gets the repair run
     const tasks = tasksOf(entries).filter(ofChange).sort((a, b) => cmpTuple([a.file, a.line], [b.file, b.line]));
+    // REQ-LOOP-009 step 4b: the plan stop. It needs no [x] task, no current task, and no question with stage plan, open or resolved. Only --plan sets that stage (034/D1, 041/D2).
+    const cur0 = readCurrent(root);
+    const started = tasks.some((t) => t.status === "done") || (cur0?.task !== undefined && cur0.task.split("/")[0] === key);
+    if (!started && !qs.some((q) => q.stage === "plan" && q.task === folder)) {
+        const text = `plan ready for ${folder}. Approve to start the tasks?`;
+        return done({ action: "ask", command: `specctx handoff ask --change ${folder} --plan "${text}"`, human: true, reason: text, state: "plan_stop" });
+    }
     const ticked = tasks.find((t) => t.status === "done" && !hasEvidence(root, t));
     if (ticked)
         return done({ action: "repair", command: `specctx task done ${ticked.id}`, state: "done_without_evidence", task: ticked.id });
+    // REQ-LOOP-008 the done tasks whose evidence went stale, earliest first (031/D4, 031/D5)
+    const stale = [];
+    for (const t of tasks) {
+        if (t.status !== "done")
+            continue;
+        const path = staleOf(root, t.id);
+        if (path !== null)
+            stale.push({ id: t.id, path });
+    }
+    // REQ-LOOP-010 a current task keeps its action. The reason names the stale tasks that wait (034/D4).
+    const waiting = stale.length ? `stale waiting: ${stale.map((x) => x.id).join(", ")}` : null;
+    const withWaiting = (r) => (waiting === null ? r : r === null ? waiting : `${r}. ${waiting}`);
     // step 6: the current task of this change
     const cur = readCurrent(root);
     const current = cur?.task && cur.task.split("/")[0] === key ? tasks.find((t) => t.id === cur.task && t.status === "open") : undefined;
@@ -141,23 +168,26 @@ 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 });
         }
         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: "work", command: `specctx task done ${current.id}`, reason, state: "task_started", task: current.id });
+    }
+    // REQ-LOOP-008 step 6b: the stale tasks repair after the current task (031/D4, 031/D5)
+    if (stale.length) {
+        // REQ-LOOP-008 one turn repairs every stale task (033/D1)
+        return done({
+            action: "repair",
+            command: stale.map((s) => `specctx task reopen ${s.id} "stale evidence: ${s.path}" && specctx task done ${s.id}`).join(" && "),
+            reason: stale.map((s) => `stale-evidence ${s.id} ${s.path}`).join(", "),
+            state: "evidence_stale",
+            task: stale[0].id,
+            tasks: stale.map((s) => s.id),
+        });
     }
     // step 7: the next open task
     const open = nextTask(root, entries, folder);
@@ -181,7 +211,8 @@ export function decideNext(root, cfg, data, want) {
 }
 /** 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/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.0";

package/package.json

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

package/skills/specctx-run/SKILL.md

@@ -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 user resolves the question.
 - `cite`: run `specctx query --change <c> --kind req`. Add the `[REQ-...]` citation and a `Verify:` code span to the task line named in `task`. Run `specctx check`. Continue.
 - `start`: run `specctx task start <t>`. Read the bundle it prints. Continue.
 - `work`: implement the task. Tag code with `// REQ-...`. Tag tests with `// Covers: REQ-...`. Then run `specctx task done <t>`.
 - `fix`: read `reason`. It holds the tail of the failed Verify output. Fix the cause. Run `specctx task done <t>` again.
 - `repair`: run 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.
+- `gate`: run `specctx gate --strict`. Fix every finding. For a `stale-evidence` finding, go back to step 1. `next` returns `repair` and its command repairs every stale task. Run the gate again until it exits 0.
 - `archive`: when `human` is true, run `specctx handoff ask --change <c> "archive <c>?"` and stop. This is the archive stop. `next` returns `ask` until the user resolves the question. When `human` is false, the user approved or `[loop] archive` is `auto`. Then run each step under `operations.archive.guidance` in `openspec/config.yaml`. Then run the command in the `command` field. Then run `openspec validate --all --strict`, `specctx check --strict`, and `specctx handoff write`.
 - `ask`: print `reason`. It is the open question. Stop. The user answers with `specctx handoff resolve <n> "<answer>"`.
 - `stop`: print `reason`. Stop.
 
 ## Rules
 
+- This skill overrides two steps of the upstream `openspec-propose` skill. It reads specs with `specctx bundle` or `specctx query`, not `openspec show`. It never runs the closing `/opsx:apply`.
 - Never tick a checkbox by hand. `specctx task done` is the only way a task closes.
 - Never use `--manual` on a task with a Verify command.
 - Never call `/opsx:apply`. This skill replaces it.
+- To write a MODIFIED block, run `specctx bundle <REQ> --block`. It prints the block as it sits in the spec file. A MODIFIED block keeps every scenario title unchanged.
+- `gate` counts the Refs line in the 500 characters of a requirement.
+- The CHANGELOG entry goes under `## Unreleased`, never under a released version.
+- After an edit under `skills/`, run `bun run build && node dist/cli.js init --skills --force` to refresh the copies.
 - Never read `openspec/specs/` or `openspec/changes/*/specs/` directly. Use the bundle from `task start` or `specctx bundle <id>`.
 - Stop on any `action` not in the list above. Print the object and ask the user.
 - Keep no state in your context. A new session starts the same loop again with step 1.