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

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, 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, 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:

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, 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:

entrix run --tier normal

Create custom rules by adding entries to docs/fitness/custom.rules.yaml. For example, to require a security scan:

- 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 defines the evidence schema and acceptance criteria. Inspect the default configuration:

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:

# 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:

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

Add custom constraints to 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 to specify which artifacts the gate requires:

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:

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

The invocation sequence defined in 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 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.

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) 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, 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 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 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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}