portawhip 0.1.0

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "portawhip",
+  "private": false,
+  "type": "module",
+  "version": "0.1.0",
+  "description": "Tools collector + context-cheap router for AI agent hosts: dispatches capability install to add-mcp/mise/asm, then routes the right one at the right moment instead of loading everything into context.",
+  "license": "MIT",
+  "homepage": "https://github.com/VVeb1250/portawhip#readme",
+  "bugs": {
+    "url": "https://github.com/VVeb1250/portawhip/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/VVeb1250/portawhip.git"
+  },
+  "keywords": [
+    "ai-agents",
+    "mcp",
+    "model-context-protocol",
+    "agent-tools",
+    "tool-router",
+    "claude-code",
+    "codex",
+    "gemini-cli",
+    "developer-tools"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "portawhip": "scripts/tui.mjs",
+    "portawhip-router": "core/router/router-cli.mjs",
+    "harness-router": "server/mcp-server.mjs"
+  },
+  "files": [
+    "adapters/",
+    "core/",
+    "docs/router-eval-set.jsonl",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "recipes/",
+    "scripts/",
+    "server/",
+    "skills/",
+    "hooks.manifest.yaml",
+    "recipe.yaml",
+    "router.config.yaml",
+    "surface-matrix.yaml",
+    "VISION.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "load": "node scripts/load.mjs",
+    "doctor": "node scripts/doctor.mjs",
+    "connectors": "node scripts/link/link-connectors.mjs status",
+    "connectors:link": "node scripts/link/link-connectors.mjs install",
+    "hooks": "node scripts/link/link-hooks.mjs status",
+    "hooks:link": "node scripts/link/link-hooks.mjs install",
+    "sync-config": "node scripts/sync/sync-config.mjs status",
+    "sync-config:preview": "node scripts/sync/sync-config.mjs preview",
+    "agents": "node scripts/sync/agents-surface.mjs",
+    "agents:connect": "node scripts/sync/agents-surface.mjs connect",
+    "agents:mcp": "node scripts/sync/agents-surface.mjs mcp",
+    "surface": "node scripts/surface-inventory.mjs",
+    "import": "node scripts/sync/import-surfaces.mjs status",
+    "import:preview": "node scripts/sync/import-surfaces.mjs preview",
+    "hooks:embedded": "node scripts/embedded-hooks.mjs",
+    "surface:sync": "node scripts/sync/sync-surfaces.mjs sync",
+    "surface:sync:check": "node scripts/sync/sync-surfaces.mjs check",
+    "surface:watch": "node scripts/sync/sync-surfaces.mjs watch",
+    "tui": "node scripts/tui.mjs",
+    "bundles": "node scripts/bundles.mjs list",
+    "bundles:status": "node scripts/bundles.mjs status",
+    "bundles:select": "node scripts/bundles.mjs select",
+    "test": "node --test",
+    "route": "node core/router/router-cli.mjs route",
+    "route:list": "node core/router/router-cli.mjs list",
+    "route:eval": "node core/router/router-cli.mjs eval --engine hybrid",
+    "route:compare": "node core/router/router-cli.mjs compare",
+    "route:graph": "node core/router/router-cli.mjs graph-compile --out .hp-state/capability-graph.json",
+    "route:enrich": "node core/router/router-cli.mjs enrich"
+  },
+  "dependencies": {
+    "@huggingface/transformers": "^4.2.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "add-mcp": "^1.13.0",
+    "agent-skill-manager": "^2.7.0",
+    "ansi-escapes": "^7.3.0",
+    "cross-spawn": "^7.0.6",
+    "ink": "^5.2.1",
+    "js-yaml": "^4.1.0",
+    "minisearch": "^7.2.0",
+    "react": "^18.3.1"
+  },
+  "devDependencies": {
+    "@agents-dev/cli": "^0.8.9",
+    "ai-config-sync-manager": "0.1.5"
+  }
+}

package/recipe.yaml

