@esneiderbravo/speclaw 0.3.7 → 0.3.9

package/README.md

@@ -129,6 +129,10 @@ tokenizer on this corpus — not a BPE dependency):
 ```bash
 speclaw budget          # human table
 speclaw budget --json   # machine-readable; used by the suite gate
+speclaw coverage        # requirement → impl → test coverage (TAP / table)
+speclaw coverage --json # machine-readable coverage report
+speclaw drift           # sealed spec ↔ code drift (default --fail-on semantic)
+speclaw drift --reseal  # photograph current bodies into lawbook/anchors/
 speclaw init --minimal  # omit setup/lifecycle MCP tools from registration
 ```
 

package/dist/cli/commands/coverage.js

@@ -0,0 +1,49 @@
+import { ui } from "../lib/ui.js";
+import { applyAdopt, buildCoverageReport, coverageExitCode, loadCoverageConfig, proposeAdopt, renderCoverageAgent, renderCoverageTable, renderCoverageTap, } from "../../modules/lawbook/coverage.js";
+/**
+ * Report requirement → impl → test coverage, or propose/apply id adoption.
+ *
+ * Flags: `--json`, `--tap`, `--adopt`, `--write`, `--change <name>`.
+ * Exit codes: 0 clean / no ids, 1 gated defects, 2 invocation error.
+ */
+export async function runCoverage(flags) {
+    const cwd = process.cwd();
+    if (flags.adopt) {
+        const proposals = proposeAdopt(cwd);
+        if (proposals.length === 0) {
+            ui.ok("Every requirement already has an identifier.");
+            return;
+        }
+        if (flags.write) {
+            const result = applyAdopt(cwd, proposals, { write: true });
+            ui.ok(`Wrote identifiers into ${result.written.length} file(s) (.bak backups kept).`);
+            for (const p of proposals) {
+                ui.plain(`  ${p.specPath}:${p.line}  ${p.title} → ${p.proposedId}${p.collision ? " (disambiguated)" : ""}`);
+            }
+            return;
+        }
+        ui.heading("coverage --adopt (dry run)");
+        for (const p of proposals) {
+            ui.plain(`  ${p.specPath}:${p.line}  ${p.title} → ${p.proposedId}${p.collision ? " (disambiguated)" : ""}`);
+        }
+        ui.plain();
+        ui.info(`Re-run with ${ui.code("--adopt --write")} to apply (backs up to .bak).`);
+        return;
+    }
+    const change = typeof flags.change === "string" ? flags.change : undefined;
+    const cfg = loadCoverageConfig(cwd);
+    const report = buildCoverageReport(cwd, { change, cfg });
+    if (flags.json) {
+        process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+    }
+    else if (flags.tap || !process.stdout.isTTY) {
+        process.stdout.write(renderCoverageTap(report) + "\n");
+    }
+    else {
+        ui.heading("speclaw coverage");
+        console.log(renderCoverageTable(report));
+        ui.plain();
+        console.log(renderCoverageAgent(report, true));
+    }
+    process.exitCode = coverageExitCode(report, cfg);
+}

package/dist/cli/commands/drift.js

@@ -0,0 +1,39 @@
+import { ui } from "../lib/ui.js";
+import { buildDriftReport, parseFailOn, renderDriftAgent, renderDriftTable, } from "../../modules/lawbook/drift.js";
+/**
+ * Report deterministic spec↔code drift, or reseal anchors from current bodies.
+ *
+ * Flags: `--json`, `--capability <name>`, `--fail-on <level>`, `--reverse`,
+ * `--reseal`, `--explain`. Default `--fail-on semantic`. Exit 0/1/2.
+ */
+export async function runDrift(flags) {
+    const cwd = process.cwd();
+    const failOn = parseFailOn(flags["fail-on"]);
+    if (failOn === null) {
+        ui.err(`--fail-on must be none, cosmetic, semantic, or any.`);
+        process.exitCode = 2;
+        return;
+    }
+    const capability = typeof flags.capability === "string" ? flags.capability : undefined;
+    const report = buildDriftReport(cwd, {
+        capability,
+        failOn,
+        reverse: Boolean(flags.reverse),
+        reseal: Boolean(flags.reseal),
+    });
+    if (flags.json) {
+        process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+    }
+    else if (!process.stdout.isTTY) {
+        process.stdout.write(renderDriftAgent(report) + "\n");
+    }
+    else {
+        ui.heading("speclaw drift");
+        console.log(renderDriftTable(report));
+        if (flags.explain) {
+            ui.plain();
+            console.log(renderDriftAgent(report, 50));
+        }
+    }
+    process.exitCode = report.summary.exitCode;
+}

