@esneiderbravo/speclaw 0.3.8 → 0.3.9

package/README.md

@@ -131,6 +131,8 @@ 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/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

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

@@ -38,6 +38,7 @@ 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
@@ -62,6 +63,7 @@ const HEADER_COMMANDS = new Set([
     "doctor",
     "budget",
     "coverage",
+    "drift",
     "telemetry",
     "index",
     "watch",
@@ -87,6 +89,8 @@ function maybeHeader(cmd, flags) {
         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. */
@@ -133,6 +137,8 @@ async function dispatch(cmd, flags) {
             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/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,
@@ -73,9 +76,32 @@ CREATE TABLE IF NOT EXISTS coverage_links (
 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 = "5";
+export const SCHEMA_VERSION = "6";
 /** The stamped schema version, or null if the db predates versioning / has no meta table. */
 function readSchemaVersion(db) {
     try {
@@ -107,6 +133,7 @@ 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;
@@ -133,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,5 @@
 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;
@@ -113,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;
             }

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";
@@ -108,8 +108,8 @@ export async function buildIndex(projectPath, onProgress) {
     const delNodes = db.prepare("DELETE FROM nodes WHERE file_id = ?");
     const delEdges = db.prepare("DELETE FROM edges WHERE src_file_id = ?");
     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)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    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
@@ -157,7 +157,7 @@ export async function buildIndex(projectPath, onProgress) {
             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 ?? ""}`);
@@ -194,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) {

package/dist/modules/lawbook/anchors.js

@@ -0,0 +1,299 @@
+/**
+ * Spec-anchor extraction, resolution, and committed JSON under
+ * `lawbook/anchors/<capability>.json`. SQLite `spec_anchors` is a projection only.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { openDb, rehydrateAnchors } from "../compass/db.js";
+import { NORMALIZER_VERSION } from "../compass/hash.js";
+import { headSha } from "../../shared/git-history.js";
+const STOPWORDS = new Set([
+    "SHALL",
+    "MUST",
+    "SHOULD",
+    "MAY",
+    "GIVEN",
+    "WHEN",
+    "THEN",
+    "AND",
+    "NOT",
+    "Requirement",
+    "Scenario",
+    "speclaw",
+    "Compass",
+    "Lawbook",
+    "LAWS",
+    "AGENTS",
+    "CLAUDE",
+    "JSON",
+    "YAML",
+    "SQL",
+    "CLI",
+    "MCP",
+    "API",
+    "HTTP",
+    "URL",
+    "AST",
+    "TS",
+    "JS",
+    "SQLite",
+    "TypeScript",
+    "GitHub",
+    "README",
+    "TODO",
+    "ISO",
+    "UTC",
+]);
+const RE_BACKTICK = /`([^`\n]{2,80})`/g;
+const RE_CASING = /\b([a-z][a-zA-Z0-9]{2,}|[A-Z][a-z][a-zA-Z0-9]{1,})\b/g;
+const RE_PATH = /\b((?:src|test|lib|app|packages)\/[\w./-]+\.(?:ts|tsx|js|mjs|py))\b/g;
+const RE_COVERS = /\b([a-z]{2,6}~[A-Za-z0-9._-]+~\d+)\b/g;
+/** Absolute path to the committed anchors directory. */
+export function anchorsDir(projectPath) {
+    return path.join(projectPath, "lawbook", "anchors");
+}
+/** Absolute path to one capability's anchors file. */
+export function anchorsPath(projectPath, capability) {
+    return path.join(anchorsDir(projectPath), `${capability}.json`);
+}
+/** Extract candidates from a markdown document. */
+export function extractCandidates(markdown) {
+    const out = [];
+    let requirementId = "";
+    let scenarioId = "";
+    for (const rawLine of markdown.split("\n")) {
+        const line = rawLine.trimEnd();
+        const req = /^###\s+Requirement:\s*(.+)$/.exec(line);
+        if (req) {
+            requirementId = slug(req[1]);
+            scenarioId = "";
+            continue;
+        }
+        const sce = /^####\s+Scenario:\s*(.+)$/.exec(line);
+        if (sce) {
+            scenarioId = slug(sce[1]);
+            continue;
+        }
+        if (/^#{1,2}\s/.test(line)) {
+            requirementId = "";
+            scenarioId = "";
+            continue;
+        }
+        if (!requirementId)
+            continue;
+        for (const m of line.matchAll(RE_COVERS)) {
+            out.push({ text: m[1], source: "covers-link", requirementId, scenarioId });
+        }
+        for (const m of line.matchAll(RE_BACKTICK)) {
+            const t = m[1].replace(/\(\s*\)$/, "").trim();
+            if (!t || t.includes(" "))
+                continue;
+            const source = RE_PATH.test(t) ? "path" : "backtick";
+            RE_PATH.lastIndex = 0;
+            out.push({ text: t, source, requirementId, scenarioId });
+        }
+        for (const m of line.matchAll(RE_CASING)) {
+            const t = m[1];
+            if (STOPWORDS.has(t) || t.length < 3)
+                continue;
+            if (!/[a-z]/.test(t) || !/[A-Z]/.test(t))
+                continue;
+            out.push({ text: t, source: "casing", requirementId, scenarioId });
+        }
+    }
+    return dedupe(out);
+}
+/** Resolve candidates against the Compass graph. */
+export function resolveCandidates(db, projectPath, cands, specId, now, sha) {
+    const rows = [];
+    const byName = db.prepare(`SELECT n.id AS id, n.norm_hash AS normHash, n.body_hash AS bodyHash, f.path AS path
+       FROM nodes n JOIN files f ON f.id = n.file_id
+      WHERE n.name = ? AND n.kind IN ('function','method','class','interface','type')`);
+    for (const c of cands) {
+        if (c.source === "path") {
+            rows.push({
+                specId,
+                requirementId: c.requirementId,
+                scenarioId: c.scenarioId,
+                anchorKind: "file",
+                symbolName: c.text,
+                filePath: c.text,
+                resolution: fs.existsSync(path.join(projectPath, c.text)) ? "unique" : "unresolved",
+                contentHash: null,
+                rawHash: null,
+                archivedAt: now,
+                commitSha: sha,
+                source: c.source,
+                normalizerVersion: NORMALIZER_VERSION,
+            });
+            continue;
+        }
+        if (c.source === "covers-link") {
+            const link = db
+                .prepare(`SELECT n.id AS id, n.norm_hash AS normHash, n.body_hash AS bodyHash,
+                  f.path AS path, n.name AS name
+             FROM coverage_links c
+             LEFT JOIN nodes n ON n.id = c.node_id
+             LEFT JOIN files f ON f.id = n.file_id
+            WHERE c.artifact_type || '~' || c.name || '~' || c.revision = ?
+            LIMIT 2`)
+                .all(c.text);
+            if (link.length === 1 && link[0].id != null && link[0].name) {
+                rows.push(mkSymbol(c, specId, link[0], "unique", now, sha, link[0].name));
+            }
+            else {
+                rows.push(mkUnresolved(c, specId, now, sha));
+            }
+            continue;
+        }
+        const matches = byName.all(c.text);
+        if (matches.length === 1) {
+            rows.push(mkSymbol(c, specId, matches[0], "unique", now, sha, c.text));
+        }
+        else if (matches.length > 1) {
+            rows.push({
+                specId,
+                requirementId: c.requirementId,
+                scenarioId: c.scenarioId,
+                anchorKind: "symbol",
+                symbolName: c.text,
+                filePath: matches[0].path,
+                resolution: "ambiguous",
+                contentHash: null,
+                rawHash: null,
+                archivedAt: now,
+                commitSha: sha,
+                source: c.source,
+                normalizerVersion: NORMALIZER_VERSION,
+            });
+        }
+        else if (c.source === "backtick") {
+            rows.push(mkUnresolved(c, specId, now, sha));
+        }
+    }
+    return rows;
+}
+function mkSymbol(c, specId, hit, resolution, now, sha, name) {
+    return {
+        specId,
+        requirementId: c.requirementId,
+        scenarioId: c.scenarioId,
+        anchorKind: "symbol",
+        symbolName: name,
+        filePath: hit.path,
+        resolution,
+        contentHash: hit.normHash,
+        rawHash: hit.bodyHash,
+        archivedAt: now,
+        commitSha: sha,
+        source: c.source,
+        normalizerVersion: NORMALIZER_VERSION,
+    };
+}
+function mkUnresolved(c, specId, now, sha) {
+    return {
+        specId,
+        requirementId: c.requirementId,
+        scenarioId: c.scenarioId,
+        anchorKind: "symbol",
+        symbolName: c.text,
+        filePath: null,
+        resolution: "unresolved",
+        contentHash: null,
+        rawHash: null,
+        archivedAt: now,
+        commitSha: sha,
+        source: c.source,
+        normalizerVersion: NORMALIZER_VERSION,
+    };
+}
+/** Read a capability anchors file, or null when absent. */
+export function readAnchorsFile(projectPath, capability) {
+    const p = anchorsPath(projectPath, capability);
+    if (!fs.existsSync(p))
+        return null;
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+}
+/** Write anchors JSON only (caller refreshes SQLite projection). */
+export function writeAnchorsFile(projectPath, doc) {
+    const dir = anchorsDir(projectPath);
+    fs.mkdirSync(dir, { recursive: true });
+    const sorted = [...doc.anchors].sort((a, b) => `${a.requirementId}\0${a.scenarioId}\0${a.symbolName}`.localeCompare(`${b.requirementId}\0${b.scenarioId}\0${b.symbolName}`));
+    const dest = anchorsPath(projectPath, doc.capability);
+    fs.writeFileSync(dest, JSON.stringify({ ...doc, anchors: sorted }, null, 2) + "\n", "utf8");
+    return dest;
+}
+/** List capability names that already have an anchors file. */
+export function listAnchoredCapabilities(projectPath) {
+    const dir = anchorsDir(projectPath);
+    if (!fs.existsSync(dir))
+        return [];
+    return fs
+        .readdirSync(dir)
+        .filter((n) => n.endsWith(".json"))
+        .map((n) => n.replace(/\.json$/, ""))
+        .sort();
+}
+/** Seal anchors for one capability from markdown and refresh the projection. */
+export function sealCapability(projectPath, capability, markdown, opts = {}) {
+    const db = openDb(projectPath);
+    try {
+        const now = opts.now ?? new Date().toISOString();
+        const sha = headSha(projectPath);
+        const specId = opts.specId ?? capability;
+        const rows = resolveCandidates(db, projectPath, extractCandidates(markdown), specId, now, sha);
+        const dest = writeAnchorsFile(projectPath, {
+            anchorsVersion: 1,
+            capability,
+            normalizerVersion: NORMALIZER_VERSION,
+            anchors: rows,
+        });
+        rehydrateAnchors(db, projectPath);
+        return {
+            capability,
+            unique: rows.filter((r) => r.resolution === "unique").length,
+            ambiguous: rows.filter((r) => r.resolution === "ambiguous").length,
+            unresolved: rows.filter((r) => r.resolution === "unresolved").length,
+            path: path.relative(projectPath, dest),
+            warned: rows.length === 0,
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+/** Seal every canonical capability under lawbook/specs/ that has a spec.md. */
+export function resealAll(projectPath) {
+    const specsRoot = path.join(projectPath, "lawbook", "specs");
+    if (!fs.existsSync(specsRoot))
+        return [];
+    const out = [];
+    for (const name of fs.readdirSync(specsRoot)) {
+        const specPath = path.join(specsRoot, name, "spec.md");
+        if (!fs.existsSync(specPath))
+            continue;
+        out.push(sealCapability(projectPath, name, fs.readFileSync(specPath, "utf8")));
+    }
+    return out;
+}
+function slug(title) {
+    return title
+        .replace(/`[^`]+`/g, "")
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 80);
+}
+function dedupe(cands) {
+    const seen = new Set();
+    const out = [];
+    for (const c of cands) {
+        const k = `${c.requirementId}\0${c.scenarioId}\0${c.source}\0${c.text}`;
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        out.push(c);
+    }
+    return out;
+}

package/dist/modules/lawbook/drift.js

@@ -0,0 +1,491 @@
+/**
+ * Deterministic spec↔code drift classification and reporting.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { openDb, indexExists, needsReindex } from "../compass/db.js";
+import { NORMALIZER_VERSION } from "../compass/hash.js";
+import { logForPath } from "../../shared/git-history.js";
+import { listAnchoredCapabilities, readAnchorsFile, resealAll, sealCapability, } from "./anchors.js";
+const FAIL_RANK = { none: 0, cosmetic: 1, semantic: 2, any: 3 };
+function stateRank(state) {
+    switch (state) {
+        case "changed-cosmetic":
+            return 1;
+        case "changed-semantic":
+        case "deleted":
+            return 2;
+        case "orphan":
+        case "ambiguous":
+            return 3;
+        default:
+            return 0;
+    }
+}
+/** Parse `--fail-on`; defaults to semantic; null when invalid. */
+export function parseFailOn(raw) {
+    if (raw === undefined || raw === true)
+        return "semantic";
+    if (typeof raw !== "string")
+        return null;
+    if (raw === "none" || raw === "cosmetic" || raw === "semantic" || raw === "any")
+        return raw;
+    return null;
+}
+/** Classify one sealed anchor against the live graph. */
+export function classifyAnchor(db, projectPath, capability, a) {
+    if (a.normalizerVersion !== NORMALIZER_VERSION) {
+        return { capability, anchor: a, state: "stale-hash" };
+    }
+    if (a.resolution === "unresolved")
+        return { capability, anchor: a, state: "orphan" };
+    if (a.resolution === "ambiguous")
+        return { capability, anchor: a, state: "ambiguous" };
+    if (a.anchorKind === "file") {
+        const ok = a.filePath != null && fs.existsSync(path.join(projectPath, a.filePath));
+        return { capability, anchor: a, state: ok ? "unchanged" : "deleted" };
+    }
+    const byName = db
+        .prepare(`SELECT n.id AS id, n.name AS name, n.kind AS kind, f.path AS path,
+              n.norm_hash AS normHash, n.body_hash AS bodyHash
+         FROM nodes n JOIN files f ON f.id = n.file_id
+        WHERE n.name = ?`)
+        .all(a.symbolName);
+    if (byName.length === 0) {
+        if (a.contentHash) {
+            const byHash = db
+                .prepare(`SELECT n.id AS id, n.name AS name, n.kind AS kind, f.path AS path,
+                  n.norm_hash AS normHash, n.body_hash AS bodyHash
+             FROM nodes n JOIN files f ON f.id = n.file_id
+            WHERE n.norm_hash = ?
+            LIMIT 1`)
+                .get(a.contentHash);
+            if (byHash)
+                return { capability, anchor: a, state: "moved", currentFile: byHash.path };
+        }
+        return { capability, anchor: a, state: "deleted" };
+    }
+    const n = byName.find((m) => m.path === a.filePath) ?? (byName.length === 1 ? byName[0] : null);
+    if (!n)
+        return { capability, anchor: a, state: "ambiguous" };
+    if (n.normHash === a.contentHash) {
+        if (n.path !== a.filePath) {
+            return { capability, anchor: a, state: "moved", currentFile: n.path };
+        }
+        if (n.bodyHash !== a.rawHash) {
+            return { capability, anchor: a, state: "changed-cosmetic", currentFile: n.path };
+        }
+        return { capability, anchor: a, state: "unchanged", currentFile: n.path };
+    }
+    return { capability, anchor: a, state: "changed-semantic", currentFile: n.path };
+}
+function attachAge(projectPath, v) {
+    if (v.state !== "changed-semantic" && v.state !== "deleted")
+        return v;
+    const file = v.currentFile ?? v.anchor.filePath;
+    if (!file)
+        return { ...v, driftDays: null };
+    const touches = logForPath(projectPath, file);
+    const last = touches[0];
+    if (!last)
+        return { ...v, commitsSince: 0, driftDays: null };
+    const archived = Date.parse(v.anchor.archivedAt);
+    const driftDays = Number.isFinite(archived)
+        ? Math.max(0, Math.floor((last.ts * 1000 - archived) / 86_400_000))
+        : null;
+    return { ...v, commitsSince: touches.length, driftDays };
+}
+function matchGlob(relPath, pattern) {
+    const norm = relPath.replace(/\\/g, "/");
+    const esc = pattern
+        .replace(/\\/g, "/")
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*\*/g, "{{DS}}")
+        .replace(/\*/g, "[^/]*")
+        .replace(/{{DS}}/g, ".*");
+    return new RegExp(`^${esc}$`).test(norm);
+}
+/**
+ * Load `capabilities[].paths` from lawbook/config.yaml (line-oriented subset).
+ * Returns an empty map when the file is missing or no paths are declared.
+ */
+export function loadCapabilityPaths(projectPath) {
+    const cfgPath = path.join(projectPath, "lawbook", "config.yaml");
+    if (!fs.existsSync(cfgPath))
+        return {};
+    const out = {};
+    let inCaps = false;
+    let current = null;
+    let inPaths = false;
+    for (const raw of fs.readFileSync(cfgPath, "utf8").split("\n")) {
+        const line = raw.replace(/\s+#.*$/, "");
+        if (/^\s*capabilities\s*:/.test(line)) {
+            inCaps = true;
+            current = null;
+            inPaths = false;
+            continue;
+        }
+        if (inCaps && /^[A-Za-z_]/.test(line)) {
+            // Next top-level key ends the capabilities block.
+            inCaps = false;
+            current = null;
+            inPaths = false;
+        }
+        if (!inCaps)
+            continue;
+        const name = /^\s*-\s*name\s*:\s*["']?([^"'#]+?)["']?\s*$/.exec(line);
+        if (name) {
+            current = name[1].trim();
+            out[current] ??= [];
+            inPaths = false;
+            continue;
+        }
+        if (/^\s*paths\s*:/.test(line)) {
+            inPaths = true;
+            const inline = /^\s*paths\s*:\s*\[([^\]]*)\]\s*$/.exec(line);
+            if (inline && current) {
+                out[current] = inline[1]
+                    .split(",")
+                    .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+                    .filter(Boolean);
+                inPaths = false;
+            }
+            continue;
+        }
+        if (inPaths && current) {
+            const item = /^\s*-\s*["']?([^"'#]+?)["']?\s*$/.exec(line);
+            if (item) {
+                out[current].push(item[1].trim());
+                continue;
+            }
+            if (/^\s*-\s*name\s*:/.test(line) || /^[A-Za-z_]/.test(line)) {
+                inPaths = false;
+            }
+        }
+    }
+    // Drop capabilities that declared no globs.
+    for (const k of Object.keys(out)) {
+        if (out[k].length === 0)
+            delete out[k];
+    }
+    return out;
+}
+/** Reverse drift: top-level symbols under capability paths with no seal. */
+export function reverseDrift(db, capabilityPaths) {
+    if (Object.keys(capabilityPaths).length === 0) {
+        return {
+            enabled: false,
+            reason: "No capabilities[].paths configured — reverse drift disabled.",
+            hits: [],
+        };
+    }
+    const anchored = new Set(db.prepare(`SELECT symbol_name AS name FROM spec_anchors`).all().map((r) => r.name));
+    const nodes = db
+        .prepare(`SELECT n.name AS name, n.kind AS kind, f.path AS path
+         FROM nodes n JOIN files f ON f.id = n.file_id
+        WHERE n.parent_id IS NULL
+          AND n.kind IN ('function','class','method','interface')`)
+        .all();
+    const hits = [];
+    for (const [capability, globs] of Object.entries(capabilityPaths)) {
+        for (const n of nodes) {
+            if (anchored.has(n.name))
+                continue;
+            if (n.path.includes(".test.") || n.path.includes("/test/"))
+                continue;
+            if (!globs.some((g) => matchGlob(n.path, g)))
+                continue;
+            hits.push({ capability, filePath: n.path, symbolName: n.name, kind: n.kind });
+        }
+    }
+    return { enabled: true, hits };
+}
+function countStates(verdicts) {
+    const c = {
+        unchanged: 0,
+        changedCosmetic: 0,
+        changedSemantic: 0,
+        moved: 0,
+        deleted: 0,
+        orphan: 0,
+        ambiguous: 0,
+        unanchored: 0,
+        staleHash: 0,
+    };
+    for (const v of verdicts) {
+        switch (v.state) {
+            case "unchanged":
+                c.unchanged++;
+                break;
+            case "changed-cosmetic":
+                c.changedCosmetic++;
+                break;
+            case "changed-semantic":
+                c.changedSemantic++;
+                break;
+            case "moved":
+                c.moved++;
+                break;
+            case "deleted":
+                c.deleted++;
+                break;
+            case "orphan":
+                c.orphan++;
+                break;
+            case "ambiguous":
+                c.ambiguous++;
+                break;
+            case "unanchored":
+                c.unanchored++;
+                break;
+            case "stale-hash":
+                c.staleHash++;
+                break;
+        }
+    }
+    return c;
+}
+function emptyReport(generatedAt, failOn, needs, exitCode) {
+    return {
+        schemaVersion: 1,
+        generatedAt,
+        normalizerVersion: NORMALIZER_VERSION,
+        needsReindex: needs,
+        summary: {
+            capabilities: 0,
+            anchors: 0,
+            unchanged: 0,
+            changedCosmetic: 0,
+            changedSemantic: 0,
+            moved: 0,
+            deleted: 0,
+            orphan: 0,
+            ambiguous: 0,
+            unanchored: 0,
+            staleHash: 0,
+            maxDriftDays: null,
+            failOn,
+            exitCode,
+        },
+        verdicts: [],
+        reverse: { enabled: false, hits: [] },
+    };
+}
+/** Exit code under a fail-on threshold. */
+export function driftExitCode(verdicts, failOn) {
+    if (failOn === "none")
+        return 0;
+    const threshold = FAIL_RANK[failOn];
+    for (const v of verdicts) {
+        const rank = stateRank(v.state);
+        if (rank === 0)
+            continue;
+        // orphan/ambiguous are rank 3 — they fail only under `--fail-on any`.
+        // cosmetic (1) and semantic/deleted (2) fail when rank is in [threshold, 2].
+        if (failOn === "any")
+            return 1;
+        if (rank >= threshold && rank <= FAIL_RANK.semantic)
+            return 1;
+    }
+    return 0;
+}
+/** Build a full drift report. */
+export function buildDriftReport(projectPath, opts = {}) {
+    const failOn = opts.failOn ?? "semantic";
+    const generatedAt = new Date().toISOString();
+    if (!indexExists(projectPath))
+        return emptyReport(generatedAt, failOn, true, 2);
+    let resealSummaries;
+    if (opts.reseal) {
+        if (opts.capability) {
+            const specPath = path.join(projectPath, "lawbook", "specs", opts.capability, "spec.md");
+            const md = fs.existsSync(specPath) ? fs.readFileSync(specPath, "utf8") : "";
+            resealSummaries = [sealCapability(projectPath, opts.capability, md)];
+        }
+        else {
+            resealSummaries = resealAll(projectPath);
+        }
+    }
+    const db = openDb(projectPath);
+    try {
+        if (needsReindex(db))
+            return emptyReport(generatedAt, failOn, true, 2);
+        const caps = opts.capability ? [opts.capability] : listAnchoredCapabilities(projectPath);
+        const verdicts = [];
+        for (const capability of caps) {
+            const file = readAnchorsFile(projectPath, capability);
+            if (!file || file.anchors.length === 0) {
+                verdicts.push({
+                    capability,
+                    anchor: {
+                        specId: capability,
+                        requirementId: "",
+                        scenarioId: "",
+                        anchorKind: "symbol",
+                        symbolName: "",
+                        filePath: null,
+                        resolution: "unresolved",
+                        contentHash: null,
+                        rawHash: null,
+                        archivedAt: generatedAt,
+                        commitSha: null,
+                        source: "backtick",
+                        normalizerVersion: NORMALIZER_VERSION,
+                    },
+                    state: "unanchored",
+                });
+                continue;
+            }
+            for (const a of file.anchors) {
+                verdicts.push(attachAge(projectPath, classifyAnchor(db, projectPath, capability, a)));
+            }
+        }
+        const reverse = opts.reverse
+            ? reverseDrift(db, opts.capabilityPaths ?? loadCapabilityPaths(projectPath))
+            : { enabled: false, reason: "Pass --reverse to enable.", hits: [] };
+        const counts = countStates(verdicts);
+        const maxDriftDays = verdicts.reduce((acc, v) => {
+            if (v.driftDays == null)
+                return acc;
+            return acc == null ? v.driftDays : Math.max(acc, v.driftDays);
+        }, null);
+        return {
+            schemaVersion: 1,
+            generatedAt,
+            normalizerVersion: NORMALIZER_VERSION,
+            needsReindex: false,
+            summary: {
+                capabilities: caps.length,
+                anchors: verdicts.filter((v) => v.state !== "unanchored").length,
+                ...counts,
+                maxDriftDays,
+                failOn,
+                exitCode: driftExitCode(verdicts, failOn),
+            },
+            verdicts,
+            reverse,
+            reseal: resealSummaries,
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+/** Human TTY table. */
+export function renderDriftTable(report) {
+    const s = report.summary;
+    const lines = [
+        `speclaw drift · ${s.capabilities} capabilities · ${s.anchors} anchors`,
+        "",
+        `unchanged ${s.unchanged}  cosmetic ${s.changedCosmetic}  moved ${s.moved}  semantic ${s.changedSemantic}  deleted ${s.deleted}  orphan ${s.orphan}  ambiguous ${s.ambiguous}`,
+    ];
+    const defects = report.verdicts.filter((v) => stateRank(v.state) >= 2);
+    if (defects.length) {
+        lines.push("");
+        for (const d of defects.slice(0, 30)) {
+            lines.push(`  ${d.state.padEnd(18)} ${d.capability} → ${d.anchor.symbolName || "(unanchored)"}` +
+                (d.currentFile ? `  ${d.currentFile}` : ""));
+        }
+        if (defects.length > 30)
+            lines.push(`  … ${defects.length - 30} more`);
+    }
+    if (report.reverse.enabled && report.reverse.hits.length) {
+        lines.push("", `reverse · ${report.reverse.hits.length} uncovered symbol(s)`);
+        for (const h of report.reverse.hits.slice(0, 15)) {
+            lines.push(`  ${h.capability}  ${h.filePath}  ${h.symbolName}`);
+        }
+    }
+    else if (report.reverse.reason) {
+        lines.push("", report.reverse.reason);
+    }
+    return lines.join("\n");
+}
+/** Bounded agent summary. */
+export function renderDriftAgent(report, maxItems = 10) {
+    if (report.needsReindex) {
+        return "Drift: index needs rebuild (`speclaw index`) before comparison.";
+    }
+    const s = report.summary;
+    const defects = report.verdicts.filter((v) => stateRank(v.state) >= 2);
+    if (defects.length === 0 && s.anchors > 0) {
+        return `Drift clean — ${s.anchors} anchors across ${s.capabilities} capabilities (fail-on ${s.failOn}).`;
+    }
+    if (s.anchors === 0) {
+        return "Drift: no sealed anchors yet. Run `speclaw drift --reseal` after indexing.";
+    }
+    const lines = [
+        `Drift: ${defects.length} defect(s) · semantic ${s.changedSemantic} · deleted ${s.deleted} · orphan ${s.orphan} (fail-on ${s.failOn}).`,
+    ];
+    for (const d of defects.slice(0, maxItems)) {
+        lines.push(`- [${d.state}] ${d.capability} ${d.anchor.symbolName}`);
+    }
+    if (defects.length > maxItems)
+        lines.push(`- … ${defects.length - maxItems} more`);
+    lines.push("Use `speclaw drift --json` for detail.");
+    return lines.join("\n");
+}
+/** Semantic/deleted findings for verify --ci. */
+export function driftFindingsForVerify(projectPath) {
+    const report = buildDriftReport(projectPath, { failOn: "semantic" });
+    const out = [];
+    for (const v of report.verdicts) {
+        if (v.state !== "changed-semantic" && v.state !== "deleted")
+            continue;
+        out.push({
+            ruleId: `drift~${v.state}`,
+            file: v.currentFile ?? v.anchor.filePath ?? "lawbook/anchors",
+            line: 1,
+            message: `Spec drift (${v.state}): ${v.capability} → ${v.anchor.symbolName}`,
+            severity: "error",
+        });
+    }
+    return out;
+}
+/** Doctor check line. */
+export function doctorDriftCheck(projectPath) {
+    const caps = listAnchoredCapabilities(projectPath);
+    if (caps.length === 0) {
+        return {
+            id: "cfg.drift",
+            title: "spec drift",
+            status: "skip",
+            detail: "no sealed anchors",
+            remedy: "speclaw drift --reseal",
+        };
+    }
+    if (!indexExists(projectPath)) {
+        return {
+            id: "cfg.drift",
+            title: "spec drift",
+            status: "warn",
+            detail: "index missing",
+            remedy: "speclaw index",
+        };
+    }
+    const report = buildDriftReport(projectPath, { failOn: "semantic" });
+    if (report.needsReindex) {
+        return {
+            id: "cfg.drift",
+            title: "spec drift",
+            status: "warn",
+            detail: "index needs rebuild before drift can run",
+            remedy: "speclaw index",
+        };
+    }
+    const bad = report.summary.changedSemantic + report.summary.deleted;
+    if (bad > 0) {
+        return {
+            id: "cfg.drift",
+            title: "spec drift",
+            status: "warn",
+            detail: `${bad} semantic/deleted across ${report.summary.anchors} anchors`,
+            remedy: "speclaw drift",
+        };
+    }
+    return {
+        id: "cfg.drift",
+        title: "spec drift",
+        status: "ok",
+        detail: `${report.summary.anchors} anchors · clean`,
+    };
+}

package/dist/modules/lawbook/engine.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { coverageArchiveBlockers } from "./coverage.js";
+import { sealCapability } from "./anchors.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
@@ -336,12 +337,49 @@ export function specArchive(projectPath, change, date) {
         throw new Error(`cannot archive "${change}" — resolve first:\n${blockers.map((b) => `  - ${b}`).join("\n")}`);
     }
     const { promoted, created, updated } = specSync(projectPath, change);
+    const seals = sealPromotedCapabilities(projectPath, change, [
+        ...promoted,
+        ...created,
+        ...updated,
+    ]);
     const archiveDir = path.join(root, "changes", "archive", `${date}-${change}`);
     fs.mkdirSync(path.dirname(archiveDir), { recursive: true });
     if (fs.existsSync(archiveDir))
         throw new Error(`archive target already exists: ${archiveDir}`);
     fs.renameSync(changeDir, archiveDir);
-    return { change, promoted, created, updated, archivedTo: path.relative(projectPath, archiveDir) };
+    return {
+        change,
+        promoted,
+        created,
+        updated,
+        archivedTo: path.relative(projectPath, archiveDir),
+        seals,
+    };
+}
+/**
+ * Seal structural anchors for every capability whose canonical spec was
+ * promoted during archive. Missing specs are skipped; zero anchors warn via
+ * {@link SealSummary.warned} but never block archive.
+ */
+function sealPromotedCapabilities(projectPath, change, promotedPaths) {
+    const caps = new Set();
+    for (const p of promotedPaths) {
+        // lawbook/specs/<capability>/spec.md → capability
+        const parts = p.replace(/\\/g, "/").split("/");
+        const specsIdx = parts.indexOf("specs");
+        if (specsIdx >= 0 && parts[specsIdx + 1])
+            caps.add(parts[specsIdx + 1]);
+    }
+    const out = [];
+    for (const capability of [...caps].sort()) {
+        const specPath = path.join(specRoot(projectPath), "specs", capability, "spec.md");
+        if (!fs.existsSync(specPath))
+            continue;
+        out.push(sealCapability(projectPath, capability, fs.readFileSync(specPath, "utf8"), {
+            specId: `${capability}#${change}`,
+        }));
+    }
+    return out;
 }
 /**
  * List the spec workspace: active changes, archived changes, and canonical

package/dist/modules/lawbook/register.js

@@ -6,6 +6,7 @@ import { assetsDir } from "../../shared/paths.js";
 import { copyRendered } from "../../shared/install.js";
 import { specInit, specValidate, specSync, specArchive, specList } from "./engine.js";
 import { buildCoverageReport, loadCoverageConfig, renderCoverageAgent } from "./coverage.js";
+import { buildDriftReport, renderDriftAgent } from "./drift.js";
 const ASSETS = assetsDir(import.meta.url);
 /**
  * Install the spec module's workflow interface into a project's ai-specs/:
@@ -47,4 +48,20 @@ export function registerSpec(server, opts = {}) {
             return text(JSON.stringify(report));
         return text(renderCoverageAgent(report, onlyDefects !== false));
     });
+    add("lawbook_drift", "Report deterministic drift between sealed spec anchors and the code graph. Call before claiming a task is done.", {
+        projectPath: z.string(),
+        capability: z.string().optional(),
+        includeReverse: z.boolean().optional(),
+        maxItems: z.number().int().min(1).max(50).optional(),
+        json: z.boolean().optional(),
+    }, async ({ projectPath, capability, includeReverse, maxItems, json }) => {
+        const report = buildDriftReport(projectPath, {
+            capability,
+            reverse: includeReverse === true,
+            failOn: "semantic",
+        });
+        if (json)
+            return text(JSON.stringify(report));
+        return text(renderDriftAgent(report, maxItems ?? 10));
+    });
 }

package/dist/shared/exposure.js

@@ -5,7 +5,7 @@ import { readManifest } from "./manifest.js";
 /**
  * Tools omitted when the exposure profile is `minimal`. Kept tools are the
  * discovery + law loop: compass_explore/search/recall, lawbook_validate/sync,
- * lawbook_coverage, law_verify, speclaw_check.
+ * lawbook_coverage, lawbook_drift, law_verify, speclaw_check.
  */
 export const MINIMAL_OMIT = new Set([
     "compass_index",

package/package.json

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