Document adversarial implementation workflow WIP

specs/markdown-agents-vision.md

@@ -178,6 +178,80 @@ 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. `<Workflow>` (#289),
+`<Worktree>` (#293), and `<PullRequest>` (#295) describe the rest and are not
+built. Together they cover the work that should not depend on model judgment:
+
+- record artifact versions of handoffs, plans, reviews, and decisions;
+- create or resolve a named workspace, branch, file, or pull request only when
+  that environmental asset is needed;
+- establish the working directory inherited by child operations;
+- read and write exact artifact content;
+- return paths, commit identities, pull-request numbers, and URLs as workflow
+  data;
+- reconcile existing state when an execution resumes; and
+- record the inputs, observed state, effects, and outputs of each operation.
+
+Agent calls analyze evidence and propose changes. 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.
+
+That run state is scoped to the operation that owns it: created inside the run
+it describes, provided contextually, and torn down with it. Nothing accumulates
+runs in a module-scoped registry, so concurrent runs cannot observe each other.
+
+Resources clean up with their enclosing execution by default. Agent sessions,
+processes, streams, and other ongoing effects always stop. An execution may
+explicitly retain a workspace for inspection. A failed or cancelled execution
+also retains a workspace when cleanup would discard uncommitted or unpushed
+changes, 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 +296,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,66 @@
+---
+required: [instructions, planner, request]
+
+props:
+  instructions: { type: string }
+  planner: { type: string }
+  request: { 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={planner}>
+  <Session name="planner">
+    <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={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. An expression prop reads the bare binding, while the prompt body
+above interpolates `{props.instructions}` — the two spellings that #305 will
+unify. Its caller supplies the request as the `request` prop and decides whether
+and where to persist the result. It would read better as projected content, but
+`<Content />` does not substitute inside a `<Prompt>` (#328), so a prop carries
+it. The handoff is a theory for investigation, not an
+implementation plan that the implementor follows unquestioningly.
+
+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.
+
+This component runs today.