@mcptoolshop/ai-loadout 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 1.0.0 — 2026-03-06
+
+Initial release.
+
+- `LoadoutIndex` schema — dispatch table for agent knowledge
+- `parseFrontmatter()` / `serializeFrontmatter()` — payload file metadata
+- `matchLoadout()` — deterministic keyword + pattern matcher
+- `lookupEntry()` — explicit entry lookup by ID
+- `validateIndex()` — structural linter for index integrity
+- `estimateTokens()` — chars/4 heuristic for budget dashboards
+- Three priority tiers: core / domain / manual
+- Trigger phases: task / plan / edit
+- Zero production dependencies

package/LICENSE

@@ -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.

package/README.md

@@ -0,0 +1,181 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/ai-loadout/readme.png" width="400" alt="ai-loadout">
+</p>
+
+<p align="center">
+  <a href="https://github.com/mcp-tool-shop-org/ai-loadout/actions/workflows/ci.yml"><img src="https://github.com/mcp-tool-shop-org/ai-loadout/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/@mcptoolshop/ai-loadout"><img src="https://img.shields.io/npm/v/@mcptoolshop/ai-loadout" alt="npm"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"></a>
+</p>
+
+Context-aware knowledge router for AI agents.
+
+`ai-loadout` is the dispatch table format and matching engine that lets AI agents load the right knowledge for the task at hand. Instead of dumping everything into context, you keep a tiny index and load payloads on demand.
+
+Think of it like a game loadout — you equip the agent with exactly the knowledge it needs before each mission.
+
+## Install
+
+```bash
+npm install @mcptoolshop/ai-loadout
+```
+
+## Core Concepts
+
+### The Dispatch Table
+
+A `LoadoutIndex` is a structured index of knowledge payloads:
+
+```json
+{
+  "version": "1.0.0",
+  "generated": "2026-03-06T12:00:00Z",
+  "entries": [
+    {
+      "id": "github-actions",
+      "path": ".rules/github-actions.md",
+      "keywords": ["ci", "workflow", "runner"],
+      "patterns": ["ci_pipeline"],
+      "priority": "domain",
+      "summary": "CI triggers, path gating, runner cost control",
+      "triggers": { "task": true, "plan": true, "edit": false },
+      "tokens_est": 680,
+      "lines": 56
+    }
+  ],
+  "budget": {
+    "always_loaded_est": 320,
+    "on_demand_total_est": 8100,
+    "avg_task_load_est": 520,
+    "avg_task_load_observed": null
+  }
+}
+```
+
+### Priority Tiers
+
+| Tier | Behavior | Example |
+|------|----------|---------|
+| `core` | Always loaded | "never skip tests to make CI green" |
+| `domain` | Loaded when task keywords match | CI rules when editing workflows |
+| `manual` | Never auto-loaded, explicit lookup only | Obscure platform gotchas |
+
+### Payload Frontmatter
+
+Each payload file carries its own routing metadata:
+
+```markdown
+---
+id: github-actions
+keywords: [ci, workflow, runner, dependabot]
+patterns: [ci_pipeline]
+priority: domain
+triggers:
+  task: true
+  plan: true
+  edit: false
+---
+
+# GitHub Actions Rules
+CI minutes are finite...
+```
+
+Frontmatter is the source of truth. The index is derived from it.
+
+## API
+
+### `matchLoadout(task, index)`
+
+Match a task description against a loadout index. Returns entries that should be loaded, ranked by match strength.
+
+```typescript
+import { matchLoadout } from "@mcptoolshop/ai-loadout";
+
+const results = matchLoadout("fix the CI workflow", index);
+// [{ entry: { id: "github-actions", ... }, score: 0.67, matchedKeywords: ["ci", "workflow"] }]
+```
+
+- Core entries always included (score 1.0)
+- Manual entries never auto-included
+- Domain entries scored by keyword overlap + pattern bonus
+- Results sorted by score descending
+
+### `lookupEntry(id, index)`
+
+Look up a specific entry by ID. For manual entries or explicit access.
+
+```typescript
+import { lookupEntry } from "@mcptoolshop/ai-loadout";
+
+const entry = lookupEntry("github-actions", index);
+```
+
+### `parseFrontmatter(content)`
+
+Parse YAML-like frontmatter from a payload file.
+
+```typescript
+import { parseFrontmatter } from "@mcptoolshop/ai-loadout";
+
+const { frontmatter, body } = parseFrontmatter(fileContent);
+if (frontmatter) {
+  console.log(frontmatter.id, frontmatter.keywords);
+}
+```
+
+### `serializeFrontmatter(fm)`
+
+Serialize a `Frontmatter` object back to a string.
+
+### `validateIndex(index)`
+
+Validate structural integrity of a `LoadoutIndex`. Returns an array of issues.
+
+```typescript
+import { validateIndex } from "@mcptoolshop/ai-loadout";
+
+const issues = validateIndex(index);
+const errors = issues.filter(i => i.severity === "error");
+if (errors.length > 0) {
+  console.error("Index has errors:", errors);
+}
+```
+
+Checks: required fields, unique IDs, kebab-case format, summary bounds, keyword presence for domain entries, valid priorities, non-negative budgets.
+
+### `estimateTokens(text)`
+
+Estimate token count from text. Uses chars/4 heuristic.
+
+```typescript
+import { estimateTokens } from "@mcptoolshop/ai-loadout";
+
+const tokens = estimateTokens(fileContent); // ~250
+```
+
+## Types
+
+```typescript
+import type {
+  LoadoutEntry,
+  LoadoutIndex,
+  Frontmatter,
+  MatchResult,
+  ValidationIssue,
+  Priority,       // "core" | "domain" | "manual"
+  Triggers,       // { task, plan, edit }
+  Budget,
+} from "@mcptoolshop/ai-loadout";
+```
+
+## Consumers
+
+- **[@mcptoolshop/claude-rules](https://github.com/mcp-tool-shop-org/claude-rules)** — CLAUDE.md optimizer for Claude Code. Uses ai-loadout for the dispatch table and matching.
+
+## Security
+
+This package is a pure data library. It does not access the filesystem, make network requests, or collect telemetry. All I/O is the consumer's responsibility.
+
+---
+
+Built by [MCP Tool Shop](https://mcp-tool-shop.github.io/)

package/dist/frontmatter.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Frontmatter parser and serializer.
+ *
+ * Parses YAML-like --- delimited blocks from payload files.
+ * Hand-rolled: supports strings, inline arrays, booleans, and
+ * one level of nested objects (triggers). No deps, deterministic.
+ */
+import type { Frontmatter } from "./types.js";
+export declare function parseFrontmatter(content: string): {
+    frontmatter: Frontmatter | null;
+    body: string;
+};
+export declare function serializeFrontmatter(fm: Frontmatter): string;

package/dist/frontmatter.js

@@ -0,0 +1,150 @@
+/**
+ * Frontmatter parser and serializer.
+ *
+ * Parses YAML-like --- delimited blocks from payload files.
+ * Hand-rolled: supports strings, inline arrays, booleans, and
+ * one level of nested objects (triggers). No deps, deterministic.
+ */
+import { DEFAULT_TRIGGERS } from "./types.js";
+const VALID_PRIORITIES = new Set(["core", "domain", "manual"]);
+// ── Parse frontmatter from file content ────────────────────────
+export function parseFrontmatter(content) {
+    const lines = content.split("\n");
+    if (lines[0]?.trim() !== "---") {
+        return { frontmatter: null, body: content };
+    }
+    let closeIndex = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i].trim() === "---") {
+            closeIndex = i;
+            break;
+        }
+    }
+    if (closeIndex === -1) {
+        return { frontmatter: null, body: content };
+    }
+    const fmLines = lines.slice(1, closeIndex);
+    const body = lines.slice(closeIndex + 1).join("\n");
+    const data = {};
+    let currentKey = "";
+    let currentArray = null;
+    let currentObject = null;
+    for (const line of fmLines) {
+        const trimmed = line.trim();
+        if (trimmed === "")
+            continue;
+        // Block array item
+        if (currentArray !== null && trimmed.startsWith("- ")) {
+            currentArray.push(trimmed.slice(2).trim());
+            continue;
+        }
+        // Nested object value (indented)
+        if (currentObject !== null && line.startsWith("  ")) {
+            const colonIdx = trimmed.indexOf(":");
+            if (colonIdx !== -1) {
+                const key = trimmed.slice(0, colonIdx).trim();
+                const val = trimmed.slice(colonIdx + 1).trim();
+                currentObject[key] = val === "true";
+                continue;
+            }
+        }
+        // Flush pending
+        if (currentArray !== null) {
+            data[currentKey] = currentArray;
+            currentArray = null;
+        }
+        if (currentObject !== null) {
+            data[currentKey] = currentObject;
+            currentObject = null;
+        }
+        // Key: value pair
+        const colonIdx = trimmed.indexOf(":");
+        if (colonIdx === -1)
+            continue;
+        const key = trimmed.slice(0, colonIdx).trim();
+        const rawVal = trimmed.slice(colonIdx + 1).trim();
+        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();
+                if (nextTrimmed.startsWith("- ")) {
+                    currentArray = [];
+                }
+                else if (fmLines[lineIdx + 1].startsWith("  ")) {
+                    currentObject = {};
+                }
+            }
+            continue;
+        }
+        // Inline array: [a, b, c]
+        if (rawVal.startsWith("[") && rawVal.endsWith("]")) {
+            const inner = rawVal.slice(1, -1);
+            data[key] = inner
+                .split(",")
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0);
+            continue;
+        }
+        // Boolean
+        if (rawVal === "true") {
+            data[key] = true;
+            continue;
+        }
+        if (rawVal === "false") {
+            data[key] = false;
+            continue;
+        }
+        // String
+        data[key] =
+            rawVal.startsWith('"') && rawVal.endsWith('"')
+                ? rawVal.slice(1, -1)
+                : rawVal;
+    }
+    // Flush trailing
+    if (currentArray !== null)
+        data[currentKey] = currentArray;
+    if (currentObject !== null)
+        data[currentKey] = currentObject;
+    // Validate required fields
+    if (typeof data.id !== "string" || !data.id) {
+        return { frontmatter: null, body: content };
+    }
+    const fm = {
+        id: data.id,
+        keywords: Array.isArray(data.keywords) ? data.keywords : [],
+        patterns: Array.isArray(data.patterns) ? data.patterns : [],
+        priority: VALID_PRIORITIES.has(data.priority)
+            ? data.priority
+            : "domain",
+        triggers: parseTriggers(data.triggers),
+    };
+    return { frontmatter: fm, body };
+}
+function parseTriggers(raw) {
+    if (!raw || typeof raw !== "object")
+        return { ...DEFAULT_TRIGGERS };
+    const obj = raw;
+    return {
+        task: typeof obj.task === "boolean" ? obj.task : DEFAULT_TRIGGERS.task,
+        plan: typeof obj.plan === "boolean" ? obj.plan : DEFAULT_TRIGGERS.plan,
+        edit: typeof obj.edit === "boolean" ? obj.edit : DEFAULT_TRIGGERS.edit,
+    };
+}
+// ── Serialize frontmatter to string ────────────────────────────
+export function serializeFrontmatter(fm) {
+    const lines = ["---"];
+    lines.push(`id: ${fm.id}`);
+    lines.push(`keywords: [${fm.keywords.join(", ")}]`);
+    if (fm.patterns.length > 0) {
+        lines.push(`patterns: [${fm.patterns.join(", ")}]`);
+    }
+    lines.push(`priority: ${fm.priority}`);
+    lines.push("triggers:");
+    lines.push(`  task: ${fm.triggers.task}`);
+    lines.push(`  plan: ${fm.triggers.plan}`);
+    lines.push(`  edit: ${fm.triggers.edit}`);
+    lines.push("---");
+    return lines.join("\n");
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { Priority, Triggers, LoadoutEntry, Budget, LoadoutIndex, Frontmatter, MatchResult, IssueSeverity, ValidationIssue, } from "./types.js";
+export { DEFAULT_TRIGGERS } from "./types.js";
+export { parseFrontmatter, serializeFrontmatter } from "./frontmatter.js";
+export { estimateTokens } from "./tokens.js";
+export { matchLoadout, lookupEntry } from "./match.js";
+export { validateIndex } from "./validate.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+export { DEFAULT_TRIGGERS } from "./types.js";
+// ── Frontmatter ────────────────────────────────────────────────
+export { parseFrontmatter, serializeFrontmatter } from "./frontmatter.js";
+// ── Tokens ─────────────────────────────────────────────────────
+export { estimateTokens } from "./tokens.js";
+// ── Matcher ────────────────────────────────────────────────────
+export { matchLoadout, lookupEntry } from "./match.js";
+// ── Validator ──────────────────────────────────────────────────
+export { validateIndex } from "./validate.js";

package/dist/match.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Loadout matcher.
+ *
+ * Given a task description and a loadout index, returns which payload
+ * entries should be loaded, ranked by match strength.
+ *
+ * Matching is deterministic:
+ * - Tokenizes the task into lowercase words
+ * - Scores each entry by keyword and pattern overlap
+ * - Returns entries above a minimum score threshold
+ * - Core entries are always included (score 1.0)
+ * - Manual entries are never auto-included (require explicit lookup)
+ */
+import type { LoadoutIndex, LoadoutEntry, MatchResult } from "./types.js";
+export declare function matchLoadout(task: string, index: LoadoutIndex): MatchResult[];
+export declare function lookupEntry(id: string, index: LoadoutIndex): LoadoutEntry | undefined;

package/dist/match.js

@@ -0,0 +1,84 @@
+/**
+ * Loadout matcher.
+ *
+ * Given a task description and a loadout index, returns which payload
+ * entries should be loaded, ranked by match strength.
+ *
+ * Matching is deterministic:
+ * - Tokenizes the task into lowercase words
+ * - Scores each entry by keyword and pattern overlap
+ * - Returns entries above a minimum score threshold
+ * - Core entries are always included (score 1.0)
+ * - Manual entries are never auto-included (require explicit lookup)
+ */
+const MIN_SCORE = 0.1; // minimum score to include a domain entry
+// ── Tokenize a task description into matchable words ───────────
+function tokenize(text) {
+    return new Set(text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, " ")
+        .split(/\s+/)
+        .filter((w) => w.length > 1));
+}
+// ── Score a single entry against task tokens ───────────────────
+function scoreEntry(entry, taskTokens) {
+    // Core entries always match
+    if (entry.priority === "core") {
+        return { score: 1.0, matchedKeywords: [], matchedPatterns: [] };
+    }
+    // Manual entries never auto-match
+    if (entry.priority === "manual") {
+        return { score: 0, matchedKeywords: [], matchedPatterns: [] };
+    }
+    // Domain entries: score by keyword and pattern overlap
+    const matchedKeywords = [];
+    const matchedPatterns = [];
+    // Keyword matching: each keyword hit contributes to the score
+    for (const kw of entry.keywords) {
+        // Multi-word keywords: check if all words are present
+        const kwWords = kw.split(/[\s-]+/);
+        if (kwWords.every((w) => taskTokens.has(w))) {
+            matchedKeywords.push(kw);
+        }
+    }
+    // Pattern matching: check if any pattern name words appear in the task
+    for (const pattern of entry.patterns) {
+        const patternWords = pattern.split("_");
+        if (patternWords.some((w) => taskTokens.has(w))) {
+            matchedPatterns.push(pattern);
+        }
+    }
+    // Score: proportion of keywords matched + pattern bonus
+    const keywordScore = entry.keywords.length > 0
+        ? matchedKeywords.length / entry.keywords.length
+        : 0;
+    const patternBonus = entry.patterns.length > 0 && matchedPatterns.length > 0
+        ? 0.2
+        : 0;
+    const score = Math.min(1.0, keywordScore + patternBonus);
+    return { score, matchedKeywords, matchedPatterns };
+}
+// ── Match a task against a loadout index ────────────────────────
+// Returns entries that should be loaded, sorted by score (highest first).
+export function matchLoadout(task, index) {
+    const taskTokens = tokenize(task);
+    const results = [];
+    for (const entry of index.entries) {
+        const { score, matchedKeywords, matchedPatterns } = scoreEntry(entry, taskTokens);
+        if (score >= MIN_SCORE) {
+            results.push({ entry, score, matchedKeywords, matchedPatterns });
+        }
+    }
+    // Sort by score descending, then by token cost ascending (prefer cheaper)
+    results.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        return a.entry.tokens_est - b.entry.tokens_est;
+    });
+    return results;
+}
+// ── Look up a specific entry by ID ─────────────────────────────
+// For manual entries or explicit lookup.
+export function lookupEntry(id, index) {
+    return index.entries.find((e) => e.id === id);
+}

