|
| 1 | +# wp3 — tracking protocol (revision 3, after two wp3 audit rounds) |
| 2 | + |
| 3 | +The seven lane branches are published, so tracking has already begun: their remote heads are live |
| 4 | +values today, before any thread pushes. What is missing is that the ledger must be regenerated by |
| 5 | +commands whose flags are named. Audit round 2 of the round unit caught a hand-written ledger citing a |
| 6 | +stale head; wp3 audit round 1 caught this plan trusting commands that do not return what it claimed; |
| 7 | +wp3 audit round 2 caught the CI rule passing vacuously when no run exists at all. |
| 8 | + |
| 9 | +## Corrected command set |
| 10 | + |
| 11 | +- Remote head: `git ls-remote origin refs/heads/<branch>`. |
| 12 | +- Pull request: `gh pr list -R lidge-jun/opencodex --head <branch> --state open --json` |
| 13 | + `number,headRefOid,reviewDecision,mergeStateStatus`. Use `list`, never `view`: `gh pr view <branch>` |
| 14 | + exits 1 when no pull request exists, which breaks a `set -e` loop, while `list` returns `[]` and |
| 15 | + exits 0. Treat `[]` as "no PR yet" and never let `jq '.[0].number'` print `null` into a table cell. |
| 16 | +- Workflow runs: `gh run list -R lidge-jun/opencodex --commit <headRefOid> --json` |
| 17 | + `workflowName,conclusion,status,databaseId,headSha,event`. `--commit` binds the SHA; `--branch` does |
| 18 | + not. Do not read `.[0]`: the list is newest-first across all workflows, so the first row is often a |
| 19 | + cancelled hygiene run while the product workflow is still `action_required`. |
| 20 | + |
| 21 | +## How CI is judged |
| 22 | + |
| 23 | +Reduce the run list to the newest run per `workflowName` for that exact SHA, by highest |
| 24 | +`databaseId`. Then: |
| 25 | + |
| 26 | +- An empty list is **not** green. It means no run exists for that commit, which is the state every |
| 27 | + lane branch is in right now. Absence of evidence is recorded as `no CI`, never as success. |
| 28 | +- `success` is the only passing conclusion. `cancelled`, `skipped`, `action_required`, `failure`, |
| 29 | + `timed_out`, and an empty conclusion with `status` other than `completed` are all not-green. |
| 30 | + `action_required` in particular is the normal state of a fork run awaiting maintainer approval. |
| 31 | +- The workflows that must be present and `success` depend on what the pull request touches, because |
| 32 | + `ci.yml` gates its product legs behind a `changes` filter. A pull request touching anything under |
| 33 | + `src/`, `gui/`, `tests/`, or `scripts/` must show `Cross-platform CI` as `success` on that SHA; one |
| 34 | + touching `gui/` must also show `React Doctor`; one touching the service paths must also show |
| 35 | + `Service lifecycle`. `PR hygiene`, `PR Labeler`, and `Enforce PR target branch` are required on |
| 36 | + every pull request. |
| 37 | +- A documentation-only pull request legitimately shows the product legs as skipped, as #4217 and |
| 38 | + #4220 did. That is recorded as "product legs skipped by the changes filter", not as green product |
| 39 | + CI, so the distinction survives into the ledger. |
| 40 | +- `mergeStateStatus` is not a CI verdict. It is frequently `UNKNOWN` on a perfectly mergeable pull |
| 41 | + request, as it was on #4210, #4203, and on #4220 after it merged. |
| 42 | + |
| 43 | +## What this phase produces |
| 44 | + |
| 45 | +1. `110_tracking_refresh.md` — the refresh block written out with the flags above plus these reading |
| 46 | + rules, so a later session cannot re-derive a softer version. |
| 47 | +2. One executed snapshot with its capture time, proving the block runs against the live repository. |
| 48 | + The snapshot says plainly that any lane pull request opened afterwards supersedes it. |
| 49 | +3. The wp4 merge choreography below. |
| 50 | + |
| 51 | +## Merge choreography for wp4 |
| 52 | + |
| 53 | +Order: L5, L3, L4, L2, L6, L7, L1. L1 goes last because `core.ts` is contended by four open pull |
| 54 | +requests and every other lane would rebase behind it; L5 goes first because it has the least |
| 55 | +contention inside this round, though it is not collision-free in the repository at large — open draft |
| 56 | +#3833 also edits `src/integrations/registry.ts`. Within a lane, a child lands only after its parent |
| 57 | +and is retargeted from the parent branch to `dev` first. |
| 58 | + |
| 59 | +Gate for each merge, re-queried at merge time rather than read from the snapshot: |
| 60 | + |
| 61 | +1. `git ls-remote origin refs/heads/<branch>` equals the pull request's `headRefOid`. |
| 62 | +2. CI on that exact SHA passes the rule above, including the presence requirement. |
| 63 | +3. `scripts/ci/assert-mergeable-review.sh [--maintainer-integration] <pr>` exits zero. That script, |
| 64 | + not `reviewDecision`, is the review gate: it requires each maintainer's *latest* review bound to |
| 65 | + the exact current head and fails closed on any API error, which a `reviewDecision` read does not. |
| 66 | +4. A carried or reimplemented pull request has its `Co-authored-by` trailer present in a branch |
| 67 | + commit, verified with `git log`, before the merge rather than after. |
| 68 | +5. The base is still `dev`, re-read after the previous merge in the series. |
| 69 | + |
| 70 | +The merge itself is `gh pr merge --merge` or `--squash` — never rebase — with |
| 71 | +`--match-head-commit <headRefOid>`, so a push landing between the gate and the merge aborts the merge |
| 72 | +instead of laundering stale evidence. When the maintainer-integration path is used, record the |
| 73 | +decision and the exact-head evidence with it. |
| 74 | + |
| 75 | +Landing proof: `git fetch origin` and then ancestry of the merge commit, or tree equality when the |
| 76 | +pull request was squashed, because a squash leaves the pull request head outside `origin/dev` |
| 77 | +ancestry. The merge command's own output is never the proof. |
| 78 | + |
| 79 | +Test-layout conflicts: `scripts/test-layout/layout.json` and `tests/fixtures/test-layout-expected.json` |
| 80 | +are resolved as a union of both sides' entries, never `--ours` or `--theirs`, since dropping a side |
| 81 | +silently unregisters another lane's test file. |
| 82 | + |
| 83 | +## Acceptance |
| 84 | + |
| 85 | +- The refresh block runs with exit 0 today, when no lane has a pull request and no run exists, and |
| 86 | + prints one line per lane with the remote head, `no PR`, and `no CI`. |
| 87 | +- Every printed field comes from one of the three commands above. |
| 88 | +- The snapshot carries its capture time and the superseding note. |
| 89 | +- The choreography names the order, the five gate conditions, the head-pinned merge command, the |
| 90 | + landing proof for both merge and squash, and the union rule for the two test-layout maps. |
| 91 | + |
| 92 | +## Out of scope |
| 93 | + |
| 94 | +No lane implementation, no lane pull request, no merge. Contributor pull requests outside this round |
| 95 | +stay outside it: merging them is a review decision the operator has not delegated. |
| 96 | + |
| 97 | +## Local checks |
| 98 | + |
| 99 | +`NOT RUN`. The refresh block only reads. |
| 100 | + |
| 101 | + |
| 102 | +## Amendments from wp3 audit round 3 |
| 103 | + |
| 104 | +The CI rule above was an allowlist, which is the wrong shape: it can only catch a failure it already |
| 105 | +named. It is replaced by its inverse. |
| 106 | + |
| 107 | +- **Every** newest-per-`workflowName` run on the exact head must be `success`. A red workflow outside |
| 108 | + any named set fails the lane; nothing passes by not being on a list. |
| 109 | +- Only runs whose `event` is `pull_request` or `push` count toward the gate. A later |
| 110 | + `workflow_dispatch` success must not outrank a failed `pull_request` run for the same workflow, |
| 111 | + which is why `event` is fetched. |
| 112 | +- Presence, corrected against the workflow files rather than from memory: `React Doctor` has no path |
| 113 | + filter and runs on every pull request, so it must always be present. `Cross-platform CI` is gated by |
| 114 | + the `changes` `ci` filter in `.github/workflows/ci.yml`, which covers more than `src/`, `gui/`, |
| 115 | + `tests/`, and `scripts/` — it also includes `bin/**`, `docker/**`, `assets/**`, `package.json`, and |
| 116 | + selected workflow files. `Service lifecycle` triggers on `src/service.ts`, `src/cli.ts`, |
| 117 | + `src/cli/index.ts`, `src/lib/bun-runtime.ts`, `package.json`, `bun.lock`, and its own two workflow |
| 118 | + files, which is why L4 in particular must read the filter rather than guess. |
| 119 | +- The authoritative per-pull-request required set is `gh pr checks <pr>`, because GitHub already |
| 120 | + resolved the filters for that head. `gh run list --commit` supplies the workflow-level conclusion |
| 121 | + and the `event`; `gh pr checks` supplies the check-run granularity. Use both. |
| 122 | +- "Product legs skipped" is a check-run fact, not a workflow fact: #4220 showed `Cross-platform CI` |
| 123 | + and `React Doctor` as workflow-level `success` with the jobs skipped inside. Read it from |
| 124 | + `gh pr checks`, never from `gh run list`. |
| 125 | + |
| 126 | +Two corrections to the merge gate: |
| 127 | + |
| 128 | +- `scripts/ci/assert-mergeable-review.sh` was described too loosely. Its default path requires one |
| 129 | + non-author maintainer approval bound to the exact current head and no outstanding maintainer |
| 130 | + `CHANGES_REQUESTED`; the `--maintainer-integration` path waives the second approval and is not |
| 131 | + itself an approving review. |
| 132 | +- Security review is a separate duty and this round triggers it: L3 owns |
| 133 | + `src/server/management/oauth-account-routes.ts`, an authentication and credential surface, so |
| 134 | + `MAINTAINERS.md` requires explicit security review before that lane lands. CI being green does not |
| 135 | + discharge it. |
| 136 | + |
0 commit comments