agent-scenario-loop 0.1.0

package/templates/integration-readme.md

@@ -0,0 +1,125 @@
+# Agent Scenario Loop Integration
+
+This folder was generated by `asl-init` for the `{{SCENARIO_ID}}` scenario.
+
+## Files
+
+- `asl.config.json`: app identifiers, artifact roots, and runner defaults
+- `scenarios/mobile/{{SCENARIO_ID}}.json`: first durable mobile scenario
+- `runner-manifests/primary-runner.json`: primary runner capability manifest
+- `runner-manifests/evidence-provider.json`: optional evidence-provider manifest
+- `scripts/asl-capture-accessibility-provider.mjs`: runnable starter accessibility provider command
+- `scripts/asl-capture-profiler-provider.mjs`: runnable starter profiler, memory, and network provider command
+- `src/devtools/profile-session.ts`: React Native app-side truth-event helper
+- `asl/package-scripts.json`: package-script snippets to merge into your app `package.json`
+- `asl/gitignore-snippet`: artifact ignore rules to merge into your app `.gitignore`
+
+`asl.config.json` declares the supported fixture, adb, simctl, agent-device, and Argent lanes that the generated scripts expose. Keep that list aligned with the scripts your project intends agents to run; `asl-validate-project` reports invalid required config as errors and omitted optional package drivers as warnings.
+
+For iOS apps with multiple installed variants on the same simulator, add sibling bundle ids to `app.iosConflictingBundleIds`. ASL treats those as a preflight guard: if a declared sibling variant is installed beside the target bundle, iOS live proof fails before launch so deep-link and profile-session evidence cannot come from the wrong app.
+
+## App Wiring
+
+1. Install the peer app dependencies used by `src/devtools/profile-session.ts` if your app does not already have them:
+
+```bash
+pnpm add @react-native-async-storage/async-storage expo-linking
+```
+
+2. Mount `useProfileSessionBootstrap()` once near the app root.
+3. Emit app-owned truth events with `emitProfileEvent()` at scenario milestones.
+4. Register command targets with `registerProfileCommandTargetHandler()` when a runner should activate app behavior directly.
+5. Append `asl/gitignore-snippet` to your app `.gitignore`; commit scenarios, runner manifests, and app truth-event wiring. Keep `paths.artifactRoot`, `paths.iosArtifactsRoot`, and `paths.androidArtifactsRoot` under ignored project-local artifact paths so agent sandboxes and git state agree on where runtime proof evidence belongs.
+
+## First Proof Loop
+
+Start with planner validation before live device proof:
+
+```bash
+asl-validate-project --root . --platform all --out artifacts/asl/project-validation
+asl-check-plan --scenario scenarios/mobile/{{SCENARIO_ID}}.json --runner runner-manifests/primary-runner.json --provider runner-manifests/evidence-provider.json --platform ios --out artifacts/asl/plan/{{SCENARIO_ID}}-ios
+asl-check-plan --scenario scenarios/mobile/{{SCENARIO_ID}}.json --runner runner-manifests/primary-runner.json --provider runner-manifests/evidence-provider.json --platform android --out artifacts/asl/plan/{{SCENARIO_ID}}-android
+```
+
+Keep deterministic validation and live device proof as separate lanes. Planner checks and fixture profile runs should work in ordinary build or agent sandboxes. Live runs that touch adb, simctl, agent-device, Argent, emulators, simulators, physical devices, Metro, or native build tools need host/device access from the first attempt. If a live command cannot reach those host services, classify it as runner environment health before treating it as a scenario regression.
+
+Use sandboxed execution for `asl-validate-project`, `asl-check-plan`, fixture profile runs that read `--events`, and `asl-live-proof` inspection. Use host/device execution for `asl-profile-android --adb-capture`, `asl-profile-ios --simctl-capture`, `asl-live-android`, `asl-live-ios`, `asl-agent-device`, `asl-argent`, and any aggregate live script with `--agent-device-proof` or `--argent-proof`. Preserve the failed health artifact and rerun the same command with the right device access instead of changing the scenario to work around environment health.
+
+When the app emits profile events, run platform profile commands against captured evidence or a live runner:
+
+```bash
+ASL_PROFILE_IOS_EVENTS=event-logs/{{SCENARIO_ID}}-ios.log pnpm asl:profile:ios
+ASL_PROFILE_ANDROID_EVENTS=event-logs/{{SCENARIO_ID}}-android.log pnpm asl:profile:android
+ASL_PROFILE_IOS_EVENTS=event-logs/{{SCENARIO_ID}}-ios.log pnpm asl:profile:ios:provider
+ASL_PROFILE_ANDROID_EVENTS=event-logs/{{SCENARIO_ID}}-android.log pnpm asl:profile:android:provider
+asl-profile-ios --config asl.config.json --scenario scenarios/mobile/{{SCENARIO_ID}}.json --simctl-capture --profile-session --profile-session-storage --launch --comparison-lane {{SCENARIO_ID}}-ios-live --out artifacts/asl/ios --run-id {{SCENARIO_ID}}-ios-live
+asl-profile-android --config asl.config.json --scenario scenarios/mobile/{{SCENARIO_ID}}.json --adb-capture --profile-session --clear-logcat --launch --comparison-lane {{SCENARIO_ID}}-android-live --out artifacts/asl/android --run-id {{SCENARIO_ID}}-android-live
+```
+
+Those commands write `health.json`, `verdict.json`, `agent-summary.md`, `metrics.json`, `causal-run.json`, and raw evidence under the printed run directory. The `*:provider` scripts also execute the starter provider commands through `runner-manifests/evidence-provider.json`, then inventory the generated accessibility, profiler, memory, and network evidence in `manifest.artifacts.evidenceAttachments`. Compare a trusted current run with an explicit artifact path:
+
+When `--wait-ms` is omitted from profile-session live capture, ASL derives the final adb or simctl evidence window from the scenario execution steps and cycle count. Pass `--wait-ms` only when a target app needs an explicit override.
+
+```bash
+ASL_COMPARE_IOS_CURRENT=artifacts/asl/ios/{{SCENARIO_ID}}/{{SCENARIO_ID}}-ios-live pnpm asl:compare:ios
+ASL_COMPARE_ANDROID_CURRENT=artifacts/asl/android/{{SCENARIO_ID}}/{{SCENARIO_ID}}-android-live pnpm asl:compare:android
+```
+
+For aggregate live proof, use the generated live scripts:
+
+```bash
+ASL_IOS_UDID=<simulator-udid> ASL_IOS_APP_ID=<bundle-id> pnpm asl:ios:live
+ASL_ANDROID_SERIAL=<emulator-or-device-serial> ASL_ANDROID_APP_ID=<package-name> pnpm asl:android:live
+```
+
+Those scripts pass `--compare-latest --fail-on-regression`. A missing trusted baseline is recorded as skipped comparison evidence; a real regression exits nonzero after artifacts are written.
+
+For repeated local runs, put machine-specific runner values in an ignored `.asl.local.env` file at your app root instead of repeating inline environment variables. ASL CLIs load the nearest `.asl.local.env` without overriding already-exported values:
+
+```bash
+ASL_HOST_DOCTOR_REQUIRE=android,ios,agent-device,argent
+ASL_AGENT_DEVICE_REQUIRED_PLATFORMS=ios,android
+ASL_ANDROID_SERIAL=<emulator-or-device-serial>
+ASL_IOS_UDID=<simulator-udid>
+ASL_ANDROID_APP_ID=<package-name>
+ASL_IOS_APP_ID=<bundle-id>
+ASL_IOS_DEV_CLIENT_URL=<dev-client-url>
+ASL_ARGENT_BIN=pnpm
+ASL_ARGENT_BASE_ARGS="dlx @swmansion/argent run"
+```
+
+Set `ASL_IOS_DEV_CLIENT_URL` only when an iOS dev-client shell must open a specific Metro URL before profile-session evidence is collected. Keep the actual URL in ignored local env state because it depends on the local app id, host, and port.
+
+## Portable Interaction Proof
+
+Use the generated interaction scripts when an external driver should prove launch, visible UI, gestures, screenshots, or another scenario-declared driver action without changing the scenario file:
+
+```bash
+ASL_IOS_UDID=<simulator-udid> ASL_IOS_APP_ID=<bundle-id> pnpm asl:agent-device:ios
+ASL_ANDROID_SERIAL=<emulator-or-device-serial> ASL_ANDROID_APP_ID=<package-name> pnpm asl:agent-device:android
+ASL_ARGENT_BIN=/path/to/argent pnpm asl:argent:check
+ASL_ARGENT_BIN=/path/to/argent ASL_IOS_APP_ID=<bundle-id> pnpm asl:argent:ios
+ASL_ARGENT_BIN=/path/to/argent ASL_ANDROID_SERIAL=<emulator-or-device-serial> ASL_ANDROID_APP_ID=<package-name> pnpm asl:argent:android
+```
+
+If agent-device already owns the device through a named session, set `ASL_IOS_AGENT_DEVICE_SESSION` or `ASL_ANDROID_AGENT_DEVICE_SESSION` instead of relying only on the direct UDID or serial; the generated direct agent-device scripts and aggregate live sidecar scripts both honor those variables. The default session mode is `reuse`, which lets that existing session own target selection. Set `ASL_IOS_AGENT_DEVICE_SESSION_MODE=bind` or `ASL_ANDROID_AGENT_DEVICE_SESSION_MODE=bind` when ASL should name the sidecar session while still forwarding the configured UDID or serial. Run `pnpm asl:agent-device:check` and `pnpm asl:argent:check` before device-bound sidecars when you need to verify installed tool surfaces; those checks write availability artifacts under `artifacts/asl/agent-device-check` and `artifacts/asl/argent-check`. The agent-device check also records active sessions in `raw/agent-device-availability.json` and summarizes them in `agent-summary.md`, so agents can choose a compatible session without rerunning discovery manually. Prefer a real `argent` executable on PATH, or set `ASL_ARGENT_BIN=/path/to/argent` when the package manager installed it somewhere else. `ASL_ARGENT_BIN=npx` with `ASL_ARGENT_BASE_ARGS="--yes @swmansion/argent run"` is supported as a wrapper shape, but verify it with `pnpm asl:argent:check` before relying on it. Argent uses `--udid` for both iOS simulators and Android emulators; ASL resolves the iOS `booted` shorthand to the concrete simulator UDID before invoking Argent. Set `ASL_ARGENT_COMMAND_TIMEOUT_MS` when package-manager or simulator startup is slower than the default command window. Set `ASL_ARGENT_IOS_SIMCTL_SCREENSHOT_FALLBACK=1` when iOS Argent launch and accessibility proof should keep running even if Argent's screenshot backend is unhealthy and simctl can still capture the screen.
+
+If your project adds an aggregate batch runner that writes `live-proof.json`, inspect it with:
+
+```bash
+ASL_LIVE_PROOF=artifacts/asl/<platform>/_live-proof/<run-id>/live-proof.json pnpm asl:live-proof
+```
+
+After Android and iOS live proofs have both written aggregate artifacts, run the generated platform-set gate:
+
+```bash
+pnpm asl:live-proof:both
+```
+
+That script requires both platform proofs, writes `artifacts/asl/live-proof-set/live-proof-set.json` plus `agent-summary.md`, and exits nonzero when either platform is missing, failed, or regressed.
+
+Set `ASL_REQUIRE_LIVE_PROOF_ARTIFACTS=1` before this gate when the local artifact tree itself is part of the proof, not just the aggregate `live-proof.json` files.
+
+Run `pnpm asl:host:doctor` before host/device live proof when adb, CoreSimulator, agent-device, or Argent availability is uncertain. Set `ASL_HOST_DOCTOR_REQUIRE=android,ios,agent-device,argent` in `.asl.local.env` or the shell when sidecar proof availability is part of the gate.
+
+The package-script snippets in `asl/package-scripts.json` include fixture, host doctor, portable agent-device and Argent interaction proof, live profile, compare, and proof-inspection commands. Merge the snippets you use into your app `package.json` so future agents can run the loop without rediscovering command arguments.

