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

Evidence: executor-gatekeeper-hook

Context Evidence

• executor-v2-output-contract established executor_evidence_v2 and removed Executor final-expression fields.
• VerifierInputHook is the existing integration point for explicit Verifier payload construction.
• ChatService.persistVerifierEvaluation(...) is the existing persistence path for verifier audit snapshots.
• ToolInvocationRepository.findBySessionIdOrderByIdAsc(...) provides the current-session invocation pool used by Gatekeeper.

Implementation Evidence

• src/main/java/com/superbiz/agent/service/ExecutorGatekeeperService.java

  • Implements schema.executor_v2.
  • Implements evidence.invocation_ref.
  • Returns status, failed_rules, warnings, and errors.

• src/main/java/com/superbiz/agent/hook/VerifierInputHook.java

  • Runs Gatekeeper after parsing Executor output and building trace summary.
  • Adds gatekeeper_result to Verifier payload.
  • Stores gatekeeper_result in VerifierContextHolder.

• src/main/java/com/superbiz/agent/util/VerifierContextHolder.java

  • Stores per-request Gatekeeper result for later persistence.

• src/main/java/com/superbiz/agent/service/ChatService.java

  • Wires ExecutorGatekeeperService into verifier hook construction.
  • Persists gatekeeper_result under diagnosis_session.self_evaluation.verifier_evaluation.

• src/main/resources/prompts/chat-verifier-prompt.md

  • Documents gatekeeper_result as an input.
  • States Gatekeeper fail must not produce PASS.

Test Evidence

• src/test/java/com/superbiz/agent/service/ExecutorGatekeeperServiceTest.java

  • Covers schema failure and valid pass behavior.
  • Covers fabricated invocation ids and tool name mismatch.

• src/test/java/com/superbiz/agent/hook/VerifierInputHookTest.java

  • Covers Verifier payload containing gatekeeper_result.
  • Covers hook behavior for fabricated invocation ids.

• src/test/java/com/superbiz/agent/service/ChatServiceSequentialAgentTest.java

  • Covers persistence of gatekeeper_result into verifier evaluation.

Validation Evidence

• mvn "-Dtest=ExecutorGatekeeperServiceTest,VerifierInputHookTest,ChatServiceSequentialAgentTest" test

  • Result: passed.
  • Coverage: 23 focused tests.

• cmd /c openspec validate executor-gatekeeper-hook

  • Result: passed.