@esneiderbravo/speclaw 2.0.7 → 2.0.9

package/dist/modules/foundation/lock.js

@@ -62,28 +62,97 @@ export function rootDigest(files) {
     }
     return digestOf(acc);
 }
-/** Read lockfile or null if missing. Throws on unknown version / parse error. */
+/**
+ * Read `speclaw.lock`.
+ *
+ * @param projectPath - Project root.
+ * @returns The lock, or `null` only when the file does not exist.
+ * @throws When the file exists but cannot be read: a parse error, a missing or
+ *   unsupported `lockfileVersion`, or a body that parses but has the wrong
+ *   structure (see {@link lockShapeError}). A malformed lock is never coerced
+ *   into an empty one, because refreshing from an empty lock would launder
+ *   every drifted strict file.
+ */
 export function readLockfile(projectPath) {
     const abs = lockfilePath(projectPath);
     if (!fs.existsSync(abs))
         return null;
-    const raw = JSON.parse(fs.readFileSync(abs, "utf8"));
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(abs, "utf8"));
+    }
+    catch (err) {
+        throw new Error(`speclaw.lock: unreadable (${err.message})`, { cause: err });
+    }
+    if (!raw || typeof raw !== "object")
+        throw new Error("speclaw.lock: not a JSON object");
     if (typeof raw.lockfileVersion !== "number") {
         throw new Error("speclaw.lock: missing lockfileVersion");
     }
     if (raw.lockfileVersion > LOCKFILE_VERSION) {
         throw new Error(`speclaw.lock: unsupported lockfileVersion ${raw.lockfileVersion} (max ${LOCKFILE_VERSION})`);
     }
+    const shape = lockShapeError(raw);
+    if (shape)
+        throw new Error(`speclaw.lock: invalid structure (${shape})`);
     return {
         lockfileVersion: raw.lockfileVersion,
         generator: String(raw.generator ?? ""),
         algorithm: "sha256",
         root: String(raw.root ?? ""),
-        files: raw.files && typeof raw.files === "object" ? raw.files : {},
-        symlinks: raw.symlinks && typeof raw.symlinks === "object" ? raw.symlinks : {},
-        accepted: Array.isArray(raw.accepted) ? raw.accepted : [],
+        files: raw.files ?? {},
+        symlinks: raw.symlinks ?? {},
+        accepted: raw.accepted ?? [],
     };
 }
