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

Decisions: executor-gatekeeper-hook

Key Decisions

Gatekeeper stays in VerifierInputHook

Decision: Gatekeeper is integrated inside VerifierInputHook, after Executor output parsing and before Verifier model execution.

Reason: The user explicitly chose to keep this version in the Verifier hook and not move validation into Executor hook. This preserves the current workflow orchestration.

No retry in this phase

Decision: Gatekeeper failure does not trigger automatic Executor retry.

Reason: Retry behavior is intentionally deferred. This phase only validates, exposes, and audits deterministic failures.

Initial rule set is intentionally small

Decision: Stage two implements only schema.executor_v2 and evidence.invocation_ref as hard checks.

Reason: These rules catch the highest-confidence physical failures with low implementation risk. Excerpt similarity, hallucination phrases, and evidence utilization remain later enhancements.

No new database schema

Decision: Persist gatekeeper_result in existing diagnosis_session.self_evaluation.verifier_evaluation.

Reason: The user asked to keep database fields minimal. Existing JSON audit storage is enough for this phase.

Internal interface impact

Decision: This is an L2 internal interface extension.

Impact:

• Verifier payload gains gatekeeper_result.
• VerifierContextHolder gains Gatekeeper result storage.
• self_evaluation.verifier_evaluation gains gatekeeper_result.
• No external API, DTO, database table, or schema migration changes.

Deferred Decisions

• Whether Gatekeeper should later trigger Executor retry.
• Whether evidence.excerpt_similarity should be hard fail or warn-only.
• Whether hallucination phrase and evidence utilization rules should be config-driven from metadata files.
• How Verifier V2 claim_checks should enforce Gatekeeper failures in code, beyond prompt instruction.

Remaining Risks

• Verifier prompt compliance is not a deterministic guarantee; stage three should make Gatekeeper fail incompatible with PASS in Verifier V2 behavior.
• Excerpt authenticity is not checked in this phase, so real invocation ids can still be paired with misleading excerpt text until a later rule is implemented.