@esneiderbravo/speclaw 2.0.18 → 2.0.20

package/dist/modules/lawbook/ship.js

@@ -4,9 +4,10 @@ import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { changedFiles, isGitRepo, mergeBase, worktreeChangedFiles } from "../../shared/git.js";
 import { handleHarness, readHarness } from "../cortex/harness.js";
-import { specArchive, specArchivePreconditions } from "./engine.js";
-import { confirmedLevel } from "./levels.js";
+import { deltaSpecFiles, specArchive, specArchivePreconditions } from "./engine.js";
+import { artifactNeeds, confirmedLevel, gatherSignals, loadCeremonyConfig, promoteCeremonyLevel, proposeLevel, readCeremonyRecord, readChangeType, } from "./levels.js";
 import { scaffoldQuick } from "./quick.js";
+import { CHANGE_NAME_RE, isPlaceholderDelta, scaffoldFeature } from "./scaffold-change.js";
 const GATE_TAIL_LINES = 12;
 /**
  * Read the `ship:` block of lawbook/config.yaml (line-oriented, like the other
@@ -79,10 +80,28 @@ function branchFiles(projectPath) {
         return [];
     const base = mergeBase(projectPath, "main") ?? mergeBase(projectPath, "master");
     const committed = base ? changedFiles(projectPath, base) : [];
-    return [...new Set([...committed, ...worktreeChangedFiles(projectPath)])]
+    return [
+        ...new Set([
+            ...committed,
+            ...worktreeChangedFiles(projectPath),
+            ...untrackedFiles(projectPath),
+        ]),
+    ]
         .filter((f) => !f.startsWith("lawbook/changes/"))
         .sort();
 }
+/** New files not yet added, outside ship's own output (`lawbook/changes/`, `.speclaw/`). */
+function untrackedFiles(projectPath) {
+    return git(projectPath, [
+        "-c",
+        "core.quotePath=false",
+        "ls-files",
+        "--others",
+        "--exclude-standard",
+    ])
+        .split("\n")
+        .filter((f) => f && !f.startsWith("lawbook/changes/") && !f.startsWith(".speclaw/"));
+}
 function secs(ms) {
     return `${(ms / 1000).toFixed(1)} s`;
 }
@@ -139,14 +158,201 @@ function findArchived(projectPath, name) {
         .pop();
     return hit ? path.join("lawbook", "changes", "archive", hit) : null;
 }
