@esneiderbravo/speclaw 2.0.3 → 2.0.4

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

package/dist/modules/lawbook/assets/rules/spec-tasks-mandatory-steps.md

@@ -27,8 +27,8 @@ steps, branch convention, and testing/documentation requirements.
   see the `spec-reports-disciplines` rule) with the unit/integration/e2e results
   for what the feature touched.
 - Update the technical documentation the change touches.
-- Archive the change within the same PR (the `archive` command / `lawbook_archive`
-  tool) after Cortex review/test PASS.
+- Archive the change within the same PR (the `archive` command / `lawbook_change`
+  action `archive`) after Cortex review/test PASS.
 
 ## 3. Manual verification — the tester must execute it
 
@@ -38,10 +38,10 @@ requires verification is not complete until the tester has verified it.
 
 ## 4. Archiving is part of the change
 
-A change is not done until it is archived with `lawbook_archive` (never a manual
+A change is not done until it is archived with `lawbook_change` action `archive` (never a manual
 `mv`). The archive lands in the same PR that implements the change.
 
-`lawbook_archive` is gated: it refuses to archive while any task is unchecked,
+Archive (`lawbook_change` action `archive`) is gated: it refuses to archive while any task is unchecked,
 while `reports/` has no discipline report, while the delta specs are not yet
 synced into the canonical specs, or while harness review/test verdicts are not
 PASS. Resolve those first — the gate is enforced in the engine, so a manual `mv`

package/dist/modules/lawbook/assets/skills/archive/steps/02-reconcile.md

@@ -1,7 +1,7 @@
 # Reconciliation review (agent-executed)
 
 Run the reconciliation from the `sync` skill: reconstruct what was built
-(branch diff since draft + `compass_explore` / `compass_impact`) and compare it
+(branch diff since draft + `compass_explore` with include `blast_radius`) and compare it
 to the change's delta specs.
 
 - **If the code drifted past the contracts:** show short insights — a tight

package/dist/modules/lawbook/assets/skills/build/steps/01-load-change.md

@@ -1,7 +1,7 @@
 # Load the change
 
 - Read `lawbook/changes/<name>/proposal.md`, `tasks.md`, and the delta specs under
-  `specs/`. If unsure which change, run `lawbook_list`.
+  `specs/`. If unsure which change, run `lawbook_change` (action: list).
 - Read the governing standards in `docs/standards/` for the areas you'll touch.
 
 Next: read `steps/02-branch.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/cortex/steps/02-dispatch-loop.md

@@ -3,10 +3,26 @@
 For the current Cortex stage (`cortex` action `brief` or `status`):
 
 1. Dispatch (spawn or adopt) the matching role with a clear handoff brief.
-   When the role is the planner, paste the explorer brief into the prompt
-   unchanged: symbols with files, callers and callees, blast radius, standards
-   already read, recommended approach, open questions, and gaps.
-2. On role completion, call the matching Cortex op:
+   - **Explorer template.** Give the intent (what the change should achieve),
+     the symbols or concepts to locate, and the questions to answer. Do not
+     list file paths for the explorer to read — it locates code through
+     Compass (`compass_find` / `compass_explore`) and reports
+     `Compass calls made: N`.
+   - When the role is the planner, paste the explorer brief into the prompt
+     unchanged: symbols with files, callers and callees, blast radius,
+     standards already read, recommended approach, open questions, and gaps.
+2. **Single question round** (after the explorer, before the planner drafts):
+   1. Propose a level with `lawbook_change` action `level`, mode `propose`,
+      passing the paths and symbols from the brief.
+   2. Dispatch the planner for questions only (no artifacts yet).
+   3. Merge the explorer open questions, the planner questions, and the level
+      confirmation into **one** `advance` with `pauseForQuestions` +
+      `openQuestions`. Ask the human once; never open a second round for the
+      level.
+   4. After the answers, record the level with `lawbook_change` action
+      `level`, mode `set` (evidence and answers in `reason`), then redispatch
+      the planner to draft.
+3. On role completion, call the matching Cortex op:
    - exploring → `advance`
    - planning with questions → `advance` + `pauseForQuestions` + `openQuestions`
    - questions after human answers → `advance` (back to planning)
@@ -15,8 +31,8 @@ For the current Cortex stage (`cortex` action `brief` or `status`):
    - reviewing PASS → `advance` + `verdict: PASS`; FAIL → `rework` + `verdict: FAIL`
    - testing PASS → `advance` + `verdict: PASS`; FAIL → `rework` + `verdict: FAIL`
    - archiving success → `advance` (to done)
-3. Max rework is 3; if the engine rejects further rework, **ask the human**.
-4. Coordinator never edits `src/`, never archives, never pushes, never runs
+4. Max rework is 3; if the engine rejects further rework, **ask the human**.
+5. Coordinator never edits `src/`, never archives, never pushes, never runs
    `laws accept`.
 
 Next: read `steps/03-complete.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/draft/steps/01-ensure-workspace.md

@@ -1,5 +1,5 @@
 # Ensure the workspace exists
 
-If `lawbook/` is missing, run the `lawbook_init` tool once to create it.
+If `lawbook/` is missing, run `lawbook_change` (action: init) once to create it.
 
 Next: read `steps/02-understand.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/draft/steps/02-understand.md

@@ -10,9 +10,12 @@
   concept) before grep/read to locate the code and its blast radius. Read the
   governing standards in `docs/standards/`.
 - Clarify what the user wants (feature / fix / refactor) and confirm scope.
-- **Propose a ceremony level** with `lawbook_level` (mode `propose`) using the
-  paths and symbols from the brief or from that locate pass; **confirm with the
-  human** (mode `set`) before writing artifacts. For an obvious one-liner,
-  offer `speclaw quick` instead.
+- When `change.json` already has a `confirmedLevel` (the coordinator recorded
+  it in the single question round), use that level and skip the separate level
+  confirmation.
+- Otherwise **propose a ceremony level** with `lawbook_change` action `level`
+  (mode `propose`) using the paths and symbols from the brief or from that
+  locate pass; **confirm with the human** (mode `set`) before writing
+  artifacts. For an obvious one-liner, offer `speclaw quick` instead.
 
 Next: read `steps/03-name-capabilities.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/draft/steps/03-name-capabilities.md

@@ -3,12 +3,14 @@
 - **Change name:** kebab-case, action-oriented (e.g. `add-login`,
   `fix-shift-overlap`). This is the folder under `lawbook/changes/`, and it is
   per-feature — always distinct.
-- **Capabilities:** run `lawbook_list` to see the canonical capabilities. A
+- **Capabilities:** run `lawbook_change` (action: list) to see the canonical capabilities. A
   capability is the living contract for an area of behavior — it is *not* the
   change. When your change modifies behavior an existing capability already
   governs, reuse that capability's **exact** name so `sync` updates its spec.
   Introduce a new capability only as a deliberate choice for a genuinely distinct
   area of behavior — never as a near-duplicate (`transfer` next to an existing
   `transfers`) of one that already exists.
+- Pass that exact capability name to the scaffold (`--capability` /
+  `capability`), so the delta stub lands in the right capability.
 
 Next: read `steps/04-write-artifacts.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/draft/steps/04-write-artifacts.md

@@ -1,8 +1,18 @@
 # Write the artifacts
 
 Artifact volume follows the **confirmed ceremony level** in `change.json`
-(propose + confirm with `lawbook_level` / the human **before** scaffolding).
-Missing `change.json` means level 3.
+(propose + confirm with `lawbook_change` action `level` / the human **before**
+scaffolding). Missing `change.json` means level 3.
+
+Scaffold with `speclaw lawbook draft <name> --level N --capability <capability>`
+(or `lawbook_change` action `draft` with `change`, `level`, and `capability`),
+passing the exact capability name chosen in the previous step. It creates
+`change.json`, `reports/README.md`, and the level's stub artifacts; fill them
+in. When the capability is new, the delta stub is a marked placeholder:
+replace it with the real spec and remove the
+`<!-- speclaw:placeholder-delta -->` marker (validate warns and sync refuses
+while it remains). For each further capability, add its delta by hand, and
+delete any stub delta the change does not use.
 
 Create under `lawbook/changes/<name>/` only what the level needs:
 

package/dist/modules/lawbook/assets/skills/explore/steps/01-investigate.md

@@ -1,11 +1,20 @@
 # Investigate
 
-- **Refresh the index first.** Run `compass_index` before investigating — it is
-  incremental (unchanged files skipped by hash), so it is cheap and keeps your
-  reasoning on the current graph rather than a stale one.
-- **Understand the code first.** Use `compass_find` (mode: concept) to find relevant code by
-  meaning and `compass_explore` to read a symbol's source plus its callers and
-  callees — before grep/read.
+- **Locate through Compass first.** Your first code-locating call is
+  `compass_find` (mode: concept for an idea, exact for a name) or
+  `compass_explore <symbol>` to read a symbol's source plus its callers and
+  callees. Use `compass_diff_context` when the question is about a diff.
+- **Index only when needed.** Run `compass_index` only when `compass_find`
+  returns nothing or reports a missing or stale index, then retry the find. It
+  is incremental (unchanged files skipped by hash).
+- **Read/Grep code only with a named reason.** Before any Read/Grep/Glob of
+  indexed source code, name which Rule 1 fallback holds: (1) a Compass call ran
+  and returned nothing useful for the query, (2) the graph is missing and
+  `compass_index` cannot build it, or (3) the target is not indexed code
+  (markdown, JSON/config, stylesheets, logs, generated files, lockfiles).
+  "I know which file it is" is not a reason — `compass_explore` takes a path.
+- **Count your Compass calls.** Keep a tally of `compass_explore`,
+  `compass_find`, and `compass_diff_context` calls for the brief.
 - **Ask sharp questions** to surface hidden assumptions, constraints, and edge
   cases. Confirm scope and non-goals.
 - **Check the law.** Read the relevant `docs/standards/` so any direction you

package/dist/modules/lawbook/assets/skills/explore/steps/02-summarize.md

@@ -9,6 +9,8 @@ Produce a brief the planner can use as the code map. Include only these fields:
 - recommended approach
 - open questions
 - gaps: the phrase "nothing unresolved", or each symbol that is still unresolved
+- `Compass calls made: N` — the count of `compass_explore`, `compass_find`, and
+  `compass_diff_context` calls (and their aliases) you made
 
 When the direction is clear, offer to `draft` the change.
 

package/dist/modules/lawbook/assets/skills/investigate/steps/02-hand-off.md

@@ -1,6 +1,6 @@
 # Hand off to draft
 
-- **`compass_impact`** on the confirmed root cause for blast radius.
+- **`compass_explore`** (include `blast_radius`) on the confirmed root cause.
 - **`speclaw lawbook draft --bug <name>`** — pre-seed only; fill repro, fix, regression test, prevention.
 
 Treat the ranking as **evidence**, not a verdict. No further steps remain — investigate workflow complete.

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

@@ -2,6 +2,6 @@
 
 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_level` if scope grew.
+level 0). Promote via `lawbook_change` (action: level, mode: promote) if scope grew.
 
 No further steps — workflow complete.

package/dist/modules/lawbook/assets/skills/sync/steps/01-confirm.md

@@ -1,5 +1,5 @@
 # Confirm which change to sync
 
-Confirm which change to sync (run `lawbook_list` if unsure).
+Confirm which change to sync (run `lawbook_change` (action: list) if unsure).
 
 Next: read `steps/02-reconcile.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/sync/steps/02-reconcile.md

@@ -3,7 +3,7 @@
 Before promoting, compare what was built against the change's delta specs:
 
 - Reconstruct what shipped: `git diff <branch-point>...HEAD` for the change's
-  branch, then `compass_explore` / `compass_impact` on the touched symbols to
+  branch, then `compass_explore` (include `blast_radius`) on the touched symbols to
   understand behavior, not just changed lines.
 - Diff intent vs reality: list behavior that is implemented but missing from,
   or contradicted by, `lawbook/changes/<name>/specs/**`.