package/templates/mobile-scenario.json

@@ -0,0 +1,133 @@
+{
+  "schemaVersion": "1.0.0",
+  "id": "first-journey",
+  "flowId": "first-journey",
+  "description": "Prove one durable mobile app journey with app-owned truth events.",
+  "journey": {
+    "name": "First journey",
+    "intent": "Run one important user journey and prove the app reached the expected state.",
+    "actor": "returning user",
+    "startState": "app ready for the journey",
+    "endState": "journey completed"
+  },
+  "platforms": ["ios", "android"],
+  "requiredCapabilities": ["launch", "sessionControl", "command", "logCapture", "artifactWrite"],
+  "optionalCapabilities": ["screenshot", "uiTree", "profiler"],
+  "truthEvents": {
+    "journeyStarted": {
+      "event": "first_journey_started",
+      "required": true,
+      "timeoutMs": 3000,
+      "phase": "intent"
+    },
+    "journeyCompleted": {
+      "event": "first_journey_completed",
+      "required": true,
+      "timeoutMs": 8000,
+      "phase": "completion"
+    }
+  },
+  "milestones": [
+    {
+      "id": "journeyStarted",
+      "event": "first_journey_started",
+      "description": "The app accepted the journey intent.",
+      "required": true,
+      "timeoutMs": 3000,
+      "phase": "intent"
+    },
+    {
+      "id": "journeyCompleted",
+      "event": "first_journey_completed",
+      "description": "The app emitted the completion truth event.",
+      "required": true,
+      "timeoutMs": 8000,
+      "phase": "completion"
+    }
+  ],
+  "expectedEvents": ["first_journey_started", "first_journey_completed"],
+  "cycles": {
+    "iterations": 3,
+    "warmupIterations": 0,
+    "stopOnFailure": true
+  },
+  "budgets": [
+    {
+      "name": "journey p95",
+      "source": "milestone",
+      "metric": "p95",
+      "unit": "ms",
+      "limit": 8000,
+      "fromMilestone": "journeyStarted",
+      "toMilestone": "journeyCompleted"
+    },
+    {
+      "name": "failures",
+      "source": "milestone",
+      "metric": "failures",
+      "unit": "count",
+      "limit": 0
+    }
+  ],
+  "steps": [
+    {
+      "id": "launch",
+      "kind": "launch"
+    },
+    {
+      "id": "start-journey",
+      "kind": "command",
+      "command": "activate-target:first-journey",
+      "driverAction": "tap",
+      "selector": {
+        "kind": "testId",
+        "value": "first-journey-start"
+      },
+      "adapterOptions": {
+        "argent": {
+          "x": 0.5,
+          "y": 0.6
+        }
+      },
+      "timeoutMs": 3000
+    },
+    {
+      "id": "wait-for-completion",
+      "kind": "waitForMilestone",
+      "milestone": "journeyCompleted",
+      "timeoutMs": 8000
+    },
+    {
+      "id": "capture-final-screen",
+      "kind": "captureEvidence",
+      "artifact": "screenshot",
+      "driverAction": "screenshot",
+      "required": false
+    }
+  ],
+  "artifacts": {
+    "required": ["logs", "signals"],
+    "optional": ["screenshot", "uiTree", "profiler"]
+  },
+  "adapterOptions": {
+    "androidAdb": {
+      "commands": [
+        {
+          "command": "activate-target:first-journey",
+          "label": "start first journey",
+          "waitMs": 300
+        }
+      ]
+    },
+    "iosSimctl": {
+      "commands": [
+        {
+          "command": "activate-target:first-journey",
+          "label": "start first journey",
+          "waitMs": 300
+        }
+      ],
+      "repeat": 3
+    }
+  }
+}

