feat(router): make search policy auditable and fail closed on capability conflict

[claude]

Summary

Type of Change

• Bug fix
• Feature / enhancement
• Refactor (no behavior change)
• Documentation
• CI / governance change
• Breaking change (see rollback plan below)

---

Governance Checklist

• Governance setup verified — ran setup_workspace_symlinks.sh, symlinks resolve (§2)
• Symlinks validated — ls -la .cursor/rules .cursor/skills .cursor/commands all resolve
• All CI gates green — no required checks failing or bypassed
• Anti-patterns checked — reviewed CANONICAL_LAW.md §7 — none violated
• CODEOWNERS notified — blast-radius files trigger auto-request; confirmed reviewers assigned
• Workspace wiring intact — §8 wiring requirements satisfied
• TRACEABILITY_MAP.yaml updated — if this PR resolves an open unknown, mark as RESOLVED
• Kernel ref discipline — thin callers use @v1, never @main or bare SHA

---

Breaking Change

• This is a breaking change

If checked, describe the impact and migration path:

Rollback Plan

---

Related Issues

Closes #

Commits

• feat(router): make search policy auditable and fail closed on capability conflict

Test plan

• make pr-check (local changed-files gate) PASS before open
• L4 kernels: Recursive Alignment + Validate & Repair (release authorized)
• CI green; agent PR remediation subscribed after open

---

Generated by Claude Code

[cryptoxdog]

Campaign 7-ROUTER — explicit search policy + router integrity

Baseline: 56e2f48 on main, package 1.1.3, clean tree, 100 tests green.

requiresSearch was already authoritative over the TaskType default (landed in #45). This PR closes the three gaps that let the routing decision misrepresent what actually happened. Each was proven by an executable probe against the baseline before any code changed.

Verified defects

#	Defect	Pre-change evidence
A	Search + vision silently dropped a capability. resolveRoute tested the search policy before the vision branch, so SCREENSHOT_ANALYSIS + images + requiresSearch: true resolved to Provider.PERPLEXITY. PerplexityClient.buildRequestBody builds text-only messages — the images were discarded with no signal.	probe asserted decision.provider === PERPLEXITY for a task carrying images
B	No audit evidence. RoutingDecision carried no field distinguishing "the caller asked for search" from "the task type implied it".	probe asserted 'searchRequired' in decision === false
C	Perplexity config could contradict its own decision. disableSearch: requiresSearch === false && !isSearchTask(type) is unreachable on a resolved search route; off-route it produced a search-provider config with web_search_options stripped.	probe asserted disableSearch === true off-route, false on-route

Implementation

• resolveSearchPolicy() in src/matrices/search-policy.ts is now the single implementation of the rule and returns both the answer and its authority. requiresSearchProvider() is a boolean view of it; isSearchTask() supplies only the TaskType default. One typeof task.requiresSearch === 'boolean' exists in src/.
• RoutingResolution gains searchRequired: boolean and searchPolicySource: EXPLICIT | TASK_DEFAULT, inherited by RoutingDecision and the call log.
• Search + vision + images throws UnsupportedCapabilityCombinationError (code: 'UNSUPPORTED_CAPABILITY_COMBINATION') from route resolution — before request identity, budget reservation, circuit permit, or dispatch.
• disableSearch is now always false, plus two dispatch invariants: decision.searchRequired === (provider === PERPLEXITY) in both directions, and a search route may never dispatch a config with search off.

Routing matrix (tests/routing-matrix.test.ts, table-driven)

Case	requiresSearch	Expected	Actual
A/B/C STRATEGIC_REASONING	false / true / omitted	NON_SEARCH / SEARCH / NON_SEARCH	✅
D/E/F COMPETITOR_RESEARCH	true / false / omitted	SEARCH / NON_SEARCH / SEARCH	✅
G/H FACT_VERIFICATION	false / omitted	NON_SEARCH / SEARCH	✅
I/J CONTENT_GENERATION	false / true	NON_SEARCH / SEARCH	✅
K/L SCREENSHOT_ANALYSIS + images	false / omitted	VISION	✅
M SCREENSHOT_ANALYSIS + images	true	fail closed	✅ throws
N/O EXTRACTION, CLASSIFICATION	true	SEARCH	✅
P/Q MARKET_RESEARCH	false / omitted	NON_SEARCH / SEARCH	✅

Every non-fail-closed case also asserts searchPolicySource (EXPLICIT for a boolean, TASK_DEFAULT for omitted) and that searchRequired matches the plane actually selected.

Non-regression proved, not assumed

Budget reserved before dispatch on both planes and reconciled to actual cost; failures charged to the circuit of the provider the policy selected (search failure opens Perplexity only, general failure opens OpenRouter only); the capability refusal reserves nothing and opens nothing; image safety validation still precedes every routing outcome; consensus stays an execution modifier and never pulls a task onto the search plane; vision model selection is byte-identical for every (image count × complexity) pair; TaskDescriptor still exposes capability fields only — application-supplied provider/model keys are stripped and the router keeps its choice.

Tests: 100 → 161. The package export map is unchanged: no 1.x provider subpath removed, none added.

Consumer compatibility (read-only; neither repo modified)

The real policy modules from each consumer — Website-Bot@3eb3536 src/intelligence/improve-llm-policy.ts and SEO-Bot@9691264 src/services/improve-llm-policy.ts — were copied unmodified into disposable ephemeral projects, compiled against the packed 1.2.0 tarball under each consumer's own strict compilerOptions, and executed:

• Website-Bot — PASS. assertWebsiteImprovePolicy() holds. All 5 operations stay off the search plane; VISUAL_PATTERN_ANALYSIS and VISUAL_DELTA_ANALYSIS still resolve to vision.
• SEO-Bot — PASS. assertSeoImprovePolicy() holds. The 4 reasoning operations stay non-search; FRESH_WEB_EVIDENCE → perplexity/sonar-pro. The inline requiresSearch: true helpers (COMPETITOR_RESEARCH, CITATION_CHECK, MARKET_RESEARCH) stay on search, and analyzeScreenshot (LAYOUT_VALIDATION + images, flag omitted) stays on vision with searchPolicySource = TASK_DEFAULT.

Neither consumer combines vision with requiresSearch: true, so the new fail-closed path is unreachable from their current call sites.

Version

1.1.3 → 1.2.0. Additive public API (SearchPolicySource, SearchPolicyResolution, resolveSearchPolicy, UnsupportedCapabilityCombinationError, two RoutingResolution fields) plus a fail-closed correction — a minor bump within 1.x. Both consumers pin 1.1.2 exactly, so neither auto-adopts; adoption is each repo's own decision.

Not proven here — please note before tagging

• Real-provider smoke was not run. No PERPLEXITY_API_KEY / OPENROUTER_API_KEY is reachable from the execution sandbox. Status is REAL_PROVIDER_SMOKE_BLOCKED, not PASS.
• Registry state for 1.2.0 was not verified from the sandbox (no read:packages scope). Confirm 1.2.0 is unpublished before pushing a v1.2.0 tag — published versions are immutable.

npm run verify:package — the isolated tarball install and export smoke I could not run locally — passed in CI on Node 20.19.0, 22.23.1, and 24.18.0.

---

Generated by Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud