spec-ctx 0.2.0 → 0.4.0

package/README.md

@@ -229,7 +229,7 @@ ignore = []                             # globs that the scan skips
 [ids]
 caps = []                               # capability codes. Empty means any code is valid.
 task_pattern = '\d+\.\d+'               # the task number in a tasks.md checkbox
-brackets = false                        # true: adopt and id new write [REQ-UA-001]. The scan reads both forms.
+brackets = false                        # true: adopt, id new, and init --schema write [REQ-UA-001] in headers. The scan reads both forms.
 
 [ids.paths]
 UA = "user-auth"                        # capability path of each code. adopt writes the derived ones.
@@ -251,6 +251,8 @@ max_attempts = 3                        # Verify failures on one task before tas
 archive = "ask"                         # "ask" stops before archive for a human. "auto" lets the loop archive.
 ```
 
+With `brackets = true`, `init --schema` installs templates with `[REQ-<CAP>-NNN]` and `[SCN-<CAP>-NNN-N]` in the headers. The merged rules show the same form. Task citations, `Refs:` lines, and tags stay bare. After you change the value, run `specctx init --schema` again. It switches each template and rule that you did not edit. It keeps the ones you edited, unless you add `--force`.
+
 Two environment variables change the engine:
 
 | Variable | Effect |
@@ -282,20 +284,51 @@ 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.2.0` on npm, with tags `v0.2.0` and `v0` and binaries on the GitHub release.
-- Archived: 001 to 025, and 027. 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.
 
 ## Measured
 
-`specctx stats --write` measures this repository after each change. The newest file is `docs/metrics/2026-10-29.md`. Its total row:
+`specctx stats --write` measures this repository after each change. The newest file is `docs/metrics/2026-10-30.md`. Its total row:
 
 | change | context_ratio | evidence_ratio | stale_catches | cycle_time_median_s | debt |
 | --- | --- | --- | --- | --- | --- |
