Make the Forgejo done gate something a worker can actually satisfy #24

Merged

john merged 2 commits from fm/fm-brief-forgejo-done-gate-unreachable into main 2026-09-05 05:21:00 +00:00

Conversation 0 Commits 2 Files changed 3 +56 -6

john commented 2026-08-29 23:29:17 +00:00

Owner

Copy link

The bug

The generated ship brief tells workers to report done: branch <name> checks green. On a Forgejo project that is an attestation they structurally cannot produce:

1. The validation tool has no Forgejo provider — its pr and ci steps skip with "provider unknown is not supported yet", so a successful run returns outcome=passed, never checks-passed.
2. The project's own CI triggers on pull_request, so nothing can run until a PR exists — and the same brief correctly tells the worker that firstmate opens the PR and that it must not go hunting for a forge credential.

So the worker is asked to report a state it cannot produce, cannot observe, and is forbidden from getting the credential to check.

What it cost, in one overnight run

Five workers reported done: at a commit believing they were finished. One of those "checks green" claims was verified false against the forge — the branch did not exist there at all. One finished job then sat idle for an hour, pipeline passed and branch pushed, because it had no defined way to say so.

One worker did the right thing: read its own contract, worked out the gate was unreachable, and blocked with evidence in lieu — every check ci.yml runs, executed on the exact pushed head. That outcome depended entirely on that worker being unusually scrupulous.

The fifth occurrence was the worker implementing this fix, which reported done at an unpushed commit while holding the explanation of the bug in its own brief. That is the strongest available evidence that the failure is in the contract rather than in any worker's judgement — a contract that asks for the impossible trains people to approximate it, and approximating "delivered" is how work silently fails to ship.

The change

bin/fm-brief.sh already resolves the origin to choose its PR-handoff wording. The done gate now uses the same resolution.

For a Forgejo origin the worker's gate is: pipeline outcome=passed, branch pushed, remote ref verified, local gates green on the exact pushed head — reported as done: branch <name> pushed <sha>, pipeline passed, CI pending firstmate PR. The brief states that firstmate opens the PR and confirms CI, so the remaining step is visibly someone else's.

The GitHub gate is unchanged.

Test

A divergent-gate test asserting the Forgejo and GitHub briefs differ appropriately, failing against pre-fix code.

Pipeline passed. Pushed at b5af0ce3 — and reported using the new wording this change introduces.

## The bug The generated ship brief tells workers to report `done: branch <name> checks green`. On a **Forgejo** project that is an attestation they structurally cannot produce: 1. The validation tool has no Forgejo provider — its `pr` and `ci` steps skip with *"provider unknown is not supported yet"*, so a successful run returns `outcome=passed`, never `checks-passed`. 2. The project's own CI triggers on `pull_request`, so nothing can run until a PR exists — and the same brief correctly tells the worker that **firstmate** opens the PR and that it must not go hunting for a forge credential. So the worker is asked to report a state it cannot produce, cannot observe, and is forbidden from getting the credential to check. ## What it cost, in one overnight run **Five workers reported `done:` at a commit believing they were finished.** One of those "checks green" claims was verified false against the forge — the branch did not exist there at all. One finished job then sat **idle for an hour**, pipeline passed and branch pushed, because it had no defined way to say so. One worker did the right thing: read its own contract, worked out the gate was unreachable, and blocked with evidence in lieu — every check `ci.yml` runs, executed on the exact pushed head. That outcome depended entirely on that worker being unusually scrupulous. **The fifth occurrence was the worker implementing this fix**, which reported done at an unpushed commit while holding the explanation of the bug in its own brief. That is the strongest available evidence that the failure is in the contract rather than in any worker's judgement — a contract that asks for the impossible trains people to approximate it, and approximating "delivered" is how work silently fails to ship. ## The change `bin/fm-brief.sh` already resolves the origin to choose its PR-handoff wording. The done gate now uses the same resolution. For a Forgejo origin the worker's gate is: pipeline `outcome=passed`, branch pushed, remote ref verified, local gates green **on the exact pushed head** — reported as `done: branch <name> pushed <sha>, pipeline passed, CI pending firstmate PR`. The brief states that firstmate opens the PR and confirms CI, so the remaining step is visibly someone else's. The GitHub gate is unchanged. ## Test A divergent-gate test asserting the Forgejo and GitHub briefs differ appropriately, failing against pre-fix code. Pipeline passed. Pushed at `b5af0ce3` — and reported using the new wording this change introduces.

john added 2 commits 2026-08-29 23:29:17 +00:00

fix(brief): make the Forgejo no-mistakes done gate reachable ... 809f2af700

The generated no-mistakes definition of done asked workers on a Forgejo-origin
project to attest "checks green" - a state they cannot produce, observe, or
obtain a credential to check. no-mistakes has no Forgejo provider, so its pr
and ci steps skip and a successful run returns outcome=passed, never
checks-passed; the project's CI runs on the pull_request-triggered workflow
that cannot fire until firstmate opens the PR, which the same brief correctly
forbids the worker from seeking a credential for.

This unreachable attestation trained workers to approximate one: on the
2026-08-29 overnight run, workers reported premature done states (one against
a branch that did not even exist on the forge), and a scrupulous worker
correctly blocked instead. The good outcome depended on individual
conscientiousness rather than the contract.

For a non-GitHub origin the worker's gate is now: pipeline outcome=passed,
branch pushed, remote ref verified at the exact head the pipeline certified,
then "done: branch <name> pushed <sha>, pipeline passed, CI pending firstmate
PR". The brief states firstmate opens the PR and confirms the CI verdict, so
the worker does not go hunting for a forge credential. The GitHub-origin gate
is unchanged.

The updated test asserts the Forgejo and GitHub no-mistakes gates diverge
appropriately and fails against the pre-fix code.

no-mistakes(document): Document Forgejo no-mistakes done-gate origin split in AGENTS.md b5af0ce305

john merged commit f3fe9a73f4 into main 2026-09-05 05:21:00 +00:00

john referenced this pull request from a commit 2026-09-05 05:21:00 +00:00

Make the Forgejo done gate something a worker can actually satisfy (#24)

john referenced this pull request from a commit 2026-09-30 11:06:05 +00:00

feat(brief): add forge=forgejo to the delivery-forge axis

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

john/firstmate!24

No description provided.