# 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

- [x] Where do the required checks stand?
  In a section of the shared workflow, chosen by the human; each `AGENTS.md` names its commands.
- [x] Are mutation tests required too?
  Yes, for Kotlin and Java, chosen by the human.
- [x] 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.
- [x] 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.
- [x] Which licenses are allowed without asking?
  Permissive and weak copyleft licenses, chosen by the human.
- [x] 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.