# Integration runbook

The integrating engineer owns main, dependency direction, shared types, build settings, app composition and evidence quality. Feature agents own implementations within their briefs. Never delegate integration by asking every agent to edit project.pbxproj.

## Before parallel dispatch

1. Agree on the provisional brand/repository slug with the owner. Confirm TV identifier and exact software builds when hardware work starts.
2. Tag a known baseline locally after checks; record SHA in the task roster. Prepare one worktree/branch per workstream. Shared worktree agents must be restricted to separate paths.
3. Freeze v1 command types and add typed session handshake, TV connection state and injected storage/motion protocols. Provide fake implementations and representative fixtures first. Review error semantics, cancellation and ownership with A/B/C/E before coding production adapters.
4. Wire adapter test targets and validate their platform availability. Keep platform-specific frameworks out of pure Swift algorithm modules.

## Per PR

Read the actual diff and test output, not just the agent summary. Confirm module ownership, no copied dependencies, no private APIs, no trust bypass, no replay and no unsupported background modes. Review concurrency around actor reentrancy and TV/session generation changes. Merge into an integration branch, resolve conflicts at the shared contract (never add a second near-identical type), then run `bash Scripts/check.sh --apps` against the combined commit.

Compile success validates type/build integration only. Run actual phone-watch activation and TV pairing checks for adapters, with hardware evidence linked to that SHA. Keep failed checks and environmental limitations visible. Revert the smallest faulty PR or keep the feature explicitly in demo/disabled state until fixed. Do not broaden a tested-TV claim to other years/models.

## Vertical slices

| Milestone | Demonstration required | Exit condition |
| --- | --- | --- |
| M0 foundation | Demo apps + domain tests | Both targets compile, documentation consistent |
| M1 named phone remote | TV prompts for Wristivo; phone right button moves selection | TLS policy, pairing/revocation and tokens verified |
| M2 watch relay | Watch button moves selection through phone | Deadline/dedup, phone lock/wake and failure states measured |
| M3 wrist input | Real right/left/up/down movements control menu | Gesture targets and lifecycle stop pass |
| M4 product prototype | Setup, forget, recovery, accessible controls | Reproducible owner acceptance on named hardware |
| M5 distribution | Signed beta and review package | Paid membership, rights/privacy/assets and all release gates |

Each milestone is an evidence gate, not a deadline estimate. Do not promise release dates until M1–M3 retire the hardware risks. If phone-background reliability requires keeping the phone app open, make that constraint explicit and reassess product value before release.

## Project and release management

`Scripts/generate-project.rb` uses development-only xcodeproj 1.27.0; the generated project is committed. Keep changes deterministic, review diffs and build both schemes after regeneration. Signing overrides stay in ignored Config/Local.xcconfig. Never commit a developer team, certificate or token. Set owned bundle identifiers before provisioning; the `com.example` prefix is for scaffold builds only.

Before a release tag, read RELEASE-CHECKLIST, compare privacy policy to code, run physical regressions, capture accurate screenshots and review video, then archive with the supported stable Xcode/SDK required at submission time. The currently installed toolchain is not proof of App Store SDK eligibility. Separate unsigned CI checks from signing/distribution jobs with minimal credentials. Gitea source hosting is independent of Apple membership.