spec-ctx 0.5.0 → 0.6.0

package/README.md

@@ -116,7 +116,7 @@ You see: one change, two tasks done, one open, and the hint.
 
 ### 3. What is next
 
-`task next` picks the first open task. It prints the requirements the task cites and its Verify command, the shell command that proves the task is done.
+`task next` picks the first open task. It prints the requirements the task cites and its Verify command, the shell command that proves the task works.
 
 ![Task add-mfa/1.3 with its requirement and Verify command](https://raw.githubusercontent.com/sonqh/spec-ctx/main/docs/demo/clips/3-next.svg)
 
@@ -132,7 +132,7 @@ You see: 711 characters, 3.6 percent of the tree. The agent reads this instead o
 
 ### 5. Done means Verify passed
 
-`task done` runs the Verify command. On exit 1 the box stays open. On exit 0 the box flips to `[x]` and an evidence file records the files that were checked.
+`task done` runs the Verify command. On exit 1 the box stays open. On exit 0 the box flips to `[x]` and an evidence file records the files that it checked.
 
 ![A refused done, the edit, and a passing done](https://raw.githubusercontent.com/sonqh/spec-ctx/main/docs/demo/clips/5-done.svg)
 
@@ -165,6 +165,16 @@ npx -y spec-ctx task done <task>        # runs that command. A pass ticks the bo
 - [`docs/getting-started.md`](https://github.com/sonqh/spec-ctx/blob/main/docs/getting-started.md) walks the fresh path with real output.
 - [`docs/reference.md`](https://github.com/sonqh/spec-ctx/blob/main/docs/reference.md) holds the install options, the path for an existing project, every command, and the config file.
 
+## Try it on your own OpenSpec repo
+
+```bash
+npx -y spec-ctx init --all              # config, ID templates, rules, and the agent skill
+npx -y spec-ctx adopt                   # gives an ID to every header without one
+npx -y spec-ctx context <task>          # the specs, code, and tests that this task needs
+```
+
+`init` prints the next command, from the state of your specs. To gate the old debt later, run `npx -y spec-ctx baseline write`, commit it with a subject that starts with `baseline:`, and run `npx -y spec-ctx gate --strict`.
+
 ## How it finds the context
 
 ```mermaid
@@ -178,7 +188,7 @@ graph LR
 
 The ID is the stable key. A reword of a header does not change it. The index is the graph of IDs: tasks, requirements, scenarios, decisions, code tags, and test tags. A decision record joins the graph through its `Refs:` line.
 
-`specctx context <task|ID|path|change>` is the one command to run before you edit. It walks the edges inside a character budget and prints one provenance line for each block. When a block does not fit, a `truncated:` line names it. `related` prints each neighbor and the reason for the link:
+`specctx context <task|ID|path|change>` is the one command to run before you edit. It walks the edges inside a character budget and prints one provenance line for each block. Each entry prints its card first. A card carries its trust labels: the provenance of the link (`declared`, `tagged`, `structural`, or `verified`) and, for a task or a requirement, the evidence state (`fresh`, `stale since <path>`, `no evidence`, `verified`, `unverified`). A card ends with `| body omitted` when its body does not fit, and `bundle <ID>` gets the body. A `truncated:` line names an entry that has no card. A task that cites no requirement gets a `note:` line. A task also gets one card for each file that its line names, with the reason `named by <task>`. `related` prints each neighbor and the reason for the link:
 
 ```text
 $ specctx related REQ-UA-004
@@ -225,17 +235,17 @@ Tests and offline machines set `SPECCTX_OPENSPEC` to the command that runs OpenS
 
 ## Status
 
-- Published: `spec-ctx@0.5.0` on npm, with binaries on the GitHub release. See `CHANGELOG.md` for each release.
-- Archived: 001 to 025, 027 to 034, 036 to 053, and 055 to 057. No change is open.
-- Upstream: the ID scheme is proposed in [OpenSpec#1967](https://github.com/Fission-AI/OpenSpec/issues/1967#issuecomment-6414314730). The schema bundle is in the community table of [OpenSpec#2157](https://github.com/Fission-AI/OpenSpec/issues/2157).
+- Published: `spec-ctx@0.6.0` on npm, with binaries on the GitHub release. See `CHANGELOG.md` for each release.
+- Archived: 001 to 025, 027 to 034, and 036 to 063. No change is open.
+- Upstream: the ID scheme has a proposal in [OpenSpec#1967](https://github.com/Fission-AI/OpenSpec/issues/1967#issuecomment-6414314730). The schema bundle is in the community table of [OpenSpec#2157](https://github.com/Fission-AI/OpenSpec/issues/2157).
 
 ## Measured
 
-`specctx stats --write` measures this repository after each change. The newest file is `docs/metrics/2026-11-05.md`. Its total row:
+`specctx stats --write` measures this repository after each change. The newest file is `docs/metrics/2026-11-07.md`. Its total row:
 
 | change | context_ratio | evidence_ratio | stale_catches | cycle_time_median_s | debt |
 | --- | --- | --- | --- | --- | --- |
-| total | 0.0164 (n=154) | 0.94 (257/273) | 65 (of 122 reopens) | 61 (n=154) | 0 (0 baselined + 0 new) |
+| total | 0.0146 (n=168) | 0.95 (286/302) | 82 (of 151 reopens) | 54 (n=168) | 0 (0 baselined + 0 new) |
 
 - `context_ratio`: the size of one task bundle divided by the size of all spec text. Lower is better. Change 047 on 2026-10-30 made the bundle hold more, so older values do not compare.
 - `evidence_ratio`: done tasks with a passed Verify command, divided by all done tasks. Higher is better.

package/dist/adopt/plan.js

@@ -84,20 +84,40 @@ function parse(root, rel, cap) {
     });
     return { rel, cap, lines, blocks, renames };
 }
-/** REQ-ADOPT-004 candidate codes in order: the base code, then two and three letters of the first segment, then a suffix letter. */
-export function codeCandidates(path) {
+/** REQ-ADOPT-012 the family code of a path with two or more segments: three letters of the first, three of the rest. */
+export function familyCode(path) {
+    const segs = path.split(/[/-]/).map((x) => x.toUpperCase().replace(/[^A-Z]/g, "")).filter(Boolean);
+    if (segs.length < 2)
+        return null;
+    const code = segs[0].slice(0, 3) + segs.slice(1).join("").slice(0, 3);
+    return /^[A-Z]{2,6}$/.test(code) ? code : null;
+}
+/** REQ-ADOPT-012 the first segment of a path, the key of its family */
+export function familySegment(path) {
+    return path.split(/[/-]/)[0] ?? path;
+}
+/** REQ-ADOPT-012 the segments shared by three or more paths */
+export function familiesOf(paths) {
+    const count = new Map();
+    for (const p of paths)
+        count.set(familySegment(p), (count.get(familySegment(p)) ?? 0) + 1);
+    return new Set([...count].filter(([, n]) => n >= 3).map(([s]) => s));
+}
+/** REQ-ADOPT-004 candidate codes in order: the base code, then two and three letters of the first segment, then a suffix letter. REQ-ADOPT-012 a family member gets its family code first. */
+export function codeCandidates(path, family = false) {
     const segs = path.split(/[/-]/).map((x) => x.toUpperCase().replace(/[^A-Z]/g, "")).filter(Boolean);
     if (!segs.length)
         return [];
     const rest = segs.slice(1).map((x) => x[0]).join("");
     const base = segs.length === 1 ? segs[0].slice(0, 3) : segs.map((x) => x[0]).join("").slice(0, 6);
-    const out = [base, (segs[0].slice(0, 2) + rest).slice(0, 6), (segs[0].slice(0, 3) + rest).slice(0, 6)];
+    const fam = family ? familyCode(path) : null;
+    const out = [...(fam ? [fam] : []), base, (segs[0].slice(0, 2) + rest).slice(0, 6), (segs[0].slice(0, 3) + rest).slice(0, 6)];
     for (let c = 66; c <= 90; c++)
         out.push((base.slice(0, 5) + String.fromCharCode(c)));
     return [...new Set(out.filter((x) => /^[A-Z]{2,6}$/.test(x)))];
 }
-export function deriveCode(path, taken = new Set()) {
-    const code = codeCandidates(path).find((c) => !taken.has(c));
+export function deriveCode(path, taken = new Set(), family = false) {
+    const code = codeCandidates(path, family).find((c) => !taken.has(c));
     if (!code)
         throw new UsageExit(`no free capability code for ${path}. Add one under [ids.paths] in spec-ctx.toml`);
     return code;
@@ -125,6 +145,8 @@ export function planAdopt(root, cfg) {
     // on a collision the shorter path keeps the base code: user-auth keeps UA, upload-api takes UPA
     const capList = [...new Set(files.map((f) => f.cap))].sort((a, b) => a.length - b.length || cmpStr(a, b));
     const taken = new Set([...cfg.ids.caps, ...codeOfPath.values()]);
+    // REQ-ADOPT-012 a family is three or more paths with one first segment (063/D1)
+    const families = familiesOf(capList);
     const caps = [];
     for (const cap of capList) {
         let code = codeOfPath.get(cap);
@@ -135,7 +157,7 @@ export function planAdopt(root, cfg) {
                 code = HAS_REQ.exec(existing.id)[1];
         }
         if (!code) {
-            code = deriveCode(cap, taken);
+            code = deriveCode(cap, taken, families.has(familySegment(cap)));
             derived = true;
             taken.add(code);
         }
@@ -275,13 +297,24 @@ export function planAdopt(root, cfg) {
         }
     }
     edits.sort((a, b) => cmpStr(a.file, b.file) || a.line - b.line);
-    return { edits, caps, unmatched };
+    // a family whose segment has no letters gives no code, so it is not listed
+    const familyList = [...families]
+        .sort(cmpStr)
+        .map((segment) => ({
+        segment,
+        prefix: segment.toUpperCase().replace(/[^A-Z]/g, "").slice(0, 3),
+        count: capList.filter((c) => familySegment(c) === segment).length,
+    }))
+        .filter((f) => f.prefix.length >= 2);
+    return { edits, caps, families: familyList, unmatched };
 }
 export function planLines(p) {
     const out = p.edits.map((e) => `${e.file}:${e.line}  ${e.old}  ->  ${e.new}`);
     const derived = p.caps.filter((c) => c.derived);
     if (derived.length)
         out.push(...derived.map((c) => `cap: ${c.code} ${c.path}`));
+    // REQ-ADOPT-012 one line per family, after the cap lines (063/D5)
+    out.push(...p.families.map((f) => `family: ${f.segment}  prefix ${f.prefix}  ${f.count} codes`));
     for (const u of p.unmatched)
         out.push(`unmatched: ${u.file}:${u.line}  ${u.header}`);
     return out;

package/dist/adopt/write.js

@@ -2,7 +2,7 @@
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { UsageExit } from "../cli/errors.js";
-import { CONFIG_FILE } from "../config.js";
+import { CONFIG_FILE, ConfigError } from "../config.js";
 import { loadConfigOrExit } from "../cli/config.js";
 import { runCommand } from "../runcmd.js";
 import { dumps } from "../util/json.js";
@@ -44,6 +44,12 @@ export function reportText(plan) {
     out.push("## Capability codes", "", "Rename a code in `spec-ctx.toml` before the IDs spread.", "", "| Code | Path | Source |", "| --- | --- | --- |");
     for (const c of plan.caps)
         out.push(`| ${c.code} | ${c.path} | ${c.derived ? "derived" : "existing"} |`);
+    // REQ-ADOPT-012 the families and their prefix (063/D5)
+    if (plan.families.length) {
+        out.push("", "Families of three or more paths with one first segment take a family code first. The prefix is the first three letters of that segment.", "");
+        for (const f of plan.families)
+            out.push(`- \`${f.segment}\`: prefix \`${f.prefix}\`, ${f.count} codes`);
+    }
     out.push("", "## Headers", "", "| File | Line | Old header | New header |", "| --- | --- | --- | --- |");
     const cell = (s) => "`" + s.replace(/\|/g, "\\|").replace(/`/g, "'") + "`";
     for (const e of plan.edits)
@@ -58,6 +64,20 @@ export function reportText(plan) {
     }
     return out.join("\n") + "\n";
 }
+/** REQ-ADOPT-011 the command after adopt. The codes in spec-ctx.toml changed, so the config loads again. */
+async function nextAfterAdopt(root, run) {
+    const { loadIndex } = await import("../index/build.js");
+    const { nextTask } = await import("../tasks/tasks.js");
+    try {
+        const task = nextTask(root, loadIndex(root, loadConfigOrExit(root)).data.entries);
+        return runCommand(run, task ? `context ${task.id}` : "status");
+    }
+    catch (e) {
+        if (e instanceof UsageExit || e instanceof ConfigError)
+            return runCommand(run, "status");
+        throw e;
+    }
+}
 export async function applyAdopt(root, cfg, plan, io, json) {
     const cfgPath = join(root, CONFIG_FILE);
     const cfgBefore = existsSync(cfgPath) ? readFileSync(cfgPath, "utf8") : null;
@@ -115,7 +135,7 @@ export async function applyAdopt(root, cfg, plan, io, json) {
     const files = new Set(plan.edits.map((e) => e.file)).size;
     const report = plan.edits.length ? REPORT_FILE : null;
     if (json)
-        io.out(dumps({ adopted: plan.edits.length, caps: plan.caps, files, report, unmatched: plan.unmatched }) + "\n");
+        io.out(dumps({ adopted: plan.edits.length, caps: plan.caps, families: plan.families, files, report, unmatched: plan.unmatched }) + "\n");
     else {
         io.out(plan.unmatched.map((u) => `unmatched: ${u.file}:${u.line}  ${u.header}\n`).join(""));
         // REQ-CLI-007 only the codes in spec-ctx.toml changed: no header, no report
@@ -123,8 +143,11 @@ export async function applyAdopt(root, cfg, plan, io, json) {
             io.out(`wrote the codes to ${CONFIG_FILE}\nnothing to adopt\n`);
         else {
             io.out(`adopted ${plan.edits.length} header(s) in ${files} file(s). Report: ${REPORT_FILE}\n`);
-            // REQ-ADOPT-002 adopt writes no baseline. The next step is a separate commit (044/D4, ADR-006 item 6).
-            io.out(`Commit the baseline with a subject that starts with baseline:.\nnext: ${runCommand(cfg.cli.run, "baseline write")}\n`);
+            // REQ-ADOPT-002 adopt writes no baseline. The gate step is a later, separate commit (044/D4, ADR-006 item 6).
+            // REQ-ADOPT-011 the last line names the context of the task that nextTask picks, or status
+            const run = cfg.cli.run;
+            io.out(`To gate the old debt later, run ${runCommand(run, "baseline write")} and commit it with a subject that starts with baseline:\n`);
+            io.out(`next: ${await nextAfterAdopt(root, run)}\n`);
         }
     }
     return 0;

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+YCBhbmQgYHNwZWNjdHggaWQgbmV3IFNDTiA8Q0FQPiAtLWZvciA8UkVRPmAuIFdoZW4gdGhlIGNoYW5nZSBuZWVkcyBzZXZlcmFsIElEcyBvZiBvbmUga2luZCwgcnVuIGBzcGVjY3R4IGlkIG5ldyAtLWNvdW50IDxuPmAgb25jZS4gR2l2ZSBldmVyeSB0YXNrIGEgYFtSRVEtLi4uXWAgY2l0YXRpb24gYW5kIGEgYFZlcmlmeTpgIGNvZGUgc3Bhbi4gVGhlbiBydW4gYHNwZWNjdHggY2hlY2sgLS1zdHJpY3RgIGFuZCBgc3BlY2N0eCBnYXRlIC0tc3RyaWN0YC4gVGhlIGdhdGUgcnVucyB0aGUgT3BlblNwZWMgdmFsaWRhdGUgYW5kIHRoZSBzcGVjLWxlbmd0aCBjaGVjay4gRml4IGV2ZXJ5IGZpbmRpbmcuIFRoZW4gcnVuIGBzcGVjY3R4IG5leHQgLS1qc29uYCBhbmQgcnVuIHRoZSBjb21tYW5kIGl0IHByaW50cy4gVGhpcyBpcyB0aGUgcGxhbiBzdG9wLiBgbmV4dGAgcmV0dXJucyBgYXNrYCB3aXRoIGBodW1hbjogdHJ1ZWAgdW50aWwgdGhlIGh1bWFuIGFwcHJvdmVzIHRoZSBxdWVzdGlvbi4gWW91IG5ldmVyIHJlc29sdmUgYSBwbGFuIHF1ZXN0aW9uIHlvdXJzZWxmLgotIGBjaXRlYDogcnVuIGBzcGVjY3R4IHF1ZXJ5IC0tY2hhbmdlIDxjPiAtLWtpbmQgcmVxYC4gQWRkIHRoZSBgW1JFUS0uLi5dYCBjaXRhdGlvbiBhbmQgYSBgVmVyaWZ5OmAgY29kZSBzcGFuIHRvIHRoZSB0YXNrIGxpbmUgbmFtZWQgaW4gYHRhc2tgLiBSdW4gYHNwZWNjdHggY2hlY2tgLiBDb250aW51ZS4KLSBgc3RhcnRgOiBydW4gYHNwZWNjdHggdGFzayBzdGFydCA8dD5gLiBSZWFkIHRoZSBidW5kbGUgaXQgcHJpbnRzLiBDb250aW51ZS4KLSBgd29ya2A6IGltcGxlbWVudCB0aGUgdGFzay4gVGFnIGNvZGUgd2l0aCBgLy8gUkVRLS4uLmAuIFRhZyB0ZXN0cyB3aXRoIGAvLyBDb3ZlcnM6IFJFUS0uLi5gLiBUaGVuIHJ1biBgc3BlY2N0eCB0YXNrIGRvbmUgPHQ+YC4KLSBgZml4YDogcmVhZCBgcmVhc29uYC4gSXQgaG9sZHMgdGhlIHRhaWwgb2YgdGhlIGZhaWxlZCBWZXJpZnkgb3V0cHV0LiBGaXggdGhlIGNhdXNlLiBSdW4gYHNwZWNjdHggdGFzayBkb25lIDx0PmAgYWdhaW4uCi0gYHJlcGFpcmA6IHJ1biB0aGUgY29tbWFuZCBpbiB0aGUgYGNvbW1hbmRgIGZpZWxkLiBJdCBydW5zIFZlcmlmeSBhZ2FpbiBmb3IgYSB0aWNrZWQgdGFzayB3aG9zZSBldmlkZW5jZSBpcyBhYnNlbnQgb3Igc3RhbGUuCi0gYGdhdGVgOiBydW4gYHNwZWNjdHggZ2F0ZSAtLXN0cmljdGAuIEZpeCBldmVyeSBmaW5kaW5nLiBGb3IgYSBgc3RhbGUtZXZpZGVuY2VgIGZpbmRpbmcsIGdvIGJhY2sgdG8gc3RlcCAxLiBgbmV4dGAgcmV0dXJucyBgcmVwYWlyYCBhbmQgaXRzIGNvbW1hbmQgcmVwYWlycyBldmVyeSBzdGFsZSB0YXNrLiBSdW4gdGhlIGdhdGUgYWdhaW4gdW50aWwgaXQgZXhpdHMgMC4KLSBgYXJjaGl2ZWA6IHdoZW4gYGh1bWFuYCBpcyB0cnVlLCBydW4gYHNwZWNjdHggaGFuZG9mZiBhc2sgLS1jaGFuZ2UgPGM+ICJhcmNoaXZlIDxjPj8iYCBhbmQgc3RvcC4gVGhpcyBpcyB0aGUgYXJjaGl2ZSBzdG9wLiBgbmV4dGAgcmV0dXJucyBgYXNrYCB1bnRpbCB0aGUgaHVtYW4gYXBwcm92ZXMgdGhlIHF1ZXN0aW9uLiBZb3UgbmV2ZXIgcmVzb2x2ZSBhbiBhcmNoaXZlIHF1ZXN0aW9uIHlvdXJzZWxmLiBBZnRlciBhIHJlamVjdGlvbiwgYG5leHRgIHJldHVybnMgYGFyY2hpdmVgIHdpdGggYGh1bWFuOiB0cnVlYCBhZ2Fpbi4gV2hlbiBgaHVtYW5gIGlzIGZhbHNlLCB0aGUgdXNlciBhcHByb3ZlZCBvciBgW2xvb3BdIGFyY2hpdmVgIGlzIGBhdXRvYC4gVGhlbiBydW4gZWFjaCBzdGVwIHVuZGVyIGBvcGVyYXRpb25zLmFyY2hpdmUuZ3VpZGFuY2VgIGluIGBvcGVuc3BlYy9jb25maWcueWFtbGAuIFRoZW4gcnVuIHRoZSBjb21tYW5kIGluIHRoZSBgY29tbWFuZGAgZmllbGQuIFRoZW4gcnVuIGBvcGVuc3BlYyB2YWxpZGF0ZSAtLWFsbCAtLXN0cmljdGAsIGBzcGVjY3R4IGNoZWNrIC0tc3RyaWN0YCwgYW5kIGBzcGVjY3R4IGhhbmRvZmYgd3JpdGVgLgotIGBhc2tgOiBwcmludCBgcmVhc29uYC4gSXQgaXMgdGhlIG9wZW4gcXVlc3Rpb24uIFN0b3AuIFlvdSBuZXZlciByZXNvbHZlIGEgcGxhbiBvciBhcmNoaXZlIHF1ZXN0aW9uIHlvdXJzZWxmLiBUaGUgaHVtYW4gZG9lcywgd2l0aCBgc3BlY2N0eCBoYW5kb2ZmIHJlc29sdmUgPG4+IC0tYXBwcm92ZSAiPGFuc3dlcj4iYCBvciBgLS1yZWplY3QgIjxhbnN3ZXI+ImAuIEEgcmVqZWN0aW9uIGtlZXBzIHRoZSBzdG9wLiBBbnkgb3RoZXIgcXVlc3Rpb24gdGFrZXMgYHNwZWNjdHggaGFuZG9mZiByZXNvbHZlIDxuPiAiPGFuc3dlcj4iYC4KLSBgc3RvcGA6IHByaW50IGByZWFzb25gLiBTdG9wLgoKIyMgUnVsZXMKCi0gVGhpcyBza2lsbCBvdmVycmlkZXMgdHdvIHN0ZXBzIG9mIHRoZSB1cHN0cmVhbSBgb3BlbnNwZWMtcHJvcG9zZWAgc2tpbGwuIEl0IHJlYWRzIHNwZWNzIHdpdGggYHNwZWNjdHggYnVuZGxlYCBvciBgc3BlY2N0eCBxdWVyeWAsIG5vdCBgb3BlbnNwZWMgc2hvd2AuIEl0IG5ldmVyIHJ1bnMgdGhlIGNsb3NpbmcgYC9vcHN4OmFwcGx5YC4KLSBOZXZlciB0aWNrIGEgY2hlY2tib3ggYnkgaGFuZC4gYHNwZWNjdHggdGFzayBkb25lYCBpcyB0aGUgb25seSB3YXkgYSB0YXNrIGNsb3Nlcy4KLSBOZXZlciB1c2UgYC0tbWFudWFsYCBvbiBhIHRhc2sgd2l0aCBhIFZlcmlmeSBjb21tYW5kLgotIE5ldmVyIGNhbGwgYC9vcHN4OmFwcGx5YC4gVGhpcyBza2lsbCByZXBsYWNlcyBpdC4KLSBUbyB3cml0ZSBhIE1PRElGSUVEIGJsb2NrLCBydW4gYHNwZWNjdHggYnVuZGxlIDxSRVE+IC0tYmxvY2tgLiBJdCBwcmludHMgdGhlIGJsb2NrIGFzIGl0IHNpdHMgaW4gdGhlIHNwZWMgZmlsZS4gQSBNT0RJRklFRCBibG9jayBrZWVwcyBldmVyeSBzY2VuYXJpbyB0aXRsZSB1bmNoYW5nZWQuCi0gYGdhdGVgIGNvdW50cyB0aGUgUmVmcyBsaW5lIGluIHRoZSA1MDAgY2hhcmFjdGVycyBvZiBhIHJlcXVpcmVtZW50LgotIFRoZSBDSEFOR0VMT0cgZW50cnkgZ29lcyB1bmRlciBgIyMgVW5yZWxlYXNlZGAsIG5ldmVyIHVuZGVyIGEgcmVsZWFzZWQgdmVyc2lvbi4KLSBBZnRlciBhbiBlZGl0IHVuZGVyIGBza2lsbHMvYCwgcnVuIGBidW4gcnVuIGJ1aWxkICYmIG5vZGUgZGlzdC9jbGkuanMgaW5pdCAtLXNraWxscyAtLWZvcmNlYCB0byByZWZyZXNoIHRoZSBjb3BpZXMuCi0gTmV2ZXIgcmVhZCBgb3BlbnNwZWMvc3BlY3MvYCBvciBgb3BlbnNwZWMvY2hhbmdlcy8qL3NwZWNzL2AgZGlyZWN0bHkuIFVzZSB0aGUgYnVuZGxlIGZyb20gYHRhc2sgc3RhcnRgIG9yIGBzcGVjY3R4IGJ1bmRsZSA8aWQ+YC4KLSBTdG9wIG9uIGFueSBgYWN0aW9uYCBub3QgaW4gdGhlIGxpc3QgYWJvdmUuIFByaW50IHRoZSBvYmplY3QgYW5kIGFzayB0aGUgdXNlci4KLSBLZWVwIG5vIHN0YXRlIGluIHlvdXIgY29udGV4dC4gQSBuZXcgc2Vzc2lvbiBzdGFydHMgdGhlIHNhbWUgbG9vcCBhZ2FpbiB3aXRoIHN0ZXAgMS4K",
+    "skills/specctx-run/SKILL.md": "LS0tCm5hbWU6IHNwZWNjdHgtcnVuCmRlc2NyaXB0aW9uOiBSdW4gdGhlIHNwZWMtY3R4IGxvb3AgaW4gYW4gT3BlblNwZWMgcHJvamVjdC4gVXNlIG9uICJydW4iLCAiY29udGludWUiLCAibmV4dCB0YXNrIiwgImJ1aWxkIHRoaXMiLCAiY2Fycnkgb24iLCBhbmQgb24gYSBmaXJzdCBtZXNzYWdlIHRoYXQgZGVzY3JpYmVzIGEgY2hhbmdlIHRvIGJ1aWxkLiBUaGUgZW5naW5lIHBpY2tzIHRoZSBuZXh0IGFjdGlvbi4gVGhlIHNraWxsIGFjdHMgb24gaXQgdW50aWwgdGhlIGNoYW5nZSByZWFjaGVzIHRoZSBhcmNoaXZlIG9yIGEgaHVtYW4gbXVzdCBkZWNpZGUuCi0tLQoKIyBzcGVjY3R4LXJ1bgoKUnVuIGBzcGVjY3R4YCBhcyBgbnB4IHNwZWMtY3R4YCB3aGVuIGl0IGlzIG5vdCBpbnN0YWxsZWQuIGBvcGVuc3BlY2AgaXMgdGhlIGNvbW1hbmQgaW4gYFtnYXRlXSBvcGVuc3BlY2Agb2YgYHNwZWMtY3R4LnRvbWxgLiBXaGVuIHRoYXQga2V5IGlzIGFic2VudCwgYG9wZW5zcGVjYCBpcyBgbnB4IC15IEBmaXNzaW9uLWFpL29wZW5zcGVjQGxhdGVzdGAuCgojIyBUaGUgbG9vcAoKMS4gUnVuIGBzcGVjY3R4IG5leHQgLS1qc29uYC4gUmVhZCBgYWN0aW9uYCwgYGNoYW5nZWAgKGA8Yz5gKSwgYHRhc2tgIChgPHQ+YCksIGBjb21tYW5kYCwgYHJlYXNvbmAsIGFuZCBgaHVtYW5gLgoyLiBBY3Qgb24gYGFjdGlvbmAgYXMgdGhlIHRhYmxlIGJlbG93IHNheXMuCjMuIFJ1biBgc3BlY2N0eCBoYW5kb2ZmIHdyaXRlYC4KNC4gUmVwZWF0IGZyb20gc3RlcCAxIHVudGlsIGBhY3Rpb25gIGlzIGBzdG9wYCBvciBgaHVtYW5gIGlzIHRydWUuCgojIyBBY3Rpb25zCgotIGBwbGFuYDogdGFrZSB0aGUgY2hhbmdlIG5hbWUgZnJvbSB0aGUgcmVxdWVzdCBvZiB0aGUgdXNlciBpbiBrZWJhYiBjYXNlLiBUaGF0IG5hbWUgaXMgYDxjPmAuIEZvbGxvdyB0aGUgdXBzdHJlYW0gYG9wZW5zcGVjLXByb3Bvc2VgIHNraWxsIGZvciBgPGM+YC4gUmVhZCBleGlzdGluZyByZXF1aXJlbWVudHMgd2l0aCBgc3BlY2N0eCBidW5kbGUgPGlkPmAgb3IgYHNwZWNjdHggcXVlcnlgLCBuZXZlciBgb3BlbnNwZWMgc2hvd2AuIFRha2UgZXZlcnkgSUQgZnJvbSBgc3BlY2N0eCBpZCBuZXcgUkVRIDxDQVA+YCBhbmQgYHNwZWNjdHggaWQgbmV3IFNDTiA8Q0FQPiAtLWZvciA8UkVRPmAuIGBpZCBuZXdgIHJlc2VydmVzIG5vdGhpbmcuIEEgc2Vjb25kIGNhbGwgYmVmb3JlIGBzcGVjY3R4IGJ1aWxkYCByZXR1cm5zIHRoZSBzYW1lIElELiBXaGVuIHRoZSBjaGFuZ2UgbmVlZHMgc2V2ZXJhbCBJRHMgb2Ygb25lIGtpbmQsIHJ1biBgc3BlY2N0eCBpZCBuZXcgLS1jb3VudCA8bj5gIG9uY2UuIEdpdmUgZXZlcnkgdGFzayBhIGBbUkVRLS4uLl1gIGNpdGF0aW9uIGFuZCBhIGBWZXJpZnk6YCBjb2RlIHNwYW4uIFRoZW4gcnVuIGBzcGVjY3R4IGNoZWNrIC0tc3RyaWN0YCBhbmQgYHNwZWNjdHggZ2F0ZSAtLXN0cmljdGAuIFRoZSBnYXRlIHJ1bnMgdGhlIE9wZW5TcGVjIHZhbGlkYXRlIGFuZCB0aGUgc3BlYy1sZW5ndGggY2hlY2suIEZpeCBldmVyeSBmaW5kaW5nLiBUaGVuIHJ1biBgc3BlY2N0eCBuZXh0IC0tanNvbmAgYW5kIHJ1biB0aGUgY29tbWFuZCBpdCBwcmludHMuIFRoaXMgaXMgdGhlIHBsYW4gc3RvcC4gYG5leHRgIHJldHVybnMgYGFza2Agd2l0aCBgaHVtYW46IHRydWVgIHVudGlsIHRoZSBodW1hbiBhcHByb3ZlcyB0aGUgcXVlc3Rpb24uIFlvdSBuZXZlciByZXNvbHZlIGEgcGxhbiBxdWVzdGlvbiB5b3Vyc2VsZi4KLSBgY2l0ZWA6IHJ1biBgc3BlY2N0eCBxdWVyeSAtLWNoYW5nZSA8Yz4gLS1raW5kIHJlcWAuIEFkZCB0aGUgYFtSRVEtLi4uXWAgY2l0YXRpb24gYW5kIGEgYFZlcmlmeTpgIGNvZGUgc3BhbiB0byB0aGUgdGFzayBsaW5lIG5hbWVkIGluIGB0YXNrYC4gUnVuIGBzcGVjY3R4IGNoZWNrYC4gQ29udGludWUuCi0gYHN0YXJ0YDogcnVuIGBzcGVjY3R4IHRhc2sgc3RhcnQgPHQ+YC4gUmVhZCB0aGUgYnVuZGxlIGl0IHByaW50cy4gRWFjaCBjYXJkIGVuZHMgd2l0aCB0cnVzdCBsYWJlbHMuIEFjdCBvbiBhIGxpbmUgbWFya2VkIGB2ZXJpZmllZGAgb3IgYGZyZXNoYC4gUmVyZWFkIGEgbGluZSBtYXJrZWQgYHN0YWxlIHNpbmNlYCwgYHVudmVyaWZpZWRgLCBvciBgbm8gZXZpZGVuY2VgIHdpdGggYHNwZWNjdHggYnVuZGxlIDxJRD5gIGJlZm9yZSB5b3UgYnVpbGQgb24gaXQuIENvbnRpbnVlLgotIGB3b3JrYDogaW1wbGVtZW50IHRoZSB0YXNrLiBUYWcgY29kZSB3aXRoIGAvLyBSRVEtLi4uYC4gVGFnIHRlc3RzIHdpdGggYC8vIENvdmVyczogUkVRLS4uLmAuIFRoZW4gcnVuIGBzcGVjY3R4IHRhc2sgZG9uZSA8dD5gLgotIGBmaXhgOiByZWFkIGByZWFzb25gLiBJdCBob2xkcyB0aGUgdGFpbCBvZiB0aGUgZmFpbGVkIFZlcmlmeSBvdXRwdXQuIEZpeCB0aGUgY2F1c2UuIFJ1biBgc3BlY2N0eCB0YXNrIGRvbmUgPHQ+YCBhZ2Fpbi4KLSBgcmVwYWlyYDogcnVuIHRoZSBjb21tYW5kIGluIHRoZSBgY29tbWFuZGAgZmllbGQuIEl0IHJ1bnMgVmVyaWZ5IGFnYWluIGZvciBhIHRpY2tlZCB0YXNrIHdob3NlIGV2aWRlbmNlIGlzIGFic2VudCBvciBzdGFsZS4KLSBgZ2F0ZWA6IHJ1biBgc3BlY2N0eCBnYXRlIC0tc3RyaWN0YC4gRml4IGV2ZXJ5IGZpbmRpbmcuIEZvciBhIGBzdGFsZS1ldmlkZW5jZWAgZmluZGluZywgZ28gYmFjayB0byBzdGVwIDEuIGBuZXh0YCByZXR1cm5zIGByZXBhaXJgIGFuZCBpdHMgY29tbWFuZCByZXBhaXJzIGV2ZXJ5IHN0YWxlIHRhc2suIFJ1biB0aGUgZ2F0ZSBhZ2FpbiB1bnRpbCBpdCBleGl0cyAwLgotIGBhcmNoaXZlYDogd2hlbiBgaHVtYW5gIGlzIHRydWUsIHJ1biBgc3BlY2N0eCBoYW5kb2ZmIGFzayAtLWNoYW5nZSA8Yz4gImFyY2hpdmUgPGM+PyJgIGFuZCBzdG9wLiBUaGlzIGlzIHRoZSBhcmNoaXZlIHN0b3AuIGBuZXh0YCByZXR1cm5zIGBhc2tgIHVudGlsIHRoZSBodW1hbiBhcHByb3ZlcyB0aGUgcXVlc3Rpb24uIFlvdSBuZXZlciByZXNvbHZlIGFuIGFyY2hpdmUgcXVlc3Rpb24geW91cnNlbGYuIEFmdGVyIGEgcmVqZWN0aW9uLCBgbmV4dGAgcmV0dXJucyBgYXJjaGl2ZWAgd2l0aCBgaHVtYW46IHRydWVgIGFnYWluLiBXaGVuIGBodW1hbmAgaXMgZmFsc2UsIHRoZSB1c2VyIGFwcHJvdmVkIG9yIGBbbG9vcF0gYXJjaGl2ZWAgaXMgYGF1dG9gLiBUaGVuIHJ1biBlYWNoIHN0ZXAgdW5kZXIgYG9wZXJhdGlvbnMuYXJjaGl2ZS5ndWlkYW5jZWAgaW4gYG9wZW5zcGVjL2NvbmZpZy55YW1sYC4gVGhlbiBydW4gdGhlIGNvbW1hbmQgaW4gdGhlIGBjb21tYW5kYCBmaWVsZC4gVGhlbiBydW4gYG9wZW5zcGVjIHZhbGlkYXRlIC0tYWxsIC0tc3RyaWN0YCwgYHNwZWNjdHggY2hlY2sgLS1zdHJpY3RgLCBhbmQgYHNwZWNjdHggaGFuZG9mZiB3cml0ZWAuCi0gYGFza2A6IHByaW50IGByZWFzb25gLiBJdCBpcyB0aGUgb3BlbiBxdWVzdGlvbi4gU3RvcC4gWW91IG5ldmVyIHJlc29sdmUgYSBwbGFuIG9yIGFyY2hpdmUgcXVlc3Rpb24geW91cnNlbGYuIFRoZSBodW1hbiBkb2VzLCB3aXRoIGBzcGVjY3R4IGhhbmRvZmYgcmVzb2x2ZSA8bj4gLS1hcHByb3ZlICI8YW5zd2VyPiJgIG9yIGAtLXJlamVjdCAiPGFuc3dlcj4iYC4gQSByZWplY3Rpb24ga2VlcHMgdGhlIHN0b3AuIEFueSBvdGhlciBxdWVzdGlvbiB0YWtlcyBgc3BlY2N0eCBoYW5kb2ZmIHJlc29sdmUgPG4+ICI8YW5zd2VyPiJgLgotIGBzdG9wYDogcHJpbnQgYHJlYXNvbmAuIFN0b3AuCgojIyBSdWxlcwoKLSBUaGlzIHNraWxsIG92ZXJyaWRlcyB0d28gc3RlcHMgb2YgdGhlIHVwc3RyZWFtIGBvcGVuc3BlYy1wcm9wb3NlYCBza2lsbC4gSXQgcmVhZHMgc3BlY3Mgd2l0aCBgc3BlY2N0eCBidW5kbGVgIG9yIGBzcGVjY3R4IHF1ZXJ5YCwgbm90IGBvcGVuc3BlYyBzaG93YC4gSXQgbmV2ZXIgcnVucyB0aGUgY2xvc2luZyBgL29wc3g6YXBwbHlgLgotIE5ldmVyIHRpY2sgYSBjaGVja2JveCBieSBoYW5kLiBgc3BlY2N0eCB0YXNrIGRvbmVgIGlzIHRoZSBvbmx5IHdheSBhIHRhc2sgY2xvc2VzLgotIE5ldmVyIHVzZSBgLS1tYW51YWxgIG9uIGEgdGFzayB3aXRoIGEgVmVyaWZ5IGNvbW1hbmQuCi0gTmV2ZXIgY2FsbCBgL29wc3g6YXBwbHlgLiBUaGlzIHNraWxsIHJlcGxhY2VzIGl0LgotIFRvIHdyaXRlIGEgTU9ESUZJRUQgYmxvY2ssIHJ1biBgc3BlY2N0eCBidW5kbGUgPFJFUT4gLS1ibG9ja2AuIEl0IHByaW50cyB0aGUgYmxvY2sgYXMgaXQgc2l0cyBpbiB0aGUgc3BlYyBmaWxlLiBBIE1PRElGSUVEIGJsb2NrIGtlZXBzIGV2ZXJ5IHNjZW5hcmlvIHRpdGxlIHVuY2hhbmdlZC4KLSBgZ2F0ZWAgY291bnRzIHRoZSBSZWZzIGxpbmUgaW4gdGhlIDUwMCBjaGFyYWN0ZXJzIG9mIGEgcmVxdWlyZW1lbnQuCi0gVGhlIENIQU5HRUxPRyBlbnRyeSBnb2VzIHVuZGVyIGAjIyBVbnJlbGVhc2VkYCwgbmV2ZXIgdW5kZXIgYSByZWxlYXNlZCB2ZXJzaW9uLgotIEFmdGVyIGFuIGVkaXQgdW5kZXIgYHNraWxscy9gLCBydW4gYGJ1biBydW4gYnVpbGQgJiYgbm9kZSBkaXN0L2NsaS5qcyBpbml0IC0tc2tpbGxzIC0tZm9yY2VgIHRvIHJlZnJlc2ggdGhlIGNvcGllcy4KLSBOZXZlciByZWFkIGBvcGVuc3BlYy9zcGVjcy9gIG9yIGBvcGVuc3BlYy9jaGFuZ2VzLyovc3BlY3MvYCBkaXJlY3RseS4gVXNlIHRoZSBidW5kbGUgZnJvbSBgdGFzayBzdGFydGAgb3IgYHNwZWNjdHggYnVuZGxlIDxpZD5gLgotIFN0b3Agb24gYW55IGBhY3Rpb25gIG5vdCBpbiB0aGUgbGlzdCBhYm92ZS4gUHJpbnQgdGhlIG9iamVjdCBhbmQgYXNrIHRoZSB1c2VyLgotIEtlZXAgbm8gc3RhdGUgaW4geW91ciBjb250ZXh0LiBBIG5ldyBzZXNzaW9uIHN0YXJ0cyB0aGUgc2FtZSBsb29wIGFnYWluIHdpdGggc3RlcCAxLgo=",
 };

package/dist/cli/commands.js

@@ -83,6 +83,9 @@ export async function run(p, io) {
     if (cmd === "report") {
         if (p.positional.length)
             throw new UsageExit("report takes no arguments");
+        // REQ-JRN-008 report prints Markdown only
+        if (json)
+            throw new UsageExit("report takes no --json flag");
         const { buildReport } = await import("../journal/report.js");
         const { VERSION } = await import("../version.js");
         io.out(buildReport(root, new Date(), { version: VERSION, node: process.version, platform: process.platform, arch: process.arch }).text);
@@ -321,8 +324,10 @@ export async function run(p, io) {
                 const { reqBlocks } = await import("../graph/bundle.js");
                 const text = reqBlocks(root, p.positional.map((i) => ids.get(i)));
                 // REQ-QRY-019 block mode has no budget, so budget is null and the text is complete (050/D6)
+                // REQ-QRY-026 block mode has no budget, so used equals chars and no block is listed
+                const n = (await import("../util/pystr.js")).cpLen(text);
                 if (json)
-                    print({ text, omitted: [], chars: (await import("../util/pystr.js")).cpLen(text), budget: null, complete: true });
+                    print({ text, omitted: [], body_omitted: [], chars: n, budget: null, complete: true, used: n, blocks: [] });
                 else
                     io.out(text);
                 return 0;
@@ -396,18 +401,23 @@ async function init(p, io) {
             return defaults().cli.run;
         }
     })();
+    // REQ-DIST-017 the next command comes from the state of the specs
+    const { detectNext } = await import("../init/next.js");
+    const d = detectNext(root, run);
+    const summary = d.summary ? `${d.summary}\n` : "";
     if (p.flags.json)
-        io.out(JSON.stringify(r, null, 2) + "\n");
+        io.out(JSON.stringify({ ...r, needs_id: d.needs_id, next: d.next }, null, 2) + "\n");
     else if (r.nothing)
-        io.out("nothing to do\n" + r.notes.map((n) => `${n}\n`).join("") + paint("dim", `next: ${runCommand(run, "status")}\n`, io.tty));
+        io.out("nothing to do\n" + r.notes.map((n) => `${n}\n`).join("") + summary + paint("dim", `next: ${d.next}\n`, io.tty));
     else {
         io.out(r.written.map((w) => `wrote ${w}\n`).join(""));
         io.out(r.merged.map((m) => `merged ${m}\n`).join(""));
         io.out(r.kept.map((k) => `kept ${k}\n`).join(""));
         io.out(r.notes.map((n) => `${n}\n`).join(""));
+        io.out(summary);
         // REQ-CLI-007 init ends with the next step. REQ-DIST-002 a kept changed file points to --force (014/D2).
         const again = [runCommand(run, "init"), all ? "--all" : [p.flags.schema ? "--schema" : "", p.flags.skills ? "--skills" : ""].filter(Boolean).join(" "), "--force"].filter(Boolean).join(" ");
-        io.out(paint("dim", `next: ${r.changed.length ? again : runCommand(run, "status")}\n`, io.tty));
+        io.out(paint("dim", `next: ${r.changed.length ? again : d.next}\n`, io.tty));
     }
     return 0;
 }

package/dist/cli/gate.js

@@ -2,6 +2,7 @@
 import { spawnSync } from "node:child_process";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join, resolve, sep } from "node:path";
+import { childEnv } from "../util/env.js";
 import { anyMatch, globRe } from "../util/glob.js";
 import { cmpStr } from "../util/pystr.js";
 const SKIP = new Set(["node_modules", ".git", ".ctx", "dist", "build"]);
@@ -93,7 +94,7 @@ async function gateSteps(root, o, io, ran) {
     io.out(`linters: ok (${files} file(s)${baselined ? `, ${baselined} baselined` : ""})\n`);
     ran.push("validate");
     // gate 4: openspec validate with the command the caller resolved (018/D2)
-    const v = spawnSync("/bin/sh", ["-c", `${o.openspec} validate --all${o.strict ? " --strict" : ""} --no-interactive`], { cwd: root, encoding: "utf8" });
+    const v = spawnSync("/bin/sh", ["-c", `${o.openspec} validate --all${o.strict ? " --strict" : ""} --no-interactive`], { cwd: root, encoding: "utf8", env: childEnv() /* REQ-DIST-016 */ });
     if (v.status !== 0) {
         io.out("validate: fail\n" + (v.stdout ?? "") + (v.stderr ?? ""));
         return "validate";

package/dist/cli/help.js

@@ -40,7 +40,7 @@ export const TABLE = [
     {
         name: "context", group: "Read", args: "<task|ID|path|change>", summary: "Print what an agent needs before it edits a task, an ID, a file, or a change.",
         flags: [
-            ["--budget <n>", "Keep the blocks to n characters. A requested block always prints, also when it is longer. Then the over budget line gives the size. The truncated line is not in this limit. The default is 8000."],
+            ["--budget <n>", "Keep the blocks to n characters. Each entry prints its card first. A card ends with its trust labels: the provenance and the evidence state. A card can end with | body omitted. Run bundle with its ID to get the body. A requested block always prints, also when it is longer. Then the over budget line gives the size. The truncated line names the entries that have no card. It is not in this limit. The default is 8000."],
             ["--depth <n>", "Follow links n steps. The default is 1."],
         ],
         exit: [OK, ["2", "A usage error, an unknown ID, or a bad path. It takes one input. Use `bundle` for several inputs or for `--block`."], INTERNAL], example: "specctx context 045/2.1",
@@ -53,7 +53,7 @@ export const TABLE = [
     {
         name: "bundle", group: "Read", args: "<ID|path|change...>", summary: "Print the spec text for the IDs, files, or changes and their links.",
         flags: [
-            ["--budget <n>", "Keep the blocks to n characters. A requested block always prints, also when it is longer. Then the over budget line gives the size. The truncated line is not in this limit. The default is 8000."],
+            ["--budget <n>", "Keep the blocks to n characters. Each entry prints its card first. A card ends with its trust labels: the provenance and the evidence state. A card can end with | body omitted. Run bundle with its ID to get the body. A requested block always prints, also when it is longer. Then the over budget line gives the size. The truncated line names the entries that have no card. It is not in this limit. 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."],
@@ -93,7 +93,7 @@ export const TABLE = [
     {
         name: "report", group: "Read", args: "", summary: "Print a bug report from the run journal in .ctx/local. Review it, then file it with `gh issue create`. Write nothing.",
         flags: [],
-        exit: [OK, ["2", "A usage error."], INTERNAL], example: "specctx report > report.md",
+        exit: [OK, ["2", "A usage error. The command has no JSON output."], INTERNAL], example: "specctx report > report.md",
     },
     {
         name: "lint tells", group: "Read", args: "<file...>", summary: "Find the AI writing tells in markdown files. Read stdin when no file is given.",
@@ -106,8 +106,8 @@ export const TABLE = [
     // Write
     { name: "build", group: "Write", args: "", summary: "Write the index to .ctx/index.json.", flags: [], exit: PLAIN, example: "specctx build" },
     {
-        name: "id new", group: "Write", args: "<kind> <code>", summary: "Print the next free ID. The kind is REQ, SCN, ADR, or DEC.",
-        flags: [["--for <REQ-ID>", "Give the requirement of a new scenario."], ["--count <n>", "Print n IDs in sequence."]],
+        name: "id new", group: "Write", args: "<kind> <code>", summary: "Print the next free ID. The kind is REQ, SCN, ADR, or DEC. A second call before `build` prints the same ID.",
+        flags: [["--for <REQ-ID>", "Give the requirement of a new scenario."], ["--count <n>", "Print n IDs in sequence. Use it to get several IDs before `build`."]],
         exit: [OK, ["2", "A usage error or an unknown code."], INTERNAL], example: "specctx id new REQ IDX",
     },
     {
@@ -211,7 +211,9 @@ export const HELP = overview();
 /** REQ-CLI-006 the page of one command: Usage, Flags, Exit codes, Example. */
 export function commandPage(c) {
     const lint = c.name.startsWith("lint ");
-    const flags = lint ? c.flags : [...c.flags, ...GLOBAL];
+    // REQ-JRN-008 the report page lists no --json, because report has no JSON output
+    const global = c.name === "report" ? GLOBAL.filter(([f]) => f !== "--json") : GLOBAL;
+    const flags = lint ? c.flags : [...c.flags, ...global];
     const out = [
         `specctx ${c.name}: ${c.summary}`,
         "",

package/dist/graph/bundle.js

@@ -1,7 +1,9 @@
 // REQ-QRY-003 canonical text with one provenance line per block, in a fixed order, within a budget.
-import { join } from "node:path";
+import { statSync } from "node:fs";
+import { isAbsolute, join, normalize } from "node:path";
 import { canon, poolOf } from "../index/canonical.js";
 import { blockRange, readText } from "../index/scan.js";
+import { Trust, provenanceClass, taggedReq } from "./trust.js";
 import { cmpStr, cmpTuple, cpLen, pyStrip, splitLines } from "../util/pystr.js";
 import { KIND_RANK, mainVersion, walkFound } from "./related.js";
 export class Lines {
@@ -42,8 +44,8 @@ function rstrip(s) {
     const t = pyStrip("x" + s);
     return t.slice(1);
 }
-export function provenance(e, reason) {
-    return `-- ${e.id} | ${e.file}:${e.line} | ${e.status} | ${reason}\n`;
+export function provenance(e, reason, trust = "") {
+    return `-- ${e.id} | ${e.file}:${e.line} | ${e.status} | ${reason}${trust}\n`;
 }
 /** REQ-JRN-002 the ID of a provenance line, or null. It anchors on the start of `provenance()` (057/D3). */
 export function parseProvenance(line) {
@@ -194,34 +196,145 @@ export function bundle(root, entries0, wanted, budget, depth, opts = {}) {
             blocks.push([m, `main version of ${r2}`, cls]);
     }
     const files = new Lines(root);
-    const texts = blocks.map(([e, reason]) => {
+    // REQ-QRY-020 one state per block: 0 none, 1 card, 2 full. The fill sets it and the output reads it in print order.
+    // REQ-QRY-023 REQ-QRY-024 REQ-QRY-025 the trust columns of each card (062/D1 to D5)
+    const trust = new Trust(root, entries);
+    const labels = (e, reason) => {
+        let prov = provenanceClass(reason);
+        if (prov === "tagged" && (e.kind === "code" || e.kind === "test")) {
+            const r = taggedReq(reason);
+            if (r && trust.lineVerified(e.file, r))
+                prov = "verified";
+        }
+        let ev = null;
+        if (e.kind === "task")
+            ev = trust.taskState(e.id);
+        else if (e.kind === "req")
+            ev = trust.reqState(e.id);
+        return { provenance: prov, evidence: ev };
+    };
+    const blk = blocks.map(([e, reason, cls]) => {
         const body = blockText(e, files);
-        // a blank line closes a block with a body. Code and test paths stay one line each.
-        return provenance(e, reason) + body + (body ? "\n" : "");
+        const l = labels(e, reason);
+        const suffix = ` | ${l.provenance}` + (l.evidence ? ` | ${l.evidence}` : "");
+        return { id: e.id, head: provenance(e, reason, suffix), body: body ? body + "\n" : "", cls, st: 0,
+            info: { id: e.id, file: e.file, line: e.line, status: e.status, reason, ...l } };
     });
-    // REQ-QRY-018 the blocks of the first loop always stay: each requested block and the main version of a requested ID (050/D2, 050/D3)
-    const keep = blocks.map((_, k) => k < pinned);
+    // REQ-QRY-021 the files that a requested task names, as class 1 cards after the code and test lines (060/D4)
+    const named = [];
+    if (depth >= 1) {
+        const taken = new Set(blocks.filter(([e]) => e.kind === "code" || e.kind === "test").map(([e]) => e.file));
+        for (const t of wanted) {
+            const te = ids.get(t);
+            if (te?.kind !== "task")
+                continue;
+            for (const path of te.paths ?? []) {
+                if (taken.has(path) || !isFile(root, path))
+                    continue;
+                taken.add(path);
+                named.push({ id: path, head: `-- ${path} | ${path} | active | named by ${t} | declared\n`, body: "", cls: 1, st: 0,
+                    info: { id: path, file: path, line: 0, status: "active", reason: `named by ${t}`, provenance: "declared", evidence: null } });
+            }
+        }
+    }
+    // the pinned blocks can hold a change, whose rank is above test, so the search starts after them
+    let at = blocks.findIndex(([e], k) => k >= pinned && (KIND_RANK[e.kind] ?? 9) > KIND_RANK.test);
+    if (at < 0)
+        at = blk.length;
+    blk.splice(Math.max(at, pinned), 0, ...named);
+    // REQ-QRY-018 the pinned blocks always stay, with their bodies (050/D2, 050/D3)
+    for (let k = 0; k < pinned; k++)
+        blk[k].st = 2;
     let used = 0;
     for (let k = 0; k < pinned; k++)
-        used += cpLen(texts[k]);
-    // fill the budget class by class, in print order inside a class, and skip a block that does not fit
-    for (let cls = 0; cls <= 3; cls++) {
-        for (let k = pinned; k < blocks.length; k++) {
-            if (blocks[k][2] !== cls)
+        used += cpLen(render(blk[k]));
+    const cost = (b, st) => cpLen(renderAs(b, st));
+    // fill in five steps, in print order inside each: cards of class 0, cards of class 1, bodies of class 0, cards of class 2, bodies of class 2
+    const cards = (cls) => {
+        for (let k = pinned; k < blk.length; k++) {
+            const b = blk[k];
+            if (b.cls !== cls || b.st)
                 continue;
-            const n = cpLen(texts[k]);
+            const st = b.body ? 1 : 2;
+            const n = cost(b, st);
             if (used + n > budget)
                 continue;
-            keep[k] = true;
+            b.st = st;
             used += n;
         }
+    };
+    const bodies = (cls) => {
+        for (let k = pinned; k < blk.length; k++) {
+            const b = blk[k];
+            if (b.cls !== cls || b.st !== 1)
+                continue;
+            const d = cost(b, 2) - cost(b, 1);
+            if (used + d > budget)
+                continue;
+            b.st = 2;
+            used += d;
+        }
+    };
+    cards(0);
+    cards(1);
+    bodies(0);
+    cards(2);
+    bodies(2);
+    // class 3 fills as a whole block
+    for (let k = pinned; k < blk.length; k++) {
+        const b = blk[k];
+        if (b.cls !== 3)
+            continue;
+        const n = cost(b, 2);
+        if (used + n > budget)
+            continue;
+        b.st = 2;
+        used += n;
     }
-    const omitted = blocks.filter((_, k) => !keep[k]).map(([e]) => e.id);
-    let text = texts.filter((_, k) => keep[k]).join("");
+    const omitted = blk.filter((b) => !b.st).map((b) => b.id);
+    const bodyOmitted = blk.filter((b) => b.st === 1).map((b) => b.id);
+    // REQ-QRY-022 the note of the first requested task with no requirement that the index holds. It prints after the pinned blocks.
+    let note = "";
+    if (depth >= 1) {
+        const t = wanted.find((w) => {
+            const te = ids.get(w);
+            return te?.kind === "task" && !te.refs.some((x) => ids.get(x)?.kind === "req");
+        });
+        if (t)
+            note = `note: ${t} cites no requirement that the index holds. The blocks come from its change and the paths it names. Add a [REQ-...] citation.\n`;
+    }
+    const out = blk.map((b) => render(b));
+    let text = out.slice(0, pinned).join("") + note + out.slice(pinned).join("");
+    // the budget counts the blocks, so the figure of the over budget line is their length
+    used = out.reduce((n, x) => n + cpLen(x), 0);
     if (omitted.length)
         text += `truncated: ${omitted.length} entries omitted: ${omitted.join(", ")}\n`;
     // REQ-QRY-018 the over budget line goes last, so the 0.4.1 output stays a prefix (050/D4)
     if (used > budget)
         text += `over budget: ${used} of ${budget} characters\n`;
-    return { text, omitted, chars: cpLen(text), budget, complete: omitted.length === 0 };
+    const printed = blk.filter((b) => b.st).map((b) => b.info);
+    return { text, omitted, body_omitted: bodyOmitted, chars: cpLen(text), budget, complete: omitted.length === 0 && bodyOmitted.length === 0, used, blocks: printed };
+}
+const MARKER = " | body omitted";
+function renderAs(b, st) {
+    if (st === 0)
+        return "";
+    if (st === 1 && b.body)
+        return b.head.slice(0, -1) + MARKER + "\n";
+    return b.head + b.body;
+}
+function render(b) {
+    return renderAs(b, b.st);
+}
+/** REQ-QRY-021 true when the path is a file under the root. */
+function isFile(root, path) {
+    const n = normalize(path);
+    if (isAbsolute(n) || n.startsWith(".."))
+        return false;
+    try {
+        return statSync(join(root, n)).isFile();
+    }
+    catch {
+        return false;
+    }
 }

package/dist/graph/files.js

@@ -24,7 +24,8 @@ export function fileEdges(entries, path) {
         for (const r of e.refs)
             push(g, r, `${verb}, tag at ${e.file}:${e.line}`);
     }
-    const mentions = entries.filter((e) => e.kind === "task" && e.canonical && (e.paths ?? []).includes(path));
+    // REQ-QRY-021 an archived task names paths too, but it is no mention
+    const mentions = entries.filter((e) => e.kind === "task" && e.canonical && !e.file.includes("/archive/") && (e.paths ?? []).includes(path));
     for (const e of mentions)
         push(2, e.id, "mentions, in task line");
     return groups.flatMap((g) => g.sort((a, b) => cmpStr(a[0], b[0])));

package/dist/graph/related.js

@@ -8,7 +8,7 @@ import { structuralEdges, structure } from "./links.js";
 export const KIND_RANK = { adr: 0, decision: 1, req: 2, scn: 2, task: 3, code: 4, test: 5, cap: 6, change: 7 };
 export const REASONS = [
     "scenario of", "ref from", "ref to", "decision for", "task cites", "implements", "covers", "mentions",
-    "delta in", "design named in", "task names", "capability of", "requirement in", "capability touched by", "main version of",
+    "delta in", "design named in", "task names", "capability of", "requirement in", "capability touched by", "main version of", "named by",
 ];
 /** The walk behind `related` and `bundle`. The map keeps the insertion order and the depth of each entry (046/D7). */
 export function walkFound(entries, start, depth, all = false) {

package/dist/graph/trust.js

@@ -0,0 +1,114 @@
+// REQ-QRY-023 REQ-QRY-024 REQ-QRY-025 the trust labels of a card: the provenance class and the evidence state.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { staleOf } from "../check/evidence.js";
+import { evidenceRel } from "../tasks/tasks.js";
+import { fileSha256 } from "../util/hash.js";
+const TAGGED = ["implements", "covers", "tag at"];
+const STRUCTURAL = ["delta in", "design named in", "task names", "capability of", "requirement in", "capability touched by", "main version of"];
+/** REQ-QRY-023 the class of a reason, by its prefix (062/D1). An unknown prefix is declared. */
+export function provenanceClass(reason) {
+    if (TAGGED.some((p) => reason.startsWith(p)))
+        return "tagged";
+    if (STRUCTURAL.some((p) => reason.startsWith(p)))
+        return "structural";
+    return "declared";
+}
+/**
+ * The trust state of one bundle run. It reads each evidence file at most once and hashes each file at most once
+ * (062/D3). It writes nothing.
+ */
+export class Trust {
+    tasks = new Map();
+    citing = new Map();
+    states = new Map();
+    evidence = new Map();
+    hashes = new Map();
+    root;
+    constructor(root, entries) {
+        this.root = root;
+        for (const e of entries) {
+            if (e.kind !== "task")
+                continue;
+            // an active copy wins over an archived one, as check does
+            const cur = this.tasks.get(e.id);
+            if (!cur || (cur.file.includes("/archive/") && !e.file.includes("/archive/")))
+                this.tasks.set(e.id, e);
+        }
+        for (const t of this.tasks.values()) {
+            for (const r of t.refs) {
+                const l = this.citing.get(r) ?? [];
+                l.push(t.id);
+                this.citing.set(r, l);
+            }
+        }
+    }
+    readEvidence(task) {
+        if (this.evidence.has(task))
+            return this.evidence.get(task);
+        const p = join(this.root, evidenceRel({ id: task }));
+        let ev = null;
+        if (existsSync(p)) {
+            try {
+                const j = JSON.parse(readFileSync(p, "utf8"));
+                ev = { files: j.files ?? {} };
+            }
+            catch {
+                ev = null;
+            }
+        }
+        this.evidence.set(task, ev);
+        return ev;
+    }
+    hash(path) {
+        if (!this.hashes.has(path))
+            this.hashes.set(path, fileSha256(join(this.root, path)));
+        return this.hashes.get(path);
+    }
+    /** REQ-QRY-024 fresh, stale since the first stale path, or no evidence (062/D2). Never the word current. */
+    taskState(id) {
+        if (this.states.has(id))
+            return this.states.get(id);
+        const t = this.tasks.get(id);
+        let s = "no evidence";
+        if (t && t.status === "done" && existsSync(join(this.root, evidenceRel({ id })))) {
+            // a damaged file is stale as a whole, as check reports it, so the decision rests on the file and not on the parse
+            if (t.file.includes("/archive/"))
+                s = "fresh";
+            else {
+                const stale = staleOf(this.root, id);
+                s = stale ? `stale since ${stale}` : "fresh";
+            }
+        }
+        this.states.set(id, s);
+        return s;
+    }
+    /** REQ-QRY-025 verified when one citing task is fresh, with an early stop (062/D3) */
+    reqState(id) {
+        for (const t of this.citing.get(id) ?? [])
+            if (this.taskState(t) === "fresh")
+                return "verified";
+        return "unverified";
+    }
+    /**
+     * REQ-QRY-023 a tagged line is verified when a done task that cites its requirement lists the file in its
+     * evidence with the current hash (062/D1a). An archived task counts too, so a changed line never reads verified.
+     */
+    lineVerified(file, req) {
+        for (const t of this.citing.get(req) ?? []) {
+            const task = this.tasks.get(t);
+            if (!task || task.status !== "done")
+                continue;
+            const ev = this.readEvidence(t);
+            const want = ev?.files[file];
+            if (want && this.hash(file) === want)
+                return true;
+        }
+        return false;
+    }
+}
+/** REQ-QRY-023 the requirement that a tagged reason names, or null */
+export function taggedReq(reason) {
+    const m = /^(?:implements|covers) (\S+)/.exec(reason);
+    return m ? m[1] : null;
+}

package/dist/index/scan.js

@@ -309,8 +309,8 @@ export function scanMarkdown(sc, rpath, entries, problems) {
                 id: tid, kind: "task", file: rpath, line: i, title: pyStrip(body), change,
                 status: pyStrip(box).toLowerCase() === "x" ? "done" : "open", refs: reqs,
             });
-            // REQ-IDX-009 an active task records the paths that its line names in backticks
-            const paths = status === "archived" ? [] : taskPaths(body);
+            // REQ-IDX-009 a task of any change records the paths that its line names in backticks
+            const paths = taskPaths(body);
             if (paths.length)
                 t.paths = paths;
             entries.push(t);

package/dist/init/init.js

@@ -6,6 +6,7 @@ import { ASSETS } from "../assets.generated.js";
 import { UsageExit } from "../cli/errors.js";
 import { CONFIG_FILE, DEFAULT_OPENSPEC, INIT_TEXT } from "../config.js";
 import { loadConfigOrExit } from "../cli/config.js";
+import { childEnv } from "../util/env.js";
 import { VERSION } from "../version.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). */
@@ -31,7 +32,7 @@ export function detectOpenspec(timeoutMs = DETECT_TIMEOUT_MS) {
     if (env !== undefined && env.trim())
         return { command: env };
     const [cmd, ...args] = DEFAULT_OPENSPEC.split(" ");
-    const r = spawnSync(cmd, [...args, "--version"], { encoding: "utf8", timeout: timeoutMs, stdio: ["ignore", "pipe", "ignore"] });
+    const r = spawnSync(cmd, [...args, "--version"], { encoding: "utf8", timeout: timeoutMs, stdio: ["ignore", "pipe", "ignore"], env: childEnv() /* REQ-DIST-016 */ });
     const m = r.status === 0 && !r.error ? /\d+\.\d+\.\d+/.exec(r.stdout ?? "") : null;
     if (!m)
         return { command: DEFAULT_OPENSPEC, note: OPENSPEC_NOTE };
@@ -402,17 +403,24 @@ export function writeGitignore(root) {
     writeFileSync(p, text);
     return add.length;
 }
-/** REQ-DIST-002 true when .gitignore has a line that ignores the whole .claude directory (017/D3). */
-export function ignoresClaude(root) {
+/** REQ-DIST-018 the agent folders that .gitignore ignores as a whole, with or without a slash. */
+export function ignoredAgentDirs(root) {
     const p = join(root, GITIGNORE);
     if (!existsSync(p))
-        return false;
+        return [];
     const lines = ignoreLines(readFileSync(p, "utf8"));
-    return lines.has(".claude") || lines.has(".claude/");
+    return [".claude", ".agents"].filter((d) => lines.has(d) || lines.has(`${d}/`));
+}
+/** REQ-DIST-018 one note for the ignored agent folders, or null when none is ignored. */
+export function ignoredNote(root) {
+    const dirs = ignoredAgentDirs(root).map((d) => `${d}/`);
+    if (dirs.length === 0)
+        return null;
+    const names = dirs.join(" and ");
+    return `note: .gitignore ignores ${names}. The skills under ${names} stay out of git.`;
 }
 /** REQ-SCH-003 where the templates with the ID placeholders are. Printed after the schema step (018/D5, 025/D4). */
 export const TEMPLATES_NOTE = `templates: ${TEMPLATES_DIR}/ (spec.md, tasks.md hold the ID placeholders)`;
-export const CLAUDE_NOTE = "note: .gitignore ignores .claude/. The skills under .claude/skills/ stay out of git. The copies under .agents/skills/ are tracked.";
 export function runInit(root, o) {
     const res = { written: [], kept: [], changed: [], merged: [], notes: [] };
     // REQ-DIST-002 the detection runs only when init writes spec-ctx.toml. An existing file stays (022/D2).
@@ -440,8 +448,9 @@ export function runInit(root, o) {
         const m = o.schema ? mergeConfig(cur, fragment, otherFragment) : null;
         if (!m || (!m.added.length && !m.merged.length)) {
             res.nothing = true;
-            if (o.skills && ignoresClaude(root))
-                res.notes.push(CLAUDE_NOTE);
+            const ign = ignoredNote(root); // REQ-DIST-018
+            if (ign)
+                res.notes.push(ign);
             if (o.schema && hasLegacySchema(cur))
                 res.notes.push(LEGACY_SCHEMA_NOTE);
             if (o.schema)
@@ -499,9 +508,10 @@ export function runInit(root, o) {
         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);
+    // REQ-DIST-018 skills under an ignored agent folder never reach git (017/D3)
+    const ign = ignoredNote(root);
+    if (ign)
+        res.notes.push(ign);
     // REQ-SCH-003 the templates line comes last, right before next: (018/D5)
     if (o.schema)
         res.notes.push(TEMPLATES_NOTE);

package/dist/init/next.js

@@ -0,0 +1,50 @@
+// REQ-DIST-017 what init says to do next, from the state of the specs.
+import { UsageExit } from "../cli/errors.js";
+import { loadConfigOrExit } from "../cli/config.js";
+import { ConfigError } from "../config.js";
+import { planAdopt } from "../adopt/plan.js";
+import { loadIndex } from "../index/build.js";
+import { nextTask } from "../tasks/tasks.js";
+import { runCommand } from "../runcmd.js";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/** true when .gitignore keeps .ctx/index.json out of git, or the index is already there */
+function indexIsSafe(root) {
+    if (existsSync(join(root, ".ctx/index.json")))
+        return true;
+    const g = join(root, ".gitignore");
+    if (!existsSync(g))
+        return false;
+    return readFileSync(g, "utf8").split("\n").map((l) => l.trim()).includes(".ctx/index.json");
+}
+/**
+ * Read the specs with the adopt planner. The planner writes nothing. When no header needs an ID,
+ * loadIndex may write .ctx/index.json, only when .gitignore already lists it or it exists (061/D1). Only a usage or config error gives
+ * the status fallback. Any other throw propagates.
+ */
+export function detectNext(root, run) {
+    const status = { needs_id: 0, summary: null, next: runCommand(run, "status") };
+    try {
+        const cfg = loadConfigOrExit(root);
+        const plan = planAdopt(root, cfg);
+        if (plan.edits.length > 0) {
+            const files = new Set(plan.edits.map((e) => e.file)).size;
+            const caps = plan.caps.filter((c) => c.derived).length;
+            return {
+                needs_id: plan.edits.length,
+                summary: `specs: ${plan.edits.length} headers in ${files} files need an ID (${caps} capability codes). adopt --dry-run shows each one.`,
+                next: runCommand(run, "adopt"),
+            };
+        }
+        // a skills refresh must not leave an untracked index behind (REQ-DIST-013)
+        if (!indexIsSafe(root))
+            return status;
+        const task = nextTask(root, loadIndex(root, cfg).data.entries);
+        return task ? { ...status, next: runCommand(run, `context ${task.id}`) } : status;
+    }
+    catch (e) {
+        if (e instanceof UsageExit || e instanceof ConfigError)
+            return status;
+        throw e;
+    }
+}

package/dist/journal/note.js

@@ -1,5 +1,5 @@
 // REQ-JRN-001 REQ-JRN-002 the sink that main() fills. It has no fs import, so a --version run loads no write code (057/D1).
-import { dirname, relative, resolve } from "node:path";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 /** REQ-JRN-002 the closed set of signals. The line version `v` versions it. */
 export const SIGNALS = ["init-ok", "context-has-code-or-test", "empty-context", "truncated-context", "usage-error", "internal-error"];
@@ -43,6 +43,9 @@ export function errInfo(e, pkgRoot = PACKAGE_ROOT) {
         catch {
             continue;
         }
+        // REQ-JRN-007 a frame like node:internal/... or <anonymous> is no path in the package
+        if (!isAbsolute(file))
+            continue;
         const rel = relative(pkgRoot, file);
         if (rel === "" || rel.startsWith("..") || rel.split(/[\\/]/).includes("node_modules") || resolve(rel) === rel)
             continue;

package/dist/loop/openspec.js

@@ -1,5 +1,6 @@
 // REQ-LOOP-001 the one OpenSpec call of next: status --change <c> --json, two keys read (024/D3, ADR-006 item 2).
 import { spawnSync } from "node:child_process";
+import { childEnv } from "../util/env.js";
 const TIMEOUT_MS = 60_000;
 /** REQ-LOOP-001 the command that gate and next run for OpenSpec. The env var wins over [gate] openspec (018/D2). */
 export function openspecCommand(configured) {
@@ -19,7 +20,7 @@ function errorMessage(stdout) {
 }
 /** Run `<openspec> status --change <folder> --json` in the root. A failure of any kind is a reason, never a throw. */
 export function openspecStatus(root, openspec, folder) {
-    const r = spawnSync("/bin/sh", ["-c", `${openspec} status --change ${folder} --json`], { cwd: root, encoding: "utf8", timeout: TIMEOUT_MS });
+    const r = spawnSync("/bin/sh", ["-c", `${openspec} status --change ${folder} --json`], { cwd: root, encoding: "utf8", timeout: TIMEOUT_MS, env: childEnv() /* REQ-DIST-016 */ });
     if (r.error && r.error.code === "ETIMEDOUT") {
         return { ok: false, reason: `openspec status timed out after ${TIMEOUT_MS / 1000}s` };
     }

package/dist/util/env.js

@@ -0,0 +1,10 @@
+// REQ-DIST-016 a child that may run npx gets the environment without the two variables of a nested npx.
+/** npm sets the first under `npx --package`. A leaked value makes a nested npx run the wrong command. */
+export const NESTED_NPX_VARS = ["npm_config_package", "npm_config_call"];
+/** A copy of `base` without the nested npx variables. It never writes to `base`. */
+export function childEnv(base = process.env) {
+    const copy = { ...base };
+    for (const k of NESTED_NPX_VARS)
+        delete copy[k];
+    return copy;
+}

package/dist/verify/run.js

@@ -1,5 +1,6 @@
 // REQ-VER-001 REQ-VER-003 run a Verify command with sh -c in the project root, with a timeout.
 import { spawn } from "node:child_process";
+import { childEnv } from "../util/env.js";
 export const TAIL_LINES = 20;
 export function tail(text, n = TAIL_LINES) {
     const lines = text.replace(/\n$/, "").split("\n");
@@ -9,7 +10,7 @@ export function tail(text, n = TAIL_LINES) {
 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, ...(env ? { env } : {}), stdio: ["ignore", "pipe", "pipe"] });
+        const child = spawn("sh", ["-c", command], { cwd, detached: true, env: childEnv(env), /* REQ-DIST-016 */ 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.5.0";
+export const VERSION = "0.6.0";

package/package.json

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

package/skills/specctx-run/SKILL.md

@@ -16,9 +16,9 @@ Run `specctx` as `npx spec-ctx` when it is not installed. `openspec` is the comm
 
 ## Actions
 
-- `plan`: take the change name from the request of the user in kebab case. That name is `<c>`. Follow the upstream `openspec-propose` skill for `<c>`. Read existing requirements with `specctx bundle <id>` or `specctx query`, never `openspec show`. Take every ID from `specctx id new REQ <CAP>` and `specctx id new SCN <CAP> --for <REQ>`. When the change needs several IDs of one kind, run `specctx id new --count <n>` once. Give every task a `[REQ-...]` citation and a `Verify:` code span. Then run `specctx check --strict` and `specctx gate --strict`. The gate runs the OpenSpec validate and the spec-length check. Fix every finding. Then run `specctx next --json` and run the command it prints. This is the plan stop. `next` returns `ask` with `human: true` until the human approves the question. You never resolve a plan question yourself.
+- `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>`. `id new` reserves nothing. A second call before `specctx build` returns the same ID. When the change needs several IDs of one kind, run `specctx id new --count <n>` once. Give every task a `[REQ-...]` citation and a `Verify:` code span. Then run `specctx check --strict` and `specctx gate --strict`. The gate runs the OpenSpec validate and the spec-length check. Fix every finding. Then run `specctx next --json` and run the command it prints. This is the plan stop. `next` returns `ask` with `human: true` until the human approves the question. You never resolve a plan question yourself.
 - `cite`: run `specctx query --change <c> --kind req`. Add the `[REQ-...]` citation and a `Verify:` code span to the task line named in `task`. Run `specctx check`. Continue.
-- `start`: run `specctx task start <t>`. Read the bundle it prints. Continue.
+- `start`: run `specctx task start <t>`. Read the bundle it prints. Each card ends with trust labels. Act on a line marked `verified` or `fresh`. Reread a line marked `stale since`, `unverified`, or `no evidence` with `specctx bundle <ID>` before you build on it. 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.