feat(skill): guide physical iPhone setup (#131)

CHANGELOG.md

@@ -14,6 +14,9 @@ All notable changes to AMKernel are recorded here. Public releases use semantic
 - Make Android Skill provisioning target-scoped: reuse verified Runtime/JDK/SDK installations, evaluate exact Node and driver constraints, execute component-level installations after scoped approval, and distinguish physical/emulator prerequisites from live session proof. Preserve raw official doctor results, task-scoped environments and external service ownership. Add bounded synthetic native-Agent approval/readiness scenarios and packaged-reference integrity regressions ([#129](https://github.com/FSQ-lab/amkernel/issues/129)); no real dependency/device or platform qualification is 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)).
+- 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)).
 
 ## [0.1.2] - 2026-11-04
 

README.md

@@ -86,6 +86,8 @@ amkernel uninstall
 
 For Android, the [packaged setup procedure](src/amkernel/skill/references/android-setup.md) first reuses verified JDK/SDK installations, then selects only target-relevant components. The Agent discloses installation methods, versions, locations and impact, executes approved changes through host tools, and verifies them. Physical-device readiness does not require emulator/AVD inventory; configured AVDs and successful doctor/status checks do not prove a live session. Setup does not expand AMKernel's platform support.
 
+For a physical iPhone, the [packaged setup procedure](src/amkernel/skill/references/ios-setup.md) reuses the selected Xcode, Runtime client, Appium/driver and applicable WDA/signing assets before proposing changes. The Agent discloses installation and security effects, performs approved technical work, and guides account, passcode and keychain confirmations in native interfaces without collecting credentials. Setup-only does not launch WDA or create a session; explicitly requested validation uses the official Python Client through `python_exec`. Prepared WDA artifacts are retained when the selected route needs them. Official Appium Skills remain the platform guidance source; iPhone setup does not expand platform qualification.
+
 Agent setup and MCP repair may use shell, PowerShell, native host tools, or focused diagnostic
 probes; they do not require an already-working `python_exec` connection. Appium session and
 device/application interaction code runs through the official Python Client in `python_exec`.

docs/HANDOFF.md

@@ -542,6 +542,32 @@ exercised evidence and its ordinary-functional, non-qualification limits.
 The deduplicated installed-wheel native Agent smoke also passed all six unchanged scenarios,
 with user/client isolation unchanged.
 
+### Target-scoped physical-iPhone Skill (#131)
+
+The packaged Skill routes physical-iPhone preparation through `ios-setup.md` before verified
+official XCUITest/real-device guidance. It reuses applicable Runtime/Xcode/Appium/driver/WDA
+assets, discloses dependency and security changes, and keeps account, passcode and keychain
+actions native and user-owned. Setup-only neither launches WDA nor creates a session. Static
+signature/profile candidacy, target readiness, reachable transport and live proof remain distinct;
+connection failure is not grounds for re-signing. Simulator/Mac2 routes, official provenance and
+core interfaces are unchanged.
+
+Focused distribution/CLI/Skill/Android/iPhone regressions passed 146 tests; protocol/oracle
+self-check passed 116 checks. Ruff check/format and full source/test Mypy (73 files) passed.
+Two independent final source reviews found no remaining blocking findings. The final wheel's
+managed distribution/Skill files match source bytes; actual stdio MCP advertised only
+`python_exec`, preserved state across two completed calls and closed transport with the kernel
+last observed alive. All 13 native Agent synthetic scenarios have passing observations: 12
+passed in the full run; a narrow partial-approval outcome oracle correction was independently
+reviewed and the remaining case passed a fresh single-scenario run. The original full run
+remains failed, not rescored. The live case completed real MCP → official Python Client →
+synthetic HTTP create/read/delete without mutation; setup-only cases created no sessions.
+See `docs/experiments/appium-agent-behavior.md` §18 and the normalized
+[evidence record](../evidence/appium-skill/ios-setup-20261105.json) for exact artifacts and limits.
+No real signing, device security change, WDA launch or physical-iPhone readiness is established;
+#98 qualification is separate.
+
+
 ## Acceptance criteria
 
 - [x] M3 and S3-001 through S3-060 are registered in GitHub Project #2 with exact dependencies and work-item contracts.

docs/decisions/0008-release-evidence-retention.md

@@ -44,6 +44,8 @@ The immutable [`v0.1.2` release](https://github.com/FSQ-lab/amkernel/releases/ta
 
 `evidence/archive-v0.1.2.json` is the offline provenance boundary. It records the immutable release and all three asset identities, preserves every original member path, size, and digest, and classifies each member as either retained in Git or release-only. Tests verify every retained file byte-for-byte against that index and reject reintroduced raw-output paths. Historical commits remain unchanged.
 
+This index covers the original release corpus, not evidence added after that release. Later normalized decision and verification records may be retained in Git without changing the immutable index; they do not exempt any original release-only path from the raw-output exclusion.
+
 ## Consequences
 
 Published raw evidence remains durable and content-addressed without increasing every future checkout. The release grows by one compressed archive and one manifest. The `v0.1.2` release must not be published until authoritative CI has generated and validated both assets from the exact release commit.

docs/development.md

@@ -218,6 +218,16 @@ Agent scenarios are documented in `docs/experiments/appium-agent-behavior.md`; t
 host tool cannot execute real installers or device commands. Synthetic approval and readiness
 evidence does not qualify real JDK/SDK installation, Appium sessions or a new host platform.
 
+iPhone Skill setup changes additionally run `tests/e2e/test_ios_setup.py` and
+`tests/e2e/ios_setup.py --self-check`, plus the installed-wheel native scenarios documented in
+`docs/experiments/appium-agent-behavior.md`. The test-only iPhone host must not run real installers,
+Xcode/signing commands, security prompts or device operations. Approval, user-action, target and
+WDA evidence is cross-checked against its journal; synthetic setup evidence is not real signing,
+WDA startup, iPhone readiness or completion of the existing physical-platform qualification.
+The standalone fixture is standard-library-only. Its protocol self-check and subprocess
+regression launch Python with `-S`; the project environment must not mask a dependency missing
+from the managed Runtime that launches the native MCP host.
+
 ### Gate 3: Actual stdio MCP end to end
 
 An MCP client must launch the packaged server over stdio and exercise the changed public path. Unit tests or direct calls into implementation classes do not satisfy this gate.

docs/experiments/appium-agent-behavior.md

@@ -962,3 +962,106 @@ user/client isolation unchanged. Wheel SHA-256:
 Normalized local reports are `/tmp/amkernel-android-dedup-native.json` and
 `/tmp/amkernel-android-dedup-selfcheck.json` (temporary, not durable raw evidence).
 
+
+## 18. iPhone setup Skill (#131)
+
+The owner accepted `ios-setup-proposal.md` and authorized implementation. The single packaged
+Skill now routes physical-iPhone setup through `references/ios-setup.md` and then verified official
+XCUITest/real-device guidance; simulator/Mac2 routes and official provenance stay unchanged. The
+reference belongs to the existing distribution installation/integrity contract, not a new installer.
+
+The procedure distinguishes requested scope, prepared dependency/device/signing readiness,
+static WDA artifact candidacy, reachable endpoints, and verified live sessions. Existing applicable
+Runtime, Node/Appium/driver/Xcode and signing assets are reused. Runtime repair preserves Python,
+AMKernel source/version, package extras and other `--with` requirements. Device-service discovery
+disables current `devicectl ddiServices`' default DDI automount; preparation changes require scoped
+approval. Native account, trust, Developer Mode, passcode and keychain confirmations stay with the
+user, one action at a time, without collecting secrets or widening keychain access. Final runner
+identity is distinct from its build/base Bundle ID, and setup retains products required by a
+prepared `.app`/`.xctestrun` route. A transport failure does not erase static artifact candidacy or
+justify re-signing. Setup-only does not launch WDA or create a session, and does not require a live
+server merely to prove installed/prepared prerequisites.
+
+`tests/e2e/ios_setup.py` reuses the existing installed-wheel/native Copilot orchestration. Its
+test-only host in `ios_setup_fixture.py` exposes bounded synthetic inspection, exact installation
+and repair disclosures, single-use grants, native-user action waits/rechecks, and append-only
+observations. It executes no actual installers, signing, device security actions or iPhone launches.
+The thirteen cases cover physical reuse, stale paired/developer history, approved/unapproved missing
+driver setup, shared Runtime client repair, warning versus constraint violation, reusable WDA,
+expired/non-covering profile repair, PIN waiting, transport timeout, shared/unknown ownership, and
+explicit live validation. Only the live-validation case enables real `amkernel/python_exec`; that
+case uses the installed official Python Client against a task-owned synthetic Appium endpoint.
+Journal observations and endpoint requests—not the final model prose or scripted echoes—must
+substantiate claims. Xcode/Appium observations, source consumption, exact grants, stale state,
+secret persistence, readiness, session/ownership and cleanup have negative oracle mutations.
+
+Run the protocol/oracle self-check and then the rebuilt-wheel native scenarios:
+
+```bash
+uv run --no-sync python tests/e2e/ios_setup.py --self-check --output /tmp/ios-self-check.json
+uv run --no-sync python tests/e2e/ios_setup.py \
+  --wheel /absolute/path/to/amkernel.whl \
+  --copilot /absolute/path/to/github-copilot \
+  --output /tmp/ios-native.json
+```
+
+The CLI also accepts `--list` and selected `--scenario` cases. Native availability and authorization
+are separate: the launcher grants the fixture host explicitly even when it is already advertised.
+Permanent regressions focus on exact-scope/single-use consumption, secret refusal without payload
+persistence, continued actual fixture RPC service after malformed repair input, false-positive
+oracle mutations, and post-preflight exception classification/scrubbing/cleanup.
+
+The pre-change wheel's observed transport case had an unreachable endpoint, a valid covering
+profile and zero installation, signing repair or session events. Its `candidate=true` was legitimate
+static artifact evidence, not launch success: an initial oracle that required `candidate=false` was
+corrected rather than used as a fabricated regression. The baseline also omitted a historical
+Developer Mode field that the original report schema never declared; that was another oracle
+mismatch, not evidence of incorrect current-device reporting. Neither observation establishes
+physical-iPhone qualification.
+
+Independent source review resolved runner/base identity and artifact retention issues, plus native
+tool authorization, Xcode/Appium evidence binding, sensitive disclosure persistence, malformed
+repair methods and duplicate grant consumption.
+
+Final focused distribution/CLI/Skill/Android/iPhone regressions passed **146 tests**. The
+protocol/oracle self-check passed **116 checks**; Ruff check and format check passed, and Mypy
+passed all **73 production-and-test files**. Two independent final read-only reviews found no
+remaining blocking findings after correcting exact repair scope, native-action argument handling,
+fresh doctor evidence, partial readiness, and read-only HTTP validation.
+
+A later native attempt recorded 13 failures with zero fixture-host calls: an undeclared
+`packaging` import prevented the standalone host from starting in the managed Runtime.
+`python -S` reproduced the import failure. The fixture was restored to standard-library-only
+imports; both existing subprocess protocol checks now run with `-S`, and Node boundary tests
+cover accepted patch/minor versions as well as malformed and out-of-range versions. This
+failed attempt remains failed evidence, not an observation of Skill decision behavior.
+
+Final wheel SHA-256 is `97fbe5ed03eb51d71e93e55b74c5572a39ca0057f9f69ca89061446db960535d`.
+Its distribution module and three changed Skill/reference files match the working source bytes.
+A real final-wheel stdio smoke advertised only `python_exec`, completed two calls with an alive
+kernel and persistent `['initial', 'persisted']` namespace result, then closed transport.
+
+With the standard-library-only host, the full native run passed 12 of 13 scenarios. The sole
+failure rejected a truthful `approval-required` outcome after the approved driver was installed
+and verified but separate WDA signing approval was denied. Independent review approved accepting
+either `blocked` or `approval-required` for that partial setup, while readiness must remain false,
+approval true and WDA blockers present. A positive mutation accepts the pending state; a negative
+mutation still rejects `completed`. A fresh driver-only native run passed with that correction.
+All 13 scenarios therefore have passing observations across those two runs; this is **not** a
+single all-green full run, and the original failed row was neither changed nor rescored.
+
+Both native runs installed the wheel in external temporary projects and passed official
+provenance/content verification. The live case used three real `python_exec` calls and observed
+HTTP 200 create/source/delete, zero remaining active sessions, unchanged fixture state and zero
+submissions; the task-owned endpoint remained available during the proof. Setup-only cases
+created no sessions. Both runs reported unchanged user configuration/isolation. Exact hashes,
+normalized observations, prior failed attempts and scope limits are retained in
+[`ios-setup-20261105.json`](../../evidence/appium-skill/ios-setup-20261105.json).
+
+
+The profile inspection snippet was exercised in the actual Runtime for matching legacy App ID
+prefix, wrong wildcard prefix, uncovered device, wrong Team and expiry; all fifteen shell blocks
+passed syntax parsing. These checks do not prove certificate revocation, current trust, real
+signing or WDA launch. Synthetic fixture evidence remains separate from any future explicitly
+authorized physical-device verification.
+