Skip to content

Commit e8895dd

Browse files
committed
📝 Reconcile the living target with the settled workflow contracts
The target described a `<Workflow>`/`<Sandbox>`/`<Stage>` spine over a sidecar Git ledger at `refs/xmd/runs`, an implicit worktree, an implementor that edits files, and a `<PullRequest>` handle carrying reviews, comments and checks. None of that is the architecture any more, and three of those constructs were rejected rather than deferred. The command selects the environment: `xmd workflow start` creates the run and its one retained Workspace, and the root document is the workflow. Named `<Repository>` and `<Worktree>` compose the checkouts from ordinary root props, so nothing resolves through a hidden alias and no single worktree is implied. Agents are read-only under that host ceiling, so the implementor returns constrained XMD that `<Expand>` admits and expands as ordinary durable effects, and `<Git.Add>`, `<Git.Commit>`, an explicit `<Git.Push>` and `<PullRequest>` follow in that order. Waiting for the user is a durable suspension that `resume` continues, which is what `<Stage>` was reaching for. Retention is no longer speculative. #291 and #365 are shipped foundation: the run retains its filtered journal, Workspace roots, and metadata, and one expansion publishes its mutation, logical root and journal result in one transaction. `JournalProvenance` (#425) is what makes that history evidence rather than storage, and it is named where the documents discuss retained evidence. Every remaining capability is marked as target behavior against #218's dependency order. Two gaps are now stated rather than assumed away. #295 moved reviews, comments and checks out of the creation result, and no issue owns the forge read that returns them to a network-denied reviewer; and the journal records which run and expansion produced a decision but not which person answered. Props are namespaced throughout (#305), `<Content />` projects at any depth (#328), and the obsolete asymmetry notes are gone.
1 parent 2b2f0a8 commit e8895dd

11 files changed

Lines changed: 1597 additions & 1047 deletions

‎specs/adversarial-implementation-workflow.md‎

Lines changed: 328 additions & 190 deletions
Large diffs are not rendered by default.

‎specs/markdown-agents-vision.md‎

Lines changed: 32 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -186,35 +186,45 @@ feedback, decisions, branches, and pull requests do not belong to whichever
186186
agent happened to create them. The document captures or resolves those assets
187187
deterministically and passes required content into agent prompts explicitly.
188188

