git 4.3.2 → 5.0.0.beta.2

data/.github/prompts/iteratively-address-copilot-reviews.prompt.md

@@ -0,0 +1,188 @@
+---
+agent: agent
+model: claude-sonnet-4.6
+description: Address all unresolved Copilot review threads on the active pull request until there are no remaining unresolved review threads
+---
+
+Address unresolved **Copilot** review threads on the active pull request. Ignore threads opened by human reviewers. Ask me for clarification or decisions as needed.
+
+If any terminal script command fails, stop immediately. Do not continue the loop, do not resolve additional threads, and do not request a new review. Report: the failed command, exit code, and the most relevant stderr output. **Exception**: the reply POST in Step 3 is intentionally non-fatal — a 404 after a force-push is expected and the resolve step must still run.
+
+## Terminology
+
+- **Review** — a top-level review submission by `copilot-pull-request-reviewer`, with a `submittedAt` timestamp and an optional summary body. A single review may contain zero or more Review Threads.
+- **Review Thread** — an inline comment thread attached to a specific code location. Key fields: `id` (GraphQL node ID, e.g. `PRRT_…`), `isResolved` (manually resolved by a maintainer), `isOutdated` (the underlying code changed since the thread was created). Each thread has one or more comments; the first comment is Copilot's suggestion.
+- **Check Run** — a standard CI status object on the HEAD commit. Note: Copilot Reviews do **not** create a Check Run; use the Reviews API to detect completion instead.
+
+## Before the Loop
+
+Run in terminal to establish `OWNER`, `REPO`, and `PR_NUMBER` for use throughout:
+
+```bash
+set -euo pipefail
+OWNER=$(gh repo view --json owner --jq '.owner.login')
+REPO=$(gh repo view --json name --jq '.name')
+PR_NUMBER=$(gh pr view --json number --jq '.number')
+: "${OWNER:?failed to resolve OWNER}"
+: "${REPO:?failed to resolve REPO}"
+: "${PR_NUMBER:?failed to resolve PR_NUMBER}"
+```
+
+Fetch unresolved, non-outdated Copilot Review Threads:
+
+```bash
+set -euo pipefail
+: "${OWNER:?missing OWNER}"
+: "${REPO:?missing REPO}"
+: "${PR_NUMBER:?missing PR_NUMBER}"
+threads_json=$(gh api graphql -f query='
+  query($owner:String!,$repo:String!,$pr:Int!){
+    repository(owner:$owner,name:$repo){
+      pullRequest(number:$pr){
+        reviewThreads(first:100){nodes{id isResolved isOutdated path
+          comments(first:1){nodes{databaseId author{login} createdAt body}}}}}}
+  }' -f owner="$OWNER" -f repo="$REPO" -F pr="$PR_NUMBER" \
+  --jq '.data.repository.pullRequest.reviewThreads.nodes')
+if [[ $(echo "$threads_json" | jq 'length') -ge 100 ]]; then
+  echo "Error: the PR already has 100 threads or more. Aborting."
+  exit 1
+fi
+echo "$threads_json" | jq '[.[] |
+  select(.isResolved==false) |
+  select(.isOutdated==false) |
+  select(.comments.nodes[0].author.login=="copilot-pull-request-reviewer")]'
+```
+
+- **Results non-empty** → proceed directly to the iteration loop.
+- **Results empty** → record `REVIEW_REQUESTED_AT` (current UTC, `YYYY-MM-DDTHH:MM:SSZ`, e.g. `2026-06-16T12:00:00Z`), request a new Copilot Review using the `mcp_github_mcp_se_request_copilot_review` tool (owner, repo, pullNumber), then jump to the **Wait for Review** section below.
+
+## Iteration Loop
+
+Repeat up to **${input:maxIterations:5}** iterations:
+
+### 1. Address threads
+
+Re-fetch unresolved, non-outdated Copilot Review Threads using the same `gh api graphql` query from Before the Loop. Group by file. For each file, read it once and address all its threads in that single pass:
+- Validate each suggestion before accepting it.
+- If a suggestion is invalid or out of scope: reply explaining why, then resolve the thread without changing code.
+- Otherwise: implement the change using TDD where possible; ensure test coverage.
+
+Skip any thread where `isOutdated` is true — the code it references has already changed; Copilot will re-evaluate it in the next Review.
+
+After all threads are addressed, run `rake`. If it fails, capture `rake 2>&1 | tail -n 50` and fix the failure before continuing.
+
+### 2. Commit and push
+
+Amend each change into the most relevant existing commit on the branch based on file name. If a change spans multiple commits or doesn't map clearly to one, ask me which commit to amend into (or whether to create a new commit). Confirm the working tree is clean and `rake` passes, then force push.
+
+### 3. Reply and resolve
+
+For each addressed thread object from the unresolved-threads query, in the same `run_in_terminal` script block that performs reply/resolve, export:
+
+- `COMMENT_DBID=.comments.nodes[0].databaseId`
+- `THREAD_ID=.id`
+- `EXPLANATION` to your plain-language fix summary for that thread
+
+Set the per-thread variables (`COMMENT_DBID`, `THREAD_ID`, `EXPLANATION`) immediately before running the commands below — do not rely on them surviving from a prior terminal invocation.
+
+Then post a reply and resolve it:
+
+```bash
+set -euo pipefail
+: "${OWNER:?missing OWNER}"
+: "${REPO:?missing REPO}"
+: "${COMMENT_DBID:?missing COMMENT_DBID}"
+: "${EXPLANATION:?missing EXPLANATION}"
+
+# Reply (COMMENT_DBID = databaseId of the thread's first comment)
+# Build JSON via jq to safely handle quotes/newlines/special chars in EXPLANATION.
+# EXPLANATION should contain the full reply text (e.g. "Fixed: ..." or "Not addressing this because...").
+BODY_JSON=$(jq -n --arg body "$EXPLANATION" '{body:$body}')
+# Non-fatal: a force-push can mark threads as outdated, causing the REST reply to return 404.
+# Always continue to the GraphQL resolve step regardless.
+gh api "repos/$OWNER/$REPO/pulls/comments/$COMMENT_DBID/replies" \
+  -X POST --input - <<<"$BODY_JSON" \
+  || echo "Warning: reply POST failed (thread may be outdated after force-push) — skipping reply, will still resolve"
+
+: "${THREAD_ID:?missing THREAD_ID}"
+
+# Resolve (THREAD_ID = GraphQL node id, e.g. PRRT_...)
+gh api graphql \
+  -f query='mutation($id:ID!){resolveReviewThread(input:{threadId:$id}){thread{isResolved}}}' \
+  -f id="$THREAD_ID"
+```
+
+### 4. Request review
+
+**If this was the ${input:maxIterations:5}th iteration**, skip steps 4 and 6 entirely — go directly to step 5 (Report) and then produce the Final Report.
+
+Otherwise, capture `REVIEW_REQUESTED_AT` by running `date -u +%Y-%m-%dT%H:%M:%SZ` in the terminal immediately before requesting the review. Then request a new Copilot Review using the `mcp_github_mcp_se_request_copilot_review` tool (owner, repo, pullNumber).
+
+### 5. Report
+
+List what was addressed and how each issue was resolved.
+
+### 6. Wait
+
+Jump to the **Wait for Review** section below. Return here to begin the next iteration once the new Copilot Review has been submitted.
+
+## Wait for Review
+
+**[BLOCKING — do not proceed until complete]** Poll for a new Copilot Review submission using the Reviews API. A Review with `submittedAt >= REVIEW_REQUESTED_AT` is the authoritative completion signal — it fires even when Copilot produces zero Review Threads.
+
+Run the following script via `run_in_terminal` (sync mode, timeout 750000 ms). Set the four variables on the first line to their actual values. On success, capture the script's last output line; on failure, follow the global failure-reporting rule (failed command, exit code, relevant stderr):
+
+```bash
+set -euo pipefail
+# Replace with actual values. REVIEW_REQUESTED_AT = output of `date -u +%Y-%m-%dT%H:%M:%SZ` captured just before requesting the review.
+OWNER="ruby-git"; REPO="ruby-git"; PR_NUMBER="1439"; REVIEW_REQUESTED_AT="2026-06-16T12:00:00Z"
+: "${OWNER:?missing OWNER}"
+: "${REPO:?missing REPO}"
+: "${PR_NUMBER:?missing PR_NUMBER}"
+: "${REVIEW_REQUESTED_AT:?missing REVIEW_REQUESTED_AT}"
+START=$(date +%s)
+for i in $(seq 1 60); do
+  new_review=$(gh pr view "$PR_NUMBER" --repo "$OWNER/$REPO" --json reviews \
+    --jq "[.reviews[] | select(.author.login==\"copilot-pull-request-reviewer\") | select(.submittedAt != null) | select(.submittedAt | fromdateiso8601 >= (\"$REVIEW_REQUESTED_AT\" | fromdateiso8601))] | length") \
+    || { rc=$?; echo "Error: gh pr view failed (exit $rc)"; exit $rc; }
+  if [[ -n "$new_review" && "$new_review" -gt 0 ]]; then
+    raw_nodes=$(gh api graphql -f query='
+      query($owner:String!,$repo:String!,$pr:Int!){
+        repository(owner:$owner,name:$repo){
+          pullRequest(number:$pr){
+            reviewThreads(first:100){nodes{isResolved isOutdated comments(first:1){nodes{author{login}}}}}
+          }
+        }
+      }' -f owner="$OWNER" -f repo="$REPO" -F pr="$PR_NUMBER" \
+      --jq '.data.repository.pullRequest.reviewThreads.nodes') \
+      || { rc=$?; echo "Error: gh api graphql failed (exit $rc)"; exit $rc; }
+    if [[ $(echo "$raw_nodes" | jq 'length') -ge 100 ]]; then
+      echo "Error: the PR already has 100 threads or more. Aborting."
+      exit 1
+    fi
+    count=$(echo "$raw_nodes" | jq "[.[] |
+      select(.isResolved==false) |
+      select(.isOutdated==false) |
+      select(.comments.nodes[0].author.login==\"copilot-pull-request-reviewer\")] | length")
+    echo "done: $count threads"  # count of all unresolved non-outdated Copilot Review Threads
+    exit 0
+  fi
+  elapsed=$(( $(date +%s) - START ))
+  echo "Waiting for Copilot Review to complete... (${elapsed}s elapsed)"
+  sleep 10
+done
+echo "timed out after 60 polls"
+exit 1
+```
+
+**If `timed out after 60 polls`**: stop immediately and ask me whether to re-request the review and retry, or abort.
+
+**If `done: 0 threads`**: the loop is complete — exit.
+
+**If `done: N threads`** (N > 0): begin the next iteration.
+
+## Final Report
+
+- Total iterations completed
+- Total threads addressed
+- Unresolved threads in the final Copilot review (should be 0 if the loop exited cleanly)

