| name | verification-protocol |
| description | Mandatory end-to-end verification for .NET MAUI and Comet app tasks. Enforces dependency ownership — broken tools and missing config are YOUR problem to fix, not blockers to report. USE FOR: any task touching UI, pages, navigation, services, or app behavior. Triggers: after code changes, before marking todos done, when reporting task results, when a tool fails. DO NOT USE FOR: documentation-only changes, squad config edits, or build system changes that don't affect the running app.
|
Verification Protocol
Verification means proving that code changes produce the intended result on a real device,
against reference material, through interactive exercise — not just proving they compile.
A fresh binary is built and deployed, the UI is inspected via DevFlow visual tree, navigation
is exercised interactively, features are tested with real inputs, and results are compared
against the original BaristaNotes app code and reference screenshots. A broken tool in this
chain is a problem to solve, not a reason to skip a step.
No task is done until verified on device. "It builds" is not done. A screenshot of a stale
binary is not done.
Rule 1: Own Your Dependencies
When a tool or dependency is broken, fix it. The solution is in the repo, the reference
code, or the documentation you were given.
| Problem | Wrong | Right |
|---|
| DevFlow won't connect | "⚠️ Skipped — agent didn't connect" | Diagnose: maui-devflow diagnose. Check csproj integration, broker status, entitlements, ports. Fix the issue. DevFlow source is in this repo — build a custom version if needed. |
| API key missing | "⚠️ Needs API key" | Read the reference app's code. It shows exactly how to source the key (IConfiguration, appsettings.json, env vars). Do what it does. |
| Simulator issue | "⚠️ No simulator available" | xcrun simctl create "Verify" "iPhone 16 Pro" then boot it. |
| Build fails on iOS TFM | "✅ Builds on Release" | Fix the iOS Debug build. That's the one that deploys. |
If you report "blocked" and the answer is in the repo — that is a failure.
Rule 2: Verify Against Reference
When reference material exists (original app code at ~/work/BaristaNotes, screenshots at
~/Downloads/baristanotes-screenshots/), compare your result against it. Do not check if
"it looks reasonable."
Rule 3: Verify the Specific Change
Generic verification is not verification. After completing all levels, explicitly test the
exact behavior your task was supposed to produce or fix:
- Added a page? → Navigate to it, confirm its controls, interact with its inputs.
- Fixed a crash? → Reproduce the original crash trigger. Confirm no crash.
- Changed a feature? → Exercise that feature with real data. Compare to reference.
If your report doesn't mention the specific thing you changed, it's incomplete.
Rule 4: Confirm Fresh Binary
Before accepting any on-device result:
dotnet clean then dotnet build — stale binaries lie.- If a deleted page still appears, the binary is stale. Rebuild.
- Use
maui-devflow MAUI platform app-info to verify build timestamp.
Verification Levels
Complete ALL levels L1–L4 for every task that touches the running app. L5 applies when the
task involves a feature listed in L5. Never skip because a tool is "unavailable" — fix the tool.
L1 Build — dotnet build on target TFM in Debug config (that's what deploys), 0 errors. If framework was modified, run dotnet test.
L2 Deploy — App launches on device/simulator. No runtime crash. Binary confirmed fresh.
L3 Inspect — DevFlow connected (maui-devflow wait). Visual tree dumped (MAUI tree --depth 15). Screenshot taken (MAUI screenshot). Compared against reference screenshots.
L4 Interact — All tabs navigated. Forms accept input (MAUI fill). Buttons tappable (MAUI tap). Push/pop navigation works. Data persists after save.
L5 Feature — Dark mode toggle renders correctly. AI features work with configured credentials. Filters produce correct results. Empty states display.
Reporting
Every verification report MUST use this exact template. Fill in every field — blank fields mean
unverified levels. The coordinator uses these fields to decide if the task is done.
✅ VERIFIED — {name}
Task: {what was changed and why}
Task-specific test: {exact steps taken to confirm the change works}
L1 Build: {0 errors | N errors} ({TFM}, Debug)
L2 Deploy: {launched on device/sim} | Binary: {fresh — built HH:MM}
L3 Inspect: DevFlow {connected port NNNN | FAILED — see diagnostics}
Tree: {key controls confirmed — list 3-5 specific elements}
Screenshot: {path}
Reference comparison: {specific differences or "matches reference"}
L4 Interact: {navigation paths tested, inputs filled, buttons tapped}
L5 Feature: {tested | N/A — not in scope because: reason}
Platform: {device/simulator model, OS version}
Commit: {short SHA or branch name}
Known deviations: {intentional differences from reference, or "none"}
Why every field matters:
L3 Inspect > Tree catches invisible issues (missing bindings, wrong control types) that screenshots missBinary: Fresh prevents the #1 verification failure: testing stale codeKnown deviations prevents the coordinator from filing bugs for intentional changesPlatform enables reproducing issues on the same device
Never report ⚠️ BLOCKED, ⚠️ SKIPPED, or ⚠️ CONDITIONAL PASS. Those mean you
didn't own the problem. If you have genuinely exhausted all options (built DevFlow from
source, tried platform-native alternatives, spent >30 minutes diagnosing), report
❌ FAILED — {name} with a full diagnostic log of everything you tried, and escalate
to the human operator. This should be rare — the answer is almost always in the repo.
