@esneiderbravo/speclaw 0.3.12 → 0.4.0

package/dist/modules/foundation/setup-tool.js

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import { loadPacks } from "../tools/packs.js";
+import { AGENTS, configureAgent } from "../../shared/agents.js";
+import { emptyReport } from "../../shared/install.js";
+import { refreshAgents } from "../../shared/agents.js";
+import { installPack } from "../tools/packs.js";
+/** Human help text for init questionnaire (not embedded in MCP schemas). */
+const profileFieldHelp = {
+    project_name: "Short project name, e.g. the repo name",
+    project_description: "One-line description of what the project does",
+    organization: "Company/team name",
+    stack_summary: "e.g. 'Next.js 15 + TypeScript frontend, FastAPI + PostgreSQL backend'",
+    architecture: "e.g. 'hexagonal architecture with bounded contexts'",
+    test_commands: "Real commands, e.g. 'pytest backend/tests && npm run test'",
+    lint_commands: "Real commands, e.g. 'ruff check . && npm run lint && tsc --noEmit'",
+    branch_pattern: "e.g. 'feature/<ticket-id>-<slug>'",
+    commit_style: "e.g. 'conventional commits, imperative, English'",
+    custom_laws: "Extra markdown for LAWS.md — project-specific binding rules",
+    compass_hints: "Markdown bullets with real entrypoints for docs/compass.md",
+    base_standards_extra: "Extra cross-cutting rules for base-standards.md",
+    modules_table: "Markdown table of modules/bounded contexts",
+    layering_rules: "Layers and allowed dependencies for architecture.md",
+    backend_layers: "Backend layer table for backend-standards.md",
+    frontend_layers: "Frontend layer table for frontend-standards.md",
+    versioning_rules: "Versioning/release convention for conventions.md",
+    documentation_extra: "Repo-specific docstring notes for documentation.md",
+};
+const profileShape = {
+    project_name: z.string(),
+    project_description: z.string().optional(),
+    organization: z.string().optional(),
+    stack_summary: z.string().optional(),
+    architecture: z.string().optional(),
+    test_commands: z.string().optional(),
+    lint_commands: z.string().optional(),
+    branch_pattern: z.string().optional(),
+    commit_style: z.string().optional(),
+    custom_laws: z.string().optional(),
+    compass_hints: z.string().optional(),
+    base_standards_extra: z.string().optional(),
+    modules_table: z.string().optional(),
+    layering_rules: z.string().optional(),
+    backend_layers: z.string().optional(),
+    frontend_layers: z.string().optional(),
+    versioning_rules: z.string().optional(),
+    documentation_extra: z.string().optional(),
+};
+export const setupActions = ["init", "configure-agent", "add-pack", "list-packs"];
+export const speclawSetupSchema = {
+    projectPath: z.string(),
+    action: z.enum(setupActions),
+    agent: z.enum(AGENTS.map((a) => a.id)).optional(),
+    pack: z.string().optional(),
+    vars: z.record(z.string()).optional(),
+};
+/**
+ * Dispatch `speclaw_setup` by action. Scaffold is CLI-only — not exposed here.
+ *
+ * @param args - Setup action and parameters.
+ */
+export function handleSpeclawSetup(args) {
+    switch (args.action) {
+        case "init":
+            return {
+                instructions: [
+                    "1. Analyze the repository at projectPath and fill profile fields from the real codebase.",
+                    "2. Call speclaw_setup with action configure-agent / add-pack as needed.",
+                    "3. Run lawbook_change action init and compass_index when scaffold completes via CLI if needed.",
+                ],
+                profileFields: profileFieldHelp,
+                packs: loadPacks(),
+                note: "Full scaffold runs via CLI: speclaw init — not MCP.",
+            };
+        case "configure-agent": {
+            if (!args.agent)
+                throw new Error(`speclaw_setup: action 'configure-agent' requires 'agent'`);
+            const report = emptyReport();
+            configureAgent(args.projectPath, args.agent, report);
+            return report;
+        }
+        case "list-packs":
+            return loadPacks();
+        case "add-pack": {
+            if (!args.pack)
+                throw new Error(`speclaw_setup: action 'add-pack' requires 'pack'`);
+            const report = emptyReport();
+            installPack(args.projectPath, args.pack, args.vars ?? {}, report);
+            refreshAgents(args.projectPath, report);
+            return report;
+        }
+        default:
+            throw new Error(`speclaw_setup: unknown action '${String(args.action)}'`);
+    }
+}
+/** Zod profile shape for CLI scaffold (not in MCP schema). */
+export { profileShape as setupProfileShape };

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