data/.github/pull_request_template.md

@@ -13,5 +13,7 @@ Review our [guidelines for contributing](https://github.com/ruby-git/ruby-git/bl
 - [ ] I reviewed and applied the project's [AI Policy](../AI_POLICY.md). I understand
   and verify any AI-assisted changes included in this PR and ensured they meet
   quality, security, and licensing standards.
-- [ ] Tests added/updated as needed and `rake` passes locally.
+- [ ] I ran `bundle exec rake` locally on this branch and it passed (see
+  [Local development setup](../CONTRIBUTING.md#local-development-setup)).
+- [ ] Tests added/updated as needed.
 - [ ] Documentation updated where applicable (README and/or YARD).

data/.github/skills/breaking-change-analysis/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: breaking-change-analysis
+description: "Assesses the impact of API changes before implementation to understand what code would break and plan appropriate migration paths. Use when removing methods, changing interfaces, or planning deprecations."
+---
+
+# Breaking Change Analysis Workflow
+
+Assess the impact of API changes before implementation. Use when removing methods,
+changing method signatures, altering return types/values, changing exception types,
+or modifying default behavior.
+
+## Contents
+
+- [How to use this skill](#how-to-use-this-skill)
+- [Related skills](#related-skills)
+- [Step 1: Identify the Change Scope](#step-1-identify-the-change-scope)
+- [Step 2: Find All Usages](#step-2-find-all-usages)
+- [Step 3: Assess and Document Impact](#step-3-assess-and-document-impact)
+- [Step 4: Plan Migration Path](#step-4-plan-migration-path)
+
+## How to use this skill
+
+Attach this file to your Copilot Chat context, then invoke it with the specific
+API/method change you are considering. Use this workflow before coding to assess
+impact and plan migration.
+
+## Related skills
+
+- [Review Backward Compatibility](../review-backward-compatibility/SKILL.md) —
+   verify backward compatibility after command migrations
+- [Development Workflow](../development-workflow/SKILL.md) — implement required
+   changes using strict TDD
+
+## Step 1: Identify the Change Scope
+
+1. Determine which classes and methods are affected.
+2. Check API visibility (`@api public` vs `@api private` in YARD docs).
+3. Check if the change affects `Git::Lib` (facade layer used by most callers).
+
+## Step 2: Find All Usages
+
+1. **Internal usages:**
+
+   ```bash
+   grep -rn "method_name" lib/ tests/ spec/
+   ```
+
+2. **External usage (if applicable):**
+
+   ```bash
+   gh search code "Git::Base#method_name language:ruby"
+   ```
+
+## Step 3: Assess and Document Impact
+
+Produce an impact assessment:
+
+```markdown
+## Breaking Change Impact Assessment
+
+### Change Description
+[What is being changed]
+
+### Affected API
+- Class: `Git::SomeClass`
+- Method: `#some_method`
+- Current signature: `def some_method(arg, opts = {})`
+- Proposed signature: `def some_method(arg, force: false)`
+
+### Internal Impact
+- Files affected: X
+- Tests to update: Y
+
+### External Impact
+- Severity: [High/Medium/Low]
+- Migration difficulty: [Easy/Medium/Hard]
+
+### Migration Path
+[How users should update their code]
+```
+
+## Step 4: Plan Migration Path
+
+**Project versioning policy:**
+- Current release line: v4.x (heading to v5.0.0)
+- Breaking changes are batched for major releases (v5.0.0)
+- Use deprecation warnings in the current release line before removal in the next major
+
+**Deprecation approach:**
+
+```ruby
+# @deprecated Use {#new_method} instead. Will be removed in v5.0.
+def old_method(*args)
+  warn "[DEPRECATION] `old_method` is deprecated. Use `new_method` instead."
+  new_method(*args)
+end
+```
+
+**Documentation requirements:**
+- Add `@deprecated` YARD tag with migration guidance
+- Mark commits with `!` for breaking changes and include `BREAKING CHANGE:` footer
+- DO NOT update CHANGELOG.md — it is auto-generated from commit messages

data/.github/skills/ci-cd-troubleshooting/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: ci-cd-troubleshooting
+description: "Diagnoses and fixes CI/CD failures in GitHub Actions workflows. Use when CI is failing on a PR, builds are broken, or tests pass locally but fail in CI."
+---
+
+# CI/CD Troubleshooting Workflow
+
+When asked to diagnose or fix CI/CD failures (e.g., "Why is CI failing on PR #999?",
+"Fix the failing build"), follow this workflow to identify the root cause and
+optionally implement fixes.
+
+## Contents
+
+- [How to use this skill](#how-to-use-this-skill)
+- [Related skills](#related-skills)
+- [Step 1: Identify the Failure](#step-1-identify-the-failure)
+- [Step 2: Fetch Relevant Logs](#step-2-fetch-relevant-logs)
+- [Step 3: Diagnose Root Cause](#step-3-diagnose-root-cause)
+- [Step 4: Reproduce Locally (if applicable)](#step-4-reproduce-locally-if-applicable)
+- [Step 5: Report Findings or Fix](#step-5-report-findings-or-fix)
+  - [Option A: Diagnostic Report ("Why is CI failing?")](#option-a-diagnostic-report-why-is-ci-failing)
+  - [Option B: Implement Fix ("Fix the failing build")](#option-b-implement-fix-fix-the-failing-build)
+- [Step 6: Verify Fix](#step-6-verify-fix)
+- [Special Troubleshooting Considerations](#special-troubleshooting-considerations)
+
+## How to use this skill
+
+Attach this file to your Copilot Chat context, then invoke it with a failing PR
+number, branch, or CI run context. Use Option A for diagnosis-only requests and
+Option B when the user explicitly asks for a fix.
+
+## Related skills
+
+- [Test Debugging](../test-debugging/SKILL.md) — deep-dive test failure analysis
+   and flakiness fixes
+- [Development Workflow](../development-workflow/SKILL.md) — full TDD execution
+   when implementing CI fixes
+- [PR Readiness Review](../pr-readiness-review/SKILL.md) — final validation
+   before opening or updating a PR
+
+## Step 1: Identify the Failure
+
+1. **Get CI Status:**
+   - For PRs: `gh pr checks #999`
+   - For branches: `gh run list --branch <branch-name> --limit 5`
+   - Note which jobs passed and which failed
+
+2. **Categorize the Failure Type:**
+   - **Test failures** - Unit tests, integration tests failing
+   - **Linter failures** - Rubocop, YARD documentation issues
+   - **Build failures** - Dependency installation, compilation errors
+   - **Timeout failures** - Jobs exceeding time limits
+   - **Platform-specific failures** - Failing on specific Ruby version or OS
+
+3. **Identify Specific Failing Steps:**
+   - Note the exact job name and step that failed
+   - Record the Ruby version, OS, and other environment details
+
+## Step 2: Fetch Relevant Logs
+
+**CRITICAL: CI logs can be massive (100K+ lines) and exceed token limits.**
+
+1. **Get the Run ID:**
+
+   ```bash
+   gh run list --branch <branch> --limit 1 --json databaseId --jq '.[0].databaseId'
+   ```
+
+2. **Fetch Failed Job Logs Only:**
+
+   ```bash
+   gh run view <run-id> --log-failed
+   ```
+
+   This limits output to only failed jobs, making it manageable.
+
+3. **Extract Key Error Information:**
+
+   - For test failures: Look for stack traces, assertion errors, specific test names
+   - For linter failures: Extract file names, line numbers, and violation types
+   - For build failures: Find dependency errors or missing packages
+   - Use `grep` to filter logs if still too large:
+
+     ```bash
+     gh run view <run-id> --log-failed | grep -A 10 -B 5 "Error\|FAILED\|Failure"
+     ```
+
+4. **Avoid Full Log Downloads:**
+
+   - Do NOT use `--log` without `--log-failed` unless specifically requested
+   - If logs are still too large, focus on the most recent or critical failure
+
+## Step 3: Diagnose Root Cause
+
+Based on the failure type, investigate:
+
+**For Test Failures:**
+
+- Check if the test exists and what it's testing
+- Look for recent changes that might have broken the test
+- Consider environment differences (local vs. CI)
+- Check for flaky tests (intermittent failures)
+
+**For Linter Failures:**
+
+- Run linters locally: `bundle exec rubocop` and `bundle exec rake yard`
+- Identify specific violations from the log
+- Check if violations are in files related to recent changes
+
+**For Build Failures:**
+
+- Check dependency versions in `Gemfile` and `git.gemspec`
+- Look for platform-specific dependency issues
+- Verify Ruby version compatibility
+
+**For Timeout Failures:**
+
+- Identify which test or step is timing out
+- Check for infinite loops or performance regressions
+- Consider if it's a resource limitation in CI environment
+
+## Step 4: Reproduce Locally (if applicable)
+
+**For PR Failures:**
+
+1. Fetch the PR branch:
+
+   ```bash
+   gh pr checkout #999
+   ```
+
+2. Run the failing tests locally:
+
+   ```bash
+   bundle exec bin/test <test-name>
+   ```
+
+3. Run linters:
+
+   ```bash
+   bundle exec rubocop
+   bundle exec rake yard
+   ```
+
+**For Branch Failures:**
+
+1. Checkout the branch.
+2. Run full CI workflow:
+
+   ```bash
+   bundle exec rake default
+   ```
+
+## Step 5: Report Findings or Fix
+
+Determine the appropriate action based on the user's request:
+
+### Option A: Diagnostic Report ("Why is CI failing?")
+
+Present findings to the user:
+
+````markdown
+# CI Failure Diagnosis: <Branch/PR>
+
+**Status:** <X of Y jobs failed>
+
+## Failed Jobs
+1. **<Job Name>** (<Ruby version>, <OS>)
+   - **Step:** <failing step name>
+   - **Failure Type:** <test/linter/build/timeout>
+
+## Root Cause
+<Explanation of what's causing the failure>
+
+## Error Details
+```
+<Relevant error messages and stack traces>
+```
+
+## Recommendations
+- <Specific fix suggestion 1>
+- <Specific fix suggestion 2>
+
+**Would you like me to implement a fix, or do you need more information?**
+````
+
+**STOP here** unless the user asks you to proceed with fixes.
+
+### Option B: Implement Fix ("Fix the failing build")
+
+Proceed based on failure type:
+
+- **Test Failures:** Use the full TDD workflow (Phase 1-3) to fix the failing tests
+- **Linter Failures:** Fix violations directly, commit with appropriate message
+  (e.g., `style: fix rubocop violations in lib/git/base.rb`)
+- **Build Failures:** Update dependencies or configuration as needed
+- **Timeout Failures:** Investigate performance issues, may require user guidance
+
+**For PR Failures on Someone Else's PR:**
+
+- You may not have push access to their branch
+- Present the fix and ask user to either:
+  - Push to the PR branch (if they have access)
+  - Comment on the PR with suggested changes
+  - Create a new PR with fixes
+
+## Step 6: Verify Fix
+
+After implementing fixes:
+
+1. **Run Affected Tests Locally:**
+
+   ```bash
+   bundle exec bin/test <test-name>
+   ```
+
+2. **Run Full CI Suite:**
+
+   ```bash
+   bundle exec rake default
+   ```
+
+3. **Push and Monitor:**
+
+   - Push the fixes
+   - Monitor CI to confirm the fix worked:
+
+     ```bash
+     gh run watch
+     ```
+
+4. **Confirm Resolution:**
+
+   ```text
+   Fix implemented and pushed. Monitoring CI run...
+   CI Status: <link to run>
+   ```
+
+## Special Troubleshooting Considerations
+
+**Platform-Specific Failures:**
+
+- If tests pass on macOS but fail on Linux/Windows, document the difference
+- Check for path separator issues (`/` vs. `\`)
+- Look for encoding differences
+- Consider file system case sensitivity
+
+**Flaky Tests:**
+
+- If a test fails intermittently, note this in your diagnosis
+- Run the test multiple times locally to confirm flakiness
+- Suggest fixes for race conditions or timing issues
+
+**Permission Issues:**
+
+- If you can't push to a PR branch, clearly communicate this limitation
+- Provide the exact commands or changes needed for the user to apply
+
+**Token Limit Management:**
+
+- Always use `--log-failed` to limit output
+- If logs are still too large, use `grep` to extract errors
+- Focus on the first failure if multiple failures exist
+- Consider running tests locally instead of relying on full CI logs