@esneiderbravo/speclaw 0.3.4 → 0.3.5

package/dist/modules/lawbook/assets/skills/draft/steps/01-ensure-workspace.md

@@ -0,0 +1,5 @@
+# Ensure the workspace exists
+
+If `lawbook/` is missing, run the `lawbook_init` tool once to create it.
+
+Next: read `steps/02-understand.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/draft/steps/02-understand.md

@@ -0,0 +1,12 @@
+# Understand the request and the code
+
+- **Refresh the index first.** Run `compass_index` before reasoning about the
+  code — it is incremental (unchanged files are skipped by hash), so this is
+  cheap and guarantees your decisions rest on the current graph, not a stale one.
+- Clarify what the user wants (feature / fix / refactor) and confirm scope.
+- Use `compass_explore` and `compass_recall` (speclaw's code index) BEFORE
+  grep/read to locate the real code the change touches and its blast radius.
+- Read the governing standards in `docs/standards/` (architecture, backend,
+  frontend, testing) so the change complies with the project's law.
+
+Next: read `steps/03-name-capabilities.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/draft/steps/03-name-capabilities.md

@@ -0,0 +1,14 @@
+# Pick a change name and its capabilities
+
+- **Change name:** kebab-case, action-oriented (e.g. `add-login`,
+  `fix-shift-overlap`). This is the folder under `lawbook/changes/`, and it is
+  per-feature — always distinct.
+- **Capabilities:** run `lawbook_list` to see the canonical capabilities. A
+  capability is the living contract for an area of behavior — it is *not* the
+  change. When your change modifies behavior an existing capability already
+  governs, reuse that capability's **exact** name so `sync` updates its spec.
+  Introduce a new capability only as a deliberate choice for a genuinely distinct
+  area of behavior — never as a near-duplicate (`transfer` next to an existing
+  `transfers`) of one that already exists.
+
+Next: read `steps/04-write-artifacts.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/draft/steps/04-write-artifacts.md

@@ -0,0 +1,41 @@
+# Write the artifacts
+
+Create under `lawbook/changes/<name>/`:
+
+- **proposal.md** — the why, the what, non-goals, and whether migrations are
+  needed. Reference the team's tracker ticket if there is one.
+- **specs/<capability>/spec.md** — the delta spec for each affected capability.
+  `sync` promotes this by overwriting the whole canonical file, so the delta must
+  carry the capability's **full** intended spec. When you are updating an existing
+  capability, **start from the current `lawbook/specs/<capability>/spec.md`** and
+  edit on top of it, so its existing requirements are carried forward — do not
+  author it from scratch, or promotion will silently drop them. Use normative
+  language and testable scenarios:
+  ```markdown
+  # <Capability>
+
+  ### Requirement: <name>
+  The system SHALL <requirement>.
+
+  #### Scenario: <name>
+  - Given <context>
+  - When <action>
+  - Then <observable outcome>
+  ```
+- **design.md** — always: approach, alternatives weighed, and the trade-offs
+  behind the decision. For a small change, keep it short — but write it.
+- **tasks.md** — ordered, checkable steps. MUST include the mandatory steps
+  from `lawbook/config.yaml` (feature branch first; tests reviewed and run;
+  manual verification executed by the agent; discipline reports produced; docs
+  updated; archive within the PR).
+- **reports/** — create the folder with a short `reports/README.md` naming the
+  discipline reports the change will need — one per discipline it touches, from an
+  open set (`backend.md`, `frontend.md`, `api.md`, `database.md`, `infra.md`,
+  `security.md`, … — and `api.md` is required when the change touches any API
+  surface) that `build` will fill, following the required report structure
+  (header · gates table · tests added · spec-scenario coverage · pre-existing
+  failures · pending manual · verdict — see the `build` skill's discipline-reports
+  step). Every change ships this folder; archive is blocked until it holds at
+  least one discipline report.
+
+Next: read `steps/05-validate.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/draft/steps/05-validate.md

