@esneiderbravo/speclaw 0.4.0 → 1.0.0

package/README.md

@@ -8,15 +8,17 @@
 &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">
+&nbsp;<img src="https://img.shields.io/badge/node-%E2%89%A522.16-0E8E8E?labelColor=0B0F10&style=flat-square" alt="Node >= 22.16">
+&nbsp;<img src="https://img.shields.io/badge/v1.0-0E8E8E?labelColor=0B0F10&style=flat-square" alt="v1.0">
 
 <br/><br/>
 
 <p align="center">
 <b>AI agents are brilliant and blind</b> — brilliant at writing code, blind to <i>your</i>
-project's rules. <b>speclaw</b> hands them what they're missing: the codebase's
+project's rules. <b>speclaw 1.0</b> hands them what they're missing: the codebase's
 <b>written laws</b> (a constitution built from your real code), a <b>local map</b> to
-navigate it without burning tokens, and a <b>disciplined workflow</b> for every change.
+navigate it without burning tokens, a <b>disciplined workflow</b> for every change,
+and the <b>gates</b> that make those laws hold in the editor, in CI, and in the PR.
 <br/>
 One command. No cloud, no LLM, no API keys — <b>everything runs on your machine.</b>
 </p>
@@ -24,6 +26,7 @@ One command. No cloud, no LLM, no API keys — <b>everything runs on your machin
 <img src="https://img.shields.io/badge/100%25_local-0E8E8E?labelColor=0B0F10&style=flat-square" alt="100% local">
 &nbsp;<img src="https://img.shields.io/badge/no_LLM_·_no_cloud-0E8E8E?labelColor=0B0F10&style=flat-square" alt="no LLM">
 &nbsp;<img src="https://img.shields.io/badge/CLI_+_MCP-0E8E8E?labelColor=0B0F10&style=flat-square" alt="CLI + MCP">
+&nbsp;<img src="https://img.shields.io/badge/8_canonical_tools-0E8E8E?labelColor=0B0F10&style=flat-square" alt="8 tools">
 &nbsp;<img src="https://img.shields.io/badge/any_agent-0E8E8E?labelColor=0B0F10&style=flat-square" alt="any agent">
 
 </div>
@@ -59,16 +62,19 @@ speclaw init
 ```
 
 The `speclaw` command is then available everywhere — run `speclaw index`,
-`speclaw doctor`, `speclaw visualize`, or `speclaw lawbook …` directly.
+`speclaw doctor`, `speclaw verify`, `speclaw owners --write`, or
+`speclaw lawbook …` directly.
 
 `init` will:
 
 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.
+   compile your blocking laws into **agent hooks**, and create a committed
+   **`speclaw.lock`** baseline for rule-file integrity.
 3. **Index your code** with a live progress bar and a summary of what it found.
-4. Register the speclaw **MCP server** in each chosen agent's config.
+4. Register the speclaw **MCP server** in each chosen agent's config
+   (eight canonical tools; use `--minimal` to omit setup/lifecycle tools).
 5. Print a prompt to paste into your agent so it fills the constitution with your
    project's real architecture and conventions.
 
@@ -82,7 +88,8 @@ When something breaks, run `speclaw doctor --json` and paste it into an issue
 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.
+your own review and with **`speclaw.lock`** digests on rule files (see
+[Verify in CI](#-verify-in-ci)).
 
 ```bash
 npm audit signatures
@@ -102,14 +109,15 @@ gh attestation verify <tarball> --owner esneiderbravo
 
 <br/>
 
-## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; The suite — four modules
+## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; The suite — five modules
 
 | 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 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. |
