codex-orchestrator 0.1.51 → 2.0.1

package/prompts/workflows/issue-breakdown.md

@@ -1,155 +0,0 @@
-# Issue Breakdown Workflow
-
-Break an approved PRD, plan, or parent issue into independently grabbable implementation issues using vertical tracer-bullet slices.
-
-Work from the current context first. If an issue number, URL, or path is provided, fetch and read the full source material and comments before drafting child issues. Use repository glossary terms and respect ADRs.
-
-## Core Rule
-
-Each child issue must deliver a narrow, complete, verifiable behavior path. Do not create horizontal tickets like "add database table", "add API", or "add UI" unless the issue also proves an end-to-end user-visible or system-visible behavior through that layer.
-
-## Slice Rules
-
-- Each slice cuts through all necessary layers for one behavior.
-- A completed slice is demoable or verifiable on its own.
-- Prefer many thin slices over a few thick slices.
-- Use explicit discovery or contract issues when a dependency, API, license, fixture, credential, or external behavior is not machine-confirmed.
-- Do not create issues whose only outcome is "create module X" unless the issue proves behavior through that module interface.
-- If the slice mainly explores a better module, interface, or seam, make it an architecture discovery/refactor issue with verification for leverage, locality, and testability.
-
-## AFK / HITL
-
-Classify each slice:
-
-- `AFK`: can be implemented by an agent with deterministic acceptance criteria and available context.
-- `HITL`: requires a human decision, design review, external access, missing credentials, product judgment, or manual validation that cannot be delegated.
-
-Prefer AFK when the contract is clear, but do not mark ambiguous work as AFK.
-
-## Spec Gates
-
-Do not write implementation specs during issue breakdown. Mark where a future worker or orchestrator must remove ambiguity before coding.
-
-Use:
-
-- `Spec required: none` for small, low-risk slices with a clear existing pattern and narrow ownership.
-- `Spec required: issue-level` for one complex issue whose implementation details must be deterministic before a worker starts.
-- `Spec required: wave-level` for related issues sharing contracts, source-of-truth files, schemas, generated artifacts, background jobs, external systems, fixtures, or final live validation.
-
-Consider a spec gate when the slice involves:
-
-- external APIs, credentials, scraping, rate limits, licenses, downloads, or third-party terms;
-- database, schema, persistence, migrations, queues, background jobs, caching, auth, billing, permissions, or shared state;
-- shared DTOs, API contracts, generated types, source-of-truth configuration, or cross-app contracts;
-- multiple services, apps, or modules that must agree on behavior;
-- AI-powered behavior, prompt contracts, deterministic fixtures, or live-AI smoke tests;
-- required browser, mobile, manual, or live smoke validation;
-- known rejected approaches or unresolved product or technical decisions.
-
-## Size / Risk
-
-Each child issue must declare the intended implementation path:
-
-- `Small / low risk`: use `small-task-implementer`; keep the issue narrow, deterministic, and directly verifiable.
-- `Medium`: use scoped implementation with TDD and configured review gates.
-- `High risk`: require issue-level or wave-level spec gates before implementation.
-
-Do not split a small issue into a parent orchestration tree just to satisfy process. Do not mark risky shared-contract work as small to avoid review.
-
-## Review Gate
-
-Before publishing child issues, run an issue-breakdown-review pass over the proposed breakdown. The review must check tracer-bullet quality, dependency correctness, AFK readiness, acceptance criteria, scope control, source-of-truth risk, spec proportionality, and orchestration risk.
-
-Apply all high-confidence review feedback before publishing. If feedback changes product scope or reveals an unconfirmed contract, ask a targeted question instead of guessing.
-
-## Draft Output
-
-Present the proposed breakdown as a numbered list. For each slice include:
-
-- **Title**
-- **Type**: AFK or HITL
-- **Size / Risk**: small / medium / high, with intended path (`small-task-implementer`, scoped implementation, issue-level spec, or wave-level spec)
-- **Blocked by**
-- **User stories covered** when available
-- **Spec required**: none / issue-level / wave-level, with one short reason
-- **External contract status**: confirmed / needs proof / not applicable
-- **Live/manual prerequisites**
-
-Ask whether the granularity, dependencies, AFK/HITL classification, spec gates, and external contract statuses are correct before publishing when the user has not already approved them.
-
-## Published Issue Template
-
-Use this structure for each child issue:
-
-```markdown
-## Parent
-
-Reference the parent issue, PRD, or source plan.
-
-## What to build
-
-Describe the vertical behavior slice end-to-end. Avoid brittle file paths and line numbers.
-
-## Acceptance criteria
-
-- [ ] Concrete, testable criterion
-- [ ] Concrete, testable criterion
-- [ ] Concrete, testable criterion
-
-## Spec gate
-
-Spec required: none / issue-level / wave-level
-
-Reason:
-
-- One concise reason, or "None - straightforward implementation with existing local patterns."
-
-## Size / risk
-
-Size: small / medium / high
-
-Intended path: small-task-implementer / scoped implementation / issue-level spec / wave-level spec
-
-Reason:
-
-- One concise reason tied to ownership, contracts, and validation.
-
-## External contracts
-
-Status: confirmed / needs proof / not applicable
-
-- API/source:
-- Auth/secret source:
-- License/terms constraints:
-- Rejected approaches:
-
-## Verification
-
-- Proof Strategy: auto / visual / browser-visual / mobile-visual / non-visual-smoke / none
-- Automated:
-- Architecture:
-- Manual/live:
-- Required fixtures or files:
-
-Choose a concrete proof strategy for every AFK issue:
-
-- `non-visual-smoke` for backend, CLI, telemetry, analytics, event dispatch, data, logging, or workflow behavior where tests, command output, logs, API responses, or machine-readable artifacts are the proof surface.
-- `browser-visual` for web UI/layout/copy/responsive behavior.
-- `mobile-visual` for Android/iOS/Flutter UI behavior where device-backed launch, screenshot, UI dump, or logs are the proof surface.
-- `visual` when visual proof is required but browser vs mobile should be selected from changed paths.
-- `none` only when normal tests/checks are sufficient and no extra acceptance proof artifacts are required.
-- `auto` when no stronger explicit choice is known.
-
-## codex-orchestrator metadata
-
-Ownership:
-
-- List the narrow files, directories, modules, or glob scopes this issue is expected to own.
-- Use scopes precise enough that non-overlapping AFK issues can run in parallel.
-
-## Blocked by
-
-Blocking issue references, or "None - can start immediately."
-```
-
-Do not close or modify the parent issue while publishing child issues.

