Files
kandev/docs/plans/remote-contribution-local-first/plan.md
T
2026-08-23 17:34:52 +00:00

255 lines
12 KiB
Markdown

---
spec: docs/specs/tasks/system-design/remote-contribution-tasks.md
created: 2026-08-12
status: completed
---
# Implementation Plan: Local-First Remote Contributions
## Overview
Keep a diverged task checkout as the user's working version. Replace the current blocking warning
with explicit version choices. Add exact-lease backend operations before the desktop and mobile UI can
offer remote replacement or local adoption.
The plan implements
[ADR-2026-08-12](../../decisions/2026-08-12-local-first-contribution-replacement.md).
## Invariants
- The task checkout is the working version. The provider branch is the published version.
- Drift detection does not change either version.
- Remote replacement targets one contribution repository and uses an exact provider-head lease.
- Adopting the provider version requires a clean working tree and creates a recovery branch first.
- Kandev exposes the managed replacement actions only through session-scoped user UI actions.
- Normal aligned, local-ahead, and provider-ahead behavior does not change.
- The first UI implementation covers GitHub PR drift. The backend operations stay provider-neutral.
## Backend
### Explicit contribution operations
Add `ReplaceRemoteContribution` and `UseRemoteContribution` to
`apps/backend/internal/agentctl/server/process/`. Keep them separate from `GitOperator.Push` so a
generic force request cannot become an implicit contribution replacement.
`ReplaceRemoteContribution` must:
1. Require a valid remote-contribution binding and a full expected commit ID.
2. Target the binding's contribution remote and exact head ref.
3. Invoke `git push` with
`--force-with-lease=refs/heads/<head>:<expected-remote-head>`.
4. Return the normal Git operation result without retrying a lease mismatch.
`UseRemoteContribution` must:
1. Reject staged, unstaged, and untracked file changes.
2. Fetch the bound contribution head without changing the current branch.
3. Require the fetched commit ID to equal `expected_remote_head`.
4. Create a unique local recovery branch at the current task HEAD.
5. Reset the task branch to the fetched provider head and retain its upstream.
6. Return the recovery branch name in the Git operation result.
Use the existing classified Git subprocess path. Validate commit IDs and generated ref names before
they reach command arguments.
### Agentctl and runtime contracts
Add these internal agentctl endpoints:
- `POST /api/v1/git/contribution/replace`
- `POST /api/v1/git/contribution/use`
Each request carries `expected_remote_head` and the existing optional `repo` scope. Extend the runtime
agentctl client with typed methods and round-trip tests.
Add the user-facing WebSocket actions `worktree.replace_contribution` and
`worktree.use_contribution`. Each payload carries `session_id`, `expected_remote_head`, and one optional
repository scope. Register the actions only in `GitHandlers`. Do not add MCP tools or automatic call
sites.
The existing gateway session authorization remains the first request guard. A destructive action must
never fan out across repositories.
## Frontend
### Relation and action model
Update `remote-contribution-relation.ts` so `diverged` means a local-first presentation instead of a
blocked workflow. Preserve normal Push and Pull capability fields. Add explicit replacement and
provider-adoption capability fields that require complete provider evidence and an exact provider
head.
Replace `remoteMutationBlocked` and the `history_changed` disabled reason with an action model that
distinguishes:
- normal Push
- provider-ahead Pull
- diverged remote replacement
- diverged provider adoption
- unavailable evidence
Add typed callbacks in `use-git-operations.ts` for both new WebSocket actions. The callbacks must keep
an explicit empty repository scope and must not use the multi-repository fan-out wrapper.
### Shared copy and result handling
Add localized copy to the `task` namespace in English, Portuguese, Simplified Chinese, and pseudo.
Use these English concepts consistently:
- status title: **PR branch changed**
- status body: **Your task version is unchanged. When you are ready, choose which version to use.**
- primary destructive action: **Replace PR branch**
- local destructive action: **Use PR version**
- secondary disclosure: **PR #<number> version**
The replacement confirmation must identify the repository and provider head. It must state that the
task version replaces the published branch. The provider-adoption confirmation must state that Kandev
creates a recovery branch and requires a clean working tree.
After provider adoption, show the recovery branch name in success feedback. Map stable backend error
conditions to translated instructions. Lease mismatches must tell the user that the PR changed again.
### Desktop Changes and VCS surfaces
For a diverged relation:
- Show one yellow warning icon in the Changes toolbar and no repeated warning banner in the body.
- Keep the local task history as the primary commit list.
- Keep the provider history collapsed behind **PR #<number> version**.
- Keep local edit and commit actions enabled.
- Replace disabled Push and force-push controls with **Replace PR branch**.
- Add **Use PR version** as the secondary version choice.
- Keep generic Pull disabled.
- Show each desktop action explanation in the shared immediate tooltip component.
Changes relation and PR-file inputs must include only pull requests whose `repository_id` and
normalized `head_branch` match a live checkout status. A historical PR may remain in Review, but it
must not supply provider commits, files, links, or drift state to Changes.
Apply the same action model to `ChangesPanelHeader`, `VcsSplitButton`, and
`VcsMultiRepoMenu`. Scope every destructive action to the selected contribution repository.
### Mobile design contract
- **Desktop outcome:** The user can inspect both versions and select which version wins.
- **Mobile entry point:** The existing Git actions trigger in the task top bar.
- **Nearest exemplar:** `session-mobile-top-bar-git-controls.tsx` supplies the compact menu entry.
`mobile-menu-sheet.tsx` supplies the inset, safe-area-aware bottom surface.
- **Hierarchy:** Keep Commit first. Show **Replace PR branch** as the primary drift action. Show
**Use PR version** and **PR #<number> version** as secondary actions.
- **Presentation:** Use the existing responsive Git menu for entry. Use an inset bottom drawer for the
destructive confirmation on phone. Keep the desktop confirmation as a dialog.
- **Rationale:** The confirmation is temporary and action-focused. It does not need a new route or a
full-height surface.
- **Geometry:** Keep one internal scroll owner. Clear the bottom safe area. Give action rows and
confirmation buttons a 44px touch target. Keep document horizontal overflow at zero.
- **Shared logic:** Reuse the relation, operation callbacks, confirmation state, and result handling.
Keep only the dialog or drawer composition viewport-specific.
- **Mobile proof:** Replace the PR branch from the Pixel 5 Git menu and verify the exact remote result.
## Tests
- **Exact leased replacement:** Add a process test with a real bare source repository. Prove that the
expected head succeeds and a moved head fails without ref mutation.
- **Provider adoption:** Add a process test that proves the recovery branch preserves old HEAD and the
task branch moves to the expected provider head. Cover dirty worktrees and stale fetches.
- **Contract forwarding:** Extend agentctl API, runtime client, and WebSocket handler tests for the new
action names, repository scope, expected head, response fields, and missing-field errors.
- **Relation policy:** Update the pure classifier tests for local-first divergence, unavailable evidence,
provider-ahead Pull, and local-ahead Push.
- **Branch-scoped selection:** Prove that a merged historical PR cannot override the open PR matching
the checked-out repository and branch, including when Review still selects the historical PR.
- **Frontend callbacks:** Prove both actions send one repository scope and the exact provider head.
- **Desktop components:** Prove that the compact state replaces the blocking warning. Prove that local
actions remain available and destructive actions require confirmation.
- **Mobile components:** Prove that the Git menu exposes all three drift actions. Prove that the phone
confirmation uses a drawer and keeps all touch actions enabled.
- **Localization:** Run the i18n catalog and changed-line ratchet checks.
## E2E Tests
### Replace a changed PR branch on desktop
- **Scenario:** A provider rewrites the PR after task creation. The user chooses the task version.
- **File:** `apps/web/e2e/tests/git/git-changes-panel.spec.ts`
- **What to verify:** The toolbar warning appears without a repeated body banner, provider history
stays collapsed, confirmation names the effect, and the remote ref changes to local HEAD through an
exact lease.
### Adopt the current PR version on desktop
- **Scenario:** A provider rewrites the PR after task creation. The user chooses the PR version.
- **File:** `apps/web/e2e/tests/git/git-changes-panel.spec.ts`
- **What to verify:** The task branch moves to the provider head, the recovery branch retains old HEAD,
and the drift status clears after provider refresh.
### Replace a changed PR branch on mobile
- **Scenario:** A phone user selects **Replace PR branch** from the Git actions menu.
- **File:** `apps/web/e2e/tests/git/mobile-pr-checkout-drift.spec.ts`
- **What to verify:** The bottom drawer explains the replacement, the action succeeds, the remote ref
changes, touch targets remain usable, and the document has no horizontal overflow.
Use real local Git refs for provider-head fixtures. Do not use synthetic commit IDs for leased actions.
Update the mock provider state after a successful push so the UI can converge to the aligned state.
## Implementation Waves And Parallel Candidates
Wave 1:
- [x] [Task 01: Exact-lease contribution operations](task-01-exact-lease-contribution-operations.md)
Wave 2:
- [x] [Task 02: Local-first relation and shared actions](task-02-local-first-relation-and-shared-actions.md)
Wave 3 (parallel candidates after Task 02, user authorization required):
- [x] [Task 03: Desktop local-first contribution UI](task-03-desktop-local-first-contribution-ui.md)
- [x] [Task 04: Mobile contribution version choices](task-04-mobile-contribution-version-choices.md)
Wave 4:
- [x] [Task 05: Desktop and mobile drift E2E](task-05-desktop-mobile-drift-e2e.md)
Wave 5:
- [x] [Task 06: Branch-scoped drift UX correction](task-06-branch-scoped-drift-ux-correction.md)
The default execution order is sequential in the primary conversation. The wave labels do not
authorize subagents.
## Verification Results
Completed 2026-08-12. Each task records its exact commands and results.
- Backend focused verification passed 1,753 tests across the process, agentctl API, runtime client, and
WebSocket handler packages.
- Frontend focused relation, operation, desktop, VCS, and mobile tests passed, including the shared
26-test desktop/mobile action suite. `pnpm run typecheck` passed.
- `pnpm run i18n:check` and `pnpm run i18n:ratchet` passed.
- Desktop and Pixel 5 drift scenarios each passed once with retries disabled. Their provider histories
use real local Git commits and verify the confirmation boundary and responsive interaction contract.
- Destructive ref mutation and provider adoption are covered by the real-Git process tests. The current
REST E2E helper cannot create the server-owned contribution binding, so browser execution stops before
mutation; the limitation is recorded in Task 05.
- The branch-scoped follow-up passed 66 focused Vitest assertions, full web lint and typecheck, i18n
catalog and ratchet checks, all 21 desktop Changes E2E scenarios, and the Pixel 5 drift scenario with
retries disabled. It proves that a merged historical PR does not drive the live checkout relation.
## Documentation Impact
The task behavior spec and the new ADR contain the user contract and safety boundary. This change does
not affect public CLI commands, configuration keys, installation, deployment, or executor setup.
`docs/public/**` does not require an update.
## Risks
- A bad lease implementation can overwrite provider commits that arrived after confirmation.
- A provider-adoption operation can lose uncommitted files unless the clean-tree guard includes staged,
unstaged, and untracked files.
- If a desktop or mobile entry point keeps the old force-push path, generic Push controls can bypass the
intended copy.
- Provider mocks can hide lease races unless E2E uses real remote refs.