@@ -0,0 +1,247 @@
+# Step 1 proof-of-concept recipe.
+# Each entry declares WHAT capability to load, not HOW — the dispatcher
+# picks the backend per `type` and shells out to a tool that already
+# solves that backend well (add-mcp / mise / asm). No install logic
+# lives in this repo.
+- id: context7
+  type: mcp
+  source: https://mcp.context7.com/mcp
+  route:
+    triggers: ["library docs", "api docs", "documentation", "how to use", "sdk usage", "package docs"]
+    description: "Fetch current docs/examples for a library, framework, or API"
+    when: [user_prompt]
+    inject: hint
+
+- id: ripgrep
+  type: cli
+  source: ripgrep
+  route:
+    triggers: ["search codebase", "grep", "find text in files", "regex search"]
+    description: "Fast regex search across files"
+    when: [user_prompt]
+    inject: hint
+    binary: rg
+
+- id: pdf
+  # id matches the skill's real installed name (not "anthropic-skills") on
+  # purpose: registry.mjs dedupes curated vs. auto-discovered entries by id,
+  # and this skill also gets auto-discovered once installed (asm reports it
+  # as "pdf" in every host's skill dir). Matching ids lets the curated,
+  # deliberately-authored route win outright instead of competing on score
+  # against a separately-discovered duplicate of the same capability.
+  type: skill
+  source: github:anthropics/skills
+  path: skills/pdf
+  route:
+    triggers: ["pdf", "merge pages", "ocr", "extract table"]
+    description: "Read/merge/split/OCR PDF files"
+    when: [user_prompt]
+    inject: hint
+
+- id: codegraph
+  # Same curated-override-wins pattern as pdf above: codegraph is already
+  # auto-discovered (installed globally as an MCP server), but it also
+  # needs a per-project .codegraph/ index before it's actually usable here.
+  # Observed live: the router suggested codegraph in THIS repo, which has
+  # no .codegraph/ — readyMarker/readyHint let the suggestion say so
+  # instead of silently implying it just works.
+  type: mcp
+  source: codegraph
+  route:
+    triggers: ["codegraph", "code graph", "call graph", "blast radius", "symbol graph"]
+    description: "MCP server: codebase knowledge graph (symbols, edges, call paths)"
+    when: [user_prompt]
+    inject: hint
+    readyMarker: ".codegraph"
+    readyHint: "codegraph init"
+
+- id: harness-router
+  type: mcp
+  source: node
+  path: "."
+  args: ["server/mcp-server.mjs"]
+  name: harness-router
+  scope: project
+  route:
+    triggers:
+      [
+        "harness-router",
+        "portawhip",
+        "hybrid-router.mjs",
+        "sparse-retriever.mjs",
+        "router-cli.mjs",
+        "fix the router",
+        "improve the router",
+      ]
+    description: "Inspect or improve this repo's harness-router/portawhip routing source"
+    when: [user_prompt]
+    inject: hint
+    action: inspect_code
+
+- id: portawhip
+  # This repo's own management skill (skills/portawhip/SKILL.md). Curated so
+  # the router surfaces it when the user talks about importing/syncing tools
+  # across hosts. install:false — it lives in-repo and is read via the pointer,
+  # like the other instruction-backed skills below.
+  type: skill
+  source: portawhip
+  path: skills/portawhip
+  install: false
+  route:
+    triggers:
+      [
+        "import capability",
+        "import tool",
+        "sync tools across hosts",
+        "share skill across hosts",
+        "fan out to all hosts",
+        "manage portawhip",
+        "surface coverage matrix",
+        "what capabilities are synced",
+        "import newly installed",
+      ]
+    description: "Manage portawhip cross-host capability sync: import, enrich, check coverage, fan out to all hosts"
+    when: [user_prompt]
+    inject: hint
+    action: read_skill
+
+- id: workspace-surface-audit
+  type: skill
+  source: workspace-surface-audit
+  install: false
+  route:
+    triggers:
+      [
+        "ecc:harness-audit",
+        "harness audit",
+        "audit connector",
+        "audit hook",
+        "connector audit",
+        "hook audit",
+        "mcp audit",
+        "workspace surface audit",
+        "harness surface",
+      ]
+    description: "Audit the active repo, MCP servers, connectors, hooks, plugins, and ECC harness surface"
+    when: [user_prompt]
+    inject: hint
+    action: read_skill
+
+- id: ai-config-sync-manager
+  type: config-sync
+  source: ai-config-sync
+  install: false
+  route:
+    triggers:
+      [
+        "sync claude codex config",
+        "sync config",
+        "config drift",
+        "copy skills to codex",
+        "copy skills to claude",
+        "sync mcp config",
+        "sync hooks permissions",
+        "claude codex drift",
+      ]
+    description: "Bidirectional Claude Code/Codex config sync via ai-config-sync-manager"
+    when: [user_prompt]
+    inject: hint
+    action: run_sync_config
+
+- id: agent-skill-manager-sync-probe
+  type: config-sync
+  source: agent-skill-manager
+  install: false
+  route:
+    triggers:
+      [
+        "agent-skill-manager",
+        "asm providers",
+        "skill providers",
+        "skills installed across hosts",
+        "sync skills",
+      ]
+    description: "Probe agent-skill-manager provider state used by the skill install backend"
+    when: [user_prompt]
+    inject: hint
+    action: run_sync_config_status
+
+- id: agents-dotdir-sync
+  type: config-sync
+  source: agents
+  install: false
+  route:
+    triggers:
+      [
+        ".agents",
+        "agents sync",
+        "agents status",
+        "single source of truth",
+        "sync all hosts",
+        "sync codex claude gemini cursor",
+      ]
+    description: "Probe or run @agents-dev/cli .agents source-of-truth sync across many hosts"
+    when: [user_prompt]
+    inject: hint
+    action: run_sync_config
+
+- id: configure-ecc
+  type: skill
+  source: configure-ecc
+  install: false
+  route:
+    triggers:
+      [
+        "update-config",
+        "update config",
+        "settings.json hook",
+        "claude code settings",
+        "codex config",
+        "mcp config",
+        "configure ecc",
+        "hook troubleshooting",
+        "fix config",
+      ]
+    description: "Configure or repair ECC/Codex/Claude harness config, hooks, settings, and MCP wiring"
+    when: [user_prompt]
+    inject: hint
+    action: read_skill
+
+- id: verification-loop
+  type: skill
+  source: verification-loop
+  install: false
+  route:
+    triggers:
+      [
+        "verify",
+        "verification",
+        "run tests",
+        "test before commit",
+        "pre commit verification",
+        "quality gate",
+        "fix bug and run tests",
+      ]
+    description: "Run build/test/lint/security verification after code changes and before commits"
+    when: [user_prompt]
+    inject: hint
+    action: read_skill
+
+- id: code-review
+  type: skill
+  source: code-review
+  install: false
+  route:
+    triggers:
+      [
+        "code-review",
+        "code review",
+        "review changed code",
+        "review before commit",
+        "bug fix review",
+        "pull request review",
+      ]
+    description: "Review changed code for bugs, regressions, missing tests, and maintainability before commit"
+    when: [user_prompt]
+    inject: hint
+    action: review_code

