Skip to content

Commit fb3b47f

Browse files
committed
📝 State the handle boundary, the two text components, and the objection text
Three claims did not match what the documents do. `artifacts.md` still said nothing consumes the pull-request handle. The boundary is now stated exactly: `Implementation` consumes all of it internally, `start.md` never receives it — what crosses the stage boundary is the verdict and the decision — and the artifact ledger records the effect independently (#291). The specification said both text components do their work in documentation. Only `Discovery` does. `InstructionFiles` puts its `<Each>` and `<File>` reads inside `<Output>`, and probing that case corrected a second assumption in the same sentence: `<File>` prints its own failures, so an unreadable instruction file is decided as a printed error before the region's `output` mode sees it. The run continues; what stops the caller is the binding rule, since `as` refuses a body holding a printed error and `instructions` stays unbound. `start.md` gains the same qualifier, because "an undecided error fails the run" is only true of undecided ones. The user checkpoint did not carry what the PR claimed it did. The planner prompt rendered each review's body; `checkpointMaterial` rendered only the author, state, and head. A user approving a change has to read the original objection, not the planner's summary of it, so the body is now in both. The earlier probe missed this because it asserted the review *author* on the checkpoint material and the *body* only on the prompt — an assertion too weak to see the omission it was meant to cover. Discrimination now asserts the body on both surfaces. Dropping any category reddens both symmetrically, and dropping the body from the checkpoint alone reddens the checkpoint while the prompt stays green — the exact shape of the defect.
1 parent 3d0b802 commit fb3b47f

4 files changed

Lines changed: 56 additions & 21 deletions

File tree

‎specs/adversarial-implementation-workflow.md‎

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -201,6 +201,11 @@ comments, and check results — rather than a subset, and names the revision und
201201
review: the diff at the head identity against the base. A verdict describes that
202202
head alone, and a moved head requires a fresh review.
203203

204+
The user's checkpoint carries the same evidence. An existing objection reaches
205+
the person approving the change in its own words, not only as the planner
206+
summarized it — a reviewer's own text is what a later reader needs to judge
207+
whether the objection was answered.
208+
204209
Factual disagreement calls for more evidence. When evidence leaves more than one
205210
viable choice, the agents present the options, consequences, and recommendations
206211
to the user. Convergence means that the final plan reflects a shared
@@ -269,9 +274,23 @@ half-record.
269274

270275
A **text component** is split by its `<Output>` boundary: the region inside runs
271276
under the `output` error mode, everything outside is documentation and runs
272-
under `throw`. `InstructionFiles` and `Discovery` are the two here, and each
273-
puts its work in documentation, so an undecided error ends the run rather than
274-
printing into a region nobody reads.
277+
under `throw`. The two here sit on opposite sides of that line, and they fail
278+
differently as a result.
279+
280+
`Discovery` runs its prompt in documentation and renders only the captured
281+
result. A failed prompt is raised there — `throwOnError` is what raises it — and
282+
`throw` ends the run.
283+
284+
`InstructionFiles` is the other way round: its `<Each>` and `<File>` reads *are*
285+
its `<Output>` region. `<File>` prints its own failures rather than propagating
286+
them, so an unreadable instruction file becomes a printed error and the region's
287+
`output` mode never decides anything. The run continues, and what stops the
288+
caller from proceeding on nothing is the binding rule: `as` refuses a body
289+
holding a printed error, so `instructions` stays unbound and the error surfaces
290+
at the invocation rather than inside the text a prompt would quote.
291+
292+
That difference is worth knowing before relying on either: a missing instruction
293+
file is visible and non-fatal, while a failed discovery prompt is fatal.
275294

276295
A **value component** declares `returns`, so it renders nothing and cannot
277296
contain `<Output>` at all — that would be a structural error. Its entire body

‎workflows/adversarial-implementation/Implementation.md‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -305,7 +305,7 @@ remote effects.
305305
### Reviews
306306

307307
<Each in={pullRequest.reviews} let="review">
308-
- {review.author} ({review.state}) on {review.headSha}
308+
- {review.author} ({review.state}) on {review.headSha}: {review.body}
309309
</Each>
310310

311311
### Comments
@@ -399,11 +399,16 @@ answer to disagree with the first.
399399
head and base identities, state, reviews, comments, and checks. This stage
400400
consumes all of it, because the planner cannot recover any of it itself: agent
401401
network access is denied for the supervised exercise, so whatever the prompt does
402-
not render is invisible to the review. Every category is rendered explicitly —
403-
each collection iterated with `<Each>`, never stringified as an object — into
404-
both the planner prompt and the checkpoint material the user reads. A review that
405-
cannot see a failing check or an existing objection is not adversarial, it is
406-
uninformed.
402+
not render is invisible to the review. Every category — reviews, comments, and
403+
checks — is rendered explicitly into both the planner prompt and the checkpoint
404+
material the user reads, each collection iterated with `<Each>` and never
405+
stringified as an object. A review that cannot see a failing check or an existing
406+
objection is not adversarial, it is uninformed.
407+
408+
The two surfaces carry the same categories and the same consequential content,
409+
including each review's body: a user approving the change reads the original
410+
objections rather than the planner's summary of them. The checkpoint omits only a
411+
check's link, which is a way to find evidence rather than evidence itself.
407412

408413
The prompt names the revision under review: the planner reviews the diff at
409414
`headSha` against `baseSha`, and a verdict describes that head only. A moved head

‎workflows/adversarial-implementation/artifacts.md‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -163,12 +163,16 @@ fields tell a decline (`proceed` false) from a review that never passed
163163
(`proceed` true, `verdictPassed` false), so no separate outcome label is needed
164164
either.
165165

166-
Neither stage returns the pull-request handle. `<PullRequest>` (#295) resolves a
167-
structured handle carrying the number, URL, head and base identities, state,
168-
reviews, comments, and checks. Nothing in this workflow consumes it, and the
169-
artifact ledger records the effect and its handle independently, so
170-
`Implementation` renders the fields a reader needs into its `report` instead. A
171-
return field typed `string` would be actively harmful: a conforming
166+
Neither stage *returns* the pull-request handle, and the boundary is worth
167+
stating exactly. `<PullRequest>` (#295) resolves a structured handle carrying the
168+
number, URL, head and base identities, state, reviews, comments, and checks.
169+
`Implementation` **consumes all of it**, internally: the planner has no network
170+
access, so the stage renders every category into the review prompt and the
171+
checkpoint material. `start.md` never receives it — what crosses the stage
172+
boundary is the verdict and the decision it gates on. The artifact ledger records
173+
the effect and its handle independently (#291).
174+
175+
A return field typed `string` would be actively harmful: a conforming
172176
`<PullRequest>` would perform its durable effects and only then fail the stage's
173177
return validation. If a later caller needs the handle, it is declared with #295's
174178
object schema.

‎workflows/adversarial-implementation/start.md‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -265,19 +265,25 @@ A **text component** — `InstructionFiles` and `Discovery` — is split by its
265265
- Everything **outside** `<Output>` is documentation and runs under the `throw`
266266
error mode. The first error stops the body and fails the run, and no
267267
`<PrintErrors>` region can print it instead.
268-
- The **`<Output>` region** runs under the `output` error mode: an undecided
268+
- The **`<Output>` region** runs under the `output` error mode: an *undecided*
269269
error there fails the run too, though a `<PrintErrors>` region may print it
270270
instead. Either way the region keeps what it had already rendered — that
271271
partial text reaches the output stream, and nothing after the failure does.
272272
Printing an `output` decision is the contract; the engine does not do it yet
273273
(#327).
274274

275+
"Undecided" is the operative word. `InstructionFiles` puts its `<File>` reads in
276+
its `<Output>` region, and `<File>` prints its own failures, so an unreadable
277+
instruction file is already decided as a printed error and the region's mode
278+
never sees it. The run continues; what stops the caller is that `as` refuses a
279+
body holding a printed error, so `instructions` stays unbound.
280+
275281
A **value component** — `UserCheckpoint`, `Planning`, `Implementation` — has no
276282
such split. Declaring `returns` means it renders nothing, so `<Output>` inside
277283
one is a structural error; its whole body runs fail-fast and a failure binds
278284
nothing at all. There is no partially validated return for a caller to gate on.
279285

280-
Either way a stage returns a complete, schema-validated result or it fails, and
286+
By one route or another a caller receives a complete result or nothing —
281287
never a half-record. The `throwOnError` on each `<Prompt>` is load-bearing for
282288
the same reason: a failed prompt without it records its failure and returns its
283289
text, raising nothing for the error mode to decide.
@@ -336,10 +342,11 @@ than receiving them pre-rendered.
336342
Neither stage returns the pull-request handle, but `Implementation` consumes it
337343
in full. `<PullRequest>` (#295) resolves the number, URL, head and base
338344
identities, state, reviews, comments, and checks; the planner has no network
339-
access, so `Implementation` renders every category explicitly into the review
340-
prompt and into the checkpoint material, and the artifact ledger (#291) records
341-
the effect independently. What `start.md` gates on is the verdict and the
342-
decision, so the handle itself never crosses the stage boundary.
345+
access, so `Implementation` renders every category — reviews with their bodies,
346+
comments, and checks — explicitly into the review prompt and into the checkpoint
347+
material, and the artifact ledger (#291) records the effect independently. What
348+
`start.md` gates on is the verdict and the decision, so the handle itself never
349+
crosses the stage boundary.
343350

344351
## Details
345352

0 commit comments

Comments
 (0)