SuperBizAgent-java/openspec/changes/archive/2026-07-07-executor-gatekeeper-hook/proposal.md

Why

Executor V2 makes the output structured, but structure alone does not prevent physical hallucinations such as fabricated invocation ids, removed fields, empty evidence bindings, or mismatched tool names. These failures should be caught deterministically before the Verifier reasons over claims.

This phase adds Gatekeeper inside VerifierInputHook as a deterministic pre-verifier quality gate and persists its result for audit.

What Changes

• Add a Gatekeeper validation service for Executor structured output.
• Add initial rules:
  • schema.executor_v2
  • evidence.invocation_ref
• Add gatekeeper_result to Verifier payload.
• Persist gatekeeper_result under diagnosis_session.self_evaluation.verifier_evaluation.
• Keep Gatekeeper in VerifierInputHook; do not move it to Executor hook.
• Keep retry behavior unchanged; failed Gatekeeper results do not trigger Executor retry in this phase.
• Keep Verifier prompt/output behavior unchanged except that it can see gatekeeper_result.

Capabilities

New Capabilities

None.

Modified Capabilities

• chat-verifier-agent: Verifier input now includes deterministic Gatekeeper results for Executor structured output.

Impact

• Affected hook: VerifierInputHook.
• Affected service/runtime: new Gatekeeper service and VerifierContextHolder.
• Affected persistence: ChatService.persistVerifierEvaluation(...) writes gatekeeper_result into existing self_evaluation.
• Affected repository access: Gatekeeper reads current-session tool_invocation rows via ToolInvocationRepository.
• Affected tests: VerifierInputHookTest and ChatServiceSequentialAgentTest.
• Database schema: no change.