Phase 4 (skipped): Guardrails, prompt library, agent scaffolding #11

Context

This is a skipped phase, not new scope. docs/ARCHITECTURE.md's roadmap lists:

5. Phase 4: Guardrails, prompt library, agent library scaffolding
6. Phase 4a: Session/context lifecycle

4a and 4b were built; Phase 4 proper was never done. backend/app/guardrails/ and backend/app/prompts/ exist in the architecture docs and directory layout but contain no implementation. It got skipped rather than deliberately dropped.

Why it matters now

Every user-supplied string reaching the LLM is currently unvalidated. There is no prompt-injection defense, no output filtering, no PII handling on the path between a user's message and the model. For a project whose stated posture is enterprise/air-gapped with hard compliance requirements, that is a conspicuous gap — and it is cheaper to add before more surface area accumulates on top.

Scope

1. Input guardrails (backend/app/guardrails/)
   • Prompt-injection heuristics on user input
   • Length/token limits before hitting the LLM
   • Decide and document what happens on a trip: reject, sanitize, or flag. Pick one and be consistent.
2. Output guardrails
   • Response filtering before it reaches the user
   • PII detection — worth deciding whether in scope, since it interacts with the audit log
3. Prompt library (backend/app/prompts/)
   • Versioned, testable prompt templates instead of inline strings
   • Note docs/AGENT_PROMPTS.md already exists — reconcile with it rather than duplicating
4. Agent library scaffolding — the pattern for adding a second agent alongside chat_agent

Design constraints

• Guardrails are deterministic logic, so per AGENTS.md they are fully TDD-able with no LLM mocking beyond the existing boundary. No excuse for thin tests here.
• Consider whether a tripped guardrail should write to AuditLog — it is append-only and already carries actor/timestamp. Probably yes for input rejections; that is a compliance-relevant event.
• Guardrails sit between the endpoint and the agent. Watch that they do not break streaming (deferred, but do not foreclose it).

Open question for the owner

Phase 4 was skipped once already. Worth an explicit decision: do it now, do it after Phase 5 deploys, or formally drop it? Leaving it implicitly skipped is the worst of the three — it stays in the docs as if planned while never getting built.