Glint's slices are written by Codex runs and reviewed by a Claude run, the
reviewer, against OCX's four virtues as PLAN.md defines them. The
maintainer has the last word, and decides structural questions through the
decision log.
Handing out a slice
- The reviewer writes a task for one slice under
docs/tasks/, taken from the slice's paragraph in its phase document. The task gives the claim, the passage, the files, the demonstration, the size bound, the seams it may touch and the branch it works on (slice/N.M). Before handing it out, the reviewer checks every statement in it against the file it names: each flag, each claim about a devicetree, Kconfig file or header, and each constraint that touches an existing spec. In Track Z, four rounds of revision came from statements that such a reading would have caught. - The reviewer starts a Codex run with
ocx2 create, using the pattern indocs/runs/codex.md. The run's objective is the task text, and the run is posted as a reply in the slice's forum thread, or on its ticket. - Codex works in its own checkout and commits only to
slice/N.M, never to trunk. Each check-in comment carries the four parts required by Development method rule 2: claim, passage, demonstration and size. - Codex replies in the thread when the slice is ready, or when it is stuck.
Slices that do not depend on each other may run at the same time. Two runs never share a branch.
Reviewing a slice
The reviewer checks out slice/N.M, rebuilds from clean, runs every
demonstration the task names, and reads the whole diff. The questions, by
virtue:
- Clarity. Does the check-in comment state the claim, the passage, the
demonstration with its observed result, and the size? Does the code do
what the slice's paragraph says, under the names the plan uses? Does
every new source file start with
SPDX-License-Identifier: MPL-2.0? - Loose Coupling. Does the slice touch other parts only through
declared seams (the platform interface,
compat/zephyr, the guest ABI)? Does it add only the dependencies its task names, with nothing board-specific (plan principle 6)? - Demonstrability. Do
crystal specand both EFI builds pass from clean, and does each named demonstration produce the result the comment claims, when the reviewer runs it? - Parsimony. Is the non-spec diff within the size bound (aim under ~200 lines; split anything over ~400)? Does it pass Tambassi's questions: nothing beyond the claim, nothing left that could be removed, each thing once, and fewer kinds of mechanism before more of them?
A change Codex made to a constraint the task states, or a check weakened so that it passes, is grounds for Resubmit, even when the result looks right. Codex reports such changes; it does not make them silently.
Then one of three verdicts:
- Merge. All four virtues hold. The reviewer records
ocx2 audit … pass, mergesslice/N.Minto trunk with a check-in that names the slice and the verdict, and adds the slice todocs/TUTORIAL.md. - Annotate and merge. The changes needed are small: wording, a missing
header, a comment, a misnamed variable, nothing that changes behaviour.
The reviewer makes them in one check-in on
slice/N.M, says what changed and why, then merges as above. - Resubmit. A virtue fails in a way that changes behaviour or
structure. The reviewer records
ocx2 audit … failwith the reasons, revises the task underdocs/tasks/where the task itself was unclear, rewriting it as one current statement (the check-in comments keep the history), and replies in the run's thread with what must change. That reply starts Codex's next turn on the same branch.
Every verdict is given in the slice's thread, so the record of why a slice was accepted lives beside the slice.
What the maintainer sees
Each merged slice leaves an audit verdict, a merge check-in and an entry in
docs/TUTORIAL.md. Anything outside a slice's task, such as a change to the
plan or a new dependency, comes to the maintainer as a question rather than
being decided in review.
While Codex runs cannot be sent
Until the reviewer's login may send runs (ocx2 create is refused without
R), the reviewer runs codex exec itself, in its checkout or in a copy of
the tree for a slice that runs in parallel. It then reviews and commits the
result on trunk as above, saying in the check-in comment what Codex wrote
and what the reviewer changed. One step cannot happen on this route:
ocx2 audit needs a login other than the one that committed, so the verdict
lives only in the check-in comment and the thread until a second login can
record it.
The reviewer runs Codex sandboxed, with codex exec --sandbox
workspace-write, in a copy of the tree under /workspace/glint-scratch.
Its shards, TMPDIR and CRYSTAL_CACHE_DIR sit inside that copy, on disk.
RAM-backed /tmp is kept for small transient files only. The sandbox
cannot reach the QEMU and U-Boot builds, so before merging, the reviewer
runs both bin/glint-run boots and the full suite outside it, with every
source variable set. A fresh TMPDIR must be empty afterwards.