@rafinery/cli 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -4,9 +4,26 @@ The machine-readable version of this lives in [`lib/releases.mjs`](lib/releases.
 CLI reads it to tell a client, on `rafa update`, exactly what an upgrade requires (nothing,
 a re-scan, or a `rafa migrate`).
 
+## 0.2.1
+
+**Adopt with:** `npx @rafinery/cli@latest update` (or `/rafa update` in Claude Code) — no re-scan,
+no migration. Recommended: `/rafa leverage` to tune your toolbox.
+
+- **Intelligence where it belongs.** `leverage` and `migrate` are now `/rafa` commands: the CLI
+  *detects* (deterministic), the LLM *acts* — `/rafa leverage` edits your config exactly (merges
+  settings, wires the MCP, scaffolds a skill, on approval); `/rafa migrate` rewrites plans to a new
+  schema preserving meaning, then compile-gates them.
+- **Two-layer update — one job each, no double work.**
+  - `rafa update` (CLI) = the **blueprint side**: pulls the latest blueprint into your repo and runs
+    the blueprint/mechanical migrations. It prints the **release notes** since your version and
+    **exactly what the brain needs** next (computed from the contract/plans schema deltas).
+  - `/rafa update` (Claude Code) = the **brain side**: runs the migrations that need intelligence
+    (re-scan a stale brain, rewrite plans to a new shape). It does **not** re-run the CLI.
+- `/rafa` redirects the terminal-only `compile` instead of erroring on it.
+
 ## 0.2.0
 
-**Adopt with:** `npm i -g @rafinery/cli@latest && rafa update` — no re-scan, no migration.
+**Adopt with:** `npx @rafinery/cli@latest update` — no re-scan, no migration.
 Your brain data is still valid (contract v1, plans v1 unchanged).
 
 - **Non-destructive vendoring.** `init`/`update` never clobber tuned files: owned files

package/blueprint/.claude/commands/rafa.md

@@ -1,5 +1,5 @@
 ---
-description: rafa — init/scan (know + improve) · improve · push. Usage: /rafa <init|scan|improve|push> [--brain-only]
+description: rafa — init · scan · improve · push · leverage · migrate · update. Usage: /rafa <init|scan|improve|push|leverage|migrate|update> [--brain-only]
 ---
 
 You are the **conductor** of the rafa agent loop, running in the **main session**.
@@ -56,8 +56,57 @@ high-leverage P0/P1s — don't nag; the dev triages.**
 `node .rafa/bin/rafa-push.mjs` — commit `.rafa/` and push to `origin` (the brain repo) with the
 dev's own git auth. Use after a scan, or to re-sync a brain that changed.
 
+## `leverage` — tune the dev's toolbox (rafa's 3rd mission; intelligence + exact edits)
+Detection is cheap and deterministic; **acting needs intelligence — that's why this is a
+`/rafa` command, not just the `rafa leverage` CLI.** The CLI *reports*; you *fix*.
+1. **Inspect** the committed toolbox: `.claude/settings.json`, `.mcp.json`, `.claude/skills/`,
+   `.claude/commands/`, and the stack (`package.json` / dirs). (`rafa leverage` gives the fast
+   deterministic signal; here you reason over the real files.)
+2. **Reason** per [`.rafa/capabilities/leverage.md`](../../.rafa/capabilities/leverage.md): what's
+   missing / misconfigured / unused — permission gaps, an MCP the stack needs but isn't wired, a
+   repeatable flow worth capturing as a skill, the best-fit *existing* skill for THIS repo. P1→P3.
+3. **Act — on the dev's approval, edit exactly.** Merge the precise permission entries, write the
+   correct `.mcp.json` server block, scaffold the skill. **Merge, never clobber** the dev's config;
+   show the diff. Propose, don't force. Never open `.env*` or read a secret value (scan's guardrail).
+
+## `migrate` — bring structured files to the current schema (the intelligent half)
+Two channels. **Mechanical** changes (field rename, path move) run deterministically via the
+terminal `rafa migrate`. **Semantic** changes — a plan's *shape* changed and each file must be
+understood to be rewritten correctly — need intelligence, and that's this command.
+1. Read the target schema in [`.rafa/contract.md`](../../.rafa/contract.md) (§6/§7 for plans) and
+   the `from` versions in `rafa.json`.
+2. For each affected file under `.rafa/plans/` (and any other structured dir), **rewrite it to
+   conform** — preserve meaning, remap fields, fill new required fields sensibly.
+3. Run `node .rafa/bin/rafa-compile.mjs` until it **exits 0** (validate-and-correct loop), surface
+   the diff for approval, then offer `rafa push` if this is a connected repo.
+
+## `update` — the BRAIN-side of an upgrade (the CLI already did the blueprint side)
+**Two layers, two actors — don't re-run the CLI here.**
+- The terminal **`npx @rafinery/cli@latest update`** already pulled the latest blueprint and ran
+  the **blueprint-side** (mechanical/structural) migrations. It also *reported* what the brain needs.
+- **`/rafa update` (this command)** does the **brain-side** migrations — the part that needs
+  intelligence — against the blueprint the CLI just installed. It does **not** pull the blueprint
+  or re-run the CLI.
+1. **Find the gap.** The brain/plans conform to a *data* version; the blueprint just moved to a
+   newer one. Compare `.rafa/manifest.json`'s `schemaVersion` (and `rafa.json`'s `contract`/`plans`)
+   to the current `.rafa/contract.md`. That gap is exactly what the CLI update flagged. (If the CLI
+   update hasn't run yet, tell the dev to run `npx @rafinery/cli@latest update` first, then return.)
+2. **Migrate the brain side:**
+   - **Contract bumped → the brain is a stale cache:** re-scan (`## scan`) to regenerate it, or for
+     a targeted change, intelligently rewrite the affected notes to the new schema and re-validate.
+   - **Plans shape changed:** rewrite each plan per `## migrate` (preserve meaning), compile to exit 0.
+3. **Record + summarize.** Run `node .rafa/bin/rafa-compile.mjs` to exit 0, then advance the data
+   version in `rafa.json` (`contract`/`plans` → the versions you migrated to). Summarize what changed;
+   on the dev's approval, `rafa push` if this is a connected repo.
+Never hand-edit around a migration or discard tuned files.
+
 ## (no argument, or unrecognized)
-Print usage and stop: `/rafa init` · `/rafa scan [--brain-only]` · `/rafa improve` · `/rafa push`.
+`/rafa` runs the in-editor passes: `init` · `scan [--brain-only]` · `improve` · `push` ·
+`leverage` · `migrate` · `update`.
+
+`compile` is a **terminal** command on the `rafa` CLI (`@rafinery/cli`) — not a slash command.
+If the dev typed it, don't error out; point them to the shell (`rafa compile`) and stop. For
+anything else unrecognized, print this usage line and stop.
 
 ---
 Token discipline: glob/grep/AST before reading; scoped reads; deterministic extraction

package/blueprint/.rafa/capabilities/leverage.md

@@ -6,8 +6,13 @@ config layer (permissions, skills, MCP servers, hooks, commands) that decides ho
 the AI engineer actually is. It surfaces what's missing, misconfigured, or unused, and points
 at the fix. This is platform DNA: **leverage what's present; never reinvent it.**
 
-Invoke via `rafa leverage` (CLI, reads the repo — no brain required). Advisory only: it reads,
-ranks, and reports; it **changes nothing**.
+**Two layers — detection is deterministic, action needs intelligence:**
+- **`rafa leverage`** (CLI) — the cheap **detector**. Reads the repo, ranks, and *reports*; it
+  **changes nothing**. Good for a notify/CI signal, and as structured input to the LLM.
+- **`/rafa leverage`** (in Claude Code) — the **actor**. rafa reasons over the real config and,
+  on the dev's approval, **applies the fix exactly** — merges the precise permission entries,
+  writes the correct `.mcp.json` block, scaffolds the skill. The CLI can't do this; only the
+  intelligence can edit correctly. The detector finds the gap; the LLM closes it.
 
 ---
 
@@ -21,8 +26,9 @@ ranks, and reports; it **changes nothing**.
    advisor. Few, relevant, dismissible.
 3. **Leverage-ranked** — `P1` security/correctness → `P2` friction/leverage → `P3` nice-to-have.
    Lead with impact × ease. Never dump an unranked wall.
-4. **Advisory, never authoritarian** — the dev owns their setup. Propose + show the fix; never
-   auto-apply. (`rafa init`/`update` apply the *permission* fixes, and only because the dev ran them.)
+4. **Approval-gated, never authoritarian** — the dev owns their setup. `rafa leverage` (CLI) only
+   proposes. `/rafa leverage` *applies*, but **only on the dev's approval and always as a merge** —
+   show the diff, never clobber, propose don't force.
 5. **Tool-agnostic by construction** — the advice engine knows nothing about any specific tool;
    all tool knowledge lives in an **adapter**. This is what makes "leverage what's available"
    true for Codex, Cursor, or any other toolchain, not just Claude Code.

package/lib/leverage.mjs

@@ -31,6 +31,8 @@ export default async function leverage() {
     console.log("");
   }
   console.log(
-    `${tips.length} suggestion(s), most impactful first. These adjust your setup — nothing was changed.`,
+    `${tips.length} suggestion(s), most impactful first. This is the detector — it changed nothing.\n` +
+      "To have rafa apply these exactly (merge settings, wire the MCP, scaffold a skill), run\n" +
+      "  /rafa leverage   in Claude Code — it edits with your approval.",
   );
 }

