Skip to content

Commit 6d4e5ea

Browse files
committed
πŸ“ Return the gate's sources, not a second copy of its answer
Two contract problems in the replacement for the authority leak. `Implementation` declared `pullRequest: { type: string }` and returned the raw binding. #295 specifies a structured handle β€” number, URL, head and base identities, state, reviews, comments, checks β€” so a conforming `<PullRequest>` would perform its durable effects and only then fail this component's return validation. The previous harness stubbed the handle as a string, which is exactly why the probe stayed green. `start.md` consumes none of it and the artifact ledger records the effect and handle independently (#291), so the field is gone and `report` renders the named fields a reader needs. If a later caller needs the handle it gets #295's object schema, never a placeholder. Both stages also returned `authorized` and `terminal`, duplicating `decision.proceed && verdictPassed` and a second reading of the same two fields. A return schema can require both sources to be present but cannot require a derived flag to agree with them, so a record pairing `proceed: false` with `authorized: true` validated β€” and `authorized` read confusingly next to the separate authorization checkpoint. Both are gone, along with the `StageResult` name, which was coined without the permission architecture.md's terminology registry requires; it is not being added there. `start.md` now computes each gate where it uses it, from the authoritative pair. After a loop, `decision.proceed` false is a decline and `decision.proceed` true with `verdictPassed` false is exhaustion; the gate refuses both and the output tells them apart, while the terminal policy stays unresolved under #290. Deferred `<Issue>` creation keeps its corrected position after the checkpoint, inside the approved path. Discrimination reruns against the real documents with effects stubbed at their specified shapes. Declined plan review: 3 turns, no authorization question, no effects. Declined pull-request review: no deferred issue, no acceptance question. Fail-then-pass reaches implementation only after the passing verdict. Planning exhaustion and pull-request-review exhaustion each reach neither. Mutations: gating on a duplicated `authorized` field advances a declined review (3 turns becomes 6); declaring the handle as a string fails return validation after commit and issue effects have already run; moving `<Issue>` ahead of approval creates it despite the decline.
1 parent a03f9e3 commit 6d4e5ea

5 files changed

Lines changed: 158 additions & 88 deletions

File tree

β€Žspecs/adversarial-implementation-workflow.mdβ€Ž

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -50,12 +50,14 @@ review neither revises, nor creates the deferred issues it proposed, nor
5050
accepts; a declined acceptance finishes as rejected.
5151

5252
A decision resolved inside a stage is gated the same way, because the stage
53-
returns it. `authorized` β€” the review's approval *and* a passing verdict β€”
54-
is what the caller reads, so a stage cannot approve its own advancement. An
55-
exhausted review loop reports `terminal: "exhausted"` with `authorized` false
56-
and therefore fails closed; what the workflow should ultimately do with an
57-
exhausted loop is an unresolved product decision under #290, and failing closed
58-
is not an answer to it.
53+
returns it. The caller reads the decision together with that stage's verdict β€”
54+
approval *and* a passing review β€” so a stage cannot approve its own advancement.
55+
A stage returns those two sources and nothing derived from them: a precomputed
56+
flag would be a second copy of the same answer that no schema could hold to
57+
agreement with its sources. The same pair distinguishes a decline from a review
58+
that reached its bound still failing, and neither advances; what the workflow
59+
should ultimately do with an exhausted loop is an unresolved product decision
60+
under #290, and refusing to advance is not an answer to it.
5961

