| name | build-loop:ibr-bridge |
| description | Routing bridge to the IBR plugin for UI visual verification. Build-loop prefers IBR `scan` / `scan_macos` when the IBR plugin is installed; otherwise falls back to build-loop's own `native-ax-driver` / `ui-validator`. Never falls back to nm/strings. NOT for API registration (use `api-registry-bridge`) or PRD grounding (use `prd-bridge`). |
| version | 0.3.0 |
| user-invocable | false |
IBR Bridge (Primary-When-Present, Native-Fallback)
Build-loop routes UI visual verification through IBR when the IBR plugin is installed, and through its own native verifiers when it isn't. There is no third path — nm/strings/git grep over symbols never satisfies the visual-evidence gate (enforced by skills/build-loop/scanners/require-visual-evidence.mjs at chunk-close and Phase 4-B).
The previous "explicit-only" policy was reversed 2026-06-04 because it left the macOS path without a default visual verifier in projects that didn't have IBR — the symbol-only escape hatch then carried briefs past the (prose-only) verify mandate.
Routing rule
At Phase 1 Assess, the orchestrator reads state.json.availablePlugins.ibr (populated by detect-plugins.mjs).
| Build-loop need | Primary (when availablePlugins.ibr == true) | Fallback (when IBR absent) |
|---|
| Web UI verify | IBR scan against the dev-server route | ui-validator agent + browser/screenshot tooling |
| macOS UI verify | IBR scan_macos against the running .app | native-ax-driver (skills/native-ax-driver/) pid-anchored AX-tree + screenshot |
| iOS sim UI verify | IBR scan against the booted sim (when supported) | xcrun simctl io booted screenshot + idb ui for interaction |
| Visual-evidence at chunk-close | Whichever of the above ran | (same) |
Subagent dispatch briefs MAY name IBR scan / scan_macos as the verifier — BUT only after the orchestrator has confirmed availablePlugins.ibr == true. When it is false, the brief MUST name the native-fallback verifier instead (per the [ME] guardrail in agents/build-orchestrator.md §"Phase 3 Execute" — never name a tool the implementer can't reach).
Allowed scope
When the bridge is the primary route (IBR present):
- Run
scan / scan_macos against the running app or dev-server route, capture the result envelope, and pass it forward as the chunk's evidence_paths / verification text.
- Use IBR token / design-system checks as comparison input.
- Run a project-authored
.ibr-test.json suite.
- Generate
.ibr-test.json drafts only when the build's plan explicitly authorizes IBR test generation.
When the bridge is the fallback route (IBR absent):
- Skip with a one-line note (
ibr: not installed; falling back to native-ax-driver / ui-validator); do NOT write to .ibr/.
- Do NOT install or download IBR mid-build.
Forbidden
- Do NOT fall back to
nm / strings / git grep over compiled symbols as UI verification. The BL-1 gate (scanners/require-visual-evidence.mjs) rejects this with exit 2 and routes the chunk back to Iterate.
- Do NOT invoke IBR viewer / dashboard / UI surfaces from build-loop.
- Do NOT write
.ibr/ unless the build's plan or the user's request requires an IBR output directory.
Output contract
The bridge returns results in the same envelope shape regardless of which route fired:
{
"status": "ran | skipped | failed",
"route": "ibr | native | fallback-skipped",
"verifier": "scan_macos | scan | native-ax-driver | ui-validator | none",
"artifacts": ["path-or-url-or-pid-anchor"],
"verification": "<freeform text suitable for the BL-1 gate envelope>",
"findings": [{"severity": "info|warn|blocker", "message": "..."}]
}
The orchestrator forwards verification and artifacts to the BL-1 gate envelope as the chunk's verification and evidence_paths fields.
Status: 0.3.0 (2026-06-04)
- Reversed the explicit-only default. IBR is now the preferred primary when present; build-loop-owned
native-ax-driver / ui-validator is the always-available fallback.
- The bridge stays
user-invocable: false because it's part of the orchestrator's verify-path routing, not a manual user command.
- Canonical build-loop design and validation artifacts remain
.build-loop/app-contract/*, ui-validator envelopes, and Review-G outputs whichever route fires.
