spec-ctx 0.1.1 → 0.1.2

package/README.md

@@ -181,7 +181,8 @@ specctx gate --strict
 - `adopt` derives a capability code from each folder name, for example `UA` for `user-auth`. It writes the codes into `spec-ctx.toml`. Rename a code there before the IDs spread.
 - `adopt` runs `check` before and after the write. A finding that the write added undoes every file. A second run prints `nothing to adopt`.
 - `task backfill` writes manual evidence for every ticked task that has none.
-- `baseline write` records the debt of the day in `.ctx/baseline.json`: untested requirements and scenarios, tasks without evidence, and legacy tasks without a citation or a Verify code span. `check` hides that debt and prints `baselined: <n>`. New debt still shows.
+- `baseline write` records the debt of the day in `.ctx/baseline.json`. The debt has five kinds. Untested requirements and scenarios. Tasks without evidence. Legacy tasks without a citation or a Verify code span. Delta headers that match no main requirement. Hard lint findings per file and rule on the gate globs. `check` hides that debt and prints `baselined: <n>`. `gate` fails the lint step only when a count rises. New debt still shows.
+- `[gate] markdown` in `spec-ctx.toml` names the markdown globs that `gate` lints. Narrow it when a folder is not yours to fix.
 - Legacy tasks stay in the baseline until an agent adds `[REQ-...]` citations and a `Verify:` code span. `specctx baseline prune` then drops them. No command adds a single entry.
 
 Both paths have an end to end test: `tests/paths/fresh.sh` and `tests/paths/existing.sh`.
