@esneiderbravo/speclaw 0.3.12 → 0.3.13

package/dist/cli/commands/lawbook.js

@@ -1,5 +1,7 @@
 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() {
@@ -89,6 +91,45 @@ export async function runSpec(flags) {
                 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, "lawbook archive <change>"), today());
                 ui.ok(`archived to ${r.archivedTo} (${r.promoted.length} spec(s) promoted)`);
@@ -103,7 +144,7 @@ export async function runSpec(flags) {
                 return;
             }
             default:
-                ui.err("Usage: speclaw lawbook <init|list|validate|sync|archive|level> [change]");
+                ui.err("Usage: speclaw lawbook <init|list|validate|sync|archive|level|draft|investigate> [change]");
                 process.exit(1);
         }
     }

package/dist/cli/commands/update.js

@@ -135,6 +135,14 @@ const MIGRATIONS = [
             "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

@@ -35,6 +35,8 @@ Lawbook (spec-driven workflow)
   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
@@ -102,6 +104,10 @@ function maybeHeader(cmd, flags) {
         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. */

package/dist/modules/foundation/doctor.js

@@ -527,6 +527,37 @@ function ceremonyChecks(projectPath) {
             ? "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) {

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/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/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/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/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/engine.js

@@ -2,7 +2,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { coverageArchiveBlockers } from "./coverage.js";
 import { sealCapability } from "./anchors.js";
-import { artifactNeeds, confirmedLevel, countUncheckedTasks, gatherSignals, hasDisciplineReport, loadCeremonyConfig, proposeLevel, } from "./levels.js";
+import { artifactNeeds, confirmedLevel, countUncheckedTasks, gatherSignals, hasDisciplineReport, loadCeremonyConfig, proposeLevel, readChangeType, readCeremonyRecord, } from "./levels.js";
+import { inferBugResolution, preventionRequiresDelta, validateBugfixContent } from "./bugfix.js";
 // speclaw's own spec-driven workflow engine. Inspired by OpenSpec's model
 // (proposals, delta specs, changes, archive) but implemented from scratch and
 // deliberately simpler: a change's specs/ holds the full intended spec for each
@@ -176,7 +177,20 @@ export function specValidate(projectPath, change, remeasure) {
         };
     }
     const level = confirmedLevel(projectPath, change);
-    const needs = artifactNeeds(level);
+    const changeType = readChangeType(projectPath, change);
+    const needs = artifactNeeds(level, changeType);
+    if (needs.bugfix) {
+        const bugPath = path.join(changeDir, "bugfix.md");
+        if (!fs.existsSync(bugPath)) {
+            issues.push(`missing bugfix.md (required for bug changes at level ${level})`);
+        }
+        else {
+            issues.push(...validateBugfixContent(level, fs.readFileSync(bugPath, "utf8")));
+        }
+        if (fs.existsSync(path.join(changeDir, "proposal.md"))) {
+            issues.push("bug changes must not include proposal.md — use bugfix.md");
+        }
+    }
     if (needs.record && !fs.existsSync(path.join(changeDir, "record.md"))) {
         issues.push(`missing record.md (required at ceremony level ${level})`);
     }
@@ -200,6 +214,14 @@ export function specValidate(projectPath, change, remeasure) {
     if (needs.deltaSpecs && deltas.length === 0) {
         issues.push(`no delta specs under specs/ (required at ceremony level ${level})`);
     }
+    if (needs.bugfix) {
+        const bugPath = path.join(changeDir, "bugfix.md");
+        if (fs.existsSync(bugPath) && preventionRequiresDelta(fs.readFileSync(bugPath, "utf8"))) {
+            if (deltas.length === 0) {
+                issues.push("prevention §7 indicates a missing canonical requirement — add a delta spec under specs/");
+            }
+        }
+    }
     // Scope-growth: when remeasure targets provided (or change.json has prior signals
     // with paths we cannot recover), only check if caller passes targets.
     if (remeasure && (remeasure.paths.length > 0 || remeasure.symbols.length > 0)) {
@@ -315,8 +337,9 @@ export function specArchivePreconditions(projectPath, change) {
         return [`change "${change}" not found under lawbook/changes/`];
     const blockers = [];
     const level = confirmedLevel(projectPath, change);
-    const needs = artifactNeeds(level);
-    // 1. Every task must be checked (tasks.md, or checklist in record.md at level 0).
+    const changeType = readChangeType(projectPath, change);
+    const needs = artifactNeeds(level, changeType);
+    // 1. Every task must be checked (tasks.md, record.md, or bugfix checklist at level 0).
     if (needs.tasksFile) {
         const tasksPath = path.join(changeDir, "tasks.md");
         if (!fs.existsSync(tasksPath)) {
@@ -339,12 +362,32 @@ export function specArchivePreconditions(projectPath, change) {
                 blockers.push(`${unchecked} unchecked task(s) in record.md`);
         }
     }
+    else if (needs.bugfix && level === 0) {
+        const bugPath = path.join(changeDir, "bugfix.md");
+        if (fs.existsSync(bugPath)) {
+            const unchecked = countUncheckedTasks(fs.readFileSync(bugPath, "utf8"));
+            if (unchecked > 0)
+                blockers.push(`${unchecked} unchecked item(s) in bugfix.md checklist`);
+        }
+    }
+    if (needs.bugfix) {
+        const bugPath = path.join(changeDir, "bugfix.md");
+        if (fs.existsSync(bugPath)) {
+            const content = fs.readFileSync(bugPath, "utf8");
+            const bugIssues = validateBugfixContent(level, content);
+            blockers.push(...bugIssues.filter((i) => i.includes("Regression test") || i.includes("§6")));
+        }
+    }
     // 2. At least one discipline report must exist (README.md scaffold aside).
     if (!hasDisciplineReport(changeDir)) {
         blockers.push("no discipline report under reports/ (build must record what was tested)");
     }
-    // 3. Delta specs must already be synced — only when the level requires them.
-    if (needs.deltaSpecs) {
+    // 3. Delta specs must already be synced — when required or when bug prevention demands it.
+    const bugPath = path.join(changeDir, "bugfix.md");
+    const bugNeedsDelta = needs.bugfix &&
+        fs.existsSync(bugPath) &&
+        preventionRequiresDelta(fs.readFileSync(bugPath, "utf8"));
+    if (needs.deltaSpecs || bugNeedsDelta) {
         for (const file of deltaSpecFiles(changeDir)) {
             const rel = path.relative(path.join(changeDir, "specs"), file);
             const canonical = path.join(root, "specs", rel);
@@ -381,7 +424,27 @@ export function specArchive(projectPath, change, date) {
         throw new Error(`cannot archive "${change}" — resolve first:\n${blockers.map((b) => `  - ${b}`).join("\n")}`);
     }
     const level = confirmedLevel(projectPath, change);
-    const sync = artifactNeeds(level).deltaSpecs
+    const changeType = readChangeType(projectPath, change);
+    const needs = artifactNeeds(level, changeType);
+    // Record bug resolution before move.
+    if (changeType === "bug") {
+        const bugPath = path.join(changeDir, "bugfix.md");
+        if (fs.existsSync(bugPath)) {
+            const rec = readCeremonyRecord(projectPath, change);
+            if (rec) {
+                rec.changeType = "bug";
+                rec.resolution = inferBugResolution(fs.readFileSync(bugPath, "utf8"));
+                const cj = path.join(changeDir, "change.json");
+                fs.writeFileSync(cj, JSON.stringify(rec, null, 2) + "\n");
+            }
+        }
+    }
+    const bugPath = path.join(changeDir, "bugfix.md");
+    const shouldSync = needs.deltaSpecs ||
+        (changeType === "bug" &&
+            fs.existsSync(bugPath) &&
+            preventionRequiresDelta(fs.readFileSync(bugPath, "utf8")));
+    const sync = shouldSync
         ? specSync(projectPath, change)
         : { change, promoted: [], created: [], updated: [] };
     const { promoted, created, updated } = sync;

package/dist/modules/lawbook/investigate.js

@@ -0,0 +1,358 @@
+import fs from "node:fs";
+import path from "node:path";
+import { indexExists, openDb } from "../compass/db.js";
+import { explore, impact, recall } from "../compass/query.js";
+import { affectedTests } from "../compass/affected.js";
+import { hotspots, coupling } from "../compass/hotspots.js";
+import { isGitRepo } from "../../shared/git.js";
+import { lastTouch } from "../../shared/git-history.js";
+import { frameSymbolName, parseStackTrace, } from "./stack-parse.js";
+const WEIGHTS = {
+    "stack-frame": 40,
+    "frame-caller": 25,
+    "frame-callee": 15,
+    hotspot: 20,
+    "temporal-coupling": 15,
+    "semantic-match": 10,
+    "hint-path": 8,
+    "recently-changed": 10,
+};
+function resolveAtLine(projectPath, file, line) {
+    if (!indexExists(projectPath))
+        return null;
+    const db = openDb(projectPath);
+    try {
+        const row = db
+            .prepare(`SELECT s.name, s.kind, s.start_line AS startLine, s.signature
+         FROM nodes s JOIN files f ON f.id = s.file_id
+         WHERE f.path = ? AND s.start_line <= ? AND s.end_line >= ?
+         ORDER BY (s.end_line - s.start_line) ASC
+         LIMIT 1`)
+            .get(file, line, line);
+        if (!row)
+            return null;
+        return {
+            name: row.name,
+            kind: row.kind,
+            startLine: row.startLine,
+            signature: row.signature ?? undefined,
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+function callerCount(projectPath, name) {
+    if (!indexExists(projectPath))
+        return 0;
+    const ex = explore(projectPath, name);
+    return ex.callers?.length ?? 0;
+}
+function addCandidate(map, key, c) {
+    const prev = map.get(key);
+    const weight = c.weight ?? WEIGHTS[c.reason];
+    const entry = prev ?? {
+        name: c.name,
+        kind: c.kind,
+        file: c.file,
+        startLine: c.startLine,
+        signature: c.signature,
+        reasons: [],
+        distanceFromFrame: c.distanceFromFrame,
+        callerCount: c.callerCount,
+        hotspotScore: c.hotspotScore,
+    };
+    entry.reasons.push({ reason: c.reason, weight, detail: c.detail });
+    entry.callerCount = Math.max(entry.callerCount, c.callerCount);
+    if (c.hotspotScore !== undefined) {
+        entry.hotspotScore = Math.max(entry.hotspotScore ?? 0, c.hotspotScore);
+    }
+    map.set(key, entry);
+}
+function scoreCandidate(c) {
+    let raw = c.reasons.reduce((s, r) => s + r.weight, 0);
+    raw /= Math.log2(c.callerCount + 2);
+    return Math.round(Math.min(100, Math.max(0, raw)));
+}
+function scanArchivedRootCauses(projectPath, symbol) {
+    const archiveRoot = path.join(projectPath, "lawbook", "changes", "archive");
+    if (!fs.existsSync(archiveRoot))
+        return [];
+    const hits = [];
+    for (const dir of fs.readdirSync(archiveRoot)) {
+        const bugfix = path.join(archiveRoot, dir, "bugfix.md");
+        if (!fs.existsSync(bugfix))
+            continue;
+        const text = fs.readFileSync(bugfix, "utf8");
+        if (text.includes(symbol))
+            hits.push(dir);
+    }
+    return hits;
+}
+/**
+ * Rank likely bug origins from the code graph and git history.
+ */
+export async function investigate(args) {
+    const maxSuspects = args.maxSuspects ?? 8;
+    const degraded = [];
+    const hintPaths = (args.hintPaths ?? []).map((p) => p.replace(/^\.\//, ""));
+    if (!args.stackTrace?.trim() && !args.symptom?.trim()) {
+        throw new Error("provide stackTrace or symptom");
+    }
+    if (args.stackTrace?.trim()) {
+        const parsed = parseStackTrace(args.projectPath, args.stackTrace);
+        if (parsed.format === "unknown" && parsed.frames.length === 0 && parsed.unresolved.length > 0) {
+            return {
+                suspects: [],
+                unresolvedFrames: parsed.unresolved,
+                degraded: [],
+                guidance: "Stack trace could not be parsed. speclaw indexes TS/JS/Python only — use `symptom` for prose triage.",
+                inputSymptom: args.stackTrace.split("\n")[0],
+            };
+        }
+    }
+    if (!indexExists(args.projectPath)) {
+        return {
+            suspects: [],
+            unresolvedFrames: [],
+            degraded: ["no-index"],
+            guidance: "No Compass index — run `speclaw index` first. Without the graph, suspects cannot be verified.",
+            inputSymptom: args.symptom ?? args.stackTrace?.split("\n")[0],
+        };
+    }
+    const candidates = new Map();
+    let unresolvedFrames = [];
+    let frames = [];
+    if (args.stackTrace?.trim()) {
+        const parsed = parseStackTrace(args.projectPath, args.stackTrace);
+        unresolvedFrames = parsed.unresolved;
+        frames = parsed.frames;
+        if (parsed.format === "unknown" && parsed.frames.length === 0) {
+            return {
+                suspects: [],
+                unresolvedFrames,
+                degraded: [],
+                guidance: "Stack trace could not be parsed. speclaw indexes TS/JS/Python only — use `symptom` for prose triage.",
+                inputSymptom: args.stackTrace.split("\n")[0],
+            };
+        }
+        frames.forEach((frame, idx) => {
+            const dist = idx;
+            const atLine = resolveAtLine(args.projectPath, frame.file, frame.line);
+            const symName = atLine?.name ?? frameSymbolName(frame) ?? frame.fn;
+            if (atLine || symName) {
+                const name = atLine?.name ?? symName;
+                const cc = callerCount(args.projectPath, name);
+                addCandidate(candidates, `${frame.file}:${name}`, {
+                    name,
+                    kind: atLine?.kind ?? "function",
+                    file: frame.file,
+                    startLine: atLine?.startLine ?? frame.line,
+                    signature: atLine?.signature,
+                    reason: "stack-frame",
+                    detail: `frame at ${frame.file}:${frame.line}`,
+                    distanceFromFrame: dist,
+                    callerCount: cc,
+                });
+                if (symName) {
+                    const ex = explore(args.projectPath, name);
+                    if (ex.found) {
+                        for (const caller of ex.callers ?? []) {
+                            addCandidate(candidates, `${caller.file}:${caller.name}`, {
+                                name: caller.name,
+                                kind: caller.kind,
+                                file: caller.file,
+                                startLine: caller.line,
+                                reason: "frame-caller",
+                                detail: `calls ${name} from the trace`,
+                                distanceFromFrame: dist + 1,
+                                callerCount: callerCount(args.projectPath, caller.name),
+                            });
+                        }
+                        for (const callee of ex.callees ?? []) {
+                            if (!callee.file)
+                                continue;
+                            addCandidate(candidates, `${callee.file}:${callee.name}`, {
+                                name: callee.name,
+                                kind: "function",
+                                file: callee.file,
+                                startLine: callee.line,
+                                reason: "frame-callee",
+                                detail: `called by ${name} in the trace`,
+                                distanceFromFrame: dist + 1,
+                                callerCount: callerCount(args.projectPath, callee.name),
+                            });
+                        }
+                    }
+                }
+            }
+        });
+    }
+    if (args.symptom?.trim() && candidates.size === 0) {
+        try {
+            const hits = await recall(args.projectPath, args.symptom, 15);
+            for (const h of hits) {
+                addCandidate(candidates, `${h.file}:${h.name}`, {
+                    name: h.name,
+                    kind: h.kind,
+                    file: h.file,
+                    startLine: h.line,
+                    signature: h.signature ?? undefined,
+                    reason: "semantic-match",
+                    detail: `semantic match for symptom`,
+                    distanceFromFrame: null,
+                    callerCount: callerCount(args.projectPath, h.name),
+                });
+            }
+        }
+        catch {
+            degraded.push("no-embeddings");
+        }
+    }
+    // Hotspots + coupling
+    const files = new Set([...candidates.values()].map((c) => c.file));
+    for (const f of frames)
+        files.add(f.file);
+    for (const h of hintPaths)
+        files.add(h);
+    try {
+        const hs = hotspots(args.projectPath, { days: 90, sortBy: "combined", limit: 200 });
+        let max = 0;
+        for (const h of hs.hotspots)
+            max = Math.max(max, h.combinedScore);
+        if (max <= 0)
+            degraded.push("no-hotspots");
+        else {
+            const hotspotByFile = new Map(hs.hotspots.map((h) => [h.file, h.combinedScore / max]));
+            for (const [file, score] of hotspotByFile) {
+                if (score < 0.3)
+                    continue;
+                for (const [key, c] of candidates) {
+                    if (c.file !== file)
+                        continue;
+                    addCandidate(candidates, key, {
+                        ...c,
+                        reason: "hotspot",
+                        detail: `hotspot score ${score.toFixed(2)} on ${file}`,
+                        hotspotScore: score,
+                    });
+                }
+            }
+        }
+    }
+    catch {
+        degraded.push("no-hotspots");
+    }
+    try {
+        for (const file of files) {
+            const co = coupling(args.projectPath, file, { limit: 5 });
+            for (const p of co.partners) {
+                if (p.strength < 0.2)
+                    continue;
+                for (const frameFile of frames.map((f) => f.file)) {
+                    if (p.file === frameFile) {
+                        for (const [key, c] of candidates) {
+                            if (c.file === file) {
+                                addCandidate(candidates, key, {
+                                    ...c,
+                                    reason: "temporal-coupling",
+                                    detail: `temporally coupled to ${frameFile} (strength ${p.strength.toFixed(2)})`,
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        degraded.push("no-coupling");
+    }
+    if (isGitRepo(args.projectPath)) {
+        for (const [key, c] of candidates) {
+            const touch = lastTouch(args.projectPath, c.file);
+            if (touch) {
+                addCandidate(candidates, key, {
+                    ...c,
+                    reason: "recently-changed",
+                    detail: `last touched ${touch}`,
+                });
+            }
+        }
+    }
+    else {
+        degraded.push("no-git");
+    }
+    for (const h of hintPaths) {
+        for (const [key, c] of candidates) {
+            if (c.file === h || c.file.endsWith(h)) {
+                addCandidate(candidates, key, {
+                    ...c,
+                    reason: "hint-path",
+                    detail: `matches hint path ${h}`,
+                });
+            }
+        }
+    }
+    let suspects = [...candidates.values()]
+        .map((c) => ({
+        name: c.name,
+        kind: c.kind,
+        file: c.file,
+        startLine: c.startLine,
+        signature: c.signature,
+        score: scoreCandidate(c),
+        reasons: c.reasons,
+        distanceFromFrame: c.distanceFromFrame,
+        hotspotScore: c.hotspotScore,
+        coveringTests: [],
+    }))
+        .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+    // Covering tests for top candidates
+    for (const s of suspects.slice(0, 5)) {
+        try {
+            const at = affectedTests(args.projectPath, { files: [s.file] });
+            s.coveringTests = at.tests.map((t) => t.file).slice(0, 5);
+        }
+        catch {
+            /* soft */
+        }
+    }
+    if (suspects.length > 0 && suspects.length < 3) {
+        // keep all when fewer than 3
+    }
+    else if (suspects.length > maxSuspects) {
+        suspects = suspects.slice(0, maxSuspects);
+    }
+    const top = suspects[0];
+    let blastRadiusSummary;
+    let priorFixes;
+    if (top) {
+        priorFixes = scanArchivedRootCauses(args.projectPath, top.name);
+        try {
+            const imp = impact(args.projectPath, { symbol: top.name, format: "grouped", maxDepth: 3 });
+            blastRadiusSummary = `${imp.totals.nodes} node(s) in ${imp.totals.modules} module(s) reachable from ${top.name}`;
+        }
+        catch {
+            blastRadiusSummary = `(run compass_impact on ${top.name})`;
+        }
+    }
+    const guidance = "Treat this ranking as evidence, not a verdict — read the top suspects yourself. " +
+        "Stack frames outrank graph neighbours; external/node_modules frames are excluded. " +
+        (priorFixes?.length
+            ? `Prior archive(s) mention this symbol: ${priorFixes.join(", ")}.`
+            : "No matching archived bugfix root cause found.");
+    return {
+        suspects,
+        unresolvedFrames,
+        degraded: [...new Set(degraded)],
+        guidance,
+        inputSymptom: args.symptom ?? args.stackTrace?.split("\n")[0]?.trim(),
+        blastRadiusSummary,
+        priorFixes,
+    };
+}
+/** Format investigate result as stable JSON text (deterministic key order). */
+export function formatInvestigateResult(result) {
+    return JSON.stringify(result, null, 2);
+}

package/dist/modules/lawbook/levels.js

@@ -34,7 +34,45 @@ const BUCKETS = {
     affectedTests: [0, 3, 15, Infinity],
     blastRadiusNodes: [2, 10, 50, Infinity],
 };
-export function artifactNeeds(level) {
+export function artifactNeeds(level, changeType = "feature") {
+    if (changeType === "bug") {
+        switch (level) {
+            case 0:
+                return {
+                    record: false,
+                    proposal: false,
+                    design: false,
+                    tasksFile: false,
+                    deltaSpecs: false,
+                    reports: true,
+                    designOptionalWithJustification: false,
+                    bugfix: true,
+                };
+            case 1:
+                return {
+                    record: false,
+                    proposal: false,
+                    design: false,
+                    tasksFile: true,
+                    deltaSpecs: false,
+                    reports: true,
+                    designOptionalWithJustification: false,
+                    bugfix: true,
+                };
+            case 2:
+            case 3:
+                return {
+                    record: false,
+                    proposal: false,
+                    design: true,
+                    tasksFile: true,
+                    deltaSpecs: false,
+                    reports: true,
+                    designOptionalWithJustification: false,
+                    bugfix: true,
+                };
+        }
+    }
     switch (level) {
         case 0:
             return {
@@ -45,6 +83,7 @@ export function artifactNeeds(level) {
                 deltaSpecs: false,
                 reports: true,
                 designOptionalWithJustification: false,
+                bugfix: false,
             };
         case 1:
             return {
@@ -55,6 +94,7 @@ export function artifactNeeds(level) {
                 deltaSpecs: true,
                 reports: true,
                 designOptionalWithJustification: false,
+                bugfix: false,
             };
         case 2:
             return {
@@ -65,6 +105,7 @@ export function artifactNeeds(level) {
                 deltaSpecs: true,
                 reports: true,
                 designOptionalWithJustification: true,
+                bugfix: false,
             };
         case 3:
             return {
@@ -75,9 +116,15 @@ export function artifactNeeds(level) {
                 deltaSpecs: true,
                 reports: true,
                 designOptionalWithJustification: false,
+                bugfix: false,
             };
     }
 }
+/** Read change type from change.json; missing ⇒ feature. */
+export function readChangeType(projectPath, change) {
+    const rec = readCeremonyRecord(projectPath, change);
+    return rec?.changeType === "bug" ? "bug" : "feature";
+}
 function bucketPoints(value, edges, points) {
     const i = edges.findIndex((max) => value <= max);
     return points[i < 0 ? 3 : i];
@@ -370,7 +417,7 @@ export function scaffoldArtifactsForLevel(projectPath, change, level) {
     const changeDir = path.join(projectPath, "lawbook", "changes", change);
     if (!fs.existsSync(changeDir))
         return;
-    const needs = artifactNeeds(level);
+    const needs = artifactNeeds(level, readChangeType(projectPath, change));
     const recordPath = path.join(changeDir, "record.md");
     const recordText = fs.existsSync(recordPath) ? fs.readFileSync(recordPath, "utf8") : "";
     const ensure = (rel, content) => {

package/dist/modules/lawbook/register.js

@@ -6,6 +6,7 @@ import { assetsDir } from "../../shared/paths.js";
 import { copyRendered } from "../../shared/install.js";
 import { specInit, specValidate, specSync, specArchive, specList } from "./engine.js";
 import { handleLevel } from "./quick.js";
+import { investigate, formatInvestigateResult } from "./investigate.js";
 import { buildCoverageReport, loadCoverageConfig, renderCoverageAgent } from "./coverage.js";
 import { buildDriftReport, renderDriftAgent } from "./drift.js";
 const ASSETS = assetsDir(import.meta.url);
@@ -39,6 +40,13 @@ export function registerSpec(server, opts = {}) {
         level: z.union([z.literal(0), z.literal(1), z.literal(2), z.literal(3)]).optional(),
         reason: z.string().optional(),
     }, async (args) => text(handleLevel(args)));
+    add("lawbook_investigate", "Rank bug origins from the graph. Pass stackTrace or symptom. Returns suspects with reasons — evidence, not a verdict.", {
+        projectPath: z.string(),
+        stackTrace: z.string().optional(),
+        symptom: z.string().optional(),
+        hintPaths: z.array(z.string()).optional(),
+        maxSuspects: z.number().int().min(1).max(25).optional(),
+    }, async (args) => text(formatInvestigateResult(await investigate(args))));
     add("lawbook_validate", "Validate a change's proposal, tasks, and delta specs before build or sync.", { projectPath: z.string(), change: z.string() }, async ({ projectPath, change }) => text(specValidate(projectPath, change)));
     add("lawbook_sync", "Promote a change's delta specs into canonical lawbook/specs/ without archiving.", { projectPath: z.string(), change: z.string() }, async ({ projectPath, change }) => text(specSync(projectPath, change)));
     add("lawbook_archive", "Sync a change into canonical specs, then move it under changes/archive/.", {

package/dist/modules/lawbook/stack-parse.js

@@ -0,0 +1,135 @@
+import path from "node:path";
+const V8_NAMED = /^\s*at\s+(?:async\s+)?(?:(.+?)\s+\()?([^\s()]+):(\d+):(\d+)\)?\s*$/;
+const V8_ANON = /^\s*at\s+([^\s()]+):(\d+):(\d+)\s*$/;
+const PY_FRAME = /^\s*File\s+"([^"]+)",\s*line\s+(\d+)(?:,\s*in\s+(.+))?\s*$/;
+function isExternal(rawPath) {
+    const n = rawPath.replace(/\\/g, "/");
+    return (n.includes("node_modules/") ||
+        n.includes("node:internal") ||
+        n.startsWith("node:") ||
+        n.includes("/lib/python") ||
+        n.includes("site-packages/"));
+}
+/**
+ * Map `dist/foo.js` → `src/foo.ts` when the basename matches (no silent guess
+ * beyond that convention).
+ */
+export function mapDistToSrc(rel) {
+    const n = rel.replace(/\\/g, "/");
+    if (!n.startsWith("dist/"))
+        return n;
+    const base = path.basename(n, path.extname(n));
+    return `src/${base}.ts`;
+}
+/**
+ * Normalize an absolute or relative trace path to a project-relative path.
+ *
+ * @param projectPath - Project root used to strip prefixes.
+ * @param rawPath - Path as it appears in the trace.
+ */
+export function normalizeTracePath(projectPath, rawPath) {
+    let p = rawPath.replace(/\\/g, "/");
+    const root = projectPath.replace(/\\/g, "/");
+    if (p.startsWith(root + "/"))
+        p = p.slice(root.length + 1);
+    if (p.startsWith("file://")) {
+        try {
+            p = decodeURIComponent(new URL(p).pathname);
+            if (p.startsWith(root + "/"))
+                p = p.slice(root.length + 1);
+        }
+        catch {
+            /* keep raw */
+        }
+    }
+    p = p.replace(/^\.\//, "");
+    p = mapDistToSrc(p);
+    return p;
+}
+function parseV8Line(line, projectPath) {
+    const named = V8_NAMED.exec(line);
+    if (named) {
+        const rawPath = named[2];
+        if (isExternal(rawPath))
+            return { raw: line.trim(), reason: "external" };
+        const fn = named[1]?.trim() ?? "";
+        const file = normalizeTracePath(projectPath, rawPath);
+        return { fn, file, line: Number(named[3]), rawPath };
+    }
+    const anon = V8_ANON.exec(line);
+    if (anon) {
+        const rawPath = anon[1];
+        if (isExternal(rawPath))
+            return { raw: line.trim(), reason: "external" };
+        return {
+            fn: "",
+            file: normalizeTracePath(projectPath, rawPath),
+            line: Number(anon[2]),
+            rawPath,
+        };
+    }
+    return null;
+}
+function parsePythonLines(lines, projectPath) {
+    const pyFrames = [];
+    const unresolved = [];
+    for (const line of lines) {
+        const m = PY_FRAME.exec(line);
+        if (!m)
+            continue;
+        const rawPath = m[1];
+        if (isExternal(rawPath)) {
+            unresolved.push({ raw: line.trim(), reason: "external" });
+            continue;
+        }
+        pyFrames.push({
+            fn: m[3]?.trim() ?? "",
+            file: normalizeTracePath(projectPath, rawPath),
+            line: Number(m[2]),
+            rawPath,
+        });
+    }
+    // Python traces list shallow→deep; invert to deepest-first like V8.
+    pyFrames.reverse();
+    return { frames: pyFrames, unresolved, format: "python" };
+}
+/**
+ * Parse a V8 (Node) or Python stack trace into own-project frames.
+ *
+ * @param projectPath - Project root for path normalization.
+ * @param stackTrace - Raw stack trace text.
+ */
+export function parseStackTrace(projectPath, stackTrace) {
+    const lines = stackTrace.split("\n");
+    const pyProbe = lines.some((l) => PY_FRAME.test(l));
+    if (pyProbe)
+        return parsePythonLines(lines, projectPath);
+    const frames = [];
+    const unresolved = [];
+    let sawV8 = false;
+    for (const line of lines) {
+        const parsed = parseV8Line(line, projectPath);
+        if (!parsed)
+            continue;
+        sawV8 = true;
+        if ("reason" in parsed)
+            unresolved.push(parsed);
+        else
+            frames.push(parsed);
+    }
+    if (!sawV8 && stackTrace.trim()) {
+        for (const line of lines) {
+            if (line.trim())
+                unresolved.push({ raw: line.trim(), reason: "unparseable" });
+        }
+        return { frames: [], unresolved, format: "unknown" };
+    }
+    return { frames, unresolved, format: "v8" };
+}
+/** Extract a simple method name from `Class.method` frames. */
+export function frameSymbolName(frame) {
+    if (!frame.fn)
+        return "";
+    const dot = frame.fn.lastIndexOf(".");
+    return dot >= 0 ? frame.fn.slice(dot + 1) : frame.fn;
+}

package/dist/shared/exposure.js

@@ -20,6 +20,7 @@ export const MINIMAL_OMIT = new Set([
     "lawbook_archive",
     "lawbook_list",
     "lawbook_level",
+    "lawbook_investigate",
     "init_project",
     "scaffold",
     "configure_agent",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esneiderbravo/speclaw",
-  "version": "0.3.12",
+  "version": "0.3.13",
   "publishConfig": {
     "access": "public"
   },