Skip to content

Commit d22fe96

Browse files
committed
📝 Settle what an exhausted planning loop asks for, and start proving it
#290 settled the exhaustion behavior these documents still called an unresolved product decision. Exhausting the bounded attempts is neither convergence nor ordinary successful completion: it starts no implementation and no later durable effect, and it asks the user for direction rather than answering on the stage's own account. A composed workflow turns that request into a durable suspension, which is #367's and unbuilt. No return schema changes. The pair a stage already returns — `decision.proceed` true with `verdictPassed` false — is what makes exhaustion distinct, and nothing else produces it, so the rule against returning a second copy of a derivable answer still holds. What changes is that the report asks instead of stopping: the two exhaustion branches now await direction, while a decline still stops. The proof #290 asks for begins beside the stages it exercises. `Agent.AddDir` is #302's and does not exist, so a no-op stub sits in the test directory alone — repository resolution is scope-local, so every name the inventory calls unresolved still resolves to nothing from the workflow directory, which the component probe confirms. One of the seven acceptance criteria is proven so far: the exact instruction paths and contents reach the planner prompt, constrained literally in the scenario so a dropped or summarized instruction fails rather than matching.
1 parent df5040e commit d22fe96

9 files changed

Lines changed: 115 additions & 25 deletions

File tree