@@ -269,18 +270,18 @@ The action runs `specctx gate`: `check --strict`, both markdown linters, `opensp
 
 ## Status
 
-- Published: `spec-ctx@0.1.1` on npm, with tags `v0.1.1` and `v0` and binaries on the GitHub release.
-- Archived: 001 to 013. No change is open. See `CHANGELOG.md` for each release.
+- Published: `spec-ctx@0.1.2` on npm, with tags `v0.1.2` and `v0` and binaries on the GitHub release.
+- Archived: 001 to 017. No change is open. See `CHANGELOG.md` for each release.
 - A version bump on `main` publishes the next release. See `docs/CONTRIBUTING.md`.
 - Upstream: the ID scheme is proposed as a comment on [OpenSpec#1967](https://github.com/Fission-AI/OpenSpec/issues/1967#issuecomment-6414314730). The schema bundle is submitted to the community table in [OpenSpec#2157](https://github.com/Fission-AI/OpenSpec/issues/2157). No pull request until a maintainer asks.
 
 ## Measured
 
-`specctx stats --write` measures this repository after each change. The newest file is `docs/metrics/2026-10-26.md`. Its total row:
+`specctx stats --write` measures this repository after each change. The newest file is `docs/metrics/2026-10-27.md`. Its total row:
 
 | change | context_ratio | evidence_ratio | stale_catches | cycle_time_median_s | debt |
 | --- | --- | --- | --- | --- | --- |
-| total | 0.0469 (n=41) | 0.85 (88/104) | 36 (of 62 reopens) | 60 (n=41) | 0 (0 baselined + 0 new) |
+| total | 0.0435 (n=52) | 0.87 (106/122) | 36 (of 68 reopens) | 70 (n=52) | 0 (0 baselined + 0 new) |
 
 - `context_ratio`: the size of one task bundle divided by the size of all spec text. Lower is better.
 - `evidence_ratio`: done tasks with a passed Verify command, divided by all done tasks. The rest have a manual note. Higher is better.

package/dist/baseline/baseline.js

@@ -1,10 +1,12 @@
 // REQ-ADOPT-005 REQ-CHK-002 the baseline ratchet in .ctx/baseline.json: sorted "rule id" pairs.
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { lintLine, parseLintLine } from "../lint/counts.js";
 import { cmpStr } from "../util/pystr.js";
 export const BASELINE_PATH = ".ctx/baseline.json";
-export const BASELINE_RULES = ["uncovered", "scenario-untested", "done-without-evidence", "manual-evidence", "task-without-req", "task-without-verify"];
-const key = (rule, id) => `${rule} ${id}`;
+export const BASELINE_RULES = ["uncovered", "scenario-untested", "done-without-evidence", "manual-evidence", "task-without-req", "task-without-verify", "missing-id"];
+/** REQ-ADOPT-005 a missing-id finding has no ID. Its key carries the file and the header title. */
+const key = (f) => (f.rule === "missing-id" ? `${f.rule} ${f.file} ${f.id}` : `${f.rule} ${f.id}`);
 /** A warning line reads "manual-evidence <task>". */
 const warningKey = (w) => w;
 export function readBaseline(root) {
@@ -24,24 +26,48 @@ function save(root, entries) {
 }
 /** The current debt that the baseline may hold: strict findings and warnings of the listed rules. */
 export function debt(findings, warnings) {
-    const out = findings.filter((f) => BASELINE_RULES.includes(f.rule)).map((f) => key(f.rule, f.id));
+    const out = findings.filter((f) => BASELINE_RULES.includes(f.rule)).map((f) => key(f));
     for (const w of warnings)
         if (BASELINE_RULES.includes(w.split(" ")[0]))
             out.push(warningKey(w));
     return out;
 }
-export function writeBaseline(root, findings, warnings) {
-    return save(root, debt(findings, warnings));
+/** REQ-ADOPT-007 one `lint <file> <rule> <count>` line per key with hard lint findings. */
+export function lintDebt(counts) {
+    return [...counts].filter(([, n]) => n > 0).map(([k, n]) => lintLine(k, n));
+}
+export function writeBaseline(root, findings, warnings, lint = new Map()) {
+    return save(root, [...debt(findings, warnings), ...lintDebt(lint)]);
 }
 /** Drop entries that no longer fire. Returns the number dropped. */
-export function pruneBaseline(root, findings, warnings) {
+export function pruneBaseline(root, findings, warnings, lint = new Map()) {
     const cur = readBaseline(root);
     if (!cur)
         return 0;
     const live = new Set(debt(findings, warnings));
-    const kept = [...cur].filter((e) => live.has(e));
+    const kept = [];
+    let pruned = 0;
+    for (const e of cur) {
+        const l = parseLintLine(e);
+        if (l) {
+            // REQ-ADOPT-007 a lint line drops at zero and lowers when the count fell
+            const now = lint.get(l.key) ?? 0;
+            if (now === 0)
+                pruned++;
+            else if (now < l.count) {
+                pruned++;
+                kept.push(lintLine(l.key, now));
+            }
+            else
+                kept.push(e);
+        }
+        else if (live.has(e))
+            kept.push(e);
+        else
+            pruned++;
+    }
     save(root, kept);
-    return cur.size - kept.length;
+    return pruned;
 }
 /** REQ-CHK-002 a finding or warning in the baseline leaves the output and counts as baselined. */
 export function applyBaseline(root, findings, warnings) {
@@ -50,7 +76,7 @@ export function applyBaseline(root, findings, warnings) {
         return { findings, warnings, baselined: 0 };
     let n = 0;
     const f2 = findings.filter((f) => {
-        const hit = base.has(key(f.rule, f.id));
+        const hit = base.has(key(f));
         if (hit)
             n++;
         return !hit;

package/dist/cli/commands.js

@@ -90,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") {
@@ -106,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
@@ -125,11 +128,12 @@ 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");
@@ -145,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");
@@ -267,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\n" + paint("dim", "next: specctx status\n", io.tty));
+        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(paint("dim", "next: specctx status\n", io.tty));
+        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

@@ -92,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 + footer(cpLen(b.text), (await import("../stats/stats.js")).specCharsOf(entries)));
+                c.io.out(b.text + (hint ? hint + "\n" : "") + footer(cpLen(b.text), (await import("../stats/stats.js")).specCharsOf(entries)));
             return 0;
         }
         case "task verify":
@@ -180,7 +182,8 @@ export async function runWorkflow(c) {
             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)
@@ -191,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;

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)]);
@@ -122,30 +135,70 @@ export function mergeConfig(current, fragment) {
     }
     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);
@@ -165,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/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.1";
+export const VERSION = "0.1.2";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-ctx",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Deterministic context engine and task workflow for OpenSpec projects.",
   "type": "module",
   "license": "MIT",