Gates Reference

🚦 Gates Reference

🇬🇧 English | 🇧🇷 Português

---

Jev Harness exposes 5 semantic decision gates — each is a typed, non-autoregressive function available across 3 interfaces: CLI pipe, MCP tool, and native SDK (Python / TypeScript / Rust).

All gates share the same contract:

• Input: Raw strings (error logs, task descriptions, evidence)
• Output: Typed response object with calibrated confidence scores
• Exit code: 0 (deterministic action safe) | 1 (LLM or human needed) | 2 (invocation error)

---

Gate 1: triage_test_failure — Test Failure Triage

The most frequently used gate. Analyzes raw test/build failure output and classifies it into an actionable category.

Decision Categories

Category	skip_llm	Exit	Description	Example
ENV_MISSING	true	0	Package not installed or environment variable not set	ModuleNotFoundError: No module named 'scipy'
FLAKY_TRANSIENT	true	0	Non-deterministic failure — retry will likely succeed	ECONNREFUSED, port busy, network timeout
TRIVIAL_ASSERTION	true	0	Simple value mismatch detectable by regex	Off-by-one, string formatting diff
DEEP_LOGIC	false	1	Genuine algorithmic bug requiring reasoning	RecursionError, SegmentationFault, multi-file race condition
CIRCULAR_FAILURE	false	1	Same fix attempted 2+ times without progress	Abort trajectory, notify user

Response Object

@dataclass
class TriageResult:
    category: str           # ENV_MISSING | FLAKY_TRANSIENT | TRIVIAL_ASSERTION | DEEP_LOGIC | CIRCULAR_FAILURE
    confidence: float       # 0.0–1.0 calibrated score
    skip_llm: bool          # True = execute deterministic fix; False = call LLM
    skip_probability: float # 0.0–1.0 probability of safe skip
    severity_score: float   # 1.0 (minor) – 4.0 (critical)
    action_recommendation: str  # Exact shell command or LLM instruction

CLI Usage

# Pipe directly from your test runner (recommended)
pytest 2>&1 | jev-harness test-gate

# Analyze a saved log file
jev-harness test-gate --log error.log

# Machine-readable JSON output
jev-harness test-gate --log error.log --json

# TypeScript (npx)
npm test 2>&1 | npx @ismaelsoilet/jev-harness test-gate

# Rust
cargo test 2>&1 | jev test-gate

Example Output

--- JEV TEST TRIAGE VERDICT ---
Category:         ENV_MISSING
Confidence:       92.0%
Skip LLM Call:    YES (Save Tokens!)
Skip Probability: 96.0%
Severity Score:   1.0 / 4.0
Recommendation:   AUTO-ACTION: Install missing dependency or check environment
                  configuration (Do NOT call LLM).
--------------------------------
Exit code: 0

--- JEV TEST TRIAGE VERDICT ---
Category:         DEEP_LOGIC
Confidence:       88.0%
Skip LLM Call:    NO — Forward to frontier model
Severity Score:   3.5 / 4.0
Recommendation:   FRONTIER LLM: Genuine logic defect detected. Send filtered
                  traceback to Claude Fable 5.1 / GPT-6 Astra.
--------------------------------
Exit code: 1

MCP Tool

{
  "tool": "jev_triage_test_failure",
  "arguments": {
    "error_output": "ModuleNotFoundError: No module named 'scipy'\n...",
    "session_context_tokens": 45000
  }
}

Python SDK

from jev_harness import triage_test_failure, JevClient

client = JevClient()
result = triage_test_failure(raw_traceback, client=client)

if result.skip_llm:
    print(f"Fix deterministically: {result.action_recommendation}")
    # e.g.: "pip install scipy"
else:
    call_frontier_llm(filtered_error=result.action_recommendation)

---

Gate 2: should_abort_trajectory — Doom Loop Breaker

Evaluates whether an agent's proposed plan is repeating a previously failed path. Prevents circular doom loops that burn 200,000+ tokens.

Abort Triggers

The gate recommends abort (should_abort=true, exit 1) when:

• The proposed action matches a previously failed attempt by ≥ 75% semantic similarity
• The same error pattern has occurred ≥ 2 times in history
• Proposed plan contradicts verified successful outcomes in history

Response Object

@dataclass
class AbortDecision:
    should_abort: bool          # True = halt and notify user
    confidence: float           # 0.0–1.0
    reasoning_summary: str      # Human-readable explanation of why
    suggested_alternative: str  # Alternative approach suggestion (if abort)

CLI Usage

jev-harness abort-check \
  --plan "Retry rewriting the entire database schema without backup" \
  --history "Attempt 1 failed with timeout. Attempt 2 failed with circular foreign key error."

# JSON output
jev-harness abort-check \
  --plan "Same migration again" \
  --history "Failed twice: timeout, then FK constraint" \
  --json

Example Output

--- JEV TRAJECTORY GUARD ---
Should Abort:    YES
Confidence:      91.0%
Reason:          Proposed plan is semantically identical to two previous
                 failed attempts. Circular doom loop detected.