6062
`proceed: true` authorizes the exact transition and effects the checkpoint
6163
assessed, and nothing more. Free-text fields in a decision record the user's
@@ -306,7 +308,11 @@ Two are not implemented:
306308
its identity and state (#295).
307309

308310
Each environmental operation declares its inputs and preconditions, reconciles
309-
existing state, returns a structured handle, and records its observed effects.
311+
existing state, returns a structured handle, and records its observed effects. A
312+
handle is a structure, never a string standing in for one: `<PullRequest>`
313+
resolves a number, URL, head and base identities, state, reviews, comments, and
314+
checks, and a stage that declared any of that as text would fail its own return
315+
validation after the effect had already happened.
310316
Rerunning a pull-request operation resolves the existing pull request rather
311317
than creating a duplicate (#297).
312318

β€Žworkflows/adversarial-implementation/Implementation.mdβ€Ž

Lines changed: 28 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -17,12 +17,9 @@ props:
1717

1818
returns:
1919
report: { type: string }
20-
pullRequest: { type: string }
2120
verdictPassed: { type: boolean }
2221
review: { type: string }
2322
revisionPrompt: { type: string }
24-
authorized: { type: boolean }
25-
terminal: { type: string }
2623
findings:
2724
type: array
2825
items:
@@ -220,7 +217,8 @@ remote effects.
220217

221218
Pull request:
222219

223-
{pullRequest}
220+
#{pullRequest.number} ({pullRequest.state}) {pullRequest.url}
221+
head {pullRequest.headSha} onto base {pullRequest.baseSha}
224222

225223
Result contract:
226224

@@ -277,7 +275,8 @@ remote effects.
277275

278276
## Pull request
279277

280-
{pullRequest}
278+
#{pullRequest.number} ({pullRequest.state}) {pullRequest.url}
279+
head {pullRequest.headSha} onto base {pullRequest.baseSha}
281280

282281
## Planner review
283282

@@ -336,24 +335,31 @@ remote effects.
336335

337336
<Return value={{
338337
report: checkpointMaterial,
339-
pullRequest: pullRequest,
340338
verdictPassed: verdict.passed,
341339
review: verdict.review,
342340
revisionPrompt: verdict.revisionPrompt,
343341
findings: verdict.findings,
344-
decision: reviewCheckpoint,
345-
authorized: reviewCheckpoint.proceed && verdict.passed,
346-
terminal: reviewCheckpoint.proceed ? (verdict.passed ? "converged" : "exhausted") : "declined"
342+
decision: reviewCheckpoint
347343
}} />
348344

349345
## The stage returns its control state
350346

351347
Like `Planning`, this is a **value component**: it resolves a user decision
352-
internally, so it returns that decision rather than a rendering of it.
353-
`authorized` is `reviewCheckpoint.proceed && verdict.passed`, and `terminal` is
354-
`converged`, `declined`, or `exhausted`. Final acceptance is reachable only when
355-
`authorized` is true, so a declined or exhausted review cannot be reported as an
356-
accepted change.
348+
internally, so it returns that decision rather than a rendering of it. It hands
349+
back the complete `reviewCheckpoint` decision and the parsed verdict's fields,
350+
and nothing derived from them. The caller reads
351+
`decision.proceed && verdictPassed` directly, so there is no second copy of that
352+
answer to disagree with the first.
353+
354+
The pull-request handle is **not** returned. `<PullRequest>` (#295) resolves a
355+
structured handle carrying the number, URL, head and base identities, state,
356+
reviews, comments, and checks, and `start.md` consumes none of it β€” the artifact
357+
ledger (#291) records the effect and its handle independently. The `report`
358+
above renders the specific fields a reader needs. A return field typed `string`
359+
would be worse than useless here: a conforming `<PullRequest>` would perform its
360+
durable effects and only then fail this component's return validation. If a
361+
later caller genuinely needs the handle, it is added with #295's object schema,
362+
never a placeholder.
357363

358364
The agent, parsing, and control-flow syntax runs today. A value component's body
359365
runs fail-fast, so the final `<Parse>` in each repair loop ends the stage rather
@@ -362,8 +368,14 @@ than passing malformed data to a durable effect.
362368
The user's decision outranks the verdict here too. `reviewCheckpoint.proceed` is
363369
read before `verdict.passed`, so a declined pull-request review leaves the loop
364370
without revising the implementation and without reporting it as reviewed. The
365-
stage is reached at all only because `start.md` gated it on both
366-
`planning.authorized` and `authorization.proceed`.
371+
stage is reached at all only because `start.md` gated it on
372+
`planning.decision.proceed && planning.verdictPassed` and then on
373+
`authorization.proceed`.
374+
375+
After the loop, `decision.proceed` true with `verdictPassed` false is what
376+
exhaustion looks like: the user kept approving and the verdict never passed. The
377+
caller's gate rejects that pair, so an exhausted review cannot reach acceptance.
378+
What the workflow should ultimately do about it stays unresolved under #290.
367379

368380
## Approval precedes durable effects
369381

β€Žworkflows/adversarial-implementation/Planning.mdβ€Ž

Lines changed: 23 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,6 @@ returns:
2020
verdictPassed: { type: boolean }
2121
review: { type: string }
2222
revisionPrompt: { type: string }
23-
authorized: { type: boolean }
24-
terminal: { type: string }
2523
decision:
2624
type: object
2725
properties:
@@ -213,30 +211,34 @@ resolves factual disagreement, while the user resolves material choices.
213211
verdictPassed: verdict.passed,
214212
review: verdict.review,
215213
revisionPrompt: verdict.revisionPrompt,
216-
decision: planCheckpoint,
217-
authorized: planCheckpoint.proceed && verdict.passed,
218-
terminal: planCheckpoint.proceed ? (verdict.passed ? "converged" : "exhausted") : "declined"
214+
decision: planCheckpoint
219215
}} />
220216

221217
## The stage returns its control state
222218

223219
This is a **value component**. A stage that resolves a user decision internally
224220
cannot discard it as rendered prose: its caller has to gate on that decision,
225221
and prose gives a caller nothing to branch on. So `Planning` declares `returns`,
226-
renders nothing, and hands back the plan, the parsed verdict's fields, the
227-
complete plan-review `UserDecision`, and two derived fields the caller reads
228-
directly:
222+
renders nothing, and hands back the plan, the parsed verdict's fields, and the
223+
complete plan-review `UserDecision`.
229224

230-
- **`authorized`** is `planCheckpoint.proceed && verdict.passed`. Only a plan
231-
that both passed review *and* was approved may reach authorization. Either one
232-
alone is not enough.
233-
- **`terminal`** distinguishes how the loop ended: `converged` (approved and
234-
passing), `declined` (the user stopped it), or `exhausted` (approved but still
235-
failing after `max` rounds).
225+
It returns those sources and nothing derived from them. A field like
226+
`authorized` would be a second copy of `decision.proceed && verdictPassed`, and
227+
a return schema cannot express that the copy must agree with its sources β€” a
228+
record claiming approval over a decline would validate. The caller reads the two
229+
authoritative fields and computes the gate itself, so there is only ever one
230+
answer.
236231

237-
`authorized` is false for both `declined` and `exhausted`, so neither can
238-
advance the workflow. That is failing closed, not a decision about what an
239-
exhausted loop *should* do.
232+
Three outcomes are distinguishable from those fields alone, which is all a caller
233+
needs:
234+
235+
| `decision.proceed` | `verdictPassed` | What happened |
236+
| --- | --- | --- |
237+
| `true` | `true` | the review passed and the user approved it |
238+
| `false` | either | the user declined; the loop stopped without revising |
239+
| `true` | `false` | the loop reached `max` still failing β€” exhaustion |
240+
241+
Only the first pair advances.
240242

241243
The loop is bounded and records why it stopped. `<Loop>` journals every
242244
iteration it enters and one terminal record whose outcome is `break` β€” a passing
@@ -261,10 +263,10 @@ text, raising nothing.
261263

262264
**Outstanding gap: the terminal policy for exhaustion.** Reaching `max`
263265
completes the loop normally β€” exhaustion is not a failure and produces no
264-
diagnostic. This stage reports it as `terminal: "exhausted"` with `authorized`
265-
false, so an exhausted loop is distinguishable from a converged one and cannot
266-
advance. That is the minimum needed to keep the workflow safe; it is not the
267-
policy. What the workflow *should* do when five rounds end without a passing
266+
diagnostic. The returned pair identifies it (`decision.proceed` true,
267+
`verdictPassed` false) and the caller's gate refuses it, so an exhausted loop
268+
cannot advance. That is the minimum needed to keep the workflow safe; it is not
269+
the policy. What the workflow *should* do when five rounds end without a passing
268270
verdict β€” return the failing plan, fail the stage, or return to the user β€” is an
269271
unresolved product decision recorded against
270272
[issue #290](https://github.com/taras/executable.md/issues/290), whose

β€Žworkflows/adversarial-implementation/artifacts.mdβ€Ž

Lines changed: 25 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -138,17 +138,12 @@ declares.
138138
`returns`, so their results are validated JSON values bound through `as` rather
139139
than text a caller would have to interpret.
140140

141-
- `StageResult` β€” what `Planning` and `Implementation` return. Each carries its
142-
prose (`plan` or `report`), the parsed verdict's fields, the complete
143-
`UserDecision` that stage resolved internally, and two derived control fields:
144-
`authorized` (`proceed && verdict.passed`) and `terminal` (`converged`,
145-
`declined`, or `exhausted`). `start.md` gates the next transition on
146-
`authorized` and reports `terminal`. A stage that resolved a user decision
147-
cannot return prose alone β€” its caller has nothing to branch on, and the
148-
authority the checkpoint exercised would be lost at the boundary.
149-
- `UserDecision` β€” the transition decision a caller gates on, returned directly
150-
by `UserCheckpoint` and embedded in each `StageResult`. Two parts combine
151-
into it. The **decision** is `proceed`, `response`, and `rationale`, validated
141+
- `UserDecision` β€” the transition decision a caller gates on. `UserCheckpoint`
142+
returns it directly, and `Planning` and `Implementation` each return the one
143+
they resolved internally, alongside their prose and their parsed verdict's
144+
fields. A stage that resolved a user decision cannot return prose alone: its
145+
caller has nothing to branch on, and the authority the checkpoint exercised
146+
would be lost at the boundary. Two parts combine into it. The **decision** is `proceed`, `response`, and `rationale`, validated
152147
against one schema on both paths: `<Elicit>` binds it when the assessment
153148
reports a material choice, and an explicit `<Parse>` binds it when there is
154149
none. `UserCheckpoint` returns those alongside the assessment fields, so one
@@ -158,6 +153,25 @@ than text a caller would have to interpret.
158153
artifact ledger (#291) and does not exist. Nothing in the returned value
159154
identifies the person who answered.
160155

156+
A stage returns those sources and nothing derived from them. `start.md` computes
157+
its gate as `decision.proceed && verdictPassed` where it uses it, rather than
158+
reading a field the stage precomputed: a return schema can require both fields to
159+
be present but cannot require a derived flag to agree with them, so a record
160+
pairing a declining decision with an approving flag would validate. The same two
161+
fields tell a decline (`proceed` false) from a review that never passed
162+
(`proceed` true, `verdictPassed` false), so no separate outcome label is needed
163+
either.
164+
165+
Neither stage returns the pull-request handle. `<PullRequest>` (#295) resolves a
166+
structured handle carrying the number, URL, head and base identities, state,
167+
reviews, comments, and checks. Nothing in this workflow consumes it, and the
168+
artifact ledger records the effect and its handle independently, so
169+
`Implementation` renders the fields a reader needs into its `report` instead. A
170+
return field typed `string` would be actively harmful: a conforming
171+
`<PullRequest>` would perform its durable effects and only then fail the stage's
172+
return validation. If a later caller needs the handle, it is declared with #295's
173+
object schema.
174+
161175
Prompt output used for control flow is JSON parsed against captured draft-07
162176
JSON Schema content. `<SafeParse>` exposes the candidate and normalized errors
163177
for a visible, bounded correction turn; a final `<Parse>` prevents invalid data

0 commit comments

Comments
Β (0)