fix(kb): address code-review findings on the auto-routing hook

Adversarial multi-agent review of the kb-mod-cacg branch surfaced these
(all verified against the real kb binary + the test suite):

- SIGPIPE/exit-5 abort: extracting the prompt via `... | head -c 2000` under
  pipefail aborted the hook on >64KB prompts (141) and on malformed stdin (5).
  Now extract with `|| true` and truncate in-shell (char-based, no mid-UTF8 split).
- No time bound: wrap `kb search` in run_with_timeout (repo convention); the
  existing `|| exit 0` already turns a 124 into a clean no-op.
- Flag-like prompts: pass the query after `--` so a prompt starting with '-'
  is not misparsed by clap and dropped.
- Context-injection hardening: scrub newlines from .title/.path/.card_id (not
  just .summary) so a tampered card cannot forge a heading in additionalContext.
- Injected hint now points at `.claude/knowledge/kb-query.sh show <card_id>`
  (resolved from the discovered KB root) instead of bare `kb show` (which needs
  --source-matrix and would error if run literally).
- kb_top_k now clamps to [1,25] so the injected block stays bounded at source.
- Codex prompts: qualify the `kb verify --round-summary` command as requiring a
  verify-tier export (the default query tier omits chunks_manifest.json).
- Tests (16 -> 27): mock kb now logs argv + is query-sensitive, so the suite
  asserts the prompt->search plumbing (verb, query-after-`--`, --source-matrix/
  --summaries/--top-k wiring); adds malformed-stdin (exit 0), >64KB prompt (no
  SIGPIPE), top-k clamp, and kb_discover_root/kb_resolve_binary override cases.

test-kb-provenance-format.sh stays 25/25; config-merge + bitlesson green.

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

Author: jake

hooks/kb-knowledge-route.sh

@@ -24,6 +24,7 @@ PLUGIN_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 source "$SCRIPT_DIR/lib/project-root.sh"
 source "$PLUGIN_ROOT/scripts/lib/config-loader.sh"
 source "$PLUGIN_ROOT/scripts/lib/kb-route-lib.sh"
+source "$PLUGIN_ROOT/scripts/portable-timeout.sh"   # run_with_timeout (falls back to direct exec if unavailable)
 
 # jq is mandatory for both config parsing and result shaping; without it, no-op.
 command -v jq >/dev/null 2>&1 || exit 0
@@ -51,31 +52,38 @@ KB_BIN="$(kb_resolve_binary "$MERGED")" || exit 0
 
 SM="$KB_ROOT/out/$DECK/source_matrix.json"
 SUM="$KB_ROOT/out/$DECK/summaries.json"
+# Project-relative path to the exported query wrapper (falls back to absolute if KB is outside the project).
+QUERY_REL="${KB_ROOT#"$PROJECT_ROOT"/}/kb-query.sh"
 
-# Extract the user prompt; cap the query length so a huge paste stays a sane query.
-PROMPT="$(printf '%s' "$INPUT" | jq -r '.prompt // empty' 2>/dev/null | head -c 2000)"
+# Extract the user prompt and cap its length. Truncate in-shell (char-based) rather than
+# piping to `head -c`: under `set -o pipefail` a >64KB prompt SIGPIPE-kills the pipeline
+# (exit 141) and `jq` on malformed stdin exits 5 — both would abort the hook instead of
+# no-op'ing. `|| true` + ${var:0:N} keeps every path graceful and avoids mid-UTF8 byte splits.
+PROMPT="$(printf '%s' "$INPUT" | jq -r '.prompt // empty' 2>/dev/null || true)"
+PROMPT="${PROMPT:0:2000}"
 [[ -n "${PROMPT//[[:space:]]/}" ]] || exit 0
 
