improvement: enhance AI assistant tools to handle repository ruleset merge restrictions #307

Problem

When attempting to merge PR #306 using GitHub API with merge_method: "merge", the following error occurred:

PUT https://api.github.com/repos/apstndb/spanner-mycli/pulls/306/merge: 405 Merge commits are not allowed on this repository.

Root Cause Identified

The repository has a Repository Ruleset that restricts merge methods:

Ruleset: "default branch" (ID: 6095644)

{
  "rules": [{
    "type": "pull_request",
    "parameters": {
      "allowed_merge_methods": ["squash"]
    }
  }]
}

This ruleset only allows squash merge, which explains why the merge method failed but squash succeeded.

Impact on AI Assistant Workflows

• Development tools that attempt programmatic merging may fail unexpectedly
• AI assistants need to adapt to repository-specific merge restrictions
• Current tools don't query ruleset configuration before attempting merges

Proposed Improvements

1. Add Ruleset-Aware Merge Strategy

Enhance development tools with intelligent merge method selection:

func GetAllowedMergeMethods(owner, repo string) ([]string, error) {
    // Query repository rulesets
    rulesets, err := gh.API("repos/{owner}/{repo}/rulesets", owner, repo)
    if err != nil {
        return nil, err
    }
    
    // Parse pull_request rules to extract allowed_merge_methods
    // Return intersection of repository settings and ruleset restrictions  
    return allowedMethods, nil
}

func SmartMerge(owner, repo string, prNumber int) error {
    allowedMethods, err := GetAllowedMergeMethods(owner, repo)
    if err != nil {
        // Fallback to default preference order
        allowedMethods = []string{"squash", "merge", "rebase"}
    }
    
    for _, method := range allowedMethods {
        if err := attemptMerge(owner, repo, prNumber, method); err == nil {
            log.Printf("✅ Merged using %s method", method)
            return nil
        }
    }
    return fmt.Errorf("all allowed merge methods failed")
}

2. Update Development Tools

Modify bin/gh-helper and bin/spanner-mycli-dev to:

• Query repository rulesets before attempting merges
• Default to squash method for this repository (based on current ruleset)
• Provide clear feedback about which method was used and why
• Cache ruleset information to avoid repeated API calls

3. Enhanced Error Messages

When merge attempts fail, provide actionable feedback:

❌ Merge failed: Repository ruleset allows only squash merges
✅ Attempting squash merge instead...
✅ PR #306 merged successfully using squash method

4. Documentation Updates

Update CLAUDE.md and development documentation:

## Repository Merge Configuration
- **Allowed methods**: Squash only (enforced by repository ruleset)
- **AI assistant default**: Use squash merge for all automated operations
- **Manual override**: Not available due to ruleset restrictions

Implementation Priority

High - This affects the reliability of AI assistant development workflows and causes unexpected failures during routine operations.

Technical Details

Repository Rulesets (newer feature) take precedence over legacy Branch Protection Rules:

• Repository settings: mergeCommitAllowed: true (allows merge commits)
• Ruleset restriction: "allowed_merge_methods": ["squash"] (overrides repository settings)
• Result: Only squash merges are permitted despite repository settings

Verification Steps

1. Test smart merge strategy with different repositories
2. Verify ruleset parsing handles all merge method combinations
3. Confirm error messages are clear and actionable
4. Update existing tools to use new merge strategy

Related Documentation

• GitHub Repository Rulesets API
• Pull Request Merge Methods

Benefits

• Reliability: Tools work consistently across different repository configurations
• User Experience: Clear feedback about merge methods and restrictions
• Maintainability: Centralized merge logic that adapts to repository policies
• Future-proof: Handles both legacy branch protection and modern rulesets