@@ -0,0 +1,11 @@
+# Validate
+
+Run the `lawbook_validate` tool for the change and fix every issue it reports
+(missing artifacts, non-normative specs, missing scenarios) before handing off
+to implementation. Read its advisory **warnings** too: a near-duplicate
+capability name usually means you should reuse the existing capability's exact
+name, and a dropped-requirement warning means the delta should start from the
+canonical. Warnings do not block, but resolve them unless the divergence is
+intentional.
+
+Next: read `steps/06-hand-off.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/draft/steps/06-hand-off.md

@@ -0,0 +1,5 @@
+# Hand off
+
+Summarize the change and tell the user it's ready to `build`.
+
+No further steps remain — draft workflow complete.

package/dist/modules/lawbook/assets/skills/explore/SKILL.md

@@ -5,27 +5,11 @@ description: Enter explore mode — a thinking partner for investigating an idea
 
 # explore — Think it through
 
-A low-commitment mode for investigating ideas and the codebase before (or
-during) a change. Nothing is written to `lawbook/` here — the output is shared
-understanding and a recommended direction.
+A low-commitment thinking partner for investigating ideas and the codebase
+before (or during) a change. Nothing is written to `lawbook/` — the output is
+shared understanding and a recommended direction.
 
-## How to explore
+Use when the user wants to think something through, understand how something
+works, or clarify requirements before drafting a change.
 
-- **Refresh the index first.** Run `compass_index` before investigating — it is
-  incremental (unchanged files skipped by hash), so it is cheap and keeps your
-  reasoning on the current graph rather than a stale one.
-- **Understand the code first.** Use `compass_recall` to find relevant code by
-  meaning and `compass_explore` to read a symbol's source plus its callers and
-  callees — before grep/read.
-- **Ask sharp questions** to surface hidden assumptions, constraints, and edge
-  cases. Confirm scope and non-goals.
-- **Check the law.** Read the relevant `docs/standards/` so any direction you
-  propose already fits the project's architecture and conventions.
-- **Weigh approaches.** Lay out the viable options with trade-offs and give a
-  recommendation, not an exhaustive survey.
-
-## Output
-
-A concise summary: the problem as understood, the constraints, the recommended
-approach, and the open questions. When the direction is clear, offer to `draft`
-the change.
+Read `steps/01-investigate.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/explore/steps/01-investigate.md

