@esneiderbravo/speclaw 2.0.8 → 2.0.10

package/dist/modules/compass/query.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
-import { openDb, indexExists } from "./db.js";
+import { openDb, indexExists, FILE_NODE_KIND } from "./db.js";
+import { BUILTIN_SQL_LIST } from "./indexer.js";
 import { getEmbedder, fromBlob, cosine } from "./embedder.js";
 import { loadAffectedConfig, filterFilesForTarget, matchGlobalFiles } from "./affected-config.js";
 function requireIndex(projectPath) {
@@ -32,8 +33,8 @@ export function search(projectPath, query, limit = 25) {
         const rows = db
             .prepare(`SELECT s.name, s.kind, f.path AS file, s.start_line AS line, s.signature
          FROM nodes s JOIN files f ON f.id = s.file_id
-         WHERE s.name LIKE ? ESCAPE '\\'
-            OR (? != '' AND f.path LIKE ? ESCAPE '\\')
+         WHERE s.kind <> '${FILE_NODE_KIND}'
+           AND (s.name LIKE ? ESCAPE '\\' OR (? != '' AND f.path LIKE ? ESCAPE '\\'))
          ORDER BY (s.name = ?) DESC, length(s.name) ASC, f.path ASC, s.start_line ASC
          LIMIT ?`)
             .all(`%${escapeLike(query)}%`, normalized, pathPattern, query, limit);
@@ -129,15 +130,18 @@ function resolveIndexedFile(db, projectPath, query) {
         return { status: "ambiguous", basename: normalized, files: suffix };
     return { status: "none" };
 }
-/** Definitions in one indexed file, ordered by source position. */
-function fileSymbols(db, file) {
+/**
+ * Nodes in one indexed file, ordered by source position: the visible
+ * definitions, or with `fileNode` only its file-owner node.
+ */
+function fileSymbols(db, file, fileNode = false) {
     return db
         .prepare(`SELECT s.id, s.name, s.kind, s.start_line, s.end_line, s.start_byte, s.end_byte,
               s.signature, f.path AS file
        FROM nodes s JOIN files f ON f.id = s.file_id
-       WHERE f.path = ?
+       WHERE f.path = ? AND (s.kind = '${FILE_NODE_KIND}') = ?
        ORDER BY s.start_line ASC, s.id ASC`)
-        .all(file);
+        .all(file, fileNode ? 1 : 0);
 }
 /** Symbols defined in `files`, stable across files. Empty when none exist. */
 function symbolsInFiles(db, files) {
@@ -147,7 +151,7 @@ function symbolsInFiles(db, files) {
     return db
         .prepare(`SELECT s.name, s.kind, f.path AS file, s.start_line AS line, s.signature
        FROM nodes s JOIN files f ON f.id = s.file_id
-       WHERE f.path IN (${placeholders})
+       WHERE f.path IN (${placeholders}) AND s.kind <> '${FILE_NODE_KIND}'
        ORDER BY f.path ASC, s.start_line ASC, s.name ASC`)
         .all(...files);
 }
@@ -171,24 +175,43 @@ function pickPrimary(symbols) {
  * `otherMatches` (same-name siblings, or the rest of a file).
  */
 function assembleExplore(db, projectPath, best, others) {
+    // Covers: req~compass-mcp-surface~1
+    // Resolved callees only, one row per target node at its first call line, so
+    // unresolved names (builtins, member calls) never crowd out project callees.
     const callees = db
-        .prepare(`SELECT e.dst_name AS name, e.line, f.path AS file
-       FROM edges e LEFT JOIN nodes s ON s.id = e.dst_node_id
-       LEFT JOIN files f ON f.id = s.file_id
+        .prepare(`SELECT s.name AS name, MIN(e.line) AS line, f.path AS file
+       FROM edges e JOIN nodes s ON s.id = e.dst_node_id
+       JOIN files f ON f.id = s.file_id
        WHERE e.src_node_id = ? AND e.kind = 'call'
-       ORDER BY e.line`)
+       GROUP BY s.id
+       ORDER BY line, s.id`)
         .all(best.id);
-    // Callers: match both the resolved edge AND any call by this name, so
-    // dynamic dispatch (a method/function called by name across sites) is not
-    // missed. Over-approximates conservatively — the point of a blast radius.
+    const unresolved = db
+        .prepare(`SELECT e.dst_name AS name, COUNT(*) AS n
+       FROM edges e
+       WHERE e.src_node_id = ? AND e.kind = 'call' AND e.dst_node_id IS NULL
+       GROUP BY e.dst_name
+       ORDER BY n DESC, e.dst_name ASC`)
+        .all(best.id);
+    // Callers: match both the resolved edge AND any non-member (`is_member = 0`)
+    // call by this name, so dynamic dispatch (a function called by name across sites) is not
+    // missed. Over-approximates conservatively — the point of a blast radius. A
+    // builtin global name (`test`, `fetch`) matches by name only within the
+    // definition's own file. A caller outside any definition is its file-owner
+    // node (`kind: "file"`).
     const callers = db
         .prepare(`SELECT DISTINCT owner.name AS name, owner.kind AS kind, f.path AS file, e.line
        FROM edges e
        JOIN nodes owner ON owner.id = e.src_node_id
        JOIN files f ON f.id = owner.file_id
-       WHERE (e.dst_node_id = ? OR e.dst_name = ?) AND e.kind = 'call'
+       WHERE (e.dst_node_id = ? OR (
+               e.dst_name = ? AND e.is_member = 0
+               AND (e.dst_name NOT IN (${BUILTIN_SQL_LIST})
+                    OR e.src_file_id = (SELECT file_id FROM nodes WHERE id = ?))
+             ))
+         AND e.kind = 'call'
        ORDER BY f.path, e.line`)
-        .all(best.id, best.name);
+        .all(best.id, best.name, best.id);
     return {
         found: true,
         symbol: {
@@ -200,7 +223,11 @@ function assembleExplore(db, projectPath, best, others) {
             signature: best.signature,
             source: readSource(projectPath, best.file, best.start_byte, best.end_byte),
         },
-        callees: callees.map((c) => ({ name: c.name, file: c.file ?? undefined, line: c.line })),
+        callees: callees.map((c) => ({ name: c.name, file: c.file, line: c.line })),
+        unresolvedCallees: {
+            count: unresolved.reduce((sum, u) => sum + Number(u.n), 0),
+            sample: unresolved.slice(0, 10).map((u) => u.name),
+        },
         callers,
         otherMatches: others.length > 0
             ? others.map((m) => ({
@@ -215,14 +242,23 @@ function assembleExplore(db, projectPath, best, others) {
 }
 /**
  * Name miss: resolve a file path to one symbol, or list symbols when the
- * basename is ambiguous or the file defines nothing. A non-unique suffix
- * falls through to {@link search}, which also matches `files.path`.
+ * basename is ambiguous or the file defines nothing. A file with no visible
+ * symbol resolves to its file-owner node (the indexer gives every symbol-less
+ * file one); a file with no node at all reports that it has no symbols. A non-unique suffix falls through to {@link search}, which also
+ * matches `files.path`.
  */
 function exploreWhenNameMisses(db, projectPath, query) {
-    // Covers: req~explore-file-path~1
+    // Covers: req~explore-file-path~2
     const resolved = resolveIndexedFile(db, projectPath, query);
     if (resolved.status === "one") {
         const symbols = fileSymbols(db, resolved.file);
+        const owner = symbols.length === 0 ? fileSymbols(db, resolved.file, true)[0] : undefined;
+        if (owner) {
+            return {
+                ...assembleExplore(db, projectPath, owner, []),
+                message: `Path "${resolved.file}" declares no symbols; resolved to its file-owner node.`,
+            };
+        }
         if (symbols.length === 0) {
             const near = search(projectPath, query, 10);
             return {
@@ -276,7 +312,7 @@ export function explore(projectPath, query) {
             .prepare(`SELECT s.id, s.name, s.kind, s.start_line, s.end_line, s.start_byte, s.end_byte,
                 s.signature, f.path AS file
          FROM nodes s JOIN files f ON f.id = s.file_id
-         WHERE s.name = ?
+         WHERE s.name = ? AND s.kind <> '${FILE_NODE_KIND}'
          ORDER BY s.kind = 'function' DESC, s.kind = 'class' DESC
          LIMIT 10`)
             .all(query);
@@ -391,6 +427,12 @@ export function impact(projectPath, symbolOrOpts, maxDepth = 4) {
         for (const d of definitions) {
             seedArgs.push(d.nodeId, d.name);
         }
+        // Covers: req~impact-id-first~1
+        // A member call (`is_member` 1 or 2) never matches by name: `items.push()` is
+        // not a call to a project function named `push`, and a call on an import
+        // binding (2) counts only through the id resolveEdges gave it, so a package
+        // receiver (`path.parse()`) never reaches a project `parse`. A builtin global name
+        // (`test`, `fetch`) matches by name only within the frontier node's file.
         // Sticky by_name: MAX(frontier.by_name, CASE WHEN edge unresolved THEN 1 ELSE 0).
         // Import edges that resolve to ANY node in the frontier node's file count as hits.
         const sql = `
@@ -412,7 +454,11 @@ export function impact(projectPath, symbolOrOpts, maxDepth = 4) {
           AND (
             (e.kind = 'call' AND (
               e.dst_node_id = f.node_id
-              OR (e.dst_node_id IS NULL AND e.dst_name = f.node_name)
+              OR (
+                e.dst_node_id IS NULL AND e.is_member = 0 AND e.dst_name = f.node_name
+                AND (e.dst_name NOT IN (${BUILTIN_SQL_LIST})
+                     OR e.src_file_id = (SELECT file_id FROM nodes WHERE id = f.node_id))
+              )
             ))
             OR (
               e.kind = 'import'
@@ -536,7 +582,7 @@ function resolveImpactSeeds(db, opts, seedFiles, warnings) {
         const rows = db
             .prepare(`SELECT n.id AS nodeId, n.name, f.path AS file, n.start_line AS line
          FROM nodes n JOIN files f ON f.id = n.file_id
-         WHERE n.name = ?
+         WHERE n.name = ? AND n.kind <> '${FILE_NODE_KIND}'
          ORDER BY n.kind = 'function' DESC, n.kind = 'class' DESC, n.id ASC
          LIMIT 50`)
             .all(opts.symbol);

package/dist/modules/compass/register.js

@@ -151,7 +151,7 @@ export function registerCompass(server, opts = {}) {
     });
     defineAliasTool(server, {
         name: "compass_affected_tests",
-        description: "Deprecated alias — use compass_diff_context or explore.",
+        description: "Deprecated alias — use compass_diff_context or explore; command may be null.",
         inputSchema: {
             projectPath: z.string(),
             files: z.array(z.string()).optional(),

package/dist/modules/compass/visualize.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { openDb, indexExists } from "./db.js";
+import { openDb, indexExists, FILE_NODE_KIND } from "./db.js";
 /**
  * Build the graph payload from the Compass index: nodes (definitions) and the
  * resolved call links between them. With a focus node, returns its neighborhood
@@ -17,11 +17,13 @@ export function graphData(projectPath, opts = {}) {
     try {
         const allNodes = db
             .prepare(`SELECT n.id, n.name, n.kind, f.path AS file, n.start_line AS line
-         FROM nodes n JOIN files f ON f.id = n.file_id`)
+         FROM nodes n JOIN files f ON f.id = n.file_id
+         WHERE n.kind <> '${FILE_NODE_KIND}'`)
             .all();
         const allEdges = db
             .prepare(`SELECT src_node_id AS s, dst_node_id AS t FROM edges
-         WHERE kind = 'call' AND dst_node_id IS NOT NULL AND src_node_id IS NOT NULL`)
+         WHERE kind = 'call' AND dst_node_id IS NOT NULL AND src_node_id IS NOT NULL
+           AND src_node_id NOT IN (SELECT id FROM nodes WHERE kind = '${FILE_NODE_KIND}')`)
             .all();
         // adjacency (undirected) + degree
         const adj = new Map();

package/dist/modules/cortex/brief.js

@@ -57,7 +57,9 @@ export function briefForStage(stage) {
                 role: "archiver",
                 agentPath: "ai-specs/agents/archiver.md",
                 skillHints: ["sync", "archive"],
-                nextOps: ["advance"],
+                // A successful `lawbook_change` archive completes the harness itself;
+                // no Cortex op follows (confirm `done` with `status`).
+                nextOps: [],
             };
         case "done":
         case null:

package/dist/modules/cortex/harness.js

@@ -12,6 +12,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { GATED_STAGES, compassGateError, compassGateWarning, evaluateCompassGate, readCompassGateMode, } from "./compass-gate.js";
 import { buildStatusSummary } from "./status.js";
+import { resolveChangeDir } from "./paths.js";
+export { resolveChangeDir } from "./paths.js";
 // Harness types live in the leaf `types.ts` so `compass-gate.ts` can use them
 // without importing this file back (no file-level import cycle).
 export { HARNESS_STAGES, } from "./types.js";
@@ -21,7 +23,8 @@ function specRoot(projectPath) {
     return path.join(projectPath, "lawbook");
 }
 function changeDir(projectPath, change) {
-    return path.join(specRoot(projectPath), "changes", change);
+    return (resolveChangeDir(projectPath, change)?.dir ??
+        path.join(specRoot(projectPath), "changes", change));
 }
 function harnessPath(projectPath, change) {
     return path.join(changeDir(projectPath, change), "harness.json");
@@ -30,11 +33,11 @@ function nowIso() {
     return new Date().toISOString();
 }
 function requireChangeDir(projectPath, change) {
-    const dir = changeDir(projectPath, change);
-    if (!fs.existsSync(dir)) {
+    const resolved = resolveChangeDir(projectPath, change);
+    if (!resolved) {
         throw new Error(`change "${change}" not found under lawbook/changes/`);
     }
-    return dir;
+    return resolved;
 }
 /**
  * Read confirmed ceremony level from change.json without importing lawbook.
@@ -120,11 +123,17 @@ function allowedAdvance(from, level, verdict) {
  */
 export function handleHarness(args) {
     const { projectPath, change, harnessOp } = args;
-    requireChangeDir(projectPath, change);
+    const resolved = requireChangeDir(projectPath, change);
     if (harnessOp === "status") {
         const state = readHarness(projectPath, change);
         return { summary: state ? buildStatusSummary(projectPath, state) : null, state };
     }
+    // An archived change is read-only: reject mutating ops before any write.
+    // Covers: req~harness-archive-completes~1
+    if (resolved.archived) {
+        throw new Error(`change ${change} is archived (${path.relative(projectPath, resolved.dir)}); ` +
+            `Cortex ops are read-only`);
+    }
     if (harnessOp === "start") {
         const existing = readHarness(projectPath, change);
         if (existing && existing.stage !== "done") {
@@ -258,6 +267,43 @@ export function handleHarness(args) {
     }
     throw new Error(`unknown harnessOp '${String(harnessOp)}'`);
 }
+/**
+ * Complete a change's harness as part of archiving: move stage `archiving` to
+ * `done` with one history entry. Called by the lawbook archive **before** the
+ * change directory moves, so a crash cannot leave the harness stuck; the
+ * returned `restore` puts the old bytes back if the move fails. A missing
+ * harness or one already `done` is left untouched.
+ *
+ * @param projectPath - Absolute path to the project root.
+ * @param change - Change name (an active change).
+ * @param note - History note naming the archive.
+ * @returns Whether the harness was completed and how to undo it.
+ * @throws If the harness is in any other stage (the archive gate prevents this).
+ */
+// Covers: req~harness-archive-completes~1
+export function completeHarnessOnArchive(projectPath, change, note) {
+    const noop = { completed: false, restore: () => { } };
+    const p = harnessPath(projectPath, change);
+    if (!fs.existsSync(p))
+        return noop;
+    const original = fs.readFileSync(p, "utf8");
+    const state = JSON.parse(original);
+    if (state.stage === "done")
+        return noop;
+    if (state.stage !== "archiving") {
+        throw new Error(`harness stage is ${state.stage} — advance to archiving before archive (${change})`);
+    }
+    const next = {
+        ...state,
+        stage: "done",
+        history: [
+            ...state.history,
+            { at: nowIso(), from: "archiving", to: "done", op: "advance", note },
+        ],
+    };
+    fs.writeFileSync(p, JSON.stringify(next, null, 2) + "\n");
+    return { completed: true, restore: () => fs.writeFileSync(p, original) };
+}
 /**
  * Archive blockers derived from harness verdicts.
  *

package/dist/modules/cortex/paths.js

@@ -0,0 +1,39 @@
+/**
+ * Change-directory resolution shared by the Cortex harness and its status
+ * summary. A leaf module (no Cortex imports) so both can use it without an
+ * import cycle; Cortex never imports the lawbook module.
+ */
+import fs from "node:fs";
+import path from "node:path";
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Resolve a change name to its directory: the active `lawbook/changes/<name>/`
+ * when it exists, otherwise the newest `lawbook/changes/archive/<YYYY-MM-DD>-<name>/`
+ * (matched exactly, so `<date>-other-<name>` never matches `<name>`).
+ *
+ * @param projectPath - Absolute path to the project root.
+ * @param change - Change name.
+ * @returns The directory and whether it is archived, or null when neither exists.
+ */
+// Covers: req~harness-archive-completes~1
+export function resolveChangeDir(projectPath, change) {
+    const active = path.join(projectPath, "lawbook", "changes", change);
+    if (fs.existsSync(active))
+        return { dir: active, archived: false };
+    const archiveRoot = path.join(projectPath, "lawbook", "changes", "archive");
+    let entries;
+    try {
+        entries = fs.readdirSync(archiveRoot);
+    }
+    catch {
+        return null;
+    }
+    const re = new RegExp(`^\\d{4}-\\d{2}-\\d{2}-${escapeRegExp(change)}$`);
+    const newest = entries
+        .filter((e) => re.test(e))
+        .sort()
+        .at(-1);
+    return newest ? { dir: path.join(archiveRoot, newest), archived: true } : null;
+}

package/dist/modules/cortex/status.js

@@ -12,6 +12,7 @@ import path from "node:path";
 import { briefForStage } from "./brief.js";
 import { stageStartedAt } from "./compass-gate.js";
 import { OUTPUT_BUDGET, estimateTokens } from "../../shared/output-budget.js";
+import { resolveChangeDir } from "./paths.js";
 /** Interval used when the key is missing or invalid. */
 export const DEFAULT_STATUS_INTERVAL_MINUTES = 5;
 /**
@@ -84,7 +85,9 @@ export function readStatusIntervalMinutes(projectPath) {
     return DEFAULT_STATUS_INTERVAL_MINUTES;
 }
 function readTaskCounts(projectPath, change) {
-    const dir = path.join(projectPath, "lawbook", "changes", change);
+    // An archived change still reports its tasks from the archive directory.
+    const dir = resolveChangeDir(projectPath, change)?.dir ??
+        path.join(projectPath, "lawbook", "changes", change);
     for (const file of ["tasks.md", "record.md"]) {
         let text;
         try {

package/dist/modules/foundation/assets/docs/compass.template.md

@@ -34,6 +34,22 @@ a request, not whole files.
 | `compass_explore` | Read a node's verbatim source plus its callers and callees. The default before editing. Add `include: ["blast_radius"]` for what could break, or `to: <symbol>` for the call path between two nodes. |
 | `compass_diff_context` | Symbols, blast radius, and tests for a diff (working tree or a rev). |
 
+Callees list only references resolved to a project symbol; the rest are counted
+in `unresolvedCallees`. A call inside a test callback or a top-level import
+shows up as a caller of kind `file`, so tests written as bare `test(...)`
+blocks are still selected. The affected-test `command` is `null` (with
+`commandReason`) when no test is reachable; otherwise run it from the repository
+root, or use `commands` (one `{ cwd, command, files }` per package, with the
+runner detected from each `package.json`: vitest, jest, or `node --test`).
+Method calls on local variables and parameters (`svc.run()`) are not bound to a
+project method, so they do not appear as callers. Calls through an imported
+re-export barrel (`index.ts` holding `export * from "./lib/core"`) bind by
+name, preferring a definition under the barrel's directory.
+
+Compass uses index schema 11. speclaw 2.0.9 or older, including an MCP entry
+pinned at `@2.0.9`, rebuilds a schema-11 index from scratch (losing the
+embedding cache). Run `speclaw update` so the pinned MCP entry moves to 2.0.10.
+
 `compass_index` also takes `action: start|stop|status` to keep the index fresh
 automatically (a debounced incremental re-index on file change).
 

package/dist/modules/foundation/compile-laws.js

@@ -4,7 +4,7 @@ import { globError, isActiveLaw, readLawManifest, seedManifestFor, mergeSeedLaws
 import { parseLawsFromStandards } from "./laws-parse.js";
 import { agentsmdDialect, claudeRulesDialect, coderabbitDialect, copilotDialect, cursorMdcDialect, patchDelimited, } from "./dialects/index.js";
 import { detectConfiguredAgents } from "../../shared/agents.js";
-import { digestText, provenanceBlock, refreshLockfile } from "./lock.js";
+import { digestText, driftedStrictPaths, provenanceBlock, refreshLockfile } from "./lock.js";
 const DIALECTS = [
     claudeRulesDialect,
     cursorMdcDialect,
@@ -159,7 +159,21 @@ export function compileLaws(opts) {
         failed: [],
         lawCount: 0,
         draftCount: 0,
+        lockPreserved: [],
     };
+    // Snapshot drift before any rule artifact is written: compilation rewrites
+    // the speclaw regions of CLAUDE.md / AGENTS.md, which must not launder edits.
+    // An existing lock that cannot be read is reported and left untouched, never
+    // rebuilt from disk (that would launder drift); compilation itself proceeds.
+    let drifted = opts.drifted ?? [];
+    if (opts.drifted === undefined && opts.refreshLock !== false) {
+        try {
+            drifted = driftedStrictPaths(projectPath);
+        }
+        catch (err) {
+            report.lockError = err.message;
+        }
+    }
     const laws = mergeLawSources(projectPath);
     validateScopes(laws);
     report.lawCount = laws.filter(isActiveLaw).length;
@@ -185,11 +199,14 @@ export function compileLaws(opts) {
     if (agents.includes("claude"))
         ensureClaudeRulesSymlink(projectPath, report);
     // Covers: req~lock-refresh-update~1
-    try {
-        refreshLockfile(projectPath);
-    }
-    catch {
-        // Lock refresh must not fail compile; `speclaw laws lock` surfaces errors.
+    if (opts.refreshLock !== false && report.lockError === undefined) {
+        try {
+            report.lockPreserved = refreshLockfile(projectPath, { drifted }).preserved;
+        }
+        catch (err) {
+            // refreshLockfile throws before writing; the caller surfaces lockError.
+            report.lockError = err.message;
+        }
     }
     return report;
 }

package/dist/modules/foundation/doctor.js

@@ -557,6 +557,15 @@ function specsOrphansCheck(projectPath) {
         remedy: `speclaw lawbook archive ${active[0]}`,
     };
 }
+/**
+ * Fix hint for an unreadable or invalid `speclaw.lock`. `laws lock` refuses
+ * such a lock, and deleting it re-baselines every pinned file, silently
+ * accepting any pending drift — so that is offered only as a last resort.
+ */
+export const UNREADABLE_LOCK_REMEDY = "resolve the merge conflict in speclaw.lock or restore it from git " +
+    "(git checkout -- speclaw.lock); upgrade speclaw if the lockfileVersion is newer. " +
+    "Last resort: delete it and run speclaw laws lock — this re-baselines every " +
+    "pinned file and accepts any pending drift";
 function integrityChecks(projectPath) {
     // Covers: req~doctor-integrity~1
     const out = [];
@@ -591,7 +600,8 @@ function integrityChecks(projectPath) {
                 title: "rule lockfile",
                 status: "error",
                 detail: err.message,
-                remedy: "speclaw laws lock",
+                // `laws lock` refuses an unreadable lock, so point at repairing it.
+                remedy: UNREADABLE_LOCK_REMEDY,
             });
         }
     }