# How to Implement Review Gates with Harness Monitor and Evidence Requirements in Routa

> Implement review gates in Routa using Harness Monitor and evidence requirements. Enforce quality checks with Entrix Fitness and Gate Specialist for robust code delivery.

- Repository: [Fengda Huang/routa](https://github.com/phodal/routa)
- Tags: how-to-guide
- Published: 2026-05-26

---

**Routa treats the Review lane as a mandatory delivery gate that combines the Harness Monitor for runtime observability, Entrix Fitness for policy validation, and the Gate Specialist for verdict decisions to enforce evidence-based quality checks before code reaches Done.**

The **phodal/routa** repository implements a robust review gate pattern that treats quality assurance as a programmable checkpoint. To implement review gates with harness monitor and evidence requirements, you configure three cooperating specialists that verify every change against concrete evidence and fitness policies before permitting progression to the Done lane.

## Understanding the Review Gate Architecture

Routa's review gate follows a three-layer architecture that separates monitoring, policy enforcement, and decision logic. This design ensures that quality gates remain testable, extensible, and strictly evidence-driven.

### The Three Cooperating Specialists

The gate integrates three distinct components:

- **Harness Monitor**: Observes execution context, surfaces Git state, changed files, and execution traces. Located in `crates/harness-monitor`, this runtime component records every command and repository change into the session trace store.

- **Entrix Fitness**: Enforces hard gates and policy constraints including file budgets, test coverage thresholds, and linting rules. Defined in [`docs/fitness/README.md`](https://github.com/phodal/routa/blob/main/docs/fitness/README.md), this engine evaluates fitness functions during the Review stage.

- **Gate Specialist**: Verifies acceptance criteria and issues routing decisions. Configured in [`resources/specialists/workflows/kanban/review.yaml`](https://github.com/phodal/routa/blob/main/resources/specialists/workflows/kanban/review.yaml), this specialist declares required evidence fields and determines whether cards move to Done, return to Dev, or become Blocked.

## Component Configuration

Implementing the review gate requires enabling each component in your Routa workspace.

### Harness Monitor Setup

The Harness Monitor runs as a background task that captures runtime evidence. Start it before processing any cards through the review lane:

```bash
cargo run -p harness-monitor -- --workspace /path/to/workspace --port 4001

```

The monitor registers a background observer that records Git changes, command executions, and diagnostic traces in the session's `traces/` collection. According to [`crates/harness-monitor/README.md`](https://github.com/phodal/routa/blob/main/crates/harness-monitor/README.md), this component provides the `harnessTrace` evidence required by the gate.

### Entrix Fitness Rules

Entrix Fitness validates cards against policy constraints without requiring code changes. The default rule set in `docs/fitness/` already contains `review.gate.evidence.required: true` constraints. Verify your configuration:

```bash
entrix run --tier normal

```

Create custom rules by adding entries to [`docs/fitness/custom.rules.yaml`](https://github.com/phodal/routa/blob/main/docs/fitness/custom.rules.yaml). For example, to require a security scan:

```yaml
- id: review.security-scan.required
  when: lane == "review"
  condition: evidence.securityScan != null
  message: "Missing security scan report"

```

### Gate Specialist Prompt

The gate prompt in [`resources/specialists/workflows/kanban/review.yaml`](https://github.com/phodal/routa/blob/main/resources/specialists/workflows/kanban/review.yaml) defines the evidence schema and acceptance criteria. Inspect the default configuration:

```yaml
name: ReviewGate
evidence:
  - devEvidence   # produced by Dev Crafter

  - harnessTrace  # produced by Harness Monitor

checks:
  - type: acceptance-criterion
    required: true

```

Add new evidence fields to enforce additional requirements. Adding `securityScan` to the evidence list forces the gate to reject cards lacking security reports.

## Step-by-Step Implementation

Follow this sequence to activate the review gate in your Routa deployment.

### Step 1: Initialize the Harness Monitor

From your project root, start the monitor to begin collecting execution evidence:

```bash

# Option A: Direct cargo execution

cargo run -p harness-monitor -- --workspace $(pwd)/workspaces/demo

# Option B: Using the Routa CLI

routa monitor start --workspace /path/to/workspace

```

The monitor exposes traces via the API at `/api/traces/<card-id>` for the gate to consume.

### Step 2: Verify Fitness Rules

Ensure Entrix Fitness evaluates the review gate constraints:

```bash
entrix run --tier normal   # executes all fitness checks including review gates

```

Add custom constraints to [`docs/fitness/custom.rules.yaml`](https://github.com/phodal/routa/blob/main/docs/fitness/custom.rules.yaml) to enforce file budgets, coverage limits, or mandatory scan artifacts.

### Step 3: Configure Evidence Requirements

Modify [`resources/specialists/workflows/kanban/review.yaml`](https://github.com/phodal/routa/blob/main/resources/specialists/workflows/kanban/review.yaml) to specify which artifacts the gate requires:

```yaml
evidence:
  - devEvidence
  - harnessTrace
  - securityScan   # additional required evidence

checks:
  - type: acceptance-criterion
    required: true

```

The **Gate Specialist** uses this configuration to validate incoming cards. Missing evidence fields automatically trigger rejection.

### Step 4: Execute the Review Gate

After a **Dev Crafter** commits changes and produces Dev Evidence, invoke the gate programmatically or via CLI:

```bash
routa gate invoke --lane review --card <card-id>

```

The invocation sequence defined in [`src/core/review/gate.ts`](https://github.com/phodal/routa/blob/main/src/core/review/gate.ts) executes:

1. **Harness Monitor** fetches the latest trace for the card ID
2. **Entrix Fitness** evaluates configured fitness functions against the evidence
3. **Gate Specialist** returns a verdict (`APPROVED` or `REJECTED`) and writes Review Findings to the card

### Step 5: Handle the Verdict

If all checks pass, the card automatically routes to **Done**. If rejected, the gate adds diagnostic evidence via [`src/client/api/gate.ts`](https://github.com/phodal/routa/blob/main/src/client/api/gate.ts) and moves the card to **Dev** or **Blocked** with explanatory notes.

## Evidence Requirements and Workflow

The review gate enforces an evidence-driven workflow that prohibits "soft" approvals. When implemented correctly:

- **Dev Evidence** includes changed files, test results, and per-criterion verification produced by the Dev Crafter
- **Harness Trace** contains runtime execution data and Git state from the monitor
- **Review Findings** document the Gate Specialist's verdict with specific criterion pass/fail status

This pattern ensures that every card reaching **Done** has verifiable artifacts backing the decision, as illustrated in [`docs/ARCHITECTURE.md`](https://github.com/phodal/routa/blob/main/docs/ARCHITECTURE.md).

## Summary

- **Routa** implements review gates through three cooperating specialists: Harness Monitor, Entrix Fitness, and Gate Specialist
- **Harness Monitor** (`crates/harness-monitor`) provides runtime execution traces and Git state evidence
- **Entrix Fitness** (`docs/fitness/`) enforces policy constraints and file budgets without code changes
- **Gate Specialist** ([`resources/specialists/workflows/kanban/review.yaml`](https://github.com/phodal/routa/blob/main/resources/specialists/workflows/kanban/review.yaml)) defines required evidence fields and acceptance criteria
- The gate workflow requires invoking `routa gate invoke --lane review --card <card-id>` after configuring all three components
- Evidence requirements are extensible through YAML configuration rather than code modification

## Frequently Asked Questions

### What evidence does the Harness Monitor capture for review gates?

The **Harness Monitor** captures Git repository state, changed files, command execution traces, and attribution data during development sessions. According to [`crates/harness-monitor/README.md`](https://github.com/phodal/routa/blob/main/crates/harness-monitor/README.md), it stores these artifacts in the session's trace store under `traces/`, making them available to the gate via the `/api/traces/<card-id>` endpoint. This evidence proves what actually occurred during development versus what was claimed.

### How do I add custom fitness rules to the review gate?

Add custom rules to [`docs/fitness/custom.rules.yaml`](https://github.com/phodal/routa/blob/main/docs/fitness/custom.rules.yaml) using the Entrix Fitness rule syntax. Define conditions that check for specific evidence fields or policy constraints, such as requiring security scans or enforcing test coverage thresholds above 80%. The gate automatically evaluates these rules when running `entrix run --tier normal` during the Review stage, rejecting cards that fail any constraint.

### Can I modify the review gate without changing source code?

Yes. The **Gate Specialist** prompt in [`resources/specialists/workflows/kanban/review.yaml`](https://github.com/phodal/routa/blob/main/resources/specialists/workflows/kanban/review.yaml) controls evidence requirements and acceptance criteria through configuration. Adding new evidence types (like `securityScan`) or modifying check parameters requires only editing this YAML file. Similarly, Entrix Fitness rules in `docs/fitness/` configure policy constraints without touching the TypeScript source in [`src/core/review/gate.ts`](https://github.com/phodal/routa/blob/main/src/core/review/gate.ts).

### What happens when a card fails the review gate?

When the **Gate Specialist** returns a `REJECTED` verdict, the system automatically routes the card back to the **Dev** lane or moves it to **Blocked**, depending on failure severity. The gate writes diagnostic evidence to the card detailing which fitness functions failed or which required evidence was missing. This feedback loop ensures developers receive concrete, actionable information about why their changes did not meet quality standards.