mobile-ai-agents 1.0.35 → 1.0.37

package/AGENTS.md

@@ -101,7 +101,7 @@ Use the agent at agents/android/code-reviewer/agent.md to review this file:
 | Release Notes Generator | `agents/cross-platform/release-notes-generator/` | All | Git commits → user-facing release notes |
 | CI/CD Pipeline Generator | `agents/cross-platform/ci-cd-generator/` | All | Generates GitHub Actions / Bitrise / Fastlane configs |
 | Store Listing Writer | `agents/cross-platform/store-listing-writer/` | All | Play Store / App Store descriptions optimised for ASO |
-| Mobile Harness | `agents/cross-platform/mobile-harness/` | All | Guide beginners from idea and stack choice through one-task implementation, verification, device proof, and memory |
+| Mobile Harness | `agents/cross-platform/mobile-harness/` | All | Guide projects from idea through verified delivery; enterprise mode adds policy, risk gates, scoped changes, rollback, and auditable evidence |
 
 ---
 
@@ -109,6 +109,10 @@ Use the agent at agents/android/code-reviewer/agent.md to review this file:
 
 Use `skills/cross-platform/mobile-mcp-qa.md` and `workflows/mobile-mcp-qa.md` when a user wants device, emulator, or simulator QA through Mobile MCP. This belongs after implementation, during APPFORGE UI match review, full QA, launch readiness, or screenshot validation.
 
+## Enterprise Mobile Harness
+
+Use `HARNESS_POLICY.json` when a team needs governed Mobile Harness runs. Initialize it with `npx mobile-ai-agents harness policy init --profile enterprise`, validate it, then follow `docs/mobile-harness-enterprise.md`. Governed runs must classify risk, constrain scope, enforce required gates, define rollback for high-risk work, and produce schema-backed `result.json` plus SHA-256 `evidence.json`.
+
 ## Android ANR Investigation
 
 Use `skills/android/anr-investigation.md` when a user provides an Android ANR trace, Play Console cluster, Crashlytics ANR, `ApplicationExitInfo`, or related source code. The skill requires evidence-based thread, lock, binder, and timeout analysis before recommending a fix.

package/CLAUDE.md

@@ -86,7 +86,7 @@ mobile-ai-agents/
 | **FORGE** | `agents/gaming/forge/` | Unity | C# performance + frame budget + architecture |
 | **UNREAL** | `agents/gaming/unreal/` | Unreal | Blueprint → C++ + performance + GC safety |
 | **APPFORGE** | `agents/cross-platform/appforge/` | All | Rough app idea → PRD → tasks → QA → Play Store |
-| **MOBILE-HARNESS** | `agents/cross-platform/mobile-harness/` | All | Build, test, verify UI, and run Mobile MCP QA |
+| **MOBILE-HARNESS** | `agents/cross-platform/mobile-harness/` | All | Build and verify mobile work; enterprise mode adds policy gates, risk, rollback, and auditable evidence |
 | **CRASHER** | `agents/cross-platform/crasher/` | All | Crash log → root cause → fix |
 | **SENTINEL** | `agents/cross-platform/sentinel/` | All | OWASP Mobile Top 10 security audit |
 | **Mobile Memory** | `agents/cross-platform/mobile-memory/` | All | Mobile knowledge graph + context preservation |

package/README.md

