spec-ctx 0.4.0 → 0.4.1

package/dist/graph/related.js

@@ -1,10 +1,17 @@
 // REQ-QRY-002 IDs reachable from a start ID, with the reason each one was included.
 import { canon, poolOf } from "../index/canonical.js";
 import { cmpStr, cmpTuple } from "../util/pystr.js";
+import { fileEdges } from "./files.js";
+import { structuralEdges, structure } from "./links.js";
 // REQ-QRY-003 fixed block order after the requested IDs
-export const KIND_RANK = { adr: 0, decision: 1, req: 2, scn: 2, task: 3, code: 4, test: 5 };
-export const REASONS = ["scenario of", "ref from", "ref to", "decision for", "task cites", "implements", "covers"];
-export function related(entries, start, depth, all = false) {
+// REQ-QRY-012 capability and change lines print after the test lines (046/D7)
+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",
+];
+/** 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) {
     const pool = poolOf(entries, all);
     const ids = canon(entries);
     for (const e of pool)
@@ -19,32 +26,48 @@ export function related(entries, start, depth, all = false) {
             s.add(e.id);
         }
     }
+    const S = structure(entries);
     const found = new Map();
-    const add = (i, reason) => {
+    const add = (i, reason, d) => {
+        if (seeds && ids.get(i) && (ids.get(i).kind === "code" || ids.get(i).kind === "test"))
+            return false;
         if (i !== start && !found.has(i)) {
-            found.set(i, reason);
+            found.set(i, { reason, depth: d });
             return true;
         }
         return false;
     };
+    const isId = ids.has(start) || entries.some((e) => e.id === start);
+    const seeds = isId ? null : fileEdges(entries, start);
+    const frontier0 = [start];
+    if (seeds) {
+        frontier0.length = 0;
+        for (const [i, reason] of seeds)
+            if (add(i, reason, 1))
+                frontier0.push(i);
+    }
     const s = ids.get(start);
     if (s && s.kind === "req")
         for (const sid of s.scenarios ?? [])
-            add(sid, `scenario of ${start}`);
-    let frontier = [start];
+            add(sid, `scenario of ${start}`, 1);
+    let frontier = frontier0;
     for (let d = 0; d < depth; d++) {
         const nxt = [];
+        const dd = d + (seeds ? 2 : 1);
         for (const x of frontier) {
             const ex = ids.get(x);
             if (ex) {
                 for (const r of ex.refs)
-                    if (add(r, `ref from ${x}`))
+                    if (add(r, `ref from ${x}`, dd))
                         nxt.push(r);
                 if (ex.kind === "req") {
                     for (const sid of ex.scenarios ?? [])
-                        if (add(sid, `scenario of ${x}`))
+                        if (add(sid, `scenario of ${x}`, dd))
                             nxt.push(sid);
                 }
+                for (const [t, reason] of structuralEdges(S, ex, x, x === start, (id) => ids.has(id)))
+                    if (add(t, reason, dd))
+                        nxt.push(t);
             }
             for (const y of [...(back.get(x) ?? [])].sort(cmpStr)) {
                 const ey = ids.get(y);
@@ -62,15 +85,39 @@ export function related(entries, start, depth, all = false) {
                     reason = `covers ${x}`;
                 else
                     reason = `ref to ${x}`;
-                if (add(y, reason))
+                if (add(y, reason, dd))
                     nxt.push(y);
             }
         }
         frontier = nxt;
     }
+    return found;
+}
+/** The main version of a modified requirement, or undefined. */
+export function mainVersion(entries, id) {
+    return structure(entries).main.get(id);
+}
+/** REQ-QRY-005 a start that is no ID is a repository path. Its links seed the walk, and the walk adds no code or test row. */
+export function related(entries, start, depth, all = false) {
+    const ids = canon(entries);
+    for (const e of poolOf(entries, all))
+        if (!ids.has(e.id))
+            ids.set(e.id, e);
+    const found = walkFound(entries, start, depth, all);
     const rank = (i) => {
         const e = ids.get(i);
         return [e ? (KIND_RANK[e.kind] ?? 9) : 9, i];
     };
-    return [...found.keys()].sort((a, b) => cmpTuple(rank(a), rank(b))).map((i) => [i, found.get(i)]);
+    const out = [];
+    // REQ-QRY-010 the main version of a modified requirement follows the pair of its delta. --all lists both copies already.
+    const withMain = (i, reason) => {
+        out.push([i, reason]);
+        if (!all && mainVersion(entries, i))
+            out.push([i, `main version of ${i}`]);
+    };
+    if (!all && mainVersion(entries, start))
+        out.push([start, `main version of ${start}`]);
+    for (const i of [...found.keys()].sort((a, b) => cmpTuple(rank(a), rank(b))))
+        withMain(i, found.get(i).reason);
+    return out;
 }

