Governance & Golden Path

CodeRadius includes a Governance-as-Code engine that evaluates declarative policy rules against your live architecture graph. Each rule is a YAML file containing a Cypher query that evaluates all in-scope entities — returning both compliant and non-compliant results — and surfaces them as structured evaluations in the Architecture Dashboard.

This is the enforcement layer for your organization's Golden Path: the curated set of standards, tooling choices, and operational patterns that every team should follow.

How It Works

The Evaluation Pipeline

1. Rule Loading       → YAML files in rules/
2. Cypher Execution   → Each rule's query runs against the graph
3. Validation         → Results are validated and normalized
4. Graph Persistence  → Evaluations stored as :PolicyEvaluation nodes (pass + fail)
5. Dashboard Render   → Evaluations appear in the Governance tab with compliance badges

The cr check command evaluates governance rules and produces a report. Each rule produces evaluations for every entity in scope — both passing and failing. Evaluations are persisted to the graph as PolicyEvaluation nodes linked to the evaluated entity via [:EVALUATED] edges.

Where Evaluations Appear

Evaluations surface in the Governance section of the Architecture Dashboard:

• Compliance badges — COMPLIANT (green), PARTIAL (yellow), NON-COMPLIANT (red) per entity
• Per-rule compliance ratios — e.g., "8/10 compliant" with pass/fail counts
• Compliance percentage — Global compliance % in the dashboard header
• Severity badges (VIOLATION, DRIFT, ADVISORY) for failing evaluations
• Structured checklists — for rules that return itemized checks (e.g., "✓ setup ✗ test ✗ run")
• Fuzzy matching hints — when a check fails, the dashboard suggests similar items found in the repository
• Passing rules section — expandable green checklist showing which rules each entity passes

Policy Rule Schema

Each policy rule is a YAML file with the following structure:

id: cr-301-makefile-targets
name: Makefile mandatory targets
description: >
  Human-readable explanation of what this rule checks
  and why it matters.
severity: error          # error | warning | info
scope: repository        # repository | service | package
failFast: false          # if true, stop evaluation on first failure
tags:
  - golden-path
  - makefile

query: |
  MATCH (r:Repository)
  // ... Cypher query that evaluates entities ...
  RETURN
    r.id         AS entityId,
    r.name       AS entityName,
    'repository' AS entityType,
    CASE WHEN <condition> THEN 'fail' ELSE 'pass' END AS status,
    CASE WHEN <condition> THEN 'Description of the violation' ELSE '' END AS detail

Required Fields

Optional Fields

The Query Contract

Every rule's Cypher query must return rows with these exact column names:

Each row returned represents one evaluation. The query must return all in-scope entities — both compliant and non-compliant. The engine uses the status column to partition results into passing and failing evaluations.

Structured Detail Protocol

For rules that check multiple items per entity (e.g., "does this Makefile have setup, test, and run targets?"), the query can return a structuredDetail map that enables rich UI rendering.

The Two-Way Payload

RETURN
  // ... standard columns ...
  { checks: checks, found: targets } AS structuredDetail

The structuredDetail map contains two arrays:

How It Renders

When an evaluation has a structuredDetail, the dashboard renders it as a vertical checklist instead of plain text:

• ✓ setup — green checkmark, full opacity
• ✗ test — red cross, full opacity, with hover tooltip: "found 'tests' — did you mean 'test'?"
• ✗ run — red cross, full opacity

The fuzzy matching is powered by a Levenshtein distance algorithm that compares each failing check label against the found array to suggest the closest match.

Example: Makefile Targets Rule

query: |
  MATCH (r:Repository)
  OPTIONAL MATCH (r)-[:HAS_TASK]->(t:Task)
  WHERE t.source = 'makefile'
  WITH r, collect(t.name) AS targets
  WITH r, targets,
       [x IN ['setup', 'test', 'run'] | {
         label: x,
         status: CASE WHEN x IN targets THEN 'pass' ELSE 'fail' END
       }] AS checks,
       [x IN ['setup', 'test', 'run'] WHERE NOT x IN targets] AS missingTargets
  RETURN
    r.id         AS entityId,
    r.name       AS entityName,
    'repository' AS entityType,
    CASE WHEN size(missingTargets) = 0 THEN 'pass' ELSE 'fail' END AS status,
    CASE WHEN size(missingTargets) = 0 THEN '' ELSE 'Missing mandatory Makefile targets' END AS detail,
    { checks: checks, found: targets } AS structuredDetail

