@esneiderbravo/speclaw 0.3.3 → 0.3.5

package/README.md

@@ -82,7 +82,7 @@ too (also `pnpm dlx` / `yarn dlx`) — but installing globally means you can run
 
 | Module | What it does |
 | :-- | :-- |
-| **Foundation** | The project's constitution: `LAWS.md` binding a set of granular standards under `docs/standards/` (base, architecture, backend, frontend, testing, documentation, conventions, lawbook), plus strict `CLAUDE.md` / `AGENTS.md` agent contracts — filled from your real codebase. It also **enforces** them: blocking laws compile into agent hooks that deny a forbidden edit at the keystroke (`speclaw check` / `speclaw_check`), and architectural laws are verified deterministically against the Compass graph — dependency rules (`deps`) and cycles (`graph`) — via `speclaw laws verify` / `law_verify`, which reports each law as passed, failed, skipped, or unknown (an unresolved reference is *unknown*, never a silent pass). |
+| **Foundation** | The project's constitution: `LAWS.md` binding a set of granular standards under `docs/standards/` (base, architecture, backend, frontend, testing, documentation, conventions, lawbook), plus strict `CLAUDE.md` / `AGENTS.md` agent contracts — filled from your real codebase. It also **enforces** them: blocking laws compile into agent hooks that deny a forbidden edit at the keystroke (`speclaw check` / `speclaw_check`), and architectural laws are verified deterministically against the Compass graph — dependency rules (`deps`) and cycles (`graph`) — via `speclaw verify` (CI orchestrator: exit codes, SARIF, markdown) and `speclaw laws verify` / `law_verify`. Each law is reported as passed, failed, skipped, or unknown (an unresolved reference is *unknown*, never a silent pass). |
 | **Compass** | speclaw's own local code graph. Parses your code (tree-sitter) into nodes + edges plus a local vector store, so an agent finds and understands code with a fraction of the tokens a grep/read loop would cost. No LLM, 100% local, lives in `.speclaw/` (gitignored). |
 | **Lawbook** | speclaw's own spec-driven workflow: `draft → build → sync → archive` (and `explore`), backed by `lawbook_*` engine tools. No external CLI. |
 | **Tools** | Opt-in packs of skills and subagents (currently the dev-agents) that agents use for specific tasks. |
