pi-remote-control/docs/SYNC.md

SYNC — Multi-Agent Coordination

Purpose: allow several agents (human or AI) to work concurrently on this codebase without stepping on each other.

Scope: all phases. This document is the live coordination surface; the phase plans (PHASE-0..PHASE-3) are immutable plans, this file tracks who is doing what right now.

---

How this works

1. Every concrete work item lives in a phase plan as T-<phase>.<n>.
2. Before starting work on a task, an agent:
   • Pulls latest main.
   • Edits the Active Claims table below to add a row claiming the task with its branch name, owner handle, and timestamp.
   • Commits that edit on main directly (small, low-conflict).
   • Then opens the feature branch and works.
3. When the task is done (PR merged) the agent removes its claim row and appends a one-line entry to History.
4. If a task needs to change a frozen interface contract (IC-1..IC-4 from Phase 1, IC-2.1 from Phase 2), the agent must:
   • Open a section under Contract Change Requests below.
   • Wait for at least one other active agent (or the orchestrator) to acknowledge by editing the row to acked: <handle>.
   • Only then implement the change.

The point: no central scheduler is required. A short structured edit on main is the lock.

---

Phase Gate

Phase	Status	Notes
Phase 0 — Spike Stream	done	✅ GREEN LIGHT with caveat: pipe-pane unreliable. See reference/PHASE-0-report.md.
Phase 0.5 — Spike tmux Control Mode	ready to start	Decides streaming path before Phase 1. See PHASE-0.5-spike-tmux-control-mode.md.
Phase 1 — Sidecar	blocked on Phase 0.5	Streaming path must be decided before T-1.1 starts.
Phase 2 — iOS MVP	blocked on Phase 1	Sidecar must be reachable and stable.
Phase 3 — iOS Augmentation	blocked on Phase 2	Continuous after MVP ships.

Update the Status column when a phase transitions. Allowed states: not started, in progress, blocked on …, done.

---

Active Claims

Task	Branch	Owner	Claimed at	ETA	Notes
(none)

Example of a filled row:

| T-1.1 | feat/p1-t1-1-tmux-manager | @jay  | 2026-05-20 14:00 | +2d | starting with manager.ts |

Rules:

• One row per task. A task can have only one active owner.
• Owner = the agent's handle (@jay, @worker-1, @scout, etc.).
• ETA is a rough estimate; missing it is OK, but if a row is stale > 2× ETA, anybody may reclaim after pinging.
• Branch must exist on the remote within 24h of the claim, otherwise the row is considered abandoned and may be removed.

---

File Ownership Map

For each high-traffic file, the table below lists the tasks that may legitimately modify it. If you need to touch a file outside this list, add a row or open a Contract Change Request.

File	Authorised Tasks
extensions/remote-control/index.ts	T-1.0, T-1.4 (events wiring only)
extensions/remote-control/server.ts (legacy)	nobody after T-1.0; legacy frozen
extensions/remote-control/server/**	T-1.0 (refactor), T-1.5, T-1.6, T-1.7
extensions/remote-control/tmux/**	T-1.1
extensions/remote-control/buffer/**	T-1.2
extensions/remote-control/sequence.ts	T-1.2
extensions/remote-control/auth/**	T-1.3, T-1.10 (device tokens only)
extensions/remote-control/pi/**	T-1.4
extensions/remote-control/apns/**	T-1.10, Phase-2 T-2.9 (when iOS supplies tokens)
extensions/remote-control/cli/**	T-1.3, T-1.7
extensions/remote-control/config.ts	T-1.7
docs/SYNC.md	all (this file)
docs/PHASE-*.md	nobody once a phase has started (frozen plan) — open a CCR to amend
docs/reference/**	nobody during implementation — archival

For the iOS repo pi-remote-ios, an analogous map will be added when Phase 2 kicks off.

---

Frozen Interface Contracts

ID	Defined in	Owner of changes
IC-1 — WebSocket frame protocol	PHASE-1-sidecar.md §Interface Contracts	T-1.5 lead, with sign-off from any active T-2.x owner
IC-2 — HTTP REST shape	PHASE-1-sidecar.md §Interface Contracts	T-1.5..T-1.7 leads
IC-3 — Pairing payload	PHASE-1-sidecar.md §Interface Contracts	T-1.3 lead
IC-4 — Config TOML schema	PHASE-1-sidecar.md §Interface Contracts	T-1.7 lead
IC-2.1 — SessionConnection Swift surface	PHASE-2-ios-mvp.md §Interface Contracts	T-2.5 lead

Once a contract is frozen (i.e. at least one consumer task has started work that depends on it), changes require a CCR.

---

Contract Change Requests (CCR)

Format:

### CCR-YYYY-MM-DD-<slug>
- **Contract**: IC-1 / IC-2 / …
- **Proposer**: @handle
- **Motivation**: 1-3 sentences.
- **Proposed change**: diff or prose.
- **Affected tasks**: list.
- **Status**: open | acked by @… | merged | rejected

(none open)

---

Cross-Phase Notes

Threads that don't belong in a single phase plan.

• Spec deviations. If implementation reveals that a spec item is wrong or unbuildable, write a short note here under History, plus open a CCR if it changes a frozen contract. The spec itself stays immutable until a v4 review round.
• Risks materialised. When a Risks row from a phase plan actually hits, log it here with the workaround used.
• Tools / shared scripts. Anything added under scripts/ that's reused across tasks gets a one-liner here.

---

History

Append-only log of completed work and notable events. One line each.

yyyy-mm-dd  @handle  T-x.y  what was done

2026-05-15  @worker-phase0  T-0.*  Phase 0 spike complete. tmux+pipe-pane PoC validated. GREEN LIGHT for Phase 1. Report: reference/PHASE-0-report.md. Branch: feat/spike-stream (kept for reference, not merged).