agent-scenario-loop 0.1.0

package/docs/adapters.md

@@ -0,0 +1,145 @@
+# Adapter Onboarding
+
+Agent Scenario Loop treats runners as replaceable ports behind stable scenarios and artifacts. Add one adapter at a time: describe its capabilities, prove planner compatibility, run a scenario, and write the standard evidence artifacts.
+
+## Choose The Role
+
+Use a primary runner when the tool owns the scenario lifecycle:
+
+- install or verify the app
+- launch the app
+- start and stop a profile session
+- execute scenario steps
+- capture required logs or truth-event evidence
+- write health, verdict, manifest, metrics, and summaries
+
+Use an evidence provider when the tool only contributes evidence:
+
+- accessibility inspection
+- profiler output
+- memory snapshots
+- network captures
+- screenshots, video, or UI tree snapshots
+
+A scenario should have one primary runner. Evidence providers can satisfy required evidence outputs or optional driver actions when they are active for the selected platform.
+
+## Describe Capabilities
+
+Create a runner manifest under `runner-manifests/` or use the fixtures in `examples/runners/` as a starting point. The shipped [runner and provider target matrix](../examples/runners/README.md) describes which fixtures are bundled adapters, external-tool targets, or project-local provider patterns.
+
+Primary runner shape:
+
+```json
+{
+  "schemaVersion": "1.0.0",
+  "runnerId": "my-android-runner",
+  "kind": "primary",
+  "platforms": ["android"],
+  "capabilities": ["launch", "sessionControl", "command", "logCapture", "artifactWrite"],
+  "driverActions": ["tap", "scroll", "assertVisible", "readLogs"],
+  "artifactOutputs": ["logs", "signals"],
+  "lifecycle": ["prepare", "launch", "startSession", "executeStep", "waitForTruthEvent", "captureEvidence", "stopSession", "finalize"]
+}
+```
+
+Evidence provider shape:
+
+```json
+{
+  "schemaVersion": "1.0.0",
+  "runnerId": "my-accessibility-provider",
+  "kind": "evidenceProvider",
+  "platforms": ["ios", "android"],
+  "capabilities": ["accessibility"],
+  "artifactOutputs": ["accessibility"],
+  "lifecycle": ["prepare", "startWindow", "capture", "stopWindow", "finalize"]
+}
+```
+
+Keep manifests honest. Do not declare a driver action until the adapter can execute it or the provider can produce the required evidence.
+
+## Prove The Plan
+
+Run compatibility before runtime:
+
+```bash
+asl-check-plan \
+  --scenario scenarios/mobile/app-startup.json \
+  --runner runner-manifests/primary-runner.json \
+  --provider runner-manifests/evidence-provider.json \
+  --platform android \
+  --out artifacts/asl/plan/app-startup-android
+```
+
+For an initialized app, use the project-level gate:
+
+```bash
+asl-validate-project --root . --platform all --out artifacts/asl/project-validation
+```
+
+The project-validation artifact gives agents structured `nextActions` for missing files, unsupported platforms, incomplete helper wiring, invalid required config, package-script drift, and planner failures. Omitted optional package drivers are preserved as warnings so teams can declare only the runner lanes they intend to support.
+
+## Implement The Port
+
+An adapter should map normalized scenario steps to tool calls:
+
+| Scenario step | Port responsibility |
+| --- | --- |
+| `launch` | install, launch, or verify the app is open |
+| `command` | dispatch an app command or driver gesture |
+| `waitForMilestone` | wait for app-owned truth events |
+| `captureEvidence` | collect logs, screenshots, UI trees, video, or provider output |
+
+When a normalized step has a `driverAction`, use `dispatchDriverAction` from the package root to call the active driver. It rejects unknown actions and missing driver methods explicitly, so a scenario cannot silently pass through an adapter that lacks the requested capability.
+
+The built-in adb and simctl adapters show the expected boundary:
+
+- `runner/android-adb-driver.ts`: adb-backed tap, scroll, assertion, UI tree, screenshot, record, and log actions
+- `runner/ios-simctl-driver.ts`: simctl-backed screenshot and log actions
+- `runner/argent.ts`: Argent-backed ASL artifact runner for launch, coordinate-backed gestures, screenshot requests, and UI descriptions
+- `runner/argent-driver.ts`: optional Argent-backed driver adapter without bundling Argent
+- `runner/profile-android.ts` and `runner/profile-ios.ts`: profile artifact pipelines that turn raw evidence into health, metrics, verdicts, and summaries
+
+External tools such as agent-device, Argent, XcodeBuildMCP, axe, profilers, and custom scripts should plug in behind the same shape. The tactical tool can change; the scenario and artifact contract should not.
+
+## Preserve Evidence
+
+Every run should leave agent-readable proof:
+
+- `health.json`
+- `verdict.json`
+- `agent-summary.md`
+- `manifest.json`
+- `metrics.json`
+- `causal-run.json`
+- `budget-verdict.json` when budgets exist
+- raw evidence under `raw/`
+- captures under `captures/`
+- provider signals under `signals/`
+
+Do not treat timing as trustworthy unless scenario health passed. If setup fails, write failed health with a concrete next action instead of producing optimistic timing claims.
+
+## Attach Provider Evidence
+
+If a provider already wrote files, attach them during profiling:
+
+```bash
+asl-profile-android \
+  --config asl.config.json \
+  --scenario scenarios/android/app-startup.json \
+  --events artifacts/raw/adb-logcat.txt \
+  --signal js:artifacts/provider/js-profile.json \
+  --signal network:artifacts/provider/network.har \
+  --capture screenshot:artifacts/provider/final-screen.png
+```
+
+If the provider should run during profiling, declare `providerCommands` in its manifest. Commands run without a shell, preserve stdout/stderr/exit code, and inventory outputs in `manifest.artifacts.evidenceAttachments`. Runtime profiles reject a provider whose `platforms` do not include the selected platform before command execution, preserving the same active-provider semantics used by planner compatibility.
+
+## Acceptance Checklist
+
+- The manifest validates against `schemas/runner-capabilities.schema.json`.
+- `asl-check-plan` passes for at least one scenario and platform.
+- Failed setup produces failed health and a useful next action.
+- Passed runs write the standard artifact set.
+- Attached evidence is inventoried with stable run-relative paths.
+- Package docs describe whether the adapter is bundled, a fixture target, or a project-local integration.

