spec-ctx 0.1.0 → 0.1.2

package/dist/cli/commands.js

@@ -3,6 +3,7 @@ import { resolve } from "node:path";
 import { UsageExit } from "./errors.js";
 import { findRoot, requireOpenSpec } from "./root.js";
 import { hintOf } from "../check/hints.js";
+import { paint } from "./color.js";
 /** check with warnings and the baseline filter. Strict mode adds the strict rules and the warnings. */
 async function runCheck(root, cfg, data, strict) {
     const { check } = await import("../check/check.js");
@@ -20,13 +21,14 @@ async function runCheck(root, cfg, data, strict) {
  * REQ-CHK-004 the findings, then a blank line, the summary line, and one line per rule with its hint.
  * A warning counts as advisory. The `baselined` line stays last (REQ-CHK-002).
  */
-export function checkText(r) {
-    const body = r.findings.map((x) => `${x.file}:${x.line}  ${x.rule}  ${x.id}\n`).join("")
+export function checkText(r, tty) {
+    // REQ-CLI-008 every finding of check is hard, so every finding line is red. stale-evidence is one of them.
+    const body = r.findings.map((x) => paint("fail", `${x.file}:${x.line}  ${x.rule}  ${x.id}\n`, tty)).join("")
         + r.warnings.map((w) => `warning: ${w}\n`).join("");
     const base = r.baselined ? `baselined: ${r.baselined}\n` : "";
     const n = r.findings.length + r.warnings.length;
     if (!n)
-        return `0 findings\n${base}`;
+        return paint("dim", "0 findings\n", tty) + base;
     const files = new Set(r.findings.map((x) => x.file));
     const count = new Map();
     for (const x of r.findings)
@@ -40,7 +42,7 @@ export function checkText(r) {
     }
     const rules = [...count.keys()].sort();
     return body
-        + `\n${n} finding${n === 1 ? "" : "s"} in ${files.size} file${files.size === 1 ? "" : "s"} (${r.findings.length} hard, ${r.warnings.length} advisory)\n`
+        + "\n" + paint("dim", `${n} finding${n === 1 ? "" : "s"} in ${files.size} file${files.size === 1 ? "" : "s"} (${r.findings.length} hard, ${r.warnings.length} advisory)\n`, tty)
         + rules.map((rule) => `${rule}  ${count.get(rule)}  ${hintOf(rule)}\n`).join("")
         + base;
 }
@@ -88,9 +90,9 @@ export async function run(p, io) {
             print(plan);
         else if (!plan.edits.length)
             io.out(plan.unmatched.length ? planLines(plan).join("\n") + "\nnothing to adopt\n" : "nothing to adopt\n");
-        // REQ-CLI-007 the dry run ends with the next step. The exit code stays 1.
+        // REQ-CLI-007 the dry run ends with the next step. REQ-ADOPT-001 the exit code stays 1 and the last line says why (017/D5).
         else
-            io.out(planLines(plan).join("\n") + `\n${plan.edits.length} headers need an ID. Next: specctx adopt\n`);
+            io.out(planLines(plan).join("\n") + `\nexit 1: ${plan.edits.length} headers need an ID. Next: specctx adopt\n`);
         return plan.edits.length ? 1 : 0;
     }
     if (cmd === "baseline write" || cmd === "baseline prune") {
@@ -104,15 +106,18 @@ export async function run(p, io) {
         const data = buildIndex(root, cfg);
         const findings = check(root, cfg, data, true);
         const warnings = manualWarnings(root, data.entries, listEvidence(root));
+        // REQ-ADOPT-007 the lint debt of the gate globs joins the baseline
+        const { lintCounts } = await import("../lint/counts.js");
+        const lint = lintCounts(root, cfg.gate.markdown.join(" ")).counts;
         if (cmd === "baseline write") {
-            const list = writeBaseline(root, findings, warnings);
+            const list = writeBaseline(root, findings, warnings, lint);
             if (json)
                 print({ baseline: BASELINE_PATH, entries: list.length });
             else
                 io.out(`wrote ${BASELINE_PATH} with ${list.length} entr${list.length === 1 ? "y" : "ies"}\n`);
         }
         else {
-            const n = pruneBaseline(root, findings, warnings);
+            const n = pruneBaseline(root, findings, warnings, lint);
             if (json)
                 print({ pruned: n });
             else
@@ -123,18 +128,19 @@ export async function run(p, io) {
     if (cmd === "gate") {
         if (p.positional.length)
             throw new UsageExit("gate takes no arguments");
-        const { runGate, DEFAULT_MARKDOWN } = await import("./gate.js");
+        const { runGate } = await import("./gate.js");
         const strict = !!f.strict;
         return runGate(root, {
             strict,
-            markdown: f.markdown ?? DEFAULT_MARKDOWN,
+            markdown: f.markdown ?? cfg.gate.markdown.join(" "),
+            json,
             check: async () => {
                 const { buildIndex } = await import("../index/build.js");
                 const { check } = await import("../check/check.js");
                 void check;
                 const data = buildIndex(root, cfg);
                 const r = await runCheck(root, cfg, data, strict);
-                return { code: r.findings.length ? 1 : 0, out: checkText(r) };
+                return { code: r.findings.length ? 1 : 0, out: checkText(r, io.tty) };
             },
         }, io);
     }
@@ -143,7 +149,8 @@ export async function run(p, io) {
         if (p.positional.length < n)
             throw new UsageExit(`${cmd} needs ${what}`);
     };
-    if (cmd === "query")
+    // REQ-QRY-001 no term lists a whole change. Without --change a term is required (017/D6).
+    if (cmd === "query" && !f.change)
         need(1, "at least one term");
     if (cmd === "related") {
         need(1, "one ID");
@@ -169,8 +176,9 @@ export async function run(p, io) {
             const r = statusReport(root, entries);
             if (json)
                 print(r);
+            // REQ-CLI-008 the next: line is dim
             else
-                io.out(statusLines(r).map((l) => l + "\n").join(""));
+                io.out(statusLines(r).map((l) => (l.startsWith("next: ") ? paint("dim", l, io.tty) : l) + "\n").join(""));
             return 0;
         }
         case "query": {
@@ -248,7 +256,7 @@ export async function run(p, io) {
             if (json)
                 print({ baselined: r.baselined, count: r.findings.length, findings: r.findings, warnings: r.warnings });
             else
-                io.out(checkText(r));
+                io.out(checkText(r, io.tty));
             return r.findings.length ? 1 : 0;
         }
     }
@@ -264,12 +272,14 @@ async function init(p, io) {
     if (p.flags.json)
         io.out(JSON.stringify(r, null, 2) + "\n");
     else if (r.nothing)
-        io.out("nothing to do\nnext: specctx status\n");
+        io.out("nothing to do\n" + r.notes.map((n) => `${n}\n`).join("") + paint("dim", "next: specctx status\n", io.tty));
     else {
         io.out(r.written.map((w) => `wrote ${w}\n`).join(""));
         io.out(r.kept.map((k) => `kept ${k}\n`).join(""));
-        // REQ-CLI-007 init ends with the next step
-        io.out("next: specctx status\n");
+        io.out(r.notes.map((n) => `${n}\n`).join(""));
+        // REQ-CLI-007 init ends with the next step. REQ-DIST-002 a kept changed file points to --force (014/D2).
+        const again = ["specctx init", all ? "--all" : [p.flags.schema ? "--schema" : "", p.flags.skills ? "--skills" : ""].filter(Boolean).join(" "), "--force"].filter(Boolean).join(" ");
+        io.out(paint("dim", `next: ${r.changed.length ? again : "specctx status"}\n`, io.tty));
     }
     return 0;
 }

package/dist/cli/gate.js

@@ -40,6 +40,8 @@ export function markdownFiles(root, globs) {
 }
 export const GATE_LOG = ".ctx/gate-log.jsonl";
 /** REQ-STAT-005 the gate steps in order. The log names the step that failed. */
+/** REQ-CLI-004 the lint detail stops here unless --json asks for every line. */
+export const LINT_DETAIL_CAP = 50;
 export const GATE_STEPS = ["check", "lint tells", "lint ste", "validate", "spec-length"];
 /** REQ-STAT-005 one JSON line per gate run, after the last step or at the first failure. */
 export function appendGateLog(root, line) {
@@ -66,33 +68,24 @@ async function gateSteps(root, o, io, ran) {
     }
     io.out(`check: ok${o.strict ? " (strict)" : ""}\n`);
     // gate 2: REQ-LINT-003 both linters of this package on the markdown globs. No python3.
-    const { lintSte } = await import("../lint/ste.js");
-    const { lintTells } = await import("../lint/tells.js");
-    const { steReport } = await import("../lint/cli.js");
-    const files = markdownFiles(root, o.markdown);
-    const bad = [];
-    let tellsFailed = false;
+    // REQ-ADOPT-007 the step fails only on a count above its baseline line.
+    const { lintCounts, lintRises } = await import("../lint/counts.js");
+    const { readBaseline } = await import("../baseline/baseline.js");
     ran.push("lint tells", "lint ste");
-    const noRotation = new Set(["synonym-rotation"]);
-    for (const f of files) {
-        const text = readFileSync(join(root, f), "utf8").replace(/\r\n?/g, "\n");
-        const tells = lintTells(text);
-        const hard = tells.filter((x) => x.level === "hard");
-        if (hard.length)
-            tellsFailed = true;
-        if (hard.length)
-            bad.push(`${f}\n` + tells.map((x) => `${f}:${x.line}: [${x.level}] ${x.rule}: ${x.match}\n`).join("") + `${hard.length} hard finding(s), baseline 0\n`);
-        const r = lintSte(text, f);
-        const ste = r.findings.filter((x) => !noRotation.has(x.rule));
-        const steHard = ste.filter((x) => x.level === "advisory-free").length;
-        if (steHard)
-            bad.push(`${f}\n` + steReport(ste, r.words, false, steHard, 0));
+    const { counts, files } = lintCounts(root, o.markdown);
+    const base = readBaseline(root);
+    const rises = lintRises(counts, base);
+    const baselined = [...base ?? []].filter((l) => l.startsWith("lint ")).length;
+    if (rises.length) {
+        const newFindings = rises.reduce((a, r) => a + r.current - r.baseline, 0);
+        const inFiles = new Set(rises.map((r) => r.key.split(" ")[1])).size;
+        const lines = rises.map((r) => `${r.key.slice(5).replace(" ", "  ")}  ${r.current} (baseline ${r.baseline})`);
+        const shown = o.json ? lines : lines.slice(0, LINT_DETAIL_CAP);
+        const more = lines.length - shown.length;
+        io.out(`linters: fail, ${newFindings} new finding(s) in ${inFiles} file(s)\n` + shown.map((l) => l + "\n").join("") + (more ? `... ${more} more line(s)\n` : ""));
+        return rises.some((r) => r.key.includes(" tells:")) ? "lint tells" : "lint ste";
     }
-    if (bad.length) {
-        io.out("linters: fail\n" + bad.join(""));
-        return tellsFailed ? "lint tells" : "lint ste";
-    }
-    io.out(`linters: ok (${files.length} file(s))\n`);
+    io.out(`linters: ok (${files} file(s)${baselined ? `, ${baselined} baselined` : ""})\n`);
     ran.push("validate");
     // gate 3: openspec validate. SPECCTX_OPENSPEC replaces the command, for tests and offline use.
     const cmd = process.env.SPECCTX_OPENSPEC ?? "npx -y @fission-ai/openspec@latest";

package/dist/cli/help.js

@@ -23,9 +23,9 @@ export const TABLE = [
     // Read
     { name: "status", group: "Read", args: "", summary: "Show the active changes, the current task, and the open questions.", flags: [], exit: PLAIN, example: "specctx status" },
     {
-        name: "query", group: "Read", args: "<term...>", summary: "Find the entries that contain all terms.",
+        name: "query", group: "Read", args: "[term...]", summary: "Find the entries that contain all terms. With --change and no term, list every entry of that change.",
         flags: [
-            ["--kind <kind>", "Show only entries of this kind."],
+            ["--kind <kind>", "Show only entries of this kind. Any case works."],
             ["--change <name>", "Show only entries of this change. The key or the full folder name works."],
             ["--limit <n>", "Show n lines at most. The default is 20. Use 0 for no limit."],
             ["--all", "Show all copies of an ID."],
@@ -56,7 +56,7 @@ export const TABLE = [
         summary: "Run `check`, the markdown linters, `openspec validate`, and the length check. Stop at the first failure.",
         flags: [
             ["--strict", "Run `check` and `openspec validate` in strict mode."],
-            ["--markdown <globs>", "Lint these markdown globs. Separate them with spaces."],
+            ["--markdown <globs>", "Lint these markdown globs instead of [gate] markdown. Separate them with spaces."],
         ],
         exit: [["0", "Every step passed."], ["1", "A step failed."], USAGE, INTERNAL], example: "specctx gate --strict",
     },
@@ -122,7 +122,7 @@ export const TABLE = [
             ["--schema", "Also install the spec-driven-ids schema and add its rules to openspec/config.yaml."],
             ["--skills", "Also install the three skills in .claude/skills and .agents/skills."],
             ["--all", "Do all three."],
-            ["--force", "Install over files that exist. An existing spec-ctx.toml stays."],
+            ["--force", "Replace the files that have other content. spec-ctx.toml stays."],
         ],
         exit: PLAIN, example: "specctx init --all",
     },
@@ -133,7 +133,7 @@ export const TABLE = [
         example: "specctx adopt --dry-run",
     },
     {
-        name: "task backfill", group: "Setup", args: "--manual <note>", summary: "Write manual evidence for every ticked task that has none.",
+        name: "task backfill", group: "Setup", args: "--manual <note>", summary: "Write manual evidence for every ticked task of an active change that has none.",
         flags: [["--manual <note>", "The note for the evidence. The flag is required."], ["--change <name>", "Look only in this change."]],
         exit: PLAIN, example: "specctx task backfill --manual \"done before spec-ctx\"",
     },

package/dist/cli/workflow.js

@@ -2,6 +2,7 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { dumps } from "../util/json.js";
+import { paint } from "./color.js";
 import { UsageExit } from "./errors.js";
 const arg = (c, n, what) => {
     const v = c.p.positional[n];
@@ -91,10 +92,12 @@ export async function runWorkflow(c) {
             const { cpLen } = await import("../util/pystr.js");
             // REQ-STAT-002 the bundle size goes next to the current task, so stats can compute the context ratio
             writeFileSync(join(c.root, CURRENT_PATH), dumps({ bundle_chars: cpLen(b.text), started_at: isoNow(), task: t.id }) + "\n");
+            // REQ-TASK-002 a task that cites no REQ gets one hint line, so the agent knows what to add
+            const hint = t.reqs.length ? null : `task ${t.id} cites no REQ. Run specctx query --change ${t.change} --kind req to list its requirements, then add [REQ-<CAP>-NNN] to the task line.`;
             if (c.json)
-                print(c, { bundle: b, task: t.id });
+                print(c, { bundle: b, hint, task: t.id });
             else
-                c.io.out(b.text);
+                c.io.out(b.text + (hint ? hint + "\n" : "") + footer(cpLen(b.text), (await import("../stats/stats.js")).specCharsOf(entries)));
             return 0;
         }
         case "task verify":
@@ -118,7 +121,7 @@ export async function runWorkflow(c) {
                 if (c.json)
                     print(c, { evidence: rel, kind: "manual", task: t.id });
                 else
-                    c.io.out(`done ${t.id} (manual). Evidence: ${rel}\n`);
+                    c.io.out(paint("ok", `done ${t.id} (manual). Evidence: ${rel}\n`, c.io.tty));
                 return 0;
             }
             if (!dry && t.done)
@@ -154,7 +157,12 @@ export async function runWorkflow(c) {
                     print(c, { command: t.verify.command, error: msg, exit: r.exit, tail: outTail, task: t.id });
                 else
                     c.io.out(outTail ? outTail + "\n" : "");
-                c.io.err(`specctx: ${msg}. Task ${t.id} stays open.\n`);
+                // REQ-VER-003 a timeout keeps its own line on stderr
+                if (r.timedOut)
+                    c.io.err(`specctx: ${msg}. Task ${t.id} stays open.\n`);
+                // REQ-TASK-003 the refusal is the last line of the output. REQ-CLI-008 it is red on a TTY.
+                else if (!c.json)
+                    c.io.out(paint("fail", `Verify failed (exit ${r.exit}). The task stays open.\n`, c.io.tty));
                 return 1;
             }
             const { sha256 } = await import("../util/hash.js");
@@ -170,11 +178,12 @@ export async function runWorkflow(c) {
             if (c.json)
                 print(c, { evidence: rel, kind: "command", task: t.id });
             else
-                c.io.out(`done ${t.id}. Evidence: ${rel}\n`);
+                c.io.out(paint("ok", `done ${t.id}. Evidence: ${rel}\n`, c.io.tty)); // REQ-CLI-008
             return 0;
         }
         case "task backfill": {
-            // REQ-TASK-006 manual evidence for every ticked task that has none, through the task done --manual path
+            // REQ-TASK-006 manual evidence for every ticked task of an active change that has none, through the task done --manual path.
+            // Archived changes stay untouched (017/D1).
             noMore(c, 0);
             const note = f.manual?.trim();
             if (!note)
@@ -185,7 +194,7 @@ export async function runWorkflow(c) {
             const want = f.change;
             const counts = new Map();
             for (const e of tasksOf(entries)) {
-                if (e.status !== "done")
+                if (e.status !== "done" || e.file.includes("/archive/"))
                     continue;
                 if (want && !matchesChange(e.change, want))
                     continue;
@@ -272,3 +281,8 @@ function clearCurrent(root, task) {
         // a damaged current.json stays for the user to read
     }
 }
+// REQ-TASK-002 the footer of task start: the bundle size and its share of the spec text. bundle never prints it.
+export function footer(n, m) {
+    const p = m > 0 ? Math.round((n / m) * 1000) / 10 : 0;
+    return `-- bundle ${n} chars, ${p}% of ${m} chars of spec text\n`;
+}

package/dist/cli.js

@@ -9,5 +9,6 @@ const code = await main(process.argv.slice(2), {
     cwd: process.cwd(),
     out: (s) => process.stdout.write(s),
     err: (s) => process.stderr.write(s),
+    tty: process.stdout.isTTY === true,
 });
 process.exitCode = code;

package/dist/config.js

@@ -16,6 +16,7 @@ export function defaults() {
         ids: { caps: [], task_pattern: "\\d+\\.\\d+", paths: {} },
         bundle: { budget: 8000, depth: 1 },
         verify: { timeout_s: 600 },
+        gate: { markdown: ["openspec/**/*.md", "decisions/*.md", "docs/**/*.md", "*.md"] },
     };
 }
 export class ConfigError extends Error {
@@ -81,6 +82,10 @@ export function loadConfig(root) {
             throw new ConfigError(`${CONFIG_FILE}: verify.timeout_s must be a number above 0.`);
         cfg.verify.timeout_s = v;
     }
+    // REQ-DIST-002 the globs that gate lints
+    const gate = sec("gate");
+    if ("markdown" in gate)
+        cfg.gate.markdown = strList(gate.markdown, "gate.markdown");
     return cfg;
 }
 /** The file that `specctx init` writes. Each key has a comment above it. */
@@ -116,4 +121,8 @@ depth = 1
 [verify]
 # Seconds before task done stops a Verify command.
 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"]
 `;

package/dist/graph/query.js

@@ -1,12 +1,15 @@
 // REQ-QRY-001 token AND over id, title, text. Score 3 for id, 2 for title, 1 for text, per term.
+// With no term and a change filter, every entry of the change matches with score 0 (017/D6).
 import { poolOf } from "../index/canonical.js";
 import { matchesChange } from "../index/scan.js";
 import { cmpTuple, pySplit } from "../util/pystr.js";
 export function query(entries, args, o = {}) {
     const terms = args.flatMap((a) => pySplit(a.toLowerCase()));
+    // REQ-QRY-001 the index stores kinds in lower case. The user may type the kind as the ID shows it.
+    const kind = o.kind?.toLowerCase();
     const hits = [];
     for (const e of poolOf(entries, !!o.all)) {
-        if ((o.kind && e.kind !== o.kind) || (o.change && !matchesChange(e.change, o.change)))
+        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
         const idl = e.id.toLowerCase();

package/dist/index/scan.js

@@ -222,7 +222,9 @@ export function scanMarkdown(sc, rpath, entries, problems) {
             const rid = m[1];
             const title = pyStrip(m[2]);
             if (!rid) {
-                problems.push([rpath, i, "missing-id", title]);
+                // REQ-CHK-001 an archived header without an ID is history. adopt never writes it.
+                if (status !== "archived")
+                    problems.push([rpath, i, "missing-id", title]);
                 curReq = null;
                 curEntry = null;
                 continue;
@@ -246,7 +248,8 @@ export function scanMarkdown(sc, rpath, entries, problems) {
             const sid = m[1];
             const title = pyStrip(m[2]);
             if (!sid) {
-                problems.push([rpath, i, "missing-id", title]);
+                if (status !== "archived")
+                    problems.push([rpath, i, "missing-id", title]);
                 continue;
             }
             const st = curEntry ? curEntry.status : status;

package/dist/init/init.js

@@ -1,5 +1,5 @@
 // REQ-DIST-002 REQ-SCH-003 REQ-SKL-002 specctx init: config file, schema bundle, skills.
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { ASSETS } from "../assets.generated.js";
 import { UsageExit } from "../cli/errors.js";
@@ -12,9 +12,22 @@ function asset(rel) {
         throw new Error(`asset ${rel} is missing from the package`);
     return Buffer.from(b64, "base64");
 }
+/**
+ * REQ-DIST-002 the config text for one project (017/D4). `tests/**` becomes `test/**` when only `test/`
+ * exists at the root. `src/**` becomes `lib/**` when only `lib/` exists. The comments stay.
+ */
+export function configText(root) {
+    const isDir = (d) => existsSync(join(root, d)) && statSync(join(root, d)).isDirectory();
+    let text = INIT_TEXT;
+    if (!isDir("tests") && isDir("test"))
+        text = text.replace('\ntests = ["tests/**"]\n', '\ntests = ["test/**"]\n');
+    if (!isDir("src") && isDir("lib"))
+        text = text.replace('\ncode = ["src/**"]\n', '\ncode = ["lib/**"]\n');
+    return text;
+}
 /** Target path relative to the project root for every file that init installs, with its bytes. */
-export function plan(o) {
-    const out = [[CONFIG_FILE, Buffer.from(INIT_TEXT)]];
+export function plan(o, root) {
+    const out = [[CONFIG_FILE, Buffer.from(configText(root))]];
     for (const rel of Object.keys(ASSETS).sort()) {
         if (o.schema && rel.startsWith(`schemas/${SCHEMA}/`) && !rel.endsWith("/config-fragment.yaml")) {
             out.push([`openspec/${rel}`, asset(rel)]);
@@ -64,6 +77,29 @@ function topBlocks(text) {
     flush();
     return blocks;
 }
+/**
+ * REQ-SCH-003 quote list items under `rules` and `operations` that hold `: ` and are not quoted.
+ * YAML reads such an item as a one key mapping. Every other line stays byte for byte.
+ */
+export function repairItems(text) {
+    let inBlock = false;
+    let fixed = 0;
+    const out = text.split("\n").map((line) => {
+        const top = TOP_KEY.exec(line);
+        if (top) {
+            inBlock = top[1] === "rules" || top[1] === "operations";
+            return line;
+        }
+        if (!inBlock)
+            return line;
+        const m = /^(\s+- )(.*?)(\s*)$/.exec(line);
+        if (!m || /^['"]/.test(m[2]) || !/:(\s|$)/.test(m[2]))
+            return line;
+        fixed++;
+        return `${m[1]}'${m[2].replace(/'/g, "''")}'${m[3]}`;
+    });
+    return { text: out.join("\n"), fixed };
+}
 /**
  * REQ-SCH-003 add each top-level key of the fragment that the project config lacks.
  * Keys that exist stay as they are. The schema key names the installed bundle.
@@ -92,32 +128,77 @@ export function mergeConfig(current, fragment) {
         text = text.replace(/\n*$/, "\n\n") + block;
         added.push(key);
     }
+    const r = repairItems(text);
+    if (r.fixed) {
+        text = r.text;
+        added.push("repaired items");
+    }
     return { text, added, kept };
 }
+/** REQ-DIST-002 the two lines init owns in .gitignore (017/D2). */
+export const GITIGNORE_LINES = [".ctx/index.json", "adopt-report.md"];
+const GITIGNORE = ".gitignore";
+/** The lines of a .gitignore, trimmed, with a leading slash dropped, so `/x` and `x` compare equal. */
+function ignoreLines(text) {
+    return new Set(text.split(/\r?\n/).map((l) => l.trim().replace(/^\//, "")));
+}
+/**
+ * REQ-DIST-002 add the absent lines under a `# spec-ctx` comment. Create the file when it is missing.
+ * Returns the number of lines added, 0 when both are present.
+ */
+export function writeGitignore(root) {
+    const p = join(root, GITIGNORE);
+    const cur = existsSync(p) ? readFileSync(p, "utf8") : null;
+    const have = cur === null ? new Set() : ignoreLines(cur);
+    const add = GITIGNORE_LINES.filter((l) => !have.has(l));
+    if (!add.length)
+        return 0;
+    const block = `# spec-ctx\n${add.join("\n")}\n`;
+    let text;
+    if (cur === null || cur === "")
+        text = block;
+    else
+        text = cur.replace(/\n*$/, "\n") + "\n" + block;
+    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) {
+    const p = join(root, GITIGNORE);
+    if (!existsSync(p))
+        return false;
+    const lines = ignoreLines(readFileSync(p, "utf8"));
+    return lines.has(".claude") || lines.has(".claude/");
+}
+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: [], notes: [] };
-    let files = plan(o);
+    const res = { written: [], kept: [], changed: [], notes: [] };
+    let files = plan(o, root);
     // REQ-CLI-007 every file present with the same bytes and no config key to add: nothing to do
-    const same = files.every(([rel, data]) => existsSync(join(root, rel)) && readFileSync(join(root, rel)).equals(data));
-    if (same && !o.force) {
+    // 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)));
+    const ignoreDone = existsSync(join(root, GITIGNORE)) && GITIGNORE_LINES.every((l) => ignoreLines(readFileSync(join(root, GITIGNORE), "utf8")).has(l));
+    if (same && ignoreDone && !o.force) {
         const cfgPath = join(root, "openspec/config.yaml");
         const cur = existsSync(cfgPath) ? readFileSync(cfgPath, "utf8") : null;
         if (!o.schema || !mergeConfig(cur, asset(`schemas/${SCHEMA}/config-fragment.yaml`).toString("utf8")).added.length) {
             res.nothing = true;
+            if (o.skills && ignoresClaude(root))
+                res.notes.push(CLAUDE_NOTE);
             return res;
         }
     }
+    // REQ-DIST-002 init never replaces spec-ctx.toml, and never fails because a file exists (014/D1)
     if (existsSync(join(root, CONFIG_FILE))) {
-        if (!o.force)
-            throw new UsageExit(`${CONFIG_FILE} exists. Use --force to install the other files over it`);
-        // --force never replaces a config that the user wrote
         files = files.filter(([rel]) => rel !== CONFIG_FILE);
         res.kept.push(CONFIG_FILE);
     }
     if (!o.force) {
-        const clash = files.filter(([rel, data]) => existsSync(join(root, rel)) && !readFileSync(join(root, rel)).equals(data));
-        if (clash.length)
-            throw new UsageExit(`these files exist with other content: ${clash.map(([r]) => r).join(", ")}. Use --force to replace them`);
+        const differs = (rel, data) => !readFileSync(join(root, rel)).equals(data);
+        res.changed = files.filter(([rel, data]) => existsSync(join(root, rel)) && differs(rel, data)).map(([rel]) => rel);
+        for (const rel of res.changed)
+            res.kept.push(`${rel} (other content)`);
+        files = files.filter(([rel]) => !existsSync(join(root, rel)));
     }
     for (const [rel, data] of files) {
         const p = join(root, rel);
@@ -137,5 +218,14 @@ export function runInit(root, o) {
         for (const k of m.kept)
             res.kept.push(`openspec/config.yaml ${k}`);
     }
+    // REQ-DIST-002 the two .gitignore lines (017/D2)
+    const added = writeGitignore(root);
+    if (added)
+        res.written.push(`${GITIGNORE} (${added} line${added === 1 ? "" : "s"})`);
+    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);
     return res;
 }

package/dist/lint/counts.js

@@ -0,0 +1,60 @@
+// REQ-ADOPT-007 hard lint findings per file and rule on the gate globs. One count per key, so the baseline survives line shifts.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { markdownFiles } from "../cli/gate.js";
+import { lintSte } from "./ste.js";
+import { lintTells } from "./tells.js";
+/** Rules that the gate never counts. The repo lints by hand with the same disable. */
+const SKIP = new Set(["synonym-rotation"]);
+export const LINT_PREFIX = "lint ";
+/** Key of one lint count: `lint <file> <linter>:<rule>`. */
+export const lintKey = (file, linter, rule) => `${LINT_PREFIX}${file} ${linter}:${rule}`;
+/** Hard findings per `lint <file> <linter>:<rule>` for the markdown globs. Files with no hard finding give no key. */
+export function lintCounts(root, globs) {
+    const counts = new Map();
+    const files = markdownFiles(root, globs);
+    for (const f of files) {
+        const text = readFileSync(join(root, f), "utf8").replace(/\r\n?/g, "\n");
+        for (const x of lintTells(text)) {
+            if (x.level !== "hard")
+                continue;
+            const k = lintKey(f, "tells", x.rule);
+            counts.set(k, (counts.get(k) ?? 0) + 1);
+        }
+        for (const x of lintSte(text, f).findings) {
+            if (x.level !== "advisory-free" || SKIP.has(x.rule))
+                continue;
+            const k = lintKey(f, "ste", x.rule);
+            counts.set(k, (counts.get(k) ?? 0) + 1);
+        }
+    }
+    return { counts, files: files.length };
+}
+/** Parse a baseline line `lint <file> <rule> <count>`. Returns null for any other line. */
+export function parseLintLine(line) {
+    if (!line.startsWith(LINT_PREFIX))
+        return null;
+    const i = line.lastIndexOf(" ");
+    const n = Number(line.slice(i + 1));
+    if (i < 0 || !Number.isInteger(n) || n < 0)
+        return null;
+    return { key: line.slice(0, i), count: n };
+}
+export const lintLine = (key, count) => `${key} ${count}`;
+/** REQ-CLI-004 the keys whose count rose above the baseline, worst first. A key with no line has a baseline of 0. */
+export function lintRises(counts, baseline) {
+    const base = new Map();
+    for (const line of baseline ?? []) {
+        const p = parseLintLine(line);
+        if (p)
+            base.set(p.key, p.count);
+    }
+    const out = [];
+    for (const [key, current] of counts) {
+        const b = base.get(key) ?? 0;
+        if (current > b)
+            out.push({ key, current, baseline: b });
+    }
+    out.sort((a, b) => b.current - b.baseline - (a.current - a.baseline) || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+    return out;
+}

package/dist/stats/stats.js

@@ -92,10 +92,14 @@ export function gateMetrics(root, last = 100) {
         gate_failures_caught: { value: failed, n: runs.length, text: String(failed) },
     };
 }
-export function computeStats(root, entries, strictFindings, warnings, only) {
-    const specChars = entries
+// REQ-STAT-002 REQ-TASK-002 the size of all canonical req, scn, and decision text. stats and the task start footer share it.
+export function specCharsOf(entries) {
+    return entries
         .filter((e) => e.canonical && (e.kind === "req" || e.kind === "scn" || e.kind === "decision"))
         .reduce((a, e) => a + cpLen(e.text ?? ""), 0);
+}
+export function computeStats(root, entries, strictFindings, warnings, only) {
+    const specChars = specCharsOf(entries);
     const { live, reopened } = readEvidence(root);
     // REQ-IDX-005 the change name of each change key, from the task entries
     const names = new Map();

package/dist/version.js

@@ -1,2 +1,2 @@
 // REQ-CLI-001 version string. tests/cli/version.test.ts keeps it equal to package.json.
-export const VERSION = "0.1.0";
+export const VERSION = "0.1.2";