+| **Foundation** | The project's constitution: `LAWS.md` binding granular standards under `docs/standards/`, plus `CLAUDE.md` / `AGENTS.md`. **Enforced** via agent hooks (`speclaw check`), deterministic graph laws (`speclaw verify` / `laws verify`), multidialect compile (`laws compile`), and committed **`speclaw.lock`** digests + injection scan (`laws lock` / `accept` / `scan`). |
+| **Compass** | Local code graph (tree-sitter → `node:sqlite`): hybrid find (FTS5 + vectors + RRF + PageRank), impact, affected-tests, hotspots, coupling, visualize. Schema **10**. No LLM — lives in `.speclaw/` (gitignored). |
+| **Lawbook** | Spec-driven workflow with **adaptive ceremony** (levels 0–3), bugfix changes + `lawbook_investigate`, EARS linting, requirement **coverage**, and sealed **drift** anchors. Loop: `explore → draft → build → sync → archive`. |
+| **Team** | Declare `team.owners` in `lawbook/config.yaml`; `speclaw owners --write` compiles a managed trailing block in `.github/CODEOWNERS` (GitHub: last match wins). Doctor checks the posture. CLI-only — no MCP tool. |
+| **Tools** | Opt-in packs of skills and subagents (currently the dev-agents). |
 
 Compass is inspired by [CodeGraph](https://github.com/colbymchenry/codegraph) and the Lawbook module by [OpenSpec](https://github.com/Fission-AI/openspec) — both MIT. speclaw reimplements the ideas as its own code and gives full credit; see [ATTRIBUTION.md](ATTRIBUTION.md).
 
@@ -123,16 +131,15 @@ tokenizer on this corpus — not a BPE dependency):
 
 | | Tokens |
 | :-- | --: |
