spec-ctx 0.1.2 → 0.3.0

package/dist/config.js

@@ -2,6 +2,8 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { parse } from "smol-toml";
+/** REQ-DIST-002 the command that gate runs for openspec validate (018/D1). */
+export const DEFAULT_OPENSPEC = "npx -y @fission-ai/openspec@latest";
 export const CONFIG_FILE = "spec-ctx.toml";
 export function defaults() {
     return {
@@ -13,10 +15,12 @@ export function defaults() {
             tests: ["tests/**"],
             ignore: [],
         },
-        ids: { caps: [], task_pattern: "\\d+\\.\\d+", paths: {} },
+        ids: { caps: [], task_pattern: "\\d+\\.\\d+", paths: {}, brackets: false },
         bundle: { budget: 8000, depth: 1 },
         verify: { timeout_s: 600 },
-        gate: { markdown: ["openspec/**/*.md", "decisions/*.md", "docs/**/*.md", "*.md"] },
+        // REQ-DIST-002 the gate lints nothing unless the project opts in (022/D1, ADR-006 item 9)
+        gate: { markdown: [], openspec: DEFAULT_OPENSPEC, base: "origin/main" },
+        loop: { max_attempts: 3, archive: "ask" },
     };
 }
 export class ConfigError extends Error {
@@ -65,6 +69,12 @@ export function loadConfig(root) {
         }
         cfg.ids.paths = { ...v };
     }
