Merge pull request #272 from morluto/agent/fork-freshness-preflight

feat(preflight): detect stale contributor forks

Author: morluto

docs/mcp-composed-workflows.md

@@ -114,6 +114,15 @@ decides whether an agent should start work. Agents select the current-work,
 portfolio, overlap, or Git comparison facts appropriate to the task. Unknown
 discovery or facet coverage prevents a “no competing work” conclusion.
 
+`workflow.preflight_contribution` also reports `fork_freshness` when the caller
+supplies a fork or the inspected workspace provides one unambiguous contributor
+remote. The read resolves both default-branch tips and compares them through
+the upstream fork network, preserving merge-base evidence and the current
+contribution branch when available. `current`, `behind`, and `diverged` are
+verified states; an unavailable fork or incomplete comparison remains unknown.
+The check never fetches local refs, synchronizes a fork, force-pushes, or
+mutates GitHub.
+
 ## Unified catalog
 
 The managed server advertises the unified `all` catalog. Current Codex and

internal/app/mcp_contribution_fork.go

@@ -0,0 +1,217 @@
+package app
+
+import (
+	"context"
+	"strings"
+
+	"github.com/morluto/gitcontribute/internal/github"
+	"github.com/morluto/gitcontribute/internal/gitremote"
+	"github.com/morluto/gitcontribute/internal/mcpcontract"
+	"github.com/morluto/gitcontribute/internal/workspace"
+)
+
+const forkFreshnessRequestCost = 5
+
+type preflightForkContext struct {
+	ref    mcpcontract.RepositoryRef
+	branch string
+	sha    string
+}
+
+// checkPreflightForkFreshness performs only provider reads. It never fetches
+// local refs or updates the fork; the compare API supplies the merge-base
+// evidence across the upstream repository network.
+func checkPreflightForkFreshness(
+	ctx context.Context,
+	reader github.Reader,
+	upstream mcpcontract.RepositoryRef,
+	fork *mcpcontract.RepositoryRef,
+	identity string,
+	candidate mcpcontract.ContributionPreflightCandidate,
+	worktrees []workspace.LocalWorktree,
+	existing *preflightExisting,
+	maxRequests int,
+	requests int,
+) (mcpcontract.ForkFreshnessOutput, bool, error) {
+	forkContext, shouldCheck, reason := resolvePreflightFork(upstream, fork, identity, candidate, worktrees, existing)
+	if !shouldCheck {
+		return mcpcontract.ForkFreshnessOutput{}, false, nil
+	}
+	result := newForkFreshnessOutput(upstream, reason)
+	if forkContext != nil {
+		result.Fork = forkContext.ref
+		result.ContributionBranch = forkContext.branch
+		result.ContributionSHA = forkContext.sha
+	}
+	if reason != "" {
+		return result, true, nil
+	}
+	if forkContext == nil {
+		result.Reason = "contributor fork could not be identified from the supplied context"
+		return result, true, nil
+	}
+	if maxRequests-requests < forkFreshnessRequestCost {
+		result.Reason = "request budget cannot fund complete fork freshness coverage"
+		return result, true, nil
+	}
+	branchReader, hasBranchReader := reader.(github.BranchReader)
+	comparisonReader, hasComparisonReader := reader.(github.CommitComparisonReader)
+	if !hasBranchReader {
+		result.Reason = "configured GitHub reader does not support branch-tip reads"
+		return result, true, nil
+	}
+	if !hasComparisonReader {
+		result.Reason = "configured GitHub reader does not support fork ancestry comparison"
+		return result, true, nil
+	}
+
+	upstreamRepo, _, err := reader.GetRepository(ctx, upstream.Owner, upstream.Repo)
+	if err != nil {
+		return forkFreshnessUnavailable(result, "upstream repository metadata could not be read", err)
+	}
+	forkRepo, _, err := reader.GetRepository(ctx, forkContext.ref.Owner, forkContext.ref.Repo)
+	if err != nil {
+		return forkFreshnessUnavailable(result, "fork repository metadata could not be read", err)
+	}
+	if !forkRepo.Fork || forkRepo.Parent == nil || !sameGitHubRepository(forkRepo.Parent.Owner, forkRepo.Parent.Name, upstream) {
+		result.Reason = "selected repository is not a fork of the requested upstream repository"
+		return result, true, nil
+	}
+	if strings.TrimSpace(upstreamRepo.DefaultBranch) == "" || strings.TrimSpace(forkRepo.DefaultBranch) == "" {
+		result.Reason = "upstream or fork default branch is unavailable"
+		return result, true, nil
+	}
+	result.UpstreamBranch = upstreamRepo.DefaultBranch
+	result.ForkBranch = forkRepo.DefaultBranch
+
+	upstreamBranch, _, err := branchReader.GetBranch(ctx, upstream.Owner, upstream.Repo, upstreamRepo.DefaultBranch)
+	if err != nil {
+		return forkFreshnessUnavailable(result, "upstream default branch could not be read", err)
+	}
+	forkBranch, _, err := branchReader.GetBranch(ctx, forkContext.ref.Owner, forkContext.ref.Repo, forkRepo.DefaultBranch)
+	if err != nil {
+		return forkFreshnessUnavailable(result, "fork default branch could not be read", err)
+	}
+	result.UpstreamSHA = upstreamBranch.CommitSHA
+	result.ForkSHA = forkBranch.CommitSHA
+	if result.UpstreamSHA == "" || result.ForkSHA == "" {
+		result.Reason = "upstream or fork default branch did not include a commit SHA"
+		return result, true, nil
+	}
+
+	comparison, _, err := comparisonReader.CompareCommits(ctx, upstream.Owner, upstream.Repo, upstreamRepo.DefaultBranch, forkContext.ref.Owner+":"+forkRepo.DefaultBranch)
+	if err != nil {
+		return forkFreshnessUnavailable(result, "upstream and fork default branches could not be compared", err)
+	}
+	if comparison.BaseSHA != "" && !strings.EqualFold(comparison.BaseSHA, result.UpstreamSHA) {
+		result.Reason = "comparison base SHA did not match the resolved upstream default branch"
+		return result, true, nil
+	}
+	if comparison.MergeBaseSHA == "" {
+		result.Reason = "comparison did not provide merge-base evidence"
+		return result, true, nil
+	}
+	result.Status, result.NextAction = classifyForkFreshness(comparison.Status)
+	if result.Status == "unavailable" {
+		result.Reason = "GitHub returned an unsupported fork comparison status"
+		return result, true, nil
+	}
+	result.MergeBaseSHA = comparison.MergeBaseSHA
+	result.AheadBy = comparison.AheadBy
+	result.BehindBy = comparison.BehindBy
+	result.Coverage = "verified"
+	result.EffectiveDiffRisk = result.Status != "current"
+	return result, true, nil
+}
+
+func resolvePreflightFork(
+	upstream mcpcontract.RepositoryRef,
+	explicit *mcpcontract.RepositoryRef,
+	identity string,
+	candidate mcpcontract.ContributionPreflightCandidate,
+	worktrees []workspace.LocalWorktree,
+	existing *preflightExisting,
+) (*preflightForkContext, bool, string) {
+	if explicit != nil {
+		return &preflightForkContext{ref: *explicit, branch: strings.TrimSpace(candidate.HeadRef), sha: strings.TrimSpace(candidate.HeadSHA)}, true, ""
+	}
+	if existing != nil && existing.details.HeadOwner != "" && existing.details.HeadRepo != "" && !sameGitHubRepository(existing.details.HeadOwner, existing.details.HeadRepo, upstream) {
+		return &preflightForkContext{
+			ref:    mcpcontract.RepositoryRef{Owner: existing.details.HeadOwner, Repo: existing.details.HeadRepo},
+			branch: existing.details.HeadRef,
+			sha:    existing.details.HeadSHA,
+		}, true, ""
+	}
+	if len(worktrees) == 0 {
+		return nil, false, ""
+	}
+
+	var candidates []preflightForkContext
+	seen := make(map[string]struct{})
+	for _, worktree := range worktrees {
+		for _, urls := range worktree.Remotes {
+			for _, remote := range urls {
+				identityRef, err := gitremote.ParseRepositoryIdentity(remote)
+				if err != nil || !strings.EqualFold(identityRef.Owner, identity) || sameGitHubRepository(identityRef.Owner, identityRef.Repo, upstream) {
+					continue
+				}
+				ref := mcpcontract.RepositoryRef{Owner: identityRef.Owner, Repo: identityRef.Repo}
+				key := strings.ToLower(ref.Owner + "/" + ref.Repo)
+				if _, ok := seen[key]; ok {
+					continue
+				}
+				seen[key] = struct{}{}
+				branch, sha := worktree.Branch, worktree.HeadSHA
+				if candidate.HeadRef != "" {
+					branch = candidate.HeadRef
+				}
+				if candidate.HeadSHA != "" {
+					sha = candidate.HeadSHA
+				}
+				candidates = append(candidates, preflightForkContext{ref: ref, branch: branch, sha: sha})
+			}
+		}
+	}
+	if len(candidates) == 1 {
+		return &candidates[0], true, ""
+	}
+	if len(candidates) > 1 {
+		return nil, true, "multiple contributor fork remotes were found; provide fork explicitly"
+	}
+	return nil, true, "no contributor fork remote was found in the supplied workspaces"
+}
+
+func newForkFreshnessOutput(upstream mcpcontract.RepositoryRef, reason string) mcpcontract.ForkFreshnessOutput {
+	return mcpcontract.ForkFreshnessOutput{
+		Status:     "unavailable",
+		Coverage:   "unavailable",
+		Upstream:   upstream,
+		Reason:     reason,
+		NextAction: "provide_fork_context_or_retry_freshness_check",
+	}
+}
+
+func forkFreshnessUnavailable(result mcpcontract.ForkFreshnessOutput, reason string, err error) (mcpcontract.ForkFreshnessOutput, bool, error) {
+	if contextError(err) {
+		return mcpcontract.ForkFreshnessOutput{}, false, err
+	}
+	result.Reason = reason
+	return result, true, nil
+}
+
+func classifyForkFreshness(providerStatus string) (string, string) {
+	switch providerStatus {
+	case "identical":
+		return "current", "publish_contribution"
+	case "behind":
+		return "behind", "sync_fork_or_fast_forward_only_update"
+	case "ahead", "diverged":
+		return "diverged", "inspect_fork_history_before_publishing"
+	default:
+		return "unavailable", "retry_freshness_check"
+	}
+}
+
+func sameGitHubRepository(owner, repo string, ref mcpcontract.RepositoryRef) bool {
+	return strings.EqualFold(strings.TrimSpace(owner), strings.TrimSpace(ref.Owner)) && strings.EqualFold(strings.TrimSpace(repo), strings.TrimSpace(ref.Repo))
+}

