lock: Role OS lockdown — dispatch truth seam

Add repo-specific context files and protect-dispatch-truth workflow
with 8 reject criteria. AILOADOUT-001 proving packet passed clean:
7 invariants traced to source, 3 liar-paths rejected, 4 design
tradeoffs named. AILOADOUT-002 queued for malformed layer signaling.

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

Author: mcp-tool-shop

.claude/context/brand-rules.md

@@ -1,10 +1,37 @@
 # Brand Rules — @mcptoolshop/ai-loadout
 
 ## Tone
-Not yet defined (init-only pass).
+
+Precise and mechanical. ai-loadout is a dispatch table, not an advisor. It scores, filters, and reports. It does not recommend, suggest, or infer.
 
 ## Domain language
-Not yet defined (init-only pass).
 
-## Notes
-This repo was initialized during breadth pass. Brand rules will be filled during lock.
+| Term | Meaning | Must not be confused with |
+|------|---------|--------------------------|
+| LoadoutEntry | A declared knowledge payload with ID, keywords, patterns, priority, and token estimate | A "suggestion" or "resource" |
+| LoadPlan | The structured output of planLoad: preload + onDemand + manual with provenance | A "recommendation" or "context plan" |
+| Score | Keyword ratio + pattern bonus (0-1), deterministic | A "relevance estimate" or "confidence" |
+| MIN_SCORE | Hard threshold at 0.1; entries below are excluded | A "soft cutoff" or "guidance threshold" |
+| Layer | One of 4 canonical locations (global/org/project/session) | A "source" or "config level" |
+| Override | Later layer replacing earlier layer's version of same entry ID | A "merge" or "combination" |
+| Provenance | Mapping from entry ID to the layer that provided the winning version | "Origin" in a vague sense |
+| Conflict | Same entry ID defined in multiple layers — always resolved by "later wins" | An "error" or "inconsistency" |
+| Dead entry | An entry that never matches any observed task | An "unused feature" |
+
+## Enforcement bans
+
+### Language that must never appear in ai-loadout output or docs
+
+- "recommended" / "suggested" / "best match" (the system scores and filters, it does not recommend)
+- "confident" / "likely" / "probably relevant" (scores are deterministic ratios, not confidence)
+- "intelligent" / "smart" / "adaptive" (matching is keyword overlap, not inference)
+- "understands" / "knows about" (routing to a payload is not comprehension)
+- "approximately matched" / "close enough" (below MIN_SCORE means excluded, period)
+
+### Contamination risks
+
+1. **Relevance inflation** — if reason strings start implying deeper understanding than keyword overlap, the dispatch truth is compromised
+2. **Capability conflation** — routing to an entry is not the same as the agent having that capability; language must never blur this
+3. **Soft-match creep** — any weakening of MIN_SCORE or introduction of "partial match" zones would destroy the hard-filter contract
+4. **Provenance hiding** — if override chains become invisible to operators, layer trust is undermined
+5. **Freshness pretense** — the system matches against declared keywords; it does not know if payloads are current

.claude/context/current-priorities.md

@@ -1,13 +1,33 @@
 # Current Priorities — @mcptoolshop/ai-loadout
 
 ## Status
-Initialized (Role OS breadth pass 2026-03-24). Not yet locked.
+
+Locked (Role OS lockdown 2026-03-24). Primary seam: knowledge dispatch correctness.
 
 ## Classification
-lock candidate later
 
-## Highest-risk seam
-Matcher correctness — knowledge dispatch must resolve to the right context for the right agent
+Lock candidate → locked.
+
+## Seam family
+
+Dispatch/routing truth — same family as any system where the selector claims correctness about which path/entry/payload was chosen.
+
+## Must-preserve invariants (9)
+
+1. **Scoring determinism** — same task + same index = same MatchResult[] (same scores, order, reasons). No randomness, no heuristics.
+2. **MIN_SCORE hard filter** — domain entries scoring below 0.1 are excluded. No soft-match zone. No "close enough."
+3. **Core always included** — priority="core" entries always get score 1.0 and mode "eager". No exceptions.
+4. **Manual never auto-included** — priority="manual" entries always get score 0. Explicit lookup only.
+5. **Layer order immutability** — global → org → project → session. Later wins. This order is a contract, not a default.
+6. **Override transparency** — every layer override is recorded as a conflict with resolution and provenance. The operator can always see which layer won.
+7. **Reason string machine-readability** — every MatchResult includes a reason string that names the matched keywords and/or patterns. This is the dispatch truth surface.
+8. **Pure-function core** — match, merge, validate, analysis modules have zero I/O, zero side effects. I/O is isolated to resolve/runtime/usage.
+9. **Zero dependencies in matching** — no LLM, no network, no external service. Dispatch is self-contained.
+
+## Banned detours
 
