spec-ctx 0.4.1 → 0.6.0

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,13 @@ 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) {
+    const m = /^-- (\S+) \| /.exec(line);
+    return m ? m[1] : null;
 }
 /** REQ-QRY-004 the canonical blocks of requirements, joined by one blank line, with no provenance line. */
 export function reqBlocks(root, reqs) {
@@ -132,12 +139,15 @@ export function bundle(root, entries0, wanted, budget, depth, opts = {}) {
         if (m)
             blocks.push([m, `main version of ${i}`, 0]);
     }
+    // REQ-QRY-018 the count of blocks that the loop above pushed. They print first and always stay.
+    const pinned = blocks.length;
     const found = new Map();
     for (const i of wanted) {
         // decisions that reference a requested ID are included at every depth, as depth 1.
         // REQ-QRY-016 They replace a deeper hit, which the walk for an earlier requested ID can leave (048/D1).
         for (const e of entries) {
-            if (e.kind !== "decision" || !e.refs.includes(i))
+            // REQ-QRY-014 a requested decision prints once, as requested (050/D10)
+            if (e.kind !== "decision" || !e.refs.includes(i) || wanted.includes(e.id))
                 continue;
             const cur = found.get(e.id);
             if (!cur || cur.depth > 1)
@@ -161,7 +171,7 @@ export function bundle(root, entries0, wanted, budget, depth, opts = {}) {
     }
     for (const c of r.cited) {
         for (const e of entries) {
-            if (e.kind !== "decision" || !e.refs.includes(c))
+            if (e.kind !== "decision" || !e.refs.includes(c) || wanted.includes(e.id))
                 continue;
             const cur = found.get(e.id);
             if (!cur || cur.depth > 1)
@@ -186,28 +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 } };
     });
-    // fill the budget class by class, in print order inside a class, and skip a block that does not fit
-    const keep = blocks.map(() => false);
+    // 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 cls = 0; cls <= 3; cls++) {
-        for (let k = 0; k < blocks.length; k++) {
-            if (blocks[k][2] !== cls)
+    for (let k = 0; k < pinned; k++)
+        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`;
-    return { text, omitted };
+    // 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`;
+    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/journal.js

@@ -0,0 +1,65 @@
+// REQ-JRN-001 REQ-JRN-003 the journal write. One call, one line, no output, no throw (057/D2, 057/D3).
+import { appendFileSync, existsSync, mkdirSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { COMMANDS } from "../cli/args.js";
+import { dumps } from "../util/json.js";
+import { SIGNALS } from "./note.js";
+export const JOURNAL_DIR = ".ctx/local";
+export const JOURNAL_FILE = "runs.jsonl";
+export const ROTATED_FILE = "runs.1.jsonl";
+export const MAX_BYTES = 256 * 1024;
+export const MAX_LINE = 4096;
+/** REQ-JRN-001 the line, with sorted keys and no newline inside. It stays under 4 KB. */
+export function journalLine(sink, run) {
+    const signals = new Set(sink.signals);
+    if (run.exit === 2)
+        signals.add("usage-error");
+    if (run.exit === 3)
+        signals.add("internal-error");
+    const rec = {
+        at: run.at ?? new Date().toISOString(),
+        cmd: sink.cmd !== undefined && COMMANDS.includes(sink.cmd) ? sink.cmd : "?",
+        exit: run.exit,
+        ms: Math.max(0, Math.round(run.ms)),
+        signals: SIGNALS.filter((s) => signals.has(s)),
+        v: 1,
+        version: run.version,
+    };
+    if (sink.err && run.exit === 3)
+        rec.err = { code: sink.err.code, frames: sink.err.frames, name: sink.err.name };
+    let line = JSON.stringify(JSON.parse(dumps(rec)));
+    if (line.length > MAX_LINE && sink.err) {
+        rec.err = { code: sink.err.code, frames: sink.err.frames.slice(0, 5), name: sink.err.name };
+        line = JSON.stringify(JSON.parse(dumps(rec)));
+    }
+    if (line.length > MAX_LINE) {
+        delete rec.err;
+        line = JSON.stringify(JSON.parse(dumps(rec)));
+    }
+    return line;
+}
+/** REQ-JRN-003 append one line. Any failure stays silent. */
+export function appendRun(sink, run) {
+    try {
+        if (process.env.SPECCTX_JOURNAL === "0")
+            return;
+        const root = sink.root;
+        if (!root)
+            return;
+        const os = join(root, "openspec");
+        if (!existsSync(os) || !statSync(os).isDirectory())
+            return;
+        const dir = join(root, JOURNAL_DIR);
+        mkdirSync(dir, { recursive: true });
+        const ignore = join(dir, ".gitignore");
+        if (!existsSync(ignore))
+            writeFileSync(ignore, "*\n");
+        const file = join(dir, JOURNAL_FILE);
+        if (existsSync(file) && statSync(file).size > MAX_BYTES)
+            renameSync(file, join(dir, ROTATED_FILE));
+        appendFileSync(file, journalLine(sink, run) + "\n");
+    }
+    catch {
+        // the journal never changes the exit code or the output
+    }
+}

package/dist/journal/note.js

@@ -0,0 +1,57 @@
+// 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, 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"];
+/** REQ-JRN-001 fill the sink. It does nothing when the caller passed no sink. */
+export function note(io, patch) {
+    const s = io.journal;
+    if (!s)
+        return;
+    if (patch.root !== undefined)
+        s.root = patch.root;
+    if (patch.cmd !== undefined)
+        s.cmd = patch.cmd;
+    if (patch.run !== undefined)
+        s.run = patch.run;
+    if (patch.signal !== undefined && SIGNALS.includes(patch.signal))
+        s.signals.add(patch.signal);
+    if (patch.err !== undefined)
+        s.err = patch.err;
+}
+/** The package root: two folders above src/journal or dist/journal. */
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+/** REQ-JRN-002 name, code, and package frames of an error. Never the message (057/D4). */
+export function errInfo(e, pkgRoot = PACKAGE_ROOT) {
+    if (!(e instanceof Error))
+        return { name: "NonError", code: null, frames: [] };
+    const raw = e.code;
+    const code = typeof raw === "string" && /^[A-Z][A-Z0-9_]*$/.test(raw) ? raw : null;
+    const frames = [];
+    // stack line 1 holds the message, so it never counts
+    for (const line of (e.stack ?? "").split("\n").slice(1)) {
+        if (!/^\s+at /.test(line))
+            continue;
+        const m = /\(?((?:file:\/\/)?[^()\s]+):(\d+):\d+\)?$/.exec(line);
+        if (!m)
+            continue;
+        let file = m[1];
+        try {
+            if (file.startsWith("file://"))
+                file = fileURLToPath(file);
+        }
+        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;
+        frames.push(`${rel.split("\\").join("/")}:${m[2]}`);
+        if (frames.length === 10)
+            break;
+    }
+    return { name: e.name, code, frames };
+}