Entrix Fitness Gate System: Continuous Quality Validation in Routa

The Entrix fitness gate system is a declarative quality validation engine that parses front-matter definitions in Markdown files, executes shell commands across tiered test suites, and enforces hard-gate failures to block regressions in the Routa codebase.

The Entrix fitness gate system serves as the central quality checkpoint in the phodal/routa repository, transforming static documentation into executable quality metrics. This system aggregates test results into weighted dimensions—such as code quality, testability, and security—to produce a final fitness score that determines whether code changes meet production standards.

How the Entrix Fitness Gate System Works

Declarative Configuration via Front-Matter

Quality rules live in docs/fitness/*.md files using YAML front-matter. Each file defines dimensions with weights, thresholds, and shell commands. The Entrix Rust crate (located in crates/entrix/) parses these definitions to build the execution plan.

Tiered Execution and Scoping

The system supports three execution tiers defined in docs/fitness/README.md:

• fast (< 30 seconds): Runs linting, type-checking, and quick TypeScript tests
• normal: Adds full TypeScript and Rust test suites plus API contract checks
• deep: Includes end-to-end tests and security scans for comprehensive validation

Each tier targets specific scopes (e.g., ci, local, pre-push) allowing developers to match validation depth to context.

Hard Gates and Quality Enforcement

Metrics marked hard_gate: true in the front-matter trigger immediate pipeline failure, blocking deployment regardless of other scores. Critical hard gates include commands like npm run test:run:fast and cargo test --workspace, ensuring foundational checks never pass silently.

Runtime Architecture and Report Processing

The TypeScript runtime in src/core/fitness/entrix-runner.ts orchestrates execution through three core functions:

Command Construction and Execution

The runEntrixCommand function builds and spawns the CLI invocation:

// Logic derived from src/core/fitness/entrix-runner.ts
const cmd = `entrix run --tier ${tier} --scope ${scope} --json`;
// Spawns process, captures stdout/stderr

The runner executes the Rust Entrix binary (or cargo run -p entrix in development) and awaits the JSON payload.

Data Normalization

normalizeEntrixReport converts raw JSON output into typed EntrixReportData structures. This standardizes metric names, exit codes, and duration formats into a consistent schema for downstream analysis.

Report Summarization

summarizeEntrixReport computes aggregated statistics including finalScore, passRate, failingMetrics, and slowestMetricMs. These values power the quality summaries exposed through Routa's interfaces.

CLI and API Integration

Routa CLI Interface

Invoke the fitness gate via the Rust CLI (crates/routa-cli/src/commands/fitness/fluency/*.rs):

# Fast local validation (lint, type-check, fast tests)

cargo run -p routa-cli -- fitness fluency --tier fast

# Export JSON for CI pipelines

cargo run -p routa-cli -- fitness fluency --format json > fitness.json

HTTP API Exposure

Next.js API routes in src/app/api/fitness/runtime/route.ts forward HTTP requests to the same runner logic. This enables CI jobs and the Tauri desktop client to fetch fitness summaries via endpoints like /api/fitness/runtime, returning the normalized report data as JSON.

Harness Engineering Loop Integration

The fitness results feed into the Harness Monitor (routa harness evolve), which auto-applies low-risk patches, compares historical snapshots for regression detection, and closes the feedback loop on quality trends. This automation leverages the structured output from summarizeEntrixReport to make data-driven decisions about code changes.

Summary

• The Entrix fitness gate system parses docs/fitness/*.md front-matter to define quality metrics, dimensions, and weights.
• Tiered execution (fast, normal, deep) provides flexible validation depth based on developer context and CI stage.
• Hard gates marked in configuration block pipelines immediately upon failure, preventing defective code from progressing.
• The TypeScript runner (src/core/fitness/entrix-runner.ts) normalizes Entrix JSON output and computes aggregated scores via normalizeEntrixReport and summarizeEntrixReport.
• Results are accessible via CLI (routa fitness fluency), HTTP API, and the Harness Monitor for continuous quality management.

Frequently Asked Questions

What files define the fitness metrics in Routa?

Quality metrics are defined in Markdown files located in docs/fitness/*.md, with configuration details specified in YAML front-matter. The authoritative rulebook resides in docs/fitness/README.md, which outlines the tier system, dimension weights, and hard gate specifications. The Rust Entrix crate parses these files to construct the execution graph.

How does the Entrix runner handle command execution?

The runEntrixCommand function in src/core/fitness/entrix-runner.ts constructs an Entrix CLI invocation (e.g., entrix run --tier fast --scope ci --json), spawns the child process, and captures the JSON payload from stdout. It then normalizes this data using normalizeEntrixReport before generating consumable summaries via summarizeEntrixReport.

What is the difference between fast, normal, and deep tiers?

The fast tier executes linting, type-checking, and quick tests in under 30 seconds for rapid feedback. The normal tier adds full TypeScript and Rust test suites plus API contract checks for comprehensive validation. The deep tier includes end-to-end tests and security scans, reserved for release candidates and security audits.

How can I programmatically access fitness results in Routa?

You can import executeEntrixRun from src/core/fitness/entrix-runner in Node.js to execute tiers programmatically and receive typed report data. Alternatively, query the Next.js API routes (e.g., /api/fitness/runtime) for HTTP-based access suitable for CI pipelines, custom dashboards, and the Tauri desktop client.

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