-| total | 0.0327 (n=76) | 0.90 (143/159) | 36 (of 81 reopens) | 98 (n=76) | 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": "LS0tCm5hbWU6IHNwZWNjdHgtcnVuCmRlc2NyaXB0aW9uOiBSdW4gdGhlIHNwZWMtY3R4IGxvb3AgaW4gYW4gT3BlblNwZWMgcHJvamVjdC4gVXNlIG9uICJydW4iLCAiY29udGludWUiLCAibmV4dCB0YXNrIiwgImJ1aWxkIHRoaXMiLCAiY2Fycnkgb24iLCBhbmQgb24gYSBmaXJzdCBtZXNzYWdlIHRoYXQgZGVzY3JpYmVzIGEgY2hhbmdlIHRvIGJ1aWxkLiBUaGUgZW5naW5lIHBpY2tzIHRoZSBuZXh0IGFjdGlvbi4gVGhlIHNraWxsIGFjdHMgb24gaXQgdW50aWwgdGhlIGNoYW5nZSByZWFjaGVzIHRoZSBhcmNoaXZlIG9yIGEgaHVtYW4gbXVzdCBkZWNpZGUuCi0tLQoKIyBzcGVjY3R4LXJ1bgoKUnVuIGBzcGVjY3R4YCBhcyBgbnB4IHNwZWMtY3R4YCB3aGVuIGl0IGlzIG5vdCBpbnN0YWxsZWQuIGBvcGVuc3BlY2AgaXMgdGhlIGNvbW1hbmQgaW4gYFtnYXRlXSBvcGVuc3BlY2Agb2YgYHNwZWMtY3R4LnRvbWxgLgoKIyMgVGhlIGxvb3AKCjEuIFJ1biBgc3BlY2N0eCBuZXh0IC0tanNvbmAuIFJlYWQgYGFjdGlvbmAsIGBjaGFuZ2VgIChgPGM+YCksIGB0YXNrYCAoYDx0PmApLCBgY29tbWFuZGAsIGByZWFzb25gLCBhbmQgYGh1bWFuYC4KMi4gQWN0IG9uIGBhY3Rpb25gIGFzIHRoZSB0YWJsZSBiZWxvdyBzYXlzLgozLiBSdW4gYHNwZWNjdHggaGFuZG9mZiB3cml0ZWAuCjQuIFJlcGVhdCBmcm9tIHN0ZXAgMSB1bnRpbCBgYWN0aW9uYCBpcyBgc3RvcGAgb3IgYGh1bWFuYCBpcyB0cnVlLgoKIyMgQWN0aW9ucwoKLSBgcGxhbmA6IGZvbGxvdyB0aGUgdXBzdHJlYW0gYG9wZW5zcGVjLXByb3Bvc2VgIHNraWxsIGZvciB0aGUgY2hhbmdlIGluIGBjb21tYW5kYC4gVGFrZSBldmVyeSBJRCBmcm9tIGBzcGVjY3R4IGlkIG5ldyBSRVEgPENBUD5gIGFuZCBgc3BlY2N0eCBpZCBuZXcgU0NOIDxDQVA+IC0tZm9yIDxSRVE+YC4gR2l2ZSBldmVyeSB0YXNrIGEgYFtSRVEtLi4uXWAgY2l0YXRpb24gYW5kIGEgYFZlcmlmeTpgIGNvZGUgc3Bhbi4gVGhlbiBydW4gYHNwZWNjdHggY2hlY2sgLS1zdHJpY3RgIGFuZCBgb3BlbnNwZWMgdmFsaWRhdGUgPGM+IC0tc3RyaWN0YC4gRml4IGV2ZXJ5IGZpbmRpbmcuIFN0b3AgYW5kIHNob3cgdGhlIHBsYW4gdG8gdGhlIHVzZXIuIFRoaXMgaXMgdGhlIHBsYW4gc3RvcC4KLSBgY2l0ZWA6IHJ1biBgc3BlY2N0eCBxdWVyeSAtLWNoYW5nZSA8Yz4gLS1raW5kIHJlcWAuIEFkZCB0aGUgYFtSRVEtLi4uXWAgY2l0YXRpb24gYW5kIGEgYFZlcmlmeTpgIGNvZGUgc3BhbiB0byB0aGUgdGFzayBsaW5lIG5hbWVkIGluIGB0YXNrYC4gUnVuIGBzcGVjY3R4IGNoZWNrYC4gQ29udGludWUuCi0gYHN0YXJ0YDogcnVuIGBzcGVjY3R4IHRhc2sgc3RhcnQgPHQ+YC4gUmVhZCB0aGUgYnVuZGxlIGl0IHByaW50cy4gQ29udGludWUuCi0gYHdvcmtgOiBpbXBsZW1lbnQgdGhlIHRhc2suIFRhZyBjb2RlIHdpdGggYC8vIFJFUS0uLi5gLiBUYWcgdGVzdHMgd2l0aCBgLy8gQ292ZXJzOiBSRVEtLi4uYC4gVGhlbiBydW4gYHNwZWNjdHggdGFzayBkb25lIDx0PmAuCi0gYGZpeGA6IHJlYWQgYHJlYXNvbmAuIEl0IGhvbGRzIHRoZSB0YWlsIG9mIHRoZSBmYWlsZWQgVmVyaWZ5IG91dHB1dC4gRml4IHRoZSBjYXVzZS4gUnVuIGBzcGVjY3R4IHRhc2sgZG9uZSA8dD5gIGFnYWluLgotIGByZXBhaXJgOiBydW4gYHNwZWNjdHggdGFzayBkb25lIDx0PmAuIEl0IHJ1bnMgVmVyaWZ5IGZvciBhIHRpY2tlZCB0YXNrIHRoYXQgaGFzIG5vIGV2aWRlbmNlLgotIGBnYXRlYDogcnVuIGBzcGVjY3R4IGdhdGUgLS1zdHJpY3RgLiBGaXggZXZlcnkgZmluZGluZy4gUnVuIGl0IGFnYWluIHVudGlsIGl0IGV4aXRzIDAuCi0gYGFyY2hpdmVgOiB3aGVuIGBodW1hbmAgaXMgdHJ1ZSwgc3RvcCBhbmQgYXNrIHRoZSB1c2VyIGluIG9uZSBsaW5lIHdoZXRoZXIgdG8gYXJjaGl2ZSBgPGM+YC4gV2hlbiBgaHVtYW5gIGlzIGZhbHNlLCBmb2xsb3cgdGhlIHVwc3RyZWFtIGBvcGVuc3BlYy1hcmNoaXZlLWNoYW5nZWAgc2tpbGwuIFRoZW4gcnVuIGBvcGVuc3BlYyB2YWxpZGF0ZSAtLWFsbCAtLXN0cmljdGAsIGBzcGVjY3R4IGNoZWNrIC0tc3RyaWN0YCwgYW5kIGBzcGVjY3R4IGhhbmRvZmYgd3JpdGVgLgotIGBhc2tgOiBwcmludCBgcmVhc29uYC4gSXQgaXMgdGhlIG9wZW4gcXVlc3Rpb24uIFN0b3AuIFRoZSB1c2VyIGFuc3dlcnMgd2l0aCBgc3BlY2N0eCBoYW5kb2ZmIHJlc29sdmUgPG4+ICI8YW5zd2VyPiJgLgotIGBzdG9wYDogcHJpbnQgYHJlYXNvbmAuIFN0b3AuCgojIyBSdWxlcwoKLSBOZXZlciB0aWNrIGEgY2hlY2tib3ggYnkgaGFuZC4gYHNwZWNjdHggdGFzayBkb25lYCBpcyB0aGUgb25seSB3YXkgYSB0YXNrIGNsb3Nlcy4KLSBOZXZlciB1c2UgYC0tbWFudWFsYCBvbiBhIHRhc2sgd2l0aCBhIFZlcmlmeSBjb21tYW5kLgotIE5ldmVyIGNhbGwgYC9vcHN4OmFwcGx5YC4gVGhpcyBza2lsbCByZXBsYWNlcyBpdC4KLSBOZXZlciByZWFkIGBvcGVuc3BlYy9zcGVjcy9gIG9yIGBvcGVuc3BlYy9jaGFuZ2VzLyovc3BlY3MvYCBkaXJlY3RseS4gVXNlIHRoZSBidW5kbGUgZnJvbSBgdGFzayBzdGFydGAgb3IgYHNwZWNjdHggYnVuZGxlIDxpZD5gLgotIFN0b3Agb24gYW55IGBhY3Rpb25gIG5vdCBpbiB0aGUgbGlzdCBhYm92ZS4gUHJpbnQgdGhlIG9iamVjdCBhbmQgYXNrIHRoZSB1c2VyLgotIEtlZXAgbm8gc3RhdGUgaW4geW91ciBjb250ZXh0LiBBIG5ldyBzZXNzaW9uIHN0YXJ0cyB0aGUgc2FtZSBsb29wIGFnYWluIHdpdGggc3RlcCAxLgo=",
+    "skills/specctx-run/SKILL.md": "LS0tCm5hbWU6IHNwZWNjdHgtcnVuCmRlc2NyaXB0aW9uOiBSdW4gdGhlIHNwZWMtY3R4IGxvb3AgaW4gYW4gT3BlblNwZWMgcHJvamVjdC4gVXNlIG9uICJydW4iLCAiY29udGludWUiLCAibmV4dCB0YXNrIiwgImJ1aWxkIHRoaXMiLCAiY2Fycnkgb24iLCBhbmQgb24gYSBmaXJzdCBtZXNzYWdlIHRoYXQgZGVzY3JpYmVzIGEgY2hhbmdlIHRvIGJ1aWxkLiBUaGUgZW5naW5lIHBpY2tzIHRoZSBuZXh0IGFjdGlvbi4gVGhlIHNraWxsIGFjdHMgb24gaXQgdW50aWwgdGhlIGNoYW5nZSByZWFjaGVzIHRoZSBhcmNoaXZlIG9yIGEgaHVtYW4gbXVzdCBkZWNpZGUuCi0tLQoKIyBzcGVjY3R4LXJ1bgoKUnVuIGBzcGVjY3R4YCBhcyBgbnB4IHNwZWMtY3R4YCB3aGVuIGl0IGlzIG5vdCBpbnN0YWxsZWQuIGBvcGVuc3BlY2AgaXMgdGhlIGNvbW1hbmQgaW4gYFtnYXRlXSBvcGVuc3BlY2Agb2YgYHNwZWMtY3R4LnRvbWxgLiBXaGVuIHRoYXQga2V5IGlzIGFic2VudCwgYG9wZW5zcGVjYCBpcyBgbnB4IC15IEBmaXNzaW9uLWFpL29wZW5zcGVjQGxhdGVzdGAuCgojIyBUaGUgbG9vcAoKMS4gUnVuIGBzcGVjY3R4IG5leHQgLS1qc29uYC4gUmVhZCBgYWN0aW9uYCwgYGNoYW5nZWAgKGA8Yz5gKSwgYHRhc2tgIChgPHQ+YCksIGBjb21tYW5kYCwgYHJlYXNvbmAsIGFuZCBgaHVtYW5gLgoyLiBBY3Qgb24gYGFjdGlvbmAgYXMgdGhlIHRhYmxlIGJlbG93IHNheXMuCjMuIFJ1biBgc3BlY2N0eCBoYW5kb2ZmIHdyaXRlYC4KNC4gUmVwZWF0IGZyb20gc3RlcCAxIHVudGlsIGBhY3Rpb25gIGlzIGBzdG9wYCBvciBgaHVtYW5gIGlzIHRydWUuCgojIyBBY3Rpb25zCgotIGBwbGFuYDogdGFrZSB0aGUgY2hhbmdlIG5hbWUgZnJvbSB0aGUgcmVxdWVzdCBvZiB0aGUgdXNlciBpbiBrZWJhYiBjYXNlLiBUaGF0IG5hbWUgaXMgYDxjPmAuIEZvbGxvdyB0aGUgdXBzdHJlYW0gYG9wZW5zcGVjLXByb3Bvc2VgIHNraWxsIGZvciBgPGM+YC4gUmVhZCBleGlzdGluZyByZXF1aXJlbWVudHMgd2l0aCBgc3BlY2N0eCBidW5kbGUgPGlkPmAgb3IgYHNwZWNjdHggcXVlcnlgLCBuZXZlciBgb3BlbnNwZWMgc2hvd2AuIFRha2UgZXZlcnkgSUQgZnJvbSBgc3BlY2N0eCBpZCBuZXcgUkVRIDxDQVA+YCBhbmQgYHNwZWNjdHggaWQgbmV3IFNDTiA8Q0FQPiAtLWZvciA8UkVRPmAuIFdoZW4gdGhlIGNoYW5nZSBuZWVkcyBzZXZlcmFsIElEcyBvZiBvbmUga2luZCwgcnVuIGBzcGVjY3R4IGlkIG5ldyAtLWNvdW50IDxuPmAgb25jZS4gR2l2ZSBldmVyeSB0YXNrIGEgYFtSRVEtLi4uXWAgY2l0YXRpb24gYW5kIGEgYFZlcmlmeTpgIGNvZGUgc3Bhbi4gVGhlbiBydW4gYHNwZWNjdHggY2hlY2sgLS1zdHJpY3RgIGFuZCBgc3BlY2N0eCBnYXRlIC0tc3RyaWN0YC4gVGhlIGdhdGUgcnVucyB0aGUgT3BlblNwZWMgdmFsaWRhdGUgYW5kIHRoZSBzcGVjLWxlbmd0aCBjaGVjay4gRml4IGV2ZXJ5IGZpbmRpbmcuIFRoZW4gcnVuIGBzcGVjY3R4IG5leHQgLS1qc29uYCBhbmQgcnVuIHRoZSBjb21tYW5kIGl0IHByaW50cy4gVGhpcyBpcyB0aGUgcGxhbiBzdG9wLiBgbmV4dGAgcmV0dXJucyBgYXNrYCB3aXRoIGBodW1hbjogdHJ1ZWAgdW50aWwgdGhlIHVzZXIgcmVzb2x2ZXMgdGhlIHF1ZXN0aW9uLgotIGBjaXRlYDogcnVuIGBzcGVjY3R4IHF1ZXJ5IC0tY2hhbmdlIDxjPiAtLWtpbmQgcmVxYC4gQWRkIHRoZSBgW1JFUS0uLi5dYCBjaXRhdGlvbiBhbmQgYSBgVmVyaWZ5OmAgY29kZSBzcGFuIHRvIHRoZSB0YXNrIGxpbmUgbmFtZWQgaW4gYHRhc2tgLiBSdW4gYHNwZWNjdHggY2hlY2tgLiBDb250aW51ZS4KLSBgc3RhcnRgOiBydW4gYHNwZWNjdHggdGFzayBzdGFydCA8dD5gLiBSZWFkIHRoZSBidW5kbGUgaXQgcHJpbnRzLiBDb250aW51ZS4KLSBgd29ya2A6IGltcGxlbWVudCB0aGUgdGFzay4gVGFnIGNvZGUgd2l0aCBgLy8gUkVRLS4uLmAuIFRhZyB0ZXN0cyB3aXRoIGAvLyBDb3ZlcnM6IFJFUS0uLi5gLiBUaGVuIHJ1biBgc3BlY2N0eCB0YXNrIGRvbmUgPHQ+YC4KLSBgZml4YDogcmVhZCBgcmVhc29uYC4gSXQgaG9sZHMgdGhlIHRhaWwgb2YgdGhlIGZhaWxlZCBWZXJpZnkgb3V0cHV0LiBGaXggdGhlIGNhdXNlLiBSdW4gYHNwZWNjdHggdGFzayBkb25lIDx0PmAgYWdhaW4uCi0gYHJlcGFpcmA6IHJ1biB0aGUgY29tbWFuZCBpbiB0aGUgYGNvbW1hbmRgIGZpZWxkLiBJdCBydW5zIFZlcmlmeSBhZ2FpbiBmb3IgYSB0aWNrZWQgdGFzayB3aG9zZSBldmlkZW5jZSBpcyBhYnNlbnQgb3Igc3RhbGUuCi0gYGdhdGVgOiBydW4gYHNwZWNjdHggZ2F0ZSAtLXN0cmljdGAuIEZpeCBldmVyeSBmaW5kaW5nLiBGb3IgYSBgc3RhbGUtZXZpZGVuY2VgIGZpbmRpbmcsIGdvIGJhY2sgdG8gc3RlcCAxLiBgbmV4dGAgcmV0dXJucyBgcmVwYWlyYCBhbmQgaXRzIGNvbW1hbmQgcmVwYWlycyBldmVyeSBzdGFsZSB0YXNrLiBSdW4gdGhlIGdhdGUgYWdhaW4gdW50aWwgaXQgZXhpdHMgMC4KLSBgYXJjaGl2ZWA6IHdoZW4gYGh1bWFuYCBpcyB0cnVlLCBydW4gYHNwZWNjdHggaGFuZG9mZiBhc2sgLS1jaGFuZ2UgPGM+ICJhcmNoaXZlIDxjPj8iYCBhbmQgc3RvcC4gVGhpcyBpcyB0aGUgYXJjaGl2ZSBzdG9wLiBgbmV4dGAgcmV0dXJucyBgYXNrYCB1bnRpbCB0aGUgdXNlciByZXNvbHZlcyB0aGUgcXVlc3Rpb24uIFdoZW4gYGh1bWFuYCBpcyBmYWxzZSwgdGhlIHVzZXIgYXBwcm92ZWQgb3IgYFtsb29wXSBhcmNoaXZlYCBpcyBgYXV0b2AuIFRoZW4gcnVuIGVhY2ggc3RlcCB1bmRlciBgb3BlcmF0aW9ucy5hcmNoaXZlLmd1aWRhbmNlYCBpbiBgb3BlbnNwZWMvY29uZmlnLnlhbWxgLiBUaGVuIHJ1biB0aGUgY29tbWFuZCBpbiB0aGUgYGNvbW1hbmRgIGZpZWxkLiBUaGVuIHJ1biBgb3BlbnNwZWMgdmFsaWRhdGUgLS1hbGwgLS1zdHJpY3RgLCBgc3BlY2N0eCBjaGVjayAtLXN0cmljdGAsIGFuZCBgc3BlY2N0eCBoYW5kb2ZmIHdyaXRlYC4KLSBgYXNrYDogcHJpbnQgYHJlYXNvbmAuIEl0IGlzIHRoZSBvcGVuIHF1ZXN0aW9uLiBTdG9wLiBUaGUgdXNlciBhbnN3ZXJzIHdpdGggYHNwZWNjdHggaGFuZG9mZiByZXNvbHZlIDxuPiAiPGFuc3dlcj4iYC4KLSBgc3RvcGA6IHByaW50IGByZWFzb25gLiBTdG9wLgoKIyMgUnVsZXMKCi0gVGhpcyBza2lsbCBvdmVycmlkZXMgdHdvIHN0ZXBzIG9mIHRoZSB1cHN0cmVhbSBgb3BlbnNwZWMtcHJvcG9zZWAgc2tpbGwuIEl0IHJlYWRzIHNwZWNzIHdpdGggYHNwZWNjdHggYnVuZGxlYCBvciBgc3BlY2N0eCBxdWVyeWAsIG5vdCBgb3BlbnNwZWMgc2hvd2AuIEl0IG5ldmVyIHJ1bnMgdGhlIGNsb3NpbmcgYC9vcHN4OmFwcGx5YC4KLSBOZXZlciB0aWNrIGEgY2hlY2tib3ggYnkgaGFuZC4gYHNwZWNjdHggdGFzayBkb25lYCBpcyB0aGUgb25seSB3YXkgYSB0YXNrIGNsb3Nlcy4KLSBOZXZlciB1c2UgYC0tbWFudWFsYCBvbiBhIHRhc2sgd2l0aCBhIFZlcmlmeSBjb21tYW5kLgotIE5ldmVyIGNhbGwgYC9vcHN4OmFwcGx5YC4gVGhpcyBza2lsbCByZXBsYWNlcyBpdC4KLSBUbyB3cml0ZSBhIE1PRElGSUVEIGJsb2NrLCBydW4gYHNwZWNjdHggYnVuZGxlIDxSRVE+IC0tYmxvY2tgLiBJdCBwcmludHMgdGhlIGJsb2NrIGFzIGl0IHNpdHMgaW4gdGhlIHNwZWMgZmlsZS4gQSBNT0RJRklFRCBibG9jayBrZWVwcyBldmVyeSBzY2VuYXJpbyB0aXRsZSB1bmNoYW5nZWQuCi0gYGdhdGVgIGNvdW50cyB0aGUgUmVmcyBsaW5lIGluIHRoZSA1MDAgY2hhcmFjdGVycyBvZiBhIHJlcXVpcmVtZW50LgotIFRoZSBDSEFOR0VMT0cgZW50cnkgZ29lcyB1bmRlciBgIyMgVW5yZWxlYXNlZGAsIG5ldmVyIHVuZGVyIGEgcmVsZWFzZWQgdmVyc2lvbi4KLSBBZnRlciBhbiBlZGl0IHVuZGVyIGBza2lsbHMvYCwgcnVuIGBidW4gcnVuIGJ1aWxkICYmIG5vZGUgZGlzdC9jbGkuanMgaW5pdCAtLXNraWxscyAtLWZvcmNlYCB0byByZWZyZXNoIHRoZSBjb3BpZXMuCi0gTmV2ZXIgcmVhZCBgb3BlbnNwZWMvc3BlY3MvYCBvciBgb3BlbnNwZWMvY2hhbmdlcy8qL3NwZWNzL2AgZGlyZWN0bHkuIFVzZSB0aGUgYnVuZGxlIGZyb20gYHRhc2sgc3RhcnRgIG9yIGBzcGVjY3R4IGJ1bmRsZSA8aWQ+YC4KLSBTdG9wIG9uIGFueSBgYWN0aW9uYCBub3QgaW4gdGhlIGxpc3QgYWJvdmUuIFByaW50IHRoZSBvYmplY3QgYW5kIGFzayB0aGUgdXNlci4KLSBLZWVwIG5vIHN0YXRlIGluIHlvdXIgY29udGV4dC4gQSBuZXcgc2Vzc2lvbiBzdGFydHMgdGhlIHNhbWUgbG9vcCBhZ2FpbiB3aXRoIHN0ZXAgMS4K",
 };

