feat: v1.1.0 — merge semantics, match enrichment, usage schema, SPEC

Add mergeIndexes() for hierarchical loadouts with provenance tracking.
Enrich MatchResult with reason and mode fields. Add LoadMode, UsageEvent,
MergeConflict, MergedIndex types. Add lazyLoad flag to LoadoutIndex.
Write full SPEC.md. 40 tests (8 new for merge).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: mcp-tool-shop

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 1.1.0 — 2026-03-06
+
+- **MatchResult enrichment**: `reason` (human-readable explanation) and `mode` (eager/lazy/manual)
+- **Merge semantics**: `mergeIndexes()` for hierarchical loadouts (global → org → project → task)
+- **MergedIndex** with provenance tracking and conflict reporting
+- **UsageEvent** schema for local-only observability
+- **lazyLoad** flag on `LoadoutIndex` for demand-paged context
+- **LoadMode** type (`eager | lazy | manual`)
+- **SPEC.md**: Full specification document
+- 8 new tests (merge), 40 total
+
 ## 1.0.3 — 2026-03-06
 
 - Brand logo URL (mcp-tool-shop-org/brand)

SPEC.md

@@ -0,0 +1,217 @@
+# ai-loadout Specification
+
+> Context-aware knowledge router for AI agents.
+> Version: 1.1.0
+
+## Overview
+
+ai-loadout is a zero-dependency kernel for routing context-budgeted knowledge to AI agents. It provides the data model, matching logic, validation, and merge semantics that consumers (like `claude-rules` or `claude-memories`) build on top of.
+
+## Data Model
+
+### LoadoutEntry
+
+A single entry in the dispatch table.
+
+| Field | Type | Constraints |
+|-------|------|-------------|
+| `id` | `string` | Kebab-case, unique, stable once created |
+| `path` | `string` | Relative to repo root, non-empty |
+| `keywords` | `string[]` | Lowercase surface words for matching. Required non-empty for `domain` entries |
+| `patterns` | `string[]` | Named intents (e.g. `ci_pipeline`), not regex |
+| `priority` | `Priority` | `"core"` \| `"domain"` \| `"manual"` |
+| `summary` | `string` | Non-empty, max 120 chars, dense routing signal |
+| `triggers` | `Triggers` | Which agent phases activate this entry |
+| `tokens_est` | `number` | Estimated tokens (chars / 4), non-negative |
+| `lines` | `number` | Line count of the payload file |
+
+### Priority Tiers
+
+| Tier | Behavior |
+|------|----------|
+| `core` | Always loaded. Score 1.0, mode `eager`. Cannot be skipped. |
+| `domain` | Keyword-triggered. Score 0.1–1.0, mode `lazy`. Loaded when task matches. |
+| `manual` | Never auto-loaded. Score 0, mode `manual`. Requires explicit `lookupEntry()`. |
+
+### Triggers
+
+Controls WHEN a payload should be loaded relative to the agent loop.
+
+| Field | Type | Default | Purpose |
+|-------|------|---------|---------|
+| `task` | `boolean` | `true` | Load during task interpretation |
+| `plan` | `boolean` | `true` | Load during plan formation |
+| `edit` | `boolean` | `false` | Load before file edits |
+
+### LoadoutIndex
+
+The dispatch table (`index.json`).
+
+| Field | Type | Required |
+|-------|------|----------|
+| `version` | `string` | Yes |
+| `generated` | `string` | Yes (ISO 8601) |
+| `entries` | `LoadoutEntry[]` | Yes |
+| `budget` | `Budget` | Yes |
+| `lazyLoad` | `boolean` | No. When true, payloads are not pre-loaded into context |
+
+### Budget
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `always_loaded_est` | `number` | Sum of `tokens_est` for all `core` entries |
+| `on_demand_total_est` | `number` | Sum of `tokens_est` for all non-core entries |
+| `avg_task_load_est` | `number` | Estimated average tokens loaded per session |
+| `avg_task_load_observed` | `number \| null` | From usage telemetry (future) |
+
+### LoadMode
+
+Controls HOW a payload is loaded into agent context.
+
+| Mode | When |
+|------|------|
+| `eager` | Loaded immediately (core entries) |
+| `lazy` | Loaded on keyword match (domain entries) |
+| `manual` | Only via explicit lookup |
+
+## Matching
+
+`matchLoadout(task, index)` → `MatchResult[]`
+
+### Algorithm
+
+1. Tokenize task description: lowercase, strip non-alphanumeric, split on whitespace, discard words ≤ 1 char
+2. For each entry:
+   - **Core**: score = 1.0, always included
+   - **Manual**: score = 0, never included
+   - **Domain**: score = (matched keywords / total keywords) + pattern bonus (0.2 if any pattern word matches)
+3. Include entries with score ≥ 0.1
+4. Sort by score descending, then by `tokens_est` ascending (cheaper first for ties)
+
+### MatchResult
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `entry` | `LoadoutEntry` | The matched entry |
+| `score` | `number` | 0–1, higher = stronger match |
+| `matchedKeywords` | `string[]` | Which keywords matched |
+| `matchedPatterns` | `string[]` | Which patterns matched |
+| `reason` | `string` | Human-readable explanation |
+| `mode` | `LoadMode` | How this entry should be loaded |
+
+### Keyword Matching
+
+- Keywords are split on whitespace/hyphens
+- All words in a multi-word keyword must be present in the task tokens
+- Score contribution: `matchedKeywords.length / totalKeywords.length`
+
+### Pattern Matching
+
+- Patterns are split on underscores
+- Any word match triggers the pattern bonus (+0.2)
+- Patterns are named intents, not regex
+
+## Validation
+
+`validateIndex(index)` → `ValidationIssue[]`
+
+Validates structural integrity only. Does NOT check filesystem (that's the consumer's job).
+
+### Issue Codes
+
+| Code | Severity | Condition |
+|------|----------|-----------|
+| `MISSING_VERSION` | error | Empty version field |
+| `MISSING_GENERATED` | warning | Empty generated timestamp |
+| `INVALID_ENTRIES` | error | Entries is not an array |
+| `MISSING_ID` | error | Entry has no id |
+| `BAD_ID_FORMAT` | warning | ID is not kebab-case |
+| `DUPLICATE_ID` | error | Same ID appears twice |
+| `MISSING_PATH` | error | Entry has no path |
+| `INVALID_PRIORITY` | error | Priority not in `core\|domain\|manual` |
+| `MISSING_SUMMARY` | error | Empty summary |
+| `LONG_SUMMARY` | warning | Summary exceeds 120 chars |
+| `EMPTY_KEYWORDS` | error | Domain entry has no keywords |
+| `BAD_TOKEN_EST` | warning | Negative or non-number token estimate |
+| `NEGATIVE_BUDGET` | warning | Budget field is negative |
+
+## Frontmatter
+
+Payload files carry YAML-like frontmatter:
+
+```
+---
+id: my-rule
+keywords: [testing, unit, integration]
+patterns: [test_strategy]
+priority: domain
+triggers:
+  task: true
+  plan: true
+  edit: false
+---
+```
+
+- `parseFrontmatter(content)` → `{ frontmatter, body }`
+- `serializeFrontmatter(fm)` → frontmatter string
+- Round-trips are deterministic
+- Missing triggers default to `{ task: true, plan: true, edit: false }`
+- Invalid priority defaults to `domain`
+
+## Merge
+
+`mergeIndexes(layers)` → `MergedIndex`
+
+For hierarchical loadouts: multiple indexes merged deterministically.
+
+### Semantics
+
+- Layers are ordered earlier → later (e.g. global, org, project, task)
+- Later layers override earlier for the same entry ID
+- All overrides are tracked as conflicts with `resolution: "override"`
+- Budget is recalculated from the merged entry set
+
+### MergedIndex
+
+Extends `LoadoutIndex` with:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `provenance` | `Record<string, string>` | entryId → source layer name |
+| `conflicts` | `MergeConflict[]` | Entries defined in multiple layers |
+
+### MergeConflict
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `entryId` | `string` | Which entry was in conflict |
+| `layers` | `string[]` | All layers that define this entry |
+| `resolution` | `"override" \| "error"` | How it was resolved |
+
+## Token Estimation
+
+`estimateTokens(text)` → `number`
+
+Heuristic: `Math.ceil(text.length / 4)`. Good enough for budget dashboards, not meant for billing.
+
+## Usage Event Schema
+
+For observability (append-only log, local-only, never networked):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `timestamp` | `string` | ISO 8601 |
+| `taskHash` | `string` | Session-local task identifier |
+| `entryId` | `string` | Which payload was loaded |
+| `trigger` | `string` | Which keyword/pattern caused the load |
+| `mode` | `LoadMode` | eager, lazy, or manual |
+| `tokensEst` | `number` | Estimated token cost |
+| `sourceLayer` | `string?` | Which hierarchy layer (future) |
+
+## Design Constraints
+
+- Zero production dependencies
+- Pure TypeScript ESM
+- Node ≥ 20
+- Deterministic: same inputs → same outputs (except `generated` timestamps)
+- Kernel only: no CLI, no filesystem access, no I/O

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcptoolshop/ai-loadout",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "Context-aware knowledge router for AI agents. Dispatch table, frontmatter spec, keyword matcher, token estimator.",
   "type": "module",
   "main": "dist/index.js",
