@esneiderbravo/speclaw 2.0.8 → 2.0.10

package/README.md

@@ -116,7 +116,7 @@ gh attestation verify <tarball> --owner esneiderbravo
 | Module | What it does |
 | :-- | :-- |
 | **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**. Refreshed silently at every Claude Code session start once built. No LLM — lives in `.speclaw/` (gitignored). |
+| **Compass** | Local code graph (tree-sitter → `node:sqlite`): hybrid find (FTS5 + vectors + RRF + PageRank), impact, affected-tests, hotspots, coupling, visualize. Schema **11**. Refreshed silently at every Claude Code session start once built. No LLM — lives in `.speclaw/` (gitignored). |
 | **Lawbook** | Spec-driven workflow with **adaptive ceremony** (levels 0–3), EARS linting, requirement **coverage**, sealed **drift** anchors, bugfix + `lawbook_investigate`. Artifacts under `lawbook/`. |
 | **Cortex** | **One brain. Many agents.** The multi-agent loop: durable `harness.json`, MCP tool `cortex` (`status`/`start`/`advance`/`rework`/`brief`), CLI `speclaw cortex`, skill `/lawbook/cortex`. Dispatches explorer → planner → implementer → reviewer → tester → archiver. |
 | **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. |
@@ -303,8 +303,27 @@ Create or refresh the committed lockfile (repo root, never under `.speclaw/`):
 speclaw laws lock
 speclaw laws scan
 speclaw laws accept AGENTS.md   # interactive TTY only — never via MCP