package/templates/package-scripts.json

@@ -0,0 +1,32 @@
+{
+  "asl:check:ios": "asl-check-plan --scenario scenarios/mobile/{{SCENARIO_ID}}.json --runner runner-manifests/primary-runner.json --provider runner-manifests/evidence-provider.json --platform ios --out artifacts/asl/plan/{{SCENARIO_ID}}-ios",
+  "asl:check:android": "asl-check-plan --scenario scenarios/mobile/{{SCENARIO_ID}}.json --runner runner-manifests/primary-runner.json --provider runner-manifests/evidence-provider.json --platform android --out artifacts/asl/plan/{{SCENARIO_ID}}-android",
+  "asl:validate": "asl-validate-project --root . --platform all --out artifacts/asl/project-validation",
+  "asl:host:doctor": "asl-host-doctor --out artifacts/asl/host-doctor",
+  "asl:profile:ios": "asl-profile-ios --config asl.config.json --scenario scenarios/mobile/{{SCENARIO_ID}}.json ${ASL_PROFILE_IOS_EVENTS:+--events $ASL_PROFILE_IOS_EVENTS} --comparison-lane {{SCENARIO_ID}}-ios-fixture --out artifacts/asl/ios --run-id {{SCENARIO_ID}}-ios",
+  "asl:profile:android": "asl-profile-android --config asl.config.json --scenario scenarios/mobile/{{SCENARIO_ID}}.json ${ASL_PROFILE_ANDROID_EVENTS:+--events $ASL_PROFILE_ANDROID_EVENTS} --comparison-lane {{SCENARIO_ID}}-android-fixture --out artifacts/asl/android --run-id {{SCENARIO_ID}}-android",
+  "asl:profile:ios:provider": "asl-profile-ios --config asl.config.json --scenario scenarios/mobile/{{SCENARIO_ID}}.json ${ASL_PROFILE_IOS_EVENTS:+--events $ASL_PROFILE_IOS_EVENTS} --provider runner-manifests/evidence-provider.json --comparison-lane {{SCENARIO_ID}}-ios-provider --out artifacts/asl/ios --run-id {{SCENARIO_ID}}-ios-provider",
+  "asl:profile:android:provider": "asl-profile-android --config asl.config.json --scenario scenarios/mobile/{{SCENARIO_ID}}.json ${ASL_PROFILE_ANDROID_EVENTS:+--events $ASL_PROFILE_ANDROID_EVENTS} --provider runner-manifests/evidence-provider.json --comparison-lane {{SCENARIO_ID}}-android-provider --out artifacts/asl/android --run-id {{SCENARIO_ID}}-android-provider",
+  "asl:agent-device:check": "asl-agent-device --check --out artifacts/asl/agent-device-check",
+  "asl:agent-device:ios": "asl-agent-device --platform ios ${ASL_IOS_AGENT_DEVICE_SESSION:+--session $ASL_IOS_AGENT_DEVICE_SESSION} ${ASL_IOS_AGENT_DEVICE_SESSION_MODE:+--session-mode $ASL_IOS_AGENT_DEVICE_SESSION_MODE} ${ASL_IOS_UDID:+--udid $ASL_IOS_UDID} ${ASL_AGENT_DEVICE_COMMAND_TIMEOUT_MS:+--command-timeout-ms $ASL_AGENT_DEVICE_COMMAND_TIMEOUT_MS} --scenario scenarios/mobile/{{SCENARIO_ID}}.json --app ${ASL_IOS_APP_ID:-com.example.app} --open --wait-ms 1000 --out artifacts/asl/agent-device-ios --run-id {{SCENARIO_ID}}-ios-agent-device",
+  "asl:agent-device:android": "asl-agent-device --platform android ${ASL_ANDROID_AGENT_DEVICE_SESSION:+--session $ASL_ANDROID_AGENT_DEVICE_SESSION} ${ASL_ANDROID_AGENT_DEVICE_SESSION_MODE:+--session-mode $ASL_ANDROID_AGENT_DEVICE_SESSION_MODE} ${ASL_ANDROID_SERIAL:+--serial $ASL_ANDROID_SERIAL} ${ASL_AGENT_DEVICE_COMMAND_TIMEOUT_MS:+--command-timeout-ms $ASL_AGENT_DEVICE_COMMAND_TIMEOUT_MS} --scenario scenarios/mobile/{{SCENARIO_ID}}.json --app ${ASL_ANDROID_APP_ID:-com.example.app} --open --wait-ms 1000 --out artifacts/asl/agent-device-android --run-id {{SCENARIO_ID}}-android-agent-device",
+  "asl:argent:check": "asl-argent --check --out artifacts/asl/argent-check",
+  "asl:argent:ios": "asl-argent --platform ios ${ASL_ARGENT_BIN:+--argent $ASL_ARGENT_BIN} ${ASL_ARGENT_BASE_ARGS:+--base-args \"$ASL_ARGENT_BASE_ARGS\"} ${ASL_ARGENT_DEVICE_FLAG:+--device-flag $ASL_ARGENT_DEVICE_FLAG} ${ASL_ARGENT_APP_FLAG:+--app-flag $ASL_ARGENT_APP_FLAG} ${ASL_ARGENT_COMMAND_TIMEOUT_MS:+--command-timeout-ms $ASL_ARGENT_COMMAND_TIMEOUT_MS} ${ASL_ARGENT_IOS_SIMCTL_SCREENSHOT_FALLBACK:+--ios-simctl-screenshot-fallback} ${ASL_XCRUN_PATH:+--xcrun $ASL_XCRUN_PATH} --scenario scenarios/mobile/{{SCENARIO_ID}}.json --app ${ASL_IOS_APP_ID:-com.example.app} --device ${ASL_IOS_UDID:-booted} --out artifacts/asl/argent-ios --run-id {{SCENARIO_ID}}-ios-argent",
+  "asl:argent:android": "asl-argent --platform android ${ASL_ARGENT_BIN:+--argent $ASL_ARGENT_BIN} ${ASL_ARGENT_BASE_ARGS:+--base-args \"$ASL_ARGENT_BASE_ARGS\"} ${ASL_ARGENT_DEVICE_FLAG:+--device-flag $ASL_ARGENT_DEVICE_FLAG} ${ASL_ARGENT_APP_FLAG:+--app-flag $ASL_ARGENT_APP_FLAG} ${ASL_ARGENT_COMMAND_TIMEOUT_MS:+--command-timeout-ms $ASL_ARGENT_COMMAND_TIMEOUT_MS} --scenario scenarios/mobile/{{SCENARIO_ID}}.json --app ${ASL_ANDROID_APP_ID:-com.example.app} --device ${ASL_ANDROID_SERIAL:-emulator-5554} --out artifacts/asl/argent-android --run-id {{SCENARIO_ID}}-android-argent",
+  "asl:android:live": "asl-live-android --config asl.config.json --scenario scenarios/mobile/{{SCENARIO_ID}}.json ${ASL_ANDROID_SERIAL:+--serial $ASL_ANDROID_SERIAL} ${ASL_ANDROID_APP_ID:+--package $ASL_ANDROID_APP_ID} ${ASL_ANDROID_REACT_NATIVE_DEBUG_HOST:+--react-native-debug-host $ASL_ANDROID_REACT_NATIVE_DEBUG_HOST} --out artifacts/asl/android-live --compare-latest --fail-on-regression",
+  "asl:android:live:agent-device": "asl-live-android --config asl.config.json --scenario scenarios/mobile/{{SCENARIO_ID}}.json ${ASL_ANDROID_SERIAL:+--serial $ASL_ANDROID_SERIAL} ${ASL_ANDROID_APP_ID:+--package $ASL_ANDROID_APP_ID} ${ASL_ANDROID_REACT_NATIVE_DEBUG_HOST:+--react-native-debug-host $ASL_ANDROID_REACT_NATIVE_DEBUG_HOST} ${ASL_ANDROID_AGENT_DEVICE_SESSION:+--agent-device-session $ASL_ANDROID_AGENT_DEVICE_SESSION} ${ASL_ANDROID_AGENT_DEVICE_SESSION_MODE:+--agent-device-session-mode $ASL_ANDROID_AGENT_DEVICE_SESSION_MODE} --out artifacts/asl/android-live --run-suffix agent-device --agent-device-proof --compare-latest --fail-on-regression",
+  "asl:android:live:argent": "asl-live-android --config asl.config.json --scenario scenarios/mobile/{{SCENARIO_ID}}.json ${ASL_ANDROID_SERIAL:+--serial $ASL_ANDROID_SERIAL} ${ASL_ANDROID_APP_ID:+--package $ASL_ANDROID_APP_ID} ${ASL_ANDROID_REACT_NATIVE_DEBUG_HOST:+--react-native-debug-host $ASL_ANDROID_REACT_NATIVE_DEBUG_HOST} --out artifacts/asl/android-live --run-suffix argent --argent-proof --compare-latest --fail-on-regression",
+  "asl:android:live:runners": "asl-live-android --config asl.config.json --scenario scenarios/mobile/{{SCENARIO_ID}}.json ${ASL_ANDROID_SERIAL:+--serial $ASL_ANDROID_SERIAL} ${ASL_ANDROID_APP_ID:+--package $ASL_ANDROID_APP_ID} ${ASL_ANDROID_REACT_NATIVE_DEBUG_HOST:+--react-native-debug-host $ASL_ANDROID_REACT_NATIVE_DEBUG_HOST} ${ASL_ANDROID_AGENT_DEVICE_SESSION:+--agent-device-session $ASL_ANDROID_AGENT_DEVICE_SESSION} ${ASL_ANDROID_AGENT_DEVICE_SESSION_MODE:+--agent-device-session-mode $ASL_ANDROID_AGENT_DEVICE_SESSION_MODE} --out artifacts/asl/android-live --run-suffix runners --agent-device-proof --argent-proof --compare-latest --fail-on-regression",
+  "asl:ios:live": "asl-live-ios --config asl.config.json --scenario scenarios/mobile/{{SCENARIO_ID}}.json ${ASL_IOS_UDID:+--device $ASL_IOS_UDID} ${ASL_IOS_APP_ID:+--bundle $ASL_IOS_APP_ID} --out artifacts/asl/ios-live --compare-latest --fail-on-regression",
+  "asl:ios:live:agent-device": "asl-live-ios --config asl.config.json --scenario scenarios/mobile/{{SCENARIO_ID}}.json ${ASL_IOS_UDID:+--device $ASL_IOS_UDID} ${ASL_IOS_APP_ID:+--bundle $ASL_IOS_APP_ID} ${ASL_IOS_AGENT_DEVICE_SESSION:+--agent-device-session $ASL_IOS_AGENT_DEVICE_SESSION} ${ASL_IOS_AGENT_DEVICE_SESSION_MODE:+--agent-device-session-mode $ASL_IOS_AGENT_DEVICE_SESSION_MODE} --out artifacts/asl/ios-live --run-suffix agent-device --agent-device-proof --compare-latest --fail-on-regression",
+  "asl:ios:live:argent": "asl-live-ios --config asl.config.json --scenario scenarios/mobile/{{SCENARIO_ID}}.json ${ASL_IOS_UDID:+--device $ASL_IOS_UDID} ${ASL_IOS_APP_ID:+--bundle $ASL_IOS_APP_ID} --out artifacts/asl/ios-live --run-suffix argent --argent-proof --compare-latest --fail-on-regression",
+  "asl:ios:live:runners": "asl-live-ios --config asl.config.json --scenario scenarios/mobile/{{SCENARIO_ID}}.json ${ASL_IOS_UDID:+--device $ASL_IOS_UDID} ${ASL_IOS_APP_ID:+--bundle $ASL_IOS_APP_ID} ${ASL_IOS_AGENT_DEVICE_SESSION:+--agent-device-session $ASL_IOS_AGENT_DEVICE_SESSION} ${ASL_IOS_AGENT_DEVICE_SESSION_MODE:+--agent-device-session-mode $ASL_IOS_AGENT_DEVICE_SESSION_MODE} --out artifacts/asl/ios-live --run-suffix runners --agent-device-proof --argent-proof --compare-latest --fail-on-regression",
+  "asl:profile:ios:live": "asl-profile-ios --config asl.config.json --scenario scenarios/mobile/{{SCENARIO_ID}}.json --simctl-capture --profile-session --profile-session-storage --launch --comparison-lane {{SCENARIO_ID}}-ios-live --out artifacts/asl/ios --run-id {{SCENARIO_ID}}-ios-live",
+  "asl:profile:android:live": "asl-profile-android --config asl.config.json --scenario scenarios/mobile/{{SCENARIO_ID}}.json --adb-capture --profile-session --clear-logcat --launch --comparison-lane {{SCENARIO_ID}}-android-live --out artifacts/asl/android --run-id {{SCENARIO_ID}}-android-live",
+  "asl:compare:ios": "asl-compare-latest --root artifacts/asl/ios --scenario {{SCENARIO_ID}} --current ${ASL_COMPARE_IOS_CURRENT:?set_ASL_COMPARE_IOS_CURRENT} --out artifacts/asl/ios/comparisons/{{SCENARIO_ID}} --fail-on-regression",
+  "asl:compare:android": "asl-compare-latest --root artifacts/asl/android --scenario {{SCENARIO_ID}} --current ${ASL_COMPARE_ANDROID_CURRENT:?set_ASL_COMPARE_ANDROID_CURRENT} --out artifacts/asl/android/comparisons/{{SCENARIO_ID}} --fail-on-regression",
+  "asl:live-proof:android": "asl-live-proof --file ${ASL_ANDROID_LIVE_PROOF:-artifacts/asl/android-live/_live-proof/android-live-proof/live-proof.json} --fail-on-regression",
+  "asl:live-proof:ios": "asl-live-proof --file ${ASL_IOS_LIVE_PROOF:-artifacts/asl/ios-live/_live-proof/ios-live-proof/live-proof.json} --fail-on-regression",
+  "asl:live-proof:both": "asl-live-proof --file ${ASL_ANDROID_LIVE_PROOF:-artifacts/asl/android-live/_live-proof/android-live-proof/live-proof.json} --file ${ASL_IOS_LIVE_PROOF:-artifacts/asl/ios-live/_live-proof/ios-live-proof/live-proof.json} --require-platforms android,ios --out artifacts/asl/live-proof-set --fail-on-regression ${ASL_REQUIRE_LIVE_PROOF_ARTIFACTS:+--require-artifacts}",
+  "asl:live-proof": "asl-live-proof --file ${ASL_LIVE_PROOF:?set_ASL_LIVE_PROOF} --fail-on-regression"
+}

