@esneiderbravo/speclaw 1.0.1 → 2.0.1

package/README.md

@@ -9,16 +9,17 @@
 &nbsp;<a href="https://www.npmjs.com/package/@esneiderbravo/speclaw?activeTab=versions"><img src="https://img.shields.io/badge/provenance-SLSA-0E8E8E?labelColor=0B0F10&style=flat-square" alt="npm provenance"></a>
 &nbsp;<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-0E8E8E?labelColor=0B0F10&style=flat-square" alt="MIT"></a>
 &nbsp;<img src="https://img.shields.io/badge/node-%E2%89%A522.16-0E8E8E?labelColor=0B0F10&style=flat-square" alt="Node >= 22.16">
-&nbsp;<img src="https://img.shields.io/badge/v1.0-0E8E8E?labelColor=0B0F10&style=flat-square" alt="v1.0">
+&nbsp;<img src="https://img.shields.io/badge/v2.0-0E8E8E?labelColor=0B0F10&style=flat-square" alt="v2.0">
 
 <br/><br/>
 
 <p align="center">
 <b>AI agents are brilliant and blind</b> — brilliant at writing code, blind to <i>your</i>
-project's rules. <b>speclaw 1.0</b> hands them what they're missing: the codebase's
-<b>written laws</b> (a constitution built from your real code), a <b>local map</b> to
-navigate it without burning tokens, a <b>disciplined workflow</b> for every change,
-and the <b>gates</b> that make those laws hold in the editor, in CI, and in the PR.
+project's rules. <b>speclaw 2.0</b> hands them what they're missing: the codebase's
+<b>written laws</b> (Foundation), a <b>local map</b> (Compass), a <b>spec-driven lawbook</b>,
+and <b>Cortex</b> — <i>One brain. Many agents.</i> — the multi-agent loop that plans,
+builds, reviews, and archives every non-trivial change. Plus the <b>gates</b> that make
+those laws hold in the editor, in CI, and in the PR.
 <br/>
 One command. No cloud, no LLM, no API keys — <b>everything runs on your machine.</b>
 </p>
@@ -26,7 +27,8 @@ One command. No cloud, no LLM, no API keys — <b>everything runs on your machin
 <img src="https://img.shields.io/badge/100%25_local-0E8E8E?labelColor=0B0F10&style=flat-square" alt="100% local">
 &nbsp;<img src="https://img.shields.io/badge/no_LLM_·_no_cloud-0E8E8E?labelColor=0B0F10&style=flat-square" alt="no LLM">
 &nbsp;<img src="https://img.shields.io/badge/CLI_+_MCP-0E8E8E?labelColor=0B0F10&style=flat-square" alt="CLI + MCP">
-&nbsp;<img src="https://img.shields.io/badge/8_canonical_tools-0E8E8E?labelColor=0B0F10&style=flat-square" alt="8 tools">
+&nbsp;<img src="https://img.shields.io/badge/9_canonical_tools-0E8E8E?labelColor=0B0F10&style=flat-square" alt="9 tools">
+&nbsp;<img src="https://img.shields.io/badge/Cortex-One_brain._Many_agents.-0E8E8E?labelColor=0B0F10&style=flat-square" alt="Cortex">
 &nbsp;<img src="https://img.shields.io/badge/any_agent-0E8E8E?labelColor=0B0F10&style=flat-square" alt="any agent">
 
 </div>
@@ -37,10 +39,10 @@ One command. No cloud, no LLM, no API keys — <b>everything runs on your machin
 > **One command. Detects your agents and wires only those.** Paste
 > `npx @esneiderbravo/speclaw@latest init` — speclaw detects Claude Code, Cursor,
 > Codex, Windsurf, and generic `AGENTS.md` surfaces, scaffolds the constitution +
-> lawbook, indexes your code, and registers the local MCP server — only for the
-> agents you pick. This one-liner is a **stable contract** (see
-> [CONTRIBUTING.md](CONTRIBUTING.md)); do not invent alternate install commands in
-> directories or newsletters.
+> lawbook + Cortex roles, indexes your code, and registers the local MCP server
+> (nine tools including `cortex`) — only for the agents you pick. This one-liner
+> is a **stable contract** (see [CONTRIBUTING.md](CONTRIBUTING.md)); do not invent
+> alternate install commands in directories or newsletters.
 
 <br/>
 
