fix(api): implement GET /api/guardrails + POST /api/guardrails/test, drop shadow/guardrails doc-fiction (#3496)

[diegosouzapw]

Closes #3496

Problem

docs/reference/API_REFERENCE.md documented a /api/guardrails* (5 routes) and /api/shadow* (5 routes) surface that did not exist — doc-fiction flagged by the check-docs-symbols quality gate (PR #3471) and frozen in KNOWN_STALE_DOC_REFS.

Fix

The guardrail pipeline is real (src/lib/guardrails/ — pii/promptInjection/visionBridge via guardrailRegistry), so I implemented the two routes that map to actual behavior and removed the fictional rest:

• GET /api/guardrails — lists the registered guardrails + status (name / enabled / priority), management-scoped via requireManagementAuth.
• POST /api/guardrails/test — dry-runs the pre-call pipeline (runPreCallHooks) over a sample input, returning the per-guardrail verdict + (possibly masked) payload. Honors disabledGuardrails.
• Removed the fictional /[id]/enable, /[id]/disable, /logs rows (guardrails are per-request via the x-omniroute-disabled-guardrails header — no persisted enable/disable surface) and the entire /api/shadow* table (shadow A-B comparison is combo-config + the real GET /api/combos/metrics).
• Dropped all 9 guardrails/shadow entries from KNOWN_STALE_DOC_REFS (allowlist 15 → 6).

Validation (Hard Rule #18 — TDD)

tests/unit/guardrails-api-3496.test.ts (RED → GREEN): route-list, dry-run pipeline, disabledGuardrails skip, 400 on missing input, plus a gate regression asserting the allowlist no longer freezes guardrails/shadow AND API_REFERENCE.md resolves cleanly through findStaleDocApiRefs.

• ✅ node --test tests/unit/guardrails-api-3496.test.ts (5/5)
• ✅ node scripts/check/check-docs-symbols.mjs (OK — 6 stale frozen, was 15)
• ✅ npm run typecheck:core
• ✅ eslint clean on new files

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

The PR implements GET /api/guardrails and POST /api/guardrails/test to resolve documentation fiction flagged by the check-docs-symbols quality gate. All changes are clean:

• Route handlers follow existing patterns in the codebase (CORS, management auth, error handling)
• Zod schema properly validates input with union types for flexible payload
• Tests cover all expected behaviors including the regression guard for the docs check
• Documentation updates accurately reflect the implemented surface

Files Reviewed (6 files)

• src/app/api/guardrails/route.ts — clean
• src/app/api/guardrails/test/route.ts — clean
• tests/unit/guardrails-api-3496.test.ts — clean
• scripts/check/check-docs-symbols.mjs — clean
• docs/reference/API_REFERENCE.md — clean
• CHANGELOG.md — clean

---

_{Reviewed by laguna-m.1-20260312:free · 1,606,426 tokens}