package/templates/primary-runner.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": "1.0.0",
+  "runnerId": "example-mobile-runner",
+  "kind": "primary",
+  "platforms": ["ios", "android"],
+  "capabilities": ["launch", "sessionControl", "command", "logCapture", "artifactWrite"],
+  "driverActions": ["tap", "readLogs"],
+  "artifactOutputs": ["logs", "signals"],
+  "lifecycle": [
+    "prepare",
+    "launch",
+    "startSession",
+    "executeStep",
+    "waitForTruthEvent",
+    "captureEvidence",
+    "stopSession",
+    "finalize"
+  ]
+}

package/templates/project.config.json

@@ -0,0 +1,37 @@
+{
+  "projectName": "replace-me",
+  "app": {
+    "displayName": "Example App",
+    "scheme": "example-app",
+    "profileSessionScheme": "example-app",
+    "iosBundleId": "com.example.app",
+    "iosConflictingBundleIds": [],
+    "androidPackage": "com.example.app",
+    "ios": {
+      "xcodeScheme": "Example App",
+      "launchConfiguration": "Debug",
+      "profileConfiguration": "Release"
+    }
+  },
+  "paths": {
+    "artifactRoot": "artifacts/asl",
+    "iosArtifactsRoot": "artifacts/asl/ios",
+    "androidArtifactsRoot": "artifacts/asl/android",
+    "scenarioRoot": "scenarios/mobile"
+  },
+  "drivers": {
+    "default": "fixture-log-ingest",
+    "supported": ["fixture-log-ingest", "adb", "ios-simctl", "agent-device", "argent", "xcodebuildmcp"]
+  },
+  "versionControl": {
+    "commit": [
+      "scenarios/**",
+      "runner-manifests/**",
+      "docs/**"
+    ],
+    "ignore": [
+      "artifacts/asl/**",
+      "raw simulator recordings, screenshots, and ephemeral profiler exports"
+    ]
+  }
+}

