feat(hook): self-contain via esbuild + new-scoring matcher + 0.5 floor (cutover prep)

Retiring published ai-loadout, so the runtime hook can no longer import it. esbuild bundle (apps/hook/esbuild.config.mjs, like the CLI) inlines the workspace kernel's new recall-aware matcher into apps/hook/dist/loadout-hook.mjs — dependency-free deployable. Floor default 0.3 -> 0.5 (re-derived for the new max(coverage, matched/5) scoring; AI_LOADOUT_MIN_SCORE override kept). ai-loadout moved deps->devDeps in apps/hook (inlined). smoke-test.ps1 drift check now compares the live hook against the freshly-built BUNDLE (default -HookPath bundle). Standalone-verified: self-contained, recall fix live (game-canon prompt scores 0.8-1.0), 0.5 floor silences noise, fail-silent intact.

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

Author: mcp-tool-shop

apps/hook/esbuild.config.mjs

@@ -0,0 +1,85 @@
+/**
+ * Bundle the loadout runtime hook into ONE self-contained ESM file.
+ *
+ * Why this exists: the LIVE hook (~/.claude/loadout-hook/loadout-hook.mjs) runs
+ * from a directory with NO node_modules. The SOURCE hook (apps/hook/loadout-hook.mjs)
+ * does `await import('@mcptoolshop/ai-loadout')` to get the matcher — fine in the
+ * workspace (it resolves to packages/kernel via the node_modules symlink), but a
+ * MODULE_NOT_FOUND in the deployed location. Published ai-loadout is being retired,
+ * so the hook can no longer depend on it being installed.
+ *
+ * The fix mirrors packages/cli/esbuild.config.mjs: esbuild INLINES the kernel
+ * (= @mcptoolshop/ai-loadout, the workspace packages/kernel, carrying the NEW
+ * recall-aware scoring) into a single dependency-free deployable. Node builtins
+ * (fs, path, os) stay external — always present at runtime.
+ *
+ *   SOURCE (apps/hook/loadout-hook.mjs)      → keeps the import; resolves to the
+ *                                              workspace kernel for dev/readability.
+ *   BUNDLE (apps/hook/dist/loadout-hook.mjs) → import inlined; this is what the
+ *                                              coordinator copies to the live hook.
+ *
+ * Format choice: ESM. The kernel is `"type": "module"` ESM and the hook source is
+ * already ESM (top-level await on the dynamic import). Bundling to ESM preserves
+ * those semantics with zero shims. The `#!/usr/bin/env node` shebang on line 1 of
+ * the source is preserved verbatim by esbuild; a post-bundle assertion verifies
+ * exactly one shebang on line 1 (a malformed shebang silently breaks the hook).
+ *
+ * Standards compliance (workflow-standards.md):
+ *   PIN_PER_STEP 2 — the bundle is a deterministic, replayable artifact of the
+ *     pinned source + pinned esbuild version (devDependencies) at a fixed target
+ *     (node20); no network, no nondeterministic input.
+ *   ANDON_AUTHORITY 2 — esbuild fails the build (non-zero) on any unresolved
+ *     import, and the shebang assertion below halts on a malformed artifact; a
+ *     broken bundle never reaches the coordinator's cutover.
+ *   EXTERNAL_VERIFIER 1 — the standalone proof (run the emitted bundle from a
+ *     clean temp dir with no node_modules) is run by the operator/coordinator, not
+ *     baked in here. skip: a build script is not a multi-model pipeline.
+ *   Remaining standards (NAMED_COMPENSATORS / DECOMPOSE_BY_SECRETS /
+ *     UNCERTAINTY_GATED_HUMANS) skip: this step performs no irreversible tool call
+ *     (it only writes dist/loadout-hook.mjs, overwritten on every run) and has no
+ *     human checkpoint. The cutover to the LIVE hook is the coordinator's step.
+ */
+
+import { build } from "esbuild";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const entry = join(here, "loadout-hook.mjs");
+const outfile = join(here, "dist", "loadout-hook.mjs");
+
+await build({
+  entryPoints: [entry],
+  outfile,
+  bundle: true,
+  platform: "node",
+  format: "esm",
+  target: "node20",
+  // The executable shebang is preserved from the entry (loadout-hook.mjs opens
+  // with `#!/usr/bin/env node`); esbuild keeps a leading hashbang verbatim. We do
+  // NOT add a `banner` shebang — that would duplicate it. The assertion below
+  // verifies exactly one shebang on line 1.
+  // Inline EVERYTHING (the @mcptoolshop/ai-loadout workspace kernel included).
+  // Only Node's own builtins stay external — always present at runtime.
+  packages: undefined,
+  external: [],
+  logLevel: "info",
+  sourcemap: false,
+  legalComments: "none",
+});
+
+// ANDON: a malformed shebang silently breaks the deployed hook (Claude Code runs
+// it as an executable). Assert exactly one `#!/usr/bin/env node` and that it is line 1.
+const out = readFileSync(outfile, "utf8");
+const lines = out.split("\n");
+const shebangCount = lines.filter((l) => l.startsWith("#!")).length;
+if (lines[0] !== "#!/usr/bin/env node" || shebangCount !== 1) {
+  console.error(
+    `bundle shebang check failed: expected exactly one '#!/usr/bin/env node' on line 1, ` +
+      `got ${shebangCount} hashbang line(s); line 1 = ${JSON.stringify(lines[0])}`,
+  );
+  process.exit(1);
+}
+
+console.log(`bundled → ${outfile} (${(out.length / 1024).toFixed(1)} kb, shebang OK)`);

