@esneiderbravo/speclaw 2.0.19 → 2.0.21

package/dist/modules/lawbook/ship.js

@@ -1,12 +1,14 @@
 import fs from "node:fs";
 import path from "node:path";
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
 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
@@ -157,14 +159,261 @@ 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 cached = cachedMeasure(projectPath, files);
+    if (cached)
+        return cached;
+    const base = mergeBase(projectPath, "main") ?? mergeBase(projectPath, "master");
+    const paths = files.filter((f) => !isVersionBump(projectPath, base, f));
+    const { thresholds } = loadCeremonyConfig(projectPath);
+    const proposal = proposeLevel(gatherSignals(projectPath, { paths, symbols: [] }, thresholds), thresholds);
+    try {
+        const file = path.join(projectPath, LEVEL_CACHE);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify({ key: fileSetKey(files), proposal }) + "\n");
+    }
+    catch {
+        // The cache only saves time; the measurement stands without it.
+    }
+    return proposal;
+}
+/**
+ * The last measurement, kept per changed-file set: measuring a large diff
+ * (blast radius, affected tests) takes seconds, so the edit hook measures in
+ * the background and ship reuses the result at the stop.
+ */
+const LEVEL_CACHE = path.join(".speclaw", "level-cache.json");
+function fileSetKey(files) {
+    return createHash("sha256").update(files.join("\n")).digest("hex");
+}
+/** The cached proposal for exactly this file set, or null. */
+function cachedMeasure(projectPath, files) {
+    try {
+        const c = JSON.parse(fs.readFileSync(path.join(projectPath, LEVEL_CACHE), "utf8"));
+        return c.key === fileSetKey(files) && c.proposal ? c.proposal : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Measure the branch's current diff into the level cache (`speclaw
+ * measure-diff`, the edit hook's detached background job).
+ *
+ * @param projectPath - Project root.
+ */
+export function measureBranchDiff(projectPath) {
+    const files = branchFiles(projectPath);
+    if (files.length)
+        measureDiff(projectPath, files);
+}
+/** The CLI entry beside this module, run by the background measurement. */
+const CLI_ENTRY = fileURLToPath(new URL("../../cli/index.js", import.meta.url));
+/** Start `speclaw measure-diff` in its own process group; never waits, never throws. */
+function measureInBackground(projectPath) {
+    try {
+        const child = spawn(process.execPath, [CLI_ENTRY, "measure-diff"], {
+            cwd: projectPath,
+            detached: true,
+            stdio: "ignore",
+            windowsHide: true,
+        });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        // The stop measures anyway; a lost background job only delays the hint.
+    }
+}
+/**
+ * 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
@@ -191,12 +440,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).
@@ -210,16 +460,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: [] });
-    }
-    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);
+    let archived = findArchived(projectPath, name);
+    if (archived && !fs.existsSync(changeDir) && reopenIfGrown(projectPath, name, archived, files)) {
+        archived = null;
+    }
+    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) {
@@ -265,6 +545,7 @@ export function shipChange(projectPath, name, opts = {}) {
         gates,
         files,
         report: reportRel,
+        pending,
         archivedTo,
         next,
         timings: {
@@ -277,6 +558,123 @@ 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.
+        }
+        const save = (next) => {
+            fs.mkdirSync(path.dirname(statePath), { recursive: true });
+            fs.writeFileSync(statePath, JSON.stringify(next) + "\n");
+        };
+        if (prev.quick === quick && !prev.pending)
+            return null;
+        // A measurement still running for this same worktree: nothing new to say yet,
+        // and listing the branch's files would cost more git calls than the answer.
+        if (prev.quick === quick && prev.pending && !measuredSince(projectPath, prev.pending.at)) {
+            if (Date.now() - prev.pending.at < MEASURE_GRACE_MS)
+                return null;
+        }
+        const files = branchFiles(projectPath);
+        const key = `${branch}\n${files.join("\n")}`;
+        if (files.length === 0 || (prev.key === key && !prev.pending)) {
+            save({ ...prev, quick, key });
+            return null;
+        }
+        // Measuring a large diff takes seconds — longer than the hook may run —
+        // so it happens in the background and the hint follows on a later call.
+        if (!cachedMeasure(projectPath, files)) {
+            const fresh = prev.pending?.key === key && Date.now() - prev.pending.at < MEASURE_GRACE_MS;
+            if (!fresh)
+                measureInBackground(projectPath);
+            save({ ...prev, quick, pending: fresh ? prev.pending : { key, at: Date.now() } });
+            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;
+        const pending = level > 0 ? pendingArtifacts(projectPath, change) : [];
+        const told = prev.told?.change === change && prev.told.level === level;
+        if (pending.length === 0 || told) {
+            save({ quick, key, ...(prev.told ? { told: prev.told } : {}) });
+            return null;
+        }
+        // "Told" is recorded only with the hint actually returned, so a level is
+        // never marked as told by a call that said nothing.
+        save({ quick, key, told: { change, level } });
+        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;
+    }
+}
+/** Whether the level cache was written at or after `at` (epoch ms). */
+function measuredSince(projectPath, at) {
+    try {
+        return fs.statSync(path.join(projectPath, LEVEL_CACHE)).mtimeMs >= at;
+    }
+    catch {
+        return false;
+    }
+}
+/** How long a started background measurement is awaited before it is started again. */
+const MEASURE_GRACE_MS = 2 * 60 * 1000;
 /**
  * Change name for a branch: the part after the last `/`, kebab-cased
  * (`fix/compass-query-output` → `compass-query-output`).
@@ -388,8 +786,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.19",
+  "version": "2.0.21",
   "publishConfig": {
     "access": "public"
   },