fix(health-c): humanize CLI errors + harden trust boundaries (+41 tests)

Stage-C humanization across kernel/memories/rules. Trust-boundary: shape-guard parsed index.json so a valid-but-wrong file emits a structured INVALID_INDEX/READ_FAILED instead of a raw TypeError/stack (KER-B1, RUL-B1, MEM-B01); memories rejects a directory target (NOT_A_FILE) instead of EISDIR (MEM-B02). Observability: kernel distinguishes malformed-vs-missing layers in resolve + counts skipped usage lines (KER-B2/B5); memories moves unresolved-ref reporting off console.warn into the CLI render path (MEM-B03). Shared flagValue bug fixed in all three (a value-flag no longer swallows the next --flag) (KER-B6/MEM-B05/RUL-B6). rules: --lazy now plumbed through validate/stats (RUL-B2) and drift issues carry fix hints + line numbers (RUL-B4). Feature-sized items (doctor cmd, per-command help, rules exports map, split atomicity) deferred to the Feature pass.

Tests: 228 -> 269 (kernel 97->117, memories 42->54, rules 89->98). Exclusive ownership; build gate green.

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

Author: mcp-tool-shop

packages/kernel/src/cli-helpers.ts

@@ -0,0 +1,101 @@
+/**
+ * Pure, side-effect-free helpers for the ai-loadout CLI.
+ *
+ * These live in their own module (separate from cli.ts) so they can be unit
+ * tested without executing the CLI's top-level argv parsing / process.exit.
+ * Nothing here writes to stdout or exits the process — callers decide how to
+ * report. The CLI wires these into its structured `fail(code, message, hint)`.
+ */
+
+import type { LoadoutIndex } from "./types.js";
+
+// ── Index shape validation (KER-B1) ──────────────────────────────
+//
+// `JSON.parse` happily returns null / numbers / arrays / wrong-shaped objects.
+// Before we hand a parsed value to validate/budget/dead/overlaps/merge — all of
+// which dereference `.entries` — confirm it actually looks like a loadout index.
+// This turns a downstream raw `TypeError: Cannot read properties of … (reading
+// 'entries')` into an actionable, structured failure at the trust boundary.
+
+/**
+ * Structural type-guard for a parsed loadout index.
+ *
+ * Minimal by design: we only assert what every consumer relies on — a plain
+ * object with an `entries` array. Per-entry validation is the job of
+ * `validateIndex`; this guard just stops the obviously-wrong file (null, a
+ * number, an array, `{}`, a missing `entries`) before it crashes elsewhere.
+ */
+export function isLoadoutIndex(value: unknown): value is LoadoutIndex {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Array.isArray((value as { entries?: unknown }).entries)
+  );
+}
+
+/**
+ * Human-readable description of why a parsed value is not a loadout index.
+ *
+ * Returned so the CLI can put a precise reason in the failure hint instead of a
+ * generic "invalid". `null` means the value *is* a valid index (no problem).
+ */
+export function describeIndexShapeProblem(value: unknown): string | null {
+  if (value === null) return "got null";
+  if (Array.isArray(value)) return "got a JSON array, expected an object";
+  const t = typeof value;
+  if (t !== "object") return `got a JSON ${t}, expected an object`;
+  if (!Array.isArray((value as { entries?: unknown }).entries)) {
+    return "object is missing an 'entries' array";
+  }
+  return null;
+}
+
+// ── Flag value parsing (KER-B6) ──────────────────────────────────
+//
+// `--project --json` must NOT let `--project` swallow `--json` as its value.
+// A value that itself starts with `--` is treated as absent: the user almost
+// certainly forgot the value, and silently consuming the next flag produces
+// confusing, hard-to-debug behavior downstream.
+
+/**
+ * Read the value of `--<flag>` from args, supporting both `--flag value` and
+ * `--flag=value` forms.
+ *
+ * Guard: if the token following `--flag` itself starts with `--`, the value is
+ * treated as ABSENT (returns `undefined`) rather than swallowing the next flag.
+ * The `--flag=` form is honored verbatim, even if the value starts with `--`,
+ * because there the user was explicit about the pairing.
+ */
+export function getFlagValue(args: string[], flag: string): string | undefined {
+  const prefix = `--${flag}=`;
+  for (const a of args) {
+    if (a.startsWith(prefix)) return a.slice(prefix.length);
+  }
+  const idx = args.indexOf(`--${flag}`);
+  if (idx !== -1 && idx + 1 < args.length && !args[idx + 1].startsWith("--")) {
+    return args[idx + 1];
+  }
+  return undefined;
+}
+
+/**
+ * Classify why `getFlagValue` returned undefined for a bare `--flag`.
+ *
+ * Lets the CLI tailor its error message:
+ *   - "missing"  → `--flag` was the last token, or absent entirely.
+ *   - "swallowed"→ `--flag` was immediately followed by another `--flag`,
+ *                  so we refused to consume it as a value.
+ *   - null       → a value WAS present (no problem).
+ */
+export function diagnoseFlagValue(
+  args: string[],
+  flag: string
+): "missing" | "swallowed" | null {
+  if (getFlagValue(args, flag) !== undefined) return null;
+  const idx = args.indexOf(`--${flag}`);
+  if (idx === -1) return "missing";
+  const next = args[idx + 1];
+  if (next !== undefined && next.startsWith("--")) return "swallowed";
+  return "missing";
+}

