@esneiderbravo/speclaw 0.3.4 → 0.3.7

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/>
 
@@ -91,6 +115,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
@@ -178,7 +226,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/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,21 +1,63 @@
 import { doctor } from "../../modules/foundation/doctor.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 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}`);
+    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/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/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

@@ -67,6 +67,31 @@ const MIGRATIONS = [
             "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.",
+    },
+    {
+        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.
+    },
 ];
 /**
  * Update speclaw and bring the current project up to date without a full re-init:
@@ -108,7 +133,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,
@@ -125,7 +155,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.
@@ -135,8 +165,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");
@@ -154,6 +186,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/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)
 
@@ -33,7 +35,9 @@ 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)
+  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
@@ -55,6 +59,8 @@ const HEADER_COMMANDS = new Set([
     "update",
     "agent",
     "doctor",
+    "budget",
+    "telemetry",
     "index",
     "watch",
     "lawbook",
@@ -64,13 +70,18 @@ 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` and `doctor --json` are machine-consumed and
+ * suppress 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;
+    if (cmd === "doctor" && flags.json)
+        return;
     header();
 }
 /** Run the handler for a single command. Returns when the command completes. */
@@ -113,6 +124,10 @@ 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 "telemetry":
+            return (await import("./commands/telemetry.js")).runTelemetry(flags);
         case "check":
             return (await import("./commands/check.js")).runCheck(flags);
         case "laws":
@@ -129,7 +144,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",
@@ -164,6 +165,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) {
@@ -173,5 +175,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 };
+}