spec-ctx 0.4.1 → 0.6.0

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

@@ -122,6 +122,65 @@ export function weakVerifyFindings(entries) {
 export function weakVerifyWarnings(entries) {
     return weakVerifyFindings(entries).map((f) => `weak-verify ${f.id} ${f.file}:${f.line}`);
 }
+/**
+ * REQ-CHK-010 REQ-CHK-008 REQ-CHK-009 one predicate for the delta test rule and the deferred notice (052/D1).
+ * A gap is a delta requirement or scenario of an active change that no test names. The rule reports the gaps of
+ * a change that has a task and no open task. The notice lists the gaps that an open task or a missing task hides.
+ */
+export function deltaGaps(entries, data) {
+    const covered = new Set(entries.filter((e) => e.kind === "test").flatMap((e) => e.refs));
+    const named = new Set(data.scn_named ?? []);
+    // an ID that a REMOVED block of an active change names waits for archive, so it needs no test
+    const pending = new Set();
+    for (const e of entries) {
+        if (e.status !== "removed")
+            continue;
+        pending.add(e.id);
+        for (const sc of e.scenarios ?? [])
+            pending.add(sc);
+    }
+    const out = new Map();
+    const slot = (change) => {
+        let g = out.get(change);
+        if (!g)
+            out.set(change, (g = { open: 0, all: 0, gaps: [] }));
+        return g;
+    };
+    for (const e of entries) {
+        if (e.kind !== "task" || e.change === "main" || e.file.includes("/archive/"))
+            continue;
+        const g = slot(e.change);
+        g.all++;
+        if (e.status !== "done")
+            g.open++;
+    }
+    const seen = new Set();
+    for (const e of entries) {
+        if ((e.kind !== "scn" && e.kind !== "req") || e.change === "main" || (e.status !== "active" && e.status !== "modified"))
+            continue;
+        if (pending.has(e.id))
+            continue;
+        const rule = e.kind === "req" ? (covered.has(e.id) ? null : "uncovered") : named.has(e.id) ? null : "scenario-untested";
+        if (!rule)
+            continue;
+        const gap = [e.file, e.line, rule, e.id];
+        const key = e.change + JSON.stringify(gap);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        slot(e.change).gaps.push(gap);
+    }
+    return out;
+}
+export function deferredOf(entries, data) {
+    const out = [];
+    for (const [change, g] of deltaGaps(entries, data)) {
+        // 052/D1 to include a change that has no task, the condition is `g.all === 0 || g.open > 0`
+        if ((g.all === 0 || g.open > 0) && g.gaps.length)
+            out.push({ change, untested: g.gaps.length, open: g.open });
+    }
+    return out.sort((x, y) => cmpTuple([x.change], [y.change]));
+}
 /** 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;
@@ -190,29 +249,10 @@ 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]);
-        }
+        // REQ-CHK-008 REQ-CHK-009 a delta item needs a test once its change has a task and no open task (038/D1, 038/D2, 039/D2)
+        for (const g of deltaGaps(entries, data).values())
+            if (g.open === 0 && g.all > 0)
+                findings.push(...g.gaps);
         findings.push(...evidenceFindings(root, entries, listEvidence(root)));
     }
     const uniq = new Map();

package/dist/cli/args.js

@@ -10,6 +10,7 @@ export const COMMAND_FLAGS = {
     bundle: { budget: "int", depth: "int", all: "bool", block: "bool" },
     context: { budget: "int", depth: "int" },
     check: { strict: "bool" },
+    report: {},
     stats: { change: "string", write: "bool" },
     gate: { strict: "bool", markdown: "string", rerun: "bool", base: "string" },
     "id new": { for: "string", count: "int" },

package/dist/cli/commands.js

@@ -6,6 +6,7 @@ import { defaults } from "../config.js";
 import { hintOf } from "../check/hints.js";
 import { paint } from "./color.js";
 import { runCommand } from "../runcmd.js";
+import { note } from "../journal/note.js";
 /** check with warnings and the baseline filter. Strict mode adds the strict rules and the warnings. */
 async function runCheck(root, cfg, data, strict) {
     const { check } = await import("../check/check.js");
@@ -28,12 +29,13 @@ async function runCheck(root, cfg, data, strict) {
  * REQ-CHK-004 the findings, then a blank line, the summary line, and one line per rule with its hint.
  * A warning counts as advisory. The `baselined` line stays last (REQ-CHK-002).
  */
-export function checkText(r, tty, run = "specctx") {
+export function checkText(r, tty, run = "specctx", deferred = []) {
     // REQ-CLI-008 every finding of check is hard, so every finding line is red. stale-evidence is one of them.
     // REQ-CHK-001 a finding with a detail, such as a retitle, carries it after the ID (021/D2)
     const body = r.findings.map((x) => paint("fail", `${x.file}:${x.line}  ${x.rule}  ${x.id}${x.detail ? `  ${x.detail}` : ""}\n`, tty)).join("")
         + r.warnings.map((w) => `warning: ${w}\n`).join("");
-    const base = r.baselined ? `baselined: ${r.baselined}\n` : "";
+    // REQ-CHK-010 a deferred line is not a finding. It comes before the baselined line, which stays last (052/D3).
+    const base = deferred.map((d) => `deferred: ${d.change}  ${d.untested} untested delta item${d.untested === 1 ? "" : "s"}, ${d.open} open task${d.open === 1 ? "" : "s"}\n`).join("") + (r.baselined ? `baselined: ${r.baselined}\n` : "");
     const n = r.findings.length + r.warnings.length;
     if (!n)
         return paint("dim", "0 findings\n", tty) + base;
@@ -75,8 +77,24 @@ export async function run(p, io) {
         return init(p, io);
     const root = findRoot(io.cwd, f.root);
     requireOpenSpec(root);
+    // REQ-JRN-001 the root is known now, so the bin entry may write the journal
+    note(io, { root });
+    // REQ-JRN-004 report runs before the config load, so a broken config still reports
+    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);
+        return 0;
+    }
     const { loadConfigOrExit } = await import("./config.js");
     const cfg = loadConfigOrExit(root);
+    // REQ-JRN-006 the exit 3 line names the report command with this prefix
+    note(io, { run: cfg.cli.run });
     const { dumps } = await import("../util/json.js");
     const print = (v) => io.out(dumps(v) + "\n");
     if (cmd === "build") {
@@ -287,6 +305,9 @@ export async function run(p, io) {
             const { bundle } = await import("../graph/bundle.js");
             const { resolveInputs } = await import("../graph/input.js");
             const ids = canon(entries);
+            // REQ-QRY-018 a negative budget is a usage error (050/D11)
+            if (f.budget !== undefined && f.budget < 0)
+                throw new UsageExit("--budget must be 0 or more");
             // REQ-QRY-005 an input that is no known ID is a path in the repository
             const { wanted, paths, errors, taskId } = resolveInputs(root, io.cwd, entries, p.positional);
             if (errors.length) {
@@ -302,8 +323,11 @@ 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: [] });
+                    print({ text, omitted: [], body_omitted: [], chars: n, budget: null, complete: true, used: n, blocks: [] });
                 else
                     io.out(text);
                 return 0;
@@ -311,6 +335,12 @@ export async function run(p, io) {
             // 047/D5 a task input passes the entry that findTask picks, so an active task wins over an archived one
             const task = taskId === undefined ? undefined : (await import("../tasks/tasks.js")).findTask(root, entries, taskId).entry;
             const b = bundle(root, entries, wanted, f.budget ?? cfg.bundle.budget, f.depth ?? cfg.bundle.depth, { all, task });
+            // REQ-JRN-002 only context emits the block signals. The sink is set only for the bin entry.
+            if (cmd === "context" && io.journal) {
+                const { contextSignals } = await import("../journal/signals.js");
+                for (const signal of contextSignals(entries, b))
+                    note(io, { signal });
+            }
             if (json)
                 print(b);
             else if (b.text === "" && wanted.every((w) => paths.has(w)))
@@ -343,10 +373,12 @@ export async function run(p, io) {
             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);
+            // REQ-CHK-010 only this case computes the deferred notice. runCheck and gate stay as they are (052/D5).
+            const deferred = f.strict ? (await import("../check/check.js")).deferredOf(entries, data) : [];
             if (json)
-                print({ baselined: r.baselined, count: findings.length, findings, warnings: r.warnings });
+                print({ baselined: r.baselined, count: findings.length, findings, warnings: r.warnings, ...(f.strict ? { deferred } : {}) });
             else
-                io.out(checkText(r, io.tty, cfg.cli.run));
+                io.out(checkText(r, io.tty, cfg.cli.run, deferred));
             return r.findings.length ? 1 : 0;
         }
     }
@@ -369,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>", "Stop at n characters. 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>", "Stop at n characters. 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."],
@@ -90,6 +90,11 @@ export const TABLE = [
         flags: [["--change <name>", "Show only this change."], ["--write", "Also write docs/metrics/<date>.md."]],
         exit: PLAIN, example: "specctx stats --write",
     },
+    {
+        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. 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.",
         flags: LINT_FLAGS, exit: LINT_EXIT, example: "specctx lint tells --baseline 0 README.md",
@@ -101,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",
     },
     {
@@ -206,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/cli/workflow.js

@@ -171,10 +171,13 @@ export async function runWorkflow(c) {
                 // REQ-LOOP-002 the fail file is the retry record. At the cap, one question stops the loop (024/D4, 024/D5).
                 const { writeFail, openQuestionFor, capQuestion, blockedLine } = await import("../loop/fails.js");
                 const { addQuestion } = await import("../handoff/questions.js");
-                const fail = writeFail(c.root, t.id, { command: t.verify.command, exit: r.timedOut ? null : r.exit }, outTail);
+                // REQ-TASK-008 the fail file and the cap question hold no machine path. The printed tail stays as it is (056/D5).
+                const { redactPaths } = await import("../util/redact.js");
+                const kept = redactPaths(outTail, c.root);
+                const fail = writeFail(c.root, t.id, { command: t.verify.command, exit: r.timedOut ? null : r.exit }, kept);
                 let question = openQuestionFor(c.root, t.id)?.n ?? null;
                 if (question === null && fail.file.attempt >= c.cfg.loop.max_attempts) {
-                    question = addQuestion(c.root, t.id, capQuestion(t.id, fail.file.attempt, outTail), "cap").n;
+                    question = addQuestion(c.root, t.id, capQuestion(t.id, fail.file.attempt, kept), "cap").n;
                 }
                 if (c.json)
                     print(c, { attempt: fail.file.attempt, command: t.verify.command, error: msg, exit: r.exit, fail: fail.rel, question, tail: outTail, task: t.id });
@@ -196,8 +199,10 @@ export async function runWorkflow(c) {
             // the Verify command can change tagged files, so the digests come from the tree after the run
             const { loadIndex } = await import("../index/build.js");
             const after = loadIndex(c.root, c.cfg).data.entries;
+            // REQ-TASK-008 the stderr tail holds no machine path. verify.command stays as the task line has it (056/D5, 056/D6).
+            const { redactPaths } = await import("../util/redact.js");
             const rel = writeEvidence(c.root, t, after, {
-                command: t.verify.command, exit: 0, stdout_sha256: sha256(r.stdout), stderr_tail: tail(r.stderr.toString("utf8")),
+                command: t.verify.command, exit: 0, stdout_sha256: sha256(r.stdout), stderr_tail: redactPaths(tail(r.stderr.toString("utf8")), c.root),
             }, "command", undefined, t.verify.cwd);
             setBox(c.root, t, true);
             clearCurrent(c.root, t.id);

package/dist/cli.js

@@ -1,14 +1,53 @@
 #!/usr/bin/env node
 // REQ-CLI-001 bin entry. tests call main() from src/main.ts in process.
+// REQ-JRN-001 this entry writes the run journal after main() returns. main() only fills the sink (057/D1).
 import { main } from "./main.js";
+import { VERSION } from "./version.js";
 process.stdout.on("error", (e) => {
     if (e.code === "EPIPE")
         process.exit(0);
 });
-const code = await main(process.argv.slice(2), {
-    cwd: process.cwd(),
-    out: (s) => process.stdout.write(s),
-    err: (s) => process.stderr.write(s),
-    tty: process.stdout.isTTY === true,
-});
+const argv = process.argv.slice(2);
+const sink = { signals: new Set() };
+const t0 = performance.now();
+let code;
+let thrown;
+let failed = false;
+try {
+    code = await main(argv, {
+        cwd: process.cwd(),
+        out: (s) => process.stdout.write(s),
+        err: (s) => process.stderr.write(s),
+        tty: process.stdout.isTTY === true,
+        journal: sink,
+    });
+}
+catch (e) {
+    failed = true;
+    thrown = e;
+    code = 3;
+    try {
+        const { errInfo } = await import("./journal/note.js");
+        sink.err = errInfo(e);
+    }
+    catch {
+        // no journal detail
+    }
+}
+try {
+    // REQ-JRN-001 a usage error before the root check keeps no root. Only the "?" command with no --root looks for one (057/D2).
+    if (sink.root === undefined && sink.cmd === "?" && !argv.some((a) => a === "--root" || a.startsWith("--root="))) {
+        const { findRoot } = await import("./cli/root.js");
+        sink.root = findRoot(process.cwd());
+    }
+    if (sink.root !== undefined && process.env.SPECCTX_JOURNAL !== "0") {
+        const { appendRun } = await import("./journal/journal.js");
+        appendRun(sink, { exit: code, ms: performance.now() - t0, version: VERSION });
+    }
+}
+catch {
+    // the journal never changes the exit code or the output
+}
+if (failed)
+    throw thrown;
 process.exitCode = code;