-## Must-preserve invariants
-Not yet documented (init-only pass — invariants will be defined during lock).
+- Adding "fuzzy matching" or "semantic similarity" to the scoring engine (breaks determinism and keyword grounding)
+- Introducing "priority between domain entries" beyond score ranking (scores already rank; adding tiers within domain would obscure the formula)
+- Making MIN_SCORE configurable per-entry or per-layer (destroys the single-threshold contract)
+- Adding "auto-refresh" for stale indexes (the system routes, consumers refresh)
+- Introducing LLM-based matching ("is this entry relevant?") — that's a different product

.claude/context/product-brief.md

@@ -1,19 +1,35 @@
 # Product Brief — @mcptoolshop/ai-loadout
 
 ## What this is
-Context-aware knowledge router for AI agents — dispatch table, matcher, hierarchical resolver
+
+Context-aware knowledge router for AI agents. Maintains a dispatch table of knowledge payloads, matches them against task descriptions using deterministic keyword/pattern scoring, resolves across a 4-layer hierarchy (global → org → project → session), and returns a LoadPlan that separates preload (core), on-demand (matched domain), and manual (everything else) entries — with provenance, conflict tracking, and observability.
 
 ## Type
-CLI + library
+
+CLI + library (pure functions for matching/merging/validation, filesystem I/O only in resolve/runtime layers)
 
 ## Core value
-Context-aware knowledge router for AI agents — dispatch table, matcher, hierarchical resolver
 
-## Non-goals
-- Not documented yet (init-only pass — context will be deepened during lock)
+Dispatch is deterministic, explainable, and observable. Every match result includes a score, matched keywords/patterns, a reason string, and provenance showing which layer the entry came from. The system never guesses — it scores, thresholds, and reports.
+
+## What it is not
+
+- Not a recommender — it matches against declared keywords and patterns, not inferred relevance
+- Not a capability evaluator — it routes to payloads, it does not assess whether payloads are accurate or current
+- Not an LLM — zero model dependency, zero heuristics, zero randomness in matching
+- Not a filesystem manager — consumers are responsible for reading payload files; ai-loadout routes to them
+- Not a quality filter — a matched entry might be stale; ai-loadout's job is to match correctly, not to evaluate freshness
+
+## Anti-thesis (7 statements)
+
+1. Must never become a vibes-based router — dispatch is keyword/pattern scoring, not "feels relevant"
+2. Must never be a "best effort" selector that hides uncertainty — if no entry matches, the result is an empty onDemand list, not a guess
+3. Must never be a capability fantasy layer — the system routes to declared payloads, it does not claim those payloads are true, current, or sufficient
+4. Must never be a silent fallback broker — when a layer is missing, malformed, or overridden, the resolver reports it in searched/conflicts, not silently
+5. Must never become a generic recommender with no dispatch truth — every match must have a score, matched keywords, and a reason
+6. Must never imply a tool/model knows something it was never actually given — routing to a payload is not the same as the agent having read it
+7. Must never soften the MIN_SCORE threshold into a "soft match" zone — below 0.1 means excluded, not "maybe"
 
-## Anti-thesis
-- Not documented yet (init-only pass)
+## Highest-risk seam
 
-## Highest-risk seam (identified, not yet locked)
-Matcher correctness — knowledge dispatch must resolve to the right context for the right agent
+**Knowledge dispatch correctness** — the boundary where the system claims the right loadout was selected. The liar-paths are: wrong match looks right (keywords overlap ambiguously), correct entry excluded by threshold, layer override silently replaces a better version, or stale index routes to outdated payloads.

.claude/context/repo-map.md

@@ -1,11 +1,81 @@
 # Repo Map — @mcptoolshop/ai-loadout
 
 ## Stack
