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: the master copy of the shared workflow.
• werkregie doc/risk-analysis.md and werkcrappit .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

• 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.
• 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: 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.