package/docs/api.md

@@ -0,0 +1,94 @@
+# Public API
+
+Agent Scenario Loop keeps its public surface small: the root package exports stable core contracts, while runner subpaths expose executable adapters for teams that want to compose the proof loop from code.
+
+## Root Package
+
+Import core contracts from `agent-scenario-loop`:
+
+```js
+const {
+  buildAgentSummaryMarkdown,
+  buildScenarioExecutionPlan,
+  buildRunIndex,
+  compareRunDirectories,
+  createArtifactLayout,
+  dispatchDriverAction,
+  evaluateRunnerCompatibility,
+  validateJson,
+} = require('agent-scenario-loop');
+```
+
+The root package is for stable, runner-neutral behavior:
+
+- artifact layout and artifact writers
+- profile-event parsing, metrics, manifests, causal runs, budget verdicts, and summaries
+- scenario execution-plan normalization
+- scenario/runner/provider compatibility checks
+- port validation and driver dispatch helpers
+- typed port contracts for primary runners, drivers, evidence providers, artifact writers, and interpreters
+- evidence interpretation gates
+- run indexing and lane-aware latest-trusted comparison selection
+- comparison artifacts
+- aggregate live-proof artifacts
+- schema validation
+
+Use `dispatchDriverAction()` when a runner has already normalized a scenario step and needs to call the active `DriverPort` implementation without binding to adb, simctl, agent-device, Argent, or another concrete tool.
+
+## Runner Subpaths
+
+Runner subpaths are public when a consuming project needs to compose a workflow without shelling out to the installed binaries:
+
+| Subpath | Purpose |
+| --- | --- |
+| `agent-scenario-loop/runner/agent-device` | agent-device capture runner that executes scenario-declared portable driver actions and writes ASL health, verdict, raw, and capture artifacts |
+| `agent-scenario-loop/runner/android-adb` | Android adb readiness, launch, profile-session control, driver actions, and logcat capture |
+| `agent-scenario-loop/runner/android-adb-driver` | adb-backed `tap`, `scroll`, `assertVisible`, `inspectTree`, `screenshot`, and `readLogs` driver adapter |
+| `agent-scenario-loop/runner/agent-device-driver` | agent-device-backed portable action adapter for `tap`, `scroll`, `assertVisible`, `inspectTree`, `screenshot`, `readLogs`, app open/close, and alert helpers |
+| `agent-scenario-loop/runner/argent` | Argent capture runner that executes launch and coordinate-backed portable driver actions, then writes ASL health, verdict, raw, and capture artifacts |
+| `agent-scenario-loop/runner/argent-driver` | Argent-backed optional adapter for launch, URL open, normalized gestures, screenshot requests, and UI descriptions without bundling Argent |
+| `agent-scenario-loop/runner/check-plan` | scenario/runner/provider compatibility artifact generation |
+| `agent-scenario-loop/runner/compare` | direct baseline/current comparison |
+| `agent-scenario-loop/runner/compare-latest` | latest trusted prior-run comparison |
+| `agent-scenario-loop/runner/demo-loop` | fixture-only loop proof |
+| `agent-scenario-loop/runner/example-android-live` | packaged Android example live proof |
+| `agent-scenario-loop/runner/example-ios-live` | packaged iOS example live proof |
+| `agent-scenario-loop/runner/host-doctor` | aggregate host/device preflight for adb, simctl, agent-device, and Argent availability before live proof |
+| `agent-scenario-loop/runner/init-project` | template scaffold command for consuming app layouts |
+| `agent-scenario-loop/runner/ios-simctl` | iOS simctl readiness, storage-backed session control, stored event capture, lifecycle crash detection, and host crash-report attachment |
+| `agent-scenario-loop/runner/ios-simctl-driver` | simctl-backed `screenshot` and `readLogs` driver adapter |
+| `agent-scenario-loop/runner/live-android` | generic one-scenario Android live proof runner with adb preflight, profile-session capture, optional agent-device and Argent sidecars, latest-trusted comparison, and aggregate live-proof artifacts |
+| `agent-scenario-loop/runner/live-ios` | generic one-scenario iOS live proof runner with simctl preflight, storage or deep-link profile-session capture, optional agent-device and Argent sidecars, latest-trusted comparison, and aggregate live-proof artifacts |
+| `agent-scenario-loop/runner/live-proof` | aggregate live-proof artifact validation, multi-artifact platform-set checks, durable `live-proof-set.json` writing, formatting, failed-proof gating, and regression gating |
+| `agent-scenario-loop/runner/profile-android` | Android profile artifact pipeline |
+| `agent-scenario-loop/runner/profile-ios` | iOS profile artifact pipeline |
+| `agent-scenario-loop/runner/validate-project` | project-level validation for initialized consumer app scaffolds |
+
+Installed binaries mirror those runner entrypoints for CLI use.
+
+## Shipped Fixtures
+
+The package intentionally ships schemas and examples:
+
+- `agent-scenario-loop/schemas/*`
+- `agent-scenario-loop/examples/*`
+- `agent-scenario-loop/templates/*`
+
+These are public fixtures and contract references. Templates are safe starting points to copy into a consuming app and adapt.
+
+For concrete runner and evidence-provider integration steps, see [Adapter Onboarding](adapters.md).
+
+## App Helper
+
+`app/profile-session.ts` is shipped as source for React Native apps to copy into their own codebase. It is not a compiled CommonJS runtime export because it depends on app-side React Native modules, app bundling, and platform storage behavior.
+
+The intended integration is:
+
+1. Copy `app/profile-session.ts` into the app.
+2. Wire `useProfileSessionBootstrap()` once near the app root.
+3. Emit app-owned truth events with `emitProfileEvent()`.
+4. Register optional command targets with `registerProfileCommandTargetHandler()`.
+
+## Stability Rule
+
+If a function, binary, schema, or example path is listed here, package smoke should verify that it is present in the packed tarball. If a new public entrypoint is added, update this document and the smoke expectations in the same change.