package/recipes/foundry.yaml

@@ -0,0 +1,27 @@
+# Foundry - whipforaweeb's recommended core bundle. Recommended, not forced:
+# `node scripts/bundles.mjs select --foundry` opts in, `select --none` opts
+# out at any time.
+#
+# Every entry here MUST carry a route: block. This is the rule that keeps
+# this bundle from repeating the predecessor project's own gripe: a set of
+# curated tools that installed cleanly but was never wired into behavior
+# ("bundle harness = bench harness, not production harness" -
+# E:\portable-harness\docs\BUNDLE.md section 7). Selecting a bundle here
+# writes the SAME recipe-file list that both scripts/load.mjs (install) and
+# the router/hooks (routing) read - so nothing in this file can end up
+# installed-then-silent.
+#
+# ast-grep is carried over from the predecessor project's already
+# bench-proven 0-tax core (docs/BUNDLE.md: "+69% precision/+76-97% codemod"
+# vs plain grep/sed on structural edits) and its mise registry name was
+# re-verified live in this repo on 2026-07-05 (`mise registry` lists
+# `ast-grep -> aqua:ast-grep/ast-grep`).
+- id: ast-grep
+  type: cli
+  source: ast-grep
+  route:
+    triggers: ["structural search", "ast-grep", "codemod", "rewrite code pattern", "syntax-aware search"]
+    description: "Structural, syntax-aware code search and rewrite (AST-based, not plain text)"
+    when: [user_prompt]
+    inject: hint
+    binary: ast-grep