-# Deterministic search. Failure (bad manifest, version drift, etc.) -> no-op.
-HITS="$("$KB_BIN" search "$PROMPT" --json --source-matrix "$SM" --summaries "$SUM" --top-k "$TOP_K" 2>/dev/null)" || exit 0
+# Deterministic search, time-bounded (a wedged/huge corpus must not hang the prompt). `--`
+# ends option parsing so a prompt beginning with '-' is taken as the QUERY, not a flag.
+HITS="$(run_with_timeout "${KB_SEARCH_TIMEOUT:-10}" "$KB_BIN" search --json --source-matrix "$SM" --summaries "$SUM" --top-k "$TOP_K" -- "$PROMPT" 2>/dev/null)" || exit 0
 printf '%s' "$HITS" | jq -e 'type == "array" and length > 0' >/dev/null 2>&1 || exit 0
 
 # Render the suggestion block. The framing is load-bearing: these are SUGGESTIONS,
 # not provenance. `kb verify --round-summary` treats the `## Knowledge Consulted`
 # section as authoritative, so this block must not be copied wholesale into it.
-BLOCK="$(printf '%s' "$HITS" | jq -r --arg deck "$DECK" '
+BLOCK="$(printf '%s' "$HITS" | jq -r --arg deck "$DECK" --arg wrapper "$QUERY_REL" '
   "## CACG Knowledge — auto-routed matches (deck: \($deck))\n"
