git 4.3.2 → 5.0.0.beta.1

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

@@ -0,0 +1,185 @@
+---
+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:
+
+**"I've completed the implementation. Please perform a comprehensive PR readiness review."**
+
+## 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
+
+## 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
+
+## 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

@@ -0,0 +1,313 @@
+---
+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 planned v5.0.0 facade
+  layer is being introduced incrementally during the architectural redesign;
+  `Git::Base` / `Git::Lib` remain the current public API until the migration
+  completes)
+- [Extract Facade from Base/Lib](../extract-facade-from-base-lib/SKILL.md) —
+  migrating public methods from `Git::Base` / `Git::Lib` into facade methods
+- [YARD Documentation](../yard-documentation/SKILL.md) — documentation
+  standards
+
+## Architecture & Module Organization
+
+**Key modules and their roles:**
+
+| Class | Role |
+| --- | --- |
+| `Git::Base` | Main facade — entry point for all user-facing operations |
+| `Git::Lib` | Low-level adapter/facade; calls `Git::Commands::*`, builds rich objects via parsers |
+| `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)
+- `tests/units/` — Legacy Test::Unit suite
+- `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::Base (facade)
+  └── Git::Lib (adapter — pre-processes args, builds rich objects)
+        └── Git::Commands::* (defines CLI API, binds args, executes)
+              └── 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::Lib`): 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 `Git::Lib`. Being incrementally migrated to `Git::Repository`.
+- **Interface layer** (`Git::Base`): User-facing API. Delegates to `Git::Lib`.
+  Returns domain objects.
+
+`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::Lib`) 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::Base#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::Base`
+- `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::Lib` 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

@@ -0,0 +1,168 @@
+---
+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. Legacy Test::Unit tests (`tests/units/`) require justification to modify.
+
+**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.