@@ -22,6 +22,7 @@
     "dist",
     "README.md",
     "CHANGELOG.md",
+    "SPEC.md",
     "LICENSE",
     "SECURITY.md",
     "logo.png"

src/index.ts

@@ -2,11 +2,15 @@
 export type {
   Priority,
   Triggers,
+  LoadMode,
   LoadoutEntry,
   Budget,
   LoadoutIndex,
   Frontmatter,
   MatchResult,
+  UsageEvent,
+  MergeConflict,
+  MergedIndex,
   IssueSeverity,
   ValidationIssue,
 } from "./types.js";
@@ -24,3 +28,6 @@ export { matchLoadout, lookupEntry } from "./match.js";
 
 // ── Validator ──────────────────────────────────────────────────
 export { validateIndex } from "./validate.js";
+
+// ── Merge ─────────────────────────────────────────────────────
+export { mergeIndexes } from "./merge.js";

src/match.ts

@@ -12,7 +12,7 @@
  * - Manual entries are never auto-included (require explicit lookup)
  */
 
-import type { LoadoutIndex, LoadoutEntry, MatchResult } from "./types.js";
+import type { LoadoutIndex, LoadoutEntry, MatchResult, LoadMode } from "./types.js";
 
 const MIN_SCORE = 0.1;  // minimum score to include a domain entry
 
