@esneiderbravo/speclaw 2.0.7 → 2.0.9

package/dist/cli/lib/self-update.js

@@ -0,0 +1,107 @@
+/**
+ * Self-update for `speclaw update`: re-run the command as
+ * `npx -y <pkg>@<latest> update …` so the latest release applies its own
+ * migrations instead of a stale binary applying old ones. This is the only CLI
+ * module that imports `child_process`; `update.ts` receives it through
+ * `UpdateHooks` so tests never spawn anything.
+ */
+// Covers: req~update-self-update~1
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Flag tokens safe to forward to the child: `-x`, `--flag`, or `--flag=value`
+ * with a conservative value charset. The charset also keeps the Windows shell
+ * spawn free of injection.
+ */
+const SAFE_TOKEN = /^--?[A-Za-z][A-Za-z0-9-]*(=[A-Za-z0-9._/:@-]*)?$/;
+/**
+ * A registry version that is safe to put on a command line: strict semver with
+ * an optional prerelease tag. Anything else (for example `"9.9.9 & calc"`) is
+ * never spawned — it would reach the Windows shell verbatim.
+ */
+const SAFE_VERSION = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/;
+/**
+ * Whether `version` is a strict semver string safe to spawn with.
+ *
+ * @param version - The `latest` version reported by the registry.
+ * @returns True only for `MAJOR.MINOR.PATCH` with an optional `-prerelease`.
+ */
+export function isSafeVersion(version) {
+    return SAFE_VERSION.test(version);
+}
+/**
+ * Whether `command` exists as a file in a directory on the env's PATH (the key
+ * is matched case-insensitively, since Windows spells it `Path`).
+ *
+ * @param command - The executable file name, e.g. `npx.cmd`.
+ * @param env - The environment whose PATH is searched.
+ * @param delimiter - The PATH separator (`;` on Windows).
+ * @returns True when some PATH entry holds `command`.
+ */
+export function onPath(command, env, delimiter = path.delimiter) {
+    const key = Object.keys(env).find((k) => k.toUpperCase() === "PATH");
+    const dirs = (key ? (env[key] ?? "") : "").split(delimiter).filter(Boolean);
+    return dirs.some((dir) => fs.existsSync(path.join(dir, command)));
+}
+/**
+ * Split the original `update` arguments into the ones forwarded to the child
+ * and the ones dropped. `update` takes no positional arguments, so dropping
+ * anything that is not a safe flag loses nothing in practice.
+ *
+ * @param argv - The arguments after `speclaw update`.
+ * @returns The forwarded tokens (in order) and the dropped ones.
+ */
+export function safeForwardArgs(argv) {
+    const forward = [];
+    const dropped = [];
+    for (const token of argv)
+        (SAFE_TOKEN.test(token) ? forward : dropped).push(token);
+    return { forward, dropped };
+}
+/**
+ * Run `npx -y <pkg>@<version> update <args>` with inherited stdio and the loop
+ * guard `SPECLAW_SELF_UPDATED=<version>` in its environment. On Windows the
+ * `npx.cmd` shim is spawned through the shell (Node refuses `.cmd` files
+ * otherwise); `args` must already be filtered by {@link safeForwardArgs}. A
+ * version that is not strict semver is never spawned, and on Windows a missing
+ * `npx.cmd` is detected up front (the shell would turn it into exit code 1
+ * rather than an ENOENT), so both report `unavailable` and the caller migrates
+ * in process.
+ *
+ * @param opts - Package name, target version, forwarded args, the base env,
+ *   and the platform (defaults to `process.platform`; tests pass `win32`).
+ * @returns `ran` with the child's exit code, or `unavailable` when it could not start.
+ */
+export function selfUpdate(opts) {
+    if (!isSafeVersion(opts.version)) {
+        return Promise.resolve({
+            kind: "unavailable",
+            reason: `invalid version ${JSON.stringify(opts.version)}`,
+        });
+    }
+    const windows = (opts.platform ?? process.platform) === "win32";
+    const command = windows ? "npx.cmd" : "npx";
+    const args = ["-y", `${opts.pkg}@${opts.version}`, "update", ...opts.args];
+    const env = { ...(opts.env ?? process.env), SPECLAW_SELF_UPDATED: opts.version };
+    if (windows && !onPath(command, env, ";")) {
+        return Promise.resolve({ kind: "unavailable", reason: `${command} not found on PATH` });
+    }
+    return new Promise((resolve) => {
+        let settled = false;
+        const done = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(outcome);
+        };
+        try {
+            const child = spawn(command, args, { stdio: "inherit", env, shell: windows });
+            child.on("error", (err) => done({ kind: "unavailable", reason: err.message }));
+            child.on("exit", (code) => done({ kind: "ran", code: code ?? 1 }));
+        }
+        catch (err) {
+            done({ kind: "unavailable", reason: err.message });
+        }
+    });
+}