package/recipes/manifest.yaml

@@ -0,0 +1,18 @@
+# Bundle catalog metadata (data only, no logic) — read by
+# `scripts/bundles.mjs list`/`status`. Every bundle here is opt-in; foundry
+# is only "recommended", never auto-installed or auto-selected (agreed
+# 2026-07-05: bundles recommend, they never force).
+foundry:
+  description: "whipforaweeb's recommended core - small, cross-OS, 0-MCP. Opt-out anytime with `bundles select --none`."
+  recommended: true
+roles:
+  secure:
+    description: "Deterministic supply-chain/secret checks (0-MCP). Pick this if your role touches dependencies, CI, or handles credentials."
+  coding:
+    description: "Code-size orientation and perf verification (0-MCP). Pick this if you write/refactor code day to day."
+  research:
+    description: "Document format conversion (0-MCP). Pick this if you work with docs, papers, or notes across formats."
+  frontend:
+    description: "JS/TS/JSON lint and format (0-MCP). Pick this if your role touches frontend or Node code."
+  backend-data:
+    description: "Query CSV/Parquet/SQLite/JSON without loading them into context (0-MCP). Pick this if your role touches data files or APIs returning JSON."

package/recipes/roles/backend-data.yaml

@@ -0,0 +1,26 @@
+# Role: backend-data - opt-in via
+# `node scripts/bundles.mjs select --role backend-data`.
+# duckdb + jq are carried over from the predecessor project's already
+# bench-proven data-query set (docs/BUNDLE.md: "+99.96% vs Read" for bulk
+# CSV/Parquet/SQLite/JSON queries, 0 MCP). Both mise registry names
+# re-verified live in this repo on 2026-07-05 (`mise registry`: duckdb ->
+# aqua:duckdb/duckdb, jq -> aqua:jqlang/jq).
+- id: duckdb
+  type: cli
+  source: duckdb
+  route:
+    triggers: ["query csv", "duckdb", "query parquet", "sql on files", "analyze large dataset"]
+    description: "Run SQL directly over CSV/Parquet/SQLite/JSON files without loading them into context"
+    when: [user_prompt]
+    inject: hint
+    binary: duckdb
+
+- id: jq
+  type: cli
+  source: jq
+  route:
+    triggers: ["parse json", "jq", "filter json", "transform json", "query json file"]
+    description: "Slice, filter, and transform JSON from the command line"
+    when: [user_prompt]
+    inject: hint
+    binary: jq

package/recipes/roles/coding.yaml

@@ -0,0 +1,26 @@
+# Role: coding - opt-in via `node scripts/bundles.mjs select --role coding`.
+# ast-grep (structural search/rewrite) already lives in foundry, so this
+# role covers what foundry doesn't: perf verification while coding.
+#
+# tokei (LOC counter) was tried and dropped live on 2026-07-05: mise's
+# registry only offers it via a cargo build (`cargo:tokei`) or an aqua entry
+# that itself refuses non-binary cargo packages ("package type cargo is not
+# supported in the aqua backend") - no prebuilt binary path on this
+# platform. That's compile-tax, the same class of problem that got
+# `headroom-ai` rejected from the predecessor project's bundle (see
+# E:\portable-harness\docs\BUNDLE.md: "= compile-tax ทุก host ... ขัด North
+# Star portable"). Not forcing a Rust toolchain install for one bundle tool.
+# No prebuilt-binary LOC-counter alternative (scc, cloc) was found in mise's
+# registry either - open gap, not silently worked around.
+#
+# hyperfine's mise registry name re-verified live on 2026-07-05
+# (`mise registry`: hyperfine -> aqua:sharkdp/hyperfine cargo:hyperfine).
+- id: hyperfine
+  type: cli
+  source: hyperfine
+  route:
+    triggers: ["benchmark command", "hyperfine", "compare performance", "measure runtime", "how fast is this"]
+    description: "Command-line benchmarking with statistically sound comparisons"
+    when: [user_prompt]
+    inject: hint
+    binary: hyperfine

