Risk Scoring

[!WARNING] Status: Planned. Risk scoring is part of the governance layer currently under development. The design below describes the planned behavior.

ChooChoo will calculate a Risk Score (0.0 - 10.0) for every proposed change. This score determines whether an agent can proceed autonomously or if human intervention is required via an approval workflow.

The Algorithm

The score is a weighted sum of five factors:

\text{RiskScore} = (I \times 0.25) + (C \times 0.30) + (A \times 0.15) + (H \times 0.15) + (E \times 0.15)

Where:

• I (Impact Radius): How many downstream artifacts are affected? Calculated from the Lineage Graph.
• C (Compliance Sensitivity): Are sensitive fields (PII, HIPAA) involved? Based on compliance tags in Contracts.
• A (Agent Confidence): How confident is the agent (inverse)? Reported via Agent Trace metadata.
• H (Historical Quality): What is the agent's track record? Derived from the Audit Trail and the agent's System Card.
• E (Environment): Is this Prod (high) or Dev (low)? Configured in .choochoorc.

Score Interpretation

When the score exceeds the auto-approve threshold, the CLI returns exit code 10 (APPROVAL_REQUIRED) and the change enters a pending_approval state in the approval workflow. The full scoring breakdown is recorded in the Audit Trail.

Factors Detail

Impact Radius (I)

The Impact Radius is computed by traversing the Lineage Graph downstream from the changed artifact. If a Product modifies its output Contract, ChooChoo finds all consumers and dependents. More downstream dependents — and more critical ones — yield a higher score.

Compliance Sensitivity (C)

Compliance tags on contract fields carry specific weights:

Fields with these tags also trigger special security considerations, including encryption requirements and access restrictions for agents.

Agent Confidence (A)

The confidence value (0.0 - 1.0) is reported in the Agent Trace metadata.confidence field. Lower confidence results in a higher risk contribution. Agents without confidence metadata receive the maximum risk score for this factor.

Historical Quality (H)

ChooChoo queries the Audit Trail for the agent's past performance — how many of its previous changes passed validation without issues. Agents with well-documented System Cards and strong track records receive lower scores.

Environment Risk (E)

• Production: 8
• Staging: 4
• Development: 1

The environment is determined from the configuration and can be overridden per-run via the CLI. In CI/CD pipelines, it's common to set this based on the target branch.

Configuring Thresholds

You can customize the approval thresholds in your .choochoorc configuration and define specific policies in .choochoo/approval-policies.yaml. The requireApproval configuration option lists which compliance tags always trigger mandatory human review regardless of the computed score.

See Approval Workflows for full policy schema documentation.

Related