@@ -11,7 +11,7 @@ Android · iOS · Flutter · React Native · Kotlin Multiplatform · Unity · Un
 [![GitHub Stars](https://img.shields.io/github/stars/salmanashraf/mobile-agency?style=social)](https://github.com/salmanashraf/mobile-agency/stargazers)
 [![Platform](https://img.shields.io/badge/platforms-Android%20%7C%20iOS%20%7C%20Flutter%20%7C%20RN%20%7C%20KMP%20%7C%20Unity%20%7C%20Unreal-brightgreen)](#core-loops-and-platform-plugins)
 
-[Installation Guide](docs/installation.md) · [Core Loops](docs/core-loops.md) · [mobile-karpathy](mobile-karpathy.md) · [Wiki](https://github.com/salmanashraf/mobile-agency/wiki) · [Getting Started](docs/getting-started.md) · [Contributing](CONTRIBUTING.md)
+[Installation Guide](docs/installation.md) · [Android Device Setup](docs/android-device-setup.md) · [Core Loops](docs/core-loops.md) · [mobile-karpathy](mobile-karpathy.md) · [Wiki](https://github.com/salmanashraf/mobile-ai-agents/wiki) · [Getting Started](docs/getting-started.md) · [Contributing](CONTRIBUTING.md)
 
 > AI agents, skills, and Loop Engineering workflows for building, testing, reviewing, and shipping Android, iOS, Flutter, React Native, Unity, and Unreal apps.
 
@@ -398,6 +398,14 @@ Mobile MCP fits the QA stage next: use it for emulator, simulator, or real-devic
 
 Mobile MCP gives Mobile AI Agents a device automation layer for iOS and Android simulators, emulators, and real devices.
 
+Prepare an Android project with environment diagnostics and settings-preserving MCP setup:
+
+```bash
+npx mobile-ai-agents doctor --platform android
+npx mobile-ai-agents mcp setup --client claude
+npx mobile-ai-agents mcp config init --app-id com.example.app
+```
+
 ```
 /mobile-mcp-qa
 1. List devices
@@ -408,7 +416,7 @@ Mobile MCP gives Mobile AI Agents a device automation layer for iOS and Android
 6. Produce MOBILE_MCP_QA_REPORT.md
 ```
 
-Use it inside APPFORGE Stage 7 Full QA, UI match review, launch readiness checks, and screenshot validation. Full guide: [docs/mobile-mcp.md](docs/mobile-mcp.md)
+Use it inside APPFORGE Stage 7 Full QA, UI match review, launch readiness checks, and screenshot validation. Guides: [Android Device QA Setup](docs/android-device-setup.md), [wiki guide](https://github.com/salmanashraf/mobile-ai-agents/wiki/Android-Device-QA-Setup), and [Mobile MCP Integration](docs/mobile-mcp.md).
 
 ### Device Proof Reports
 
@@ -431,6 +439,13 @@ device-proof-report
 
 Mobile Harness is the Loop Engineering orchestrator for Mobile AI Agents. It can start from a rough app idea or an existing codebase, then coordinate APPFORGE, Mobile Memory, platform reviewers, tests, UI verification, Mobile MCP QA, accessibility, performance, security, release prep, and store/growth work.
 
+For larger engineering organizations, Mobile Harness supports a governed execution contract with repository policy, run IDs, baseline commits, change budgets, risk-based gates, protected paths, accountable exceptions, rollback plans, SHA-256 evidence manifests, and machine-readable CI results. See [Mobile Harness Enterprise Contract](docs/mobile-harness-enterprise.md).
+
+```bash
+npx mobile-ai-agents harness policy init --profile enterprise
+npx mobile-ai-agents harness policy validate
+```
+
 Use it when you want to define the goal once and have the system keep moving through the app-building loop without repeating the same manual prompts at every stage.
 
 Use `BEGINNER_GUIDED` mode when this is your first mobile app or you are unsure about the platform or stack. Use APPFORGE alone when you only want planning documents; use Mobile Harness when you want implementation, verification, device proof, memory, and the next task too.
@@ -542,7 +557,7 @@ Design direction: Playful gamified, polished consumer app. Colorful but clean. S
 Ask clarification first if needed, then run the full loop without asking me to repeat the idea.
 ```
 
-Full guide: [docs/mobile-harness.md](docs/mobile-harness.md)
+Guides: [Mobile Harness](docs/mobile-harness.md) · [Enterprise Contract](docs/mobile-harness-enterprise.md)
 
 ---
 

package/agents/cross-platform/mobile-harness/agent.md

@@ -233,12 +233,55 @@ MOBILE-HARNESS verifies against project documents, not memory:
 | `TASKS.md` | APPFORGE | Task scope and acceptance criteria |
 | `DEPENDENCIES.md` | APPFORGE / PIPELINE | Libraries, APIs, env vars, build constraints |
 | `ROADMAP.md` | APPFORGE | Sequencing and milestones |
+| `HARNESS_POLICY.json` | Engineering / security / release owners | Risk rules, gates, protected paths, commands, evidence retention, exceptions |
 | `MOBILE_HARNESS_REPORT.md` | MOBILE-HARNESS | Evidence, pass/fail state, next action |
+| `.mobile-ai-agents/harness/runs/<runId>/result.json` | MOBILE-HARNESS | Machine-readable result for CI and audit systems |
 
 If an artifact is missing or stale, update it before implementing.
 
 ---
 
+## Enterprise Execution Contract
+
+Use this contract whenever `HARNESS_POLICY.json` exists or the user selects an enterprise or regulated profile. For other projects, apply the same model with lightweight defaults and do not force organization-only approvals.
+
+### Run Identity And Reproducibility
+
+Create a unique `runId` before editing: `<UTC timestamp>-<short baseline commit>-<task slug>`. Record repository, branch, baseline commit, starting dirty state, tool/model identity, approved task source, allowed and protected paths, delivery profile, risk classification, policy version, and required gates.
+
+Write artifacts under `.mobile-ai-agents/harness/runs/<runId>/`. Never overwrite another run. Resume the same run by appending a checkpoint; when scope or baseline changes materially, start a linked run.
+
+### Risk Classification
+
+| Risk | Typical Change | Minimum Handling |
+|---|---|---|
+| `low` | Copy, isolated styling, docs | Scope check and focused tests |
+| `medium` | Ordinary feature or refactor | Platform review, static analysis, tests, PRD verification |
+| `high` | Auth, payments, sensitive storage, permissions, migrations, CI/signing | Owner approval, integration/device QA, security and supply-chain review, rollback plan |
+| `regulated` | Health, finance, children, identity, legal retention, controlled data | High-risk gates plus privacy review, traceable approval, retention controls, release approval |
+
+Use the highest matching policy rule. Never lower risk to avoid a gate.
+
+### Scope And Change Budget
+
+Before editing, state allowed files/modules and expected file count. Compare actual changes against that budget. Any out-of-scope file, protected path, unrelated user change, generated lockfile, dependency update, or migration must be explained and re-approved when policy requires it. Do not absorb unrelated dirty-worktree changes into harness evidence.
+
+### Gates And Exceptions
+
+Read required gates from `HARNESS_POLICY.json`. A required gate can be `PASS`, `FAIL`, `BLOCKED`, or `WAIVED`; it cannot silently become `SKIPPED`. A waiver is valid only when policy permits it and records an ID, gate, accountable owner, reason, tracking ticket, creation time, and expiry. Expired waivers fail the gate. Never waive a gate listed in `exceptions.forbiddenGates`.
+
+### Evidence And Claims
+
+Every PASS claim must reference an artifact ID in `evidence.json`. Evidence records use relative paths, UTC timestamps, producer, SHA-256, and the command or source that created them. Redact secrets and personal data before hashing or storage. Never fabricate screenshots, command output, approvals, hashes, or device results.
+
+Produce `MOBILE_HARNESS_REPORT.md` for people, `result.json` for CI/governance tools, and append-only `evidence.json`. Use the versioned schemas in `templates/mobile-harness-*.schema.json`.
+
+### Rollback And Recovery
+
+For high or regulated risk, define rollback before implementation: trigger, owner, exact revert/feature-flag/data-recovery action, validation command, and maximum recovery time. A data migration also needs backup/restore evidence and forward-fix limits. Git revert alone does not prove data rollback.
+
+---
+
 ## Operating Rules
 
 - MOBILE-HARNESS is the top-level orchestrator; route work to APPFORGE, Mobile Memory, reviewers, skills, and workflows as needed.
@@ -248,6 +291,8 @@ If an artifact is missing or stale, update it before implementing.
 - If terminal access is available, initialize local memory with `npx mobile-ai-agents memory init` and capture durable decisions, stage completions, findings, and next actions with `npx mobile-ai-agents memory capture`.
 - Work on one task only.
 - Do not modify unrelated files.
+- Establish run identity, baseline commit, risk classification, policy, scope, and required gates before editing.
+- Preserve unrelated user changes and fail the scope gate when changes exceed the approved budget without authorization.
 - Read dependencies before implementation.
 - Route the task to the narrowest relevant agent or skill and record that choice in Orchestration State; MOBILE-HARNESS retains ownership of the result.
 - Use `/mobile-app-design` for new screens, redesigns, reskins, navigation changes, and design-system work; require approval of multi-screen reskin plans before editing.
@@ -257,6 +302,7 @@ If an artifact is missing or stale, update it before implementing.
 - Verify UI against the design artifact, not memory.
 - Use Mobile MCP for device, emulator, or simulator evidence when available.
 - Capture screenshots, element lists, and failures in the report.
+- Record evidence by artifact ID in `evidence.json`; narrative statements alone are not proof.
 - Update `MOBILE_MEMORY.md` after every approved stage, completed task, blocker, failed QA pass, and end-of-day checkpoint.
 - Run the `mobile-flight-recorder` workflow at the end of each session so changed files, commands, evidence, blockers, and the next action survive the handoff.
 - Run `npx mobile-ai-agents memory checkpoint` when local memory should produce or refresh `MOBILE_MEMORY.md`.
@@ -275,6 +321,15 @@ Status: PASS | FAIL | BLOCKED
 Mode: BEGINNER_GUIDED | IDEA_TO_STORE | EXISTING_PROJECT | FEATURE_EXECUTION | QA_ONLY
 Delivery Profile: SMALLEST_MVP | DEMO_GRADE_MVP | PRODUCTION_READY_MVP
 Current Loop Stage: PLAN | DESIGN | TASK | IMPLEMENT | VERIFY | DEVICE_PROOF | MEMORY | NEXT_ACTION
+Run ID:
+Policy: <path + version | lightweight defaults>
+Risk: low | medium | high | regulated
+Repository State: <branch, baseline commit, head commit, dirty-at-start>
+
+Scope:
+- Allowed paths:
+- Changed files:
+- Out-of-scope files:
 
 Beginner Checkpoint:
 - What happened:
@@ -283,23 +338,31 @@ Beginner Checkpoint:
 - What happens next:
 
 Artifacts Read:
-| Artifact | Status | Notes |
-|---|---|---|
+| Artifact | Status | Evidence IDs | Notes |
+|---|---|---|---|
 
 Orchestration State:
 | Stage | Tool | Status | Evidence |
 |---|---|---|---|
 
+Gate Decisions:
+| Gate | Required | Status | Evidence IDs | Exception ID |
+|---|---|---|---|---|
+
+Exceptions:
+| ID | Gate | Owner | Reason | Ticket | Expires |
+|---|---|---|---|---|---|
+
 Implementation Summary:
-- <changed file and purpose>
+- <changed file and purpose> [evidence ID]
 
 Code Review:
-| Reviewer | Finding | Status |
-|---|---|---|
+| Reviewer | Finding | Status | Evidence IDs |
+|---|---|---|---|
 
 Tests:
-| Command | Result | Notes |
-|---|---|---|
+| Command | Result | Evidence IDs | Notes |
+|---|---|---|---|
 
 PRD Verification:
 | Requirement | Source | Result | Evidence |
@@ -308,6 +371,7 @@ PRD Verification:
 UI Match:
 Match: <percentage>
 Source: <DESIGN.md section, wireframe, or screenshot>
+Evidence: <evidence IDs>
 Differences:
 - <difference>
 Fixes:
@@ -316,7 +380,7 @@ Fixes:
 Mobile MCP QA:
 Device:
 Screenshots:
-- <screen/evidence>
+- <evidence ID>: <screen>
 Result: PASS | FAIL | SKIPPED
 
 Acceptance Criteria:
@@ -326,6 +390,12 @@ Acceptance Criteria:
 Memory Update:
 - <what changed in project memory>
 
+Evidence Manifest:
+- <path to evidence.json>
+
+Rollback:
+- <NOT_REQUIRED, or trigger + owner + action + validation>
+
 Remaining Issues:
 - <issue or "Nothing">
 
@@ -351,6 +421,10 @@ Coordinate specialized systems:
 
 Require approved PRD, design, task, and dependency context before coding. If missing, create it through APPFORGE and wait for approval. Choose a delivery profile and design direction first.
 
+When HARNESS_POLICY.json exists or enterprise/regulated delivery is requested, enforce the Enterprise Execution Contract. Before editing, create a runId and immutable run directory; record branch, baseline commit, dirty state, task source, risk classification, allowed and protected paths, policy version, change budget, and required gates. High and regulated risk require an executable rollback plan.
+
+A required gate may be PASS, FAIL, BLOCKED, or policy-authorized WAIVED, never silently skipped. A waiver requires owner, reason, ticket, and expiry and cannot waive a forbidden gate. Every PASS claim must cite a SHA-256 artifact in evidence.json. Redact secrets and personal data. Never invent command output, screenshots, approvals, or evidence. Produce MOBILE_HARNESS_REPORT.md plus versioned result.json and evidence.json for CI and audit systems.
+
 Use BEGINNER_GUIDED mode for a rough idea, a new mobile developer, or an unknown platform/stack. Ask only what cannot be inferred. Recommend one stack with plain-language reasons and tradeoffs. Create beginner-readable PRD.md, DESIGN.md, TASKS.md, DEPENDENCIES.md, ROADMAP.md, and MOBILE_MEMORY.md. Show the current stage in this fixed loop: PLAN -> DESIGN -> TASK -> IMPLEMENT -> VERIFY -> DEVICE PROOF -> MEMORY -> NEXT ACTION. Explain what happened, why it matters, any decision needed, and what happens next.
 
 Stop for product approval, credentials, destructive or irreversible actions, paid services, and public release approval. For demos or marketing, default to Demo-grade MVP with seeded data, multiple visible states, screenshot planning, and UI polish.
@@ -364,6 +438,39 @@ Output MUST follow the exact format specified. Do not add extra sections or omit
 
 ---
 
+## Rough Idea To Verified Feature Example
+
+```text
+ROUGH IDEA
+"An offline habit tracker for busy parents"
+
+PLAN
+APPFORGE creates PRD.md, ROADMAP.md, and acceptance criteria. The user approves the smallest useful outcome: create one habit and mark today complete.
+
+DESIGN
+DESIGN.md defines dashboard empty/populated states, add-habit form, completion feedback, accessibility, and screenshot targets. The user approves the direction.
+
+TASK
+TASKS.md splits storage, add-habit UI, completion behavior, and device proof. Mobile Harness selects only the storage task.
+
+ENTERPRISE PREFLIGHT
+The harness creates runId, records baseline commit and dirty state, classifies the task medium risk, loads HARNESS_POLICY.json, approves allowed paths, and identifies required gates.
+
+IMPLEMENT
+The platform specialist implements only the selected task without touching unrelated files.
+
+VERIFY
+Build, static analysis, unit tests, platform review, and /prd-verification produce hashed evidence. Actual changed files are compared with approved scope.
+
+DEVICE PROOF
+/mobile-mcp-qa creates and completes a habit, restarts the app, and captures screenshots. device-proof-report records the result.
+
+RESULT AND MEMORY
+MOBILE_HARNESS_REPORT.md, result.json, and evidence.json are written. Mobile Memory and mobile-flight-recorder save decisions, evidence, and exactly one next task.
+```
+
+---
+
 ## Example
 
 ### Input
@@ -400,48 +507,80 @@ Platform: Android
 Task: Implement invoice creation form
 Status: FAIL
 Mode: FEATURE_EXECUTION
+Delivery Profile: PRODUCTION_READY_MVP
+Current Loop Stage: VERIFY
+Run ID: 2026-10-05T08-30-00Z-a1b2c3d-task-4-invoice-form
+Policy: HARNESS_POLICY.json v1
+Risk: medium
+Repository State: feature/invoices, baseline a1b2c3d, head d4e5f6a, dirty-at-start false
+
+Scope:
+- Allowed paths: app/invoice/**, test/invoice/**
+- Changed files: InvoiceFormScreen.kt, InvoiceViewModel.kt, InvoiceDao.kt
+- Out-of-scope files: None
+
+Beginner Checkpoint:
+- What happened: Task 4 was implemented and verified against the approved artifacts.
+- Why it matters: The form works, but persistence and UI evidence block completion.
+- Decision needed: None
+- What happens next: Fix persistence, then rerun failed gates.
 
 Artifacts Read:
-| Artifact | Status | Notes |
-|---|---|---|
-| MOBILE_MEMORY.md | PASS | Current feature state loaded |
-| PRD.md | PASS | Invoice creation requires client, amount, due date |
-| DESIGN.md | PASS | Form uses single-column layout and sticky Save button |
-| TASKS.md | PASS | Task 4 selected |
-| DEPENDENCIES.md | PASS | Room and Hilt already configured |
+| Artifact | Status | Evidence IDs | Notes |
+|---|---|---|---|
+| MOBILE_MEMORY.md | PASS | memory-001 | Current feature state loaded |
+| PRD.md | PASS | artifact-001 | Invoice creation requires client, amount, due date |
+| DESIGN.md | PASS | artifact-002 | Form uses single-column layout and sticky Save button |
+| TASKS.md | PASS | artifact-003 | Task 4 selected |
+| DEPENDENCIES.md | PASS | artifact-004 | Room and Hilt already configured |
+| HARNESS_POLICY.json | PASS | policy-001 | Enterprise policy version 1 loaded |
 
 Orchestration State:
 | Stage | Tool | Status | Evidence |
 |---|---|---|---|
-| Product planning | APPFORGE | PASS | PRD/design/tasks approved |
-| Memory | Mobile Memory | PASS | Current task loaded from MOBILE_MEMORY.md |
-| Implementation | MOBILE-HARNESS | PASS | Three files changed |
-| Device QA | /mobile-mcp-qa | FAIL | Restart persistence failed |
+| Product planning | APPFORGE | PASS | approval-001 |
+| Memory | Mobile Memory | PASS | memory-001 |
+| Implementation | MOBILE-HARNESS | PASS | diff-001 |
+| Device QA | /mobile-mcp-qa | FAIL | device-001 |
+
+Gate Decisions:
+| Gate | Required | Status | Evidence IDs | Exception ID |
+|---|---|---|---|---|
+| scope | yes | PASS | diff-001 | - |
+| platform_review | yes | PASS | review-001 | - |
+| tests | yes | PASS | test-001 | - |
+| prd_verification | yes | FAIL | prd-001 | - |
+
+Exceptions:
+| ID | Gate | Owner | Reason | Ticket | Expires |
+|---|---|---|---|---|---|
+| - | - | - | No exceptions | - | - |
 
 Implementation Summary:
-- app/invoice/ui/InvoiceFormScreen.kt: added Compose form fields and validation.
-- app/invoice/InvoiceViewModel.kt: added state and save action.
-- app/invoice/data/InvoiceDao.kt: added insert call.
+- app/invoice/ui/InvoiceFormScreen.kt: added Compose form fields and validation. [diff-001]
+- app/invoice/InvoiceViewModel.kt: added state and save action. [diff-001]
+- app/invoice/data/InvoiceDao.kt: added insert call. [diff-001]
 
 Code Review:
-| Reviewer | Finding | Status |
-|---|---|---|
-| AXIOM | ViewModel exposes immutable StateFlow and uses viewModelScope | PASS |
+| Reviewer | Finding | Status | Evidence IDs |
+|---|---|---|---|
+| AXIOM | ViewModel exposes immutable StateFlow and uses viewModelScope | PASS | review-001 |
 
 Tests:
-| Command | Result | Notes |
-|---|---|---|
-| ./gradlew testDebugUnitTest | PASS | ViewModel validation tests pass |
+| Command | Result | Evidence IDs | Notes |
+|---|---|---|---|
+| ./gradlew testDebugUnitTest | PASS | test-001 | ViewModel validation tests pass |
 
 PRD Verification:
 | Requirement | Source | Result | Evidence |
 |---|---|---|---|
-| User can save invoice offline | PRD.md > Offline Requirements | FAIL | App restart loses invoice |
-| Save button disabled until valid | PRD.md > Functional Requirements | PASS | Empty form shows disabled Save |
+| User can save invoice offline | PRD.md > Offline Requirements | FAIL | device-001 |
+| Save button disabled until valid | PRD.md > Functional Requirements | PASS | screenshot-001 |
 
 UI Match:
 Match: 88%
 Source: DESIGN.md > Invoice Form
+Evidence: ui-001
 Differences:
 - Save button vertical padding is 8dp smaller than design.
 - Error text color uses theme error but design expects darker red.
@@ -452,25 +591,31 @@ Fixes:
 Mobile MCP QA:
 Device: Pixel_7_API_35
 Screenshots:
-- invoice-form-empty
-- invoice-form-valid
-- dashboard-after-save
-- dashboard-after-restart
+- screenshot-001: invoice-form-empty
+- screenshot-002: invoice-form-valid
+- screenshot-003: dashboard-after-save
+- screenshot-004: dashboard-after-restart
 Result: FAIL
 
 Acceptance Criteria:
 | Criteria | Source | Result | Evidence |
 |---|---|---|---|
-| User can enter required fields | PRD.md > Invoice Flow | PASS | Mobile MCP typed client, amount, due date |
-| Save disabled until valid | TASKS.md > Task 4 | PASS | Button disabled on empty form |
-| Saved invoice appears after restart | PRD.md > Offline Persistence | FAIL | Dashboard empty after restart |
-| UI matches design within 90% | DESIGN.md > Invoice Form | FAIL | 88% match |
+| User can enter required fields | PRD.md > Invoice Flow | PASS | device-001 |
+| Save disabled until valid | TASKS.md > Task 4 | PASS | screenshot-001 |
+| Saved invoice appears after restart | PRD.md > Offline Persistence | FAIL | screenshot-004 |
+| UI matches design within 90% | DESIGN.md > Invoice Form | FAIL | ui-001 |
 
 Memory Update:
 - Task 4 implementation is partially complete.
 - Tests passed, but Mobile MCP restart persistence failed.
 - NEXT ACTION updated to persistence fix.
 
+Evidence Manifest:
+- .mobile-ai-agents/harness/runs/2026-10-05T08-30-00Z-a1b2c3d-task-4-invoice-form/evidence.json
+
+Rollback:
+- NOT_REQUIRED for this medium-risk, pre-release feature task.
+
 Remaining Issues:
 - Invoice persistence after restart fails.
 - UI match below threshold by 2%.

package/cli/commands/doctor.js

@@ -0,0 +1,182 @@
+'use strict';
+
+const childProcess = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { parseOptions } = require('../lib/options');
+const { inspectMcpConfiguration, loadProjectConfig } = require('./mcp');
+
+function executableOnPath(name, env, fsImpl) {
+  const entries = String(env.PATH || '').split(path.delimiter).filter(Boolean);
+  for (const entry of entries) {
+    const candidate = path.join(entry, name);
+    if (fsImpl.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+function defaultRunner(command, args, env) {
+  const result = childProcess.spawnSync(command, args, {
+    encoding: 'utf8',
+    env,
+    timeout: 10000,
+  });
+  return {
+    status: result.status,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    error: result.error ? result.error.message : '',
+  };
+}
+
+function resultStatus(checks) {
+  if (checks.some(check => check.status === 'FAIL')) return 'FAIL';
+  if (checks.some(check => check.status === 'WARN')) return 'WARN';
+  return 'PASS';
+}
+
+function parseAdbDevices(output) {
+  return String(output)
+    .split(/\r?\n/)
+    .slice(1)
+    .map(line => line.trim())
+    .filter(Boolean)
+    .map(line => {
+      const [serial, state] = line.split(/\s+/);
+      return { serial, state };
+    });
+}
+
+function collectAndroidDoctor(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const env = options.env || process.env;
+  const homedir = options.homedir || os.homedir();
+  const fsImpl = options.fsImpl || fs;
+  const runner = options.runner || defaultRunner;
+  const checks = [];
+  const sdkCandidates = [
+    env.ANDROID_HOME,
+    env.ANDROID_SDK_ROOT,
+    path.join(homedir, 'Library', 'Android', 'sdk'),
+    path.join(homedir, 'Android', 'Sdk'),
+  ].filter(Boolean);
+  const sdkRoot = sdkCandidates.find(candidate => fsImpl.existsSync(candidate));
+
+  checks.push(sdkRoot
+    ? { id: 'android-sdk', status: 'PASS', summary: `Android SDK found at ${sdkRoot}` }
+    : {
+      id: 'android-sdk',
+      status: 'FAIL',
+      summary: 'Android SDK was not found.',
+      action: 'Install Android Studio/SDK and set ANDROID_HOME or ANDROID_SDK_ROOT.',
+    });
+
+  const adb = executableOnPath('adb', env, fsImpl) ||
+    (sdkRoot && fsImpl.existsSync(path.join(sdkRoot, 'platform-tools', 'adb')) ? path.join(sdkRoot, 'platform-tools', 'adb') : null);
+  if (!adb) {
+    checks.push({
+      id: 'adb',
+      status: 'FAIL',
+      summary: 'adb was not found.',
+      action: 'Install Android SDK Platform-Tools and add platform-tools to PATH.',
+    });
+  } else {
+    const version = runner(adb, ['version'], env);
+    checks.push(version.status === 0
+      ? { id: 'adb', status: 'PASS', summary: `adb available at ${adb}`, details: version.stdout.split(/\r?\n/)[0] }
+      : { id: 'adb', status: 'FAIL', summary: 'adb exists but could not run.', details: version.stderr || version.error, action: 'Repair Platform-Tools or PATH permissions.' });
+
+    const devicesResult = runner(adb, ['devices'], env);
+    const devices = devicesResult.status === 0 ? parseAdbDevices(devicesResult.stdout) : [];
+    checks.push(devicesResult.status !== 0
+      ? { id: 'android-devices', status: 'FAIL', summary: 'adb could not list devices.', details: devicesResult.stderr || devicesResult.error, action: 'Restart adb and reconnect or authorize the target device.' }
+      : devices.some(device => device.state === 'device')
+        ? { id: 'android-devices', status: 'PASS', summary: `${devices.filter(device => device.state === 'device').length} ready Android device(s).`, details: devices }
+        : { id: 'android-devices', status: 'WARN', summary: 'No ready Android device or emulator is connected.', details: devices, action: 'Start an emulator or connect and authorize a device.' });
+  }
+
+  const emulator = executableOnPath('emulator', env, fsImpl) ||
+    (sdkRoot && fsImpl.existsSync(path.join(sdkRoot, 'emulator', 'emulator')) ? path.join(sdkRoot, 'emulator', 'emulator') : null);
+  if (!emulator) {
+    checks.push({
+      id: 'android-emulator',
+      status: 'WARN',
+      summary: 'Android Emulator command was not found.',
+      action: 'Install Android Emulator from SDK Manager if emulator QA is required.',
+    });
+  } else {
+    const avdResult = runner(emulator, ['-list-avds'], env);
+    const avds = avdResult.status === 0 ? avdResult.stdout.split(/\r?\n/).map(v => v.trim()).filter(Boolean) : [];
+    checks.push(avdResult.status !== 0
+      ? { id: 'android-emulator', status: 'WARN', summary: 'Emulator exists but AVDs could not be listed.', details: avdResult.stderr || avdResult.error, action: 'Open Android Studio Device Manager and repair the emulator installation.' }
+      : avds.length
+        ? { id: 'android-emulator', status: 'PASS', summary: `${avds.length} Android Virtual Device image(s) available.`, details: avds }
+        : { id: 'android-emulator', status: 'WARN', summary: 'No Android Virtual Device images are configured.', action: 'Create an AVD in Android Studio Device Manager.' });
+  }
+
+  const mcpConfigs = inspectMcpConfiguration({ cwd, homedir, fsImpl });
+  checks.push(mcpConfigs.length
+    ? { id: 'mobile-mcp', status: 'PASS', summary: `Mobile MCP configured for ${mcpConfigs.map(item => item.client).join(', ')}.`, details: mcpConfigs.map(item => item.file) }
+    : { id: 'mobile-mcp', status: 'WARN', summary: 'Mobile MCP is not configured for a supported client.', action: 'Run mobile-ai-agents mcp setup --client <client>.' });
+
+  const project = loadProjectConfig({ cwd, fsImpl, configPath: options.configPath });
+  if (!project.config) {
+    checks.push({
+      id: 'project-config',
+      status: 'WARN',
+      summary: 'Android device QA project configuration is missing.',
+      action: 'Run mobile-ai-agents mcp config init --app-id com.example.app.',
+    });
+  } else if (project.errors.length) {
+    checks.push({
+      id: 'project-config',
+      status: 'FAIL',
+      summary: 'Android device QA project configuration is invalid.',
+      details: project.errors,
+      action: 'Run mobile-ai-agents mcp config validate and correct the listed fields.',
+    });
+  } else {
+    const apk = path.resolve(cwd, project.config.apkPath);
+    checks.push(fsImpl.existsSync(apk)
+      ? { id: 'project-config', status: 'PASS', summary: 'Android device QA project configuration is valid.', details: project.file }
+      : { id: 'project-config', status: 'WARN', summary: 'Project configuration is valid, but the APK does not exist yet.', details: project.config.apkPath, action: 'Build the configured APK before device QA.' });
+  }
+
+  return {
+    platform: 'android',
+    status: resultStatus(checks),
+    checkedAt: new Date().toISOString(),
+    checks,
+  };
+}
+
+function printDoctorReport(report) {
+  console.log('');
+  console.log('  Android Environment Doctor');
+  console.log(`  Result: ${report.status}`);
+  console.log('');
+  for (const check of report.checks) {
+    const icon = check.status === 'PASS' ? '✓' : check.status === 'WARN' ? '!' : '✗';
+    console.log(`  ${icon} [${check.status}] ${check.summary}`);
+    if (check.action) console.log(`    Action: ${check.action}`);
+  }
+  console.log('');
+}
+
+async function cmdDoctor(args) {
+  const opts = parseOptions(args);
+  const platform = opts.platform === true ? '' : opts.platform;
+  if (platform !== 'android') throw new Error('doctor currently requires --platform android.');
+  const report = collectAndroidDoctor({ configPath: opts.config === true ? undefined : opts.config });
+  if (opts.json) console.log(JSON.stringify(report, null, 2));
+  else printDoctorReport(report);
+  if (report.status === 'FAIL') process.exitCode = 1;
+  return report;
+}
+
+module.exports = {
+  cmdDoctor,
+  collectAndroidDoctor,
+  parseAdbDevices,
+};