Composable .ad scripts: recorded fragments reusable across flows (design spike)

[thymikee]

Motivation — measured, not hypothetical

The E3 repair-economics matrix (36 trials, 2 models × 2 prompts × 3 drift types) established that when a recorded flow drifts, re-recording is usually cheaper than agent repair (label drift: re-record $1.21 vs repair median $2.34; cascade: $1.55 vs $2.05; repair wins only on single diverged reads via the corrective-read path, $0.69). Re-record cost scales with flow length — so the unit of re-recording is the lever. If 30 flows share a recorded login path and login drifts, today that is 30 re-records; with composable fragments it is one.

This is the direct continuation of the replay thesis: cheap regeneration is the repair path, and composition shrinks the regeneration unit.

Current state

• .ad scripts are closed units: context + open … close, no include/import mechanism.
• The only composition in the system is Maestro-side runFlow, handled by the typed engine — with a documented bug class: ADR-0012 records an included file expanding into the linear plan, shifting every subsequent step index and corrupting divergence attribution + the include's own line table. ADR-0015 (migration item 6) moves includes into the interpreter.
• Useful internals already half-exist: recording knows how to slice a session at a boundary (saveScriptBoundary), and replay --from N --plan-digest provides mid-script addressing.

Design constraints (load-bearing — from the Maestro scars + the identity model)

1. Fragments don't own lifecycle. No open/close inside a fragment; the composing flow owns session, context line, and launch state. Otherwise reuse implies hidden relaunches.
2. Recorded entry guards. A fragment recorded from screen X is only valid at screen X. Fragment capture should auto-record an entry assertion (a wait/identity anchor for the starting screen) as the fragment's first step — without it, composition reintroduces the silent-wrong-screen class that target-v1 annotations exist to prevent.
3. Stable addressing across expansion. Divergence already carries step.source.path:line; attribution must stay per-fragment (fragment digest + local step index), never a flattened global index, or resume tokens (--from + --plan-digest) and divergence reports become ambiguous exactly as in the ADR-0012 incident.
4. One composition model. Native .ad composition and the Maestro interpreter's includes should share semantics; do not grow two parallel schemes.

Open questions for the spike

• Recording UX: how does a user capture a fragment (explicit start/stop markers in-session vs post-hoc slicing of a saved session)?
• Composed plan digest: derivation from fragment digests (content-addressed) so a fragment edit invalidates exactly the compositions that use it?
• Evidence staleness: shared fragments age independently of their callers — does a composition pin fragment versions, and what does drift in a shared fragment report as?
• Annotation compatibility: fragments must keep the reserved-comment property (old runners ignore what they don't know).

Suggested outcome

An ADR (spike, not implementation) settling the fragment model, addressing scheme, and recording UX — then implementation can be scoped.

[thymikee]

Triage complete: this is sufficiently constrained for an ADR/design-spike agent. The measurable repair-economics motivation, non-lifecycle fragment rule, entry guard, fragment-local provenance, digest invalidation, and recording-UX questions define a useful bounded outcome.

One architecture guardrail for the ADR: “one composition model” should mean shared identity, provenance, digest, lifecycle, and failure-reporting semantics. It must not move Maestro runFlow includes out of the source-preserving typed interpreter required by ADR 0015, and it must not flatten native fragment steps into a global index—the failure mode recorded in ADR 0012. If shared machinery emerges, it should sit below both interpreters as a small composition/provenance model rather than becoming a second replay engine.

Marking ready-for-agent for the ADR spike only; implementation should follow as separately scoped work after the ADR is accepted.