Skip to content

Commit d83beb0

Browse files
committed
📝 Return stage control state so user authority survives the boundary
`Planning` and `Implementation` consumed their internal checkpoint decisions and returned only prose, so authority leaked at the component boundary. A declined plan review broke the planning loop, but `start.md` still asked the authorization question and could reach `Implementation`; a declined pull-request review still let the change be reported accepted. `Implementation` also created deferred `<Issue>` effects before its review checkpoint ran, so the planner's proposed disposition became a durable GitHub object before the user approved it. The earlier probe stubbed the outer stages, so it never exercised those paths. Both stages are now value components. Each returns its prose, the parsed verdict's fields, the complete `UserDecision` it resolved, and two derived control fields the caller gates on: `authorized`, which is `proceed && verdict.passed`, and `terminal`, which distinguishes `converged` from `declined` and `exhausted`. A stage cannot approve its own advancement, and an exhausted loop reports itself distinctly and fails closed — which is not a decision about what exhaustion should do, still unresolved under #290. `start.md` gates on those returns: authorization is requested only after a passing plan verdict and an approving plan-review decision, acceptance only after a passing pull-request verdict and an approving review decision. It renders the human-readable reports from the returned fields. Deferred `<Issue>` creation moved inside the approved branch, after the checkpoint. `proceed: true` authorizes the exact proposed transition and effects; the free-text response records reasoning and never amends effects, because an effect that has already executed cannot be amended by prose. `proceed: false` performs none of them. Discrimination against the real `Planning`, `Implementation`, and `UserCheckpoint`, stubbing only the agent transport and the three deterministic components that do not exist. A declined plan review: 3 agent turns, no authorization question, no implementation turn, no effects. A declined pull-request review: no deferred issue, no acceptance question. A failing verdict with approval performs the revision turn and reaches the next stage only after a later passing verdict. Exhaustion reaches neither. Moving `<Issue>` ahead of approval creates the issue despite a decline; bypassing a caller gate advances past a declined review; reducing either return to text leaves the gate fields unresolved. Each mutation changes an observed result.
1 parent 19bd24f commit d83beb0

5 files changed

Lines changed: 355 additions & 202 deletions

File tree

‎specs/adversarial-implementation-workflow.md‎

Lines changed: 39 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -43,15 +43,32 @@ but the component does not encode that role. It may determine that user
4343
involvement is unnecessary, but only the user resolves a material choice.
4444

