werkdock/docs/prs/2026-10-20-PR#15-agentic-workflow.md

# PR#15: The Shared Agentic Workflow

> **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.

## Related Links

- [werkregie `doc/agentic-workflow.md`](https://git.javagil.de/mi/werkregie/src/branch/main/doc/agentic-workflow.md):
  the master copy of the shared workflow.
- [werkregie `doc/risk-analysis.md`](https://git.javagil.de/mi/werkregie/src/branch/main/doc/risk-analysis.md)
  and [werkcrappit `.werkrevisor.toml`](https://git.javagil.de/mi/werkcrappit/src/branch/main/.werkrevisor.toml):
  the models for the risk analysis and the review rules.

## Problem

werkdock is the only Werk repository without the shared workflow of the Werk family.
Its `main` requires no approval and only the status `werkator`, so no AI review guards a merge.
It has no `AGENTS.md`, no PR documents, no plan in Werkbaum, no review rules for werkrevisor and no risk analysis.
The required checks for vulnerabilities and licenses do not run.

## Non-Goals

- No change of the CLI.
- No fix of the vulnerabilities that the new check finds on `main`; see "Follow-up PRs".
- No branch protection, collaborator rights or machine config on mih09; only the human sets them up.

## Solution

Equipment, as "Equipment of a Repository" of the shared workflow lists it:

- `docs/agentic-workflow.md` is a copy of the master copy `doc/agentic-workflow.md` in werkregie.
- `AGENTS.md` refers to it and holds the build, the checks, the hard invariants from the README and RFCs 0001 and 0002,
  and what werkdock adds to the workflow: the version in `internal/cli/cli.go`, a `CHANGELOG.md` section per version,
  RFCs for larger decisions, and the manual rollout to mih09.
- `CLAUDE.md` imports both.
- `docs/prs/README.md` and `docs/prs/TEMPLATE.md` give the PR documents their structure, without a version line,
  since werkdock keeps its version in the code.
- `docs/werkdock.werkbaum` holds the plan: what the CHANGELOG lists as done, PR#14 and this PR in work, the ideas of the README.
- `docs/risk-analysis.md`: criticality high, set by the human.
- `.werkrevisor.toml` takes the structure of werkcrappit's, with Go globs for tests and main code.
  The risk template `jvm-spring-backend` loses the categories without a meaning for a sandbox CLI,
  and gains `sandbox_isolation`: a change of what a sandboxed process sees or reaches on the host gives YELLOW.
  Its thresholds are not measured on werkdock yet.
  The writing rules leave out `CHANGELOG.md`, which wraps its prose at 72 columns.
  The risk analysis, the vulnerability exceptions and the allowed licenses are hard YELLOW.
  werkrevisor checks `hard_yellow.paths` only outside the docs globs,
  so these name each place of documentation but `docs/risk-analysis.md` (werkrevisor PR#126).

Required checks, with govulncheck and go-licenses, which the human accepted as the tools for Go:

- `tools/check-licenses` runs go-licenses v2.0.1 against `tools/allowed-licenses.txt`, the allowlist of the workflow;
  the build `default` runs it.
- `tools/vulncheck` runs govulncheck v1.8.0 and fails on each vulnerability whose symbol the code calls.
  With `-base origin/main`, it fails only on a call that the merge base lacks,
  a call being the module, its version and the called symbol:
  so another symbol of an advisory or another affected version fails, the same call does not;
  it scans an export of the merge base, so it writes nothing into the repository.
- The new build `dependencies` runs it with `-base origin/main` for each branch but `main`;
  the new build `vulnerability-data` runs it in full on `main` each night at 02:00.
- `go run` loads both tools at a pinned version into the module cache; `go.mod` stays without a requirement,
  as RFC 0001 asks.
  govulncheck v1.8.0 needs Go 1.26; the Go 1.24.4 of the build image switches to it by `GOTOOLCHAIN=auto`
  and still checks the standard library of Go 1.24.4.

Measured on the workstation with Go 1.26.8:

- In full, `tools/vulncheck` fails on `main` with 7 called vulnerabilities of the standard library, e.g. GO-2026-6617.
- With `-base origin/main`, it passes on this branch.
- On a scratch commit that calls `language.ParseAcceptLanguage` of golang.org/x/text v0.3.6,
  it fails with the 2 vulnerabilities that this commit brings, among them GO-2022-1059, and not with the 7 of `main`.
- `tools/check-licenses` passes; werkdock has no dependency.

Werkator reads `statusContext` only from the config of `main`.
Until this PR is merged, the build `dependencies` of this branch reports as `werkator`, too.
The status `werkator` of a commit of this branch is then that of the build that finished last;
build-results.json on mih09 holds both.

Version 0.12.1 with an internal section in `CHANGELOG.md`:
the next free version is above 0.11.0 of `main` and 0.12.0 of the open PR#14.

## Open Questions

- [x] Which tools for the required checks of Go, which the workflow only proposes?
  govulncheck and go-licenses, decided by the human on 2026-10-20.
- [x] Which criticality?
  high, set by the human on 2026-10-20: werkdock is the isolation boundary for unreviewed code
  and hands credentials into the sandbox.

## Additional Changes

- The opening paragraph of the existing `CHANGELOG.md` and the comment on `Version` in `internal/cli/cli.go`:
  each branch raises the version, not only one that changes behavior.

## Prerequisite PRs

- [werkrevisor PR#126](https://git.javagil.de/mi/werkrevisor/pulls/126): the host config `config/werkdock.toml`,
  installed on mih09 with the build `ai-review` on 2026-10-20.

## Follow-up PRs

- The Go toolchain: a `toolchain` line in `go.mod` with a Go without known vulnerabilities,
  for the CI and the binary on mih09, then its rollout.
  The nightly build `vulnerability-data` stays red until then.