spec-ctx 0.4.0 → 0.5.0

package/dist/graph/bundle.js

@@ -1,9 +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 { canon } from "../index/canonical.js";
+import { canon, poolOf } from "../index/canonical.js";
 import { blockRange, readText } from "../index/scan.js";
-import { cmpTuple, cpLen, pyStrip, splitLines } from "../util/pystr.js";
-import { KIND_RANK, related } from "./related.js";
+import { cmpStr, cmpTuple, cpLen, pyStrip, splitLines } from "../util/pystr.js";
+import { KIND_RANK, mainVersion, walkFound } from "./related.js";
 export class Lines {
     cache = new Map();
     root;
@@ -19,7 +19,8 @@ export class Lines {
 }
 /** Markdown text of an entry. Code and test entries print no body, only their provenance line. */
 export function blockText(e, files) {
-    if (e.kind === "code" || e.kind === "test")
+    // REQ-QRY-009 a capability or a change prints its provenance line only
+    if (e.kind === "code" || e.kind === "test" || e.kind === "cap" || e.kind === "change")
         return "";
     const lines = files.get(e.file);
     const start = e.line - 1;
@@ -44,56 +45,183 @@ function rstrip(s) {
 export function provenance(e, reason) {
     return `-- ${e.id} | ${e.file}:${e.line} | ${e.status} | ${reason}\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) {
     const files = new Lines(root);
     return reqs.map((e) => blockText(e, files)).join("\n");
 }
-export function bundle(root, entries, wanted, budget, depth, all = false) {
+/** REQ-QRY-012 the budget class of a block (046/D7). A lower class keeps its place first. */
+function budgetClass(e, requested, hit) {
+    if (requested)
+        return 0;
+    if (!hit || hit.depth >= 2)
+        return 3;
+    if (e.kind === "code" || e.kind === "test")
+        return 1;
+    if (e.kind === "decision" && e.status === "archived")
+        return 3;
+    return 2;
+}
+/**
+ * REQ-QRY-016 REQ-QRY-017 the requirements that the task cites or that the file tags, and the code and test
+ * entries of each, from one pass over the pool (047/D3, 047/D7). The entries get depth 1.
+ */
+function reach(entries, ids, wanted, all) {
+    const cited = [];
+    const tagged = [];
+    const add = (list, r) => {
+        if (ids.get(r)?.kind === "req" && !cited.includes(r) && !tagged.includes(r))
+            list.push(r);
+    };
+    const pool = poolOf(entries, all);
+    for (const i of wanted) {
+        const e = ids.get(i);
+        if (e?.kind === "task")
+            for (const r of e.refs)
+                add(cited, r);
+        // a requested input that is no ID is a path. Only the tags of the file count, not a mention in a task line.
+        else if (!e)
+            for (const x of pool)
+                if (x.file === i && (x.kind === "code" || x.kind === "test"))
+                    for (const r of x.refs)
+                        add(tagged, r);
+    }
+    const lines = new Map();
+    if (!cited.length && !tagged.length)
+        return { cited, lines };
+    const want = new Set([...cited, ...tagged]);
+    const back = new Map();
+    for (const x of pool) {
+        if (x.kind !== "code" && x.kind !== "test")
+            continue;
+        for (const r of x.refs) {
+            if (!want.has(r))
+                continue;
+            let l = back.get(r);
+            if (!l)
+                back.set(r, (l = []));
+            l.push(x);
+        }
+    }
+    for (const r of [...cited, ...tagged]) {
+        for (const x of (back.get(r) ?? []).sort((a, b) => cmpStr(a.id, b.id))) {
+            if (!lines.has(x.id))
+                lines.set(x.id, { reason: `${x.kind === "code" ? "implements" : "covers"} ${r}`, depth: 1 });
+        }
+    }
+    return { cited, lines };
+}
+export function bundle(root, entries0, wanted, budget, depth, opts = {}) {
+    const all = !!opts.all;
+    // 047/D5 the entry that the caller found stands for its ID. It goes last, so canon() holds it.
+    const entries = opts.task && canon(entries0).get(opts.task.id) !== opts.task ? [...entries0.filter((e) => e !== opts.task), opts.task] : entries0;
     const ids = canon(entries);
+    // block, reason, class. The array is in print order.
     const blocks = [];
     for (const i of wanted) {
+        // REQ-QRY-005 a path has no block of its own. Its links come from related below.
+        if (!ids.has(i))
+            continue;
         const copies = [ids.get(i)];
         if (all)
             copies.push(...entries.filter((e) => e.id === i && !e.canonical));
         for (const e of copies)
-            blocks.push([e, "requested"]);
+            blocks.push([e, "requested", 0]);
+        // REQ-QRY-010 the main version of a modified requirement, also for a requested ID
+        const m = all ? undefined : mainVersion(entries, i);
+        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
+        // 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) && !found.has(e.id))
-                found.set(e.id, `decision for ${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)
+                found.set(e.id, { reason: `decision for ${i}`, depth: 1 });
         }
-        for (const [r, reason] of related(entries, i, depth, all)) {
+        for (const [r, hit] of walkFound(entries, i, depth, all)) {
             if (!wanted.includes(r) && !found.has(r))
-                found.set(r, reason);
+                found.set(r, hit);
+        }
+    }
+    // REQ-QRY-016 REQ-QRY-017 the cited requirements, their decisions, and the lines of the requirements of a task or a file
+    const r = depth >= 1 ? reach(entries, ids, wanted, all) : { cited: [], lines: new Map() };
+    const citedSet = new Set(r.cited);
+    for (const t of wanted) {
+        const te = ids.get(t);
+        if (te?.kind !== "task")
+            continue;
+        for (const c of te.refs)
+            if (citedSet.has(c) && !wanted.includes(c) && !found.has(c))
+                found.set(c, { reason: `ref from ${t}`, depth: 1 });
+    }
+    for (const c of r.cited) {
+        for (const e of entries) {
+            if (e.kind !== "decision" || !e.refs.includes(c) || wanted.includes(e.id))
+                continue;
+            const cur = found.get(e.id);
+            if (!cur || cur.depth > 1)
+                found.set(e.id, { reason: `decision for ${c}`, depth: 1 });
         }
     }
+    for (const [id, hit] of r.lines) {
+        const cur = found.get(id);
+        if (!wanted.includes(id) && (!cur || cur.depth > 1))
+            found.set(id, hit);
+    }
     // scenarios print inside their requirement
-    const tail = [...found.keys()].filter((r) => ids.has(r) && ids.get(r).kind !== "scn");
+    const tail = [...found.keys()].filter((x) => ids.has(x) && ids.get(x).kind !== "scn");
     tail.sort((a, b) => cmpTuple([KIND_RANK[ids.get(a).kind] ?? 9, a], [KIND_RANK[ids.get(b).kind] ?? 9, b]));
-    for (const r of tail)
-        blocks.push([ids.get(r), found.get(r)]);
+    for (const r2 of tail) {
+        const hit = found.get(r2);
+        const e = ids.get(r2);
+        const cls = citedSet.has(r2) ? 0 : budgetClass(e, false, hit);
+        blocks.push([e, hit.reason, cls]);
+        const m = all ? undefined : mainVersion(entries, r2);
+        if (m)
+            blocks.push([m, `main version of ${r2}`, cls]);
+    }
     const files = new Lines(root);
-    const out = [];
-    const omitted = [];
-    let used = 0;
-    for (const [e, reason] of blocks) {
+    const texts = blocks.map(([e, reason]) => {
         const body = blockText(e, files);
         // a blank line closes a block with a body. Code and test paths stay one line each.
-        const t = provenance(e, reason) + body + (body ? "\n" : "");
-        const n = cpLen(t);
-        if (used + n > budget) {
-            omitted.push(e.id);
-            continue;
+        return provenance(e, reason) + body + (body ? "\n" : "");
+    });
+    // REQ-QRY-018 the blocks of the first loop always stay: each requested block and the main version of a requested ID (050/D2, 050/D3)
+    const keep = blocks.map((_, k) => k < pinned);
+    let used = 0;
+    for (let k = 0; k < pinned; k++)
+        used += cpLen(texts[k]);
+    // fill the budget class by class, in print order inside a class, and skip a block that does not fit
+    for (let cls = 0; cls <= 3; cls++) {
+        for (let k = pinned; k < blocks.length; k++) {
+            if (blocks[k][2] !== cls)
+                continue;
+            const n = cpLen(texts[k]);
+            if (used + n > budget)
+                continue;
+            keep[k] = true;
+            used += n;
         }
-        out.push(t);
-        used += n;
     }
-    let text = out.join("");
+    const omitted = blocks.filter((_, k) => !keep[k]).map(([e]) => e.id);
+    let text = texts.filter((_, k) => keep[k]).join("");
     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`;
+    return { text, omitted, chars: cpLen(text), budget, complete: omitted.length === 0 };
 }

package/dist/graph/files.js

@@ -0,0 +1,31 @@
+// REQ-QRY-006 the links of one file: code tags, Covers tags, and paths that active task lines name.
+import { canon } from "../index/canonical.js";
+import { cmpStr } from "../util/pystr.js";
+/**
+ * The direct links of a repository path as [ID, reason] pairs. The order is `implements`,
+ * `covers`, `mentions`, then by ID. An ID keeps its first reason. Only canonical IDs count.
+ */
+export function fileEdges(entries, path) {
+    const ids = canon(entries);
+    const groups = [[], [], []];
+    const seen = new Set();
+    const push = (g, id, reason) => {
+        if (!ids.has(id) || seen.has(id))
+            return;
+        seen.add(id);
+        groups[g].push([id, reason]);
+    };
+    const tagged = entries
+        .filter((e) => e.file === path && (e.kind === "code" || e.kind === "test"))
+        .sort((a, b) => a.line - b.line);
+    for (const e of tagged) {
+        const g = e.kind === "code" ? 0 : 1;
+        const verb = e.kind === "code" ? "implements" : "covers";
+        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));
+    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/input.js

@@ -0,0 +1,37 @@
+// REQ-QRY-005 REQ-QRY-011 REQ-QRY-015 turn the inputs of bundle or context into IDs, changes, and paths (047/D2).
+import { canon } from "../index/canonical.js";
+import { changeInput, resolveFileInput } from "./path.js";
+/** An ID wins over a change, and a change wins over a path (045/D1, 046/D8). */
+export function resolveInputs(root, cwd, entries, inputs) {
+    const ids = canon(entries);
+    const wanted = [];
+    const paths = new Set();
+    const unknown = [];
+    const errors = [];
+    let taskId;
+    for (const i of inputs) {
+        if (ids.has(i)) {
+            wanted.push(i);
+            if (taskId === undefined && ids.get(i).kind === "task")
+                taskId = i;
+            continue;
+        }
+        const ch = changeInput(entries, i);
+        if (ch) {
+            wanted.push(ch);
+            continue;
+        }
+        const r = resolveFileInput(root, cwd, i);
+        if ("rel" in r) {
+            wanted.push(r.rel);
+            paths.add(r.rel);
+        }
+        else if (r.error.startsWith("unknown id "))
+            unknown.push(i);
+        else
+            errors.push(r.error);
+    }
+    if (unknown.length)
+        errors.unshift(`unknown id(s): ${unknown.join(", ")}`);
+    return { wanted, paths, errors, taskId };
+}

package/dist/graph/links.js

@@ -0,0 +1,96 @@
+import { cmpStr } from "../util/pystr.js";
+const CHANGE_DIR = /^(openspec\/changes\/(?:archive\/)?[^/]+)\//;
+const CAP_SPEC = /(?:^|\/)specs\/([^/]+)\/spec\.md$/;
+/** The change folder that holds a file, or undefined. */
+export const folderOf = (file) => CHANGE_DIR.exec(file)?.[1];
+/** The capability name of a `specs/<cap>/spec.md` path, or undefined. */
+export const capNameOf = (file) => CAP_SPEC.exec(file)?.[1];
+function push(m, k, v) {
+    const l = m.get(k);
+    if (!l)
+        m.set(k, [v]);
+    else if (!l.includes(v))
+        l.push(v);
+}
+const cache = new WeakMap();
+export function structure(entries) {
+    let s = cache.get(entries);
+    if (s)
+        return s;
+    s = { deltas: new Map(), caps: new Map(), reqsOfCap: new Map(), designs: new Map(), tasksOf: new Map(), main: new Map() };
+    const modified = new Set();
+    for (const e of entries) {
+        if (e.kind === "req" || e.kind === "scn") {
+            const dir = folderOf(e.file);
+            const cap = capNameOf(e.file);
+            if (dir && cap) {
+                push(s.deltas, dir, e.id);
+                push(s.caps, dir, cap);
+            }
+            if (e.kind === "req" && e.canonical && cap)
+                push(s.reqsOfCap, cap, e.id);
+            if (e.kind === "req" && e.canonical && e.status === "modified")
+                modified.add(e.id);
+        }
+        else if (e.kind === "task" && e.links) {
+            for (const l of e.links) {
+                if (!l.startsWith("design:"))
+                    continue;
+                const d = l.slice(7);
+                push(s.designs, e.id, d);
+                push(s.tasksOf, d, e.id);
+            }
+        }
+    }
+    for (const e of entries) {
+        if (e.kind === "req" && !e.canonical && e.status === "active" && e.change === "main" && modified.has(e.id) && !s.main.has(e.id)) {
+            s.main.set(e.id, e);
+        }
+    }
+    for (const l of [s.caps, s.reqsOfCap, s.tasksOf])
+        for (const v of l.values())
+            v.sort(cmpStr);
+    cache.set(entries, s);
+    return s;
+}
+/**
+ * The structural edges that leave one entry, as [ID, reason] pairs. A task reaches its deltas and a
+ * capability reaches its requirements only when each is the start of the walk (046/D5).
+ */
+export function structuralEdges(s, ex, x, isStart, has) {
+    const out = [];
+    const put = (id, reason) => {
+        if (has(id))
+            out.push([id, reason]);
+    };
+    if (ex.kind === "task") {
+        // like a capability, a task reaches its deltas only as the start, so depth 2 adds no sibling (046/D5)
+        const dir = folderOf(ex.file);
+        if (isStart)
+            for (const id of (dir && s.deltas.get(dir)) || [])
+                put(id, `delta in change of ${x}`);
+        for (const id of s.designs.get(x) ?? [])
+            put(id, `design named in ${x}`);
+    }
+    else if (ex.kind === "decision") {
+        for (const id of s.tasksOf.get(x) ?? [])
+            put(id, `task names ${x}`);
+    }
+    else if (ex.kind === "req") {
+        const cap = capNameOf(ex.file);
+        if (cap)
+            put(`cap/${cap}`, `capability of ${x}`);
+    }
+    else if (ex.kind === "cap" && isStart) {
+        for (const id of s.reqsOfCap.get(ex.title) ?? [])
+            put(id, `requirement in ${x}`);
+    }
+    else if (ex.kind === "change") {
+        const dir = folderOf(ex.file);
+        for (const id of (dir && s.deltas.get(dir)) || [])
+            put(id, `delta in ${x}`);
+        for (const c of (dir && s.caps.get(dir)) || [])
+            put(`cap/${c}`, `capability touched by ${x}`);
+    }
+    return out;
+}

package/dist/graph/path.js

@@ -0,0 +1,54 @@
+// REQ-QRY-005 REQ-QRY-008 REQ-QRY-011 turn the input of related or bundle into a change or a repository path.
+import { realpathSync, statSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { changeKey, resolveChange } from "../index/scan.js";
+const ID_SHAPE = /^(?:(?:REQ|SCN)-[A-Z]{2,6}-\d{3}(?:-\d+)?|ADR-\d{3}|[^/\s]+\/(?:\d+\.\d+|D\d+)|(?:change|cap)\/[^/\s]+)$/;
+/**
+ * REQ-QRY-011 a change key or a folder name that is no ID resolves to `change/<key>`.
+ * The caller runs this after the ID check and before the path rule (046/D8).
+ */
+export function changeInput(entries, input) {
+    const folder = resolveChange(entries, input);
+    if (folder === undefined)
+        return undefined;
+    const id = `change/${changeKey(folder)}`;
+    return entries.some((e) => e.id === id) ? id : undefined;
+}
+/** An input that looks like an ID. When it is no file, the error is `unknown id`. */
+export const idShaped = (input) => ID_SHAPE.test(input);
+function real(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return null;
+    }
+}
+/** REQ-QRY-008 the path against the root, then against the working directory. The result is a file inside the root. */
+export function resolveFileInput(root, cwd, input) {
+    const realRoot = real(root) ?? root;
+    const tries = isAbsolute(input) ? [input] : [resolve(root, input), resolve(cwd, input)];
+    let found = null;
+    for (const t of tries) {
+        const r = real(t);
+        if (r !== null) {
+            found = r;
+            break;
+        }
+    }
+    if (found === null)
+        return idShaped(input) ? { error: `unknown id ${input}` } : { error: `no such file: ${input}` };
+    const rel = relative(realRoot, found);
+    if (rel === "" || rel.startsWith("..") || isAbsolute(rel))
+        return { error: `outside the repository: ${input}` };
+    let isFile = false;
+    try {
+        isFile = statSync(found).isFile();
+    }
+    catch {
+        isFile = false;
+    }
+    if (!isFile)
+        return idShaped(input) ? { error: `unknown id ${input}` } : { error: `not a file: ${input}` };
+    return { rel: rel.split(sep).join("/") };
+}

package/dist/graph/query.js

@@ -9,6 +9,9 @@ export function query(entries, args, o = {}) {
     const kind = o.kind?.toLowerCase();
     const hits = [];
     for (const e of poolOf(entries, !!o.all)) {
+        // REQ-QRY-013 change and cap entries show only for an explicit --kind
+        if (!kind && (e.kind === "cap" || e.kind === "change"))
+            continue;
         if ((kind && e.kind !== kind) || (o.change && !matchesChange(e.change, o.change)))
             continue;
         // REQ-IDX-005 --change takes a key or a full folder name

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();