package/dist/baseline/baseline.js

@@ -4,11 +4,14 @@ import { join } from "node:path";
 import { lintLine, parseLintLine } from "../lint/counts.js";
 import { cmpStr } from "../util/pystr.js";
 export const BASELINE_PATH = ".ctx/baseline.json";
-export const BASELINE_RULES = ["uncovered", "scenario-untested", "done-without-evidence", "manual-evidence", "task-without-req", "task-without-verify", "missing-id"];
+export const BASELINE_RULES = ["uncovered", "scenario-untested", "done-without-evidence", "manual-evidence", "task-without-req", "task-without-verify", "weak-verify", "missing-id"];
 /** REQ-ADOPT-005 a missing-id finding has no ID. Its key carries the file and the header title. */
 const key = (f) => (f.rule === "missing-id" ? `${f.rule} ${f.file} ${f.id}` : `${f.rule} ${f.id}`);
-/** A warning line reads "manual-evidence <task>". */
-const warningKey = (w) => w;
+/**
+ * A warning line reads "manual-evidence <task>" or "weak-verify <task> <file>:<line>".
+ * REQ-ADOPT-005 the key keeps the rule and the task, so a weak-verify warning matches its strict finding (028/D10).
+ */
+const warningKey = (w) => w.split(" ").slice(0, 2).join(" ");
 export function readBaseline(root) {
     const p = join(root, BASELINE_PATH);
     if (!existsSync(p))

package/dist/check/check.js

@@ -6,6 +6,7 @@ import { changeKey } from "../index/scan.js";
 import { listEvidence } from "../tasks/evidence.js";
 import { cmpTuple } from "../util/pystr.js";
 import { evidenceFindings } from "./evidence.js";
+import { isWeakVerify, parseVerify } from "../verify/parse.js";
 // the first ID of a retired row can be a scenario. Only a REQ or ADR can be reused, but the SCN still counts as the row ID.
 const RETIRED_RE = /\b(REQ-[A-Z]{2,6}-\d{3}|SCN-[A-Z]{2,6}-\d{3}-\d+|ADR-\d{3})\b/g;
 const REQ_CAP = /^REQ-([A-Z]{2,6})-/;
@@ -69,6 +70,11 @@ function renamedTargets(root, file) {
     }
     return out;
 }