packages/kernel/src/cli.ts

@@ -14,11 +14,17 @@ import { readFileSync, existsSync } from "node:fs";
 import { resolve, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { LoadoutIndex } from "./types.js";
-import { readUsage, summarizeUsage, summaryToJSON } from "./usage.js";
+import { readUsage, readUsageWithStats, summarizeUsage, summaryToJSON } from "./usage.js";
 import { findDeadEntries, findKeywordOverlaps, analyzeBudget } from "./analysis.js";
 import { resolveLoadout, explainEntry } from "./resolve.js";
 import type { ResolveOptions } from "./resolve.js";
 import { validateIndex } from "./validate.js";
+import {
+  isLoadoutIndex,
+  describeIndexShapeProblem,
+  getFlagValue,
+  diagnoseFlagValue,
+} from "./cli-helpers.js";
 
 // ── Colors ────────────────────────────────────────────────────
 const BOLD = "\x1b[1m";
@@ -49,36 +55,60 @@ function positionalArgs(args: string[]): string[] {
   return args.filter((a) => !a.startsWith("--"));
 }
 
-function getFlagValue(args: string[], flag: string): string | undefined {
-  const prefix = `--${flag}=`;
-  for (const a of args) {
-    if (a.startsWith(prefix)) return a.slice(prefix.length);
-  }
+// getFlagValue / diagnoseFlagValue live in cli-helpers.ts (testable, pure).
+
+/**
+ * Read a path-valued flag, failing with a clear, actionable error when the
+ * value was swallowed by a following flag (e.g. `--project --json`). A truly
+ * absent flag returns undefined (these flags all have sensible defaults).
+ */
+function getPathFlag(args: string[], flag: string): string | undefined {
+  if (diagnoseFlagValue(args, flag) === "swallowed") {
+    fail(
+      "MISSING_FLAG_VALUE",
+      `--${flag} was given without a value (the next token "--${nextToken(args, flag)}" is a flag, not a value).`,
+      `Provide a value, e.g. '--${flag} <path>' or '--${flag}=<path>'.`
+    );
+  }
+  return getFlagValue(args, flag);
+}
+
+function nextToken(args: string[], flag: string): string {
   const idx = args.indexOf(`--${flag}`);
-  if (idx !== -1 && idx + 1 < args.length && !args[idx + 1].startsWith("--")) {
-    return args[idx + 1];
-  }
-  return undefined;
+  return idx !== -1 ? (args[idx + 1] ?? "").replace(/^--/, "") : "";
 }
 
 function getResolveOpts(args: string[]): ResolveOptions {
   return {
-    projectRoot: getFlagValue(args, "project"),
-    globalDir: getFlagValue(args, "global"),
-    orgPath: getFlagValue(args, "org"),
-    sessionPath: getFlagValue(args, "session"),
+    projectRoot: getPathFlag(args, "project"),
+    globalDir: getPathFlag(args, "global"),
+    orgPath: getPathFlag(args, "org"),
+    sessionPath: getPathFlag(args, "session"),
   };
 }
 
 function loadIndex(path: string): LoadoutIndex {
   if (!existsSync(path)) {
     fail("FILE_NOT_FOUND", `Index not found: ${path}`);
   }
+  let parsed: unknown;
   try {
-    return JSON.parse(readFileSync(path, "utf-8")) as LoadoutIndex;
+    parsed = JSON.parse(readFileSync(path, "utf-8"));
   } catch (e) {
     fail("PARSE_ERROR", `Failed to parse index: ${path}`, (e as Error).message);
   }
+  // Trust boundary: valid JSON is not necessarily a valid index. Assert the
+  // shape here so a wrong-but-parseable file fails with a clear, actionable
+  // message instead of a raw TypeError later in validate/budget/dead/overlaps.
+  if (!isLoadoutIndex(parsed)) {
+    const problem = describeIndexShapeProblem(parsed);
+    fail(
+      "INVALID_INDEX",
+      `File is valid JSON but not a loadout index: ${path}`,
+      `Expected an object with an 'entries' array${problem ? ` (${problem})` : ""}. Run 'ai-loadout validate' for details.`
+    );
+  }
+  return parsed;
 }
 
 function getVersion(): string {
@@ -135,9 +165,15 @@ function cmdUsage(args: string[]) {
   }
 
   const jsonlPath = resolve(positional[0]);
-  const events = readUsage(jsonlPath);
+  const { events, skipped } = readUsageWithStats(jsonlPath);
   const json = hasFlag(args, "json");
 
+  // Surface dropped lines so a corrupt log doesn't silently undercount.
+  // (Stay quiet in --json mode to keep stdout machine-parseable.)
+  if (skipped > 0 && !json) {
+    warn(`Skipped ${skipped} malformed line(s) in ${jsonlPath}`);
+  }
+
   if (events.length === 0) {
     if (json) { log("[]"); return; }
     info("No usage events found");
@@ -346,14 +382,25 @@ function cmdResolve(args: string[]) {
   for (const s of result.searched) {
     if (s.found) {
       ok(`${s.name.padEnd(10)} ${DIM}${s.path}${RESET}`);
+    } else if (s.malformed) {
+      // Present but unparseable — call it out distinctly from a missing file
+      // so the user knows there's a corrupt file to fix, not one to create.
+      warn(`${s.name.padEnd(10)} ${DIM}${s.path}${RESET} ${YELLOW}(malformed JSON — skipped)${RESET}`);
     } else {
       log(`  ${DIM}—${RESET} ${s.name.padEnd(10)} ${DIM}${s.path} (not found)${RESET}`);
     }
   }
 
   if (result.layers.length === 0) {
-    log(`\n  ${YELLOW}No loadout indexes found.${RESET}`);
-    log(`  ${DIM}Create .claude/loadout/index.json or ~/.ai-loadout/index.json${RESET}\n`);
+    // Echo the ACTUAL searched paths rather than a hardcoded default list, so
+    // the message reflects any --global/--org/--project/--session overrides and
+    // tells the user exactly where to put a file.
+    const searchedPaths = result.searched.map((s) => s.path);
+    log(`\n  ${YELLOW}No loadout indexes found in any of:${RESET}`);
+    for (const p of searchedPaths) {
+      log(`  ${DIM}  • ${p}${RESET}`);
+    }
+    log(`  ${DIM}Create one of the above to get started.${RESET}\n`);
     return;
   }
 

packages/kernel/src/index.ts

@@ -33,7 +33,7 @@ export { validateIndex } from "./validate.js";
 export { mergeIndexes } from "./merge.js";
 
 // ── Usage ─────────────────────────────────────────────────────
-export { recordUsage, readUsage, summarizeUsage, summaryToJSON } from "./usage.js";
+export { recordUsage, readUsage, readUsageWithStats, summarizeUsage, summaryToJSON } from "./usage.js";
 export type { UsageSummary, UsageSummaryJSON } from "./usage.js";
 
 // ── Analysis ──────────────────────────────────────────────────

packages/kernel/src/resolve.ts

@@ -32,6 +32,15 @@ export interface SearchedLayer {
   name: string;
   path: string;
   found: boolean;
+  /**
+   * The file exists on disk but its JSON could not be parsed. Distinct from
+   * `found: false` (file absent) so callers don't report a present-but-corrupt
+   * layer as "not found" — that's misleading. Additive/optional: undefined
+   * means "not malformed" (either absent, or found and parsed fine).
+   */
+  malformed?: boolean;
+  /** Parse error message when `malformed` is true (for diagnostics). */
+  error?: string;
 }
 
 /** Result of resolving the full layer stack. */
@@ -119,9 +128,15 @@ export function discoverLayers(opts?: ResolveOptions): {
         const raw = readFileSync(path, "utf-8");
         const index = JSON.parse(raw) as LoadoutIndex;
         layers.push({ name, path, index });
-      } catch {
-        // Malformed file — skip silently, same as missing
-        searched[searched.length - 1].found = false;
+      } catch (e) {
+        // Malformed file — skip it (don't sink the whole resolve), but record
+        // that it was malformed (not merely absent) so callers can report the
+        // difference. A present-but-corrupt file shown as "not found" hides a
+        // problem the user needs to fix.
+        const rec = searched[searched.length - 1];
+        rec.found = false;
+        rec.malformed = true;
+        rec.error = (e as Error).message;
       }
     }
   }

packages/kernel/src/tests/cli-helpers.test.ts

@@ -0,0 +1,92 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import {
+  isLoadoutIndex,
+  describeIndexShapeProblem,
+  getFlagValue,
+  diagnoseFlagValue,
+} from "../cli-helpers.js";
+
+// ── isLoadoutIndex (KER-B1) ──────────────────────────────────────
+
+describe("isLoadoutIndex (KER-B1 trust boundary)", () => {
+  it("accepts an object with an entries array", () => {
+    assert.equal(isLoadoutIndex({ entries: [] }), true);
+    assert.equal(isLoadoutIndex({ version: "1.0.0", entries: [{ id: "a" }] }), true);
+  });
+
+  it("rejects valid-but-wrong JSON that would crash downstream", () => {
+    // These all parse as valid JSON yet would throw a raw TypeError the moment
+    // something reads `.entries`. The guard catches them at the boundary.
+    assert.equal(isLoadoutIndex(null), false);
+    assert.equal(isLoadoutIndex(42), false);
+    assert.equal(isLoadoutIndex("a string"), false);
+    assert.equal(isLoadoutIndex(true), false);
+    assert.equal(isLoadoutIndex({}), false);
+    assert.equal(isLoadoutIndex([]), false);
+    assert.equal(isLoadoutIndex([{ entries: [] }]), false);
+    assert.equal(isLoadoutIndex({ entries: "not an array" }), false);
+    assert.equal(isLoadoutIndex({ version: "1.0.0" }), false); // missing entries
+  });
+});
+
+describe("describeIndexShapeProblem (KER-B1 actionable hint)", () => {
+  it("returns null for a valid index (no problem)", () => {
+    assert.equal(describeIndexShapeProblem({ entries: [] }), null);
+  });
+
+  it("names the specific problem for each wrong shape", () => {
+    assert.match(describeIndexShapeProblem(null)!, /null/);
+    assert.match(describeIndexShapeProblem([])!, /array/);
+    assert.match(describeIndexShapeProblem(42)!, /number/);
+    assert.match(describeIndexShapeProblem("x")!, /string/);
+    assert.match(describeIndexShapeProblem({})!, /entries/);
+    assert.match(describeIndexShapeProblem({ entries: 5 })!, /entries/);
+  });
+});
+
+// ── getFlagValue (KER-B6) ────────────────────────────────────────
+
+describe("getFlagValue (KER-B6 defensive flag parsing)", () => {
+  it("reads --flag value", () => {
+    assert.equal(getFlagValue(["--project", "/tmp/x"], "project"), "/tmp/x");
+  });
+
+  it("reads --flag=value", () => {
+    assert.equal(getFlagValue(["--project=/tmp/x"], "project"), "/tmp/x");
+  });
+
+  it("honors --flag=value even when value starts with -- (explicit pairing)", () => {
+    assert.equal(getFlagValue(["--project=--json"], "project"), "--json");
+  });
+
+  it("does NOT swallow a following flag as the value", () => {
+    // `--project --json` previously returned "--json"; now it returns undefined
+    // because the user clearly forgot the value for --project.
+    assert.equal(getFlagValue(["--project", "--json"], "project"), undefined);
+  });
+
+  it("returns undefined when the flag is the last token", () => {
+    assert.equal(getFlagValue(["resolve", "--project"], "project"), undefined);
+  });
+
+  it("returns undefined when the flag is absent", () => {
+    assert.equal(getFlagValue(["resolve", "--json"], "project"), undefined);
+  });
+});
+
+describe("diagnoseFlagValue (KER-B6 error classification)", () => {
+  it("returns null when a value is present", () => {
+    assert.equal(diagnoseFlagValue(["--project", "/tmp/x"], "project"), null);
+    assert.equal(diagnoseFlagValue(["--project=/tmp/x"], "project"), null);
+  });
+
+  it("classifies a swallowed following flag", () => {
+    assert.equal(diagnoseFlagValue(["--project", "--json"], "project"), "swallowed");
+  });
+
+  it("classifies an absent or trailing flag as missing", () => {
+    assert.equal(diagnoseFlagValue(["resolve"], "project"), "missing");
+    assert.equal(diagnoseFlagValue(["resolve", "--project"], "project"), "missing");
+  });
+});