189-
`<File>` and `<Glob>` already perform such operations. `<Workflow>` (#289),
190-
`<Worktree>` (#293), and `<PullRequest>` (#295) describe the rest and are not
191-
built. Together they cover the work that should not depend on model judgment:
192-
193-
- record artifact versions of handoffs, plans, reviews, and decisions;
194-
- create or resolve a named workspace, branch, file, or pull request only when
195-
that environmental asset is needed;
189+
`<File>` and `<Glob>` already perform such operations. The command supplies the
190+
rest: `xmd workflow start` creates a workflow run with one retained Workspace
191+
(#366), and named `<Repository>` and `<Worktree>` composition (#293),
192+
deterministic local Git effects (#294), explicit `<Git.Push>` (#370),
193+
`<PullRequest>` (#295), and `<Issue>` (#296) describe the effects inside it. None
194+
of them is built. Together they cover the work that should not depend on model
195+
judgment:
196+
197+
- retain each handoff, plan, review, and decision as a filtered journal event
198+
bound to the Workspace root current when it was written;
199+
- create or resolve a named repository, worktree, branch, file, or pull request
200+
only when that environmental asset is needed;
196201
- establish the working directory inherited by child operations;
197-
- read and write exact artifact content;
202+
- read and write exact content through the contextual filesystem boundary;
198203
- return paths, commit identities, pull-request numbers, and URLs as workflow
199204
data;
200-
- reconcile existing state when an execution resumes; and
205+
- reconcile existing external state when an execution resumes; and
201206
- record the inputs, observed state, effects, and outputs of each operation.
202207

203-
Agent calls analyze evidence and propose changes. Deterministic components apply
204-
approved environmental changes and provide exact required content to the next
205-
call. Generated files are optional exports rather than the handoff protocol.
206-
This removes manual copying between agent-owned transcripts, plan files, and
207-
working directories.
208-
209-
That run state is scoped to the operation that owns it: created inside the run
210-
it describes, provided contextually, and torn down with it. Nothing accumulates
211-
runs in a module-scoped registry, so concurrent runs cannot observe each other.
208+
Agent calls analyze evidence and propose changes; they do not perform them. Under
209+
a workflow run an Agent is read-only, and a proposal reaches the Workspace as
210+
generated XMD that a constrained evaluator preflights and expands as ordinary
211+
durable effects (#302, #369). Deterministic components apply approved
212+
environmental changes and provide exact required content to the next call.
213+
Generated files are optional exports rather than the handoff protocol. This
214+
removes manual copying between agent-owned transcripts, plan files, and working
215+
directories.
216+
217+
Live run state is scoped to the operation that owns it: created inside the
218+
operation it describes, provided contextually, and torn down with it. Nothing
219+
accumulates runs in a module-scoped registry, so concurrent runs cannot observe
220+
each other. What outlives the process is retained deliberately, in the run's own
221+
store, addressed by a public run ID.
212222

213223
Resources clean up with their enclosing execution by default. Agent sessions,
214-
processes, streams, and other ongoing effects always stop. An execution may
215-
explicitly retain a workspace for inspection. A failed or cancelled execution
216-
also retains a workspace when cleanup would discard uncommitted or unpushed
217-
changes, and reports the path, branch, and reason that recovery is required.
224+
processes, streams, and other ongoing effects always stop. Cleanup releases live
225+
attachments without deleting run-owned state: every run status is retained until
226+
an explicit deletion, so a failed or cancelled execution keeps its checkouts and
227+
its journal, and reports the path, branch, and reason that recovery is required.
218228
Durable published results such as commits, issues, and pull requests remain
219229
addressable after scoped resources close.
220230

‎workflows/adversarial-implementation/Discovery.md‎

Lines changed: 20 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
---
2-
required: [instructions, planner, request]
2+
required: [instructions, planner, request, worktree]
33

44
props:
55
instructions: { type: string }
66
planner: { type: string }
77
request: { type: string }
8+
worktree: { type: string }
89
---
910

1011
# Discovery
@@ -15,8 +16,10 @@ issue may enter directly at implementor planning.
1516

1617
## Target shape
1718

18-
<Agent name={planner}>
19+
<Agent name={props.planner}>
1920
<Session name="planner">
21+
<Agent.AddDir path={props.worktree} />
22+
2023
<Prompt as="handoff" throwOnError>
2124
Repository instructions:
2225

@@ -47,20 +50,27 @@ issue may enter directly at implementor planning.
4750
- Decisions that remain with the user
4851

4952
The component declares no `returns`, so its `<Output>` region is its return
50-
value and a caller's `as` binds that rendered text. `<Agent name={planner}>`
53+
value and a caller's `as` binds that rendered text. `<Agent name={props.planner}>`
5154
selects the agent from a validated prop rather than a literal: the agent
5255
components take their props from a literal or from an expression that resolves
53-
to a string. An expression prop reads the bare binding, while the prompt body
54-
above interpolates `{props.instructions}` — the two spellings that #305 will
55-
unify. Its caller supplies the request as the `request` prop and decides whether
56-
and where to persist the result. It would read better as projected content, but
57-
`<Content />` does not substitute inside a `<Prompt>` (#328), so a prop carries
58-
it. The handoff is a theory for investigation, not an
56+
to a string, and props are namespaced in expression props and text alike (#305).
57+
Its caller supplies the request as the `request` prop and decides whether and
58+
where to persist the result. The handoff is a theory for investigation, not an
5959
implementation plan that the implementor follows unquestioningly.
6060

61+
`<Agent.AddDir>` is what gives the planner read access to the checkout, and it
62+
is the only thing that does. Lexical cwd — established here by the enclosing
63+
`<Worktree>` — governs where XMD's own file operations resolve; it registers
64+
nothing with an Agent. The two are separate operations
65+
([#302](https://github.com/taras/executable.md/issues/302), unbuilt), and the
66+
planner's access is read-only either way: the workflow host enforces that
67+
ceiling and no prop in this document can raise it. Registration belongs to the
68+
enclosing Agent session, which is why it sits inside `<Session>`; the exact
69+
placement rule is #302's to settle.
70+
6171
The prompt sits outside `<Output>`, so it runs under the `throw` error mode:
6272
`throwOnError` turns a failed prompt into a failure the mode then ends the
6373
stage on. Without it a failed prompt records its failure and returns its text,
6474
and the stage would hand its caller an empty handoff.
6575

66-
This component runs today.
76+
Everything here except `<Agent.AddDir>` runs today.

0 commit comments

Comments
 (0)