fix(health-a): package defects across kernel/memories/rules (+25 tests)

memories: tighten inline-path parser so prose citations no longer become index entries (the memory-files/full-frame/see-also junk defect); surface unresolved refs; add ID_TOO_LONG validate rule; export nameToId; fix frontmatter summary-truncation asymmetry; regression tests (MEM-001/002/003/004/007/009). kernel: rewrite SECURITY.md threat model to match actual FS I/O; fix frontmatter indexOf line mis-resolution; fix usage --json dropping the modes Set; changelog date (KER-01/03/06/08; public API unchanged). rules: bounds-check --rules-dir arg parsing; structured INVALID_SIGNALS error; drift-detection tests; remove dead unsplittable plumbing (RUL-001/002/003/005/006).

Tests: 203 -> 228 green (kernel 93->97, memories 35->42, rules 75->89). Exclusive file ownership verified, no cross-domain edits.

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

Author: mcp-tool-shop

packages/kernel/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## 1.4.3 — unreleased
+## 1.4.3 — 2026-06-16
 
 - **`validate` CLI command** (2026-03-25): validate index structure from the command line (`ai-loadout validate <index>`)
 - **Fix**: `loadIndex()` now emits structured error on malformed JSON instead of raw stack trace (2026-03-25)

packages/kernel/SECURITY.md

@@ -2,22 +2,45 @@
 
 ## Attack Surface
 
-`@mcptoolshop/ai-loadout` is a **pure data library**. It has:
-
-- **No filesystem access** — does not read or write files
-- **No network access** — makes no HTTP requests, opens no sockets
-- **No code execution** — no `eval`, `Function()`, or dynamic imports
-- **No telemetry** — collects and transmits nothing
-- **No native dependencies** — pure TypeScript, zero production deps
-
-All I/O is the consumer's responsibility. This package only transforms data structures in memory.
+`@mcptoolshop/ai-loadout` is a small, locally-scoped library. Its surface breaks into three parts:
+
+- **Pure core** — matching, merging, validation, token estimation, and frontmatter
+  parsing/serialization are pure functions with no side effects. They only transform
+  data structures in memory.
+- **Resolver** — `discoverLayers()` / `resolveLoadout()` / the `resolve` CLI command
+  perform **local-only filesystem reads** to discover layer index files in fixed,
+  canonical locations (`~/.ai-loadout/index.json`, `<project>/.claude/loadout/index.json`,
+  and explicit org/session paths). It reads `index.json` files with `readFileSync` and
+  probes for their existence with `existsSync`. It never writes, never walks arbitrary
+  trees, and never follows network locations.
+- **Usage tracking** — `recordUsage()` / `readUsage()` perform **append-only local
+  JSONL writes** (`appendFileSync`) and reads (`readFileSync`) to a path supplied by the
+  caller. Events are appended one line at a time; nothing is ever transmitted.
+
+Across all three parts:
+
+- **No network access** — makes no HTTP requests, opens no sockets.
+- **No code execution** — no `eval`, `Function()`, or dynamic imports.
+- **No telemetry / exfiltration** — usage data stays on the local disk path the caller
+  chooses; nothing is collected centrally or sent anywhere.
+- **No secrets** — the library handles loadout metadata only; it reads no credentials,
+  environment secrets, or tokens.
+- **No native dependencies** — pure TypeScript, zero production deps.
+
+Filesystem access is confined to: reading the caller-specified index files the resolver
+discovers, and reading/appending the caller-specified usage JSONL log. The library never
+writes outside the path the caller hands it.
 
 ## Input Validation
 
 The `parseFrontmatter()` function processes untrusted text input. It uses simple string splitting — no YAML parser, no regex-based evaluation, no prototype pollution vectors.
 
 The `validateIndex()` function checks structural integrity of index objects. It does not execute or interpret any field values.
 
+The resolver and usage reader treat on-disk files as untrusted: malformed `index.json`
+layers are skipped silently (the layer is reported as not found), and malformed JSONL
+usage lines are skipped without throwing. No file content is ever executed or evaluated.
+
 ## Supported Versions
 
 | Version | Supported |

