@esneiderbravo/speclaw 2.0.0 → 2.0.2

package/README.md

@@ -332,14 +332,19 @@ 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 upgrade:
+you when one lands. To bring a project up to date (migrations only — never runs
+`npm install -g`):
 
 ```bash
 speclaw update
 ```
 
-`update` upgrades the global package **and** brings the current project up to date
-without a re-init, splitting files by who owns them:
+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` brings the current project up to date without a re-init, splitting files
+by who owns them:
 
 - **Managed files** (skills/commands/rules under `ai-specs/`) are **refreshed**.
   Pass `--backup` to keep a `<file>.bak` before overwrite.
@@ -348,7 +353,8 @@ without a re-init, splitting files by who owns them:
   prints a prompt for the agent you're using.
 - **`speclaw.lock`** and the CODEOWNERS owners block are refreshed when configured.
 
-- `speclaw update --check` — report whether an update exists, change nothing.
+- `speclaw update --check` — report version status only; do not migrate.
+- `speclaw update --migrate-only` — silent no-op alias of the default (compat).
 - `NO_UPDATE_NOTIFIER=1` — silence the reminder.
 
 <br/>

package/dist/cli/commands/init.js

@@ -45,7 +45,8 @@ 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: run ${ui.code("speclaw update")} first, then ${ui.code("speclaw init")} again.`);
+        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.plain();
     }
     if (interactive) {

package/dist/cli/commands/update.js

@@ -1,4 +1,3 @@
-import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { ui, c } from "../lib/ui.js";
@@ -11,6 +10,17 @@ import { readManifest } from "../../shared/manifest.js";
 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`.
+ *
+ * @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.`);
+}
 // 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-
 // shipped version (e.g. 0.1.11) would never fire for projects already on it.
@@ -196,70 +206,56 @@ const MIGRATIONS = [
             "`esneiderbravo/speclaw@v2`. See `docs/cortex.md`.\n" +
             "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
     },
+    {
+        version: "2.0.1",
+        describe: "speclaw update no longer upgrades the global npm package",
+        agentPrompt: "- `speclaw update` applies **project** migrations only — it does **not** run " +
+            "`npm install -g`. If a newer binary exists on npm it prints an advisory; " +
+            "upgrade the CLI separately (`npm i -g @esneiderbravo/speclaw@latest` or " +
+            "`npx @esneiderbravo/speclaw@latest update`). Prefer `npx @…@latest` when the " +
+            "installed binary is stale so migrations match the latest package.\n" +
+            "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
+    },
 ];
 /**
- * Update speclaw and bring the current project up to date without a full re-init:
- * upgrade the global package, 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: 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).
  *
- * @param flags - `--check` reports without changing anything; `--migrate-only`
- *   skips the global upgrade and only applies project changes (used internally
- *   after the package is upgraded, so migrations run from the new version).
+ * @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.
  */
