7.5 KiB
created, status, requirements, system_design, legacy_specs
| created | status | requirements | system_design | legacy_specs | |||||
|---|---|---|---|---|---|---|---|---|---|
| 2026-08-30 | implemented |
|
|
Implementation Plan: Empty Remote Repositories
Overview
This package lets Kandev launch task worktrees from empty remote repositories. It keeps remote publication behind existing explicit Push and Create PR actions.
Implementation starts with typed remote-state evidence and a marked local baseline. The Git publication flow then consumes that baseline through task runtime credentials.
Frontend error mapping, desktop and mobile evidence, and public documentation complete the delivery package.
Scope
In scope
- Classify an authenticated zero-ref advertisement as an empty remote.
- Create a deterministic empty local baseline and exact marker ref.
- Create normal task worktrees from the local baseline.
- Publish the baseline before the task branch during explicit Push and Create PR actions.
- Preserve local and remote history when another actor initializes the remote.
- Show localized recovery errors through existing desktop and mobile Changes surfaces.
- Document empty-remote launch and first publication.
Out of scope
- Create a hosted repository.
- Add project templates or initial files.
- Publish a remote ref during task launch.
- Force, reset, merge, or rebase during bootstrap recovery.
- Add change-request support for another provider.
- Add a new page, dialog, drawer, setting, or database column.
Technical approach
Remote-state evidence and local baseline
Add a typed RemoteRefState result to strict clone and refresh boundaries. Carry has_refs, empty, or unknown into the worktree request.
Add internal/gitbootstrap for the deterministic empty commit and marker-ref contract. Create the base and marker refs in one local ref transaction.
Update internal/worktree.Manager to accept only authenticated empty evidence. Create the marked baseline under the existing repository lock before normal branch planning.
Keep non-empty missing-branch, authentication, network, timeout, cancellation, and ancestry errors fail-closed.
Explicit first publication
Add one GitOperator helper that validates the marker and advertises the selected remote with task runtime credentials.
If the remote remains empty, push the marked base without force. Then use the existing task-branch push path.
Reuse the helper in ordinary Push and Create PR. Call provider change-request creation only after both refs exist.
Return bounded error codes for a changed remote, failed base publication, and failed task-branch publication after base success.
User-visible recovery
Extend the shared Git operation result types with the bounded error codes. Map them to localized Changes toasts.
Reuse the existing Changes split button, change-request dialog, mobile task layout, and mobile menu treatment. Add no new responsive composition.
Add English, Portuguese, Simplified Chinese, and Traditional Chinese catalog entries. Generate both Traditional Chinese variants through the repository script.
End-to-end evidence
Add a disposable empty Git remote fixture. Create a task through the normal task flow and make one project change.
The desktop scenario proves launch, commit, Push, base-first publication, and task-branch publication. The phone scenario proves that the existing Changes touch path reaches the same result.
The nearest mobile exemplar is the existing task layout and responsive Changes menu. The workflow uses the current scroll owner, safe-area handling, and touch targets.
Public documentation
Update the task workflow guides with the empty-remote behavior and publication boundary. Correct the existing local-repository text that still describes an unborn main branch.
Classify both pages as how-to guides. Keep provider credentials and recovery limits visible beside the relevant steps.
Tests
AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.1and001.6: strict refresh tests distinguish zero refs from missing branch and unavailable remote.AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.2through001.5: real-Git worktree tests inspect the empty tree, marker, branch, and remote refs.AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.7: multi-repository preparation tests isolate the marker and baseline.AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.1through002.4:GitOperatortests prove base-first Push and Create PR without force.AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.5through002.7: race and partial-result tests prove safe recovery and stable error codes.AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.9: provider tests prove that change-request creation starts after both pushes.AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.8: worktree tests prove that only typed zero-ref evidence permits the marked baseline.
E2E tests
apps/web/e2e/tests/git/empty-remote-repository.spec.tscovers task launch, commit, Push, remotemain, and the task branch.apps/web/e2e/tests/git/mobile-empty-remote-repository.spec.tscovers the same Push outcome through the phone Changes menu.- The mobile scenario uses the configured
mobile-chromePixel 5 project. It asserts the user result, not only control visibility.
Work orders
- Task 01: Seed Empty Remote Worktrees
- Task 02: Publish the Empty Remote Base
- Task 03: Surface Publication Recovery
- Task 04: Prove the Empty Remote Workflow
- Task 05: Document the Empty Remote Workflow
Verification results
Completed.
- Task 01:
go test ./internal/gitbootstrap ./internal/repoclone ./internal/worktree ./internal/orchestrator/executor(954 tests passed). - Task 02:
go test ./internal/agentctl/server/process ./internal/agentctl/server/api ./internal/agent/handlers ./internal/orchestrator/handlers(1,573 tests passed). - Task 03: focused Vitest suite (22 tests passed),
pnpm run i18n:check, andpnpm run typecheckpassed. - Task 04: desktop and
mobile-chromePlaywright scenarios passed. - Task 05: public-doc tests (61 passed), public-doc validation (41 pages), and
git diff --check -- docs/publicpassed. - Repository specification lint passed with
python3 scripts/lint-spec-files.py --all. - Review round: marker retirement, marked-base recovery, base mismatch, and credential-safe probe regressions passed; backend lint reports 0 issues.
- Review fixup coverage: absence-lease publication, immutable baseline refspec, post-publication race detection, local-baseline recreation, refreshed local-base fallback, deterministic Git identity, stdout/stderr separation, and credential-safe diagnostics are covered by focused regressions.
Risks
- A weak empty-remote probe can confuse a missing branch or credential error with zero refs.
- Marker heuristics can publish user history. Implementation must compare exact refs.
- Another actor can initialize the remote between advertisement and base push.
- Baseline publication can succeed before task-branch publication fails.
- Provider and executor credential routes can expose different read and write authority.
- Multi-repository task roots can route a marker or Push to the wrong repository without exact scoping.