@esneiderbravo/speclaw 0.3.12 → 0.4.0

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) => {