apps/hook/loadout-hook.mjs

@@ -14,7 +14,7 @@
 //   • AI_LOADOUT_HOOK=debug     → print why-silent + top near-misses to STDERR only
 //                                 (never stdout; the suppressOutput / fail-silent
 //                                 contract and the ≤200-token budget are untouched)
-//   • AI_LOADOUT_MIN_SCORE=<n>  → override the score floor (default 0.3) for
+//   • AI_LOADOUT_MIN_SCORE=<n>  → override the score floor (default 0.5) for
 //                                 calibration, without an edit + mirror→live cutover
 // Latency budget: < 500 ms cold. Never blocks.
 
@@ -32,14 +32,17 @@ const USAGE_PATH = resolve(HOME, '.ai-loadout', 'usage.jsonl');
 const MAX_ENTRIES = 5;
 const MAX_LINE_CHARS = 180;
 // Minimum match score for a DOMAIN entry to be injected. Core entries (score 1.0)
-// always pass. Calibrated 2026-06-16 against the live 336-entry index: observed
-// incidental single-keyword noise tops out at ~0.25, genuine topical matches begin
-// ~0.33+, so 0.3 is the "confident match" floor that delivers the design's
-// "below-threshold → emit nothing". Override per-run with AI_LOADOUT_MIN_SCORE for
-// calibration without an edit + cutover. Recall on keyword-rich entries (e.g. game
-// canon) is a separate Phase-2 keyword-curation concern, not this floor's job.
+// always pass. Re-calibrated 2026-06-16 for the NEW recall-aware scoring in the
+// inlined kernel matcher: score = max(coverage, matched/ABSOLUTE_K=5) + patternBonus.
+// Under this blend a genuine multi-keyword match lands at ~0.6+ (3 matched keywords
+// → absolute 3/5 = 0.6, plus the 0.2 patternBonus if a pattern also fires), while
+// incidental / generic single- or double-keyword noise tops out around ~0.4
+// (2/5 = 0.4). So 0.5 is the new "confident match" floor that delivers the design's
+// "below-threshold → emit nothing" (was 0.3 under the OLD matched/total coverage
+// scoring, where genuine matches began ~0.33). Override per-run with
+// AI_LOADOUT_MIN_SCORE for calibration without an edit + cutover.
 const _envMin = Number(process.env.AI_LOADOUT_MIN_SCORE);
-const HOOK_MIN_SCORE = Number.isFinite(_envMin) ? _envMin : 0.3;
+const HOOK_MIN_SCORE = Number.isFinite(_envMin) ? _envMin : 0.5;
 
 // Debug diagnostics → STDERR only (never stdout, so suppressOutput + fail-silent
 // are preserved). Answers "why was the hook silent on a prompt I expected a hit for".

apps/hook/package.json

@@ -7,12 +7,14 @@
   "main": "loadout-hook.mjs",
   "scripts": {
     "test": "node --check loadout-hook.mjs",
+    "bundle": "node esbuild.config.mjs",
     "smoke": "pwsh -NoProfile -File smoke-test.ps1"
   },
   "engines": {
     "node": ">=20"
   },
-  "dependencies": {
-    "@mcptoolshop/ai-loadout": "^1.4.3"
+  "devDependencies": {
+    "@mcptoolshop/ai-loadout": "^1.4.3",
+    "esbuild": "^0.28.1"
   }
 }

