3.5 KiB
3.5 KiB
status, system, created, owners
| status | system | created | owners | |
|---|---|---|---|---|
| draft | workspaces | 2026-08-25 |
|
Worktree Base Refresh Requirements
Overview
The workspace system owns the base ref for a task worktree. A host worktree can use a local base without remote publication. Remote refresh improves freshness, but it must not prevent intentional local development.
Remote materialization has a different contract. If Kandev has no usable local base, it must obtain the selected branch before it creates the worktree.
Terminology
- Local base: A valid local ref that Kandev can use to create the worktree.
- Best-effort refresh: A remote refresh attempt that can fall back to a local base.
- Required materialization: A remote fetch that is necessary because no usable local base exists.
- Fetched remote base: The remote-tracking ref from a successful fetch.
Requirements
REQ-WORKSPACES-WORKTREE-BASE-REFRESH-001: Local-First Worktree Base
Intent: Preserve local development while Kandev attempts to refresh remote state before worktree creation.
User story: As a workspace user, I want Kandev to create worktrees from my local branches without publishing them first.
Acceptance criteria
- AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.1: When pull-before-worktree is disabled, Kandev shall use an available local base without remote access.
- AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.2: When pull-before-worktree is enabled and a local base exists, Kandev shall attempt a remote refresh before it creates or recreates the worktree.
- AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.3: When refresh has an authentication, network, timeout, missing-branch, or non-cancellation Git error, Kandev shall use the local base and show a credential-safe warning.
- AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.4: When the refresh succeeds, Kandev shall preserve local-only commits and include compatible remote commits when one ref contains the other.
- AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.5: When local and remote refs diverge, Kandev shall preserve the selected local base and show a warning.
- AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.6: When no local base exists, Kandev shall stop preparation if required materialization cannot provide the selected branch.
- AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.7: When one repository in a multi-repository task has a usable local fallback, its refresh error shall not stop the task agent.
- AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.8: When required materialization fails for any repository, Kandev shall stop the task agent and identify that repository in a credential-safe error.
- AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.9: When an authenticated remote
advertises zero refs, Kandev shall use the marked local baseline from
REQ-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001. - AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.10: When the caller cancels preparation, Kandev shall stop without creating a fallback worktree.
Compatibility
This requirement replaces the universal fail-closed refresh behavior from Kandev v0.92.1. Remote-only executors and branches keep strict materialization.
Out of scope
- Making setup-script errors fatal.
- Refreshing a valid worktree that Kandev reuses.
- Adding a background repository-refresh service.
- Resetting, rebasing, merging, or removing local refs.
- Changing agent Git transport after the agent starts.
- Pushing a local branch during worktree preparation.