Files
kandev/docs/plans/fork-pr-base-resolution/task-02-qualified-materialization.md
T

130 lines
7.1 KiB
Markdown

---
id: "02-qualified-materialization"
title: "Materialize the qualified PR base"
status: done
wave: 2
depends_on:
- "01-pr-base-identity"
plan: "plan.md"
requirements:
- REQ-WORKSPACES-WORKTREE-BASE-REFRESH-001
acceptance_criteria:
- AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.15
- AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.16
- AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.17
- AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.19
system_design:
- ../../specs/workspaces/system-design/worktree-base-refresh.md
---
# Task 02: Materialize the qualified PR base
## Summary
Carry qualified base identity through preparation and materialize its exact ref.
Preserve checkout-head selection, origin, push routing, and valid worktree reuse.
## In scope
- Extract a shared Git materialization primitive into `internal/common/gitbase`.
Reuse it from agentctl comparison setup and host worktree preparation.
- Forward the typed contract through lifecycle request copies, per-repository
requests, worktree creation/recreation, and remote materialization DTOs.
- Select qualified bases before branch-only fallback. Verify the fetched commit
and optional provider OID. Reject target failure without using origin/local refs.
- Preserve exact PR-head fetching from its owning namespace. Keep the PR head
and target base separate when both repositories use the same branch name.
- Test both same-name and non-default targets, OID drift, collisions, auth errors,
cancellation, linked-worktree common directories, and valid reuse.
## Out of scope
Recovery actions, changed comparison scheduling, new credentials, and new UI.
## Acceptance
- Two bare-repository fixtures prove preparation uses upstream's OID even when
fork `main` exists. The checkout still starts at the requested PR head.
- Any required qualified fetch/identity failure blocks preparation. No fallback
rewrites origin, upstream, user branches, or push configuration.
- Remote client round trips preserve the target. Existing asynchronous
comparison, ordinary worktree, and same-repository fallback tests pass.
## Verification
```bash
(cd apps/backend && go test ./internal/common/gitbase ./internal/worktree ./internal/agent/runtime/lifecycle ./internal/agent/runtime/agentctl ./internal/agentctl/server/api ./internal/agentctl/server/process -run 'Test(MaterializeQualifiedBase|CreateWorktree_QualifiedPRBase|MaterializeRepository_QualifiedPRBase|QualifiedPRBase|MaterializeComparisonTarget|ResolveRemoteDefaultBranch|ResolveBaseRefWithFallback|CreateWorktree_MissingRemoteBase)' -count=1)
(cd apps/backend && go test ./internal/common/gitbase ./internal/worktree ./internal/agent/runtime/lifecycle ./internal/agent/runtime/agentctl ./internal/agentctl/server/api ./internal/agentctl/server/process -count=1)
git diff --check
```
Start with failing same-name fork/upstream tests. Cover every changed test file
in the complete package command. Record actual results after implementation.
## Files likely touched
- `apps/backend/internal/common/gitbase/materialize.go` and `materialize_test.go` (new)
- `apps/backend/internal/worktree/worktree.go`
- `apps/backend/internal/worktree/manager_lifecycle.go`
- `apps/backend/internal/worktree/manager_pr_base.go` and `manager_pr_base_test.go` (new)
- `apps/backend/internal/agent/runtime/lifecycle/types.go`
- `apps/backend/internal/agent/runtime/lifecycle/env_preparer.go`
- `apps/backend/internal/agent/runtime/lifecycle/env_preparer_worktree.go`
- `apps/backend/internal/agent/runtime/lifecycle/manager_launch.go`
- `apps/backend/internal/agent/runtime/lifecycle/manager_execution.go`
- `apps/backend/internal/agent/runtime/lifecycle/workspace_materialization.go`
- `apps/backend/internal/agent/runtime/lifecycle/qualified_pr_base_test.go` (new)
- `apps/backend/internal/agent/runtime/agentctl/client_workspace_sources.go`
- `apps/backend/internal/agent/runtime/agentctl/client_workspace_sources_test.go`
- `apps/backend/internal/agentctl/server/api/workspace_materialize.go`
- `apps/backend/internal/agentctl/server/api/workspace_materialize_pr_base_test.go` (new)
- `apps/backend/internal/agentctl/server/process/comparison_target.go`
- `apps/backend/internal/agentctl/server/process/comparison_target_test.go`
## Dependencies
Task 01 supplies validated target identity and provider observations.
Read scoped agentctl and API guidance before changing their code.
## Risks
Preparation and background comparison have different failure policies. Share
only the Git primitive. Preserve context deadlines and task credential scopes.
Do not add the same target fetch to both preparation and immediate reuse.
## Parallelism
`sequential`
## Inputs
- Worktree base refresh design: Preparation and materialization.
- Existing `materializeComparisonTarget` implementation and its tests.
- Existing live-default, stacked-PR, and remote-contribution worktree tests.
## Results
- Added `internal/common/gitbase.Materialize` for deterministic qualified
remote setup, exact branch fetch, commit resolution, and optional provider
OID verification. Agentctl comparison materialization now uses the shared
primitive and keeps its existing asynchronous status/error policy.
- Host worktree creation and recreation carry the qualified target, bypass
branch/default fallback, preserve cancellation, and fetch the PR snapshot
from the validated base repository separately from the target branch.
- Qualified remote checkout reuse now fetches and verifies the pinned base OID
and PR head before accepting an existing checkout. PR-head fetches return the
observed commit OID, and branch restoration uses that immutable object ID.
- When a qualified base and contribution binding coexist, both materializers
verify the PR number, branches, base attachment, and source repository. A
same-number, same-branch contribution from another fork is rejected.
- Lifecycle single-repository, multi-repository, workspace recovery, and remote
materialization requests preserve the typed PR base. Remote agentctl checks
request identity, materializes the target, and checks out the exact PR head.
- Regression coverage includes linked worktrees, same-named fork/upstream
branches, non-default target branches, PR-head preservation, stale OIDs,
collisions, authentication errors, cancellation, and DTO propagation.
- Focused verification: `go test ./internal/common/gitbase ./internal/worktree ./internal/agent/runtime/lifecycle ./internal/agent/runtime/agentctl ./internal/agentctl/server/api ./internal/agentctl/server/process -run 'Test(MaterializeQualifiedBase|CreateWorktree_QualifiedPRBase|MaterializeRepository_QualifiedPRBase|QualifiedPRBase|MaterializeComparisonTarget|ResolveRemoteDefaultBranch|ResolveBaseRefWithFallback|CreateWorktree_MissingRemoteBase)' -count=1`: passed.
- Full package verification: `go test ./internal/common/gitbase ./internal/worktree ./internal/agent/runtime/lifecycle ./internal/agent/runtime/agentctl ./internal/agentctl/server/api ./internal/agentctl/server/process -count=1`: passed.
- Task 01 regression check: `go test ./internal/github ./internal/backendapp ./internal/orchestrator/executor -run 'Test(PRBase|ResolveTaskRepoInfo|GithubPRBase)' -count=1`: passed.
- `git diff --check`: passed.