package/dist/tests/frontmatter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/frontmatter.test.js

@@ -0,0 +1,87 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { parseFrontmatter, serializeFrontmatter } from "../frontmatter.js";
+import { DEFAULT_TRIGGERS } from "../types.js";
+describe("parseFrontmatter", () => {
+    it("returns null when no delimiters", () => {
+        const { frontmatter, body } = parseFrontmatter("Just content");
+        assert.equal(frontmatter, null);
+        assert.equal(body, "Just content");
+    });
+    it("parses basic frontmatter", () => {
+        const content = "---\nid: test\nkeywords: [ci, deploy]\npriority: domain\n---\n\nBody";
+        const { frontmatter, body } = parseFrontmatter(content);
+        assert.ok(frontmatter);
+        assert.equal(frontmatter.id, "test");
+        assert.deepEqual(frontmatter.keywords, ["ci", "deploy"]);
+        assert.equal(frontmatter.priority, "domain");
+        assert.ok(body.includes("Body"));
+    });
+    it("parses triggers block", () => {
+        const content = "---\nid: t\nkeywords: [x]\npriority: core\ntriggers:\n  task: false\n  plan: true\n  edit: true\n---\nBody";
+        const { frontmatter } = parseFrontmatter(content);
+        assert.ok(frontmatter);
+        assert.equal(frontmatter.triggers.task, false);
+        assert.equal(frontmatter.triggers.plan, true);
+        assert.equal(frontmatter.triggers.edit, true);
+    });
+    it("defaults triggers when missing", () => {
+        const content = "---\nid: t\nkeywords: [x]\npriority: domain\n---\nBody";
+        const { frontmatter } = parseFrontmatter(content);
+        assert.ok(frontmatter);
+        assert.deepEqual(frontmatter.triggers, DEFAULT_TRIGGERS);
+    });
+    it("returns null when id missing", () => {
+        const content = "---\nkeywords: [x]\npriority: domain\n---\nBody";
+        const { frontmatter } = parseFrontmatter(content);
+        assert.equal(frontmatter, null);
+    });
+    it("defaults invalid priority to domain", () => {
+        const content = "---\nid: t\nkeywords: [x]\npriority: bogus\n---\nBody";
+        const { frontmatter } = parseFrontmatter(content);
+        assert.ok(frontmatter);
+        assert.equal(frontmatter.priority, "domain");
+    });
+    it("handles patterns field", () => {
+        const content = "---\nid: t\nkeywords: [x]\npatterns: [ci_pipeline, deploy_flow]\npriority: domain\n---\nBody";
+        const { frontmatter } = parseFrontmatter(content);
+        assert.ok(frontmatter);
+        assert.deepEqual(frontmatter.patterns, ["ci_pipeline", "deploy_flow"]);
+    });
+    it("handles empty keywords gracefully", () => {
+        const content = "---\nid: t\nkeywords: []\npriority: manual\n---\nBody";
+        const { frontmatter } = parseFrontmatter(content);
+        assert.ok(frontmatter);
+        assert.deepEqual(frontmatter.keywords, []);
+    });
+});
+describe("serializeFrontmatter", () => {
+    it("round-trips correctly", () => {
+        const original = {
+            id: "github-actions",
+            keywords: ["ci", "workflow"],
+            patterns: ["ci_pipeline"],
+            priority: "domain",
+            triggers: { task: true, plan: true, edit: false },
+        };
+        const serialized = serializeFrontmatter(original);
+        const { frontmatter } = parseFrontmatter(serialized + "\n\nBody");
+        assert.ok(frontmatter);
+        assert.equal(frontmatter.id, original.id);
+        assert.deepEqual(frontmatter.keywords, original.keywords);
+        assert.deepEqual(frontmatter.patterns, original.patterns);
+        assert.equal(frontmatter.priority, original.priority);
+        assert.deepEqual(frontmatter.triggers, original.triggers);
+    });
+    it("omits empty patterns", () => {
+        const fm = {
+            id: "test",
+            keywords: ["x"],
+            patterns: [],
+            priority: "core",
+            triggers: { task: true, plan: true, edit: false },
+        };
+        const serialized = serializeFrontmatter(fm);
+        assert.ok(!serialized.includes("patterns:"));
+    });
+});

