feat(hook): debug mode + score logging + env-override floor + shape guard

Stage-C observability for the live hook (HOK-B1..B5), all stderr-only so suppressOutput/fail-silent + the <=200-token budget are untouched. AI_LOADOUT_HOOK=debug explains every silent path and prints top near-misses below the floor; usage events now record score + reason + taskHashSource (so the floor can be re-calibrated from field data and timestamp-fallback events aren't counted as distinct tasks); AI_LOADOUT_MIN_SCORE overrides the 0.3 floor without an edit+cutover; a shape guard distinguishes a malformed index from a missing one. package.json test no longer deadlocks on stdin (node --check) + adds engines. Applied mirror+live byte-identical (hash E45F6BE0...); compensator backup loadout-hook.mjs.bak-pre-hokb-20260616.

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

Author: mcp-tool-shop

apps/hook/loadout-hook.mjs

@@ -7,9 +7,15 @@
 //   • Emit AT MOST 5 entries as one-line pointers: "- <id> — <summary> → <path>"
 //   • Total additionalContext kept ≤ ~200 tokens
 //   • Below-threshold match (score < HOOK_MIN_SCORE) → emit nothing (silent)
-//   • Always-record loaded events to ~/.ai-loadout/usage.jsonl
+//   • Always-record loaded events to ~/.ai-loadout/usage.jsonl (incl. score + reason)
 //
-// Off-switch: AI_LOADOUT_HOOK=off  no-op exit 0.
+// Switches (env):
+//   • AI_LOADOUT_HOOK=off       → no-op exit 0
+//   • 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
+//                                 calibration, without an edit + mirror→live cutover
 // Latency budget: < 500 ms cold. Never blocks.
 
 import { readFileSync, appendFileSync, existsSync, mkdirSync } from 'node:fs';
@@ -29,9 +35,19 @@ const MAX_LINE_CHARS = 180;
 // 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". Recall on keyword-rich entries (e.g. game
+// "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.
-const HOOK_MIN_SCORE = 0.3;
+const _envMin = Number(process.env.AI_LOADOUT_MIN_SCORE);
+const HOOK_MIN_SCORE = Number.isFinite(_envMin) ? _envMin : 0.3;
+
+// 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".
+const DEBUG = process.env.AI_LOADOUT_HOOK === 'debug';
+function debug(msg) {
+  if (!DEBUG) return;
+  try { process.stderr.write('[loadout-hook] ' + msg + '\n'); } catch { /* ignore */ }
+}
 
 function readStdinSync() {
   try {
@@ -53,30 +69,39 @@ function clip(s, n) {
 }
 
 async function main() {
-  if (!existsSync(INDEX_PATH)) { safeExit(0); return; }
+  if (!existsSync(INDEX_PATH)) { debug('silent: no index at ' + INDEX_PATH); safeExit(0); return; }
 
   const stdin = readStdinSync();
   let payload;
-  try { payload = JSON.parse(stdin); } catch { safeExit(0); return; }
+  try { payload = JSON.parse(stdin); } catch { debug('silent: stdin is not valid JSON'); safeExit(0); return; }
   const prompt = (payload.prompt || payload.user_prompt || payload.message || '').toString();
-  if (!prompt.trim()) { safeExit(0); return; }
+  if (!prompt.trim()) { debug('silent: empty prompt'); safeExit(0); return; }
 
   let index;
-  try { index = JSON.parse(readFileSync(INDEX_PATH, 'utf8')); } catch { safeExit(0); return; }
+  try { index = JSON.parse(readFileSync(INDEX_PATH, 'utf8')); } catch { debug('silent: index is not valid JSON'); safeExit(0); return; }
+  // Shape guard: a valid-but-wrong index would otherwise throw inside matchLoadout
+  // and look identical to "no index". Surface the difference in debug mode.
+  if (!index || !Array.isArray(index.entries)) { debug('silent: index parsed but has no entries[] array (malformed)'); safeExit(0); return; }
 
   let matchLoadout;
   try {
     ({ matchLoadout } = await import('@mcptoolshop/ai-loadout'));
   } catch {
+    debug('silent: could not import @mcptoolshop/ai-loadout');
     safeExit(0); return;
   }
 
   let results;
-  try { results = matchLoadout(prompt, index); } catch { safeExit(0); return; }
-  const top = (results || [])
-    .filter(r => r && r.entry && r.entry.priority !== 'manual' && r.score >= HOOK_MIN_SCORE)
-    .slice(0, MAX_ENTRIES);
-  if (top.length === 0) { safeExit(0); return; }
+  try { results = matchLoadout(prompt, index); } catch { debug('silent: matchLoadout threw'); safeExit(0); return; }
+  const eligible = (results || []).filter(r => r && r.entry && r.entry.priority !== 'manual');
+  const top = eligible.filter(r => r.score >= HOOK_MIN_SCORE).slice(0, MAX_ENTRIES);
+  if (top.length === 0) {
+    if (DEBUG) {
+      const near = eligible.slice(0, 3).map(r => `${(r.score ?? 0).toFixed(3)} ${r.entry.id} (${r.reason || ''})`);
+      debug(`silent: no match ≥ floor ${HOOK_MIN_SCORE}. top near-misses: ` + (near.length ? near.join(' | ') : '(none)'));
+    }
+    safeExit(0); return;
+  }
 
   const lines = top.map(r => {
     const id  = r.entry.id || '(unnamed)';
@@ -89,22 +114,34 @@ async function main() {
     '[loadout-hook] Memory entries relevant to this prompt (open the file pointer before acting, do not paraphrase from the summary):\n' +
     lines.join('\n');
 
-  // Record usage (best-effort; never block)
+  // Record usage (best-effort; never block). Records score + reason so the floor can
+  // be re-calibrated from field data (ai-loadout usage/dead), and a taskHashSource
+  // marker so ungroupable (timestamp-fallback) events aren't counted as distinct tasks.
   try {
     if (!existsSync(dirname(USAGE_PATH))) mkdirSync(dirname(USAGE_PATH), { recursive: true });
     const ts = new Date().toISOString();
-    const taskHash = (payload.prompt_id || payload.session_id || '').toString().slice(0, 12) || ts.replace(/[-:.TZ]/g, '').slice(0, 14);
+    const sessionId = (payload.session_id || '').toString();
+    const promptId = (payload.prompt_id || '').toString();
+    let taskHash, taskHashSource;
+    if (sessionId) { taskHash = sessionId.slice(0, 12); taskHashSource = 'session'; }
+    else if (promptId) { taskHash = promptId.slice(0, 12); taskHashSource = 'prompt'; }
+    else { taskHash = ts.replace(/[-:.TZ]/g, '').slice(0, 14); taskHashSource = 'timestamp'; }
     const events = top.map(r => JSON.stringify({
       timestamp: ts,
       taskHash,
+      taskHashSource,
       entryId: r.entry.id,
       trigger: 'UserPromptSubmit',
       mode: r.mode || 'lazy',
+      score: typeof r.score === 'number' ? r.score : null,
+      reason: r.reason || '',
       tokensEst: r.entry.tokens_est || 0
     })).join('\n') + '\n';
     appendFileSync(USAGE_PATH, events, 'utf8');
   } catch { /* swallow */ }
 
+  if (DEBUG) debug(`injected ${top.length} pointer(s): ` + top.map(r => `${r.entry.id}@${(r.score ?? 0).toFixed(3)}`).join(', '));
+
   process.stdout.write(JSON.stringify({
     suppressOutput: true,
     hookSpecificOutput: {

apps/hook/package.json

@@ -6,7 +6,11 @@
   "description": "UserPromptSubmit hook that injects pointers to relevant memory entries from ~/.ai-loadout/index.json",
   "main": "loadout-hook.mjs",
   "scripts": {
-    "test": "node loadout-hook.mjs"
+    "test": "node --check loadout-hook.mjs",
+    "smoke": "pwsh -NoProfile -File smoke-test.ps1"
+  },
+  "engines": {
+    "node": ">=20"
   },
   "dependencies": {
     "@mcptoolshop/ai-loadout": "^1.4.3"