-- See package.json for full dependency list
 
-## Primary seam (identified, not yet locked)
-Matcher correctness — knowledge dispatch must resolve to the right context for the right agent
+- TypeScript (Node.js), zero runtime dependencies
+- 12 source modules, ~2,800 lines
+- Node built-in test runner (8 test files)
+- Single entry: CLI (`bin/ai-loadout`)
+- Library exports for programmatic use
 
-## Validation law
-- See package.json scripts for test/verify commands
-- Init-only pass — detailed repo map will be written during lock
+## Module architecture
+
+| Layer | Modules | Purpose | I/O? |
+|-------|---------|---------|------|
+| Types | `types.ts` | LoadoutEntry, LoadoutIndex, MatchResult, MergedIndex, Budget, etc. | No |
+| Parsing | `frontmatter.ts` | YAML-like frontmatter extraction from markdown payloads | No |
+| Validation | `validate.ts` | Structural validation of indexes (duplicate IDs, missing fields, budget) | No |
+| Matching | `match.ts` | Deterministic keyword/pattern scoring against task descriptions | No |
+| Merging | `merge.ts` | Deterministic layer merge with conflict tracking and provenance | No |
+| Tokens | `tokens.ts` | Token estimation (chars / 4 heuristic) | No |
+| Analysis | `analysis.ts` | Dead entry detection, keyword overlap, budget breakdown | No |
+| Resolution | `resolve.ts` | Layer discovery (4 canonical locations), file loading, merge orchestration | Yes (reads) |
+| Runtime | `runtime.ts` | Agent API: planLoad, recordLoad, manualLookup | Yes (reads + appends) |
+| Usage | `usage.ts` | Append-only JSONL event logging, usage summarization | Yes (reads + appends) |
+| CLI | `cli.ts` | Command router (resolve, explain, usage, dead, overlaps, budget) | Yes |
+| Exports | `index.ts` | Public API surface | No |
+
+**Key architectural property:** All core logic (match, merge, validate, analysis) is pure functions. No filesystem, no network, no side effects. I/O is isolated to resolve/runtime/usage/cli layers.
+
+## Primary seam: Knowledge dispatch correctness
+
+### Dispatch decision flow
+
+```
+planLoad(task)
+  ├─ resolveLoadout()
+  │   ├─ discoverLayers(): check global, org, project, session in fixed order
+  │   │   └─ missing/malformed layers: silently skipped, recorded in searched[]
+  │   └─ mergeIndexes(): later layer overrides earlier for same entry ID
+  │       └─ all overrides tracked as conflicts with resolution: "override"
+  │
+  ├─ matchLoadout(task, merged.index)
+  │   ├─ tokenize(task): lowercase, strip non-alphanum, split, discard ≤1 char
+  │   ├─ scoreEntry() per entry:
+  │   │   ├─ core: score=1.0 (always included)
+  │   │   ├─ manual: score=0 (never auto-included)
+  │   │   └─ domain: (matchedKeywords/totalKeywords) + patternBonus(0.2)
+  │   ├─ filter: score ≥ MIN_SCORE (0.1)
+  │   └─ sort: score desc, then tokens_est asc
+  │
+  └─ separate into: preload (core) / onDemand (domain ≥ 0.1) / manual (rest)
+```
+
+### Contract surfaces that must stay synchronized
+
+| Surface | Location | What it governs |
+|---------|----------|-----------------|
+| MIN_SCORE threshold | `match.ts:17` | Hard boundary: domain entries below 0.1 are excluded |
+| Scoring formula | `match.ts:66-77` | keyword ratio + pattern bonus (0.2), capped at 1.0 |
+| Layer order | `resolve.ts:93-108` | global → org → project → session, fixed |
+| Override rule | `merge.ts` | Later layer wins for same entry ID, always |
+| Reason strings | `match.ts:104-110` | Machine-readable match explanation per entry |
+| Provenance | `merge.ts` → `runtime.ts` | Entry ID → source layer name mapping |
+| Conflict tracking | `merge.ts` | Every override recorded with layers and resolution |
+
+### Liar-path surfaces (where wrong dispatch could look right)
+
+| Risk | Where | Observable? |
+|------|-------|-------------|
+| Ambiguous keywords → wrong entry loads | `match.ts` scoring | Yes: `overlaps` command detects shared keywords |
+| Correct entry excluded by threshold | `match.ts:97` MIN_SCORE filter | No recovery — intentional hard filter |
+| Layer override silently replaces better version | `merge.ts` override logic | Yes: `explain` command shows full override chain |
+| Malformed layer silently skipped | `resolve.ts:122-125` catch block | Partially: marked as not found in searched[], but not distinguishable from genuinely missing |
+| Stale index routes to outdated payloads | Outside system scope | Yes: `dead` + `usage` commands detect drift over time |
+| Token estimate wildly off | `tokens.ts` chars/4 heuristic | Yes: `budget` command compares estimated vs observed |
+
+## Validation
+
+- `npm test` — 8 test files via Node `--test`
+- `npm run build` — TypeScript compilation
+- Key tests: `match.test.ts` (scoring determinism, threshold enforcement), `resolve.test.ts` (layer discovery, merge, conflict tracking)

