feat(compose): sequence separately recorded Flow bundles

README.md

@@ -179,11 +179,29 @@ mode stays on one origin. macOS and Linux bind one exact app and window, while a
 governed Windows run binds its application identity.
 
 If a task crosses a browser and a native app, or otherwise changes backend,
-record and qualify one bundle per surface and orchestrate those bundles outside
-Flow. Qualify each handoff and the end-to-end result verifier before deployment.
-The CLI doesn't compose separately recorded bundles today. Program authors can
-bind individual steps to different HTTP systems, but that is API actuation
-rather than recorded GUI backend switching.
+record one bundle per surface. `openadapt-flow compose` sequences the compiled
+bundles:
+
+```bash
+openadapt-flow compose \
+  --child intake=./intake-bundle \
+  --child posting=./posting-bundle \
+  --handoff intake.patient_id=posting.patient_id \
+  --out composed
+openadapt-flow certify composed --policy clinical-write
+openadapt-flow run composed --config deploy.yaml
+```
+
+Child A must end `VERIFIED` (or a halt class you named with `--allow-halt`)
+before child B starts. Handoffs copy parameter values that A's confirmed
+effect contract already bound. The parent will not guess a window title or a
+URL. Missing evidence stops the run. Qualify each handoff and the end-to-end
+result verifier before deployment.
+
+Compose will not retarget one recording onto a second backend. Program authors
+can bind individual steps to different HTTP systems, but that is API actuation
+rather than recorded GUI backend switching. If you installed the OpenAdapt
+launcher, `openadapt flow compose` is the same command.
 
 ## How a step finds its target
 