-| **speclaw budget (always-on)** | **~12.9k** (8 MCP tools · ceiling **13.0k**) |
+| **speclaw budget (always-on)** | **~13.7k** (8 MCP tools · ceiling **14.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 coverage        # requirement → impl → test coverage (TAP / table)
-speclaw coverage --json # machine-readable coverage report
 speclaw drift           # sealed spec ↔ code drift (default --fail-on semantic)
-speclaw drift --reseal  # photograph current bodies into lawbook/anchors/
+speclaw owners --write  # team.owners → .github/CODEOWNERS
 speclaw init --minimal  # omit setup/lifecycle MCP tools from registration
 ```
 
@@ -159,38 +166,40 @@ non-trivial lands without a spec change. It's a loop of five steps:
 | Step | What happens |
 | :-- | :-- |
 | **explore** | Think an idea through *before* committing to it — should we do this, and how. Writes nothing. |
-| **draft** | Capture the intent as a change under `lawbook/changes/<name>/` — four artifacts plus a `reports/` folder, always (see below). |
+| **draft** | Propose a **ceremony level** (0–3) from graph signals, confirm it, then scaffold only what that level needs under `lawbook/changes/<name>/`. |
 | **build** | Implement the tasks in order, keeping code and spec in agreement, and record test results under `reports/`. |
-| **sync** | Reconcile the delta specs against what was actually built, then promote them into the canonical `lawbook/specs/` — the always-true description of how the system behaves. |
-| **archive** | Reconcile, then validate, promote, and move the change to `lawbook/changes/archive/` — **in the same PR**, never a post-merge chore. Gated: refused while any task is unchecked, `reports/` is empty, or the specs are unsynced. |
+| **sync** | Reconcile the delta specs against what was actually built, then promote them into the canonical `lawbook/specs/`. |
+| **archive** | Reconcile, then validate, promote, and move the change to `lawbook/changes/archive/` — **in the same PR**. Gated on tasks, reports, synced specs, and coverage. |
 
-**Every `draft` writes four artifacts under `lawbook/changes/<name>/` — none optional:**
+**Ceremony levels** (confirmed in `change.json`; missing ⇒ level 3):
 
-| Artifact | What it captures |
-| :-- | :-- |
-| `proposal.md` | The **why** — motivation, what changes, non-goals, and whether migrations are needed. |
-| `specs/<capability>/spec.md` | The **delta specs** — one per affected capability, normative and testable. |
-| `design.md` | The **how** — approach, alternatives weighed, and the trade-offs behind the decision. |
-| `tasks.md` | The **plan** — ordered, checkable steps, including the mandatory ones from `config.yaml`. |
+| Level | When | Artifacts |
+| :-- | :-- | :-- |
+| **0** | One-liner / typo / docs-only | `speclaw quick` → `record.md` + `reports/` |
+| **1** | Small fix with a delta | `record.md` + `tasks.md` + ≥1 delta + `reports/` |
+| **2** | Normal feature | `proposal.md` + tasks + deltas + `reports/` (`design.md` optional) |
+| **3** | Full ceremony | proposal + design + tasks + deltas + `reports/` |
+| **bug** | Regression / RCA | `speclaw lawbook draft --bug` → `bugfix.md` + investigate first |
 
-Plus a **`reports/`** folder — scaffolded at draft, filled at build with one report per discipline (`backend.md`, `frontend.md`, …) recording the real unit/integration/e2e results. Evidence of testing travels with the change, and `lawbook_archive` refuses to archive without it.
+Plus a **`reports/`** folder — scaffolded at draft, filled at build with one report
+per discipline (`backend.md`, `frontend.md`, `api.md`, …). `lawbook_archive`
+refuses to archive without it.
 
 > [!NOTE]
 > **Delta specs are normative and testable.** Requirements use `SHALL`/`MUST`
-> under `### Requirement:` headers, each with one or more `#### Scenario:` blocks
-> whose acceptance criteria hold without production integrations. `lawbook_validate`
-> checks that the code matches what the spec promises before you sync or archive.
+> under `### Requirement:` headers (EARS-friendly), each with `#### Scenario:`
+> blocks. `lawbook_validate` checks structure; `speclaw coverage` tracks
+> `req~…~N` → impl/test via `// Covers:` comments.
 
 **Three ways to drive it — same engine, no external CLI:**
 
-- **In your agent** — the `/lawbook:explore`, `/lawbook:draft`, `/lawbook:build`, `/lawbook:sync`, `/lawbook:archive` commands (installed as skills).
-- **MCP tools** — eight canonical tools: `compass_explore`, `compass_find`, `compass_diff_context`, `compass_index`, `lawbook_change`, `lawbook_investigate`, `speclaw_setup`, `speclaw_check`.
-- **CLI** — `speclaw lawbook init | list | validate | sync | archive`.
+- **In your agent** — `/lawbook:explore`, `/lawbook:draft`, `/lawbook:build`, `/lawbook:sync`, `/lawbook:archive` (and `/lawbook:quick`, investigate).
+- **MCP tools** — eight canonical: `compass_explore`, `compass_find`, `compass_diff_context`, `compass_index`, `lawbook_change`, `lawbook_investigate`, `speclaw_setup`, `speclaw_check`.
+- **CLI** — `speclaw lawbook …`, `speclaw quick`, `speclaw coverage`, `speclaw drift`.
 
-The workspace is committed under `lawbook/`: `specs/` (canonical), `changes/`
-(in-flight), `changes/archive/` (shipped), and `config.yaml` (the mandatory task
-steps every change must include). The standards themselves are amended the same
-way — through a spec change reviewed by a human.
+The workspace is committed under `lawbook/`: `specs/`, `changes/`,
+`changes/archive/`, `anchors/` (drift photographs), and `config.yaml`
+(mandatory tasks, ceremony cuts, `team.owners`, EARS knobs).
 
 <br/>
 
@@ -204,7 +213,7 @@ still use Compass and the lawbook engine by calling the CLI from its shell.
 <p align="center"><b>CLI</b> — the installer &amp; operator, runs anywhere <code>node</code> does</p>
 <p align="center"><img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/terminal-cli.png" width="800" alt="speclaw CLI commands"></p>
 
-<p align="center"><b>MCP</b> — the integrated agent surface, auto-registered by <code>init</code></p>
+<p align="center"><b>MCP</b> — eight canonical tools, auto-registered by <code>init</code></p>
 <p align="center"><img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/terminal-mcp.png" width="800" alt="speclaw MCP tools"></p>
 
 <br/>
@@ -216,26 +225,20 @@ still use Compass and the lawbook engine by calling the CLI from its shell.
 </p>
 
 **Committed vs. local.** Your **personalized source** is committed — `LAWS.md`,
-`CLAUDE.md`, `AGENTS.md`, `docs/standards/*`, `docs/compass.md`, and the
-`lawbook/` workspace. speclaw's **regenerable workflow content is local, not
-committed**: only `ai-specs/` (skills, commands, rules, agent packs, and its
-`.speclaw.json` manifest) is gitignored, because `init`/`update` reconstruct it
-from the package — like a dependency. So **after cloning a speclaw project, run
-`speclaw init` (or `speclaw update`)** to regenerate `ai-specs/` locally, which
-the agent IDE symlinks point into. If a project committed `ai-specs/` before
-this behavior existed, `init`/`update` print the exact `git rm -r --cached
-ai-specs` command to stop tracking it (they never touch your git index
-themselves). The agent directories (`.claude/`, `.cursor/`, …) are **left to
-you** — commit your own skills and commands there if you want to.
+`CLAUDE.md`, `AGENTS.md`, `docs/standards/*`, `docs/compass.md`, the `lawbook/`
+workspace, and **`speclaw.lock`** (rule digests at the repo root). speclaw's
+**regenerable workflow content is local, not committed**: only `ai-specs/`
+(skills, commands, rules, agent packs, and its `.speclaw.json` manifest) is
+gitignored, because `init`/`update` reconstruct it from the package. So **after
+cloning a speclaw project, run `speclaw init` (or `speclaw update`)** to
+regenerate `ai-specs/` locally. Optional **`team.owners`** in
+`lawbook/config.yaml` compiles into a managed block at the end of
+`.github/CODEOWNERS` via `speclaw owners --write`.
 
 **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. 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`.
+hooks into that agent's settings **by identity** — it never touches hooks you
+added yourself. The compiled law manifest lives in `.speclaw/laws-manifest.json`
+(gitignored), and a context-coverage log feeds `speclaw doctor`.
 
 <br/>
 
@@ -261,27 +264,44 @@ So `speclaw init` compiles your blocking laws into agent hooks: a law marked
 and source. `speclaw check --dry-run --path <file>` previews what would block, and
 `speclaw doctor` reports how many of your laws actually reached the agent's
 context. Agents without hooks (Cursor, Codex) enforce the same laws in CI via
-`speclaw verify`.
+`speclaw verify`. Digests in `speclaw.lock` catch silent edits to the rule files
+themselves (the *Rules File Backdoor*).
 
 <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.**
+index, and — when `speclaw.lock` is present — compares digests of managed rule
+files and scans them (plus skill packs) for known injection patterns. It is
+deterministic: **no model, no API key, no network.**
 
 ```bash
 speclaw verify --ci --sarif speclaw.sarif --json speclaw.json
 ```
 
+Create or refresh the committed lockfile (repo root, never under `.speclaw/`):
+
+```bash
+speclaw laws lock
+speclaw laws scan
+speclaw laws accept AGENTS.md   # interactive TTY only — never via MCP
+```
+
 | Exit | Meaning |
 | :-- | :-- |
 | **0** | No findings at or above `--fail-on` (default `error`) |
-| **1** | At least one finding at or above `--fail-on` |
+| **1** | At least one finding at or above `--fail-on` (including strict integrity / scan errors) |
 | **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 |
 
+**Limits (honest):** digests catch any edit; the scanner catches known payload
+shapes after Unicode normalization — not LLM-grade semantic injection. Digest
+acceptance is a human gate (`laws accept` on a TTY). There is no Sigstore signing
+of the lock in this release. Regenerable IDE mirrors (e.g. `.cursor/rules` →
+`ai-specs/`) are not pinned as strict committed files.
+
 On GitHub:
 
 ```yaml
@@ -290,7 +310,8 @@ On GitHub:
 
 `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.
+protection yourself; speclaw does not. Pair with `speclaw owners` + *Require
+review from Code Owners* when you declare `team.owners`.
 
 <br/>
 
@@ -306,17 +327,12 @@ speclaw update
 `update` upgrades the global package **and** brings the current project up to date
 without a re-init, splitting files by who owns them:
 
-- **Managed files** (speclaw's workflow machinery — the skills, commands, rules,
-  and agent packs under `ai-specs/`) are **refreshed** to the new version, so
-  improvements actually reach your project. They live locally (gitignored, see
-  *What lands in your project*) and are reconstructed from the package. If you
-  edited one locally, `update` reports the overwrite; pass `--backup` to keep a
-  `<file>.bak` (itself gitignored) before it is refreshed.
-- **Personalized files** (your constitution and standards — `CLAUDE.md`,
-  `AGENTS.md`, `LAWS.md`, `docs/standards/*`, `docs/compass.md`,
-  `lawbook/config.yaml`) are **never auto-edited**. When a release changes their
-  speclaw-authored content, `update` prints a prompt for **the agent you're
-  using** to apply the change while preserving your project's specifics.
+- **Managed files** (skills/commands/rules under `ai-specs/`) are **refreshed**.
+  Pass `--backup` to keep a `<file>.bak` before overwrite.
+- **Personalized files** (`CLAUDE.md`, `AGENTS.md`, `LAWS.md`, `docs/standards/*`,
+  `docs/compass.md`, `lawbook/config.yaml`) are **never auto-edited** — `update`
+  prints a prompt for the agent you're using.
+- **`speclaw.lock`** and the CODEOWNERS owners block are refreshed when configured.
 
 - `speclaw update --check` — report whether an update exists, change nothing.
 - `NO_UPDATE_NOTIFIER=1` — silence the reminder.
@@ -325,7 +341,7 @@ without a re-init, splitting files by who owns them:
 
 ## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; Requirements
 
-- **Node.js ≥ 22** — uses the built-in `node:sqlite`.
+- **Node.js ≥ 22.16** — uses built-in `node:sqlite` (FTS5 for hybrid find).
 - **No native builds, no services, no API keys, no LLM download.** Tree-sitter
   parsers ship as WASM; the vector store is local.
 
@@ -338,6 +354,6 @@ without a re-init, splitting files by who owns them:
 [CodeGraph](https://github.com/colbymchenry/codegraph) &nbsp;·&nbsp;
 see [ATTRIBUTION.md](ATTRIBUTION.md)
 
-<i>speclaw · where specs become law</i>
+<i>speclaw 1.0 · where specs become law</i>
 
 </div>

package/dist/cli/commands/index-build.js

@@ -2,15 +2,24 @@ import { buildIndex } from "../../modules/compass/indexer.js";
 import { startWatch } from "../../modules/compass/watcher.js";
 import { ui, renderProgress, clearProgress } from "../lib/ui.js";
 /** (Re)build the Compass code graph for the cwd, showing progress and final stats. */
-export async function runIndex(_flags) {
+export async function runIndex(flags) {
     const cwd = process.cwd();
     ui.step("Indexing with Compass");
     const start = Date.now();
-    const stats = await buildIndex(cwd, (e) => renderProgress(e.done, e.total, e.file));
+    const stats = await buildIndex(cwd, {
+        force: Boolean(flags.force),
+        prune: Boolean(flags.prune),
+        maxCacheMB: flags["max-cache-mb"] ? Number(flags["max-cache-mb"]) : undefined,
+        retentionDays: flags.retention ? Number(flags.retention) : undefined,
+        onProgress: (e) => renderProgress(e.done, e.total, e.file),
+    });
     clearProgress();
     const secs = ((Date.now() - start) / 1000).toFixed(1);
+    const root = stats.rootUnchanged ? " · root unchanged" : "";
     ui.ok(`${stats.files} files · ${stats.nodes} nodes · ${stats.edges} edges · ` +
-        `${stats.embeddings} embeddings · ${stats.unchanged} unchanged  (${secs}s)`);
+        `${stats.computed} computed · ${stats.fromCache} fromCache · ` +
+        `${stats.unchanged} unchanged · ${stats.skippedByStat} skippedByStat` +
+        `${root}  (${secs}s)`);
 }
 /** Build the initial index, then watch for file changes to keep it fresh. */
 export async function runWatch(_flags) {

package/dist/cli/commands/lawbook.js

@@ -72,6 +72,7 @@ export async function runSpec(flags) {
                 return;
             }
             case "validate": {
+                // Covers: req~ears-cli-surface~1
                 const r = specValidate(cwd, req(change, "lawbook validate <change>"));
                 if (r.valid)
                     ui.ok(`${r.change} is valid (${r.deltaSpecs.length} delta spec(s))`);

package/dist/cli/commands/laws.js

@@ -1,21 +1,107 @@
 import { list } from "../lib/args.js";
 import { ui, c } from "../lib/ui.js";
+import * as clack from "@clack/prompts";
 import { verifyLaws } from "../../modules/foundation/verify.js";
+import { compileLaws } from "../../modules/foundation/compile-laws.js";
+import { importRulesFrom } from "../../modules/foundation/import-rules.js";
+import { acceptLockPath, isInteractiveTty, refreshLockfile, verifyIntegrity, } from "../../modules/foundation/integrity.js";
+import { digestText, prepareIntegrityText, readLockfile } from "../../modules/foundation/lock.js";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+const LAWS_SUBS = "verify|compile|import|lock|accept|scan";
 /**
- * `speclaw laws <subcommand>` — the CLI twin of the batch law tools. Today it
- * exposes `verify`, the twin of the `law_verify` MCP tool: it runs the project's
- * deterministic `deps`/`graph` laws against the Compass index and prints the
- * four-state result. Both transports delegate to the same {@link verifyLaws}
- * core, so the CLI and the tool never diverge.
- *
- * - `laws verify [--engine deps,graph] [--path a,b] [--law id1,id2] [--json]`
+ * `speclaw laws <subcommand>` — verify (batch), compile (dialects), import (draft),
+ * lock / accept / scan (rule-file integrity).
  *
  * @param flags - Parsed CLI flags; `flags._[0]` is the subcommand.
  */
+// Covers: req~laws-integrity-cli~1, req~laws-accept-human~1
 export async function runLaws(flags) {
     const sub = flags._[0];
+    if (sub === "compile") {
+        const agents = list(flags.agent);
+        const report = compileLaws({
+            projectPath: process.cwd(),
+            agents: agents.length ? agents : undefined,
+        });
+        if (flags.json) {
+            console.log(JSON.stringify(report, null, 2));
+            return;
+        }
+        ui.heading("speclaw laws compile");
+        ui.ok(`${report.lawCount} active · ${report.draftCount} draft · ` +
+            `${report.written.length} written · ${report.unchanged.length} unchanged` +
+            (report.failed.length ? ` · ${report.failed.length} failed` : ""));
+        for (const f of report.failed)
+            ui.warn(`${f.path}: ${f.error}`);
+        if (report.failed.length)
+            process.exit(1);
+        return;
+    }
+    if (sub === "import") {
+        const from = typeof flags.from === "string" ? flags.from : "";
+        if (!from) {
+            ui.err(`Usage: ${ui.code("speclaw laws import --from rulesync")}`);
+            process.exit(1);
+        }
+        try {
+            const report = importRulesFrom(process.cwd(), from);
+            if (flags.json) {
+                console.log(JSON.stringify(report, null, 2));
+                return;
+            }
+            ui.heading("speclaw laws import");
+            ui.ok(`${report.imported.length} imported · ${report.skipped.length} skipped`);
+            for (const id of report.imported)
+                ui.plain(`  + ${c.cream(id)}`);
+        }
+        catch (err) {
+            ui.err(err.message);
+            process.exit(1);
+        }
+        return;
+    }
+    if (sub === "lock") {
+        const lock = refreshLockfile(process.cwd());
+        if (flags.json) {
+            console.log(JSON.stringify(lock, null, 2));
+            return;
+        }
+        ui.heading("speclaw laws lock");
+        ui.ok(`Wrote speclaw.lock — ${Object.keys(lock.files).length} file(s), ` +
+            `${Object.keys(lock.symlinks).length} symlink(s), root ${lock.root.slice(0, 19)}…`);
+        return;
+    }
+    if (sub === "scan") {
+        const report = verifyIntegrity({ projectPath: process.cwd(), checks: "scan" });
+        if (flags.json) {
+            console.log(JSON.stringify(report, null, 2));
+            return;
+        }
+        ui.heading("speclaw laws scan");
+        if (report.findings.length === 0) {
+            ui.ok("No injection findings.");
+            return;
+        }
+        for (const f of report.findings) {
+            const line = `${f.path}:${f.line}`;
+            const msg = `${c.cream(f.detector)} — ${line} ${f.message}`;
+            if (f.severity === "error")
+                ui.err(msg);
+            else
+                ui.warn(msg);
+        }
+        if (report.findings.some((f) => f.severity === "error"))
+            process.exit(1);
+        return;
+    }
+    if (sub === "accept") {
+        await runAccept(flags);
+        return;
+    }
     if (sub !== "verify") {
-        ui.err(`Unknown laws subcommand: ${sub ?? "(none)"} — try ${ui.code("speclaw laws verify")}.`);
+        ui.err(`Unknown laws subcommand: ${sub ?? "(none)"} — try ${ui.code(`speclaw laws ${LAWS_SUBS}`)}.`);
         process.exit(1);
     }
     const engines = list(flags.engine).filter((e) => e === "deps" || e === "graph");
@@ -46,3 +132,58 @@ export async function runLaws(flags) {
     if (report.findings.length === 0 && summary.evaluated > 0)
         ui.ok("No violations.");
 }
+async function runAccept(flags) {
+    const cwd = process.cwd();
+    if (!isInteractiveTty()) {
+        ui.err("`speclaw laws accept` requires an interactive TTY — digest acceptance is human-only.");
+        process.exit(1);
+    }
+    const rel = typeof flags._[1] === "string" ? flags._[1] : "";
+    if (!rel) {
+        ui.err(`Usage: ${ui.code("speclaw laws accept <path>")}`);
+        process.exit(1);
+    }
+    const lock = readLockfile(cwd);
+    if (!lock) {
+        ui.err("No speclaw.lock — run `speclaw laws lock` first.");
+        process.exit(1);
+    }
+    const abs = path.join(cwd, rel);
+    if (!fs.existsSync(abs)) {
+        ui.err(`File not found: ${rel}`);
+        process.exit(1);
+    }
+    const raw = prepareIntegrityText(rel, fs.readFileSync(abs, "utf8"));
+    const actual = digestText(raw);
+    const expected = lock.files[rel]?.digest;
+    ui.heading("speclaw laws accept");
+    ui.info(`${rel}`);
+    if (expected)
+        ui.plain(`  expected ${expected}`);
+    ui.plain(`  actual   ${actual}`);
+    if (expected === actual) {
+        ui.ok("Digest already matches the lock — nothing to accept.");
+        return;
+    }
+    const noteFlag = typeof flags.note === "string" ? flags.note : undefined;
+    const confirmed = await clack.confirm({
+        message: `Update speclaw.lock digest for ${rel}?`,
+        initialValue: false,
+    });
+    if (clack.isCancel(confirmed) || !confirmed) {
+        ui.warn("Accept cancelled — lockfile unchanged.");
+        process.exit(1);
+    }
+    let note = noteFlag;
+    if (!note) {
+        const n = await clack.text({
+            message: "Optional note for the accept audit trail",
+            placeholder: "why this digest is trusted",
+        });
+        if (!clack.isCancel(n) && n.trim())
+            note = n.trim();
+    }
+    const by = os.userInfo().username || process.env.USER || "unknown";
+    acceptLockPath(cwd, rel, { by, note });
+    ui.ok(`Accepted ${rel} — lock updated (by ${by}).`);
+}

package/dist/cli/commands/owners.js

@@ -0,0 +1,44 @@
+import { ui } from "../lib/ui.js";
+import { checkOwners, writeOwners } from "../../modules/team/owners.js";
+/**
+ * Spec-ownership CLI: compile `team.owners` into `.github/CODEOWNERS`.
+ * `--write` mutates; default / `--check` reports drift without writing.
+ */
+// Covers: req~owners-cli~1
+export async function runOwners(flags) {
+    const cwd = process.cwd();
+    const doWrite = Boolean(flags.write);
+    if (doWrite) {
+        try {
+            const result = writeOwners(cwd);
+            if (!result.written) {
+                ui.info(result.reason ?? "nothing to write");
+                return;
+            }
+            ui.ok(`wrote speclaw owners block (${result.capabilities} key(s)) → ${result.path.replace(cwd + "/", "")}`);
+            return;
+        }
+        catch (err) {
+            ui.err(err.message);
+            process.exit(1);
+        }
+    }
+    const check = checkOwners(cwd);
+    if (check.ok) {
+        ui.ok(check.detail);
+        return;
+    }
+    ui.err(check.detail);
+    if (check.expected !== undefined && flags.diff) {
+        ui.plain();
+        ui.step("expected");
+        console.log(check.expected);
+        ui.plain();
+        ui.step("actual");
+        console.log(check.actual ?? "(missing)");
+    }
+    else {
+        ui.info(`Run ${ui.code("speclaw owners --write")} to refresh, or ${ui.code("--diff")} to compare.`);
+    }
+    process.exit(1);
+}

package/dist/cli/commands/query.js

@@ -1,4 +1,5 @@
-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";
@@ -16,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": {
@@ -34,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": {