package/dist/tests/match.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/match.test.js

@@ -0,0 +1,88 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { matchLoadout, lookupEntry } from "../match.js";
+import { DEFAULT_TRIGGERS } from "../types.js";
+function makeIndex(...entries) {
+    return {
+        version: "1.0.0",
+        generated: new Date().toISOString(),
+        entries: entries.map((e) => ({
+            id: e.id,
+            path: `.rules/${e.id}.md`,
+            keywords: e.keywords,
+            patterns: e.patterns ?? [],
+            priority: e.priority ?? "domain",
+            summary: `Summary for ${e.id}`,
+            triggers: { ...DEFAULT_TRIGGERS },
+            tokens_est: 100,
+            lines: 10,
+        })),
+        budget: {
+            always_loaded_est: 0,
+            on_demand_total_est: 0,
+            avg_task_load_est: 0,
+            avg_task_load_observed: null,
+        },
+    };
+}
+describe("matchLoadout", () => {
+    it("always includes core entries", () => {
+        const index = makeIndex({ id: "core-rule", keywords: [], priority: "core" }, { id: "domain-rule", keywords: ["ci"], priority: "domain" });
+        const results = matchLoadout("unrelated task", index);
+        assert.equal(results.length, 1);
+        assert.equal(results[0].entry.id, "core-rule");
+        assert.equal(results[0].score, 1.0);
+    });
+    it("never auto-includes manual entries", () => {
+        const index = makeIndex({ id: "manual-rule", keywords: ["ci", "deploy"], priority: "manual" });
+        const results = matchLoadout("fix the ci pipeline and deploy", index);
+        assert.equal(results.length, 0);
+    });
+    it("matches domain entries by keywords", () => {
+        const index = makeIndex({ id: "ci", keywords: ["ci", "workflow", "runner"] }, { id: "shipping", keywords: ["publish", "release", "npm"] });
+        const results = matchLoadout("update the ci workflow", index);
+        assert.equal(results.length, 1);
+        assert.equal(results[0].entry.id, "ci");
+        assert.ok(results[0].matchedKeywords.includes("ci"));
+        assert.ok(results[0].matchedKeywords.includes("workflow"));
+    });
+    it("scores by keyword overlap proportion", () => {
+        const index = makeIndex({ id: "narrow", keywords: ["ci", "workflow", "runner", "matrix", "dependabot"] }, { id: "broad", keywords: ["ci", "workflow"] });
+        const results = matchLoadout("fix the ci workflow", index);
+        // "broad" has 2/2 match (1.0), "narrow" has 2/5 match (0.4)
+        assert.equal(results[0].entry.id, "broad");
+        assert.ok(results[0].score > results[1].score);
+    });
+    it("gives pattern bonus", () => {
+        // Use entries where keyword match is partial so the 0.2 bonus is visible
+        const index = makeIndex({ id: "with-pattern", keywords: ["ci", "workflow", "runner"], patterns: ["ci_pipeline"] }, { id: "without-pattern", keywords: ["ci", "workflow", "runner"] });
+        // Task matches 1/3 keywords (0.33) + pattern bonus (0.2) = 0.53 vs 0.33
+        const results = matchLoadout("fix the ci pipeline", index);
+        const withPattern = results.find((r) => r.entry.id === "with-pattern");
+        const without = results.find((r) => r.entry.id === "without-pattern");
+        assert.ok(withPattern.score > without.score);
+    });
+    it("returns empty for no matches", () => {
+        const index = makeIndex({ id: "ci", keywords: ["ci", "workflow"] });
+        const results = matchLoadout("update the readme", index);
+        assert.equal(results.length, 0);
+    });
+    it("sorts by score descending", () => {
+        const index = makeIndex({ id: "low", keywords: ["ci", "workflow", "runner", "matrix", "dependabot"] }, { id: "high", keywords: ["ci"] });
+        const results = matchLoadout("fix ci", index);
+        assert.equal(results[0].entry.id, "high");
+    });
+});
+describe("lookupEntry", () => {
+    it("finds entry by id", () => {
+        const index = makeIndex({ id: "ci", keywords: ["ci"] }, { id: "shipping", keywords: ["npm"] });
+        const entry = lookupEntry("shipping", index);
+        assert.ok(entry);
+        assert.equal(entry.id, "shipping");
+    });
+    it("returns undefined for missing id", () => {
+        const index = makeIndex({ id: "ci", keywords: ["ci"] });
+        const entry = lookupEntry("nope", index);
+        assert.equal(entry, undefined);
+    });
+});