4545
That authority controls execution rather than describing it. A checkpoint binds
46-
a schema-validated decision, and every material transition is gated on its
47-
`proceed`: `proceed: false` never advances the workflow. A declined handoff does
48-
not start planning, a declined authorization does not start implementation, a
49-
declined review neither revises nor accepts, and a declined acceptance finishes
50-
as rejected. A checkpoint that found no material choice produces an explicit
51-
`proceed: true` recording why, so a transition never advances because a decision
52-
was missing. What remains missing is stopping *at* the boundary — halting
53-
cleanly where the user answered so a later invocation resumes there, with a
54-
recorded stop reason — which is `<Stage>` (#298) over `<Workflow>` (#289).
46+
a schema-validated decision, and every material transition is gated on it:
47+
`proceed: false` never advances the workflow. A declined handoff does not start
48+
planning; a declined authorization does not start implementation; a declined
49+
review neither revises, nor creates the deferred issues it proposed, nor
50+
accepts; a declined acceptance finishes as rejected.
51+
52+
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.
59+
60+
`proceed: true` authorizes the exact transition and effects the checkpoint
61+
assessed, and nothing more. Free-text fields in a decision record the user's
62+
reasoning; nothing reads them to amend what runs, because an effect that has
63+
already executed cannot be amended by prose. This is why durable effects follow
64+
their approval rather than preceding it — the deferred issues a review proposes
65+
are created inside the approved path, after the checkpoint.
66+
67+
A checkpoint that found no material choice produces an explicit `proceed: true`
68+
recording why, so a transition never advances because a decision was missing.
69+
What remains missing is stopping *at* the boundary — halting cleanly where the
70+
user answered so a later invocation resumes there, with a recorded stop reason —
71+
which is `<Stage>` (#298) over `<Workflow>` (#289).
5572

5673
## Smallest complete path
5774

@@ -221,11 +238,19 @@ normalized clone reaches the caller. `<Glob>` declares `returns`, so the
221238
`string[]` this workflow binds is that validated clone rather than a
222239
by-reference binding.
223240

224-
Every stage component in this workflow is a text component, because each
225-
stage's output is also material a user reads at a checkpoint.
226-
`<UserCheckpoint>` is not a stage and is the one exception: it declares
227-
`returns` and binds a validated transition decision, because its result is
228-
branched on rather than read.
241+
A stage that only produces material for the next prompt is a text component:
242+
`InstructionFiles` and `Discovery` render their result and a caller's `as` binds
243+
that text. A stage that resolves a user decision inside itself declares
244+
`returns` instead. `Planning` and `Implementation` each run a review loop that
245+
asks the user a question, so each returns its prose, its parsed verdict, the
246+
complete `UserDecision` it resolved, and the derived `authorized` and `terminal`
247+
its caller gates on. `<UserCheckpoint>` does the same for a single decision.
248+
249+
The rule is about where authority lives. A controller that resolves a decision
250+
and returns only a rendering of it has discarded the thing its caller needs: the
251+
caller would go on to ask the next question regardless, and could report a change
252+
accepted whose review the user rejected. Control state crosses a component
253+
boundary as data or it does not cross at all.
229254

230255
### A stage fails rather than returning a half-record
231256

‎workflows/adversarial-implementation/Implementation.md‎

Lines changed: 91 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,46 @@ props:
1414
instructions: { type: string }
1515
planner: { type: string }
1616
implementor: { type: string }
17+
18+
returns:
19+
report: { type: string }
20+
pullRequest: { type: string }
21+
verdictPassed: { type: boolean }
22+
review: { type: string }
23+
revisionPrompt: { type: string }
24+
authorized: { type: boolean }
25+
terminal: { type: string }
26+
findings:
27+
type: array
28+
items:
29+
type: object
30+
properties:
31+
disposition: { type: string }
32+
title: { type: string }
33+
description: { type: string }
34+
evidence:
35+
type: array
36+
items:
37+
type: string
38+
required: [disposition, title, description, evidence]
39+
additionalProperties: false
40+
decision:
41+
type: object
42+
properties:
43+
requiresUser: { type: boolean }
44+
proceed: { type: boolean }
45+
assessment: { type: string }
46+
recommendation: { type: string }
47+
question: { type: string }
48+
options:
49+
type: array
50+
items:
51+
type: string
52+
response: { type: string }
53+
rationale: { type: string }
54+
required:
55+
[requiresUser, proceed, assessment, recommendation, question, options, response, rationale]
56+
additionalProperties: false
1757
---
1858

1959
# Implementation
@@ -230,15 +270,6 @@ remote effects.
230270
</Session>
231271
</Agent>
232272

233-
<Each in={verdict.findings} let="finding">
234-
<If condition={finding.disposition === "defer"}>
235-
<Issue
236-
pullRequest={pullRequest}
237-
finding={finding}
238-
/>
239-
</If>
240-
</Each>
241-
242273
<Capture as="checkpointMaterial">
243274
## Authorized plan
244275

@@ -269,6 +300,14 @@ remote effects.
269300
as="reviewCheckpoint"
270301
/>
271302
<If condition={reviewCheckpoint.proceed}>
303+
<Each in={verdict.findings} let="finding">
304+
<If condition={finding.disposition === "defer"}>
305+
<Issue
306+
pullRequest={pullRequest}
307+
finding={finding}
308+
/>
309+
</If>
310+
</Each>
272311
<If condition={verdict.passed}>
273312
<Break />
274313
<Else>
@@ -295,61 +334,53 @@ remote effects.
295334
</If>
296335
</Loop>
297336

298-
<Output>
299-
<If condition={reviewCheckpoint.proceed}>
300-
# Implementation result
301-
302-
## Pull request
303-
304-
{pullRequest}
305-
306-
## Planner review
307-
308-
Passed: {verdict.passed}
309-
310-
{verdict.review}
311-
312-
## Findings
313-
314-
<Each in={verdict.findings} let="finding">
315-
### {finding.title}
316-
317-
Disposition: {finding.disposition}
318-
319-
{finding.description}
320-
</Each>
321-
<Else>
322-
# Pull-request review rejected
323-
324-
The user declined to continue at the pull-request review checkpoint. The
325-
implementation below was neither revised nor accepted.
326-
327-
{reviewCheckpoint.rationale}
328-
329-
## Pull request
330-
331-
{pullRequest}
332-
333-
## Planner review
334-
335-
Passed: {verdict.passed}
336-
337-
{verdict.review}
338-
</Else>
339-
</If>
340-
</Output>
341-
342-
The agent, parsing, and control-flow syntax in this component runs today, on
343-
the same terms as `Planning`: the body outside `<Output>` runs under the
344-
`throw` error mode, so the final `<Parse>` in each repair loop ends the stage
345-
rather than passing malformed data to a durable effect.
337+
<Return value={{
338+
report: checkpointMaterial,
339+
pullRequest: pullRequest,
340+
verdictPassed: verdict.passed,
341+
review: verdict.review,
342+
revisionPrompt: verdict.revisionPrompt,
343+
findings: verdict.findings,
344+
decision: reviewCheckpoint,
345+
authorized: reviewCheckpoint.proceed && verdict.passed,
346+
terminal: reviewCheckpoint.proceed ? (verdict.passed ? "converged" : "exhausted") : "declined"
347+
}} />
348+
349+
## The stage returns its control state
350+
351+
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.
357+
358+
The agent, parsing, and control-flow syntax runs today. A value component's body
359+
runs fail-fast, so the final `<Parse>` in each repair loop ends the stage rather
360+
than passing malformed data to a durable effect.
346361

347362
The user's decision outranks the verdict here too. `reviewCheckpoint.proceed` is
348363
read before `verdict.passed`, so a declined pull-request review leaves the loop
349364
without revising the implementation and without reporting it as reviewed. The
350-
stage is reached at all only because `start.md` gated it on
351-
`authorization.proceed`; a declined authorization means these prompts and the
352-
durable effects below them never run.
365+
stage is reached at all only because `start.md` gated it on both
366+
`planning.authorized` and `authorization.proceed`.
367+
368+
## Approval precedes durable effects
369+
370+
Deferred `<Issue>` creation sits **inside** the approved branch, after the
371+
checkpoint. The planner proposes a disposition; the user's approval is what
372+
turns that proposal into a durable GitHub object. Creating the issues first
373+
would make the planner's classification take effect before anyone approved it,
374+
and an issue is not undone by a later decline.
375+
376+
`proceed: true` authorizes the exact transition and the exact effects proposed
377+
in the material the checkpoint assessed — here, an `<Issue>` for every finding
378+
the verdict marked `defer`. It is not an invitation to amend them. The free-text
379+
`response` and `rationale` are a record of the user's reasoning, and nothing
380+
reads them to change which effects run: an effect that already executed cannot
381+
be silently amended by prose. A user who wants different effects declines, and
382+
`proceed: false` performs none of them — no issue, no revision turn, no
383+
acceptance.
353384

354385
`<Commit>` (#294), `<PullRequest>` (#295), and `<Issue>` (#296) do not exist,
355386
and reconciling those durable GitHub effects idempotently is #297. Until they

‎workflows/adversarial-implementation/Planning.md‎

Lines changed: 70 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,31 @@ props:
1414
instructions: { type: string }
1515
planner: { type: string }
1616
implementor: { type: string }
17+
18+
returns:
19+
plan: { type: string }
20+
verdictPassed: { type: boolean }
21+
review: { type: string }
22+
revisionPrompt: { type: string }
23+
authorized: { type: boolean }
24+
terminal: { type: string }
25+
decision:
26+
type: object
27+
properties:
28+
requiresUser: { type: boolean }
29+
proceed: { type: boolean }
30+
assessment: { type: string }
31+
recommendation: { type: string }
32+
question: { type: string }
33+
options:
34+
type: array
35+
items:
36+
type: string
37+
response: { type: string }
38+
rationale: { type: string }
39+
required:
40+
[requiresUser, proceed, assessment, recommendation, question, options, response, rationale]
41+
additionalProperties: false
1742
---
1843

1944
# Planning
@@ -183,44 +208,42 @@ resolves factual disagreement, while the user resolves material choices.
183208
</If>
184209
</Loop>
185210

186-
<Output>
187-
<If condition={planCheckpoint.proceed}>
188-
# Implementation plan
189-
190-
{plan}
191-
192-
## Planner review
193-
194-
Passed: {verdict.passed}
195-
196-
{verdict.review}
197-
<Else>
198-
# Plan review rejected
199-
200-
The user declined to continue at the plan-review checkpoint. The plan below
201-
was neither revised nor accepted.
202-
203-
{planCheckpoint.rationale}
204-
205-
## Implementation plan as it stood
206-
207-
{plan}
208-
209-
## Planner review
210-
211-
Passed: {verdict.passed}
212-
213-
{verdict.review}
214-
</Else>
215-
</If>
216-
</Output>
211+
<Return value={{
212+
plan: plan,
213+
verdictPassed: verdict.passed,
214+
review: verdict.review,
215+
revisionPrompt: verdict.revisionPrompt,
216+
decision: planCheckpoint,
217+
authorized: planCheckpoint.proceed && verdict.passed,
218+
terminal: planCheckpoint.proceed ? (verdict.passed ? "converged" : "exhausted") : "declined"
219+
}} />
220+
221+
## The stage returns its control state
222+
223+
This is a **value component**. A stage that resolves a user decision internally
224+
cannot discard it as rendered prose: its caller has to gate on that decision,
225+
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:
229+
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).
236+
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.
217240

218241
The loop is bounded and records why it stopped. `<Loop>` journals every
219242
iteration it enters and one terminal record whose outcome is `break` — a passing
220243
verdict or a declined checkpoint — `exhausted`, or `error`, and it refuses a
221244
replay whose stored outcome or iteration count disagrees with what this run
222245
reached. `<Loop>` opens no binding scope, so `plan`, `verdict`, and
223-
`planCheckpoint` hold their final values in the `<Output>` region above.
246+
`planCheckpoint` hold their final values where `<Return>` reads them.
224247

225248
The user's decision outranks the verdict. The outer `<If>` reads
226249
`planCheckpoint.proceed` before the inner one reads `verdict.passed`, so a
@@ -229,24 +252,21 @@ presenting it as reviewed — a rejection is neither a revision request nor an
229252
acceptance. `<Break />` works from that nested position, so the two conditions
230253
compose without a flag binding between them.
231254

232-
The body outside `<Output>` runs under the `throw` error mode, which is what
233-
makes the bounded repair turns a real gate: `<SafeParse>` absorbs a malformed
234-
verdict so the document can show the correction prompt, and the final `<Parse>`
235-
ends the stage if the candidate is still invalid. `throwOnError` on each
236-
`<Prompt>` is required for the same reason — a failed prompt without it records
237-
its failure and returns its text, raising nothing.
238-
239-
**Outstanding gap: exhaustion is unhandled.** Reaching `max` completes the loop
240-
normally — exhaustion is not a failure and produces no diagnostic — so whether
241-
an exhausted planning loop counts as converged is this document's policy to
242-
state, and this document does not yet state it. An exhausted loop leaves
243-
`planCheckpoint.proceed` true and `verdict.passed` false, so it takes the same
244-
`<Output>` branch as a converged plan and is distinguished only by the flag it
245-
reports. That branch reports `verdict.passed` rather than titling itself
246-
converged, but reporting the flag is not deciding what should happen. What the
247-
workflow does when five rounds end without a passing verdict — return the
248-
failing plan, fail the stage, or return to the user — is an unresolved product
249-
decision recorded against
255+
A value component's body runs fail-fast, which is what makes the bounded repair
256+
turns a real gate: `<SafeParse>` absorbs a malformed verdict so the document can
257+
show the correction prompt, and the final `<Parse>` ends the stage if the
258+
candidate is still invalid. `throwOnError` on each `<Prompt>` is required for the
259+
same reason — a failed prompt without it records its failure and returns its
260+
text, raising nothing.
261+
262+
**Outstanding gap: the terminal policy for exhaustion.** Reaching `max`
263+
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
268+
verdict — return the failing plan, fail the stage, or return to the user — is an
269+
unresolved product decision recorded against
250270
[issue #290](https://github.com/taras/executable.md/issues/290), whose
251271
acceptance pins the behavior. This synchronization slice does not choose it.
252272

0 commit comments

Comments
 (0)