@esneiderbravo/speclaw 0.3.5 → 0.3.8

package/README.md

@@ -5,6 +5,8 @@
 <br/>
 
 <a href="https://www.npmjs.com/package/@esneiderbravo/speclaw"><img src="https://img.shields.io/npm/v/@esneiderbravo/speclaw?color=0E8E8E&labelColor=0B0F10&style=flat-square&label=npm" alt="npm"></a>
+&nbsp;<a href="https://github.com/esneiderbravo/speclaw/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/esneiderbravo/speclaw/ci.yml?branch=main&label=CI&labelColor=0B0F10&style=flat-square&color=0E8E8E" alt="CI"></a>
+&nbsp;<a href="https://www.npmjs.com/package/@esneiderbravo/speclaw?activeTab=versions"><img src="https://img.shields.io/badge/provenance-SLSA-0E8E8E?labelColor=0B0F10&style=flat-square" alt="npm provenance"></a>
 &nbsp;<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-0E8E8E?labelColor=0B0F10&style=flat-square" alt="MIT"></a>
 &nbsp;<img src="https://img.shields.io/badge/node-%E2%89%A522-0E8E8E?labelColor=0B0F10&style=flat-square" alt="Node >= 22">
 
@@ -29,32 +31,40 @@ One command. No cloud, no LLM, no API keys — <b>everything runs on your machin
 <br/>
 
 > [!TIP]
-> **Install once, then one command sets everything up.** Install speclaw globally, run
-> `speclaw init`, pick the agents you use, and speclaw scaffolds the project, indexes
-> your code, and hands your agent a ready-to-paste prompt to finish the setup.
+> **One command. Detects your agents and wires only those.** Paste
+> `npx @esneiderbravo/speclaw@latest init` — speclaw detects Claude Code, Cursor,
+> Codex, Windsurf, and generic `AGENTS.md` surfaces, scaffolds the constitution +
+> lawbook, indexes your code, and registers the local MCP server — only for the
+> agents you pick. This one-liner is a **stable contract** (see
+> [CONTRIBUTING.md](CONTRIBUTING.md)); do not invent alternate install commands in
+> directories or newsletters.
 
 <br/>
 
 ## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; Quick start
 
-Install speclaw globally (once), then run `init` in your project root:
-
 ```bash
-npm i -g @esneiderbravo/speclaw
-speclaw init
+npx @esneiderbravo/speclaw@latest init
 ```
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/terminal-quickstart.png" width="800" alt="speclaw init">
 </p>
 
-The `speclaw` command is now available everywhere — run `speclaw index`,
-`speclaw visualize`, or `speclaw lawbook …` directly in any project.
+Prefer a global install for repeated CLI use?
+
+```bash
+npm i -g @esneiderbravo/speclaw
+speclaw init
+```
+
+The `speclaw` command is then available everywhere — run `speclaw index`,
+`speclaw doctor`, `speclaw visualize`, or `speclaw lawbook …` directly.
 
 `init` will:
 
-1. **Ask which agents you use** (Claude Code, Cursor, Codex, …) — and configure
-   only those. Add more later; nothing is forced on you.
+1. **Ask which agents you use** (Claude Code, Cursor, Codex, Windsurf, …) — and
+   configure only those. Add more later; nothing is forced on you.
 2. Write the **foundation** (constitution + standards) and the **lawbook workflow**,
    and compile your blocking laws into **agent hooks** for the agents that support them.
 3. **Index your code** with a live progress bar and a summary of what it found.
@@ -62,9 +72,23 @@ The `speclaw` command is now available everywhere — run `speclaw index`,
 5. Print a prompt to paste into your agent so it fills the constitution with your
    project's real architecture and conventions.
 
-Prefer not to install globally? A one-off `npx @esneiderbravo/speclaw init` works
-too (also `pnpm dlx` / `yarn dlx`) — but installing globally means you can run the
-`speclaw` commands directly afterwards.
+When something breaks, run `speclaw doctor --json` and paste it into an issue
+(required on bug reports). Output is redacted by default.
+
+<br/>
+
+## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; Verify a release (provenance)
+
+Every npm publish is signed via **Trusted Publishing (OIDC)** and carries a
+SLSA provenance attestation tied to this repository and workflow. That proves
+*where* the tarball was built — not that its contents are benign. Pair it with
+your own review and (later) law-integrity pinning.
+
+```bash
+npm audit signatures
+# After downloading the tarball from the registry:
+gh attestation verify <tarball> --owner esneiderbravo
+```
 
 <br/>
 