+    // REQ-ADOPT-010 the header form that adopt and id new write (027/D2)
+    if ("brackets" in ids) {
+        if (typeof ids.brackets !== "boolean")
+            throw new ConfigError(`${CONFIG_FILE}: ids.brackets must be true or false.`);
+        cfg.ids.brackets = ids.brackets;
+    }
     const bundle = sec("bundle");
     for (const k of ["budget", "depth"]) {
         if (k in bundle) {
@@ -86,6 +96,32 @@ export function loadConfig(root) {
     const gate = sec("gate");
     if ("markdown" in gate)
         cfg.gate.markdown = strList(gate.markdown, "gate.markdown");
+    // REQ-DIST-002 the OpenSpec command. An empty string would run " validate", so it is an error too (018/D1).
+    if ("openspec" in gate) {
+        if (typeof gate.openspec !== "string" || !gate.openspec.trim())
+            throw new ConfigError(`${CONFIG_FILE}: gate.openspec must be a string that is not empty.`);
+        cfg.gate.openspec = gate.openspec;
+    }
+    // REQ-ADOPT-008 the ref whose merge base with HEAD holds the baseline that gate compares with (020/D5)
+    if ("base" in gate) {
+        if (typeof gate.base !== "string" || !gate.base.trim())
+            throw new ConfigError(`${CONFIG_FILE}: gate.base must be a string that is not empty.`);
+        cfg.gate.base = gate.base;
+    }
+    // REQ-LOOP-003 the loop keys (024/D6)
+    const loop = sec("loop");
+    if ("max_attempts" in loop) {
+        const v = loop.max_attempts;
+        if (typeof v !== "number" || !Number.isInteger(v) || v < 1)
+            throw new ConfigError(`${CONFIG_FILE}: loop.max_attempts must be an integer of 1 or more.`);
+        cfg.loop.max_attempts = v;
+    }
+    if ("archive" in loop) {
+        const v = loop.archive;
+        if (v !== "ask" && v !== "auto")
+            throw new ConfigError(`${CONFIG_FILE}: loop.archive must be "ask" or "auto".`);
+        cfg.loop.archive = v;
+    }
     return cfg;
 }
 /** The file that `specctx init` writes. Each key has a comment above it. */
@@ -111,6 +147,9 @@ ignore = []
 caps = []
 # Pattern of the task number in a tasks.md checkbox.
 task_pattern = '\\d+\\.\\d+'
+# true makes adopt and id new write the ID in square brackets, [REQ-UA-001], as OpenSpec PR #1979 reads it.
+# false writes the bare form, REQ-UA-001. The scan reads both forms.
+brackets = false
 
 [bundle]
 # Default character budget of a bundle.
@@ -123,6 +162,18 @@ depth = 1
 timeout_s = 600
 
 [gate]
-# Markdown globs that gate lints. The baseline holds the lint debt of these files.
-markdown = ["openspec/**/*.md", "decisions/*.md", "docs/**/*.md", "*.md"]
+# Markdown globs that gate lints with the tells and STE linters. Empty means no lint.
+# To turn it on, set markdown = ["openspec/**/*.md", "decisions/*.md", "docs/**/*.md", "*.md"]. The spec-ctx repository opts in.
+markdown = []
+# The command that gate runs for openspec validate. Set it to "openspec" for a global install or a fork,
+# or pin a version. The env var SPECCTX_OPENSPEC overrides it for one run.
+openspec = "npx -y @fission-ai/openspec@latest"
+# The ref whose merge base with HEAD holds the baseline that gate compares with. New entries fail the gate.
+base = "origin/main"
+
+[loop]
+# Verify failures on one task before task done writes a question and the loop stops.
+max_attempts = 3
+# "ask" stops before archive for a human. "auto" lets the loop archive when the gate passes.
+archive = "ask"
 `;

package/dist/handoff/handoff.js

@@ -2,11 +2,13 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { UsageExit } from "../cli/errors.js";
-import { changeKey } from "../index/scan.js";
+import { changeKey, matchesChange } from "../index/scan.js";
+import { activeFolders } from "../loop/next.js";
 import { listEvidence } from "../tasks/evidence.js";
 import { activeChanges, nextTask } from "../tasks/tasks.js";
 import { cmpStr, splitLines } from "../util/pystr.js";
-import { isoNow, today } from "../util/time.js";
+import { isoNow } from "../util/time.js";
+import { addQuestion, fromHandoffItems, hasQuestions, readQuestions, renderQuestions, resolveQuestion, writeQuestions } from "./questions.js";
 export const HANDOFF_PATH = ".ctx/handoff.md";
 export const CURRENT_PATH = ".ctx/current.json";
 const SCALARS = ["change", "current", "base", "as_of"];
@@ -86,9 +88,24 @@ function evidenceRows(root, active) {
     return rows;
 }
 const AT = / \(at (\S+)\)$/;
+/**
+ * REQ-HND-002 move the questions of an old handoff.md into questions.json once (022/D8).
+ * Returns the count, 0 when the file exists or the handoff has no question.
+ */
+function migrateQuestions(root, prev) {
+    if (!prev || hasQuestions(root))
+        return 0;
+    if (!prev.open_questions.length && !prev.resolved.length)
+        return 0;
+    const qs = fromHandoffItems(prev.open_questions, prev.resolved);
+    writeQuestions(root, qs);
+    return qs.length;
+}
 /** Generate the handoff. Two runs with no change in between write the same bytes. */
 export function writeHandoff(root, entries) {
     const prev = readHandoff(root);
+    const migrated = migrateQuestions(root, prev);
+    const lists = renderQuestions(readQuestions(root));
     const active = activeChanges(entries);
     const next = nextTask(root, entries);
     const rows = evidenceRows(root, active);
@@ -108,41 +125,57 @@ export function writeHandoff(root, entries) {
             const m = AT.exec(item.split("\n")[0]);
             return !m || after(m[1]);
         }),
-        open_questions: prev?.open_questions ?? [],
-        resolved: prev?.resolved ?? [],
+        // REQ-HND-001 both lists come from questions.json, never from the previous file (022/D7)
+        open_questions: lists.open_questions,
+        resolved: lists.resolved,
         next: next ? `${next.id}  ${next.text}` : "no open task",
         evidence: `${rows.length} task(s), ${rows.filter((r) => r.kind === "command").length} command, ${rows.filter((r) => r.kind === "manual").length} manual`,
     };
     save(root, h);
+    if (migrated)
+        h.migrated = migrated;
     return h;
 }
-function ensure(root, entries) {
-    return readHandoff(root) ?? writeHandoff(root, entries);
-}
-export function ask(root, entries, text) {
-    const q = text.replace(/\s*\n\s*/g, " ").trim();
-    if (!q)
-        throw new UsageExit("handoff ask needs a question");
-    const h = ensure(root, entries);
-    h.open_questions.push(`${q} (task ${currentTask(root)}, ${today()})`);
+/** The handoff with its two question lists rendered again from questions.json. The other sections stay. */
+function refresh(root, entries) {
+    const h = readHandoff(root) ?? writeHandoff(root, entries);
+    const lists = renderQuestions(readQuestions(root));
+    h.open_questions = lists.open_questions;
+    h.resolved = lists.resolved;
     save(root, h);
     return h;
 }
-export function resolve(root, entries, n, answer) {
-    const h = ensure(root, entries);
-    if (!Number.isInteger(n) || n < 1 || n > h.open_questions.length) {
-        throw new UsageExit(`no open question ${n}. The handoff has ${h.open_questions.length}`);
+/**
+ * REQ-HND-002 append an open question to questions.json and render the handoff again (022/D6).
+ * REQ-LOOP-005 with a change, the question carries the active change folder, so next blocks the change (029/D1).
+ */
+export function ask(root, entries, text, change) {
+    let task = currentTask(root);
+    let stage;
+    if (change !== undefined) {
+        const folder = activeFolders(root).find((f) => matchesChange(f, change));
+        if (folder === undefined)
+            throw new UsageExit(`no active change ${change}`);
+        task = folder;
+        stage = stageOf(entries, folder);
     }
-    const a = answer.replace(/\s*\n\s*/g, " ").trim();
-    if (!a)
-        throw new UsageExit("handoff resolve needs an answer");
-    const [item] = h.open_questions.splice(n - 1, 1);
-    h.resolved.push(`${item.split("\n")[0]} answer: ${a}`);
-    save(root, h);
+    const q = addQuestion(root, task, text, stage);
+    const h = refresh(root, entries);
+    h.asked = q.n;
     return h;
 }
+/** REQ-LOOP-007 archive when the change has a task and every task is [x], plan otherwise. The text plays no part (031/D1). */
+export function stageOf(entries, folder) {
+    const tasks = entries.filter((e) => e.kind === "task" && e.change === folder && !e.file.includes("/archive/"));
+    return tasks.length > 0 && tasks.every((t) => t.status === "done") ? "archive" : "plan";
+}
+/** 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);
+    return refresh(root, entries);
+}
 export function addReopened(root, entries, task, reason) {
-    const h = ensure(root, entries);
+    const h = readHandoff(root) ?? writeHandoff(root, entries);
     h.reopened.push(`${task} ${reason.replace(/\s*\n\s*/g, " ").trim()} (at ${isoNow()})`);
     save(root, h);
 }

package/dist/handoff/questions.js

@@ -0,0 +1,101 @@
+// REQ-HND-002 the open and resolved questions in .ctx/questions.json (022/D6, ADR-006 item 1).
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { UsageExit } from "../cli/errors.js";
+import { isoNow } from "../util/time.js";
+export const QUESTIONS_PATH = ".ctx/questions.json";
+/** The questions sorted by n. An absent file is an empty list. A damaged file is a usage error, not a crash. */
+export function readQuestions(root) {
+    const p = join(root, QUESTIONS_PATH);
+    if (!existsSync(p))
+        return [];
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(p, "utf8"));
+    }
+    catch {
+        throw new UsageExit(`${QUESTIONS_PATH} is not valid JSON`);
+    }
+    if (!Array.isArray(raw))
+        throw new UsageExit(`${QUESTIONS_PATH} must hold a JSON list`);
+    return raw.slice().sort((a, b) => a.n - b.n);
+}
+export function hasQuestions(root) {
+    return existsSync(join(root, QUESTIONS_PATH));
+}
+export function writeQuestions(root, qs) {
+    mkdirSync(join(root, ".ctx"), { recursive: true });
+    const sorted = qs.slice().sort((a, b) => a.n - b.n);
+    writeFileSync(join(root, QUESTIONS_PATH), JSON.stringify(sorted, null, 2) + "\n");
+}
+/** One line of text. A question or an answer never spans lines in the file. */
+export function oneLine(text) {
+    return text.replace(/\s*\n\s*/g, " ").trim();
+}
+/** REQ-HND-002 append an open question with the next n. Returns the new question. */
+export function addQuestion(root, task, text, stage) {
+    const q = oneLine(text);
+    if (!q)
+        throw new UsageExit("handoff ask needs a question");
+    const qs = readQuestions(root);
+    const n = qs.reduce((m, x) => Math.max(m, x.n), 0) + 1;
+    const item = { n, asked_at: isoNow(), task, text: q, status: "open" };
+    if (stage !== undefined)
+        item.stage = stage;
+    qs.push(item);
+    writeQuestions(root, qs);
+    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) {
+    const qs = readQuestions(root);
+    const item = qs.find((x) => x.n === n && x.status === "open");
+    if (!Number.isInteger(n) || !item) {
+        const open = qs.filter((x) => x.status === "open").length;
+        throw new UsageExit(`no open question ${n}. The file has ${open} open question(s)`);
+    }
+    const a = oneLine(answer);
+    if (!a)
+        throw new UsageExit("handoff resolve needs an answer");
+    item.status = "resolved";
+    item.answer = a;
+    item.resolved_at = isoNow();
+    writeQuestions(root, qs);
+    return item;
+}
+const ITEM = /^(.*) \(task (\S+), (\d{4}-\d{2}-\d{2})\)(?: answer: (.*))?$/s;
+/**
+ * REQ-HND-002 the questions of an old handoff.md as objects (022/D8). Resolved items come first, then open ones,
+ * with n from 1 in that order. An item that does not match the old pattern keeps its whole text and task none.
+ */
+export function fromHandoffItems(open, resolved) {
+    const out = [];
+    const push = (item, status) => {
+        const m = ITEM.exec(item);
+        const q = m
+            ? { n: out.length + 1, asked_at: m[3], task: m[2], text: oneLine(m[1]), status }
+            : { n: out.length + 1, asked_at: "none", task: "none", text: oneLine(item), status };
+        if (status === "resolved")
+            q.answer = m?.[4] !== undefined ? oneLine(m[4]) : "";
+        out.push(q);
+    };
+    for (const item of resolved)
+        push(item, "resolved");
+    for (const item of open)
+        push(item, "open");
+    return out;
+}
+/** The last 10 resolved entries render. The rest stay in the file. */
+export const RESOLVED_SHOWN = 10;
+/** REQ-HND-001 the two lists of handoff.md as rendered item text (022/D7). */
+export function renderQuestions(qs) {
+    const date = (q) => q.asked_at.slice(0, 10);
+    const head = (q) => `Q${q.n} ${q.text} (task ${q.task}, ${date(q)})`;
+    const open = qs.filter((q) => q.status === "open").map(head);
+    const done = qs.filter((q) => q.status === "resolved");
+    const shown = done.slice(-RESOLVED_SHOWN).map((q) => `${head(q)} answer: ${q.answer ?? ""}`);
+    const more = done.length - Math.min(done.length, RESOLVED_SHOWN);
+    if (more > 0)
+        shown.push(`and ${more} more in ${QUESTIONS_PATH}`);
+    return { open_questions: open, resolved: shown };
+}

package/dist/ids/ids.js

@@ -1,4 +1,4 @@
-// REQ-IDS-001 REQ-IDS-002 REQ-IDS-003 ID allocation and retirement.
+// REQ-IDS-001 REQ-IDS-002 REQ-IDS-003 REQ-IDS-004 ID allocation and retirement.
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { UsageExit } from "../cli/errors.js";
@@ -48,23 +48,28 @@ export function newIds(root, cfg, entries, o) {
         return cap;
     };
     const seq = (start, fmt) => Array.from({ length: o.count }, (_, i) => fmt(start + i));
+    // REQ-IDS-004 a REQ or SCN ID goes into a header, so it takes the configured form (027/D5)
+    const form = (ids) => (cfg.ids.brackets ? ids.map((id) => `[${id}]`) : ids);
     switch (kind) {
         case "REQ": {
             const cap = checkCap(o.cap);
             const start = next(new RegExp(`^REQ-${cap}-(\\d{3})$`));
             if (start + o.count - 1 > 999)
                 throw new UsageExit(`no free REQ number for ${cap}`);
-            return seq(start, (n) => `REQ-${cap}-${pad(n)}`);
+            return form(seq(start, (n) => `REQ-${cap}-${pad(n)}`));
         }
         case "SCN": {
             const cap = checkCap(o.cap);
             if (!o.forReq)
                 throw new UsageExit("id new SCN needs --for <REQ-ID>");
-            const m = /^REQ-([A-Z]{2,6})-(\d{3})$/.exec(o.forReq);
-            if (!m || m[1] !== cap)
+            // REQ-IDS-004 --for takes the bare or the bracketed form
+            const m = /^(?:REQ-([A-Z]{2,6})-(\d{3})|\[REQ-([A-Z]{2,6})-(\d{3})\])$/.exec(o.forReq);
+            const forCap = m?.[1] ?? m?.[3];
+            const forNum = m?.[2] ?? m?.[4];
+            if (!m || forCap !== cap)
                 throw new UsageExit(`--for ${o.forReq} is not a REQ ID of ${cap}`);
-            const start = next(new RegExp(`^SCN-${cap}-${m[2]}-(\\d+)$`));
-            return seq(start, (n) => `SCN-${cap}-${m[2]}-${n}`);
+            const start = next(new RegExp(`^SCN-${cap}-${forNum}-(\\d+)$`));
+            return form(seq(start, (n) => `SCN-${cap}-${forNum}-${n}`));
         }
         case "ADR": {
             const start = next(/^ADR-(\d{3})$/);

package/dist/index/scan.js

@@ -8,8 +8,10 @@ const S = "[ \\t\\n\\r\\f\\v]";
 export const ID_RE = /\b(REQ-[A-Z]{2,6}-\d{3}|SCN-[A-Z]{2,6}-\d{3}-\d+|ADR-\d{3})\b/g;
 const ID_FULL = /^(?:REQ-[A-Z]{2,6}-\d{3}|SCN-[A-Z]{2,6}-\d{3}-\d+|ADR-\d{3})$/;
 const SCN_RE = /\bSCN-[A-Z]{2,6}-\d{3}-\d+\b/g;
-const REQ_HDR = new RegExp(`^### Requirement:${S}*(REQ-[A-Z]{2,6}-\\d{3})?${S}*(.*)$`, "s");
-const SCN_HDR = new RegExp(`^#### Scenario:${S}*(SCN-[A-Z]{2,6}-\\d{3}-\\d+)?${S}*(.*)$`, "s");
+// REQ-IDX-006 the ID is bare or in square brackets, the form OpenSpec reads since PR #1979 (027/D1).
+// Group 1 is the bare ID, group 2 the bracketed ID, group 3 the title.
+const REQ_HDR = new RegExp(`^### Requirement:${S}*(?:(REQ-[A-Z]{2,6}-\\d{3})|\\[(REQ-[A-Z]{2,6}-\\d{3})\\](?=${S}|$))?${S}*(.*)$`, "s");
+const SCN_HDR = new RegExp(`^#### Scenario:${S}*(?:(SCN-[A-Z]{2,6}-\\d{3}-\\d+)|\\[(SCN-[A-Z]{2,6}-\\d{3}-\\d+)\\](?=${S}|$))?${S}*(.*)$`, "s");
 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");
@@ -219,8 +221,8 @@ export function scanMarkdown(sc, rpath, entries, problems) {
         }
         let m = REQ_HDR.exec(line);
         if (m) {
-            const rid = m[1];
-            const title = pyStrip(m[2]);
+            const rid = m[1] ?? m[2];
+            const title = pyStrip(m[3]);
             if (!rid) {
                 // REQ-CHK-001 an archived header without an ID is history. adopt never writes it.
                 if (status !== "archived")
@@ -245,8 +247,8 @@ export function scanMarkdown(sc, rpath, entries, problems) {
         }
         m = SCN_HDR.exec(line);
         if (m) {
-            const sid = m[1];
-            const title = pyStrip(m[2]);
+            const sid = m[1] ?? m[2];
+            const title = pyStrip(m[3]);
             if (!sid) {
                 if (status !== "archived")
                     problems.push([rpath, i, "missing-id", title]);