@esneiderbravo/speclaw 2.0.8 → 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

@@ -12,6 +12,8 @@ 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";
@@ -21,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");
@@ -30,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.
@@ -120,11 +123,17 @@ function allowedAdvance(from, level, verdict) {
  */
 export function handleHarness(args) {
     const { projectPath, change, harnessOp } = args;
-    requireChangeDir(projectPath, change);
+    const resolved = requireChangeDir(projectPath, change);
     if (harnessOp === "status") {
         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);
         if (existing && existing.stage !== "done") {
@@ -258,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/status.js

@@ -12,6 +12,7 @@ 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;
 /**
@@ -84,7 +85,9 @@ export function readStatusIntervalMinutes(projectPath) {
     return DEFAULT_STATUS_INTERVAL_MINUTES;
 }
 function readTaskCounts(projectPath, change) {
-    const dir = path.join(projectPath, "lawbook", "changes", 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 {

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,
             });
         }
     }