ADR-007: One workflow commits generated files, and it marks its commits to skip CI

Context

Adopting the record (ADR-001) added a Docs workflow that regenerates the views and commits them back. The repository already had Build README, which rendered README.md from its templates and committed that back. Both triggered on changes under docs/, and the record’s views are written to docs/.

The observed sequence on the first pull request:

1. A push ran Docs. Its docs-generate job regenerated and committed; its docs-lint job checked out exactly the SHA that job output, and passed.
2. Build README then rendered README.md and committed it — becoming the branch tip, after the lint had already run.
3. That bot commit opened a fresh Docs run for the pull request, which GitHub gated at action_required because the triggering actor was github-actions[bot]. It had zero jobs and never executed.

So the tip of the branch was never linted, and there was a permanently unapproved run sitting on the pull request. docs-lint reads docs-generate’s output SHA precisely to avoid this class of problem, and a second committing workflow defeats it from outside.

Luria’s generate action had already solved the half it controls: its default commit message carries GitHub’s skip marker, so its own bot pushes open no run. Build README carried no marker, and neither did the SVG converter or the registry builder.

Decision

One job generates and commits. docs-generate renders the README from its templates — llamero build_template ... --commit=False, which writes the file and leaves it staged for someone else — and then runs luria’s generate action, whose git add -A picks up the README along with the record’s views and makes a single commit carrying the skip marker.

Build README is deleted. Every remaining workflow that commits as the bot names the skip marker in its message.

The luria actions are pinned to a released tag rather than @main, which is what their own comments ask for once a project depends on them.

Alternatives considered

• Mark the generated files unscannable. The first fix attempted, and it addressed a different symptom of the same tangle — the reference scanner reading filenames out of a generated file tree. It left both workflows committing, so the unchecked-tip problem survived. Removing a generated inventory and a duplicate committer removed both.
• Have Build README run first and Docs second. Ordering two independent workflows means guessing at scheduling. They are not independent — one writes what the other reads — so they are one job.
• Let the bot’s commits trigger runs, and approve them. Manual approval on every regeneration, forever, for a run whose only purpose is to check work the previous run already checked.
• Status quo. The lint stays green while never seeing the commit anyone will actually merge, which is worse than not having it: it reports safety it is not providing.

Consequences

The README is now regenerated on the Docs workflow’s triggers — pull requests and pushes to the default branch — rather than on any push touching docs/. That is broader coverage, not narrower.

llamero’s --commit=False is load-bearing and easy to drop by accident. If it is ever removed, the old behaviour returns silently: the build still works, and the lint quietly stops covering the tip. The step carries a comment saying so.