+/** REQ-CHK-006 the header line of an entry as its file writes it, without the line end. */
+function headerLine(root, e) {
+    const line = readFileSync(join(root, e.file), "utf8").split(/\r?\n/)[e.line - 1];
+    return (line ?? `### Requirement: ${e.id} ${e.title}`).trimEnd();
+}
 /**
  * REQ-CHK-001 retitle-needs-renamed: a MODIFIED or REMOVED header of an active change whose ID exists in main
  * with another title, and whose delta file has no RENAMED TO line with that header. Upstream OpenSpec matches
@@ -91,10 +97,31 @@ export function retitleFindings(root, entries) {
             targets.set(e.file, renamedTargets(root, e.file));
         if (targets.get(e.file).some(([id, title]) => title === e.title && (id === null || id === e.id)))
             continue;
-        out.push({ file: e.file, line: e.line, rule: "retitle-needs-renamed", id: e.id, detail: `"${m.title}" -> "${e.title}"` });
+        // REQ-CHK-006 the hint copies both header lines as the files write them, bare or in brackets (031/D7)
+        const hint = `Add to the delta before the MODIFIED block:\n## RENAMED Requirements\n- FROM: \`${headerLine(root, m)}\`\n- TO: \`${headerLine(root, e)}\``;
+        out.push({ file: e.file, line: e.line, rule: "retitle-needs-renamed", id: e.id, detail: `"${m.title}" -> "${e.title}"`, hint });
     }
     return out;
 }
+/**
+ * REQ-CHK-005 weak-verify: a task of an active change whose Verify command always exits 0 (028/D2).
+ * A task with no Verify command has task-without-verify already, so it gets no second finding.
+ */
+export function weakVerifyFindings(entries) {
+    const out = [];
+    for (const e of entries) {
+        if (e.kind !== "task" || e.change === "main" || e.file.includes("/archive/"))
+            continue;
+        const v = parseVerify(e.title);
+        if (v.command !== null && isWeakVerify(v.command))
+            out.push({ file: e.file, line: e.line, rule: "weak-verify", id: e.id });
+    }
+    return out;
+}
+/** REQ-CHK-005 the plain-mode form of weak-verify: one warning "weak-verify <task> <file>:<line>" per task (028/D3). */
+export function weakVerifyWarnings(entries) {
+    return weakVerifyFindings(entries).map((f) => `weak-verify ${f.id} ${f.file}:${f.line}`);
+}
 /** Sorted, unique findings. The scan never reads .ctx/, so evidence adds no index entry. */
 export function check(root, cfg, data, strict) {
     const entries = data.entries;
@@ -163,12 +190,36 @@ 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();
     for (const f of findings)
         uniq.set(JSON.stringify(f), f);
     const plain = [...uniq.values()].map(([file, line, rule, id]) => ({ file, line, rule, id }));
-    const all = [...plain, ...retitleFindings(root, entries)];
+    // REQ-CHK-005 weak-verify is hard only in strict mode. Plain mode prints it as a warning (028/D3).
+    const all = [...plain, ...retitleFindings(root, entries), ...(strict ? weakVerifyFindings(entries) : [])];
     return all.sort((a, b) => cmpTuple([a.file, a.line, a.rule, a.id], [b.file, b.line, b.rule, b.id]));
 }