This query:

1. Matches all repositories and collects their Makefile task names
2. Builds a checks array with pass/fail status for each required target
3. Returns all repositories with a status of 'pass' or 'fail'
4. Returns both a human-readable detail string and a machine-readable structuredDetail map

Standard Rule Library

To accelerate adoption, CodeRadius provides a curated library of standard governance rules in the coderadius-ai/governance-rules-core repository.

To use them, clone the repository into your local rules directory:

git clone https://github.com/coderadius-ai/governance-rules-core.git rules/core

The library includes production-tested policies for Makefile targets, TypeScript strict mode, Docker base image registries, team ownership, CI/CD configuration, and service health. See the full rule catalog for details.

Writing Custom Rules

To add a custom policy rule:

1. Create a YAML file in rules/ (or any subdirectory under rules/)
2. Follow the schema described above
3. Test the Cypher query directly in Memgraph Lab before embedding it in the rule
4. Re-run cr check --output graph to persist evaluations
5. Run cr ui to see the compliance dashboard

Tips for Writing Effective Rules

• Start with Memgraph Lab. Write and debug your Cypher query interactively before wrapping it in YAML.
• Return all in-scope entities. Use CASE WHEN ... THEN 'fail' ELSE 'pass' END AS status — do not filter out compliant entities.
• Use structuredDetail for multi-item checks. If your rule checks 3+ conditions per entity, return a checks array for rich rendering.
• Include the found array. If your rule checks for expected items, also return the actual items found. This enables fuzzy matching in the UI.
• Use native Cypher maps, not string concatenation. Return { checks: checks, found: targets } as a native map. The executor handles JSON serialization.

Testing a Rule Query

-- Run this in Memgraph Lab to preview evaluations before adding the rule
MATCH (r:Repository)
OPTIONAL MATCH (r)-[:HAS_TASK]->(t:Task)
WHERE t.source = 'makefile'
WITH r, collect(t.name) AS targets
WITH r, targets,
     [x IN ['setup', 'test', 'run'] WHERE NOT x IN targets] AS missingTargets
RETURN
  r.name AS repo,
  CASE WHEN size(missingTargets) = 0 THEN 'PASS' ELSE 'FAIL' END AS status,
  missingTargets
ORDER BY status, r.name

Querying Evaluations Directly

You can query PolicyEvaluation nodes directly in Memgraph Lab for custom analysis:

-- All evaluations grouped by rule
MATCH (pe:PolicyEvaluation)
RETURN pe.ruleName AS rule, pe.status AS status, count(pe) AS total
ORDER BY rule, status

-- Compliance summary per rule
MATCH (pe:PolicyEvaluation)
RETURN pe.ruleName AS rule,
       count(CASE WHEN pe.status = 'pass' THEN 1 END) AS passing,
       count(CASE WHEN pe.status = 'fail' THEN 1 END) AS failing,
       count(pe) AS total
ORDER BY failing DESC

-- All violations for a specific repository
MATCH (r:Repository {name: 'my-service'})-[:EVALUATED]->(pe:PolicyEvaluation)
WHERE pe.status = 'fail'
RETURN pe.ruleName, pe.severity, pe.detail

-- Fully compliant entities (pass all evaluated rules)
MATCH (entity)-[:EVALUATED]->(pe:PolicyEvaluation)
WITH entity, collect(pe.status) AS statuses
WHERE NOT 'fail' IN statuses
RETURN entity.name AS entity, size(statuses) AS rulesEvaluated
ORDER BY entity.name

Graph Lifecycle

PolicyEvaluation nodes use a full-replace strategy:

1. Pre-clean — Before evaluating, all existing PolicyEvaluation nodes for the evaluated rules are deleted
2. Write — New evaluations (pass + fail) are persisted with fresh timestamps
3. Orphan GC — Evaluations from deleted rules (YAML removed) are garbage-collected

This ensures the graph always reflects the current compliance state. No stale data accumulates.

Design Notes

Rules are evaluated via Cypher queries against the graph, validated, and persisted as PolicyEvaluation nodes. The dashboard handles rendering — including graceful degradation (if structured data is malformed, the plain detail string is used as fallback) and fuzzy matching (computed in the browser, not in Cypher).

Rules are pure queries. They return native Cypher maps; the system handles validation and serialization.

Further Reading

• Architecture Dashboard — The unified dashboard that renders governance evaluations
• CLI Reference — cr check command documentation
• coderadius.yaml — Per-repository configuration that policies can check against