@@ -0,0 +1,16 @@
+# Investigate
+
+- **Refresh the index first.** Run `compass_index` before investigating — it is
+  incremental (unchanged files skipped by hash), so it is cheap and keeps your
+  reasoning on the current graph rather than a stale one.
+- **Understand the code first.** Use `compass_recall` to find relevant code by
+  meaning and `compass_explore` to read a symbol's source plus its callers and
+  callees — before grep/read.
+- **Ask sharp questions** to surface hidden assumptions, constraints, and edge
+  cases. Confirm scope and non-goals.
+- **Check the law.** Read the relevant `docs/standards/` so any direction you
+  propose already fits the project's architecture and conventions.
+- **Weigh approaches.** Lay out the viable options with trade-offs and give a
+  recommendation, not an exhaustive survey.
+
+Next: read `steps/02-summarize.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/explore/steps/02-summarize.md

@@ -0,0 +1,7 @@
+# Summarize
+
+Produce a concise summary: the problem as understood, the constraints, the
+recommended approach, and the open questions. When the direction is clear,
+offer to `draft` the change.
+
+No further steps remain — explore workflow complete.

package/dist/modules/lawbook/assets/skills/sync/SKILL.md

@@ -13,33 +13,4 @@ become the source of truth but the change isn't finished (e.g. multi-PR work).
 promoting, YOU reconcile the delta specs against what was actually built, so the
 specs that become canonical describe reality, not just the original draft.
 
-## Steps
-
-1. Confirm which change to sync (run `lawbook_list` if unsure).
-
-2. **Reconcile code → delta specs (agent-executed).** Before promoting, compare
-   what was built against the change's delta specs:
-   - Reconstruct what shipped: `git diff <branch-point>...HEAD` for the change's
-     branch, then `compass_explore` / `compass_impact` on the touched symbols to
-     understand behavior, not just changed lines.
-   - Diff intent vs reality: list behavior that is implemented but missing from,
-     or contradicted by, `lawbook/changes/<name>/specs/**`.
-   - Write the gaps into the delta specs — normative `SHALL`/`MUST` requirements
-     under `### Requirement:` and `#### Scenario:` acceptance criteria — so the
-     contract matches what was built. Capture only behavior that actually
-     exists; never invent scope that was not implemented.
-   - If nothing drifted, make no edits and say so.
-
-3. Run `lawbook_validate` for the change; do not sync a change whose specs are
-   invalid.
-
-4. Run the `lawbook_sync` tool for the change. It copies each
-   `lawbook/changes/<name>/specs/<capability>/spec.md` over the canonical
-   `lawbook/specs/<capability>/spec.md` and reports what it promoted, flagging
-   each as **created** (new capability) or **updated** (overwrote an existing
-   one). A capability you expected to update showing up as *created* means the
-   delta forked a near-duplicate — fix the name before promoting.
-
-5. Report to the user what you reconciled (or that nothing drifted) and the
-   promoted files (created vs updated). The change stays active — `archive` it
-   when it's fully done.
+Read `steps/01-confirm.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/sync/steps/01-confirm.md

@@ -0,0 +1,5 @@
+# Confirm which change to sync
+
+Confirm which change to sync (run `lawbook_list` if unsure).
+
+Next: read `steps/02-reconcile.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/sync/steps/02-reconcile.md

@@ -0,0 +1,16 @@
+# Reconcile code → delta specs (agent-executed)
+
+Before promoting, compare what was built against the change's delta specs:
+
+- Reconstruct what shipped: `git diff <branch-point>...HEAD` for the change's
+  branch, then `compass_explore` / `compass_impact` on the touched symbols to
+  understand behavior, not just changed lines.
+- Diff intent vs reality: list behavior that is implemented but missing from,
+  or contradicted by, `lawbook/changes/<name>/specs/**`.
+- Write the gaps into the delta specs — normative `SHALL`/`MUST` requirements
+  under `### Requirement:` and `#### Scenario:` acceptance criteria — so the
+  contract matches what was built. Capture only behavior that actually
+  exists; never invent scope that was not implemented.
+- If nothing drifted, make no edits and say so.
+
+Next: read `steps/03-validate.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/sync/steps/03-validate.md

@@ -0,0 +1,6 @@
+# Validate
+
+Run `lawbook_validate` for the change; do not sync a change whose specs are
+invalid.
+
+Next: read `steps/04-promote.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/sync/steps/04-promote.md

@@ -0,0 +1,10 @@
+# Promote
+
+Run the `lawbook_sync` tool for the change. It copies each
+`lawbook/changes/<name>/specs/<capability>/spec.md` over the canonical
+`lawbook/specs/<capability>/spec.md` and reports what it promoted, flagging
+each as **created** (new capability) or **updated** (overwrote an existing
+one). A capability you expected to update showing up as *created* means the
+delta forked a near-duplicate — fix the name before promoting.
+
+Next: read `steps/05-report.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/sync/steps/05-report.md

@@ -0,0 +1,7 @@
+# Report
+
+Report to the user what you reconciled (or that nothing drifted) and the
+promoted files (created vs updated). The change stays active — `archive` it
+when it's fully done.
+
+No further steps remain — sync workflow complete.

package/dist/modules/lawbook/register.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { z } from "zod";
-import { text } from "../../shared/mcp.js";
+import { defineTool, text } from "../../shared/mcp.js";
+import { shouldExpose } from "../../shared/exposure.js";
 import { assetsDir } from "../../shared/paths.js";
 import { copyRendered } from "../../shared/install.js";
 import { specInit, specValidate, specSync, specArchive, specList } from "./engine.js";
@@ -16,41 +17,21 @@ export function installWorkflow(projectPath, vars, report, opts) {
     copyRendered(path.join(ASSETS, "commands"), path.join(aiSpecs, "commands", "lawbook"), vars, report, opts);
     copyRendered(path.join(ASSETS, "rules"), path.join(aiSpecs, "rules"), vars, report, opts);
 }
-// ─── The spec module: speclaw's own spec-driven workflow (no external OpenSpec) ───
-// Mechanical operations behind the draft/build/sync/archive/explore commands.
 /** Register the spec workflow MCP tools (init, list, validate, sync, archive). */