package/prompts/workflows/issue-tree-orchestration.md

@@ -1,163 +0,0 @@
-# Issue Tree Orchestration Workflow / Issue Orchestrator
-
-Coordinate a parent issue or PRD with child implementation issues through dependency-aware waves, integration review, phase-gated handoff, and final verification.
-
-Use orchestration only when the work is explicitly a parent/child issue tree or the caller asks for coordination, delegation, parallel agent work, or waves. Do not implement the parent issue directly when child implementation issues exist.
-
-## Required Inputs
-
-- Parent issue, PRD, or plan.
-- Child issue references, or permission to discover linked child issues from the issue tracker.
-- Repo instructions, including `AGENTS.md`, domain docs, ADRs, and issue-tracker label policy.
-- Current git status and branch.
-
-## Core Rules
-
-1. Treat the dependency graph and active wave plan as the live orchestration ledger.
-2. Do not start a child issue until blockers and preconditions are satisfied or explicitly cleared.
-3. Keep one integrator responsible for merge sequencing, handoff checks, validation, and final reconciliation.
-4. Use parallel workers only for disjoint write scopes.
-5. Never let two workers edit the same file, generated artifact, source-of-truth rule, schema, or shared contract at the same time.
-6. Do not broaden scope, add cleanup, or redesign the parent unless a blocker is proven.
-7. If repo reality contradicts the issue, parent PRD, or wave plan, stop and ask for clarification.
-8. Use TDD for behavior-changing child issues.
-9. Honor issue-level and wave-level spec gates before coding.
-
-## Verification Contract
-
-A child issue is not complete until every acceptance criterion has proof.
-
-Allowed proof includes test result, smoke result, command output, API or browser check, mobile proof, log evidence, DB inspection, or an explicit skipped-verification reason with risk. No proof means the issue remains incomplete, blocked, or explicitly deferred in the wave ledger.
-
-## Orient
-
-1. Read repo instructions and issue-tracker config.
-2. Fetch the parent and child issues.
-3. Extract acceptance criteria, blockers, out-of-scope items, rejected approaches, preconditions, and validation expectations.
-4. Build a dependency graph: ready, blocked, final integration/regression.
-5. Identify protected paths, likely source-of-truth owners, and files that must not be edited concurrently.
-6. Extract each issue's spec gate metadata.
-7. Extract each issue's size/risk and intended path (`small-task-implementer`, scoped implementation, issue-level spec, or wave-level spec).
-8. Mark unresolved external contracts, credentials, live fixtures, or human-only decisions as blocked until proven or cleared.
-
-## Plan Waves
-
-Create the smallest safe parallel wave first:
-
-- start only issues with no unresolved blockers;
-- prefer independent vertical slices over horizontal layer splits;
-- avoid parallel writes to the same owner files unless scopes are truly disjoint;
-- keep final cross-cutting regression or cleanup issues for the last wave;
-- define each wave exit gate: worker reports, integration diff review, combined validation, and blocker reconciliation;
-- decide whether the wave requires a spec gate.
-- keep small low-risk children on the compact `small-task-implementer` path when their ownership and validation are genuinely narrow.
-
-## Spec Gates
-
-Run a spec gate when an active issue says `Spec required: issue-level` or `Spec required: wave-level`, or when implementation would otherwise require guessing about contracts, state, ownership, external dependencies, validation, or rejected approaches.
-
-Use an issue-level spec for one complex isolated child. Use a wave-level spec when several child issues share contracts, source-of-truth files, runtime flow, fixtures, or validation. If multiple active issues are marked issue-level but clearly share the same source-of-truth files or execution flow, coalesce them into one wave spec.
-
-Default to a compact execution checklist. Expand to a full spec only when compact mode would leave safety, contract, ownership, or validation ambiguity.
-
-Accepted spec gate output must identify:
-
-- active child issues covered;
-- source-of-truth contracts and ownership;
-- protected paths and rejected approaches;
-- exact implementation phases;
-- first behavior proof or Contract Test Ledger rows when needed;
-- validation gates;
-- stop conditions.
-
-Only after the spec gate is accepted should implementation workers start.
-
-## Delegate
-
-For each issue in the active wave, assign one worker with a narrow ownership scope. Worker instructions must include:
-
-- parent and child issue references;
-- accepted implementation spec reference when a spec gate was run;
-- repo policy and relevant docs to read;
-- instruction to use TDD for behavior changes;
-- instruction to use `$small-task-implementer` only for child issues explicitly classified as small/low-risk, and to escalate if hidden risk appears;
-- exact ownership boundaries;
-- warning that other agents may be editing the repo;
-- instruction not to revert or overwrite user or worker changes;
-- protected paths, rejected approaches, and out-of-scope items;
-- required preconditions and verification commands;
-- stop conditions;
-- required final report: changed files, proof per acceptance criterion, tests run, skipped checks, risks, blockers, and unresolved acceptance criteria.
-- required `reviewHandoff`: flow used, risk level, implemented contract, proof by acceptance criterion, review focus, agent-verified checks, and maintainer-only checks with reasons the agent could not verify them.
-
-While workers run, the integrator should do non-overlapping work: read docs, inspect ownership, map integration points, and prepare validation. Do not duplicate a worker's implementation.
-
-## Integrate Each Wave
-
-Treat each wave as a hard execution gate:
-
-1. Review worker reports before touching code.
-2. Review diffs and verify scope boundaries.
-3. Resolve conflicts without discarding user or worker changes.
-4. Remove duplicated logic, competing source-of-truth changes, and workaround-shaped code.
-5. Check for architecture drift: shallow modules, one-adapter seams, duplicated rules, or tests coupled to implementation details.
-6. Reconcile every active child issue as complete, blocked with evidence, or deferred.
-7. Verify each child's declared path: small-task-implementer stayed compact, and medium/high-risk work satisfied spec/review/proof expectations.
-8. Verify TDD evidence for behavior-changing issues.
-9. Run the smallest meaningful combined validation for the wave.
-10. Run repo architecture checks when available and applicable.
-11. Verify implementation stayed inside the accepted spec, or document why a spec amendment was required.
-12. Run cleanup-review and code-review when repo policy or change size requires them.
-13. Fix high-confidence review findings and rerun validation.
-14. Create focused commits for completed child issues, or one documented wave commit when safe separation is impossible.
-15. Update the dependency graph before starting the next wave.
-
-If a worker reports an ambiguous or risky decision, pause and ask the user a targeted question.
-
-## Finish And Delivery
-
-After all child issues are implemented, blocked, or deferred:
-
-1. Run final integration or regression issues last.
-2. Reconcile all child acceptance criteria, skipped checks, blockers, and out-of-scope protections.
-3. Run cleanup-review before final code-review when repo policy requires it.
-4. Fix grounded findings and rerun relevant checks.
-5. Write a Parent Risk/Proof Mini-Report summarizing child outcomes, flow used per child, risk levels, proof coverage, skipped checks, and the exact human review focus.
-6. Summarize completed issues, verification, skipped checks, and follow-up risks.
-7. Comment on completed child issues with result summaries and verification.
-8. Close completed child issues only after completion evidence is posted.
-9. Comment on the parent with completed children, validation, Parent Risk/Proof Mini-Report, out-of-scope items preserved, and residual risks.
-10. Open or prepare a pull request when requested or expected by repo workflow.
-11. Stop before any human-only action such as PR approval, merge, product decision, manual validation, missing access, or secrets.
-
-## Stop Conditions
-
-Stop immediately if:
-
-- a required precondition cannot be satisfied exactly;
-- a required file, symbol, command, issue, or dependency is missing;
-- a child issue cannot be validated with available repo context;
-- a required spec gate cannot produce an accepted spec;
-- an external contract is not machine-confirmed;
-- completing a child would touch protected or out-of-scope areas;
-- two active workers need the same write target or source-of-truth owner;
-- a worker introduces duplicate business rules, dispatch builders, normalization, persistence accounting, or compatibility layers;
-- implementation would use a rejected approach;
-- review exposes ambiguity that cannot be resolved from code, docs, or issues;
-- the next wave depends on unverified, blocked, or ambiguous work.
-
-## Completion Standard
-
-Do not claim orchestration is complete until:
-
-- every child issue is complete, blocked with evidence, or explicitly deferred;
-- every reached wave exit gate has passed;
-- every required spec gate was completed and accepted;
-- integration diffs have been reviewed and remediated;
-- protected paths and rejected approaches were respected;
-- source-of-truth ownership remains singular;
-- behavior-changing child issues used TDD or documented a no-seam testing gap;
-- required validation ran, or skipped checks have concrete reasons;
-- required cleanup-review and code-review gates completed;
-- completed child issues have focused commits or documented wave commits;
-- completed children and the parent have been updated unless delivery was explicitly skipped.

