Layer 5: Specialist Reasoning Agents

[d3v07]

Blocked until d3v07 reviews and approves or requests changes on frex22's Layers 1-4 PR.

Assignee:
d3v07

Branch:
feature/d3v07-layers-5-8-safety-execution-governance

Context:
Use the Layer 5 architecture image as the visual and technical spec. This layer keeps the existing specialist reasoning roles focused on read-only diagnosis and explanation. Agents analyze and explain. Deterministic code still decides.

Goal:
Harden the Specialist Reasoning Agents while preserving the current architecture boundaries.

Current roles to keep:

• Diagnose Agent
• Candidate Agent
• Rationale Agent

Required work:

• Keep all specialist agents read-only.
• Add stricter prompts if needed.
• Ensure each agent output is structured and evidence-grounded.
• Ensure outputs remain inputs to deterministic validation only.
• Preserve current four MVP tool names:
  • explain_slow_query
  • diagnose_candidate
  • compare_candidate_indexes
  • rationalize_recommendation

Non-negotiable constraints:

• Do not allow agents to select the final winner.
• Do not allow agents to apply indexes.
• Do not allow agents to verify runs.
• Do not expose raw credentials to agents.
• Do not change EvidencePack v1 unless explicitly approved.
• Do not rename current tools.
• Do not add mutation authority to any agent.

Acceptance criteria:

• Diagnose, Candidate, and Rationale roles remain clearly read-only.
• Agent prompts or adapters make the expected structured output explicit.
• Deterministic Python remains the only final authority for winner selection.
• Existing agent/tool tests still pass.
• UI/system map language still says agents recommend and deterministic code decides.

Tests:
Run relevant backend and agent tests, including:
uv run pytest tests/unit/test_agent_engine.py tests/unit/test_tools.py tests/unit/test_orchestrator.py -q
uv run pytest -q

Also verify dashboard still builds if UI labels are touched:
cd dashboard && npm run lint
cd dashboard && ./node_modules/.bin/tsc --noEmit
cd dashboard && npm run build

Deviation guard:
Stop and ask before changing EvidencePack v1, renaming tools, adding API routes, adding mutation authority, exposing credentials, or marking VERIFIED from agent output.

[d3v07]

Already covered by main. The three specialist reasoning agents — Diagnose, Candidate, Rationale — are implemented as phase-gated read-only roles with deterministic winner recomputation (agents/, api/agent_engine.py); three distinct Agent Engine reasoning engines are deployed and serving. Verified during the Layers 5–8 assessment; the related rail + governance shipped in #100. Closing as done.