apps/hook/smoke-test.ps1

@@ -2,41 +2,61 @@
 <#
   Smoke test for the loadout hook.
 
-  - Drift check (HOK-05): mirror (apps/hook) vs live (~/.claude/loadout-hook) must be byte-identical.
-  - Threshold check (HOK-01): drives the hook with representative prompts and shows what it injects.
-    A min-score floor means weak/incidental matches and off-topic prompts go silent.
+  - Drift check (HOK-05): the LIVE hook (~/.claude/loadout-hook) must be byte-identical
+    to the BUNDLE (apps/hook/dist/loadout-hook.mjs) — the dependency-free deployable
+    that the coordinator copies to the live location. (The source loadout-hook.mjs is
+    NOT the deployable: it `import`s @mcptoolshop/ai-loadout, which the live dir cannot
+    resolve. The bundle inlines the kernel matcher.) The bundle is (re)built here first.
+  - Threshold check (HOK-01): drives the hook with representative prompts and shows what
+    it injects. The min-score floor (default 0.5 under the recall-aware scoring) means
+    weak/incidental matches and off-topic prompts go silent.
 
   Isolation: runs the hook under a SCRATCH HOME (a copy of the live ~/.ai-loadout/index.json),
   so testing never appends to the live usage.jsonl.
 
   Usage:
-    ./smoke-test.ps1                 # tests the MIRROR copy (this repo) by default
-    ./smoke-test.ps1 -HookPath live  # tests the LIVE copy (~/.claude/loadout-hook)
+    ./smoke-test.ps1                  # tests the BUNDLE (apps/hook/dist) by default
+    ./smoke-test.ps1 -HookPath source # tests the SOURCE copy (needs the workspace node_modules)
+    ./smoke-test.ps1 -HookPath live   # tests the LIVE copy (~/.claude/loadout-hook)
 #>
 param(
-  [string]$HookPath = 'mirror'
+  [ValidateSet('bundle', 'source', 'live')]
+  [string]$HookPath = 'bundle'
 )
 $ErrorActionPreference = 'Continue'
 
-$mirror = Join-Path $PSScriptRoot 'loadout-hook.mjs'
+$source = Join-Path $PSScriptRoot 'loadout-hook.mjs'
+$bundle = Join-Path $PSScriptRoot 'dist/loadout-hook.mjs'
 $live   = Join-Path $HOME '.claude/loadout-hook/loadout-hook.mjs'
 
-# ── Drift check (HOK-05) ────────────────────────────────────────
+# ── (Re)build the bundle so the drift check compares against a fresh artifact ──
 Write-Output ('=' * 78)
-Write-Output 'DRIFT CHECK — mirror vs live (must be byte-identical)'
+Write-Output 'BUILD — esbuild bundle (apps/hook/dist/loadout-hook.mjs)'
 Write-Output ('=' * 78)
-$mirrorHash = (Get-FileHash $mirror -Algorithm SHA256).Hash
+& node (Join-Path $PSScriptRoot 'esbuild.config.mjs')
+if ($LASTEXITCODE -ne 0) { Write-Output "BUILD FAILED (esbuild exit $LASTEXITCODE)"; exit 1 }
+Write-Output ''
+
+# ── Drift check (HOK-05): live must equal the BUNDLE ────────────
+Write-Output ('=' * 78)
+Write-Output 'DRIFT CHECK — live vs bundle (must be byte-identical)'
+Write-Output ('=' * 78)
+$bundleHash = (Get-FileHash $bundle -Algorithm SHA256).Hash
 if (Test-Path $live) {
   $liveHash = (Get-FileHash $live -Algorithm SHA256).Hash
-  if ($mirrorHash -eq $liveHash) { Write-Output "OK — identical ($mirrorHash)" }
-  else { Write-Output "DRIFT — mirror=$mirrorHash  live=$liveHash" }
+  if ($bundleHash -eq $liveHash) { Write-Output "OK — identical ($bundleHash)" }
+  else { Write-Output "DRIFT — bundle=$bundleHash  live=$liveHash" }
 } else {
   Write-Output "live copy not found at $live"
 }
 Write-Output ''
 
 # ── Resolve which hook to drive ─────────────────────────────────
-$hook = if ($HookPath -eq 'live') { $live } else { $mirror }
+$hook = switch ($HookPath) {
+  'live'   { $live }
+  'source' { $source }
+  default  { $bundle }
+}
 Write-Output "Driving: $hook"
 Write-Output ''