package/prompts/workflows/prd.md

@@ -1,80 +0,0 @@
-# PRD Workflow
-
-Turn the current parent issue, conversation context, and repository context into a Product Requirements Document. Do not interview the user by default; synthesize what is already known, and record open questions instead of inventing product or technical decisions.
-
-Use the repository's issue tracker and triage label vocabulary from repo instructions when available. Use the project's domain glossary vocabulary throughout the PRD, and respect ADRs in the area being changed.
-
-## Process
-
-1. Explore the repository enough to understand the current product and codebase state.
-2. Identify the major modules, interfaces, contracts, or flows likely to change.
-3. Actively look for opportunities to define deep modules: small, testable interfaces that encapsulate meaningful behavior.
-4. Capture unresolved product, contract, external dependency, or validation questions explicitly.
-5. Write the PRD using the template below.
-6. If the execution environment has issue-tracker access and the caller requested publication, publish the PRD to the configured tracker and apply the triage entry label.
-
-## PRD Template
-
-### Problem Statement
-
-Describe the problem from the user's perspective. Name the pain, missing capability, or operational risk without assuming an implementation.
-
-### Solution
-
-Describe the desired solution from the user's perspective. Focus on outcomes and observable behavior.
-
-### User Stories
-
-Provide a numbered list of user stories in this format:
-
-1. As an `<actor>`, I want `<feature>`, so that `<benefit>`.
-
-Cover the important actors, workflows, edge cases, and operational scenarios.
-
-### Implementation Decisions
-
-List implementation decisions already known or confirmed. Include:
-
-- modules, contracts, or interfaces expected to change;
-- schema, DTO, API, or persistence decisions;
-- state machine, background job, auth, permission, caching, or integration decisions;
-- specific interactions between systems;
-- rejected approaches and why they are rejected.
-
-Do not include brittle file paths or line numbers. If a prototype produced a snippet that captures a decision more precisely than prose, include only the decision-rich part and note that it came from a prototype.
-
-### Testing Decisions
-
-List testing decisions. Include:
-
-- what behavior must be proven through public interfaces;
-- which modules or flows need tests;
-- existing prior art in the repository;
-- required smoke, browser, mobile, API, or live validation;
-- cases where a deterministic test seam is missing and must be created or explicitly accepted as risk.
-
-### Risk And Proof
-
-Classify the initiative so downstream automation can choose the right implementation path:
-
-- small low-risk work that should stay on the Small Task Implementer path;
-- medium scoped implementation work that needs TDD and review gates;
-- high-risk contracts that need issue-level or wave-level spec gates before coding.
-
-List the proof strategy a maintainer should expect after implementation: tests, smoke checks, artifacts, review focus, and any proof that cannot be automated locally.
-
-### Out of Scope
-
-List adjacent behavior that should not be included in this PRD.
-
-### Further Notes
-
-Record open questions, migration notes, rollout notes, compatibility concerns, and follow-up ideas.
-
-## Quality Bar
-
-- The PRD must be durable: useful even if files move.
-- The PRD must be specific enough to break into vertical implementation issues.
-- The PRD must make risk and proof expectations explicit enough that small tasks are not over-orchestrated and risky work is not under-specified.
-- Do not hide unresolved decisions inside implementation work.
-- Do not mark work as agent-ready when the PRD still depends on unconfirmed external contracts, credentials, manual design decisions, or ambiguous acceptance criteria.