@@ -95,7 +95,21 @@ export function matchLoadout(
     );
 
     if (score >= MIN_SCORE) {
-      results.push({ entry, score, matchedKeywords, matchedPatterns });
+      const mode: LoadMode = entry.priority === "manual"
+        ? "manual"
+        : entry.priority === "core"
+          ? "eager"
+          : "lazy";
+
+      const reason = entry.priority === "core"
+        ? "core: always loaded"
+        : matchedKeywords.length > 0 && matchedPatterns.length > 0
+          ? `keywords [${matchedKeywords.join(", ")}] + patterns [${matchedPatterns.join(", ")}]`
+          : matchedKeywords.length > 0
+            ? `keywords [${matchedKeywords.join(", ")}]`
+            : `patterns [${matchedPatterns.join(", ")}]`;
+
+      results.push({ entry, score, matchedKeywords, matchedPatterns, reason, mode });
     }
   }
 

src/merge.ts

@@ -0,0 +1,83 @@
+/**
+ * Index merge for hierarchical loadouts.
+ *
+ * Deterministic merge: later layers override earlier ones.
+ * Same-ID entries from a later layer replace the earlier version.
+ * Conflicts (same keyword, different payload, same priority) are reported.
+ */
+
+import type { LoadoutIndex, LoadoutEntry, MergedIndex, MergeConflict, Budget } from "./types.js";
+import { estimateTokens } from "./tokens.js";
+
+interface LayeredIndex {
+  name: string;     // e.g. "global", "org", "project", "task"
+  index: LoadoutIndex;
+}
+
+/**
+ * Merge multiple loadout indexes in order (earlier → later, later wins).
+ *
+ * Returns a MergedIndex with provenance tracking and conflict reports.
+ */
+export function mergeIndexes(layers: LayeredIndex[]): MergedIndex {
+  const entryMap = new Map<string, { entry: LoadoutEntry; layer: string }>();
+  const provenance: Record<string, string> = {};
+  const conflicts: MergeConflict[] = [];
+
+  // Track which layers define each ID for conflict detection
+  const idLayers = new Map<string, string[]>();
+
+  for (const { name, index } of layers) {
+    for (const entry of index.entries) {
+      // Track all layers that define this ID
+      const existing = idLayers.get(entry.id) ?? [];
+      existing.push(name);
+      idLayers.set(entry.id, existing);
+
+      // Later layer overrides earlier
+      entryMap.set(entry.id, { entry, layer: name });
+      provenance[entry.id] = name;
+    }
+  }
+
+  // Report entries defined in multiple layers
+  for (const [id, layerNames] of idLayers) {
+    if (layerNames.length > 1) {
+      conflicts.push({
+        entryId: id,
+        layers: layerNames,
+        resolution: "override",
+      });
+    }
+  }
+
+  const entries = [...entryMap.values()].map((v) => v.entry);
+
+  // Recalculate budget from merged entries
+  const coreTokens = entries
+    .filter((e) => e.priority === "core")
+    .reduce((sum, e) => sum + e.tokens_est, 0);
+  const onDemandTokens = entries
+    .filter((e) => e.priority !== "core")
+    .reduce((sum, e) => sum + e.tokens_est, 0);
+  const domainEntries = entries.filter((e) => e.priority === "domain");
+  const avgTaskLoad = domainEntries.length > 0
+    ? Math.round(onDemandTokens / domainEntries.length)
+    : 0;
+
+  const budget: Budget = {
+    always_loaded_est: coreTokens,
+    on_demand_total_est: onDemandTokens,
+    avg_task_load_est: avgTaskLoad,
+    avg_task_load_observed: null,
+  };
+
+  return {
+    version: "1.0.0",
+    generated: new Date().toISOString(),
+    entries,
+    budget,
+    provenance,
+    conflicts,
+  };
+}