docs: fix stale platforms/ios paths after Apple consolidation (#968) + remaining-work plan

[thymikee]

Summary

Post-#968 (Apple platform consolidation) follow-up: doc/config path fixes, live runner validation, and the decomposed plan for the remaining Phase 3 work.

1. Stale path fixes (the code change here)

#968 moved the OS-agnostic Apple runner engine from src/platforms/ios/ to src/platforms/apple/core/, but several docs/config still pointed at the old locations (actively misleading to agents grepping those paths):

• AGENTS.md — repointed the runner-seam map, the Apple-family sync rule, the record/trace seam, the search-roots hint, and the platform-backends list at src/platforms/apple/core/...; renamed "iOS Runner Seams" → "Apple Runner Seams".
• .fallowrc.json — dropped the two stale ignoreExports entries for the removed src/platforms/ios/{apps,index}.ts (the live src/platforms/apple/core/apps.ts entry already covers those test-only exports).
• ios-runner/{README,RUNNER_PROTOCOL}.md — pointed the TypeScript-client links at src/platforms/apple/core/runner/runner-client.ts.

Docs/config only; no behavior change. fallow audit, tsc, oxlint --deny-warnings, and rslib build stay green.

2. Live runner validation

Ran the full iOS simulator replay suite on a booted iPhone 17 Pro (building the runner fresh): 6/6 passed in 160s — 01-settings, 02-deep-navigation, 03-scroll-discovery, 04-text-input-keyboard, 05-app-lifecycle, 06-swipe-gestures. Confirms the consolidated Apple runner works live across tap/scroll/type/swipe/lifecycle. (This is the live smoke replay the plan now relies on after the request-count CI gate was removed.)

3. My #968 review follow-ups — already resolved in the merge

Items 3–5 from the review are addressed in the merged #968: the existing iOS/tvOS/macOS disallowed SDK lists do not contain xros/xrsimulator (only the new visionOS row does); the device.ts visionOS comment is accurate; and apple/core no longer imports backward through ios/ shims (the shims are deleted, imports point at siblings).

Remaining Phase 3 work (plan — needs issues filed)

The remaining work from plans/phase3-platform-plugin-progress.md decomposes into the units below. I have full agent-ready bodies for each but could not auto-file them as GitHub issues (blocked by the external-write guard — needs your OK). Once filed, plans/phase3-platform-plugin-progress.md can be removed (its content lives in the issues + perfect-shape.md §5–7 + ADR-0009).

Sequencing (→ = blocked by):

b.2 ─┬─> d.5
b.3 ─┴─> d.1 ──┐
d.2 ───────────┤
d.4 ───────────┼─> d.3 (LAST: public Platform collapse ios/macos→apple)
d.5 ───────────┘
cleanup-tests / cosmetic-rename  (independent)

Unit	Summary	Label	Blocked by
b.2	Relocate supports()/unsupportedHint() Apple closures onto plugin.capability.supportsByDefault (parity-gated)	ready-for-agent	—
b.3	Platform-neutral daemon facets providers/recording/appLog/perf (4-way fan-out, each parity-gated)	ready-for-agent	—
d.1	Relocate plugin + interactor + interactions.ts under platforms/apple	ready-for-agent	b.3
d.2	Promote tvOS to an explicit Apple-OS leaf (preserve focus-only/UNSUPPORTED-tap)	ready-for-agent	—
d.4	watchOS unsupported sentinel	ready-for-agent	—
d.5	Per-AppleOS capability tables	ready-for-agent	b.2
d.3	Final public Platform collapse ios/macos → apple (~59 macOS + 47 isApplePlatform sites)	ready-for-human	b.2,b.3,d.1,d.2,d.5
cleanup	Relocate the 18 Apple unit tests out of platforms/ios/__tests__ (+ split index.test.ts, move recording-scripts.test.ts)	ready-for-agent	—
cosmetic	Rename ios-runner → apple-runner + runIosRunnerCommand/createIosRunnerCachePrewarmOnColdBoot	backlog	—

Discipline (perfect-shape §7): every derived table/closure is pinned by a table-/closure-equivalence parity test across src/__tests__/test-utils/device-fixtures.ts before any hand site is deleted; do not flatten the leaves (two-finger XCTest synthesis, tvOS focus-only, AppKit macOS helper).

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.4 MB	1.4 MB	0 B
JS gzip	450.4 kB	450.4 kB	0 B
npm tarball	549.7 kB	549.7 kB	0 B
npm unpacked	1.9 MB	1.9 MB	0 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	27.8 ms	27.7 ms	-0.1 ms
CLI --help	48.1 ms	49.3 ms	+1.2 ms

Top changed chunks: no changes in the largest emitted chunks.

[thymikee]

Review pass for head ddd6a1f found no actionable blockers.

Checked against ADR-0009 and the Phase 3 platform-plugin plan: the PR only updates stale docs/config paths after #968, keeps the remaining Apple work explicitly sequenced, and does not claim the public Platform collapse or deferred Apple leaf work is done. The replacement runner/device/app paths exist under src/platforms/apple/core, and the removed fallow ignores target src/platforms/ios files that no longer exist on main. All 21 reported checks are green, and the PR body includes live iOS simulator replay evidence for the relocated runner path.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-01 05:24 UTC