git 4.3.2 → 5.0.0.beta.1

data/.github/skills/review-arguments-dsl/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: review-arguments-dsl
+description: "Audits a command class's arguments DSL definition to verify it accurately maps Ruby call arguments to git CLI arguments in the correct order with correct DSL methods and modifiers."
+---
+
+# Review Arguments DSL
+
+Verify that a command class's `arguments do ... end` definition accurately maps Ruby
+call arguments to git CLI arguments, in the correct order, with the correct DSL
+methods and modifiers.
+
+## Contents
+
+- [Contents](#contents)
+- [Related skills](#related-skills)
+- [Input](#input)
+  - [Command source code](#command-source-code)
+  - [Command test code](#command-test-code)
+  - [Git documentation for the git command](#git-documentation-for-the-git-command)
+- [Reference](#reference)
+  - [Architecture Context (Base Pattern)](#architecture-context-base-pattern)
+  - [DSL to CLI Mapping](#dsl-to-cli-mapping)
+- [Workflow](#workflow)
+- [Output](#output)
+
+## Related skills
+
+- [Command Implementation](../command-implementation/SKILL.md) — class structure, phased rollout gates, and
+  internal compatibility contracts
+- [Command Test Conventions](../command-test-conventions/SKILL.md) — unit/integration test conventions for command classes
+- [Command YARD Documentation](../command-yard-documentation/SKILL.md) — documentation completeness for command classes
+
+## Input
+
+What the agent requires to run this skill and where to get it.
+
+### Command source code
+
+Read the command class from `lib/git/commands/{command}.rb` or, for subcommands,
+`lib/git/commands/{command}/{subcommand}.rb`. For subcommands, also read the
+namespace module at `lib/git/commands/{command}.rb` which should list all sibling
+subcommands and provide the module-level documentation.
+
+### Command test code
+
+Read unit tests matching `spec/unit/git/commands/{command}/**/*_spec.rb`. Use these as
+supplemental evidence when tracing the verification chain (Ruby call → bound
+argument → expected git CLI). Coverage completeness is assessed by the
+[Command Test Conventions](../command-test-conventions/SKILL.md) skill.
+
+### Git documentation for the git command
+
+- **Latest-version online command documentation**
+
+  Read the **entire** official git documentation online man page for the command
+  for the latest version of git. This version will be used as the primary
+  authority for DSL completeness, including the options to include in the
+  DSL, argument names, aliases, ordering, etc.
+  Fetch this version from the URL `https://git-scm.com/docs/git-{command}`
+  (this URL always serves the latest release).
+
+- **Minimum-version online command documentation**
+
+  Read the **entire** official git documentation online man page for the command for
+  the `Git::MINIMUM_GIT_VERSION` version of git. This will be used only for
+  command-introduction and `requires_git_version` decisions. Fetch this version from
+  URL `https://git-scm.com/docs/git-{command}/{version}`.
+
+Do **not** scaffold from local `git <command> -h` output alone — the installed Git
+version is unknown and may differ from the latest supported version. Local help should
+NOT be used even as a supplemental check.
+
+## Reference
+
+### Architecture Context (Base Pattern)
+
+Command classes follow this structure:
+
+- `class < Git::Commands::Base`
+- class-level `arguments do ... end`
+- optional class-level macros such as `allow_exit_status <range>` and
+  `requires_git_version <version>`
+- YARD documentation with `@overload` blocks containing `@param`, `@option`,
+  `@return`, and `@raise` tags, in one of two forms:
+  - **when `#call` is overridden:** standard YARD comments directly above `def call`
+  - **when `#call` is not overridden:** a `# @!method call(*, **)` directive with
+    nested standard YARD comments
+
+The CLI argument mapping is still defined exclusively by the Arguments DSL. The
+`Base` class handles binding and execution.
+
+### DSL to CLI Mapping
+
+<!--
+Purpose: gives the agent the mental model for predicting CLI output from a
+DSL definition — the mapping rules needed to execute the verification chain
+(Ruby call → bound argument → expected git CLI).
+
+CHECKLIST.md works in the reverse direction: given git man-page behavior,
+which DSL method and modifiers to use.
+-->
+
+The Arguments DSL (`arguments do ... end`) declares how Ruby keyword and positional
+arguments map to git CLI flags, options, and operands. See [CHECKLIST.md §
+Verify DSL method per option type](CHECKLIST.md#2-verify-dsl-method-per-option-type)
+for the full DSL method mapping table.
+
+Key behaviors:
+
+- **Basic emit** — `flag_option :verbose` → `--verbose`; `value_option :message` →
+  `--message <value>`; `operand :commit` → bare `<value>` in positional slot.
+- **`flag_or_value_option`** — hybrid: `true` → `--flag`; string → `--flag value`
+  (or `--flag=value` with `inline:`); `false`/`nil` → nothing. Supports `negatable:`.
+- **`key_value_option`** — accepts a Hash or Array of pairs; emits `--flag key=value`
+  per pair. `key_separator:` overrides `=`; `inline:` joins as `--flag=key=value`.
+- **`custom_option`** — block receives the raw value and returns CLI strings; String
+  is appended, Array is concatenated, `nil`/empty emits nothing.
+- **nil / false suppression** — for boolean-style options (`flag_option`,
+  `flag_or_value_option` in boolean mode), `false` or `nil` suppresses emission.
+  For `value_option` / `inline_value` options, `false` is treated as a value
+  (stringified to `"false"`) unless a type constraint rejects it. `nil` suppresses
+  emission for all option types (including negatable options — `false` is absent,
+  not `--no-*`).
+- **Output order matches definition order** — bound arguments are emitted in the
+  order entries appear in `arguments do`.
+- **Name-to-flag mapping** — underscores become hyphens, single-char names map to
+  `-x`, multi-char names map to `--name`. **Case is preserved**: `:A` → `-A`, `:N` →
+  `-N`. Uppercase short flags do not require `as:`.
+- **`as:` override** — emits a verbatim string instead of deriving the flag from the
+  symbol name. See [CHECKLIST.md § The `as:` escape
+  hatch](CHECKLIST.md#the-as-escape-hatch) for when use is justified.
+- **Aliases** — first alias is canonical and determines the generated flag; remaining
+  aliases are accepted as caller-side synonyms. Long name first:
+  `%i[force f]`, not `%i[f force]`.
+- **`negatable:`** — registers two entries: the positive key and a `no_` companion.
+  Both follow standard boolean semantics: `true` emits the flag, `false`/`nil` omits
+  it. Pass `no_edit: true` to emit `--no-edit`.
+  - `flag_option :edit, negatable: true` → `:edit` `[Boolean]` and `:no_edit`
+    `[Boolean]`
+  - `flag_or_value_option :track, negatable: true` → `:track` `[Boolean, String]`
+    (positive or value form) and `:no_track` `[Boolean]` (boolean only; the negated
+    form never takes a value)
+- **`inline:`** — `value_option :format, inline: true` emits `--format=value` as one
+  token; without it, `--format value` as two tokens.
+- **`max_times:`** — `flag_option :force, max_times: 2` with `force: 2` emits
+  `--force --force`.
+- **`repeatable:`** — accepts an array; emits the flag once per value
+  (e.g., `--include a --include b`).
+- **`as_operand:`** — `value_option :pathspec, as_operand: true` is passed as a
+  keyword but emitted in the operand position after `end_of_options`.
+- **`literal`** — always emits its string unconditionally; the caller has no control.
+- **`execution_option`** — never emits anything to argv; forwarded as Ruby kwargs to
+  the subprocess runner.
+- **`skip_cli:` on operands** — `operand ..., skip_cli: true` binds and validates
+  like any other operand and remains accessible on `Bound`, but is excluded from argv
+  emission.
+- **`end_of_options`** — signals end of options in the emitted argv; only operands
+  may follow (though operands may also appear before it). Emits `--` by default.
+  Override with `as:` when the command uses a different token. See [CHECKLIST.md §
+  Choosing the `as:` token](CHECKLIST.md#choosing-the-as-token) for the decision
+  rule.
+- **Operand/option name collision** — if a positional operand and a keyword option
+  share the same name, the **option keeps its name** and the **operand is renamed**.
+  For repeatable operands, prefer the plural form (`:commit` → `:commits`). See
+  [CHECKLIST.md § Operand naming](CHECKLIST.md#operand-naming) for details.
+
+## Workflow
+
+1. **Determine scope and exclusions** — using the git documentation loaded during
+   [Input](#input), identify which options are in scope for the DSL. See
+   [CHECKLIST.md §1](CHECKLIST.md#1-determine-scope-and-exclusions).
+
+2. **Audit each DSL entry** — for each entry in `arguments do`, walk through
+   [CHECKLIST.md](CHECKLIST.md) §2–§5:
+   1. Verify DSL method per option type
+   2. Verify alias and `as:` usage
+   3. Verify ordering
+   4. Verify modifiers
+
+   For each entry, also trace the verification chain — confirm the full mapping:
+
+   `Ruby call → bound argument → expected git CLI`
+
+   Compare the expected CLI output against the git man-page documentation.
+
+3. **Check completeness** — verify the DSL as a whole against the git man page per
+   [CHECKLIST.md §6](CHECKLIST.md#6-check-completeness): YARD↔DSL parity, missing
+   options, repeatable flags, operand naming, and per-argument validation.
+
+4. **Check class-level declarations** — verify `allow_exit_status` and
+   `requires_git_version` per
+   [CHECKLIST.md §7](CHECKLIST.md#7-check-class-level-declarations).
+
+5. **Check the validation delegation policy** — verify that cross-argument
+   constraint methods (`conflicts`, `requires`, etc.) are used only when
+   justified. See the constraint policy in
+   [CHECKLIST.md §6 Per-argument validation completeness](CHECKLIST.md#per-argument-validation-completeness).
+
+6. **Collect issues** — record all findings for the [Output](#output).
+
+## Output
+
+Produce:
+
+1. A per-entry table:
+
+   | # | DSL method | Definition | CLI output | Correct? | Issue |
+   | --- | --- | --- | --- | --- | --- |
+
+2. A list of missing options/modifier/order/conflict issues
+3. Any class-level declaration mismatches: `allow_exit_status` not present with
+   a `Range` and rationale comment when the command has non-zero successful
+   exits; `requires_git_version` not present only when the command was
+   introduced after `Git::MINIMUM_GIT_VERSION`

data/.github/skills/review-backward-compatibility/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: review-backward-compatibility
+description: "Audits Git::Lib methods for backward compatibility after commands are moved to Git::Commands::* classes. Use to verify that migrated commands maintain their existing public API."
+---
+
+# Review Backward Compatibility
+
+Review `Git::Lib` methods for backward compatibility after commands are moved to
+`Git::Commands::*` classes. This skill guides the process of restoring backward
+compatibility for a specific set of git commands while maintaining the benefits of
+the new command infrastructure.
+
+## Contents
+
+- [How to use this skill](#how-to-use-this-skill)
+- [Related skills](#related-skills)
+- [Objective](#objective)
+- [Current Command Architecture Note](#current-command-architecture-note)
+- [Instructions](#instructions)
+  - [Branch setup](#branch-setup)
+  - [Step 1: Identify Methods Added Since v4.3.0](#step-1-identify-methods-added-since-v430)
+  - [Step 2: Remove New Methods](#step-2-remove-new-methods)
+  - [Step 3: Restore Backward-Compatible Implementations](#step-3-restore-backward-compatible-implementations)
+  - [Step 4: Add Required Dependencies](#step-4-add-required-dependencies)
+  - [Step 5: Verify the Changes](#step-5-verify-the-changes)
+- [Example: Stash Commands](#example-stash-commands)
+  - [Legacy Methods (v4.3.0)](#legacy-methods-v430)
+  - [New Methods (removed)](#new-methods-removed)
+  - [Implementation Pattern](#implementation-pattern)
+- [Key Principles](#key-principles)
+- [Validation Checklist](#validation-checklist)
+- [Usage](#usage)
+
+## How to use this skill
+
+Attach this file to your Copilot Chat context, then invoke it with the git
+command name(s) to audit. Example:
+
+```text
+Remove methods added to Git::Lib since v4.3.0 for the `branch` git command
+and ensure the remaining methods are backward compatible.
+```
+
+Replace `branch` with the specific git command(s) you want to audit (e.g.,
+`worktree`, `tag`, `merge`, `reset`).
+
+## Related skills
+
+- [Refactor Command to CommandLineResult](../refactor-command-to-commandlineresult/SKILL.md) — migrating command classes to Base;
+  the counterpart to this skill's `Git::Lib` facade focus
+- [Command Implementation](../command-implementation/SKILL.md) — class structure, phased rollout gates, and
+  internal compatibility contracts
+
+## Objective
+
+For the specified git command(s), remove methods added to `Git::Lib` since v4.3.0 and ensure that remaining methods (which existed in v4.3.0) are backward compatible.
+
+## Current Command Architecture Note
+
+When auditing modern implementations, assume command classes follow `Git::Commands::Base`:
+
+- classes use `class < Git::Commands::Base` with `arguments do ... end`
+- command entrypoint is `call(*, **)` (inherited from `Base`)
+- exit-status behavior is centralized via `allow_exit_status` declarations on the class
+
+Because of this, backward-compatibility adaptation should happen in `Git::Lib`
+methods (facade/adapter layer), not by reintroducing legacy execution logic inside
+command classes.
+
+## Instructions
+
+### Branch setup
+
+All work must be done on a feature branch. **Never commit or push directly to
+`main`.**
+
+Before starting, create a new branch:
+
+```bash
+git checkout -b <feature-branch-name>
+```
+
+All commits in this workflow go on the feature branch. When work is complete,
+open a pull request — do not merge or push directly into `main`.
+
+### Step 1: Identify Methods Added Since v4.3.0
+
+1. Check out the v4.3.0 tag to examine the historical state:
+
+   **Warning:** `git checkout` modifies the working tree. Stash or commit any
+   uncommitted changes first (`git stash`).
+
+   ```bash
+   git checkout v4.3.0
+   ```
+
+2. Search `lib/git/lib.rb` for all methods related to the specified git command(s):
+   ```bash
+   grep -n "def <command_name>" lib/git/lib.rb
+   ```
+
+3. Document each method found, including:
+   - Method name and signature
+   - Return value type (String, Array, Hash, Boolean, etc.)
+   - Exact return value format (e.g., `Array<[Integer, String]>`, `String` with specific content)
+
+4. Return to your feature branch:
+   ```bash
+   git checkout -
+   ```
+
+5. Search for the same command methods in the current version:
+   ```bash
+   grep -n "def <command_name>" lib/git/lib.rb
+   ```
+
+6. Create two lists:
+   - **Legacy methods**: Methods that existed in v4.3.0 (must be preserved and made compatible)
+   - **New methods**: Methods that don't exist in v4.3.0 (should be removed)
+
+### Step 2: Remove New Methods
+
+1. Identify all new methods that were added after v4.3.0
+2. Remove these methods entirely from `lib/git/lib.rb`
+3. Remove any `require` statements that are only used by the removed methods
+
+### Step 3: Restore Backward-Compatible Implementations
+
+For each legacy method that needs to be preserved:
+
+1. **Use modern command infrastructure internally:**
+   - Call the appropriate `Git::Commands::<Command>::*` class
+   - Ensure all necessary command classes are required at the top of the file
+
+2. **Convert return values to match v4.3.0 exactly:**
+   - Compare the return type from the modern command with the v4.3.0 return type
+   - If they differ, add conversion logic to transform the result
+   - Modern commands typically return `CommandLineResult` objects with `.stdout`, `.stderr`, and `.status`
+   - Legacy methods may have returned raw strings, arrays, or other types
+
+3. **Create helper methods if needed:**
+   - For complex conversions (e.g., parsing output into specific formats), create private helper methods
+   - Name helpers clearly (e.g., `<command>_info_to_legacy`)
+   - Place helpers near the bottom of the file in the private section
+
+### Step 4: Add Required Dependencies
+
+1. Ensure all necessary `require` statements are present:
+   ```ruby
+   require_relative 'git/commands/<command>/<action>'
+   require_relative 'git/parsers/<command>' # if using parsers
+   ```
+
+2. Only keep requires for:
+   - Command classes used by the legacy methods
+   - Parsers needed for conversion
+   - Remove requires for deleted commands
+
+### Step 5: Verify the Changes
+
+1. Check the diff to ensure:
+   ```bash
+   git diff lib/git/lib.rb
+   ```
+   - All new methods are removed
+   - All legacy methods are present with correct signatures
+   - Return value conversions are in place
+   - Correct require statements are present
+
+2. Verify that the implementation uses modern command classes:
+   ```bash
+   git diff lib/git/lib.rb | grep -E "^\+.*Git::Commands::<Command>"
+   ```
+
+3. Check the net line change (should be negative if removing methods):
+   ```bash
+   git diff --stat lib/git/lib.rb
+   ```
+
+## Example: Stash Commands
+
+Here's how this process was applied to the `stash` commands:
+
+### Legacy Methods (v4.3.0)
+- `stashes_all` → returned `Array<[Integer, String]>` (index and message pairs)
+- `stash_save(message)` → returned regex match result (truthy/falsy)
+- `stash_apply(id)` → returned `String` (stdout)
+- `stash_clear` → returned `String` (stdout)
+- `stash_list` → returned `String` (stdout)
+
+### New Methods (removed)
+- `stash_branch`
+- `stash_create`
+- `stash_drop`
+- `stash_pop`
+- `stash_push`
+- `stashes_list`
+- `git_stash_show_*` methods
+
+### Implementation Pattern
+
+```ruby
+# Requires at top of file
+require_relative 'git/commands/stash/apply'
+require_relative 'git/commands/stash/clear'
+require_relative 'git/commands/stash/list'
+require_relative 'git/commands/stash/push'
+require_relative 'git/parsers/stash'
+
+# Legacy method implementations
+def stashes_all
+  result = Git::Commands::Stash::List.new(self).call
+  stashes = Git::Parsers::Stash.parse_list(result.stdout)
+  stashes.map { |info| stash_info_to_legacy(info) }
+end
+
+def stash_save(message)
+  result = Git::Commands::Stash::Push.new(self).call(message: message)
+  result.stdout =~ /HEAD is now at/
+end
+
+def stash_apply(id = nil)
+  result = Git::Commands::Stash::Apply.new(self).call(id)
+  result.stdout
+end
+
+def stash_clear
+  result = Git::Commands::Stash::Clear.new(self).call
+  result.stdout
+end
+
+def stash_list
+  result = Git::Commands::Stash::List.new(self).call
+  result.stdout
+end
+
+# Helper method (in private section)
+private
+
+def stash_info_to_legacy(stash_info)
+  [stash_info.index, stash_info.message]
+end
+```
+
+## Key Principles
+
+1. **Maintain exact v4.3.0 return values**: Don't change return types even slightly
+2. **Use modern infrastructure internally**: Leverage `Git::Commands::*` classes for actual git operations
+3. **Remove all new methods**: Don't try to make new methods backward compatible - just remove them
+4. **Minimize changes**: Only modify what's necessary for backward compatibility
+5. **Document conversions**: Make helper methods clear and well-named
+6. **Apply policy at the facade**: `Git::Lib` methods pass policy options explicitly
+   (e.g. `no_edit: true`, `verbose: true`, `no_progress: true`) — command classes stay
+   neutral. See "Command-layer neutrality" in CONTRIBUTING.md.
+
+## Validation Checklist
+
+- [ ] Working on a feature branch (not `main`)
+- [ ] Identified all methods for the command in v4.3.0
+- [ ] Documented v4.3.0 return values exactly
+- [ ] Removed all methods not present in v4.3.0
+- [ ] Implemented legacy methods using modern command classes
+- [ ] Added conversion logic where return types differ
+- [ ] Created helper methods for complex conversions
+- [ ] Updated require statements correctly
+- [ ] Verified changes with git diff
+- [ ] Net line count decreased (removed more than added)
+
+## Usage
+
+To apply this process, say:
+
+> Remove methods added to Git::Lib since v4.3.0 for `<command_name>` git command(s) and ensure the remaining methods are backward compatible.
+
+Replace `<command_name>` with the specific git command(s) you want to audit (e.g., `branch`, `merge`, `tag`, `reset`, etc.).

data/.github/skills/review-cross-command-consistency/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: review-cross-command-consistency
+description: "Compares sibling command classes for consistent structure, documentation, testing, and exit-status conventions under the Base architecture. Use for cross-command audits."
+---
+
+# Review Cross-Command Consistency
+
+Review sibling command classes (same module/family) for consistent structure,
+documentation, testing, and exit-status conventions under the `Base` architecture.
+
+## Contents
+
+- [How to use this skill](#how-to-use-this-skill)
+- [Prerequisites](#prerequisites)
+- [Related skills](#related-skills)
+- [Version-Aware Comparison Scope](#version-aware-comparison-scope)
+- [What to Check](#what-to-check)
+  - [1. Class structure consistency](#1-class-structure-consistency)
+  - [2. Arguments DSL consistency](#2-arguments-dsl-consistency)
+  - [3. Exit-status consistency](#3-exit-status-consistency)
+  - [4. YARD consistency](#4-yard-consistency)
+  - [5. Unit spec consistency](#5-unit-spec-consistency)
+  - [6. Integration spec consistency](#6-integration-spec-consistency)
+  - [7. Migration process consistency](#7-migration-process-consistency)
+- [Output](#output)
+
+## How to use this skill
+
+Attach this file to your Copilot Chat context, then invoke it with the sibling
+command files (same module/family) to compare. Examples:
+
+```text
+Using the Review Cross-Command Consistency skill, review the
+Git::Commands::Diff family: lib/git/commands/diff/patch.rb,
+lib/git/commands/diff/numstat.rb, lib/git/commands/diff/raw.rb.
+```
+
+```text
+Review Cross-Command Consistency: all files under lib/git/commands/stash/
+```
+
+The invocation needs two or more sibling command files from the same family.
+
+## 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
+
+- [Command Implementation](../command-implementation/REFERENCE.md#phased-rollout-requirements) — canonical class-shape checklist, phased
+  rollout gates, and internal compatibility contracts
+- [Review Arguments DSL](../review-arguments-dsl/SKILL.md) — verifying DSL entries match git CLI
+- [Command Test Conventions](../command-test-conventions/SKILL.md) — unit/integration test conventions for command classes
+- [Command YARD Documentation](../command-yard-documentation/SKILL.md) — documentation completeness for command classes
+
+## Version-Aware Comparison Scope
+
+Before flagging siblings as inconsistent for option names, aliases, negated
+forms, or documented values, determine the repository's minimum supported Git
+version from project metadata. In this repository, `git.gemspec` declares
+`git 2.28.0 or greater`.
+
+Consistency judgments for CLI surface area must be based on the minimum
+supported Git version, not only on the locally installed Git. Use
+version-matched upstream documentation first, version-matched upstream source
+when exact parser behavior is ambiguous, and local `git <command> -h` output
+only as a supplemental check.
+
+## What to Check
+
+### 1. Class structure consistency
+
+- [ ] all classes use `class < Git::Commands::Base`
+- [ ] all require `git/commands/base`
+- [ ] all use `arguments do ... end` (no legacy `ARGS =` constants)
+- [ ] simple commands carry YARD directive `# @!method call(*, **)` with nested `@overload` blocks and have no explicit `def call` definition
+- [ ] commands with legitimate `call` overrides (stdin protocol, input validation, non-trivial option routing) use explicit YARD docs instead and do **not** carry the `# @!method` directive
+- [ ] commands with `call` overrides use `Base#with_stdin` for stdin feeding and delegate exit-status validation to `validate_exit_status!`
+
+### 2. Arguments DSL consistency
+
+- [ ] shared options use same alias/modifier patterns
+- [ ] shared entries appear in same relative order
+- [ ] command-specific differences are intentional and documented
+- [ ] no `literal` entries for policy/output-control flags (`--no-edit`, `--verbose`,
+      `--no-progress`, `--no-color`, etc.) — command classes are neutral, faithful
+      representations of the git CLI; all siblings use `flag_option` /
+      `value_option` for these, leaving policy decisions to the facade. See
+      "Command-layer neutrality" in CONTRIBUTING.md.
+
+### 3. Exit-status consistency
+
+- [ ] siblings with same git exit semantics use same `allow_exit_status` range
+- [ ] rationale comments are present and consistent in tone
+- [ ] commands without non-zero successful exits do not declare custom ranges
+
+### 4. YARD consistency
+
+- [ ] consistent class summaries and `@api private`
+- [ ] `@overload` coverage consistent for equivalent call shapes
+- [ ] `@return` and `@raise` wording consistent across siblings — `@raise [Git::FailedError]` uses the canonical generic form ("if git exits with a non-zero exit status" for default range; "if git exits outside the allowed range (exit code > N)" for non-default); never enumerates specific failure causes
+- [ ] tag short descriptions do not end with punctuation
+- [ ] multi-paragraph tag descriptions have a blank comment line between the short
+      description and each continuation paragraph
+
+### 5. Unit spec consistency
+
+- [ ] expectations include `raise_on_failure: false` where command invocation is asserted
+- [ ] similar option paths use similar context naming
+- [ ] exit-status tests are parallel where ranges are shared
+
+### 6. Integration spec consistency
+
+- [ ] success/failure grouping uses same structure
+- [ ] no output-format assertions (smoke + error handling only)
+
+### 7. Migration process consistency
+
+See **[Command Implementation § Phased rollout requirements](../command-implementation/REFERENCE.md#phased-rollout-requirements)** for
+the canonical checklist. During a cross-command audit, verify that sibling commands
+were migrated in the same slice and that the same quality gates were applied.
+
+## Output
+
+1. Summary table:
+
+   | Aspect | File A | File B | File C | Status |
+   | --- | --- | --- | --- | --- |
+
+2. Inconsistency list with canonical recommendation:
+
+   | Issue | Files | Recommended canonical form |
+   | --- | --- | --- |
+
+> **Branch workflow:** Implement any fixes on a feature branch. Never commit or
+> push directly to `main` — open a pull request when changes are ready to merge.