werkrevisor/docs/prs/2026-10-08-PR#63-risk-in-repo-config.md

PR#63: each repository chooses and tunes its risk categories in .werkrevisor.toml

WARNING: This document describes only the change applied in this PR. It may already be outdated once the next PR is merged. Historic PR documentation is not maintained along with new PRs; treat it as a snapshot.

The Problem

Which risks matter depends on the ecosystem of a repository, and since PR#46 werkrevisor keeps them in templates. Only the host config selects a template, and no repository can change one category. werkcrappit, a Gradle and PIT plugin without Spring, fits jvm-spring-backend only in part, and werkator, a build system, has its own risks, e.g. in the slots of parallel builds. The plan of 2026-10-08 moves the categories into the .werkrevisor.toml of each repository.

Non-Goals

• No change of the templates; they stay the starting point.
• No change of the rule that every change of .werkrevisor.toml needs a human and counts only from the default branch.

The Scenarios

Feature: each repository chooses and tunes its risk categories

Background

• Given the host config judges every file with Jev and allows the repository to tune the risks

Scenario#63.01: the repository chooses the template

So that a repository names its ecosystem itself.

• Given the .werkrevisor.toml of the repository sets [path_judge] risk_template = "jvm-spring-backend"
• When werkrevisor reviews a PR of this repository
• Then Jev answers the categories of this template

Verified by

• test_risk_repo: test_the_repository_chooses_the_template

Scenario#63.02: the repository changes the threshold or the consequence of a category

So that a category that is noise in this repository gives only a hint.

• Given the repository sets action = "hint" for the category concurrency
• When Jev rates a changed file at or above its threshold for this category
• Then the category gives only a hint

Verified by

• test_risk_repo: test_the_repository_changes_the_threshold_or_the_consequence_of_a_category

Scenario#63.03: the repository switches a category off

So that a category without meaning in this repository costs no question and no hint.

• Given the repository sets action = "off" for the category sql_injection
• When werkrevisor asks Jev about a changed file
• Then Jev gets no question for this category

Verified by

• test_risk_repo: test_the_repository_switches_a_category_off

Scenario#63.04: the repository adds an own category

So that a repository names a risk that no template knows, e.g. the slots of parallel builds.

• Given the repository defines a category with name, title, question, threshold and action
• When Jev rates a changed file at or above its threshold
• Then the review is YELLOW with this category

Verified by

• test_risk_repo: test_the_repository_adds_an_own_category

Scenario#63.05: the host can forbid the tuning

So that a host such as hs.hsadmin.ng keeps its categories fixed.

• Given the host config sets [path_judge] repository_may_tune_risks = false
• When the .werkrevisor.toml of the repository sets a risk template or a category
• Then the config is refused with a message that the host does not allow it

Verified by

• test_risk_repo: test_the_host_can_forbid_the_tuning

The Solution

• .werkrevisor.toml may set [path_judge] risk_template and a list [[risk.categories]].
• An entry with the name of a template category changes its yellow_min, orange_min or action; action = "off" removes it.
• An entry with a new name is a category of its own and needs name, title, question, yellow_min and action; kinds defaults to main code, and orange_min is optional, as in a template.
• The host key [path_judge] repository_may_tune_risks, default true, allows both.
• risk_template is no longer host only: tests/test_pathjudge.py drops it from the host-only keys and adds repository_may_tune_risks.
• config/hsadmin-ng.toml sets repository_may_tune_risks = false, as it already forbids the repository to enable the judge.
• The inside diagram names the risk template among the keys of .werkrevisor.toml.
• The README describes it with an example; docs/werkrevisor.werkbaum marks the node as merged.
• werkrevisor 0.30.0.

Prerequisite PRs

• PR#62: werkrevisor 0.29.0, merged.