package/lib/migrate.mjs

@@ -14,9 +14,15 @@ export default async function migrate() {
 
   if (pending.length === 0) {
     console.log(
-      `✓ Nothing to migrate — plans v${from.plans}, contract v${from.contract} ` +
+      `✓ Nothing mechanical to migrate — plans v${from.plans}, contract v${from.contract} ` +
         `already match ${CURRENT.version}.`,
     );
+    if (CURRENT.plans > from.plans || CURRENT.contract > from.contract) {
+      console.log(
+        "  ↳ but the schema version advanced. If a plan/brain SHAPE changed and files need\n" +
+          "    rewriting, that's a semantic migration — run  /rafa migrate  in Claude Code.",
+      );
+    }
     // Still advance the stamp so the recorded CLI version reflects reality.
     stampCurrent(cwd);
     return;

package/lib/migrations/index.mjs

@@ -6,10 +6,18 @@
 // Contract:
 //   id          string                       stable identifier, shown in the log
 //   kind        "plans" | "contract" | "config"
+//   mode        "mechanical" | "assisted"    default "mechanical"
 //   summary     string                       one line: what it changes + why
 //   appliesTo(from, to) => boolean           from = stampedVersions(cwd), to = CURRENT
 //   run(cwd)    => { changed: string[], notes: string[] }   idempotent; report what it touched
 //
+// mode distinguishes the two migration channels:
+//   "mechanical" — a deterministic transform (field rename, path move, add-default). `run` does
+//                  it here in the CLI, no LLM needed.
+//   "assisted"   — the shape changed and each file must be UNDERSTOOD to be rewritten. The CLI
+//                  can't do this correctly; `run` is a no-op that flags it, and `/rafa migrate`
+//                  (the LLM) rewrites the files against the contract. Intelligence lives there.
+//
 // Empty by design until a release actually changes a shape — the SEAM is what matters,
 // so the first breaking change ships its migration here and `rafa migrate` just works.
 // Example (kept as a reference, not registered):

package/lib/releases.mjs

@@ -3,11 +3,14 @@
 // package.json). It declares the contract + plans schema versions that release ships and
 // the strongest action a client must take to adopt it:
 //
-//   requires: "update"   → re-sync the blueprint (`rafa update`); no data change
-//             "migrate"  → run `rafa migrate` (a structured file changed shape)
-//             "rescan"   → the brain contract changed incompatibly; regenerate via `/rafa scan`
+//   requires:   "update" | "migrate" | "rescan"   the strongest structural action
+//               ("update" → just re-sync files; "migrate"/"rescan" are also computed
+//                deterministically from the contract/plans version deltas below).
+//   recommends: string[]   soft follow-ups this release suggests (e.g. ["leverage"]) — shown
+//               by `update` as recommended, not required.
 //
-// `update` reads this to tell the client — transparently — what an upgrade means for them.
+// `update` reads this to tell the client — transparently — what an upgrade means for them:
+// the release notes since their version, and exactly which actions the upgrade needs.
 
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -31,6 +34,18 @@ export const RELEASES = [
       "Non-destructive vendoring (merge settings, never clobber tuned agents); secrets " +
       "guardrail in scan; `rafa leverage` toolbox advisor; version-aware updates + `rafa migrate`.",
   },
+  {
+    version: "0.2.1",
+    contract: 1,
+    plans: 1,
+    requires: "update",
+    recommends: ["leverage"],
+    summary:
+      "leverage & migrate are now intelligent `/rafa` commands — the LLM applies toolbox fixes " +
+      "and rewrites plans exactly. Two-layer update: `rafa update` (CLI) does the blueprint side + " +
+      "blueprint migrations and reports what the brain needs; new `/rafa update` does the brain-side " +
+      "migrations (re-scan / rewrite). `rafa update` now prints release notes + required actions.",
+  },
 ];
 
 // The release this CLI build ships (last entry).

package/lib/stamp.mjs

@@ -46,10 +46,18 @@ export function stampedVersions(cwd) {
   };
 }
 