-export function registerSpec(server) {
-    server.registerTool("lawbook_init", {
-        description: "Initialize speclaw's spec-driven workflow in a project: creates lawbook/ (specs/, changes/, changes/archive/, config.yaml, README). Idempotent — never overwrites existing files.",
-        inputSchema: { projectPath: z.string().describe("Absolute path to the project") },
-    }, async ({ projectPath }) => text(specInit(projectPath)));
-    server.registerTool("lawbook_list", {
-        description: "List the spec workspace: active changes, archived changes, and canonical capabilities under spec/.",
-        inputSchema: { projectPath: z.string().describe("Absolute path to the project") },
-    }, async ({ projectPath }) => text(specList(projectPath)));
-    server.registerTool("lawbook_validate", {
-        description: "Validate a change's artifacts: proposal.md and tasks.md present, and delta specs use normative language (SHALL/MUST), '### Requirement:' headers, and '#### Scenario:' acceptance criteria. Returns the blocking issues to fix plus advisory (non-blocking) warnings — a capability name that resembles an existing canonical one, or requirements dropped versus the canonical. Used by the draft/build commands before proceeding.",
-        inputSchema: {
-            projectPath: z.string().describe("Absolute path to the project"),
-            change: z.string().describe("Change name (folder under lawbook/changes/)"),
-        },
-    }, async ({ projectPath, change }) => text(specValidate(projectPath, change)));
-    server.registerTool("lawbook_sync", {
-        description: "Promote a change's delta specs into the canonical lawbook/specs/ (per capability), without archiving. Reports each promoted spec as created (new capability) or updated (overwrote an existing one). Backs the `sync` command.",
-        inputSchema: {
-            projectPath: z.string().describe("Absolute path to the project"),
-            change: z.string().describe("Change name (folder under lawbook/changes/)"),
-        },
-    }, async ({ projectPath, change }) => text(specSync(projectPath, change)));
-    server.registerTool("lawbook_archive", {
-        description: "Finalize a change: sync its delta specs into lawbook/specs/, then move it to lawbook/changes/archive/<date>-<name>/. Backs the `archive` command. Pass today's date as YYYY-MM-DD.",
-        inputSchema: {
-            projectPath: z.string().describe("Absolute path to the project"),
-            change: z.string().describe("Change name (folder under lawbook/changes/)"),
-            date: z
-                .string()
-                .regex(/^\d{4}-\d{2}-\d{2}$/)
-                .describe("Today's date, YYYY-MM-DD"),
-        },
+export function registerSpec(server, opts = {}) {
+    const minimal = Boolean(opts.minimal);
+    const add = (name, description, inputSchema, handler) => {
+        if (!shouldExpose(name, minimal))
+            return;
+        defineTool(server, { name, description, inputSchema, handler });
+    };
+    add("lawbook_init", "Create the lawbook/ workspace (specs, changes, archive, config). Idempotent.", { projectPath: z.string() }, async ({ projectPath }) => text(specInit(projectPath)));
+    add("lawbook_list", "List active changes, archives, and canonical capabilities under lawbook/.", { projectPath: z.string() }, async ({ projectPath }) => text(specList(projectPath)));
+    add("lawbook_validate", "Validate a change's proposal, tasks, and delta specs before build or sync.", { projectPath: z.string(), change: z.string() }, async ({ projectPath, change }) => text(specValidate(projectPath, change)));
+    add("lawbook_sync", "Promote a change's delta specs into canonical lawbook/specs/ without archiving.", { projectPath: z.string(), change: z.string() }, async ({ projectPath, change }) => text(specSync(projectPath, change)));
+    add("lawbook_archive", "Sync a change into canonical specs, then move it under changes/archive/.", {
+        projectPath: z.string(),
+        change: z.string(),
+        date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
     }, async ({ projectPath, change, date }) => text(specArchive(projectPath, change, date)));
 }

package/dist/modules/tools/register.js

@@ -1,27 +1,27 @@
 import { z } from "zod";
-import { text } from "../../shared/mcp.js";
+import { defineTool, text } from "../../shared/mcp.js";
+import { shouldExpose } from "../../shared/exposure.js";
 import { emptyReport } from "../../shared/install.js";
 import { refreshAgents } from "../../shared/agents.js";
 import { loadPacks, installPack } from "./packs.js";
 export { loadPacks, installPack };
-// ─── The tools module: opt-in packs of skills, agents, and commands ───
 /** Register the tools-module MCP tools (list_packs, add_pack). */
-export function registerTools(server) {
-    server.registerTool("list_packs", {
-        description: "List the available speclaw skill packs and what each contains.",
-        inputSchema: {},
-    }, async () => text(loadPacks()));
-    server.registerTool("add_pack", {
-        description: "Add a single pack to an already-initialized project, then refresh IDE symlinks. Pass template vars (organization, ...) if the pack needs them.",
-        inputSchema: {
-            projectPath: z.string().describe("Absolute path to the project"),
-            pack: z.string().describe("Pack name (see list_packs)"),
-            vars: z.record(z.string()).optional().describe("Template variables for rendering"),
-        },
+export function registerTools(server, opts = {}) {
+    const minimal = Boolean(opts.minimal);
+    const add = (name, description, inputSchema, handler) => {
+        if (!shouldExpose(name, minimal))
+            return;
+        defineTool(server, { name, description, inputSchema, handler });
+    };
+    add("list_packs", "List available speclaw skill packs and what each contains.", {}, async () => text(loadPacks()));
+    add("add_pack", "Install one pack into an initialized project and refresh IDE symlinks.", {
+        projectPath: z.string(),
+        pack: z.string(),
+        vars: z.record(z.string()).optional(),
     }, async ({ projectPath, pack, vars }) => {
         const report = emptyReport();
         installPack(projectPath, pack, vars ?? {}, report);
-        refreshAgents(projectPath, report); // link the new content into already-configured agents
+        refreshAgents(projectPath, report);
         return text(report);
     });
 }

package/dist/server.js

@@ -4,14 +4,20 @@ import { registerCompass } from "./modules/compass/register.js";
 import { registerSpec } from "./modules/lawbook/register.js";
 import { registerFoundation } from "./modules/foundation/register.js";
 import { registerTools } from "./modules/tools/register.js";
-/** Build the speclaw MCP server with every module's tools registered. */
-export function buildServer() {
+import { isMinimalMode } from "./shared/exposure.js";
+/**
+ * Build the speclaw MCP server with every module's tools registered.
+ *
+ * @param opts - Optional exposure overrides; defaults to {@link isMinimalMode}.
+ */
+export function buildServer(opts = {}) {
+    const minimal = opts.minimal ?? isMinimalMode();
     const server = new McpServer({ name: "speclaw", version: "0.1.0" });
-    // Each module contributes its own MCP tools. Adding a module = one line here.
-    registerFoundation(server); // init_project, scaffold, configure_agent, doctor
-    registerSpec(server); // lawbook_init, lawbook_validate, lawbook_sync, lawbook_archive, lawbook_list
-    registerCompass(server); // compass_index, explore, search, recall, impact, trace, watch
-    registerTools(server); // list_packs, add_pack
+    const reg = { minimal };
+    registerFoundation(server, reg);
+    registerSpec(server, reg);
+    registerCompass(server, reg);
+    registerTools(server, reg);
     return server;
 }
 /** Start the MCP server over stdio (used by `speclaw mcp`). */

package/dist/shared/budget.js

@@ -0,0 +1,159 @@
+import fs from "node:fs";
+import path from "node:path";
+import { isMinimalMode, loadDeclaredBudget, packageRoot } from "./exposure.js";
+import { toolDefinitionTokens } from "./schema-tokens.js";
+import { estimateTokens } from "./tokens.js";
+/**
+ * Measure always-on context cost across the four surfaces.
+ *
+ * @param opts - Paths and optional pre-collected tool definitions.
+ * @returns Structured measurement; `total` excludes path-scoped surface D.
+ */
+export function measureBudget(opts = {}) {
+    const projectPath = opts.projectPath ?? process.cwd();
+    const packagePath = opts.packagePath ?? packageRoot();
+    const minimal = opts.minimal ?? isMinimalMode(projectPath);
+    const toolDefs = opts.tools ?? [];
+    const toolDetails = toolDefs.map((t) => ({
+        name: t.name,
+        tokens: toolDefinitionTokens(t),
+    }));
+    const tools = toolDetails.reduce((s, t) => s + t.tokens, 0);
+    const skillRoots = [
+        path.join(packagePath, "src/modules/lawbook/assets/skills"),
+        path.join(packagePath, "dist/modules/lawbook/assets/skills"),
+        path.join(projectPath, "ai-specs/skills"),
+    ];
+    const commandRoots = [
+        path.join(packagePath, "src/modules/lawbook/assets/commands"),
+        path.join(packagePath, "dist/modules/lawbook/assets/commands"),
+        path.join(projectPath, "ai-specs/commands"),
+    ];
+    const skillFiles = firstExistingFiles(skillRoots, (dir) => collectSkillBudgetFiles(dir));
+    const commandFiles = firstExistingFiles(commandRoots, (dir) => listFilesRecursive(dir).filter((f) => f.endsWith(".md")));
+    const scDetails = [...skillFiles, ...commandFiles].map((f) => ({
+        path: path.relative(packagePath, f) || path.relative(projectPath, f) || f,
+        tokens: estimateTokens(safeRead(f)),
+    }));
+    const skillsAndCommands = scDetails.reduce((s, x) => s + x.tokens, 0);
+    const alwaysOnPaths = ["CLAUDE.md", "AGENTS.md", "LAWS.md", "docs/compass.md"].map((rel) => path.join(projectPath, rel));
+    const alwaysOnDetails = alwaysOnPaths
+        .filter((p) => fs.existsSync(p))
+        .map((p) => ({
+        path: path.relative(projectPath, p),
+        tokens: estimateTokens(safeRead(p)),
+    }));
+    const alwaysOnInstructions = alwaysOnDetails.reduce((s, x) => s + x.tokens, 0);
+    const pathScopedDetails = collectPathScoped(projectPath);
+    const pathScoped = pathScopedDetails.reduce((s, x) => s + x.tokens, 0);
+    return {
+        tools,
+        skillsAndCommands,
+        alwaysOnInstructions,
+        pathScoped,
+        total: tools + skillsAndCommands + alwaysOnInstructions,
+        profile: minimal ? "minimal" : "full",
+        toolCount: toolDefs.length,
+        details: {
+            tools: toolDetails,
+            skillsAndCommands: scDetails,
+            alwaysOn: alwaysOnDetails,
+            pathScoped: pathScopedDetails,
+        },
+    };
+}
+/**
+ * Format a human-readable budget table.
+ *
+ * @param m - Measurement.
+ * @param declared - Optional declared ceilings for an ok/over column.
+ */
+export function formatBudgetTable(m, declared) {
+    const d = declared ?? loadDeclaredBudget();
+    const row = (label, tokens, cap) => {
+        const capStr = cap === null ? "—".padStart(8) : String(cap).padStart(8);
+        const status = cap === null ? "" : tokens <= cap ? "  ok" : "  OVER";
+        return `${label.padEnd(40)} ${String(tokens).padStart(8)} ${capStr}${status}`;
+    };
+    const lines = [
+        "Superficie                              tokens   presupuesto",
+        row(`A  tools MCP (${m.toolCount}, ${m.profile})`, m.tools, d.surfaces.tools),
+        row("B  skills + commands", m.skillsAndCommands, d.surfaces.skillsAndCommands),
+        row("C  always-on instructions", m.alwaysOnInstructions, d.surfaces.alwaysOnInstructions),
+        row("D  path-scoped rules", m.pathScoped, null),
+        `${"".padEnd(40)} ${"──────".padStart(8)} ${"──────".padStart(8)}`,
+        row("TOTAL always-on", m.total, m.profile === "minimal" ? d.minimal.total : d.total),
+    ];
+    return lines.join("\n");
+}
+function safeRead(file) {
+    try {
+        return fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function listFilesRecursive(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...listFilesRecursive(full));
+        else
+            out.push(full);
+    }
+    return out;
+}
+/** Skill budget: dispatcher SKILL.md + only that counts for B's "loaded at turn" description;
+ * for always-present skill index we count SKILL.md bodies (dispatchers) fully and step files
+ * are loaded on demand — still include step files in B per design (commands full; skills
+ * frontmatter+description each turn). For simplicity and honesty we count entire SKILL.md
+ * (dispatcher) and do NOT count steps/ toward always-on B (JIT). */
+function collectSkillBudgetFiles(skillsRoot) {
+    if (!fs.existsSync(skillsRoot))
+        return [];
+    const files = [];
+    for (const entry of fs.readdirSync(skillsRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const skillMd = path.join(skillsRoot, entry.name, "SKILL.md");
+        if (fs.existsSync(skillMd))
+            files.push(skillMd);
+    }
+    return files;
+}
+function firstExistingFiles(roots, collect) {
+    for (const root of roots) {
+        if (!fs.existsSync(root))
+            continue;
+        const files = collect(root);
+        if (files.length)
+            return files;
+    }
+    return [];
+}
+function collectPathScoped(projectPath) {
+    const details = [];
+    const ruleDirs = [
+        path.join(projectPath, ".claude/rules"),
+        path.join(projectPath, "ai-specs/rules"),
+    ];
+    for (const dir of ruleDirs) {
+        if (!fs.existsSync(dir))
+            continue;
+        for (const f of listFilesRecursive(dir).filter((p) => p.endsWith(".md"))) {
+            const body = safeRead(f);
+            // Heuristic: frontmatter with paths: means path-scoped lazy load.
+            if (/^---[\s\S]*?^paths:\s*$/m.test(body) || /^---[\s\S]*?^paths:/m.test(body)) {
+                details.push({
+                    path: path.relative(projectPath, f),
+                    tokens: estimateTokens(body),
+                });
+            }
+        }
+    }
+    return details;
+}