@@ -74,7 +76,7 @@ The `speclaw` command is then available everywhere — run `speclaw index`,
    **`speclaw.lock`** baseline for rule-file integrity.
 3. **Index your code** with a live progress bar and a summary of what it found.
 4. Register the speclaw **MCP server** in each chosen agent's config
-   (eight canonical tools; use `--minimal` to omit setup/lifecycle tools).
+   (nine canonical tools; use `--minimal` to omit setup/lifecycle tools).
 5. Print a prompt to paste into your agent so it fills the constitution with your
    project's real architecture and conventions.
 
@@ -109,15 +111,16 @@ gh attestation verify <tarball> --owner esneiderbravo
 
 <br/>
 
-## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; The suite — five modules
+## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; The suite — six modules
 
 | 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**. No LLM — lives in `.speclaw/` (gitignored). |
-| **Lawbook** | Spec-driven workflow with **adaptive ceremony** (levels 0–3), bugfix changes + `lawbook_investigate`, EARS linting, requirement **coverage**, and sealed **drift** anchors. Loop: `explore → draft → build → sync → archive`. |
+| **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. |
-| **Tools** | Opt-in packs of skills and subagents (currently the dev-agents). |
+| **Tools** | Opt-in pack catalog (empty by default). Role agents (explorer/planner/implementer/reviewer/tester/archiver) ship with Lawbook + Cortex. |
 
 Compass is inspired by [CodeGraph](https://github.com/colbymchenry/codegraph) and the Lawbook module by [OpenSpec](https://github.com/Fission-AI/openspec) — both MIT. speclaw reimplements the ideas as its own code and gives full credit; see [ATTRIBUTION.md](ATTRIBUTION.md).
 
@@ -131,7 +134,7 @@ tokenizer on this corpus — not a BPE dependency):
 
 | | Tokens |
 | :-- | --: |
