feat(cli): unified loadout-os CLI — wraps kernel/memories/rules + doctor/report (P3)

New @mcptoolshop/loadout-os package (bin loadout-os), the consolidation payoff. Namespaced wrapped surfaces (loadout-os memories|rules <cmd>) + flat kernel verbs (resolve/explain/usage/dead/overlaps/budget/validate) — flat-vs-namespaced resolves the validate name collision. Rituals: doctor (read-only health screen — store validates, index parse, mirror<->live drift hash, malformed layers, 0-core warning, observability-loop-null, hook wired, usage growing) and report (summarizeUsage + findDeadEntries + analyzeBudget + score distribution). hook test drives apps/hook HOME-isolated. One arg parser, structured CliError (code/message/hint), fail-loud on swallowed flag values. refresh + rules-split stubbed (refresh writes the live index -> needs a compensator, handled separately; split is interactive). Wired into root build order (cli builds last, after its 3 deps).

Tests: +51 (cli). Workspace total 347 green. Live read-only checks: doctor ok:true on the real 336-entry index, report parsed 1516 events, hook test left usage.jsonl byte-identical.

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

Author: mcp-tool-shop

package-lock.json

@@ -12,9 +12,9 @@
   ],
   "//buildOrder": "INTENTIONAL: kernel must build before memories and rules — they import the kernel's built dist. Do NOT 'simplify' build/test/verify to `--workspaces` (npm does not guarantee topo order) or the order breaks. The PowerShell hook smoke-test (apps/hook/smoke-test.ps1) is deliberately NOT in verify: it is Windows/rig-specific and would break Linux CI.",
   "scripts": {
-    "build": "npm run build -w packages/kernel && npm run build -w packages/memories && npm run build -w packages/rules",
-    "test": "npm run test -w packages/kernel && npm run test -w packages/memories && npm run test -w packages/rules",
-    "verify": "npm run build && npm run verify -w packages/kernel && npm run verify -w packages/memories && npm run verify -w packages/rules"
+    "build": "npm run build -w packages/kernel && npm run build -w packages/memories && npm run build -w packages/rules && npm run build -w packages/cli",
+    "test": "npm run test -w packages/kernel && npm run test -w packages/memories && npm run test -w packages/rules && npm run test -w packages/cli",
+    "verify": "npm run build && npm run verify -w packages/kernel && npm run verify -w packages/memories && npm run verify -w packages/rules && npm run verify -w packages/cli"
   },
   "engines": {
     "node": ">=20"

package.json

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-tool-shop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/cli/LICENSE

@@ -0,0 +1,87 @@
+# @mcptoolshop/loadout-os
+
+The unified **Knowledge OS** CLI. One `loadout-os` binary that wraps the three
+library packages of this workspace and absorbs the operational rituals that used
+to be a multi-step manual sequence.
+
+It wraps:
+
+- **kernel** — [`@mcptoolshop/ai-loadout`](../kernel) — the knowledge router (resolve / match / budget / usage analysis)
+- **memories** — [`@mcptoolshop/claude-memories`](../memories) — MEMORY.md → dispatch index
+- **rules** — [`@mcptoolshop/claude-rules`](../rules) — CLAUDE.md section analysis + rule-file linting
+- the **runtime hook** — [`apps/hook/loadout-hook.mjs`](../../apps/hook) — the `UserPromptSubmit` pointer-injector
+
+Every wrapped surface calls the library export directly (one process, one arg
+parser, one structured-error shape) — `loadout-os` does not shell out to the
+legacy `ai-loadout` / `claude-memories` / `claude-rules` bins.
+
+## Command tree
+
+### Namespaces (wrapped library surfaces)
+
+```
+loadout-os memories index    <MEMORY.md> [--lazy] [--json]
+loadout-os memories validate <MEMORY.md> [--json]
+loadout-os memories stats    <MEMORY.md> [--json]
+loadout-os memories health   [path] [--json]
+
+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
+```
+
+### Flat verbs (knowledge router / kernel)
+
+```
+loadout-os resolve                  # resolve layered loadouts (global → org → project → session)
+loadout-os explain <entry-id>       # how an entry resolved across layers
+loadout-os usage <jsonl>            # usage summary from the event log
+loadout-os dead <index> <jsonl>     # entries never loaded
+loadout-os overlaps <index>         # keyword routing ambiguities
+loadout-os budget <index> [jsonl]   # token budget breakdown
+loadout-os validate <index>         # validate index STRUCTURE (kernel)
+```
+
+> **Name collision, resolved by namespacing.** The flat `validate <index>` is the
+> kernel's index-structure validator. The store/rules linters are namespaced —
+> `memories validate <MEMORY.md>` and `rules validate` — so all three coexist.
+
+### Rituals
+
+```
+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 (see below)
+```
+
+- **`doctor`** — one read-only screen: store `MEMORY.md` validates, the global
+  index parses + validates, the runtime hook mirror matches the repo source (drift
+  check), no malformed resolver layers, at least one core entry, observability
+  loop wired, hook wired in `settings.json`, and `usage.jsonl` growing. `--json`
+  emits `{ checks: [{ id, status, message, hint }], ok }`. Exit 0 when all checks
+  pass or warn; exit 1 on any fail. **Never writes.**
+- **`report`** — composes usage summary + dead-entry detection + token budget,
+  plus a score distribution when usage events carry a `score`. `--json` for the
+  machine-readable shape. Exit 2 when an input is missing. **Read-only.**
+- **`hook test`** — runs the real `loadout-hook.mjs` against a sample prompt in an
+  isolated HOME so the live `usage.jsonl` is never written.
+- **`refresh`** — *stubbed this wave.* It writes the live global index and needs a
+  named compensator, so it is handled separately; for now run the Index Freshness
+  Ritual (memories index → validate → copy to `~/.ai-loadout/index.json`).
+
+## Build & test
+
+```
+npm run build    # tsc
+npm test         # node --test dist/tests/*.test.js
+npm run verify   # tsc --noEmit && node --test dist/tests/*.test.js
+```
+
+## SDK use
+
+Importing the package is side-effect-free — the dispatcher only runs when the
+file is the process entrypoint. Composable exports: `dispatch`, `runDoctor` /
+`buildReport` / `runHookTest` (and their `print*` renderers + `default*Paths`
+helpers).

packages/cli/README.md

@@ -0,0 +1,42 @@
+{
+  "name": "@mcptoolshop/loadout-os",
+  "version": "0.0.0",
+  "description": "Unified Knowledge OS CLI — wraps ai-loadout (kernel) + claude-memories + claude-rules and absorbs the operational rituals (doctor, report, refresh) into one loadout-os binary.",
+  "license": "MIT",
+  "author": "mcp-tool-shop",
+  "type": "module",
+  "bin": {
+    "loadout-os": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test dist/tests/*.test.js",
+    "verify": "tsc --noEmit && node --test dist/tests/*.test.js"
+  },
+  "dependencies": {
+    "@mcptoolshop/ai-loadout": "^1.4.3",
+    "@mcptoolshop/claude-memories": "^1.0.3",
+    "@mcptoolshop/claude-rules": "^1.2.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "^5.7",
+    "c8": "^11"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}