Policy Configuration

Policy Configuration

Use policy invariants to enforce cycle limits and prevent regression. For an overview, see Circular Dependencies.

Strict Policy (Greenfield Projects)

metrics:
  - id: scc

policy:
  invariants:
    # No cycles allowed
    - metric: scc.cycle_count
      op: "=="
      value: 0
      severity: error
      message: "Circular dependencies detected - all modules must be independent"

    # Largest cycle size must be zero in acyclic graphs
    - metric: scc.max_cycle_size
      op: "=="
      value: 0
      severity: error
      message: "Largest cycle must be zero"

    # No nodes should be in cycles
    - metric: scc.total_nodes_in_cycles
      op: "=="
      value: 0
      severity: error
      message: "Modules are stuck in circular dependencies"

Pragmatic Policy (Legacy Codebases)

policy:
  invariants:
    # Don't let cycles grow
    - metric: scc.max_cycle_size
      op: "<="
      value: 5
      severity: error
      message: "Cycle too large (more than 5 nodes)"

    # Limit total damage
    - metric: scc.total_nodes_in_cycles
      op: "<="
      value: 20
      severity: warning
      message: "Too many nodes in cycles"

Gradual Improvement Policy

Track progress over time using baseline comparison:

arxo.yml

metrics:
  - id: scc

policy:
  baseline:
    mode: git
    ref: origin/main

  invariants:
    # Don't let the largest cycle grow
    - metric: scc.max_cycle_size
      op: "<="
      baseline: true  # Compare against baseline
      severity: error
      message: "Largest cycle is growing"

    # Don't let total nodes in cycles increase
    - metric: scc.total_nodes_in_cycles
      op: "<="
      baseline: true
      severity: error
      message: "More modules are getting stuck in cycles"

Policy Metric Reference

Module-Level Metrics

Metric	Use for	Good Direction
scc.cycle_count	Number of cycles	Lower is better (0 = no cycles)
scc.max_cycle_size	Size of largest cycle; use == 0 for zero cycles	Lower is better (0 = no cycles)
scc.total_nodes_in_cycles	Total modules involved in any cycle	Lower is better (0 = no cycles)
scc.component_count	Total SCCs (healthy = node count)	Higher is better (more SCCs = fewer cycles)

Function-Level Metrics (Call Graph)

Metric	Use for	Good Direction
scc.function.cycle_count	Number of function-level cycles	Lower is better (0 = no cycles)
scc.function.max_cycle_size	Largest function-level cycle	Lower is better (0 = no cycles)
scc.function.call_mass	Call volume within cycles (runtime coupling)	Lower is better (0 = no cycles)
scc.function.total_nodes_in_cycles	Functions stuck in call cycles	Lower is better (0 = no cycles)

Further Reading

• SCC Overview - Metric overview and interpretation
• SCC - Fixing Cycles - How to break cycles
• Policy Examples - Real-world policy configurations