package/docs/authoring.md

@@ -0,0 +1,196 @@
+# Scenario Authoring
+
+Start with one journey that matters. A good scenario is boring, repeatable, inspectable, and portable.
+
+## Init Command
+
+After installing the package, scaffold the starter layout with:
+
+```bash
+asl-init --out . --scenario first-journey
+```
+
+That creates:
+
+- `asl.config.json`
+- `scenarios/mobile/first-journey.json`
+- `runner-manifests/primary-runner.json`
+- `runner-manifests/evidence-provider.json`
+- `scripts/asl-capture-accessibility-provider.mjs`
+- `scripts/asl-capture-profiler-provider.mjs`
+- `src/devtools/profile-session.ts`
+- `asl/README.md`
+- `asl/package-scripts.json`
+- `asl/gitignore-snippet`
+
+The command refuses to overwrite existing files unless `--force` is provided. Use `--dry-run` to preview the file list without writing. It does not edit your existing `package.json` or `.gitignore`; merge the generated script and ignore snippets intentionally. Project validation reports an error until the required generated `asl:*` scripts are present in the app `package.json`, and it flags direct installed-bin scripts that drift from `asl/package-scripts.json`.
+
+After filling in app identifiers, validate the whole initialized project before runtime proof:
+
+```bash
+asl-validate-project --root . --platform all --out artifacts/asl/project-validation
+```
+
+Project validation checks the app-side profile-session helper, package-script snippets, app `package.json` script merge and drift, project config required fields, declared `drivers.supported` entries for fixture, adb, simctl, agent-device, and Argent lanes, scenario manifests, runner manifests, provider manifests, local provider-command script references, and planner compatibility. Validation also classifies declared drivers into package-supported lanes, known external target contracts such as XcodeBuildMCP, and custom driver names, so agents can distinguish bundled ASL execution paths from adapter targets that must be supplied by the host project. Missing live app identifiers such as `app.profileSessionScheme`, `app.iosBundleId`, or `app.androidPackage` are errors for the selected platform, as are missing artifact roots and missing scenario-root declarations for the selected platform. Placeholder app identity values are reported as warnings so a fresh scaffold can still prove installability while real app setup remains visible before live proof. The JSON artifact also includes structured `nextActions` for agents.
+
+Project validation also checks whether `.gitignore` includes the generated `asl/gitignore-snippet` patterns for runtime artifacts, local runner config, traces, and local proof captures. Missing patterns are warnings with an `ignore_runtime_artifacts` next action; they do not block setup, but they should be fixed before running live scenarios repeatedly.
+
+The generated compare and live-proof scripts require `ASL_COMPARE_IOS_CURRENT`, `ASL_COMPARE_ANDROID_CURRENT`, or `ASL_LIVE_PROOF` so agents pass explicit artifact paths instead of leaving shell-sensitive placeholders in package scripts.
+
+## Templates
+
+You can also copy these files manually and rename them as needed:
+
+| Template | Use |
+| --- | --- |
+| `templates/project.config.json` | Project-local app identifiers, artifact paths, and runner defaults |
+| `templates/mobile-scenario.json` | First portable mobile scenario |
+| `templates/primary-runner.json` | Primary runner capability manifest |
+| `templates/evidence-provider.json` | Optional evidence-provider manifest |
+| `templates/scripts/asl-capture-accessibility-provider.mjs` | Runnable starter provider command for deterministic accessibility evidence |
+| `templates/scripts/asl-capture-profiler-provider.mjs` | Runnable starter provider command for deterministic profiler, memory, and network evidence |
+| `templates/integration-readme.md` | Consumer-app wiring guide generated into `asl/README.md` |
+| `templates/package-scripts.json` | Package-script snippets generated into `asl/package-scripts.json`; project validation also checks that required scripts exist in app `package.json` and direct installed-bin scripts have not drifted |
+
+The JSON templates are schema-checked, and every shipped template is checked by package smoke. They intentionally use neutral placeholder names.
+
+## Scenario Shape
+
+A scenario should answer five questions:
+
+1. What journey does the app need to prove?
+2. Which app-owned truth events prove progress and completion?
+3. How many cycles should run?
+4. Which budgets are meaningful only after scenario health passes?
+5. Which runner capabilities or driver actions are required?
+
+Minimal fields:
+
+- `id`: stable scenario id, such as `feed-open` or `checkout-submit`
+- `flowId`: stable product flow id used in summaries and causal artifacts
+- `platforms`: `ios`, `android`, or both
+- `requiredCapabilities`: lifecycle and evidence ownership needed for the run
+- `truthEvents`: app-owned events that make the scenario trustworthy
+- `steps`: launch, command, wait, gesture, assertion, or evidence capture steps
+
+Preferred fields:
+
+- `journey`: human-readable intent, actor, start state, and end state
+- `comparisonLane`: default historical baseline lane for runs of this scenario
+- `milestones`: named event checkpoints with phases and timeouts
+- `cycles`: iteration count and stop policy
+- `budgets`: thresholds to evaluate only after truth-event health passes
+- `artifacts`: required and optional evidence outputs
+
+Use `comparisonLane` when a scenario should always compare within one stable proof mode, such as `feed-open-android-live`. Profile CLIs can also receive `--comparison-lane`; the CLI flag wins when one-off runs need a different lane.
+
+## Truth Events
+
+Treat truth events as app-owned facts, not runner observations. The app should emit them from the code path that actually represents the journey state.
+
+Good truth events:
+
+- `feed_open_requested`
+- `feed_first_content_visible`
+- `message_send_completed`
+- `checkout_submit_failed`
+
+Weak truth events:
+
+- `button_clicked`
+- `waited_1000ms`
+- `screen_probably_loaded`
+
+Timing is not trusted unless scenario health passes. If a required truth event is missing, the run can still write artifacts, but verdicts and comparisons must remain inconclusive.
+
+## Steps
+
+Use steps to describe intent and required adapter actions:
+
+- `launch`: app lifecycle start
+- `command`: app command such as `activate-target:first-journey`
+- `waitForMilestone`: wait for an app-owned truth event
+- `captureEvidence`: collect logs, screenshot, profiler output, or another artifact
+- `gesture`: portable UI gesture intent
+- `assertUi`: UI assertion intent
+
+Use `driverAction` only when the scenario truly requires a concrete operation such as `tap`, `scroll`, `assertVisible`, `screenshot`, `readLogs`, or `collectPerfSignals`. The planner fails early when no active runner or provider can satisfy a required driver action.
+
+Use `selector` to describe the intended app target without committing the scenario to one driver. Supported selector kinds are `testId`, `accessibilityId`, `accessibilityLabel`, `text`, `resourceId`, and `xpath`.
+
+```json
+{
+  "id": "start-journey",
+  "kind": "gesture",
+  "driverAction": "tap",
+  "selector": {
+    "kind": "testId",
+    "value": "first-journey-start"
+  }
+}
+```
+
+Adapters may resolve selectors through accessibility trees, test ids, native UI inspection, or tool-specific selector engines. Android adb resolves `testId`, `resourceId`, `accessibilityId`, `accessibilityLabel`, and `text` selectors from UIAutomator bounds for tap and scroll actions. Argent gesture steps currently use normalized or pixel coordinates from `adapterOptions.argent`; it does not resolve tap or scroll targets from selectors. Coordinates belong in adapter metadata only when the selected runner cannot resolve a durable selector.
+
+## Runners And Providers
+
+Primary runners own the run lifecycle: prepare, launch, start session, execute commands, wait, capture evidence, stop, and finalize.
+
+Evidence providers attach smaller evidence windows: profiler data, accessibility snapshots, memory evidence, network evidence, or other signals.
+
+Use an evidence provider when:
+
+- the primary runner should not own that tool
+- the evidence can be collected independently
+- the same provider should work with multiple primary runners
+
+When a provider or custom script has already written files, attach them to a profile run with repeatable CLI flags:
+
+```bash
+asl-profile-android \
+  --config asl.config.json \
+  --scenario scenarios/android/app-startup.json \
+  --events artifacts/raw/adb-logcat.txt \
+  --signal js:artifacts/provider/js-profile.json \
+  --signal network:artifacts/provider/network.har \
+  --capture screenshot:artifacts/provider/final-screen.png \
+  --capture uiTree:artifacts/provider/ui-tree.json
+```
+
+Signals are copied into `signals/js`, `signals/memory`, or `signals/network` and listed in `manifest.json`. Captures are copied into `captures`; screenshots are listed in `artifacts.captures.screenshots`, while video and UI tree captures replace the matching named capture path in the manifest. Every attached file is also listed in `artifacts.evidenceAttachments` with kind, run-relative path, source filename, byte size, and sha256 hash. Attached provider evidence is preserved as proof, but timing verdicts still come from app-owned truth events and budgets.
+
+Provider manifests can also declare `providerCommands`. Profile runners execute those commands when passed with `--provider <manifest>`, but only when the provider manifest includes the selected platform. A provider with `platforms: ["ios"]` passed to an Android profile writes failed `health.json` with `provider_platform_unsupported` and does not run the command. Commands run without a shell, can use placeholders such as `{providerDir}`, `{runDir}`, `{runId}`, `{scenarioId}`, and `{platform}`, and must declare their output files. Provider-channel outputs are copied or preserved under `raw/providers/<provider-id>/` and inventoried in `artifacts.evidenceAttachments`; signal and capture outputs can still map into the standard `signals/*` or `captures/` folders. Command stdout, stderr, exit code, phase, and argv are preserved under `raw/provider-commands/`. When a provider command exits nonzero, the runner writes failed `health.json`, inconclusive `verdict.json`, and `agent-summary.md` with a next-action hint instead of making timing claims.
+
+The `examples/runners/script-*.json` manifests show package-neutral wrappers for accessibility, profiler, memory, and network evidence. They intentionally reference placeholder commands such as `capture-accessibility` or `capture-memory`; replace those with your project-local script, binary, or agent command. The contract that matters is the declared output path and evidence kind, not the specific tool used to create the file.
+
+## Artifacts
+
+A completed profile run should leave the standard artifact set:
+
+- `health.json`
+- `verdict.json`
+- `agent-summary.md`
+- `manifest.json`
+- `metrics.json`
+- `causal-run.json`
+- `budget-verdict.json` when budgets are configured
+- `summary.md`
+- `raw/*`
+- `captures/*`
+- `signals/*`
+
+Commit scenario definitions, runner manifests, docs, and app integration code. Do not commit generated native folders, runtime artifacts, simulator recordings, screenshots, profiler exports, or local app data containers.
+
+## Validation
+
+Validate a scenario and runner before execution:
+
+```bash
+pnpm check-plan -- --scenario templates/mobile-scenario.json --runner templates/primary-runner.json --platform ios --out artifacts/plan/first-journey
+```
+
+Run the release gate before publishing package changes:
+
+```bash
+pnpm release:check
+```