Alternative:     Re-align with user. Consider a fundamentally different
                 approach: staged migration with FK deferral.
----------------------------
Exit code: 1

MCP Tool

{
  "tool": "jev_should_abort_trajectory",
  "arguments": {
    "proposed_step": "Retry rewriting the database schema",
    "recent_attempts_summary": "Attempt 1: timeout. Attempt 2: FK constraint error."
  }
}

Python SDK

from jev_harness import should_abort_trajectory

abort = should_abort_trajectory(
    proposed_step="Retry identical refactoring",
    recent_attempts_summary="Attempt 1 failed, attempt 2 failed the same way",
    client=client,
)
if abort.should_abort:
    notify_user(f"Dead end reached: {abort.reasoning_summary}")
    suggest_alternative(abort.suggested_alternative)

---

Gate 3: route_model_tier — Intelligent Model Router

Selects the most cost-effective model tier for a given task, preventing over-engineering and unnecessary frontier spend.

Routing Tiers

Tier	Model	Use Case	Cost
DETERMINISTIC	Local script / bash	Typo fix, formatting, git status, simple rename	$0.00
FAST_SYSTEM1	Gemini 3.8 Flash / Qwen Omni Flash	Simple feature, moderate complexity	$0.002/call
BALANCED	Gemini 3.5 Pro / DeepSeek V4-Pro	Standard feature implementation	$0.05/call
HEAVY_SYSTEM2	Claude Fable 5.1 / GPT-6 Astra	Deep architecture, multi-file race conditions	$1.00+/call

CLI Usage

# Simple task → DETERMINISTIC
jev-harness route --task "Fix typo in docstring and reformat with black"
# → TIER: DETERMINISTIC | Model: Direct Python/Bash Script (0 LLM Tokens)

# Complex task → HEAVY_SYSTEM2
jev-harness route --task "Refactor distributed actor supervision tree across 14 modules"
# → TIER: HEAVY_SYSTEM2 | Model: Claude Fable 5.1 / GPT-6 Astra (~$10.00/1M in)

# JSON output for programmatic use
jev-harness route --task "Add unit test for the parseDate helper" --json

---

Gate 4: verify_step_completion — Step Verification

Calibrated, evidence-based verification of whether a step's success criteria have been met. Prevents agents from falsely claiming completion.

CLI Usage

jev-harness verify \
  --criteria "Must export format_date function and pass all 10 unit tests" \
  --output "All 10 unit tests passed in 0.02s. format_date exported in index.ts."

# → VERIFIED: true | Confidence: 97.0%

jev-harness verify \
  --criteria "All database migrations must complete without errors" \
  --output "Migration 003 failed with FK constraint violation."

# → VERIFIED: false | Confidence: 99.0%
# Exit code: 1

Response Object

@dataclass
class VerificationResult:
    verified: bool          # True = criteria met; False = criteria not met
    confidence: float       # 0.0–1.0
    gaps: list[str]         # Specific unmet criteria (if verified=False)
    evidence_summary: str   # What evidence was found

---

Gate 5: modulate_reasoning_effort — Astra-Jev

Dynamically governs per-generation reasoning effort for frontier models. Compiles provider-specific API parameters to eliminate unnecessary CoT latency and token spend on mechanical steps.

→ See the dedicated Astra-Jev page for full documentation.

Quick Reference

# Evaluate task for DeepSeek
jev-harness reasoning-effort \
  --context "git status and check changed files" \
  --target-provider deepseek --json
# → {"effort": "low", "provider_params": {"extra_body": {"thinking": {"type": "enabled"}}, "reasoning_effort": "low"}}

# Evaluate for Anthropic
jev-harness reasoning-effort \
  --context "Architect distributed consensus with Raft" \
  --target-provider anthropic --json
# → {"effort": "high", "provider_params": {"thinking": {"type": "adaptive"}, "output_config": {"effort": "high"}}}

---

Cross-Gate: Canonical Agent Decision Protocol

Inject these rules into any agent's system prompt to enforce token-optimal behavior:

MANDATORY PROTOCOL — Jev Harness Token Governance:

1. ZERO-LLM TRIAGE: Before calling any frontier LLM on a test/build failure,
   run `jev-harness test-gate` (or MCP tool `jev_triage_test_failure`).
   If skip_llm=true (exit 0): execute action_recommendation directly. No LLM call.
   If skip_llm=false (exit 1): forward ONLY the filtered action_recommendation
   to the frontier model — NOT the full raw traceback.

2. CIRCUIT BREAKER: If any operation fails 2 consecutive times, MUST run
   `jev-harness abort-check` (or `jev_should_abort_trajectory`).
   If should_abort=true (exit 1): HALT. Notify user. Ask for direction.
   Never burn tokens on a 3rd identical attempt.

3. REASONING MODULATION (Astra-Jev): For mechanical operations
   (git commands, file reads, formatting, simple edits):
   call `jev_modulate_reasoning_effort` and inject the returned
   provider_params into the API call to disable or lower reasoning effort.
   Reserve high/adaptive reasoning ONLY for architectural decisions and
   complex algorithmic problems.