@@ -269,7 +287,7 @@ agents at [openadapt.ai/compare](https://openadapt.ai/compare).
 
 ## What runs where
 
-Record, compile, lint, certify, replay, and run are local. By default, a healthy
+Record, compile, compose, lint, certify, replay, and run are local. By default, a healthy
 replay makes no generative-model API call. Grounding, identity, and state
 verification integrations can make calls when enabled. This is not the same as
 no network: the app you're driving, a remote backend, and any effect verifier
@@ -321,8 +339,9 @@ generated [docs/VERIFICATION.md](docs/VERIFICATION.md). For security review,
 [docs/ENTERPRISE_ARCHITECTURE.md](docs/ENTERPRISE_ARCHITECTURE.md).
 
 There is more here than this page covers: workflow programs with states, loops
-and guarded transitions; data-driven `for-each` over a worklist; multi-trace
-induction that quarantines an underdetermined intent instead of guessing;
+and guarded transitions; data-driven `for-each` over a worklist; composing
+separately recorded bundles; multi-trace induction that quarantines an
+underdetermined intent instead of guessing;
 pluggable SQL, REST, FHIR and document-hash effect oracles; durable
 checkpoint and resume; Agent Skill and MCP emission. Those are in
 [docs/CAPABILITIES.md](docs/CAPABILITIES.md), and the whole documentation set

claims.yaml

@@ -951,3 +951,42 @@ claims:
         public demo that other users mutate and that resets daily; the sample
         is small (10 agent runs). Only the verifier + task-prompt units run in
         CI. `reproducibility: field` forbids ever labeling this `supported`.
+
+  # -------------------------------- compose separately recorded bundles
+  - id: compose-recorded-bundles
+    claim: >-
+      openadapt-flow compose sequences named, already-compiled child bundles
+      under a handoff contract. Each child stays bound to its recorded
+      surface. The parent starts a child only after a predecessor ends
+      VERIFIED (or an explicit allowed halt class). Handoffs copy
+      effect-bound parameter values from confirmed effect receipts; missing
+      evidence HALTs. certify and run execute the parent artifact.
+    surfaces: [README.md, docs]
+    tier: supported
+    evidence:
+      - path: tests/test_compose_authoring.py
+        proves: >-
+          Authoring copies two child bundles, records the handoff contract,
+          and refuses a source that is not effect-bound, an unknown target
+          parameter, a single child, a cyclic after-graph, and a backwards
+          handoff.
+      - path: tests/test_compose_runtime.py
+        node: test_two_child_fixture_second_is_local_backend
+        proves: >-
+          A two-child fixture runs intake through MockMed with independent
+          effect verification, then a local FakeBackend child that receives
+          the verified patient_id. Missing handoff evidence and an
+          unverified predecessor HALT before the next child starts.
+      - path: tests/test_cli_compose.py
+        proves: >-
+          The compose parser dispatches, the CLI writes a composition
+          artifact, and replay refuses to run one.
+    caveats:
+      - >-
+        The parent sequences admitted child runs. It does not enlarge the
+        workflow-program graph and does not introduce a process contract.
+        It does not switch backends inside one recording.
+      - >-
+        Evidence is unit tests plus a local mock second child. This claim
+        does not cover Production admission or a live Citrix session.
+

docs/CAPABILITIES.md

@@ -21,6 +21,14 @@ at replaying one. These capabilities layer onto the same $0, model-free runtime.
   authoring time rather than emitting a bad bundle. This turns a replay of
   one recorded path into governed execution over a queue:
   `openadapt-flow for-each bundle --records worklist.csv --out queue-bundle`.
+- **Compose separately recorded bundles.** `compose` takes named compiled
+  child bundles and a handoff contract and writes a parent artifact that
+  `certify` and `run` execute. Each child keeps the surface it was recorded
+  on. The parent runs children in `--child` order, or an explicit `--after`
+  DAG, and starts a child only after every predecessor ends `VERIFIED` (or an
+  `--allow-halt` class you named). Handoffs copy effect-bound parameter
+  values from the predecessor's confirmed effect receipt. Missing evidence
+  HALTs. The launcher form is `openadapt flow compose`.
 - **See what a demonstration compiled into.** `visualize` renders a
   program-graph view of a bundle before it runs: the ordered steps, the
   resolution ladder each step will try, where an identity gate is armed,

docs/LIMITS.md

@@ -30,12 +30,21 @@ For the current evidence behind each capability claim, see
 | Citrix / VDI pixel-window automation | **Required CI plus counted no-DOM stand-in** | The dedicated exact-Workspace-window backend, readiness gate, governed run, and durable resume passed 3 healthy effect-confirmed no-DOM trials plus 3 drift safe-halts. | The retained record explicitly has `ica_hdx_accepted=false`; live ICA/HDX acceptance stays bound to the exact deployment instead of being inferred from a stand-in or RDP. |
 | Managed browser execution | **Separate product target and workflow admissions** | The hosted lane admits attested browser bundles; production mode requires a configured real runner and refuses silent mock fallback. | It does not extend the supported claim to Windows, RDP, Citrix, PHI-bearing shared-cloud execution, an SLA, or a regulated certification. |
 | On-premises / customer-managed deployment | **Release and clean-machine evidence; site acceptance required** | Deployment configuration, local run gates, egress checks, and audit primitives are supplied. | OpenAdapt does not configure the customer's firewall, KMS, storage, identity provider, backups, retention, incident response, or legal compliance program. |
+| Compose separately recorded bundles | **Required CI** | `openadapt-flow compose` writes a parent sequencer from named compiled children plus a handoff contract. Unit tests cover authoring validation, fail-closed missing-handoff HALT, and a two-child fixture whose second child is a local mock backend. | It does not merge two recordings into one backend, retarget a bundle onto a surface it was not recorded on, or introduce a process contract. Live Citrix, Production admission, and cross-application field campaigns are not claimed here. |
 
 These evidence entries do not assign a product lifecycle state or accept risk.
 An actively admitted release can still produce an unsafe workflow if the
 demonstration, inferred checks, policy, or deployment configuration is
 inadequate.
 
+## Composing separately recorded bundles
+
+`compose` sequences already-compiled children through the governed `run`
+path. A child starts only after every predecessor ends `VERIFIED`, or a halt
+class named with `--allow-halt`. A handoff copies an effect-bound parameter
+from a confirmed receipt. Missing evidence HALTs. Subflows and worklists
+stay inside each child, on that child's surface.
+
 ## What "deterministic" means
 
 The compiled program fixes the action sequence, parameters, target evidence,

docs/SURFACES.md

@@ -39,6 +39,12 @@ unqualified `replay bundle` selects the bound surface rather than the browser.
 Bundles compiled before surface binding carry no `surface` and behave exactly
 as before.
 
+A composition does not merge surfaces. `openadapt-flow compose` copies each
+child bundle into a parent artifact; `run` executes those children one at a
+time against the surface sealed into that child. There is no backend switch
+inside a recording, and no parent-level `--backend` that retargets every
+child.
+
 ## Execution boundary and evidence, per surface
 
 Every substrate runs on the same small `Backend` protocol and the same governed

docs/VERIFICATION.md

@@ -12,7 +12,7 @@
 
 ## What is bound to required CI vs. being validated
 
-- **Bound to required CI pass evidence (11):** `web-supported`, `deterministic-zero-model-replay`, `effect-verification-silent-writes`, `identity-gate-halt-armed`, `identifier-crop-compile-emission`, `halt-teach-promote`, `typed-business-decisions-supported`, `reviewed-judgment-cases-supported`, `qualified-remote-decision-v2-supported`, `mockmed-benchmark-ci-reproducible`, `substrate-runtime-validation-supported`
+- **Bound to required CI pass evidence (12):** `web-supported`, `deterministic-zero-model-replay`, `effect-verification-silent-writes`, `identity-gate-halt-armed`, `identifier-crop-compile-emission`, `halt-teach-promote`, `typed-business-decisions-supported`, `reviewed-judgment-cases-supported`, `qualified-remote-decision-v2-supported`, `mockmed-benchmark-ci-reproducible`, `substrate-runtime-validation-supported`, `compose-recorded-bundles`
 - **Being validated — opt-in / infra-gated or field (8):** `effect-verifier-kit`, `windows-desktop-validating`, `macos-native-validating`, `linux-native-validating`, `rdp-validating`, `desktop-recording-validating`, `citrix-pixel-validating`, `openemr-field-benchmark`
 - **Roadmap / research (1):** `win32-window-replay-roadmap`
 
@@ -405,3 +405,21 @@
 
 - The historical result uses OCR evidence from a visible saved message row. It does not use an out-of-band OpenEMR system-of-record read.
 - FIELD TEST, NOT CI-reproducible: the head-to-head ran against a SHARED public demo that other users mutate and that resets daily; the sample is small (10 agent runs). Only the verifier + task-prompt units run in CI. `reproducibility: field` forbids ever labeling this `supported`.
+
+### `compose-recorded-bundles` — supported — bound to required CI pass evidence
+
+> openadapt-flow compose sequences named, already-compiled child bundles under a handoff contract. Each child stays bound to its recorded surface. The parent starts a child only after a predecessor ends VERIFIED (or an explicit allowed halt class). Handoffs copy effect-bound parameter values from confirmed effect receipts; missing evidence HALTs. certify and run execute the parent artifact.
+
+- Surfaces: README.md, docs
+- Strongest evidence strength: **supported** (tier is `supported`)
+
+| Backing evidence | Kind | Gating / CI stage | Strength | Proves |
+|---|---|---|---|---|
+| `tests/test_compose_authoring.py` | test | ci (required PR gate (test)) | supported | Authoring copies two child bundles, records the handoff contract, and refuses a source that is not effect-bound, an unknown target parameter, a single child, a cyclic after-graph, and a backwards handoff. |
+| `tests/test_compose_runtime.py` | test | ci (required PR gate (test)) | supported | A two-child fixture runs intake through MockMed with independent effect verification, then a local FakeBackend child that receives the verified patient_id. Missing handoff evidence and an unverified predecessor HALT before the next child starts. |
+| `tests/test_cli_compose.py` | test | ci (required PR gate (test)) | supported | The compose parser dispatches, the CLI writes a composition artifact, and replay refuses to run one. |
+
+**Caveats (honest limits):**
+
+- The parent sequences admitted child runs. It does not enlarge the workflow-program graph and does not introduce a process contract. It does not switch backends inside one recording.
+- Evidence is unit tests plus a local mock second child. This claim does not cover Production admission or a live Citrix session.

docs/design/WORKFLOW_PROGRAM_IR.md

@@ -758,3 +758,11 @@ These are additive to the document and the tests. They do not change the IR.
   Do", "Your Wish is My Command"): resolving demonstration ambiguity by asking
   concrete questions.
 </content>
+
+## Composition of separately recorded bundles
+
+Subflows reuse a subgraph inside one workflow, on one surface. Two recordings
+need `openadapt-flow compose`, which sequences already-compiled child bundles
+without enlarging this IR: no new `StateKind`, no process contract. Handoffs
+are effect-bound parameter facts. See `openadapt_flow/composition.py`.
+

docs/verification.json

@@ -1454,6 +1454,60 @@
         }
       ],
       "errors": []
