@esneiderbravo/speclaw 0.2.1 → 0.3.1

package/dist/modules/compass/db.js

@@ -47,9 +47,17 @@ CREATE TABLE IF NOT EXISTS node_embeddings (
   model TEXT NOT NULL,
   vec BLOB NOT NULL
 );
+-- git_history_cache: memoized results of the expensive git-history scans
+-- (churn, co-change), keyed by query and invalidated when HEAD moves.
+CREATE TABLE IF NOT EXISTS git_history_cache (
+  query_key TEXT PRIMARY KEY,
+  head_sha TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  computed_at INTEGER NOT NULL
+);
 `;
 /** Schema version stamped into the `meta` table on first creation. */
-export const SCHEMA_VERSION = "3";
+export const SCHEMA_VERSION = "4";
 /** The stamped schema version, or null if the db predates versioning / has no meta table. */
 function readSchemaVersion(db) {
     try {
@@ -81,6 +89,7 @@ function isStale(db) {
 /** Drop every table (children first) so the current schema can be recreated cleanly. */
 function resetSchema(db) {
     db.exec(`
+    DROP TABLE IF EXISTS git_history_cache;
     DROP TABLE IF EXISTS node_embeddings;
     DROP TABLE IF EXISTS edges;
     DROP TABLE IF EXISTS nodes;

package/dist/modules/compass/git-history-cache.js