@@ -105,6 +129,8 @@ 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 init --minimal  # omit setup/lifecycle MCP tools from registration
 ```
 
@@ -202,7 +228,10 @@ you** — commit your own skills and commands there if you want to.
 
 **Enforcement artifacts.** For agents that support hooks, speclaw merges its law
 hooks into that agent's settings (e.g. `.claude/settings.json`) **by identity** —
-it never touches hooks you added yourself. The compiled law manifest lives in
+it never touches hooks you added yourself. Each speclaw `mcp_tool` hook includes
+an `input` map Claude Code substitutes from the hook event (`${cwd}`,
+`${hook_event_name}`, `${tool_input.file_path}`, …) so `speclaw_check` receives
+`projectPath` / `event` / `payload`. The compiled law manifest lives in
 `.speclaw/laws-manifest.json` (gitignored, regenerated on `init`/`update`), and a
 context-coverage log in `.speclaw/context-log.jsonl` feeds `speclaw doctor`.
 

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/doctor.js

@@ -1,31 +1,63 @@
 import { doctor } from "../../modules/foundation/doctor.js";
-import { measureInstallBudget } from "../../modules/foundation/context-budget.js";
 import { ui } from "../lib/ui.js";
-/** Verify the installation, printing each check and exiting non-zero on failure. */
-export async function runDoctor(_flags) {
-    const cwd = process.cwd();
-    const checks = doctor(cwd);
+const STATUS_MARK = {
+    ok: "ok",
+    warn: "warn",
+    error: "error",
+    skip: "skip",
+};
+function printHuman(report) {
     ui.heading("speclaw doctor");
-    for (const c of checks) {
-        if (c.ok)
-            ui.ok(`${c.name} — ${c.detail}`);
-        else
-            ui.err(`${c.name} — ${c.detail}`);
-    }
-    try {
-        const m = measureInstallBudget(cwd);
-        ui.ok(`context budget — profile ${m.profile} · ${m.toolCount} tools · ~${m.total} always-on tokens ` +
-            `(A ${m.tools} · B ${m.skillsAndCommands} · C ${m.alwaysOnInstructions}; D path-scoped ${m.pathScoped} not in total)`);
-    }
-    catch (err) {
-        ui.warn(`context budget — could not measure: ${err.message}`);
+    for (const section of report.sections) {
+        ui.plain();
+        ui.ok(`${section.id}  [${STATUS_MARK[section.status]}]`);
+        for (const c of section.checks) {
+            const line = `${c.title.padEnd(24)} ${c.detail ?? c.status}`;
+            if (c.status === "ok" || c.status === "skip")
+                ui.ok(`  ${line}`);
+            else if (c.status === "warn") {
+                ui.warn(`  ${line}`);
+                if (c.remedy)
+                    ui.plain(`      → ${c.remedy}`);
+            }
+            else {
+                ui.err(`  ${line}`);
+                if (c.remedy)
+                    ui.plain(`      → ${c.remedy}`);
+            }
+        }
     }
-    const failed = checks.filter((c) => !c.ok).length;
     ui.plain();
-    if (failed === 0)
+    const warns = report.sections.flatMap((s) => s.checks).filter((c) => c.status === "warn").length;
+    const errs = report.sections.flatMap((s) => s.checks).filter((c) => c.status === "error").length;
+    if (errs === 0 && warns === 0)
         ui.ok("Everything is within the law.");
+    else if (errs === 0) {
+        ui.warn(`${warns} warning(s). Run \`speclaw doctor --json\` and paste it into an issue.`);
+    }
+    else {
+        ui.err(`${errs} error(s), ${warns} warning(s).`);
+    }
+}
+/**
+ * Verify the installation. Supports `--json`, `--offline`, `--strict`,
+ * `--redact` (default) / `--no-redact`.
+ */
+export async function runDoctor(flags) {
+    const cwd = process.cwd();
+    const redact = flags["no-redact"] ? false : true;
+    const report = await doctor(cwd, {
+        offline: Boolean(flags.offline),
+        redact,
+    });
+    if (flags.json) {
+        process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+    }
     else {
-        ui.warn(`${failed} check(s) failed.`);
+        printHuman(report);
+    }
+    const strict = Boolean(flags.strict);
+    if (report.status === "error" || (strict && report.status === "warn")) {
         process.exit(1);
     }
 }

package/dist/cli/commands/telemetry.js

@@ -0,0 +1,16 @@
+import { ui } from "../lib/ui.js";
+/**
+ * Telemetry posture command. speclaw ships **no** telemetry code — `status`
+ * says so; enable/disable/log are rejected.
+ */
+export async function runTelemetry(flags) {
+    const sub = flags._[0] ?? "status";
+    if (sub === "status") {
+        ui.ok("speclaw includes no telemetry — nothing is collected or transmitted.");
+        ui.plain("Policy: 100% local. There is no enable path and no analytics endpoint.");
+        return;
+    }
+    ui.err(`telemetry ${sub} is unavailable: speclaw does not include telemetry. ` +
+        "Run `speclaw telemetry status`.");
+    process.exit(1);
+}

