Skip to content

Commit 981e50c

Browse files
committed
🎫 Bind with <Let>, and file a deferred finding where it belongs
Four merged capabilities change what this target may say, and two of them change what it writes. `<Capture>` left the reserved set with no alias (#528), so every structural invocation here is `<Let>` — nine of them across five documents, plus the prose that named the removed directive. The pull-request loop's seed stops being JavaScript: `<Let as="pullRequest" value={{}} />` binds the empty object directly, which is the shipped form for exactly this. It does not close #301's gap and the documents say so — `<Let value>` binds a value, and does not make an ordinary component prop whose expression evaluates to `undefined` become omitted, so the seeded `number={pullRequest.number}` still waits on the omission nothing has built. The deferred-issue markup was invalid against the shipped contract (#516). It passed `pullRequest` and `finding` props that do not exist on a component whose schema is closed. It now writes what #516 actually offers: an `<IssueTracker url={props.tracker}>` naming the container, a paired `<Issue title={finding.title} as="deferredIssue">` whose body is the description, and a result read as exactly `{ url }`. The body carries what a reader needs to know why the finding was deferred — the finding, its evidence, the pull request it came from, and the review and checkpoint that classified it. `tracker` is a new required root prop threaded to the stage; it selects a target and grants nothing, because the ceiling lives beside the host's credentials. That moves `<Issue>` out of the unresolved inventory and leaves one name in it. `<Expand>` is the only component here that resolves to nothing, and the stage still cannot reach the forge — which is unreachable, not unbuilt. Authentication and crash inspection are recorded where the documents already discuss the effects they belong to. Credentials are live host input acquired per invocation and are not a prop, a retained value, a journal field or anything an Agent sees (#532). A crashed run is inspected from a private recovered copy, leaving the authoritative source byte-identical (#521).
1 parent 7257683 commit 981e50c

9 files changed

Lines changed: 207 additions & 103 deletions

File tree

‎specs/adversarial-implementation-workflow.md‎

Lines changed: 29 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -503,8 +503,24 @@ explicit composition rather than one implicit workspace:
503503
upstream change and no implicit stage or commit. `<PullRequest>` requires that
504504
Push's own matching successful evidence rather than performing a hidden push
505505
(#295, shipped).
506-
- `<Issue>` reconciles an approved deferred finding (#296), over the shared
507-
external reconciliation of #297.
506+
- `<IssueTracker>` names the tracker or project new issues belong in, and a
507+
paired `<Issue title=… as=…>` files an approved deferred finding with its
508+
description as the element body, binding `{ url }` (#296, shipped by #516).
509+
The authored tracker URL selects a target and grants no authority: the host
510+
installs an adapter-private ceiling beside its credentials, and a target
511+
outside it fails before any provider observes anything. `IssueApi` is its own
512+
boundary rather than a Git one.
513+
514+
Authentication for all of them is ambient host input, acquired per provider
515+
invocation (#532, shipped): HTTP Git uses the invoking user's credential-helper
516+
chain for the exact locator, SSH uses the selected ambient agent and known-host
517+
policy, and GitHub API calls read `GH_TOKEN`, then `GITHUB_TOKEN`, then
518+
`gh auth token --hostname github.com`. It is never a public credential prop, a
519+
workflow secret schema, a copied credential, a retained value, Workspace
520+
material, a command argument, a URL, a journal field, output, or a diagnostic
521+
cause. Replay acquires no credentials; an interrupted effect reacquires current
522+
host authentication and reconciles through its provider contract. Agents receive
523+
neither credentials nor direct network authority.
508524

509525
Each environmental operation declares its inputs and preconditions, reconciles
510526
existing state, returns a structured result, and records its observed effects. A
@@ -626,6 +642,16 @@ History reads already-filtered retained protocol events, so it exposes no value
626642
the security policy has not already seen, and the authored source position it
627643
reports is descriptive evidence about an event rather than identity.
628644

645+
Inspection survives a crashed host (#521, shipped). The ordinary reading is of
646+
the retained snapshot. The single condition it cannot get past is SQLite's exact
647+
`SQLITE_READONLY_ROLLBACK`, a hot rollback journal a lost host left behind; that
648+
falls through to recovery, which copies the database and journal under recovery
649+
coordination and lets SQLite roll the journal back into the private copy. The
650+
authoritative crashed source is left byte-identical for the write-capable owner
651+
whose job recovery actually is. Recovery coordination grants no executor or
652+
lifecycle authority and opens no Workspace or provider effects, and `list`
653+
remains complete-or-error.
654+
629655
The authority underneath is shipped as #367's second slice (#466). The executor
630656
lock owns every lifecycle transition, so single-executor ownership, atomic begin
631657
and settle, cancellation and deletion are built. Cancellation never reaches into
@@ -949,7 +975,7 @@ shipped behavior. They are recorded because the answers constrain what remains.
949975
9. **How does a document read a prop?** Under the `props` namespace, in
950976
expression props and in text alike: `agent={props.planner}` and
951977
`{props.instructions}`. Declaring a prop creates no bare binding
952-
(#305, shipped). Authored bindings — from `as`, `<Capture>`, `<Each>`, `<Loop>`, `<Return>` —
978+
(#305, shipped). Authored bindings — from `as`, `<Let>`, `<Each>`, `<Loop>`, `<Return>` —
953979
stay bare.
954980
10. **Where may a component body project its caller's content?** Anywhere it
955981
writes `<Content />`, including nested inside another invocation such as a

‎specs/markdown-agents-vision.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -198,9 +198,9 @@ one retained Workspace and `xmd workflow resume` continues it from the retained
198198
journal (#366, shipped). The composition inside that run is there too: named
199199
`<Repository>`, `<Worktree>` and lexical `<Dir>` are registered by the workflow
200200
host (#293, shipped). The durable effects are there too: deterministic
201-
local Git effects (#294), explicit `<Git.Push>` (#495), and `<PullRequest>`
202-
(#295) are all registered by the workflow host. `<Issue>` (#296) is the one that
203-
is still not built. Together they cover the work that should not depend on model
201+
local Git effects (#294), explicit `<Git.Push>` (#495), `<PullRequest>` (#295)
202+
and the `<IssueTracker>`/`<Issue>` pair (#296) are all registered by the
203+
workflow host. Together they cover the work that should not depend on model
204204
judgment:
205205

206206
- retain each handoff, plan, review, and decision as a filtered journal event

‎workflows/adversarial-implementation/Implementation.md‎

Lines changed: 74 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
required: [plan, authorization, instructions, planner, implementor]
2+
required: [plan, authorization, instructions, planner, implementor, tracker]
33

44
props:
55
plan: { type: string }
@@ -14,6 +14,7 @@ props:
1414
instructions: { type: string }
1515
planner: { type: string }
1616
implementor: { type: string }
17+
tracker: { type: string }
1718

1819
returns:
1920
report: { type: string }
@@ -71,7 +72,7 @@ That is the whole shape of the stage: **agents inspect; XMD mutates.**
7172

7273
## Target shape
7374

74-
<Capture as="proposalSchema" select="code[lang=json]">
75+
<Let as="proposalSchema" select="code[lang=json]">
7576
```json
7677
{
7778
"$schema": "http://json-schema.org/draft-07/schema#",
@@ -86,9 +87,9 @@ That is the whole shape of the stage: **agents inspect; XMD mutates.**
8687
"additionalProperties": false
8788
}
8889
```
89-
</Capture>
90+
</Let>
9091

91-
<Capture as="pullRequestVerdictSchema" select="code[lang=json]">
92+
<Let as="pullRequestVerdictSchema" select="code[lang=json]">
9293
```json
9394
{
9495
"$schema": "http://json-schema.org/draft-07/schema#",
@@ -127,11 +128,9 @@ That is the whole shape of the stage: **agents inspect; XMD mutates.**
127128
"additionalProperties": false
128129
}
129130
```
130-
</Capture>
131+
</Let>
131132

132-
```ts eval
133-
let pullRequest = {};
134-
```
133+
<Let as="pullRequest" value={{}} />
135134

136135
<Agent name={props.implementor}>
137136
<Session name="implementor">
@@ -304,7 +303,7 @@ let pullRequest = {};
304303
</Session>
305304
</Agent>
306305

307-
<Capture as="checkpointMaterial">
306+
<Let as="checkpointMaterial">
308307
## Authorized plan
309308

310309
{props.plan}
@@ -349,7 +348,7 @@ let pullRequest = {};
349348
- {item}
350349
</Each>
351350
</Each>
352-
</Capture>
351+
</Let>
353352
<UserCheckpoint
354353
purpose="resolve the pull-request review"
355354
agent={props.planner}
@@ -359,10 +358,28 @@ let pullRequest = {};
359358
<If condition={reviewCheckpoint.proceed}>
360359
<Each in={verdict.findings} let="finding">
361360
<If condition={finding.disposition === "defer"}>
362-
<Issue
363-
pullRequest={pullRequest}
364-
finding={finding}
365-
/>
361+
<IssueTracker url={props.tracker}>
362+
<Issue title={finding.title} as="deferredIssue">
363+
{finding.description}
364+
365+
Evidence:
366+
367+
<Each in={finding.evidence} let="item">
368+
- {item}
369+
</Each>
370+
371+
Deferred from pull request #{pullRequest.number}
372+
({pullRequest.url}), reviewing {pullRequest.headSha} onto
373+
{pullRequest.baseSha}.
374+
375+
The reviewing planner classified this finding as `defer` rather
376+
than as a revision, and the user approved that disposition:
377+
378+
{reviewCheckpoint.assessment}
379+
User response: {reviewCheckpoint.response}
380+
Rationale: {reviewCheckpoint.rationale}
381+
</Issue>
382+
</IssueTracker>
366383
</If>
367384
</Each>
368385
<If condition={verdict.passed}>
@@ -494,22 +511,26 @@ A revision iteration commits again, so the head it asks about is not the head
494511
the existing pull request holds — which is why an unnumbered second request
495512
would be a **conflict** rather than an update: it asked for one to exist, not
496513
for whatever is there to become this. The loop therefore says which one it
497-
means. `let pullRequest = {}` seeds the binding once, before the loop; on the
498-
first iteration `pullRequest.number` is `undefined`, so `number` is omitted and
499-
the unnumbered create-or-adopt contract applies; the successful result replaces
500-
the seed through ordinary `as` binding, and every later iteration passes the
514+
means. `<Let as="pullRequest" value={{}} />` seeds the binding once, before the
515+
loop — a direct value rather than rendered content (#528, shipped). On the first
516+
iteration `pullRequest.number` is `undefined`, so `number` is omitted and the
517+
unnumbered create-or-adopt contract applies; the successful result replaces the
518+
seed through ordinary `as` binding, and every later iteration passes the
501519
retained positive number and selects the numbered update contract for that exact
502520
pull request. `<Loop>` opens no binding scope, which is what lets one iteration
503521
read what the previous one bound.
504522

505-
The engine contract underneath it is **#301's, and not built yet**: an
506-
expression prop evaluating to `undefined` is omitted before prop validation and
507-
before the durable JSON boundary, so the component never receives `undefined`
508-
and no journal or replay stores it. A required prop that evaluates to
509-
`undefined` still fails validation as missing, `null` stays an explicit value
510-
passed only where a schema accepts it, and an unbound name still fails. Today
511-
the engine refuses such a prop instead of omitting it, so this is the one part
512-
of the loop that does not run yet.
523+
The seed is shipped; the omission it relies on is not. `<Let value>` binds the
524+
empty object and nothing more — it does not make an ordinary component prop
525+
whose expression evaluates to `undefined` become omitted. That is the engine
526+
contract **#301's amendment settles and nothing has built yet**: such a prop is
527+
omitted before prop validation and before the durable JSON boundary, so the
528+
component never receives `undefined` and no journal or replay stores it. A
529+
required prop that evaluates to `undefined` still fails validation as missing,
530+
`null` stays an explicit value passed only where a schema accepts it, and an
531+
unbound name still fails. Today the engine refuses such a prop instead of
532+
omitting it, so the seeded `number={pullRequest.number}` is still the one part
533+
of this loop that does not run.
513534

514535
## The reviewer sees what it judges
515536

@@ -590,8 +611,16 @@ settled); a composed workflow suspends there for it (#367, shipped).
590611

591612
## Approval precedes durable effects
592613

593-
Deferred `<Issue>` creation sits **inside** the approved branch, after the
594-
checkpoint. The planner proposes a disposition; the user's approval is what
614+
Deferred issue creation sits **inside** the approved branch, after the
615+
checkpoint. `<IssueTracker url={props.tracker}>` names the container the issues
616+
belong in and `<Issue title={finding.title} as="deferredIssue">` renders the
617+
description as its body, binding `{ url }` and nothing else. The authored
618+
tracker URL selects a target; it grants no authority. The workflow host installs
619+
an adapter-private ceiling beside its credentials, and a target outside that
620+
ceiling fails before any provider observes anything — so a document can write
621+
any URL here and reach nothing the host had not already allowed. `IssueApi` is
622+
its own boundary: a tracker is not a Repository, and no Git effect is involved
623+
in filing one. The planner proposes a disposition; the user's approval is what
595624
turns that proposal into a durable forge object. Creating the issues first
596625
would make the planner's classification take effect before anyone approved it,
597626
and an issue is not undone by a later decline.
@@ -605,8 +634,8 @@ approval sets in motion, unchanged and unsummarized:
605634
description of it;
606635
- the **revision prompt** that goes to the implementor when the verdict has not
607636
passed — the literal `verdict.revisionPrompt`; and
608-
- each finding's **evidence**, because `<Issue>` receives the complete finding
609-
and a `defer` disposition turns it into a durable forge object.
637+
- each finding's **evidence**, because a `defer` disposition renders that
638+
finding into a durable forge object and the issue body carries it.
610639

611640
Approving instructions or evidence the user never read would be the same
612641
authority leak as not asking at all. It is not an invitation to amend them
@@ -628,28 +657,30 @@ revision turn, or acceptance.
628657
| Written above | Supplied by | Status |
629658
| --- | --- | --- |
630659
| `<Expand>` | #369 | unbuilt; public name open. The evaluator under it is shipped (#497), for observation only |
631-
| `<Issue>` | #296 | unbuilt |
660+
| `<IssueTracker>`, `<Issue>` | #296, delivered by #516 | shipped — registered by the workflow host |
632661
| `<Git.Push>` | delivered by #495 | shipped — registered by the workflow host |
633662
| `<PullRequest>` | #295, delivered by #500 and #504 | shipped — registered by the workflow host |
634663
| omitting an expression prop that evaluates to `undefined` | #301 | unbuilt — the loop's `number={pullRequest.number}` depends on it |
635664
| `<Git.Add>`, staged-only `<Git.Commit>` | #294 | shipped |
636665
| shared Git-host reconciliation behind push, pull request and issue | #297 | shipped — the surface, and now the push and pull-request components over it |
637666
| the forge read that returns reviews, comments and checks | `<Fetch>` (#456) | shipped — this stage does not write it yet |
638667

639-
The agent, parsing, capture, and control-flow syntax runs today, and so do the
640-
Git effects: `<Git.Add>`, `<Git.Commit>`, `<Git.Push>` and `<PullRequest>` are
641-
all built and registered by the workflow host.
668+
The agent, parsing, binding, and control-flow syntax runs today, and so do the
669+
forge effects: `<Git.Add>`, `<Git.Commit>`, `<Git.Push>`, `<PullRequest>`,
670+
`<IssueTracker>` and `<Issue>` are all built and registered by the workflow
671+
host.
642672

643673
The loop body above still does not expand, and it is worth separating the two
644-
reasons. **Two names resolve to nothing** — `<Expand>` (#369) and `<Issue>`
645-
(#296) — and one **engine capability is unbuilt**: omitting an expression prop
646-
that evaluates to `undefined` (#301), which the seeded `number={pullRequest.number}`
647-
needs on its first pass. Neither of those is a statement about `<Git.Push>` or
648-
`<PullRequest>`: those are shipped, and this stage still cannot reach them,
649-
because the `<Expand>` that would produce the change to stage and commit comes
650-
first. A shipped component behind an unbuilt prerequisite is unreachable here,
651-
not unbuilt. Until the prerequisites land, the effects this stage stands for
652-
remain explicit user-run steps between manual stages.
674+
reasons. **One name resolves to nothing** — `<Expand>` (#369) — and one **engine
675+
capability is unbuilt**: omitting an expression prop that evaluates to
676+
`undefined` (#301), which the seeded `number={pullRequest.number}` needs on its
677+
first pass. Neither is a statement about the forge components. Those are
678+
shipped, and this stage still cannot reach them, because the `<Expand>` that
679+
would produce the change to stage and commit comes first. A shipped component
680+
behind an unbuilt prerequisite is unreachable here, not unbuilt — and the
681+
deferred-issue path is the furthest one back, since it also waits on the review
682+
that only a real change produces. Until the prerequisites land, the effects this
683+
stage stands for remain explicit user-run steps between manual stages.
653684

654685
Props are namespaced throughout (#305). `proposal`, `commit`, `pullRequest`,
655686
`verdict`, `checkpointMaterial`, and `reviewCheckpoint` are authored bindings and

‎workflows/adversarial-implementation/Planning.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ is render the evidence each agent needs into its prompt.
5252

5353
## Target shape
5454

55-
<Capture as="verdictSchema" select="code[lang=json]">
55+
<Let as="verdictSchema" select="code[lang=json]">
5656
```json
5757
{
5858
"$schema": "http://json-schema.org/draft-07/schema#",
@@ -66,7 +66,7 @@ is render the evidence each agent needs into its prompt.
6666
"additionalProperties": false
6767
}
6868
```
69-
</Capture>
69+
</Let>
7070

7171
<Agent name={props.implementor}>
7272
<Session name="implementor">
@@ -165,7 +165,7 @@ is render the evidence each agent needs into its prompt.
165165
</Session>
166166
</Agent>
167167

168-
<Capture as="checkpointMaterial">
168+
<Let as="checkpointMaterial">
169169
## Implementation plan
170170

171171
{plan}
@@ -179,7 +179,7 @@ is render the evidence each agent needs into its prompt.
179179
Revision prompt:
180180

181181
{verdict.revisionPrompt}
182-
</Capture>
182+
</Let>
183183
<UserCheckpoint
184184
purpose="resolve the plan review"
185185
agent={props.planner}

‎workflows/adversarial-implementation/UserCheckpoint.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ value — `assessment`, `recommendation`, `question`, `options`, `response`, and
3535

3636
## Target shape
3737

38-
<Capture as="assessmentSchema" select="code[lang=json]">
38+
<Let as="assessmentSchema" select="code[lang=json]">
3939

4040
```json
4141
{
@@ -62,9 +62,9 @@ value — `assessment`, `recommendation`, `question`, `options`, `response`, and
6262
}
6363
```
6464

65-
</Capture>
65+
</Let>
6666

67-
<Capture as="decisionSchema" select="code[lang=json]">
67+
<Let as="decisionSchema" select="code[lang=json]">
6868
```json
6969
{
7070
"$schema": "http://json-schema.org/draft-07/schema#",
@@ -81,7 +81,7 @@ value — `assessment`, `recommendation`, `question`, `options`, `response`, and
8181
"additionalProperties": false
8282
}
8383
```
84-
</Capture>
84+
</Let>
8585

8686
<Agent name={props.agent}>
8787
<Session name="user-checkpoint">

‎workflows/adversarial-implementation/artifacts.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,23 @@ descriptive evidence about an event, never identity — nothing is located by
136136
reconstructing a position from an expansion ID, the current definition, or the
137137
Workspace.
138138

139+
**A crashed run is inspectable, from a private copy** (#521, shipped). Ordinary
140+
inspection reads the retained snapshot and costs nothing extra. Only one
141+
condition falls through to recovery: SQLite's exact
142+
`SQLITE_READONLY_ROLLBACK` — a hot rollback journal a lost host left behind,
143+
which a read-only connection may not put back. The extended code is the whole
144+
signal, because the primary readonly conditions describe a database nobody may
145+
write for other reasons and answering those with recovery would be guessing.
146+
147+
The retained database and its journal are copied under recovery coordination,
148+
and SQLite rolls the journal back into the *copy*. The authoritative crashed
149+
source stays byte-identical, exactly as its lost host left it, still waiting for
150+
the write-capable owner whose job recovery actually is. Coordination is held for
151+
the copy and released before the copy is recovered; it grants no executor or
152+
lifecycle authority and opens no Workspace or provider effects. `list` stays
153+
complete-or-error: it reports every run or it fails, never a partial listing
154+
that silently omits the crashed one.
155+
139156
`history --forkable` adds a forkability column and a blockers column, and
140157
removes nothing — so a caller that does not ask for them reads the same history
141158
it always did. Selecting an event to fork from is shipped (#368, delivered by

0 commit comments

Comments
 (0)