package/prompts/workflows/scoped-implementation.md

@@ -1,129 +0,0 @@
-# Scoped Implementation Workflow / Spec Implementer
-
-Implement one scoped issue or approved implementation spec. Follow the issue, repo policy, and runner completion contract exactly. Do not redesign the work unless repo reality proves a blocker.
-
-## Core Rules
-
-1. Keep scope narrow. Do not broaden the issue, add unrelated cleanup, or invent adjacent features.
-2. Treat protected paths, rejected approaches, out-of-scope items, and repo instructions as hard constraints.
-3. Confirm required services, env vars, fixtures, commands, and repo state before editing.
-4. Stop if exact execution would require guessing about contracts, state, ownership, credentials, or validation.
-5. Prefer existing local patterns and deep module boundaries over new abstractions.
-6. Do not add pass-through modules, one-adapter seams, or test-only helpers unless they improve real locality or leverage.
-7. Add comments only where they clarify non-obvious behavior.
-
-## Task Sizing
-
-Before editing, classify the issue:
-
-- `Small / low risk`: clear behavior, narrow ownership, no schema/persistence/auth/background/shared-contract change, and a targeted validation path exists. Use the Small Task Implementer path (`$small-task-implementer`): compact contract, smallest edit, targeted proof, explicit escalation if hidden risk appears.
-- `Medium`: behavior-changing runtime work that touches shared flow, multiple files, or meaningful tests, but does not require a parent issue tree. Use this scoped implementation workflow with TDD and the configured review gates.
-- `High risk`: schemas, persistence, queues, retries, idempotency, auth, permissions, billing, caching, external contracts, multi-service work, or broad source-of-truth changes. Use the scoped/spec path only if the issue already provides deterministic contracts; otherwise return `needs-promotion` with evidence.
-
-Do not run a heavy plan/spec process for a genuinely small task. Do not force a small task path when the change reveals hidden shared-contract or validation risk.
-
-## TDD And Behavior Proof
-
-For runtime behavior changes, use strict TDD red-to-green:
-
-1. Choose one observable behavior.
-2. Write one focused behavior test first.
-3. Prove the test fails before implementation.
-4. Implement the smallest correct change.
-5. Prove the test passes after implementation.
-6. Repeat vertically for the next behavior.
-7. Refactor only while green.
-
-Report the failing/red and passing/green evidence in validation. Do not batch many imagined tests before implementing. If no correct test seam exists, report why the available seams would give false confidence and provide the strongest alternate proof.
-
-## Execution Flow
-
-1. Read the issue, comments, repo instructions, and relevant docs.
-2. Identify acceptance criteria, blockers, out-of-scope items, validation expectations, and likely source-of-truth owners.
-3. Inspect current git status and avoid reverting user changes.
-4. Implement the smallest complete solution.
-5. Keep validation proportional to risk and blast radius.
-6. Preserve runner-owned publication boundaries: do not push, open PRs, merge, publish, deploy, or mutate GitHub labels/comments.
-7. Produce the structured completion report required by the runner.
-
-## Review Gates
-
-Run cleanup-review before code-review for medium or large runtime changes, or when repo policy requires it. Fix high-confidence cleanup findings and rerun relevant validation.
-
-Run code-review before completion when the issue or repo policy requires it, or when the change touches shared behavior, APIs, persistence, auth, permissions, caching, concurrency, background jobs, navigation, middleware, or multiple runtime files. Fix grounded findings or report blockers with evidence.
-
-For compact low-risk changes, focused validation plus a clear completion report is enough unless repo policy says otherwise.
-
-## Review Handoff
-
-For completed work, include `reviewHandoff` in the runner JSON report:
-
-- `flowUsed`: `small-task-implementer`, `scoped-implementation`, `spec-implementer`, `issue-tree-child`, or `other`;
-- `riskLevel`: `low`, `medium`, or `high`;
-- `implementedContract`: what behavior or invariant changed;
-- `proofByAcceptanceCriteria`: acceptance criteria mapped to test/smoke/artifact evidence;
-- `reviewFocus`: the exact files, states, contracts, or edge cases a human should inspect;
-- `agentVerifiedChecks`: checks, commands, code searches, import/path confirmations, or fallback-path confirmations the agent completed before handoff;
-- `maintainerOnlyChecks`: objects with `check` and `reasonAgentCouldNotVerify`, only for actions the agent cannot honestly complete itself, such as product decisions, approvals, credentials, external access, deploy/release decisions, or stakeholder judgment. Do not put runnable commands, code-search checks, import checks, or generic "confirm" tasks here.
-
-## Acceptance Proof
-
-Declare the proof mode in the runner completion report `proofPlan`. Choose the
-narrowest mode that proves the issue: `none`, `non-visual-smoke`, `cli`, `api`,
-`worker`, `browser-visual`, or `mobile-visual`. Do not choose non-visual modes
-for UI or mobile behavior, and do not choose `none` when acceptance criteria need
-observable proof. The runner validates `proofPlan` before publication.
-
-Prepare runner-owned acceptance proof artifacts when configured. For visual work,
-screenshots must be tied back to the acceptance criteria; for non-visual work,
-use smoke outputs, logs, or other observable artifacts. Let the runner execute
-configured proof commands when the prompt says so, and keep proof script repair
-inside proof-owned paths.
-
-For web UI work, prepare a proof-owned browser proof scenario when the runner
-uses `visual-proof auto` or `visual-proof browser`. Use explicit base URLs,
-ordered actions/assertions, named screenshot and DOM checkpoints, and criteria
-refs. Do not run or claim the final runner-owned proof command yourself.
-
-For Android mobile app UI work, use device-backed proof instead of Playwright:
-
-1. Run `adb devices -l`.
-2. Prefer a connected non-emulator device serial and set `export ANDROID_SERIAL=<serial>`.
-3. If no device exists, run `emulator -list-avds`, start an AVD in a separate shell with `emulator -avd <avd-name>`, and wait with `adb wait-for-device`.
-4. After selecting the adb target, use Test Android Apps skills when available.
-5. For native Android projects, use the project Gradle wrapper (`./gradlew`) with a writable `GRADLE_USER_HOME`, build the relevant debug APK, then install and launch it through adb on the selected target.
-6. For Flutter Android projects only, start Flutter rebuild/install with the detected Flutter SDK and writable `PUB_CACHE` and `GRADLE_USER_HOME` directories. If rebuild/install fails because the SDK cache is read-only, retry only when `CODEX_ORCHESTRATOR_FLUTTER_ROOT` points to a preconfigured writable Flutter SDK: set `FLUTTER_ROOT` to that path, prepend `$FLUTTER_ROOT/bin` to `PATH`, run `flutter precache --android`, then rebuild/install again. If no writable Flutter SDK is configured, report the concrete SDK cache permission error.
-7. Do not use Playwright as the primary proof path for Android mobile app verification.
-8. If Test Android Apps cannot be enabled, or no usable Android device or emulator is available, report a warning/skipped check with the concrete plugin or adb/emulator reason and proceed only if repo policy allows it.
-
-For native iOS app UI work, use simulator- or device-backed proof instead of Playwright:
-
-1. Run `xcrun simctl list devices available`.
-2. Choose an available simulator when no physical device is provided.
-3. Build with `xcodebuild` using a writable `-derivedDataPath`.
-4. Install and launch with `xcrun simctl install` and `xcrun simctl launch`.
-5. Do not use Android or Flutter proof steps for native iOS projects unless the repository is explicitly a Flutter project targeting iOS.
-6. If no usable iOS simulator/device or Xcode tooling is available, report a warning/skipped check with the concrete xcodebuild/simctl reason and proceed only if repo policy allows it.
-
-## Stop Conditions
-
-Stop and report a blocker if:
-
-- a required file, symbol, command, dependency, or interface differs from the issue/spec;
-- a required precondition cannot be satisfied;
-- validation cannot prove the intended behavior with available repo context;
-- completing the work requires touching protected paths or using rejected approaches;
-- the change would require unapproved migration, compatibility logic, external access, or product decisions;
-- review exposes ambiguity that cannot be resolved from code, docs, or the issue;
-- the runner completion contract cannot be satisfied safely.
-
-## Completion Standard
-
-Do not mark the issue complete until:
-
-- every acceptance criterion is implemented, blocked with evidence, or explicitly out of scope;
-- validation commands and behavior proof have run, or skipped checks have concrete reasons;
-- applicable cleanup-review and code-review gates have run;
-- protected paths stayed untouched and rejected approaches were avoided;
-- changed files, validation, review handoff, skipped checks, residual risks, and blockers are reported;
-- the structured completion report is written exactly where the runner requested it.