Skip to content

Commit cc871a8

Browse files
authored
Merge pull request #4221 from lidge-jun/codex/260911-round-tracking-1
docs(devlog): mechanize the lane tracking refresh and fix the wp4 merge gate
2 parents 183e1bb + 9f550ae commit cc871a8

2 files changed

Lines changed: 188 additions & 0 deletions

File tree

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
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+
Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Tracking refresh
2+
3+
Run this to regenerate the lane rows of `060_ledger.md`. Every field it prints comes from a command,
4+
so the ledger cannot drift into narration the way it did before audit round 2 caught a stale head.
5+
6+
```bash
7+
set -uo pipefail
8+
REPO=lidge-jun/opencodex
9+
for b in codex/260911-l1-responses-core codex/260911-l2-catalog-provider codex/260911-l3-account-pool codex/260911-l4-service-cli codex/260911-l5-integrations-io codex/260911-l6-streaming-tools codex/260911-l7-docs; do
10+
head=$(git ls-remote origin "refs/heads/$b" | cut -f1)
11+
if [ -z "$head" ]; then echo "$b MISSING"; continue; fi
12+
pr=$(gh pr list -R "$REPO" --head "$b" --state open --json number,headRefOid,reviewDecision,mergeStateStatus)
13+
prtxt=$(printf '%s' "$pr" | jq -r 'if length==0 then "pr=none" else "pr=#\(.[0].number) prhead=\(.[0].headRefOid[0:9]) review=\(.[0].reviewDecision // "-") mergeState=\(.[0].mergeStateStatus // "-")" end')
14+
runs=$(gh run list -R "$REPO" --commit "$head" --json workflowName,conclusion,status,databaseId,event)
15+
ci=$(printf '%s' "$runs" | jq -r '[.[] | select(.event=="pull_request" or .event=="push")] | group_by(.workflowName) | map(max_by(.databaseId)) | if length==0 then "ci=no-run" else (map(select(.conclusion != "success")) | if length>0 then "ci=NOT-GREEN[" + (map(.workflowName + "=" + (if (.conclusion // "") == "" then .status else .conclusion end)) | join(";")) + "]" else "ci=green[" + ((. | length | tostring)) + " workflows]" end) end')
16+
echo "$b head=${head:0:9} $prtxt $ci"
17+
done
18+
```
19+
20+
## Reading rules
21+
22+
- `pr=none` means `gh pr list --head` returned `[]`. Use `list`, never `view`: `gh pr view <branch>`
23+
exits 1 when no pull request exists and would abort the loop.
24+
- `ci=no-run` means no `pull_request` or `push` run exists for that exact head. It is **not** green.
25+
Every lane reads that way right now, before any thread pushes.
26+
- The verdict reduces to the newest run per `workflowName` by `databaseId`, and requires *every* one
27+
of them to be `success`. It is not an allowlist: a red workflow nobody thought to name still fails
28+
the lane.
29+
- Only `pull_request` and `push` events count, so a later `workflow_dispatch` success cannot outrank a
30+
failed run of the same workflow.
31+
- `mergeState=UNKNOWN` is common and is not a mergeability verdict; it appeared on #4210, #4203, and
32+
on #4220 after it merged.
33+
- Which checks are skipped inside a green workflow is a check-run fact, readable only from
34+
`gh pr checks <pr>`. #4220 showed `Cross-platform CI` and `React Doctor` as workflow-level `success`
35+
with the product jobs skipped inside, which is correct for a documentation-only pull request and
36+
must be recorded as such rather than as green product CI.
37+
38+
## Snapshot — 2026-09-10T16:47Z
39+
40+
```text
41+
codex/260911-l1-responses-core head=29c342da7 pr=none ci=no-run
42+
codex/260911-l2-catalog-provider head=b28f06ee0 pr=none ci=no-run
43+
codex/260911-l3-account-pool head=6fd401636 pr=none ci=no-run
44+
codex/260911-l4-service-cli head=f48cede91 pr=none ci=no-run
45+
codex/260911-l5-integrations-io head=a7a92089c pr=none ci=no-run
46+
codex/260911-l6-streaming-tools head=3760f81fd pr=none ci=no-run
47+
codex/260911-l7-docs head=cd5dcd6a2 pr=none ci=no-run
48+
```
49+
50+
Exit 0. Any lane pull request opened after that time supersedes this snapshot; re-run the block
51+
rather than trusting it.
52+

0 commit comments

Comments
 (0)