+const LOCK_OWNERSHIPS = ["strict", "advisory", "scan-only"];
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+ * The first structural defect of a parsed lock body. `files`, `symlinks`, and
+ * `accepted` may be absent (they default to empty), but when present they must
+ * have the lockfile's types: `files` maps paths to `{ digest: string,
+ * ownership }`, `symlinks` maps paths to `{ target: string }`, and `accepted`
+ * is an array of `{ path: string, digest: string }` records.
+ *
+ * @param raw - The parsed JSON object.
+ * @returns A short description of the defect, or `null` when the shape is valid.
+ */
+function lockShapeError(raw) {
+    const { files, symlinks, accepted } = raw;
+    if (files !== undefined) {
+        if (!isPlainObject(files))
+            return "files is not an object";
+        for (const [rel, e] of Object.entries(files)) {
+            if (!isPlainObject(e) || typeof e.digest !== "string") {
+                return `files["${rel}"] has no string digest`;
+            }
+            if (typeof e.ownership !== "string" || !LOCK_OWNERSHIPS.includes(e.ownership)) {
+                return `files["${rel}"] has an unknown ownership`;
+            }
+        }
+    }
+    if (symlinks !== undefined) {
+        if (!isPlainObject(symlinks))
+            return "symlinks is not an object";
+        for (const [rel, e] of Object.entries(symlinks)) {
+            if (!isPlainObject(e) || typeof e.target !== "string") {
+                return `symlinks["${rel}"] has no string target`;
+            }
+        }
+    }
+    if (accepted !== undefined) {
+        if (!Array.isArray(accepted))
+            return "accepted is not an array";
+        for (const [i, a] of accepted.entries()) {
+            if (!isPlainObject(a) || typeof a.path !== "string" || typeof a.digest !== "string") {
+                return `accepted[${i}] needs a string path and digest`;
+            }
+        }
+    }
+    return null;
+}
 /** Write lockfile with stable JSON formatting. */
 export function writeLockfile(projectPath, lock) {
     const abs = lockfilePath(projectPath);
@@ -269,24 +338,159 @@ export function extractSpeclawYamlBlock(raw) {
         /<!-- speclaw:begin-provenance[\s\S]*?speclaw:end-provenance -->/.exec(raw);
     return m2 ? m2[0] : null;
 }
-/** Create or refresh speclaw.lock from the current tree. */
-export function refreshLockfile(projectPath) {
-    const prev = (() => {
-        try {
-            return readLockfile(projectPath);
-        }
-        catch {
-            return null;
+/**
+ * Strict lock paths whose on-disk digest matches neither the locked digest nor
+ * an `accepted[]` digest for that path — files edited outside the speclaw
+ * pipeline. A missing file is not drifted (verify reports it as missing).
+ * Callers that write rule files must compute this **before** those writes.
+ *
+ * @param projectPath - Project root holding `speclaw.lock`.
+ * @param prev - The current lock; read from disk when omitted.
+ * @returns The drifted strict paths, sorted (empty when no lockfile exists).
+ * @throws When `speclaw.lock` exists but cannot be read (parse error,
+ *   unsupported `lockfileVersion`, invalid structure) — an unreadable lock is
+ *   never "no drift".
+ */
+// Covers: req~lock-preserves-drift~1
+export function driftedStrictPaths(projectPath, prev = readLockfile(projectPath)) {
+    if (!prev)
+        return [];
+    const drifted = [];
+    for (const [rel, entry] of Object.entries(prev.files)) {
+        if (entry.ownership !== "strict")
+            continue;
+        const actual = onDiskDigest(projectPath, rel);
+        if (actual === null || actual === entry.digest)
+            continue;
+        if (prev.accepted.some((a) => a.path === rel && a.digest === actual))
+            continue;
+        drifted.push(rel);
+    }
+    return drifted.sort();
+}
+/**
+ * The warning shown for a strict file whose locked digest a refresh kept.
+ *
+ * @param rel - Project-relative path of the drifted file.
+ * @returns One line naming the file and the `laws accept` command.
+ */
+export function lockPreservedWarning(rel) {
+    return (`${rel} drifted from speclaw.lock — kept the locked digest; ` + `run speclaw laws accept ${rel}`);
+}
+/**
+ * The integrity digest of a project file as it is on disk.
+ *
+ * @param projectPath - Project root.
+ * @param rel - Project-relative path.
+ * @returns The digest, or `null` when the path is not a regular file.
+ */
+export function onDiskDigest(projectPath, rel) {
+    const abs = path.join(projectPath, rel);
+    if (!fs.existsSync(abs) || !fs.statSync(abs).isFile())
+        return null;
+    return digestText(prepareIntegrityText(rel, fs.readFileSync(abs, "utf8")));
+}
+/** Thrown when the tree or the lock changed between a confirmation and its write. */
+export class LockChangedError extends Error {
+    constructor(detail) {
+        super(`${detail} changed while the confirmation was open`);
+        this.name = "LockChangedError";
+    }
+}
+/**
+ * Re-check a confirmed re-baseline against the lock and the snapshot about to
+ * be written: the drifted set must be exactly the confirmed paths, and each
+ * path's locked and on-disk digests must equal what was shown.
+ *
+ * @returns The drifted paths (equal to the confirmed ones).
+ * @throws {LockChangedError} On any difference.
+ */
+function checkConfirmedDrift(projectPath, prev, files, confirmed) {
+    const now = driftedStrictPaths(projectPath, prev);
+    const shown = confirmed.map((c) => c.path).sort();
+    const extra = now.filter((p) => !shown.includes(p));
+    if (extra.length)
+        throw new LockChangedError(`newly drifted ${extra.join(", ")}`);
+    const gone = shown.filter((p) => !now.includes(p));
+    if (gone.length)
+        throw new LockChangedError(gone.join(", "));
+    for (const c of confirmed) {
+        if (prev?.files[c.path]?.digest !== c.locked) {
+            throw new LockChangedError(`the locked digest of ${c.path}`);
         }
-    })();
+        // A locked path outside discovery is not in the snapshot; read it directly.
+        const actual = files[c.path]?.digest ?? onDiskDigest(projectPath, c.path);
+        if (actual !== c.actual)
+            throw new LockChangedError(c.path);
+    }
+    return now;
+}
+/**
+ * Create or refresh speclaw.lock from the current tree without laundering
+ * tampering: a strict path that drifted from the lock keeps its locked digest
+ * (and is reported in `preserved`) unless `rebaseline` is given, which only the
+ * interactive `laws lock --force` passes. Clean strict paths are refreshed, new
+ * strict paths are added, and advisory paths are refreshed freely. `accepted[]`
+ * entries survive only while they equal their path's locked digest. A fresh
+ * baseline is built only when no lockfile exists: a lockfile that exists but
+ * cannot be read is never overwritten, because rebuilding it from disk would
+ * launder every drifted strict file (and downgrade a newer-format lock).
+ *
+ * @param projectPath - Project root.
+ * @param opts - `drifted`: the drifted strict paths computed before any rule
+ *   file was written (defaults to computing them now); `rebaseline`: re-baseline
+ *   drifted paths to disk and record an `accepted[]` entry by `by` for each
+ *   (with the optional human `note` appended to the `laws lock --force` note).
+ *   `rebaseline.confirmed` is what the human was shown and approved; when
+ *   given, the drifted set and every locked and on-disk digest are re-checked
+ *   against it from the snapshot about to be written, closing the gap between
+ *   the prompt and the write.
+ * @returns The written lock plus the preserved, re-baselined, and pruned counts.
+ * @throws When `speclaw.lock` exists but cannot be read (parse error,
+ *   unsupported `lockfileVersion`, invalid structure); nothing is written.
+ * @throws {LockChangedError} When `rebaseline.confirmed` no longer matches the
+ *   drifted set or the digests on disk; nothing is written.
+ */
+// Covers: req~lock-preserves-drift~1
+export function refreshLockfile(projectPath, opts = {}) {
+    const prev = readLockfile(projectPath);
     const { files, symlinks } = snapshotLockEntries(projectPath);
-    const lock = buildLock({
-        files,
-        symlinks,
-        accepted: prev?.accepted ?? [],
-    });
+    const confirmed = opts.rebaseline?.confirmed;
+    const drifted = confirmed
+        ? checkConfirmedDrift(projectPath, prev, files, confirmed)
+        : (opts.drifted ?? driftedStrictPaths(projectPath, prev));
+    const accepted = [...(prev?.accepted ?? [])];
+    const preserved = [];
+    const rebaselined = [];
+    const at = new Date().toISOString();
+    for (const rel of drifted) {
+        const old = prev?.files[rel];
+        const next = files[rel];
+        if (!old || !next || old.ownership !== "strict")
+            continue;
+        if (opts.rebaseline) {
+            if (next.digest !== old.digest) {
+                rebaselined.push(rel);
+                accepted.push({
+                    path: rel,
+                    digest: next.digest,
+                    at,
+                    by: opts.rebaseline.by,
+                    note: opts.rebaseline.note
+                        ? `laws lock --force: ${opts.rebaseline.note}`
+                        : "laws lock --force",
+                });
+            }
+        }
+        else if (next.digest !== old.digest) {
+            files[rel] = old;
+            preserved.push(rel);
+        }
+    }
+    const kept = accepted.filter((a) => files[a.path] !== undefined && files[a.path].digest === a.digest);
+    const lock = buildLock({ files, symlinks, accepted: kept });
     writeLockfile(projectPath, lock);
-    return lock;
+    return { lock, preserved, rebaselined, pruned: accepted.length - kept.length };
 }
 /** Render a data-only provenance HTML comment (no imperatives). */
 export function provenanceBlock(opts) {

package/dist/modules/foundation/scaffold.js

@@ -11,7 +11,8 @@ import { pkgVersion } from "../../shared/version.js";
 import { mergeSeedLaws, readLawManifest, seedManifestFor, writeLawManifest, } from "./laws.js";
 import { installHooks } from "./hooks.js";
 import { compileLaws } from "./compile-laws.js";
-import { refreshLockfile } from "./lock.js";
+import { driftedStrictPaths, refreshLockfile } from "./lock.js";
+export { lockPreservedWarning } from "./lock.js";
 import { refreshOwnersIfConfigured } from "../team/owners.js";
 const ASSETS = assetsDir(import.meta.url);
 // Every {{var}} the foundation templates may reference. Ones the agent didn't
@@ -128,7 +129,19 @@ export function scaffold(projectPath, profile, packNames, agents = [], opts = {}
     const unknown = packNames.filter((n) => !packs[n]);
     if (unknown.length)
         throw new Error(`Unknown packs: ${unknown.join(", ")}`);
-    const report = { ...emptyReport(), nextSteps: [] };
+    const report = { ...emptyReport(), nextSteps: [], lockPreserved: [] };
+    // Snapshot strict-file drift before writing anything: the rule files written
+    // below (foundation, agents, compiled laws) must not re-baseline an edit made
+    // outside the pipeline.
+    // A lockfile that exists but cannot be read is reported in `lockError` and
+    // left byte-identical: rebuilding it from disk would launder drift.
+    let drifted = [];
+    try {
+        drifted = driftedStrictPaths(projectPath);
+    }
+    catch (err) {
+        report.lockError = err.message;
+    }
     const vars = { ...FOUNDATION_DEFAULTS, ...profile };
     // Managed trees (MANAGED_TREES) carry speclaw's workflow logic and may be
     // overwritten on update; the foundation (personalized) is always additive.
@@ -157,17 +170,20 @@ export function scaffold(projectPath, profile, packNames, agents = [], opts = {}
     // executable-laws will extend the same manifest with more backends.
     const lawManifest = ensureLawManifest(projectPath, report);
     try {
-        compileLaws({ projectPath, agents, writeManifest: false });
+        compileLaws({ projectPath, agents, writeManifest: false, drifted, refreshLock: false });
     }
     catch {
         // Compilation must not fail scaffold; `speclaw laws compile` surfaces errors.
     }
     // Covers: req~lock-refresh-update~1
-    try {
-        refreshLockfile(projectPath);
-    }
-    catch {
-        // Lock refresh must not fail scaffold; `speclaw laws lock` surfaces errors.
+    if (report.lockError === undefined) {
+        try {
+            report.lockPreserved = refreshLockfile(projectPath, { drifted }).preserved;
+        }
+        catch (err) {
+            // refreshLockfile throws before writing; init/update surface lockError.
+            report.lockError = err.message;
+        }
     }
     ensureVerifyWorkflow(projectPath, report);
     report.hooks = installHooks(projectPath, agents, lawManifest, report, {

package/dist/modules/lawbook/assets/agents/archiver.md

@@ -9,8 +9,11 @@ You are the **archiver** role in speclaw's **Cortex** (One brain. Many agents.).
 ## Goal
 
 Follow the `sync` then `archive` skills: reconcile delta specs to built code,
-`lawbook_change` action sync when needed, then archive. Advance Cortex to
-`done` after a successful archive.
+`lawbook_change` action sync when needed, then archive. A successful archive
+completes the Cortex harness itself (`harnessCompleted` in the result); do not
+call a mutating Cortex op (`advance`, `rework`, `start`) afterwards. Confirm
+with the read-only `cortex` action `status` that the stage is `done`, and
+report it to the coordinator.
 
 ## Hard constraints
 

package/dist/modules/lawbook/assets/commands/cortex.md

@@ -9,3 +9,5 @@ explorer → planner → implementer → reviewer → tester → archiver. Drive
 with the `cortex` MCP tool (`status`/`start`/`advance`/`rework`/`brief`) or
 `speclaw cortex …`. Surface planner questions to the human. Do not implement
 product code yourself.
+The run posts status updates every `cortex.statusIntervalMinutes` minutes
+(`lawbook/config.yaml`, default 5, `0` disables, at most 60).

package/dist/modules/lawbook/assets/skills/cortex/steps/01-load-or-start.md

@@ -22,4 +22,31 @@ Stage → role:
 | archiving | archiver (`sync` + `archive`) |
 | done | stop — report success |
 
+## Status updates
+
+- Read `summary.statusIntervalMinutes` from the `status` result (after
+  `start`, run `status` once). `0` disables unsolicited updates; never parse
+  `lawbook/config.yaml` yourself.
+- Create the timer only when the summary is non-null and the stage is not
+  `done`, the interval is greater than 0, and the host has a session timer
+  (Claude Code `CronCreate`, session-only, at least 1 minute). Then create
+  **one** recurring timer every `statusIntervalMinutes` minutes:
+  - schedule: for 1–59 minutes use `*/N * * * *`; for 60 (the engine caps the
+    interval at 60) use an hourly expression such as `7 * * * *`;
+  - prompt: the timer firing is a fresh prompt, so it must carry its context.
+    Name the change and the rules: run `cortex` action `status` for that
+    change and post the update in the session's language; skip the ping while
+    the stage is `questions`; when the stage is `done` or the run was stopped,
+    delete this timer (`CronDelete`) and post nothing.
+- Remember the id that `CronCreate` returns; it is the run's status timer.
+  Before creating one, check that no status timer exists for this change
+  (your remembered id, or `CronList`), so there is exactly one per run.
+  `CronDelete` always targets that id.
+- Create the timer only inside a Cortex run, never a second one per run, and
+  none when the interval is 0.
+- Prefer background role dispatch: the timer fires only while the session is
+  idle, not during a blocking dispatch.
+- On a host without a session timer, the after-op and before-dispatch updates
+  of the dispatch loop stand in for it.
+
 Next: read `steps/02-dispatch-loop.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/cortex/steps/02-dispatch-loop.md