.claude/workflows/protect-dispatch-truth.md

@@ -0,0 +1,52 @@
+# Workflow: Protect Dispatch Truth
+
+**Repo:** @mcptoolshop/ai-loadout
+**Seam:** Knowledge dispatch correctness — the boundary where the system claims the right loadout was selected for a given task.
+
+## What this workflow protects
+
+The contract that dispatch decisions are deterministic, explainable, and grounded in declared keywords/patterns — and that the system never claims more about a match than the scoring formula actually computed.
+
+## Automatic reject criteria (8)
+
+A proposed change MUST be rejected if it:
+
+1. **Makes dispatch reasoning less explicit** — removes or weakens reason strings, provenance tracking, or conflict reporting so the operator cannot trace why an entry was selected
+2. **Weakens deterministic selection rules** — introduces randomness, heuristics, LLM-based scoring, or environment-dependent behavior into the matching engine
+3. **Blurs primary selection with fallback/degraded selection** — frames an empty onDemand result as though entries were found, or hides that layers were missing/malformed
+4. **Invents or overstates capability/knowledge access** — implies that routing to a payload means the agent has that knowledge, or that a matched entry is accurate/current
+5. **Allows stale capability assumptions to masquerade as current truth** — weakens observability tools (dead entry detection, usage tracking, budget analysis) that catch staleness
+6. **Softens failure or mismatch classification into advisory mush** — converts the MIN_SCORE hard filter into a soft boundary, introduces "partial match" zones, or makes excluded entries appear as weak recommendations
+7. **Changes output semantics without synchronized docs/tests/context updates** — modifies LoadPlan structure, reason string format, provenance shape, or conflict reporting without updating all consumers
+8. **Makes human-facing reassurance stronger while leaving machine-facing semantics unchanged** — e.g., CLI output says "good coverage" while LoadPlan shows most entries in manual (org-wide reassurance drift rule)
+
+## The key question this workflow answers
+
+**When ai-loadout chooses a loadout, what must it say about why, and what must it never imply about capability or knowledge access?**
+
+### Must say
+- Score: the exact keyword ratio + pattern bonus (0-1)
+- Matched keywords: which declared keywords were found in the task
+- Matched patterns: which declared patterns triggered
+- Reason: human-readable explanation combining the above
+- Mode: eager (core), lazy (domain match), or manual (explicit lookup only)
+- Provenance: which layer provided the winning version of each entry
+- Conflicts: which entries were overridden and by which layers
+
+### Must never imply
+- That a matched entry means the agent has that knowledge (routing ≠ loading ≠ comprehension)
+- That a high score means high relevance (score is keyword overlap ratio, not semantic relevance)
+- That an entry's declared keywords are current (the system matches against declarations, not reality)
+- That missing layers are errors (most setups only have project-level; missing layers are normal)
+- That an empty onDemand list means no relevant knowledge exists (it means no declared entry matched — the knowledge might exist but not be indexed)
+- That a conflict was resolved "correctly" (later-wins is a rule, not a judgment)
+
+## When to re-prove
+
+Re-prove this workflow when:
+- The scoring formula changes (keyword weighting, pattern bonus, threshold)
+- The layer discovery or merge algorithm changes
+- MIN_SCORE value changes
+- New match modes are added beyond eager/lazy/manual
+- Reason string format changes
+- The LoadPlan output shape changes