@@ -0,0 +1,65 @@
+import { churn, coChanges, headSha, } from "../../shared/git-history.js";
+import { openDb } from "./db.js";
+/**
+ * Look up a cached payload valid at the current HEAD, or compute it and store it.
+ *
+ * When `head` is `null` (no commits / not a repo) the cache is bypassed entirely
+ * and `compute()` runs directly, so an empty repo never poisons the cache.
+ *
+ * @param projectPath - Project root, whose `.speclaw/index.db` holds the cache.
+ * @param head - The current HEAD SHA, or `null` when there is none.
+ * @param queryKey - Stable key identifying this query (function + options).
+ * @param compute - Produces the fresh result on a miss.
+ * @param serialize - Turns the result into a JSON-safe payload string.
+ * @param deserialize - Rebuilds the result from a stored payload string.
+ * @returns The cached-or-freshly-computed result.
+ */
+function readThrough(projectPath, head, queryKey, compute, serialize, deserialize) {
+    if (head === null)
+        return compute();
+    const db = openDb(projectPath);
+    try {
+        const row = db
+            .prepare("SELECT head_sha, payload FROM git_history_cache WHERE query_key = ?")
+            .get(queryKey);
+        if (row && row.head_sha === head) {
+            return deserialize(row.payload);
+        }
+        const value = compute();
+        db.prepare(`INSERT INTO git_history_cache(query_key, head_sha, payload, computed_at)
+       VALUES (?, ?, ?, 0)
+       ON CONFLICT(query_key) DO UPDATE SET
+         head_sha = excluded.head_sha,
+         payload = excluded.payload,
+         computed_at = excluded.computed_at`).run(queryKey, head, serialize(value));
+        return value;
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * {@link churn}, memoized in the Compass index until `HEAD` moves.
+ *
+ * @param projectPath - Project root to query.
+ * @param opts - Same options as {@link churn}.
+ * @returns Per-path change counts and the shallow marker, cached per HEAD.
+ */
+export function cachedChurn(projectPath, opts = {}) {
+    const key = `churn:${JSON.stringify({ since: opts.since ?? null, pathspec: opts.pathspec ?? null })}`;
+    return readThrough(projectPath, headSha(projectPath), key, () => churn(projectPath, opts), (value) => JSON.stringify({ shallow: value.shallow, byPath: [...value.byPath] }), (payload) => {
+        const parsed = JSON.parse(payload);
+        return { shallow: parsed.shallow, byPath: new Map(parsed.byPath) };
+    });
+}
+/**
+ * {@link coChanges}, memoized in the Compass index until `HEAD` moves.
+ *
+ * @param projectPath - Project root to query.
+ * @param opts - Same options as {@link coChanges}.
+ * @returns The co-change pairs and the shallow marker, cached per HEAD.
+ */
+export function cachedCoChanges(projectPath, opts = {}) {
+    const key = `coChanges:${JSON.stringify({ since: opts.since ?? null, minSupport: opts.minSupport ?? null })}`;
+    return readThrough(projectPath, headSha(projectPath), key, () => coChanges(projectPath, opts), (value) => JSON.stringify(value), (payload) => JSON.parse(payload));
+}

package/dist/modules/foundation/assets/docs/standards/lawbook.template.md

@@ -32,7 +32,9 @@ itself — never delegates it.
 ## Reports
 
 Every change carries a `reports/` folder. `build` writes one report per
-discipline it touched (`backend.md`, `frontend.md`, …) recording what was tested
+discipline it touched, named for that discipline — an open set (`backend.md`,
+`frontend.md`, `api.md`, `database.md`, `infra.md`, … — `api.md` required
+whenever the change touches an API surface) recording what was tested
 and the real results — unit, integration, and end-to-end as applicable — with
 the commands run and their output. It is evidence of testing that travels with
 the change; the archive is blocked until at least one discipline report exists.

package/dist/modules/foundation/assets/docs/standards/testing-standards.template.md

@@ -45,9 +45,18 @@ suppressing a linter or deleting a test.
 ## Reports — evidence travels with the change
 
 Every change records its testing under `lawbook/changes/<name>/reports/`, one
-file per discipline it touched (`backend.md`, `frontend.md`, …). `build`
-produces them; archiving is blocked until the change has at least one discipline
-report.
+file per discipline it touched, named for that discipline. The set is open, not
+fixed: `backend.md`, `frontend.md`, and `api.md` are the common ones, but write
+`database.md`, `infra.md`, `security.md`, `performance.md`, `e2e.md`, etc. when
+the change exercises those concerns. `build` produces them; archiving is blocked
+until the change has at least one discipline report.
+
+`api.md` is **mandatory whenever the change touches an API surface** — a new or
+modified endpoint, its contract, its status codes, or its auth/permission or
+ordering guarantees — and a `backend.md` unit report does not substitute for it.
+It documents the method and path, the auth/permissions, the response shape and
+every status code the change governs, any ordering guarantee, and how the
+contract was exercised (test client and/or `curl`) kept isolated from live data.
 
 Each report MUST follow a fixed structure, so the evidence is reproducible rather
 than improvised:

package/dist/modules/lawbook/assets/rules/spec-reports-disciplines.md

@@ -0,0 +1,78 @@
+---
+description: Require one test report per discipline a change touches (an open set — backend, frontend, api, database, infra, security, performance, e2e, …), with the api report mandatory whenever the change touches an API surface.
+alwaysApply: true
+---
+
+# Spec Reports: Discipline Coverage
+
+A change's evidence of testing lives under `lawbook/changes/<name>/reports/`, as
+**one file per discipline the change actually touched**, named for that
+discipline (`<discipline>.md`) — never a single lumped report.
+
+## 1. The set of disciplines is open — name what the change touched
+
+There is no fixed list. Write a report for each area of concern the change
+exercised, and omit the ones it did not. Common disciplines include, but are
+**not limited to**:
+
+- **`backend.md`** — domain/service logic, persistence, jobs.
+- **`frontend.md`** — UI flows, components, client state.
+- **`api.md`** — the endpoint contract itself (see §2).
+- **`database.md`** — schema changes, migrations, data integrity.
+- **`infra.md`** — IaC, CI/CD pipelines, deployment/runtime config.
+- **`security.md`** — authn/authz, secrets, attack surface.
+- **`performance.md`** — benchmarks, load, latency budgets.
+- **`e2e.md`** — full cross-service or cross-layer journeys.
+- **`mobile.md`**, **`contract.md`**, **`data.md`**, **`accessibility.md`**, …
+
+When a change touches a concern none of these names fit, coin a clear
+`<discipline>.md` for it rather than folding it into an ill-fitting bucket. The
+goal is that the evidence a reviewer needs for each concern is where they expect
+it — not that reports match a checklist.
+
+## 2. The API report is mandatory whenever an API surface is touched
+
+`api` is called out because it is the discipline most often (wrongly) absorbed
+into `backend` and lost. When a change **adds or modifies an API surface** — a
+new or changed endpoint, its request/response contract, its status codes, or its
+auth/permission or ordering guarantees — you MUST write `api.md`. This is not
+optional:
+
+- A `backend.md` unit report does **not** substitute for it — the contract
+  (shape, status codes, auth, ordering) is a distinct concern a service-unit
+  report does not capture.
+- A `frontend.md` report does **not** substitute for it either.
+
+A change that touches no endpoint or contract MAY omit `api.md`.
+
+`api.md` MUST document the contract: the method and path, the auth and
+permissions required, the response shape and **every** status code the change
+governs (e.g. `200`/`401`/`403`/`404`), and any ordering or consistency
+guarantee. It MUST record how the contract was exercised — a test client and/or a
+live request such as `curl` — and, per the verification-safety rule, how that
+exercise stayed isolated from any live data store (read-only, ephemeral store, or
+rolled-back transaction — never a write to real data without authorization).
+
+## 3. Every report follows the required structure
+
+Regardless of discipline, each report keeps the fixed structure so evidence is
+reproducible, not improvised: title + header (discipline · change · date ·
+branch · cwd) → gates-and-results table (each check, exact command, real result
+with pass/fail counts) → tests added/updated → spec-scenario coverage table
+(every `#### Scenario` mapped to how it was verified) → pre-existing/unrelated
+failures (with proof, or "none") → pending manual steps (or "none") → one-line
+verdict. See the `build` skill (Step 5) and
+`docs/standards/testing-standards.md`.
+
+When a test kind does not yet apply (e.g. no unit runner), the report says so in
+place of that evidence and records the gates and manual verification that stood
+in.
+
+## 4. Reports gate the archive
+
+`lawbook_archive` refuses to archive while `reports/` holds no discipline report
+(the `reports/README.md` scaffold does not count). Which disciplines a change
+touched — and therefore which reports are owed, including `api.md` for any
+API-touching change — is the agent's responsibility to judge and satisfy before
+archiving; the engine gate counts files but cannot infer the set of concerns a
+change exercised.

package/dist/modules/lawbook/assets/rules/spec-tasks-mandatory-steps.md

@@ -21,9 +21,11 @@ steps, branch convention, and testing/documentation requirements.
   (see `docs/standards/testing-standards.md`).
 - Perform manual verification of the behavior — **the agent executes this
   itself, never the user.**
-- Produce the discipline reports under `reports/` (`backend.md`, `frontend.md`,
-  … as relevant) with the unit/integration/e2e results for what the feature
-  touched.
+- Produce the discipline reports under `reports/` — one per discipline the change
+  touched, from an open set (`backend.md`, `frontend.md`, `api.md`, `database.md`,
+  `infra.md`, … — `api.md` is required whenever the change touches an API surface;
+  see the `spec-reports-disciplines` rule) with the unit/integration/e2e results
+  for what the feature touched.
 - Update the technical documentation the change touches.
 - Archive the change within the same PR (the `archive` command / `lawbook_archive`
   tool).

package/dist/modules/lawbook/assets/skills/build/SKILL.md

@@ -62,9 +62,21 @@ authorization you obtained).
 ## Step 5 — Write the discipline reports (mandatory)
 
 Record the evidence of testing under `lawbook/changes/<name>/reports/`, one file
-per discipline the change touched (`backend.md`, `frontend.md`, …). Omit
-disciplines the change did not touch; the archive is blocked until at least one
-discipline report exists.
+per discipline the change touched, named for that discipline. The set is **open,
+not a fixed list** — `backend.md`, `frontend.md`, and `api.md` are the common
+ones, but write `database.md`, `infra.md`, `security.md`, `performance.md`,
+`e2e.md`, etc. when the change exercises those concerns, and coin a clear
+`<discipline>.md` for anything none of them fit. Omit disciplines the change did
+not touch; the archive is blocked until at least one discipline report exists.
+
+**`api.md` is mandatory whenever the change touches an API surface** — a new or
+modified endpoint, its request/response contract, its status codes, or its
+auth/permission or ordering guarantees. A `backend.md` unit report does not
+substitute for it: the contract is a distinct concern. In `api.md` document the
+method and path, the auth/permissions, the response shape and every status code
+the change governs (e.g. `200`/`401`/`403`/`404`), any ordering guarantee, and
+how the contract was exercised (test client and/or `curl`) — kept isolated from
+any live data store per Step 4.
 
 Each report MUST follow this structure, in order — the fixed shape is what makes
 the evidence trustworthy and reproducible, rather than left to improvisation:

package/dist/modules/lawbook/assets/skills/draft/SKILL.md

@@ -68,8 +68,11 @@ Create under `lawbook/changes/<name>/`:
   manual verification executed by the agent; discipline reports produced; docs
   updated; archive within the PR).
 - **reports/** — create the folder with a short `reports/README.md` naming the
-  discipline reports (`backend.md`, `frontend.md`, … as relevant) that `build`
-  will fill, following the required report structure (header · gates table ·
+  discipline reports the change will need — one per discipline it touches, from an
+  open set (`backend.md`, `frontend.md`, `api.md`, `database.md`, `infra.md`,
+  `security.md`, … — and `api.md` is required when the change touches any API
+  surface) that `build` will fill, following the required report structure
+  (header · gates table ·
   tests added · spec-scenario coverage · pre-existing failures · pending manual ·
   verdict — see the `build` skill, Step 5). Every change ships this folder;
   archive is blocked until it holds at least one discipline report.

package/dist/modules/lawbook/engine.js

@@ -26,7 +26,7 @@ mandatory_task_steps:
   - "Review and update the affected tests."
   - "Run the quality gates and verify they pass (see docs/standards/testing-standards.md)."
   - "Perform manual verification of the behavior — the agent executes this itself, never the user."
-  - "Produce the discipline reports under reports/ (unit/integration/e2e results for what the feature touched)."
+  - "Produce the discipline reports under reports/ — one per discipline touched, from an open set (e.g. backend.md, frontend.md, api.md, database.md, infra.md, security.md; api.md is required whenever the change touches an API surface) — with the unit/integration/e2e results for what the feature touched."
   - "Update the technical documentation touched by the change."
   - "Archive the change within the same PR (lawbook:archive)."
 

package/dist/shared/git-history.js

@@ -0,0 +1,204 @@
+import { spawnSync } from "node:child_process";
+/** ASCII NUL — the record/field separator git emits with `-z` and we request via `%x00`. */
+const NUL = "\0";
+/**
+ * Run git in `projectPath` and return stdout, or `null` on any failure.
+ *
+ * Best-effort like {@link isGitRepo}: git missing, not a repo, or a non-zero
+ * exit all yield `null` so callers can fail soft rather than throw.
+ */
+function git(projectPath, args) {
+    // `core.quotePath=false` keeps non-ASCII paths as raw UTF-8 instead of git's
+    // default octal-escaped, double-quoted form — so our path parsing stays exact.
+    const res = spawnSync("git", ["-C", projectPath, "-c", "core.quotePath=false", ...args], {
+        encoding: "utf8",
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    if (res.status !== 0 || typeof res.stdout !== "string")
+        return null;
+    return res.stdout;
+}
+/** Parse a `--numstat` count field: `-` (binary) becomes `0`, anything non-numeric too. */
+function numstat(field) {
+    if (field === "-")
+        return 0;
+    const n = Number.parseInt(field, 10);
+    return Number.isFinite(n) ? n : 0;
+}
+/**
+ * The current `HEAD` commit SHA, or `null` when the repo has no commits yet
+ * (or is not a repo / git is unavailable).
+ *
+ * @param projectPath - Directory inside the work tree to query.
+ * @returns The 40-char SHA, or `null`.
+ */
+export function headSha(projectPath) {
+    const out = git(projectPath, ["rev-parse", "HEAD"]);
+    const sha = out?.trim();
+    return sha ? sha : null;
+}
+/**
+ * Whether `projectPath` is inside a shallow clone (e.g. CI's `--depth=1`), where
+ * history is truncated and change/coupling counts would be misleadingly low.
+ *
+ * @param projectPath - Directory inside the work tree to query.
+ * @returns `true` only when git reports the repository is shallow.
+ */
+export function isShallowRepo(projectPath) {
+    const out = git(projectPath, ["rev-parse", "--is-shallow-repository"]);
+    return out?.trim() === "true";
+}
+/**
+ * The commits that touched `relPath`, most-recent first, with the line churn
+ * each introduced there.
+ *
+ * Fail-soft: a path with no history, a repo with no commits, or an unavailable
+ * git binary all yield an empty list. Records are parsed over NUL separators, so
+ * paths containing spaces or unicode are handled correctly.
+ *
+ * `since`/`until` bound the history as a **revision range** (`since..until`,
+ * `until` defaulting to `HEAD`) — the exact, deterministic form drift needs
+ * (`<archived-sha>..HEAD`), not an approximate date window. `since` is exclusive.
+ *
+ * @param projectPath - Project root to query.
+ * @param relPath - Project-relative path whose history to read.
+ * @param opts - Optional revision bounds: `since` (exclusive lower bound) and
+ *   `until` (upper bound, default `HEAD`) — any revision git accepts, e.g. a SHA.
+ * @returns The touching commits, newest first; empty when there is no history.
+ */
+export function logForPath(projectPath, relPath, opts = {}) {
+    const range = [];
+    if (opts.since)
+        range.push(`${opts.since}..${opts.until ?? "HEAD"}`);
+    else if (opts.until)
+        range.push(opts.until);
+    // Per commit: <sha>\0<ts>\0 then one numstat line per file it touched.
+    const out = git(projectPath, [
+        "log",
+        "--format=%x00%H%x00%ct%x00",
+        "--numstat",
+        ...range,
+        "--",
+        relPath,
+    ]);
+    if (out === null)
+        return [];
+    const touches = [];
+    // The stream is a sequence of "\0<sha>\0<ts>\0<numstat lines>" per commit.
+    const records = out.split(NUL);
+    // records[0] is empty (leading NUL); then repeating [sha, ts, tail...] where
+    // `tail` holds the numstat lines for that commit up to the next leading NUL.
+    for (let i = 1; i + 1 < records.length; i += 3) {
+        const sha = records[i]?.trim();
+        const ts = Number.parseInt(records[i + 1] ?? "", 10);
+        const tail = records[i + 2] ?? "";
+        if (!sha || !Number.isFinite(ts))
+            continue;
+        let added = 0;
+        let deleted = 0;
+        for (const line of tail.split("\n")) {
+            const cols = line.split("\t");
+            if (cols.length < 3)
+                continue;
+            added += numstat(cols[0]);
+            deleted += numstat(cols[1]);
+        }
+        touches.push({ sha, ts, added, deleted });
+    }
+    return touches;
+}
+/**
+ * How many commits touched each file in the window, summed from `--numstat`.
+ *
+ * Fail-soft: yields an empty map on any git failure. Does not follow renames —
+ * a renamed file is counted under its path as it appears in each commit (a safe
+ * superset, not a precise lineage). The result carries the {@link isShallowRepo}
+ * marker so consumers can degrade to "insufficient data" on a shallow clone.
+ *
+ * @param projectPath - Project root to query.
+ * @param opts - Optional `since` window (any date/revision git accepts) and a
+ *   `pathspec` list to restrict which paths are considered.
+ * @returns Per-path change counts and the shallow marker.
+ */
+export function churn(projectPath, opts = {}) {
+    const shallow = isShallowRepo(projectPath);
+    const args = ["log", "--numstat", "--format=%x00"];
+    if (opts.since)
+        args.push(`--since=${opts.since}`);
+    if (opts.pathspec && opts.pathspec.length > 0)
+        args.push("--", ...opts.pathspec);
+    const out = git(projectPath, args);
+    const byPath = new Map();
+    if (out === null)
+        return { shallow, byPath };
+    for (const line of out.split("\n")) {
+        // Numstat rows are "<added>\t<deleted>\t<path>"; the %x00 format lines and
+        // blank lines have no tabs and are skipped.
+        const cols = line.split("\t");
+        if (cols.length < 3)
+            continue;
+        const path = cols[2].replace(/^\0+/, "").trim();
+        if (!path)
+            continue;
+        byPath.set(path, (byPath.get(path) ?? 0) + 1);
+    }
+    return { shallow, byPath };
+}
+/**
+ * For every pair of files that changed together, how many commits touched both.
+ *
+ * Groups each commit's changed files and emits a count per unordered pair. Pairs
+ * with fewer than `minSupport` shared commits are omitted. Fail-soft (empty on
+ * git failure) and does not follow renames. Carries the shallow marker.
+ *
+ * @param projectPath - Project root to query.
+ * @param opts - Optional `since` window and `minSupport` threshold (default `1`).
+ * @returns The qualifying co-change pairs and the shallow marker.
+ */
+export function coChanges(projectPath, opts = {}) {
+    const shallow = isShallowRepo(projectPath);
+    const minSupport = opts.minSupport ?? 1;
+    const args = ["log", "--name-only", "--format=%x00"];
+    if (opts.since)
+        args.push(`--since=${opts.since}`);
+    const out = git(projectPath, args);
+    if (out === null)
+        return { shallow, pairs: [] };
+    const counts = new Map();
+    // Each commit's file list is the run of lines between two %x00 markers.
+    for (const commitBlock of out.split(NUL)) {
+        const files = commitBlock
+            .split("\n")
+            .map((l) => l.trim())
+            .filter((l) => l.length > 0);
+        const unique = [...new Set(files)].sort();
+        for (let i = 0; i < unique.length; i++) {
+            for (let j = i + 1; j < unique.length; j++) {
+                const key = `${unique[i]}\t${unique[j]}`;
+                counts.set(key, (counts.get(key) ?? 0) + 1);
+            }
+        }
+    }
+    const pairs = [];
+    for (const [key, count] of counts) {
+        if (count < minSupport)
+            continue;
+        const [a, b] = key.split("\t");
+        pairs.push({ a: a, b: b, count });
+    }
+    pairs.sort((x, y) => y.count - x.count || x.a.localeCompare(y.a) || x.b.localeCompare(y.b));
+    return { shallow, pairs };
+}
+/**
+ * The SHA of the most recent commit that touched `relPath`, or `null` when the
+ * path has no history (or on any git failure).
+ *
+ * @param projectPath - Project root to query.
+ * @param relPath - Project-relative path.
+ * @returns The last-touching commit SHA, or `null`.
+ */
+export function lastTouch(projectPath, relPath) {
+    const out = git(projectPath, ["log", "-1", "--format=%H", "--", relPath]);
+    const sha = out?.trim();
+    return sha ? sha : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esneiderbravo/speclaw",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "publishConfig": {
     "access": "public"
   },