package/docs/concepts.md

@@ -0,0 +1,136 @@
+# Concepts
+
+Agent Scenario Loop exists because agent-driven app work rarely belongs to one tool.
+
+One runner may edit code. Another may build the app. Another may drive Android. Another may drive iOS. Others may collect logs, screenshots, accessibility output, profiler traces, memory evidence, network captures, or summaries.
+
+Execution is not the missing piece.
+
+The missing piece is a durable place for scenarios, evidence, and comparisons to live after any one runner finishes. Agent Scenario Loop coordinates scenarios, runners, and evidence so a project keeps a stable record of what happened across tools and over time.
+
+## What is an agent runner?
+
+An agent runner is any tool that can carry out part of a software workflow on your behalf.
+
+It might:
+
+- click through an app
+- run commands
+- inspect a screen
+- collect diagnostics
+- drive a simulator or device
+- collect logs, traces, or accessibility output
+
+Examples include Codex, Argent, Agent Device, adb-based automation, accessibility tooling, Xcode instrumentation, Maestro, Detox, Appium, profilers, and custom internal runners. You do not need to know any specific one of these tools to understand Agent Scenario Loop. They are all ways to execute or observe part of a scenario.
+
+## Why orchestration matters
+
+The moment you want to mix multiple runners, reuse scenarios, compare results across runs, preserve evidence, or evaluate changes over time, things become fragmented quickly.
+
+Every tool has its own way to define work, capture results, and preserve context.
+
+Agent Scenario Loop provides the layer that coordinates the work:
+
+1. Define an application scenario.
+2. Attach the runners and instrumentation appropriate for that scenario.
+3. Execute the scenario.
+4. Collect evidence throughout the run.
+5. Preserve the evidence as an artifact that humans and agents can inspect later.
+
+## Vendor-neutral by design
+
+Scenarios should outlive tooling choices.
+
+The best runner for a task today may not be the best runner six months from now. Agent Scenario Loop treats runners as interchangeable components. You can swap runners, combine runners, introduce new runners, or compare runners without rewriting your scenario definitions.
+
+The goal is not to build another agent runner. The goal is to provide a common orchestration and evidence layer that sits above them.
+
+## Evidence is the output
+
+Most testing systems produce a pass/fail result. Agent Scenario Loop produces evidence.
+
+Evidence can include:
+
+- logs
+- traces
+- memory measurements
+- CPU measurements
+- network activity
+- accessibility results
+- performance metrics
+- custom signals
+
+The scenario is not simply proving correctness. The scenario is generating evidence.
+
+That evidence is preserved and becomes part of the project's understanding of itself. One run is useful. A hundred runs are more valuable because they let the project ask whether memory usage is improving, performance is degrading, regressions are appearing, or an optimization actually helped.
+
+## Scenarios become assets
+
+Most automation is tightly coupled to the tools that created it.
+
+When the tooling changes, the automation is rewritten. When the agent changes, the workflow changes. When the framework changes, the evidence disappears.
+
+Agent Scenario Loop is built around the opposite idea: scenarios are long-lived project assets.
+
+A scenario captures something important about your application:
+
+- how users consume content
+- how creators upload media
+- how campaigns are created
+- how livestreams behave
+- how conversations load
+
+These concerns exist independently of whichever tools happen to execute them today.
+
+As tooling evolves, your scenarios remain. As better agents emerge, your scenarios remain. As instrumentation improves, your scenarios remain.
+
+Over time, a project accumulates a growing library of scenarios that describe its most important behaviors. Those scenarios become a stable lens through which change can be evaluated.
+
+Not just whether something works today. Whether it is improving over time.
+
+## The locus of control
+
+Most teams unknowingly give the locus of control to the current tool.
+
+Agent Scenario Loop moves it back into the application itself.
+
+The feed is the thing that matters. The livestream is the thing that matters. The creator upload flow is the thing that matters. Agent Scenario Loop makes those concerns first-class citizens and lets tooling orbit around them instead of the other way around.
+
+Every new scenario increases coverage. Every execution adds evidence. Every comparison adds historical context.
+
+Eventually, the project develops a durable understanding of how critical parts of the application behave across releases, refactors, platform upgrades, and agent-driven changes.
+
+The tooling may change. The runners may change. The agents may change. The scenarios remain the source of truth.
+
+That is a different philosophy from frameworks that primarily evaluate agents. Agent Scenario Loop is built to evaluate the evolution of software.
+
+## How it differs from testing frameworks
+
+Agent Scenario Loop does not make existing testing frameworks obsolete.
+
+Traditional frameworks usually optimize for:
+
+> Did the application behave correctly?
+
+Agent Scenario Loop optimizes for:
+
+> What did we learn from running this scenario?
+
+Both questions matter. Agent Scenario Loop focuses on the second question by preserving health, verdicts, metrics, logs, traces, comparisons, and other run evidence in a stable artifact shape.
+
+## How it differs from agent evaluation
+
+Agent Scenario Loop is not primarily evaluating agents.
+
+An agent may execute part of a run. A runner may drive a device. A profiler may collect signals. None of those is the center of the model.
+
+The scenario is.
+
+The feed, livestream, upload flow, checkout flow, or conversation thread is the thing being studied over time.
+
+## Read next
+
+- [Principles](principles.md) for the project doctrine
+- [Contracts](contracts.md) for the current artifact and package surface
+- [Live Proofs](live-proofs.md) for fixture, Android, iOS, and comparison runs
+- [Runner docs](../runner/README.md) for the host execution boundary