package/dist/tests/tokens.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/tokens.test.js

@@ -0,0 +1,14 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { estimateTokens } from "../tokens.js";
+describe("estimateTokens", () => {
+    it("estimates ~1 token per 4 chars", () => {
+        assert.equal(estimateTokens("abcd"), 1);
+        assert.equal(estimateTokens("abcde"), 2);
+        assert.equal(estimateTokens(""), 0);
+    });
+    it("handles long text", () => {
+        const text = "a".repeat(400);
+        assert.equal(estimateTokens(text), 100);
+    });
+});

package/dist/tests/validate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/validate.test.js

@@ -0,0 +1,92 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { validateIndex } from "../validate.js";
+import { DEFAULT_TRIGGERS } from "../types.js";
+function makeEntry(overrides = {}) {
+    return {
+        id: "test-rule",
+        path: ".rules/test-rule.md",
+        keywords: ["test"],
+        patterns: [],
+        priority: "domain",
+        summary: "A test rule",
+        triggers: { ...DEFAULT_TRIGGERS },
+        tokens_est: 100,
+        lines: 10,
+        ...overrides,
+    };
+}
+function makeIndex(entries) {
+    return {
+        version: "1.0.0",
+        generated: new Date().toISOString(),
+        entries,
+        budget: {
+            always_loaded_est: 100,
+            on_demand_total_est: 200,
+            avg_task_load_est: 100,
+            avg_task_load_observed: null,
+        },
+    };
+}
+describe("validateIndex", () => {
+    it("passes clean index", () => {
+        const index = makeIndex([makeEntry()]);
+        const issues = validateIndex(index);
+        assert.equal(issues.length, 0);
+    });
+    it("catches missing version", () => {
+        const index = makeIndex([makeEntry()]);
+        index.version = "";
+        const issues = validateIndex(index);
+        assert.ok(issues.some((i) => i.code === "MISSING_VERSION"));
+    });
+    it("catches duplicate IDs", () => {
+        const index = makeIndex([
+            makeEntry({ id: "dupe" }),
+            makeEntry({ id: "dupe" }),
+        ]);
+        const issues = validateIndex(index);
+        assert.ok(issues.some((i) => i.code === "DUPLICATE_ID"));
+    });
+    it("catches missing summary", () => {
+        const index = makeIndex([makeEntry({ summary: "" })]);
+        const issues = validateIndex(index);
+        assert.ok(issues.some((i) => i.code === "MISSING_SUMMARY"));
+    });
+    it("warns on long summary", () => {
+        const index = makeIndex([makeEntry({ summary: "x".repeat(121) })]);
+        const issues = validateIndex(index);
+        assert.ok(issues.some((i) => i.code === "LONG_SUMMARY"));
+    });
+    it("catches empty keywords on domain entries", () => {
+        const index = makeIndex([makeEntry({ priority: "domain", keywords: [] })]);
+        const issues = validateIndex(index);
+        assert.ok(issues.some((i) => i.code === "EMPTY_KEYWORDS"));
+    });
+    it("allows empty keywords on manual entries", () => {
+        const index = makeIndex([makeEntry({ priority: "manual", keywords: [] })]);
+        const issues = validateIndex(index);
+        assert.ok(!issues.some((i) => i.code === "EMPTY_KEYWORDS"));
+    });
+    it("catches missing path", () => {
+        const index = makeIndex([makeEntry({ path: "" })]);
+        const issues = validateIndex(index);
+        assert.ok(issues.some((i) => i.code === "MISSING_PATH"));
+    });
+    it("warns on non-kebab-case ID", () => {
+        const index = makeIndex([makeEntry({ id: "NotKebab" })]);
+        const issues = validateIndex(index);
+        assert.ok(issues.some((i) => i.code === "BAD_ID_FORMAT"));
+    });
+    it("catches invalid priority", () => {
+        const index = makeIndex([makeEntry({ priority: "bogus" })]);
+        const issues = validateIndex(index);
+        assert.ok(issues.some((i) => i.code === "INVALID_PRIORITY"));
+    });
+    it("warns on negative token estimate", () => {
+        const index = makeIndex([makeEntry({ tokens_est: -5 })]);
+        const issues = validateIndex(index);
+        assert.ok(issues.some((i) => i.code === "BAD_TOKEN_EST"));
+    });
+});

