refactor(skill): unify Appium readiness and Apple guidance

CHANGELOG.md

@@ -22,10 +22,13 @@ experimental; Windows support is not claimed.
 - Deduplicate Android Skill setup/readiness guidance: keep Android procedures in `android-setup.md`, retain routing in the main Skill, and centralize shared Appium service ownership in the execution seam. Preserve the existing rules and tests without changing Apple branches, pinned official source or core behavior ([#130](https://github.com/FSQ-lab/amkernel/issues/130)).
 - Correct strict typing in the Android setup experiment's JSON narrowing, version evidence and regression annotations without changing approval/readiness decisions. The full production-and-test Mypy gate now passes alongside the existing protocol/oracle smoke ([#133](https://github.com/FSQ-lab/amkernel/issues/133)).
 - Add target-scoped physical-iPhone setup to the packaged `amkernel` Skill: reuse applicable Runtime/Xcode/Appium/WDA assets, disclose dependency and security changes, guide native account/passcode/keychain actions, and distinguish profile/runner identity repair from connection failures. Preserve official Appium guidance, setup-only no-launch/no-session, shared-resource ownership and required prepared artifacts. Extend managed-reference integrity coverage; core interfaces and platform qualification remain unchanged ([#131](https://github.com/FSQ-lab/amkernel/issues/131)).
+- Add target-scoped native macOS setup guidance before the verified Mac2 route: reuse the actual Runtime/Appium home/Xcode selection, resolve exact Node/Appium/driver compatibility, keep privacy and administrator choices native and user-owned, and distinguish prepared prerequisites from live target control. Add a deterministic synthetic approval/readiness oracle without changing core interfaces or platform qualification ([#140](https://github.com/FSQ-lab/amkernel/issues/140)).
 - Deduplicate physical-iPhone Skill service, connection, and lifecycle guidance by requiring the existing shared Appium execution contract. Retain WDA launch approval, native security prompts, selected-route capabilities, ownership reconciliation, and prepared-artifact preservation; official skills, core behavior, and test infrastructure are unchanged ([#131](https://github.com/FSQ-lab/amkernel/issues/131)).
 - Scope the immutable release-evidence audit to the original archive corpus so later normalized verification records remain admissible. Preserve every retained member's byte-size/digest checks and reject reintroduced release-only paths without changing the published index ([#131](https://github.com/FSQ-lab/amkernel/issues/131)).
 - Concentrate Android execution guidance in a managed `android-execution.md` reference: distinguish app/page/context/target evidence, refresh element assumptions, bound scrolling and waits, separate input from persistence, and preserve requested final state. Adapt outcome-first and minimal-observation principles from the OpenAI CUA sample without changing Runtime, setup or official inputs. Restore two missing native behavior prompts and accept successful pre-action state evidence rather than requiring XML for restoration; strict baseline boundary regressions preserve the behavioral contract ([#98](https://github.com/FSQ-lab/amkernel/issues/98)).
 - Unify Android, iOS and native macOS observation guidance: use controls for sufficient location/action/result evidence, with explicit-image requests and genuinely visual questions taking the screenshot path. Require rendered image observations before image-dependent actions, current coordinate geometry and observed results; retain privacy, approval and lifecycle boundaries. Add three-platform synthetic visual fixtures and image-identity/ordering regressions without changing Runtime, setup or pinned official inputs ([#98](https://github.com/FSQ-lab/amkernel/issues/98)).
+- Extend the CUA-informed outcome-first execution contract to iOS/XCUITest and native macOS/Mac2. Short-flow prompts now state the requested final UI state instead of prescribing driver code; shared guidance requires current app/context/window evidence, fresh semantic targets and observed results. Synthetic evaluators now reject an unobserved iOS state change and unnecessarily fragmented Mac2 execution without changing Runtime, setup, ownership or platform-qualification boundaries ([#98](https://github.com/FSQ-lab/amkernel/issues/98)).
+- Replace duplicated platform readiness prose with one structured readiness/authorization contract and shallow platform adapters. Shrink the main Skill to routing and execution invariants; delete copied version-sensitive Node/Appium/driver procedures from Android, physical-iPhone and native-macOS guidance; add a focused iOS Simulator adapter; carry one exact authorization effect set across official-Skill handoffs; expose one structured fail-closed official-guidance verifier result; and reject every Windows host or target without mutation or fallback. Approval remains procedural guidance, not a security boundary ([#98](https://github.com/FSQ-lab/amkernel/issues/98)).
 
 ## [0.1.2] - 2026-11-04
 

docs/HANDOFF.md

@@ -2,7 +2,7 @@
 
 ## Task
 
-Resolve the separately scoped post-release core CI defects #114/#115, then continue the owner-authorized ordered real-platform acceptance, real Windows Android verification, and installed-wheel Codex/cross-OS Stage 4 evaluation without changing the public interface or support claims.
+Resolve the separately scoped post-release core CI defects #114/#115, then continue the owner-authorized Android, iOS and native macOS acceptance plus installed-wheel Codex/cross-OS Stage 4 evaluation without changing the public Runtime interface. Windows is explicitly outside AMKernel support.
 
 ## Context
 
@@ -143,16 +143,12 @@ discovery returned one connected development-enabled target, not XCUITest readin
 Existing task-local Java 17 and Android SDK/adb were found and execution-validated;
 no new dependency installation or shared ADB startup was performed in this attempt.
 
-Windows prerequisite discovery found no authorized reachable Windows/Android host
-or repository self-hosted runner. No actual Windows command or failure was
-observed. `published-011-windows-readiness-20261103.json` distinguishes those facts
-from static shipped-code POSIX requirements: Artifact Store startup, Supervisor
-spawning/control and Runner signal initialization lack native Windows support.
-Windows needs the separate accepted platform design required by #100/ADR-0005;
-do not remove guards or weaken file-identity/owned-cleanup contracts as a shortcut.
-A new authorized hosted Windows job can supply lifecycle-only evidence, not the
-required Android-device scenario. Missing existing jobs do not prove hosted
-execution impossible. Issue #100 records the investigated limits and dependencies.
+Historical Windows prerequisite discovery found no authorized reachable host and identified native
+Windows gaps in process and signal handling. That evidence remains retained, but the owner decision
+is now explicit: AMKernel does not support Windows hosts or targets, and Windows qualification is
+not a product prerequisite or roadmap item. Keep the existing guards; never route through Windows
+material retained in the pinned upstream Appium snapshot or weaken file-identity/owned-cleanup
+contracts to imply support.
 
 The unreleased #98 Skill revision now presents one novice-first interface: the user supplies a
 plain-language outcome while the Agent discovers safe facts, chooses one platform route, avoids
@@ -167,7 +163,7 @@ or completion of the outstanding actual-platform sequence.
 
 Issues #102, #103, #104, #106, #107 and #108 are closed against their completed,
 merged and independently reviewed defect contracts. #98 and #105 remain open for
-the outstanding actual-platform sequence; #100 still requires real Windows evidence.
+the outstanding supported-platform sequence. #100 is not an AMKernel support objective.
 The latest read-only Project #2 check has #81 Planning and #79/#82 Ready.
 Available credentials have `read:project`, not board-write scope; issue updates do not imply board changes.
 Complex Mac #109, dynamic-list #97 and Gmail privacy expansion #99 stay deferred.
@@ -333,7 +329,7 @@ Separate defects own the work: [#102](https://github.com/FSQ-lab/amkernel/issues
 then [#98](https://github.com/FSQ-lab/amkernel/issues/98) real Agent behavior. Environment discovery
 [#106](https://github.com/FSQ-lab/amkernel/issues/106) and owned-state/conversation behavior
 [#107](https://github.com/FSQ-lab/amkernel/issues/107) remain separate contracts. Gmail privacy
-expansion #99 remains post-v1; Windows Android #100 still requires real Windows evidence.
+expansion #99 remains post-v1; Windows Android #100 is outside AMKernel support.
 
 #102 now distinguishes constraints, tested coverage, observed failures, and proven incompatibility.
 `evidence/appium-skill/compatibility-20261102.json` retains bounded real Copilot CLI 1.0.105 /
@@ -587,6 +583,45 @@ not an all-resources-cleaned claim. See experiment §19 and the
 [normalized evidence](../evidence/appium-skill/android-execution-20261105.json).
 No Android World rerun, score improvement or real-device/platform qualification is established.
 
+### iOS and native macOS outcome-first execution (#98)
+
+The CUA-informed Android execution principles now cover iOS/XCUITest and native macOS/Mac2
+through the shared `amkernel-appium.md` seam. Packaged routing requires the shared reference for
+Apple scenarios. It establishes current iOS app/context/view and macOS app/window/focus identity,
+invalidates stale element and coordinate assumptions after transitions, prefers semantic targets,
+and verifies the requested result instead of trusting a successful command return. Setup,
+Runtime, ownership and official-skill inputs are unchanged.
+
+The iOS and macOS short-flow prompts now provide the novice's requested final state and fixture
+location without prescribing capabilities, selectors, clicks, sessions or call partitioning. The
+oracle still requires the correct inferred driver route, one change action, observed pre-action
+and requested post-action state, bounded compact calls, truthful cleanup and no unnecessary
+screenshot. Focused observation and evaluator regressions passed 125 tests; independent review
+found no remaining actionable issue. This is synthetic behavior evidence only; no real Apple
+target or broader platform qualification is established.
+
+### Unified readiness and authorization interface
+
+The installed Skill is now a 220-line router over `readiness-contract.md`. Android physical,
+Android emulator, iOS Simulator, physical iPhone and native macOS adapters use one canonical
+target/readiness/authorization/live-control/cleanup result. The authorization effect set survives
+first-party to official-Skill handoff, so an identical approved change is not confirmed twice;
+changed effects require a new disclosure. This remains behavioral guidance, not a security control.
+
+Version-sensitive Node/Appium/driver prerequisites and procedures were deleted from first-party
+platform references. Verified official Skills own those facts; first-party adapters retain target
+applicability, local selection, ownership and result normalization. Official distribution now has
+one `--json` verifier result while preserving the existing fail-closed manifest, receipt and exact
+tree checks internally. A focused iOS Simulator adapter separates runtime, configured target, boot
+and live control while marking physical trust/signing/WDA provisioning not applicable. Every
+Windows host or target is blocked without mutation or session fallback.
+
+Focused behavior regressions passed 139 tests; Skill/distribution checks passed 62 tests; Ruff and
+Python diagnostics passed. Independent review found and drove fixes for canonical required-layer
+coverage, zero execution calls on Windows, and explicit-decline state consistency. Re-review found
+no remaining actionable issue. The direct repository verifier invocation failed closed with the
+expected missing installed-project receipt; temporary installed-project tests covered both
+structured verified and failed results.
 
 ### Shared control-first and visual-fallback execution (#98)
 
@@ -648,6 +683,26 @@ both non-pending cases. Independent read-only review found no actionable finding
 the earlier acceptance evidence, not the Runtime or any platform qualification.
 The final combined evaluator/process-boundary regression run passed 112 tests.
 
+### Target-scoped native macOS setup guidance (#140)
+
+The packaged Skill routes native macOS setup through an AMKernel-owned discovery, compatibility,
+approval and readiness reference before the verified pinned Mac2 procedure. It reuses the selected
+Runtime, Appium home and Xcode; evaluates current Node/npm/Appium/Mac2 plus Python Client/Selenium
+constraints without reducing them to majors; and keeps administrator, Xcode and privacy choices
+native and user-owned. Prepared setup remains distinct from live target control. Setup creates no
+session or target launch, and any approved task-owned server smoke must be stopped.
+
+The deterministic oracle covers nine ready, missing and incompatible dependency, Xcode and privacy
+profiles. Exact grants bind both technical changes and user-executed native handoffs. A completed
+outcome requires environment `summary.requiredOk`, required doctor success, server status/driver
+evidence, a successful bounded smoke result and later cleanup. Focused macOS/Android/iPhone setup,
+distribution and Skill regressions passed 199 tests; the nine-profile executable oracle, Ruff
+check/format and Mypy over 77 source/test files passed. Independent review found three oracle
+blockers and verified every correction with no blocking finding remaining. No live dependency
+install, Appium/Mac2 server or session, Xcode/privacy change, native Agent evaluation, platform
+qualification or release
+occurred. See experiment §21.
+
 ## Acceptance criteria
 
 - [x] M3 and S3-001 through S3-060 are registered in GitHub Project #2 with exact dependencies and work-item contracts.

docs/architecture.md

@@ -402,6 +402,16 @@ The skill guides installation, readiness, diagnosis, and first successful automa
 
 A skill can guide the Agent through setup, external process lifecycle, library usage, waits, large-output reduction, debugging, and cleanup. A skill is procedural knowledge, not an executable capability or security mechanism.
 
+The installed Skill presents a narrow routing interface over one shared readiness and authorization
+contract. Platform references are adapters: they select applicable layers and add platform facts.
+Verified official Appium Skills own version-sensitive prerequisites, driver checks, capabilities
+and procedures; first-party guidance owns target selection, applicability, Runtime identity,
+authorization continuity, resource ownership, normalized results and cleanup truth. Approval
+remains procedural guidance, never enforcement.
+
+AMKernel does not support Windows hosts or Windows targets. Windows material retained inside a
+verified upstream snapshot is supply-chain provenance, not a supported route.
+
 Each experiment produces evidence about the kernel:
 
 - which live objects need persistence;

docs/experiments/appium-agent-behavior.md

@@ -1188,3 +1188,42 @@ The [bounded evidence record](../../evidence/appium-skill/observation-policy-202
 retains report/harness digests, prior failures, observations and limits. This proves native
 Agent → installed Skill → stdio MCP → official Appium Python Client → synthetic endpoint
 behavior, not real-device/driver qualification or an Android World score improvement.
+
+## 21. Target-scoped native macOS setup guidance (#140)
+
+The packaged Skill now reads `references/macos-setup.md` before the verified pinned
+`setup-mac2` route. The AMKernel-owned reference supplies the Runtime seam, existing
+Node/Appium/Appium-home and Xcode selection, exact compatibility and approval decisions,
+target identity, privacy handoff, and prepared-versus-live reporting. The official Skill retains
+current Mac2 environment, doctor and bounded server-smoke details. iOS/tvOS, Android, task
+execution, troubleshooting, core interfaces and pinned official inputs are unchanged.
+
+The guidance treats macOS privacy as process-identity-specific. Password, administrator,
+Xcode license/first launch, Accessibility, Automation and applicable Screen Recording choices
+remain native and user-owned. It prohibits TCC database edits/resets, silent global Xcode
+selection, `sudo npm`, duplicate Appium homes, setup-only sessions and static-check claims of live
+control. An approved task-owned server smoke may run but must be stopped; a compatible supplied
+server is preserved. Setup-only readiness does not launch the target app.
+
+`tests/e2e/macos_setup_fixture.py` and `macos_setup.py` are deterministic in-process models; they
+run no installer, Appium server, Mac2 driver, Xcode operation, privacy mutation, target app or
+session. Nine profiles cover ready-stack reuse, missing and incompatible Mac2 repair, exact
+Node/npm/Appium/Mac2 range evaluation, Runtime Python/Client/Selenium compatibility, missing Xcode
+native action, and privacy pending. Native Xcode/privacy completion must match the exact disclosed
+approval grant while remaining user-executed. The oracle rejects unapproved, drifted or reused
+grants; forbidden TCC/global-Xcode/security changes; readiness overclaims; session creation;
+shared/unapproved or leaked server smokes; and blanket Screen Recording requirements.
+
+A completed setup outcome now requires the official environment summary and required doctor
+checks plus exactly one approved task-owned server start, status/driver observation, successful
+bounded smoke result and later stop. Discovery, approval-required and blocked outcomes remain
+distinct and do not manufacture smoke evidence.
+
+Focused macOS/Android/iPhone setup, distribution and Skill regressions passed **199 tests**. The
+macOS protocol/oracle self-check passed all **9 profiles**; Ruff check/format and Mypy passed all
+**77 source/test files**. The first independent review found three oracle blockers in dependency
+ranges, bounded smoke completion and native-action approval binding; the final review verified all
+three corrections and reported no remaining blocking finding. This is source-level deterministic
+behavior evidence only. No native Agent evaluation, real dependency installation, Appium/Mac2
+server or session, Xcode/privacy change, live target control, platform qualification, release or
+Android World evaluation occurred.

src/amkernel/distribution.py

@@ -646,6 +646,9 @@ def _skill_files(self) -> tuple[str, ...]:
             "references/android-setup.md",
             "references/android-execution.md",
             "references/ios-setup.md",
+            "references/ios-simulator.md",
+            "references/macos-setup.md",
+            "references/readiness-contract.md",
             "scripts/verify_official_skills.py",
         )