‎specs/adversarial-implementation-workflow.md‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -60,9 +60,14 @@ approval *and* a passing review — so a stage cannot approve its own advancemen
6060
A stage returns those two sources and nothing derived from them: a precomputed
6161
flag would be a second copy of the same answer that no schema could hold to
6262
agreement with its sources. The same pair distinguishes a decline from a review
63-
that reached its bound still failing, and neither advances; what the workflow
64-
should ultimately do with an exhausted loop is an unresolved product decision
65-
under #290, and refusing to advance is not an answer to it.
63+
that reached its bound still failing, and neither advances. That pair is also
64+
what makes exhaustion a distinct outcome without a separate label, which is what
65+
#290 settled: an exhausted loop is neither convergence nor ordinary successful
66+
completion, it starts no implementation and no later durable effect, and it asks
67+
the user for direction rather than answering on the stage's own account. A
68+
composed workflow turns that request into a durable suspension (#367, unbuilt),
69+
and resume never reads exhaustion, silence, or an unchanged verdict as
70+
approval.
6671

6772
`proceed: true` authorizes the exact transition and effects the checkpoint
6873
assessed, and nothing more. The rule binds the material as much as the decision:
@@ -941,10 +946,6 @@ The exercise must resolve enough of these to implement one vertical slice:
941946
producing a host path at all (#227)?
942947
7. Which durable signals may schedule a resumption, and how is one arbitrated
943948
against an iteration's own completion and direct user input (#300)?
944-
8. What does a planning loop that reaches `max` without a passing verdict do —
945-
return the failing plan, fail the stage, or return to the user (#290)? An
946-
exhausted loop is not a failure and produces no diagnostic, so the answer is
947-
the document's policy to state, and it is not stated yet.
948949
9. What records who answered an elicitation? The journal retains the validated
949950
decision and its question fingerprint but no actor identity, so a decision is
950951
attributable to a run and an expansion but not to a person. No issue owns it.

‎workflows/adversarial-implementation/Implementation.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -531,8 +531,10 @@ stage is reached at all only because `start.md` gated it on
531531

532532
After the loop, `decision.proceed` true with `verdictPassed` false is what
533533
exhaustion looks like: the user kept approving and the verdict never passed. The
534-
caller's gate rejects that pair, so an exhausted review cannot reach acceptance.
535-
What the workflow should ultimately do about it stays unresolved under #290.
534+
caller's gate rejects that pair, so an exhausted review cannot reach acceptance
535+
and starts no later durable effect. As in `Planning`, exhaustion is a request
536+
for user direction rather than a terminal answer of the stage's own (#290,
537+
settled); a composed workflow suspends there for it (#367, unbuilt).
536538

537539
## Approval precedes durable effects
538540

‎workflows/adversarial-implementation/Planning.md‎

Lines changed: 18 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -289,16 +289,24 @@ returning something half-formed for a caller to branch on. `throwOnError` on eac
289289
`<Prompt>` is required for the same reason: a failed prompt without it records
290290
its failure and returns its text, raising nothing.
291291

292-
**Outstanding gap: the terminal policy for exhaustion.** Reaching `max`
293-
completes the loop normally — exhaustion is not a failure and produces no
294-
diagnostic. The returned pair identifies it (`decision.proceed` true,
295-
`verdictPassed` false) and the caller's gate refuses it, so an exhausted loop
296-
cannot advance. That is the minimum needed to keep the workflow safe; it is not
297-
the policy. What the workflow *should* do when five rounds end without a passing
298-
verdict — return the failing plan, fail the stage, or return to the user — is an
299-
unresolved product decision recorded against
300-
[issue #290](https://github.com/taras/executable.md/issues/290), whose
301-
acceptance pins the behavior. This synchronization slice does not choose it.
292+
**Exhaustion asks for direction.** Reaching `max` completes the loop normally —
293+
exhaustion is not a failure and produces no diagnostic — and it is neither
294+
convergence nor ordinary successful completion
295+
([#290](https://github.com/taras/executable.md/issues/290), settled). The
296+
returned pair is what makes it a distinct outcome: `decision.proceed` true with
297+
`verdictPassed` false is exhaustion, and nothing else produces that pair. The
298+
caller's gate refuses it, so an exhausted loop starts no implementation and no
299+
later durable effect, and cannot be reported as convergence or success.
300+
301+
What the caller does with it is ask the user. An exhausted planning loop returns
302+
to its caller for direction rather than terminating on its own account: five
303+
rounds of evidence did not converge, and only the user decides what happens
304+
next. Under a composed workflow that request becomes a durable suspension — the
305+
run records why it stopped and the material the user needs, releases its
306+
executor, and resumes only from explicit user direction, so neither exhaustion
307+
nor silence nor an unchanged verdict is ever read as approval. That lifecycle is
308+
#367's and is unbuilt; what this document owns is the boundary, and the boundary
309+
holds without it.
302310

303311
Every `plan`, `verdict`, and `planCheckpoint` is already durable: each `<Prompt>`
304312
is one durable operation, each `<Elicit>` answer is journaled against its

‎workflows/adversarial-implementation/start.md‎

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -135,10 +135,11 @@ specification](../../specs/executable-mdx-spec.md) is the authority for both.
135135
</If>
136136
<Else>
137137
<If condition={implementation.decision.proceed}>
138-
# Stopped: the pull-request review never passed
138+
# Awaiting direction: the pull-request review never passed
139139

140140
The user kept approving and the verdict never passed, so the
141-
change was never offered for acceptance.
141+
change was never offered for acceptance. This is not a rejection
142+
and not an acceptance: the workflow is asking what to do next.
142143

143144
{implementation.review}
144145

@@ -163,10 +164,11 @@ specification](../../specs/executable-mdx-spec.md) is the authority for both.
163164
</If>
164165
<Else>
165166
<If condition={planning.decision.proceed}>
166-
# Stopped: the plan review never passed
167+
# Awaiting direction: the plan review never passed
167168

168169
The user kept approving and the verdict never passed, so
169-
authorization was never requested.
170+
authorization was never requested. This is not a rejection and not
171+
an approval: the workflow is asking what to do next.
170172

171173
{planning.review}
172174

@@ -284,8 +286,14 @@ authoritative pair, read where it is used.
284286
The same pair distinguishes the failure modes without a separate label. After a
285287
loop, `decision.proceed` false means the user declined; `decision.proceed` true
286288
with `verdictPassed` false means the loop reached `max` still failing. Neither
287-
passes the gate. What an exhausted loop *should* do remains an unresolved
288-
product decision under #290 — refusing to advance is not an answer to it.
289+
passes the gate, so neither starts implementation or any later durable effect.
290+
291+
Those two are reported differently, because they are different requests. A
292+
decline is finished: the user said no. Exhaustion is not — it is the workflow
293+
asking the user what to do after five rounds failed to converge (#290, settled).
294+
Under a composed workflow that request is where the run suspends durably for
295+
user direction (#367, unbuilt); here it is where the report asks, and neither
296+
exhaustion nor an unchanged verdict is ever read as approval.
289297

290298
A checkpoint that found no material choice still produces an explicit
291299
`proceed: true` with its reason, so nothing advances because a decision was
Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
required: [path]
3+
4+
props:
5+
path: { type: string }
6+
---
7+
8+
<Output></Output>
Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
<WhenPrompt
2+
as="discovery"
3+
template="{?before}## `workflows/adversarial-implementation/tests/fixtures/AGENTS.md`{?gap}Root instructions: prefer evidence over assertion.{?middle}## `workflows/adversarial-implementation/tests/fixtures/nested/AGENTS.md`{?gap2}Nested instructions: never edit a test to make it pass.{?rest}Add a health endpoint{?tail}"
4+
/>
5+
6+
HANDOFF
7+
8+
Purpose: add a health endpoint.
9+
10+
User decisions: the route is `/health`.
11+
12+
Hypotheses the implementor must test: the router already exposes a mount point.
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Root instructions: prefer evidence over assertion.
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Nested instructions: never edit a test to make it pass.
Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Planning document logic
2+
3+
The stages in this directory are the shipped-syntax part of the workflow, and
4+
this document is the proof that they execute
5+
([#290](https://github.com/taras/executable.md/issues/290)). It uses stub Agents
6+
and document-supplied answers in one process and one working directory. Nothing
7+
here needs WorkflowRun persistence, a Repository or Worktree, Git, a forge, or a
8+
Worker Shell.
9+
10+
One thing has to be supplied for `Discovery` and `Planning` to run at all:
11+
`<Agent.AddDir>` is #302's and does not exist. `Agent/AddDir.md` beside this
12+
document is a no-op stub, and it resolves only for documents in *this*
13+
directory — registration and repository resolution are both scope-local, so the
14+
name still resolves to nothing everywhere the workflow's own inventory says it
15+
does.
16+
17+
## Instruction files reach the prompt exactly
18+
19+
`InstructionFiles` renders the exact path and content of every file it is
20+
given, and `Discovery` interpolates that rendering into its prompt. The scenario
21+
constrains the literal instruction text, so a prompt that dropped or summarized
22+
it fails rather than matching.
23+
24+
<Test name="exact instruction paths and contents reach the planner prompt">
25+
26+
<InstructionFiles
27+
paths={["workflows/adversarial-implementation/tests/fixtures/AGENTS.md", "workflows/adversarial-implementation/tests/fixtures/nested/AGENTS.md"]}
28+
as="instructions"
29+
/>
30+
31+
<AssertStringIncludes actual={instructions} expected="tests/fixtures/AGENTS.md" />
32+
<AssertStringIncludes actual={instructions} expected="Root instructions: prefer evidence over assertion." />
33+
<AssertStringIncludes actual={instructions} expected="tests/fixtures/nested/AGENTS.md" />
34+
<AssertStringIncludes actual={instructions} expected="Nested instructions: never edit a test to make it pass." />
35+
36+
<TestAgent>
37+
<TestAgent.Scenario agent="test" session="planner" src="./agents/discovery.md" />
38+
39+
<Discovery
40+
instructions={instructions}
41+
planner="test"
42+
request="Add a health endpoint"
43+
worktree="."
44+
as="handoff"
45+
/>
46+
</TestAgent>
47+
48+
<AssertStringIncludes actual={handoff} expected="HANDOFF" />
49+
</Test>

0 commit comments

Comments
 (0)