+const RECORD_STUB = "<!-- 2–5 lines: what and why. -->";
 function fillRecord(recordPath, summary) {
     if (!fs.existsSync(recordPath))
         return;
-    const body = fs
-        .readFileSync(recordPath, "utf8")
-        .replace("<!-- 2–5 lines: what and why. -->", summary)
-        .replace(/^- \[ \] /gm, "- [x] ");
-    fs.writeFileSync(recordPath, body);
+    let body = fs.readFileSync(recordPath, "utf8");
+    // A function replacer: `$&` or `$'` in a commit body must stay literal.
+    if (summary)
+        body = body.replace(RECORD_STUB, () => summary);
+    fs.writeFileSync(recordPath, body.replace(/^- \[ \] /gm, "- [x] "));
+}
+/**
+ * The branch's own commit messages (subjects and bodies, trailers dropped),
+ * skipping commits that only touched ship's output; empty when there are none.
+ * A Conventional Commit body is the change's why, so it stands in for one.
+ */
+function commitSummary(projectPath) {
+    const base = mergeBase(projectPath, "main") ?? mergeBase(projectPath, "master");
+    if (!base)
+        return "";
+    return git(projectPath, [
+        "log",
+        "--format=%B",
+        `${base}..HEAD`,
+        "--",
+        ".",
+        ":(exclude)lawbook/changes",
+        ":(exclude).speclaw",
+    ])
+        .split("\n")
+        .filter((l) => !/^[\w-]+-by:/i.test(l))
+        .join("\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim()
+        .split("\n")
+        .slice(0, COMMIT_SUMMARY_LINES)
+        .join("\n");
+}
+/** A record's why is a few lines; a long branch history keeps only its start. */
+const COMMIT_SUMMARY_LINES = 15;
+/** A manifest whose only diff against `base` is its `"version"` lines: a release bump. */
+function isVersionBump(projectPath, base, file) {
+    if (!base || !/(^|\/)package(-lock)?\.json$/.test(file))
+        return false;
+    const lines = git(projectPath, ["diff", "-U0", base, "--", file])
+        .split("\n")
+        .filter((l) => /^[+-](?![+-]{2})/.test(l));
+    return lines.length > 0 && lines.every((l) => /^[+-]\s*"version"\s*:/.test(l));
+}
+/**
+ * Propose a ceremony level from the branch diff itself. A release bump of the
+ * manifests is not a global change, so it does not raise the level.
+ */
+function measureDiff(projectPath, files) {
+    const base = mergeBase(projectPath, "main") ?? mergeBase(projectPath, "master");
+    const paths = files.filter((f) => !isVersionBump(projectPath, base, f));
+    const { thresholds } = loadCeremonyConfig(projectPath);
+    return proposeLevel(gatherSignals(projectPath, { paths, symbols: [] }, thresholds), thresholds);
+}
+/**
+ * Create the change at the level its diff measures: level 0 gets a record,
+ * level 1+ the feature stubs that level requires. The level is recorded as
+ * `measured`, so a later, larger diff raises it.
+ */
+function scaffoldMeasured(projectPath, name, files, measured) {
+    const proposal = measured ?? measureDiff(projectPath, files);
+    const targets = { paths: files, symbols: [] };
+    const level = proposal.level ?? 0;
+    if (level > 0 && CHANGE_NAME_RE.test(name)) {
+        scaffoldFeature(projectPath, name, { level, targets, proposal, confirmedBy: "measured" });
+    }
+    else {
+        scaffoldQuick(projectPath, name, targets, { proposal, confirmedBy: "measured" });
+    }
+}
+/** Raise a measured level when the branch diff has grown past it; a human-set level stands. */
+function remeasure(projectPath, name, files) {
+    const rec = readCeremonyRecord(projectPath, name);
+    if (rec?.confirmedBy !== "measured")
+        return;
+    const proposal = measureDiff(projectPath, files);
+    if (proposal.level !== null && proposal.level > rec.confirmedLevel) {
+        promoteCeremonyLevel(projectPath, name, proposal.level, "the branch diff grew", proposal);
+    }
+}
+/**
+ * Reopen a change archived on this branch at a measured level the diff has
+ * since outgrown (work shipped at a mid-task stop, then grew): move it back
+ * under `lawbook/changes/`, drop its finished harness, and raise its level. An
+ * archive that already exists at the merge base belongs to merged work and stays.
+ *
+ * @returns Whether the change was reopened.
+ */
+function reopenIfGrown(projectPath, name, archivedRel, files) {
+    const archivedDir = path.join(projectPath, archivedRel);
+    let rec = {};
+    try {
+        rec = JSON.parse(fs.readFileSync(path.join(archivedDir, "change.json"), "utf8"));
+    }
+    catch {
+        return false;
+    }
+    if (rec.confirmedBy !== "measured" || rec.confirmedLevel === undefined)
+        return false;
+    const base = mergeBase(projectPath, "main") ?? mergeBase(projectPath, "master");
+    if (!base)
+        return false;
+    // git object paths are POSIX on every platform.
+    const objectPath = `${archivedRel.split(path.sep).join("/")}/change.json`;
+    const atBase = spawnSync("git", ["cat-file", "-e", `${base}:${objectPath}`], {
+        cwd: projectPath,
+    });
+    if (atBase.status === 0)
+        return false;
+    const proposal = measureDiff(projectPath, files);
+    if (proposal.level === null || proposal.level <= rec.confirmedLevel)
+        return false;
+    const changeDir = path.join(projectPath, "lawbook", "changes", name);
+    fs.renameSync(archivedDir, changeDir);
+    fs.rmSync(path.join(changeDir, "harness.json"), { force: true });
+    promoteCeremonyLevel(projectPath, name, proposal.level, "the branch diff grew", proposal);
+    return true;
+}
+/**
+ * Text a scaffold, a promotion, or ship itself leaves in an artifact until
+ * someone writes it. Task stubs match whole generated lines only, so a real
+ * task that starts the same way ("Make the hook idempotent") is never a stub.
+ */
+const STUBS = {
+    // At level 1+ the level-0 file list ship filled in is not a why.
+    "record.md": [/<!-- 2–5 lines: what and why\. -->/, /^Changed \d+ file\(s\): /m],
+    "proposal.md": [
+        /<!-- The problem and who it affects\. -->/,
+        /\(promoted — fill in why\)/,
+        // A promotion seeds Why from the level rationale and What with this line.
+        /\(promoted from level \d\)/,
+    ],
+    "design.md": [/<!-- Module boundaries, data flow, and decisions\. -->/, /\(promoted — fill in\)/],
+    "tasks.md": [
+        /^\s*- \[[ xX]\] (1\.1 Implement the change|Implement|Make the fix|Make the change|Add or update a regression test|Add or update tests|Record evidence under reports\/|Write discipline report under reports\/)\s*$/m,
+    ],
+};
+/**
+ * Artifacts the change's confirmed level requires that are missing or still a
+ * scaffold stub, as instructions the agent can act on. Level 0 owes nothing:
+ * its record falls back to the commits or the file list, so it costs no turn. Bug-shaped changes keep
+ * their own checks (`bugfix.md`) and are not judged here.
+ *
+ * @param projectPath - Project root with `lawbook/`.
+ * @param name - Change name.
+ * @returns One instruction per missing artifact; empty when the change is documented.
+ */
+export function pendingArtifacts(projectPath, name) {
+    const dir = path.join(projectPath, "lawbook", "changes", name);
+    if (!fs.existsSync(dir) || readChangeType(projectPath, name) === "bug")
+        return [];
+    const level = confirmedLevel(projectPath, name);
+    const needs = artifactNeeds(level, "feature");
+    const rel = (f) => path.join("lawbook", "changes", name, f);
+    const state = (f) => {
+        const abs = path.join(dir, f);
+        if (!fs.existsSync(abs))
+            return "missing";
+        const text = fs.readFileSync(abs, "utf8");
+        return (STUBS[f] ?? []).some((m) => m.test(text)) ? "stub" : "written";
+    };
+    const out = [];
+    // Level 0 never waits on prose: the record falls back to commits or the file list.
+    if (needs.record && level > 0 && state("record.md") !== "written") {
+        out.push(`${rel("record.md")}: write what changed and why (2–5 lines) under "What changes"`);
+    }
+    if (needs.proposal && state("proposal.md") !== "written") {
+        out.push(`${rel("proposal.md")}: write why, what changes, and the impact`);
+    }
+    const design = state("design.md");
+    if (needs.design && !needs.designOptionalWithJustification && design !== "written") {
+        out.push(`${rel("design.md")}: write the approach — boundaries, data flow, decisions`);
+    }
+    else if (design === "stub") {
+        out.push(`${rel("design.md")}: write the approach, or delete it (optional at level 2)`);
+    }
+    if (needs.tasksFile && state("tasks.md") !== "written") {
+        out.push(`${rel("tasks.md")}: list the tasks this change did, checked (- [x])`);
+    }
+    if (needs.deltaSpecs) {
+        const specs = deltaSpecFiles(dir);
+        if (specs.length === 0) {
+            out.push(`${rel("specs/<capability>/spec.md")}: add the full intended spec of the capability this changes`);
+        }
+        for (const f of specs) {
+            if (isPlaceholderDelta(fs.readFileSync(f, "utf8"))) {
+                out.push(`${path.relative(projectPath, f)}: replace the placeholder with the capability's full intended spec (or move it to the capability it changes)`);
+            }
+        }
+    }
+    return out;
 }
 /**
  * Record the test verdict derived from gate exit codes. Ship never records a
@@ -173,12 +379,13 @@ function recordGateVerdict(projectPath, change) {
     }
 }
 /**
- * Fast path for finished work, in one call: scaffold a level-0 record when the
- * change does not exist, run the project's gates once, and write a discipline
- * report from their real output. At level 0 passing gates are the whole
- * verification, so the change is archived. At level 1+ ship stops after the
- * evidence: review is a human (or reviewer-role) decision taken on the PR, and
- * the archive follows it.
+ * Fast path for finished work, in one call: create the change at the level its
+ * branch diff measures (raising a measured level when the diff grew), refuse
+ * to run the gates while an artifact that level requires is missing or still a
+ * stub, then run the project's gates once and write a discipline report from
+ * their real output. At level 0 passing gates are the whole verification, so
+ * the change is archived. At level 1+ ship stops after the evidence: review is
+ * a human (or reviewer-role) decision taken on the PR, and the archive follows it.
  *
  * @param projectPath - Project root with `lawbook/`.
  * @param name - Change name (kebab-case).
@@ -192,16 +399,46 @@ export function shipChange(projectPath, name, opts = {}) {
     const date = opts.date ?? new Date().toISOString().slice(0, 10);
     const changeDir = path.join(projectPath, "lawbook", "changes", name);
     const files = branchFiles(projectPath);
-    const archived = findArchived(projectPath, name);
-    if (!fs.existsSync(changeDir) && !archived) {
-        scaffoldQuick(projectPath, name, { paths: [], symbols: [] });
+    let archived = findArchived(projectPath, name);
+    if (archived && !fs.existsSync(changeDir) && reopenIfGrown(projectPath, name, archived, files)) {
+        archived = null;
     }
-    const summary = opts.summary ??
-        (files.length
-            ? `Changed ${files.length} file(s): ${files.slice(0, 8).join(", ")}${files.length > 8 ? ", …" : ""}`
-            : "No file changes detected.");
-    fillRecord(path.join(changeDir, "record.md"), summary);
+    if (!fs.existsSync(changeDir) && !archived)
+        scaffoldMeasured(projectPath, name, files);
+    else if (fs.existsSync(changeDir))
+        remeasure(projectPath, name, files);
+    const commits = isGitRepo(projectPath) ? commitSummary(projectPath) : "";
+    const fileList = files.length
+        ? `Changed ${files.length} file(s): ${files.slice(0, 8).join(", ")}${files.length > 8 ? ", …" : ""}`
+        : "No file changes detected.";
+    fillRecord(path.join(changeDir, "record.md"), opts.summary ?? (commits || (confirmedLevel(projectPath, name) === 0 ? fileList : "")));
+    const pending = pendingArtifacts(projectPath, name);
     const t1 = Date.now();
+    if (pending.length) {
+        const level = confirmedLevel(projectPath, name);
+        const why = readCeremonyRecord(projectPath, name)?.rationale ?? "";
+        return {
+            change: name,
+            gatesPassed: false,
+            gates: [],
+            files,
+            report: null,
+            pending,
+            archivedTo: null,
+            next: [
+                `level ${level}${why ? ` (${why})` : ""}: document the change, then stop again — the gates run once it is written`,
+                ...pending,
+            ],
+            timings: {
+                scaffold: t1 - t0,
+                gates: 0,
+                report: 0,
+                archive: 0,
+                overhead: t1 - t0,
+                total: t1 - t0,
+            },
+        };
+    }
     const commands = opts.gates ?? cfg.gates ?? detectGates(projectPath);
     const gates = [];
     for (const command of commands) {
@@ -247,6 +484,7 @@ export function shipChange(projectPath, name, opts = {}) {
         gates,
         files,
         report: reportRel,
+        pending,
         archivedTo,
         next,
         timings: {
@@ -259,6 +497,92 @@ export function shipChange(projectPath, name, opts = {}) {
         },
     };
 }
+/** Where {@link docHint} remembers what it last measured and told. */
+const DOC_HINT_STATE = path.join(".speclaw", "doc-hint.json");
+/** The change the hook would ship on this branch: the one last shipped here, else the branch's. */
+function branchChange(projectPath, branch) {
+    const marker = readMarker(projectPath);
+    return marker && marker.branch === branch && marker.change
+        ? marker.change
+        : changeNameForBranch(branch);
+}
+/**
+ * The documentation a change owes, told while the agent is still working so it
+ * writes it in the same turn as the code instead of after a blocked stop. Runs
+ * from the `PostToolUse` hook: it re-measures only when the set of changed
+ * files changed, creates the change once the diff measures level 1 or more,
+ * and speaks once per change and level. Never throws; null means say nothing.
+ *
+ * @param projectPath - Project root.
+ * @returns The hint for the agent, or null.
+ */
+export function docHint(projectPath) {
+    try {
+        if (!fs.existsSync(path.join(projectPath, "lawbook")))
+            return null;
+        // One git call answers "anything new?" on most calls (this runs after every
+        // edit and Bash call): branch, HEAD, and the worktree outside ship's output.
+        const status = git(projectPath, [
+            "-c",
+            "core.quotePath=false",
+            "status",
+            "--porcelain=v2",
+            "--branch",
+            "--untracked-files=all",
+        ]);
+        const branch = /^# branch\.head (.+)$/m.exec(status)?.[1] ?? "";
+        if (!branch || ["main", "master", "(detached)"].includes(branch))
+            return null;
+        const quick = status
+            .split("\n")
+            .filter((l) => !l.includes(" lawbook/changes/") && !l.includes(" .speclaw/"))
+            .join("\n");
+        const statePath = path.join(projectPath, DOC_HINT_STATE);
+        let prev = {};
+        try {
+            prev = JSON.parse(fs.readFileSync(statePath, "utf8"));
+        }
+        catch {
+            // First hint on this checkout.
+        }
+        if (prev.quick === quick)
+            return null;
+        const files = branchFiles(projectPath);
+        const key = `${branch}\n${files.join("\n")}`;
+        const remember = (extra) => {
+            fs.mkdirSync(path.dirname(statePath), { recursive: true });
+            fs.writeFileSync(statePath, JSON.stringify({ ...prev, quick, key, ...extra }) + "\n");
+        };
+        if (files.length === 0 || prev.key === key) {
+            remember({});
+            return null;
+        }
+        const change = branchChange(projectPath, branch);
+        const changeDir = path.join(projectPath, "lawbook", "changes", change);
+        const archived = findArchived(projectPath, change);
+        if (fs.existsSync(changeDir))
+            remeasure(projectPath, change, files);
+        else if (archived)
+            reopenIfGrown(projectPath, change, archived, files);
+        else {
+            const proposal = measureDiff(projectPath, files);
+            if ((proposal.level ?? 0) > 0)
+                scaffoldMeasured(projectPath, change, files, proposal);
+        }
+        const level = fs.existsSync(changeDir) ? confirmedLevel(projectPath, change) : 0;
+        remember({ change, level });
+        const pending = level > 0 ? pendingArtifacts(projectPath, change) : [];
+        if (pending.length === 0 || (prev.change === change && prev.level === level))
+            return null;
+        const why = readCeremonyRecord(projectPath, change)?.rationale ?? "";
+        return (`speclaw: this change measures level ${level}${why ? ` (${why})` : ""}. ` +
+            `In this same turn, before you stop, write briefly and truthfully:\n- ${pending.join("\n- ")}\n` +
+            `The Stop hook then runs the gates once.`);
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Change name for a branch: the part after the last `/`, kebab-cased
  * (`fix/compass-query-output` → `compass-query-output`).
@@ -311,30 +635,41 @@ function readMarker(projectPath) {
     return { branch: "", change: "", fingerprint: raw };
 }
 /**
- * Fingerprint of the branch's work outside `lawbook/changes/`: the working tree
- * diffed against the merge base with `main`/`master`, plus untracked files
- * (names and contents). Committing that work leaves it unchanged — a commit is not new work —
- * and ship writes under `lawbook/changes/`, so its own output never changes it.
- * Without a merge base it falls back to the diff against HEAD plus HEAD itself.
+ * Fingerprint of the branch's work outside `lawbook/changes/` and `.speclaw/`: every path that
+ * differs from the merge base with `main`/`master` or is untracked, with its
+ * working-tree contents. A file hashes the same whether it is untracked, staged
+ * or committed, so committing work — new files included — is not new work; ship
+ * writes under `lawbook/changes/`, so its own output never changes it either.
+ * Without a merge base it falls back to the paths changed against HEAD plus HEAD itself.
  */
 function workFingerprint(projectPath) {
     const base = mergeBase(projectPath, "main") ?? mergeBase(projectPath, "master");
-    const diff = git(projectPath, ["diff", base ?? "HEAD", "--", ".", ":(exclude)lawbook/changes"]);
+    const tracked = git(projectPath, [
+        "-c",
+        "core.quotePath=false",
+        "diff",
+        "--name-only",
+        base ?? "HEAD",
+        "--",
+        ".",
+        ":(exclude)lawbook/changes",
+        ":(exclude).speclaw",
+    ]).split("\n");
     const hash = createHash("sha256");
-    for (const f of git(projectPath, ["ls-files", "--others", "--exclude-standard"]).split("\n")) {
-        if (!f || f.startsWith("lawbook/changes/") || f.startsWith(".speclaw/"))
+    for (const f of [...new Set([...tracked, ...untrackedFiles(projectPath)])].sort()) {
+        if (!f)
             continue;
-        // Contents, not just names: editing a new, not-yet-added file is new work.
         hash.update(`${f}\n`);
         try {
             hash.update(fs.readFileSync(path.join(projectPath, f)));
         }
         catch {
-            // Vanished or unreadable since listing: its name stands in.
+            // Deleted, vanished or unreadable: its name stands in.
+            hash.update("\0");
         }
     }
     const anchor = base ?? git(projectPath, ["rev-parse", "HEAD"]).trim();
-    return hash.update(`\n${anchor}\n${diff}`).digest("hex");
+    return hash.update(`\n${anchor}\n`).digest("hex");
 }
 /**
  * The `Stop` hook body: when the agent ends a turn on a feature branch with
@@ -359,8 +694,6 @@ export function shipOnStop(projectPath) {
     }
     // A change shipped by name on this branch keeps receiving the branch's later
     // work; the branch name would point at another (possibly archived) change.
-    const change = marker && marker.branch === branch && marker.change
-        ? marker.change
-        : changeNameForBranch(branch);
+    const change = branchChange(projectPath, branch);
     return { skipped: null, change, result: shipChange(projectPath, change) };
 }

package/dist/modules/lawbook/stack-parse.js

@@ -1,4 +1,13 @@
+import fs from "node:fs";
 import path from "node:path";
+function realRoot(projectPath) {
+    try {
+        return fs.realpathSync(projectPath);
+    }
+    catch {
+        return projectPath;
+    }
+}
 const V8_NAMED = /^\s*at\s+(?:async\s+)?(?:(.+?)\s+\()?([^\s()]+):(\d+):(\d+)\)?\s*$/;
 const V8_ANON = /^\s*at\s+([^\s()]+):(\d+):(\d+)\s*$/;
 const PY_FRAME = /^\s*File\s+"([^"]+)",\s*line\s+(\d+)(?:,\s*in\s+(.+))?\s*$/;
@@ -29,14 +38,21 @@ export function mapDistToSrc(rel) {
  */
 export function normalizeTracePath(projectPath, rawPath) {
     let p = rawPath.replace(/\\/g, "/");
-    const root = projectPath.replace(/\\/g, "/");
-    if (p.startsWith(root + "/"))
-        p = p.slice(root.length + 1);
+    // A runtime prints real paths: under a symlinked root (macOS /tmp → /private/tmp)
+    // the trace names the real root, not the one the project was opened by.
+    const roots = [
+        ...new Set([projectPath, realRoot(projectPath)].map((r) => r.replace(/\\/g, "/"))),
+    ];
+    const strip = () => {
+        const root = roots.find((r) => p.startsWith(r + "/"));
+        if (root)
+            p = p.slice(root.length + 1);
+    };
+    strip();
     if (p.startsWith("file://")) {
         try {
             p = decodeURIComponent(new URL(p).pathname);
-            if (p.startsWith(root + "/"))
-                p = p.slice(root.length + 1);
+            strip();
         }
         catch {
             /* keep raw */

package/dist/server.js

@@ -7,6 +7,20 @@ import { registerFoundation } from "./modules/foundation/register.js";
 import { registerTools } from "./modules/tools/register.js";
 import { isMinimalMode } from "./shared/exposure.js";
 import { pkgVersion } from "./shared/version.js";
+/**
+ * Sent in the MCP `initialize` response; Claude Code keeps it in the agent's
+ * context even while tool definitions are deferred, so it names the one tool
+ * per job that replaces a shell read. Kept short: it is paid on every session.
+ */
+export const SERVER_INSTRUCTIONS = [
+    "speclaw has a tool for each of these jobs; use it instead of shell reads:",
+    '- Locate code: compass_find. Read it: compass_explore (include ["source"]; maxDepth 4 reads a whole call chain; blast_radius before changing a symbol). Not cat/sed/grep/rg.',
+    "- Failing test, bug, or stack trace: lawbook_investigate first, with the test output as stackTrace — it ranks the code that test reaches.",
+    "- Before running tests or finishing: compass_diff_context (what the diff touches, which tests cover it).",
+    "- Multi-module or public-API work: lawbook_change draft before coding; validate any spec you write.",
+    "- No or stale index: compass_index. 3+ large independent parts: cortex. Setup: speclaw_setup.",
+    "Markdown, JSON, and config files are fine to read directly.",
+].join("\n");
 /**
  * Build the speclaw MCP server with every module's tools registered.
  *
@@ -14,7 +28,7 @@ import { pkgVersion } from "./shared/version.js";
  */
 export function buildServer(opts = {}) {
     const minimal = opts.minimal ?? isMinimalMode();
-    const server = new McpServer({ name: "speclaw", version: pkgVersion() });
+    const server = new McpServer({ name: "speclaw", version: pkgVersion() }, { instructions: SERVER_INSTRUCTIONS });
     const reg = { minimal };
     registerFoundation(server, reg);
     registerSpec(server, reg);

package/dist/shared/exposure.js

@@ -5,14 +5,11 @@ import { readManifest } from "./manifest.js";
 /**
  * Tools omitted when the exposure profile is `minimal`. Kept tools are the
  * discovery + law loop: compass_explore/find/diff_context, lawbook_change,
- * cortex. Deprecated aliases are never registered in minimal mode.
+ * lawbook_investigate, cortex, and speclaw_check — the tool every installed
+ * hook calls, so omitting it silently disables the laws and the Compass nudge.
+ * Deprecated aliases are never registered in minimal mode.
  */
-export const MINIMAL_OMIT = new Set([
-    "compass_index",
-    "lawbook_investigate",
-    "speclaw_setup",
-    "speclaw_check",
-]);
+export const MINIMAL_OMIT = new Set(["compass_index", "speclaw_setup"]);
 /**
  * Whether minimal exposure is active for this process / project.
  * `SPECLAW_MINIMAL=1` wins; otherwise the project manifest's `minimal` flag.

package/dist/shared/index-stats.js

@@ -0,0 +1,40 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Totals of the last index run, kept beside the index as plain JSON so hot
+ * paths (the hooks) can size the repo without opening the database.
+ */
+export const INDEX_STATS_FILE = path.join(".speclaw", "index-stats.json");
+/**
+ * Record the index totals after a run. Best-effort: a failed write never fails
+ * the index.
+ *
+ * @param projectPath - Project root.
+ * @param totals - Whole-repository counts after the run.
+ */
+export function writeIndexStats(projectPath, totals) {
+    try {
+        const file = path.join(projectPath, INDEX_STATS_FILE);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify({ files: totals.files, nodes: totals.nodes }) + "\n");
+    }
+    catch {
+        // The stats are an optimization for hooks; the index itself is intact.
+    }
+}
+/**
+ * The last index run's totals, or null when no run recorded them.
+ *
+ * @param projectPath - Project root.
+ */
+export function readIndexStats(projectPath) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(projectPath, INDEX_STATS_FILE), "utf8"));
+        return typeof raw.files === "number"
+            ? { files: raw.files, nodes: typeof raw.nodes === "number" ? raw.nodes : 0 }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/shared/mcp.js

@@ -25,8 +25,8 @@ export function text(value, budget = "brief") {
 }
 /**
  * Register one MCP tool after enforcing the context-budget caps (description
- * word count and estimated definition tokens). Does **not** set
- * `defer_loading` — that is not author-settable for MCP servers.
+ * word count and estimated definition tokens). `alwaysLoad` marks the
+ * definition `_meta["anthropic/alwaysLoad"]` so Claude Code never defers it.
  *
  * @param server - MCP server to register on.
  * @param spec - Tool name, description, schema, and handler.
@@ -51,6 +51,7 @@ export function defineTool(server, spec) {
         description: spec.description,
         inputSchema,
         ...(spec.annotations ? { annotations: spec.annotations } : {}),
+        ...(spec.alwaysLoad ? { _meta: { "anthropic/alwaysLoad": true } } : {}),
     }, spec.handler);
 }
 const ALIAS_MAX_WORDS = 12;

package/package.json

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