package/dist/cli/commands/update.js

@@ -79,6 +79,27 @@ const MIGRATIONS = [
             "(no server-side defer_loading).\n" +
             "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
     },
+    {
+        version: "0.3.6",
+        describe: "Doctor JSON diagnostics and stable install one-liner",
+        agentPrompt: "- Mention that `speclaw doctor --json` is the support report (redacted by default) " +
+            "and that the stable install command is `npx @esneiderbravo/speclaw@latest init`.\n" +
+            "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
+    },
+    {
+        version: "0.3.7",
+        describe: "Claude Code mcp_tool hooks pass speclaw_check input via ${…} templates",
+        // 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.",
+    },
 ];
 /**
  * Update speclaw and bring the current project up to date without a full re-init:

package/dist/cli/index.js

@@ -35,8 +35,10 @@ Lawbook (spec-driven workflow)
   lawbook archive <c>      Finalize and archive a change
 
 Other
-  doctor                   Verify the installation
+  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)
+  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
   verify                   Verify laws for CI: exit codes, --sarif, --json, --strict-engines
@@ -59,6 +61,8 @@ const HEADER_COMMANDS = new Set([
     "agent",
     "doctor",
     "budget",
+    "coverage",
+    "telemetry",
     "index",
     "watch",
     "lawbook",
@@ -68,7 +72,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` is machine-consumed and suppresses 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")
@@ -77,6 +83,10 @@ function maybeHeader(cmd, flags) {
         return;
     if (cmd === "budget" && flags.json)
         return;
+    if (cmd === "doctor" && flags.json)
+        return;
+    if (cmd === "coverage" && (flags.json || flags.tap))
+        return;
     header();
 }
 /** Run the handler for a single command. Returns when the command completes. */
@@ -121,6 +131,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 "telemetry":
+            return (await import("./commands/telemetry.js")).runTelemetry(flags);
         case "check":
             return (await import("./commands/check.js")).runCheck(flags);
         case "laws":

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

@@ -55,9 +55,27 @@ 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);
 `;
 /** Schema version stamped into the `meta` table on first creation. */
-export const SCHEMA_VERSION = "4";
+export const SCHEMA_VERSION = "5";
 /** The stamped schema version, or null if the db predates versioning / has no meta table. */
 function readSchemaVersion(db) {
     try {
@@ -89,6 +107,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 coverage_links;
     DROP TABLE IF EXISTS git_history_cache;
     DROP TABLE IF EXISTS node_embeddings;
     DROP TABLE IF EXISTS edges;

package/dist/modules/compass/extract.js

@@ -1,4 +1,9 @@
 import { parse } from "./parser.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 +36,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 +97,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)) {
@@ -79,6 +130,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 +141,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/indexer.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 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 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,12 +147,13 @@ 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;
@@ -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;
         }
@@ -165,6 +193,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());
         db.exec("COMMIT");
     }
     catch (err) {

package/dist/modules/foundation/context-budget.js

@@ -1,12 +1,22 @@
+import { z } from "zod";
 import { registerCompass } from "../compass/register.js";
 import { registerSpec } from "../lawbook/register.js";
 import { registerTools } from "../tools/register.js";
-import { registerFoundation } from "./register.js";
+import { registerFoundationCore } from "./register-core.js";
 import { measureBudget } from "../../shared/budget.js";
-import { isMinimalMode, packageRoot } from "../../shared/exposure.js";
+import { isMinimalMode, packageRoot, shouldExpose } from "../../shared/exposure.js";
+/** Mirrors the `doctor` tool surface without importing `doctor.ts` (avoids a cycle). */
+const DOCTOR_TOOL_FOR_BUDGET = {
+    name: "doctor",
+    description: "Verify the speclaw install; returns a versioned DoctorReport (schemaVersion 1).",
+    inputSchema: { projectPath: z.string() },
+};
 /**
  * Collect tool definitions as the MCP server would register them for a profile.
  *
+ * Uses `registerFoundationCore` plus a static `doctor` stub so budget/doctor
+ * measurement never imports the live `doctor` implementation (module cycle).
+ *
  * @param minimal - Exposure profile.
  */
 export function collectRegisteredTools(minimal) {
@@ -22,7 +32,10 @@ export function collectRegisteredTools(minimal) {
     };
     const opts = { minimal };
     const stub = server;
-    registerFoundation(stub, opts);
+    registerFoundationCore(stub, opts);
+    if (shouldExpose("doctor", minimal)) {
+        tools.push(DOCTOR_TOOL_FOR_BUDGET);
+    }
     registerSpec(stub, opts);
     registerCompass(stub, opts);
     registerTools(stub, opts);