Document adversarial implementation workflow WIP

specs/markdown-agents-vision.md

@@ -178,6 +178,90 @@ Structured distillation is preferred when later control flow depends on the
 result. Free-form summaries are useful context, but they are not substitutes for
 validated workflow state.
 
+## Workflow-owned development artifacts
+
+A development workflow owns its material environment and logical run state.
+Worktrees, working directories, captured handoffs, implementation plans,
+feedback, decisions, branches, and pull requests do not belong to whichever
+agent happened to create them. The document captures or resolves those assets
+deterministically and passes required content into agent prompts explicitly.
+
+`<File>` and `<Glob>` already perform such operations. The command supplies the
+rest: `xmd workflow start` creates a workflow run with one retained Workspace
+(#366), and named `<Repository>` and `<Worktree>` composition (#293),
+deterministic local Git effects (#294), explicit `<Git.Push>` (#370),
+`<PullRequest>` (#295), and `<Issue>` (#296) describe the effects inside it. None
+of them is built. Together they cover the work that should not depend on model
+judgment:
+
+- retain each handoff, plan, review, and decision as a filtered journal event
+  bound to the Workspace root current when it was written;
+- create or resolve a named repository, worktree, branch, file, or pull request
+  only when that environmental asset is needed;
+- establish the working directory inherited by child operations;
+- read and write exact content through the contextual filesystem boundary;
+- return paths, commit identities, pull-request numbers, and URLs as workflow
+  data;
+- reconcile existing external state when an execution resumes; and
+- record the inputs, observed state, effects, and outputs of each operation.
+
+Agent calls analyze evidence and propose changes; they do not perform them. Under
+a workflow run an Agent is read-only, and a proposal reaches the Workspace as
+generated XMD that a constrained evaluator preflights and expands as ordinary
+durable effects (#302, #369). Deterministic components apply approved
+environmental changes and provide exact required content to the next call.
+Generated files are optional exports rather than the handoff protocol. This
+removes manual copying between agent-owned transcripts, plan files, and working
+directories.
+
+Live run state is scoped to the operation that owns it: created inside the
+operation it describes, provided contextually, and torn down with it. Nothing
+accumulates runs in a module-scoped registry, so concurrent runs cannot observe
+each other. What outlives the process is retained deliberately, in the run's own
+store, addressed by a public run ID.
+
+Resources clean up with their enclosing execution by default. Agent sessions,
+processes, streams, and other ongoing effects always stop. Cleanup releases live
+attachments without deleting run-owned state: every run status is retained until
+an explicit deletion, so a failed or cancelled execution keeps its checkouts and
+its journal, and reports the path, branch, and reason that recovery is required.
+Durable published results such as commits, issues, and pull requests remain
+addressable after scoped resources close.
+
+## Living workflows with `xmd play`
+
+`xmd run` executes a fixed document. `xmd play` treats the document as a living
+collaborative workspace:
+
+```sh
+xmd play workflow.md
+```
+
+The executable document, rather than a hidden conversation, is the shared source
+of workflow intent and progress. Agents propose visible document changes or new
+executions. The runtime validates proposals, enforces policy, and performs
+deterministic effects. The user approves material changes and remains the final
+authority for product behavior, scope, architecture, risk, and lasting
+constraints.
+
+An accepted proposal becomes an inspectable document revision. Rejected
+proposals, failed executions, reviewer rejections, and later successful attempts
+retain their provenance so the engineering history explains how the workflow
+changed. Hidden session history may help an agent reason, but it is never the
+only source of consequential workflow state.
+
+Named agent sessions remain scope-owned while Play is active. Each invocation
+receives explicit workflow context and references to workflow-owned artifacts.
+The document and execution record identify what each agent received, what it
+proposed, what the runtime applied, and which user decision authorized a
+material transition.
+
+Play rests on the same deterministic asset and agent orchestration needed by an
+automated implementation loop. The loop is the proving ground for worktree,
+file, pull-request, review, decision, cleanup, and recovery semantics. Play adds
+collaborative document evolution after those operations are reliable; it does
+not replace them with agent-managed shell work.
+
 ## Foundation and agent layer
 
 Executable.md separates two concerns:
@@ -222,6 +306,10 @@ its declared props:
 6. What happens when it fails or returns invalid output?
 7. Why did the workflow take a branch or stop?
 8. What evidence in the execution record supports those answers?
+9. Which environmental assets did the workflow create or resolve, and who owns
+   their cleanup or retention?
+10. In Play, what document change was proposed, what effects were validated, and
+    which user decision accepted it?
 
 If those answers depend on hidden host behavior, implicit transcript sharing, or
 an agent's own account of what it did, the design does not satisfy the product

workflows/adversarial-implementation/Discovery.md

@@ -0,0 +1,76 @@
+---
+required: [instructions, planner, request, worktree]
+
+props:
+  instructions: { type: string }
+  planner: { type: string }
+  request: { type: string }
+  worktree: { type: string }
+---
+
+# Discovery
+
+The workflow enters through design discovery or a bounded deferred issue.
+Discovery includes a user-planner interview. A sufficiently specified deferred
+issue may enter directly at implementor planning.
+
+## Target shape
+
+<Agent name={props.planner}>
+  <Session name="planner">
+    <Agent.AddDir path={props.worktree} />
+
+    <Prompt as="handoff" throwOnError>
+      Repository instructions:
+
+      {props.instructions}
+
+      User request:
+
+      {props.request}
+
+      Produce a user-validated design handoff and a falsifiable implementation
+      theory. Distinguish user decisions from hypotheses the implementor must
+      test.
+    </Prompt>
+  </Session>
+</Agent>
+
+<Output>{handoff}</Output>
+
+## Handoff contents
+
+- Purpose and observable behavior
+- User decisions, constraints, non-goals, and accepted risks
+- Repository and architectural context
+- Falsifiable implementation theory
+- Assumptions to confirm or refute
+- Required evidence and validation
+- Likely pull-request topology
+- Decisions that remain with the user
+
+The component declares no `returns`, so its `<Output>` region is its return
+value and a caller's `as` binds that rendered text. `<Agent name={props.planner}>`
+selects the agent from a validated prop rather than a literal: the agent
+components take their props from a literal or from an expression that resolves
+to a string, and props are namespaced in expression props and text alike (#305).
+Its caller supplies the request as the `request` prop and decides whether and
+where to persist the result. The handoff is a theory for investigation, not an
+implementation plan that the implementor follows unquestioningly.
+
+`<Agent.AddDir>` is what gives the planner read access to the checkout, and it
+is the only thing that does. Lexical cwd — established here by the enclosing
+`<Worktree>` — governs where XMD's own file operations resolve; it registers
+nothing with an Agent. The two are separate operations
+([#302](https://github.com/taras/executable.md/issues/302), unbuilt), and the
+planner's access is read-only either way: the workflow host enforces that
+ceiling and no prop in this document can raise it. Registration belongs to the
+enclosing Agent session, which is why it sits inside `<Session>`; the exact
+placement rule is #302's to settle.
+
+The prompt sits outside `<Output>`, so it runs under the `throw` error mode:
+`throwOnError` turns a failed prompt into a failure the mode then ends the
+stage on. Without it a failed prompt records its failure and returns its text,
+and the stage would hand its caller an empty handoff.
+
+Everything here except `<Agent.AddDir>` runs today.