feat(cli): refresh ritual (compensator) + per-command help + rules split passthrough

Completes the loadout-os Phase-3 surface. refresh folds the Index Freshness Ritual into one command: index store -> ANDON-halt validate -> path-rewrite + copy to dest -> re-validate; NAMED_COMPENSATOR backs up dest to <dest>.bak before the (irreversible, hook-read-every-prompt) write and restores on failure, printing an undo line; --dry-run writes nothing. Per-command --help for every leaf (Hard Gate C; documents the dead <index> <jsonl> ordering + the flat-vs-namespaced validate collision). rules split now wraps via subprocess passthrough (inherited stdio for the readline prompt). Old-bin deprecating shims + the live refresh run remain deferred to Phase 6 (supervised). Tests: cli 51->78; all scratch-isolated, no live ~/.ai-loadout or canonical-store writes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: mcp-tool-shop

packages/cli/src/cli.ts

@@ -32,7 +32,6 @@ import {
   DIM,
   RESET,
   RED,
-  YELLOW,
   log,
   hasFlag,
   flagValue,
@@ -47,7 +46,7 @@ import {
   rulesAnalyze,
   rulesValidate,
   rulesStats,
-  rulesSplitNotice,
+  rulesSplit,
   kernelResolve,
   kernelExplain,
   kernelUsage,
@@ -60,6 +59,8 @@ import {
 import { runDoctor, printDoctor, defaultDoctorPaths } from "./doctor.js";
 import { buildReport, printReport } from "./report.js";
 import { runHookTest, printHookTest, defaultHookPath } from "./hook.js";
+import { dispatchRefresh } from "./refresh.js";
+import { interceptHelp } from "./help.js";
 
 // ── Version ───────────────────────────────────────────────────
 export function getVersion(): string {
@@ -94,7 +95,7 @@ ${BOLD}Rituals:${RESET}
   loadout-os doctor [--json]                       Read-only health screen
   loadout-os report [--index <p>] [--jsonl <p>]    Observability over usage.jsonl
   loadout-os hook test [--prompt "<text>"]         Drive the runtime hook on a sample prompt
-  loadout-os refresh                               (not yet implemented — use the Index Freshness Ritual)
+  loadout-os refresh [--store <d>] [--dest <p>] [--dry-run]   Index Freshness Ritual (index → validate → write global)
 
 ${BOLD}Options:${RESET}
   --json       Machine-readable output (doctor/report/most verbs)
@@ -129,18 +130,23 @@ ${BOLD}loadout-os rules${RESET} — wraps @mcptoolshop/claude-rules
   loadout-os rules analyze <CLAUDE.md> [--rules-dir <dir>] [--json]
   loadout-os rules validate [--rules-dir <dir>] [--lazy] [--repo-root <dir>] [--json]
   loadout-os rules stats <CLAUDE.md> [--rules-dir <dir>] [--json]
-  loadout-os rules split    (interactive — not wrapped; use the claude-rules bin)
+  loadout-os rules split [CLAUDE.md] [--yes] [--dry-run]   (interactive — passes through to claude-rules)
 `;
 }
 
 // ── Namespace dispatchers ─────────────────────────────────────
 function dispatchMemories(args: string[]): void {
-  if (hasFlag(args, "help") || args.length === 0) {
+  // Namespace-level help: `memories --help` or `memories` (no subcommand).
+  // A help flag WITH a subcommand falls through to per-command help below.
+  const firstIsSub = args.length > 0 && !args[0].startsWith("-");
+  if (args.length === 0 || (hasFlag(args, "help") && !firstIsSub)) {
     log(memoriesHelp());
     return;
   }
   const sub = args[0];
   const rest = args.slice(1);
+  // Per-command help: `memories index --help`, etc.
+  if (interceptHelp(`memories ${sub}`, rest)) return;
   switch (sub) {
     case "index":
       return memoriesIndex(rest);
@@ -160,12 +166,20 @@ function dispatchMemories(args: string[]): void {
 }
 
 function dispatchRules(args: string[]): void {
-  if (hasFlag(args, "help") || args.length === 0) {
+  // Namespace-level help: `rules --help` or `rules` (no subcommand). A help flag
+  // WITH a subcommand falls through to per-command help below — except `split`,
+  // whose --help we own here (we never forward --help into the interactive bin).
+  const firstIsSub = args.length > 0 && !args[0].startsWith("-");
+  if (args.length === 0 || (hasFlag(args, "help") && !firstIsSub)) {
     log(rulesHelp());
     return;
   }
   const sub = args[0];
   const rest = args.slice(1);
+  // Per-command help: `rules analyze --help`, `rules split --help`, etc.
+  // For split we intercept --help BEFORE the passthrough so the readline prompt
+  // is never spawned just to ask for usage.
+  if (interceptHelp(`rules ${sub}`, rest)) return;
   switch (sub) {
     case "analyze":
       return rulesAnalyze(rest);
@@ -174,7 +188,7 @@ function dispatchRules(args: string[]): void {
     case "stats":
       return rulesStats(rest);
     case "split":
-      return rulesSplitNotice();
+      return rulesSplit(rest);
     default:
       throw new CliError(
         "UNKNOWN_COMMAND",
@@ -231,6 +245,8 @@ function dispatchReport(args: string[]): void {
 
 function dispatchHook(args: string[]): void {
   const sub = args[0];
+  // `hook test --help` (or `hook --help`) → per-command help for "hook test".
+  if (interceptHelp("hook test", args)) return;
   if (sub !== "test") {
     throw new CliError(
       "UNKNOWN_COMMAND",
@@ -255,14 +271,6 @@ function dispatchHook(args: string[]): void {
   }
 }
 
-function refreshStub(): void {
-  log();
-  log(`  ${YELLOW}!${RESET} ${BOLD}loadout-os refresh${RESET} is not yet implemented.`);
-  log(`  ${DIM}It writes the live global index and needs a named compensator; deferred to a later wave.${RESET}`);
-  log(`  ${DIM}For now, run the Index Freshness Ritual (claude-memories index → validate → copy to ~/.ai-loadout/index.json).${RESET}`);
-  log();
-}
-
 // ── Main dispatch ─────────────────────────────────────────────
 const FLAT_KERNEL = new Set([
   "resolve",
@@ -287,14 +295,29 @@ export function dispatch(args: string[]): void {
     return;
   }
 
-  if (args.length === 0 || (hasFlag(args, "help") && !["memories", "rules"].includes(args[0]))) {
+  // Top-level help: no args, or a help flag with NO command in front of it
+  // (the first token is itself a flag). A help flag AFTER a command routes to
+  // that command's per-command help, handled inside each dispatcher / below.
+  const firstIsCmd = args.length > 0 && !args[0].startsWith("-");
+  if (args.length === 0 || (hasFlag(args, "help") && !firstIsCmd)) {
     log(topLevelHelp());
     return;
   }
 
   const cmd = args[0];
   const rest = args.slice(1);
 
+  // Per-command help for the flat verbs + rituals (namespaces handle their own
+  // inside dispatchMemories/dispatchRules; hook handles "hook test" below).
+  if (
+    cmd !== "memories" &&
+    cmd !== "rules" &&
+    cmd !== "hook" &&
+    interceptHelp(cmd, rest)
+  ) {
+    return;
+  }
+
   switch (cmd) {
     case "memories":
       return dispatchMemories(rest);
@@ -307,7 +330,7 @@ export function dispatch(args: string[]): void {
     case "hook":
       return dispatchHook(rest);
     case "refresh":
-      return refreshStub();
+      return dispatchRefresh(rest);
     case "resolve":
       return kernelResolve(rest);
     case "explain":

packages/cli/src/commands.ts

@@ -13,7 +13,9 @@
  */
 
 import { readFileSync, existsSync, statSync } from "node:fs";
-import { resolve } from "node:path";
+import { resolve, dirname, join } from "node:path";
+import { createRequire } from "node:module";
+import { spawnSync } from "node:child_process";
 
 // memories
 import {
@@ -362,9 +364,72 @@ export function rulesStats(args: string[]): void {
   log("");
 }
 
-export function rulesSplitNotice(): void {
-  warn("`rules split` is interactive and not yet wrapped by loadout-os.");
-  info("Use the `claude-rules split` bin directly for the interactive extraction workflow.");
+/**
+ * Resolve the absolute path to the `claude-rules` bin (its `split` command is
+ * interactive). We resolve via the package's exported package.json — the only
+ * subpath the package's `exports` map exposes — then read `bin.claude-rules`
+ * and join it against the package dir. This works whether the dependency is the
+ * published node_modules copy or a symlinked workspace package; both expose
+ * `./package.json`. Returns null when the package (or its built bin) is absent.
+ */
+export function resolveRulesBin(): string | null {
+  try {
+    const req = createRequire(import.meta.url);
+    const pkgJsonPath = req.resolve("@mcptoolshop/claude-rules/package.json");
+    const pkg = req("@mcptoolshop/claude-rules/package.json") as {
+      bin?: string | Record<string, string>;
+    };
+    const binRel =
+      typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.["claude-rules"];
+    if (!binRel) return null;
+    const binAbs = join(dirname(pkgJsonPath), binRel);
+    return existsSync(binAbs) ? binAbs : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build the argv for the subprocess passthrough: `node <rules-bin> split <args>`.
+ * Pure + exported so a test can assert the argv is constructed correctly
+ * (right bin, the literal "split", forwarded user args) WITHOUT spawning the
+ * interactive readline prompt.
+ */
+export function buildSplitArgv(rulesBin: string, args: string[]): string[] {
+  return [rulesBin, "split", ...args];
+}
+
+/**
+ * `rules split` — subprocess passthrough to the interactive `claude-rules split`.
+ *
+ * split drives a readline Y/n/skip prompt per proposed extraction, so it cannot
+ * be wrapped as a pure library call. We spawn the rules bin with INHERITED
+ * stdio (stdin/stdout/stderr) so the prompt works exactly as it does standalone,
+ * forwarding the user's args/flags verbatim ([CLAUDE.md], --dry-run, --yes, …).
+ * The child's exit code becomes ours.
+ */
+export function rulesSplit(args: string[]): void {
+  const rulesBin = resolveRulesBin();
+  if (!rulesBin) {
+    fail(
+      "RULES_BIN_NOT_FOUND",
+      "Could not resolve the @mcptoolshop/claude-rules bin for the interactive split.",
+      "Ensure @mcptoolshop/claude-rules is installed/built, then retry; or run `claude-rules split` directly.",
+    );
+  }
+  const argv = buildSplitArgv(rulesBin, args);
+  info(`Handing off to the interactive claude-rules split (${argv[0]}) …`);
+  const res = spawnSync(process.execPath, argv, { stdio: "inherit" });
+  if (res.error) {
+    fail(
+      "RULES_SPLIT_SPAWN_FAILED",
+      `Failed to spawn the claude-rules split bin: ${res.error.message}`,
+    );
+  }
+  // Forward the child's exit code as our own (split owns the outcome).
+  if (typeof res.status === "number" && res.status !== 0) {
+    process.exitCode = res.status;
+  }
 }
 
 // ══════════════════════════════════════════════════════════════