internal/app/mcp_contribution_preflight.go

@@ -29,6 +29,16 @@ func (r *MCPReader) PreflightContribution(ctx context.Context, in mcpcontract.Co
 	}
 	in.Repository.Owner = strings.TrimSpace(in.Repository.Owner)
 	in.Repository.Repo = strings.TrimSpace(in.Repository.Repo)
+	if in.Fork != nil {
+		in.Fork.Owner = strings.TrimSpace(in.Fork.Owner)
+		in.Fork.Repo = strings.TrimSpace(in.Fork.Repo)
+		if err := (domain.RepoRef{Owner: in.Fork.Owner, Repo: in.Fork.Repo}).Validate(); err != nil {
+			return mcpcontract.ContributionPreflightOutput{}, fmt.Errorf("validate fork repository: %w", err)
+		}
+		if sameGitHubRepository(in.Fork.Owner, in.Fork.Repo, in.Repository) {
+			return mcpcontract.ContributionPreflightOutput{}, errors.New("fork repository must differ from the upstream repository")
+		}
+	}
 	if in.Limit == 0 {
 		in.Limit = defaultContributionPreflightLimit
 	}
@@ -182,6 +192,16 @@ func (r *MCPReader) PreflightContribution(ctx context.Context, in mcpcontract.Co
 		out.Status = "existing_pr"
 		out.NextAction = "review_or_follow_through"
 	}
+	forkFreshness, forkChecked, forkErr := checkPreflightForkFreshness(ctx, reader, in.Repository, in.Fork, identity.Login, in.Candidate, worktrees, existingMatch(existing), in.MaxRequests, requests)
+	if forkErr != nil {
+		return mcpcontract.ContributionPreflightOutput{}, forkErr
+	}
+	if forkChecked {
+		out.ForkFreshness = &forkFreshness
+		if forkFreshness.Coverage != "verified" {
+			out.CoverageReasons = append(out.CoverageReasons, "fork freshness coverage is unavailable: "+forkFreshness.Reason)
+		}
+	}
 	if len(out.CoverageReasons) == 0 {
 		out.Coverage = "live_verified"
 		if out.Existing == nil {
@@ -192,6 +212,13 @@ func (r *MCPReader) PreflightContribution(ctx context.Context, in mcpcontract.Co
 	return out, nil
 }
 
+func existingMatch(existing []preflightExisting) *preflightExisting {
+	if len(existing) == 0 {
+		return nil
+	}
+	return &existing[0]
+}
+
 type preflightExisting struct {
 	marker  github.Issue
 	details github.PullRequestDetails