@esneiderbravo/speclaw 2.0.3 → 2.0.5

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/foundation/integrity.js

@@ -9,7 +9,9 @@ import { digestText, discoverIntegrityPaths, integrityPolicy, isRegenerableIdeMi
 import { loadScanSuppressions, scanPaths } from "./scan.js";
 /**
  * Verify digests and/or scan rule files. Missing lockfile is soft (ok=true)
- * with guidance to run `speclaw laws lock`.
+ * with guidance to run `speclaw laws lock`. Lock entries for regenerable IDE
+ * mirrors (files or the `.claude/rules/speclaw` symlink) that are missing or
+ * retargeted only warn; other managed symlinks fail strictly.
  */
 export function verifyIntegrity(opts) {
     const projectPath = opts.projectPath;
@@ -174,6 +176,11 @@ export function verifyIntegrity(opts) {
             catch {
                 actual = null;
             }
+            // Entries for regenerable mirror links come from locks written before
+            // they stopped being pinned; the link targets gitignored `ai-specs/` and
+            // is absent or dangling on clean clones, so it warns only and never
+            // fails CI.
+            const regenerable = isRegenerableIdeMirror(rel);
             if (actual === null) {
                 symlinks.push({
                     path: rel,
@@ -181,13 +188,16 @@ export function verifyIntegrity(opts) {
                     actualTarget: null,
                     status: "missing",
                 });
-                ok = false;
+                if (!regenerable)
+                    ok = false;
                 verifyFindings.push({
                     lawId: "integrity~symlink~1",
-                    severity: "error",
+                    severity: regenerable ? "warn" : "error",
                     engine: "integrity",
                     file: rel,
-                    message: `Managed symlink missing (expected → ${entry.target})`,
+                    message: regenerable
+                        ? "Regenerable IDE mirror symlink missing — run `speclaw update` or `speclaw laws lock` to drop the stale entry"
+                        : `Managed symlink missing (expected → ${entry.target})`,
                 });
             }
             else if (normalizeLink(actual) !== normalizeLink(entry.target)) {
@@ -197,13 +207,16 @@ export function verifyIntegrity(opts) {
                     actualTarget: actual,
                     status: "mismatch",
                 });
-                ok = false;
+                if (!regenerable)
+                    ok = false;
                 verifyFindings.push({
                     lawId: "integrity~symlink~1",
-                    severity: "error",
+                    severity: regenerable ? "warn" : "error",
                     engine: "integrity",
                     file: rel,
-                    message: `Managed symlink retargeted`,
+                    message: regenerable
+                        ? "Regenerable IDE mirror symlink retargeted — run `speclaw update` or `speclaw laws lock` to drop the stale entry"
+                        : `Managed symlink retargeted`,
                     detail: `expected ${entry.target} found ${actual}`,
                 });
             }

package/dist/modules/foundation/lock.js

@@ -106,13 +106,13 @@ export function buildLock(opts) {
 /** Integrity severity policy for a project-relative path. */
 export function integrityPolicy(relPath) {
     const n = relPath.split("\\").join("/");
-    // `.cursor/rules/` mirrors regenerable `ai-specs/` (gitignored) — lock/CI must
-    // not treat them as strict committed files; scan when present, never pin.
+    // Regenerable IDE mirrors of gitignored `ai-specs/` (`.cursor/rules/`, the
+    // `.claude/rules/speclaw` link) fall through to scan-only: lock/CI must not
+    // treat them as strict committed files; scan when present, never pin.
     if (n === "AGENTS.md" ||
         n === "CLAUDE.md" ||
         n.startsWith(".github/instructions/") ||
-        n === ".coderabbit.yaml" ||
-        n === ".claude/rules/speclaw") {
+        n === ".coderabbit.yaml") {
         return "strict";
     }
     if (n === "LAWS.md" || n === "docs/compass.md" || n.startsWith("docs/standards/")) {
@@ -120,10 +120,22 @@ export function integrityPolicy(relPath) {
     }
     return "scan-only";
 }
-/** True when a path is an IDE mirror of regenerable (typically gitignored) content. */
+/**
+ * True when a path is an IDE mirror of regenerable (typically gitignored) content.
+ *
+ * Covers the `.claude/rules/speclaw` symlink as well as mirror files: the link
+ * targets gitignored `ai-specs/rules`, so on a clean clone it is absent (when
+ * the project ignores it) or dangling, and must never be pinned in, or fail
+ * verify against, the lock.
+ *
+ * @param relPath - Project-relative path (file or symlink).
+ * @returns Whether lock/verify should treat the path as regenerable.
+ */
 export function isRegenerableIdeMirror(relPath) {
     const n = relPath.split("\\").join("/");
-    return (n.startsWith(".cursor/rules/") ||
+    return (n === ".claude/rules/speclaw" ||
+        n.startsWith(".claude/rules/speclaw/") ||
+        n.startsWith(".cursor/rules/") ||
         n.startsWith(".cursor/skills/") ||
         n.startsWith(".cursor/commands/") ||
         n.startsWith(".claude/skills/") ||
@@ -226,6 +238,8 @@ export function prepareIntegrityText(relPath, raw) {
  * Snapshot digests for discovered files with ownership policy.
  * For `.coderabbit.yaml`, digests only the speclaw delimited block when present.
  * For `docs/compass.md`, digests with the regenerable map body stripped.
+ * Regenerable IDE mirror symlinks ({@link isRegenerableIdeMirror}) are never
+ * pinned, so the lock is identical with or without the local link.
  */
 export function snapshotLockEntries(projectPath) {
     const { files: paths, symlinks } = discoverIntegrityPaths(projectPath);
@@ -239,8 +253,11 @@ export function snapshotLockEntries(projectPath) {
         files[rel] = { digest: digestText(raw), ownership };
     }
     const symlinkMap = {};
-    for (const s of symlinks)
+    for (const s of symlinks) {
+        if (isRegenerableIdeMirror(s.path))
+            continue;
         symlinkMap[s.path] = { target: s.target };
+    }
     return { files, symlinks: symlinkMap };
 }
 /** Extract a speclaw-marked region from coderabbit yaml if present. */

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.