SuperBizAgent-java/devflow/projects/2026-07-07-executor-gatekeeper-hook/brief.md

Brief: executor-gatekeeper-hook

Background

Stage one of Executor Structured Output V2 changed Chat Executor output to executor_evidence_v2, removing final-expression fields from Executor. That made the output structured, but it did not yet prevent deterministic evidence attribution failures such as fabricated invocation ids, removed fields, empty evidence bindings, or mismatched tool names.

Goal

Add a deterministic Gatekeeper between Executor output parsing and Verifier model execution.

The Gatekeeper should:

• Validate the initial Executor V2 schema.
• Validate claims[].evidence_bindings[].source_invocation_ids against current-session tool_invocation rows.
• Validate evidence binding tool_name against the persisted invocation tool name.
• Expose a small gatekeeper_result to Verifier and audit persistence.

Scope

Included:

• New Gatekeeper validation service.
• schema.executor_v2 initial rule.
• evidence.invocation_ref initial rule.
• VerifierInputHook payload integration.
• VerifierContextHolder storage.
• ChatService verifier evaluation persistence.
• Minimal verifier prompt update.
• Focused tests for Gatekeeper, hook payload, fabricated invocation ids, tool name mismatch, and persistence.

Excluded:

• No Executor retry on Gatekeeper failure.
• No excerpt similarity rule in this phase.
• No hallucination phrase or evidence utilization rule in this phase.
• No Verifier V2 claim_checks.
• No Composer.
• No database schema changes.

OpenSpec

• Change: openspec/changes/executor-gatekeeper-hook
• Parent stage: openspec/changes/archive/2026-07-07-executor-v2-output-contract