@esneiderbravo/speclaw 2.0.3 → 2.0.5

package/dist/cli/commands/check.js

@@ -14,7 +14,9 @@ async function readStdin() {
  *
  * - `--hook-payload -` reads a hook event JSON from stdin, evaluates it, prints
  *   the `hookSpecificOutput` contract, and exits 2 on `deny` (the documented
- *   command-hook block signal).
+ *   command-hook block signal). `PostToolUse` never carries a
+ *   `permissionDecision`: it prints `additionalContext` when the result has a
+ *   reason (nothing otherwise) and always exits 0.
  * - `--dry-run [--path P] [--event E]` previews the verdict for a synthetic
  *   action against path `P`, without blocking anything (always exits 0).
  * - with no flags, prints a summary of the project's declared laws.
@@ -37,6 +39,14 @@ export async function runCheck(flags) {
         const event = (payload.hook_event_name ?? payload.event ?? "PreToolUse");
         const toolName = (payload.tool_name ?? payload.toolName);
         const result = checkAction({ projectPath: cwd, event, toolName, payload });
+        if (event === "PostToolUse") {
+            // PostToolUse (feedback laws, the Compass-first nudge) carries context
+            // only and never a permission decision. Other events keep their output.
+            if (result.hookSpecificOutput) {
+                console.log(JSON.stringify({ hookSpecificOutput: result.hookSpecificOutput }));
+            }
+            return;
+        }
         const decision = result.verdict === "deny" ? "deny" : "allow";
         console.log(JSON.stringify({
             hookSpecificOutput: {

package/dist/cli/commands/cortex.js

@@ -40,6 +40,7 @@ export async function runCortex(flags) {
             pauseForQuestions: Boolean(flags["pause-questions"]),
             note: typeof flags.note === "string" ? flags.note : undefined,
         });
+        printHarnessWarnings(result);
         console.log(JSON.stringify(result, null, 2));
     }
     catch (err) {
@@ -47,3 +48,19 @@ export async function runCortex(flags) {
         process.exit(1);
     }
 }
+/**
+ * Print the Compass-first gate outcome of a harness result to stderr — the
+ * `compassEvidence` count, then any warning — keeping stdout pure JSON.
+ *
+ * @param result - Any `handleHarness` result.
+ */
+export function printHarnessWarnings(result) {
+    const { compassEvidence: ev, warnings } = result;
+    if (ev) {
+        process.stderr.write(`  compass-first: ${ev.calls} Compass evidence call(s) in stage "${ev.stage}" (compassGate: ${ev.mode})\n`);
+    }
+    if (!Array.isArray(warnings))
+        return;
+    for (const w of warnings)
+        process.stderr.write(`  ! ${String(w)}\n`);
+}

package/dist/cli/commands/index-build.js

@@ -1,18 +1,26 @@
 import { buildIndex } from "../../modules/compass/indexer.js";
 import { startWatch } from "../../modules/compass/watcher.js";
+import { recordCompassCall } from "../../shared/compass-calls.js";
 import { ui, renderProgress, clearProgress } from "../lib/ui.js";
 /** (Re)build the Compass code graph for the cwd, showing progress and final stats. */
 export async function runIndex(flags) {
     const cwd = process.cwd();
-    ui.step("Indexing with Compass");
+    recordCompassCall(cwd, "compass_index");
+    const json = Boolean(flags.json);
+    if (!json)
+        ui.step("Indexing with Compass");
     const start = Date.now();
     const stats = await buildIndex(cwd, {
         force: Boolean(flags.force),
         prune: Boolean(flags.prune),
         maxCacheMB: flags["max-cache-mb"] ? Number(flags["max-cache-mb"]) : undefined,
         retentionDays: flags.retention ? Number(flags.retention) : undefined,
-        onProgress: (e) => renderProgress(e.done, e.total, e.file),
+        onProgress: json ? undefined : (e) => renderProgress(e.done, e.total, e.file),
     });
+    if (json) {
+        process.stdout.write(JSON.stringify(stats, null, 2) + "\n");
+        return;
+    }
     clearProgress();
     const secs = ((Date.now() - start) / 1000).toFixed(1);
     const root = stats.rootUnchanged ? " · root unchanged" : "";
@@ -20,6 +28,9 @@ export async function runIndex(flags) {
         `${stats.computed} computed · ${stats.fromCache} fromCache · ` +
         `${stats.unchanged} unchanged · ${stats.skippedByStat} skippedByStat` +
         `${root}  (${secs}s)`);
+    const t = stats.totals;
+    ui.info(`Totals: ${t.files} files · ${t.nodes} nodes · ${t.edges} edges`);
+    ui.info(stats.nextStep);
 }
 /** Build the initial index, then watch for file changes to keep it fresh. */
 export async function runWatch(_flags) {

package/dist/cli/commands/lawbook.js

@@ -1,8 +1,10 @@
 import { specInit, specValidate, specSync, specArchive, specList, } from "../../modules/lawbook/engine.js";
 import { handleLevel } from "../../modules/lawbook/quick.js";
 import { scaffoldBugfix } from "../../modules/lawbook/bugfix.js";
+import { scaffoldFeature } from "../../modules/lawbook/scaffold-change.js";
 import { investigate, formatInvestigateResult } from "../../modules/lawbook/investigate.js";
 import { handleHarness } from "../../modules/cortex/harness.js";
+import { printHarnessWarnings } from "./cortex.js";
 import { list } from "../lib/args.js";
 import { ui } from "../lib/ui.js";
 function today() {
@@ -115,21 +117,32 @@ export async function runSpec(flags) {
                 return;
             }
             case "draft": {
-                if (!flags.bug) {
-                    ui.err("Usage: speclaw lawbook draft --bug <name> [--level N] [--json]");
-                    process.exit(1);
-                }
-                const name = typeof flags.bug === "string" ? flags.bug : req(change, "lawbook draft --bug <name>");
                 const levelFlag = flags.level;
-                const level = levelFlag === undefined || levelFlag === true
-                    ? undefined
-                    : Number(levelFlag);
-                const result = scaffoldBugfix(cwd, name, { level });
+                const level = levelFlag === undefined || levelFlag === true ? undefined : parseLevel(levelFlag);
+                if (flags.bug) {
+                    const name = typeof flags.bug === "string" ? flags.bug : req(change, "lawbook draft --bug <name>");
+                    const result = scaffoldBugfix(cwd, name, { level });
+                    if (flags.json) {
+                        console.log(JSON.stringify(result, null, 2));
+                        return;
+                    }
+                    ui.ok(`bug change "${name}" scaffolded at ${result.dir}`);
+                    return;
+                }
+                const name = req(change, "lawbook draft <name> [--level N] [--capability C] [--json] | --bug <name>");
+                const result = scaffoldFeature(cwd, name, {
+                    level,
+                    reason: typeof flags.reason === "string" ? flags.reason : undefined,
+                    capability: typeof flags.capability === "string" ? flags.capability : undefined,
+                });
                 if (flags.json) {
                     console.log(JSON.stringify(result, null, 2));
                     return;
                 }
-                ui.ok(`bug change "${name}" scaffolded at ${result.dir}`);
+                ui.ok(`feature change "${name}" scaffolded at ${result.dir} ` +
+                    (result.level === null
+                        ? "(level unconfirmed — run `speclaw lawbook level set`)"
+                        : `(level ${result.level})`));
                 return;
             }
             case "archive": {
@@ -170,6 +183,7 @@ export async function runSpec(flags) {
                     pauseForQuestions: Boolean(flags["pause-questions"]),
                     note: typeof flags.note === "string" ? flags.note : undefined,
                 });
+                printHarnessWarnings(result);
                 if (flags.json) {
                     console.log(JSON.stringify(result, null, 2));
                     return;
@@ -187,6 +201,13 @@ export async function runSpec(flags) {
         process.exit(1);
     }
 }
+/** Parse a `--level` flag value into a ceremony level; throws on anything but 0–3. */
+function parseLevel(raw) {
+    const n = Number(Array.isArray(raw) ? raw[raw.length - 1] : raw);
+    if (n === 0 || n === 1 || n === 2 || n === 3)
+        return n;
+    throw new Error(`--level must be 0, 1, 2, or 3 (got "${String(raw)}")`);
+}
 /** Return the value or print a usage error and exit if it is missing. */
 function req(value, usage) {
     if (!value) {

package/dist/cli/commands/query.js

@@ -5,6 +5,16 @@ import { hotspots, coupling } from "../../modules/compass/hotspots.js";
 import { diffContext, formatDiffContext } from "../../modules/compass/diff-context.js";
 import { list } from "../lib/args.js";
 import { ui } from "../lib/ui.js";
+import { recordCompassCall } from "../../shared/compass-calls.js";
+/** CLI query verbs that are Compass call-log twins of an MCP tool. */
+const LOGGED_VERBS = {
+    explore: "compass_explore",
+    search: "compass_search",
+    recall: "compass_recall",
+    impact: "compass_impact",
+    trace: "compass_trace",
+    "diff-context": "compass_diff_context",
+};
 /**
  * Run a Compass query from the shell — the same surface agents call via MCP.
  *
@@ -20,6 +30,9 @@ export async function runQuery(cmd, flags) {
     const focus = list(flags.focus);
     const maxTokens = flags["max-tokens"] ? Number(flags["max-tokens"]) : undefined;
     const explain = Boolean(flags.explain);
+    const logged = LOGGED_VERBS[cmd];
+    if (logged)
+        recordCompassCall(cwd, logged);
     try {
         switch (cmd) {
             case "explore": {

package/dist/cli/index.js

@@ -18,7 +18,7 @@ Setup
   agent add <id>           Configure another agent later (symlinks + MCP)
 
 Compass (code intelligence — the same surface agents use via MCP)
-  index                    (Re)build the local code graph (--force / --prune)
+  index                    (Re)build the local code graph (--force / --prune / --json)
   watch                    Keep the index fresh on file changes
   explore <node>           A node's source + callers/callees
   search <query>           Hybrid find (BM25+vector+name); --focus --max-tokens --explain
@@ -39,6 +39,7 @@ Lawbook (spec-driven workflow)
   lawbook init             Create the lawbook/ workspace
   lawbook list             Active/archived changes and capabilities
   lawbook level <mode>     Propose/set/promote/explain ceremony level (--json)
+  lawbook draft <name>     Scaffold a feature change (--level N, --capability C, --json)
   lawbook draft --bug <c>  Scaffold a bug change (bugfix.md + reports)
   lawbook investigate      Rank bug suspects from graph (--symptom / --stack-trace, --json)
   lawbook validate <c>     Validate a change's artifacts
@@ -115,6 +116,8 @@ function maybeHeader(cmd, flags) {
         return;
     if (cmd === "quick" && flags.json)
         return;
+    if (cmd === "index" && flags.json)
+        return;
     if (cmd === "lawbook" && flags.json && flags._[0] === "level")
         return;
     if (cmd === "lawbook" && flags.json && flags._[0] === "investigate")

package/dist/modules/compass/indexer.js

@@ -212,6 +212,8 @@ export async function buildIndex(projectPath, onProgressOrOpts) {
         removed: 0,
         rootUnchanged: false,
         embedder: embedder.id,
+        totals: { files: 0, nodes: 0, edges: 0 },
+        nextStep: "",
     };
     const cfg = loadAffectedConfig(projectPath);
     const existing = new Map();
@@ -398,6 +400,8 @@ export async function buildIndex(projectPath, onProgressOrOpts) {
         evictCacheBySize(db, maxCacheMB);
         db.prepare("INSERT INTO meta(key, value) VALUES ('indexed_at', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(new Date().toISOString());
         clearNeedsReindex(db);
+        stats.totals = countTotals(db);
+        stats.nextStep = indexNextStep(stats.totals);
         db.exec("COMMIT");
     }
     catch (err) {
@@ -416,6 +420,16 @@ export async function buildIndex(projectPath, onProgressOrOpts) {
     }
     return stats;
 }
+function countTotals(db) {
+    const count = (table) => Number(db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get().n);
+    return { files: count("files"), nodes: count("nodes"), edges: count("edges") };
+}
+/** Next-step hint printed after an index run; names the query tools, not grep. */
+export function indexNextStep(totals) {
+    const fmt = (n) => n.toLocaleString("en-US");
+    return (`Index ready: ${fmt(totals.files)} files, ${fmt(totals.nodes)} symbols. ` +
+        `Next: compass_find "<concept>" or compass_explore <symbol> — do not grep.`);
+}
 function evictCacheBySize(db, maxCacheMB) {
     const limitBytes = maxCacheMB * 1024 * 1024;
     const row = db

package/dist/modules/compass/register.js

@@ -3,6 +3,7 @@ import { defineTool, defineAliasTool, text } from "../../shared/mcp.js";
 import { shouldExpose } from "../../shared/exposure.js";
 import { aliasesEnabled } from "../../shared/tool-catalog.js";
 import { logDeprecatedCall, prefixDeprecated } from "../../shared/deprecation.js";
+import { recordCompassCall } from "../../shared/compass-calls.js";
 import { buildIndex } from "./indexer.js";
 import { impact } from "./query.js";
 import { affectedTests } from "./affected.js";
@@ -17,7 +18,14 @@ export function registerCompass(server, opts = {}) {
     const add = (name, description, inputSchema, handler) => {
         if (!shouldExpose(name, minimal))
             return;
-        defineTool(server, { name, description, inputSchema, handler });
+        // Every canonical call lands in the call log the Cortex gate and the
+        // Compass-first nudge read; the write is best-effort and never throws.
+        const call = handler;
+        const logged = ((args, extra) => {
+            recordCompassCall(args.projectPath, name);
+            return call(args, extra);
+        });
+        defineTool(server, { name, description, inputSchema, handler: logged });
     };
     add("compass_explore", "Symbol context in one call: source, callers, callees, blast radius, tests, hotspot. Prefer before grep.", {
         projectPath: z.string(),
@@ -85,6 +93,7 @@ export function registerCompass(server, opts = {}) {
         inputSchema: { projectPath: z.string(), query: z.string(), limit: z.number().optional() },
         handler: async ({ projectPath, query, limit }) => {
             logDeprecatedCall(projectPath, "compass_search");
+            recordCompassCall(projectPath, "compass_search");
             const body = JSON.stringify(await findSymbols(projectPath, query, "exact", limit), null, 2);
             return text(prefixDeprecated("compass_search", body));
         },
@@ -95,6 +104,7 @@ export function registerCompass(server, opts = {}) {
         inputSchema: { projectPath: z.string(), query: z.string(), limit: z.number().optional() },
         handler: async ({ projectPath, query, limit }) => {
             logDeprecatedCall(projectPath, "compass_recall");
+            recordCompassCall(projectPath, "compass_recall");
             const body = JSON.stringify(await findSymbols(projectPath, query, "concept", limit), null, 2);
             return text(prefixDeprecated("compass_recall", body));
         },
@@ -111,6 +121,7 @@ export function registerCompass(server, opts = {}) {
         },
         handler: async (args) => {
             logDeprecatedCall(args.projectPath, "compass_impact");
+            recordCompassCall(args.projectPath, "compass_impact");
             const sym = args.symbol ?? args.node;
             const body = sym
                 ? JSON.stringify(await exploreRich({
@@ -133,6 +144,7 @@ export function registerCompass(server, opts = {}) {
         },
         handler: async ({ projectPath, from, to, maxDepth }) => {
             logDeprecatedCall(projectPath, "compass_trace");
+            recordCompassCall(projectPath, "compass_trace");
             const body = JSON.stringify(await exploreRich({ projectPath, node: from, to, maxDepth }), null, 2);
             return text(prefixDeprecated("compass_trace", body));
         },
@@ -148,6 +160,7 @@ export function registerCompass(server, opts = {}) {
         },
         handler: async (args) => {
             logDeprecatedCall(args.projectPath, "compass_affected_tests");
+            recordCompassCall(args.projectPath, "compass_affected_tests");
             const body = JSON.stringify(affectedTests(args.projectPath, args), null, 2);
             return text(prefixDeprecated("compass_affected_tests", body));
         },
@@ -158,6 +171,7 @@ export function registerCompass(server, opts = {}) {
         inputSchema: { projectPath: z.string(), limit: z.number().optional() },
         handler: async ({ projectPath, limit }) => {
             logDeprecatedCall(projectPath, "compass_hotspots");
+            recordCompassCall(projectPath, "compass_hotspots");
             const body = JSON.stringify(hotspots(projectPath, { limit }), null, 2);
             return text(prefixDeprecated("compass_hotspots", body));
         },
@@ -168,6 +182,7 @@ export function registerCompass(server, opts = {}) {
         inputSchema: { projectPath: z.string(), file: z.string() },
         handler: async ({ projectPath, file }) => {
             logDeprecatedCall(projectPath, "compass_coupling");
+            recordCompassCall(projectPath, "compass_coupling");
             const body = JSON.stringify(coupling(projectPath, file, {}), null, 2);
             return text(prefixDeprecated("compass_coupling", body));
         },
@@ -181,6 +196,7 @@ export function registerCompass(server, opts = {}) {
         },
         handler: async ({ projectPath, action }) => {
             logDeprecatedCall(projectPath, "compass_watch");
+            recordCompassCall(projectPath, "compass_watch");
             const result = action === "start"
                 ? startWatch(projectPath)
                 : action === "stop"

package/dist/modules/cortex/compass-gate.js

@@ -0,0 +1,84 @@
+/**
+ * Compass-first evidence gate for Cortex `advance`.
+ *
+ * Leaving `exploring` or `implementing` requires (strict) or recommends (warn)
+ * at least one Compass evidence call in the shared call log since the current
+ * stage started. Cortex must not import from the lawbook module, so the
+ * `compassGate` key is read with a local regex scan of `lawbook/config.yaml`.
+ *
+ * // Covers: req~compass-evidence-gate~1
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { EVIDENCE_TOOLS, countEvidence, readCompassCalls } from "../../shared/compass-calls.js";
+/** Mode used when the key is missing or invalid. */
+export const DEFAULT_COMPASS_GATE = "warn";
+/** Stages whose exit is gated. */
+export const GATED_STAGES = new Set(["exploring", "implementing"]);
+const GATE_KEY = /^compassGate:[ \t]*(["']?)([A-Za-z]*)\1[ \t]*(?:#.*)?$/m;
+/**
+ * Read the top-level `compassGate` key from `lawbook/config.yaml`.
+ *
+ * Quotes are optional and a trailing comment is allowed. A missing file or
+ * key, or any value other than `off`/`warn`/`strict`, yields `warn`.
+ *
+ * @param projectPath - Project root.
+ */
+export function readCompassGateMode(projectPath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(projectPath, "lawbook", "config.yaml"), "utf8");
+    }
+    catch {
+        return DEFAULT_COMPASS_GATE;
+    }
+    const value = GATE_KEY.exec(raw)?.[2];
+    return value === "off" || value === "warn" || value === "strict" ? value : DEFAULT_COMPASS_GATE;
+}
+/**
+ * When the current stage started: the `at` of the newest history entry whose
+ * `to` is the current stage. `start` enters `exploring` and `rework` enters
+ * `implementing`, so a rework restarts the window. Null when none matches.
+ *
+ * @param state - Harness state.
+ */
+export function stageStartedAt(state) {
+    for (let i = state.history.length - 1; i >= 0; i--) {
+        const entry = state.history[i];
+        if (entry.to === state.stage)
+            return entry.at;
+    }
+    return null;
+}
+/**
+ * Count Compass evidence calls since the current stage started.
+ *
+ * Reads only the bounded call-log tail. With no matching history entry every
+ * log entry is eligible.
+ *
+ * @param projectPath - Project root.
+ * @param state - Harness state before the advance.
+ * @param mode - Gate mode; defaults to {@link readCompassGateMode}.
+ */
+export function evaluateCompassGate(projectPath, state, mode = readCompassGateMode(projectPath)) {
+    const since = stageStartedAt(state);
+    const sinceMs = since === null ? Number.NaN : Date.parse(since);
+    const calls = countEvidence(readCompassCalls(projectPath, Number.isNaN(sinceMs) ? {} : { sinceMs }));
+    return { mode, stage: state.stage, since, calls, satisfied: calls > 0 };
+}
+function evidenceToolList() {
+    return [...EVIDENCE_TOOLS].join(", ");
+}
+/** Error text for a strict rejection. */
+export function compassGateError(result) {
+    return (`compass-first: cannot leave stage "${result.stage}" — no Compass evidence call ` +
+        `(${evidenceToolList()}) since ${result.since ?? "the stage started"}. ` +
+        `Locate and read the code with compass_find / compass_explore first, ` +
+        `or relax compassGate (off|warn) in lawbook/config.yaml.`);
+}
+/** Warning text for a warn-mode advance without evidence. */
+export function compassGateWarning(result) {
+    return (`compass-first: left stage "${result.stage}" with no Compass evidence call ` +
+        `(${evidenceToolList()}) since ${result.since ?? "the stage started"}. ` +
+        `Set compassGate: strict in lawbook/config.yaml to enforce.`);
+}

package/dist/modules/cortex/harness.js

@@ -10,16 +10,10 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-export const HARNESS_STAGES = [
-    "exploring",
-    "planning",
-    "questions",
-    "implementing",
-    "reviewing",
-    "testing",
-    "archiving",
-    "done",
-];
+import { GATED_STAGES, compassGateError, compassGateWarning, evaluateCompassGate, readCompassGateMode, } from "./compass-gate.js";
+// Harness types live in the leaf `types.ts` so `compass-gate.ts` can use them
+// without importing this file back (no file-level import cycle).
+export { HARNESS_STAGES, } from "./types.js";
 export const harnessOps = ["status", "start", "advance", "rework"];
 const DEFAULT_MAX_REWORK = 3;
 function specRoot(projectPath) {
@@ -186,6 +180,19 @@ export function handleHarness(args) {
             return next;
         }
         const to = allowedAdvance(current.stage, current.level, args.verdict ?? undefined);
+        // Compass-first gate: runs before any write, so a strict rejection leaves
+        // harness.json byte-identical.
+        let compassEvidence;
+        const warnings = [];
+        const mode = GATED_STAGES.has(current.stage) ? readCompassGateMode(projectPath) : "off";
+        if (mode !== "off") {
+            const { satisfied, ...evidence } = evaluateCompassGate(projectPath, current, mode);
+            compassEvidence = evidence;
+            if (!satisfied && mode === "strict")
+                throw new Error(compassGateError(evidence));
+            if (!satisfied)
+                warnings.push(compassGateWarning(evidence));
+        }
         const verdicts = { ...current.verdicts };
         if (current.stage === "reviewing" && args.verdict)
             verdicts.review = args.verdict;
@@ -208,7 +215,9 @@ export function handleHarness(args) {
             ],
         };
         writeHarness(projectPath, change, next);
-        return next;
+        if (!compassEvidence)
+            return next;
+        return warnings.length ? { ...next, compassEvidence, warnings } : { ...next, compassEvidence };
     }
     if (harnessOp === "rework") {
         if (current.stage !== "reviewing" && current.stage !== "testing") {

package/dist/modules/cortex/types.js

@@ -0,0 +1,14 @@
+/**
+ * Harness state types shared by `harness.ts` and `compass-gate.ts`. A leaf
+ * module: it imports nothing, so neither consumer forms an import cycle.
+ */
+export const HARNESS_STAGES = [
+    "exploring",
+    "planning",
+    "questions",
+    "implementing",
+    "reviewing",
+    "testing",
+    "archiving",
+    "done",
+];

package/dist/modules/foundation/assets/AGENTS.template.md

@@ -16,8 +16,8 @@ Claude-specific notes: [`CLAUDE.md`](CLAUDE.md). The law: [`LAWS.md`](LAWS.md).
    standards below. Open the standard that governs your change before making
    it. Conflicts resolve in favor of the standard; amendments go through a
    spec change, never silent deviation.
-2. **Compass first, always** — for any code question call `compass_explore` /
-   `compass_search` / `compass_recall` **before** any grep/sed/cat/Read,
+2. **Compass first, always** — for any code question call `compass_find` /
+   `compass_explore` **before** any grep/sed/cat/Read,
    including files you already know by name. Fall back to manual file tools only
    after Compass returns nothing useful, the graph is missing (`compass_index`
    first), or the target isn't indexed code (stylesheets, config, logs). Cheat

package/dist/modules/foundation/assets/CLAUDE.template.md

@@ -31,9 +31,10 @@ ignore it.
 
 This repo is indexed by Compass, speclaw's local code graph (`.speclaw/`). For
 **any** question about code — what a symbol is, what it uses, who calls it,
-where it lives, how a value flows — call Compass **first**: `compass_search` /
-`compass_recall` to locate, `compass_explore` to read a symbol with its callers
-and callees, `compass_impact` / `compass_trace` for blast radius and call paths.
+where it lives, how a value flows — call Compass **first**: `compass_find` to
+locate, `compass_explore` to read a symbol with its callers and callees (include
+`blast_radius` for what could break, `to` for a call path), and
+`compass_diff_context` for the context of a diff.
 Run `compass_index` first if the graph is missing.
 
 This includes files you already know the name of: to learn what `Foo` imports,

package/dist/modules/foundation/assets/docs/compass.template.md

@@ -18,7 +18,7 @@ is nothing extra to install.
 | Without Compass | With Compass |
 |-----------------|--------------|
 | Many `Grep` + `Read` round-trips (tokens spent scanning) | One `compass_explore` call returns just the relevant node |
-| Guess which file matters | `compass_recall` finds code by meaning |
+| Guess which file matters | `compass_find` finds code by name or meaning |
 | Edit without knowing the blast radius | callers/callees returned with the node |
 | Whole files dumped into context | verbatim source of the node + its neighbors only |
 
@@ -30,12 +30,12 @@ a request, not whole files.
 | Tool | Use it to |
 |------|-----------|
 | `compass_index` | Build/refresh the graph (`.speclaw/index.db`). Incremental — unchanged files are skipped by hash. Run once after init and after significant edits. |
-| `compass_explore` | Read a node's verbatim source plus its callers and callees. The default before editing. |
-| `compass_search` | Structural search: find nodes by name/keyword. |
-| `compass_recall` | Semantic search: describe what you want in natural language and get nodes ranked by meaning. |
-| `compass_impact` | Blast radius: every node that transitively calls a target — "what could break if I change this?" before editing. |
-| `compass_trace` | Trace a call path between two nodes — how an entrypoint reaches a sink. |
-| `compass_watch` | Keep the index fresh automatically (start/stop a debounced incremental re-index on file change). |
+| `compass_find` | Find code: `mode: exact` by name/keyword, `mode: concept` by meaning in natural language. |
+| `compass_explore` | Read a node's verbatim source plus its callers and callees. The default before editing. Add `include: ["blast_radius"]` for what could break, or `to: <symbol>` for the call path between two nodes. |
+| `compass_diff_context` | Symbols, blast radius, and tests for a diff (working tree or a rev). |
+
+`compass_index` also takes `action: start|stop|status` to keep the index fresh
+automatically (a debounced incremental re-index on file change).
 
 If the graph is missing (no `.speclaw/index.db`), run `compass_index` first —
 a missing graph is not license to skip Compass. The only legitimate fallbacks

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

@@ -43,11 +43,11 @@ verdicts are complete.
 - Scenario headers use exactly `#### Scenario:`.
 - Acceptance criteria are testable without production integrations.
 - The implemented code must match what the delta spec promises. Validate with
-  the `lawbook_validate` tool before syncing or archiving.
+  `lawbook_change` (action: validate) before syncing or archiving.
 
 ## Archiving discipline
 
-Always archive with the `archive` command / `lawbook_archive` tool, never a manual
+Always archive with the `archive` command / `lawbook_change` (action: archive), never a manual
 `mv`. The engine refuses archive while tasks are unchecked, reports are missing,
 specs are out of sync when required, or harness review/test verdicts are not PASS.
 

package/dist/modules/foundation/check.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { performance } from "node:perf_hooks";
 import { compileScope, hasBackend, isActiveLaw, manifestPath, matchCompiled, readLawManifest, } from "./laws.js";
+import { compassNudge, isNudgeEvent } from "./compass-nudge.js";
 const cache = new Map();
 /**
  * Load the project's compiled law index, using the in-process cache when the
@@ -79,18 +80,35 @@ function recordContextCoverage(projectPath, laws, file) {
  * another (unimplemented) backend are skipped. The evaluator fails open: a
  * missing or unparseable manifest, or any exception, yields `allow` with a
  * diagnostic — an enforcement layer that blocks when its own checker crashes is
- * worse than none.
+ * worse than none. On `PostToolUse` Read/Grep/Glob it evaluates no law and carries
+ * only the advisory Compass-first `nudge` (see `compass-nudge.ts`), which never
+ * alters the verdict.
  *
  * @param args - The project, hook event, optional tool name, and raw payload.
  * @returns The verdict, the laws evaluated, an optional reason, and `elapsedMs`.
  */
 export function checkAction(args) {
     const start = performance.now();
-    const done = (r) => ({
-        ...r,
-        elapsedMs: performance.now() - start,
-    });
+    // Runs before the manifest load so the nudge works with no laws at all; it
+    // swallows its own errors and returns null.
+    const nudge = compassNudge(args);
+    const done = (r) => {
+        const reason = nudge ? (r.reason ? `${r.reason}\n${nudge}` : nudge) : r.reason;
+        return {
+            ...r,
+            ...(nudge ? { nudge, reason } : {}),
+            // Only PostToolUse: Stop / InstructionsLoaded keep their pre-change shape.
+            ...(reason && args.event === "PostToolUse"
+                ? { hookSpecificOutput: { hookEventName: args.event, additionalContext: reason } }
+                : {}),
+            elapsedMs: performance.now() - start,
+        };
+    };
     try {
+        // Laws govern mutations: a PostToolUse Read/Grep/Glob carries only the
+        // nudge and never evaluates a law, so reads stay as silent as on main.
+        if (isNudgeEvent(args))
+            return done({ verdict: "allow", evaluated: [] });
         const laws = loadLaws(args.projectPath);
         if (!laws) {
             return done({