package/dist/handoff/handoff.js

@@ -164,16 +164,18 @@ export function ask(root, entries, text, change, plan = false) {
     h.asked = q.n;
     return h;
 }
-/** REQ-LOOP-007 archive when the change has a task and every task is [x]. Else plan with the flag and design without it. The text plays no part (041/D2). */
+/** REQ-LOOP-007 plan with the flag, whatever the task state. Else archive when the change has a task and every task is [x]. Else design. The text plays no part (041/D2). */
 export function stageOf(entries, folder, plan = false) {
+    if (plan)
+        return "plan";
     const tasks = entries.filter((e) => e.kind === "task" && e.change === folder && !e.file.includes("/archive/"));
     if (tasks.length > 0 && tasks.every((t) => t.status === "done"))
         return "archive";
-    return plan ? "plan" : "design";
+    return "design";
 }
 /** REQ-HND-002 resolve question n in questions.json and render the handoff again (022/D6). */
-export function resolve(root, entries, n, answer) {
-    resolveQuestion(root, n, answer);
+export function resolve(root, entries, n, answer, verdict) {
+    resolveQuestion(root, n, answer, verdict);
     return refresh(root, entries);
 }
 export function addReopened(root, entries, task, reason) {

package/dist/handoff/questions.js

@@ -47,7 +47,7 @@ export function addQuestion(root, task, text, stage) {
     return item;
 }
 /** REQ-HND-002 resolve the open question n with an answer. Exit 2 when n is not an open question. */
-export function resolveQuestion(root, n, answer) {
+export function resolveQuestion(root, n, answer, verdict) {
     const qs = readQuestions(root);
     const item = qs.find((x) => x.n === n && x.status === "open");
     if (!Number.isInteger(n) || !item) {
@@ -57,6 +57,14 @@ export function resolveQuestion(root, n, answer) {
     const a = oneLine(answer);
     if (!a)
         throw new UsageExit("handoff resolve needs an answer");
+    // REQ-HND-004 a plan or archive question needs one verdict. Other stages take none (048/D3).
+    const needs = item.stage === "plan" || item.stage === "archive";
+    if (needs && (verdict === undefined || verdict === "both"))
+        throw new UsageExit("handoff resolve needs --approve or --reject for a plan or archive question");
+    if (!needs && verdict !== undefined)
+        throw new UsageExit("--approve and --reject apply to plan and archive questions");
+    if (needs)
+        item.verdict = verdict;
     item.status = "resolved";
     item.answer = a;
     item.resolved_at = isoNow();

package/dist/index/build.js

@@ -1,14 +1,39 @@
-// REQ-IDX-001 REQ-IDX-002 REQ-IDX-004 build, write, and load .ctx/index.json.
+// REQ-IDX-001 REQ-IDX-002 REQ-IDX-004 REQ-IDX-014 build, write, and load .ctx/index.json.
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { fsNowMs, mtimeMsOf, pause, setMtimeMs } from "./clock.js";
 import { join } from "node:path";
 import { dumps } from "../util/json.js";
 import { cmpStr, cmpTuple } from "../util/pystr.js";
 import { markCanonical } from "./canonical.js";
+import { addStructure } from "./structure.js";
 import { scanMarkdown, scannedOf, scanner, scanSource, walk } from "./scan.js";
 export const INDEX_PATH = ".ctx/index.json";
-export function buildIndex(root, cfg, files, sc) {
+/** REQ-IDX-014 the most that a file mtime may pass the clock reading of a build and still count as a write in its tick. */
+const TICK_MS = 50;
+/** REQ-IDX-014 the most waits of 2 ms for the file clock to pass the newest mtime: 100 ms in all. */
+const MAX_PAUSES = 50;
+/**
+ * REQ-IDX-004 build and write the index. `t0` is the clock reading taken before the walk of `files`. The index file gets
+ * `t0` as its mtime, so a write in the same tick as the build, or during it, leaves a file at or after that mtime (049/D2).
+ * A newest file 0 to 50 ms after `t0` makes the build wait until the file clock passes it, then take `t0` again (049/D4).
+ * A file far after `t0`, such as one dated in the future, gets no wait. Only file clock readings enter this logic.
+ */
+export function buildIndex(root, cfg, files, sc, t0) {
     const s = sc ?? scanner(root, cfg);
+    let at = t0 ?? fsNowMs(root);
     const list = files ?? walk(s);
+    const newest = scannedOf(root, list).newest_mtime_ms;
+    if (newest >= at && newest - at <= TICK_MS) {
+        for (let i = 0; i < MAX_PAUSES; i++) {
+            at = fsNowMs(root);
+            if (at > newest)
+                break;
+            pause(2);
+        }
+    }
+    return buildOnce(root, cfg, list, s, at);
+}
+function buildOnce(root, cfg, list, s, t0) {
     const entries = [];
     const problems = [];
     const scnNamed = new Set();
@@ -18,6 +43,7 @@ export function buildIndex(root, cfg, files, sc) {
         else
             scanSource(s, f.path, entries, scnNamed);
     }
+    addStructure(entries, list);
     markCanonical(entries);
     entries.sort((a, b) => cmpTuple([a.id, a.file, a.line], [b.id, b.file, b.line]));
     const uniq = new Map();
@@ -32,10 +58,12 @@ export function buildIndex(root, cfg, files, sc) {
     };
     mkdirSync(join(root, ".ctx"), { recursive: true });
     writeFileSync(join(root, INDEX_PATH), dumps(data) + "\n");
+    setMtimeMs(join(root, INDEX_PATH), t0);
     return data;
 }
 /** REQ-IDX-004 compare the stored scan record with a fresh stat walk. Rebuild on a mismatch. */
 export function loadIndex(root, cfg) {
+    const t0 = fsNowMs(root);
     const sc = scanner(root, cfg);
     const files = walk(sc);
     const p = join(root, INDEX_PATH);
@@ -50,8 +78,9 @@ export function loadIndex(root, cfg) {
     }
     const fresh = scannedOf(root, files);
     if (data === null || !data.scanned || data.scanned.count !== fresh.count
-        || data.scanned.newest_mtime_ms !== fresh.newest_mtime_ms || Object.keys(data.scanned).length !== 2) {
-        return { data: buildIndex(root, cfg, files, sc), rebuilt: true };
+        || data.scanned.newest_mtime_ms !== fresh.newest_mtime_ms || Object.keys(data.scanned).length !== 2
+        || fresh.newest_mtime_ms >= (mtimeMsOf(p) ?? 0)) {
+        return { data: buildIndex(root, cfg, files, sc, t0), rebuilt: true };
     }
     return { data, rebuilt: false };
 }

package/dist/index/clock.js

@@ -0,0 +1,55 @@
+// REQ-IDX-014 the file system clock. A write gets its mtime from a coarse kernel clock, so two writes in one tick
+// share an mtime. The index keeps the clock reading of the start of its build as its own mtime (049/D2).
+import { closeSync, mkdirSync, openSync, statSync, unlinkSync, utimesSync } from "node:fs";
+import { join } from "node:path";
+/** Whole milliseconds of an mtime in nanoseconds. */
+export function msOf(ns) {
+    return Number(ns / 1000000n);
+}
+/**
+ * The time of the file system clock in whole milliseconds: create one file in `.ctx/`, stat it, delete it. When the
+ * clock cannot be read, the value is one second before `Date.now()`. An earlier value can only cause an extra rebuild.
+ */
+export function fsNowMs(root) {
+    const dir = join(root, ".ctx");
+    const f = join(dir, `.clock-${process.pid}`);
+    try {
+        mkdirSync(dir, { recursive: true });
+        try {
+            unlinkSync(f);
+        }
+        catch {
+            // no old file
+        }
+        closeSync(openSync(f, "wx"));
+        const ms = msOf(statSync(f, { bigint: true }).mtimeNs);
+        try {
+            unlinkSync(f);
+        }
+        catch {
+            // the reading stays
+        }
+        return ms;
+    }
+    catch {
+        return Date.now() - 1000;
+    }
+}
+/** Set the mtime of a file to a whole number of milliseconds. Half a millisecond is added so that rounding keeps the value. */
+export function setMtimeMs(path, ms) {
+    const t = (ms + 0.5) / 1000;
+    utimesSync(path, t, t);
+}
+/** The mtime of a file in whole milliseconds, or null when it is absent. */
+export function mtimeMsOf(path) {
+    try {
+        return msOf(statSync(path, { bigint: true }).mtimeNs);
+    }
+    catch {
+        return null;
+    }
+}
+/** Sleep for a few milliseconds. The engine has no timer, so this blocks on a wait cell. */
+export function pause(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}

package/dist/index/scan.js

@@ -15,13 +15,15 @@ const SCN_HDR = new RegExp(`^#### Scenario:${S}*(?:(SCN-[A-Z]{2,6}-\\d{3}-\\d+)|
 const ADR_HDR = new RegExp(`^# (ADR-\\d{3})${S}+(.*)$`, "s");
 const REFS_RE = new RegExp(`^Refs:${S}*(.+)$`, "s");
 const TASK_REQ = new RegExp(`\\[(REQ-[A-Z]{2,6}-\\d{3}(?:${S}*,${S}*REQ-[A-Z]{2,6}-\\d{3})*)\\]`, "g");
-const CODE_TAG = new RegExp(`(?://|#|/\\*|\\*)${S}*(REQ-[A-Z]{2,6}-\\d{3})`);
+// REQ-IDX-008 the first marker and ID start the tag. Every REQ ID to the end of the line counts, with word boundaries (045/D5).
+const CODE_TAG = new RegExp(`(?://|#|/\\*|\\*)${S}*(REQ-[A-Z]{2,6}-\\d{3})\\b`);
+const CODE_SPAN = /`([^`]+)`/g;
 // REQ-IDX-007 the rest of the line after Covers:, and each REQ ID in it with word boundaries (042/D4)
 const COVER_TAG = /Covers:(.*)$/s;
 const REQ_ID = /\bREQ-[A-Z]{2,6}-\d{3}\b/g;
 const SENTENCE_END = new RegExp(`(?<=[.!?])${S}`);
 const COMMA = new RegExp(`${S}*,${S}*`);
-const SKIP_DIRS = new Set(["node_modules", ".git"]);
+const SKIP_DIRS = new Set(["node_modules", ".git", ".ctx"]);
 export function scanner(root, cfg) {
     const s = cfg.scan;
     const all = [...s.specs, ...s.changes, ...s.decisions, ...s.code, ...s.tests];
@@ -295,15 +297,23 @@ export function scanMarkdown(sc, rpath, entries, problems) {
             const reqs = [];
             for (const g of body.matchAll(TASK_REQ))
                 reqs.push(...g[1].split(COMMA));
-            if (reqs.length === 0)
-                problems.push([rpath, i, "task-without-req", tid]);
-            if (!body.includes("Verify:"))
-                problems.push([rpath, i, "task-without-verify", tid]);
+            // REQ-CHK-001 an archived task is history: no citation finding
+            if (status !== "archived") {
+                if (reqs.length === 0)
+                    problems.push([rpath, i, "task-without-req", tid]);
+                if (!body.includes("Verify:"))
+                    problems.push([rpath, i, "task-without-verify", tid]);
+            }
             // the full task body is the title, so query output shows the Verify clause
-            entries.push(entry({
+            const t = entry({
                 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);
+            if (paths.length)
+                t.paths = paths;
+            entries.push(t);
         }
     }
     // REQ-IDX-002 text holds the lower-cased body of each block
@@ -325,6 +335,20 @@ export function scanMarkdown(sc, rpath, entries, problems) {
         }
     }
 }
+/** REQ-IDX-009 code spans with no space and no `*` that hold a `/` or a `.`. A leading `./` is dropped. */
+export function taskPaths(body) {
+    const out = new Set();
+    for (const m of body.matchAll(CODE_SPAN)) {
+        let t = m[1];
+        if (/[ \t\n\r\f\v*]/.test(t) || !(t.includes("/") || t.includes(".")))
+            continue;
+        while (t.startsWith("./"))
+            t = t.slice(2);
+        if (t)
+            out.add(t);
+    }
+    return [...out].sort(cmpStr);
+}
 export function isTestPath(sc, rpath) {
     const name = rpath.slice(rpath.lastIndexOf("/") + 1);
     return anyMatch(sc.tests, rpath) || rpath.includes("/tests/") || rpath.startsWith("tests/")
@@ -360,7 +384,10 @@ export function scanSource(sc, rpath, entries, scnNamed) {
         }
         const m = CODE_TAG.exec(line);
         if (m && !line.includes("Covers:")) {
-            entries.push(entry({ id: `${rpath}:${i}`, kind: "code", file: rpath, line: i, title: pyStrip(line), change: "main", status: "active", refs: [m[1]] }));
+            const ids = [...new Set(line.slice(m.index).match(REQ_ID) ?? [])];
+            for (const rid of ids) {
+                entries.push(entry({ id: `${rpath}:${i}`, kind: "code", file: rpath, line: i, title: pyStrip(line), change: "main", status: "active", refs: [rid] }));
+            }
         }
     }
 }

package/dist/index/structure.js

@@ -0,0 +1,97 @@
+// REQ-IDX-010 REQ-IDX-012 REQ-IDX-013 change entries, capability entries, and the design links of tasks.
+import { cmpStr } from "../util/pystr.js";
+import { changeKey, changeOf, resolveChange, taskPaths } from "./scan.js";
+const CHANGE_DIR = /^(openspec\/changes\/(?:archive\/)?[^/]+)\//;
+const ARCHIVE_DATE = /^openspec\/changes\/archive\/(\d{4}-\d{2}-\d{2})-/;
+const CAP_SPEC = /(?:^|\/)specs\/([^/]+)\/spec\.md$/;
+// REQ-IDX-012 a full name `<key>/D<n>` or a bare `D<n>`. A bare D follows no letter, digit, slash, or hyphen.
+const FULL_DESIGN = /(?<![\w/-])([\w-]+)\/D(\d+)(?!\w)/g;
+const BARE_DESIGN = /(?<![\w/-])D(\d+)(?!\w)/g;
+function entryOf(e) {
+    return { ...e, line: 1, text: "", canonical: true, refs: [] };
+}
+/** REQ-IDX-013 the winner among folders with one key: active first, then the smaller name. Archived: newest date, then the smaller name. */
+function better(a, b) {
+    if (a.archived !== b.archived)
+        return !a.archived;
+    if (a.archived && a.date !== b.date)
+        return a.date > b.date;
+    return cmpStr(a.change, b.change) < 0;
+}
+/** REQ-IDX-010 one change entry per key and one cap entry per capability name. */
+function structureEntries(files) {
+    const folders = new Map();
+    const caps = new Map();
+    for (const f of files) {
+        const m = CHANGE_DIR.exec(f.path);
+        if (m) {
+            let fo = folders.get(m[1]);
+            if (!fo) {
+                const date = ARCHIVE_DATE.exec(f.path)?.[1] ?? "";
+                folders.set(m[1], (fo = { dir: m[1], change: changeOf(f.path), archived: f.path.includes("/archive/"), date, files: [] }));
+            }
+            fo.files.push(f.path);
+        }
+        const c = CAP_SPEC.exec(f.path);
+        if (c) {
+            let l = caps.get(c[1]);
+            if (!l)
+                caps.set(c[1], (l = []));
+            l.push(f.path);
+        }
+    }
+    const win = new Map();
+    for (const fo of folders.values()) {
+        const key = changeKey(fo.change);
+        const cur = win.get(key);
+        if (!cur || better(fo, cur))
+            win.set(key, fo);
+    }
+    const out = [];
+    for (const [key, fo] of win) {
+        const proposal = `${fo.dir}/proposal.md`;
+        const file = fo.files.includes(proposal) ? proposal : [...fo.files].sort(cmpStr)[0];
+        out.push(entryOf({ id: `change/${key}`, kind: "change", file, title: fo.change, change: fo.change, status: fo.archived ? "archived" : "active" }));
+    }
+    for (const [name, list] of caps) {
+        // the main spec, else the first active delta, else the newest archived delta
+        const sorted = [...list].sort(cmpStr);
+        const file = sorted.find((p) => p.startsWith("openspec/specs/"))
+            ?? sorted.find((p) => !p.includes("/archive/"))
+            ?? sorted[sorted.length - 1];
+        out.push(entryOf({ id: `cap/${name}`, kind: "cap", file, title: name, change: "main", status: "active" }));
+    }
+    return out;
+}
+/** REQ-IDX-012 the `design:` links of a task. The scan reads the text before `Verify:` with the path spans removed. */
+function designLinks(entries) {
+    const decisions = new Set(entries.filter((e) => e.kind === "decision").map((e) => e.id));
+    for (const t of entries) {
+        if (t.kind !== "task")
+            continue;
+        let body = t.title;
+        const v = body.indexOf("Verify:");
+        if (v >= 0)
+            body = body.slice(0, v);
+        for (const p of taskPaths(body))
+            body = body.split("`" + p + "`").join(" ");
+        const found = new Set();
+        for (const m of body.matchAll(FULL_DESIGN)) {
+            const folder = resolveChange(entries, m[1]);
+            const id = `${folder === undefined ? m[1] : changeKey(folder)}/D${m[2]}`;
+            if (decisions.has(id))
+                found.add(id);
+        }
+        const own = `${changeKey(t.change)}/D`;
+        for (const m of body.matchAll(BARE_DESIGN))
+            if (decisions.has(own + m[1]))
+                found.add(own + m[1]);
+        if (found.size)
+            t.links = [...found].sort(cmpStr).map((id) => `design:${id}`);
+    }
+}
+/** Add the structural entries and the design links. It runs after the scan and before the canonical mark. */
+export function addStructure(entries, files) {
+    designLinks(entries);
+    entries.push(...structureEntries(files));
+}

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 { 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). */
 export const TEMPLATES_DIR = `openspec/templates/${SCHEMA}`;
@@ -41,7 +42,7 @@ export function detectOpenspec(timeoutMs = DETECT_TIMEOUT_MS) {
  * exists at the root. `src/**` becomes `lib/**` when only `lib/` exists. The comments stay.
  * `openspec` replaces the default command on the `openspec = ` line (022/D2).
  */
-export function configText(root, openspec = DEFAULT_OPENSPEC) {
+export function configText(root, openspec = DEFAULT_OPENSPEC, run = null) {
     const isDir = (d) => existsSync(join(root, d)) && statSync(join(root, d)).isDirectory();
     let text = INIT_TEXT;
     if (!isDir("tests") && isDir("test"))
@@ -50,8 +51,18 @@ export function configText(root, openspec = DEFAULT_OPENSPEC) {
         text = text.replace('\ncode = ["src/**"]\n', '\ncode = ["lib/**"]\n');
     if (openspec !== DEFAULT_OPENSPEC)
         text = text.replace(`\nopenspec = "${DEFAULT_OPENSPEC}"\n`, `\nopenspec = ${JSON.stringify(openspec)}\n`);
+    // REQ-DIST-015 a run prefix adds the [cli] section at the end (043/D3)
+    if (run !== null)
+        text += `\n[cli]\n# The prefix of every command that spec-ctx prints for you to run. init wrote it because it ran under npx.\nrun = ${JSON.stringify(run)}\n`;
     return text;
 }
+/**
+ * REQ-DIST-015 the run prefix that init writes. npm sets npm_command to exec for npm exec and npx.
+ * Any other value, or none, gives null and the default applies (043/D3).
+ */
+export function runPrefixFor(env) {
+    return env.npm_command === "exec" ? `npx -y spec-ctx@${VERSION}` : null;
+}
 /**
  * REQ-SCH-006 wrap the ID after a requirement or scenario header prefix in square brackets (032/D1).
  * An ID in brackets already stays. Task citations, Refs lines, and tags have no header prefix, so they stay bare.
@@ -74,8 +85,8 @@ export function bracketsOf(root) {
     return existsSync(join(root, CONFIG_FILE)) ? loadConfigOrExit(root).ids.brackets : false;
 }
 /** Target path relative to the project root for every file that init installs, with its bytes. */
-export function plan(o, root, openspec = DEFAULT_OPENSPEC, brackets = false) {
-    const out = [[CONFIG_FILE, Buffer.from(configText(root, openspec))]];
+export function plan(o, root, openspec = DEFAULT_OPENSPEC, brackets = false, run = null) {
+    const out = [[CONFIG_FILE, Buffer.from(configText(root, openspec, run))]];
     for (const rel of Object.keys(ASSETS).sort()) {
         // REQ-SCH-003 only the four templates land in the project. The fragment merges into config.yaml. No schema folder (025/D3)
         if (o.schema && rel.startsWith(TEMPLATES_SRC)) {
@@ -416,7 +427,7 @@ export function runInit(root, o) {
     const brackets = bracketsOf(root);
     const fragment = fragmentText(brackets);
     const otherFragment = fragmentText(!brackets);
-    let files = plan(o, root, openspec, brackets);
+    let files = plan(o, root, openspec, brackets, runPrefixFor(process.env));
     // REQ-CLI-007 every file present with the same bytes and no config key to add: nothing to do
     // an existing spec-ctx.toml counts as present, because the user owns it (014/D4)
     const same = files.every(([rel, data]) => existsSync(join(root, rel)) && (rel === CONFIG_FILE || readFileSync(join(root, rel)).equals(data)));

package/dist/loop/fails.js

@@ -4,6 +4,7 @@ import { dirname, join } from "node:path";
 import { readQuestions } from "../handoff/questions.js";
 import { isFailFile } from "../tasks/evidence.js";
 import { evidenceRel } from "../tasks/tasks.js";
+import { runCommand } from "../runcmd.js";
 import { dumps } from "../util/json.js";
 import { cmpStr } from "../util/pystr.js";
 import { isoNow } from "../util/time.js";
@@ -66,6 +67,13 @@ export function failsInWindow(root, task, questions) {
 export function openQuestionFor(root, task, questions) {
     return (questions ?? safeQuestions(root)).find((q) => q.task === task && q.status === "open");
 }
+/**
+ * REQ-LOOP-014 an open attempt-cap question of the task: stage cap only. A question with no stage is a person's (044/D3).
+ * The text plays no part (044/D3).
+ */
+export function isCapQuestion(q, task) {
+    return q.status === "open" && q.task === task && q.stage === "cap";
+}
 /** Write the next fail file of a task. The attempt counts the window, the file number counts every fail file. */
 export function writeFail(root, task, verify, tail) {
     const attempt = failsInWindow(root, task).length + 1;
@@ -85,8 +93,8 @@ export function capQuestion(task, attempts, tail) {
     return `task ${task} failed Verify ${attempts} times. Last: ${failLine(tail)}. What should change?`;
 }
 /** REQ-LOOP-002 the last line of a failed `task done` at the cap. Strict mode. */
-export function blockedLine(n) {
-    return `blocked: question ${n} written. Run specctx handoff resolve ${n} "<answer>" to continue.`;
+export function blockedLine(n, run = "specctx") {
+    return `blocked: question ${n} written. Run ${runCommand(run, `handoff resolve ${n} "<answer>"`)} to continue.`;
 }
 /**
  * REQ-LOOP-006 the reason line of a Verify tail (029/D3): the last line that starts with `fail:`, `FAIL`, or `(fail)`