@@ -91,6 +91,30 @@ Compass is inspired by [CodeGraph](https://github.com/colbymchenry/codegraph) an
 
 <br/>
 
+## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; Context cost
+
+speclaw publishes and **gates** its own always-on context cost. Measured with a
+deterministic offline estimator (`speclaw/estimate-v1`, about ±8% vs Anthropic's
+tokenizer on this corpus — not a BPE dependency):
+
+| | Tokens |
+| :-- | --: |
+| **speclaw budget (always-on)** | **~11.7k** (budget ceiling **13.0k**) |
+| Spec Kit commands alone | ~18.6k ([spec-kit#1401](https://github.com/github/spec-kit/issues/1401)) |
+
+```bash
+speclaw budget          # human table
+speclaw budget --json   # machine-readable; used by the suite gate
+speclaw init --minimal  # omit setup/lifecycle MCP tools from registration
+```
+
+Raising a number in committed `token-budget.json` is a reviewable PR. Optional
+calibration (never CI): `npm run budget:calibrate` with `ANTHROPIC_API_KEY`.
+MCP servers cannot mark tools `defer_loading` — savings come from shorter
+definitions, omitted registration (`--minimal`), and JIT skill steps.
+
+<br/>
+
 ## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; The spec-driven workflow (Lawbook)
 
 Lawbook is speclaw's answer to the biggest risk with AI agents: **code that
@@ -210,6 +234,35 @@ context. Agents without hooks (Cursor, Codex) enforce the same laws in CI via
 
 <br/>
 
+## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; Verify in CI
+
+`speclaw verify` evaluates your `deps` and `graph` laws against the local Compass
+index. It is deterministic: **no model, no API key, no network.**
+
+```bash
+speclaw verify --ci --sarif speclaw.sarif --json speclaw.json
+```
+
+| Exit | Meaning |
+| :-- | :-- |
+| **0** | No findings at or above `--fail-on` (default `error`) |
+| **1** | At least one finding at or above `--fail-on` |
+| **2** | Usage error (unknown `--fail-on` / `--format`) |
+| **3** | Environment (shallow clone under `--ci`, or an unwritable `--sarif`/`--json` path) |
+| **4** | At least one law was skipped, and `--strict-engines` was set |
+
+On GitHub:
+
+```yaml
+- uses: esneiderbravo/speclaw@v1
+```
+
+`init` / `update` write `.github/workflows/speclaw.yml` only when that path is
+missing — they never overwrite your CI. Make the check required in branch
+protection yourself; speclaw does not.
+
+<br/>
+
 ## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; Staying up to date
 
 speclaw checks for new releases in the background (at most once a day) and nudges

package/dist/cli/commands/budget.js

@@ -0,0 +1,36 @@
+import { ui } from "../lib/ui.js";
+import { formatBudgetTable } from "../../shared/budget.js";
+import { loadDeclaredBudget } from "../../shared/exposure.js";
+import { measureInstallBudget } from "../../modules/foundation/context-budget.js";
+/** Print the context-budget table or JSON. */
+export async function runBudget(flags) {
+    const cwd = process.cwd();
+    const minimal = flags.minimal === true ? true : flags.minimal === false ? false : undefined;
+    const measurement = measureInstallBudget(cwd, minimal);
+    const declared = loadDeclaredBudget();
+    if (flags.json) {
+        console.log(JSON.stringify({
+            schemaVersion: 1,
+            profile: measurement.profile,
+            tools: measurement.tools,
+            skillsAndCommands: measurement.skillsAndCommands,
+            alwaysOnInstructions: measurement.alwaysOnInstructions,
+            pathScoped: measurement.pathScoped,
+            total: measurement.total,
+            toolCount: measurement.toolCount,
+            declared: {
+                tools: declared.surfaces.tools,
+                skillsAndCommands: declared.surfaces.skillsAndCommands,
+                alwaysOnInstructions: declared.surfaces.alwaysOnInstructions,
+                total: measurement.profile === "minimal" ? declared.minimal.total : declared.total,
+            },
+            details: measurement.details,
+        }, null, 2));
+        return;
+    }
+    ui.heading("speclaw budget");
+    console.log(formatBudgetTable(measurement, declared));
+    ui.plain();
+    ui.info(`profile: ${measurement.profile} · tools registered: ${measurement.toolCount}`);
+    ui.info("Spec Kit (commands only), for comparison: ~18,600 — github/spec-kit#1401");
+}

package/dist/cli/commands/doctor.js

@@ -1,8 +1,10 @@
 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 checks = doctor(process.cwd());
+    const cwd = process.cwd();
+    const checks = doctor(cwd);
     ui.heading("speclaw doctor");
     for (const c of checks) {
         if (c.ok)
@@ -10,6 +12,14 @@ export async function runDoctor(_flags) {
         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}`);
+    }
     const failed = checks.filter((c) => !c.ok).length;
     ui.plain();
     if (failed === 0)

package/dist/cli/commands/init.js

@@ -87,7 +87,9 @@ export async function runInit(flags) {
     if (reinit) {
         ui.info("speclaw is already set up here — your existing files are kept; only missing pieces are added.");
     }
-    const report = scaffold(cwd, profile, packs, agents);
+    const report = scaffold(cwd, profile, packs, agents, {
+        minimal: Boolean(flags.minimal),
+    });
     ui.ok(`Foundation ${c.muted("— LAWS.md + 8 standards + CLAUDE.md/AGENTS.md")}`);
     ui.ok(`Lawbook workflow ${c.muted("— draft · build · sync · archive · explore")}`);
     for (const p of packs)

package/dist/cli/commands/update.js

@@ -60,6 +60,25 @@ const MIGRATIONS = [
             "in docs/standards/testing-standards.md (the 'Manual & end-to-end verification' section).\n" +
             "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
     },
+    {
+        version: "0.3.4",
+        describe: "CI verify workflow (if missing) and seed-law merge",
+        agentPrompt: "- If you want pull requests gated on speclaw, add the `speclaw` GitHub check as a " +
+            "required status check in branch protection. speclaw never enables that itself.\n" +
+            "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
+    },
+    {
+        version: "0.3.5",
+        describe: "Context budget: compact map markers and budget-aware agent contracts",
+        agentPrompt: "- In docs/compass.md, ensure the markers `<!-- speclaw:map:start -->` and " +
+            "`<!-- speclaw:map:end -->` exist (usually just above 'Project-specific starting points') " +
+            "so `compass_index` can regenerate the compact project map between them. Do not hand-edit " +
+            "the content between the markers.\n" +
+            "- Optionally note in CLAUDE.md / AGENTS.md that `speclaw budget` reports always-on context " +
+            "cost and that `speclaw init --minimal` / `SPECLAW_MINIMAL=1` omit setup MCP tools " +
+            "(no server-side defer_loading).\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:
@@ -101,7 +120,12 @@ export async function runUpdate(flags) {
             // Re-exec the NEWLY installed binary so migrations run with the new assets
             // and any new feature steps — not this (now-stale) process. Carry --backup
             // through so the refresh honors it after the upgrade.
-            const reArgs = ["update", "--migrate-only", ...(backup ? ["--backup"] : [])];
+            const reArgs = [
+                "update",
+                "--migrate-only",
+                ...(backup ? ["--backup"] : []),
+                ...(flags.minimal ? ["--minimal"] : []),
+            ];
             const re = spawnSync("speclaw", reArgs, {
                 stdio: "inherit",
                 shell: winShell,
@@ -118,7 +142,7 @@ export async function runUpdate(flags) {
                 return;
         }
     }
-    applyProjectMigrations(cwd, backup);
+    applyProjectMigrations(cwd, backup, flags.minimal ? true : undefined);
 }
 /**
  * Additively apply the current version's content and feature steps to a project.
@@ -128,8 +152,10 @@ export async function runUpdate(flags) {
  * @param backup - When true, a locally edited managed file is copied to
  *   `<file>.bak` before it is refreshed; the default overwrites it in place
  *   (recoverable from git) and only reports the overwrite.
+ * @param minimal - When true, persist minimal exposure; when undefined, keep
+ *   the manifest's existing value.
  */
-function applyProjectMigrations(cwd, backup) {
+function applyProjectMigrations(cwd, backup, minimal) {
     const initialized = fs.existsSync(path.join(cwd, "ai-specs")) || fs.existsSync(path.join(cwd, "LAWS.md"));
     if (!initialized) {
         ui.step("Project");
@@ -147,6 +173,7 @@ function applyProjectMigrations(cwd, backup) {
     const report = scaffold(cwd, { project_name: detectProjectName(cwd) }, packs, agents, {
         refreshManaged: true,
         backup,
+        ...(minimal !== undefined ? { minimal } : {}),
     });
     const changed = report.written.filter((w) => !w.includes(".gitignore"));
     if (changed.length) {

package/dist/cli/commands/verify.js

@@ -0,0 +1,118 @@
+import fs from "node:fs";
+import { list } from "../lib/args.js";
+import { ui, c } from "../lib/ui.js";
+import { isShallowRepo } from "../../shared/git-history.js";
+import { pkgVersion } from "../../shared/version.js";
+import { parseFailOn, verifyExitCode } from "../../modules/foundation/ci.js";
+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";
+const FORMATS = new Set(["text", "json", "sarif", "markdown"]);
+/**
+ * `speclaw verify` — the CI orchestrator over {@link verifyLaws}. Formats and
+ * exit codes live here; graph evaluation stays in `verify.ts`. `speclaw check`
+ * (hooks) and `speclaw laws verify` (the thin batch twin) are unchanged.
+ *
+ * @param flags - Parsed CLI flags.
+ */
+export async function runVerify(flags) {
+    const cwd = process.cwd();
+    const ci = Boolean(flags.ci);
+    if (ci)
+        process.env.NO_COLOR = "1";
+    const failOn = parseFailOn(flags["fail-on"]);
+    if (failOn === null) {
+        ui.err(`--fail-on must be error, warn, or info.`);
+        process.exit(2);
+    }
+    const format = flags.format === undefined || flags.format === true ? "text" : String(flags.format);
+    if (!FORMATS.has(format)) {
+        ui.err(`--format must be text, json, sarif, or markdown.`);
+        process.exit(2);
+    }
+    const strict = Boolean(flags["strict-engines"]);
+    const engines = list(flags.engine).filter((e) => e === "deps" || e === "graph");
+    const paths = list(flags.path);
+    if (ci && isShallowRepo(cwd)) {
+        ui.err("Shallow clone — speclaw cannot see the merge base. Check out with fetch-depth: 0.");
+        process.exit(3);
+    }
+    const manifest = loadManifestForVerify(cwd);
+    const report = verifyLaws({
+        projectPath: cwd,
+        paths: paths.length ? paths : undefined,
+        engines: engines.length ? engines : undefined,
+        lawIds: list(flags.law).length ? list(flags.law) : undefined,
+    });
+    const sarifPath = typeof flags.sarif === "string" ? flags.sarif : undefined;
+    const jsonPath = typeof flags.json === "string" ? flags.json : undefined;
+    if (sarifPath) {
+        if (!writeOut(sarifPath, JSON.stringify(toSarif(report, sarifCtx(manifest.laws)), null, 2))) {
+            process.exit(3);
+        }
+    }
+    if (jsonPath) {
+        if (!writeOut(jsonPath, JSON.stringify(report, null, 2)))
+            process.exit(3);
+    }
+    const summaryFile = process.env.GITHUB_STEP_SUMMARY;
+    if (summaryFile) {
+        try {
+            fs.appendFileSync(summaryFile, toMarkdown(report));
+        }
+        catch (err) {
+            ui.warn(`Could not write $GITHUB_STEP_SUMMARY: ${err.message}`);
+        }
+    }
+    printReport(report, format, flags.json === true && !jsonPath);
+    process.exit(verifyExitCode(report, { failOn, strictEngines: strict }));
+}
+function sarifCtx(laws) {
+    return { speclawVersion: pkgVersion(), laws };
+}
+function writeOut(file, body) {
+    try {
+        fs.writeFileSync(file, body.endsWith("\n") ? body : body + "\n");
+        return true;
+    }
+    catch (err) {
+        ui.err(`Cannot write ${file}: ${err.message}`);
+        return false;
+    }
+}
+function printReport(report, format, jsonStdout) {
+    if (jsonStdout || format === "json") {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    if (format === "sarif") {
+        // Rules need the loaded laws; re-read via the same fallback the run used.
+        const laws = loadManifestForVerify(process.cwd()).laws;
+        console.log(JSON.stringify(toSarif(report, sarifCtx(laws)), null, 2));
+        return;
+    }
+    if (format === "markdown") {
+        process.stdout.write(toMarkdown(report));
+        return;
+    }
+    const { summary } = report;
+    ui.heading("speclaw verify");
+    ui.info(`${summary.passed} passed · ${c.red(String(summary.failed))} failed · ` +
+        `${summary.skipped} skipped · ${summary.unknown} unknown ` +
+        `(${report.elapsedMs.toFixed(1)} ms)`);
+    if (summary.evaluated === 0 && summary.skipped === 0) {
+        ui.warn("0 batch laws evaluated — verify is not checking anything.");
+    }
+    for (const f of report.findings) {
+        const at = f.line ? `${f.file}:${f.line}` : f.file;
+        ui.warn(`${c.cream(f.lawId)} — ${at}${f.detail ? ` ${f.detail}` : ""}`);
+    }
+    for (const u of report.unknown)
+        ui.plain(`  ? ${c.cream(u.lawId)} — ${u.detail}`);
+    for (const s of report.skipped) {
+        ui.plain(`  – ${c.cream(s.lawId)} — skipped: ${s.reason}${s.detail ? ` (${s.detail})` : ""}`);
+    }
+    if (report.findings.length === 0 && summary.evaluated > 0)
+        ui.ok("No violations.");
+}

package/dist/cli/index.js

@@ -11,7 +11,9 @@ Install globally so the command is always available:
 
 Setup
   init                     Interactive setup: pick agents, scaffold, index, get the prompt
+                           (--minimal omits setup/lifecycle MCP tools)
   update                   Upgrade speclaw and apply only what's new (no re-init)
+                           (--minimal persists minimal exposure; omit to keep prior)
   agent list               Show which agents are configured
   agent add <id>           Configure another agent later (symlinks + MCP)
 
@@ -34,8 +36,10 @@ Lawbook (spec-driven workflow)
 
 Other
   doctor                   Verify the installation
+  budget                   Measure always-on context cost (tools, skills, instructions)
   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
   mcp                      Start the MCP server (used by your agent's config)
   help                     Show this help
   --version                Print the installed speclaw version
@@ -54,6 +58,7 @@ const HEADER_COMMANDS = new Set([
     "update",
     "agent",
     "doctor",
+    "budget",
     "index",
     "watch",
     "lawbook",
@@ -63,13 +68,15 @@ 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.
+ * child process. `budget --json` is machine-consumed and suppresses the header.
  */
-function maybeHeader(cmd) {
+function maybeHeader(cmd, flags) {
     if (!process.stdout.isTTY && process.env.FORCE_COLOR !== "1")
         return;
     if (!HEADER_COMMANDS.has(cmd))
         return;
+    if (cmd === "budget" && flags.json)
+        return;
     header();
 }
 /** Run the handler for a single command. Returns when the command completes. */
@@ -112,10 +119,14 @@ async function dispatch(cmd, flags) {
             return (await import("./commands/lawbook.js")).runSpec(flags);
         case "doctor":
             return (await import("./commands/doctor.js")).runDoctor(flags);
+        case "budget":
+            return (await import("./commands/budget.js")).runBudget(flags);
         case "check":
             return (await import("./commands/check.js")).runCheck(flags);
         case "laws":
             return (await import("./commands/laws.js")).runLaws(flags);
+        case "verify":
+            return (await import("./commands/verify.js")).runVerify(flags);
         default:
             ui.err(`Unknown command: ${cmd}`);
             console.log(HELP);
@@ -126,7 +137,7 @@ async function dispatch(cmd, flags) {
 async function main() {
     const [cmd, ...rest] = process.argv.slice(2);
     const flags = parseFlags(rest);
-    maybeHeader(cmd);
+    maybeHeader(cmd, flags);
     await dispatch(cmd, flags);
     await maybeNotifyUpdate(cmd);
 }

package/dist/modules/compass/indexer.js

@@ -9,6 +9,7 @@ const SKIP_DIRS = new Set([
     ".git",
     "node_modules",
     "dist",
+    "dist-test",
     "build",
     ".next",
     "out",
@@ -173,5 +174,13 @@ export async function buildIndex(projectPath, onProgress) {
     finally {
         db.close();
     }
+    // Compact map in committed docs/compass.md (between markers) — zero tool-call cost.
+    try {
+        const { writeCompactMap } = await import("./map.js");
+        writeCompactMap(projectPath);
+    }
+    catch {
+        // Map generation must never fail an index run.
+    }
     return stats;
 }

package/dist/modules/compass/map.js

@@ -0,0 +1,114 @@
+import fs from "node:fs";
+import path from "node:path";
+import { openDb } from "./db.js";
+import { estimateTokens } from "../../shared/tokens.js";
+import { loadDeclaredBudget } from "../../shared/exposure.js";
+export const MAP_START = "<!-- speclaw:map:start -->";
+export const MAP_END = "<!-- speclaw:map:end -->";
+/**
+ * Build a compact project map (hubs + top-level layout) from the Compass DB.
+ * Truncates to the declared map token budget.
+ *
+ * @param projectPath - Project root with `.speclaw/index.db`.
+ * @returns Map body text (no markers), or null if the index is missing/empty.
+ */
+export function generateCompactMap(projectPath) {
+    const dbPath = path.join(projectPath, ".speclaw", "index.db");
+    if (!fs.existsSync(dbPath))
+        return null;
+    const db = openDb(projectPath);
+    try {
+        const fileCount = db.prepare("SELECT COUNT(*) AS c FROM files").get().c;
+        const nodeCount = db.prepare("SELECT COUNT(*) AS c FROM nodes").get().c;
+        if (fileCount === 0)
+            return null;
+        const hubs = db
+            .prepare(`SELECT n.name AS name, COUNT(*) AS fan_in
+         FROM edges e
+         JOIN nodes n ON n.id = e.dst_node_id
+         WHERE e.kind = 'call' AND e.dst_node_id IS NOT NULL
+         GROUP BY n.id
+         ORDER BY fan_in DESC
+         LIMIT 12`)
+            .all();
+        const topDirs = db
+            .prepare(`SELECT CASE
+           WHEN instr(path, '/') > 0 THEN substr(path, 1, instr(path, '/') - 1)
+           ELSE path
+         END AS top, COUNT(*) AS c
+         FROM files
+         GROUP BY top
+         ORDER BY c DESC
+         LIMIT 8`)
+            .all();
+        const hubLine = hubs.length === 0
+            ? "hubs: (none yet)"
+            : `hubs: ${hubs.map((h) => `${h.name} ${h.fan_in}`).join(" · ")}`;
+        const dirLine = topDirs.map((d) => `${d.top}/ (${d.c})`).join("  ");
+        let body = [
+            `speclaw · ${fileCount} files · ${nodeCount} nodes`,
+            dirLine,
+            hubLine,
+            "entry: src/server.ts (mcp) · src/cli/index.ts (bin)",
+        ].join("\n");
+        const cap = loadDeclaredBudget().map;
+        let omitted = false;
+        while (estimateTokens(body) > cap && hubs.length > 3) {
+            hubs.pop();
+            omitted = true;
+            const shorter = hubs.length === 0
+                ? "hubs: (truncated)"
+                : `hubs: ${hubs.map((h) => `${h.name} ${h.fan_in}`).join(" · ")}`;
+            body = [
+                `speclaw · ${fileCount} files · ${nodeCount} nodes`,
+                dirLine,
+                shorter,
+                "entry: src/server.ts (mcp) · src/cli/index.ts (bin)",
+                omitted ? "(entries omitted to fit map budget)" : "",
+            ]
+                .filter(Boolean)
+                .join("\n");
+        }
+        if (estimateTokens(body) > cap) {
+            body = [
+                `speclaw · ${fileCount} files · ${nodeCount} nodes`,
+                "entry: src/server.ts (mcp) · src/cli/index.ts (bin)",
+                "(entries omitted to fit map budget)",
+            ].join("\n");
+        }
+        return body;
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Replace content between map markers in `docs/compass.md`. Preserves content
+ * outside markers. Does nothing (with reason) when markers are missing or the
+ * map cannot be generated.
+ *
+ * @param projectPath - Project root.
+ */
+export function writeCompactMap(projectPath) {
+    const compassPath = path.join(projectPath, "docs", "compass.md");
+    if (!fs.existsSync(compassPath)) {
+        return { written: false, reason: "docs/compass.md missing" };
+    }
+    const original = fs.readFileSync(compassPath, "utf8");
+    const start = original.indexOf(MAP_START);
+    const end = original.indexOf(MAP_END);
+    if (start < 0 || end < 0 || end < start) {
+        return { written: false, reason: "map markers missing — not regenerating" };
+    }
+    const map = generateCompactMap(projectPath);
+    if (!map) {
+        // Leave markers but clear body so we don't leave a stale map.
+        const next = original.slice(0, start + MAP_START.length) + "\n" + original.slice(end);
+        if (next !== original)
+            fs.writeFileSync(compassPath, next);
+        return { written: false, reason: "no index or empty graph — map omitted" };
+    }
+    const next = original.slice(0, start + MAP_START.length) + "\n" + map + "\n" + original.slice(end);
+    fs.writeFileSync(compassPath, next);
+    return { written: true };
+}