package/dist/tokens.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Token estimation.
+ *
+ * Rough heuristic: 1 token ≈ 4 characters for English text.
+ * Good enough for budget dashboards; not meant for billing.
+ */
+export declare function estimateTokens(text: string): number;

package/dist/tokens.js

@@ -0,0 +1,9 @@
+/**
+ * Token estimation.
+ *
+ * Rough heuristic: 1 token ≈ 4 characters for English text.
+ * Good enough for budget dashboards; not meant for billing.
+ */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}

package/dist/types.d.ts

@@ -0,0 +1,50 @@
+export type Priority = "core" | "domain" | "manual";
+export interface Triggers {
+    task: boolean;
+    plan: boolean;
+    edit: boolean;
+}
+export interface LoadoutEntry {
+    id: string;
+    path: string;
+    keywords: string[];
+    patterns: string[];
+    priority: Priority;
+    summary: string;
+    triggers: Triggers;
+    tokens_est: number;
+    lines: number;
+}
+export interface Budget {
+    always_loaded_est: number;
+    on_demand_total_est: number;
+    avg_task_load_est: number;
+    avg_task_load_observed: number | null;
+}
+export interface LoadoutIndex {
+    version: string;
+    generated: string;
+    entries: LoadoutEntry[];
+    budget: Budget;
+}
+export interface Frontmatter {
+    id: string;
+    keywords: string[];
+    patterns: string[];
+    priority: Priority;
+    triggers: Triggers;
+}
+export interface MatchResult {
+    entry: LoadoutEntry;
+    score: number;
+    matchedKeywords: string[];
+    matchedPatterns: string[];
+}
+export type IssueSeverity = "error" | "warning";
+export interface ValidationIssue {
+    severity: IssueSeverity;
+    code: string;
+    message: string;
+    entryId?: string;
+}
+export declare const DEFAULT_TRIGGERS: Triggers;

