@esneiderbravo/speclaw 0.3.11 → 0.3.13

package/dist/cli/commands/lawbook.js

@@ -1,11 +1,15 @@
 import { specInit, specValidate, specSync, specArchive, specList, } from "../../modules/lawbook/engine.js";
+import { handleLevel } from "../../modules/lawbook/quick.js";
+import { scaffoldBugfix } from "../../modules/lawbook/bugfix.js";
+import { investigate, formatInvestigateResult } from "../../modules/lawbook/investigate.js";
+import { list } from "../lib/args.js";
 import { ui } from "../lib/ui.js";
 function today() {
     // The MCP path passes the date in; the CLL runs on a real machine, so read it here.
     return new Date().toISOString().slice(0, 10);
 }
 /**
- * Run a spec-workflow subcommand: init, list, validate, sync, or archive.
+ * Run a spec-workflow subcommand: init, list, validate, sync, archive, or level.
  *
  * @param flags - Parsed flags; `_[0]` is the subcommand and `_[1]` the change name where required.
  * @throws Exits the process with code 1 on unknown subcommands, missing arguments, or engine errors.
@@ -27,13 +31,48 @@ export async function runSpec(flags) {
                 if (!r.initialized)
                     return ui.warn("No lawbook/ — run `speclaw lawbook init`.");
                 ui.heading("Lawbook workspace");
-                ui.info(`active changes: ${r.activeChanges.join(", ") || "none"}`);
+                if (r.activeChanges.length === 0)
+                    ui.info("active changes: none");
+                else {
+                    ui.info("active changes:");
+                    for (const name of r.activeChanges) {
+                        const lvl = r.activeLevels[name] ?? 3;
+                        ui.info(`  ${name}  (level ${lvl})`);
+                    }
+                }
                 ui.info(`archived: ${r.archivedChanges.join(", ") || "none"}`);
                 ui.info(`capabilities: ${r.capabilities.join(", ") || "none"}`);
                 return;
             }
+            case "level": {
+                const modeRaw = change ?? "propose";
+                const mode = modeRaw;
+                if (!["propose", "set", "promote", "explain"].includes(mode)) {
+                    ui.err("Usage: speclaw lawbook level <propose|set|promote|explain> [--change <c>] [--path …] [--level N] [--reason …] [--json]");
+                    process.exit(1);
+                }
+                const levelFlag = flags.level;
+                const level = levelFlag === undefined || levelFlag === true
+                    ? undefined
+                    : Number(levelFlag);
+                const result = handleLevel({
+                    projectPath: cwd,
+                    mode,
+                    change: typeof flags.change === "string" ? flags.change : flags._[2],
+                    paths: list(flags.path),
+                    symbols: list(flags.symbol),
+                    level,
+                    reason: typeof flags.reason === "string" ? flags.reason : undefined,
+                });
+                if (flags.json) {
+                    console.log(JSON.stringify(result, null, 2));
+                    return;
+                }
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
             case "validate": {
-                const r = specValidate(cwd, req(change, "spec validate <change>"));
+                const r = specValidate(cwd, req(change, "lawbook validate <change>"));
                 if (r.valid)
                     ui.ok(`${r.change} is valid (${r.deltaSpecs.length} delta spec(s))`);
                 else {
@@ -47,13 +86,52 @@ export async function runSpec(flags) {
                 return;
             }
             case "sync": {
-                const r = specSync(cwd, req(change, "spec sync <change>"));
+                const r = specSync(cwd, req(change, "lawbook sync <change>"));
                 ui.ok(`promoted ${r.promoted.length} spec(s)`);
                 r.promoted.forEach((p) => ui.info(`${r.created.includes(p) ? "created" : "updated"}: ${p}`));
                 return;
             }
+            case "investigate": {
+                const stackTrace = typeof flags["stack-trace"] === "string"
+                    ? flags["stack-trace"]
+                    : typeof flags.stackTrace === "string"
+                        ? flags.stackTrace
+                        : undefined;
+                const symptom = typeof flags.symptom === "string" ? flags.symptom : undefined;
+                const result = await investigate({
+                    projectPath: cwd,
+                    stackTrace,
+                    symptom,
+                    hintPaths: list(flags.path),
+                    maxSuspects: flags.max !== undefined && flags.max !== true ? Number(flags.max) : undefined,
+                });
+                if (flags.json) {
+                    console.log(formatInvestigateResult(result));
+                    return;
+                }
+                console.log(formatInvestigateResult(result));
+                return;
+            }
+            case "draft": {
+                if (!flags.bug) {
+                    ui.err("Usage: speclaw lawbook draft --bug <name> [--level N] [--json]");
+                    process.exit(1);
+                }
+                const name = typeof flags.bug === "string" ? flags.bug : req(change, "lawbook draft --bug <name>");
+                const levelFlag = flags.level;
+                const level = levelFlag === undefined || levelFlag === true
+                    ? undefined
+                    : Number(levelFlag);
+                const result = scaffoldBugfix(cwd, name, { level });
+                if (flags.json) {
+                    console.log(JSON.stringify(result, null, 2));
+                    return;
+                }
+                ui.ok(`bug change "${name}" scaffolded at ${result.dir}`);
+                return;
+            }
             case "archive": {
-                const r = specArchive(cwd, req(change, "spec archive <change>"), today());
+                const r = specArchive(cwd, req(change, "lawbook archive <change>"), today());
                 ui.ok(`archived to ${r.archivedTo} (${r.promoted.length} spec(s) promoted)`);
                 r.promoted.forEach((p) => ui.info(`${r.created.includes(p) ? "created" : "updated"}: ${p}`));
                 for (const s of r.seals) {
@@ -66,7 +144,7 @@ export async function runSpec(flags) {
                 return;
             }
             default:
-                ui.err("Usage: speclaw lawbook <init|list|validate|sync|archive> [change]");
+                ui.err("Usage: speclaw lawbook <init|list|validate|sync|archive|level|draft|investigate> [change]");
                 process.exit(1);
         }
     }

package/dist/cli/commands/quick.js

@@ -0,0 +1,35 @@
+import { list } from "../lib/args.js";
+import { ui } from "../lib/ui.js";
+import { scaffoldQuick } from "../../modules/lawbook/quick.js";
+/**
+ * Scaffold a level-0 change (`speclaw quick <name>`).
+ *
+ * @param flags - `_[0]` is the change name; optional `--path` / `--symbol` / `--json`.
+ */
+export async function runQuick(flags) {
+    const cwd = process.cwd();
+    const name = flags._[0];
+    if (!name || typeof name !== "string") {
+        ui.err("Usage: speclaw quick <name> [--path <file>] [--symbol <sym>] [--json]");
+        process.exit(1);
+    }
+    try {
+        const result = scaffoldQuick(cwd, name, {
+            paths: list(flags.path),
+            symbols: list(flags.symbol),
+        });
+        if (flags.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        ui.ok(`level-0 change ${ui.code(result.change)} at ${result.dir}`);
+        ui.info(result.proposal.rationale);
+        if (result.proposal.level !== null && result.proposal.level > 0) {
+            ui.warn(`measured proposal was level ${result.proposal.level} — promote if the fix grows`);
+        }
+    }
+    catch (err) {
+        ui.err(err.message);
+        process.exit(1);
+    }
+}

package/dist/cli/commands/update.js

@@ -125,6 +125,24 @@ const MIGRATIONS = [
             "(`node_metrics`) — reindex with `speclaw index`. Default history window is 90 days.\n" +
             "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
     },
+    {
+        version: "0.3.12",
+        describe: "Adaptive ceremony levels 0–3, speclaw quick, lawbook_level",
+        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 / " +
+            "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.",
+    },
+    {
+        version: "0.3.13",
+        describe: "Bugfix specs — draft --bug, bugfix.md, lawbook_investigate",
+        agentPrompt: "- Mention bug changes: `speclaw lawbook draft --bug`, `bugfix.md` (repro + regression + prevention), " +
+            "and `lawbook_investigate` / the investigate skill for graph-backed RCA. Feature ceremony unchanged; " +
+            "`changeType: bug` in `change.json`. Security-withheld mode is not in this release.\n" +
+            "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
+    },
 ];
 /**
  * Update speclaw and bring the current project up to date without a full re-init:

package/dist/cli/index.js

@@ -31,8 +31,12 @@ Compass (code intelligence — the same surface agents use via MCP)
   visualize [node]         Interactive HTML graph → .speclaw/graph.html
 
 Lawbook (spec-driven workflow)
+  quick <name>             Scaffold a level-0 change (record.md + reports)
   lawbook init             Create the lawbook/ workspace
   lawbook list             Active/archived changes and capabilities
+  lawbook level <mode>     Propose/set/promote/explain ceremony level (--json)
+  lawbook draft --bug <c>  Scaffold a bug change (bugfix.md + reports)
+  lawbook investigate      Rank bug suspects from graph (--symptom / --stack-trace, --json)
   lawbook validate <c>     Validate a change's artifacts
   lawbook sync <c>         Promote delta specs to canonical
   lawbook archive <c>      Finalize and archive a change
@@ -54,7 +58,8 @@ Other
 // interactive, human-facing commands whose stdout is prose. Deliberately
 // excluded: `version`/`--version`/`-v` (bare scriptable value), the Compass
 // query family (`explore`/`search`/`recall`/`impact`/`trace`/`affected-tests`/
-// `hotspots`/`coupling`, machine-consumed output), `mcp` (a long-running stdio
+// `hotspots`/`coupling`, machine-consumed output), `quick` (often --json),
+// `mcp` (a long-running stdio
 // server), and `init` (already opens with the fuller `banner()`).
 const HEADER_COMMANDS = new Set([
     undefined,
@@ -71,6 +76,7 @@ const HEADER_COMMANDS = new Set([
     "index",
     "watch",
     "lawbook",
+    "quick",
 ]);
 /**
  * Print the branded header once, ahead of a command's output, when it is a
@@ -94,6 +100,14 @@ function maybeHeader(cmd, flags) {
         return;
     if (cmd === "drift" && flags.json)
         return;
+    if (cmd === "quick" && flags.json)
+        return;
+    if (cmd === "lawbook" && flags.json && flags._[0] === "level")
+        return;
+    if (cmd === "lawbook" && flags.json && flags._[0] === "investigate")
+        return;
+    if (cmd === "lawbook" && flags.json && flags._[0] === "draft")
+        return;
     header();
 }
 /** Run the handler for a single command. Returns when the command completes. */
