@esneiderbravo/speclaw 2.0.18 → 2.0.20

package/dist/modules/lawbook/investigate.js

@@ -16,7 +16,50 @@ const WEIGHTS = {
     "semantic-match": 10,
     "hint-path": 8,
     "recently-changed": 10,
+    "test-reachable": 20,
+    leaf: 10,
 };
+/** Test files: their frames show where a failure surfaced, never its cause. */
+const TEST_FILE_RE = /(^|\/)(tests?|__tests__|spec)\/|\.(test|spec)\.[cm]?[jt]sx?$|(^|\/)test_[^/]+\.py$/;
+/** Call depth and node cap for the walk from the failing test's file. */
+const REACH_DEPTH = 8;
+const REACH_CAP = 80;
+/**
+ * Every project symbol reachable by calls from `files` (a failing test, a
+ * stack frame's file), breadth-first, with its depth and whether it calls
+ * anything else in the project. Only this code can make that test fail.
+ */
+function reachableFrom(projectPath, files) {
+    const out = new Map();
+    for (const seed of files) {
+        const root = explore(projectPath, seed);
+        if (!root.found)
+            continue;
+        let frontier = (root.callees ?? []).filter((c) => c.file).map((c) => ({ ...c, depth: 1 }));
+        while (frontier.length && out.size < REACH_CAP) {
+            const next = [];
+            for (const c of frontier) {
+                const key = `${c.file}:${c.name}`;
+                if (out.has(key) || out.size >= REACH_CAP)
+                    continue;
+                const ex = explore(projectPath, c.name);
+                const callees = (ex.callees ?? []).filter((x) => x.file);
+                out.set(key, {
+                    name: c.name,
+                    file: c.file,
+                    line: c.line,
+                    depth: c.depth,
+                    leaf: callees.length === 0,
+                    from: seed,
+                });
+                if (c.depth < REACH_DEPTH)
+                    next.push(...callees.map((x) => ({ ...x, depth: c.depth + 1 })));
+            }
+            frontier = next;
+        }
+    }
+    return out;
+}
 function resolveAtLine(projectPath, file, line) {
     if (!indexExists(projectPath))
         return null;
@@ -94,7 +137,7 @@ function scanArchivedRootCauses(projectPath, symbol) {
  * Rank likely bug origins from the code graph and git history.
  */
 export async function investigate(args) {
-    const maxSuspects = args.maxSuspects ?? 8;
+    const maxSuspects = args.maxSuspects ?? 5;
     const degraded = [];
     const hintPaths = (args.hintPaths ?? []).map((p) => p.replace(/^\.\//, ""));
     if (!args.stackTrace?.trim() && !args.symptom?.trim()) {
@@ -138,6 +181,10 @@ export async function investigate(args) {
             };
         }
         frames.forEach((frame, idx) => {
+            // A test's own frame is where the failure surfaced, not where it was
+            // caused: it seeds the reachable walk below but is never a suspect.
+            if (TEST_FILE_RE.test(frame.file))
+                return;
             const dist = idx;
             const atLine = resolveAtLine(args.projectPath, frame.file, frame.line);
             const symName = atLine?.name ?? frameSymbolName(frame) ?? frame.fn;
@@ -189,10 +236,38 @@ export async function investigate(args) {
             }
         });
     }
-    if (args.symptom?.trim() && candidates.size === 0) {
+    // A failing test (hinted, or a frame's file) bounds the search: only code it
+    // reaches can fail it, so look-alike symbols elsewhere never outrank that path.
+    const reach = reachableFrom(args.projectPath, [
+        ...new Set([...hintPaths, ...frames.map((f) => f.file)]),
+    ]);
+    for (const [key, r] of reach) {
+        addCandidate(candidates, key, {
+            name: r.name,
+            kind: "function",
+            file: r.file,
+            startLine: r.line,
+            reason: "test-reachable",
+            detail: `reached from ${r.from} in ${r.depth} call(s)`,
+            distanceFromFrame: r.depth,
+            callerCount: callerCount(args.projectPath, r.name),
+        });
+        if (r.leaf) {
+            const c = candidates.get(key);
+            addCandidate(candidates, key, {
+                ...c,
+                reason: "leaf",
+                detail: "calls nothing else in the project",
+            });
+        }
+    }
+    if (args.symptom?.trim() && (candidates.size === 0 || reach.size > 0)) {
         try {
             const hits = await recall(args.projectPath, args.symptom, 15);
             for (const h of hits) {
+                // With a reachable set, a semantic hit only corroborates code on it.
+                if (reach.size > 0 && !candidates.has(`${h.file}:${h.name}`))
+                    continue;
                 addCandidate(candidates, `${h.file}:${h.name}`, {
                     name: h.name,
                     kind: h.kind,
@@ -295,7 +370,11 @@ export async function investigate(args) {
             }
         }
     }
-    let suspects = [...candidates.values()]
+    let suspects = [...candidates.entries()]
+        .filter(([key, c]) => reach.size === 0 ||
+        reach.has(key) ||
+        c.reasons.some((r) => r.reason === "stack-frame" || r.reason === "frame-caller"))
+        .map(([, c]) => c)
         .map((c) => ({
         name: c.name,
         kind: c.kind,
@@ -345,7 +424,9 @@ export async function investigate(args) {
             : "No matching archived bugfix root cause found.");
     return {
         suspects,
-        unresolvedFrames,
+        // Runtime and dependency frames are excluded by design; listing each one
+        // only spends the reader's tokens.
+        unresolvedFrames: unresolvedFrames.filter((f) => f.reason !== "external"),
         degraded: [...new Set(degraded)],
         guidance,
         inputSymptom: args.symptom ?? args.stackTrace?.split("\n")[0]?.trim(),

package/dist/modules/lawbook/levels.js

@@ -13,11 +13,11 @@ export const DEFAULT_THRESHOLDS = {
     modulesTouched: [0, 2, 4, 6],
     affectedTests: [0, 1, 2, 4],
     blastRadiusNodes: [0, 1, 3, 5],
-    publicApi: 4,
+    publicApi: 5,
     globalFile: 5,
     hotspot: 3,
     hotspotFloor: 0.7,
-    cuts: [3, 8, 15],
+    cuts: [5, 16, 25],
     globalGlobs: [
         "package.json",
         "package-lock.json",
@@ -29,6 +29,8 @@ export const DEFAULT_THRESHOLDS = {
     docGlobs: ["**/*.md", "docs/**", "assets/**"],
     moduleRoots: ["src"],
 };
+/** Commits in the hotspot window a file needs before it can count as a hotspot. */
+const MIN_HOTSPOT_COMMITS = 3;
 const BUCKETS = {
     filesTouched: [1, 3, 10, Infinity],
     modulesTouched: [1, 2, 4, Infinity],
@@ -301,7 +303,11 @@ export function gatherSignals(projectPath, targets, t = DEFAULT_THRESHOLDS) {
         }
         try {
             const hs = hotspots(projectPath, { days: 90, sortBy: "combined", limit: 200 });
-            const byFile = new Map(hs.hotspots.map((h) => [h.file, h.combinedScore]));
+            // The score is relative to the hottest file, so in a young repo any file
+            // is "the hottest"; only files with real churn count as hotspots.
+            const byFile = new Map(hs.hotspots
+                .filter((h) => h.activity.commits >= MIN_HOTSPOT_COMMITS)
+                .map((h) => [h.file, h.combinedScore]));
             let maxCombined = 0;
             for (const h of hs.hotspots)
                 maxCombined = Math.max(maxCombined, h.combinedScore);

package/dist/modules/lawbook/quick.js

@@ -6,8 +6,9 @@ import { scaffoldChange } from "./scaffold-change.js";
  * @param projectPath - Project root with `lawbook/`.
  * @param name - Change folder name (kebab-case).
  * @param targets - Optional paths/symbols used to propose the level (default empty → score 0).
+ * @param measured - A proposal already measured from `targets`, and who confirmed the level.
  */
-export function scaffoldQuick(projectPath, name, targets = { paths: [], symbols: [] }) {
+export function scaffoldQuick(projectPath, name, targets = { paths: [], symbols: [] }, measured = {}) {
     // quick always records level 0; if measurement says higher, still allow but note it.
     const quickRationale = (proposal) => proposal.level === null
         ? proposal.rationale
@@ -16,6 +17,8 @@ export function scaffoldQuick(projectPath, name, targets = { paths: [], symbols:
             : proposal.rationale;
     const r = scaffoldChange(projectPath, name, {
         targets,
+        proposal: measured.proposal,
+        confirmedBy: measured.confirmedBy,
         level: 0,
         recordProposal: (proposal) => ({ ...proposal, rationale: quickRationale(proposal) }),
         reason: (proposal) => proposal.level !== null && proposal.level > 0 ? "speclaw quick" : undefined,
@@ -23,7 +26,7 @@ export function scaffoldQuick(projectPath, name, targets = { paths: [], symbols:
         artifacts: ({ proposal }) => ({
             "record.md": `# ${name}
 
-**Level:** 0 (proposed: ${proposal.level ?? "n/a"}, confirmed by: human)
+**Level:** 0 (proposed: ${proposal.level ?? "n/a"}, confirmed by: ${measured.confirmedBy ?? "human"})
 **Why:** ${quickRationale(proposal)}
 
 ## What changes

package/dist/modules/lawbook/register.js

@@ -28,19 +28,21 @@ export function installWorkflow(projectPath, vars, report, opts) {
 /** Register the spec workflow MCP tools. */
 export function registerSpec(server, opts = {}) {
     const minimal = Boolean(opts.minimal);
-    const add = (name, description, inputSchema, handler) => {
+    const add = (name, description, inputSchema, handler, alwaysLoad = false) => {
         if (!shouldExpose(name, minimal))
             return;
-        defineTool(server, { name, description, inputSchema, handler });
+        defineTool(server, { name, description, inputSchema, handler, alwaysLoad });
     };
-    add("lawbook_change", "Lawbook lifecycle: init, list, draft, validate, sync, archive, level, coverage, drift.", lawbookChangeSchema, async (args) => text(handleLawbookChange(args)));
-    add("lawbook_investigate", "Rank bug origins from the graph. Pass stackTrace or symptom — evidence, not verdict.", {
+    add("lawbook_change", "Specs: draft before multi-module or public-API work, validate specs you write; level, sync, archive, list, coverage, drift.", lawbookChangeSchema, async (args) => text(handleLawbookChange(args)));
+    add("lawbook_investigate", "Use first on a bug, failing test, or stack trace: ranks likely origins from the graph.", {
         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))));
+    }, async (args) => text(formatInvestigateResult(await investigate(args))), 
+    // Bugs are the commonest task; deferred, agents read files to triage.
+    true);
     if (minimal || !aliasesEnabled())
         return;
     const aliasHandler = (alias, action) => async (args) => {

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

@@ -25,9 +25,7 @@ export function scaffoldChange(projectPath, name, opts) {
         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 proposal = opts.proposal ?? measureTargets(projectPath, targets);
     const level = typeof opts.level === "function" ? opts.level(proposal) : opts.level;
     const stored = opts.recordProposal ? opts.recordProposal(proposal) : proposal;
     const reason = typeof opts.reason === "function" ? opts.reason(proposal) : opts.reason;
@@ -52,7 +50,7 @@ export function scaffoldChange(projectPath, name, opts) {
         let confirmed = setCeremonyLevel(projectPath, name, {
             proposal: stored,
             level,
-            confirmedBy: "human",
+            confirmedBy: opts.confirmedBy ?? "human",
             reason,
         });
         if (opts.changeType) {
@@ -71,9 +69,13 @@ export function scaffoldChange(projectPath, name, opts) {
         files: [...Object.keys(files), "reports/README.md", "change.json"],
     };
 }
-const featureRecordMd = (name, level, proposal) => `# ${name}
+function measureTargets(projectPath, targets) {
+    const { thresholds } = loadCeremonyConfig(projectPath);
+    return proposeLevel(gatherSignals(projectPath, targets, thresholds), thresholds);
+}
+const featureRecordMd = (name, level, proposal, confirmedBy) => `# ${name}
 
-**Level:** ${level} (proposed: ${proposal.level ?? "n/a"}, confirmed by: human)
+**Level:** ${level} (proposed: ${proposal.level ?? "n/a"}, confirmed by: ${confirmedBy})
 **Why:** ${proposal.rationale}
 
 ## What changes
@@ -172,18 +174,19 @@ The system SHALL provide the behavior described in \`proposal.md\` for ${change}
  * @param level - Confirmed level, or `undefined` for no stubs.
  * @param proposal - Proposal quoted in `record.md`.
  * @param delta - Capability and starting content for the delta (levels 1–3).
+ * @param confirmedBy - Who confirmed the level, quoted in `record.md`.
  */
 export function featureStubs(name, level, proposal, delta = {
     capability: name,
     content: featureDeltaMd(name, name),
-}) {
+}, confirmedBy = "human") {
     const spec = { [`specs/${delta.capability}/spec.md`]: delta.content };
     switch (level) {
         case 0:
-            return { "record.md": featureRecordMd(name, 0, proposal) };
+            return { "record.md": featureRecordMd(name, 0, proposal, confirmedBy) };
         case 1:
             return {
-                "record.md": featureRecordMd(name, 1, proposal),
+                "record.md": featureRecordMd(name, 1, proposal, confirmedBy),
                 "tasks.md": featureTasksMd(name),
                 ...spec,
             };
@@ -211,7 +214,8 @@ export function featureStubs(name, level, proposal, delta = {
  *
  * @param projectPath - Project root with `lawbook/`.
  * @param name - Change folder name (kebab-case).
- * @param opts - Optional level, override reason, delta capability, and targets.
+ * @param opts - Optional level, override reason, delta capability, targets, a proposal
+ *   already measured from them, and who confirmed the level.
  * @throws When `capability` is not kebab-case (plus every `scaffoldChange` refusal).
  */
 export function scaffoldFeature(projectPath, name, opts = {}) {
@@ -231,9 +235,11 @@ export function scaffoldFeature(projectPath, name, opts = {}) {
     return scaffoldChange(projectPath, name, {
         changeType: "feature",
         targets: opts.targets,
+        proposal: opts.proposal,
+        confirmedBy: opts.confirmedBy,
         level: opts.level,
         reason: opts.reason,
         reportsReadme: `# Reports — ${name}\n\nAdd at least one discipline report before archive.\n`,
-        artifacts: ({ level, proposal }) => featureStubs(name, level, proposal, { capability, content }),
+        artifacts: ({ level, proposal }) => featureStubs(name, level, proposal, { capability, content }, opts.confirmedBy),
     });
 }