package/dist/check/evidence.js

@@ -1,7 +1,30 @@
 // REQ-CHK-003 evidence rules of check --strict.
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileSha256 } from "../util/hash.js";
+import { evidenceRel } from "../tasks/tasks.js";
+/**
+ * REQ-CHK-003 REQ-LOOP-008 the stale paths of one evidence file, sorted. A damaged file is stale as a whole and
+ * returns its own path. check and next both read this, so the two never differ (031/D5).
+ */
+export function staleFiles(root, rel) {
+    let files = {};
+    try {
+        const ev = JSON.parse(readFileSync(join(root, rel), "utf8"));
+        files = ev.files ?? {};
+    }
+    catch {
+        return [rel];
+    }
+    return Object.keys(files).filter((p) => fileSha256(join(root, p)) !== files[p]).sort();
+}
+/** REQ-LOOP-008 the first stale path of the evidence of a task, or null when it is fresh or absent (031/D5). */
+export function staleOf(root, task) {
+    const rel = evidenceRel({ id: task });
+    if (!existsSync(join(root, rel)))
+        return null;
+    return staleFiles(root, rel)[0] ?? null;
+}
 export function evidenceFindings(root, entries, evidence) {
     const out = [];
     const tasks = new Map();
@@ -27,19 +50,8 @@ export function evidenceFindings(root, entries, evidence) {
         // archived changes are exempt from stale-evidence
         if (!active)
             continue;
-        let files = {};
-        try {
-            const ev = JSON.parse(readFileSync(join(root, rel), "utf8"));
-            files = ev.files ?? {};
-        }
-        catch {
-            out.push([rel, 1, "stale-evidence", `${id} ${rel}`]);
-            continue;
-        }
-        for (const [path, digest] of Object.entries(files)) {
-            if (fileSha256(join(root, path)) !== digest)
-                out.push([rel, 1, "stale-evidence", `${id} ${path}`]);
-        }
+        for (const path of staleFiles(root, rel))
+            out.push([rel, 1, "stale-evidence", `${id} ${path}`]);
     }
     for (const e of entries) {
         if (e.kind === "task" && e.status === "done" && !e.file.includes("/archive/") && !have.has(e.id)) {

package/dist/check/hints.js

@@ -9,16 +9,23 @@ 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." },
-    "stale-evidence": { level: "hard", hint: "Run specctx task reopen and then specctx task done." },
+    // 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>." },
     "evidence-without-done": { level: "hard", hint: "Run specctx task done, or remove the evidence file." },
+    // REQ-CHK-005 advisory in plain check. check --strict reports it as a hard finding (028/D5).
+    "weak-verify": { level: "advisory", hint: "Name a test file or a command whose exit code proves the task." },
     "manual-evidence": { level: "advisory", hint: "Give the task a Verify command and run specctx task done again." },
     // REQ-CHK-001 the hint is the block to paste. The finding line carries the ID and both titles (021/D3).
     // REQ-ADOPT-010 FROM copies the main header and TO copies the delta header, each in its own form (027/D4).

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": {},
+    "handoff ask": { change: "string", plan: "bool" },
     "handoff resolve": {},
     adopt: { "dry-run": "bool" },
     "baseline write": {},

package/dist/cli/commands.js

@@ -10,7 +10,12 @@ async function runCheck(root, cfg, data, strict) {
     const { applyBaseline } = await import("../baseline/baseline.js");
     const findings = check(root, cfg, data, strict);
     let warnings = [];
-    if (strict) {
+    if (!strict) {
+        // REQ-CHK-005 plain check prints weak-verify as an advisory warning (028/D3)
+        const { weakVerifyWarnings } = await import("../check/check.js");
+        warnings = weakVerifyWarnings(data.entries);
+    }
+    else {
         const { manualWarnings } = await import("../check/evidence.js");
         const { listEvidence } = await import("../tasks/evidence.js");
         warnings = manualWarnings(root, data.entries, listEvidence(root));
@@ -35,16 +40,29 @@ export function checkText(r, tty) {
     for (const x of r.findings)
         count.set(x.rule, (count.get(x.rule) ?? 0) + 1);
     for (const w of r.warnings) {
-        const [rule, task] = w.split(" ");
+        const [rule, task, at] = w.split(" ");
         count.set(rule, (count.get(rule) ?? 0) + 1);
+        // REQ-CHK-005 a weak-verify warning ends with <file>:<line> of the task line (028/D4)
+        if (rule === "weak-verify" && at)
+            files.add(at.replace(/:\d+$/, ""));
         // a manual-evidence warning names a task. Its file is the evidence file of the task.
-        if (task?.includes("/"))
+        else if (task?.includes("/"))
             files.add(`.ctx/evidence/${task}.json`);
     }
+    // REQ-CHK-006 the distinct hints that findings carry, in finding order. A rule with none prints the table hint (031/D6).
+    const own = new Map();
+    for (const x of r.findings) {
+        if (x.hint === undefined)
+            continue;
+        const l = own.get(x.rule) ?? [];
+        if (!l.includes(x.hint))
+            l.push(x.hint);
+        own.set(x.rule, l);
+    }
     const rules = [...count.keys()].sort();
     return body
         + "\n" + paint("dim", `${n} finding${n === 1 ? "" : "s"} in ${files.size} file${files.size === 1 ? "" : "s"} (${r.findings.length} hard, ${r.warnings.length} advisory)\n`, tty)
-        + rules.map((rule) => `${rule}  ${count.get(rule)}  ${hintOf(rule)}\n`).join("")
+        + rules.map((rule) => `${rule}  ${count.get(rule)}  ${own.get(rule)?.join("\n") ?? hintOf(rule)}\n`).join("")
         + base;
 }
 export async function run(p, io) {
@@ -55,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") {
@@ -129,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, {
@@ -182,9 +199,13 @@ export async function run(p, io) {
             const r = statusReport(root, entries);
             if (json)
                 print(r);
-            // REQ-CLI-008 the next: line is dim
-            else
-                io.out(statusLines(r).map((l) => (l.startsWith("next: ") ? paint("dim", l, io.tty) : l) + "\n").join(""));
+            else {
+                // REQ-CLI-007 the next: line is the command of the decision of specctx next, so the two never disagree (030/D1)
+                const { decideNext } = await import("../loop/next.js");
+                const d = decideNext(root, cfg, data);
+                // REQ-CLI-008 the next: line is dim
+                io.out(statusLines(r, d.command).map((l) => (l.startsWith("next: ") ? paint("dim", l, io.tty) : l) + "\n").join(""));
+            }
             return 0;
         }
         case "next": {
@@ -240,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);
@@ -269,8 +305,10 @@ export async function run(p, io) {
         }
         case "check": {
             const r = await runCheck(root, cfg, data, !!f.strict);
+            // REQ-CHK-004 REQ-CHK-006 the JSON keeps its shape. A finding hint is for the human form only (031/D6).
+            const findings = r.findings.map(({ hint: _hint, ...rest }) => rest);
             if (json)
-                print({ baselined: r.baselined, count: r.findings.length, findings: r.findings, warnings: r.warnings });
+                print({ baselined: r.baselined, count: findings.length, findings, warnings: r.warnings });
             else
                 io.out(checkText(r, io.tty));
             return r.findings.length ? 1 : 0;

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;
+    }
+}