@@ -6,5 +6,5 @@ Archive the completed change: $ARGUMENTS
 
 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
+`lawbook_change` (action: validate), then `lawbook_change` (action: 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

@@ -8,4 +8,4 @@ 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.
+instead. Finish by running `lawbook_change` (action: validate) and fixing every issue.

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

@@ -4,7 +4,7 @@ description: Enter explore mode — a thinking partner before or during a change
 
 Explore: $ARGUMENTS
 
-Follow the `explore` skill: use `compass_recall`/`compass_explore` to understand
+Follow the `explore` skill: use `compass_find` (mode: concept)/`compass_explore` to understand
 the code, ask sharp questions, check the relevant `docs/standards/`, weigh
 approaches with trade-offs, and give a recommendation. Write nothing to
 `lawbook/`; when the direction is clear, offer to `draft` the change.

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/sync.md

@@ -5,6 +5,6 @@ description: Promote a change's delta specs into the canonical specs, without ar
 Sync the change's specs into canonical: $ARGUMENTS
 
 Follow the `sync` skill: reconcile the delta specs against what was actually
-built (branch diff + code graph), validate the change (`lawbook_validate`), then
-run `lawbook_sync` to promote each delta spec into `lawbook/specs/`. Report what
+built (branch diff + code graph), validate the change (`lawbook_change` (action: validate)), then
+run `lawbook_change` (action: sync) to promote each delta spec into `lawbook/specs/`. Report what
 you reconciled and what was promoted; leave the change active.

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/SKILL.md

@@ -9,7 +9,7 @@ Close out a completed change: its delta specs become canonical and the change
 folder moves to `lawbook/changes/archive/`. This is part of the PR that
 implements the change, not a post-merge chore.
 
-`lawbook_archive` is **gated** — the engine refuses to archive (and reports the
+`lawbook_change` (action: archive) is **gated** — the engine refuses to archive (and reports the
 reason) while any task is unchecked, while `reports/` holds no discipline report,
 or while the delta specs are not yet synced into the canonical specs. So archive
 is the last step of a completed change: reconcile, sync, then archive.

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

@@ -1,8 +1,8 @@
 # Validate and sync
 
-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
+Run `lawbook_change` (action: validate). If the confirmed ceremony level requires delta specs
+(levels 1–3), run `lawbook_change` (action: sync) to promote them into `lawbook/specs/` —
+`lawbook_change` (action: 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/archive/steps/04-archive.md

@@ -1,6 +1,6 @@
 # Archive
 
-Run the `lawbook_archive` tool with the change name and today's date
+Run the `lawbook_change` (action: archive) tool with the change name and today's date
 (`YYYY-MM-DD`). It re-checks the gate deterministically and, if it passes,
 moves `lawbook/changes/<name>/` to `lawbook/changes/archive/<date>-<name>/`.
 If it refuses, resolve the reported blockers (unchecked tasks, missing

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

@@ -4,7 +4,7 @@
   code — it is incremental (unchanged files are skipped by hash), so this is
   cheap and guarantees your decisions rest on the current graph, not a stale one.
 - Clarify what the user wants (feature / fix / refactor) and confirm scope.
-- Use `compass_explore` and `compass_recall` (speclaw's code index) BEFORE
+- Use `compass_explore` and `compass_find` (mode: concept) (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

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

@@ -13,6 +13,7 @@ Create under `lawbook/changes/<name>/` only what the level needs:
 - **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:
 

package/dist/modules/lawbook/assets/skills/draft/steps/05-validate.md

@@ -1,6 +1,6 @@
 # Validate
 
-Run the `lawbook_validate` tool for the change and fix every issue it reports
+Run the `lawbook_change` (action: validate) tool for the change and fix every issue it reports
 (missing artifacts, non-normative specs, missing scenarios) before handing off
 to implementation. Read its advisory **warnings** too: a near-duplicate
 capability name usually means you should reuse the existing capability's exact

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

@@ -3,7 +3,7 @@
 - **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_recall` to find relevant code by
+- **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.
 - **Ask sharp questions** to surface hidden assumptions, constraints, and edge

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/steps/02-implement.md

@@ -1,7 +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
+discipline report under `reports/`. Archive with `lawbook_change` (action: archive) (no sync at
 level 0). Promote via `lawbook_level` if scope grew.
 
 No further steps — workflow complete.

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

@@ -9,7 +9,7 @@ Update the project's canonical specifications (`lawbook/specs/`) with a change's
 delta specs, without archiving the change. Use this when the specs should
 become the source of truth but the change isn't finished (e.g. multi-PR work).
 
-`lawbook_sync` is a deterministic copy — it is blind to the code. So before
+`lawbook_change` (action: sync) is a deterministic copy — it is blind to the code. So before
 promoting, YOU reconcile the delta specs against what was actually built, so the
 specs that become canonical describe reality, not just the original draft.
 

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

@@ -1,6 +1,6 @@
 # Validate
 
-Run `lawbook_validate` for the change; do not sync a change whose specs are
+Run `lawbook_change` (action: validate) for the change; do not sync a change whose specs are
 invalid.
 
 Next: read `steps/04-promote.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/sync/steps/04-promote.md

@@ -1,6 +1,6 @@
 # Promote
 
-Run the `lawbook_sync` tool for the change. It copies each
+Run the `lawbook_change` (action: sync) tool for the change. It copies each
 `lawbook/changes/<name>/specs/<capability>/spec.md` over the canonical
 `lawbook/specs/<capability>/spec.md` and reports what it promoted, flagging
 each as **created** (new capability) or **updated** (overwrote an existing

package/dist/modules/lawbook/bugfix.js

@@ -0,0 +1,195 @@
+import fs from "node:fs";
+import path from "node:path";
+import { gatherSignals, loadCeremonyConfig, proposeLevel, setCeremonyLevel, writeCeremonyRecord, } from "./levels.js";
+export const BUGFIX_HEADINGS = [
+    "1. Observed symptom",
+    "2. Minimal reproduction",
+    "3. Root cause",
+    "4. Blast radius",
+    "5. Proposed fix",
+    "6. Regression test",
+    "7. Prevention",
+];
+/** Parsed section bodies keyed by heading label. */
+export function parseBugfixSections(content) {
+    const out = new Map();
+    for (const part of content.split(/^##\s+/m).slice(1)) {
+        const nl = part.indexOf("\n");
+        if (nl < 0) {
+            out.set(part.trim(), "");
+            continue;
+        }
+        out.set(part.slice(0, nl).trim(), part.slice(nl + 1).trim());
+    }
+    return out;
+}
+function sectionBody(sections, key) {
+    for (const [h, b] of sections) {
+        if (h.toLowerCase().startsWith(key.toLowerCase()))
+            return b;
+    }
+    return "";
+}
+function isFilled(body) {
+    const t = body.trim();
+    if (!t)
+        return false;
+    if (/^n\/a\s*:/i.test(t))
+        return true;
+    return t.length > 2;
+}
+/** True when prevention says a canonical requirement was missing. */
+export function preventionRequiresDelta(content) {
+    const prev = sectionBody(parseBugfixSections(content), "7. Prevention");
+    if (!prev)
+        return false;
+    return (/\b(requirement|spec)\b.*\b(miss|missing|absent|incomplete|add|update)\b/i.test(prev) ||
+        /\bfaltaba\b/i.test(prev) ||
+        /\bmissing requirement\b/i.test(prev));
+}
+/** Infer archive resolution from bugfix.md content. */
+export function inferBugResolution(content) {
+    if (/\bnot-a-bug\b/i.test(content) || /resolution:\s*not-a-bug/i.test(content)) {
+        return "not-a-bug";
+    }
+    const repro = sectionBody(parseBugfixSections(content), "2. Minimal reproduction");
+    if (/unreproducible\s*:/i.test(repro))
+        return "mitigated";
+    return "fixed";
+}
+/**
+ * Validate bugfix.md sections for a ceremony level.
+ *
+ * @returns Human-readable issues (empty when valid).
+ */
+export function validateBugfixContent(level, content) {
+    const issues = [];
+    const sections = parseBugfixSections(content);
+    for (const h of BUGFIX_HEADINGS) {
+        if (!sections.has(h) && ![...sections.keys()].some((k) => k.startsWith(h.split(".")[0]))) {
+            issues.push(`bugfix.md missing heading "## ${h}"`);
+        }
+    }
+    const repro = sectionBody(sections, "2. Minimal reproduction");
+    if (!isFilled(repro) && !/unreproducible\s*:/i.test(repro)) {
+        issues.push("bugfix.md §2 requires reproduction steps or an `unreproducible:` block");
+    }
+    const requiredAt0 = [
+        "1. Observed symptom",
+        "2. Minimal reproduction",
+        "3. Root cause",
+        "5. Proposed fix",
+        "6. Regression test",
+    ];
+    const optionalAt0 = ["4. Blast radius", "7. Prevention"];
+    const allRequired = level >= 1 ? [...BUGFIX_HEADINGS] : requiredAt0;
+    for (const key of allRequired) {
+        const body = sectionBody(sections, key);
+        if (!isFilled(body) && !/unreproducible\s*:/i.test(body)) {
+            issues.push(`bugfix.md §${key.split(".")[0]} (${key}) is empty`);
+        }
+    }
+    if (level === 0) {
+        for (const key of optionalAt0) {
+            const body = sectionBody(sections, key);
+            if (body && !isFilled(body) && !/^n\/a\s*:/i.test(body)) {
+                issues.push(`bugfix.md §${key.split(".")[0]} must be filled or start with \`n/a:\``);
+            }
+        }
+    }
+    const prevention = sectionBody(sections, "7. Prevention");
+    const resolution = inferBugResolution(content);
+    if (resolution === "not-a-bug" && !isFilled(prevention)) {
+        issues.push("not-a-bug resolution requires a prevention entry (usually a spec clarity fix)");
+    }
+    else if (level >= 1 && !isFilled(prevention)) {
+        issues.push("bugfix.md §7 Prevention must be answered (law, spec gap, or explicit none with reason)");
+    }
+    const regression = sectionBody(sections, "6. Regression test");
+    const mitigated = /unreproducible\s*:/i.test(repro);
+    if (!mitigated && !isFilled(regression)) {
+        issues.push("bugfix.md §6 Regression test is required unless reproduction is unreproducible");
+    }
+    if (mitigated && !isFilled(regression) && !/\binstrument/i.test(content)) {
+        issues.push("unreproducible bugs require instrumentation (§6 or explicit instrumentation reference)");
+    }
+    return issues;
+}
+function bugfixTemplate(name, level, seed) {
+    const symptom = seed?.inputSymptom ??
+        "<What you see: error message, wrong value, screenshot reference. Do not interpret yet.>";
+    const root = seed?.suspects?.[0] != null
+        ? `${seed.suspects[0].name} (${seed.suspects[0].file}:${seed.suspects[0].startLine}) **(candidate — verify)**`
+        : "<symbol (file:line) — must resolve against the graph>";
+    const blast = seed?.blastRadiusSummary ??
+        "<Run compass_impact on the confirmed root cause; list modules and call sites.>";
+    return `# Bugfix: ${name}
+
+**Level:** ${level} · **Type:** bug · **Severity:** normal
+
+## 1. Observed symptom
+${symptom}
+
+## 2. Minimal reproduction
+<!-- Steps to reproduce, or \`unreproducible: <reason and what was tried>\` -->
+
+## 3. Root cause
+${root}
+
+## 4. Blast radius
+${blast}
+
+## 5. Proposed fix
+<!-- The change; note discarded alternatives if any. -->
+
+## 6. Regression test
+<!-- test/path.test.ts::case name — must fail BEFORE the fix -->
+
+## 7. Prevention
+<!-- New law (executable-laws block), missing spec requirement, or "none: <reason>" -->
+`;
+}
+/**
+ * Scaffold a bug change: `bugfix.md`, `change.json`, and `reports/`.
+ */
+export function scaffoldBugfix(projectPath, name, opts = {}) {
+    const changeDir = path.join(projectPath, "lawbook", "changes", name);
+    if (fs.existsSync(changeDir)) {
+        throw new Error(`change "${name}" already exists under lawbook/changes/`);
+    }
+    const targets = opts.targets ?? { paths: [], symbols: [] };
+    const { thresholds } = loadCeremonyConfig(projectPath);
+    const signals = gatherSignals(projectPath, targets, thresholds);
+    const proposal = proposeLevel(signals, thresholds);
+    const level = opts.level ?? (proposal.level !== null && proposal.level <= 1 ? proposal.level : 1);
+    fs.mkdirSync(path.join(changeDir, "reports"), { recursive: true });
+    fs.writeFileSync(path.join(changeDir, "bugfix.md"), bugfixTemplate(name, level, opts.seed));
+    fs.writeFileSync(path.join(changeDir, "reports", "README.md"), `# Reports — ${name}\n\nBug reports MUST include the regression test **failing before the fix**.\n`);
+    if (level >= 1) {
+        fs.writeFileSync(path.join(changeDir, "tasks.md"), `- [ ] Reproduce and confirm root cause\n- [ ] Implement fix\n- [ ] Add regression test (red before, green after)\n- [ ] Complete prevention §7\n- [ ] Write discipline report under reports/\n`);
+    }
+    if (level >= 2) {
+        fs.writeFileSync(path.join(changeDir, "design.md"), `# Design — ${name}\n\n## Approach\n\n(structural bugfix — document the fix architecture)\n`);
+    }
+    const record = setCeremonyLevel(projectPath, name, {
+        proposal,
+        level,
+        confirmedBy: "human",
+    });
+    const updated = { ...record, changeType: "bug" };
+    writeCeremonyRecord(projectPath, name, updated);
+    return { change: name, proposal, record: updated, dir: changeDir };
+}
+/** Read change type from an archived folder path. */
+export function readChangeTypeFromDir(changeDir) {
+    const p = path.join(changeDir, "change.json");
+    if (!fs.existsSync(p))
+        return "feature";
+    try {
+        const raw = JSON.parse(fs.readFileSync(p, "utf8"));
+        return raw.changeType === "bug" ? "bug" : "feature";
+    }
+    catch {
+        return "feature";
+    }
+}

package/dist/modules/lawbook/change-tool.js

@@ -0,0 +1,90 @@
+import { z } from "zod";
+import { specInit, specValidate, specSync, specArchive, specList } from "./engine.js";
+import { handleLevel } from "./quick.js";
+import { buildCoverageReport, loadCoverageConfig, renderCoverageAgent } from "./coverage.js";
+import { buildDriftReport, renderDriftAgent } from "./drift.js";
+export const lawbookChangeActions = [
+    "init",
+    "list",
+    "validate",
+    "sync",
+    "archive",
+    "level",
+    "coverage",
+    "drift",
+];
+export const lawbookChangeSchema = {
+    projectPath: z.string(),
+    action: z.enum(lawbookChangeActions),
+    change: z.string().optional(),
+    date: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/)
+        .optional(),
+    mode: z.enum(["propose", "set", "promote", "explain"]).optional(),
+    paths: z.array(z.string()).optional(),
+    symbols: z.array(z.string()).optional(),
+    level: z.union([z.literal(0), z.literal(1), z.literal(2), z.literal(3)]).optional(),
+    reason: z.string().optional(),
+    onlyDefects: z.boolean().optional(),
+    json: z.boolean().optional(),
+    capability: z.string().optional(),
+    includeReverse: z.boolean().optional(),
+    maxItems: z.number().int().min(1).max(50).optional(),
+};
+function requireField(args, field) {
+    const v = args[field];
+    if (typeof v === "string" && v.length > 0)
+        return v;
+    throw new Error(`lawbook_change: action '${args.action}' requires '${String(field)}'`);
+}
+/**
+ * Dispatch `lawbook_change` by action.
+ *
+ * @param args - Unified lawbook lifecycle arguments.
+ */
+export function handleLawbookChange(args) {
+    switch (args.action) {
+        case "init":
+            return specInit(args.projectPath);
+        case "list":
+            return specList(args.projectPath);
+        case "validate":
+            return specValidate(args.projectPath, requireField(args, "change"));
+        case "sync":
+            return specSync(args.projectPath, requireField(args, "change"));
+        case "archive":
+            return specArchive(args.projectPath, requireField(args, "change"), requireField(args, "date"));
+        case "level":
+            if (!args.mode)
+                throw new Error(`lawbook_change: action 'level' requires 'mode'`);
+            return handleLevel({
+                projectPath: args.projectPath,
+                mode: args.mode,
+                change: args.change,
+                paths: args.paths,
+                symbols: args.symbols,
+                level: args.level,
+                reason: args.reason,
+            });
+        case "coverage": {
+            const cfg = loadCoverageConfig(args.projectPath);
+            const report = buildCoverageReport(args.projectPath, { change: args.change, cfg });
+            if (args.json)
+                return report;
+            return renderCoverageAgent(report, args.onlyDefects !== false);
+        }
+        case "drift": {
+            const report = buildDriftReport(args.projectPath, {
+                capability: args.capability,
+                reverse: args.includeReverse === true,
+                failOn: "semantic",
+            });
+            if (args.json)
+                return report;
+            return renderDriftAgent(report, args.maxItems ?? 10);
+        }
+        default:
+            throw new Error(`lawbook_change: unknown action '${String(args.action)}'`);
+    }
+}