package/dist/cli/commands/lawbook.js

@@ -56,6 +56,13 @@ export async function runSpec(flags) {
                 const r = specArchive(cwd, req(change, "spec archive <change>"), today());
                 ui.ok(`archived to ${r.archivedTo} (${r.promoted.length} spec(s) promoted)`);
                 r.promoted.forEach((p) => ui.info(`${r.created.includes(p) ? "created" : "updated"}: ${p}`));
+                for (const s of r.seals) {
+                    const msg = `sealed ${s.capability}: ${s.unique} unique / ${s.ambiguous} ambiguous / ${s.unresolved} unresolved → ${s.path}`;
+                    if (s.warned)
+                        ui.warn(msg + " (no resolvable anchors)");
+                    else
+                        ui.info(msg);
+                }
                 return;
             }
             default:

package/dist/cli/commands/update.js

@@ -92,6 +92,22 @@ const MIGRATIONS = [
         // scaffold → installHooks already rewrites .claude/settings.json when the
         // compiled hook shape changes; no extra run() step.
     },
+    {
+        version: "0.3.8",
+        describe: "Requirement coverage: speclaw coverage + lawbook_coverage + schema 5",
+        agentPrompt: "- Mention `speclaw coverage` / `lawbook_coverage` for requirement → impl → test coverage " +
+            "(ids like `req~name~1`, `// Covers:` comments). Compass schema is now 5 — reindex with " +
+            "`speclaw index`. Optionally add coverage.gateArchive / defaultNeeds under lawbook/config.yaml.\n" +
+            "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
+    },
+    {
+        version: "0.3.9",
+        describe: "Spec drift: speclaw drift + lawbook_drift + schema 6 dual hashes",
+        agentPrompt: "- Mention `speclaw drift` / `lawbook_drift` for sealed spec↔code drift " +
+            "(committed `lawbook/anchors/*.json`, dual body/norm hashes). Compass schema is now 6 — " +
+            "reindex with `speclaw index`, then `speclaw drift --reseal` once to photograph current bodies.\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/commands/verify.js

@@ -8,6 +8,7 @@ import { toMarkdown } from "../../modules/foundation/report-md.js";
 import { toSarif } from "../../modules/foundation/sarif.js";
 import { loadManifestForVerify } from "../../modules/foundation/laws.js";
 import { verifyLaws } from "../../modules/foundation/verify.js";
+import { driftFindingsForVerify } from "../../modules/lawbook/drift.js";
 const FORMATS = new Set(["text", "json", "sarif", "markdown"]);
 /**
  * `speclaw verify` — the CI orchestrator over {@link verifyLaws}. Formats and
@@ -45,6 +46,19 @@ export async function runVerify(flags) {
         engines: engines.length ? engines : undefined,
         lawIds: list(flags.law).length ? list(flags.law) : undefined,
     });
+    // Structural spec↔code drift (when anchors exist) contributes semantic/deleted
+    // findings into the same report stream used by SARIF / exit codes.
+    for (const f of driftFindingsForVerify(cwd)) {
+        report.findings.push({
+            lawId: f.ruleId,
+            severity: "error",
+            engine: "graph",
+            file: f.file,
+            line: f.line,
+            message: f.message,
+        });
+        report.summary.failed += 1;
+    }
     const sarifPath = typeof flags.sarif === "string" ? flags.sarif : undefined;
     const jsonPath = typeof flags.json === "string" ? flags.json : undefined;
     if (sarifPath) {

package/dist/cli/index.js

@@ -37,6 +37,8 @@ Lawbook (spec-driven workflow)
 Other
   doctor                   Verify the installation (--json, --offline, --strict)
   budget                   Measure always-on context cost (tools, skills, instructions)
+  coverage                 Requirement → impl → test coverage (--json, --tap, --adopt, --write)
+  drift                    Spec↔code drift (--json, --reseal, --reverse, --fail-on)
   telemetry status         Confirm speclaw ships no telemetry
   check                    Evaluate an action against the laws (hooks call this; --dry-run to preview)
   laws verify              Verify the deterministic dependency/graph laws against the index
@@ -60,6 +62,8 @@ const HEADER_COMMANDS = new Set([
     "agent",
     "doctor",
     "budget",
+    "coverage",
+    "drift",
     "telemetry",
     "index",
     "watch",
@@ -70,8 +74,9 @@ const HEADER_COMMANDS = new Set([
  * header-eligible command AND stdout is an interactive terminal (so pipes,
  * redirection, and CI stay clean — mirroring the color gate in `ui.ts`). A
  * forced-color signal counts as interactive so the header is exercisable in a
- * child process. `budget --json` and `doctor --json` are machine-consumed and
- * suppress the header.
+ * child process. `budget --json`, `doctor --json`, and `coverage` when emitting
+ * TAP/JSON (or when stdout is not a TTY) are machine-consumed and suppress the
+ * header.
  */
 function maybeHeader(cmd, flags) {
     if (!process.stdout.isTTY && process.env.FORCE_COLOR !== "1")
@@ -82,6 +87,10 @@ function maybeHeader(cmd, flags) {
         return;
     if (cmd === "doctor" && flags.json)
         return;
+    if (cmd === "coverage" && (flags.json || flags.tap))
+        return;
+    if (cmd === "drift" && flags.json)
+        return;
     header();
 }
 /** Run the handler for a single command. Returns when the command completes. */
@@ -126,6 +135,10 @@ async function dispatch(cmd, flags) {
             return (await import("./commands/doctor.js")).runDoctor(flags);
         case "budget":
             return (await import("./commands/budget.js")).runBudget(flags);
+        case "coverage":
+            return (await import("./commands/coverage.js")).runCoverage(flags);
+        case "drift":
+            return (await import("./commands/drift.js")).runDrift(flags);
         case "telemetry":
             return (await import("./commands/telemetry.js")).runTelemetry(flags);
         case "check":

package/dist/cli/lib/untrack.js

@@ -12,6 +12,7 @@ import { listTrackedPaths } from "../../shared/git.js";
  *
  * @param projectPath - Project root to inspect and address.
  */
+// Covers: req~agent-ide-committable~1, req~ai-specs-untrack-hint~1
 export function reportTrackedLocalContent(projectPath) {
     const tracked = listTrackedPaths(projectPath, ["ai-specs"]);
     if (!tracked.length)

package/dist/modules/compass/db.js

@@ -23,10 +23,13 @@ CREATE TABLE IF NOT EXISTS nodes (
   start_byte INTEGER NOT NULL,
   end_byte INTEGER NOT NULL,
   parent_id INTEGER,
-  signature TEXT
+  signature TEXT,
+  body_hash TEXT,
+  norm_hash TEXT
 );
 CREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes(name);
 CREATE INDEX IF NOT EXISTS idx_nodes_file ON nodes(file_id);
+CREATE INDEX IF NOT EXISTS idx_nodes_norm_hash ON nodes(norm_hash);
 -- edges: a reference from one node to a named target, resolved lazily.
 CREATE TABLE IF NOT EXISTS edges (
   id INTEGER PRIMARY KEY,
@@ -55,9 +58,50 @@ CREATE TABLE IF NOT EXISTS git_history_cache (
   payload TEXT NOT NULL,
   computed_at INTEGER NOT NULL
 );
+-- coverage_links: derived requirement-coverage directives from comment nodes.
+-- Spec items themselves are NOT persisted — always reparsed from disk.
+CREATE TABLE IF NOT EXISTS coverage_links (
+  id INTEGER PRIMARY KEY,
+  artifact_type TEXT NOT NULL,
+  name TEXT NOT NULL,
+  revision INTEGER NOT NULL,
+  kind TEXT NOT NULL,
+  file_path TEXT NOT NULL,
+  line INTEGER NOT NULL,
+  node_id INTEGER REFERENCES nodes(id) ON DELETE CASCADE,
+  source_type TEXT NOT NULL,
+  origin TEXT NOT NULL,
+  UNIQUE (artifact_type, name, revision, kind, file_path, line)
+);
+CREATE INDEX IF NOT EXISTS idx_cov_target ON coverage_links(artifact_type, name, revision);
+CREATE INDEX IF NOT EXISTS idx_cov_file ON coverage_links(file_path);
+CREATE INDEX IF NOT EXISTS idx_cov_node ON coverage_links(node_id);
+-- spec_anchors: projection of committed lawbook/anchors/*.json (source of truth on disk).
+CREATE TABLE IF NOT EXISTS spec_anchors (
+  id INTEGER PRIMARY KEY,
+  spec_id TEXT NOT NULL,
+  capability TEXT NOT NULL,
+  requirement_id TEXT NOT NULL,
+  scenario_id TEXT NOT NULL DEFAULT '',
+  anchor_kind TEXT NOT NULL,
+  symbol_name TEXT NOT NULL,
+  file_path TEXT,
+  node_id INTEGER REFERENCES nodes(id) ON DELETE SET NULL,
+  resolution TEXT NOT NULL,
+  content_hash TEXT,
+  raw_hash TEXT,
+  archived_at TEXT NOT NULL,
+  commit_sha TEXT,
+  source TEXT NOT NULL,
+  normalizer_version INTEGER NOT NULL DEFAULT 1,
+  UNIQUE (spec_id, requirement_id, scenario_id, anchor_kind, symbol_name)
+);
+CREATE INDEX IF NOT EXISTS idx_anchors_capability ON spec_anchors(capability);
+CREATE INDEX IF NOT EXISTS idx_anchors_symbol ON spec_anchors(symbol_name);
+CREATE INDEX IF NOT EXISTS idx_anchors_node ON spec_anchors(node_id);
 `;
 /** Schema version stamped into the `meta` table on first creation. */
-export const SCHEMA_VERSION = "4";
+export const SCHEMA_VERSION = "6";
 /** The stamped schema version, or null if the db predates versioning / has no meta table. */
 function readSchemaVersion(db) {
     try {
@@ -89,6 +133,8 @@ function isStale(db) {
 /** Drop every table (children first) so the current schema can be recreated cleanly. */
 function resetSchema(db) {
     db.exec(`
+    DROP TABLE IF EXISTS spec_anchors;
+    DROP TABLE IF EXISTS coverage_links;
     DROP TABLE IF EXISTS git_history_cache;
     DROP TABLE IF EXISTS node_embeddings;
     DROP TABLE IF EXISTS edges;
@@ -114,15 +160,61 @@ export function openDb(projectPath) {
     fs.mkdirSync(dir, { recursive: true });
     const db = new DatabaseSync(path.join(dir, "index.db"));
     db.exec("PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON;");
-    if (isStale(db))
+    const wiped = isStale(db);
+    if (wiped)
         resetSchema(db);
     db.exec(SCHEMA);
     const row = db.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get();
     if (!row) {
         db.prepare("INSERT INTO meta(key, value) VALUES ('schema_version', ?)").run(SCHEMA_VERSION);
     }
+    if (wiped) {
+        db.prepare("INSERT INTO meta(key, value) VALUES ('needs_reindex', '1') ON CONFLICT(key) DO UPDATE SET value = excluded.value").run();
+    }
+    // Projection from committed JSON — safe even when nodes are empty (node_id null).
+    rehydrateAnchors(db, projectPath);
     return db;
 }
+/**
+ * Rebuild `spec_anchors` from `lawbook/anchors/*.json`. Idempotent; called on
+ * every open so a wiped `.speclaw/` still sees committed seals.
+ */
+export function rehydrateAnchors(db, projectPath) {
+    const dir = path.join(projectPath, "lawbook", "anchors");
+    db.exec("DELETE FROM spec_anchors");
+    if (!fs.existsSync(dir))
+        return;
+    const ins = db.prepare(`INSERT OR REPLACE INTO spec_anchors(
+       spec_id, capability, requirement_id, scenario_id, anchor_kind, symbol_name,
+       file_path, node_id, resolution, content_hash, raw_hash, archived_at, commit_sha,
+       source, normalizer_version
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, NULL, ?, ?, ?, ?, ?, ?, ?)`);
+    for (const name of fs.readdirSync(dir)) {
+        if (!name.endsWith(".json"))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(fs.readFileSync(path.join(dir, name), "utf8"));
+        }
+        catch {
+            continue;
+        }
+        const capability = parsed.capability ?? name.replace(/\.json$/, "");
+        const nv = Number(parsed.normalizerVersion ?? 1);
+        for (const a of parsed.anchors ?? []) {
+            ins.run(String(a.specId ?? capability), capability, String(a.requirementId ?? ""), String(a.scenarioId ?? ""), String(a.anchorKind ?? "symbol"), String(a.symbolName ?? ""), a.filePath == null ? null : String(a.filePath), String(a.resolution ?? "unresolved"), a.contentHash == null ? null : String(a.contentHash), a.rawHash == null ? null : String(a.rawHash), String(a.archivedAt ?? new Date().toISOString()), a.commitSha == null ? null : String(a.commitSha), String(a.source ?? "backtick"), Number(a.normalizerVersion ?? nv));
+        }
+    }
+}
+/** Whether the index was wiped and must be rebuilt before hash comparisons. */
+export function needsReindex(db) {
+    const row = db.prepare("SELECT value FROM meta WHERE key = 'needs_reindex'").get();
+    return row?.value === "1";
+}
+/** Clear the needs-reindex marker after a successful index run. */
+export function clearNeedsReindex(db) {
+    db.prepare("DELETE FROM meta WHERE key = 'needs_reindex'").run();
+}
 /** Absolute path to the index database file for a project. */
 export function indexPath(projectPath) {
     return path.join(projectPath, ".speclaw", "index.db");

package/dist/modules/compass/extract.js

@@ -1,4 +1,10 @@
 import { parse } from "./parser.js";
+import { rawHash, structuralHash } from "./hash.js";
+const COMMENT_TYPES = new Set(["comment", "line_comment", "block_comment"]);
+/** `Covers:` / `Needs:` / `@covers` at the start of a comment line. */
+const RE_DIRECTIVE = /(?:^|\s|\*)\s*(?:@)?(covers|needs)\s*:?\s+([^\n*]+)/i;
+/** One OFT-shaped id: type~name~revision. */
+const RE_ID = /\b([a-z]{2,6})~([A-Za-z0-9._-]+)~(\d+)\b/g;
 const DEF_LOOKUP = new WeakMap();
 function defKindMap(lang) {
     let m = DEF_LOOKUP.get(lang);
@@ -31,14 +37,59 @@ function calleeName(node, lang) {
 function signatureOf(node) {
     return node.text.split("\n")[0].trim().slice(0, 200);
 }
+/** Parse Covers:/Needs: directives from a comment node's text. */
+function parseCoverageComment(node, ownerIndex) {
+    const text = node.text;
+    const dir = RE_DIRECTIVE.exec(text);
+    if (!dir)
+        return [];
+    const kind = dir[1].toLowerCase();
+    const out = [];
+    for (const m of dir[2].matchAll(RE_ID)) {
+        out.push({
+            kind,
+            artifactType: m[1],
+            name: m[2],
+            revision: Number(m[3]),
+            line: node.startPosition.row + 1,
+            startByte: node.startIndex,
+            endByte: node.endIndex,
+            endLine: node.endPosition.row + 1,
+        });
+    }
+    // silence unused until attribution; ownerIndex filled by attachCoverage
+    void ownerIndex;
+    return out;
+}
+/**
+ * Attribute a coverage comment to a symbol: next def within 2 lines, else
+ * innermost containing symbol, else file-level (null).
+ */
+function attachCoverage(raw, symbols) {
+    return raw.map((c) => {
+        const next = symbols.find((s) => s.startByte >= c.endByte);
+        if (next && next.startLine - c.endLine <= 2) {
+            return { ...c, ownerIndex: symbols.indexOf(next) };
+        }
+        const containing = symbols
+            .map((s, i) => ({ s, i }))
+            .filter(({ s }) => s.startByte <= c.startByte && c.endByte <= s.endByte)
+            .sort((a, b) => a.s.endByte - a.s.startByte - (b.s.endByte - b.s.startByte));
+        if (containing.length > 0) {
+            return { ...c, ownerIndex: containing[0].i };
+        }
+        return { ...c, ownerIndex: null };
+    });
+}
 /**
- * Walk a parsed tree extracting definitions (with nesting) and the call/import
- * references each definition contains. Single traversal, O(nodes).
+ * Walk a parsed tree extracting definitions (with nesting), call/import
+ * references, and requirement-coverage directives from comment nodes. Single
+ * traversal, O(nodes).
  *
  * @param source - The full source text of the file.
  * @param lang - Language configuration describing definition/call/import nodes.
- * @returns The extracted symbols and references; `parentIndex`/`ownerIndex`
- * fields index back into the `symbols` array to express nesting and ownership.
+ * @returns The extracted symbols, references, and coverage directives;
+ * `parentIndex`/`ownerIndex` fields index back into the `symbols` array.
  * @throws If the source cannot be parsed for the given language.
  */
 export async function extract(source, lang) {
@@ -47,6 +98,7 @@ export async function extract(source, lang) {
     const importSet = new Set(lang.importNodes);
     const symbols = [];
     const refs = [];
+    const rawCoverage = [];
     const walk = (node, ownerIndex) => {
         let nextOwner = ownerIndex;
         if (kinds.has(node.type)) {
@@ -62,6 +114,8 @@ export async function extract(source, lang) {
                     endByte: node.endIndex,
                     parentIndex: ownerIndex,
                     signature: signatureOf(node),
+                    bodyHash: rawHash(source, node.startIndex, node.endIndex),
+                    normHash: structuralHash(node),
                 });
                 nextOwner = index;
             }
@@ -79,6 +133,9 @@ export async function extract(source, lang) {
                 ownerIndex,
             });
         }
+        else if (COMMENT_TYPES.has(node.type)) {
+            rawCoverage.push(...parseCoverageComment(node, ownerIndex));
+        }
         for (let i = 0; i < node.childCount; i++) {
             const child = node.child(i);
             if (child)
@@ -87,5 +144,5 @@ export async function extract(source, lang) {
     };
     walk(tree.rootNode, null);
     tree.delete();
-    return { symbols, refs };
+    return { symbols, refs, coverage: attachCoverage(rawCoverage, symbols) };
 }

package/dist/modules/compass/hash.js

@@ -0,0 +1,77 @@
+/**
+ * Content hashes for Compass nodes: raw body bytes vs structural (tree-sitter)
+ * normal form. Structural hashes ignore comments and insignificant whitespace
+ * while preserving string literals — the dual-hash pair powers drift classification.
+ */
+import { createHash } from "node:crypto";
+/** Bump when the structural walk changes; stored anchors become `stale-hash`. */
+export const NORMALIZER_VERSION = 1;
+const COMMENT_TYPES = new Set([
+    "comment",
+    "line_comment",
+    "block_comment",
+    "html_comment",
+    "hash_bang_line",
+]);
+/** Types whose text is emitted verbatim (spaces inside matter). */
+const VERBATIM_TYPES = new Set([
+    "string",
+    "string_literal",
+    "string_fragment",
+    "template_string",
+    "template_literal",
+    "raw_string_literal",
+    "regex",
+    "regex_pattern",
+    "concatenated_string",
+]);
+function digest(parts) {
+    const h = createHash("sha256");
+    for (const p of parts) {
+        h.update(p);
+        h.update("\u0000");
+    }
+    return h.digest("hex").slice(0, 32);
+}
+/**
+ * Hash of the exact source bytes for a symbol range (detects cosmetic edits).
+ *
+ * @param source - Full file source as UTF-8 string.
+ * @param startByte - Inclusive start offset.
+ * @param endByte - Exclusive end offset.
+ */
+export function rawHash(source, startByte, endByte) {
+    return createHash("sha256").update(source.slice(startByte, endByte)).digest("hex").slice(0, 32);
+}
+/**
+ * Structural hash of a tree-sitter subtree. Invariant to reformatting and
+ * comments; sensitive to control flow, identifiers, and string contents.
+ *
+ * @param node - Definition node from the parse tree.
+ */
+export function structuralHash(node) {
+    const parts = [`v${NORMALIZER_VERSION}`];
+    const walk = (n) => {
+        if (COMMENT_TYPES.has(n.type))
+            return;
+        if (VERBATIM_TYPES.has(n.type)) {
+            parts.push(`str:${n.text}`);
+            return;
+        }
+        if (n.namedChildCount === 0) {
+            const t = n.text.trim();
+            if (t.length > 0)
+                parts.push(t);
+            return;
+        }
+        parts.push(`(${n.type}`);
+        for (let i = 0; i < n.childCount; i++) {
+            const c = n.child(i);
+            if (c)
+                walk(c);
+        }
+        parts.push(")");
+    };
+    walk(node);
+    return digest(parts);
+}

package/dist/modules/compass/indexer.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { createHash } from "node:crypto";
-import { openDb } from "./db.js";
+import { openDb, clearNeedsReindex } from "./db.js";
 import { langForPath } from "./languages.js";
 import { extract } from "./extract.js";
 import { getEmbedder, toBlob } from "./embedder.js";
@@ -29,6 +29,24 @@ const MAX_FILE_BYTES = 1_500_000;
 function hashOf(content) {
     return createHash("sha256").update(content).digest("hex");
 }
+/**
+ * Infer a covering artifact's type from its project-relative path.
+ * Full glob config lives in lawbook; this is the indexer default so links are
+ * typed even before a coverage report runs.
+ */
+function inferSourceType(relPath) {
+    const p = relPath.split("\\").join("/");
+    if (/(^|\/)test\/integration\//.test(p) || /(^|\/)tests\/integration\//.test(p))
+        return "itest";
+    if (/(^|\/)test\/unit\//.test(p) ||
+        /(^|\/)tests\/unit\//.test(p) ||
+        /\.test\.[cm]?[jt]sx?$/.test(p) ||
+        /\.spec\.[cm]?[jt]sx?$/.test(p) ||
+        /(^|\/)test\//.test(p)) {
+        return "utest";
+    }
+    return "impl";
+}
 function* walkFiles(root) {
     const stack = [root];
     while (stack.length) {
@@ -89,9 +107,13 @@ export async function buildIndex(projectPath, onProgress) {
     const updFile = db.prepare("UPDATE files SET hash = ?, lang = ? WHERE id = ?");
     const delNodes = db.prepare("DELETE FROM nodes WHERE file_id = ?");
     const delEdges = db.prepare("DELETE FROM edges WHERE src_file_id = ?");
-    const insNode = db.prepare(`INSERT INTO nodes(file_id, name, kind, start_line, end_line, start_byte, end_byte, parent_id, signature)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    const delCoverage = db.prepare("DELETE FROM coverage_links WHERE file_path = ?");
+    const insNode = db.prepare(`INSERT INTO nodes(file_id, name, kind, start_line, end_line, start_byte, end_byte, parent_id, signature, body_hash, norm_hash)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
     const insEdge = db.prepare(`INSERT INTO edges(src_node_id, src_file_id, dst_name, kind, line) VALUES (?, ?, ?, ?, ?)`);
+    const insCoverage = db.prepare(`INSERT OR REPLACE INTO coverage_links(
+       artifact_type, name, revision, kind, file_path, line, node_id, source_type, origin
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`);
     const insEmbed = db.prepare(`INSERT OR REPLACE INTO node_embeddings(node_id, dim, model, vec) VALUES (?, ?, ?, ?)`);
     const allFiles = [...walkFiles(projectPath)];
     db.exec("BEGIN");
@@ -125,16 +147,17 @@ export async function buildIndex(projectPath, onProgress) {
                 updFile.run(hash, lang.id, prior.id);
                 delNodes.run(prior.id);
                 delEdges.run(prior.id);
+                delCoverage.run(rel);
                 fileId = prior.id;
             }
             else {
                 fileId = Number(insFile.run(rel, hash, lang.id).lastInsertRowid);
             }
-            const { symbols, refs } = await extract(content, lang);
+            const { symbols, refs, coverage } = await extract(content, lang);
             const nodeIds = [];
             for (const s of symbols) {
                 const parentId = s.parentIndex !== null ? nodeIds[s.parentIndex] : null;
-                const id = Number(insNode.run(fileId, s.name, s.kind, s.startLine, s.endLine, s.startByte, s.endByte, parentId, s.signature).lastInsertRowid);
+                const id = Number(insNode.run(fileId, s.name, s.kind, s.startLine, s.endLine, s.startByte, s.endByte, parentId, s.signature, s.bodyHash, s.normHash).lastInsertRowid);
                 nodeIds.push(id);
                 // embed the node from its name + signature (cheap, meaningful text)
                 const vec = await embedder.embed(`${s.kind} ${s.name} ${s.signature ?? ""}`);
@@ -146,6 +169,11 @@ export async function buildIndex(projectPath, onProgress) {
                 insEdge.run(srcId, fileId, r.name, r.kind, r.line);
                 stats.edges++;
             }
+            const sourceType = inferSourceType(rel);
+            for (const c of coverage) {
+                const nodeId = c.ownerIndex !== null ? nodeIds[c.ownerIndex] : null;
+                insCoverage.run(c.artifactType, c.name, c.revision, c.kind, rel, c.line, nodeId, sourceType, "comment");
+            }
             stats.files++;
             stats.nodes += symbols.length;
         }
@@ -166,6 +194,7 @@ export async function buildIndex(projectPath, onProgress) {
       WHERE kind = 'call' AND dst_node_id IS NULL
     `);
         db.prepare("INSERT INTO meta(key, value) VALUES ('indexed_at', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(new Date().toISOString());
+        clearNeedsReindex(db);
         db.exec("COMMIT");
     }
     catch (err) {

package/dist/modules/foundation/doctor.js

@@ -7,6 +7,7 @@ import { readManifest } from "../../shared/manifest.js";
 import { pkgName, pkgVersion } from "../../shared/version.js";
 import { indexExists, openDb } from "../compass/db.js";
 import { specList } from "../lawbook/engine.js";
+import { doctorDriftCheck } from "../lawbook/drift.js";
 import { globError, hasBackend, hasBatchBackend, readLawManifest } from "./laws.js";
 import { redactValue } from "../../shared/redact.js";
 const STATUS_RANK = {
@@ -558,6 +559,16 @@ export async function doctor(projectPath, opts = {}) {
         configuration.push(await budgetCheck(projectPath));
         configuration.push(freshnessCheck(projectPath));
         configuration.push(specsOrphansCheck(projectPath));
+        {
+            const d = doctorDriftCheck(projectPath);
+            addCheck(configuration, {
+                id: d.id,
+                title: d.title,
+                status: d.status,
+                detail: d.detail,
+                remedy: d.remedy,
+            });
+        }
         const configured = detectConfiguredAgents(projectPath);
         const mcpAgents = AGENTS.filter((a) => a.mcpFile && configured.includes(a.id));
         if (mcpAgents.length === 0) {