@esneiderbravo/speclaw 2.0.19 → 2.0.21

package/dist/cli/commands/ship-on-stop.js

@@ -1,8 +1,9 @@
-import { shipOnStop } from "../../modules/lawbook/ship.js";
+import { measureBranchDiff, shipOnStop } from "../../modules/lawbook/ship.js";
 /**
  * `speclaw ship-on-stop`: the Claude Code `Stop` hook. Ships the branch's
  * change when the work changed since the last ship; prints nothing on stdout.
- * A failing gate goes to stderr with exit 2 so the agent sees it and fixes it
+ * Artifacts the change's level still owes, or a failing gate, go to stderr with
+ * exit 2 so the agent sees them and writes or fixes them
  * — once: when the hook already blocked this stop (`stop_hook_active`), it
  * exits 0 so the agent can never loop. Any other failure exits 0.
  *
@@ -13,6 +14,10 @@ export async function runShipOnStop(cwd = process.cwd()) {
     const active = await stopHookActive();
     try {
         const out = shipOnStop(cwd);
+        if (out.skipped === null && out.result.pending.length && !active) {
+            process.stderr.write(`speclaw: ${out.result.next.join("\n- ")}\n`);
+            process.exit(2);
+        }
         if (out.skipped === null && !out.result.gatesPassed && !active) {
             const failed = out.result.gates[out.result.gates.length - 1];
             process.stderr.write(`speclaw: gate failed — ${failed.command} (exit ${failed.exitCode}). Fix it before finishing.\n${failed.tail}\n`);
@@ -23,6 +28,21 @@ export async function runShipOnStop(cwd = process.cwd()) {
         // A hook must never break the session.
     }
 }
+/**
+ * `speclaw measure-diff`: the edit hook's detached background job. Measures the
+ * branch diff's ceremony level into `.speclaw/level-cache.json` so the next
+ * hook call and the stop reuse it. Silent and fail-safe.
+ *
+ * @param cwd - Project root (defaults to the process working directory).
+ */
+export async function runMeasureDiff(cwd = process.cwd()) {
+    try {
+        measureBranchDiff(cwd);
+    }
+    catch {
+        // A background job must never surface anywhere.
+    }
+}
 /** Whether this stop was already blocked by the hook once (`stop_hook_active`). */
 async function stopHookActive() {
     try {

package/dist/cli/commands/ship.js

@@ -31,7 +31,8 @@ export async function runShip(flags) {
             else
                 ui.err(`${g.command} failed, exit ${g.exitCode} (${t})`);
         }
-        ui.ok(`report ${ui.code(result.report)}`);
+        if (result.report)
+            ui.ok(`report ${ui.code(result.report)}`);
         if (result.archivedTo)
             ui.ok(`archived to ${result.archivedTo}`);
         for (const n of result.next)

package/dist/cli/commands/update.js

@@ -143,7 +143,7 @@ const MIGRATIONS = [
         agentPrompt: "- Mention ceremony levels 0–3 (`change.json`), `speclaw quick` for level-0 scaffolds, and " +
             "`lawbook_level` / `speclaw lawbook level` for propose/set/promote. Artifact volume follows " +
             "the confirmed level; missing `change.json` still means full ceremony (level 3). Optional " +
-            "`ceremony:` block in `lawbook/config.yaml` (cuts default [3, 8, 15]). Update LAWS / " +
+            "`ceremony:` block in `lawbook/config.yaml` (cuts default [5, 16, 25]). Update LAWS / " +
             "docs/standards/lawbook.md wording if the project still says every change needs all four artifacts.\n" +
             "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
     },

package/dist/cli/index.js

@@ -131,6 +131,8 @@ async function dispatch(cmd, flags) {
             return (await import("./commands/ship.js")).runShip(flags);
         case "ship-on-stop":
             return (await import("./commands/ship-on-stop.js")).runShipOnStop();
+        case "measure-diff":
+            return (await import("./commands/ship-on-stop.js")).runMeasureDiff();
         case "cortex":
             return (await import("./commands/cortex.js")).runCortex(flags);
         case "lawbook":
@@ -177,7 +179,7 @@ async function main() {
     await maybeHeader(cmd, flags);
     await dispatch(cmd, flags);
     // The SessionStart and edit hooks must stay silent: no update notice either.
-    if (cmd === "session-start" || cmd === "reindex-file" || cmd === "ship-on-stop")
+    if (["session-start", "reindex-file", "ship-on-stop", "measure-diff"].includes(cmd ?? ""))
         return;
     await maybeNotifyUpdate(cmd);
 }

package/dist/cli/lib/help.js

@@ -25,6 +25,7 @@ Compass (code intelligence — the same surface agents use via MCP)
   index                    (Re)build the local code graph (--force / --prune / --json)
   session-start            Silent, fail-safe refresh of an existing index (SessionStart hook)
   ship-on-stop             Ship the branch's change when work changed (Stop hook)
+  measure-diff             Measure the branch diff's level into the cache (edit hook job)
   reindex-file [paths...]  Silent re-index of edited files (PostToolUse hook; stdin JSON)
   watch                    Keep the index fresh on file changes
   explore <node>           A node's source + callers/callees
@@ -176,6 +177,16 @@ Keep the Compass index fresh: re-index changed files until interrupted (Ctrl-C).
 The Claude Code Stop hook. On a feature branch whose work changed since the
 last ship, runs \`speclaw ship\` for the change named after the branch. Prints
 nothing on stdout; a failing gate goes to stderr with exit 2 once.
+`,
+    },
+    {
+        name: "measure-diff",
+        usage: `Usage: speclaw measure-diff
+
+Measure the branch diff's ceremony level into .speclaw/level-cache.json. The
+edit hook starts it as a detached background job when the changed files change,
+so the hook never waits on a slow measurement; ship reuses the cached result.
+Silent and fail-safe.
 `,
     },
     {

package/dist/modules/compass/explore-rich.js

@@ -4,6 +4,72 @@ import { FILE_NODE_KIND, indexExists, openDb } from "./db.js";
 import { hotspots } from "./hotspots.js";
 import { summarizeImpact } from "./impact-summary.js";
 import { budgetExploreShape, applyTextBudget, OUTPUT_BUDGET, } from "../../shared/output-budget.js";
+/** Chain limits per output mode: nodes, and source lines per node. */
+const CHAIN_LIMITS = { brief: { nodes: 8, lines: 25 }, full: { nodes: 20, lines: 80 } };
+function chainNode(projectPath, name, depth, withSource, maxLines) {
+    const ex = explore(projectPath, name);
+    if (!ex.found || !ex.symbol)
+        return null;
+    const node = {
+        name: ex.symbol.name,
+        file: ex.symbol.file,
+        startLine: ex.symbol.startLine,
+        depth,
+    };
+    if (withSource && ex.symbol.source) {
+        const lines = ex.symbol.source.split("\n");
+        node.source =
+            lines.length > maxLines ? lines.slice(0, maxLines).join("\n") + "\n…" : ex.symbol.source;
+    }
+    return { node, callees: (ex.callees ?? []).map((c) => c.name) };
+}
+/**
+ * Breadth-first callee tree below `root` to `maxDepth`, capped per mode; or,
+ * with `path`, the symbols along that call path. Records a truncation when the
+ * node cap cut the walk short.
+ */
+function buildChain(projectPath, root, rootCallees, opts, truncated) {
+    const limits = CHAIN_LIMITS[opts.mode];
+    const out = [];
+    if (opts.path) {
+        opts.path.slice(1).forEach((name, i) => {
+            const hit = chainNode(projectPath, name, i + 1, opts.withSource, limits.lines);
+            if (hit && out.length < limits.nodes)
+                out.push(hit.node);
+        });
+        return out;
+    }
+    const seen = new Set([root]);
+    let frontier = rootCallees.map((name) => ({ name, depth: 1 }));
+    let skipped = 0;
+    while (frontier.length) {
+        const next = [];
+        for (const { name, depth } of frontier) {
+            if (seen.has(name))
+                continue;
+            seen.add(name);
+            if (out.length >= limits.nodes) {
+                skipped++;
+                continue;
+            }
+            const hit = chainNode(projectPath, name, depth, opts.withSource, limits.lines);
+            if (!hit)
+                continue;
+            out.push(hit.node);
+            if (depth < opts.maxDepth)
+                next.push(...hit.callees.map((c) => ({ name: c, depth: depth + 1 })));
+        }
+        frontier = next;
+    }
+    if (skipped) {
+        truncated.push({
+            field: "chain",
+            omitted: skipped,
+            hint: 'use mode:"full", a lower maxDepth, or to:<symbol> for one path',
+        });
+    }
+    return out;
+}
 const DEFAULT_INCLUDES = [
     "source",
     "callers",
@@ -38,6 +104,9 @@ export async function exploreRich(query) {
                 ? `Call path ${query.node} → ${query.to} (${pathResult.hops} hop(s))`
                 : `No call path found within depth limit`,
         };
+        if (pathResult.path && pathResult.path.length > 1) {
+            out.chain = buildChain(query.projectPath, query.node, [], { maxDepth: 0, path: pathResult.path, withSource: includes.includes("source"), mode }, truncated);
+        }
         if (!includes.includes("source") && out.symbol)
             out.symbol = withoutSource(out.symbol);
         if (!includes.includes("callers"))
@@ -51,6 +120,9 @@ export async function exploreRich(query) {
     }
     const base = explore(query.projectPath, query.node, { includeRefs: true });
     const out = { ...base, truncated, degraded };
+    if (base.found && base.symbol && includes.includes("callees") && (query.maxDepth ?? 1) > 1) {
+        out.chain = buildChain(query.projectPath, base.symbol.name, (base.callees ?? []).map((c) => c.name), { maxDepth: query.maxDepth ?? 1, withSource: includes.includes("source"), mode }, truncated);
+    }
     if (!includes.includes("source") && out.symbol)
         out.symbol = withoutSource(out.symbol);
     if (!includes.includes("callers"))

package/dist/modules/compass/indexer.js

@@ -9,6 +9,7 @@ import { contentHashFor, defaultEmbedText } from "./embed-input.js";
 import { buildDirHashMap, dirHash, HASH_EMPTY } from "./merkle.js";
 import { loadAffectedConfig, isTestPath, inferModule, } from "./affected-config.js";
 import { realPathOf } from "../../shared/paths.js";
+import { writeIndexStats } from "../../shared/index-stats.js";
 import { personalizedPageRank, edgeWeightMul } from "./pagerank.js";
 const SKIP_DIRS = new Set([
     ".git",
@@ -937,6 +938,7 @@ export async function buildIndex(projectPath, onProgressOrOpts) {
         stats.totals = countTotals(db);
         stats.nextStep = indexNextStep(stats.totals);
         db.exec("COMMIT");
+        writeIndexStats(projectPath, stats.totals);
     }
     catch (err) {
         // SQLite may already have rolled back (or BEGIN never succeeded): an

package/dist/modules/compass/register.js

@@ -16,7 +16,7 @@ const includeEnum = z.array(z.enum(["source", "callers", "callees", "blast_radiu
 /** Register Compass MCP tools on the given server. */
 export function registerCompass(server, opts = {}) {
     const minimal = Boolean(opts.minimal);
-    const add = (name, description, inputSchema, handler) => {
+    const add = (name, description, inputSchema, handler, alwaysLoad = false) => {
         if (!shouldExpose(name, minimal))
             return;
         // Every canonical call lands in the call log the Cortex gate and the
@@ -26,9 +26,9 @@ export function registerCompass(server, opts = {}) {
             recordCompassCall(args.projectPath, name);
             return call(args, extra);
         });
-        defineTool(server, { name, description, inputSchema, handler: logged });
+        defineTool(server, { name, description, inputSchema, handler: logged, alwaysLoad });
     };
-    add("compass_explore", "Symbol context in one call: source, callers, callees, blast radius, tests, hotspot. Prefer before grep.", {
+    add("compass_explore", "Symbol context in one call: source, callers, callees, blast radius, tests. maxDepth>1 returns the whole callee chain with source.", {
         projectPath: z.string(),
         node: z.string(),
         to: z.string().optional(),
@@ -45,7 +45,9 @@ export function registerCompass(server, opts = {}) {
             maxDepth,
         });
         return text(formatExploreRich(result, (mode ?? "brief")), mode ?? "brief");
-    });
+    }, 
+    // The two code-reading tools load up front: deferred, agents `cat` instead.
+    true);
     add("compass_find", "Hybrid search over the index: BM25, vectors, and name match. mode sets weights; pass focus for edited files.", {
         projectPath: z.string(),
         query: z.string(),
@@ -56,8 +58,8 @@ export function registerCompass(server, opts = {}) {
     }, async ({ projectPath, query, mode, limit, focus, maxTokens }) => {
         const found = await findSymbols(projectPath, query, mode, limit, { focus, maxTokens });
         return text(formatFindResponse(found), { maxTokens: found.cap });
-    });
-    add("compass_diff_context", "Graph context of changes in one call: symbols, blast radius, tests, hotspots. Default: working tree.", {
+    }, true);
+    add("compass_diff_context", "Use before testing or finishing: what the diff touches — symbols, blast radius, covering tests.", {
         projectPath: z.string(),
         rev: z.string().optional(),
         paths: z.array(z.string()).optional(),
@@ -72,8 +74,8 @@ export function registerCompass(server, opts = {}) {
             maxDepth,
         });
         return text(formatDiffContext(result, (mode ?? "brief")), mode ?? "brief");
-    });
-    add("compass_index", "Build or refresh the code graph index; optional watch action for live re-index.", {
+    }, true);
+    add("compass_index", "Use when the index is missing or stale: build or refresh the code graph; watch re-indexes live.", {
         projectPath: z.string(),
         action: z.enum(["index", "start", "stop", "status"]).optional(),
         force: z.boolean().optional(),

package/dist/modules/cortex/register.js

@@ -23,7 +23,7 @@ export function registerCortex(server, opts = {}) {
             return;
         defineTool(server, { name, description, inputSchema, handler });
     };
-    add("cortex", "Cortex multi-agent loop: status with summary, start, advance, rework, brief for a change.", {
+    add("cortex", "Only when work splits into 3+ large independent parts: the multi-agent loop — start, brief, advance, rework, status.", {
         projectPath: z.string(),
         change: z.string(),
         action: z.enum(cortexActions),

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

@@ -27,9 +27,12 @@ Claude-specific notes: [`CLAUDE.md`](CLAUDE.md). The law: [`LAWS.md`](LAWS.md).
    agents.*). Branch `<type>/<slug>`, locate with Compass, implement the
    change and its test yourself, run the tests, finish. The `Stop` hook
    (`speclaw ship-on-stop`) — or `speclaw ship <change> --summary "<what and
-   why>"` as your last step on agents without hooks — records the change, runs
-   the gates once, writes the report from their real output, and archives
-   level-0 work. Review happens on the PR and never blocks the agent. Add
+   why>"` as your last step on agents without hooks — sizes the change from
+   its diff, names the artifacts that level owes while you edit (the why,
+   tasks, delta specs, proposal/design; write them in the same turn), runs the
+   gates once, writes the report
+   from their real output, and archives level-0 work. Commit with a message
+   whose body says why. Review happens on the PR and never blocks the agent. Add
    agents only to run three or more large, independent parts in parallel.
    Details: the `cortex` skill and
    [`docs/standards/lawbook.md`](docs/standards/lawbook.md).

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

@@ -55,9 +55,12 @@ See [`docs/compass.md`](docs/compass.md).
 Every change is built with **Cortex** (*One brain. Many agents.*), and Cortex
 costs no more time than working alone: branch `<type>/<slug>`, locate with
 Compass, implement the change and its test yourself, run the tests, finish.
-Then stop: the `Stop` hook (`speclaw ship-on-stop`) records the change, runs
-the gates once, writes the report from their real output, and archives
-level-0 work with no agent turns; a failing gate comes back to you. Do not run
+Then stop: the `Stop` hook (`speclaw ship-on-stop`) sizes the change from its
+diff, runs the gates once, writes the report from their real output, and
+archives level-0 work with no agent turns. What the level owes (the why — a
+commit body counts — tasks, delta specs, proposal/design) is named while you
+edit: write it in the same turn. A missing piece or a failing gate comes back
+to you at the stop. Do not run
 `speclaw ship` yourself, check the hook, open the archive, edit the generated
 report, read the process docs, or drive the harness by hand. Review happens on the PR, never blocking the
 agent. Add agents only to run three or more large, independent parts in

package/dist/modules/foundation/check.js

@@ -3,6 +3,27 @@ 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";
+/**
+ * Whether a check call should carry the documentation hint: its own mutation
+ * hook group, or a Bash call (agents edit through the shell too). The hint
+ * itself lives in the lawbook module and is loaded by the MCP handler only, so
+ * this hot path never loads the index database.
+ */
+export function wantsDocHint(args) {
+    if (args.event !== "PostToolUse")
+        return false;
+    const payload = (args.payload ?? {});
+    return payload.speclaw_hint === "doc" || (args.toolName ?? payload.tool_name) === "Bash";
+}
+/** Append a hint to a `PostToolUse` result's reason and the agent's additional context. */
+export function withHint(result, hint) {
+    const reason = result.reason ? `${result.reason}\n${hint}` : hint;
+    return {
+        ...result,
+        reason,
+        hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: reason },
+    };
+}
 const cache = new Map();
 /**
  * Load the project's compiled law index, using the in-process cache when the
@@ -92,6 +113,8 @@ export function checkAction(args) {
     // 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);
+    // The documentation-hint group never evaluates a law (see wantsDocHint).
+    const docGroup = args.payload?.speclaw_hint === "doc";
     const done = (r) => {
         const reason = nudge ? (r.reason ? `${r.reason}\n${nudge}` : nudge) : r.reason;
         return {
@@ -107,7 +130,7 @@ export function checkAction(args) {
     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))
+        if (isNudgeEvent(args) || docGroup)
             return done({ verdict: "allow", evaluated: [] });
         const laws = loadLaws(args.projectPath);
         if (!laws) {

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

@@ -3,6 +3,7 @@ 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";
+import { readIndexStats } from "../../shared/index-stats.js";
 // Covers: req~compass-nudge~1
 //
 // The Compass-first nudge: on `PostToolUse` for Read/Grep/Glob of indexed code,
@@ -11,7 +12,63 @@ import { langForPath } from "../compass/languages.js";
 // 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"]);
+export const NUDGE_TOOLS = new Set(["Read", "Grep", "Glob", "Bash"]);
+/** Shell commands that print a file's contents: a Bash `Read`. */
+const SHELL_READERS = new Set(["cat", "head", "tail", "sed", "less", "more", "nl", "bat", "awk"]);
+/** Shell commands that search contents: a Bash `Grep`. */
+const SHELL_SEARCHERS = new Set(["grep", "egrep", "rg", "ag", "ack", "git-grep"]);
+/**
+ * The code read a Bash command performs, as the Read/Grep call it stands in
+ * for, or null when it reads no indexed code. A reader counts only with an
+ * existing indexed file argument (so `cat > f <<EOF` writes stay silent); a
+ * searcher counts on an indexed file, a directory, or the whole repo.
+ */
+export function bashCodeRead(projectPath, command) {
+    // Split on command separators first, then pipes: a command after `|` reads
+    // the previous command's output, not a file (`npm test | grep fail`).
+    const commands = command.split(/\|\||&&|;|\n/).map((c) => c.split("|")[0] ?? "");
+    for (const segment of commands) {
+        const words = segment.trim().split(/\s+/).filter(Boolean);
+        let verb = words[0] ? path.basename(words[0]) : "";
+        let rest = words.slice(1);
+        if (verb === "git" && rest[0] === "grep") {
+            verb = "git-grep";
+            rest = rest.slice(1);
+        }
+        const reader = SHELL_READERS.has(verb);
+        if (!reader && !SHELL_SEARCHERS.has(verb))
+            continue;
+        // A redirect or heredoc writes; `sed -i` edits in place.
+        if (reader && rest.some((w) => w.startsWith(">") || w.startsWith("<<")))
+            continue;
+        if (verb === "sed" && rest.some((w) => /^-[a-zA-Z]*i/.test(w)))
+            continue;
+        const args = rest.filter((w) => !w.startsWith("-")).map((w) => w.replace(/^['"]|['"]$/g, ""));
+        const existing = args.filter((a) => {
+            const target = resolveTarget(projectPath, a);
+            return target !== null && target !== ROOT && isDirectory(projectPath, target) !== undefined;
+        });
+        if (reader) {
+            const file = existing.find((a) => indexedExt(path.extname(a) || "."));
+            if (file)
+                return { tool: "Read", raw: file };
+            continue;
+        }
+        const where = existing.find((a) => isDirectory(projectPath, a) === true || indexedExt(path.extname(a) || "."));
+        // Shell quoting and escapes are not part of the searched text.
+        const pattern = args[0]?.replace(/^[\\'"]+|[\\'"]+$/g, "") || undefined;
+        // No path argument: a search of the working directory, i.e. the repo.
+        if (where || existing.length === 0)
+            return { tool: "Grep", raw: where ?? ".", pattern };
+    }
+    return null;
+}
+/**
+ * Below this many indexed files, reading a file costs less than a graph query
+ * (measured: in a 2-file repo a nudged agent spent an extra turn on Compass and
+ * still read the file), so the nudge stays silent.
+ */
+export const NUDGE_MIN_INDEXED_FILES = 40;
 /** 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. */
@@ -160,10 +217,21 @@ export function compassNudge(args, now = Date.now()) {
         if (args.event !== "PostToolUse")
             return null;
         const payload = args.payload ?? {};
-        const tool = usable(args.toolName) ?? usable(payload.tool_name);
+        let tool = usable(args.toolName) ?? usable(payload.tool_name);
         if (!tool || !NUDGE_TOOLS.has(tool))
             return null;
-        const input = (payload.tool_input ?? payload.toolInput ?? payload);
+        const indexed = readIndexStats(args.projectPath);
+        if (indexed && indexed.files < NUDGE_MIN_INDEXED_FILES)
+            return null;
+        let input = (payload.tool_input ?? payload.toolInput ?? payload);
+        if (tool === "Bash") {
+            const command = usable(input.command);
+            const read = command ? bashCodeRead(args.projectPath, command) : null;
+            if (!read)
+                return null;
+            tool = read.tool;
+            input = { path: read.raw, ...(read.pattern ? { pattern: read.pattern } : {}) };
+        }
         // 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);

package/dist/modules/foundation/doctor.js

@@ -724,7 +724,7 @@ function ceremonyChecks(projectPath) {
             id: "cfg.ceremony.cuts",
             title: "ceremony thresholds",
             status: "warn",
-            detail: "invalid ceremony.cuts — using built-in defaults [3, 8, 15]",
+            detail: "invalid ceremony.cuts — using built-in defaults [5, 16, 25]",
             remedy: "fix cuts in lawbook/config.yaml so they are strictly increasing, or remove the block",
         });
     }

package/dist/modules/foundation/hooks.js

@@ -48,9 +48,9 @@ export const REINDEX_FILE_COMMAND = speclawCommand("reindex-file");
 export const SHIP_ON_STOP_MARKER = "speclaw ship-on-stop";
 /**
  * The POSIX `sh` command the `Stop` hook runs: when the agent finishes a turn
- * with new changes on a feature branch, speclaw records the change, runs the
- * gates once, writes the report from their real output, and archives level-0
- * work — with no agent turn. Guarded on `lawbook/` instead of the index. Its
+ * with new changes on a feature branch, speclaw sizes the change from its diff,
+ * returns the artifacts that level owes, runs the gates once, writes the report
+ * from their real output, and archives level-0 work — with no agent turn. Guarded on `lawbook/` instead of the index. Its
  * stderr is kept so a failing gate reaches the agent (exit 2).
  */
 export const SHIP_ON_STOP_COMMAND = speclawCommand("ship-on-stop");
@@ -98,6 +98,7 @@ const SPECLAW_HOOK_INPUT = {
             pattern: "${tool_input.pattern}",
             glob: "${tool_input.glob}",
             type: "${tool_input.type}",
+            command: "${tool_input.command}",
         },
     },
 };
@@ -109,6 +110,15 @@ const SPECLAW_HOOK = {
     timeout: 5,
     input: SPECLAW_HOOK_INPUT,
 };
+/**
+ * The documentation-hint hook: `speclaw_check` with `speclaw_hint: "doc"`, so
+ * an edit tells the agent what its change's level owes while it still works,
+ * without evaluating any law.
+ */
+const DOC_HINT_HOOK = {
+    ...SPECLAW_HOOK,
+    input: { ...SPECLAW_HOOK_INPUT, payload: { ...SPECLAW_HOOK_INPUT.payload, speclaw_hint: "doc" } },
+};
 /** Tool-name matcher for the file-mutating tools the `path` backend can evaluate. */
 const MUTATION_MATCHER = "Write|Edit|MultiEdit|NotebookEdit";
 /**
@@ -116,7 +126,7 @@ const MUTATION_MATCHER = "Write|Edit|MultiEdit|NotebookEdit";
  * 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";
+export const NUDGE_MATCHER = "Read|Grep|Glob|Bash";
 /**
  * True when a hook object is one speclaw owns (safe to replace on merge): an
  * `mcp_tool` hook on the `speclaw` server, or a `command` hook whose command
@@ -142,9 +152,10 @@ export 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). Two groups are always emitted, even with no
- * laws: one `PostToolUse` group matching `Read|Grep|Glob` for the Compass-first
- * nudge, a separate `PostToolUse` group matching the mutating tools whose
+ * (the context-coverage audit). Groups always emitted, even with no laws: one
+ * `PostToolUse` group matching `Read|Grep|Glob|Bash` for the Compass-first
+ * nudge (Bash also carries the documentation hint), one matching the mutating
+ * tools for the documentation hint, a separate `PostToolUse` group matching the mutating tools whose
  * `command` hook re-indexes the edited file in the background, and one
  * `SessionStart` group whose `command` hook refreshes the index silently when a
  * session starts. A law whose scope contains a malformed glob is
@@ -174,6 +185,8 @@ export function compileHooks(manifest) {
     byEvent.PostToolUse = [{ matcher: NUDGE_MATCHER, hooks: [{ ...SPECLAW_HOOK }] }];
     if (hasFeedback)
         byEvent.PostToolUse.unshift({ matcher: MUTATION_MATCHER, hooks: [{ ...SPECLAW_HOOK }] });
+    // Always present: edits learn what their change's level owes in the same turn.
+    byEvent.PostToolUse.push({ matcher: MUTATION_MATCHER, hooks: [{ ...DOC_HINT_HOOK }] });
     // Covers: req~edit-reindex-hook~1
     // Its own group, never folded into the feedback `mcp_tool` group, and only
     // the keys the agent's hook schema defines (no `async`).

package/dist/modules/foundation/register-core.js

@@ -3,7 +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 { checkAction } from "./check.js";
+import { checkAction, wantsDocHint, withHint } from "./check.js";
 import { handleSpeclawSetup, speclawSetupSchema } from "./setup-tool.js";
 function makeAdd(server, minimal) {
     return (name, description, inputSchema, handler) => {
@@ -19,13 +19,22 @@ function makeAdd(server, minimal) {
 export function registerFoundationCore(server, opts = {}) {
     const minimal = Boolean(opts.minimal);
     const add = makeAdd(server, minimal);
-    add("speclaw_setup", "Project setup: init questionnaire, configure agent, list or add packs.", speclawSetupSchema, async (args) => text(handleSpeclawSetup(args)));
+    add("speclaw_setup", "Use to install or reconfigure speclaw: init questionnaire, configure an agent, list or add packs.", speclawSetupSchema, async (args) => text(handleSpeclawSetup(args)));
     add("speclaw_check", "Invoked by speclaw's hooks to enforce laws — do not call directly.", {
         projectPath: z.string(),
         event: z.enum(["PreToolUse", "PostToolUse", "Stop", "InstructionsLoaded"]),
         toolName: z.string().optional(),
         payload: z.record(z.unknown()),
-    }, async ({ projectPath, event, toolName, payload }) => text(checkAction({ projectPath, event: event, toolName, payload })));
+    }, async ({ projectPath, event, toolName, payload }) => {
+        const args = { projectPath, event: event, toolName, payload };
+        const result = checkAction(args);
+        if (!wantsDocHint(args))
+            return text(result);
+        // Loaded here, not in checkAction: the hint measures the diff with the index.
+        const { docHint } = await import("../lawbook/ship.js");
+        const hint = docHint(projectPath);
+        return text(hint ? withHint(result, hint) : result);
+    });
     if (minimal || !aliasesEnabled())
         return;
     defineAliasTool(server, {

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

@@ -8,18 +8,18 @@ description: Cortex — One brain. Many agents. The standard way to build any ch
 One brain does the critical path; mechanical work costs no agent turns.
 
 1. Branch `<type>/<slug>` (the slug is the change name).
-2. Locate with Compass (`compass_find` / `compass_explore`). Do not read
-   LAWS.md, config, standards, or `--help` to learn the process — this is it.
-3. Implement the change and its test yourself; ask the human only when blocked.
-4. Run the tests once.
-5. Stop. In Claude Code the `Stop` hook (`speclaw ship-on-stop`) records the
-   change, runs the gates once, writes the report from real output, and
-   archives level-0 work; a failing gate comes back to you. Do not run ship,
-   check the hook, or edit its output. Agents without hooks run `speclaw ship
-   <change> --summary "<what and why>"` once, last.
+2. Locate with `compass_find`, read with `compass_explore` (`include:
+   ["source"]`), not cat/grep. No LAWS.md, config, or `--help`.
+3. Public-API or multi-module work: `draft` skill first.
+4. Implement the change and its test yourself; ask only when blocked.
+5. Run the tests once; commit with a body that says why.
+6. Stop. The `Stop` hook sizes the change from its diff and lists what its
+   level owes in `lawbook/changes/<change>/` (why, checked tasks, delta spec,
+   proposal, design). Write just that and stop again: gates run once, level 0
+   archives. Never run ship or edit its report. Without hooks: `speclaw ship <change> --summary "<why>"`, last.
 
-Never drive the harness by hand, write proposal/design/reports for small work,
-or post status updates. Review happens on the PR and never blocks you.
+Never drive the harness by hand or post status updates. Review happens on the
+PR and never blocks you.
 
 Only when the work splits into three or more large, independent parts, read
 `steps/01-load-or-start.md` (fan-out lane: parallel agents, never a chain).

package/dist/modules/lawbook/assets/skills/quick/steps/02-implement.md

@@ -1,6 +1,7 @@
 # Implement and evidence
 
-Make the fix, tick every `- [ ]` in `record.md`, and write at least one
+Locate and read the code with `compass_find` / `compass_explore` (include
+`source`), not cat/grep. Make the fix, tick every `- [ ]` in `record.md`, and write at least one
 discipline report under `reports/`. Archive with `lawbook_change` (action: archive) (no sync at
 level 0). Promote via `lawbook_change` (action: level, mode: promote) if scope grew.
 

package/dist/modules/lawbook/assets/skills/test/steps/01-quality-gates.md

@@ -5,6 +5,8 @@ Run the repo's gates from `docs/standards/testing-standards.md`:
 - Tests: `{{test_commands}}`
 - Lint / type-check: `{{lint_commands}}`
 
-Run them yourself and report real output. A red gate blocks completion.
+Call `compass_diff_context` first: it lists the tests that cover the diff, so a
+failure points at the right suite instead of a re-read of the code. Then run
+the gates yourself and report real output. A red gate blocks completion.
 
 Next: read `steps/02-manual-verification.md` and do only what it says.