A documentation updater has to change files. That is the one property the whole package currently rules out: edit denied outside the run directory, jobs with contents: read, and both together because the runtime commits and pushes a dirty working tree by itself.
Whoever opens the permissions up for the first writing agent takes that property away from all of them, not just the new one. So the lane gets built before the agent that needs it.
What to build
Two lanes, distinguishable in the manifest (output: report | patch).
Reading stays as it is.
Writing means: the agent produces a patch in its working directory and nothing else. No push, no commit, and no token with write access anywhere in its process environment. A second job, with no model key, contents: write and pull-requests: write, applies the patch and opens a pull request.
The separation is then a property rather than a setting: the job that reads a stranger's text cannot write, and the job that can write reads one file.
Acceptance criteria
- No job holds the model key and write access to the repository at the same time.
- The applying job calls no model and reads nothing but the patch from the artifact.
- The patch is uploaded as an artifact: visible, downloadable, reviewable, even if nobody merges the pull request it produces.
- An empty patch ends the run green, with no pull request and no comment noise.
- The default is a branch of its own plus a pull request. Pushing directly to the branch of the pull request under review is possible only if the operator switches it on, and is documented as what it is: the agent writing into the branch it just read.
- For fork pull requests the writing lane is off, with no switch.
- A patch that does not apply cleanly ends with a visible reason rather than half-applied changes.
- The separation and its reason are in
docs/threat-model.md.
To bear in mind
- A legal or licence review comes first, the documentation updater second. A reading agent proves the manifest is really an extension point; only a writing one proves this lane. In that order fewer things fall over at once.
- This is also the road to autofix. Whether a repository wants autofix commits is that repository's decision; here it becomes a switch.
git apply against a branch that has moved on is the likeliest failure. Fail visibly rather than guess.- A documentation updater needs more context than a reviewer: the diff, the affected documents, and the rule about which document covers what. That rule lives in the project's own
AGENTS.md, so the prompt has to ask for it rather than assume a structure.
A documentation updater has to change files. That is the one property the whole package currently rules out:
editdenied outside the run directory, jobs withcontents: read, and both together because the runtime commits and pushes a dirty working tree by itself.Whoever opens the permissions up for the first writing agent takes that property away from all of them, not just the new one. So the lane gets built before the agent that needs it.
What to build
Two lanes, distinguishable in the manifest (
output: report | patch).Reading stays as it is.
Writing means: the agent produces a patch in its working directory and nothing else. No push, no commit, and no token with write access anywhere in its process environment. A second job, with no model key,
contents: writeandpull-requests: write, applies the patch and opens a pull request.The separation is then a property rather than a setting: the job that reads a stranger's text cannot write, and the job that can write reads one file.
Acceptance criteria
docs/threat-model.md.To bear in mind
git applyagainst a branch that has moved on is the likeliest failure. Fail visibly rather than guess.AGENTS.md, so the prompt has to ask for it rather than assume a structure.