-// Re-stamp to the versions this CLI build ships (called after init/update/migrate).
+// Re-stamp to the versions this CLI build ships (called after init, or after update when NO
+// brain-side migration remains — i.e. blueprint AND data are current together).
 export function stampCurrent(cwd, extra = {}) {
   return writeStamp(cwd, {
     ...extra,
     rafa: { cli: CLI_VERSION, contract: CURRENT.contract, plans: CURRENT.plans },
   });
 }
+
+// Advance ONLY the blueprint/CLI version — the data (brain/plans) version is left where it is,
+// so `/rafa update` can still see the gap and run the brain-side migrations. Use after
+// `rafa update` when brain-side work remains.
+export function stampCli(cwd) {
+  return writeStamp(cwd, { rafa: { cli: CLI_VERSION } });
+}

package/lib/update.mjs

@@ -9,8 +9,8 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { blueprintSource, copyBlueprint } from "./blueprint.mjs";
 import { reportBlueprint, reportSettings } from "./init.mjs";
-import { CURRENT, releasesAfter } from "./releases.mjs";
-import { stampedVersions, stampCurrent } from "./stamp.mjs";
+import { CURRENT, CLI_VERSION, releasesAfter } from "./releases.mjs";
+import { stampedVersions, stampCurrent, stampCli } from "./stamp.mjs";
 import { pendingMigrations } from "./migrations/index.mjs";
 import { notifyIfBehind } from "./version-check.mjs";
 