package/templates/scripts/asl-capture-accessibility-provider.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Parses simple `--key value` CLI arguments.
+ *
+ * @param {string[]} argv
+ * @returns {Record<string, string | boolean>}
+ */
+function parseArgs(argv) {
+  const args = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token?.startsWith('--')) {
+      continue;
+    }
+
+    const key = token.slice(2);
+    const value = argv[index + 1];
+    if (value && !value.startsWith('--')) {
+      args[key] = value;
+      index += 1;
+    } else {
+      args[key] = true;
+    }
+  }
+  return args;
+}
+
+/**
+ * Reads a required string CLI argument.
+ *
+ * @param {Record<string, string | boolean>} args
+ * @param {string} key
+ * @returns {string}
+ */
+function requireStringArg(args, key) {
+  const value = args[key];
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`Missing required --${key} value.`);
+  }
+  return value;
+}
+
+/**
+ * Writes a formatted JSON artifact.
+ *
+ * @param {string} outPath
+ * @param {Record<string, unknown>} payload
+ * @returns {void}
+ */
+function writeJsonArtifact(outPath, payload) {
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+}
+
+/**
+ * Writes deterministic accessibility evidence for a scaffolded provider command.
+ *
+ * @param {{outPath: string, platform: string, runId: string, scenarioId: string}} options
+ * @returns {void}
+ */
+function writeAccessibilityEvidence({
+  outPath,
+  platform,
+  runId,
+  scenarioId,
+}) {
+  writeJsonArtifact(outPath, {
+    checks: [
+      {
+        id: 'scenario-entrypoint-visible',
+        selector: {
+          kind: 'testId',
+          value: 'asl-example-title',
+        },
+        status: 'passed',
+      },
+    ],
+    platform,
+    providerId: 'example-evidence-provider',
+    runId,
+    scenarioId,
+    schemaVersion: '1.0.0',
+    summary: 'Replace this scaffold accessibility evidence with project-local axe, inspector, or driver output.',
+    violations: [],
+  });
+}
+
+/**
+ * Runs the provider script.
+ *
+ * @returns {void}
+ */
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  writeAccessibilityEvidence({
+    outPath: requireStringArg(args, 'out'),
+    platform: requireStringArg(args, 'platform'),
+    runId: requireStringArg(args, 'run-id'),
+    scenarioId: requireStringArg(args, 'scenario'),
+  });
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/templates/scripts/asl-capture-profiler-provider.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Parses simple `--key value` CLI arguments.
+ *
+ * @param {string[]} argv
+ * @returns {Record<string, string | boolean>}
+ */
+function parseArgs(argv) {
+  const args = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token?.startsWith('--')) {
+      continue;
+    }
+
+    const key = token.slice(2);
+    const value = argv[index + 1];
+    if (value && !value.startsWith('--')) {
+      args[key] = value;
+      index += 1;
+    } else {
+      args[key] = true;
+    }
+  }
+  return args;
+}
+
+/**
+ * Reads a required string CLI argument.
+ *
+ * @param {Record<string, string | boolean>} args
+ * @param {string} key
+ * @returns {string}
+ */
+function requireStringArg(args, key) {
+  const value = args[key];
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`Missing required --${key} value.`);
+  }
+  return value;
+}
+
+/**
+ * Writes a formatted JSON artifact.
+ *
+ * @param {string} outPath
+ * @param {Record<string, unknown>} payload
+ * @returns {void}
+ */
+function writeJsonArtifact(outPath, payload) {
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+}
+
+/**
+ * Writes deterministic evidence for a scaffolded provider command.
+ *
+ * @param {{memoryOutPath: string, networkOutPath: string, outPath: string, platform: string, runId: string, scenarioId: string}} options
+ * @returns {void}
+ */
+function writeProviderEvidence({
+  memoryOutPath,
+  networkOutPath,
+  outPath,
+  platform,
+  runId,
+  scenarioId,
+}) {
+  const shared = {
+    platform,
+    providerId: 'example-evidence-provider',
+    runId,
+    scenarioId,
+    schemaVersion: '1.0.0',
+  };
+
+  writeJsonArtifact(outPath, {
+    ...shared,
+    samples: [],
+    summary: 'Replace this scaffold provider with a project-local profiler command when real profiler data is available.',
+  });
+  writeJsonArtifact(memoryOutPath, {
+    ...shared,
+    jsHeapBytes: null,
+    nativeHeapBytes: null,
+    summary: 'Replace this scaffold memory signal with device or runtime memory evidence.',
+  });
+  writeJsonArtifact(networkOutPath, {
+    log: {
+      creator: {
+        name: 'agent-scenario-loop scaffold provider',
+        version: '1.0.0',
+      },
+      entries: [],
+      version: '1.2',
+    },
+    ...shared,
+  });
+}
+
+/**
+ * Runs the provider script.
+ *
+ * @returns {void}
+ */
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  writeProviderEvidence({
+    memoryOutPath: requireStringArg(args, 'memory-out'),
+    networkOutPath: requireStringArg(args, 'network-out'),
+    outPath: requireStringArg(args, 'out'),
+    platform: requireStringArg(args, 'platform'),
+    runId: requireStringArg(args, 'run-id'),
+    scenarioId: requireStringArg(args, 'scenario'),
+  });
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}