package/dist/cli/lib/update-check.js

@@ -77,23 +77,28 @@ export function isNewer(latest, current) {
  * cache unless `force` is set. Falls back to stale cache when offline.
  *
  * @param opts - `force` bypasses the cache and always queries the registry.
- * @returns The current/latest versions and whether an upgrade is available.
+ * @returns The current/latest versions, whether an upgrade is available, and
+ *   `fresh`: true only when `latest` came from the registry during this call
+ *   (a cached or offline value is not fresh — `npx` could not resolve it either).
  */
 export async function checkForUpdates(opts = {}) {
     const current = pkgVersion();
     const cache = readCache();
     let latest;
+    let fresh = false;
     if (!opts.force && cache && Date.now() - cache.checkedAt < TTL_MS) {
         latest = cache.latest;
     }
     else {
         latest = await fetchLatest(pkgName());
-        if (latest)
+        if (latest) {
+            fresh = true;
             writeCache(latest);
+        }
         else if (cache)
             latest = cache.latest; // offline: use whatever we last knew
     }
-    return { current, latest, updateAvailable: !!latest && isNewer(latest, current) };
+    return { current, latest, updateAvailable: !!latest && isNewer(latest, current), fresh };
 }
 /** The public npm page for a package, where an upgrade can be reviewed. */
 export function npmPackageUrl(name) {
@@ -102,8 +107,8 @@ export function npmPackageUrl(name) {
 /**
  * Build the two-line "update available" notice. The latest version is rendered
  * as a clickable link to the package's npm page, so a capable terminal lets the
- * user open the release with a single click. Project migrations stay
- * `speclaw update`; the binary is upgraded separately (prefer npx).
+ * user open the release with a single click. `speclaw update` upgrades itself
+ * (it re-runs at the latest version through npx) and migrates the project.
  *
  * @param current - The installed version.
  * @param latest - The newest published version.
@@ -119,16 +124,18 @@ export function upgradeNotice(current, latest) {
         c.muted(" available") +
         "\n" +
         "  " +
-        c.muted("prefer ") +
-        c.cyan(`npx ${name}@latest update`) +
-        c.muted(" — or ") +
+        c.muted("run ") +
         c.cyan("speclaw update") +
-        c.muted(" to migrate this project"));
+        c.muted(" (or ") +
+        c.cyan(`npx ${name}@latest update`) +
+        c.muted(") — it upgrades itself through npx and migrates this project"));
 }
 /**
  * Print the "update available" notice to stderr when a newer version exists.
  * No-op for the `mcp`/`update`/`help`/`version` commands, on non-TTY stderr, or
  * when NO_UPDATE_NOTIFIER / SPECLAW_NO_UPDATE_NOTIFIER is set. Never throws.
+ * `SPECLAW_UPDATE_NOTIFIER=force` lifts only the TTY check, so a test with
+ * piped stderr can prove a command path does (or does not) reach the notifier.
  *
  * @param cmd - The command that just ran (used to skip noisy contexts).
  */
@@ -136,7 +143,7 @@ export async function maybeNotifyUpdate(cmd) {
     try {
         if (process.env.NO_UPDATE_NOTIFIER || process.env.SPECLAW_NO_UPDATE_NOTIFIER)
             return;
-        if (!process.stderr.isTTY)
+        if (!process.stderr.isTTY && process.env.SPECLAW_UPDATE_NOTIFIER !== "force")
             return;
         // `init` shows its own prominent up-front warning and ends on the clean
         // copy-paste prompt — don't append a second notice after it.

package/dist/modules/cortex/brief.js

@@ -57,7 +57,9 @@ export function briefForStage(stage) {
                 role: "archiver",
                 agentPath: "ai-specs/agents/archiver.md",
                 skillHints: ["sync", "archive"],
-                nextOps: ["advance"],
+                // A successful `lawbook_change` archive completes the harness itself;
+                // no Cortex op follows (confirm `done` with `status`).
+                nextOps: [],
             };
         case "done":
         case null:

package/dist/modules/cortex/harness.js

@@ -11,6 +11,9 @@
 import fs from "node:fs";
 import path from "node:path";
 import { GATED_STAGES, compassGateError, compassGateWarning, evaluateCompassGate, readCompassGateMode, } from "./compass-gate.js";
+import { buildStatusSummary } from "./status.js";
+import { resolveChangeDir } from "./paths.js";
+export { resolveChangeDir } from "./paths.js";
 // Harness types live in the leaf `types.ts` so `compass-gate.ts` can use them
 // without importing this file back (no file-level import cycle).
 export { HARNESS_STAGES, } from "./types.js";
@@ -20,7 +23,8 @@ function specRoot(projectPath) {
     return path.join(projectPath, "lawbook");
 }
 function changeDir(projectPath, change) {
-    return path.join(specRoot(projectPath), "changes", change);
+    return (resolveChangeDir(projectPath, change)?.dir ??
+        path.join(specRoot(projectPath), "changes", change));
 }
 function harnessPath(projectPath, change) {
     return path.join(changeDir(projectPath, change), "harness.json");
@@ -29,11 +33,11 @@ function nowIso() {
     return new Date().toISOString();
 }
 function requireChangeDir(projectPath, change) {
-    const dir = changeDir(projectPath, change);
-    if (!fs.existsSync(dir)) {
+    const resolved = resolveChangeDir(projectPath, change);
+    if (!resolved) {
         throw new Error(`change "${change}" not found under lawbook/changes/`);
     }
-    return dir;
+    return resolved;
 }
 /**
  * Read confirmed ceremony level from change.json without importing lawbook.
@@ -112,15 +116,23 @@ function allowedAdvance(from, level, verdict) {
     }
 }
 /**
- * Dispatch a harness op for a change.
+ * Dispatch a harness op for a change. `status` also returns the status
+ * summary (`req~cortex-status-summary~1`); other ops return the state.
  *
  * // Covers: req~harness-state~1
  */
 export function handleHarness(args) {
     const { projectPath, change, harnessOp } = args;
-    requireChangeDir(projectPath, change);
+    const resolved = requireChangeDir(projectPath, change);
     if (harnessOp === "status") {
-        return { state: readHarness(projectPath, change) };
+        const state = readHarness(projectPath, change);
+        return { summary: state ? buildStatusSummary(projectPath, state) : null, state };
+    }
+    // An archived change is read-only: reject mutating ops before any write.
+    // Covers: req~harness-archive-completes~1
+    if (resolved.archived) {
+        throw new Error(`change ${change} is archived (${path.relative(projectPath, resolved.dir)}); ` +
+            `Cortex ops are read-only`);
     }
     if (harnessOp === "start") {
         const existing = readHarness(projectPath, change);
@@ -255,6 +267,43 @@ export function handleHarness(args) {
     }
     throw new Error(`unknown harnessOp '${String(harnessOp)}'`);
 }
+/**
+ * Complete a change's harness as part of archiving: move stage `archiving` to
+ * `done` with one history entry. Called by the lawbook archive **before** the
+ * change directory moves, so a crash cannot leave the harness stuck; the
+ * returned `restore` puts the old bytes back if the move fails. A missing
+ * harness or one already `done` is left untouched.
+ *
+ * @param projectPath - Absolute path to the project root.
+ * @param change - Change name (an active change).
+ * @param note - History note naming the archive.
+ * @returns Whether the harness was completed and how to undo it.
+ * @throws If the harness is in any other stage (the archive gate prevents this).
+ */
+// Covers: req~harness-archive-completes~1
+export function completeHarnessOnArchive(projectPath, change, note) {
+    const noop = { completed: false, restore: () => { } };
+    const p = harnessPath(projectPath, change);
+    if (!fs.existsSync(p))
+        return noop;
+    const original = fs.readFileSync(p, "utf8");
+    const state = JSON.parse(original);
+    if (state.stage === "done")
+        return noop;
+    if (state.stage !== "archiving") {
+        throw new Error(`harness stage is ${state.stage} — advance to archiving before archive (${change})`);
+    }
+    const next = {
+        ...state,
+        stage: "done",
+        history: [
+            ...state.history,
+            { at: nowIso(), from: "archiving", to: "done", op: "advance", note },
+        ],
+    };
+    fs.writeFileSync(p, JSON.stringify(next, null, 2) + "\n");
+    return { completed: true, restore: () => fs.writeFileSync(p, original) };
+}
 /**
  * Archive blockers derived from harness verdicts.
  *

package/dist/modules/cortex/paths.js

@@ -0,0 +1,39 @@
+/**
+ * Change-directory resolution shared by the Cortex harness and its status
+ * summary. A leaf module (no Cortex imports) so both can use it without an
+ * import cycle; Cortex never imports the lawbook module.
+ */
+import fs from "node:fs";
+import path from "node:path";
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Resolve a change name to its directory: the active `lawbook/changes/<name>/`
+ * when it exists, otherwise the newest `lawbook/changes/archive/<YYYY-MM-DD>-<name>/`
+ * (matched exactly, so `<date>-other-<name>` never matches `<name>`).
+ *
+ * @param projectPath - Absolute path to the project root.
+ * @param change - Change name.
+ * @returns The directory and whether it is archived, or null when neither exists.
+ */
+// Covers: req~harness-archive-completes~1
+export function resolveChangeDir(projectPath, change) {
+    const active = path.join(projectPath, "lawbook", "changes", change);
+    if (fs.existsSync(active))
+        return { dir: active, archived: false };
+    const archiveRoot = path.join(projectPath, "lawbook", "changes", "archive");
+    let entries;
+    try {
+        entries = fs.readdirSync(archiveRoot);
+    }
+    catch {
+        return null;
+    }
+    const re = new RegExp(`^\\d{4}-\\d{2}-\\d{2}-${escapeRegExp(change)}$`);
+    const newest = entries
+        .filter((e) => re.test(e))
+        .sort()
+        .at(-1);
+    return newest ? { dir: path.join(archiveRoot, newest), archived: true } : null;
+}

package/dist/modules/cortex/register.js

@@ -8,6 +8,7 @@ import { defineTool, text } from "../../shared/mcp.js";
 import { shouldExpose } from "../../shared/exposure.js";
 import { handleHarness, harnessOps, readHarness, } from "./harness.js";
 import { briefForStage } from "./brief.js";
+import { fitStatusResult } from "./status.js";
 export const cortexActions = [...harnessOps, "brief"];
 /**
  * Register the canonical `cortex` MCP tool.
@@ -22,7 +23,7 @@ export function registerCortex(server, opts = {}) {
             return;
         defineTool(server, { name, description, inputSchema, handler });
     };
-    add("cortex", "Cortex multi-agent loop: status, start, advance, rework, brief for a change.", {
+    add("cortex", "Cortex multi-agent loop: status with summary, start, advance, rework, brief for a change.", {
         projectPath: z.string(),
         change: z.string(),
         action: z.enum(cortexActions),
@@ -36,7 +37,7 @@ export function registerCortex(server, opts = {}) {
             const brief = briefForStage(state?.stage ?? null);
             return text(JSON.stringify({ state, ...brief }, null, 2));
         }
-        return text(handleHarness({
+        const result = handleHarness({
             projectPath,
             change,
             harnessOp: action,
@@ -44,6 +45,8 @@ export function registerCortex(server, opts = {}) {
             verdict: verdict ?? null,
             openQuestions,
             pauseForQuestions,
-        }));
+        });
+        // `text()` cuts from the end; fit `status` so `summary` and valid JSON survive.
+        return text(action === "status" && "summary" in result ? fitStatusResult(result) : result);
     });
 }

package/dist/modules/cortex/status.js

@@ -0,0 +1,200 @@
+/**
+ * Per-change status summary for Cortex `status`: stage, active role, time in
+ * stage, task progress, rework, pending verdicts, and the configured interval
+ * at which the coordinator posts status updates.
+ *
+ * Cortex must not import from the lawbook module, so task checkboxes and the
+ * `cortex.statusIntervalMinutes` key are read with local text scans, like
+ * `readCompassGateMode`.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { briefForStage } from "./brief.js";
+import { stageStartedAt } from "./compass-gate.js";
+import { OUTPUT_BUDGET, estimateTokens } from "../../shared/output-budget.js";
+import { resolveChangeDir } from "./paths.js";
+/** Interval used when the key is missing or invalid. */
+export const DEFAULT_STATUS_INTERVAL_MINUTES = 5;
+/**
+ * Largest interval reported. A session timer is a cron expression, and
+ * an every-N-minutes step only exists for N ≤ 59; 60 is the hourly ping.
+ */
+export const MAX_STATUS_INTERVAL_MINUTES = 60;
+const CHECKBOX = /^\s*[-*]\s+\[( |x|X)\]/;
+/**
+ * Count Markdown task-list items (`- [ ]`, `- [x]`, `* [X]`). Brackets outside
+ * a list item are ignored. This is a line scan, not a Markdown parser: items
+ * inside fenced code blocks are counted, and `+` bullets and numbered
+ * (`1. [ ]`) items are not.
+ *
+ * @param text - Markdown source.
+ * @returns Checked and total item counts.
+ */
+export function countTaskCheckboxes(text) {
+    let done = 0;
+    let total = 0;
+    for (const lineText of text.split(/\r?\n/)) {
+        const m = CHECKBOX.exec(lineText);
+        if (!m)
+            continue;
+        total++;
+        if (m[1] !== " ")
+            done++;
+    }
+    return { done, total };
+}
+/**
+ * Read `statusIntervalMinutes` from the top-level `cortex:` block of
+ * `lawbook/config.yaml`. Quotes and a trailing comment are allowed. A missing
+ * file, block, or key, or any value that is not a whole number ≥ 0, yields 5.
+ * Values above 60 are clamped to 60. Never throws.
+ *
+ * This is a line scan, not a YAML parser: the key is accepted at any
+ * indentation under `cortex:` (nested maps included), and flow style
+ * (`cortex: {statusIntervalMinutes: 3}`) is not read, so it yields 5.
+ *
+ * @param projectPath - Project root.
+ *
+ * // Covers: req~cortex-status-interval~1
+ */
+export function readStatusIntervalMinutes(projectPath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(projectPath, "lawbook", "config.yaml"), "utf8");
+    }
+    catch {
+        return DEFAULT_STATUS_INTERVAL_MINUTES;
+    }
+    const lines = raw.split(/\r?\n/);
+    const start = lines.findIndex((l) => /^cortex:[ \t]*(?:#.*)?$/.test(l));
+    if (start < 0)
+        return DEFAULT_STATUS_INTERVAL_MINUTES;
+    for (let i = start + 1; i < lines.length; i++) {
+        const l = lines[i];
+        // The block ends at the next column-0 key; blank and comment lines are skipped.
+        if (/^\S/.test(l) && !l.startsWith("#"))
+            break;
+        const m = /^\s+statusIntervalMinutes:\s*(\S+)/.exec(l);
+        if (!m)
+            continue;
+        const value = m[1].replace(/#.*$/, "").replace(/^(["'])(.*)\1$/, "$2");
+        if (!/^\d+$/.test(value))
+            return DEFAULT_STATUS_INTERVAL_MINUTES;
+        return Math.min(Number(value), MAX_STATUS_INTERVAL_MINUTES);
+    }
+    return DEFAULT_STATUS_INTERVAL_MINUTES;
+}
+function readTaskCounts(projectPath, change) {
+    // An archived change still reports its tasks from the archive directory.
+    const dir = resolveChangeDir(projectPath, change)?.dir ??
+        path.join(projectPath, "lawbook", "changes", change);
+    for (const file of ["tasks.md", "record.md"]) {
+        let text;
+        try {
+            text = fs.readFileSync(path.join(dir, file), "utf8");
+        }
+        catch {
+            continue;
+        }
+        return countTaskCheckboxes(text);
+    }
+    return null;
+}
+function elapsedSince(startedAt, now) {
+    if (!startedAt)
+        return null;
+    const t = Date.parse(startedAt);
+    if (Number.isNaN(t))
+        return null;
+    return Math.max(0, Math.floor((now.getTime() - t) / 60000));
+}
+/**
+ * Build the status summary of a running change from its harness state, its
+ * task list, and the configured status interval.
+ *
+ * @param projectPath - Project root.
+ * @param state - Harness state of the change.
+ * @param now - Clock for `elapsedMinutes`; injectable for tests.
+ * @returns The structured summary and its one-line English rendering.
+ *
+ * // Covers: req~cortex-status-summary~1
+ */
+export function buildStatusSummary(projectPath, state, now = new Date()) {
+    const role = briefForStage(state.stage).role;
+    const startedAt = stageStartedAt(state);
+    const elapsedMinutes = elapsedSince(startedAt, now);
+    const tasks = readTaskCounts(projectPath, state.change);
+    const pendingVerdicts = [];
+    if (state.level >= 1 && state.verdicts.review !== "PASS")
+        pendingVerdicts.push("review");
+    if (state.verdicts.test !== "PASS")
+        pendingVerdicts.push("test");
+    const openQuestions = state.openQuestions.length;
+    const parts = [
+        state.change,
+        role ? `${state.stage} (${role})` : state.stage,
+        elapsedMinutes === null ? "elapsed n/a" : `${elapsedMinutes}m in stage`,
+        tasks ? `tasks ${tasks.done}/${tasks.total}` : "tasks n/a",
+        `rework ${state.iteration}/${state.maxRework}`,
+        `pending: ${pendingVerdicts.length ? pendingVerdicts.join(", ") : "none"}`,
+    ];
+    if (state.stage === "questions") {
+        parts.push(`waiting on human: ${openQuestions} question(s)`);
+    }
+    return {
+        change: state.change,
+        stage: state.stage,
+        role,
+        stageStartedAt: startedAt,
+        elapsedMinutes,
+        tasks,
+        iteration: state.iteration,
+        maxRework: state.maxRework,
+        pendingVerdicts,
+        openQuestions,
+        statusIntervalMinutes: readStatusIntervalMinutes(projectPath),
+        line: parts.join(" · "),
+    };
+}
+/**
+ * Fit a `status` result into the brief MCP output budget without ever cutting
+ * `summary`. `text()` truncates a payload from the end, which would yield
+ * invalid JSON and lose whatever comes last; this keeps the payload under the
+ * budget instead, by dropping the oldest `state.history` entries (newest
+ * kept) and recording how many were dropped in `historyOmitted`. If an empty
+ * history still does not fit, `state` becomes `null` with `stateOmitted`.
+ * Only the MCP rendering is trimmed: `harness.json` and the CLI keep the full
+ * history.
+ *
+ * @param result - The `handleHarness` `status` result.
+ * @param maxTokens - Token ceiling; defaults to the brief output budget.
+ * @returns A result whose pretty-printed JSON fits `maxTokens`.
+ *
+ * // Covers: req~cortex-status-summary~1
+ */
+export function fitStatusResult(result, maxTokens = OUTPUT_BUDGET.brief) {
+    const fits = (value) => estimateTokens(JSON.stringify(value, null, 2)) <= maxTokens;
+    const { summary, state } = result;
+    const full = { summary, state };
+    if (!state || fits(full))
+        return full;
+    const history = state.history;
+    const keepLast = (k) => ({
+        summary,
+        historyOmitted: history.length - k,
+        state: { ...state, history: k > 0 ? history.slice(-k) : [] },
+    });
+    // Fitting is monotone in the number of kept entries: binary-search the most.
+    let lo = 0;
+    let hi = history.length - 1;
+    if (!fits(keepLast(0)))
+        return { summary, stateOmitted: true, state: null };
+    while (lo < hi) {
+        const mid = Math.ceil((lo + hi) / 2);
+        if (fits(keepLast(mid)))
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return keepLast(lo);
+}

package/dist/modules/foundation/compile-laws.js

@@ -4,7 +4,7 @@ import { globError, isActiveLaw, readLawManifest, seedManifestFor, mergeSeedLaws
 import { parseLawsFromStandards } from "./laws-parse.js";
 import { agentsmdDialect, claudeRulesDialect, coderabbitDialect, copilotDialect, cursorMdcDialect, patchDelimited, } from "./dialects/index.js";
 import { detectConfiguredAgents } from "../../shared/agents.js";
-import { digestText, provenanceBlock, refreshLockfile } from "./lock.js";
+import { digestText, driftedStrictPaths, provenanceBlock, refreshLockfile } from "./lock.js";
 const DIALECTS = [
     claudeRulesDialect,
     cursorMdcDialect,
@@ -159,7 +159,21 @@ export function compileLaws(opts) {
         failed: [],
         lawCount: 0,
         draftCount: 0,
+        lockPreserved: [],
     };
+    // Snapshot drift before any rule artifact is written: compilation rewrites
+    // the speclaw regions of CLAUDE.md / AGENTS.md, which must not launder edits.
+    // An existing lock that cannot be read is reported and left untouched, never
+    // rebuilt from disk (that would launder drift); compilation itself proceeds.
+    let drifted = opts.drifted ?? [];
+    if (opts.drifted === undefined && opts.refreshLock !== false) {
+        try {
+            drifted = driftedStrictPaths(projectPath);
+        }
+        catch (err) {
+            report.lockError = err.message;
+        }
+    }
     const laws = mergeLawSources(projectPath);
     validateScopes(laws);
     report.lawCount = laws.filter(isActiveLaw).length;
@@ -185,11 +199,14 @@ export function compileLaws(opts) {
     if (agents.includes("claude"))
         ensureClaudeRulesSymlink(projectPath, report);
     // Covers: req~lock-refresh-update~1
-    try {
-        refreshLockfile(projectPath);
-    }
-    catch {
-        // Lock refresh must not fail compile; `speclaw laws lock` surfaces errors.
+    if (opts.refreshLock !== false && report.lockError === undefined) {
+        try {
+            report.lockPreserved = refreshLockfile(projectPath, { drifted }).preserved;
+        }
+        catch (err) {
+            // refreshLockfile throws before writing; the caller surfaces lockError.
+            report.lockError = err.message;
+        }
     }
     return report;
 }

package/dist/modules/foundation/doctor.js

@@ -557,6 +557,15 @@ function specsOrphansCheck(projectPath) {
         remedy: `speclaw lawbook archive ${active[0]}`,
     };
 }
+/**
+ * Fix hint for an unreadable or invalid `speclaw.lock`. `laws lock` refuses
+ * such a lock, and deleting it re-baselines every pinned file, silently
+ * accepting any pending drift — so that is offered only as a last resort.
+ */
+export const UNREADABLE_LOCK_REMEDY = "resolve the merge conflict in speclaw.lock or restore it from git " +
+    "(git checkout -- speclaw.lock); upgrade speclaw if the lockfileVersion is newer. " +
+    "Last resort: delete it and run speclaw laws lock — this re-baselines every " +
+    "pinned file and accepts any pending drift";
 function integrityChecks(projectPath) {
     // Covers: req~doctor-integrity~1
     const out = [];
@@ -591,7 +600,8 @@ function integrityChecks(projectPath) {
                 title: "rule lockfile",
                 status: "error",
                 detail: err.message,
-                remedy: "speclaw laws lock",
+                // `laws lock` refuses an unreadable lock, so point at repairing it.
+                remedy: UNREADABLE_LOCK_REMEDY,
             });
         }
     }