mishkan-harness 0.2.0 → 0.2.3

package/payload/mishkan/commands/mishkan-org-reference.md

@@ -0,0 +1,58 @@
+---
+name: mishkan-org-reference
+description: Print the MISHKAN organisation reference — 45 agents across 8 groups (Orchestration, Research, Chosheb, Panim, Yasad, Mishmar, Migdal, Sefer) with their roles, sources, and one-line descriptions. Use when you've forgotten who does what, or want a quick recall of the team structure.
+---
+
+# /mishkan-org-reference
+
+Print the MISHKAN organisation reference inline. Runs the harness CLI's
+`org` subcommand to surface the full structure so it lands in the session
+transcript and stays consultable as the conversation continues.
+
+## What it does
+
+Prints, per group:
+
+- Group name + domain (e.g. *Yasad · Backend*).
+- For each agent in the group: alias (capitalised), snake_case role,
+  one-line description.
+
+The data source is `~/.claude/mishkan/org/org.json`, generated from
+`docs/design/MISHKAN_agent_aliases.md` at install time.
+
+## How to run
+
+Invoke the harness CLI:
+
+```bash
+npx mishkan-harness org
+```
+
+For a structured JSON dump (e.g. to feed another tool):
+
+```bash
+npx mishkan-harness org --json
+```
+
+Always present the printed reference back to the user verbatim — do not
+summarise it. The whole point of this command is recall; truncation defeats
+the purpose. If the CLI is not installed, surface the install hint
+(`npx mishkan-harness install`) rather than guessing.
+
+## When to suggest it
+
+- The user asks "qui fait X ?" / "who is responsible for Y in the org?".
+- The user names an agent by alias and you're unsure of the role
+  (this is the recall use case — print, don't guess).
+- The user wants to learn the org structure ("recall me everyone in Mishmar").
+
+## When NOT to use it
+
+- Routine in-session work where the agent identity is already established.
+- Exploratory questions about the harness itself — those go through Nehemiah.
+
+## See also
+
+- Full agent roster with biblical source and meaning:
+  `docs/design/MISHKAN_agent_aliases.md`
+- The Org-Ref tab in `mishkan-watch` (TUI): same data, browsable visually.

package/payload/mishkan/commands/mishkan-skills-misses.md

@@ -0,0 +1,47 @@
+---
+description: Aggregate the skill-discovery miss log into a tuning report (top patterns + reasons + window).
+argument-hint: "[--top N]"
+---
+
+Surface the skill-discovery miss-log signal so we know which skills need
+better triggers and whether the thresholds are tuned to the actual score
+distribution.
+
+Run the aggregator:
+
+```bash
+python3 ~/.claude/mishkan/scripts/skill-discovery-misses.py --top 10
+```
+
+The report covers:
+
+- **Total misses** in the log and the observation window.
+- **By reason** — `no_match_above_threshold` (router ran, scores too low),
+  `index_missing_or_unreadable` (indexer hasn't run), `no_live_entries`
+  (every entry's source_path is dead), `router_exception:*` (bug).
+- **Top N patterns** — task signatures that produced empty buckets,
+  grouped by their sorted unique keywords so the same shape clusters.
+  Each pattern carries a count, last_seen, and an example task.
+
+Two tuning levers, in order:
+
+1. **Description tuning** (preferred). If the same pattern shows up in the
+   top-N and a skill clearly *should* have caught it, enrich that skill's
+   `description` so the keywords used in the task hit. This is the
+   D-011 §"Phase 1 → Phase 2 path" rule: tune descriptions before
+   threshold (description fixes are free; threshold changes affect every
+   future routing).
+2. **Threshold tuning** (only after 2 sprints of stable distribution).
+   Lower `--threshold-high` if real matches are being demoted to
+   `should_consider`; raise it if `must_load` is over-firing on
+   marginally-relevant skills.
+
+Surface the report verbatim, then call out:
+
+- Any pattern with count ≥ 5 — that's a recurring miss worth a description
+  edit.
+- A miss rate (`total / sessions-since-first-seen`) over ~10% — the index
+  or trigger surface is the wrong shape for the workload.
+- `router_exception:*` reasons — those are bugs; escalate to Bezalel.
+
+If the miss log is empty, say so — that is success, not nothing-to-report.

package/payload/mishkan/commands/mishkan-skills-reindex.md

@@ -0,0 +1,33 @@
+---
+description: Rebuild the universal skill-discovery index by rescanning every installed skill root.
+argument-hint: "(no arguments)"
+---
+
+Rebuild the universal skill-discovery index.
+
+Run the indexer in manual-rebuild mode:
+
+```bash
+python3 ~/.claude/mishkan/scripts/skill-discovery-indexer.py --manual
+```
+
+The indexer scans, in precedence order:
+
+1. `~/.claude/mishkan/skills/`        (origin = mishkan)
+2. `~/.claude/skills/`                (origin = user)
+3. `~/.claude/plugins/*/skills/`      (origin = plugin)
+4. `<current-repo>/.claude/skills/`   (origin = project)
+
+It writes `~/.claude/mishkan/skill-discovery/index.json` and prints a summary
+of how many entries were indexed and how many name collisions were recorded.
+
+After the rebuild, surface:
+
+- The total count.
+- The number of collisions (if non-zero, mention they live in
+  `index.json.meta.collisions`).
+- Any errors logged to `~/.claude/mishkan/skill-discovery/indexer-errors.jsonl`
+  (read the last 5 lines if the file exists).
+
+If the rebuild fails (non-zero exit, parse error), do **not** retry blindly —
+surface the error to Y4NN.

package/payload/mishkan/commands/skills.md

@@ -0,0 +1,35 @@
+---
+description: Surface the most relevant installed skills for the current task (advisory; you decide what to load).
+argument-hint: "[optional task description; defaults to the current message context]"
+---
+
+Run the **skill-discovery** layer against the current task.
+
+Task (from arguments, fall back to the active message): $ARGUMENTS
+
+Steps:
+
+1. If a task description was passed as `$ARGUMENTS`, use it verbatim.
+   Otherwise, write a one-paragraph summary of what the user is trying to
+   do right now.
+2. Invoke the router:
+   ```bash
+   python3 ~/.claude/mishkan/scripts/skill-discovery-router.py \
+       --task "<task summary>"
+   ```
+3. Parse the JSON response. Surface the three buckets to the user with this
+   shape:
+   - **must_load** — name, one-line description, origin tag
+   - **should_consider** — name, one-line description, origin tag
+   - **adjacent** — name only (cheaper context)
+4. If `stale_rebuild_needed: true`, tell the user to run
+   `/mishkan-skills-reindex`.
+5. If buckets are all empty, surface that fact — the miss is already logged
+   to `~/.claude/mishkan/skill-discovery/misses.jsonl` for tuning.
+6. **Do not auto-load** any non-`mishkan` skill for a stateful operation;
+   ask Y4NN first. Generative work may be loaded after reading the skill's
+   description.
+
+This command is advisory. The actual loading decision stays with the model
+and with Y4NN. Apply the skill-discovery skill (`~/.claude/mishkan/skills/skill-discovery/`)
+for interpretation rules.

package/payload/mishkan/commands/sprint-close.md

@@ -14,7 +14,9 @@ Then run:
    ADRs, API docs, runbooks, team docs updated in `docs/`.
 5. Resolved research + decisions promoted to the Cognee project graph
    (**cognee-promote** skill) — gated by Nehemiah + Bezalel.
-6. Observability aggregation runs; improvement-layer queries refresh.
+6. Observability aggregation runs (`bash {{MISHKAN}}/scripts/observability-aggregate.sh`)
+   to produce per-tool and per-outcome counts plus per-session activity from
+   `logs/*.jsonl`. Improvement-layer queries refresh from the produced summary.
 7. Update `./CLAUDE.md` to the next sprint (S+1) and reset milestone.
 
 Stateful operations stop at Y4NN's hands. Reporters surface structured summaries

package/payload/mishkan/hooks/pre-tool-knowledge-route.sh

@@ -0,0 +1,231 @@
+#!/usr/bin/env bash
+# MISHKAN PreToolUse — graphify-first advisory (Phase 2: advisory injection).
+#
+# Per D-009 + amendment 2026-06-07 (MISHKAN_decisions.md):
+#
+# When a structural Read or Grep fires on a source file, this hook does
+# TWO things:
+#   1. Emit a hook_fire event on the bus (telemetry preserved from
+#      Phase 1; the Knowledge tab keeps its Graphify activity counter).
+#   2. Inject an advisory block via hookSpecificOutput.additionalContext
+#      suggesting `graphify query` as the cheaper, structurally precise
+#      alternative. The hook never blocks; the agent is free to ignore
+#      the advisory and proceed with the Read/Grep.
+#
+# Skill-discovery's PreToolUse skill-routing hook can't be relied on
+# alone to push graphify because its router scores skills against the
+# initial Task prompt — "implement payment flow" matches
+# implementation skills, not "structural-question" skills like
+# graphify-query-craft. The runtime nudge here closes that gap: it
+# fires at the exact moment the agent is about to do a Read/Grep that
+# Graphify could have answered, regardless of what was injected at
+# dispatch time.
+#
+# Triggers:
+#   - Read on file_path ending in a source extension (.py .ts .tsx .js
+#     .jsx .mjs .cjs .go .rs .java .php .rb)
+#   - Grep on a bare-identifier pattern (^[A-Za-z_][A-Za-z0-9_]*$)
+#
+# NOT triggers (configs / markdown / YAML / regex Grep patterns). Per
+# D-009 §2.
+#
+# Performance contract: <= 50 ms p95. Bash hot path keeps the cold-start
+# below the Python alternative (the D-009 §6 unknown). No subprocess
+# beyond jq; fail-open everywhere; never blocks a tool call. If the
+# project has no graphify-out/ directory, the advisory is suppressed
+# (no point recommending a tool the project hasn't initialised).
+
+set -uo pipefail
+
+# jq absent -> noop. Observability never breaks a tool call.
+command -v jq >/dev/null 2>&1 || exit 0
+
+# Source the observability bus (fail-open if not yet installed).
+MISHKAN_HOME_RES="${MISHKAN_HOME:-$HOME/.claude/mishkan}"
+# shellcheck disable=SC1091
+source "${MISHKAN_HOME_RES}/observability/bus.sh" 2>/dev/null || exit 0
+
+INPUT="$(cat)"
+tool="$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)"
+session="$(printf '%s' "$INPUT" | jq -r '.session_id // "unknown"' 2>/dev/null)"
+
+# Structural-Read detection.
+target=""
+structural=0
+case "$tool" in
+  Read)
+    path="$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)"
+    lc_path="$(printf '%s' "$path" | tr '[:upper:]' '[:lower:]')"
+    case "$lc_path" in
+      *.py|*.ts|*.tsx|*.js|*.jsx|*.mjs|*.cjs|*.go|*.rs|*.java|*.php|*.rb)
+        structural=1
+        target="$path"
+        ;;
+    esac
+    ;;
+  Grep)
+    pattern="$(printf '%s' "$INPUT" | jq -r '.tool_input.pattern // empty' 2>/dev/null)"
+    # Bare identifier only: ^[A-Za-z_][A-Za-z0-9_]*$
+    if [ -n "$pattern" ] && printf '%s' "$pattern" | grep -Eq '^[A-Za-z_][A-Za-z0-9_]*$'; then
+      structural=1
+      target="$pattern"
+    fi
+    ;;
+esac
+
+[ "$structural" = 1 ] || exit 0
+
+# Emit the telemetry event (Phase 1 contract preserved).
+if command -v bus_emit >/dev/null 2>&1; then
+  short_target="$(printf '%s' "$target" | cut -c1-120)"
+  payload="$(jq -cn --arg t "$short_target" \
+    '{hook:"knowledge-route", decision:"ok", phase:2,
+      reason:"structural read/grep detected — advisory injected",
+      target:$t}' 2>/dev/null)"
+  bus_emit "$session" "hook_fire" "$tool" "completed" "$payload"
+fi
+
+# Three knowledge stores per D-008 — we mention all three so the agent
+# has the full palette instead of a graphify-only push:
+#   1. Graphify  — code structure (who calls X, dependencies, paths)
+#   2. Cognee work    — project semantic memory (decisions, conventions)
+#   3. Cognee curated — cross-project reference library (specs, learnings)
+# The agent picks whichever fits its actual question.
+
+project_root="${CLAUDE_PROJECT_DIR:-$PWD}"
+graphify_available="no"
+[ -d "$project_root/graphify-out" ] && graphify_available="yes"
+
+# Gather objective graph signals so the agent has data, not a verdict.
+graph_nodes="?"
+graph_edges="?"
+graph_age=""
+graph_json="$project_root/graphify-out/graph.json"
+if [ -f "$graph_json" ]; then
+  graph_nodes="$(jq -r '(.nodes // []) | length' "$graph_json" 2>/dev/null || echo '?')"
+  graph_edges="$(jq -r '(.links // .edges // []) | length' "$graph_json" 2>/dev/null || echo '?')"
+  scan_mtime="$(stat -c '%Y' "$graph_json" 2>/dev/null || stat -f '%m' "$graph_json" 2>/dev/null || echo 0)"
+  now_ts="$(date +%s)"
+  age_s=$((now_ts - scan_mtime))
+  if   [ "$age_s" -lt 3600 ];  then graph_age="$((age_s / 60))min ago"
+  elif [ "$age_s" -lt 86400 ]; then graph_age="$((age_s / 3600))h ago"
+  else                              graph_age="$((age_s / 86400))d ago"
+  fi
+  [ "$age_s" -gt 3600 ] && graph_age="$graph_age (stale — \`/code-graph scan\` to refresh)"
+fi
+
+# Cognee freshness — use the daemon's poll cache instead of probing
+# directly. The cognee_poll source already does HTTP probes every 30s
+# and writes the latest node counts to a small cache file. Reading the
+# cache stays within the 50ms p95 budget (a probe wouldn't). When the
+# cache is missing or stale, we fall back to "?" — the cognee line in
+# the palette still appears, the agent just doesn't get the count.
+cognee_cache="$HOME/.cache/mishkan/cognee-counts.json"
+cognee_work_nodes="?"
+cognee_curated_nodes="?"
+cognee_freshness=""
+if [ -f "$cognee_cache" ]; then
+  cognee_work_nodes="$(jq -r '.work.nodes // "?"' "$cognee_cache" 2>/dev/null || echo '?')"
+  cognee_curated_nodes="$(jq -r '.curated.nodes // "?"' "$cognee_cache" 2>/dev/null || echo '?')"
+  cog_mtime="$(stat -c '%Y' "$cognee_cache" 2>/dev/null || stat -f '%m' "$cognee_cache" 2>/dev/null || echo 0)"
+  cog_age_s=$((now_ts - cog_mtime))
+  if [ "$cog_age_s" -lt 120 ]; then
+    cognee_freshness="cache fresh ($((cog_age_s))s ago)"
+  elif [ "$cog_age_s" -lt 3600 ]; then
+    cognee_freshness="cache $((cog_age_s / 60))min old"
+  else
+    cognee_freshness="cache $((cog_age_s / 3600))h old — daemon may be down"
+  fi
+fi
+# Helper formatting for the cognee lines in the palette below.
+fmt_cognee_count() {
+  case "$1" in
+    "?")        echo "(node count unknown)" ;;
+    0|"0")      echo "(empty — nothing ingested yet)" ;;
+    *)          echo "($1 nodes)" ;;
+  esac
+}
+cog_work_hint="$(fmt_cognee_count "$cognee_work_nodes")"
+cog_curated_hint="$(fmt_cognee_count "$cognee_curated_nodes")"
+
+# Build the advisory palette. Includes ALL three stores when each can
+# help; per-tool wording so the agent sees a pre-formed command for its
+# actual target/pattern (Grep) or topic (Read).
+# Per-route token cost hints — concrete numbers so the agent sees the
+# trade-off, not just a name. Read scales with file size; graphify and
+# cognee are roughly constant per query.
+GRAPHIFY_COST_HINT="~1.8k tokens"
+COGNEE_COST_HINT="~500 tokens"
+
+case "$tool" in
+  Read)
+    short="$(basename "$target")"
+    file_lines="?"
+    read_cost_hint="~? tokens"
+    if [ -f "$target" ]; then
+      file_lines="$(wc -l < "$target" 2>/dev/null || echo '?')"
+      if [ "$file_lines" != "?" ] && [ "$file_lines" -gt 0 ]; then
+        read_tokens=$((file_lines * 4))   # ~4 tokens / line of source
+        if [ "$read_tokens" -lt 200 ]; then
+          read_cost_hint="<200 tokens"
+        else
+          read_cost_hint="~${read_tokens} tokens"
+        fi
+      fi
+    fi
+    if [ "$graphify_available" = "yes" ]; then
+      graphify_line="**CODE STRUCTURE** (call graph / dependencies / impact / where used) — \"who calls X\", \"what depends on Y\", \"path between A and B\" → \`graphify query \"<question>\"\` ($GRAPHIFY_COST_HINT). Graph: $graph_nodes nodes / $graph_edges edges, last scan $graph_age."
+    else
+      graphify_line="**CODE STRUCTURE** → no \`graphify-out/\` in this project (graphify not initialised; run \`graphify update .\` to enable)."
+    fi
+    advisory="About to Read \`$short\` (~$file_lines lines, $read_cost_hint). MISHKAN has four knowledge surfaces — each answers a different question type (D-008):
+
+- $graphify_line
+- **THIS project's MEMORY** — what WE already decided, wrote, resolved (ADRs, runbooks, past sprints, resolved research) → \`mcp__cognee__search\` against the work graph $cog_work_hint ($COGNEE_COST_HINT).
+- **CROSS-PROJECT REFERENCE** — what we learned on OTHER projects, ingested specs and standards, shared read-only library → \`mcp__cognee-curated__search\` $cog_curated_hint ($COGNEE_COST_HINT).
+- **THIS file's literal content** — actual source / docs / config of \`$short\` → Read is the right tool, $read_cost_hint.
+
+Pick the surface that matches your actual question."
+    ;;
+  Grep)
+    # Verify whether the Grep target is actually a node in the current
+    # graph. When yes → graphify is a sure win, we flag it. When no →
+    # graphify has nothing on this identifier; don't burn 1.8k on a
+    # query whose seed isn't in the graph.
+    target_in_graph="unknown"
+    if [ "$graphify_available" = "yes" ] && [ -f "$graph_json" ]; then
+      # Graphify nodes carry the identifier in `label` (and a normalised
+      # form in `norm_label`); `id` is the internal scope-prefixed key
+      # ("file_path_segment_identifier") which never matches a bare grep.
+      target_in_graph="$(jq -r --arg t "$target" '
+        if (.nodes // []) | map((.label // empty), (.norm_label // empty)) | index($t)
+        then "yes" else "no" end
+      ' "$graph_json" 2>/dev/null || echo unknown)"
+    fi
+    if [ "$graphify_available" = "yes" ]; then
+      case "$target_in_graph" in
+        yes) graphify_line="**CODE STRUCTURE** (call graph / dependencies / impact) — who calls $target, what depends on it, path between symbols → \`graphify query \"who calls $target\"\` or \`graphify affected $target --depth 2\` ($GRAPHIFY_COST_HINT each). **\`$target\` IS a node in the graph — graphify will return real callers, including indirect ones Grep misses.** Graph: $graph_nodes nodes / $graph_edges edges, last scan $graph_age." ;;
+        no)  graphify_line="**CODE STRUCTURE** → \`$target\` is NOT a node in the current graph ($graph_nodes nodes / $graph_edges edges, last scan $graph_age). Either truly absent (graphify won't help) or the graph is stale (\`/code-graph scan\` to refresh). Don't burn $GRAPHIFY_COST_HINT on a seedless query." ;;
+        *)   graphify_line="**CODE STRUCTURE** (call graph / dependencies / impact) — who calls $target, what depends on it → \`graphify query \"who calls $target\"\` or \`graphify affected $target --depth 2\` ($GRAPHIFY_COST_HINT each, catches indirect callers Grep misses). Graph: $graph_nodes nodes / $graph_edges edges, last scan $graph_age." ;;
+      esac
+    else
+      graphify_line="**CODE STRUCTURE** → no \`graphify-out/\` in this project (run \`graphify update .\` to enable; Grep stays valid in the meantime)."
+    fi
+    advisory="\`Grep $target\` on a bare identifier — MISHKAN has four knowledge surfaces and each answers a different question type (D-008):
+
+- $graphify_line
+- **THIS project's MEMORY** — \"why is $target the way it is, who decided it, when, in which sprint\" — our ADRs, runbooks, past research → \`mcp__cognee__search\` with $target as a term $cog_work_hint ($COGNEE_COST_HINT).
+- **CROSS-PROJECT REFERENCE** — \"is $target a standard term elsewhere, what does the spec / curated learning say about it\" → \`mcp__cognee-curated__search\` $cog_curated_hint ($COGNEE_COST_HINT).
+- **LITERAL text occurrences** — \"every line that contains the exact string \`$target\`, regardless of meaning\" → Grep is the right tool.
+
+Pick the surface that matches your actual question."
+    ;;
+esac
+
+# Emit hookSpecificOutput.additionalContext via stdout. Claude Code
+# prepends this to the tool call context. Never sets permissionDecision
+# — this is advisory, not gating.
+jq -cn --arg ctx "$advisory" \
+  '{hookSpecificOutput:{hookEventName:"PreToolUse", additionalContext:$ctx}}' 2>/dev/null
+
+exit 0

package/payload/mishkan/hooks/pre-tool-task-skill-route.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# MISHKAN PreToolUse — auto-inject skill-discovery advisory on Task calls
+# (D-011 Phase 2).
+#
+# Fires before Task / Agent (subagent) tool calls. Reads the task prompt
+# from the Claude Code hook stdin payload, runs the universal
+# skill-discovery router in --format injection mode, and returns the
+# resulting compact markdown block via the official PreToolUse
+# additionalContext field — Claude prepends it to the subagent's prompt.
+#
+# Output protocol (Claude Code hooks):
+#     {
+#       "hookSpecificOutput": {
+#         "hookEventName": "PreToolUse",
+#         "additionalContext": "## Discovered skills (advisory)\n..."
+#       }
+#     }
+#
+# This is the documented contract for PreToolUse advisory context — the
+# same shape SessionStart uses for additionalContext. We deliberately do
+# NOT set permissionDecision: the router is advisory, never a gate.
+#
+# Performance contract: <= 100 ms p95. The router is a small stdlib-only
+# Python script reading a flat JSON index; cold-start is the dominant cost
+# (~40-60 ms on the harness host) and only fires once per Task call.
+#
+# Hard constraints:
+#   - Hard cap 600 tokens of injection (router enforces; we trust it).
+#   - Skip injection entirely on empty buckets — do not pollute the
+#     subagent prompt with "no skills found" noise.
+#   - Fail-open on every error path: no output, exit 0, never block the
+#     Task call.
+#   - Trust marker preserved: non-mishkan entries already get a
+#     "(community)" suffix from the router's injection renderer.
+#
+# Wired in payload/install/settings.hooks.json under PreToolUse with
+# matcher "Task|Agent" (matches the existing model-route entry pattern).
+
+set -uo pipefail
+
+# jq absent -> noop. The Task call proceeds without advisory injection.
+command -v jq >/dev/null 2>&1 || exit 0
+# python3 absent -> noop, same reason.
+command -v python3 >/dev/null 2>&1 || exit 0
+
+MISHKAN_HOME_RES="${MISHKAN_HOME:-$HOME/.claude/mishkan}"
+ROUTER="${MISHKAN_HOME_RES}/scripts/skill-discovery-router.py"
+[ -f "$ROUTER" ] || exit 0
+
+# Source the observability bus (fail-open if not installed).
+# shellcheck disable=SC1091
+source "${MISHKAN_HOME_RES}/observability/bus.sh" 2>/dev/null || true
+
+INPUT="$(cat)"
+tool="$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)"
+session="$(printf '%s' "$INPUT" | jq -r '.session_id // "unknown"' 2>/dev/null)"
+
+# Belt-and-braces matcher: settings.json already filters to Task|Agent,
+# but if a future Claude Code release widens the matcher we'd be a noop
+# anyway. Better to short-circuit explicitly.
+case "$tool" in
+  Task|Agent) ;;
+  *) exit 0 ;;
+esac
+
+# Extract the subagent's prompt. Task/Agent payloads carry the prompt at
+# .tool_input.prompt; if absent we have nothing to route on.
+prompt="$(printf '%s' "$INPUT" | jq -r '.tool_input.prompt // empty' 2>/dev/null)"
+if [ -z "$prompt" ]; then
+  exit 0
+fi
+
+# Truncate to a sane size before handing to the router. The router's
+# tokenizer caps usefully around ~500 chars of signal; we cap higher to
+# preserve trailing keywords, but past 4 KB we're just paying cold-start
+# tokens for nothing.
+prompt_trim="$(printf '%s' "$prompt" | head -c 4000)"
+
+# Run the router. We pass --format injection so we get the compact
+# markdown block (empty when buckets are empty). Timeout caps the
+# worst-case at 1.5 s — well above the 100 ms p95 budget but a hard floor
+# against a wedged interpreter blocking the Task call.
+block="$(
+  timeout 1.5s python3 "$ROUTER" \
+    --task "$prompt_trim" \
+    --format injection \
+    --max-injection-tokens 600 2>/dev/null
+)" || block=""
+
+# Empty injection -> skip entirely. No additionalContext key, no noise.
+if [ -z "$block" ]; then
+  if command -v bus_emit >/dev/null 2>&1; then
+    payload="$(jq -cn '{hook:"task-skill-route", decision:"ok",
+                        reason:"no skills matched (empty buckets)"}' 2>/dev/null)"
+    bus_emit "$session" "hook_fire" "$tool" "completed" "$payload"
+  fi
+  exit 0
+fi
+
+# Build the PreToolUse hookSpecificOutput envelope. additionalContext is
+# the documented field for advisory text prepended to the tool's prompt
+# (Claude Code hooks docs, PreToolUse section). We do NOT set
+# permissionDecision — advisory only, never a gate.
+jq -cn --arg ctx "$block" '{
+  hookSpecificOutput: {
+    hookEventName: "PreToolUse",
+    additionalContext: $ctx
+  }
+}'
+
+if command -v bus_emit >/dev/null 2>&1; then
+  # Truncate the bus payload — the full block lives in the Task's context,
+  # not in the event log.
+  preview="$(printf '%s' "$block" | head -c 200 | tr '\n' ' ')"
+  payload="$(jq -cn --arg p "$preview" \
+    '{hook:"task-skill-route", decision:"allow",
+      reason:"injected skill-discovery advisory",
+      preview:$p}' 2>/dev/null)"
+  bus_emit "$session" "hook_fire" "$tool" "completed" "$payload"
+fi
+
+exit 0

package/payload/mishkan/hooks/session-start-skill-index.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# MISHKAN SessionStart — skill-index drift check (D-011 Phase 2).
+#
+# Runs the universal skill-discovery indexer in --stat-only mode at the start
+# of every session. The indexer compares each known SKILL.md mtime against
+# meta.last_scan and rebuilds only on drift (or if the index is missing).
+#
+# Performance contract: <= 200 ms p95. The stat-only sweep is just mtime calls
+# against ~200 files; a full rebuild (rare) is bounded by file count and runs
+# in well under a second.
+#
+# Fail-open by contract: any error -> exit 0 silently. The discovery layer
+# never blocks a session boot. If indexing fails, the router will surface
+# `index_missing_or_unreadable` on its next call and /mishkan-skills-reindex
+# is the recovery path.
+#
+# Wired in payload/install/settings.hooks.json under SessionStart.
+
+set -uo pipefail
+
+MISHKAN_HOME_RES="${MISHKAN_HOME:-$HOME/.claude/mishkan}"
+INDEXER="${MISHKAN_HOME_RES}/scripts/skill-discovery-indexer.py"
+
+# Indexer missing (older harness install / partial payload) -> noop.
+[ -f "$INDEXER" ] || exit 0
+
+# python3 absent -> noop. Never block session boot on a missing interpreter.
+command -v python3 >/dev/null 2>&1 || exit 0
+
+# stat-only does the cheap path; rebuilds only on drift. --quiet keeps
+# stdout empty so SessionStart additionalContext isn't polluted by indexer
+# noise (this hook is purely a side-effect; the router consumes the index).
+python3 "$INDEXER" --stat-only --quiet >/dev/null 2>&1 || true
+
+exit 0

package/payload/mishkan/observability/schema.json

@@ -85,7 +85,7 @@
             "type": "object",
             "required": ["hook"],
             "properties": {
-              "hook": {"type": "string", "description": "hook name: ira, model-route, graphify-nudge, trace, observe"},
+              "hook": {"type": "string", "description": "hook name: ira, model-route, knowledge-route, trace, observe"},
               "decision": {"type": "string", "enum": ["allow", "deny", "advise", "ok", "blocked"]},
               "reason": {"type": "string"}
             }