git 4.3.2 → 5.0.0.beta.2

data/.github/skills/facade-implementation/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: facade-implementation
+description: "Scaffolds new and reviews existing Git::Repository facade methods (organized into Git::Repository::* topic modules) with unit tests, integration tests, and YARD docs. Use when adding a new facade method to Git::Repository, updating an existing facade method, choosing or creating a topic module under lib/git/repository/, or reviewing a facade method for correctness."
+---
+
+# Facade Implementation
+
+Scaffold new and review existing facade methods on `Git::Repository`. Facade methods
+live in topic modules under `lib/git/repository/<topic>.rb` (e.g.
+{Git::Repository::Staging}) and are included into the `Git::Repository` class.
+
+A facade method is the public-API entry point that orchestrates one or more
+`Git::Commands::*` calls, optional argument pre-processing, and optional output
+parsing into rich Ruby return values. See
+[redesign/2_architecture_redesign.md §2.1](../../../redesign/2_architecture_redesign.md)
+for the five facade responsibilities this layer is designed around.
+
+## Contents
+
+- [How to use this skill](#how-to-use-this-skill)
+- [Related skills](#related-skills)
+- [Input](#input)
+  - [Existing facade source](#existing-facade-source)
+  - [Existing facade tests](#existing-facade-tests)
+  - [Underlying command class(es)](#underlying-command-classes)
+  - [Underlying parsers (if any)](#underlying-parsers-if-any)
+- [Reference](#reference)
+- [Workflow](#workflow)
+- [Output](#output)
+
+## How to use this skill
+
+Attach this file to your Copilot Chat context, then invoke with the facade method
+to scaffold, update, or review. Examples:
+
+```text
+Using the Facade Implementation skill, scaffold Git::Repository::Staging#add.
+```
+
+```text
+Facade Implementation review: Git::Repository::Committing#commit.
+```
+
+## Related skills
+
+- [Facade Test Conventions](../facade-test-conventions/SKILL.md) — unit and
+  integration test conventions for facade methods (load when scaffolding or
+  reviewing tests)
+- [Facade YARD Documentation](../facade-yard-documentation/SKILL.md) — facade-specific
+  YARD rules for module-level and method-level docs
+- [Extract Facade from Base/Lib](../extract-facade-from-base-lib/SKILL.md) — when a
+  new facade method is migrated from `Git::Base` or `Git::Lib`, the extraction
+  workflow drives this skill in scaffold/update mode
+- [Command Implementation](../command-implementation/SKILL.md) — the underlying
+  `Git::Commands::*` classes a facade method calls. Scaffold any missing command
+  class first.
+- [YARD Documentation](../yard-documentation/SKILL.md) — baseline YARD formatting
+  rules
+- [RSpec Unit Testing Standards](../rspec-unit-testing-standards/SKILL.md) — baseline
+  RSpec rules
+- [Project Context](../project-context/SKILL.md) — three-layer architecture overview
+
+## Input
+
+The user provides:
+
+1. **Method name** — the public Ruby method name (e.g. `add`, `branches_all`,
+   `commit`).
+2. **Git operation(s)** — which `Git::Commands::*` class(es) the method orchestrates.
+   If the relevant command class does not exist yet, scaffold it first via
+   [Command Implementation](../command-implementation/SKILL.md).
+3. **Optional context** — the source `Git::Lib` / `Git::Base` method when migrating
+   (handled by [Extract Facade from Base/Lib](../extract-facade-from-base-lib/SKILL.md)).
+
+> **Note:** `Git::Repository` is intentionally empty during early phases of the
+> redesign. Its `initialize(execution_context:)` constructor is introduced
+> alongside the first facade method extraction; subsequent extractions only
+> add new topic modules and `include` lines.
+
+The agent then gathers:
+
+### Existing facade source
+
+Read `lib/git/repository.rb` to see the `include Git::Repository::<Topic>` lines and
+which topic modules exist. List `lib/git/repository/` to see all current topic
+modules and the facade methods they already define.
+
+Skip when scaffolding into a brand-new topic module.
+
+### Existing facade tests
+
+Read `spec/unit/git/repository/<topic>_spec.rb` and
+`spec/integration/git/repository/<topic>_spec.rb` (if present). Use as supplemental
+evidence of the existing test style before extending or reviewing.
+
+### Underlying command class(es)
+
+Read `lib/git/commands/<command>.rb` for each command the facade method calls.
+The command's `arguments do` block defines the option keys the facade may forward,
+and the YARD `@!method call` block documents what each option does. The facade must
+not pass option keys the command does not declare.
+
+### Underlying parsers (if any)
+
+Read `lib/git/parsers/<parser>.rb` for any parser the facade uses to transform
+command stdout into structured data.
+
+## Reference
+
+See [REFERENCE.md](REFERENCE.md) for the full reference covering:
+
+- Files to generate
+- Topic module selection (existing modules + decision rules for creating a new module)
+- Designing a facade method (return type, signature, body shape)
+- Topic module skeleton (file layout)
+- The five facade responsibilities as a checklist
+- Argument pre-processing patterns (path normalization, option whitelisting via
+  `SharedPrivate.assert_valid_opts!` + `private_constant`,
+  deprecation handling, defaults)
+- Internal helpers and encapsulation (sibling `module_function` modules under
+  `lib/git/repository/` instead of private methods on `Git::Repository`;
+  bare-noun naming; growth path from `SharedPrivate` to responsibility-named
+  modules)
+- When to call multiple commands (orchestration sequences)
+- When to use a parser vs. raw stdout
+- When to use a result-class factory method
+- Common failures (one-line delegation when orchestration is needed; leaking
+  command-class types into the public API; bypassing the execution context;
+  hardcoding policy options the caller cannot override)
+
+Subagents load REFERENCE.md directly during the workflow steps that need it.
+
+## Workflow
+
+This skill supports three modes. Determine which mode applies before starting:
+
+- **Scaffold** — adding a new facade method (and possibly a new topic module).
+  Follow all steps.
+- **Update** — modifying an existing facade method (e.g. adding a new option to
+  forward). Skip step 2 (module selection); steps 3a–3c are extending existing files
+  rather than creating them.
+- **Review** — auditing an existing facade method (no changes). Follow all steps but
+  produce findings instead of code.
+
+1. **Gather input** — collect the method name, target git operation(s), and any
+   migration source per [Input](#input). Read the underlying command class(es) and
+   parser(s) the method will call.
+
+2. **Choose the topic module** — load
+   [REFERENCE.md](REFERENCE.md) and apply [Topic module
+   selection](REFERENCE.md#topic-module-selection):
+
+   - Prefer extending an existing module under `lib/git/repository/`.
+   - Create a new module only when the topic is recognizable — preferably
+     matching a git-scm category (<https://git-scm.com/docs>) — and the methods
+     would be awkward to place in any existing module. The deciding factor is
+     topic fit, not method count; a single method that is genuinely distinct
+     can start its own module.
+   - New module names follow the two-tier convention: gerund (`Staging`, `Logging`,
+     `Diffing`) for single-action modules; `Noun + Operations` (`RemoteOperations`,
+     `ObjectOperations`) for mixed-bag modules. See
+     [REFERENCE.md §Naming a new topic module](REFERENCE.md#naming-a-new-topic-module).
+
+3. **For the facade method**, repeat steps 3a–3e:
+
+   a. **Scaffold the facade method (subagent)** *(scaffold/update modes only)* —
+      delegate to a subagent: load [REFERENCE.md](REFERENCE.md) and the
+      [Facade YARD Documentation](../facade-yard-documentation/SKILL.md) skill,
+      then create or extend `lib/git/repository/<topic>.rb` using the [Designing
+      a facade method](REFERENCE.md#designing-a-facade-method) section and
+      [Topic module skeleton](REFERENCE.md#topic-module-skeleton). For new topic
+      modules, also add the `require` and `include` lines to
+      `lib/git/repository.rb`.
+
+   Steps 3b and 3c may run **in parallel** (they produce independent files).
+
+   b. **Scaffold unit tests (subagent)** *(scaffold/update modes only)* — delegate
+      to a subagent: load **[Facade Test
+      Conventions](../facade-test-conventions/SKILL.md)** (which loads [RSpec Unit
+      Testing Standards](../rspec-unit-testing-standards/SKILL.md)), then create or
+      extend `spec/unit/git/repository/<topic>_spec.rb` following the unit
+      conventions (stub `Git::Commands::*` and `Git::Parsers::*` via
+      `instance_double`; assert delegation contracts; cover each pre-processing
+      branch).
+
+   c. **Scaffold integration tests (subagent)** *(scaffold/update modes only)* —
+      delegate to a subagent: load **[Facade Test
+      Conventions](../facade-test-conventions/SKILL.md)**, then create or extend
+      `spec/integration/git/repository/<topic>_spec.rb` following the integration
+      conventions (real git in a temp repository; assert end-to-end Ruby return
+      value, not intermediate command results). Skip integration tests for true
+      one-line delegators that add no orchestration on top of the underlying
+      command — the command's own integration tests already cover that path.
+
+   Steps 3d and 3e may run **in parallel** (they review independent file sets).
+
+   d. **Review Facade Tests (subagent)** — delegate to a subagent: load and apply
+      **[Facade Test Conventions](../facade-test-conventions/SKILL.md)** against the
+      unit and integration spec files. In *scaffold/update* modes, fix all findings
+      and repeat until clean. In *review* mode, record findings only.
+
+   e. **Review YARD Documentation (subagent)** — delegate to a subagent: load and
+      apply **[Facade YARD Documentation](../facade-yard-documentation/SKILL.md)**
+      against the topic module file. In *scaffold/update* modes, fix all findings
+      and repeat until clean. In *review* mode, record findings only.
+
+4. **Review facade shape and orchestration** — load
+   [REFERENCE.md](REFERENCE.md) and verify against the [Five facade
+   responsibilities checklist](REFERENCE.md#the-five-facade-responsibilities-checklist),
+   the [Designing a facade method](REFERENCE.md#designing-a-facade-method) section, and
+   [Common failures](REFERENCE.md#common-failures). Confirm the method:
+
+   - delegates to a `Git::Commands::*` class via `@execution_context` (never
+     constructs commands with `self` or builds CLI argv directly)
+   - does not return a `Git::CommandLineResult` from the public contract unless
+     that is the documented return type for the entire topic module
+   - whitelists forwarded options when the caller's hash is opaque
+     (per-method `<METHOD>_ALLOWED_OPTS` constant +
+     `SharedPrivate.assert_valid_opts!(allowed, **)` — do **not**
+     also `slice`; see [Option
+     whitelisting](REFERENCE.md#option-whitelisting-preventing-api-expansion))
+   - places each `<METHOD>_ALLOWED_OPTS` constant **immediately before** the
+     method that uses it (not grouped at the top of the module)
+   - handles defaults and deprecations explicitly, not by relying on command
+     internals
+   - is explicitly classified as `legacy-contract` (legacy predecessor exists)
+     or `5.x-native` (new facade API), and signature shape matches that
+     classification
+   - has tests that verify call-shape compatibility when classification is
+     `legacy-contract` (positional hash and/or keyword-arg / `**opts` forms where required)
+
+5. **Run quality gates** — discover the prerequisite tasks for `default:parallel`
+   and run them sequentially, fixing failures before advancing:
+
+   ```bash
+   bundle exec ruby -e "require 'rake'; load 'Rakefile'; puts Rake::Task['default:parallel'].prerequisites"
+   ```
+
+   Run each listed task **individually** in order via `bundle exec rake <task>`
+   (one task per invocation). On failure, fix the issue and re-run that same task.
+   Continue until every task passes on its first attempt with no fixes needed.
+
+## Output
+
+For **scaffold** and **update** modes, produce:
+
+1. **Topic module** — `lib/git/repository/<topic>.rb` (created or extended)
+2. **Facade wiring** — `lib/git/repository.rb` updated with `require` and `include`
+   when a new topic module was created
+3. **Unit tests** — `spec/unit/git/repository/<topic>_spec.rb`
+4. **Integration tests** — `spec/integration/git/repository/<topic>_spec.rb`
+   (omit only for true one-line delegators)
+5. **All quality gates pass** — rspec, minitest, rubocop, and yard all green
+
+For **review** mode, produce:
+
+| Check | Status | Issue |
+| --- | --- | --- |
+| Topic module placement | Pass/Fail | ... |
+| Orchestration via `@execution_context` | Pass/Fail | ... |
+| Argument pre-processing complete | Pass/Fail | ... |
+| Option whitelisting (where required) | Pass/Fail | ... |
+| `*_ALLOWED_OPTS` placed immediately before its method | Pass/Fail | ... |
+| Signature classification documented | Pass/Fail | ... |
+| Signature shape matches classification | Pass/Fail | ... |
+| Return value matches documented contract | Pass/Fail | ... |
+| Parser/result-class wiring correct | Pass/Fail | ... |
+| YARD docs complete | Pass/Fail | ... |
+| Unit + integration coverage | Pass/Fail | ... |
+
+Then list required fixes.
+> **Branch workflow:** Implement scaffolding or updates on a feature branch.
+> Never commit or push directly to `main` — open a pull request when changes
+> are ready to merge.

data/.github/skills/facade-test-conventions/SKILL.md

@@ -0,0 +1,394 @@
+---
+name: facade-test-conventions
+description: "Conventions for writing and reviewing unit and integration tests for Git::Repository facade methods (modules under lib/git/repository/). Use when scaffolding new facade tests or auditing existing ones in spec/unit/git/repository/ and spec/integration/git/repository/."
+---
+
+# Facade Test Conventions
+
+Conventions for writing and reviewing unit and integration tests for facade
+methods on `Git::Repository::*` modules.
+
+## Contents
+
+- [How to use this skill](#how-to-use-this-skill)
+- [Related skills](#related-skills)
+- [Input](#input)
+- [Reference](#reference)
+  - [Unit tests](#unit-tests)
+    - [Setup pattern](#setup-pattern)
+    - [Cover these cases](#cover-these-cases)
+    - [Expectations for command invocation](#expectations-for-command-invocation)
+    - [What not to test](#what-not-to-test)
+    - [Unit test grouping](#unit-test-grouping)
+  - [Integration tests](#integration-tests)
+    - [When to write integration tests](#when-to-write-integration-tests)
+    - [When to skip integration tests](#when-to-skip-integration-tests)
+    - [Integration test grouping](#integration-test-grouping)
+    - [What integration tests assert](#what-integration-tests-assert)
+    - [What integration tests do not assert](#what-integration-tests-do-not-assert)
+- [Workflow](#workflow)
+- [Output](#output)
+  - [When writing new facade tests](#when-writing-new-facade-tests)
+  - [When reviewing existing facade tests](#when-reviewing-existing-facade-tests)
+
+## How to use this skill
+
+Attach this file to your Copilot Chat context, then invoke with the spec file(s)
+to write or review. Include the corresponding facade module for context. Examples:
+
+```text
+Using the Facade Test Conventions skill, scaffold tests for Git::Repository::Staging.
+```
+
+```text
+Facade Test Conventions review: spec/unit/git/repository/committing_spec.rb.
+```
+
+## Related skills
+
+- [RSpec Unit Testing Standards](../rspec-unit-testing-standards/SKILL.md) — baseline
+  RSpec rules that govern all unit test structure, naming, setup, stubbing, and
+  coverage; this skill adds facade-specific conventions on top
+- [Facade Implementation](../facade-implementation/SKILL.md) — facade module
+  structure and orchestration patterns
+- [Facade YARD Documentation](../facade-yard-documentation/SKILL.md) — YARD docs
+  for facade modules and methods
+- [Command Test Conventions](../command-test-conventions/SKILL.md) — sibling skill
+  that tests the underlying `Git::Commands::*` classes the facade calls
+
+## Input
+
+The invocation needs the unit and/or integration spec file(s) to review. Including
+the corresponding facade module file (`lib/git/repository/<topic>.rb`) provides
+useful context for verifying delegation contracts and option forwarding.
+
+**Prerequisite:** Read the **entire** [RSpec Unit Testing
+Standards](../rspec-unit-testing-standards/SKILL.md) skill (line 1 through EOF)
+before beginning. It defines the baseline Rules 1–28 that this skill extends.
+
+## Reference
+
+### Unit tests
+
+Facade unit tests verify the **orchestration contract** between the facade method
+and the components it calls (`Git::Commands::*`, `Git::Parsers::*`,
+`Git::ExecutionContext::Repository`). They do not run real git.
+
+The collaborators (commands, parsers) are stubbed via `instance_double`. The unit
+test asserts:
+
+1. The facade constructs each command class with the injected
+   `@execution_context`.
+2. Each command's `#call` is invoked with the expected positional and keyword
+   arguments (verifying argument pre-processing).
+3. For multi-command sequences, the calls happen in the documented order.
+4. The parser/result-class is invoked with the command's stdout (when applicable).
+5. The facade returns the value its public contract documents.
+
+#### Setup pattern
+
+```ruby
+RSpec.describe Git::Repository::Staging do
+  let(:execution_context) { instance_double(Git::ExecutionContext::Repository) }
+  let(:described_instance) { Git::Repository.new(execution_context: execution_context) }
+  let(:command_result) { instance_double(Git::CommandLineResult, stdout: '') }
+  let(:add_command) { instance_double(Git::Commands::Add) }
+  let(:add_result) { command_result }
+
+  before do
+    allow(Git::Commands::Add).to receive(:new).with(execution_context).and_return(add_command)
+  end
+
+  describe '#add' do
+    # ...
+  end
+end
+```
+
+The shared `command_result` `let` provides a default empty-stdout result; each
+per-command alias (`add_result`, `branch_list_result`, ...) lets individual
+tests override stdout in isolation — e.g.
+`let(:add_result) { instance_double(Git::CommandLineResult, stdout: 'fixture output') }`
+in a nested `context` — without affecting other tests in the file.
+
+Setup invariants:
+
+- The subject is an instance of `Git::Repository`, **not** the module itself.
+  Modules are mixed into the class; tests must exercise the class to reflect
+  real call sites.
+- `execution_context` is an `instance_double(Git::ExecutionContext::Repository)`
+  — never a `double('ExecutionContext')` and never a real context.
+- Each command class is stubbed with `allow(Klass).to receive(:new).with(execution_context).and_return(...)`
+  so the facade's command construction (with the right execution context) is
+  verified by the stub.
+
+#### Cover these cases
+
+- **Default invocation** — facade called with no arguments (or only required
+  positional args) delegates with the documented defaults. Assert the return
+  value once per facade method to verify pass-through.
+- **Each positional argument variation** — single value, array, nil where
+  applicable.
+- **Each option the facade exposes** — including aliases, deprecated keys, and
+  policy defaults the facade applies (`no_edit: true`, etc.).
+- **Multi-command sequences** — when the facade calls more than one command,
+  use `expect ... receive(:call).with(...).ordered` to assert ordering and
+  intermediate-result wiring.
+- **Parser invocation** — when the facade uses a `Git::Parsers::*` class,
+  stub the parser and assert it is called with the command's stdout. Assert the
+  facade returns what the parser returned.
+- **Raw `CommandLineResult` return** — when the facade's contract is to
+  return the command's `Git::CommandLineResult` directly (not `.stdout` and
+  not a parser output), assert `eq(<command>_result)` to verify pass-through.
+- **Option whitelisting** — when the facade defines a `<METHOD>_ALLOWED_OPTS`
+  constant and calls `Git::Repository::Internal.assert_valid_opts!`, test that
+  an unknown key raises `ArgumentError` and a known key is forwarded.
+- **Deprecation handling** — when the facade rewrites or warns on deprecated
+  keys, test that the deprecation warning is emitted and the new key is
+  forwarded.
+- **Signature compatibility call shapes** — when a facade method preserves a
+  legacy public contract, include tests for each call shape the 4.x public API
+  used (positional hash and/or keyword-arg / `**opts` where applicable).
+
+#### Expectations for command invocation
+
+Use the standard rspec-mocks form (no command-specific helper exists for the
+facade layer):
+
+```ruby
+it 'delegates to Git::Commands::Add#call with the given path' do
+  expect(add_command).to receive(:call).with('path/to/file.rb').and_return(add_result)
+  described_instance.add('path/to/file.rb')
+end
+```
+
+For command + parser orchestration (single command whose stdout is fed to a
+parser), use `.ordered` to assert the call sequence:
+
+```ruby
+it 'lists branches then parses the output' do
+  expect(branch_list_command).to(
+    receive(:call)
+        .with(all: true, format: Git::Parsers::Branch::FORMAT_STRING)
+        .and_return(branch_list_result)
+        .ordered
+  )
+
+  expect(Git::Parsers::Branch).to(
+    receive(:parse_list)
+        .with(branch_list_result.stdout)
+        .and_return(parsed_branches)
+        .ordered
+  )
+
+  expect(described_instance.branches_all).to eq(parsed_branches)
+end
+```
+
+For genuinely multi-command orchestration (the facade calls more than one
+command), chain `.ordered` across each command's `#call`, wiring intermediate
+results through as needed:
+
+```ruby
+it 'saves the stash then lists stashes' do
+  expect(stash_save_command).to(
+    receive(:call).with(message: 'wip').and_return(stash_save_result).ordered
+  )
+
+  expect(stash_list_command).to(
+    receive(:call).and_return(stash_list_result).ordered
+  )
+
+  expect(described_instance.stash_save_and_list(message: 'wip')).to eq(parsed_stashes)
+end
+```
+
+#### What not to test
+
+- **Command argv building.** That is the command class's contract and is covered
+  by `spec/unit/git/commands/<command>_spec.rb`. The facade unit test should
+  stub `#call` and assert the keyword arguments the facade passes — not assert
+  on the CLI tokens that reach git.
+- **Parser internals.** Stub the parser class method and assert the facade calls
+  it with the right input. Parser parsing is covered by `spec/unit/git/parsers/`.
+- **Real command execution.** Facade unit tests must not exercise
+  `Git::ExecutionContext::Repository` for real. Use `instance_double`.
+- **Multiple input strings exercising the same code path** — one test per
+  argument type is sufficient (string vs. array vs. nil), not one per value.
+- **`#initialize` of the facade module.** The module is mixed into
+  `Git::Repository`; constructor coverage belongs to `repository_spec.rb`.
+
+#### Unit test grouping
+
+One `describe '#<method_name>'` block per facade method. Inside, use flat
+`context` blocks per argument variation. Optional sections at the end (in order)
+when present:
+
+- `context 'option whitelisting'` —
+  `Git::Repository::Internal.assert_valid_opts!` raises on unknown keys and
+  forwards known keys unchanged (no `slice` — the assertion is the only
+  enforcement mechanism)
+- `context 'deprecation handling'` — `Git::Deprecation.warn` assertions and
+  key-rewrite tests
+- `context 'input validation'` — `ArgumentError` raised by the facade itself
+  (not by the command)
+- `context 'signature compatibility'` — for legacy-contract methods, exercises
+  required call shapes (legacy positional hash and/or keyword-arg / `**opts` forms)
+
+The exit code section that command specs use does **not** apply to facade specs
+— exit-status handling is the command's concern; the facade's tests assume the
+command either returns a result or raises.
+
+### Integration tests
+
+Facade integration tests run real git in a temp repository and verify the
+**end-to-end Ruby return value** of the facade method.
+
+Each integration spec file tests **one facade module** (one
+`spec/integration/git/repository/<topic>_spec.rb`). Inside, group by facade
+method.
+
+#### When to write integration tests
+
+Facade integration tests are the **exception, not the default**. Most facade
+behavior is already covered end-to-end by the underlying command's own
+integration tests; re-running real git through the facade re-exercises the
+same code path without adding signal.
+
+Write a facade integration test only when the facade adds behavior that is
+**not** exercised by any single command's integration tests:
+
+- **Multi-command orchestration** — the facade calls more than one command
+  and the integration test confirms the documented end-to-end value emerges
+  from the sequence against real git.
+- **Facade-owned post-processing of real git output** — the facade itself
+  (not the command) parses, aggregates, or transforms raw command output
+  before returning. A real git invocation proves the post-processing handles
+  actual output rather than a mocked string.
+
+#### When to skip integration tests
+
+Skip for everything else, including:
+
+- **One-line delegators** that pass arguments through to a single command
+  with no pre/post-processing (e.g. `Git::Repository::Staging#add`,
+  `#reset`).
+- **Single-command facade methods that delegate parsing to a parser or
+  result-class factory** — the command's own integration test already
+  exercises that command + parser against real git.
+- **Argument pre-processing** (path normalization, deprecation key rewrites,
+  option whitelisting) — these are pure-Ruby transforms with no git
+  involvement; unit tests prove them and real git adds no signal.
+- **Error-path assertions** (`raise_error(Git::FailedError)`) — these test
+  the command's error wrapping, not the facade.
+
+When skipping, document why with a code comment in the spec file or a `#`
+header in `spec/integration/git/repository/<topic>_spec.rb` explaining which
+methods are covered exclusively by command integration tests.
+
+#### Integration test grouping
+
+Mirror the [Command Test Conventions](../command-test-conventions/SKILL.md)
+integration grouping. Use a multi-command or post-processing facade method —
+single-command delegators do not warrant integration tests (see [When to skip
+integration tests](#when-to-skip-integration-tests)):
+
+The shared context (e.g. `'in an empty repository'`) provides `repo` and
+`repo_dir` helpers. Facade integration specs must override `execution_context`
+to a `Git::ExecutionContext::Repository` (the shared context's default is
+`repo.lib`, a `Git::Lib`). Stage any required repository state in a `before`
+block inside the spec itself.
+
+```ruby
+RSpec.describe Git::Repository::Stashing, :integration do
+  include_context 'in an empty repository' # provides repo and repo_dir helpers
+
+  let(:execution_context) { Git::ExecutionContext::Repository.from_base(repo) }
+  let(:described_instance) { Git::Repository.new(execution_context: execution_context) }
+
+  before do
+    write_file('README.md', 'initial')
+    repo.add('README.md')
+    repo.commit('Initial commit')
+    write_file('README.md', 'work in progress')
+    repo.add('README.md')
+  end
+
+  describe '#stash_save_and_list' do
+    it 'returns the new stash entry after saving' do
+      result = described_instance.stash_save_and_list(message: 'wip')
+      expect(result).to all(be_a(Git::Stash))
+      expect(result.first.message).to include('wip')
+    end
+  end
+end
+```
+
+One `context 'when the command succeeds'` block (or just `it` blocks directly
+under `describe`) per facade method, with one or more variations that exercise
+the orchestration sequence or post-processing. Do **not** add a `context 'when
+the command fails'` block — error wrapping is the command's concern and is
+covered by command integration tests.
+
+#### What integration tests assert
+
+- The Ruby return value's **structure and key fields** (e.g., classes,
+  required attributes, presence of expected entries).
+- Multi-command orchestration produces the documented end-to-end value, not
+  intermediate command results.
+- For signature-compatibility behavior that is user-visible at runtime,
+  integration coverage may assert that legacy call shapes are accepted.
+
+#### Review checks for signature policy
+
+When reviewing existing facade tests, add these checks:
+
+1. If the method is `legacy-contract`, unit tests cover required call shapes.
+2. Test expectations validate public contract behavior, not only command
+   delegation internals.
+
+#### What integration tests do not assert
+
+- Specific CLI tokens reaching git (covered by command unit tests).
+- Specific git output formatting (testing git, not the facade).
+- Edge cases that vary between git versions in immaterial ways. Anchor
+  assertions on stable inputs (paths, ref names) the test controls — not on git
+  message phrasing.
+
+## Workflow
+
+1. Load the [RSpec Unit Testing
+   Standards](../rspec-unit-testing-standards/SKILL.md) skill (line 1 through
+   EOF).
+2. Read the spec file(s) under review and the corresponding facade module
+   (`lib/git/repository/<topic>.rb`) plus the underlying `Git::Commands::*` and
+   `Git::Parsers::*` files the facade calls.
+3. Audit each spec against the rules in [Reference](#reference), checking unit
+   and integration tests separately.
+4. Produce the [Output](#output).
+
+## Output
+
+### When writing new facade tests
+
+Produce the unit and (when applicable) integration spec files following the
+patterns above. Then self-verify by running every checklist item in the
+[Reference](#reference) section against your output.
+
+### When reviewing existing facade tests
+
+Provide:
+
+1. issue table
+
+   | Check | Status | Issue |
+   | --- | --- | --- |
+
+2. corrected snippets for failing checks
+
+3. **Self-verify before concluding** — re-run the reference against your proposed
+   snippets until all checks pass.
+
+> **Branch workflow:** Implement any new or updated tests on a feature branch.
+> Never commit or push directly to `main` — open a pull request when changes are
+> ready to merge.