English · 日本語
Developer guide: code structure, the scenario DSL, and the development routine¶
A guide to the source tree and how to work in it. It covers where each file sits and which classes live in it. It explains how the scenario domain-specific language (DSL) and its
Selectorfields work, and what happens inside each class while a scenario runs. It ends with the routine for developing and verifying a change.
Related: architecture · concepts · run loop · drivers · glossary
How to read this page¶
The page runs in one direction, from the outside in. It opens with a picture of the whole system and locates every file. It then names the handful of types that carry the rest of the code. After that, it follows a single command through the code and describes each class in turn. A reader who starts at the top and stops anywhere still ends with a complete, if coarser, picture.
Three companion pages carry the depth this reading guide leaves out. Architecture holds the module table and the dependency-layer contract. Run loop explains the deterministic runner's semantics. Drivers explains each backend's platform seam. The glossary defines the domain vocabulary term by term.
Two vocabulary notes make the rest readable. A scenario is one YAML (YAML Ain't Markup Language) file that describes a user flow as a list of steps. A backend is one platform's implementation of the driver interface. Examples are XCUITest for the iOS Simulator, adb for Android, and Playwright for a web browser.
1. The shape of the system¶
Bajutsu splits into two tiers that never mix. Tier 1 uses a large language model (LLM) to author a scenario and to investigate a failure. Tier 2 replays the scenario deterministically. It derives the verdict from machine-checkable assertions, with no model anywhere on the path. The scenario file is the hub between the two tiers. Tier 1 writes the file, humans own and edit it afterwards, and Tier 2 consumes it.
Mermaid source
flowchart TB
goal(["Natural-language goal"])
human(["Human edit"])
scenario[["Scenario YAML<br/>the shared hub"]]
subgraph t1["Tier 1 · LLM authors and investigates"]
rec["record / crawl"]
agent["Agent<br/>proposes one step at a time"]
rec <--> agent
end
subgraph t2["Tier 2 · deterministic, no LLM"]
runner["runner<br/>leases a device, launches the app"]
orch["orchestrator<br/>act, wait, verify"]
driver{{"Driver interface<br/>the one platform seam"}}
asserts["assertions<br/>the verdict"]
report["report<br/>manifest, JUnit, CTRF, HTML"]
runner --> orch --> driver
orch --> asserts --> report
end
backends["XCUITest · adb · Playwright · fake"]
triage["triage<br/>root cause, advisory"]
goal --> rec
rec ==> scenario
human ==> scenario
scenario ==> runner
driver --> backends
report --> triage
triage -.->|proposes edits| scenario
classDef ai fill:#fde68a,stroke:#d97706,color:#1f2937;
classDef det fill:#bfdbfe,stroke:#2563eb,color:#1f2937;
class t1 ai
class t2 det
Three properties of the picture explain most of the code's shape.
- The verdict path holds no model. Prime directive 1 forbids an LLM anywhere in
runor in the continuous integration (CI) gate. The whole Tier 2 column stays free of the AI packages. - One seam, many platforms. Every platform difference hides behind the
Driverinterface. A new platform means a new backend rather than a fork of the core. - The scenario is the durable artifact. Nothing else persists between sessions. The scenario schema doubles as the contract every feature reads.
2. Where the files live¶
2.1 The repository's top level¶
| Path | What lives there |
|---|---|
bajutsu/ |
The Python logic core: 324 files, roughly 78,000 lines. Everything the rest of this page describes. |
tests/ |
The deterministic test suite: 381 files, roughly 125,000 lines. Larger than the code it covers. |
BajutsuKit/ |
The Swift test-support package: the resident XCUITest runner, the in-app collector, the WebView and z-order channels. |
BajutsuAndroid/ · BajutsuAndroidUIAutomatorServer/ · IdentifierTool/ |
The Kotlin counterparts: the in-app hooks, the resident UI Automator server, and the identifier-tagging library. |
demos/ |
Runnable examples, including the showcase fixture built five times across platforms. |
scenarios/ |
Scenario YAML files the repository runs against its own fixtures. |
docs/ · docs/ja/ |
This documentation, English and its Japanese mirror. |
roadmaps/ |
One directory per roadmap item, bilingual, carrying the rationale behind each decision. |
scripts/ |
Repository tooling: the linters, the diagram renderer, the repository map. |
2.2 The bajutsu/ package¶
The package splits into a shared common/ core and one directory per user-facing command. A command
directory holds that command's own logic plus its cli.py, which registers the Typer command. The
map below groups the directories by the job they do rather than alphabetically.
Mermaid source
flowchart TB
subgraph cmd["Commands · one directory each, plus its cli.py"]
c1["run/ · record/ · crawl/ · repl/ · triage/"]
c2["codegen/ · mcp/ · serve/ · analysis/"]
c3["cli/ · assembles the Typer app"]
end
subgraph exec["Execution core · common/"]
r["runner/<br/>device pool, launch, pipeline"]
o["orchestrator/<br/>the step loop"]
pl["platform_lifecycle/<br/>app bring-up per platform"]
end
subgraph seam["Platform seam · common/"]
d["drivers/<br/>Driver protocol + backends"]
bc["backend_cli/<br/>simctl, adb wrappers"]
b["backends.py<br/>actuator selection"]
end
subgraph contract["Contract · common/"]
s["scenario/<br/>pydantic schema + loaders"]
cfg["config/<br/>defaults, per-target Effective"]
end
subgraph out["Output · common/"]
a["assertions/<br/>the verdict"]
e["evidence/<br/>artifacts per step"]
rep["report/<br/>manifest, JUnit, CTRF, HTML"]
end
subgraph peri["Periphery · common/"]
ag["agents/<br/>authoring, triage, alerts"]
ai["ai/<br/>vendor-neutral LLM seam"]
end
cmd --> exec
cmd -.-> peri
exec --> seam
exec --> contract
exec --> out
peri -.-> seam
out --> contract
classDef det fill:#bfdbfe,stroke:#2563eb,color:#1f2937;
classDef aip fill:#fde68a,stroke:#d97706,color:#1f2937;
class exec,seam,contract,out det
class peri aip
common/ holds a further set of single-purpose helpers:
capability/: what a backend supports.run_meta/: run identity and artifact storage.analytics/: token and cost accounting.evidence/,devices/,provisioning/,github/, andcloud/.
The module table in architecture.md describes each in one row.
2.3 Every package, in one table¶
The diagram above groups directories by role. The tables below list every directory in the same
groups. Each row gives the file and line counts that make repo-map ARGS="--code" reports, and the
modules the directory holds. The tables form a fuller inventory than the diagram's boxes have room
for.
Commands — one directory per user-facing feature, plus its own cli.py.
| Package | Files, lines | Holds |
|---|---|---|
cli/ |
4, 786 | Typer app assembly: _shared, dotenv, handoff |
cli/commands/ |
5, 448 | Commands with no owning feature: doctor, lint, report, schema |
run/ |
3, 1,701 | cli (the run command), notify |
record/ |
4, 1,318 | capture, cli, loop |
crawl/ |
9, 3,109 | cli, core, flows, guide, report, repro, serialize, tabs |
repl/ |
5, 371 | cli, loop, render, session |
triage/ |
3, 1,203 | cli, heuristic |
codegen/ |
7, 2,623 | cli, common, xcuitest, playwright, uiautomator |
mcp/ |
4, 327 | cli, resources, tools |
analysis/ |
7, 2,543 | audit, coverage, flakiness, impact, stats, trace |
analysis/cli/ |
8, 870 | One Typer command per report |
serve/ |
28, 8,457 | The local web UI's own top-level modules (state, routes, handler, executor, jobs, …); cli/, operations/, and server/ break out below |
serve/cli/ |
4, 873 | serve, worker, approve |
serve/operations/ |
27, 6,997 | One module per web-UI operation: capture, codegen, coverage, doctor, enrich, evidence, lint, metrics, runs, triage, upload, … |
serve/server/ |
17, 3,691 | The hosted (multi-tenant) backend: app, db, executor, models, oauth, artifacts, baselines, sessions, secrets |
Execution core — the device pool, the step loop, and per-platform app bring-up.
| Package | Files, lines | Holds |
|---|---|---|
common/runner/ |
11, 3,122 | pipeline, pool, launch, device_provider, recovery, mailbox, build, types |
common/orchestrator/ |
6, 3,534 | loop, waits, substitution, evidence_rules, types |
common/orchestrator/actions/ |
2, 139 | The action-handler registry (_registry) |
common/orchestrator/actions/handlers/ |
10, 1,254 | gestures, scroll, device, navigation, http, generate, totp, manual |
common/platform_lifecycle/ |
7, 968 | protocols, factories, readiness, relaunchers, device_control, read_session |
common/platform_lifecycle/environments/ |
8, 3,115 | ios, xcuitest, xcuitest_live, android, web, fake |
Platform seam — the Driver protocol and every backend behind it.
| Package | Files, lines | Holds |
|---|---|---|
common/drivers/ |
14, 7,198 | base, actuation, coordinate_tree, fake, xcuitest, adb, playwright, xcuitest_live, elements, dom, web_network, webview, zorder |
common/backend_cli/ |
4, 2,428 | simctl, adb, adb_resident |
common/devices/ |
4, 181 | errors, id, os |
common/capability/ |
4, 548 | capabilities, capability_preflight, preflight |
Contract — the scenario schema and the resolved-config shape.
| Package | Files, lines | Holds |
|---|---|---|
common/scenario/ |
9, 1,232 | load, load_expanded, expand, select, serialize, edit, interp, system_alerts |
common/scenario/models/ |
9, 1,942 | scenario, steps, actions, assertions, selector, evidence, mocks, _base |
common/config/ |
5, 1,234 | schema, effective, resolve, accessors |
Output — the verdict, the captured evidence, and the rendered report.
| Package | Files, lines | Holds |
|---|---|---|
common/assertions/ |
6, 1,225 | evaluate, network, visual, schema, _common |
common/evidence/ |
9, 3,440 | core, golden, intervals, media, network, redaction, sink, visual |
common/report/ |
11, 2,176 | manifest, ctrf, format, rows, panels, html, richtext, archive, load, from_grouping |
Periphery — the paths that reach a model.
| Package | Files, lines | Holds |
|---|---|---|
common/agents/ |
12, 2,386 | protocols, factory, claude, claude_backed, claude_enrich, claude_triage, ai_config, anthropic_client, availability, enrich, alerts |
common/ai/ |
8, 1,072 | base, registry, anthropic, claude_code, disabled, prompts, banner |
Shared utilities under common/ — single-purpose helpers no other group owns.
| Package | Files, lines | Holds |
|---|---|---|
common/ (flat files) |
14, 2,652 | backends, doctor, lint, mailbox, totp, cancellation, config_source, deprecations, diagnostics, handoff, screenshots, stall_diagnostics, _yaml |
common/analytics/ |
4, 862 | ledger, stats, usage |
common/run_meta/ |
6, 602 | files, id, root, artifact_perms, object_store |
common/provisioning/ |
3, 364 | provision, requirements |
common/cloud/ |
2, 678 | devicefarm |
common/github/ |
4, 232 | actions, app, errors |
2.4 Finding a file without reading the tree¶
Three commands print a fresh map on every run, so no committed index goes stale.
make repo-map ARGS="--code" # every package and top-level module
make repo-map ARGS="--docs" # every docs page, with its own summary
make repo-map ARGS="--headings docs/x.md" # one file's headings and their spans
3. The four contracts everything else builds on¶
Four types carry the load. Most of the remaining classes exist to produce one of the four, consume one, or move one across a boundary. Learning the four first makes every later class legible.
Mermaid source
classDiagram
class Scenario {
<<pydantic, authoring>>
+str name
+Preconditions preconditions
+list~Step~ setup
+list~Step~ steps
+list~Assertion~ expect
+list~CleanupRule~ cleanup
+list~CaptureRule~ capture_policy
}
class Step {
<<pydantic, authoring>>
+Selector tap
+TypeText type
+Wait wait
+list~Assertion~ assert_
+39 action fields in all
}
class Assertion {
<<pydantic, authoring>>
+Exists exists
+TextMatch value
+RequestMatch request
+15 kinds in all
}
class Driver {
<<Protocol, runtime>>
+query() list~Element~
+tap(Selector)
+type_text(str)
+swipe(Point, Point)
+wait_for(Selector) bool
+screenshot(str)
+capabilities() set~str~
}
class Element {
<<TypedDict, runtime>>
+str identifier
+str label
+list~str~ traits
+str value
+Frame frame
}
class Effective {
<<frozen dataclass>>
+str target
+PlatformConfig platform_config
+list~str~ backend
+str device
+list~str~ capture
+RunDefaults run_defaults
}
class RunResult {
<<dataclass>>
+str scenario
+bool ok
+list~StepOutcome~ steps
+list~AssertionResult~ expect_results
+list~Artifact~ artifacts
}
Scenario "1" *-- "many" Step
Step "1" *-- "many" Assertion
Driver ..> Element : returns
Scenario ..> Driver : executed against
Effective ..> Driver : configures
Driver ..> RunResult : produces evidence for
Scenario (common/scenario/models/)
is the authoring model. It builds on pydantic with extra="forbid", so an unknown key fails the
load rather than passing unnoticed. A Step carries one of 39 action fields. An Assertion carries
one of 15 kinds. The strictness matters because the scenario is the single artifact that outlives
a session.
Driver (common/drivers/base.py)
is the runtime contract: a Protocol of 23 methods that every backend satisfies. The runtime
Element and Selector sit beside it. Both are TypedDict rather than pydantic models, because
the step loop touches them thousands of times per run. The authoring Selector converts to the
runtime one through as_selector().
Effective (common/config/effective.py)
is one target's fully resolved configuration: the team defaults overlaid by that target's own
block. Freezing the configuration keeps anything downstream from rewriting it. The platform-specific knobs
narrow behind a single platform_config: PlatformConfig field, a discriminated union of
IosConfig | WebConfig | AndroidConfig. One optional field per platform would leave a new sibling
field that every reader must learn to ignore. With the union, a new platform adds a member
instead. Every app-specific difference lives here, which keeps the tool itself app-agnostic.
RunResult (common/orchestrator/types.py)
is one scenario's outcome: the verdict, one StepOutcome per step, the trailing assertion results,
and every artifact captured along the way. The reporter renders a list of them and nothing else.
4. The scenario DSL: what a scenario file looks like¶
A scenario is plain YAML. The Scenario, Step, and Assertion models from section 3 check it
with extra="forbid", so a typo in a key fails the load rather than passing unnoticed. This
section reads one real scenario end to end, then tables the vocabulary the scenario draws from. The
full, normative grammar lives in DSL grammar. The authoring guides with worked
recipes are scenarios and cookbook.
4.1 One scenario, read end to end¶
scenarios/smoke.yaml,
unedited, checks that this documentation site's own landing page renders:
description: >-
Docs-site smoke — the landing page loads and shows its "Get started" and "GitHub"
hero buttons. The fastest check that the Playwright backend reaches the live site.
scenarios:
- name: the landing page shows its hero calls-to-action
description: Wait for the "Get started" hero, then assert both hero buttons and a populated page.
steps:
- wait: { for: { label: "Get started" }, timeout: 15 }
expect:
- exists: { label: "Get started" }
- exists: { labelMatches: "GitHub" }
- count: { sel: { traits: [link] }, atLeast: 5 }
Three parts recur in every scenario.
stepsis the ordered list that the step loop (section 6) executes. Here, onewaitstep polls for the hero button instead of sleeping a fixed duration (prime directive 2).expectis the scenario-level assertion block, checked once after the last step. Here, three independent checks must all pass.- A
{ label: … },{ labelMatches: … }, or{ traits: […] }object is aSelector(section 3), the same shape that ataportypestep's target takes.
4.2 Selecting the element: the Selector¶
Almost every step and assertion targets one element on screen. Every target is a Selector, the
type introduced as one of the four contracts in section 3. This subsection is the authoring view:
which fields exist, and which to reach for first. The runtime side is section 7.2's
resolve_unique. That section covers how a Selector narrows a query() snapshot to exactly one
element, and what happens when the narrowing fails. The full reference is
selectors.
Every provided field combines with a logical AND, with two exceptions. within is a separate,
spatial filter applied after the rest. index is a last resort, applied after every other field
has narrowed the candidates as far as it can.
| Field | Matches | Role |
|---|---|---|
id |
The exact accessibility identifier. Accepts a list, matched as an OR — one candidate per platform's native spelling of the same id — for example [stable.refresh, stable_refresh] for an Android View, whose android:id cannot hold a dot. |
First choice: stable, non-localized, data-derived. |
idMatches |
A glob pattern over the identifier (or a list of globs, matched as an OR). | For a deliberate multi-match: a count assertion, or a forEach step's sel. |
label |
The exact accessibility label. | Auxiliary; disambiguation only, since a label can be localized. |
labelMatches |
A substring or regex over the label. | Auxiliary, for the same reason. |
traits |
A subset test against the element's normalized traits (table below). | Auxiliary — narrows by type, for example traits: [button]. |
value |
The exact accessibility value. | Auxiliary. |
within |
Elements whose frame sits inside a container the nested Selector resolves to. The accessibility tree Bajutsu reads is flat, so "parent" is geometric rather than structural, and within may nest. |
Disambiguation, when two candidates share every other field. |
index |
The nth of several content-distinct candidates (a negative value counts from the end). | Last resort — flaky, since it depends on paint order. |
traits draws from a small, backend-normalized vocabulary (common/drivers/base.py's Trait
class):
| Trait | Marks |
|---|---|
button |
A tappable button. |
link |
A hyperlink. |
notEnabled |
The element is disabled — backs the disabled / enabled assertions. |
selected |
The element is selected or toggled — backs the selected assertion. |
other |
A generic, unclassified element; the resolution algorithm treats it specially (section 7.2). |
secureTextField |
The platform itself marks the field secret, so redaction masks its value with no configuration. |
An author who reaches for index before id, label, or traits has the ordering backwards.
id survives a redesign that merely moves the element on screen. index breaks the moment the
screen gains or loses a sibling.
4.3 The 39 step kinds¶
Every Step carries exactly one of 39 action fields (common/scenario/models/steps.py). Pydantic
validation enforces this, not convention. Two of the fields, wait and assert, are conditions
that the step loop polls directly. The rest dispatch through the action registry (section 7.5).
| Group | Fields | What they do |
|---|---|---|
| Gestures | tap, tapPoint, doubleTap, longPress, swipe, drag, scroll, pinch, rotate, back, navigate, openUrl |
Touch and navigation input. |
| Text and selection | type, select, clear, delete, copy, paste, selectOption, setPickerValue |
Enter, select, copy, and paste text — copy requires a prior select (section 7.5). |
| Conditions | wait, assert |
Poll a condition or an assertion block; never a fixed sleep. |
| App and device lifecycle | relaunch, setLocation, push, clearKeychain, clearClipboard, setClipboard, background, foreground, overrideStatusBar, clearStatusBar, handleSystemAlert |
Drive the app's lifecycle and the simulated device around it. |
| Data and values | http, totp, generate, email |
Produce or fetch a value: an HTTP call, a time-based one-time password (TOTP) code, a random value, a mailbox lookup. |
| Composition and control flow | use, web, manual, if, forEach |
Expand a component, scope a block to a WebView, mark a human takeover, or branch and loop. |
4.4 The 15 assertion kinds¶
Every Assertion (common/scenario/models/assertions.py) carries one of 15 fields.
assertions/evaluate.py (section 7.6) evaluates each field. The evaluator is a total function
that returns a failing result rather than raising.
| Group | Fields | Checks |
|---|---|---|
| Element state and content | exists, value, label, count, enabled, disabled, selected |
An element's presence, text, count, or toggled state. |
| Network | request, event, requestSequence, responseSchema |
Observed HTTP traffic — one exchange, an ordered sequence, or a response body against a schema. |
| Screen comparison | visual, golden |
A screenshot against a baseline image, or an element tree against a recorded one. |
| Clipboard | clipboard |
The device clipboard's current text. |
| Element attribute | attribute |
One HTML attribute of an element, read on demand (web only; BE-0466). |
4.5 Control flow, composition, and data¶
| Construct | Field(s) | What it does |
|---|---|---|
| Conditional | if step (condition, then, else) |
Branches on an Assertion, evaluated the same way expect is. |
| Loop | forEach step (sel, as, steps) |
Repeats steps once per element a Selector matches. |
| Component | use step, plus a separate component file |
Expands a named, parameterized step list at compile time, resolved before the run ever starts (expand.py, section 7.1) — the step loop never sees a use step. |
| WebView scope | web step (within, steps) |
Scopes a nested step list to a WebView reached through the Selector in within. |
| Interrupt handler | interrupts: (scenario-level) |
Clears an interstitial screen — a permission dialog, an app-update prompt — that can appear at an unpredictable point mid-run, sharing the enclosing scenario's vars.*. |
| Setup / teardown phase | setup: / cleanup: (scenario-level) |
Steps run ahead of steps and after the verdict exists, reported apart from the main step list. |
| Data-driven rows | data: / dataFile: |
Instantiates one scenario per row of an inline list or a CSV file, substituting ${row.*}. |
4.6 Interpolation: ${namespace.key}¶
One primitive (common/scenario/interp.py) backs every substitution that a scenario can make. A
flat bindings map, which the caller supplies, keys the lookups.
| Namespace | Source | Resolved |
|---|---|---|
params.* |
A component's with: block |
At component-expansion time, before the run starts. |
row.* |
A data-driven scenario's data: / dataFile: row |
At data-expansion time, before the run starts. |
secrets.* |
The target config's resolved secret values | At run time, from the Effective config (section 3). |
vars.* |
An extract step's captured value |
At run time, as the step loop executes — the one namespace that changes mid-run. |
4.7 Evidence capture: capturePolicy¶
A scenario's capturePolicy (common/scenario/models/evidence.py) names rules that the step loop
fires repeatedly, rather than a one-shot instruction. As a result, a second run collects the same
evidence with no AI involved. Each rule's on trigger is exactly one of three values: action (an
id-matched step just ran), event: screenChanged, or result: failure. The rule's capture list
names the artifact kinds to collect when the trigger fires. Evidence covers the full
mechanism, including the baseline capture guarantee that every step gets regardless of
capturePolicy.
5. Layers, and the boundary the gate enforces¶
The packages sort into three layers, and the gate checks the sort. make lint-imports runs
import-linter against layers declared in pyproject.toml,
so a forbidden import fails make check rather than surviving until someone notices.
| Layer | Members | Rule |
|---|---|---|
| Deterministic core | orchestrator/, runner/, drivers/base.py, assertions/, evidence/, report/, config/, scenario/, capability/ |
Must not import the periphery, and must stay free of the hosting extras. |
| Contract | scenario/ and drivers/base.py |
Must not import the runtime core, so a consumer can depend on the schema without pulling the runner in. |
| Periphery | serve/, mcp/, codegen/, agents/, ai/, record/, crawl/, triage/ |
Each removable behind an optional install extra. |
The core-must-not-import-periphery rule enforces prime directive 1 statically. A pure element-tree
helper that a core module needs lives in the core rather than in record/. The resolved AI
settings live in config/ as a plain AiConfig, so the core reads them without importing an AI
client. Architecture records the full contract
set.
6. What happens when a scenario runs¶
bajutsu run is the command every other Tier 2 path resembles. Following it once explains the
runner, the orchestrator, the driver layer, and the reporter together.
Mermaid source
sequenceDiagram
autonumber
participant CLI as run/cli.py
participant Pipe as runner/pipeline.py
participant Pool as runner/pool.py
participant Env as platform_lifecycle
participant Orch as orchestrator/loop.py
participant Drv as Driver backend
participant Sink as evidence FileSink
participant Rep as report/
CLI->>CLI: resolve config, load and expand scenarios
CLI->>Pipe: run_and_report(eff, scenarios, lease)
Pipe->>Pool: lease(eff, scenario)
Pool->>Env: boot device, install, launch app
Env-->>Pool: ready driver
Pool-->>Pipe: Lease(driver, sink, control, collector)
Pipe->>Orch: run_scenario(driver, scenario, sink, ...)
loop for each step
Orch->>Sink: capture pre-step baseline
Orch->>Drv: act — tap, type, swipe, ...
Orch->>Drv: wait for condition
Orch->>Orch: evaluate step assertions
Orch->>Sink: capture post-step evidence
end
Orch->>Orch: evaluate trailing expect block
Orch-->>Pipe: RunResult
Pipe->>Pool: lease.release()
Pipe->>Rep: manifest.json, JUnit, CTRF, HTML
The numbered walk below names the file behind each arrow.
- Resolve the configuration.
run/cli.pyreads the config file, overlays the target's block, and produces one frozenEffective. Command-line flags override the file. - Load and expand the scenarios.
common/scenario/load.pyparses each YAML file intoScenariomodels.expand.pythen resolves the compile-time constructs:use:macros expand into their component's steps, and a data-driven scenario becomes one instance per data row. - Select the backend.
common/backends.pypicks the actuator. Given several candidates it picks the cheapest one whose capability set covers the scenario's needs. - Lease a device.
common/runner/pool.pybounds concurrency and hands out aLease. TheLeasebundles the live driver with that device's evidence sink, relaunch function, device control, and network collector.common/platform_lifecycle/performs the platform-specific bring-up behind oneRunEnvironmentprotocol. The pool never branches on the backend name. - Run the scenario.
common/orchestrator/loop.pyexecutes the step list. Section 6.1 covers one step in detail. - Decide the verdict.
common/assertions/evaluate.pyevaluates every assertion. The function is total: it returns a failingAssertionResultrather than raising, so one bad assertion never aborts the run. - Write the report.
common/report/renders theRunResultlist into four files:manifest.json, a JUnit XML file, a Common Test Report Format (CTRF) JSON file, and a self-contained HTML page. The manifest is the single source of truth the other three derive from.
6.1 One step, from the inside¶
Each step follows the same three beats: act, then wait, then verify. The orchestrator captures evidence around the beats and guards the screen against interruptions between them.
Mermaid source
flowchart TB
start(["next step"]) --> interp["interpolate ${params}, ${vars}, ${secrets}"]
interp --> pre["capture pre-step screenshot + element tree"]
pre --> kind{"step kind"}
kind -->|"wait"| w["poll the condition until it holds<br/>no fixed sleep, ever"]
kind -->|"assert"| a["poll the assertions"]
kind -->|"action"| act["_do_action dispatches to<br/>the registered handler"]
w --> ok{"passed?"}
a --> ok
act --> ok
ok -->|"yes"| post["capture post-step evidence"]
ok -->|"no"| guard{"alert guard<br/>cleared a blocker?"}
guard -->|"yes, retry once"| kind
guard -->|"no"| fail["record the failure"]
post --> outcome["record StepOutcome"]
fail --> stop(["stop the scenario"])
outcome --> start
classDef det fill:#bfdbfe,stroke:#2563eb,color:#1f2937;
class w,a,act,post det
Two rules of the loop follow directly from prime directive 2, determinism first. A wait never sleeps for a fixed duration. It polls a condition until the condition holds or the budget expires. An ambiguous selector fails immediately rather than acting on whichever element matched first.
7. The classes, layer by layer¶
7.1 The scenario model¶
common/scenario/ holds
the authoring schema in models/ and the pipeline that turns text into runnable objects around it.
| File | Classes and functions | Job |
|---|---|---|
models/scenario.py |
Scenario, Component, ScenarioFile, Preconditions, SystemAlertHandling |
The top-level document and the per-scenario setup. |
models/steps.py |
Step, If, ForEach, Use, Web, Interrupt, CleanupRule, Extract |
One step, plus the control-flow and lifecycle wrappers. |
models/assertions.py |
Assertion, Exists, TextMatch, CountMatch, RequestMatch, VisualMatch, GoldenMatch |
The 15 assertion kinds. |
models/actions.py |
TypeText, Swipe, Scroll, HttpRequest, Generate, Email, Totp, and more |
One model per action's arguments. |
models/selector.py |
Selector |
The authoring selector, converted to the runtime one by as_selector(). |
load.py · load_expanded.py |
load_scenario_file, load_scenarios |
Parse YAML, check the schema version. |
expand.py |
expand_components, expand_data, apply_setups |
Resolve use: macros and data rows before the run. |
interp.py |
interpolate |
Substitute ${params.x}, ${row.x}, ${secrets.x}, and ${vars.x}. |
select.py · edit.py · serialize.py |
filtering, programmatic edits, YAML output | Support --only, triage's fixes, and the authoring paths. |
The split between compile time and run time matters. expand.py runs once, before the run touches
any device, so the step list the orchestrator sees holds no macros. The run loop never needs to
resolve a component mid-scenario.
7.2 The driver layer¶
common/drivers/base.py
is the determinism core and the one file worth reading in full. Beyond the Driver protocol, it
holds the resolution functions that every backend shares.
Mermaid source
classDiagram
class Driver {
<<Protocol>>
+query() list~Element~
+tap(sel)
+type_text(text)
+swipe(frm, to)
+wait_for(sel) bool
+screenshot(path)
+capabilities() set~str~
}
class CoordinateTreeDriver {
<<shared base>>
+transient-empty retry
+stable-key settle
+_resolve(sel)
}
class EvidenceProvider {
<<Protocol>>
+network_collector(mocks)
}
class ViewportProvider {
<<Protocol>>
+viewport() Point
}
class BackendLifecycle {
<<Protocol>>
+navigate()
+close()
+await_ready(timeout)
}
class XcuitestDriver {
iOS Simulator
resident on-device runner
}
class AdbDriver {
Android
resident UI Automator server
}
class PlaywrightDriver {
web browser
}
class XcuitestLiveDriver {
device cloud
W3C WebDriver
}
class FakeDriver {
in-memory, no device
}
Driver <|.. XcuitestDriver
Driver <|.. AdbDriver
Driver <|.. PlaywrightDriver
Driver <|.. XcuitestLiveDriver
Driver <|.. FakeDriver
CoordinateTreeDriver <|-- AdbDriver
PlaywrightDriver ..|> EvidenceProvider
XcuitestDriver ..|> ViewportProvider
AdbDriver ..|> ViewportProvider
BackendLifecycle ..> PlaywrightDriver : cast(), 3 of 5 hooks
BackendLifecycle ..> XcuitestDriver : cast(), 2 of 5 hooks
resolve_unique(elements, sel) carries prime directive 2 on its own. It narrows one query()
snapshot to exactly one element. No match raises ElementNotFound. Two content-distinct matches
raise AmbiguousSelector. The function never picks a winner by position on its own, because
acting on whichever element matched first is the flakiness the whole design exists to prevent. Only
an author's explicit index selects the nth of several content-distinct candidates, the documented
last resort (selectors).
Two refinements soften the rule without weakening it. Candidates reporting identical content
collapse to one, since nothing distinguishes them for an author to disambiguate on. A generic
other-trait wrapper drops out when a classified sibling shares its label.
Mermaid source
flowchart TB
q["query() — one screen snapshot"] --> fa["find_all(elements, sel)"]
fa --> w{"within given?"}
w -->|yes| ct["contains() — keep the nested candidates"]
w -->|no| n
ct --> n{"how many candidates?"}
n -->|none| e1["ElementNotFound"]
n -->|one| ok["the resolved element"]
n -->|two or more| dup["collapse content-identical candidates"]
dup --> ix{"still several?"}
ix -->|no| ok
ix -->|index given| ok
ix -->|no index| e2["AmbiguousSelector"]
ok --> cov{"the backend's cover check"}
cov -->|yes| e3["ElementNotTappable"]
cov -->|no| act["the backend performs the action"]
The cover check sits outside resolve_unique, in the backend, and takes one of two forms. A
backend with no native hit-test calls base.raise_if_covered on the resolved element.
AdbDriver, XcuitestLiveDriver, and FakeDriver share that document-order proxy.
PlaywrightDriver asks the browser instead, through document.elementFromPoint. Separating the
check from resolution keeps resolution a pure function of one snapshot. That leaves "something is
over it" a backend's answer, not a selector's.
Narrow optional protocols carry the capability differences between platforms. A fat interface
would force every backend to stub out methods it cannot support. Instead, base.py declares small
protocols such as EvidenceProvider, ViewportProvider, and ReadLagProvider. Four more follow:
ReadOrderProvider, SettledReadProvider, RawSourceProvider, and SettledCacheInvalidator. A
caller checks membership at runtime. A backend implements a narrow protocol purely when its
platform genuinely supports the behavior.
BackendLifecycle is the deliberate exception. The concrete drivers own disjoint subsets of its
five hooks. PlaywrightDriver implements navigate/close/reset_context. XcuitestDriver
implements await_ready/health_ready. Because the subsets are disjoint, none of the drivers
satisfies a structural isinstance. The platform_lifecycle environments reach each hook through
cast(BackendLifecycle, driver) instead. The protocol is a typing umbrella over the call sites,
not a conformance target.
FakeDriver deserves its own note. The in-memory backend lets the entire orchestrator run
without a device, which is why the deterministic gate runs on Linux in seconds and needs no
Simulator.
7.3 The environment layer¶
common/platform_lifecycle/
answers a question the driver deliberately does not: how does the app get onto a device and become
ready? protocols.py declares RunEnvironment and CrawlEnvironment, and environments/ supplies
one implementation per platform — ios, xcuitest, xcuitest_live, android, web, and fake.
The protocol covers bring-up (start), readiness, relaunch, device control, and teardown. It also
holds the per-platform answers to three questions that the runner needs:
- Whether the platform records video up front.
- Whether the platform observes network traffic through the driver.
- Whether the platform's resident runner survives between scenarios.
Because the answers live behind the protocol, runner/pool.py and crawl/cli.py drive iOS,
Android, and web through one interface rather than branching on the actuator name.
7.4 The runner¶
common/runner/ turns a
config plus a scenario list into a report.
| File | Key classes | Job |
|---|---|---|
pipeline.py |
_ScenarioRunner, run_all, run_and_report, run_matrix_and_report |
One run's shared context, applied to each scenario in turn. |
pool.py |
device_pool |
Bound concurrency, hand out leases, tear down cleanly. |
types.py |
Lease |
A live driver bundled with its sink, relaunch, control, and collector. |
device_provider.py |
DeviceProvider, DeviceLease, _LocalProvider, _AppiumProvider |
Where the run's devices come from: local, or a reserved cloud device. |
recovery.py |
RetryDecision, CrashRecoveryBudget, RunCrashRecoveryBudget |
Whether a crashed backend earns a retry, and how much wall-clock time recovery may spend. |
launch.py · launch_server.py |
launch_driver |
Build the driver and bring the app up. |
mailbox.py |
transport registry | Resolve the email step's transport by kind. |
_ScenarioRunner is a frozen dataclass that holds one run's shared context. The context covers
the resolved config, the lease factory, the redactor, the capability set, and the output knobs.
Freezing the dataclass and keeping every per-scenario value local to run_one lets
ThreadPoolExecutor workers share one instance safely when workers > 1.
Crash recovery sits beside the verdict, never inside it. A backend crash is infrastructure, not
a test result. recovery.py retries the scenario on a freshly leased device, up to a bounded count
and a bounded wall-clock budget. Once the budget runs out, the scenario fails loudly. The loud
failure keeps a genuinely crash-inducing scenario visible.
7.5 The orchestrator¶
common/orchestrator/
holds the step loop. loop.py is the largest file in the core, and its structure repays a moment.
| Class or function | Role |
|---|---|
run_scenario() |
The entry point. Starts the requested evidence intervals, runs the setup, main, and cleanup phases, evaluates the trailing expect, and assembles the RunResult. |
StepLoopState |
The mutable state one phase carries: the accumulated variable bindings, the previous step's element tree, and the read counters. |
_LoopConfig |
The frozen half: the driver, sink, clock, alert guard, and scenario. |
_StepRunner |
The dispatcher. exec_steps walks the list; _handle_if, _handle_for_each, _handle_web, and _handle_action handle each step shape. |
_run_step_body() |
One step's effect, returning (ok, reason, assertion_results, snapshot). Never raises for an expected failure. |
_InterruptGuard |
Fires a scenario's interrupts handlers when an interstitial screen appears mid-run. |
_ScreenRead |
A lazily cached element-tree read, so one step never queries the same screen twice. |
types.py holds the loop's vocabulary: StepOutcome, RunResult, AlertEvent,
AlertGuardConfig, SelectionState, and the Clock protocol, which lets tests run without real
sleeps. waits.py holds the polling machinery and WaitTrace. WaitTrace records a wait's poll
timeline, so a timeout stays diagnosable from the artifacts alone.
Mermaid source
flowchart LR
s(["wait starts"]) --> rd["read the screen, or the observed traffic"]
rd --> m{"condition met?"}
m -->|yes| ok(["the step continues"])
m -->|no| ag["alert guard — clear a system prompt"]
ag --> ig["interrupts — clear an interstitial screen"]
ig --> d{"past the deadline?"}
d -->|yes| to["fail — wait_diagnostic writes the WaitTrace"]
d -->|no| bo["_adaptive_sleep — the rest of the poll period"]
bo --> rd
Three details of that loop invite the opposite reading. The loop checks the condition before
the guards, so a satisfied wait never actuates anything. It checks the deadline last, which is
why the first read always happens. And _adaptive_sleep is no backoff: it sleeps out the rest of
a fixed poll interval. A query() backed by a device dump has often spent that interval already. Every
exit decides on the condition or the deadline, never on a fixed pause.
Action dispatch is a registry, not a conditional chain.
actions/_registry.py
derives the runtime action list from the Step model itself, so declaring a field on Step makes
the action visible automatically. Handlers live in actions/handlers/, grouped by theme, and
register themselves with an @_handler(kind) decorator. The themes are gestures, scroll,
device, navigation, http, generate, totp, and manual. The dispatcher also owns the
text-selection contract in one place. copy requires an active selection, select establishes
one, and every other action invalidates it. The contract keeps the handlers stateless across
backends.
7.6 Assertion evaluation¶
common/assertions/
holds the verdict, and holds nothing else. evaluate.py keeps one evaluator per kind behind an
@_evaluator("kind") decorator, mirroring the action registry. network.py matches request,
event, and requestSequence against observed traffic. visual.py compares images. schema.py
validates a response body. _common.py defines the shared AssertionResult.
Two properties matter more than the individual evaluators.
- Evaluation is total. It returns a failing result rather than raising, so a malformed assertion fails its own check without aborting the run.
EvalContextbundles the ambient inputs that an evaluator may need: the baseline directory for a visual comparison, the schema directory, the golden directory, and the clipboard. A step-levelassertdeliberately receives a narrowed context, since no fresh screenshot exists mid-step for a visual comparison to read.
7.7 Evidence¶
common/evidence/
answers what a run leaves behind.
core.pydeclares theEvidenceSinkprotocol with two implementations.NullSinkrecords nothing and costs nothing, and the run loop checks for it before paying for an extra query.FileSinkwrites artifacts under the run directory.intervals.pyruns the scenario-wide recordings — video and the device log — as child processes, started before the first step and finalized after verification. Every interval kind is opt-in, so a scenario requesting none records none.network.pyholdsNetworkExchange, the observed-request model both the in-app collectors and the Playwright hook produce, plus the deterministic in-protocol mocks.redaction.pyholdsRedactor, which masks secret values, configured labels, headers, and fields before anything reaches disk.visual.pyandgolden.pycompare a screenshot against a baseline image and an element tree against a recorded tree.
A scenario expresses evidence capture as a rule that fires repeatedly, not as a one-shot
instruction. Its capturePolicy names triggers, and the loop fires the matching rules at every
step, so a second run collects the same evidence with no AI involved.
7.8 Reporting¶
common/report/ renders
the RunResult list four ways.
manifest.pywritesmanifest.jsonand the JUnit XML.ctrf.pywrites the CTRF JSON.html.py,rows.py,panels.py, andrichtext.pybuild the interactive HTML page.
archive.py and load.py export a finished run as a .zip and reload it offline for
re-rendering. manifest.json is the single source of truth, and CI reads it rather than parsing
the HTML.
Mermaid source
flowchart LR
drv["Driver — screenshot · element tree · raw dump"] --> sink["EvidenceSink"]
net["in-app collectors — NetworkExchange"] --> sink
iv["Interval — video · device log"] --> sink
sink --> w["RunArtifactWriter — one write path, applies the Redactor"]
rr["the RunResult list"] --> wr["write_report — renders all four"]
subgraph dir["the run directory"]
art["per-step evidence"]
man["manifest.json — what CI reads"]
o1["junit.xml · ctrf.json · report.html"]
end
w --> art
wr --> man
wr --> o1
dir --> z["run .zip — archive_run_dir packs the directory"]
man -.->|"offline re-render"| o1
The shape closes two readings the prose invites. The four report files are siblings, not a
chain. write_report renders all four from the same in-memory RunResult list. CI reads the
manifest. The other three do not derive from it. The offline re-render alone reads it back. The two
writers also differ in reach. The per-step sink applies the scenario's redact rules. The report's
own writer carries secret literals alone. manifest.json lands without those rules, as
evidence states.
8. The Tier 1 paths: authoring and investigation¶
Three commands reach a model, and each keeps the model behind a narrow protocol so the deterministic core never sees it.
Mermaid source
classDiagram
class Agent {
<<Protocol>>
+next_action(Observation) Proposal
+plan(goal) list~str~
}
class Observation {
+list~Element~ elements
+bytes screenshot
+str goal
}
class Proposal {
+Step step
+str reasoning
+bool done
}
class AiBackend {
<<Protocol>>
+create_message(MessageRequest) MessageResponse
}
class ActionProposer {
<<Protocol>>
+propose(elements, screenshot, candidates) Proposal
}
class TriageAgent {
<<Protocol>>
+triage(TriageContext) Triage
}
class Triage {
+str summary
+str category
+list~str~ suggestions
+Fix fix
}
Agent <|.. ClaudeAgent
ClaudeBackedAgent <|-- ClaudeAgent
ClaudeBackedAgent ..> AiBackend
AiBackend <|.. AnthropicBackend
AiBackend <|.. ClaudeCodeBackend
ActionProposer <|.. ClaudeActionProposer
TriageAgent <|.. HeuristicTriageAgent
TriageAgent <|.. ClaudeTriageAgent
TriageAgent ..> Triage
Agent ..> Observation
Agent ..> Proposal
record/ authors a scenario from a natural-language goal.
loop.py runs observe →
propose → execute → emit:
- It reads the screen into an
Observation. - It asks the
Agentfor aProposal. - It executes the proposed
Stepthrough the same_do_actiondispatcher that the deterministic loop uses. - It appends the step to the growing scenario.
Reusing the dispatcher is what makes a recorded step replayable. capture.py covers the
proxy-actuation path, where a human drives the app and the recorder captures the resulting steps.
Mermaid source
flowchart LR
obs["read the screen — Observation"] --> ask["Agent.next_action"]
ask --> prop{"Proposal"}
prop -->|a Step| exec["_do_action — the deterministic dispatcher"]
prop -->|needs a person| hand["handoff"]
prop -->|goal reached| emit(["emit the scenario"])
exec --> app["append the step"]
app --> obs
hand --> obs
crawl/ explores an app breadth-first and emits a screen map.
core.py holds the graph
types Fingerprint, Node, Edge, Action, and ScreenMap, plus the _Coordinator that walks
them. A screen's Fingerprint decides whether the crawl has visited the screen before, so the walk
terminates. guide.py declares ActionProposer. It ships a deterministic implementation beside
the model-backed ClaudeActionProposer, which keeps a crawl runnable with no credentials at all.
triage/ investigates a failed run.
heuristic.py
assembles a TriageContext from the run directory, and HeuristicTriageAgent derives a Triage
from rules alone. Each Fix carries structure rather than prose, as in renameId, addIndex, and
raiseTimeout. The structure lets --apply rewrite the scenario and --rerun check the rewrite.
triage --ai swaps in ClaudeTriageAgent behind the same protocol. Triage is advisory in both
forms: it proposes an edit and never changes a verdict.
common/ai/ keeps the vendor behind one seam. AiBackend normalizes the request and response
types. registry.py maps a provider name onto an adapter:
anthropic.pyserves the Anthropic API and Amazon Bedrock.claude_code.pyserves the Claude Code command-line interface.- The
disabledprovider has a factory that raises, so no AI path can construct a backend by accident.
9. codegen, serve, mcp, and analysis¶
codegen/ turns a passing scenario into a native test.
common.py declares
the CodeGenerator protocol: file_preamble, scenario_open, step_lines, assertion_lines,
scenario_close, and file_footer. render_test_file walks the scenario once and calls the
protocol. Three emitters implement the protocol: xcuitest.py for Swift, playwright.py for
TypeScript, and uiautomator.py for Kotlin. A step whose behavior exists purely at run time raises
rather than emitting wrong code without a word.
serve/ is the browser application. state.py holds ServeState, the process-wide state
bundling the job registry, the session manager, the scenario store, and the provider settings.
routes.py declares the routes as data, so both the standard-library handler (handler.py) and the
FastAPI application (server/app.py) serve the same route table. The executor/ package declares
the RunExecutor seam, which hands a created job to whatever runs it. The server never runs a job
itself (BE-0449). bajutsu serve wires DbQueueExecutor, which enqueues every job for a
bajutsu worker. The worker runs the job through the body in jobs.py. A state built without a
queue gets UnqueuedExecutor. That executor fails each job at dispatch.
mcp/ exposes run and doctor as Model Context Protocol (MCP) tools and a run's evidence as
MCP resources, so an editor-side agent reaches the deterministic paths without a shell.
analysis/ holds the read-only advisory reports. None of them gates CI.
audit: a determinism and flakiness audit.coverage: identifier-namespace coverage.impact: which steps a diff affects.stats: run statistics in aggregate.flakiness: cross-run ranking.trace: one run's timeline.
10. Adding or changing a feature: the development and verification routine¶
10.1 Where to start, by kind of change¶
The map below turns the structure above into a starting point for the most common changes.
| Goal | Start here | Then |
|---|---|---|
| Support a new platform | common/drivers/ — a new class satisfying Driver |
Add a RunEnvironment under platform_lifecycle/environments/, register the actuator in backends.py, and run the driver conformance suite. |
| Add a step action | common/scenario/models/steps.py — a field on Step |
Add a handler in orchestrator/actions/handlers/, then an emitter arm in each codegen/ generator. |
| Add an assertion kind | common/scenario/models/assertions.py |
Add an evaluator in assertions/evaluate.py behind @_evaluator. |
| Add a config knob | common/config/schema.py, then effective.py |
Read it wherever the resolved Effective already reaches. |
| Add a CLI command | A cli.py beside the feature it belongs to |
Register it in cli/__init__.py's module list and classify it in capability/capabilities.py. |
| Add an evidence kind | common/evidence/core.py |
Extend the capturePolicy schema and the report renderer. |
Two rules hold across every row. A change on the verdict path must not reach an AI package, and the gate checks the rule mechanically. A change that adds behavior needs a test that would fail without it, since the deterministic suite is the regression net.
10.2 The development routine¶
Mermaid source
flowchart LR
branch(["Branch or worktree<br/>claude/<topic>"])
implement["Implement the change<br/>inside one layer"]
test["Add or update a test"]
fast["Fast checks<br/>format · lint · typecheck · test"]
gate{"make check<br/>green?"}
verify["Verify beyond the suite<br/>conformance suite · on-device · make docs"]
preflight["make preflight<br/>fetch + rebase + the gate"]
push["Push<br/>pre-push hook re-runs make check"]
noverify(["git push --no-verify<br/>forbidden, no exceptions"])
pr["Open the pull request"]
ci{"CI"}
done(["Merged"])
branch --> implement --> test --> fast --> gate
gate -->|no| implement
gate -->|yes| verify --> preflight --> push --> pr --> ci
push -.->|never| noverify
ci -->|red| implement
ci -->|green + reviewed| done
classDef det fill:#bfdbfe,stroke:#2563eb,color:#1f2937;
classDef warn fill:#fecaca,stroke:#dc2626,color:#1f2937;
class gate,ci det
class noverify warn
- Isolate the session. Branch off
mainasclaude/<topic>(a human contributor:<user>/<topic>).make worktree TOPIC=<topic>builds the branch and its worktree in one step, so two sessions never share a checkout. Claude Code keeps its own worktrees under.claude/worktrees/. - Implement the change, staying inside the layer that section 5's table points to. A change
that reaches across the boundary fails
make lint-importsimmediately rather than merging unnoticed. The deterministic core importing the periphery is one example. - Add or update a test alongside it. The deterministic suite (
tests/) is the regression net. A change with no test that would fail without it is not yet done.tests/driver_conformance.pyis the one spec that every backend's tests share, a technology compatibility kit (TCK) for theDriverprotocol. A new backend implementsConformanceHarnessonce and inherits the whole suite rather than writing its own. - Run the fast checks while iterating, rather than the full gate on every save.
make format,make lint,make typecheck, andmake testeach check one thing and finish quickly.make checkruns all of them plus the slower structural checks (import layering, docstrings, the roadmap, secret scanning) in the same order that CI does. "Green locally" is meant to predict "green in CI". - Verify manually beyond the test suite for anything that touches a driver, a backend, or a diagram. Section 10.3 below says which command to run, by what changed.
- Rebase before pushing.
make preflightfetchesorigin/main, rebases onto it, runs the gate, and prints a "definition of done" reminder. The command is the do-it-early version of what the pre-push hook enforces anyway. A conflict or a red check surfaces before it costs a round trip. - Push, then open a pull request (PR). The tracked pre-push hook runs
make checkbefore every push and refuses a red one.git push --no-verifyis forbidden, without exception, since it merely moves the same red result onto the shared PR instead of catching it locally. The kind of work decides whether the session or a human opens the PR, and whether the PR opens Draft or Ready for review. SeeCLAUDE.md's "Who opens the PR depends on the work" and "PRs created by Claude Code always start as Draft". The full parallel-development picture (rebase discipline, git defenses, worktree isolation) is AI development.
10.3 Verification, by what you touched¶
| What you touched | Fast check | Fuller verification |
|---|---|---|
| The scenario schema, a step action, or an assertion | make test (FakeDriver-backed unit tests, no device needed) |
tests/orchestrator/ and tests/scenario/ cover the step loop and the model; add a scenario under scenarios/ for an end-to-end example if the change needs one. |
| A driver or a backend | uv run pytest tests/test_driver_conformance.py — the shared conformance contract, run against FakeDriver on the fast gate |
An on-device pass: make -C demos/showcase run-swiftui (needs make deps first, macOS and a Simulator) for iOS; uv run bajutsu run --backend web --target web --config demos/web/demo.config.yaml for the web track, which needs no Mac. |
| Config schema or resolution | make test |
uv run bajutsu doctor --target <name> --config <path> against a real config, to see the resolved Effective the change produces. |
| A CLI command | make test |
Run the command by hand against a fixture config; capability/capabilities.py's own test asserts every registered command is classified. |
| Documentation, including a diagram | make lint-roadmap, textlint (tools/textlint/) |
make docs (mkdocs build --strict); a changed mermaid fence needs make docs-diagrams to re-render its checked-in SVG, the convention this page's own diagrams follow. |
Coverage ratchets alongside the change, not after it. make lint-pr flags when measured coverage
drifts more than two points above the total floor. make coverage-floors raises the per-file
snapshot (coverage-floors.json) once a file's coverage has genuinely risen. The command is the
deliberate, reviewable way to record a gain, never a way to paper over a drop.
11. Further reading¶
- Architecture — the module table, the dependency layers, and the implementation status of everything the design describes.
- Run loop — the deterministic runner's semantics in depth.
- Drivers — each backend's platform seam and capability set.
- Selectors — deterministic resolution, the determinism core in detail.
- Scenarios and DSL grammar — the authoring reference and the normative grammar.
- API reference — generated from the docstrings and typed signatures.
DESIGN.md— the design rationale, in Japanese.