package/recipes/roles/frontend.yaml

@@ -0,0 +1,14 @@
+# Role: frontend - opt-in via `node scripts/bundles.mjs select --role frontend`.
+# biome is a single-binary linter+formatter for JS/TS/JSON (fast, no Node
+# toolchain dependency at the binary level). mise registry name re-verified
+# live in this repo on 2026-07-05 (`mise registry`: biome ->
+# aqua:biomejs/biome npm:@biomejs/biome).
+- id: biome
+  type: cli
+  source: biome
+  route:
+    triggers: ["lint javascript", "biome", "format typescript", "lint frontend code", "js formatter"]
+    description: "Lint and format JS/TS/JSON (fast, single binary)"
+    when: [user_prompt]
+    inject: hint
+    binary: biome

package/recipes/roles/research.yaml

@@ -0,0 +1,31 @@
+# Role: research - opt-in via `node scripts/bundles.mjs select --role research`.
+# pandoc handles the common research friction of converting between document
+# formats (docs/papers/notes) without a heavyweight app. mise registry name
+# re-verified live in this repo on 2026-07-05 (`mise registry`: pandoc ->
+# github:jgm/pandoc).
+- id: pandoc
+  type: cli
+  source: pandoc
+  route:
+    triggers: ["convert document", "pandoc", "markdown to pdf", "docx to markdown", "document format conversion"]
+    description: "Convert between document formats (markdown, docx, pdf, html, and more)"
+    when: [user_prompt]
+    inject: hint
+    binary: pandoc
+
+# markitdown converts binary office/PDF documents to LLM-friendly markdown -
+# the common research-material-ingestion step pandoc doesn't cover well
+# (pandoc is markup<->markup; markitdown targets docx/pptx/xlsx/pdf/images
+# specifically). Installed live via mise's pipx backend on 2026-07-05
+# (`source: pipx:markitdown` - no short-name alias in mise's own registry,
+# but the pipx-qualified name resolves and installs cleanly: pure Python
+# wheels, no compiler needed, ~25MB, a few seconds).
+- id: markitdown
+  type: cli
+  source: pipx:markitdown
+  route:
+    triggers: ["convert to markdown", "markitdown", "extract text from pdf", "docx to text", "read office document"]
+    description: "Convert docx/pptx/xlsx/pdf/images to markdown for LLM-friendly reading"
+    when: [user_prompt]
+    inject: hint
+    binary: markitdown

package/recipes/roles/secure.yaml

@@ -0,0 +1,27 @@
+# Role: secure - opt-in via `node scripts/bundles.mjs select --role secure`
+# (combine with other roles: --role secure,coding).
+#
+# gitleaks + osv-scanner are carried over from the predecessor project's
+# already bench-proven secure-agent set (docs/BUNDLE.md: "tested PASS",
+# 0 MCP, deterministic). Both mise registry names were re-verified live in
+# this repo on 2026-07-05 (`mise registry`: gitleaks -> aqua:gitleaks/gitleaks,
+# osv-scanner -> aqua:google/osv-scanner).
+- id: gitleaks
+  type: cli
+  source: gitleaks
+  route:
+    triggers: ["secret scan", "gitleaks", "leaked credentials", "hardcoded secret", "api key in code"]
+    description: "Scan for hardcoded secrets/credentials before they get committed"
+    when: [user_prompt]
+    inject: hint
+    binary: gitleaks
+
+- id: osv-scanner
+  type: cli
+  source: osv-scanner
+  route:
+    triggers: ["vulnerability scan", "osv-scanner", "dependency vulnerabilities", "cve check", "supply chain"]
+    description: "Scan dependencies for known vulnerabilities (OSV database)"
+    when: [user_prompt]
+    inject: hint
+    binary: osv-scanner

