werkregie/doc/prs/2026-10-13-PR#58-required-checks.md

PR#58: Required Checks of All werk Repositories

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.

Problem

None of the werk repositories checks its dependencies for known vulnerabilities or for their licenses. The shared workflow requires no check of a build at all; only AGENTS.md of werkator requires mutation tests, with werkcrappit's Mutation-CRAP.

The repositories use these ecosystems:

• Kotlin and Java with Gradle: werkator, werkcrappit, werkregie, werkjournal, werkprobe, werkbaum, werkrevisor's statistics, hsadmin-ng;
• Python: werkrevisor;
• JavaScript with npm: werkbaum's frontend, werkjournal;
• Go: werkdock.

Non-Goals

• No setup of a check in a repository; each one follows as a PR of its own, the Kotlin and Java repositories first.
• No binding tool for Python, npm and Go yet; the section names proposals.

Solution

• doc/agentic-workflow.md, the master copy, gets the section "Required Checks", with defaults from which a repository deviates only with a reason in its risk analysis:
  • vulnerabilities of the dependencies: the criticality of the repository sets the CVSS score that fails the build; an exception is suppressed with its reason in a file that the review rules of the repository mark as critical;
  • licenses of the dependencies against an allowlist of permissive and weak copyleft licenses; any other license fails the build and needs the consent of the human;
  • mutation tests with werkcrappit for Kotlin and Java, as werkator has them: Mutation-CRAP at most 15, maxMutationCrap as a ratchet;
  • a table of the tools per ecosystem: binding for Kotlin and Java, proposed for the others.
• Each repository keeps a criticality and risk analysis in docs/risk-analysis.md; only the human sets the criticality: high fails the build from CVSS 4, normal, the default, from CVSS 7, low from CVSS 9.
• "Equipment of a Repository" lists docs/risk-analysis.md, and the row of AGENTS.md names the checks.
• The plan gets #ops.checks with a node for the setup in werkregie.
• Version 0.35.3.

Open Questions

• Where do the required checks stand? In a section of the shared workflow, chosen by the human; each AGENTS.md names its commands.
• Are mutation tests required too? Yes, for Kotlin and Java, chosen by the human.
• From which severity does a vulnerability fail the build? By the criticality of the repository: high from CVSS 4, normal from CVSS 7, low from CVSS 9; chosen by the human.
• May a repository deviate from the defaults? Yes, with a reason in its criticality and risk analysis, which each repository keeps; chosen by the human.
• Which licenses are allowed without asking? Permissive and weak copyleft licenses, chosen by the human.
• When do the checks run? In the build of every PR; the vulnerability database is cached and updated at most once a day. Mutation tests may run in a nightly build, since a first run takes hours.

Follow-up PRs

• werkregie writes its risk analysis and sets up OWASP Dependency-Check, the license check and the mutation tests.
• The other repositories take over the section with their next PR and set up their checks.