git 5.1.0 → 5.2.0

data/.github/skills/yard-documentation/element-rules.md

@@ -1,162 +0,0 @@
-# YARD Element-Specific Rules
-
-Per-element YARD requirements for classes, modules, constants, attributes,
-dynamically defined methods, and value objects
-(`Data.define` / `Struct.new`).
-
-Consult this file when documenting one of those elements. Rules that apply to
-**every** doc comment (formatting, length limits, tag order) and to **methods**
-live in [SKILL.md](SKILL.md).
-
-## Contents
-
-- [Contents](#contents)
-- [Classes](#classes)
-- [Modules](#modules)
-- [Constants](#constants)
-- [Attributes](#attributes)
-- [Dynamically defined methods (`@!method`)](#dynamically-defined-methods-method)
-- [`Data.define` classes](#datadefine-classes)
-- [`Struct.new` classes](#structnew-classes)
-
-## Classes
-
-- One-sentence class description as a **noun phrase** (or starting with "Represents…") — the description should pass
-  the "This class is a…" litmus test (i.e. you should be able to prefix "This class
-  is a" and produce a grammatical sentence). "Represents…" is an accepted convention.
-  Do not start descriptions with "This class is…", "Provides…", or "Encapsulates…".
-  - Good: `Wrapper around the git binary`, `Immutable value object for a branch
-    delete result`, `Represents a git branch`
-  - Bad: `This class wraps the git binary`, `Provides branch deletion`,
-    `Encapsulates branch state`
-- `@api public` or `@api private` tag to declare visibility — use `@api public` for
-  stable user-facing classes; use `@api private` for internal implementation classes
-  (e.g., `Git::ExecutionContext::*`, `Git::Commands::*`, parsers)
-- At least one `@example` showing typical instantiation or primary usage — this
-  applies to all classes including `@api private` classes
-- Error/exception classes must also state when the error is raised in class-level
-  prose, using caller-facing wording such as `Raised when branch deletion fails`
-- Deprecated classes must include `@deprecated` explaining the migration path
-- When present, class-level tags must appear in this order: `@example`, `@note`,
-  `@deprecated`, `@see`, `@api`, `@abstract`
-
-## Modules
-
-- One-sentence description — "Namespace for…", "Provides helpers for…", or
-  "Mixin that adds…"
-- `@api public` or `@api private` — use `@api public` for stable user-facing modules;
-  use `@api private` for internal implementation modules
-- No `@example` required unless the module provides standalone methods
-- Deprecated modules must include `@deprecated` explaining the migration path
-- When present, module-level tags must appear in the same order as class-level
-  tags: `@example`, `@note`, `@deprecated`, `@see`, `@api`
-
-## Constants
-
-- A comment immediately above the constant describing its purpose and valid values
-- No special YARD tag is needed; YARD picks up the preceding comment automatically
-- Add `# @return [Type]` when the constant holds a collection, frozen structure, or
-  domain-specific type whose shape is not immediately obvious from the value
-
-## Attributes
-
-- For explicitly written `attr_reader`, `attr_accessor`, and `attr_writer` declarations,
-  place the documentation directly above the attribute; do **not** use the `@!attribute`
-  directive
-- For dynamically created attributes, `Data.define` members, or `Struct.new`
-  members, you **must** use a `# @!attribute [r/rw/w] name` YARD directive
-- Must include `@return [Type] description` explaining the value and its units or
-  constraints if relevant
-- For explicit `attr_reader`/`attr_accessor`/`attr_writer`, include a short
-  description paragraph above the attribute in addition to `@return`
-- For `@!attribute` directives (in `Data.define` / `Struct.new`), the `@return`
-  tag inside the directive block serves as the sole documentation — no separate
-  short description is needed
-- Tags inside `@!attribute` (and `@!method`) directive blocks must be indented
-  two extra spaces relative to the directive itself
-- Must be defined at the class level, not inside method bodies
-
-## Dynamically defined methods (`@!method`)
-
-Use the `# @!method name(params)` directive for methods created via
-metaprogramming (`define_method`, method-generating DSLs, etc.) that have no
-literal `def`. Place the directive and its doc comment where the method would
-logically appear in the class body. Tags inside the directive block follow the
-same indentation rule as `@!attribute` — indented two extra spaces relative to
-the directive.
-
-If an `@!method` block uses `@overload`, follow overload tag-placement rules in
-[SKILL.md](SKILL.md): keep `@return` inside each overload, keep shared
-`@raise` at top level, and keep `@api` at top level.
-
-## `Data.define` classes
-
-Immutable value objects defined with `Data.define` use the following conventions
-(see `Git::BranchDeleteFailure` for a canonical example):
-
-- Class-level doc: noun-phrase short description, `@example`, `@see`, `@api`
-- One `@!attribute [r]` directive per member with `@return [Type] description`
-- Attribute directives are placed after class-level tags and before the
-  `Data.define` line
-- Custom methods defined inside the `Data.define` block follow standard method
-  rules
-
-```ruby
-# Immutable value object for a failed branch delete
-#
-# @example Create a failure object
-#   failure = BranchDeleteFailure.new(
-#     name: 'nonexistent',
-#     error_message: "branch 'nonexistent' not found."
-#   )
-#   failure.name          #=> 'nonexistent'
-#   failure.error_message #=> "branch 'nonexistent' not found."
-#
-# @see Git::BranchDeleteResult
-#
-# @api public
-#
-# @!attribute [r] name
-#
-#   @return [String] the branch name that failed to delete
-#
-# @!attribute [r] error_message
-#
-#   @return [String] the git error message explaining the failure
-#
-BranchDeleteFailure = Data.define(:name, :error_message)
-```
-
-## `Struct.new` classes
-
-Document `Struct.new` classes using the same conventions as `Data.define` classes:
-class-level doc with a noun-phrase short description, `@example`, `@see`, `@api`,
-and one `@!attribute` directive per member with `@return [Type] description`.
-
-Unlike `Data.define`, a `Struct.new` class is **mutable** — it generates
-read-write accessors — so use `@!attribute [rw]` (not `[r]`) for its members and
-do not describe it as immutable.
-
-```ruby
-# Value object for a diff hunk's location within a file
-#
-# @example Create and update a hunk location
-#   loc = HunkLocation.new(start_line: 10, line_count: 3)
-#   loc.start_line #=> 10
-#   loc.line_count = 4
-#   loc.line_count #=> 4
-#
-# @see Git::DiffInfo
-#
-# @api public
-#
-# @!attribute [rw] start_line
-#
-#   @return [Integer] the 1-based line where the hunk begins
-#
-# @!attribute [rw] line_count
-#
-#   @return [Integer] the number of lines the hunk spans
-#
-HunkLocation = Struct.new(:start_line, :line_count, keyword_init: true)
-```

data/.github/skills-deprecated/README.md

@@ -1,21 +0,0 @@
-# Deprecated skills
-
-This directory holds skills that have been **retired** from active use. They are
-kept on disk for historical reference only — they are intentionally located outside
-`.github/skills/` so they are not auto-discovered or loaded into agent context.
-
-## Retired skills
-
-- **`extract-command-from-lib/`** — guided migrating a `Git::Lib` `#command` call
-  into a `Git::Commands::*` class during the v5.0.0 architectural redesign.
-- **`extract-facade-from-base-lib/`** — guided migrating a public method from
-  `Git::Base` / `Git::Lib` into a `Git::Repository::*` facade method during the same
-  redesign.
-- **`review-backward-compatibility/`** — audited `Git::Lib` methods for backward
-  compatibility during the migration to `Git::Commands::*`. `Git::Lib` was deleted in
-  PR #1456 as part of Phase 4 Step A; this workflow no longer applies.
-
-The extract-* skills describe migration work that is now complete: `Git::Base` and
-`Git::Lib` have been removed from the codebase, so there is nothing left to extract.
-All three skills remain here as a record of the workflow used during the migration,
-in case similar work is needed again in the future.

data/.github/skills-deprecated/extract-command-from-lib/SKILL.md

@@ -1,487 +0,0 @@
----
-name: extract-command-from-lib
-description: "Migrates a direct #command call in Git::Lib to a Git::Commands::* class as part of the architectural redesign. Use when extracting a specific command during the Strangler Fig migration."
----
-
-# Extract Command from Lib
-
-Replace a direct `#command` call in `Git::Lib` with a call to a `Git::Commands::*`
-class. The git subcommand is determined by the first (or first few) arguments to the
-`#command` method call.
-
-## Contents
-
-- [How to use this skill](#how-to-use-this-skill)
-- [Prerequisites](#prerequisites)
-- [Related skills](#related-skills)
-- [Input](#input)
-- [Workflow](#workflow)
-  - [Branch setup](#branch-setup)
-  - [Step 1 — Identify the `#command` call](#step-1-identify-the-command-call)
-  - [Step 2 — Plan the migration and get approval](#step-2-plan-the-migration-and-get-approval)
-  - [Step 3 — Ensure adequate legacy tests](#step-3-ensure-adequate-legacy-tests)
-  - [Step 4 — Ensure the `Git::Commands::*` class exists](#step-4-ensure-the-gitcommands-class-exists)
-  - [Step 5 — Update `Git::Lib` to delegate to the command class](#step-5-update-gitlib-to-delegate-to-the-command-class)
-- [Commit discipline](#commit-discipline)
-- [Create a pull request](#create-a-pull-request)
-- [Quality gates (run at every step)](#quality-gates-run-at-every-step)
-- [Common patterns](#common-patterns)
-  - [Simple delegation (stdout passthrough)](#simple-delegation-stdout-passthrough)
-  - [Delegation with post-processing](#delegation-with-post-processing)
-  - [Delegation with parsed return value](#delegation-with-parsed-return-value)
-  - [Delegation with opts-hash key normalization](#delegation-with-opts-hash-key-normalization)
-  - [Delegation with option filtering (preventing API expansion)](#delegation-with-option-filtering-preventing-api-expansion)
-- [What stays in `Git::Lib`](#what-stays-in-gitlib)
-- [What moves to `Git::Commands::*`](#what-moves-to-gitcommands)
-
-## How to use this skill
-
-Attach this file to your Copilot Chat context, then invoke it with a short message
-identifying the `Git::Lib` method or `#command` call to migrate. Examples:
-
-```text
-Using the Extract Command from Lib skill, migrate Git::Lib#worktree_add —
-it calls command('worktree', 'add', ...).
-```
-
-```text
-Extract Command from Lib: command('ls-tree', ...)
-```
-
-The invocation needs either the `Git::Lib` method name or the git subcommand string
-from the `#command` call (or both).
-
-## Prerequisites
-
-Before starting, you **MUST** load the following skill(s) in their entirety:
-
-- [YARD Documentation](../../skills/yard-documentation/SKILL.md) — authoritative
-  source for YARD formatting rules and writing standards;
-
-## Related skills
-
-Run or reference these skills during the workflow:
-
-- [Command Implementation](../../skills/command-implementation/SKILL.md) — generates and reviews `Git::Commands::*`
-  classes, unit tests, integration tests, and YARD docs (used in Step 4 if the
-  command class does not exist yet); also the canonical class-shape checklist,
-  phased rollout gates, and internal compatibility contracts
-- [Review Arguments DSL](../../skills/review-arguments-dsl/SKILL.md) — verifying DSL entries match git CLI
-- [Command Test Conventions](../../skills/command-test-conventions/SKILL.md) — unit/integration test conventions for command classes
-- [Command YARD Documentation](../../skills/command-yard-documentation/SKILL.md) — documentation completeness for command classes
-- [Review Cross-Command Consistency](../../skills/review-cross-command-consistency/SKILL.md) — sibling consistency within a command family
-- [Review Backward Compatibility](../../skills/review-backward-compatibility/SKILL.md) — preserving `Git::Lib` return-value contracts
-- [Extract Facade from Base/Lib](../extract-facade-from-base-lib/SKILL.md) — the
-  follow-on extraction that moves the public method from `Git::Base` /
-  `Git::Lib` into a `Git::Repository::*` facade method (Phase 4 deletes both
-  `Git::Base` and `Git::Lib`)
-
-## Input
-
-Required:
-
-1. A `Git::Lib` method that contains one or more `command(...)` calls to replace
-2. The git subcommand name (derived from the first arguments to `#command`)
-
-## Workflow
-
-### 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 the `#command` call
-
-1. Locate the `Git::Lib` method that calls `command(...)`.
-2. Note:
-   - the git subcommand (first argument(s) to `#command`)
-   - the options/arguments passed after the subcommand
-   - execution options (e.g., `timeout:`, `out:`, `err:`, `env:`)
-   - the return value and any post-processing (`.stdout`, parsing, regex matching)
-3. Document the method's current **public contract**: signature, return type, and
-   return-value format (String, Array, Hash, Boolean, etc.)
-4. Run linters and rubocop to confirm a clean baseline:
-
-   ```bash
-   bundle exec rubocop
-   ```
-
-   Fix any issues before continuing.
-
-### Step 2 — Plan the migration and get approval
-
-Before writing or changing any code, present a migration plan and **wait for
-explicit confirmation** from the user. Do not proceed until they approve.
-
-The plan must cover every `#command` call identified above. For each one, state:
-
-| `Git::Lib` method | `#command` call | Target `Git::Commands` class | Class exists? | Notes |
-| --- | --- | --- | --- | --- |
-| `some_method` | `command('sub', '--flag', arg)` | `Git::Commands::Sub` (new) or existing | ✅ / 🆕 | any mapping decisions |
-
-Also state:
-
-- Which (if any) new `Git::Commands::*` classes need to be created
-- How optional or empty arguments will be handled (e.g., nil vs `''` operands)
-- Any return-value post-processing that stays in `Git::Lib`
-
-Then ask:
-
-> Does this mapping look correct? Any changes before I start implementing?
-
-**Do not move to Step 3 until the user confirms the plan.**
-
-### Step 3 — Ensure adequate legacy tests
-
-Before making any changes, verify that `tests/units/` has adequate tests for the
-`Git::Lib` method being migrated.
-
-1. Search existing legacy tests for coverage of the method:
-
-   ```bash
-   grep -rn '<method_name>' tests/units/
-   ```
-
-2. If coverage is insufficient, add **minimal new tests** to the legacy test suite
-   that exercise the method's current behavior. These tests ensure the refactor does
-   not break backward compatibility.
-   - Do **not** change existing tests.
-   - Follow existing legacy test conventions (`Test::Unit::TestCase`,
-     `assert_command_line_eq`, `in_temp_dir`, etc.).
-   - Verify new tests pass:
-
-     ```bash
-     bundle exec bin/test <test-file-basename>
-     ```
-
-   - Run rubocop against the new test file:
-
-     ```bash
-     bundle exec rubocop tests/units/<test-file>
-     ```
-
-   - Fix any issues before continuing.
-3. Commit the new legacy tests:
-
-   ```bash
-   git add tests/units/<test-file>
-   git commit -m "refactor(test): add legacy tests for <method_name>"
-   ```
-
-### Step 4 — Ensure the `Git::Commands::*` class exists
-
-1. Search `lib/git/commands/` for an existing command class that matches the git
-   subcommand:
-
-   ```bash
-   find lib/git/commands -name '*.rb' | sort
-   ```
-
-   Also check the class contents to confirm the existing class covers the same
-   subcommand variation (e.g., `branch --show-current` vs. `branch --list`).
-
-2. **If the command class already exists**, skip to Step 5.
-
-3. **If the command class does not exist**, scaffold it using the
-  [Command Implementation](../../skills/command-implementation/SKILL.md) skill. This produces:
-
-   - `lib/git/commands/<command>.rb` (or `lib/git/commands/<family>/<action>.rb`)
-   - `spec/unit/git/commands/<command>_spec.rb`
-   - `spec/integration/git/commands/<command>_spec.rb`
-
-4. Verify the new command class:
-
-   ```bash
-   bundle exec rspec spec/unit/git/commands/<command>_spec.rb
-   bundle exec rspec spec/integration/git/commands/<command>_spec.rb
-   bundle exec rubocop lib/git/commands/<command>.rb
-   bundle exec rake yard
-   ```
-
-   Fix any issues before continuing.
-
-5. Commit the new command class and its tests:
-
-   ```bash
-   git add lib/git/commands/<command>*.rb spec/
-   git commit -m "refactor(command): add Git::Commands::<Command> class"
-   ```
-
-### Step 5 — Update `Git::Lib` to delegate to the command class
-
-1. Replace the `command(...)` call with a call to the `Git::Commands::*` class:
-
-   ```ruby
-   # Before
-   def some_method(args)
-     command('some-command', '--flag', args).stdout
-   end
-
-   # After
-   def some_method(args)
-     Git::Commands::SomeCommand.new(self).call(args, flag: true).stdout
-   end
-   ```
-
-2. Preserve the method's **exact return value contract** — apply any parsing or
-   transformation after `.stdout` / `.stderr` / `.status` to match the original
-   return type.
-
-3. **Prevent API expansion** — the command class may accept many more options than
-   the legacy `Git::Lib` method ever exposed. Only forward the options that were
-   part of the original `Git::Lib` method's public API. Use a `<COMMAND>_ALLOWED_OPTS`
-   constant to whitelist permitted option keys, call `assert_valid_opts` to raise
-   on unknown keys, then filter with `opts.slice` before forwarding:
-
-   ```ruby
-   PULL_ALLOWED_OPTS = %i[allow_unrelated_histories].freeze
-
-   def pull(remote = nil, branch = nil, opts = {})
-     assert_valid_opts(opts, PULL_ALLOWED_OPTS)
-     allowed_opts = opts.slice(*PULL_ALLOWED_OPTS)
-     Git::Commands::Pull.new(self).call(remote, branch, **allowed_opts).stdout
-   end
-   ```
-
-   `assert_valid_opts` raises `ArgumentError` for any unrecognised key, giving
-   callers a clear error instead of silently ignoring unknown options. This
-   ensures that callers cannot accidentally pass options that happen to match
-   command DSL option names but were never part of the public contract.
-
-4. Add the appropriate `require_relative` at the top of `lib/git/lib.rb` if not
-   already present.
-
-4. Verify:
-
-   ```bash
-   bundle exec bin/test <legacy-test-file-basename>
-   bundle exec rspec
-   bundle exec rubocop
-   bundle exec rake yard
-   ```
-
-   Fix any issues before continuing.
-
-5. Commit the `Git::Lib` change:
-
-   ```bash
-   git add lib/git/lib.rb
-   git commit -m "refactor(lib): delegate <method_name> to Git::Commands::<Command>"
-   ```
-
-## Commit discipline
-
-Keep work organized into **three logical commit categories** (each optional if no
-changes were needed for that step):
-
-1. `refactor(test): add legacy tests for <method_name>` — new tests in
-   `tests/units/`
-2. `refactor(command): add Git::Commands::<Command> class` — new command class,
-   unit specs, and integration specs
-3. `refactor(lib): delegate <method_name> to Git::Commands::<Command>` — `Git::Lib`
-   changes only
-
-During implementation, you may use multiple task-level commits. Before opening a
-PR, follow the repository finalize workflow (see
-[Development Workflow](../../skills/development-workflow/SKILL.md)) and squash commits as
-required.
-
-**Issue and PR references in commit bodies:** 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, breaking the
-body/footer split. To close an issue/PR, use `Closes`/`Fixes`/`Resolves #<number>`
-in the footer. To merely mention one for context, omit the `#` and no footer line
-is needed.
-
-If further changes are needed after task commits are created:
-
-- Amend the change to the **appropriate commit** (e.g., a command class fix goes
-  into the `refactor(command)` commit).
-- Rebase the later commits on top:
-
-  ```bash
-  git rebase -i <base-commit>
-  ```
-
-- After rebasing, verify all quality gates still pass:
-
-  ```bash
-  bundle exec rspec && bundle exec rake test && bundle exec rubocop && bundle exec rake yard
-  ```
-
-## Create a pull request
-
-Once all commits are clean and quality gates pass, create a PR for the branch.
-
-If changes are made after the PR is created:
-
-- Amend the change to the appropriate commit.
-- Rebase later commits on top.
-- Force-push the branch:
-
-  ```bash
-  git push --force-with-lease
-  ```
-
-## Quality gates (run at every step)
-
-```bash
-bundle exec rspec
-bundle exec rake test
-bundle exec rubocop
-bundle exec rake yard
-```
-
-All four must pass before committing at each step. If errors are found, fix them
-before continuing.
-
-## Common patterns
-
-### Simple delegation (stdout passthrough)
-
-```ruby
-# Before
-def symbolic_ref(branch_name)
-  command('symbolic-ref', 'HEAD', "refs/heads/#{branch_name}")
-end
-
-# After
-def symbolic_ref(branch_name)
-  Git::Commands::SymbolicRef.new(self).call(branch_name).stdout
-end
-```
-
-### Delegation with post-processing
-
-```ruby
-# Before
-def cat_file_type(object)
-  command('cat-file', '-t', object).stdout
-end
-
-# After
-def cat_file_type(object)
-  Git::Commands::CatFile::Type.new(self).call(object).stdout
-end
-```
-
-### Delegation with parsed return value
-
-```ruby
-# Before
-def worktree_list
-  worktrees = {}
-  command('worktree', 'list', '--porcelain').stdout.split("\n").each do |w|
-    # ... parsing ...
-  end
-  worktrees
-end
-
-# After
-def worktree_list
-  result = Git::Commands::Worktree::List.new(self).call
-  worktrees = {}
-  result.stdout.split("\n").each do |w|
-    # ... parsing stays in Git::Lib ...
-  end
-  worktrees
-end
-```
-
-### Delegation with opts-hash key normalization
-
-When the legacy method accepted a flat `opts` hash and uses a `KEY_NORMALIZATIONS`
-constant to rename option keys before forwarding them, the constant's keys must be
-the same type as the keys callers actually pass.
-
-**Ruby's `'key':` symbol-literal syntax creates a *symbol* key** — `{ 'update-head-ok': :x }`
-stores the key `:'update-head-ok'`, not the string `'update-head-ok'`. If legacy
-callers pass string keys, the lookup misses and the raw key is forwarded unchanged,
-causing a git "unsupported option" error at runtime.
-
-Always symbolize keys before the normalization lookup:
-
-```ruby
-# ❌ Bug — string key 'update-head-ok' misses the symbol key :'update-head-ok'
-opts = opts.transform_keys { |k| KEY_NORMALIZATIONS.fetch(k, k) }
-
-# ✅ Correct — symbolize first so both string and symbol callers match
-opts = opts.transform_keys do |k|
-  sym = k.is_a?(Symbol) ? k : k.to_sym
-  KEY_NORMALIZATIONS.fetch(sym, sym)
-end
-```
-
-**When to apply this pattern:** Whenever `transform_keys` is combined with a
-normalization constant whose keys use the `'hyphenated-name':` symbol-literal
-syntax. Scan the constant's definition to confirm its keys are symbols, then
-confirm whether existing callers pass strings or symbols. If callers are a mix —
-or if callers are `Git::Base` or `Git::Lib` methods that forward user-supplied
-hashes — add the symbolization guard.
-
-### Delegation with option filtering (preventing API expansion)
-
-A command class may expose many more options than the legacy `Git::Lib` method
-ever accepted. Without filtering, callers could accidentally pass options that
-happen to match command DSL names but were never part of the public contract.
-
-The facade is also where **policy options** are set as safe defaults — options
-that support non-interactive execution, control output format for parsing, or
-set other command-level defaults. The command class stays neutral; the facade
-makes the defaults explicit. Some defaults are **fixed** (not in `ALLOWED_OPTS` —
-`assert_valid_opts` rejects them if a caller supplies them); others are
-**overridable** (in `ALLOWED_OPTS`, placed before `**opts` so the caller's value
-wins on collision). Examples: `no_edit: true`, `verbose: true`,
-`no_progress: true`, `no_color: true`.
-See "Command-layer neutrality" in CONTRIBUTING.md.
-
-Declare an `<COMMAND>_ALLOWED_OPTS` constant listing only the options that were
-present in the original method. Call `assert_valid_opts` first to raise
-`ArgumentError` on unrecognised keys, then use `opts.slice` to filter before
-forwarding:
-
-```ruby
-# Only :allow_unrelated_histories was accepted by the original Git::Lib#pull
-PULL_ALLOWED_OPTS = %i[allow_unrelated_histories].freeze
-
-def pull(remote = nil, branch = nil, opts = {})
-  raise ArgumentError, 'You must specify a remote if a branch is specified' if remote.nil? && !branch.nil?
-
-  assert_valid_opts(opts, PULL_ALLOWED_OPTS)
-  allowed_opts = opts.slice(*PULL_ALLOWED_OPTS)
-  positional_args = [remote, branch].compact
-  # no_edit: true is the non-interactive default (see CONTRIBUTING.md)
-  Git::Commands::Pull.new(self).call(*positional_args, no_edit: true, **allowed_opts).stdout
-end
-```
-
-`assert_valid_opts` is a private helper already defined in `Git::Lib` — no extra
-require is needed. It raises `ArgumentError: Unknown options: <key>` when any
-unrecognised key is present, giving callers a clear error rather than silently
-dropping the option.
-
-Name the constant after the git subcommand (`PULL_ALLOWED_OPTS`, `FETCH_ALLOWED_OPTS`,
-etc.) and place it immediately before the method definition.
-
-## What stays in `Git::Lib`
-
-- Output parsing and transformation (until a parser class is created)
-- Return-value adaptation to preserve backward compatibility
-- Option validation and filtering to prevent API expansion (see `<COMMAND>_ALLOWED_OPTS` + `assert_valid_opts` pattern)
-- Deprecation shims (e.g., option renames)
-- Method signatures and public API surface
-
-## What moves to `Git::Commands::*`
-
-- Argument building and CLI flag generation
-- `#command` invocation
-- Exit-status handling via `allow_exit_status`

data/.github/skills-deprecated/extract-facade-from-base-lib/KEYWORD_ARG_REMEDIATION.md

@@ -1,22 +0,0 @@
-# Keyword-arg remediation list
-
-The following facade methods are known to use `**opts`/`**` keyword-splat where
-the legacy `Git::Base` or `Git::Lib` predecessor used a positional options hash
-(`opts = {}`). Each is a candidate `legacy-contract` violation that must be
-resolved before `Git.open`/`.clone`/`.init`/`.bare` are changed to return
-`Git::Repository`: either fix the signature or
-record an explicit `5.x-native` justification.
-
-| Facade method | Current signature | Expected classification | Action needed |
-| --- | --- | --- | --- |
-| `Git::Repository::Staging#add` | `add(paths = '.', **)` | `legacy-contract` | Verify against 4.x `Git::Lib#add`; change to `opts = {}` if legacy |
-| `Git::Repository::Staging#reset` | `reset(commitish = nil, **)` | `legacy-contract` | Verify against 4.x `Git::Lib#reset`; change to `opts = {}` if legacy |
-| `Git::Repository::Committing#commit` | `commit(message = nil, **opts)` | `legacy-contract` | Verify against 4.x `Git::Base#commit`; change to `opts = {}` if legacy |
-| `Git::Repository::Committing#commit_all` | `commit_all(*, **)` | `legacy-contract` | Verify against 4.x `Git::Base#commit_all`; change to `opts = {}` if legacy |
-| `Git::Repository::Committing#commit_tree` | `commit_tree(tree, **opts)` | needs classification | Classify; if 5.x-native confirm; if legacy-contract fix signature |
-| `Git::Repository::Committing#write_and_commit_tree` | `write_and_commit_tree(**)` | needs classification | Classify; if 5.x-native confirm; if legacy-contract fix signature |
-| `Git::Repository::Branching#branch_delete` | `branch_delete(*branches, **options)` | needs classification | Verify against 4.x `Git::Base#branch_delete`; classify and fix or confirm |
-| `Git::Repository::Inspecting#fsck` | `fsck(*objects, **)` | needs classification | Verify against 4.x `Git::Lib#fsck`; classify and fix or confirm |
-
-This list is seeded from a static scan of `lib/git/repository/**/*.rb` and may be
-incomplete. A full public-method inventory is required before closing the sweep.