+    },
+    {
+      "id": "compose-recorded-bundles",
+      "claim": "openadapt-flow compose sequences named, already-compiled child bundles under a handoff contract. Each child stays bound to its recorded surface. The parent starts a child only after a predecessor ends VERIFIED (or an explicit allowed halt class). Handoffs copy effect-bound parameter values from confirmed effect receipts; missing evidence HALTs. certify and run execute the parent artifact.",
+      "tier": "supported",
+      "reproducibility": null,
+      "surfaces": [
+        "README.md",
+        "docs"
+      ],
+      "strongest_evidence": "supported",
+      "caveats": [
+        "The parent sequences admitted child runs. It does not enlarge the workflow-program graph and does not introduce a process contract. It does not switch backends inside one recording.",
+        "Evidence is unit tests plus a local mock second child. This claim does not cover Production admission or a live Citrix session."
+      ],
+      "evidence": [
+        {
+          "path": "tests/test_compose_authoring.py",
+          "kind": "test",
+          "exists": true,
+          "strength": "supported",
+          "gating": "ci (required PR gate (test))",
+          "node": null,
+          "node_found": null,
+          "ci_job": "test",
+          "junit_status": null,
+          "proves": "Authoring copies two child bundles, records the handoff contract, and refuses a source that is not effect-bound, an unknown target parameter, a single child, a cyclic after-graph, and a backwards handoff."
+        },
+        {
+          "path": "tests/test_compose_runtime.py",
+          "kind": "test",
+          "exists": true,
+          "strength": "supported",
+          "gating": "ci (required PR gate (test))",
+          "node": "test_two_child_fixture_second_is_local_backend",
+          "node_found": true,
+          "ci_job": "test",
+          "junit_status": null,
+          "proves": "A two-child fixture runs intake through MockMed with independent effect verification, then a local FakeBackend child that receives the verified patient_id. Missing handoff evidence and an unverified predecessor HALT before the next child starts."
+        },
+        {
+          "path": "tests/test_cli_compose.py",
+          "kind": "test",
+          "exists": true,
+          "strength": "supported",
+          "gating": "ci (required PR gate (test))",
+          "node": null,
+          "node_found": null,
+          "ci_job": "test",
+          "junit_status": null,
+          "proves": "The compose parser dispatches, the CLI writes a composition artifact, and replay refuses to run one."
+        }
+      ],
+      "errors": []
     }
   ]
 }