packages/kernel/src/cli.ts

@@ -14,7 +14,7 @@ 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 } from "./usage.js";
+import { readUsage, summarizeUsage, summaryToJSON } from "./usage.js";
 import { findDeadEntries, findKeywordOverlaps, analyzeBudget } from "./analysis.js";
 import { resolveLoadout, explainEntry } from "./resolve.js";
 import type { ResolveOptions } from "./resolve.js";
@@ -147,7 +147,9 @@ function cmdUsage(args: string[]) {
   const summary = summarizeUsage(events);
 
   if (json) {
-    log(JSON.stringify(summary, null, 2));
+    // summary.modes is a Set<string>; JSON.stringify would drop it to {}.
+    // Project to a JSON-safe shape (modes → array) before serializing.
+    log(JSON.stringify(summary.map(summaryToJSON), null, 2));
     return;
   }
 

packages/kernel/src/frontmatter.ts

@@ -41,7 +41,8 @@ export function parseFrontmatter(
   let currentArray: string[] | null = null;
   let currentObject: Record<string, boolean> | null = null;
 
-  for (const line of fmLines) {
+  for (let i = 0; i < fmLines.length; i++) {
+    const line = fmLines[i];
     const trimmed = line.trim();
     if (trimmed === "") continue;
 
@@ -81,13 +82,14 @@ export function parseFrontmatter(
     currentKey = key;
 
     if (rawVal === "") {
-      // Peek at next line to determine if block array or object
-      const lineIdx = fmLines.indexOf(line);
-      if (lineIdx + 1 < fmLines.length) {
-        const nextTrimmed = fmLines[lineIdx + 1].trim();
+      // Peek at next line to determine if block array or object.
+      // Use the loop index `i` directly: indexOf(line) would return the
+      // first byte-identical line, mis-resolving duplicate-value keys.
+      if (i + 1 < fmLines.length) {
+        const nextTrimmed = fmLines[i + 1].trim();
         if (nextTrimmed.startsWith("- ")) {
           currentArray = [];
-        } else if (fmLines[lineIdx + 1].startsWith("  ")) {
+        } else if (fmLines[i + 1].startsWith("  ")) {
           currentObject = {};
         }
       }

packages/kernel/src/index.ts

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

packages/kernel/src/tests/frontmatter.test.ts

@@ -62,6 +62,44 @@ describe("parseFrontmatter", () => {
     assert.ok(frontmatter);
     assert.deepEqual(frontmatter.keywords, []);
   });
+
+  it("peeks the correct next line for byte-identical empty-value keys", () => {
+    // Regression (KER-03): the empty-value block-key peek used
+    // `fmLines.indexOf(line)`, which returns the FIRST byte-identical line.
+    // When the same empty-value key line ("triggers:") appears twice, the
+    // SECOND occurrence would peek the FIRST occurrence's next line and
+    // mis-classify its block (array vs object).
+    //
+    // First `triggers:` is followed by a dash item (would open an array);
+    // the last-wins `triggers:` is followed by an indented object. With the
+    // buggy indexOf, the second `triggers:` peeks the first occurrence's next
+    // line ("- task") and wrongly opens an array, so the real triggers object
+    // is dropped and triggers fall back to DEFAULT_TRIGGERS. With numeric
+    // indexing, the second occurrence peeks its OWN next line and parses the
+    // object correctly.
+    const content = [
+      "---",
+      "id: dup-key",
+      "keywords: [x]",
+      "priority: core",
+      "triggers:",        // first occurrence — dash item follows
+      "- task",           //   (buggy indexOf peek target for the 2nd key)
+      "triggers:",        // byte-identical key line — indented object follows
+      "  task: false",
+      "  plan: false",
+      "  edit: true",
+      "---",
+      "Body",
+    ].join("\n");
+    const { frontmatter } = parseFrontmatter(content);
+    assert.ok(frontmatter);
+    // The winning (second) triggers block must be parsed as an object.
+    // On the buggy code it would be skipped, leaving DEFAULT_TRIGGERS
+    // (task: true, edit: false) — distinct from the expected values below.
+    assert.equal(frontmatter.triggers.task, false);
+    assert.equal(frontmatter.triggers.plan, false);
+    assert.equal(frontmatter.triggers.edit, true);
+  });
 });
 
 describe("serializeFrontmatter", () => {

packages/kernel/src/tests/usage.test.ts

@@ -3,7 +3,7 @@ import assert from "node:assert/strict";
 import { writeFileSync, unlinkSync, mkdtempSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import { recordUsage, readUsage, summarizeUsage } from "../usage.js";
+import { recordUsage, readUsage, summarizeUsage, summaryToJSON } from "../usage.js";
 import type { UsageEvent } from "../types.js";
 
 function makeTmp(): string {
@@ -109,4 +109,51 @@ describe("summarizeUsage", () => {
     const summary = summarizeUsage(events);
     assert.equal(summary[0].lastLoaded, "2026-03-06T12:00:00Z");
   });
+
+  it("tracks unique modes as a Set", () => {
+    const events = [
+      makeEvent({ entryId: "a", mode: "eager" }),
+      makeEvent({ entryId: "a", mode: "lazy" }),
+      makeEvent({ entryId: "a", mode: "eager" }),
+    ];
+    const summary = summarizeUsage(events);
+    assert.ok(summary[0].modes instanceof Set);
+    assert.equal(summary[0].modes.size, 2);
+    assert.ok(summary[0].modes.has("eager"));
+    assert.ok(summary[0].modes.has("lazy"));
+  });
+});
+
+describe("summaryToJSON (KER-06)", () => {
+  it("serializes modes as an array, not an empty object", () => {
+    // Regression: JSON.stringify(summary) drops the modes Set to {}.
+    // summaryToJSON projects modes to an array so --json output keeps them.
+    const events = [
+      makeEvent({ entryId: "a", mode: "eager" }),
+      makeEvent({ entryId: "a", mode: "lazy" }),
+    ];
+    const summary = summarizeUsage(events);
+
+    // The raw Set would serialize to {} — confirm the bug we are fixing.
+    assert.equal(JSON.stringify(summary[0].modes), "{}");
+
+    const json = summary.map(summaryToJSON);
+    assert.ok(Array.isArray(json[0].modes));
+    assert.deepEqual([...json[0].modes].sort(), ["eager", "lazy"]);
+
+    // The serialized JSON string actually contains the modes.
+    const serialized = JSON.stringify(json, null, 2);
+    const parsed = JSON.parse(serialized) as Array<{ modes: string[] }>;
+    assert.deepEqual(parsed[0].modes.sort(), ["eager", "lazy"]);
+  });
+
+  it("preserves all other summary fields", () => {
+    const events = [makeEvent({ entryId: "x", trigger: "kw-ci", tokensEst: 42 })];
+    const json = summaryToJSON(summarizeUsage(events)[0]);
+    assert.equal(json.entryId, "x");
+    assert.equal(json.loadCount, 1);
+    assert.equal(json.totalTokens, 42);
+    assert.deepEqual(json.triggers, ["kw-ci"]);
+    assert.deepEqual(json.modes, ["lazy"]);
+  });
 });

packages/kernel/src/usage.ts

@@ -96,3 +96,36 @@ export function summarizeUsage(events: UsageEvent[]): UsageSummary[] {
     }))
     .sort((a, b) => b.loadCount - a.loadCount);
 }
+
+/**
+ * A JSON-safe projection of a UsageSummary.
+ *
+ * `UsageSummary.modes` is a `Set<string>`, which `JSON.stringify` serializes to
+ * `{}` — silently dropping the data. This shape replaces the Set with an array
+ * so `--json` output (and any other JSON consumer) round-trips the modes.
+ */
+export interface UsageSummaryJSON {
+  entryId: string;
+  loadCount: number;
+  totalTokens: number;
+  lastLoaded: string;
+  triggers: string[];
+  modes: string[];
+}
+
+/**
+ * Convert a UsageSummary to a JSON-safe shape (Set<string> modes → string[]).
+ *
+ * Use this at any JSON serialization boundary instead of stringifying the
+ * summary directly, which would drop `modes`.
+ */
+export function summaryToJSON(summary: UsageSummary): UsageSummaryJSON {
+  return {
+    entryId: summary.entryId,
+    loadCount: summary.loadCount,
+    totalTokens: summary.totalTokens,
+    lastLoaded: summary.lastLoaded,
+    triggers: summary.triggers,
+    modes: [...summary.modes],
+  };
+}

packages/memories/src/index-gen.ts

@@ -39,7 +39,20 @@ export function generateIndex(
   for (const ref of analysis.refs) {
     // Try relative to MEMORY.md, then relative to parent
     const fullPath = resolveRefPath(ref.path, fileDir, parentDir);
-    if (!fullPath) continue;
+    if (!fullPath) {
+      // MEM-002: don't drop unresolved refs silently. A ref whose path
+      // doesn't resolve (a non-existent file, a glob like `memory/*.md`,
+      // or an absolute path) used to vanish here with zero trace — that's
+      // exactly how parser junk slipped through undetected. Surface it.
+      if (!analysis.missingFiles.includes(ref.path)) {
+        analysis.missingFiles.push(ref.path);
+      }
+      console.warn(
+        `[claude-memories] unresolved ref "${ref.name || ref.path}" ` +
+          `→ ${ref.path} (line ${ref.line + 1}); skipped from index`,
+      );
+      continue;
+    }
 
     const content = readFileSync(fullPath, "utf-8");
     const { frontmatter } = parseFrontmatter(content);
@@ -82,6 +95,14 @@ export function generateIndex(
   };
 }
 
+/** Max summary length — keep entry summaries compact in the dispatch table. */
+const MAX_SUMMARY = 120;
+
+/** Truncate a summary to MAX_SUMMARY chars. Shared by both entry builders. */
+function truncateSummary(summary: string): string {
+  return summary.slice(0, MAX_SUMMARY);
+}
+
 function entryFromFrontmatter(
   fm: Frontmatter,
   ref: MemoryRef,
@@ -94,7 +115,9 @@ function entryFromFrontmatter(
     keywords: fm.keywords,
     patterns: fm.patterns,
     priority: fm.priority,
-    summary: ref.description || `Memory: ${ref.name}`,
+    // MEM-007: truncate here too — entryFromContent already truncated to
+    // 120, this branch did not, so a long summary survived asymmetrically.
+    summary: truncateSummary(ref.description || `Memory: ${ref.name}`),
     triggers: fm.triggers,
     tokens_est: estimateTokens(content),
     lines,
@@ -113,7 +136,7 @@ function entryFromContent(ref: MemoryRef, content: string): LoadoutEntry {
     patterns: [],
     priority: "domain",
     summary: ref.description
-      ? ref.description.slice(0, 120)
+      ? truncateSummary(ref.description)
       : `Memory: ${ref.name}`,
     triggers: { ...DEFAULT_TRIGGERS },
     tokens_est: estimateTokens(content),
@@ -125,8 +148,13 @@ function entryFromContent(ref: MemoryRef, content: string): LoadoutEntry {
  * Convert a display name to kebab-case ID.
  * "AI Loadout" → "ai-loadout"
  * "Claude Guardian" → "claude-guardian"
+ *
+ * Exported (MEM-009) so the parser and validator can reuse the exact
+ * same derivation — the kebab id is the contract shared between
+ * ref-parsing (MEM-001 junk-id rejection) and validate (MEM-004
+ * ID_TOO_LONG length check).
  */
-function nameToId(name: string): string {
+export function nameToId(name: string): string {
   return name
     .toLowerCase()
     .replace(/[^a-z0-9\s-]/g, "")