DO NOT MERGE — Verification autopilot and routing policy engine (experimental)

docs/02-injection-pipeline.md

@@ -30,6 +30,7 @@ This document explains how vercel-plugin decides **which skills to inject**, **w
    - [Vercel.json Key-Aware Routing](#verceljson-key-aware-routing)
    - [Profiler Boost](#profiler-boost)
    - [Setup Mode Routing](#setup-mode-routing)
+   - [Route-Scoped Verified Policy Recall](#route-scoped-verified-policy-recall)
    - [Unified Ranker](#unified-ranker)
 7. [Dedup State Machine](#dedup-state-machine)
    - [Three State Sources](#three-state-sources)
@@ -481,6 +482,61 @@ effectivePriority = base + vercelJsonAdjustment + profilerBoost
 
 When the project is greenfield (`VERCEL_PLUGIN_GREENFIELD=true`), the `bootstrap` skill gets a massive priority boost of **+50**, ensuring it's always injected first. If `bootstrap` didn't naturally match the tool call, it's synthetically added to the match set.
 
+### Route-Scoped Verified Policy Recall
+
+**Source**: `hooks/src/policy-recall.mts` → `selectPolicyRecallCandidates()`, integrated in `pretooluse-skill-inject.mts` at Stage 4.95
+
+After all pattern-matched skills are ranked and before injection, the hook checks whether an **active verification story** with a non-null `targetBoundary` exists. If so, it queries the project's routing policy for historically winning skills that pattern matching missed.
+
+**Preconditions** (all must be true):
+1. `cwd` and `sessionId` are available
+2. An active verification story exists (via `loadCachedPlanResult` → `selectPrimaryStory`)
+3. `primaryNextAction.targetBoundary` is non-null
+
+**Lookup precedence** (first qualifying bucket wins — no cross-bucket merging):
+1. **Exact route** — e.g. `PreToolUse|flow-verification|clientRequest|Bash|/settings`
+2. **Wildcard route** — e.g. `PreToolUse|flow-verification|clientRequest|Bash|*`
+3. **Legacy 4-part key** — e.g. `PreToolUse|flow-verification|clientRequest|Bash`
+
+**Qualification thresholds** (same conservatism as `derivePolicyBoost`):
+- Minimum 3 exposures
+- Minimum 65% success rate (weighted: `directiveWins` count at 0.25×)
+- Minimum +2 policy boost
+
+**Tie-breaking** is deterministic: `recallScore` DESC → `exposures` DESC → skill name ASC (lexicographic).
+
+**Insertion behavior** — recalled skills are **bounded second-order candidates**, not slot-1 overrides:
+- When direct pattern matches exist: recalled skill inserts at index 1 (behind the top direct match)
+- When no direct matches exist: recalled skill takes index 0
+- At most 1 recalled skill per PreToolUse invocation (`maxCandidates: 1`)
+- Skills already in `rankedSkills` or `injectedSkills` (dedup) are excluded
+
+**How recall differs from ordinary policy boosts**:
+- Policy boosts adjust `effectivePriority` of already-matched skills — they only amplify what pattern matching found
+- Policy recall **injects a skill that pattern matching missed entirely**, based on historical verification evidence
+- Recalled skills are marked `synthetic: true` in the routing decision trace
+- Recalled skills use `trigger: "policy-recall"` and `reasonCode: "route-scoped-verified-policy-recall"` in injection metadata
+- Recalled skills are NOT forced to summary-only mode (the summary and full payloads are identical via `skillInvocationMessage`)
+
+**Trace output**: Recalled candidates appear in `ranked[]` with:
+```json
+{
+  "skill": "verification",
+  "synthetic": true,
+  "pattern": {
+    "type": "policy-recall",
+    "value": "route-scoped-verified-policy-recall"
+  }
+}
+```
+
+**When recall is skipped**, a `policy-recall-skipped` log line is emitted with reason `no_active_verification_story` or `no_target_boundary`.
+
+**Observability**:
+- `policy-recall-lookup` is emitted before any recalled skill is inserted
+- It includes `requestedScenario`, `checkedScenarios[]`, `selectedBucket`, `selectedSkills[]`, `rejected[]`, and `hintCodes[]`
+- This is the canonical machine-readable explanation for why route-scoped recall did or did not fire
+
 ### Unified Ranker
 
 **Source**: `patterns.mts:rankEntries()`

docs/06-runtime-internals.md

@@ -28,6 +28,7 @@ This document covers implementation details that go beyond the pipeline overview
    - [Profiler Boost (+5)](#profiler-boost-5)
    - [Vercel.json Key Routing (±10)](#verceljson-key-routing-10)
    - [Special-Case Boosts](#special-case-boosts)
+   - [Route-Scoped Verified Policy Recall](#route-scoped-verified-policy-recall)
    - [Ranking Function](#ranking-function)
    - [Budget Enforcement](#budget-enforcement)
    - [Prompt Signal Scoring](#prompt-signal-scoring)
@@ -507,6 +508,7 @@ Every matched skill receives an **effective priority** computed from its base pr
 | Setup-mode bootstrap | **+50** | `bootstrap` skill | Greenfield or ≥3 bootstrap hints |
 | TSX review trigger | **+40** | `react-best-practices` | After N `.tsx` edits (default 3) |
 | Dev-server verify | **+45** | `agent-browser-verify` | Dev server command detected |
+| Policy recall | *splice at idx 1* | Any verified skill | Active story + target boundary + policy evidence |
 
 ### Base Priority Range (4–8)
 
@@ -556,6 +558,79 @@ If the skill's associated key **exists** in `vercel.json` → +10. If the skill
 - **Dev-server verify (+45)**: On `npm run dev`, `next dev`, `vercel dev`, etc., injects `agent-browser-verify` + `verification` companion. Capped at 2 injections per session (loop guard).
 - **Vercel env help**: One-time injection when `vercel env add/update/pull` commands are detected.
 
+### Route-Scoped Verified Policy Recall
+
+**Source**: `hooks/src/policy-recall.mts` → `selectPolicyRecallCandidates()`
+
+Policy recall is a **post-ranking injection stage** (Stage 4.95) that fires between ranking and skill body loading. It is fundamentally different from policy boosts:
+
+| Aspect | Policy Boost | Policy Recall |
+|--------|-------------|---------------|
+| Input | Skill already matched by patterns | Skill **not** matched by patterns |
+| Effect | Adjusts `effectivePriority` | Splices skill into `rankedSkills` array |
+| Trace field | `policyBoost` (number) | `synthetic: true`, `pattern.type: "policy-recall"` |
+| Reason code | `"policy-boost"` | `"route-scoped-verified-policy-recall"` |
+| Trigger | Always (when policy data exists) | Only when active verification story + target boundary exist |
+
+**Selector algorithm** (`selectPolicyRecallCandidates`):
+
+1. Generate scenario key candidates via `scenarioKeyCandidates()` — exact route, wildcard (`*`), legacy 4-part key
+2. For each candidate key (in precedence order), look up the policy bucket
+3. Filter entries: `exposures >= 3`, `successRate >= 0.65`, `policyBoost >= 2`, not in `excludeSkills`
+4. Sort: `recallScore` DESC → `exposures` DESC → `skill` ASC
+5. Return first qualifying bucket's top `maxCandidates` entries (default 1) — no cross-bucket merging
+
+**Recall score formula**:
+```
+recallScore = derivePolicyBoost(stats) × 1000
+            + round(successRate × 100) × 10
+            + directiveWins × 5
+            + wins
+            − staleMisses
+```
+
+Where `successRate = (wins + directiveWins × 0.25) / max(exposures, 1)`.
+
+**Insertion semantics**: The recalled skill is spliced at `index = rankedSkills.length > 0 ? 1 : 0`, ensuring it never preempts the strongest direct match. It then flows through normal budget enforcement and cap logic.
+
+**Synthetic trace marking**: All recalled skills are added to the `syntheticSkills` set and appear in the routing decision trace with:
+```json
+{
+  "skill": "<name>",
+  "synthetic": true,
+  "pattern": { "type": "policy-recall", "value": "route-scoped-verified-policy-recall" },
+  "summaryOnly": false
+}
+```
+
+**Log events**:
+- `policy-recall-injected` (debug): Emitted per recalled skill with `skill`, `scenario`, `insertionIndex`, `exposures`, `wins`, `directiveWins`, `successRate`, `policyBoost`, `recallScore`
+- `policy-recall-skipped` (debug): Emitted when preconditions fail, with `reason`: `"no_active_verification_story"` or `"no_target_boundary"`
+- `policy-recall-lookup` (debug): Emitted before any recalled skill is inserted, with `requestedScenario`, `checkedScenarios[]`, `selectedBucket`, `selectedSkills[]`, `rejected[]`, and `hintCodes[]`
+
+### Routing Doctor (`session-explain --json`)
+
+`session-explain` includes an additive `doctor` object that explains the latest routing decision without changing routing behavior.
+
+```json
+{
+  "doctor": {
+    "latestDecisionId": "abc123",
+    "latestScenario": "PreToolUse|flow-verification|clientRequest|Bash|/settings",
+    "latestRanked": [],
+    "policyRecall": {
+      "selectedBucket": "PreToolUse|flow-verification|clientRequest|Bash|/settings",
+      "selected": [],
+      "rejected": [],
+      "hints": []
+    },
+    "hints": []
+  }
+}
+```
+
+The contract is additive-only and intended for downstream agents, CI diagnostics, and local operator debugging.
+
 ### Ranking Function
 
 **Source**: `hooks/src/patterns.mts` → `rankEntries()`

docs/skill-injection.md

@@ -764,3 +764,64 @@ This catches `cookies()` calls without `await`, but skips client components (whi
 | `VERCEL_PLUGIN_LOG_LEVEL` | `off` | — | `off` / `summary` / `debug` / `trace` |
 | `VERCEL_PLUGIN_HOOK_DEDUP` | — | — | `off` to disable dedup entirely |
 | `VERCEL_PLUGIN_AUDIT_LOG_FILE` | — | — | Audit log path or `off` |
+
+---
+
+## Learned Routing Rulebook & Capsule Provenance
+
+When the routing-policy compiler promotes verified rules into a **Learned Routing Rulebook**, the ranking pipeline can apply per-rule boosts at injection time. Every decision capsule records which rule (if any) fired via the `rulebookProvenance` field, so downstream consumers never need to re-derive ranking state.
+
+### Canonical Rulebook JSON
+
+```json
+{
+  "version": 1,
+  "createdAt": "2026-03-28T08:15:00.000Z",
+  "sessionId": "sess_123",
+  "rules": [
+    {
+      "id": "PreToolUse|flow-verification|uiRender|Bash|agent-browser-verify",
+      "scenario": "PreToolUse|flow-verification|uiRender|Bash",
+      "skill": "agent-browser-verify",
+      "action": "promote",
+      "boost": 8,
+      "confidence": 0.93,
+      "reason": "replay verified: no regressions, learned routing matched winning skill",
+      "sourceSessionId": "sess_123",
+      "promotedAt": "2026-03-28T08:15:00.000Z",
+      "evidence": {
+        "baselineWins": 4,
+        "baselineDirectiveWins": 2,
+        "learnedWins": 4,
+        "learnedDirectiveWins": 2,
+        "regressionCount": 0
+      }
+    }
+  ]
+}
+```
+
+### Decision Capsule Provenance
+
+When a rulebook rule fires, the capsule includes:
+
+```json
+{
+  "rulebookProvenance": {
+    "matchedRuleId": "PreToolUse|flow-verification|uiRender|Bash|agent-browser-verify",
+    "ruleBoost": 8,
+    "ruleReason": "replay verified: no regressions, learned routing matched winning skill",
+    "rulebookPath": "/tmp/vercel-plugin-routing-policy-<hash>-rulebook.json"
+  }
+}
+```
+
+When no rule fires, the field is `null`:
+
+```json
+{
+  "rulebookProvenance": null
+}
+```
+
+Each ranked entry in the capsule's `ranked` array also carries the per-skill fields `matchedRuleId`, `ruleBoost`, `ruleReason`, and `rulebookPath` for full traceability.

generated/build-from-skills.manifest.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "generatedAt": "2026-03-23T18:09:18.986Z",
+  "generatedAt": "2026-03-28T19:42:43.133Z",
   "templates": [
     {
       "template": "agents/ai-architect.md.tmpl",

generated/skill-catalog.md

@@ -1,7 +1,7 @@
 # Skill Catalog
 
 > Auto-generated by `scripts/generate-catalog.ts` — do not edit manually.
-> Generated: 2026-03-23T18:07:35.703Z
+> Generated: 2026-03-28T00:24:28.407Z
 > Skills: 39
 
 ## Table of Contents

generated/skill-manifest.json

@@ -1,6 +1,12 @@
 {
-  "generatedAt": "2026-03-23T18:09:21.758Z",
+  "generatedAt": "2026-03-28T19:42:43.059Z",
   "version": 2,
+  "excludedSkills": [
+    {
+      "slug": "fake-banned-test-skill",
+      "reason": "test-only-pattern"
+    }
+  ],
   "skills": {
     "vercel-agent": {
       "priority": 4,

hooks/cli-routing-replay.mjs

@@ -0,0 +1,33 @@
+// hooks/src/cli-routing-replay.mts
+import { replayRoutingSession } from "./routing-replay.mjs";
+import { createLogger } from "./logger.mjs";
+var log = createLogger();
+var sessionId = process.argv[2];
+if (!sessionId) {
+  log.summary("cli_error", { reason: "missing_session_id" });
+  process.stderr.write(
+    JSON.stringify({
+      ok: false,
+      error: "missing_session_id",
+      usage: "node cli-routing-replay.mjs <sessionId>"
+    }) + "\n"
+  );
+  process.exit(1);
+}
+try {
+  const report = replayRoutingSession(sessionId);
+  log.summary("cli_complete", {
+    sessionId,
+    traceCount: report.traceCount,
+    scenarioCount: report.scenarioCount,
+    recommendationCount: report.recommendations.length
+  });
+  process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+} catch (err) {
+  const message = err instanceof Error ? err.message : String(err);
+  log.summary("cli_error", { reason: "replay_failed", message });
+  process.stderr.write(
+    JSON.stringify({ ok: false, error: "replay_failed", message }) + "\n"
+  );
+  process.exit(2);
+}