git 5.1.0 → 5.2.0

data/.github/skills/development-workflow/SKILL.md

@@ -1,512 +0,0 @@
----
-name: development-workflow
-description: "Follows a strict Test-Driven Development (TDD) workflow with four phases: triage, prepare, execute, and finalize. Use for bug fixes, feature implementation, refactoring, maintenance tasks, and issue triage / diagnosis (triage phase only for diagnosis without implementation)."
----
-
-# Development Workflow
-
-This skill implements a strict Test-Driven Development (TDD) workflow.
-
-**This project strictly follows TDD practices. All production code MUST be
-written using the TDD process described below.**
-
-## Contents
-
-- [Contents](#contents)
-- [How to use this skill](#how-to-use-this-skill)
-- [Workflow Overview](#workflow-overview)
-- [Core TDD Principles](#core-tdd-principles)
-- [Phase 0: TRIAGE](#phase-0-triage)
-- [Phase 1: PREPARE](#phase-1-prepare)
-- [Phase 2: EXECUTE](#phase-2-execute)
-  - [RED-GREEN Step](#red-green-step)
-  - [REFACTOR Step](#refactor-step)
-  - [VERIFY Step](#verify-step)
-  - [COMMIT Step](#commit-step)
-  - [REPLAN Step](#replan-step)
-- [Phase 3: FINALIZE](#phase-3-finalize)
-  - [Per-Task Commits](#per-task-commits)
-- [Related skills](#related-skills)
-- [Additional Guidelines](#additional-guidelines)
-- [Example TDD Cycle](#example-tdd-cycle)
-
-## How to use this skill
-
-Attach this file to your Copilot Chat context, then invoke it when implementing
-features, fixing bugs, refactoring, or maintaining code. Follow phases in order
-and stop after TRIAGE when the issue is non-actionable or needs clarification.
-
-## Workflow Overview
-
-When assigned a task involving a GitHub issue, follow this workflow:
-
-1. **Phase 0: TRIAGE** - Understand the issue and determine if action is needed
-2. **Phase 1: PREPARE** - Set up the environment and plan the implementation
-3. **Phase 2: EXECUTE** - Implement the solution using TDD
-4. **Phase 3: FINALIZE** - Squash commits and create the PR
-
-**Note:** Not all issues require implementation. Phase 0 may result in requesting
-clarification, confirming the issue is a duplicate, or determining no changes are
-needed.
-
-## Related skills
-
-- [RSpec Unit Testing Standards](../rspec-unit-testing-standards/SKILL.md) — RSpec rules for test structure, naming,
-  setup patterns, stubbing, and coverage; apply when writing tests during TDD cycles
-- [TDD Refactor Step](../tdd-refactor-step/SKILL.md) — detailed guidance for the
-  REFACTOR step: code smells, techniques, test cleanup, and rubocop integration
-- [Test Debugging](../test-debugging/SKILL.md) — focused diagnosis for failing or
-  flaky tests
-- [CI/CD Troubleshooting](../ci-cd-troubleshooting/SKILL.md) — workflow for CI
-  failures and environment-specific issues
-- [PR Readiness Review](../pr-readiness-review/SKILL.md) — final quality gate
-  before opening a pull request
-- [Command Implementation](../command-implementation/SKILL.md) — scaffolding and
-  reviewing `Git::Commands::*` classes during implementation
-- [Facade Implementation](../facade-implementation/SKILL.md) — scaffolding and
-  reviewing `Git::Repository::*` facade methods during implementation
-
-## Core TDD Principles
-
-Adhere to the following fundamental principles to ensure high code quality and test
-coverage:
-
-- **Never Write Production Code without a Failing Test**
-- **Bug Fixes Start with Tests:** Before fixing any bug, write a failing test that
-  demonstrates the bug and fails in the expected way. Only then fix the code to make
-  the test pass.
-- **Tests Drive Design:** Let the test dictate the API and architecture. If the test
-  is hard to write, the design is likely wrong. When this happens, stop and suggest
-  one or more design alternatives. Offer to stash any current changes and work on the
-  design improvements first before continuing with the original task.
-- **Write Tests Incrementally:** Build tests in small steps, writing just enough to
-  get the next expected failure. For example, first write a test that references a
-  class that doesn't exist (fails), then define the empty class (passes), then extend
-  the test to call a method (fails), then define the method (passes), etc.
-- **Tests Should Be Atomic:** Each test should verify exactly one logical behavior,
-  making failures easy to diagnose and understand.
-- **Prefer the Simplest Solution:** Choose the simplest implementation that could
-  possibly work, even if it seems naive. Complexity should only be added when driven
-  by actual requirements in tests.
-- **No Implementation in Advance:** Only write the code strictly needed to pass the
-  current test.
-
-## Phase 0: TRIAGE
-
-The purpose of this phase is to understand what the issue is asking for, investigate
-the current state of the codebase, and determine whether implementation is needed.
-
-**Use this phase when the user references a GitHub issue number** (e.g., "Fix issue
-\#999", "Implement \#999", "Diagnose issue \#999").
-
-1. **Fetch the Issue:** Use `gh issue view #999` to read the full issue content,
-   including description, comments, and labels.
-
-2. **Understand the Request:** Analyze what is being asked:
-   - Is this a bug report? Feature request? Question? Documentation issue?
-   - Is the issue clear and actionable, or does it need clarification?
-   - Are there reproduction steps or examples provided?
-
-3. **Search for Context:** Investigate the codebase to understand the area affected:
-   - Use `grep_search` or `semantic_search` to find relevant code
-   - Read related test files to understand existing behavior
-   - Check if similar functionality already exists
-   - Look for related issues or PRs that might be relevant
-
-4. **Reproduce (if applicable):** For bug reports:
-   - Try to reproduce the issue based on the provided steps
-   - Run existing tests to see if they catch the issue
-   - Verify the issue still exists in the current codebase
-
-5. **Determine Next Steps and Report Findings:**
-
-   **Option A: Issue needs clarification**
-   - Comment on the issue using `gh issue comment #999 --body "..."`
-   - Ask specific questions about reproduction steps, expected behavior, or use case
-   - **STOP here** - wait for user/reporter response before proceeding
-
-   **Option B: Issue is not actionable (duplicate, won't-fix, already resolved)**
-   - Comment on the issue explaining your findings
-   - Suggest closing the issue or linking to related issues
-   - **STOP here** - no implementation needed
-
-   **Option C: Issue is clear and actionable**
-   - Comment on the issue confirming you understand the request and plan to implement
-   - Summarize your understanding and proposed approach
-   - **Proceed to Phase 1: PREPARE** to begin implementation
-
-   **Option D: User asked only to diagnose (not implement)**
-   - Comment on the issue with your diagnostic findings
-   - Explain what you discovered (root cause, affected code, potential solutions)
-   - **STOP here** - wait for confirmation to proceed with implementation
-
-**GitHub CLI Commands for Phase 0:**
-
-- View issue: `gh issue view #999`
-- View with comments: `gh issue view #999 --comments`
-- Comment on issue: `gh issue comment #999 --body "Your comment here"`
-- Search issues: `gh issue list --search "keyword"`
-
-## Phase 1: PREPARE
-
-The purpose of this phase is to ensure the project environment is ready, establish a
-clean baseline, and create a clear implementation plan before writing any code.
-
-**Only proceed to this phase if Phase 0 determined that implementation is needed.**
-
-1. **Check Uncommitted Changes:** If there are any uncommitted changes in the
-   project, ask the user what to do with them before continuing: include them in the
-   current implementation plan, ignore them, or stash them before continuing.
-2. **Create Feature Branch:** Create a new branch from `origin/main` using the naming
-   convention `<type>/<short-description>` (e.g., `fix/issue-999`).
-3. **Verify Project Setup:** Run `bin/setup` to ensure that the project is ready
-   for development.
-4. **Verify Clean Baseline:** Ensure that all existing tests and linters pass by
-   running `bundle exec rake default`.
-5. **Analyze and Plan:** Understand the requirements, identify edge cases and
-   potential challenges, and break the work into small, isolated tasks. Consider what
-   tests will be needed and in what order they should be written.
-6. **Consider Refactoring:** Look for ways to make the implementation of the feature
-   or bug fix easier by performing one or more refactorings. If any are found,
-   suggest them to the user. If the user confirms the refactoring, do the refactoring
-   in a separate TDD process. Only once the refactoring is completed should the
-   current feature or bug fix be worked on.
-7. **Review Implementation Guidelines:** When implementing or modifying git command
-   wrappers, read the "Wrapping a git command" section in CONTRIBUTING.md before
-   proceeding. This ensures consistent API design
-   for method placement, naming, parameters, and output processing.
-
-## Phase 2: EXECUTE
-
-The purpose of this phase is to implement each planned task using strict TDD cycles,
-ensuring every line of production code is driven by a failing test.
-
-Execute each task by repeating the following cycle of steps until all tasks are
-complete:
-
-1. **RED-GREEN:** Write failing tests and implement code to make them pass
-2. **REFACTOR:** Improve code quality and design without changing behavior
-3. **VERIFY:** Confirm the task is complete and code meets quality standards
-4. **COMMIT:** Create a commit for the completed task
-5. **REPLAN:** Review the implementation plan, then return to step 1 for the next
-   task
-
-When all tasks are complete, proceed to **Phase 3: FINALIZE**.
-
-### RED-GREEN Step
-
-1. **RED Substep**
-
-   The purpose of this substep is to write a failing test that you hypothesize will
-   pass with the next incremental bit of task implementation.
-
-   - **Write the Test:** Write a single, focused, failing test or extend an existing
-     test for the current task.
-   - **Keep It Minimal:** Only write enough of a test to get an expected, failing
-     result (the test should fail for the *right* reason).
-   - **Execute and Analyze:** Run the specific test file (e.g.,
-     `bundle exec rspec spec/unit/git/commands/<command>_spec.rb`) and analyze the
-     output.
-   - **Confirm Expected Failure:** Confirm it fails with an expected error (e.g.,
-     assertion failure or missing definition).
-   - **Validate:** If the test passes without implementation, the test is invalid or
-     the logic already exists. When that happens, revise or skip.
-
-2. **GREEN Substep**
-
-   The purpose of this substep is to write just enough production code to make the
-   failing test(s) pass.
-
-   - **Write Minimal Code:** Write the minimum amount of code required to make the
-     test pass.
-   - **Use Simple Solutions:** It is acceptable to use hardcoded values or "quick and
-     dirty" logic here just to get to green, even if this means intentionally writing
-     clearly suboptimal code that you will improve during the REFACTOR step.
-   - **No Premature Optimization:** Do NOT optimize, clean up, or improve code style
-     during GREEN—that work belongs in the REFACTOR step.
-   - **Execute and Verify:** Run the specific test file
-     - **If the test passes**, proceed to the REFACTOR step
-     - **If the test fails**, read the FULL error output including the stack trace.
-       Identify the exact failing line and assertion before modifying any code. Fix
-       only what the error indicates, then re-run. Repeat until the test passes.
-   - **Rollback on Repeated Failure:** If the test cannot be made to pass within 3
-     attempts, revert all changes from this RED-GREEN cycle, report the issue to the
-     user, and ask for guidance before proceeding.
-   - **Stay Focused:** Do not implement future features or optimizations yet.
-
-### REFACTOR Step
-
-The purpose of this step is to improve code quality and design without changing
-behavior, ensuring the codebase remains clean and maintainable.
-
-**You must consider refactoring before starting the next task.** Remove duplication,
-improve variable names, and apply design patterns. Skip this step only if the code is
-already clean and simple—avoid over-engineering.
-
-For detailed guidance on code smells, refactoring techniques, test cleanup, and
-rubocop integration, see the
-[TDD Refactor Step](../tdd-refactor-step/SKILL.md) skill.
-
-- **Generalize the Implementation:** Ensure the code solves the general case, not
-  just the specific test case. Replace hardcoded values used to pass the test with
-  actual logic.
-- **Limit Scope:** Do not perform refactorings that affect files outside the
-  immediate scope of the current task. If a broader refactor is needed, add it to the
-  task list during the REPLAN step as a separate task.
-- **Execute All Tests:** Run `bundle exec rake default` and verify they still pass.
-- **Verify Test Independence:** Verify tests can run independently in any order.
-- **Confirm Improvement:** Ensure the refactoring made the code clearer, simpler, or
-  more maintainable.
-
-### VERIFY Step
-
-The purpose of this step is to confirm that the current task is fully complete before
-moving to the next task.
-
-- **Confirm Implementation Complete:** Verify all functionality for the task is
-  implemented.
-- **Run All Tests:** Run `bundle exec rspec` and `bundle exec rake test` to ensure
-  all tests pass.
-- **Run Linters:** Run `bundle exec rubocop` and `bundle exec rake yard` to verify
-  code style and documentation standards.
-- **Check Code Quality:** Confirm the code is clean and well-factored.
-- **Audit Command Tests (command tasks only):** If this task added or modified tests
-  for any `Git::Commands::*` class, apply the
-  [Command Test Conventions](../command-test-conventions/SKILL.md) skill to every new or
-  changed spec file before committing. Fix any violations found before moving to the
-  COMMIT step.
-- **Audit Command YARD Docs (command tasks only):** If this task added or modified
-  any `Git::Commands::*` source file, apply the
-  [Command YARD Documentation](../command-yard-documentation/SKILL.md)
-  skill to each changed source file. Fix any documentation gaps before committing.
-- **STOP on Unexpected Failure:** If any test unexpectedly fails during VERIFY, STOP
-  immediately and report the failure to the user. Do not attempt to fix the failure
-  without first explaining what went wrong and getting confirmation to proceed.
-
-### COMMIT Step
-
-The purpose of this step is to create a checkpoint after successfully completing a
-task, providing a safe rollback point.
-
-- **Create Commit:** Commit all changes from this task using the appropriate
-  conventional commit type (see the **Per-Task Commits** section below for guidance).
-- **Keep Commits Atomic:** Each commit should represent one completed task with all
-  tests passing and linters clean.
-
-### REPLAN Step
-
-The purpose of this step is to review progress and adjust the implementation plan
-based on what was learned during the current task.
-
-- **Review Implementation Plan:** Assess whether the remaining tasks are still valid
-  and appropriately scoped based on what was learned.
-- **Identify New Tasks:** If the implementation revealed new requirements, edge
-  cases, or necessary refactorings, add them to the task list.
-- **Reprioritize if Needed:** Adjust task order if dependencies or priorities have
-  changed.
-- **Sync Redesign Tracker (required for command migrations):** If the task adds,
-  migrates, or rewires any `Git::Commands::*` usage, update
-  `redesign/3_architecture_implementation.md` in the same task commit:
-  - mark migrated command checklist entries (`[ ]` → `[x]`)
-  - update Phase 2 migrated count in the Progress Tracker
-  - update "Next Task" to the next unchecked command in list order
-  - ensure command spec paths use `spec/unit/...` or `spec/integration/...` (never
-    stale `spec/git/...` paths)
-  - run a stale-doc sanity check by comparing unchecked `Git::Commands::*` entries
-    against files under `lib/git/commands/`; resolve any mismatches before moving on
-- **Report Progress:** Briefly summarize what was completed and what remains.
-  **ALWAYS** print the updated task list with status (e.g., `[x] Task 1`, `[ ] Task
-  2`).
-- **Continue or Complete:** If tasks remain, return to RED-GREEN for the next task.
-  If all tasks are complete, proceed to **Phase 3: FINALIZE**.
-
-## Phase 3: FINALIZE
-
-The purpose of this phase is to consolidate all task commits into a single, clean
-commit and complete the feature or bug fix.
-
-1. **Run Final Verification:** Run `bundle exec rake default` one final time to
-   ensure everything passes.
-2. **Safety Check:** Run `git log --oneline HEAD~N..HEAD` (where N is the number of
-   task commits) to list the commits included in the squash. Verify these are
-   strictly the commits generated during the current session. If unexpected commits
-   appear, STOP and ask the user for the correct value of N.
-3. **Capture Commit Messages:** Run `git log --format="- %s" HEAD~N..HEAD` to capture
-   individual commit messages for inclusion in the final commit body.
-4. **Draft the Squash Message:** Prepare a commit message with:
-   - **Subject:** A single line summarizing the entire feature or fix (e.g.,
-     `feat(branch): add Branch#create method`)
-   - **Body:** A summary of what was implemented, the captured commit messages from
-     step 2, key decisions made, and any relevant context. Wrap lines at 100
-     characters.
-5. **Propose the Squash:** Present the drafted message and the commands to squash to
-   the user:
-   - `git reset --soft HEAD~N` (where N is the number of task commits)
-   - `git commit -m "<drafted message>"`
-6. **Wait for Confirmation:** Do NOT execute the squash until the user reviews the
-   commits and confirms. The user may want to adjust the message or keep some commits
-   separate.
-7. **Execute on Confirmation:** Once confirmed, run `git reset --soft HEAD~N` to
-   unstage the task commits while preserving all changes, then commit with the
-   approved message.
-8. **Handle Commit Hook Failure:** If the commit fails due to a `commit-msg` hook
-   rejection (e.g., commitlint error):
-   - Read the error message carefully to identify the formatting issue.
-   - To validate a message file before committing:
-     ```bash
-     npx commitlint --format @commitlint/format < commit_msg.txt
-     ```
-   - To diagnose *why* a message is rejected (e.g., unexpected body/footer split),
-     inspect how the parser tokenizes it:
-     ```bash
-     cat commit_msg.txt | node -e "
-     const parse = require('@commitlint/parse');
-     let msg = '';
-     process.stdin.on('data', d => msg += d);
-     process.stdin.on('end', () =>
-       parse.default(msg.trim()).then(r => console.log(JSON.stringify(r, null, 2)))
-     );
-     " | jq
-     ```
-   - Fix the commit message to comply with the project's commit conventions.
-   - Retry the commit. The changes remain staged after a hook failure, so only the
-     `git commit` command needs to be re-run.
-   - If the commit fails 3 times, STOP and report the issue to the user with the
-     exact error message.
-9. **Create the Pull Request:** Push the branch and open the PR. **CRITICAL:** The
-   terminal tool mangles multi-line markdown (backticks, asterisks, newlines) in any
-   shell command — including heredocs and inline `--body "..."` arguments. Always
-   write the PR body using the **`create_file` tool** (not the terminal), then
-   reference that file:
-   - Use `create_file` to write the body to `./pr_body.md` (repo-relative path,
-     works on all platforms)
-   - Then run in the terminal: `git push origin <branch>`
-   - Then run in the terminal: `gh pr create --title "<title>" --base <target-branch> --body-file ./pr_body.md`
-     (choose `main` or `4.x` per the [branch strategy](/CONTRIBUTING.md))
-
-   After creating the PR, verify the stored body with
-   `gh pr view <number> --json body --jq '.body'`. If it is garbled, rewrite
-   `./pr_body.md` with `create_file` and fix with
-   `gh pr edit <number> --body-file ./pr_body.md`.
-
-
-### Per-Task Commits
-
-In the COMMIT step, create a commit for the completed task following these
-guidelines:
-
-- **Use Appropriate Types:**
-  - `test:` for adding or modifying tests (RED step)
-  - `feat:` for new **user-facing** functionality (triggers MINOR version bump)
-  - `fix:` for bug fixes (GREEN step for bugs)
-  - `refactor:` for code improvements without behavior change
-  - `chore:` for internal tooling or maintenance
-- **Use Scope When Relevant:** Include a scope to indicate the affected component
-  (e.g., `feat(branch):`, `test(remote):`).
-- **Write Clear Subjects:** Use imperative mood, lowercase, no period (e.g.,
-  `feat(branch): add create method`).
-- **Issue and PR References in the Body:** Do not use `#<number>` in the commit
-  body — write `issue 1000` not `issue #1000`. A commitlint parser flaw treats
-  any line containing `#<number>` as a footer token, permanently breaking the
-  body/footer split for all subsequent lines.
-  - To **close** an issue/PR, use `Closes`/`Fixes`/`Resolves` with `#` in the
-    footer — e.g. `Closes #1000`.
-  - To **mention** an issue for context only, omit the `#` in the body and no
-    footer line is needed.
-
-## Additional Guidelines
-
-These guidelines supplement the TDD process:
-
-- **Justify Test Modifications:** If an existing test needs to be modified, STOP and
-  report to the user before making the change. Explain which test needs modification,
-  why the expected behavior is changing, and whether this represents a breaking
-  change. Wait for user confirmation before proceeding.
-- **Unrelated Test Failures:** If you need to modify a test file that is not related
-  to the current task to make the build pass, STOP and report to the user. This
-  usually indicates a deeper regression, environment issue, or flawed assumption. Do
-  not attempt to fix unrelated tests without user guidance.
-- **Handle Discovered Complexity:** If the implementation reveals a complex logic
-  gap, add it to your task list but finish the current cycle first.
-- **Test Names Describe Behavior:** Name tests to clearly describe what behavior they
-  verify (e.g., `test_creates_new_branch` not `test_branch`).
-- **Ask for Clarification:** Stop and ask for clarification if requirements or
-  expectations are ambiguous.
-- **Do NOT Update CHANGELOG.md:** The CHANGELOG is auto-generated from commit
-  messages. Never edit it manually.
-- **Bulk File Text Substitutions:** When renaming classes, methods, or files across
-  many files simultaneously, avoid complex chained `sed` commands — the terminal tool
-  can mangle multi-pattern substitutions with non-trivial quoting or multi-line
-  heredocs. Instead, write the substitution logic to a temporary Ruby script and
-  execute it:
-
-  ```ruby
-  # tmp_rename.rb
-  files = Dir.glob('lib/**/*.rb') +
-          Dir.glob('spec/**/*.rb') +
-          Dir.glob('tests/**/*.rb')
-  files.each do |f|
-    src = File.read(f)
-    # Apply most-specific patterns first to avoid partial matches
-    new_src = src
-      .gsub('OldClassName', 'NewClassName')
-      .gsub("require_relative 'old_path'", "require_relative 'new_path'")
-    File.write(f, new_src) if new_src != src
-  end
-  ```
-
-  Run the script, then delete it:
-
-  ```
-  ruby tmp_rename.rb
-  rm tmp_rename.rb          # macOS/Linux
-  del tmp_rename.rb         # Windows (cmd)
-  Remove-Item tmp_rename.rb # Windows (PowerShell)
-  ```
-
-  Apply substitutions from most-specific to least-specific to prevent partial
-  matches (e.g., replace `FooBarBaz` before `FooBar`).
-
-## Example TDD Cycle
-
-Each task follows this cycle: **RED → GREEN → REFACTOR → VERIFY → COMMIT → REPLAN**
-
-**RED:** Write a failing test that describes the desired behavior.
-
-```ruby
-# spec/unit/git/commands/example_spec.rb
-it 'passes the --force flag when force: true is given' do
-  expect_command_capturing('example', '--force').and_return(command_result(''))
-
-  described_class.new(execution_context).call(force: true)
-end
-# Run: bundle exec rspec spec/unit/git/commands/example_spec.rb
-#      → fails: NameError (Git::Commands::Example is not defined yet)
-```
-
-**GREEN:** Write minimal code to make the test pass.
-
-```ruby
-# lib/git/commands/example.rb
-module Git
-  module Commands
-    class Example < Base
-      arguments do
-        literal 'example'
-        flag_option :force
-      end
-    end
-  end
-end
-# Run: bundle exec rspec spec/unit/git/commands/example_spec.rb → passes
-```
-
-**REFACTOR:** Improve code quality without changing behavior, then run all tests.
-
-**VERIFY:** Run `bundle exec rake default` to confirm tests and linters pass.
-
-**COMMIT:** `git commit -m "feat(branch): add Branch#create method"`
-
-**REPLAN:** Report progress, update task list, proceed to next task or FINALIZE.
-
-**FINALIZE (after all tasks):** Propose squash commit with captured messages, wait