AGENTS.md

1# GitHub automation guide
2 
3This directory is still only partially standardized. Several historical workflows and helper locations do not yet follow one uniform shape. Do not copy old patterns blindly. For new work, bug fixes, and cleanup, use the `ci.yml` + `comment.atom.yml` + `autofix.atom.yml` + `report.atom.yml` + `.github/scripts/handoff.py` system as the reference topology unless a maintainer explicitly chooses a different boundary.
4 
5## Required reading
6 
7Before changing GitHub automation, read the current versions of:
8 
9- `.github/workflows/ci.yml`
10- `.github/workflows/comment.atom.yml`
11- `.github/workflows/autofix.atom.yml`
12- `.github/workflows/report.atom.yml`
13- `.github/scripts/handoff.py`
14- `scripts/scopes.ts`
15- `specs/current/ci.md` when changing scope rules, confidence tiers, or guards
16- `e2e/tests/packaged-smoke-workflow.test.ts`
17- `scripts/approve-fork-pr-workflows.ts` and `e2e/tests/scripts/approve-fork-pr-workflows.test.ts` when touching fork PR approval behavior
18 
19If the change affects cross-workflow behavior, update the topology tests instead of relying only on workflow YAML review.
20 
21## Architecture
22 
23GitHub automation uses two layers.
24 
25Business layer:
26 
27- Business workflows decide what happened and what should be requested next.
28- `ci.yml` is the main low-privilege PR, merge-queue, and manual validation gate (application merge bar only).
29- `ci.yml` should run validation, decide scopes, and produce typed handoff artifacts.
30- Packaging checks are standalone and outside the merge gate: `nix.yml` (flake check) and `docker-image.yml` (image validate + publish). Do not re-attach them to `Validate workspace`.
31- Business workflows should not perform trusted writes to PR comments or branches when a capability workflow can do it.
32 
33Atomic capability layer:
34 
35- Capability workflows perform reusable trusted operations from well-defined inputs.
36- `comment.atom.yml` consumes `handoff-comment-*` artifacts and upserts pure text PR comments.
37- `autofix.atom.yml` consumes `handoff-autofix-*` artifacts and applies same-repository patches.
38- `report.atom.yml` consumes `handoff-report-*` artifacts and handles advanced comments that need trusted materialization, such as dependency install, R2 access, artifact processing, or report generation before upsert.
39- `rerun.atom.yml` watches completed `ci` runs and requests one `gh run rerun --failed` when leaf jobs died to runner/spot cancel. Decision logic lives in `.github/scripts/rerun_infra_cancel.py`; it must not rerun ordinary assertion failures or stale heads.
40- `.github/scripts/handoff.py` owns artifact names, directory layout, discovery, and contract validation for `comment`, `autofix`, and `report` handoffs.
41 
42Default rule: do not add a new domain-specific follow-on workflow such as `foo.comment.atom.yml`, `foo.autofix.atom.yml`, or `foo.report.atom.yml` until the flow has been tested against these existing atomic capabilities.
43 
44## Directory conventions
45 
46- `.github/workflows/` contains GitHub Actions workflow entrypoints.
47- `.github/actions/` contains reusable composite actions for workflow setup steps.
48- `.github/scripts/` contains workflow-owned scripts and contracts that are not general repo developer commands.
49- `.github/scripts/release/` contains release workflow implementation helpers. Keep release-only helpers there and CI handoff helpers at `.github/scripts/`.
50- Root `scripts/` remains for repo-level developer checks, product scripts, and guard/test logic. Do not move workflow-only handoff glue there just to make it look more general.
51 
52New workflow-owned helpers should usually live under `.github/scripts/`. Prefer TypeScript for project-owned scripts in general, but Python is acceptable for small GitHub runner glue when stdlib portability and low setup cost matter. Keep such exceptions narrow and covered by `pnpm guard` policy.
53 
54## Handoff contract
55 
56Use `.github/scripts/handoff.py` for all CI follow-on artifact names and paths. The canonical layout is:
57 
58- `handoff/comment/<id>/metadata.json` plus `body.md`
59- `handoff/autofix/<id>/metadata.json` plus `patch.diff`
60- `handoff/report/<id>/metadata.json`
61 
62Artifact names must come from `handoff.py artifact-name <kind> <id>`, and download patterns must come from `handoff.py artifact-pattern <kind>`.
63 
64`metadata.json` always identifies the target PR, head SHA, base SHA, CI run id, handoff kind, and handoff id. Capability-specific fields belong in that capability's metadata and must be validated by `handoff.py`.
65 
66Do not hand-roll artifact name prefixes, alternate directory layouts, or one-off metadata parsers in workflows. Extend `handoff.py` first, then use the new contract from producers and consumers.
67 
68## Capability rules
69 
70### `comment.atom.yml`
71 
72Use `comment.atom.yml` for pure text PR comments only.
73 
74- Input is an already-final `body.md`.
75- The body must contain a stable marker.
76- The workflow validates PR state, draft state, head SHA, and base SHA before upsert.
77- It writes the GitHub API payload through `jq -n --rawfile body ...` and `gh api --input`.
78- It must not install dependencies, access R2, execute report scripts, understand Nix, understand visual diffs, or checkout PR code.
79 
80### `autofix.atom.yml`
81 
82Use `autofix.atom.yml` for same-repository patch application.
83 
84- Input is `patch.diff` plus metadata including `allowed_paths` and `commit_message`.
85- Fork PRs must skip, not fail.
86- Closed, draft, stale head, and stale base cases must skip, not fail.
87- Apply patches only after validating the live PR state.
88- Verify the resulting changed files exactly match `allowed_paths`.
89- Prefer the configured bot app token for pushes so follow-up CI is triggered as expected.
90- Do not use this workflow for arbitrary commands, generated scripts, or PR-head code execution.
91 
92### `report.atom.yml`
93 
94Use `report.atom.yml` for advanced comments, meaning comment bodies that are not pure text inputs.
95 
96Examples include reports that need:
97 
98- downloading and combining artifacts,
99- installing dependencies,
100- accessing R2 or other trusted secrets,
101- rendering media or diffs,
102- generating a rich markdown body from trusted base code.
103 
104`report.atom.yml` is a trusted writer and materializer. It may upsert comments directly because that is part of the advanced comment capability, but it must do so with the same file-backed payload hygiene as `comment.atom.yml`.
105 
106Rules:
107 
108- Treat all PR-produced artifacts as untrusted data.
109- Do not checkout or execute PR-head code in `report.atom.yml`.
110- Checkout trusted base/default code before running repository scripts.
111- Validate PR state, draft state, head SHA, and base SHA before secret use and again before comment upsert when practical.
112- Keep report type dispatch explicit. If multiple report types grow, add a clear handler boundary instead of burying branching in shell fragments.
113 
114## Fork PR approval
115 
116`fork-pr-workflow-approval.yml` and `scripts/approve-fork-pr-workflows.ts` are a separate security boundary. They may approve low-risk fork PR `pull_request` runs, but must not approve trusted `workflow_run` capability workflows.
117 
118Keep `.github/workflows/ci.yml` as the only approved workflow path unless a maintainer explicitly expands the allowlist. `comment.atom.yml`, `autofix.atom.yml`, `report.atom.yml`, release workflows, deployment workflows, and any workflow with trusted secrets or write permissions must stay outside fork auto-approval.
119 
120## Common iteration flow
121 
1221. Classify the change.
123   - Validation or business decision: start in `ci.yml`.
124   - Pure text PR comment: produce `handoff/comment` and let `comment.atom.yml` consume it.
125   - Same-repo patch: produce `handoff/autofix` and let `autofix.atom.yml` consume it.
126   - Rich/generated comment: produce `handoff/report` and let `report.atom.yml` materialize and upsert it.
127   - New naming, paths, or metadata: update `.github/scripts/handoff.py`.
1282. Update scope routing in `scripts/scopes.ts` when a workflow/script should trigger a validation lane.
1293. Update topology coverage in `e2e/tests/packaged-smoke-workflow.test.ts` or the relevant script test.
1304. Run the focused checks:
131   - `python3 .github/scripts/handoff.py self-check`
132   - `actionlint -color`
133   - `pnpm --filter @open-design/e2e test tests/packaged-smoke-workflow.test.ts`
1345. Run repo-level checks before handing off:
135   - `pnpm guard`
136   - `pnpm typecheck`
137 
138Use `git diff --check` before finishing workflow edits.
139 
140## FAQ
141 
142### Should I add a new `*.comment.atom.yml` workflow?
143 
144Usually no. If the body is already final markdown, produce `handoff/comment` and use `comment.atom.yml`. If the body must be generated from artifacts, secrets, or report code, produce `handoff/report` and use `report.atom.yml`.
145 
146### Why not put rich visual report generation in `comment.atom.yml`?
147 
148Because `comment.atom.yml` is the pure text comment shell. Installing dependencies, using R2 secrets, downloading screenshots, and generating diffs are advanced comment materialization, which belongs in `report.atom.yml`.
149 
150### Why can `report.atom.yml` upsert comments directly?
151 
152`report.atom.yml` is not a pure producer. It is the auditable advanced comment capability: materialize a non-pure text comment and publish it. The key boundary is that this power is explicit in one workflow with trusted inputs, stale checks, and file-backed payload hygiene.
153 
154### Why does `autofix.atom.yml` skip fork PRs?
155 
156Fork PR branches are not writable by the base repository in the same trust model, and pushing generated changes to forks would require a different permission and ownership design. Skip fork PRs and use comments or report output for contributor guidance.
157 
158### Can trusted `workflow_run` workflows checkout PR code?
159 
160No, not by default. They may download PR artifacts as data, but must not execute PR-provided code or scripts. Checkout trusted base/default code before running repository scripts.
161 
162### Why centralize handoff names in `handoff.py`?
163 
164GitHub artifact behavior is easy to drift: artifact names must be unique per upload, and consumers need stable patterns. Centralizing names, paths, and validation keeps producers and consumers aligned and makes topology tests meaningful.
165 
166### Where should tests live?
167 
168Cross-workflow topology tests belong in `e2e/tests/` when they observe repository-level behavior. Root `scripts/` is test-free (enforced by `pnpm guard`); script behavior-contract coverage lives in `e2e/tests/scripts/`. Do not add one-off `*.test.ts` files just because a workflow helper exists; prefer existing topology coverage and helper self-checks when that is enough.
169