-| **speclaw budget (always-on)** | **~13.7k** (8 MCP tools · ceiling **14.0k**) |
+| **speclaw budget (always-on)** | **~13.7k** (9 MCP tools · ceiling **14.6k**) |
 | Spec Kit commands alone | ~18.6k ([spec-kit#1401](https://github.com/github/spec-kit/issues/1401)) |
 
 ```bash
@@ -150,28 +153,45 @@ definitions, omitted registration (`--minimal`), and JIT skill steps.
 
 <br/>
 
-## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; The spec-driven workflow (Lawbook)
+## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; Cortex — One brain. Many agents.
 
-Lawbook is speclaw's answer to the biggest risk with AI agents: **code that
-drifts from intent.** The intent is written first, the code is made to match it,
-and the spec is promoted to the project's canonical record — so nothing
-non-trivial lands without a spec change. It's a loop of five steps:
+The biggest risk with AI agents isn't capability — it's **one session doing
+everything**: explore, code, "review," test, and archive with no durable state
+and no role boundaries. **Cortex** is speclaw's answer: a coordinator brain that
+dispatches specialized roles through a durable harness. Lawbook holds the specs;
+Cortex runs the loop. Cheat sheet: [`docs/cortex.md`](docs/cortex.md).
 
-```
-   ┌─────────┐    ┌───────┐    ┌───────┐    ┌──────┐    ┌─────────┐
-   │ explore │ ─▶ │ draft │ ─▶ │ build │ ─▶ │ sync │ ─▶ │ archive │
-   └─────────┘    └───────┘    └───────┘    └──────┘    └─────────┘
-```
+<p align="center">
+  <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/cortex-loop.png" width="800" alt="Cortex — One brain. Many agents.">
+</p>
 
-| Step | What happens |
-| :-- | :-- |
-| **explore** | Think an idea through *before* committing to it — should we do this, and how. Writes nothing. |
-| **draft** | Propose a **ceremony level** (0–3) from graph signals, confirm it, then scaffold only what that level needs under `lawbook/changes/<name>/`. |
-| **build** | Implement the tasks in order, keeping code and spec in agreement, and record test results under `reports/`. |
-| **sync** | Reconcile the delta specs against what was actually built, then promote them into the canonical `lawbook/specs/`. |
-| **archive** | Reconcile, then validate, promote, and move the change to `lawbook/changes/archive/` — **in the same PR**. Gated on tasks, reports, synced specs, and coverage. |
+| Role | Stage | Owns |
+| :-- | :-- | :-- |
+| **explorer** | exploring | Compass-first investigation; writes nothing under `lawbook/` / `src/` |
+| **planner** | planning | Ceremony level + change artifacts; questions always go to the human |
+| **implementer** | implementing | Code + tests; stops at hand-off (no final gates, no archive) |
+| **reviewer** | reviewing | `reports/review.md` PASS/FAIL; no code patches (skipped at level 0) |
+| **tester** | testing | Quality gates, manual verification, discipline reports |
+| **archiver** | archiving | Sync + `lawbook_archive` **in the same PR** |
+
+State lives in `lawbook/changes/<name>/harness.json`. Archive is gated on
+harness verdicts (test PASS; review PASS when level ≥ 1) plus tasks, reports,
+sync, and coverage. Max 3 reworks; then the coordinator asks you.
 
-**Ceremony levels** (confirmed in `change.json`; missing ⇒ level 3):
+<p align="center">
+  <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/terminal-cortex.png" width="800" alt="speclaw cortex brief">
+</p>
+
+**Drive it three ways — same engine:**
+
+- **In your agent** — `/lawbook/cortex` (coordinator) plus per-role skills
+- **MCP** — canonical tool `cortex` (`status` / `start` / `advance` / `rework` / `brief`)
+- **CLI** — `speclaw cortex …`
+
+### Lawbook — the specs Cortex runs
+
+Lawbook is the **artifact layer**: adaptive ceremony (levels 0–3), EARS linting,
+requirement **coverage**, sealed **drift** anchors, bugfix + investigate.
 
 | Level | When | Artifacts |
 | :-- | :-- | :-- |
@@ -181,25 +201,15 @@ non-trivial lands without a spec change. It's a loop of five steps:
 | **3** | Full ceremony | proposal + design + tasks + deltas + `reports/` |
 | **bug** | Regression / RCA | `speclaw lawbook draft --bug` → `bugfix.md` + investigate first |
 
-Plus a **`reports/`** folder — scaffolded at draft, filled at build with one report
-per discipline (`backend.md`, `frontend.md`, `api.md`, …). `lawbook_archive`
-refuses to archive without it.
-
 > [!NOTE]
 > **Delta specs are normative and testable.** Requirements use `SHALL`/`MUST`
 > under `### Requirement:` headers (EARS-friendly), each with `#### Scenario:`
 > blocks. `lawbook_validate` checks structure; `speclaw coverage` tracks
 > `req~…~N` → impl/test via `// Covers:` comments.
 
-**Three ways to drive it — same engine, no external CLI:**
-
-- **In your agent** — `/lawbook:explore`, `/lawbook:draft`, `/lawbook:build`, `/lawbook:sync`, `/lawbook:archive` (and `/lawbook:quick`, investigate).
-- **MCP tools** — eight canonical: `compass_explore`, `compass_find`, `compass_diff_context`, `compass_index`, `lawbook_change`, `lawbook_investigate`, `speclaw_setup`, `speclaw_check`.
-- **CLI** — `speclaw lawbook …`, `speclaw quick`, `speclaw coverage`, `speclaw drift`.
-
-The workspace is committed under `lawbook/`: `specs/`, `changes/`,
-`changes/archive/`, `anchors/` (drift photographs), and `config.yaml`
-(mandatory tasks, ceremony cuts, `team.owners`, EARS knobs).
+The workspace is committed under `lawbook/`: `specs/`, `changes/` (with
+`harness.json` per active change), `changes/archive/`, `anchors/`, and
+`config.yaml`.
 
 <br/>
 
@@ -208,12 +218,12 @@ The workspace is committed under `lawbook/`: `specs/`, `changes/`,
 speclaw meets you where you are. Everything works through the **CLI** — so no one
 is blocked by MCP setup — and the same capabilities are exposed as **MCP tools**
 for a smoother, integrated experience once configured. An agent without MCP can
-still use Compass and the lawbook engine by calling the CLI from its shell.
+still use Compass, Cortex, and the lawbook engine by calling the CLI from its shell.
 
 <p align="center"><b>CLI</b> — the installer &amp; operator, runs anywhere <code>node</code> does</p>
 <p align="center"><img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/terminal-cli.png" width="800" alt="speclaw CLI commands"></p>
 
-<p align="center"><b>MCP</b> — eight canonical tools, auto-registered by <code>init</code></p>
+<p align="center"><b>MCP</b> — nine canonical tools (incl. <code>cortex</code>), auto-registered by <code>init</code></p>
 <p align="center"><img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/terminal-mcp.png" width="800" alt="speclaw MCP tools"></p>
 
 <br/>
@@ -225,10 +235,10 @@ still use Compass and the lawbook engine by calling the CLI from its shell.
 </p>
 
 **Committed vs. local.** Your **personalized source** is committed — `LAWS.md`,
-`CLAUDE.md`, `AGENTS.md`, `docs/standards/*`, `docs/compass.md`, the `lawbook/`
-workspace, and **`speclaw.lock`** (rule digests at the repo root). speclaw's
-**regenerable workflow content is local, not committed**: only `ai-specs/`
-(skills, commands, rules, agent packs, and its `.speclaw.json` manifest) is
+`CLAUDE.md`, `AGENTS.md`, `docs/standards/*`, `docs/compass.md`, `docs/cortex.md`,
+the `lawbook/` workspace, and **`speclaw.lock`** (rule digests at the repo root).
+speclaw's **regenerable workflow content is local, not committed**: only `ai-specs/`
+(skills, commands, rules, role agents, and its `.speclaw.json` manifest) is
 gitignored, because `init`/`update` reconstruct it from the package. So **after
 cloning a speclaw project, run `speclaw init` (or `speclaw update`)** to
 regenerate `ai-specs/` locally. Optional **`team.owners`** in
@@ -252,7 +262,8 @@ follows `apps/*/src`, `packages/*/src`, or `src/` rather than copying
 > of AI coding agents isn't lack of capability — it's working without the project's
 > tacit knowledge: the rules the team actually lives by. speclaw makes that
 > knowledge explicit, executable, and binding, and gives agents a local map
-> (Compass) and a disciplined workflow (Lawbook) to act on it — without burning tokens.
+> (Compass), a lawbook of specs, and **Cortex** to run the multi-agent loop —
+> without burning tokens.
 
 This is why "enforced" is literal, not a metaphor. Anthropic's own guidance puts
 it plainly:
@@ -308,7 +319,7 @@ of the lock in this release. Regenerable IDE mirrors (e.g. `.cursor/rules` →
 On GitHub:
 
 ```yaml
-- uses: esneiderbravo/speclaw@v1
+- uses: esneiderbravo/speclaw@v2
 ```
 
 `init` / `update` write `.github/workflows/speclaw.yml` only when that path is
@@ -321,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.
@@ -337,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/>
@@ -357,6 +374,6 @@ without a re-init, splitting files by who owns them:
 [CodeGraph](https://github.com/colbymchenry/codegraph) &nbsp;·&nbsp;
 see [ATTRIBUTION.md](ATTRIBUTION.md)
 
-<i>speclaw 1.0 · where specs become law</i>
+<i>speclaw 2.0 · where specs become law</i>
 
 </div>

package/dist/cli/commands/cortex.js

@@ -0,0 +1,49 @@
+import { handleHarness, readHarness } from "../../modules/cortex/harness.js";
+import { briefForStage } from "../../modules/cortex/brief.js";
+import { list } from "../lib/args.js";
+import { ui } from "../lib/ui.js";
+const OPS = ["status", "start", "advance", "rework", "brief"];
+/**
+ * Run `speclaw cortex <op> --change <name> […]`.
+ *
+ * @param flags - Parsed flags; `_[0]` is the op.
+ */
+export async function runCortex(flags) {
+    const cwd = process.cwd();
+    const opRaw = flags._[0];
+    const op = opRaw;
+    if (!OPS.includes(op)) {
+        ui.err("Usage: speclaw cortex <status|start|advance|rework|brief> --change <name> [--verdict PASS|FAIL] [--question …] [--pause-questions] [--note …] [--json]");
+        process.exit(1);
+    }
+    const changeName = typeof flags.change === "string" ? flags.change : flags._[1];
+    if (!changeName) {
+        ui.err("Usage: speclaw cortex <op> --change <name>");
+        process.exit(1);
+    }
+    try {
+        if (op === "brief") {
+            const state = readHarness(cwd, changeName);
+            const brief = briefForStage(state?.stage ?? null);
+            const result = { state, ...brief };
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        const verdictRaw = typeof flags.verdict === "string" ? flags.verdict.toUpperCase() : undefined;
+        const verdict = verdictRaw === "PASS" || verdictRaw === "FAIL" ? verdictRaw : undefined;
+        const result = handleHarness({
+            projectPath: cwd,
+            change: changeName,
+            harnessOp: op,
+            verdict: verdict ?? null,
+            openQuestions: list(flags.question),
+            pauseForQuestions: Boolean(flags["pause-questions"]),
+            note: typeof flags.note === "string" ? flags.note : undefined,
+        });
+        console.log(JSON.stringify(result, null, 2));
+    }
+    catch (err) {
+        ui.err(err.message);
+        process.exit(1);
+    }
+}

package/dist/cli/commands/init.js

@@ -10,9 +10,7 @@ import { list } from "../lib/args.js";
 import { ui, c, banner, renderProgress, clearProgress } from "../lib/ui.js";
 import { checkForUpdates } from "../lib/update-check.js";
 import { reportTrackedLocalContent } from "../lib/untrack.js";
-const PACK_LABELS = {
-    agents: "dev-agents (backend · frontend · product)",
-};
+const PACK_LABELS = {};
 /** Best-effort project name: the package.json name (unscoped) or the directory name. */
 export function detectProjectName(cwd) {
     try {
@@ -26,7 +24,8 @@ export function detectProjectName(cwd) {
     return path.basename(cwd);
 }
 /**
- * Interactive setup: pick agents and packs, scaffold, index, and print the handoff prompt.
+ * Interactive setup: pick agents (and packs when any exist), scaffold, index,
+ * and print the handoff prompt.
  *
  * @param flags - Parsed flags; runs interactively on a TTY unless `--agents`, `--yes`, or
  *   `-y` is set. Honors `--project-name`, `--packs`, and `--no-index`.
@@ -37,6 +36,8 @@ export async function runInit(flags) {
     const interactive = Boolean(process.stdin.isTTY) && !flags.agents && !flags.yes && !flags.y;
     let agents;
     let packs;
+    const availablePacks = loadPacks();
+    const packIds = Object.keys(availablePacks);
     banner();
     // Scaffolding with a stale version writes yesterday's foundation, so recommend
     // upgrading first — prominently, before any prompts, so there's time to cancel.
@@ -44,34 +45,39 @@ 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) {
-        const answers = await clack.group({
+        // Covers: req~remove-agents-pack~1
+        const prompts = {
             agents: () => clack.multiselect({
                 message: "Which agents do you use? (space to select)",
                 options: AGENTS.map((a) => ({ value: a.id, label: a.label })),
                 initialValues: ["claude"],
                 required: true,
             }),
-            packs: () => clack.multiselect({
+        };
+        if (packIds.length > 0) {
+            prompts.packs = () => clack.multiselect({
                 message: "Which tool packs to install?",
-                options: Object.entries(loadPacks()).map(([id, def]) => ({
+                options: packIds.map((id) => ({
                     value: id,
                     label: id,
-                    hint: def.description.slice(0, 50),
+                    hint: availablePacks[id].description.slice(0, 50),
                 })),
-                initialValues: ["agents"],
+                initialValues: [],
                 required: false,
-            }),
-        }, { onCancel: () => process.exit(1) });
+            });
+        }
+        const answers = await clack.group(prompts, { onCancel: () => process.exit(1) });
         agents = answers.agents;
-        packs = answers.packs;
+        packs = answers.packs ?? [];
     }
     else {
         agents = list(flags.agents).length ? list(flags.agents) : ["claude"];
-        packs = list(flags.packs).length ? list(flags.packs) : ["agents"];
+        packs = list(flags.packs);
     }
     const unknownAgents = agents.filter((a) => !agentById(a));
     if (unknownAgents.length) {
@@ -91,7 +97,8 @@ export async function runInit(flags) {
         minimal: Boolean(flags.minimal),
     });
     ui.ok(`Foundation ${c.muted("— LAWS.md + 8 standards + CLAUDE.md/AGENTS.md")}`);
-    ui.ok(`Lawbook workflow ${c.muted("— draft · build · sync · archive · explore")}`);
+    ui.ok(`Lawbook workflow ${c.muted("— cortex · explore · draft · build · sync · archive")}`);
+    ui.ok(`Role agents ${c.muted("— explorer · planner · implementer · reviewer · tester · archiver")}`);
     for (const p of packs)
         ui.ok(`${PACK_LABELS[p] ?? p + " pack"}`);
     specInit(cwd);
@@ -132,7 +139,7 @@ export async function runInit(flags) {
         "commit messages, branch names, PR and ticket language — don't assume. " +
         "Start with init_project."));
     ui.plain();
-    ui.info(`The dev-agents read those standards for your stack — filling them well makes them stack-aware.`);
+    ui.info(`Non-trivial work runs through Cortex — use ${ui.code("/lawbook/cortex")} (or the cortex skill).`);
     ui.plain();
     ui.info(`Add an agent:   ${ui.code("speclaw agent add cursor")}`);
     ui.info(`Refresh index:  ${ui.code("speclaw index")}`);

package/dist/cli/commands/lawbook.js

@@ -2,6 +2,7 @@ import { specInit, specValidate, specSync, specArchive, specList, } from "../../
 import { handleLevel } from "../../modules/lawbook/quick.js";
 import { scaffoldBugfix } from "../../modules/lawbook/bugfix.js";
 import { investigate, formatInvestigateResult } from "../../modules/lawbook/investigate.js";
+import { handleHarness } from "../../modules/cortex/harness.js";
 import { list } from "../lib/args.js";
 import { ui } from "../lib/ui.js";
 function today() {
@@ -144,8 +145,40 @@ export async function runSpec(flags) {
                 }
                 return;
             }
+            case "harness": {
+                const opRaw = change;
+                const op = opRaw;
+                if (!["status", "start", "advance", "rework"].includes(op)) {
+                    ui.err("Usage: speclaw lawbook harness <status|start|advance|rework> --change <name> [--verdict PASS|FAIL] [--question …] [--pause-questions] [--note …] [--json]");
+                    process.exit(1);
+                }
+                const changeName = typeof flags.change === "string" ? flags.change : flags._[2];
+                if (!changeName) {
+                    ui.err("Usage: speclaw lawbook harness <op> --change <name>");
+                    process.exit(1);
+                }
+                const verdictRaw = typeof flags.verdict === "string" ? flags.verdict.toUpperCase() : undefined;
+                const verdict = verdictRaw === "PASS" || verdictRaw === "FAIL"
+                    ? verdictRaw
+                    : undefined;
+                const result = handleHarness({
+                    projectPath: cwd,
+                    change: changeName,
+                    harnessOp: op,
+                    verdict: verdict ?? null,
+                    openQuestions: list(flags.question),
+                    pauseForQuestions: Boolean(flags["pause-questions"]),
+                    note: typeof flags.note === "string" ? flags.note : undefined,
+                });
+                if (flags.json) {
+                    console.log(JSON.stringify(result, null, 2));
+                    return;
+                }
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
             default:
-                ui.err("Usage: speclaw lawbook <init|list|validate|sync|archive|level|draft|investigate> [change]");
+                ui.err("Usage: speclaw lawbook <init|list|validate|sync|archive|level|draft|investigate|harness> [change]");
                 process.exit(1);
         }
     }

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.
@@ -168,8 +178,9 @@ const MIGRATIONS = [
         version: "1.0.0",
         describe: "speclaw 1.0 — official release (enforcement + graph + lawbook + owners)",
         agentPrompt: "- speclaw **1.0** is the official release: Foundation (hooks + `speclaw.lock` integrity), " +
-            "Compass (schema 10, eight canonical MCP tools), Lawbook (ceremony 0–3, coverage, drift, " +
-            "bugfix), and Team (`team.owners` → `speclaw owners --write`). Install remains " +
+            "Compass (schema 10), Lawbook (ceremony 0–3, coverage, drift, bugfix), " +
+            "Cortex (multi-agent loop; nine canonical MCP tools including `cortex`), " +
+            "and Team (`team.owners` → `speclaw owners --write`). Install remains " +
             "`npx @esneiderbravo/speclaw@latest init`. CI consumers use `esneiderbravo/speclaw@v1`.\n" +
             "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
     },
@@ -184,70 +195,67 @@ const MIGRATIONS = [
             "`speclaw laws compile` if agent rule files look stale, then `speclaw index`.\n" +
             "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
     },
+    {
+        version: "2.0.0",
+        describe: "speclaw 2.0 — Cortex (One brain. Many agents.) + nine MCP tools",
+        agentPrompt: "- speclaw **2.0** ships **Cortex**: durable multi-agent loop (`harness.json`), " +
+            "MCP tool `cortex` (`status`/`start`/`advance`/`rework`/`brief`), CLI " +
+            "`speclaw cortex`, skill `/lawbook/cortex`, and role agents " +
+            "(explorer → planner → implementer → reviewer → tester → archiver). " +
+            "Canonical MCP surface is **nine** tools. CI consumers: " +
+            "`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.