package/router.config.yaml

@@ -0,0 +1,120 @@
+# Tunable router defaults. This is data the scorer reads at runtime —
+# not decision logic. Missing file / missing keys fall back to the same
+# defaults shown here (core/state/config.mjs), so this file is optional.
+#
+# Two thresholds, not one — curated (recipe.yaml) triggers are deliberately
+# authored, so a single hit is trustworthy (recipeThreshold=1). Auto-
+# discovered triggers (core/registry/discover.mjs) are inferred from free-text
+# descriptions across 300+ installed skills and produce real single-word
+# noise (e.g. "write" fired on "write a poem about the ocean" against
+# writing-related skills) — verified requiring 2 distinct hits removes that
+# false positive without losing true matches (grep/pdf/docs still route).
+engine: hybrid
+threshold: 2
+recipeThreshold: 1
+# Hybrid retrieval uses minisearch (core/router/sparse-retriever.mjs) — score scale
+# is in the hundreds/thousands, not the small BM25-ish numbers the old
+# hand-rolled engine produced. Two thresholds here too, for the same reason
+# as recipeThreshold above: curated entries (recipe.yaml) need a much lower
+# bar than auto-discovered ones. Verified empirically (docs/archive/phase2.5-verify.md):
+# generic domain vocabulary shared across hundreds of skill docs ("architecture",
+# "patterns") can outscore a genuine curated match (ripgrep/context7), so one
+# global threshold can't separate "real auto match" from "noise" AND "real
+# curated match" at the same time. Calibrated against docs/router-eval-set.jsonl:
+# 350 clears all 18 negatives (0 false positives, including both hard prompts
+# that regress-test the old noisy hook) while keeping all 5 original Phase-2
+# positives; costs 4 of 7 newer p25 positives (accepted: silence > wrong guess).
+hybridThreshold: 350
+hybridRecipeThreshold: 130
+# Auto-discovered MCP/CLI tools are a third bucket, not "skills with a lower
+# bar": add-mcp/mise give no description, so their documents are just a bare
+# name with almost nothing for generic vocabulary to falsely match against.
+# Verified: 0 false positives from any mcp/cli-type entry across the full
+# negative eval set, so this can sit far below hybridThreshold without risk
+# — recovers real "use <tool>" matches (exa/github/playwright) that
+# hybridThreshold=350 was silently dropping.
+hybridToolThreshold: 80
+# Optional Phase-2.5 graph. If the file is absent, graph expansion is a no-op.
+# Schema: {"edges":[{"from":"capability-id","to":"neighbor-id","type":"related_skill","weight":1}]}
+graphPath: .hp-state/capability-graph.json
+graphBoost: 0.25
+k: 5
+# A lane (skill or tool) where the top match barely beats the runner-up is
+# diffuse-vocabulary noise, not a genuine pick - verified against the last
+# remaining false positive in docs/router-eval-set.jsonl: "what context
+# signals should a router observe before injecting a skill" scores
+# example-skill and skill-development within 0.3% of each other (both lit up
+# by the same generic "router"/"skill"/"injecting" words shared across
+# hundreds of skill docs), while every genuine match in the eval set has a
+# clear top pick with no close runner-up. Swept 1.05/1.08/1.12 against the
+# full eval set - all three give the same result (a plateau, not a knife's
+# edge), so 1.05 is not a fragile fit to one prompt. Confirmed this doesn't
+# fix everything: it's a geometry-of-scores fix, so it can't separate a
+# genuinely peaked-but-wrong match (a doc that's confidently, unambiguously
+# the top hit yet still the wrong one) - that needs a semantic signal
+# (planned: PLAN.md Phase 4's local embedding model), not a sharper number.
+peakednessRatio: 1.05
+# Phase 4 semantic layer (PLAN.md): dense retrieval via BAAI/bge-m3
+# (core/router/dense-embedder.mjs) - a second, meaning-based channel additive to the
+# lexical one above, on by default so every user gets it with zero manual
+# setup (no install script, no model management - transformers.js downloads
+# and caches the model itself on first use, MIT-licensed, ~543MB quantized,
+# 100+ languages including Thai). Exists to close the one gap threshold/
+# margin tuning on lexical scores alone provably cannot: a genuine paraphrase
+# with little/no shared vocabulary (docs/router-eval-set.jsonl's e2e-testing
+# miss - "use Playwright to test login flow" vs the skill's own wording).
+# Fails soft to a no-op whenever the model isn't reachable, so this is safe
+# to leave on - every caller sees identical output to before whenever dense
+# doesn't contribute. denseThreshold is on cosine similarity's own 0..1
+# scale, never comparable to hybridThreshold's hundreds/thousands scale.
+# The push hook (adapters/hooks/universal-hook.mjs) explicitly disables this
+# per-call: it's a fresh subprocess per prompt, so it can't amortize a
+# 500MB+ model load the way the long-lived MCP server/CLI can.
+denseEnabled: true
+# 0.6, not the more intuitive-looking 0.55 - verified live against
+# docs/router-eval-set.jsonl with the real BGE-M3 model (not simulated): 0.55
+# let a genuinely irrelevant agent/skill pair through on "audit why route
+# suggestions are noisy and injected at the wrong time" (network-config-
+# reviewer/caveman-review, both boosted over the line by
+# actionAlignmentFactor's "review" match stacked on top of raw cosine
+# ~0.48-0.50 - BGE-M3's ambient similarity floor for unrelated short text,
+# not a genuine match). Swept 0.55/0.56/0.58/0.60 against the full eval set:
+# 0.55-0.56 fail, 0.58-0.60 both clean (falsePositiveCount 0, precisionAt1/
+# recallAt3 still 1, including the e2e-testing paraphrase this channel exists
+# to rescue) - a real plateau, not one lucky number. Picked 0.60 for extra
+# margin over the 0.58 edge.
+denseThreshold: 0.6
+# WS-A mode differentiation: the push hook sees a raw prompt without the
+# agent's reasoned intent summary. Characterization proved lexical/dense
+# signals cannot reliably separate meta-discussion from an actionable request,
+# so unsolicited push is silent by default. Set PORTAWHIP_PUSH_MODE=legacy as
+# a temporary rollback switch; pull route() remains enabled and recall-generous.
+pushMode: silent
+# Phase 3 push-mode hook: hard char budget per injected suggestion block
+# (proxy for tokens — no tokenizer dependency for this). Lines are added
+# until the next one would exceed this, so it degrades to fewer/shorter
+# lines rather than truncating mid-line.
+#
+# Bumped 320 -> 640 (2026-07-06): adding actionDirective() (invocation
+# syntax per kind, so suggestions actually get acted on) made a first-time
+# mcp line ~265 chars on its own (the ToolSearch-fallback clause is the
+# biggest chunk) - 320 only fit one such line even when lane-reserved
+# results (core/router/hybrid-router.mjs) legitimately surface 2-3 relevant
+# capabilities across skill/agent/tool lanes at once. Repeat mentions
+# within the same session already render tersely (universal-hook.mjs's
+# sessionSuggestedIds), so this cost is paid at most once per id per
+# session, not every turn - 640 fits ~2 full mcp lines or a full
+# skill+agent+tool combo comfortably.
+pushBudgetChars: 640
+# Push/pull asymmetry (2026-07-09 audit): push is an unsolicited interruption,
+# pull (MCP route()) is a solicited lookup. Advisory-systems literature calls
+# the push failure mode alert fatigue - CDSS systems with 90%+ override rates
+# get tuned out entirely, and this repo's own feedback log was at 22/26
+# suggestions ignored. Push therefore drops any hit below this calibrated
+# confidence unless it's required-tier (curated recipe.yaml entries); pull
+# keeps generous recall untouched.
+pushMinConfidence: 0.75
+# Interrupt budget per capability per session: full line once, terse reminder
+# once, then silent. (Repeat-terse already existed via sessionSuggestedIds;
+# this adds the "then shut up" cap.)
+pushMaxMentionsPerSession: 2