@@ -30,9 +30,27 @@ For the current Cortex stage (`cortex` action `brief` or `status`):
    - implementing done → `advance` (reviewing, or testing at level 0)
    - reviewing PASS → `advance` + `verdict: PASS`; FAIL → `rework` + `verdict: FAIL`
    - testing PASS → `advance` + `verdict: PASS`; FAIL → `rework` + `verdict: FAIL`
-   - archiving success → `advance` (to done)
+   - archiving success → no Cortex op: the archive itself moves the harness
+     to `done` (the result reports `harnessCompleted`). Confirm with `cortex`
+     action `status` that the stage is `done`; never `advance` an archived
+     change (the engine rejects it).
 4. Max rework is 3; if the engine rejects further rework, **ask the human**.
 5. Coordinator never edits `src/`, never archives, never pushes, never runs
    `laws accept`.
+6. **Status updates.** Unless `summary.statusIntervalMinutes` is 0, post a
+   compact update after every Cortex op and just before every blocking role
+   dispatch, built from the `status` summary fields:
+   - the change, the stage and active role, the elapsed time in the stage;
+   - tasks done/total, rework iteration/max, and the pending verdicts;
+   - in `questions`, that the human owes answers.
+
+   Write it in the session's language (the language of the human's most
+   recent messages); keep stage, role, and tool names, file paths, and change
+   names in English. `summary.line` is English-only; use it as is only in an
+   English session. Skip timer pings while the stage is `questions` (the
+   question round already speaks to the human). When the human asks to stop
+   the updates, delete the timer (`CronDelete` with the id `CronCreate`
+   returned) and post no further unsolicited update for this run. An explicit
+   request for status is always answered.
 
 Next: read `steps/03-complete.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/cortex/steps/03-complete.md

@@ -1,6 +1,8 @@
 # Complete
 
-When Cortex stage is `done` (or the human stops the run), summarize:
+When Cortex stage is `done` (or the human stops the run), first delete the
+status timer if one exists (`CronDelete` with the id `CronCreate` returned,
+or the id `CronList` shows for this change), then summarize:
 
 - Change name and final stage
 - Review/test verdicts and iteration count

package/dist/modules/lawbook/change-tool.js

@@ -6,6 +6,7 @@ import { scaffoldFeature } from "./scaffold-change.js";
 import { buildCoverageReport, loadCoverageConfig, renderCoverageAgent } from "./coverage.js";
 import { buildDriftReport, renderDriftAgent } from "./drift.js";
 import { handleHarness, harnessOps } from "../cortex/harness.js";
+import { fitStatusResult } from "../cortex/status.js";
 export const lawbookChangeActions = [
     "init",
     "list",
@@ -111,7 +112,7 @@ export function handleLawbookChange(args) {
             if (!args.harnessOp) {
                 throw new Error(`lawbook_change: action 'harness' requires 'harnessOp'`);
             }
-            return handleHarness({
+            const result = handleHarness({
                 projectPath: args.projectPath,
                 change: requireField(args, "change"),
                 harnessOp: args.harnessOp,
@@ -120,6 +121,8 @@ export function handleLawbookChange(args) {
                 pauseForQuestions: args.pauseForQuestions,
                 note: args.note ?? args.reason,
             });
+            // MCP-only path: fit `status` to the output budget like the `cortex` tool.
+            return args.harnessOp === "status" && "summary" in result ? fitStatusResult(result) : result;
         }
         default:
             throw new Error(`lawbook_change: unknown action '${String(args.action)}'`);

package/dist/modules/lawbook/engine.js

@@ -6,7 +6,7 @@ import { classifyEars, diagnoseEars, extractNormativeBody, loadEarsConfig, split
 import { artifactNeeds, confirmedLevel, countUncheckedTasks, gatherSignals, hasDisciplineReport, loadCeremonyConfig, proposeLevel, readChangeType, readCeremonyRecord, } from "./levels.js";
 import { inferBugResolution, preventionRequiresDelta, validateBugfixContent } from "./bugfix.js";
 import { isPlaceholderDelta } from "./scaffold-change.js";
-import { harnessArchiveBlockers } from "../cortex/harness.js";
+import { completeHarnessOnArchive, harnessArchiveBlockers } from "../cortex/harness.js";
 // speclaw's own spec-driven workflow engine. Inspired by OpenSpec's model
 // (proposals, delta specs, changes, archive) but implemented from scratch and
 // deliberately simpler: a change's specs/ holds the full intended spec for each
@@ -501,7 +501,17 @@ export function specArchive(projectPath, change, date) {
     fs.mkdirSync(path.dirname(archiveDir), { recursive: true });
     if (fs.existsSync(archiveDir))
         throw new Error(`archive target already exists: ${archiveDir}`);
-    fs.renameSync(changeDir, archiveDir);
+    // Complete the harness before the move (the archived path is not known to
+    // Cortex until then); a failed move puts the old harness bytes back.
+    // Covers: req~harness-archive-completes~1
+    const harness = completeHarnessOnArchive(projectPath, change, "archived by lawbook archive");
+    try {
+        renameDir(changeDir, archiveDir);
+    }
+    catch (err) {
+        harness.restore();
+        throw err;
+    }
     return {
         change,
         promoted,
@@ -509,8 +519,20 @@ export function specArchive(projectPath, change, date) {
         updated,
         archivedTo: path.relative(projectPath, archiveDir),
         seals,
+        harnessCompleted: harness.completed,
     };
 }
+/**
+ * The directory move used by {@link specArchive}; a seam so tests can provoke
+ * a failed move and check the harness is restored. Test-only: product code
+ * must never reassign it.
+ */
+export const archiveFs = {
+    renameSync: (from, to) => fs.renameSync(from, to),
+};
+function renameDir(from, to) {
+    archiveFs.renameSync(from, to);
+}
 /**
  * Seal structural anchors for every capability whose canonical spec was
  * promoted during archive. Missing specs are skipped; zero anchors warn via

package/dist/shared/agents.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { ensureGitignore } from "./install.js";
+import { pkgName, pkgVersion } from "./version.js";
 /** The agents speclaw can configure. Add one here and the CLI picks it up. */
 export const AGENTS = [
     {
@@ -48,7 +49,39 @@ export const AGENTS = [
 export function agentById(id) {
     return AGENTS.find((a) => a.id === id);
 }
-const MCP_ENTRY = { type: "stdio", command: "npx", args: ["-y", "@esneiderbravo/speclaw", "mcp"] };
+/**
+ * The speclaw MCP server entry, pinned to the running package version so the
+ * agent's MCP server matches the CLI that wrote the config (an unpinned entry
+ * runs whatever npx happens to have cached).
+ *
+ * @returns `npx -y <pkg>@<version> mcp` over stdio.
+ */
+// Covers: req~mcp-entry-pinned~1
+export function mcpEntry() {
+    return { type: "stdio", command: "npx", args: ["-y", `${pkgName()}@${pkgVersion()}`, "mcp"] };
+}
+/**
+ * Whether an existing `speclaw` entry is the stock npx launcher speclaw wrote
+ * (pinned or not), as opposed to a custom one the user owns.
+ *
+ * @param entry - The existing `mcpServers.speclaw` value.
+ * @returns True for `{ type?, command: "npx", args: ["-y", <pkg>[@<v>], "mcp"] }`.
+ */
+function isStockMcpEntry(entry) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry))
+        return false;
+    const e = entry;
+    if (Object.keys(e).some((k) => k !== "type" && k !== "command" && k !== "args"))
+        return false;
+    if (e.command !== "npx" || !Array.isArray(e.args) || e.args.length !== 3)
+        return false;
+    const [y, pkg, mcp] = e.args;
+    const name = pkgName();
+    return (y === "-y" &&
+        mcp === "mcp" &&
+        typeof pkg === "string" &&
+        (pkg === name || pkg.startsWith(`${name}@`)));
+}
 /** True when `p` exists as a filesystem entry (including a symlink), without following it. */
 function isSymlink(p) {
     try {
@@ -59,7 +92,12 @@ function isSymlink(p) {
         return false;
     }
 }
-/** Register the speclaw stdio MCP server in an agent's config file, merging into any existing config and skipping if already present. */
+/**
+ * Register the speclaw stdio MCP server in an agent's config file, merging into
+ * any existing config. A missing entry is written pinned; a stock npx entry
+ * (pinned to another version or unpinned) is re-pinned; any other shape is a
+ * custom entry and is kept untouched.
+ */
 function writeMcpConfig(projectPath, mcpFile, report) {
     // The agent MCP config is per-developer wiring — regenerated by `speclaw init`
     // / `agent add`, points at a local runner — not shared source. Keep it out of
@@ -70,14 +108,25 @@ function writeMcpConfig(projectPath, mcpFile, report) {
     if (fs.existsSync(mcpPath))
         config = JSON.parse(fs.readFileSync(mcpPath, "utf8"));
     config.mcpServers = config.mcpServers ?? {};
-    if (config.mcpServers["speclaw"]) {
-        report.skipped.push(`${mcpPath} (speclaw already registered)`);
-        return;
+    const pinned = mcpEntry();
+    const existing = config.mcpServers["speclaw"];
+    let note = "speclaw MCP server";
+    if (existing) {
+        if (!isStockMcpEntry(existing)) {
+            report.skipped.push(`${mcpPath} (custom speclaw entry kept)`);
+            return;
+        }
+        const e = existing;
+        if (e.type === pinned.type && JSON.stringify(e.args) === JSON.stringify(pinned.args)) {
+            report.skipped.push(`${mcpPath} (speclaw already registered)`);
+            return;
+        }
+        note = `speclaw MCP entry pinned to ${pkgVersion()}`;
     }
-    config.mcpServers["speclaw"] = { ...MCP_ENTRY };
+    config.mcpServers["speclaw"] = pinned;
     fs.mkdirSync(path.dirname(mcpPath), { recursive: true });
     fs.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n");
-    report.written.push(`${mcpPath} (speclaw MCP server)`);
+    report.written.push(`${mcpPath} (${note})`);
 }
 /**
  * Configure one agent: create its symlinks into ai-specs and register the MCP server.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esneiderbravo/speclaw",
-  "version": "2.0.7",
+  "version": "2.0.9",
   "publishConfig": {
     "access": "public"
   },