@esneiderbravo/speclaw 2.0.2 → 2.0.4

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({

package/dist/modules/foundation/compass-nudge.js

@@ -0,0 +1,189 @@
+import fs from "node:fs";
+import path from "node:path";
+import { NUDGE_ENTRY, isEvidenceTool, readCompassCalls, recordCompassCall, } from "../../shared/compass-calls.js";
+// Pure extension → language table: loads no grammar and opens no index DB.
+import { langForPath } from "../compass/languages.js";
+// Covers: req~compass-nudge~1
+//
+// The Compass-first nudge: on `PostToolUse` for Read/Grep/Glob of indexed code,
+// remind the agent to locate and read through Compass when the call log shows
+// no recent Compass evidence. Advisory context only — it never gates and never
+// touches the verdict. It reads only the bounded call-log tail and the
+// in-memory extension table, so it stays inside the hook latency budget.
+/** Tools whose completed calls the nudge watches. */
+export const NUDGE_TOOLS = new Set(["Read", "Grep", "Glob"]);
+/** No nudge when a Compass evidence call landed within this window. */
+export const NUDGE_EVIDENCE_WINDOW_MS = 10 * 60 * 1000;
+/** At most one nudge per this window. */
+export const NUDGE_RATE_LIMIT_MS = 5 * 60 * 1000;
+/** Path segments that are never indexed source. */
+const SKIP_SEGMENTS = new Set(["node_modules", ".git", ".speclaw", "dist"]);
+/**
+ * True for a `PostToolUse` Read/Grep/Glob call. Those calls are the nudge's
+ * alone: laws govern mutations, so `checkAction` skips law evaluation for them.
+ */
+export function isNudgeEvent(args) {
+    if (args.event !== "PostToolUse")
+        return false;
+    const tool = usable(args.toolName) ?? usable(args.payload?.tool_name);
+    return !!tool && NUDGE_TOOLS.has(tool);
+}
+/** A usable string: non-empty and not an unsubstituted `${…}` hook placeholder. */
+function usable(v) {
+    if (typeof v !== "string")
+        return null;
+    const s = v.trim();
+    return s && !s.includes("${") ? s : null;
+}
+/** Sentinel target for a repo-wide search: no path, or the project root. */
+const ROOT = "";
+/**
+ * The project-relative POSIX target, {@link ROOT} for the project root, or
+ * null when the nudge has nothing to say about it: outside the project, or
+ * under a never-indexed directory.
+ */
+function resolveTarget(projectPath, raw) {
+    const root = path.resolve(projectPath);
+    const rel = path.relative(root, path.resolve(root, raw));
+    if (!rel)
+        return ROOT;
+    if (rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel))
+        return null;
+    const segments = rel.split(path.sep);
+    if (segments.some((seg) => SKIP_SEGMENTS.has(seg)))
+        return null;
+    return segments.join("/");
+}
+/** ripgrep `--type` names whose extension differs from the name. */
+const RG_TYPE_EXT = {
+    rust: "rs",
+    python: "py",
+    typescript: "ts",
+    javascript: "js",
+    ruby: "rb",
+    csharp: "cs",
+    kotlin: "kt",
+    markdown: "md",
+    golang: "go",
+};
+/** True when `ext` (with or without the dot) is a Compass-indexed extension. */
+function indexedExt(ext) {
+    return langForPath(`x.${ext.replace(/^\./, "")}`) !== undefined;
+}
+/**
+ * The extensions a glob restricts matches to, expanding `*.{ts,md}` braces;
+ * an empty list when the last segment names no extension (e.g. `**\/*`).
+ */
+function globExtensions(glob) {
+    const last = glob.split("/").pop() ?? glob;
+    const brace = /\.\{([^}]*)\}$/.exec(last);
+    if (brace)
+        return brace[1]
+            .split(",")
+            .map((e) => e.trim())
+            .filter(Boolean);
+    const ext = path.extname(last);
+    return ext && !/[*?[]/.test(ext) ? [ext.slice(1)] : [];
+}
+/** A glob is code-targeting when it is extension-less or names an indexed extension. */
+function globTargetsCode(glob) {
+    const exts = globExtensions(glob);
+    return exts.length === 0 || exts.some(indexedExt);
+}
+/** Grep is restricted to non-indexed files when its `glob` or `type` says so. */
+function grepRestrictedAway(input) {
+    const glob = usable(input.glob);
+    if (glob && !globTargetsCode(glob))
+        return true;
+    const type = usable(input.type);
+    if (type && !indexedExt(RG_TYPE_EXT[type] ?? type))
+        return true;
+    return false;
+}
+/**
+ * Whether a Read/Grep/Glob of `target` is code access the nudge cares about.
+ *
+ * - Read: the file has an indexed extension.
+ * - Grep: an indexed file, a directory, or a repo-wide search ({@link ROOT}),
+ *   unless `glob`/`type` restrict it to non-indexed extensions.
+ * - Glob: an indexed file, a directory, or a repo-wide search, when `pattern`
+ *   names an indexed extension or none at all (e.g. `**\/*`); a directory with
+ *   no pattern stays eligible.
+ */
+function eligible(projectPath, tool, target, input) {
+    if (target === ROOT)
+        return tool !== "Read" && searchEligible(tool, "", input);
+    const dir = isDirectory(projectPath, target);
+    if (tool === "Read")
+        return dir !== true && indexedExt(path.extname(target) || ".");
+    // A directory has no extension, even when its name has a dot (`src/v1.2`).
+    const ext = dir === true ? "" : path.extname(target);
+    return searchEligible(tool, ext, input, target);
+}
+/**
+ * Whether the target is a directory: one cheap `statSync`, no index access.
+ * Undefined when it cannot be stat'ed (missing, permissions) — callers then
+ * fall back to the extension heuristic.
+ */
+function isDirectory(projectPath, target) {
+    try {
+        return fs.statSync(path.join(projectPath, target)).isDirectory();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Grep/Glob eligibility once the target's extension (`""` for a directory) is known. */
+function searchEligible(tool, ext, input, target = ROOT) {
+    if (ext && !indexedExt(ext))
+        return false;
+    if (tool === "Grep")
+        return !grepRestrictedAway(input);
+    const pattern = usable(input.pattern);
+    if (!pattern)
+        return target !== ROOT;
+    return globTargetsCode(pattern);
+}
+/**
+ * Evaluate the Compass-first nudge for one check call.
+ *
+ * Returns the nudge text — after recording a `nudge` entry in the call log for
+ * the rate limit — or null when the event is not an eligible `PostToolUse`
+ * Read/Grep/Glob, a Compass evidence call landed in the last 10 minutes, or a
+ * nudge already fired in the last 5 minutes. Never throws.
+ *
+ * @param args - The check call's project, event, tool, and raw payload.
+ * @param now - Current epoch ms (injectable for tests).
+ */
+export function compassNudge(args, now = Date.now()) {
+    try {
+        if (args.event !== "PostToolUse")
+            return null;
+        const payload = args.payload ?? {};
+        const tool = usable(args.toolName) ?? usable(payload.tool_name);
+        if (!tool || !NUDGE_TOOLS.has(tool))
+            return null;
+        const input = (payload.tool_input ?? payload.toolInput ?? payload);
+        // No path on Grep/Glob means the cwd: a repo-wide search.
+        const raw = usable(input.file_path) ?? usable(input.path) ?? ".";
+        const target = resolveTarget(args.projectPath, raw);
+        if (target === null || !eligible(args.projectPath, tool, target, input))
+            return null;
+        const pattern = usable(input.pattern);
+        const recent = readCompassCalls(args.projectPath, { sinceMs: now - NUDGE_EVIDENCE_WINDOW_MS });
+        if (recent.some((c) => isEvidenceTool(c.tool)))
+            return null;
+        const rateFloor = now - NUDGE_RATE_LIMIT_MS;
+        if (recent.some((c) => c.tool === NUDGE_ENTRY && Date.parse(c.at) >= rateFloor))
+            return null;
+        recordCompassCall(args.projectPath, NUDGE_ENTRY, new Date(now));
+        const stem = target === ROOT ? "" : path.basename(target, path.extname(target));
+        const query = tool === "Grep" && pattern ? pattern : stem || pattern || "<concept>";
+        const symbol = stem || (tool === "Grep" && pattern ? pattern : "<symbol>");
+        return (`Compass first: no compass_find / compass_explore call in the last 10 min. ` +
+            `Try \`compass_explore ${symbol}\` or \`compass_find "${query}"\` before reading code.`);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/modules/foundation/hooks.js

@@ -11,7 +11,13 @@ const SPECLAW_HOOK_INPUT = {
     payload: {
         hook_event_name: "${hook_event_name}",
         tool_name: "${tool_name}",
-        tool_input: { file_path: "${tool_input.file_path}" },
+        tool_input: {
+            file_path: "${tool_input.file_path}",
+            path: "${tool_input.path}",
+            pattern: "${tool_input.pattern}",
+            glob: "${tool_input.glob}",
+            type: "${tool_input.type}",
+        },
     },
 };
 /** The speclaw hook object — its `{type, server}` pair is the merge identity. */
@@ -24,6 +30,12 @@ const SPECLAW_HOOK = {
 };
 /** Tool-name matcher for the file-mutating tools the `path` backend can evaluate. */
 const MUTATION_MATCHER = "Write|Edit|MultiEdit|NotebookEdit";
+/**
+ * Tool-name matcher for the code-reading tools the Compass-first nudge watches.
+ * Installed on `PostToolUse` only: there the result is context the agent reads
+ * and the event cannot gate the tool; a `PreToolUse` "allow" would auto-approve.
+ */
+export const NUDGE_MATCHER = "Read|Grep|Glob";
 /** True when a hook object is one speclaw owns (safe to replace on merge). */
 function isSpeclawHook(h) {
     const o = h;
@@ -33,7 +45,8 @@ function isSpeclawHook(h) {
  * Compile a law manifest into the hook groups speclaw contributes, one per event
  * the laws demand: `PreToolUse` when any `bloqueo` law exists, `PostToolUse` for
  * `feedback`, `Stop` for `gate`, and `InstructionsLoaded` whenever any law exists
- * (the context-coverage audit). A law whose scope contains a malformed glob is
+ * (the context-coverage audit). One `PostToolUse` group matching `Read|Grep|Glob`
+ * is always emitted for the Compass-first nudge, even with no laws. A law whose scope contains a malformed glob is
  * excluded and reported, so a bad pattern fails loudly at generation rather than
  * silently matching nothing at runtime.
  *
@@ -56,8 +69,10 @@ export function compileHooks(manifest) {
     const hasGate = valid.some((l) => l.enforcement === "gate");
     if (hasBloqueo)
         byEvent.PreToolUse = [{ matcher: MUTATION_MATCHER, hooks: [{ ...SPECLAW_HOOK }] }];
+    // The Compass-first nudge entry is always present, laws or not.
+    byEvent.PostToolUse = [{ matcher: NUDGE_MATCHER, hooks: [{ ...SPECLAW_HOOK }] }];
     if (hasFeedback)
-        byEvent.PostToolUse = [{ matcher: MUTATION_MATCHER, hooks: [{ ...SPECLAW_HOOK }] }];
+        byEvent.PostToolUse.unshift({ matcher: MUTATION_MATCHER, hooks: [{ ...SPECLAW_HOOK }] });
     if (hasGate)
         byEvent.Stop = [{ hooks: [{ ...SPECLAW_HOOK }] }];
     if (valid.length > 0)

package/dist/modules/lawbook/assets/agents/archiver.md

@@ -1,7 +1,7 @@
 ---
 name: archiver
 description: Reconcile specs, sync, and archive a change when Cortex stage is archiving. No new feature implementation.
-tools: Read, Grep, Glob, Write, Edit, Bash, CallMcpTool, mcp__speclaw__compass_explore, mcp__speclaw__lawbook_change, mcp__speclaw__lawbook_validate, mcp__speclaw__lawbook_sync, mcp__speclaw__lawbook_archive, mcp__speclaw__cortex
+tools: Read, Grep, Glob, Write, Edit, Bash, CallMcpTool, mcp__speclaw__compass_explore, mcp__speclaw__lawbook_change, mcp__speclaw__cortex
 ---
 
 You are the **archiver** role in speclaw's **Cortex** (One brain. Many agents.).

package/dist/modules/lawbook/assets/agents/explorer.md

@@ -1,7 +1,7 @@
 ---
 name: explorer
 description: Read-only codebase investigation for a lawbook change. Use when the Cortex stage is exploring (or investigate for bugs). Compass-first; writes nothing under lawbook/ or src/.
-tools: Read, Grep, Glob, CallMcpTool, mcp__speclaw__compass_explore, mcp__speclaw__compass_find, mcp__speclaw__compass_impact, mcp__speclaw__compass_trace, mcp__speclaw__compass_index, mcp__speclaw__lawbook_investigate
+tools: Read, Grep, Glob, CallMcpTool, mcp__speclaw__compass_explore, mcp__speclaw__compass_find, mcp__speclaw__compass_diff_context, mcp__speclaw__compass_index, mcp__speclaw__lawbook_change, mcp__speclaw__lawbook_investigate
 disallowedTools: Write, Edit, MultiEdit, Bash, NotebookEdit
 ---
 
@@ -9,9 +9,12 @@ You are the **explorer** role in speclaw's **Cortex** (One brain. Many agents.).
 
 ## Goal
 
-Investigate the idea or bug with Compass **before** any grep/read. Produce a
-short brief for the planner: relevant symbols, blast radius, risks, and open
-questions. Do **not** draft change artifacts or edit source.
+Investigate the idea or bug with Compass **before** any grep/read: locate with
+`compass_find`, read with `compass_explore`, and run `compass_index` only when
+find returns nothing or reports a missing or stale index. Read/Grep code only
+after naming which Rule 1 fallback holds. Produce a short brief for the
+planner: relevant symbols, blast radius, risks, open questions, and
+`Compass calls made: N`. Do **not** draft change artifacts or edit source.
 
 ## Skill
 

package/dist/modules/lawbook/assets/agents/implementer.md

@@ -1,7 +1,7 @@
 ---
 name: implementer
 description: Implement drafted lawbook tasks in source and tests. Use when Cortex stage is implementing. Does not run final quality gates, review, sync, or archive.
-tools: Read, Grep, Glob, Write, Edit, Bash, CallMcpTool, mcp__speclaw__compass_explore, mcp__speclaw__compass_find, mcp__speclaw__compass_impact, mcp__speclaw__compass_index, mcp__speclaw__lawbook_change, mcp__speclaw__cortex
+tools: Read, Grep, Glob, Write, Edit, Bash, CallMcpTool, mcp__speclaw__compass_explore, mcp__speclaw__compass_find, mcp__speclaw__compass_diff_context, mcp__speclaw__compass_index, mcp__speclaw__lawbook_change, mcp__speclaw__cortex
 disallowedTools: NotebookEdit
 ---
 

package/dist/modules/lawbook/assets/agents/planner.md

@@ -1,7 +1,7 @@
 ---
 name: planner
 description: Draft lawbook change artifacts and ceremony level. Use when Cortex stage is planning. Asks clarifying questions via the coordinator; never edits src/.
-tools: Read, Grep, Glob, Write, Edit, CallMcpTool, mcp__speclaw__compass_explore, mcp__speclaw__compass_find, mcp__speclaw__lawbook_change, mcp__speclaw__lawbook_level
+tools: Read, Grep, Glob, Write, Edit, CallMcpTool, mcp__speclaw__compass_explore, mcp__speclaw__compass_find, mcp__speclaw__lawbook_change
 disallowedTools: Bash, NotebookEdit
 ---
 
@@ -11,7 +11,8 @@ You are the **planner** role in speclaw's **Cortex** (One brain. Many agents.).
 
 Turn the explorer brief + user intent into a reviewable change under
 `lawbook/changes/<name>/` at the confirmed ceremony level. Prefer `draft` /
-`quick` skills.
+`quick` skills; scaffold with `lawbook_change` action `draft` (`change`,
+`level`).
 
 A complete explorer brief is the code map. Do not re-investigate it. Call
 Compass only for a gap the brief names.
@@ -19,8 +20,10 @@ Compass only for a gap the brief names.
 ## Questions
 
 If anything material is ambiguous, **stop**. Return numbered questions to the
-coordinator (do not invent answers). The coordinator advances Cortex with
-`pauseForQuestions`. After human answers, continue drafting.
+coordinator (do not invent answers). When dispatched for questions only, return
+the questions and draft nothing. The coordinator batches them with the explorer
+open questions and the level confirmation into one `pauseForQuestions` round.
+After the human answers, draft at the level the coordinator recorded.
 
 ## Hard constraints
 

package/dist/modules/lawbook/assets/agents/reviewer.md

@@ -1,7 +1,7 @@
 ---
 name: reviewer
 description: Deep review of implemented change without patching code. Writes reports/review.md with PASS or FAIL. Use when Cortex stage is reviewing.
-tools: Read, Grep, Glob, Write, CallMcpTool, mcp__speclaw__compass_explore, mcp__speclaw__compass_find, mcp__speclaw__compass_impact, mcp__speclaw__compass_trace, mcp__speclaw__lawbook_change, mcp__speclaw__cortex
+tools: Read, Grep, Glob, Write, CallMcpTool, mcp__speclaw__compass_explore, mcp__speclaw__compass_find, mcp__speclaw__compass_diff_context, mcp__speclaw__lawbook_change, mcp__speclaw__cortex
 disallowedTools: Edit, MultiEdit, Bash, NotebookEdit
 ---
 

package/dist/modules/lawbook/assets/agents/tester.md

@@ -1,7 +1,7 @@
 ---
 name: tester
 description: Run quality gates and manual verification; write discipline reports. Use when Cortex stage is testing. May add missing tests only — not features.
-tools: Read, Grep, Glob, Write, Edit, Bash, CallMcpTool, mcp__speclaw__compass_explore, mcp__speclaw__compass_affected_tests, mcp__speclaw__lawbook_change, mcp__speclaw__cortex
+tools: Read, Grep, Glob, Write, Edit, Bash, CallMcpTool, mcp__speclaw__compass_explore, mcp__speclaw__compass_diff_context, mcp__speclaw__lawbook_change, mcp__speclaw__cortex
 ---
 
 You are the **tester** role in speclaw's **Cortex** (One brain. Many agents.).

package/dist/modules/lawbook/assets/commands/draft.md

@@ -4,8 +4,8 @@ description: Draft a new spec-driven change at the confirmed ceremony level befo
 
 Draft a new change under `lawbook/changes/<name>/` for: $ARGUMENTS
 
-Follow the `draft` skill: ensure `lawbook/` exists (`lawbook_init`), investigate
-with Compass, propose a ceremony level (`lawbook_level` mode `propose`) and
+Follow the `draft` skill: ensure `lawbook/` exists (`lawbook_change` action `init`), investigate
+with Compass, propose a ceremony level (`lawbook_change` action `level`, mode `propose`) and
 **confirm** it with the human (`set`), then scaffold only the artifacts that
 level requires. For true one-liners use `speclaw quick` / the `quick` skill
 instead. Finish by running `lawbook_change` (action: validate) and fixing every issue.

package/dist/modules/lawbook/assets/commands/quick.md

@@ -6,9 +6,9 @@ Scaffold a **ceremony level 0** change named `$ARGUMENTS` with `speclaw quick`
 (or the equivalent `scaffoldQuick` path). Do **not** invent `proposal.md` /
 `design.md` / delta specs for a true one-liner.
 
-1. Ensure `lawbook/` exists (`lawbook_init` if needed).
+1. Ensure `lawbook/` exists (`lawbook_change` action `init` if needed).
 2. Prefer passing `--path` / `--symbol` so the proposal rationale is measured.
 3. Confirm with the human if the measured proposal is higher than 0 — promote
-   (`lawbook_level` mode `promote`) instead of staying at quick.
+   (`lawbook_change` action `level`, mode `promote`) instead of staying at quick.
 4. Implement, check the checklist in `record.md`, write a discipline report
    under `reports/`, then archive (no sync required at level 0).

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

@@ -70,7 +70,7 @@ in.
 
 ## 4. Reports gate the archive
 
-`lawbook_archive` refuses to archive while `reports/` holds no discipline report
+`lawbook_change` action `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