-  + "Search suggestions only. Open a card with `kb show <card_id>` (or read its `.md`) and cite it in your round summary'"'"'s `## Knowledge Consulted` section ONLY if you actually opened and used it.\n\n"
+  + "Search suggestions only. Open a card with `\($wrapper) show <card_id>` (or read its `.md`) and cite it in your round summary'"'"'s `## Knowledge Consulted` section ONLY if you actually opened and used it.\n\n"
   + ( [ .[]
-        | "- `\(.path)` (\(.card_id)) — \(.title): "
+        | "- `\((.path // "") | gsub("[\r\n]+";" "))` (\((.card_id // "") | gsub("[\r\n]+";" "))) — \((.title // "") | gsub("[\r\n]+";" ") | .[0:200]): "
           + ((.summary // "") | gsub("[\r\n]+"; " ") | .[0:200])
       ] | join("\n") )
 ')"
 
 # Hard byte cap so a pathological corpus can never bloat every prompt.
 MAX_BYTES=4096
 if [[ "$(printf '%s' "$BLOCK" | wc -c)" -gt "$MAX_BYTES" ]]; then
-    BLOCK="$(printf '%s' "$BLOCK" | head -c "$MAX_BYTES")"$'\n- … (truncated)'
+    BLOCK="$(printf '%s' "$BLOCK" | head -c "$MAX_BYTES" || true)"$'\n- … (truncated)'
 fi
 
 jq -n --arg ctx "$BLOCK" \

prompt-template/codex/full-alignment-review.md

@@ -74,7 +74,7 @@ The `Mainline Progress Verdict` line is mandatory. If you omit it, the Humanize
 - Verify Claude's claims match reality
 - Identify any gaps, bugs, or incomplete work
 - Reference @{{DOCS_PATH}} for design documents
-- **Knowledge Provenance Check**: Verify Claude's summary includes a `## Knowledge Consulted` section listing concrete reference files (e.g. CACG cards under `.claude/knowledge/cards/<deck>/**/*.md`, other `.claude/knowledge/**/*.md`, vendor manuals, paper PDFs, metric manifests) or the exact string `N/A -- task not KB-relevant this round`. If the section is missing on KB-relevant work, or if `N/A` is used as a shortcut for domain-specific / modeling / metrics tasks, flag as a Blocking Side Issue. When a CACG export is present, the cited card paths can be content-verified with `kb verify --round-summary <summary-file> --source-matrix .claude/knowledge/out/<deck>/source_matrix.json --chunks-manifest .claude/knowledge/out/<deck>/chunks_manifest.json`.
+- **Knowledge Provenance Check**: Verify Claude's summary includes a `## Knowledge Consulted` section listing concrete reference files (e.g. CACG cards under `.claude/knowledge/cards/<deck>/**/*.md`, other `.claude/knowledge/**/*.md`, vendor manuals, paper PDFs, metric manifests) or the exact string `N/A -- task not KB-relevant this round`. If the section is missing on KB-relevant work, or if `N/A` is used as a shortcut for domain-specific / modeling / metrics tasks, flag as a Blocking Side Issue. When a **verify-tier (or full)** CACG export is present (`chunks_manifest.json` ships only at `--tier verify` and above; the default `query` tier omits it), the cited card paths can be content-verified with `kb verify --round-summary <summary-file> --source-matrix .claude/knowledge/out/<deck>/source_matrix.json --chunks-manifest .claude/knowledge/out/<deck>/chunks_manifest.json`.
 
 ## Part 4: {{GOAL_TRACKER_UPDATE_SECTION}}
 

prompt-template/codex/regular-review.md

@@ -35,7 +35,7 @@ Below is Claude's summary of the work completed:
   - Your review should elaborate on those unfinished tasks, explore the codebase, and draft an implementation plan.
   - A good engineering implementation plan should be **singular, directive, and definitive**, rather than discussing multiple possible implementation options.
   - The implementation plan should be **unambiguous**, internally consistent, and coherent from beginning to end, so that **Claude can execute the work accurately and without error**.
-- **Knowledge Provenance Check**: Verify Claude's summary includes a `## Knowledge Consulted` section listing concrete reference files (e.g. CACG cards under `.claude/knowledge/cards/<deck>/**/*.md`, other `.claude/knowledge/**/*.md`, vendor manuals, paper PDFs, metric manifests) or the exact string `N/A -- task not KB-relevant this round`. If the section is missing on KB-relevant work, or if `N/A` is used as a shortcut for domain-specific / modeling / metrics tasks, flag as a Blocking Side Issue. When a CACG export is present, the cited card paths can be content-verified with `kb verify --round-summary <summary-file> --source-matrix .claude/knowledge/out/<deck>/source_matrix.json --chunks-manifest .claude/knowledge/out/<deck>/chunks_manifest.json`.
+- **Knowledge Provenance Check**: Verify Claude's summary includes a `## Knowledge Consulted` section listing concrete reference files (e.g. CACG cards under `.claude/knowledge/cards/<deck>/**/*.md`, other `.claude/knowledge/**/*.md`, vendor manuals, paper PDFs, metric manifests) or the exact string `N/A -- task not KB-relevant this round`. If the section is missing on KB-relevant work, or if `N/A` is used as a shortcut for domain-specific / modeling / metrics tasks, flag as a Blocking Side Issue. When a **verify-tier (or full)** CACG export is present (`chunks_manifest.json` ships only at `--tier verify` and above; the default `query` tier omits it), the cited card paths can be content-verified with `kb verify --round-summary <summary-file> --source-matrix .claude/knowledge/out/<deck>/source_matrix.json --chunks-manifest .claude/knowledge/out/<deck>/chunks_manifest.json`.
 
 ## Part 2: Goal Alignment Check (MANDATORY)
 

scripts/lib/kb-route-lib.sh

@@ -61,10 +61,15 @@ kb_resolve_binary() {
     command -v "$bin" >/dev/null 2>&1
 }
 
-# kb_sanitize_top_k <raw>  ->  prints a positive integer (default 5)
+# kb_sanitize_top_k <raw>  ->  prints a positive integer in [1,25] (default 5)
 #   get_config_value tostring-coerces numbers, so kb_top_k arrives as a
-#   string. Reject 0/negative/non-numeric and fall back to 5.
+#   string. Reject 0/negative/non-numeric (-> 5) and clamp huge values (-> 25)
+#   so the injected block stays bounded at the source.
 kb_sanitize_top_k() {
     local raw="$1"
-    if [[ "$raw" =~ ^[1-9][0-9]*$ ]]; then printf '%s' "$raw"; else printf '5'; fi
+    if [[ "$raw" =~ ^[1-9][0-9]*$ ]]; then
+        if [ "$raw" -gt 25 ]; then printf '25'; else printf '%s' "$raw"; fi
+    else
+        printf '5'
+    fi
 }