+speclaw laws lock --force       # list drifted files, confirm, re-baseline — interactive TTY only
 ```
 
+A lock refresh (`init`, `update`, `laws compile`, `laws lock`) never launders an
+edit: a strict file (`CLAUDE.md`, `AGENTS.md`, compiled rules) that drifted from
+the lock outside speclaw **keeps its locked digest**, and the command warns
+`run speclaw laws accept <path>`, so `verify` keeps failing until a human
+accepts it. Clean strict files, new strict files, and advisory files
+(`LAWS.md`, `docs/standards/*`) are refreshed freely, and stale `accepted[]`
+entries are pruned — an `accepted[]` entry lasts until the next refresh rewrites
+that file, after which the audit trail lives in git history. `laws lock --force`
+lists each drifted file with its locked and on-disk digests, asks for
+confirmation (default No), then re-baselines them and records an `accepted[]`
+entry for each (`--note` adds the reason); without a TTY, when declined, or when
+any file or digest changed while the prompt was open, it exits 1 and leaves the
+lock untouched. A `speclaw.lock` that exists but cannot be read (merge-conflict
+markers, a newer `lockfileVersion`, or valid JSON with the wrong structure) is
+never rebuilt: every refresh leaves it byte-identical and reports the error, and
+the CLI (including `laws accept`) exits non-zero until it is repaired (or deleted
+and re-created with `laws lock`).
+
 | Exit | Meaning |
 | :-- | :-- |
 | **0** | No findings at or above `--fail-on` (default `error`) |
@@ -335,16 +354,20 @@ review from Code Owners* when you declare `team.owners`.
 ## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; Staying up to date
 
 speclaw checks for new releases in the background (at most once a day) and nudges
-you when one lands. To bring a project up to date (migrations only — never runs
-`npm install -g`):
+you when one lands. To bring a project up to date (never runs `npm install -g`):
 
 ```bash
 speclaw update
 ```
 
-If a newer binary is on npm, `update` prints an advisory (`current → latest`) and
-how to upgrade the binary separately (`npm i -g @esneiderbravo/speclaw@latest`, or
-prefer `npx @esneiderbravo/speclaw@latest update`), then still migrates the project.
+`update` upgrades itself: when npm reports a newer release during the run, it
+re-executes as `npx -y @esneiderbravo/speclaw@<latest> update` with the same
+flags (also in CI), so the latest release applies its own migrations, and exits
+with that run's code. It migrates with the installed binary instead when you opt
+out (`--no-self-update` or `SPECLAW_NO_SELF_UPDATE=1`), when the registry is
+unreachable (a cached version only), or when `npx` cannot be started; it then
+prints how to upgrade the binary yourself (`npm i -g @esneiderbravo/speclaw@latest`).
+`init` only advises — prefer `npx @esneiderbravo/speclaw@latest init`.
 
 `update` brings the current project up to date without a re-init, splitting files
 by who owns them:
@@ -354,11 +377,17 @@ by who owns them:
 - **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 version status only; do not migrate.
+- **`speclaw.lock`** and the CODEOWNERS owners block are refreshed when configured
+  (a drifted strict file keeps its locked digest — see `laws accept` above).
+- **Agent MCP entry** — `init`, `agent add`, and `update` pin it to the installed
+  version (`npx -y @esneiderbravo/speclaw@<version> mcp`); `update` re-pins the
+  stock entry and keeps a custom one (e.g. a local `node` path).
+
+- `speclaw update --check` — report version status only; do not re-run or migrate.
+- `speclaw update --no-self-update` — migrate with the installed binary.
 - `speclaw update --migrate-only` — silent no-op alias of the default (compat).
 - `NO_UPDATE_NOTIFIER=1` — silence the reminder.
+- `speclaw <command> --help` (or `-h`) — that command's usage; runs nothing.
 
 <br/>
 

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

@@ -1,26 +1,13 @@
 import { buildIndex } from "../../modules/compass/indexer.js";
 import { startWatch } from "../../modules/compass/watcher.js";
 import { recordCompassCall } from "../../shared/compass-calls.js";
+import { helpFor } from "../lib/help.js";
 import { ui, renderProgress, clearProgress } from "../lib/ui.js";
-/** Usage text for `speclaw index --help`. */
-export const INDEX_HELP = `Usage: speclaw index [options]
-
-(Re)build the local Compass code graph for the current directory. Runs are
-incremental: unchanged files are skipped, and an unchanged project skips the
-global post-processing.
-
-Options
-  --force              Re-extract every file
-  --prune              Also evict embedding-cache rows unused for --retention days
-  --retention <days>   Retention window for --prune (default 30)
-  --max-cache-mb <mb>  Embedding-cache size cap (default 256)
-  --json               Print the index statistics as JSON
-`;
 /** (Re)build the Compass code graph for the cwd, showing progress and final stats. */
 export async function runIndex(flags) {
     const cwd = process.cwd();
     if (flags.help || flags.h) {
-        process.stdout.write(INDEX_HELP);
+        process.stdout.write(helpFor("index") ?? "");
         return;
     }
     recordCompassCall(cwd, "compass_index");

package/dist/cli/commands/init.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import * as clack from "@clack/prompts";
-import { scaffold } from "../../modules/foundation/scaffold.js";
+import { lockPreservedWarning, scaffold } from "../../modules/foundation/scaffold.js";
 import { specInit } from "../../modules/lawbook/engine.js";
 import { buildIndex } from "../../modules/compass/indexer.js";
 import { AGENTS, agentById } from "../../shared/agents.js";
@@ -45,8 +45,9 @@ export async function runInit(flags) {
     const upd = await checkForUpdates();
     if (upd.updateAvailable && upd.latest) {
         ui.warn(`You're on ${c.muted(upd.current)} — latest is ${c.bold(c.cyan(upd.latest))}.`);
-        ui.info(`Recommended: refresh the binary with ${ui.code("npx @esneiderbravo/speclaw@latest init")} ` +
-            `(or ${ui.code("npm i -g @esneiderbravo/speclaw@latest")}), then run ${ui.code("speclaw init")} again.`);
+        ui.info(`Recommended: run ${ui.code("npx @esneiderbravo/speclaw@latest init")} instead ` +
+            `(or ${ui.code("npm i -g @esneiderbravo/speclaw@latest")}, then ${ui.code("speclaw init")} again). ` +
+            `Later, ${ui.code("speclaw update")} upgrades itself through npx.`);
         ui.plain();
     }
     if (interactive) {
@@ -103,6 +104,13 @@ export async function runInit(flags) {
         ui.ok(`${PACK_LABELS[p] ?? p + " pack"}`);
     specInit(cwd);
     ui.ok(`Lawbook workspace ${c.muted("— lawbook/")}`);
+    for (const rel of report.lockPreserved)
+        ui.warn(lockPreservedWarning(rel));
+    if (report.lockError) {
+        // An existing lock that cannot be read is left untouched, never rebuilt.
+        ui.err(`${report.lockError} — speclaw.lock was left unchanged; repair it and re-run.`);
+        process.exitCode = 1;
+    }
     if (reinit && report.skipped.length) {
         ui.info(`${report.written.length} added · ${c.cream(String(report.skipped.length))} preserved untouched`);
     }

package/dist/cli/commands/lawbook.js

@@ -156,6 +156,8 @@ export async function runSpec(flags) {
                     else
                         ui.info(msg);
                 }
+                if (r.harnessCompleted)
+                    ui.ok("Cortex harness completed (stage done)");
                 return;
             }
             case "harness": {

package/dist/cli/commands/laws.js

@@ -5,7 +5,7 @@ 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 { digestText, driftedStrictPaths, LockChangedError, lockPreservedWarning, onDiskDigest, prepareIntegrityText, readLockfile, } from "../../modules/foundation/lock.js";
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
@@ -27,6 +27,8 @@ export async function runLaws(flags) {
         });
         if (flags.json) {
             console.log(JSON.stringify(report, null, 2));
+            if (report.failed.length || report.lockError)
+                process.exit(1);
             return;
         }
         ui.heading("speclaw laws compile");
@@ -35,7 +37,11 @@ export async function runLaws(flags) {
             (report.failed.length ? ` · ${report.failed.length} failed` : ""));
         for (const f of report.failed)
             ui.warn(`${f.path}: ${f.error}`);
-        if (report.failed.length)
+        for (const rel of report.lockPreserved)
+            ui.warn(lockPreservedWarning(rel));
+        if (report.lockError)
+            ui.err(lockUnreadableMessage(report.lockError));
+        if (report.failed.length || report.lockError)
             process.exit(1);
         return;
     }
@@ -63,14 +69,7 @@ export async function runLaws(flags) {
         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)}…`);
+        await runLock(flags);
         return;
     }
     if (sub === "scan") {
@@ -132,9 +131,124 @@ export async function runLaws(flags) {
     if (report.findings.length === 0 && summary.evaluated > 0)
         ui.ok("No violations.");
 }
+/**
+ * Injectable TTY check shared by `laws accept` and `laws lock --force`.
+ * Test-only seam: product code must never reassign it.
+ */
+export const lawsTty = { isInteractive: isInteractiveTty };
+/**
+ * Injectable yes/no prompt shared by `laws accept` and `laws lock --force`.
+ * Defaults to No; a cancelled prompt counts as No. Test-only seam: product
+ * code must never reassign it.
+ */
+export const lawsConfirm = {
+    confirm: async (message) => {
+        const answer = await clack.confirm({ message, initialValue: false });
+        return !clack.isCancel(answer) && answer === true;
+    },
+};
+/** The error shown when `speclaw.lock` exists but cannot be read. */
+function lockUnreadableMessage(detail) {
+    return (`${detail} — speclaw.lock was left unchanged. Repair it (resolve merge markers, ` +
+        "or upgrade speclaw for a newer lockfileVersion); to start over, delete it and " +
+        "run `speclaw laws lock`.");
+}
+/** The `by` recorded in `accepted[]` entries for a human acceptance. */
+function acceptedBy() {
+    return os.userInfo().username || process.env.USER || "unknown";
+}
+/**
+ * `speclaw laws lock [--force] [--note <text>]`: create or refresh
+ * `speclaw.lock`. A drifted strict file keeps its locked digest and is warned
+ * about. `--force` re-baselines drifted files and records an `accepted[]` entry
+ * for each; it requires an interactive TTY (without one it exits 1 before
+ * touching the lock) and an explicit confirmation after listing each drifted
+ * path with its locked and on-disk digests (No or cancel exits 1, lock
+ * unchanged). If the drifted set, a locked digest, or an on-disk digest
+ * changed while the prompt was open, nothing is written and it exits 1. An
+ * existing lock that cannot be read is never overwritten: the
+ * command exits 1.
+ *
+ * @param flags - Parsed CLI flags (`--force`, `--note`, `--json`).
+ */
+// Covers: req~laws-accept-human~1, req~laws-integrity-cli~1
+export async function runLock(flags) {
+    const cwd = process.cwd();
+    const force = Boolean(flags.force);
+    if (force && !lawsTty.isInteractive()) {
+        ui.err("`speclaw laws lock --force` requires an interactive TTY — re-baselining is human-only.");
+        process.exit(1);
+    }
+    let prev;
+    let drifted;
+    try {
+        prev = readLockfile(cwd);
+        drifted = driftedStrictPaths(cwd, prev);
+    }
+    catch (err) {
+        ui.err(lockUnreadableMessage(err.message));
+        process.exitCode = 1;
+        return;
+    }
+    let rebaseline;
+    if (force && drifted.length) {
+        ui.heading("speclaw laws lock --force");
+        const confirmed = [];
+        for (const rel of drifted) {
+            const locked = prev.files[rel].digest;
+            const actual = onDiskDigest(cwd, rel) ?? "(missing)";
+            confirmed.push({ path: rel, locked, actual });
+            ui.info(rel);
+            ui.plain(`  expected ${locked}`);
+            ui.plain(`  actual   ${actual}`);
+        }
+        const n = drifted.length;
+        const approved = await lawsConfirm.confirm(`Re-baseline ${n} drifted strict file${n === 1 ? "" : "s"} in speclaw.lock?`);
+        if (!approved) {
+            ui.warn("Re-baseline cancelled — lockfile unchanged.");
+            process.exitCode = 1;
+            return;
+        }
+        const note = typeof flags.note === "string" && flags.note.trim() ? flags.note.trim() : undefined;
+        rebaseline = { by: acceptedBy(), note, confirmed };
+    }
+    let result;
+    try {
+        // With `confirmed`, the refresh re-checks the drift and digests the human
+        // approved against the snapshot it writes, and throws on any difference.
+        result = refreshLockfile(cwd, { drifted, rebaseline });
+    }
+    catch (err) {
+        if (err instanceof LockChangedError) {
+            ui.err(`${err.message} — speclaw.lock was not written. Re-run ` +
+                "`speclaw laws lock --force` to review the current digests.");
+        }
+        else {
+            ui.err(lockUnreadableMessage(err.message));
+        }
+        process.exitCode = 1;
+        return;
+    }
+    const { lock } = result;
+    if (flags.json) {
+        console.log(JSON.stringify(lock, null, 2));
+        for (const rel of result.preserved)
+            process.stderr.write(lockPreservedWarning(rel) + "\n");
+        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)}…`);
+    for (const rel of result.preserved)
+        ui.warn(lockPreservedWarning(rel));
+    for (const rel of result.rebaselined)
+        ui.warn(`${rel} re-baselined by --force (recorded in accepted[]).`);
+    if (result.pruned)
+        ui.info(`Pruned ${result.pruned} stale accepted entr${result.pruned === 1 ? "y" : "ies"}.`);
+}
 async function runAccept(flags) {
     const cwd = process.cwd();
-    if (!isInteractiveTty()) {
+    if (!lawsTty.isInteractive()) {
         ui.err("`speclaw laws accept` requires an interactive TTY — digest acceptance is human-only.");
         process.exit(1);
     }
@@ -143,7 +257,15 @@ async function runAccept(flags) {
         ui.err(`Usage: ${ui.code("speclaw laws accept <path>")}`);
         process.exit(1);
     }
-    const lock = readLockfile(cwd);
+    let lock;
+    try {
+        lock = readLockfile(cwd);
+    }
+    catch (err) {
+        ui.err(lockUnreadableMessage(err.message));
+        process.exitCode = 1;
+        return;
+    }
     if (!lock) {
         ui.err("No speclaw.lock — run `speclaw laws lock` first.");
         process.exit(1);
@@ -166,11 +288,8 @@ async function runAccept(flags) {
         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) {
+    const confirmed = await lawsConfirm.confirm(`Update speclaw.lock digest for ${rel}?`);
+    if (!confirmed) {
         ui.warn("Accept cancelled — lockfile unchanged.");
         process.exit(1);
     }
@@ -183,7 +302,18 @@ async function runAccept(flags) {
         if (!clack.isCancel(n) && n.trim())
             note = n.trim();
     }
-    const by = os.userInfo().username || process.env.USER || "unknown";
-    acceptLockPath(cwd, rel, { by, note });
+    const by = acceptedBy();
+    try {
+        acceptLockPath(cwd, rel, { by, note });
+    }
+    catch (err) {
+        // The lock is re-read here; it may have become unreadable during the prompt.
+        // Only lock read errors get the repair advice; others (a scan-only path)
+        // are reported as-is.
+        const detail = err.message;
+        ui.err(detail.startsWith("speclaw.lock:") ? lockUnreadableMessage(detail) : detail);
+        process.exitCode = 1;
+        return;
+    }
     ui.ok(`Accepted ${rel} — lock updated (by ${by}).`);
 }

package/dist/cli/commands/query.js

@@ -47,8 +47,11 @@ export async function runQuery(cmd, flags) {
                 console.log(s.source);
                 ui.heading("Callees");
                 r.callees?.forEach((c) => ui.info(`${c.name}${c.file ? ` (${c.file}:${c.line})` : ""}`));
+                if (r.unresolvedCallees && r.unresolvedCallees.count > 0) {
+                    ui.info(`+ ${r.unresolvedCallees.count} unresolved call(s): ${r.unresolvedCallees.sample.join(", ")}`);
+                }
                 ui.heading("Callers");
-                r.callers?.forEach((c) => ui.info(`${c.name} (${c.file}:${c.line})`));
+                r.callers?.forEach((c) => ui.info(`${c.kind === "file" ? "(file) " : ""}${c.name} (${c.file}:${c.line})`));
                 return;
             }
             case "search":
@@ -147,7 +150,14 @@ export async function runQuery(cmd, flags) {
                 ui.info(result.reason);
                 result.tests.forEach((t) => ui.info(t.file));
                 ui.heading("Command");
-                console.log(result.command);
+                // Covers: req~affected-test-selection~1
+                if (result.command === null) {
+                    console.log(`no command: ${result.commandReason}`);
+                }
+                else {
+                    console.log(result.command);
+                    ui.info(result.commandReason);
+                }
                 result.warnings.forEach((w) => ui.warn(w));
                 return;
             }

package/dist/cli/commands/update.js

@@ -2,8 +2,9 @@ import fs from "node:fs";
 import path from "node:path";
 import { ui, c } from "../lib/ui.js";
 import { checkForUpdates, isNewer } from "../lib/update-check.js";
+import { isSafeVersion, safeForwardArgs, selfUpdate } from "../lib/self-update.js";
 import { pkgName, pkgVersion } from "../../shared/version.js";
-import { scaffold } from "../../modules/foundation/scaffold.js";
+import { lockPreservedWarning, scaffold } from "../../modules/foundation/scaffold.js";
 import { PERSONALIZED } from "../../modules/foundation/ownership.js";
 import { detectConfiguredAgents } from "../../shared/agents.js";
 import { readManifest } from "../../shared/manifest.js";
@@ -11,15 +12,16 @@ import { loadPacks } from "../../modules/tools/packs.js";
 import { detectProjectName } from "./init.js";
 import { reportTrackedLocalContent } from "../lib/untrack.js";
 /**
- * How to upgrade the installed binary without this command spawning `npm install -g`.
+ * How to upgrade the installed binary when `update` migrates with the running
+ * one (opted out, offline, or `npx` unavailable). Never spawns `npm install -g`.
  *
  * @param name - Package name on npm (usually `pkgName()`).
  * @returns One-line advisory for the terminal.
  */
 export function binaryUpgradeHint(name) {
-    return (`Upgrade the binary separately with ${ui.code(`npm i -g ${name}@latest`)} ` +
-        `(or prefer ${ui.code(`npx ${name}@latest update`)}). ` +
-        `This command only migrates the project.`);
+    return (`This run migrates with the installed binary. Normally ${ui.code("speclaw update")} ` +
+        `upgrades itself through npx; to upgrade the binary yourself run ` +
+        `${ui.code(`npm i -g ${name}@latest`)} (or ${ui.code(`npx ${name}@latest update`)}).`);
 }
 // The first migration must be tagged at the version that introduces this
 // mechanism (0.1.12): `isNewer` is strict, so an entry tagged at an already-
@@ -216,17 +218,58 @@ const MIGRATIONS = [
             "installed binary is stale so migrations match the latest package.\n" +
             "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
     },
+    {
+        version: "2.0.9",
+        describe: "speclaw update re-executes itself at the latest version; MCP entry pinned; " +
+            "lock refresh preserves drift",
+        agentPrompt: "- `speclaw update` now upgrades itself: when npm reports a newer release during the " +
+            "run, it re-executes as `npx -y @esneiderbravo/speclaw@<latest> update` (also in CI) and " +
+            "that release applies its own migrations. Opt out with `--no-self-update` or " +
+            "`SPECLAW_NO_SELF_UPDATE=1`. If your docs tell users to upgrade the binary separately " +
+            "before `speclaw update`, drop that step.\n" +
+            "- The agent MCP entry is pinned to the installed version " +
+            "(`npx -y @esneiderbravo/speclaw@<version> mcp`); `speclaw update` re-pins a stock entry " +
+            "and keeps a custom one.\n" +
+            "- A lock refresh (init/update/`laws compile`/`laws lock`) no longer re-baselines a " +
+            "strict rule file (CLAUDE.md, AGENTS.md, compiled rules) edited outside speclaw: it keeps " +
+            "the locked digest and warns `run speclaw laws accept <path>`. `speclaw laws lock --force` " +
+            "re-baselines on an interactive TTY only. Mention this where the project documents " +
+            "`speclaw.lock`.\n" +
+            "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
+    },
+    {
+        version: "2.0.10",
+        describe: "Compass schema 11 — truthful callers, callees, and affected-test commands",
+        agentPrompt: "- Compass is now **schema 11**: the first `speclaw index` after upgrading migrates " +
+            "10→11 and re-extracts every file once (embeddings are reused). Where the project " +
+            'mentions "Schema **10**" or "Compass (schema 10)", change it to schema 11 ' +
+            "(10→11 forces a reindex; embeddings reused).\n" +
+            "- speclaw 2.0.9 or older (including an MCP entry pinned at `@2.0.9` or a stale " +
+            "global CLI) treats a schema-11 index as incompatible and rebuilds it from scratch, " +
+            "dropping the embedding cache. Where the project documents the index or the MCP entry, " +
+            "add: run `speclaw update` so the pinned MCP entry moves to 2.0.10; an older speclaw " +
+            "opening this index rebuilds it from scratch.\n" +
+            "- Affected-test `command` may now be `null` (with `commandReason`) when no test is " +
+            "reachable, and `commands[]` lists one `{ cwd, command, files }` per package. If the " +
+            "project's docs or scripts run `command` blindly, make them handle `null`.\n" +
+            "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
+    },
 ];
 /**
- * Bring the current project up to date without a full re-init: check whether a
- * newer binary exists on npm (advisory only — never runs `npm install -g`), then
- * additively apply any new standards, skills, commands, and feature steps this
- * project is missing (existing files untouched).
+ * Bring the current project up to date without a full re-init. When the npm
+ * registry, queried during this run, reports a newer release, re-execute as
+ * `npx -y <pkg>@<latest> update <flags>` and exit with the child's code — the
+ * latest release then applies its own migrations, never this stale binary.
+ * Otherwise (already latest, opted out, offline cache only, loop guard set, or
+ * `npx` unavailable) additively apply the project migrations in process.
  *
- * @param flags - `--check` reports version status only (no migrate);
- *   `--migrate-only` is a silent no-op alias of the default (compat).
- * @param hooks - Optional test seams for the version check and migrate path.
+ * @param flags - `--check` reports version status only (no re-run, no migrate);
+ *   `--no-self-update` migrates with this binary; `--migrate-only` is a silent
+ *   no-op alias of the default (compat).
+ * @param hooks - Optional test seams for the version check, the spawn, the
+ *   environment, and the migrate path.
  */
+// Covers: req~update-self-update~1
 export async function runUpdate(flags, hooks = {}) {
     const cwd = process.cwd();
     // `--migrate-only` is accepted for compat but is a no-op alias of default
@@ -235,27 +278,61 @@ export async function runUpdate(flags, hooks = {}) {
     const backup = Boolean(flags.backup);
     const check = hooks.checkForUpdates ?? checkForUpdates;
     const migrate = hooks.applyProjectMigrations ?? applyProjectMigrations;
+    const spawnSelf = hooks.selfUpdate ?? selfUpdate;
+    const env = hooks.env ?? process.env;
+    const runMigrations = () => migrate(cwd, backup, flags.minimal ? true : undefined);
     ui.step("Checking for updates");
-    const { current, latest, updateAvailable } = await check({ force: true });
+    const { current, latest, updateAvailable, fresh } = await check({ force: true });
     if (!latest) {
         ui.warn("Could not reach the npm registry — skipping the version check.");
+        if (!checkOnly)
+            runMigrations();
+        return;
+    }
+    if (!updateAvailable) {
+        ui.ok(`Already on the latest version (${current}).`);
+        if (!checkOnly)
+            runMigrations();
+        return;
+    }
+    ui.info(`${c.muted(current)} ${c.muted("→")} ${c.cyan(latest)}`);
+    if (checkOnly) {
+        ui.info(`Run ${ui.code("speclaw update")} — it upgrades itself to ${latest} through npx and ` +
+            `migrates this project.`);
+        return;
     }
-    else if (updateAvailable) {
-        ui.info(`${c.muted(current)} ${c.muted("→")} ${c.cyan(latest)}`);
-        ui.info(binaryUpgradeHint(pkgName()));
-        if (checkOnly) {
-            ui.info(`Run ${ui.code("speclaw update")} to apply project migrations with the binary you have.`);
+    // parseFlags turns `--no-self-update` into `flags["no-self-update"]`; accept
+    // the `self-update: false` spelling too in case a caller builds flags by hand.
+    const optedOut = Boolean(flags["no-self-update"]) ||
+        flags["self-update"] === false ||
+        Boolean(env.SPECLAW_NO_SELF_UPDATE);
+    const why = optedOut
+        ? "self-update is turned off"
+        : env.SPECLAW_SELF_UPDATED
+            ? "already re-executed once"
+            : !fresh
+                ? "the registry was unreachable (cached version only)"
+                : !isSafeVersion(latest)
+                    ? `the registry reported an invalid version ${JSON.stringify(latest)}`
+                    : null;
+    if (why === null) {
+        const { forward, dropped } = safeForwardArgs(hooks.argv ?? process.argv.slice(3));
+        if (dropped.length)
+            ui.warn(`Not forwarding unsafe argument(s): ${dropped.join(" ")}`);
+        ui.step(`Re-running ${ui.code(`npx -y ${pkgName()}@${latest} update`)}`);
+        const outcome = await spawnSelf({ pkg: pkgName(), version: latest, args: forward, env });
+        if (outcome.kind === "ran") {
+            // The child applied the migrations; the parent never migrates as well.
+            process.exitCode = outcome.code;
             return;
         }
+        ui.warn(`Could not start npx (${outcome.reason}) — migrating with the installed binary.`);
     }
     else {
-        ui.ok(`Already on the latest version (${current}).`);
-        if (checkOnly)
-            return;
+        ui.info(`Not re-running at ${latest}: ${why}.`);
     }
-    if (checkOnly)
-        return;
-    migrate(cwd, backup, flags.minimal ? true : undefined);
+    ui.info(binaryUpgradeHint(pkgName()));
+    runMigrations();
 }
 /**
  * Additively apply the current version's content and feature steps to a project.
@@ -310,6 +387,15 @@ function applyProjectMigrations(cwd, backup, minimal) {
         ui.warn(`${c.cream(rel)} had local edits — overwritten with the current version. ` +
             `Recover from git, or re-run with ${ui.code("--backup")} to keep a .bak.`);
     }
+    // A strict rule file edited outside the pipeline keeps its locked digest;
+    // only a human `speclaw laws accept` moves it.
+    for (const rel of report.lockPreserved)
+        ui.warn(lockPreservedWarning(rel));
+    if (report.lockError) {
+        // An existing lock that cannot be read is left untouched, never rebuilt.
+        ui.err(`${report.lockError} — speclaw.lock was left unchanged; repair it and re-run.`);
+        process.exitCode = 1;
+    }
     // A project several releases behind jumps straight to @latest, so apply EVERY
     // migration newer than its recorded version — not just the next one — oldest
     // first (sorted, so array order can't matter). Entries are cumulative: never