package/dist/types.js

@@ -0,0 +1,6 @@
+// ── Defaults ───────────────────────────────────────────────────
+export const DEFAULT_TRIGGERS = {
+    task: true,
+    plan: true,
+    edit: false,
+};

package/dist/validate.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Index validator.
+ *
+ * Validates the structural integrity of a LoadoutIndex.
+ * Does NOT check the filesystem — that's the consumer's job
+ * (e.g. claude-rules checks that files exist on disk).
+ *
+ * This validates the data model only:
+ * - Required fields present
+ * - IDs unique and kebab-case
+ * - Summaries present and bounded
+ * - Domain entries have keywords
+ * - No empty arrays where content is expected
+ * - Budget numbers are non-negative
+ */
+import type { LoadoutIndex, ValidationIssue } from "./types.js";
+export declare function validateIndex(index: LoadoutIndex): ValidationIssue[];

package/dist/validate.js

@@ -0,0 +1,148 @@
+/**
+ * Index validator.
+ *
+ * Validates the structural integrity of a LoadoutIndex.
+ * Does NOT check the filesystem — that's the consumer's job
+ * (e.g. claude-rules checks that files exist on disk).
+ *
+ * This validates the data model only:
+ * - Required fields present
+ * - IDs unique and kebab-case
+ * - Summaries present and bounded
+ * - Domain entries have keywords
+ * - No empty arrays where content is expected
+ * - Budget numbers are non-negative
+ */
+const KEBAB_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const VALID_PRIORITIES = new Set(["core", "domain", "manual"]);
+export function validateIndex(index) {
+    const issues = [];
+    // Version check
+    if (!index.version) {
+        issues.push({
+            severity: "error",
+            code: "MISSING_VERSION",
+            message: "Index is missing a version field",
+        });
+    }
+    // Generated timestamp
+    if (!index.generated) {
+        issues.push({
+            severity: "warning",
+            code: "MISSING_GENERATED",
+            message: "Index is missing a generated timestamp",
+        });
+    }
+    // Entries array
+    if (!Array.isArray(index.entries)) {
+        issues.push({
+            severity: "error",
+            code: "INVALID_ENTRIES",
+            message: "Index entries must be an array",
+        });
+        return issues; // can't continue
+    }
+    // Per-entry validation
+    const ids = new Set();
+    for (const entry of index.entries) {
+        // ID required
+        if (!entry.id) {
+            issues.push({
+                severity: "error",
+                code: "MISSING_ID",
+                message: "Entry is missing an id field",
+            });
+            continue;
+        }
+        // ID format
+        if (!KEBAB_RE.test(entry.id)) {
+            issues.push({
+                severity: "warning",
+                code: "BAD_ID_FORMAT",
+                message: `ID "${entry.id}" is not kebab-case`,
+                entryId: entry.id,
+            });
+        }
+        // Duplicate ID
+        if (ids.has(entry.id)) {
+            issues.push({
+                severity: "error",
+                code: "DUPLICATE_ID",
+                message: `Duplicate entry ID: "${entry.id}"`,
+                entryId: entry.id,
+            });
+        }
+        ids.add(entry.id);
+        // Path required
+        if (!entry.path) {
+            issues.push({
+                severity: "error",
+                code: "MISSING_PATH",
+                message: `Entry "${entry.id}" has no path`,
+                entryId: entry.id,
+            });
+        }
+        // Priority valid
+        if (!VALID_PRIORITIES.has(entry.priority)) {
+            issues.push({
+                severity: "error",
+                code: "INVALID_PRIORITY",
+                message: `Entry "${entry.id}" has invalid priority "${entry.priority}"`,
+                entryId: entry.id,
+            });
+        }
+        // Summary required and bounded
+        if (!entry.summary || entry.summary.length === 0) {
+            issues.push({
+                severity: "error",
+                code: "MISSING_SUMMARY",
+                message: `Entry "${entry.id}" has no summary`,
+                entryId: entry.id,
+            });
+        }
+        else if (entry.summary.length > 120) {
+            issues.push({
+                severity: "warning",
+                code: "LONG_SUMMARY",
+                message: `Entry "${entry.id}" summary exceeds 120 chars (${entry.summary.length})`,
+                entryId: entry.id,
+            });
+        }
+        // Domain entries must have keywords
+        if (entry.priority === "domain" && (!entry.keywords || entry.keywords.length === 0)) {
+            issues.push({
+                severity: "error",
+                code: "EMPTY_KEYWORDS",
+                message: `Domain entry "${entry.id}" has no keywords — cannot be routed`,
+                entryId: entry.id,
+            });
+        }
+        // Token estimate sanity
+        if (typeof entry.tokens_est !== "number" || entry.tokens_est < 0) {
+            issues.push({
+                severity: "warning",
+                code: "BAD_TOKEN_EST",
+                message: `Entry "${entry.id}" has invalid token estimate: ${entry.tokens_est}`,
+                entryId: entry.id,
+            });
+        }
+    }
+    // Budget validation
+    if (index.budget) {
+        if (index.budget.always_loaded_est < 0) {
+            issues.push({
+                severity: "warning",
+                code: "NEGATIVE_BUDGET",
+                message: "always_loaded_est is negative",
+            });
+        }
+        if (index.budget.on_demand_total_est < 0) {
+            issues.push({
+                severity: "warning",
+                code: "NEGATIVE_BUDGET",
+                message: "on_demand_total_est is negative",
+            });
+        }
+    }
+    return issues;
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@mcptoolshop/ai-loadout",
+  "version": "1.0.0",
+  "description": "Context-aware knowledge router for AI agents. Dispatch table, frontmatter spec, keyword matcher, token estimator.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "verify": "tsc --noEmit && node --test dist/tests/*.test.js",
+    "test": "node --test dist/tests/*.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "ai",
+    "agent",
+    "loadout",
+    "knowledge",
+    "routing",
+    "dispatch",
+    "context",
+    "frontmatter",
+    "mcp"
+  ],
+  "author": "mcp-tool-shop",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}