@@ -135,6 +149,8 @@ async function dispatch(cmd, flags) {
             return (await import("./commands/query.js")).runQuery(cmd, flags);
         case "visualize":
             return (await import("./commands/visualize.js")).runVisualize(flags);
+        case "quick":
+            return (await import("./commands/quick.js")).runQuick(flags);
         case "lawbook":
             return (await import("./commands/lawbook.js")).runSpec(flags);
         case "doctor":

package/dist/modules/foundation/doctor.js

@@ -8,6 +8,7 @@ import { pkgName, pkgVersion } from "../../shared/version.js";
 import { indexExists, openDb } from "../compass/db.js";
 import { specList } from "../lawbook/engine.js";
 import { doctorDriftCheck } from "../lawbook/drift.js";
+import { loadCeremonyConfig } from "../lawbook/levels.js";
 import { globError, hasBackend, hasBatchBackend, readLawManifest } from "./laws.js";
 import { redactValue } from "../../shared/redact.js";
 const STATUS_RANK = {
@@ -467,6 +468,98 @@ function specsOrphansCheck(projectPath) {
         remedy: `speclaw lawbook archive ${active[0]}`,
     };
 }
+/** Ceremony config validity + archived level histogram. */
+function ceremonyChecks(projectPath) {
+    const out = [];
+    const { invalidCuts } = loadCeremonyConfig(projectPath);
+    if (invalidCuts) {
+        out.push({
+            id: "cfg.ceremony.cuts",
+            title: "ceremony thresholds",
+            status: "warn",
+            detail: "invalid ceremony.cuts — using built-in defaults [3, 8, 15]",
+            remedy: "fix cuts in lawbook/config.yaml so they are strictly increasing, or remove the block",
+        });
+    }
+    else {
+        out.push({
+            id: "cfg.ceremony.cuts",
+            title: "ceremony thresholds",
+            status: "ok",
+            detail: "ceremony cuts valid (or using defaults)",
+        });
+    }
+    const archiveRoot = path.join(projectPath, "lawbook", "changes", "archive");
+    const counts = { "0": 0, "1": 0, "2": 0, "3": 0, missing: 0 };
+    if (fs.existsSync(archiveRoot)) {
+        for (const name of fs.readdirSync(archiveRoot)) {
+            const dir = path.join(archiveRoot, name);
+            if (!fs.statSync(dir).isDirectory())
+                continue;
+            // archived folder is YYYY-MM-DD-name; change.json lives inside
+            const rec = (() => {
+                try {
+                    const p = path.join(dir, "change.json");
+                    if (!fs.existsSync(p))
+                        return null;
+                    return JSON.parse(fs.readFileSync(p, "utf8"));
+                }
+                catch {
+                    return null;
+                }
+            })();
+            if (!rec || rec.confirmedLevel === undefined) {
+                counts.missing += 1;
+                counts["3"] += 1;
+            }
+            else {
+                counts[String(rec.confirmedLevel)] = (counts[String(rec.confirmedLevel)] ?? 0) + 1;
+            }
+        }
+    }
+    const total = (counts["0"] ?? 0) + (counts["1"] ?? 0) + (counts["2"] ?? 0) + (counts["3"] ?? 0);
+    out.push({
+        id: "cfg.ceremony.levels",
+        title: "ceremony level distribution",
+        status: "ok",
+        value: JSON.stringify(counts),
+        detail: total === 0
+            ? "no archived changes"
+            : `archived levels: 0=${counts["0"]}, 1=${counts["1"]}, 2=${counts["2"]}, 3=${counts["3"]} (missing change.json=${counts.missing})`,
+    });
+    const typeCounts = { feature: 0, bug: 0, unknown: 0 };
+    if (fs.existsSync(archiveRoot)) {
+        for (const name of fs.readdirSync(archiveRoot)) {
+            const dir = path.join(archiveRoot, name);
+            if (!fs.statSync(dir).isDirectory())
+                continue;
+            try {
+                const p = path.join(dir, "change.json");
+                if (!fs.existsSync(p)) {
+                    typeCounts.unknown += 1;
+                    typeCounts.feature += 1;
+                    continue;
+                }
+                const raw = JSON.parse(fs.readFileSync(p, "utf8"));
+                if (raw.changeType === "bug")
+                    typeCounts.bug += 1;
+                else
+                    typeCounts.feature += 1;
+            }
+            catch {
+                typeCounts.unknown += 1;
+            }
+        }
+    }
+    out.push({
+        id: "cfg.ceremony.changeTypes",
+        title: "change type distribution",
+        status: "ok",
+        value: JSON.stringify(typeCounts),
+        detail: `archived types: feature=${typeCounts.feature}, bug=${typeCounts.bug}`,
+    });
+    return out;
+}
 function configurationChecks(projectPath, initialised) {
     if (!initialised) {
         const ids = [
@@ -559,6 +652,7 @@ export async function doctor(projectPath, opts = {}) {
         configuration.push(await budgetCheck(projectPath));
         configuration.push(freshnessCheck(projectPath));
         configuration.push(specsOrphansCheck(projectPath));
+        configuration.push(...ceremonyChecks(projectPath));
         {
             const d = doctorDriftCheck(projectPath);
             addCheck(configuration, {

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

@@ -1,11 +1,10 @@
 ---
-description: Finalize a completed change — sync specs into canonical, then archive it.
+description: Finalize a completed change — sync specs when needed, then archive it.
 ---
 
 Archive the completed change: $ARGUMENTS
 
-Follow the `archive` skill: confirm every task is done and gates are green, run
-the reconciliation review (recommend a sync with short insights if the code
-drifted past the contracts), run `lawbook_validate`, then `lawbook_archive` with
-today's date (YYYY-MM-DD). It syncs the specs and moves the change to
-`lawbook/changes/archive/`. Never move the folder by hand.
+Follow the `archive` skill: confirm every task (or level-0 checklist) is done
+and gates are green, reconcile if the level has delta specs, run
+`lawbook_validate`, then `lawbook_archive` with today's date (YYYY-MM-DD). Sync
+runs only when the ceremony level requires specs. Never move the folder by hand.

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

@@ -1,12 +1,11 @@
 ---
-description: Draft a new spec-driven change (proposal, delta specs, tasks) before coding.
+description: Draft a new spec-driven change at the confirmed ceremony level before coding.
 ---
 
 Draft a new change under `lawbook/changes/<name>/` for: $ARGUMENTS
 
-Follow the `draft` skill: ensure `lawbook/` exists (`lawbook_init`), investigate the
-code with `compass_explore`/`compass_recall`, read the governing
-`docs/standards/`, then write `proposal.md`, `specs/<capability>/spec.md`
-(normative `SHALL`/`MUST` + `#### Scenario:`), `design.md`, and
-`tasks.md` (with the mandatory steps from `lawbook/config.yaml`). Finish by
-running `lawbook_validate` and fixing every issue.
+Follow the `draft` skill: ensure `lawbook/` exists (`lawbook_init`), investigate
+with Compass, propose a ceremony level (`lawbook_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_validate` and fixing every issue.

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

@@ -0,0 +1,7 @@
+---
+description: Investigate a bug — graph-backed suspect ranking before draft --bug.
+---
+
+Investigate: $ARGUMENTS
+
+Follow the `investigate` skill: refresh the index, call `lawbook_investigate`, explore the top suspect, then offer `draft --bug`.

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

@@ -0,0 +1,14 @@
+---
+description: Scaffold a level-0 lawbook change (record.md + reports) for a tiny fix.
+---
+
+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).
+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.
+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

@@ -76,3 +76,11 @@ 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
 archiving; the engine gate counts files but cannot infer the set of concerns a
 change exercised.
+
+## 5. Bug changes must show the regression test failing first
+
+When `changeType` is **bug**, the discipline report MUST include the output of
+the regression test **failing before the fix** (or document why instrumentation
+substitutes for a red-green cycle when reproduction is `unreproducible:`). A test
+that only passes after the fix — with no evidence it ever failed — does not
+satisfy the bug gate.

package/dist/modules/lawbook/assets/skills/archive/steps/03-validate-and-sync.md

@@ -1,7 +1,8 @@
 # Validate and sync
 
-Run `lawbook_validate`, then `lawbook_sync` to promote the delta specs into
-`lawbook/specs/`. This is required, not optional: `lawbook_archive` refuses
-unless the canonical specs already match the delta specs.
+Run `lawbook_validate`. If the confirmed ceremony level requires delta specs
+(levels 1–3), run `lawbook_sync` to promote them into `lawbook/specs/` —
+`lawbook_archive` refuses unless the canonical specs already match. At **level
+0**, skip sync (there are no deltas).
 
 Next: read `steps/04-archive.md` and do only what it says.

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

@@ -1,6 +1,6 @@
 ---
 name: draft
-description: Draft a new spec-driven change — proposal, delta specs, and tasks — before writing any code. Use when the user wants to start, plan, or propose a new feature, fix, or refactor: "draft a change for X", "propose X", "let's plan X", "spec out X", "new change". Part of speclaw's lawbook module (draft → build → sync → archive).
+description: Draft a new spec-driven change — propose a ceremony level, then write only the artifacts that level needs — before writing any code. Use when the user wants to start, plan, or propose a new feature, fix, or refactor: "draft a change for X", "propose X", "let's plan X", "spec out X", "new change". Part of speclaw's lawbook module (draft → build → sync → archive).
 ---
 
 # draft — Draft a new change

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

@@ -6,6 +6,9 @@
 - Clarify what the user wants (feature / fix / refactor) and confirm scope.
 - Use `compass_explore` and `compass_recall` (speclaw's code index) BEFORE
   grep/read to locate the real code the change touches and its blast radius.
+- **Propose a ceremony level** with `lawbook_level` (mode `propose`) using the
+  paths/symbols you found; **confirm with the human** (mode `set`) before
+  writing artifacts. For an obvious one-liner, offer `speclaw quick` instead.
 - Read the governing standards in `docs/standards/` (architecture, backend,
   frontend, testing) so the change complies with the project's law.
 

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

@@ -1,15 +1,26 @@
 # Write the artifacts
 
-Create under `lawbook/changes/<name>/`:
-
-- **proposal.md** — the why, the what, non-goals, and whether migrations are
-  needed. Reference the team's tracker ticket if there is one.
-- **specs/<capability>/spec.md** — the delta spec for each affected capability.
-  `sync` promotes this by overwriting the whole canonical file, so the delta must
-  carry the capability's **full** intended spec. When you are updating an existing
-  capability, **start from the current `lawbook/specs/<capability>/spec.md`** and
-  edit on top of it, so its existing requirements are carried forward — do not
-  author it from scratch, or promotion will silently drop them. Use normative
+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.
+
+Create under `lawbook/changes/<name>/` only what the level needs:
+
+- **Level 0** — prefer `speclaw quick` / the `quick` skill: `record.md`
+  (inline checklist) + `reports/` + `change.json`. No proposal/design/deltas.
+- **Level 1** — `record.md`, `tasks.md`, ≥1 delta under
+  `specs/<capability>/spec.md`, `reports/`, `change.json`.
+- **Level 2** — `proposal.md`, `tasks.md`, delta specs, `reports/`;
+  `design.md` optional only with justification in `record.md`.
+- **Level 3** — `proposal.md`, `design.md`, `tasks.md`, delta specs, `reports/`.
+- **Bug (`draft --bug`)** — `bugfix.md` instead of proposal/design; see the investigate skill for RCA first.
+
+For every level that needs delta specs:
+
+- **specs/<capability>/spec.md** — the delta for each affected capability.
+  `sync` promotes by overwriting the whole canonical file, so the delta must
+  carry the capability's **full** intended spec. When updating an existing
+  capability, **start from** `lawbook/specs/<capability>/spec.md`. Use normative
   language and testable scenarios:
   ```markdown
   # <Capability>
@@ -22,20 +33,13 @@ Create under `lawbook/changes/<name>/`:
   - When <action>
   - Then <observable outcome>
   ```
-- **design.md** — always: approach, alternatives weighed, and the trade-offs
-  behind the decision. For a small change, keep it short — but write it.
-- **tasks.md** — ordered, checkable steps. MUST include the mandatory steps
-  from `lawbook/config.yaml` (feature branch first; tests reviewed and run;
-  manual verification executed by the agent; discipline reports produced; docs
-  updated; archive within the PR).
-- **reports/** — create the folder with a short `reports/README.md` naming the
-  discipline reports the change will need — one per discipline it touches, from an
-  open set (`backend.md`, `frontend.md`, `api.md`, `database.md`, `infra.md`,
-  `security.md`, … — and `api.md` is required when the change touches any API
-  surface) that `build` will fill, following the required report structure
-  (header · gates table · tests added · spec-scenario coverage · pre-existing
-  failures · pending manual · verdict — see the `build` skill's discipline-reports
-  step). Every change ships this folder; archive is blocked until it holds at
-  least one discipline report.
+
+- **tasks.md** (levels 1–3) — ordered, checkable steps. MUST include the
+  mandatory steps from `lawbook/config.yaml` (feature branch first; tests;
+  manual verification by the agent; discipline reports; docs; archive in PR).
+- **reports/** — always scaffold with `reports/README.md` naming expected
+  disciplines (`backend.md`, `frontend.md`, `api.md`, … — `api.md` when an API
+  surface is touched). Archive is blocked until at least one discipline report
+  exists.
 
 Next: read `steps/05-validate.md` and do only what it says.

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

@@ -0,0 +1,10 @@
+---
+name: investigate
+description: Forensic bug triage — rank suspects via lawbook_investigate before draft --bug. Use with a stack trace or symptom when starting RCA.
+---
+
+# investigate — Bug RCA from the graph
+
+Use when work is **"this is broken"**, not **"build X"**.
+
+Read `steps/01-investigate.md` and do only what it says.

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

@@ -0,0 +1,7 @@
+# Investigate the bug
+
+- Refresh the index (`compass_index`).
+- Call **`lawbook_investigate`** with `stackTrace` and/or `symptom`.
+- **`compass_explore`** the top suspect — read the code yourself.
+
+Next: read `steps/02-hand-off.md` and do only what it says.

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

@@ -0,0 +1,6 @@
+# Hand off to draft
+
+- **`compass_impact`** on the confirmed root cause for blast radius.
+- **`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/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: quick
+description: Scaffold a level-0 lawbook change (record.md + reports) for a tiny fix. Use when the user wants a one-line fix, typo, or docs-only tweak without full ceremony — "quick change", "speclaw quick", "level 0", "skip proposal".
+---
+
+# quick — Level-0 change
+
+Create `lawbook/changes/<name>/` with `record.md`, `change.json` (confirmed
+level 0), and `reports/`. No proposal, design, or delta specs.
+
+Read `steps/01-scaffold.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/quick/steps/01-scaffold.md

@@ -0,0 +1,6 @@
+# Scaffold the level-0 change
+
+Run `speclaw quick <name>` (or the library scaffold) so `record.md`,
+`change.json`, and `reports/` exist. Pass `--path` / `--symbol` when known.
+
+Next: read `steps/02-implement.md` and do only what it says.

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

@@ -0,0 +1,7 @@
+# Implement and evidence
+
+Make the fix, tick every `- [ ]` in `record.md`, and write at least one
+discipline report under `reports/`. Archive with `lawbook_archive` (no sync at
+level 0). Promote via `lawbook_level` if scope grew.
+
+No further steps — workflow complete.