@esneiderbravo/speclaw 0.3.13 → 1.0.0

package/dist/cli/commands/query.js

@@ -1,6 +1,8 @@
-import { explore, search, recall, impact, trace } from "../../modules/compass/query.js";
+import { explore, impact, trace } from "../../modules/compass/query.js";
+import { hybridSearch } from "../../modules/compass/hybrid.js";
 import { affectedTests } from "../../modules/compass/affected.js";
 import { hotspots, coupling } from "../../modules/compass/hotspots.js";
+import { diffContext, formatDiffContext } from "../../modules/compass/diff-context.js";
 import { list } from "../lib/args.js";
 import { ui } from "../lib/ui.js";
 /**
@@ -15,6 +17,9 @@ export async function runQuery(cmd, flags) {
     const cwd = process.cwd();
     const args = flags._;
     const asJson = Boolean(flags.json);
+    const focus = list(flags.focus);
+    const maxTokens = flags["max-tokens"] ? Number(flags["max-tokens"]) : undefined;
+    const explain = Boolean(flags.explain);
     try {
         switch (cmd) {
             case "explore": {
@@ -33,16 +38,34 @@ export async function runQuery(cmd, flags) {
                 r.callers?.forEach((c) => ui.info(`${c.name} (${c.file}:${c.line})`));
                 return;
             }
-            case "search": {
-                const hits = search(cwd, need(args[0], "search <query>"));
-                ui.heading(`${hits.length} result(s)`);
-                hits.forEach((h) => ui.info(`${h.name} (${h.kind}) ${h.file}:${h.line}`));
-                return;
-            }
+            case "search":
             case "recall": {
-                const hits = await recall(cwd, need(args[0], 'recall "<query>"'));
-                ui.heading(`${hits.length} result(s) by meaning`);
-                hits.forEach((h) => ui.info(`${h.score.toFixed(3)}  ${h.name} (${h.kind}) ${h.file}:${h.line}`));
+                const q = need(args[0], cmd === "recall" ? 'recall "<query>"' : "search <query>");
+                const mode = cmd === "recall" ? "concept" : "exact";
+                const result = await hybridSearch(cwd, q, {
+                    mode,
+                    focus: focus.length ? focus : undefined,
+                    maxTokens,
+                });
+                if (asJson) {
+                    console.log(JSON.stringify(result, null, 2));
+                    return;
+                }
+                ui.heading(`${result.hits.length} hybrid hit(s) · route=${result.route} · tokens=${result.tokens}/${result.budget}`);
+                if (result.degraded.length)
+                    ui.warn(`degraded: ${result.degraded.join(", ")}`);
+                if (result.focus.length)
+                    ui.info(`focus: ${result.focus.join(", ")}`);
+                for (const h of result.hits) {
+                    const sig = explain
+                        ? `  [bm25=${h.signals.bm25Rank ?? "-"} knn=${h.signals.knnRank ?? "-"} name=${h.signals.nameRank ?? "-"} pr=${h.signals.pagerank.toFixed(4)} hops=${h.signals.hops} score=${h.signals.score.toFixed(4)}]`
+                        : "";
+                    ui.info(`${h.name} (${h.kind}) ${h.file}:${h.line}${sig}`);
+                }
+                if (explain && result.rendered) {
+                    ui.heading("TreeContext");
+                    console.log(result.rendered);
+                }
                 return;
             }
             case "impact": {
@@ -161,6 +184,25 @@ export async function runQuery(cmd, flags) {
                 result.warnings.forEach((w) => ui.warn(w));
                 return;
             }
+            case "diff-context": {
+                const files = list(flags.file);
+                const rev = typeof flags.rev === "string" ? flags.rev : undefined;
+                if (files.length === 0 && !rev && !flags.worktree) {
+                    need(undefined, "diff-context [--file <path>...] [--rev <ref>] [--worktree]");
+                }
+                const result = diffContext({
+                    projectPath: cwd,
+                    rev: flags.worktree ? "WORKTREE" : rev,
+                    paths: files.length ? files : undefined,
+                    mode: flags.full ? "full" : "brief",
+                });
+                if (asJson) {
+                    console.log(JSON.stringify(result, null, 2));
+                    return;
+                }
+                console.log(formatDiffContext(result));
+                return;
+            }
             case "trace": {
                 const r = trace(cwd, need(args[0], "trace <from> <to>"), need(args[1], "trace <from> <to>"));
                 ui.heading(`Trace ${r.from} → ${r.to}`);

package/dist/cli/commands/update.js

@@ -136,11 +136,41 @@ const MIGRATIONS = [
             "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
     },
     {
-        version: "0.3.13",
-        describe: "Bugfix specs — draft --bug, bugfix.md, lawbook_investigate",
-        agentPrompt: "- Mention bug changes: `speclaw lawbook draft --bug`, `bugfix.md` (repro + regression + prevention), " +
-            "and `lawbook_investigate` / the investigate skill for graph-backed RCA. Feature ceremony unchanged; " +
-            "`changeType: bug` in `change.json`. Security-withheld mode is not in this release.\n" +
+        version: "0.4.0",
+        describe: "Tool surface — eight canonical MCP tools, aliases deprecated",
+        agentPrompt: "- MCP exposes eight canonical tools: `compass_explore`, `compass_find`, `compass_diff_context`, " +
+            "`compass_index`, `lawbook_change`, `lawbook_investigate`, `speclaw_setup`, `speclaw_check`. " +
+            "Retired names (e.g. `compass_search`, `lawbook_validate`, `init_project`) are aliases with " +
+            "`[deprecated]` responses — prefer the canonical names. `scaffold`, `doctor`, `compass_visualize`, " +
+            "and `law_verify` are CLI-only. Minimal profile omits setup/check/investigate/index.\n" +
+            "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
+    },
+    {
+        version: "0.4.1",
+        describe: "Rule integrity — speclaw.lock digests + injection scan",
+        agentPrompt: "- Mention committed `speclaw.lock` at the repo root (never under `.speclaw/`), " +
+            "`speclaw laws lock` / `accept` / `scan`, and that digest acceptance is interactive TTY only " +
+            "(never via MCP). `speclaw verify` folds integrity findings with deps/graph. " +
+            "Strict paths include AGENTS.md / CLAUDE.md / compiled rules; standards docs are advisory.\n" +
+            "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
+    },
+    {
+        version: "0.4.2",
+        describe: "Spec ownership — team.owners → CODEOWNERS",
+        agentPrompt: '- Optional `team.owners` in `lawbook/config.yaml` maps capability names (and `"*"`) to ' +
+            "`@user` / `@org/team` / email owners. Run `speclaw owners --write` to compile a managed " +
+            "block at the **end** of `.github/CODEOWNERS` (GitHub: last match wins). `speclaw doctor` " +
+            "errors if content appears after the end marker. No new MCP tool — CLI only. " +
+            "deriveFromTraceability is not enabled in this release.\n" +
+            "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
+    },
+    {
+        version: "1.0.0",
+        describe: "speclaw 1.0 — official release (enforcement + graph + lawbook + owners)",
+        agentPrompt: "- speclaw **1.0** is the official release: Foundation (hooks + `speclaw.lock` integrity), " +
+            "Compass (schema 10, eight canonical MCP tools), Lawbook (ceremony 0–3, coverage, drift, " +
+            "bugfix), and Team (`team.owners` → `speclaw owners --write`). Install remains " +
+            "`npx @esneiderbravo/speclaw@latest init`. CI consumers use `esneiderbravo/speclaw@v1`.\n" +
             "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
     },
 ];

package/dist/cli/commands/verify.js

@@ -8,6 +8,7 @@ import { toMarkdown } from "../../modules/foundation/report-md.js";
 import { toSarif } from "../../modules/foundation/sarif.js";
 import { loadManifestForVerify } from "../../modules/foundation/laws.js";
 import { verifyLaws } from "../../modules/foundation/verify.js";
+import { foldIntegrityIntoReport, verifyIntegrity } from "../../modules/foundation/integrity.js";
 import { driftFindingsForVerify } from "../../modules/lawbook/drift.js";
 const FORMATS = new Set(["text", "json", "sarif", "markdown"]);
 /**
@@ -46,6 +47,13 @@ export async function runVerify(flags) {
         engines: engines.length ? engines : undefined,
         lawIds: list(flags.law).length ? list(flags.law) : undefined,
     });
+    // Rule-file integrity (speclaw.lock digests + injection scan). Soft when no lock.
+    // Covers: req~integrity-verify~1
+    const integrity = verifyIntegrity({ projectPath: cwd });
+    foldIntegrityIntoReport(report, integrity);
+    if (integrity.guidance && format === "text" && flags.json !== true) {
+        ui.info(integrity.guidance);
+    }
     // Structural spec↔code drift (when anchors exist) contributes semantic/deleted
     // findings into the same report stream used by SARIF / exit codes.
     for (const f of driftFindingsForVerify(cwd)) {

package/dist/cli/index.js

@@ -18,13 +18,14 @@ Setup
   agent add <id>           Configure another agent later (symlinks + MCP)
 
 Compass (code intelligence — the same surface agents use via MCP)
-  index                    (Re)build the local code graph, with progress
+  index                    (Re)build the local code graph (--force / --prune)
   watch                    Keep the index fresh on file changes
   explore <node>           A node's source + callers/callees
-  search <query>           Find nodes by name/keyword
-  recall "<query>"         Find code by meaning (semantic)
+  search <query>           Hybrid find (BM25+vector+name); --focus --max-tokens --explain
+  recall "<query>"         Hybrid find with concept weights; same flags as search
   impact <node>            Blast radius (grouped by module; --flat / --json)
   affected-tests           Tests affected by a change (--file / --from-diff / --json)
+  diff-context             Change context for a diff (--file / --rev / --worktree / --json)
   hotspots                 Rank files by recent churn × AST complexity (--json / --sort)
   coupling <file>          Temporal co-change partners for a file (--json)
   trace <from> <to>        A call path between two nodes
@@ -46,10 +47,16 @@ Other
   budget                   Measure always-on context cost (tools, skills, instructions)
   coverage                 Requirement → impl → test coverage (--json, --tap, --adopt, --write)
   drift                    Spec↔code drift (--json, --reseal, --reverse, --fail-on)
+  owners                   Compile team.owners → .github/CODEOWNERS (--write / --check / --diff)
   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
+  laws compile             Compile laws into agent rule dialects (AGENTS / Claude / Cursor / …)
+  laws import              Import third-party rules as draft laws (--from rulesync)
+  laws lock                Create/refresh committed speclaw.lock digests for rule files
+  laws accept <path>       Interactively accept a changed rule-file digest (TTY only)
+  laws scan                Scan rule/skill files for prompt-injection patterns
+  verify                   Verify laws + integrity 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
@@ -73,6 +80,7 @@ const HEADER_COMMANDS = new Set([
     "coverage",
     "drift",
     "telemetry",
+    "owners",
     "index",
     "watch",
     "lawbook",
@@ -144,6 +152,7 @@ async function dispatch(cmd, flags) {
         case "impact":
         case "trace":
         case "affected-tests":
+        case "diff-context":
         case "hotspots":
         case "coupling":
             return (await import("./commands/query.js")).runQuery(cmd, flags);
@@ -163,6 +172,8 @@ async function dispatch(cmd, flags) {
             return (await import("./commands/drift.js")).runDrift(flags);
         case "telemetry":
             return (await import("./commands/telemetry.js")).runTelemetry(flags);
+        case "owners":
+            return (await import("./commands/owners.js")).runOwners(flags);
         case "check":
             return (await import("./commands/check.js")).runCheck(flags);
         case "laws":

package/dist/modules/compass/budget.js

@@ -0,0 +1,128 @@
+/**
+ * Fit ranked retrieval hits into a token budget via binary search, and render
+ * a compact TreeContext with elision markers.
+ */
+/**
+ * Rough token estimate: ~4 chars/token, sampling every 100th line on large text.
+ *
+ * @param s - Text to estimate.
+ */
+export function estimateTokens(s) {
+    if (s.length < 4000)
+        return Math.ceil(s.length / 4);
+    const lines = s.split("\n");
+    if (lines.length < 200)
+        return Math.ceil(s.length / 4);
+    let sampled = 0;
+    let count = 0;
+    for (let i = 0; i < lines.length; i += 100) {
+        sampled += lines[i].length + 1;
+        count++;
+    }
+    const avg = sampled / Math.max(count, 1);
+    return Math.ceil((avg * lines.length) / 4);
+}
+/**
+ * Render hits as a TreeContext block with `⋮` elision between non-adjacent lines.
+ *
+ * @param hits - Ordered hits to include.
+ */
+export function renderTreeContext(hits) {
+    if (hits.length === 0)
+        return "";
+    const byFile = new Map();
+    for (const h of hits) {
+        const list = byFile.get(h.file) ?? [];
+        list.push(h);
+        byFile.set(h.file, list);
+    }
+    const parts = [];
+    for (const [file, list] of byFile) {
+        parts.push(`# ${file}`);
+        list.sort((a, b) => a.line - b.line);
+        let lastLine = -Infinity;
+        for (const h of list) {
+            if (h.line - lastLine > 3 && lastLine !== -Infinity)
+                parts.push("⋮");
+            const sig = h.signature ?? `${h.kind} ${h.name}`;
+            parts.push(`${h.line}| ${sig}`);
+            if (h.excerpt) {
+                const lines = h.excerpt.split("\n");
+                if (lines.length > 6) {
+                    parts.push(...lines.slice(0, 3).map((l) => `  ${l}`));
+                    parts.push("  ⋮");
+                    parts.push(...lines.slice(-2).map((l) => `  ${l}`));
+                }
+                else {
+                    parts.push(...lines.map((l) => `  ${l}`));
+                }
+            }
+            lastLine = h.line;
+        }
+    }
+    return parts.join("\n");
+}
+/**
+ * Binary-search how many leading hits fit `maxTokens` within 15% tolerance.
+ * Never returns empty when hits is non-empty — truncates the first hit instead.
+ *
+ * @param ranked - Hits in final rank order.
+ * @param maxTokens - Token budget.
+ */
+export function fitToBudget(ranked, maxTokens) {
+    const budget = Math.max(1, maxTokens);
+    if (ranked.length === 0) {
+        return { rendered: "", tokens: 0, budget, hitCount: 0 };
+    }
+    let lower = 1;
+    let upper = ranked.length;
+    let best = renderTreeContext(ranked.slice(0, 1));
+    let bestCount = 1;
+    while (lower <= upper) {
+        const mid = (lower + upper) >> 1;
+        const tree = renderTreeContext(ranked.slice(0, mid));
+        const n = estimateTokens(tree);
+        if (Math.abs(n - budget) / budget < 0.15) {
+            return { rendered: tree, tokens: n, budget, hitCount: mid };
+        }
+        if (n <= budget) {
+            best = tree;
+            bestCount = mid;
+            lower = mid + 1;
+        }
+        else {
+            upper = mid - 1;
+        }
+    }
+    // Single oversized hit: truncate excerpt.
+    if (bestCount === 1 && estimateTokens(best) > budget) {
+        const h = { ...ranked[0], excerpt: truncateExcerpt(ranked[0].excerpt, budget) };
+        const rendered = renderTreeContext([h]);
+        return { rendered, tokens: estimateTokens(rendered), budget, hitCount: 1 };
+    }
+    return {
+        rendered: best,
+        tokens: estimateTokens(best),
+        budget,
+        hitCount: bestCount,
+    };
+}
+function truncateExcerpt(excerpt, budget) {
+    if (!excerpt)
+        return "";
+    const maxChars = Math.max(32, budget * 3);
+    if (excerpt.length <= maxChars)
+        return excerpt;
+    return `${excerpt.slice(0, maxChars)}\n⋮`;
+}
+/**
+ * Default token budget inspired by aider: clamp between 1024 and 4096, ×8 when
+ * there is no focus set.
+ *
+ * @param hasFocus - Whether a non-empty focus file set is in use.
+ * @param maxInput - Optional model input window hint.
+ */
+export function defaultBudget(hasFocus, maxInput = 32_000) {
+    const base = Math.max(1024, Math.min(Math.floor(maxInput / 8), 4096));
+    return hasFocus ? base : base * 8;
+}