pmacs/docs/gate-protocol-build-framing.md

scripts/gate --protocol — the build its sweep depends on

Status: framing pass, revision 1. Pre-implementation. Awaiting approval.

A narrow lane, deliberately. One missing step in one script, plus the boundary question that let it go missing. No feature work, no src/, no protocol.

---

1. The defect

scripts/gate --protocol adds the CRDT workspace sweep. That sweep has a documented precondition, and the script does not run it.

docs/agent-handoff.md §5 (:532-535):

The crdt sweep needs cargo build --workspace first, or twelve gpu_invocation_acceptance tests fail on a missing pmacs-gpu binary. cargo build --workspace --no-default-features --features luajit,crdt is the invocation that produces both binaries.

scripts/gate's plan emitter (:187-204) goes … → gpu → sweep → sweep-crdt → diff-check, with no build step anywhere. Read from the source, not inferred from the failure.

Observed, not theorised. PR #228's first gate run failed step 09 with twelve gpu_invocation_acceptance::crdt::* failures, all "build pmacs-gpu before this acceptance suite", and debug/pmacs-gpu was absent from that worktree's target directory. Running the documented invocation and re-running the gate turned it green.

2. Why it was latent until now, which is the interesting part

#225 caused this to become reachable, and #225 is also what makes it matter.

Before #225 every worktree on this machine resolved to one shared CARGO_TARGET_DIR. That directory almost always already contained a pmacs-gpu binary from some earlier build, so the precondition was satisfied by accident on essentially every run. #225 gave each worktree its own target directory; a fresh one starts empty, and the omission becomes load-bearing on the very first --protocol run in a new worktree.

So this is not "a bug #225 introduced". It is a pre-existing gap in the documented procedure that #225 stopped hiding — and the reason it is urgent rather than tidy is that the failure mode is not a red gate. A red gate is fine; it stops you. The hazard is the reverse: a green --protocol run whose crdt sweep was decided by what happened to be in the build directory rather than by the diff. That is a gate that reports coverage it does not have, which is precisely what #225 exists to prevent.

3. The likely mechanism, marked as inference

The failing tests are namespaced gpu_invocation_acceptance::crdt::*, which suggests they are feature-gated to crdt and therefore compile and run only under the crdt sweep. That would explain why the default sweep passes on a tree with no pmacs-gpu binary at all — it never runs the tests that spawn it.

This is inference from the test names and one observation, and it is not yet verified. Q#GR-1 makes establishing it part of the work rather than an assumption the fix rests on.

4. The change

My vote: a named build-crdt gate step, emitted immediately before sweep-crdt and only under --protocol, running the invocation handoff §5 names.

• A named step, not a silent prelude. It appears in --print-plan, gets its own numbered log alongside the others, and fails the suite with its own name if the build fails.
• Not folded into the sweep-crdt command. cargo build … && cargo test … would make a build failure appear under the name sweep-crdt in the failure list — a wrong attribution in the one place the script exists to be trustworthy about.
• Only under --protocol. If §3's inference holds, the default sweep does not need it, and adding an unconditional workspace build to every gate run is a real cost paid for nothing.

5. The boundary question, which is the durable half

The script's own header says:

docs/agent-handoff.md section 3 owns the REASONING for each of these … --print-plan renders this without running anything, which is what makes drift from section 3 testable.

The drift here is from §5, not §3 — and that is a coherent reason for the omission rather than mere oversight. scripts/gate was written against §3's gate policy; this precondition lives in §5's hazard register, which the script never claimed to encode.

So the durable fix is not only the missing line. It is deciding where a requirement like this belongs, and making the script's stated contract match what it actually has to guarantee. My vote: §3 gains the precondition (it is gate policy — it decides whether a gate's result means anything), §5 keeps the incident and its signature, and the script's header stops naming §3 as its only source. Q#GR-3.

6. Open questions

Q#GR-1 — what exactly must be built, and does the default sweep need it too?

§5 names cargo build --workspace --no-default-features --features luajit,crdt and says it "produces both binaries". §3's inference says the default sweep is unaffected. Neither is verified by this document.

Required before implementation, by observation rather than reading: delete pmacs-gpu from a target directory, run the default sweep, and record whether it passes; then repeat for the crdt sweep. If the default sweep also needs a binary, the step is unconditional and §4's "only under --protocol" is wrong.

This is the one thing in this lane I would not accept on reasoning. The whole defect is a precondition nobody checked; establishing its replacement by reading would repeat the error at one remove.

Q#GR-2 — does a build failure fail the suite, or abort it?

My vote: fail like any other gate, and let the remaining steps run. --no-fail-fast is the established posture of this suite, and a sweep that then fails for the missing binary produces a second, consistent signal rather than a mysterious absence.

The counter-argument is real: twelve downstream failures with a known cause is noise. But the script already prints per-gate logs and a FAILED: list, so the cause is named at the top, and suppressing downstream output is how a tool starts deciding what its user is allowed to see.

Q#GR-3 — where does this requirement live?

See §5. My vote: §3 gains it, §5 keeps the incident, the script's header cites both. The alternative — leave §5 as the only home and have the script silently encode it — reproduces exactly the condition that made this gap invisible.

Q#GR-4 — should --print-plan be asserted against the handoff?

Tempting and out of scope. A test that parses prose out of agent-handoff.md and compares it to the plan would be brittle in the direction that produces false confidence. Not in this lane, and named so it is not mistaken for an oversight.

7. Verification

• --print-plan --protocol emits build-crdt immediately before sweep-crdt. Order asserted, not just presence: a build after the sweep it feeds is the same defect with an extra line.
• --print-plan WITHOUT --protocol does not emit it (subject to Q#GR-1 — if the default sweep turns out to need the binary too, this assertion inverts and §4 changes with it).
• A real fresh-target --protocol run goes green without a manual build, which is the acceptance criterion and the thing that was false. Witnessed on a target directory with no pmacs-gpu in it.
• A failing build is attributed to build-crdt, not to sweep-crdt (Q#GR-2) — the wrong-name case §4 rejects.
• The existing 15 tests/gate_script_acceptance.rs tests still pass, and the new assertions join them on the no-gates paths (--print-plan runs nothing), keeping the suite cheap.

What this will NOT prove: that the plan matches the handoff in general (Q#GR-4), or that any other §5 hazard is encoded in the script — this lane fixes one and asks where such requirements belong, it does not audit §5.

8. Not in scope

Any feature work. Any src/ change. Auditing the rest of handoff §5 for further unencoded preconditions (worth doing; not here). A plan-versus-handoff consistency test (Q#GR-4). Changing which gates the suite runs, or the acceptance-suite selection policy — §3 remains authoritative for both. Rerunning PR #228's gate, which is that lane's unblocking step and happens after this lands, not inside it.