@@ -30,39 +30,54 @@ export default async function update() {
   reportBlueprint(copyBlueprint(blueprintSource(), TARGET));
   reportSettings(TARGET);
 
-  // What changed since the client's last version — the transparent part.
+  // ── Blueprint-side migrations: mechanical/deterministic, run here in the CLI. ──
+  // (Anything needing intelligence is left for the brain-side pass — /rafa update.)
+  const pending = pendingMigrations(from, CURRENT);
+  const mechanical = pending.filter((m) => (m.mode ?? "mechanical") !== "assisted");
+  for (const m of mechanical) {
+    try {
+      const r = m.run(TARGET);
+      console.log(`  ✓ migrated ${m.id}: ${r.changed.length} file(s)`);
+    } catch (e) {
+      console.log(`  ! migration ${m.id} failed: ${e instanceof Error ? e.message : e}`);
+    }
+  }
+
+  // ── Release notes: what changed since the client's version. ──
   const news = releasesAfter(from.cli);
   if (news.length) {
-    console.log(`\n  Changes since ${from.cli}:`);
-    for (const r of news) console.log(`    • ${r.version} — ${r.summary}`);
+    console.log(`\n  Release notes  (${from.cli} → ${CLI_VERSION}):`);
+    for (const r of news) console.log(`    ${r.version} — ${r.summary}`);
   }
 
-  // Does the upgrade require action beyond re-syncing files?
-  const rescan = CURRENT.contract > from.contract;
-  const migrate = CURRENT.plans > from.plans || pendingMigrations(from, CURRENT).length > 0;
-
-  console.log("");
-  if (rescan) {
-    console.log(
-      `  ⚠ Brain contract v${from.contract} → v${CURRENT.contract}: your brain is now stale.\n` +
-        "    Run  /rafa scan  to regenerate it, then  rafa push.",
+  // ── Brain-side follow-ups: the CLI can't do these — they need intelligence. Route to /rafa update. ──
+  // The gap is measured against the DATA version (from.contract/plans), which only advances when the
+  // brain/plans are actually regenerated — not by this blueprint sync.
+  const brain = [];
+  if (CURRENT.contract > from.contract) {
+    brain.push(
+      `Re-scan the brain  (contract v${from.contract} → v${CURRENT.contract}; the brain is a stale cache)`,
     );
   }
-  if (migrate) {
-    console.log(
-      `  ⚠ Plan/structure schema changed (plans v${from.plans} → v${CURRENT.plans}).\n` +
-        "    Run  rafa migrate  to bring your files forward.",
-    );
+  if (CURRENT.plans > from.plans || pending.some((m) => m.mode === "assisted")) {
+    brain.push(`Rewrite plans to the new shape  (plans v${from.plans} → v${CURRENT.plans})`);
   }
-  if (!rescan && !migrate) {
-    console.log("  ✓ No re-scan or migration needed — your brain data is still valid.");
+
+  console.log("");
+  if (brain.length) {
+    console.log("  Brain-side follow-ups — run  /rafa update  in Claude Code (needs intelligence):");
+    for (const b of brain) console.log(`    • ${b}`);
+    // Blueprint is current, but the data still lags — keep the gap visible for /rafa update.
+    stampCli(TARGET);
+  } else {
+    console.log("  ✓ No brain migration needed — your brain data is still valid.");
+    stampCurrent(TARGET);
   }
 
-  // Advance the stamp to what we just installed.
-  stampCurrent(TARGET);
+  const recs = new Set(news.flatMap((r) => r.recommends ?? []));
+  if (recs.has("leverage")) console.log("  ↳ recommended: /rafa leverage (tune your toolbox).");
 
   console.log(
-    "\n  Your brain data (.rafa/brain, .rafa/improve) was untouched. " +
-      "Review any `.new` files, then restart Claude Code to reload the agents.",
+    "\n  Owned files you tuned were preserved (review any `.new`). Restart Claude Code to reload the agents.",
   );
 }

package/lib/version-check.mjs

@@ -27,7 +27,7 @@ export async function notifyIfBehind(installed = CLI_VERSION) {
   if (!latest || cmpSemver(latest, installed) <= 0) return latest;
   console.log(
     `\n  ⬆ rafinery ${latest} is available (you're on ${installed}).\n` +
-      `     Update:  npm i -g @rafinery/cli@latest  &&  rafa update\n`,
+      `     Update:  npx @rafinery/cli@latest update   (fetches the latest CLI + vendors it into your repo)\n`,
   );
   return latest;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafinery/cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "rafa — the AI engineer CLI. Vendors the rafa blueprint into your repo (shadcn-style) and runs the deterministic contract gates.",
   "type": "module",
   "bin": {