-export async function runUpdate(flags) {
+export async function runUpdate(flags, hooks = {}) {
     const cwd = process.cwd();
-    const migrateOnly = Boolean(flags["migrate-only"]);
+    // `--migrate-only` is accepted for compat but is a no-op alias of default
+    // (version check + project migrations). It no longer skips the version check.
     const checkOnly = Boolean(flags.check);
     const backup = Boolean(flags.backup);
-    const winShell = process.platform === "win32";
-    if (!migrateOnly) {
-        ui.step("Checking for updates");
-        const { current, latest, updateAvailable } = await checkForUpdates({ force: true });
-        if (!latest) {
-            ui.warn("Could not reach the npm registry — skipping the version check.");
-        }
-        else if (updateAvailable) {
-            ui.info(`${c.muted(current)} ${c.muted("→")} ${c.cyan(latest)}`);
-            if (checkOnly) {
-                ui.info(`Run ${ui.code("speclaw update")} to upgrade and apply what's new.`);
-                return;
-            }
-            ui.step(`Updating ${pkgName()} globally`);
-            const install = spawnSync("npm", ["install", "-g", `${pkgName()}@latest`], {
-                stdio: "inherit",
-                shell: winShell,
-            });
-            if (install.status !== 0) {
-                ui.err("Global update failed. Try again with elevated permissions (e.g. sudo), or check your npm setup.");
-                process.exit(1);
-            }
-            ui.ok(`Updated to ${latest}`);
-            // Re-exec the NEWLY installed binary so migrations run with the new assets
-            // and any new feature steps — not this (now-stale) process. Carry --backup
-            // through so the refresh honors it after the upgrade.
-            const reArgs = [
-                "update",
-                "--migrate-only",
-                ...(backup ? ["--backup"] : []),
-                ...(flags.minimal ? ["--minimal"] : []),
-            ];
-            const re = spawnSync("speclaw", reArgs, {
-                stdio: "inherit",
-                shell: winShell,
-            });
-            if (re.error) {
-                ui.warn(`Upgraded — now run ${ui.code("speclaw update --migrate-only")} to apply project changes.`);
-                return;
-            }
-            process.exit(re.status ?? 0);
-        }
-        else {
-            ui.ok(`Already on the latest version (${current}).`);
-            if (checkOnly)
-                return;
+    const check = hooks.checkForUpdates ?? checkForUpdates;
+    const migrate = hooks.applyProjectMigrations ?? applyProjectMigrations;
+    ui.step("Checking for updates");
+    const { current, latest, updateAvailable } = await check({ force: true });
+    if (!latest) {
+        ui.warn("Could not reach the npm registry — skipping the version check.");
+    }
+    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.`);
+            return;
         }
     }
-    applyProjectMigrations(cwd, backup, flags.minimal ? true : undefined);
+    else {
+        ui.ok(`Already on the latest version (${current}).`);
+        if (checkOnly)
+            return;
+    }
+    if (checkOnly)
+        return;
+    migrate(cwd, backup, flags.minimal ? true : undefined);
 }
 /**
  * Additively apply the current version's content and feature steps to a project.

package/dist/cli/index.js

@@ -12,8 +12,8 @@ Install globally so the command is always available:
 Setup
   init                     Interactive setup: pick agents, scaffold, index, get the prompt
                            (--minimal omits setup/lifecycle MCP tools)
-  update                   Upgrade speclaw and apply only what's new (no re-init)
-                           (--minimal persists minimal exposure; omit to keep prior)
+  update                   Apply project migrations (advisory if a newer binary exists)
+                           (--check reports version only; --minimal persists minimal exposure)
   agent list               Show which agents are configured
   agent add <id>           Configure another agent later (symlinks + MCP)
 

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

@@ -102,15 +102,16 @@ 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 while `speclaw update` remains the
- * command that performs the upgrade.
+ * user open the release with a single click. Project migrations stay
+ * `speclaw update`; the binary is upgraded separately (prefer npx).
  *
  * @param current - The installed version.
  * @param latest - The newest published version.
  * @returns The formatted, styled notice (no leading/trailing blank lines).
  */
 export function upgradeNotice(current, latest) {
-    const latestLink = c.cyan(link(latest, npmPackageUrl(pkgName())));
+    const name = pkgName();
+    const latestLink = c.cyan(link(latest, npmPackageUrl(name)));
     return ("  " +
         c.amber("⬆ speclaw ") +
         c.muted(current + " → ") +
@@ -118,9 +119,11 @@ export function upgradeNotice(current, latest) {
         c.muted(" available") +
         "\n" +
         "  " +
-        c.muted("run ") +
+        c.muted("prefer ") +
+        c.cyan(`npx ${name}@latest update`) +
+        c.muted(" — or ") +
         c.cyan("speclaw update") +
-        c.muted(" — upgrades and applies only what's new"));
+        c.muted(" to migrate this project"));
 }
 /**
  * Print the "update available" notice to stderr when a newer version exists.

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

@@ -13,6 +13,9 @@ Turn the explorer brief + user intent into a reviewable change under
 `lawbook/changes/<name>/` at the confirmed ceremony level. Prefer `draft` /
 `quick` skills.
 
+A complete explorer brief is the code map. Do not re-investigate it. Call
+Compass only for a gap the brief names.
+
 ## Questions
 
 If anything material is ambiguous, **stop**. Return numbered questions to the

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

@@ -3,6 +3,9 @@
 For the current Cortex stage (`cortex` action `brief` or `status`):
 
 1. Dispatch (spawn or adopt) the matching role with a clear handoff brief.
+   When the role is the planner, paste the explorer brief into the prompt
+   unchanged: symbols with files, callers and callees, blast radius, standards
+   already read, recommended approach, open questions, and gaps.
 2. On role completion, call the matching Cortex op:
    - exploring → `advance`
    - planning with questions → `advance` + `pauseForQuestions` + `openQuestions`

package/dist/modules/lawbook/assets/skills/draft/steps/02-understand.md

@@ -1,15 +1,18 @@
 # Understand the request and the code
 
-- **Refresh the index first.** Run `compass_index` before reasoning about the
-  code — it is incremental (unchanged files are skipped by hash), so this is
-  cheap and guarantees your decisions rest on the current graph, not a stale one.
+- When the handoff includes a complete explorer brief (symbols with files,
+  callers and callees, blast radius, standards already read, recommended
+  approach, open questions, and gaps), that brief is the code map. Call
+  `compass_find` or `compass_explore` only for a gap the brief names. Re-read
+  a file under `docs/standards/` only when the brief does not cite it.
+- When the handoff has no complete explorer brief, refresh the index with
+  `compass_index`, then use `compass_explore` and `compass_find` (mode:
+  concept) before grep/read to locate the code and its blast radius. Read the
+  governing standards in `docs/standards/`.
 - Clarify what the user wants (feature / fix / refactor) and confirm scope.
-- Use `compass_explore` and `compass_find` (mode: concept) (speclaw's code index) BEFORE
-  grep/read to locate the real code the change touches and its blast radius.
 - **Propose a ceremony level** with `lawbook_level` (mode `propose`) using the
-  paths/symbols you found; **confirm with the human** (mode `set`) before
-  writing artifacts. For an obvious one-liner, offer `speclaw quick` instead.
-- Read the governing standards in `docs/standards/` (architecture, backend,
-  frontend, testing) so the change complies with the project's law.
+  paths and symbols from the brief or from that locate pass; **confirm with the
+  human** (mode `set`) before writing artifacts. For an obvious one-liner,
+  offer `speclaw quick` instead.
 
 Next: read `steps/03-name-capabilities.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/explore/steps/02-summarize.md

@@ -1,7 +1,15 @@
 # Summarize
 
-Produce a concise summary: the problem as understood, the constraints, the
-recommended approach, and the open questions. When the direction is clear,
-offer to `draft` the change.
+Produce a brief the planner can use as the code map. Include only these fields:
+
+- symbols, each with its file
+- callers and callees
+- blast radius
+- standards in `docs/standards/` already read
+- recommended approach
+- open questions
+- gaps: the phrase "nothing unresolved", or each symbol that is still unresolved
+
+When the direction is clear, offer to `draft` the change.
 
 No further steps remain — explore workflow complete.

package/package.json

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