git 5.1.0 → 5.2.0

data/.github/skills/pr-readiness-review/SKILL.md

@@ -1,205 +0,0 @@
----
-name: pr-readiness-review
-description: "Performs a comprehensive pre-PR readiness review covering tests, code quality, security, and commit conventions. Use at the end of implementation before submitting a pull request."
----
-
-# PR Readiness Review Workflow
-
-Use this at the end of implementation to prepare for PR submission. Example
-request:
-
-> I've completed the implementation. Please perform a comprehensive PR readiness
-> review.
-
-## Contents
-
-- [Contents](#contents)
-- [How to use this skill](#how-to-use-this-skill)
-- [Prerequisites](#prerequisites)
-- [Related skills](#related-skills)
-- [1. Run Final Validation](#1-run-final-validation)
-- [2. Verify Testing Quality](#2-verify-testing-quality)
-- [3. Review Code Quality](#3-review-code-quality)
-- [4. Verify Against Git Documentation](#4-verify-against-git-documentation)
-- [5. Check Commit Quality](#5-check-commit-quality)
-- [6. Review Documentation](#6-review-documentation)
-- [7. Verify Branch Placement](#7-verify-branch-placement)
-- [8. Generate PR Summary](#8-generate-pr-summary)
-
-## How to use this skill
-
-Attach this file to your Copilot Chat context, then invoke it after
-implementation is complete and before opening a pull request. This workflow is a
-final quality gate and reporting template.
-
-## Prerequisites
-
-Before starting, you **MUST** load the following skill(s) in their entirety:
-
-- [YARD Documentation](../yard-documentation/SKILL.md) — authoritative
-  source for YARD formatting rules and writing standards;
-
-## Related skills
-
-- [RSpec Unit Testing Standards](../rspec-unit-testing-standards/SKILL.md) — baseline rules that all unit tests must
-  comply with, including testing only via public interfaces; these standards take precedence over any older guidance
-- [Development Workflow](../development-workflow/SKILL.md) — primary
-  implementation process prior to readiness checks
-- [Command Test Conventions](../command-test-conventions/SKILL.md) — unit/integration
-  test conventions for command classes
-- [Command YARD Documentation](../command-yard-documentation/SKILL.md)
-  — verify command documentation completeness and consistency
-- [Facade Test Conventions](../facade-test-conventions/SKILL.md) —
-  unit/integration test conventions for `Git::Repository::*` facade methods
-- [Facade YARD Documentation](../facade-yard-documentation/SKILL.md) — verify
-  facade module/method documentation completeness and consistency
-- [Reviewing Skills](../reviewing-skills/SKILL.md) — audit skill quality,
-  discoverability, reference structure, and cross-skill links when skill files
-  change
-
-## 1. Run Final Validation
-
-Execute and report results for:
-
-- `bundle exec rake default` - all tests and linters must pass
-- Check test output for any Ruby warnings
-
-## 2. Verify Testing Quality
-
-**Unit Tests (Critical):**
-
-- [ ] **100% coverage of all changed code** - every branch, edge case, error condition
-- [ ] All external dependencies properly mocked (execution_context, git commands)
-- [ ] Each test verifies one specific behavior
-- [ ] Comprehensive coverage: success paths, failures, edge cases, error handling
-- [ ] Test only through public interfaces (see RSpec Unit Testing Standards Rule 6)
-
-**Integration Tests (Essential Only):**
-
-- [ ] **Minimal and purposeful** - only test what unit tests cannot verify
-- [ ] Each test validates one specific git interaction pattern
-- [ ] Tests verify mocked assumptions match real git behavior
-- [ ] No redundancy - don't duplicate what unit tests already cover
-- [ ] Follow CONTRIBUTING.md guidelines: test gem's interaction with git, not git itself
-
-**Command Tests (if any `Git::Commands::*` specs are included):**
-
-- [ ] Apply the [Command Test Conventions](../command-test-conventions/SKILL.md) skill to
-  every new or modified unit and integration spec file for command classes. Resolve
-  all findings before proceeding.
-
-## 3. Review Code Quality
-
-- [ ] YARD documentation complete for all public methods/classes
-- [ ] Include `@api public` or `@api private` tags appropriately
-- [ ] Usage examples in YARD docs show common patterns
-- [ ] **Command YARD Docs (if any `Git::Commands::*` source files are included):**
-  Apply the [Command YARD Documentation](../command-yard-documentation/SKILL.md)
-  skill to every new or modified command source file. Resolve all findings before
-  proceeding.
-- [ ] No breaking changes (or properly marked with `!` in commits)
-- [ ] Cross-platform compatible on all supported OSes; any platform-specific logic is properly guarded and tested
-- [ ] No security issues (command injection, path traversal, etc.)
-- [ ] Uses Arguments DSL for building git commands
-
-## 4. Verify Against Git Documentation
-
-- [ ] Determine the repository's minimum supported Git version from project metadata
-- [ ] Read version-matched upstream documentation for the implemented command
-- [ ] Inspect version-matched upstream source when docs are ambiguous about exact option forms
-- [ ] Use local `git <command> -h` output only as a supplemental check for the installed Git
-- [ ] Confirm all documented options are considered
-- [ ] All edge cases from git documentation are tested
-- [ ] Error handling matches git's actual behavior
-- [ ] Exit codes handled correctly (especially partial failures)
-
-## 5. Check Commit Quality
-
-- [ ] All commits follow Conventional Commits format: `type: description`
-- [ ] Description is lowercase, no ending period, under 100 chars
-- [ ] Valid types: feat, fix, docs, test, refactor, chore, perf, build, ci, style, revert
-- [ ] Breaking changes marked with `!` and include `BREAKING CHANGE:` footer
-- [ ] Each commit is atomic and has a clear purpose
-
-## 6. Review Documentation
-
-- [ ] Architecture docs updated if new patterns introduced (redesign/*.md)
-- [ ] If command migration work is included, `redesign/3_architecture_implementation.md`
-  is synchronized (checklist status, Phase 2 count, and "Next Task")
-- [ ] Run a stale-doc audit for command migration docs by comparing unchecked
-  `Git::Commands::*` entries against files in `lib/git/commands/`
-- [ ] Verify command spec references in redesign docs point to `spec/unit/...` or
-  `spec/integration/...` as applicable (not `spec/git/...`)
-- [ ] README.md updated if public API changed
-- [ ] Examples are clear and demonstrate common use cases
-- [ ] All `@param`, `@return`, `@raise` tags are accurate
-- [ ] **Skill docs (if any `.github/skills/**` files are included):** Apply the
-  [Reviewing Skills](../reviewing-skills/SKILL.md) skill to every new or
-  modified skill. Verify TOC anchors, relative links, cross-skill deep links,
-  referenced files, and any stated inheritance/override relationships.
-
-## 7. Verify Branch Placement
-
-Before creating the PR, confirm the branch situation:
-
-- [ ] Changes are on a feature branch (not `main` or `4.x`), named
-  `<type>/<short-description>`
-- [ ] Branch targets the correct base: `main` for features/breaking changes;
-  `4.x` for security fixes and backward-compatible v4.x-only changes
-
-**If changes are on the wrong branch:** Create a new branch from the appropriate
-base (`origin/main` or `origin/4.x`) and relocate the existing work using the
-most appropriate Git approach — cherry-pick (specific commits), rebase (linear
-history), or recommit (uncommitted changes) — based on the situation.
-
-## 8. Generate PR Summary
-
-Provide a comprehensive report with:
-
-**Implementation Summary:**
-
-- What was implemented and why
-- Key design decisions made
-- Any trade-offs or limitations
-
-**Test Coverage:**
-
-- Unit tests: X examples covering Y scenarios
-- Integration tests: Z examples validating specific git interactions
-- Coverage: 100% of changed lines (or explain gaps)
-- Edge cases tested: [list critical ones]
-
-**Quality Verification:**
-
-- ✅ Items that passed all checks
-- ⚠️ Items that need attention (if any)
-- Reference to relevant documentation verified
-
-**Suggested PR Materials:**
-
-- PR Title: `type: clear description of change`
-- PR Description draft including:
-  - Summary of changes
-  - Why this change is needed
-  - Test coverage details
-  - Breaking changes (if any)
-  - Checklist from .github/pull_request_template.md
-
-**PR Body Editing Safety:**
-
-- The terminal tool mangles multi-line markdown (backticks, asterisks, newlines) in
-  any shell command, including heredocs. Always write the PR body using the
-  **`create_file` tool** (the VS Code Copilot agent tool that writes file content
-  directly, bypassing the terminal entirely), then reference the file:
-  - `gh pr create --body-file <path>` when opening
-  - `gh pr edit <number> --body-file <path>` when updating
-- **Never** use inline `--body "..."` or `cat > file << 'EOF'` heredocs for PR bodies
-- After any body update, verify the stored text with:
-  - `gh pr view <number> --json body --jq '.body'`
-- If the body is garbled, rewrite the file with `create_file` and re-run `gh pr edit`
-
-**Next Steps:**
-
-- Any remaining items to address before PR submission
-- Confirmation that all checklist items are complete
-- Make sure to create a feature branch for the PR -- never push directly to main

data/.github/skills/project-context/SKILL.md

@@ -1,306 +0,0 @@
----
-name: project-context
-description: 'Reference guide for ruby-git architecture, coding standards, design philosophy, key technical details, and compatibility requirements. Use when answering architecture questions, deciding where new code belongs, reviewing coding standards, or understanding the layered command/parser/facade design.'
----
-
-# Project Context
-
-Reference for ruby-git's architecture, coding standards, design philosophy, and
-technical constraints. Load this skill when answering questions about code structure,
-where logic belongs, or how the layers interact.
-
-## Contents
-
-- [How to use this skill](#how-to-use-this-skill)
-- [Related skills](#related-skills)
-- [Architecture & Module Organization](#architecture--module-organization)
-- [Layer Responsibilities](#layer-responsibilities)
-- [Coding Standards](#coding-standards)
-- [Design Philosophy](#design-philosophy)
-- [Key Technical Details](#key-technical-details)
-- [Compatibility](#compatibility)
-- [Performance](#performance)
-- [Implementation Notes](#implementation-notes)
-
-## How to use this skill
-
-Attach this file to your Copilot Chat context when you need architecture guidance,
-coding standard details, or implementation constraints.
-
-## Related skills
-
-- [Development Workflow](../development-workflow/SKILL.md) — TDD cycle and commit
-  conventions for day-to-day work
-- [Command Implementation](../command-implementation/SKILL.md) — generating and
-  reviewing command classes in the layered architecture
-- [Facade Implementation](../facade-implementation/SKILL.md) — generating and
-  reviewing `Git::Repository::*` facade methods, the gem's public API layer
-- [YARD Documentation](../yard-documentation/SKILL.md) — documentation
-  standards
-
-## Architecture & Module Organization
-
-**Key modules and their roles:**
-
-| Class | Role |
-| --- | --- |
-| `Git::Repository` | Main facade — entry point for all user-facing operations; methods live in `Git::Repository::*` topic modules under `lib/git/repository/`, included into the class |
-| `Git::ExecutionContext::*` | Configured subprocess runner; holds binary path, env vars, and global opts; provides `#command_capturing`/`#command_streaming` to command classes |
-| `Git::Commands::*` | Command classes: define CLI API, bind args, execute → return `CommandLineResult` |
-| `Git::CommandLine` | Subprocess execution: escaping, timeout, stdout/stderr capture |
-| `Git::Parsers::*` | Transform raw stdout into structured data |
-| `Git::Object::*` | Immutable Git objects (Commit, Tree, Blob, Tag) |
-| `Git::Status` | Working-directory status (enumerable `StatusFile` collection) |
-| `Git::Diff` | Diff operations (enumerable `DiffFile` collection) |
-| `Git::Log` | Chainable commit-history query builder |
-| `Git::Branch/Branches` | Branch management (local + remote) |
-| `Git::Remote` | Remote repository references |
-| `Git::Worktree/Worktrees` | Worktree support |
-| `Git::Stash/Stashes` | Stash management |
-
-**Key directories:**
-
-- `lib/git/` — Core library code
-- `lib/git/commands/` — Command classes (new architecture)
-- `lib/git/repository/` — Facade topic modules (`Git::Repository::*`)
-- `spec/unit/` — RSpec unit tests (mocked execution context)
-- `spec/integration/` — RSpec integration tests (real git repositories)
-- `spec/support/` — Shared test contexts and helpers
-- `redesign/` — Architecture redesign documentation
-  - `redesign/3_architecture_implementation.md` is a living migration tracker.
-    When command migrations land, keep checklist states, "Next Task", and Phase 2
-    progress counts synchronized with `lib/git/commands/` and current spec paths.
-
-## Layer Responsibilities
-
-The three-layer architecture separates concerns cleanly:
-
-```
-Git::Repository (facade — topic modules under lib/git/repository/)
-  └── Git::Commands::* (defines CLI API, binds args, executes via execution_context)
-        └── Git::ExecutionContext::* (configured subprocess runner: env, binary, global opts)
-              └── Git::CommandLine (subprocess execution)
-```
-
-- **Commands layer** (`Git::Commands::*`): Owns the git CLI contract. Declares
-  arguments via DSL, executes command, returns `CommandLineResult`. No parsing.
-  - `literal` entries are **only** for operation selectors (subcommand names,
-    mode flags like `--delete` that define what the class does). Output-format
-    flags, parser-contract options, and other caller-controlled options belong as
-    `flag_option` / `value_option` — not as `literal` entries.
-  - Each command class represents **one operation**, not one output format.
-    Output-mode flags (`--patch`, `--numstat`, `--raw`, `--format=…`) are options
-    declared in the DSL; the facade chooses which to pass. Separate subclasses
-    for the same operation with different output modes are an anti-pattern.
-- **Parser layer** (`Git::Parsers::*`): Transforms raw stdout/stderr into structured
-  Ruby data. No execution.
-- **Facade layer** (`Git::Repository::*`): Pre-processes caller arguments, invokes
-  the right command class, calls parsers, constructs rich response objects.
-  **Parser-contract options** (e.g. `no_color: true`, `pretty: 'raw'`,
-  `format: FORMAT_STRING`) are passed explicitly at the facade call site — this makes
-  the parser contract auditable by reading the topic module method.
-
-`Git::Commands::Base` provides default `#initialize(execution_context)` and `#call`.
-Command classes that need non-zero successful exits declare
-`allow_exit_status <Range>` with a rationale comment.
-
-### Command-layer neutrality
-
-Command classes are neutral, faithful representations of the git CLI. They declare
-options via the DSL but never embed policy choices (output-control flags, editor
-suppression, progress, verbose mode). The facade (`Git::Repository::*`) sets safe defaults
-at each call site. Some defaults are **fixed** (not in `ALLOWED_OPTS` — rejected by
-`assert_valid_opts!` before reaching the command); others are **overridable** (in
-`ALLOWED_OPTS`, placed before the caller's `**opts` so the caller's value wins).
-The execution layer (`GIT_EDITOR='true'`) is an unconditional safety net.
-
-> **Anti-pattern:** `literal '--no-edit'`, `literal '--verbose'`,
-> `literal '--no-progress'` inside a command class.
->
-> **Correct pattern:** `flag_option :edit, negatable: true` in the command;
-> `no_edit: true` passed from the facade call site.
-
-### Validation Boundaries
-
-Command classes use per-argument validation parameters (`required:`, `type:`,
-`allow_nil:`, etc.) and operand format validation. They generally do **not** declare
-cross-argument constraint methods (`conflicts`, `requires`, `requires_one_of`,
-`requires_exactly_one_of`, `forbid_values`, `allowed_values`) — git is the single source of truth for its
-own option semantics. The narrow exception is **arguments git cannot observe in
-its argv**: if an argument is `skip_cli: true`, git never sees it and cannot detect
-incompatibilities — `conflicts` and/or `requires_one_of` are appropriate. Example:
-`cat-file --batch` uses both because `:objects` is `skip_cli: true`:
-
-| Validated by Commands | Mechanism |
-| --- | --- |
-| Unknown options | `validate_unsupported_options!` in Arguments DSL |
-| Required options | `required: true` in Arguments DSL |
-| Type checking | `type:` in Arguments DSL |
-| Option-like operand rejection | Automatic for operands before `--` |
-
-| Delegated to git (semantic) | Surfaced as |
-| --- | --- |
-| Option conflicts (`--soft` vs `--hard`) | `Git::FailedError` |
-| Option dependencies (`--all-match` requires `--grep`) | `Git::FailedError` |
-| At-least-one-of groups | `Git::FailedError` |
-| Value-set membership | `Git::FailedError` |
-| Forbidden value combinations | `Git::FailedError` |
-
-The constraint DSL infrastructure (`conflicts`, `requires`, `requires_one_of`,
-`requires_exactly_one_of`, `forbid_values`, `allowed_values`) remains available in `Git::Commands::Arguments`
-and is used only for `skip_cli: true` argument constraints, and in narrow documented cases for
-git-visible arguments whose combination causes silent data loss (no error, wrong result).
-See `redesign/3_architecture_implementation.md` Insight 6 for the full policy and exception criteria.
-
-## Coding Standards
-
-### Ruby Style
-
-- `frozen_string_literal: true` at the top of every Ruby file
-- Ruby 3.2.0+ idioms; keyword arguments for multi-parameter methods
-- `private` keyword form (not `private :method_name`)
-- Pattern matching for complex conditionals where appropriate
-
-### Naming
-
-| Kind | Convention | Example |
-| --- | --- | --- |
-| Class/Module | PascalCase | `Git::CommandLine` |
-| Method/variable | snake_case | `current_branch` |
-| Constant | UPPER_SNAKE_CASE | `VERSION` |
-| Predicate | ends with `?` | `bare?` |
-| Mutating method | ends with `!` | `reset!` |
-| Parsed metadata struct (top-level `Git::`) | `*Info` suffix | `BranchInfo`, `TagInfo`, `StashInfo` |
-| Mutating-operation outcome struct (top-level `Git::`) | `*Result` suffix | `BranchDeleteResult`, `TagDeleteResult` |
-
-**Result class constraints:**
-
-- `*Info` / `*Result` suffixes are reserved for top-level `Git::` data structs.
-  Never apply them to `Git::Commands::*` classes — command classes are subprocess
-  runners, not data structs, and a name like `Commands::Foo::BarInfo` misleads
-  readers.
-- Never name a sub-command class `Object` — it shadows Ruby's `::Object`.
-
-### Code Organization
-
-- Single-responsibility classes; one public class per file as a general rule
-- Tightly-coupled helper classes may share a file
-- Core code in `lib/git/`; command classes in `lib/git/commands/`
-
-### Documentation
-
-- YARD for all public methods: `@param`, `@return`, `@raise`, `@example`
-- Use `@overload` with explicit keyword params when methods use `**`
-- `@api private` on internal methods
-- Document edge cases, platform differences, security considerations
-
-## Design Philosophy
-
-See [CONTRIBUTING.md](../../CONTRIBUTING.md) for authoritative, complete guidelines.
-
-**Summary:**
-
-- **Lightweight wrapper** — minimal abstraction over `git` CLI
-- **Principle of least surprise** — predictable, follows git conventions
-- **Direct CLI mapping** — `git add` → `Git::Repository#add`; use prefix + suffix for
-  multi-purpose commands (`#ls_files_untracked`, `#ls_files_staged`)
-- **Parameter naming** mirrors long CLI options
-- **Rich output objects** — translate git output to Ruby objects when useful to
-  callers
-- **No unnecessary extensions** — stay close to git's actual behavior
-
-## Key Technical Details
-
-### Error Hierarchy
-
-All gem errors inherit from `Git::Error`:
-
-- `Git::FailedError` — non-zero exit status
-- `Git::SignaledError` — killed by signal
-- `Git::TimeoutError` — exceeded timeout (subclass of `SignaledError`)
-- `ArgumentError` — invalid arguments
-
-All errors include structured data (command, output, status) for debugging. Never
-swallow exceptions silently.
-
-### Path Handling
-
-- Working-directory paths: relative to repo working directory
-- Paths stored as `Pathname` objects on `Git::Repository`
-- `Git::EscapedPath` for paths with special characters
-- Handle Windows path separators; test with Unicode filenames
-
-### Encoding
-
-- Use `rchardet` for automatic encoding detection
-- Handle UTF-8, ASCII, and platform-default encodings
-- Be aware of binary vs. text mode differences on Windows
-
-### Timeouts
-
-- Global timeout configurable; per-command override available
-- `Git::TimeoutError` is raised on expiry
-- Built into `Git::CommandLine`; document implications in YARD
-
-### Dependencies
-
-- `activesupport` (≥ 5.0) — utilities and deprecation handling
-- `addressable` (~> 2.8) — URI parsing
-- `process_executer` (~> 4.0) — subprocess execution with timeout
-- `rchardet` (~> 1.9) — character encoding detection
-
-## Compatibility
-
-- **Minimum Ruby (language level):** 3.2.0
-- **Supported Rubies:** MRI (macOS, Linux, Windows); latest JRuby and TruffleRuby on Linux
-- **Minimum Git:** 2.28.0
-- **Platforms:** macOS, Linux, Windows (JRuby/TruffleRuby officially supported on Linux only)
-- Use `File.join` and forward slashes; avoid platform-specific paths in tests
-- Windows has different path handling, file-system behavior, and line endings; JRuby on Windows is not supported
-- Document git version requirements for features that need newer git
-
-## Performance
-
-### Commands and subprocesses
-
-- Commands execute with global or per-command configurable timeout
-- Subprocess execution is handled by `Git::CommandLine`; do not shell out directly
-- Clean up resources (file handles, temp files) after every operation
-- Handle large repository operations efficiently
-
-### Memory
-
-- Lazy-load Git objects when possible; cache appropriately
-- Stream large outputs rather than buffering everything
-- Be mindful of memory with large diffs and logs
-
-### Repository operations
-
-- Minimize Git command executions; use batch operations where possible
-- Cache Git objects when appropriate
-- Consider performance implications of deep history traversal
-
-## Implementation Notes
-
-### Adding new commands
-
-Follow the three-layer pattern: command class (CLI contract) → parser (output
-transform) → `Git::Repository::*` facade method (orchestration + rich object). See
-[Command Implementation](../command-implementation/SKILL.md).
-
-### Working with paths
-
-- Store as `Pathname`; use `Git::EscapedPath` for special chars
-- Test with Unicode filenames and Windows separators
-
-### Working with repository objects
-
-- Handle missing/invalid objects gracefully
-- Test with all object types (commits, trees, blobs, tags)
-
-### Security
-
-- Use `Git::CommandLine` for all command execution — it handles proper escaping
-- Validate and sanitize user-supplied paths and arguments
-- Document security implications in YARD
-- Be aware of git hook execution risks

data/.github/skills/pull-request-review/SKILL.md

@@ -1,168 +0,0 @@
----
-name: pull-request-review
-description: "Reviews pull requests against project standards and posts review comments via the gh CLI. Use when reviewing PRs, checking coding standards compliance, or performing approval reviews."
----
-
-# Pull Request Review Workflow
-
-When asked to review a pull request (e.g., "Review PR #999"), follow this workflow to
-analyze the changes, provide feedback, and optionally post the review to GitHub.
-
-## Contents
-
-- [How to use this skill](#how-to-use-this-skill)
-- [Related skills](#related-skills)
-- [Step 1: Fetch the PR](#step-1-fetch-the-pr)
-- [Step 2: Review Against Project Standards](#step-2-review-against-project-standards)
-- [Step 3: Present Review Findings](#step-3-present-review-findings)
-- [Step 4: Get User Approval](#step-4-get-user-approval)
-- [Step 5: Post the Review](#step-5-post-the-review)
-- [Step 6: Confirm Completion](#step-6-confirm-completion)
-
-## How to use this skill
-
-Attach this file to your Copilot Chat context, then invoke it with the PR number
-to review. Follow Step 4 explicitly: do not post review comments until the user
-confirms.
-
-## Related skills
-
-- [RSpec Unit Testing Standards](../rspec-unit-testing-standards/SKILL.md) — RSpec rules to apply when evaluating
-   test quality in a PR
-- [PR Readiness Review](../pr-readiness-review/SKILL.md) — internal pre-PR checks
-   before formal review
-- [CI/CD Troubleshooting](../ci-cd-troubleshooting/SKILL.md) — investigate failed
-   checks discovered during review
-- [Review Backward Compatibility](../review-backward-compatibility/SKILL.md) —
-   deeper audit when API compatibility concerns surface
-
-## Step 1: Fetch the PR
-
-1. **Read PR Details:** Use `gh pr view #999` to get title, description, author, and
-   status.
-2. **Get Changed Files:** Use `gh pr diff #999` to see the complete diff.
-3. **Check PR Status:** Note if it's a draft, has merge conflicts, or has existing
-   reviews.
-
-## Step 2: Review Against Project Standards
-
-Evaluate the PR against these criteria:
-
-**Code Quality:** Ruby style (RuboCop-compliant), `frozen_string_literal: true`, proper naming (snake_case/PascalCase), single-responsibility, no duplication, Ruby 3.2+ idioms.
-
-**Testing:** Changes are covered by atomic RSpec specs (`spec/`), well-named, and passing CI.
-
-**Documentation:** YARD docs on public methods with `@param`, `@return`, `@raise`, `@example`. README updated for user-facing changes. Platform differences and security documented. For `Git::Commands::*` classes, `@raise [Git::FailedError]` must use the canonical generic wording — **never** enumerate failure causes; see the `@raise` wording table in [Command YARD Documentation](../command-yard-documentation/SKILL.md#3-return-and-raise-tags).
-
-**Architecture:** Correct layer placement (Base/Lib/CommandLine), principle of least surprise, direct Git command mapping, proper error hierarchy.
-
-**Commits:** Conventional Commits format, lowercase subjects under 100 chars, no trailing period. Breaking changes use `!` and `BREAKING CHANGE:` footer.
-
-**Compatibility:** Backward compatible (or marked breaking), Ruby 3.2+, Git 2.28.0+, cross-platform (Windows/macOS/Linux).
-
-**Security:** No command injection, proper escaping via Git::CommandLine, input validation, resource cleanup.
-
-## Step 3: Present Review Findings
-
-Present your findings to the user in this format:
-
-```text
-# PR Review: #999 - [PR Title]
-
-**Author:** [username]
-**Status:** [open/draft/has conflicts/etc.]
-
-## Summary
-[Brief description of what the PR does]
-
-## Recommendation
-- **Review Type:** [APPROVE / COMMENT / REQUEST CHANGES]
-- **Rationale:** [Why this recommendation]
-
-## General Comments
-
-[Overall feedback on the PR - architecture decisions, approach, etc.]
-
-## Line-Specific Comments
-
-[file.rb:123]
-[Specific feedback about this line or section]
-
-[file.rb:456-460]
-[Feedback about this range of lines]
-
-## Checklist Results
-
-**Passing:**
-- Uses proper Ruby style
-- Tests included
-- ...
-
-**Issues Found:**
-- Missing YARD documentation on `SomeClass#method`
-- Commit message "Fixed bug" doesn't follow conventional commits
-- ...
-
----
-
-**Here is the review. Do you have any questions or want additional changes, OR should I go ahead and post this review on the PR?**
-```
-
-## Step 4: Get User Approval
-
-Wait for the user to respond. They may:
-
-- **Approve posting:** Proceed to Step 5
-- **Request changes to review:** Modify your findings and re-present
-- **Ask questions:** Answer and clarify before proceeding
-- **Decide not to post:** End the workflow
-
-Do NOT post the review without explicit user confirmation.
-
-## Step 5: Post the Review
-
-Once the user confirms, post the review using the GitHub CLI:
-
-**For reviews with line-specific comments:**
-
-1. Create the review: `gh pr review #999 --comment` (or `--approve` or
-   `--request-changes`)
-2. Add the general comment as the review body using `-b "comment text"`
-3. For line-specific comments, you may need to use the GitHub API or instruct the
-   user to add them manually in the GitHub UI
-
-**For reviews with only general comments:**
-
-```bash
-gh pr review #999 --approve -b "Your general comment here"
-# or
-gh pr review #999 --comment -b "Your general comment here"
-# or
-gh pr review #999 --request-changes -b "Your general comment here"
-```
-
-**Note:** The `gh` CLI has limitations with line-specific comments. If the review
-includes line-specific comments, inform the user of this limitation and either:
-
-- Post only the general comment via CLI and provide the line comments for manual
-  posting
-- Provide the full review text for the user to post manually
-- Use the GitHub API if line-specific commenting is critical
-
-## Step 6: Confirm Completion
-
-After posting, confirm with the user:
-
-```text
-Review posted successfully to PR #999.
-View at: [PR URL from gh pr view output]
-```
-
-When editing a PR description as part of follow-up review changes, use a
-file-based flow for reliability:
-
-- write/update markdown in a local file
-- run `gh pr edit #999 --body-file <path>`
-- verify the final stored body with `gh pr view #999 --json body`
-
-Avoid long multiline inline `--body "..."` commands for complex markdown.