git 5.0.0.beta.1 → 5.0.0.beta.2

data/redesign/3_architecture_implementation.md

@@ -9,11 +9,12 @@ risk and allows for a gradual, controlled migration to the new architecture.
   - [Facade Modules Completed](#facade-modules-completed)
     - [Facade module naming convention](#facade-module-naming-convention)
   - [Next Task](#next-task)
-    - [Phase 3 Public Interface Completion](#phase-3-public-interface-completion)
+    - [D2 / Phase 4 is the remaining redesign step](#d2--phase-4-is-the-remaining-redesign-step)
+    - [Phase 3 Overview](#phase-3-overview)
     - [Workstream A — Fill facade coverage gaps](#workstream-a--fill-facade-coverage-gaps)
     - [Workstream B — C0: Redirect `Git::Base` factory methods to `facade_repository`](#workstream-b--c0-redirect-gitbase-factory-methods-to-facade_repository)
     - [Workstream C — C1: Prepare and flip top-level entry points to return `Git::Repository`](#workstream-c--c1-prepare-and-flip-top-level-entry-points-to-return-gitrepository)
-    - [Workstream D — C2+C3: Remove compatibility bridges](#workstream-d--c2c3-remove-compatibility-bridges)
+    - [Workstream D — C3: Remove compatibility fallbacks](#workstream-d--c3-remove-compatibility-fallbacks)
     - [Workstream E — Migrate or deprecate instance helper methods](#workstream-e--migrate-or-deprecate-instance-helper-methods)
     - [Workstream F — `Git` module utility methods still using `Git::Lib` directly](#workstream-f--git-module-utility-methods-still-using-gitlib-directly)
     - [Phase 3 dependency order](#phase-3-dependency-order)
@@ -31,6 +32,10 @@ risk and allows for a gradual, controlled migration to the new architecture.
     - [⏳ Commands To Migrate](#-commands-to-migrate)
 - [Phase 3: Refactoring the Public Interface](#phase-3-refactoring-the-public-interface)
 - [Phase 4: Final Cleanup and Release Preparation](#phase-4-final-cleanup-and-release-preparation)
+  - [Phase 4 step graph](#phase-4-step-graph)
+    - [Step A — Remove old code](#step-a--remove-old-code)
+    - [Step B — Finalize test suite](#step-b--finalize-test-suite)
+    - [Step C — Update documentation](#step-c--update-documentation)
 
 ## Progress Tracker
 
@@ -38,44 +43,68 @@ risk and allows for a gradual, controlled migration to the new architecture.
 | ----- | ------ | ----------- | :--------------: | :--------------: |
 | Phase 1 | ✅ Complete | Foundation and scaffolding | 5% | 100% |
 | Phase 2 | ✅ Complete | Migrating commands (all checklist items done) | 40% | 100% |
-| Phase 3 | ⏳ In Progress | Refactoring public interface — see [Facade Modules Completed](#facade-modules-completed) and [Facade coverage checklist](#facade-coverage-checklist) | 45% | 50% |
+| Phase 3 | ✅ Complete | Refactoring public interface — see [Facade Modules Completed](#facade-modules-completed) and [Facade coverage checklist](#facade-coverage-checklist) | 45% | 100% |
 | Phase 4 | 🔲 Not Started | Final cleanup and release | 10% | 0% |
-| **TOTAL** | -- | -- | **100%** | **68%** |
+| **TOTAL** | -- | -- | **100%** | **90%** |
 
 ### Facade Modules Completed
 
 | Module | File | Included in `Git::Repository` | `Git::Base` delegates |
 | ------ | ---- | ------------------------------ | --------------------- |
-| `Git::Repository::Staging` | `lib/git/repository/staging.rb` | ✅ | `add`, `reset`, `rm`, `clean`, `ignored_files` |
+| `Git::Repository::Staging` | `lib/git/repository/staging.rb` | ✅ | `add`, `reset`, `reset_hard`, `apply`, `apply_mail`, `read_tree`, `rm`, `mv`, `clean`, `ignored_files` |
 | `Git::Repository::Committing` | `lib/git/repository/committing.rb` | ✅ | `commit`, `commit_all`, `write_tree`; `commit_tree` and `write_and_commit_tree` wrap the SHA result in `Git::Object::Commit.new(self, ...)` |
-| `Git::Repository::Branching` | `lib/git/repository/branching.rb` | ✅ | `checkout`, `checkout_file`, `checkout_index`, `current_branch`, `local_branch?`, `remote_branch?`, `branch?`, `branch_delete`, `branch_new`, `branch_contains`, `branches_all`, `update_ref` |
+| `Git::Repository::Branching` | `lib/git/repository/branching.rb` | ✅ | `checkout`, `checkout_file`, `checkout_index`, `current_branch`, `current_branch_state`, `local_branch?`, `remote_branch?`, `branch?`, `branch`, `branches`, `branch_delete`, `branch_new`, `change_head_branch`, `branch_contains`, `branches_all`, `update_ref` |
+| `Git::Repository::ContextHelpers` | `lib/git/repository/context_helpers.rb` | ✅ | `chdir`, `with_index`, `with_temp_index`, `with_working`, `with_temp_working`, `set_index`, `set_working` |
 | `Git::Repository::Merging` | `lib/git/repository/merging.rb` | ✅ | `merge`, `revert`, `each_conflict`; `merge_base` wraps the returned SHA strings in `Git::Object::Commit.new(self, ...)` instances |
-| `Git::Repository::RemoteOperations` | `lib/git/repository/remote_operations.rb` | ✅ | `fetch`, `pull`, `push`, `add_remote`, `remove_remote`, `config_remote`, `remotes`, `set_remote_url`, `remote_set_branches` |
-| `Git::Repository::Stashing` | `lib/git/repository/stashing.rb` | ✅ | `stash_save`, `stash_apply`, `stash_clear`, `stashes_all` |
-| `Git::Repository::Diffing` | `lib/git/repository/diffing.rb` | ✅ | `diff_path_status`, `diff_name_status`, `diff_full` |
-| `Git::Repository::Inspecting` | `lib/git/repository/inspecting.rb` | ✅ | `show`, `fsck` |
-| `Git::Repository::ObjectOperations` | `lib/git/repository/object_operations.rb` | ✅ | `rev_parse`, `tree_depth`, `ls_tree`, `grep`, `archive`, `tags`, `add_tag`, `delete_tag` |
+| `Git::Repository::RemoteOperations` | `lib/git/repository/remote_operations.rb` | ✅ | `fetch`, `pull`, `push`, `remote_add` (alias: `add_remote`), `remote_remove` (alias: `remove_remote`), `remote_set_url` (alias: `set_remote_url`), `config_remote`, `remote`, `remotes`, `ls_remote`, `remote_set_branches` |
+| `Git::Repository::Stashing` | `lib/git/repository/stashing.rb` | ✅ | `stash_list`, `stash_save`, `stash_apply`, `stash_clear`, `stashes_all` |
+| `Git::Repository::Diffing` | `lib/git/repository/diffing.rb` | ✅ | `diff_full`, `diff_numstat`, `diff_stats`, `diff`, `diff_path_status` (alias: `diff_name_status`), `diff_files`, `diff_index` |
+| `Git::Repository::Inspecting` | `lib/git/repository/inspecting.rb` | ✅ | `describe`, `show`, `fsck` |
 | `Git::Repository::Logging` | `lib/git/repository/logging.rb` | ✅ | `log`, `full_log_commits` |
-| `Git::Repository::StatusOperations` | `lib/git/repository/status_operations.rb` | ✅ | `ls_files`, `no_commits?` (renamed from `Git::Lib#empty?`), `untracked_files`, `status`; `Git::Base#ls_files` delegates to facade |
-| `Git::Repository::Configuring` | `lib/git/repository/configuring.rb` | ✅ | `config`; `Git::Base#config` delegates to facade |
+| `Git::Repository::Maintenance` | `lib/git/repository/maintenance.rb` | ✅ | `repack`, `gc` |
+| `Git::Repository::ObjectOperations` | `lib/git/repository/object_operations.rb` | ✅ | `cat_file_contents`, `cat_file_size`, `cat_file_type`, `cat_file_commit`, `cat_file_tag`, `rev_parse`, `tag_sha`, `full_tree`, `tree_depth`, `name_rev`, `ls_tree`, `grep`, `archive`, `gblob`, `gcommit`, `gtree`, `tag`, `object`, `tags`, `add_tag`, `delete_tag` |
+| `Git::Repository::StatusOperations` | `lib/git/repository/status_operations.rb` | ✅ | `ls_files`, `no_commits?` / `empty?`, `untracked_files`, `status` |
+| `Git::Repository::Configuring` | `lib/git/repository/configuring.rb` | ✅ | `config`, `config_get`, `config_list`, `config_set`, `global_config`, `global_config_get`, `global_config_list`, `global_config_set` |
 | `Git::Repository::WorktreeOperations` | `lib/git/repository/worktree_operations.rb` | ✅ | `worktrees_all`, `worktree_add`, `worktree_remove`, `worktree_prune`, `worktree`, `worktrees` |
 
 #### Facade module naming convention
 
-New topic modules follow a **two-tier** convention:
+New topic modules follow a **three-tier** convention:
 
 - **Gerund** (verb-ing) when a single action word clearly names the whole module:
-  `Staging`, `Committing`, `Branching`, `Merging`, `Logging`, `Diffing`, `Stashing`, `Configuring`.
+  `Staging`, `Committing`, `Branching`, `Merging`, `Logging`, `Diffing`, `Stashing`,
+  `Configuring`, `Inspecting`.
 - **Noun + `Operations`** when the module is a mixed bag of methods grouped by git
   concept rather than a single action: `RemoteOperations`, `ObjectOperations`,
   `StatusOperations`, `WorktreeOperations`.
+- **Descriptive utility names** for cross-cutting helpers or housekeeping APIs that
+  are not domain-object names: `ContextHelpers`, `Maintenance`.
 
 Do **not** use plain nouns that clash with existing domain-object class names
 such as `Branch`, `Diff`, `Log`, `Object`, `Remote`, `Status`, `Worktree`, etc.
 
 ### Next Task
 
-#### Phase 3 Public Interface Completion
+#### D2 / Phase 4 is the remaining redesign step
+
+F1 and F2 are both ✅ complete. All Phase 4 prerequisites are now satisfied, and
+the remaining unchecked redesign item is D2.
+
+Phase 4 (final cleanup and release — deleting `Git::Base`/`Git::Lib`) can now begin.
+The first cleanup PR should remove the `base_object` / `from_base` bridge in the
+same releasable change that deletes or retires `Git::Base`.
+The following are also required and are already ✅ complete:
+
+| Step | Status |
+| ---- | ------ |
+| C1c-2: public-API parity audit and remediation sweep | ✅ |
+| E: block-based helper/path-context methods migrated | ✅ |
+
+Steps C1d-1, C1d-2, and C1d-3 are ✅ complete (see their detail sections below for full specs).
+
+---
+
+#### Phase 3 Overview
 
 All 9 domain-object migrations are ✅ complete:
 
@@ -91,19 +120,10 @@ All 9 domain-object migrations are ✅ complete:
 | `Git::Branches` | [PR #1356](https://github.com/ruby-git/ruby-git/pull/1356), [PR #1357](https://github.com/ruby-git/ruby-git/pull/1357), [PR #1358](https://github.com/ruby-git/ruby-git/pull/1358), [PR #1359](https://github.com/ruby-git/ruby-git/pull/1359) |
 | `Git::Worktree` + `Git::Worktrees` | — |
 
-The remaining work splits into six workstreams:
-
-- Workstream A adds missing `Git::Repository` facade methods
-- B wires `Git::Base` factory methods to call the facade
-- C moves construction/global state and flips the top-level entry points
-- D removes compatibility bridges
-- E migrates helper/path-context methods
-- F removes the last `Git` module utility calls that still route through `Git::Lib`
-
-The required `Git::Commands::*` classes already exist (`Clone`, `LsRemote`,
-`ConfigOptionSyntax::*`, `Rm`, `Clean`, `Show`, `Fsck`, etc.). The remaining work is
-facade/adapter wiring, parser reuse, and public-API parity decisions — not new
-command-layer scaffolding. The full scope is defined in Workstreams A–F below.
+The work was organized into six workstreams (A–F). All workstreams that are
+prerequisites for C1d are now ✅ complete. F1 and F2 are both ✅ complete — F2
+moved the remaining `Git` module utility methods off `Git::Lib`. Phase 4 is
+ready to proceed.
 
 **Sequencing** (see [Phase 3 dependency order](#phase-3-dependency-order) for the
 reasoning behind each edge):
@@ -121,8 +141,8 @@ graph LR
     C1a-2 --> C1c-2
     C1b --> C1c-2
     C1c-1 --> C1c-2
-    C1c-2 --> C1d
-    C1d --> D1 --> Phase4["Phase 4"]
+    C1c-2 --> C1d-1
+    C1d-1 --> C1d-2 --> C1d-3 --> D1 --> Phase4["Phase 4"]
     D2 --> Phase4
     F1 --> Phase4
     F2 --> Phase4
@@ -177,9 +197,10 @@ These are read-only repository inspection operations that don't fit an existing
 
 Files touched: `lib/git/repository/inspecting.rb` (new), `lib/git/repository.rb` (add `include Git::Repository::Inspecting`), `spec/unit/git/repository/inspecting_spec.rb` (new), `lib/git/base.rb`
 
-**Not covered by A1–A4:** lower-level public methods such as `describe`, `repack`,
-`gc`, `apply`, `apply_mail`, `read_tree`, and `cat_file` are handled by the C1c-2
-public-API parity audit before `Git.open` starts returning `Git::Repository`.
+**Later covered by C1c-2:** lower-level public methods such as `describe`,
+`repack`, `gc`, `apply`, `apply_mail`, `read_tree`, and `cat_file_*` were
+subsequently migrated into `Inspecting`, `Maintenance`, `Staging`, and
+`ObjectOperations` before `Git.open` started returning `Git::Repository`.
 
 ---
 
@@ -228,7 +249,7 @@ This workstream is intentionally split into two PRs because the path/accessor
 state work is independent of the clone/init work, and combining them would make a
 very large PR.
 
-**Step C1a-1 — Path state, accessors, and `.open`/`.bare` factories**
+**Step C1a-1 — Path state, accessors, and `.open`/`.bare` factories** ✅
 
 | `Git::Base` class method | Target |
 | --- | --- |
@@ -242,7 +263,7 @@ must also expose the path/accessor surface currently provided by `Git::Base`: `d
 
 Files touched: `lib/git/repository.rb`, `lib/git/base.rb`
 
-**Step C1a-2 — `.clone` and `.init` factories**
+**Step C1a-2 — `.clone` and `.init` factories** ✅
 
 | `Git::Base` / `Git` method | Target |
 | --- | --- |
@@ -259,7 +280,7 @@ Workstream F.
 
 Files touched: `lib/git/repository.rb`, `lib/git/base.rb`, `lib/git.rb`
 
-**Step C1b — Move global config singleton ownership off `Git::Base`**
+**Step C1b — Move global config singleton ownership off `Git::Base`** ✅
 
 `Git.configure` and `Git.config` both delegate to `Base.config`, which returns the
 `Git::Base`-owned `Git::Config` singleton. When `Git::Base` is deleted, these break.
@@ -286,7 +307,7 @@ documented as a v5 breaking change or already deprecated for removal. This audit
 the gate that prevents the entry-point flip from silently dropping public methods
 just because `Git::Base` still exists in the tree.
 
-**Step C1c-1 — Signature-compatibility guidance and process** ⬜
+**Step C1c-1 — Signature-compatibility guidance and process** ✅
 
 Update extraction and review skills to document the signature-compatibility
 classification policy (legacy-contract vs 5.x-native), parity-check requirements,
@@ -305,7 +326,7 @@ Files touched: `.github/skills/extract-facade-from-base-lib/SKILL.md`,
 
 Tracked as [Issue #1369](https://github.com/ruby-git/ruby-git/issues/1369).
 
-**Step C1c-2 — End-of-Phase-3 public-API parity audit and remediation sweep** ⬜
+**Step C1c-2 — End-of-Phase-3 public-API parity audit and remediation sweep** ✅
 
 Compare every public `Git::Base` method against `Git::Repository`; fix mismatches
 or explicitly record each as a documented v5 breaking change. No unclassified
@@ -317,7 +338,7 @@ Required audit buckets:
 | --- | --- |
 | Path/accessors | `dir`, `repo`, `index`, `repo_size` must exist on `Git::Repository` (C1a-1 owns this) |
 | Compatibility aliases/wrappers | `remove`, `revparse`, `diff_name_status`, `reset_hard`, `is_local_branch?`, `is_remote_branch?`, `is_branch?`, `checkout` must be migrated or intentionally removed with upgrade notes (`checkout` is called by `Git.export` on the `Git.clone` result) |
-| Low-level public methods | `describe`, `repack`, `gc`, `apply`, `apply_mail`, `read_tree`, `cat_file` must be migrated to topic modules or intentionally removed with upgrade notes |
+| Low-level public methods | Resolved in the current tree: `describe` → `Inspecting`; `repack`/`gc` → `Maintenance`; `apply`/`apply_mail`/`read_tree` → `Staging`; `cat_file_*` → `ObjectOperations`. Any intentional removals still require upgrade notes. |
 | Factory/domain-object returns | Confirm B plus A2/A3 cover `branch`, `branches`, `remote`, `remotes`, `tag`, `tags`, object factories, and tag create/delete return shapes |
 | Keyword-arg facades | For `legacy-contract` methods, preserve the exact 4.x call shape (including rare `**opts` signatures); for `5.x-native` methods, use `opts = {}` style for consistency |
 
@@ -326,15 +347,38 @@ Files touched: `lib/git/repository/*.rb` (topic modules for migrated methods),
 
 Tracked as [Issue #1370](https://github.com/ruby-git/ruby-git/issues/1370).
 
-**Step C1d — Update `lib/git.rb` entry points to return `Git::Repository`**
+##### Step C1d-1 — Flip entry points
 
 With C1a, C1b, C1c, A, B, and E in place, update `Git.open`, `Git.clone`,
 `Git.init`, and `Git.bare` in `lib/git.rb` to call `Git::Repository.*` and return
 `Git::Repository` directly, bypassing `Git::Base` entirely.
 
+**Prerequisite fix before landing C1d-1:** delete `spec/integration/git/lib/config_spec.rb`
+after confirming behavior coverage exists in `spec/integration/git/repository/configuring_spec.rb`.
+The `def lib = self` shim causes `subject(:lib) { repo.lib }` to return `Git::Repository` (self),
+which triggers deprecation warnings from every deprecated alias call (config_set, config_get,
+global_config_set, etc.) in that spec.
+
+##### Step C1d-2 — Eliminate internal `.lib` callers
+
+Clean up all `.lib` callers from tests while the silent `def lib = self` shim is still in
+place, then add `Git::Deprecation.behavior = :raise` to both test suites. See the phase table
+in the [Next Task](#next-task) section for the full per-phase breakdown.
+
+##### Step C1d-3 — Remove dead fallbacks and add deprecation warning
+
+- Add `diff_numstat` delegator to `Git::Base` (prerequisite: not currently defined there)
+- Remove dead `respond_to?` + `.lib` fallback branches from `lib/git/diff.rb`,
+  `lib/git/diff_stats.rb`, `lib/git/diff_path_status.rb`, `lib/git/status.rb`
+- Replace `def lib = self` in `lib/git/repository.rb` with a `Git::Deprecation.warn` body
+  (removal version: v6.0.0; returns `self`)
+- Remove `command_capturing`, `command_streaming`, and private `env_overrides` from
+  `lib/git/repository.rb` — these were added only to feed the silent shim
+- Add unit test asserting the deprecation warning and `self` return
+
 ---
 
-#### Workstream D — C2+C3: Remove compatibility bridges
+#### Workstream D — C3: Remove compatibility fallbacks
 
 ⚠️ These are v5-only cleanup steps. They are not 4.x-compatible and must be kept out
 of 4.x release candidates unless an explicit breaking-change decision has already
@@ -379,20 +423,6 @@ After D1, domain objects should assume their provider is `Git::Repository` (or a
 compatible object that implements the repository facade methods directly), not an
 object with a `.lib` escape hatch.
 
-##### Step D2 — Remove the `base_object` bridge
-
-⚠️ Do **not** ship D2 as a standalone PR while `Git::Base` remains functional.
-`Git::Base#facade_repository` currently depends on
-`Git::ExecutionContext::Repository.from_base(self)`, so deleting the bridge before
-deleting or retiring `Git::Base` would leave the tree unreleasable.
-
-D2 belongs in the Phase 4 old-code deletion PR (or in the same v5 cleanup PR that
-removes `Git::Base` as a usable public entry point):
-
-- Delete `attr_reader :base_object`
-- Remove `base_object:` from `#initialize` and body
-- Remove or convert `from_base` factory
-
 ---
 
 #### Workstream E — Migrate or deprecate instance helper methods
@@ -405,7 +435,7 @@ helpers would drop existing public `Git::Base` behavior.
 `Git::Repository`. They must either be migrated before `Git::Base` can be deleted,
 or explicitly deprecated with removal in v6.0. The recommended path is migration.
 
-**Step E — Migrate block-based helper/path-context methods to `Git::Repository`** ⬜
+**Step E — Migrate block-based helper/path-context methods to `Git::Repository`** ✅
 
 | `Git::Base` method | Proposed destination | Notes |
 | --- | --- | --- |
@@ -419,8 +449,8 @@ or explicitly deprecated with removal in v6.0. The recommended path is migration
 removed at the same time, since `with_index`/`with_working` depend on the same
 invalidation logic.
 
-Files touched: `lib/git/repository.rb` (or a new `Git::Repository::ContextHelpers`
-module), `lib/git/base.rb`, `spec/unit/git/repository/` (new or extended spec)
+Files touched: `lib/git/repository/context_helpers.rb`, `lib/git/base.rb`,
+`spec/unit/git/repository/` (new or extended spec)
 
 ---
 
@@ -434,7 +464,7 @@ Three `Git`-module-level methods bypass `Git::Repository` entirely and call
 non-`Git::Lib` adapter path using `Git::ExecutionContext::Global` plus existing
 parsing logic.
 
-**Step F1 — Move `Git.ls_remote` and `Git.default_branch` off `Git::Lib`** ⬜
+**Step F1 — Move `Git.ls_remote` and `Git.default_branch` off `Git::Lib`** ✅
 
 | `Git` module method | Current path | Required work |
 | --- | --- | --- |
@@ -449,7 +479,7 @@ use the same command class.
 Files touched: `lib/git.rb`, `lib/git/base.rb`, and parser/helper code extracted
 from `Git::Lib` as needed
 
-**Step F2 — Move `Git.global_config`, `#config`, and `#global_config` off `Git::Lib`** ⬜
+**Step F2 — Move `Git.global_config`, `#config`, and `#global_config` off `Git::Lib`** ✅
 
 | `Git` module method | Current path | Required work |
 | --- | --- | --- |
@@ -494,19 +524,15 @@ classified as a v5-only PR with upgrade-note coverage before it lands.
 | A4 | ✅ | Add `Inspecting#show` and `#fsck` | 4.x-compatible | `Git::Base#show` and `#fsck` remain behavior-compatible and delegate internally. |
 | B | ✅ | Redirect `Git::Base` domain-object factories | 4.x-compatible | Method signatures and return types stay the same; only the internal provider changes to `Git::Repository`. Split into object/tag factories and branch/remote factories if the PR grows. |
 | C1a-1 | ✅ | Add `Git::Repository.open`/`.bare`, path state, and `dir`/`repo`/`index`/`repo_size` | 4.x-compatible additive | `Git.open`/`.bare` still return `Git::Base`; new repository factories are additive until C1d. |
-| C1a-2 | ⬜ | Add `Git::Repository.clone`/`.init` | 4.x-compatible additive | `Git.clone`/`.init` still return `Git::Base`; clone/init behavior is duplicated behind new factories without changing public entry points. |
-| C1b | ⬜ | Move global config ownership | 4.x-compatible | `Git.config`, `Git.configure`, and `Git::Base.config` keep working; `Git::Base.config` remains as a delegator. |
-| E | ⬜ | Add repository helper/path-context methods | 4.x-compatible additive | `Git::Base` helpers keep working; `Git::Repository` gains equivalent behavior before any top-level return-type change. Split index helpers and working-directory helpers if needed. |
-| F1 | ⬜ | Move `Git.ls_remote` and `Git.default_branch` off `Git::Lib` | 4.x-compatible | Return formats and error behavior match current 4.x-compatible behavior. |
-| F2 | ⬜ | Move `Git.global_config`, module `#config`, and module `#global_config` off `Git::Lib` | 4.x-compatible | Config methods keep the same return formats and write behavior. |
-| C1c-1 | ⬜ | Guidance/process: signature-compatibility policy for extraction and review ([#1369](https://github.com/ruby-git/ruby-git/issues/1369)) | 4.x-compatible / docs-only | Guidance and review checklists define legacy-contract vs 5.x-native signatures, including test expectations. |
-| C1c-2 | ⬜ | End-of-Phase-3 public-API parity audit and remediation sweep ([#1370](https://github.com/ruby-git/ruby-git/issues/1370)) | 4.x-compatible | All four parity audit buckets resolved (fix or documented removal) before C1d; no unclassified compatibility gap remains. |
-| C1d | ⬜ | Flip `Git.open`/`.clone`/`.init`/`.bare` to return `Git::Repository` | v5 boundary | Explicit breaking change because class identity changes from `Git::Base` to `Git::Repository`; method-level parity must be complete first. |
-| D1 | ⬜ | Remove domain-object `Git::Base` guards and `@base.lib` fallbacks | v5 cleanup | Explicitly drops direct `Git::Base` provider support in domain-object constructors; normal factory-created objects remain supported. |
-| D2 / Phase 4 | ⬜ | Remove `base_object`/`from_base` with `Git::Base` deletion or retirement | v5 cleanup | Must land with the old-code deletion path; not releasable as a standalone PR while `Git::Base#facade_repository` depends on it. |
-
----
-
+| C1a-2 | ✅ | Add `Git::Repository.clone`/`.init` | 4.x-compatible additive | `Git.clone`/`.init` still return `Git::Base`; clone/init behavior is duplicated behind new factories without changing public entry points. |
+| C1b | [#1385](https://github.com/ruby-git/ruby-git/pull/1385) ✅ | Move global config ownership | 4.x-compatible | `Git.config`, `Git.configure`, and `Git::Base.config` keep working; `Git::Base.config` remains as a delegator. |
+| E | ✅ | Add repository helper/path-context methods | 4.x-compatible additive | `Git::Base` helpers keep working; `Git::Repository` gains equivalent behavior before any top-level return-type change. Split index helpers and working-directory helpers if needed. |
+| F1 | ✅ | Move `Git.ls_remote` and `Git.default_branch` off `Git::Lib` | 4.x-compatible | Return formats and error behavior match current 4.x-compatible behavior. |
+| F2 | ✅ | Move `Git.global_config`, module `#config`, and module `#global_config` off `Git::Lib` | 4.x-compatible | Config methods keep the same return formats and write behavior. |
+| C1c-1 | ✅ | Guidance/process: signature-compatibility policy for extraction and review ([#1369](https://github.com/ruby-git/ruby-git/issues/1369)) | 4.x-compatible / docs-only | Guidance and review checklists define legacy-contract vs 5.x-native signatures, including test expectations. |
+| C1c-2 | ✅ | End-of-Phase-3 public-API parity audit and remediation sweep ([#1370](https://github.com/ruby-git/ruby-git/issues/1370)) | 4.x-compatible | All four parity audit buckets resolved (fix or documented removal) before C1d; no unclassified compatibility gap remains. |
+| C1d | ✅ | Flip `Git.open`/`.clone`/`.init`/`.bare` to return `Git::Repository` | v5 boundary | Explicit breaking change because class identity changes from `Git::Base` to `Git::Repository`; method-level parity must be complete first. Split into C1d-1 (entry point flip), C1d-2 (eliminate internal .lib callers + add deprecation enforcement to both test suites), and C1d-3 (remove dead fallbacks + replace silent lib shim with real deprecation warning). |
+| D1 | ✅ | Remove domain-object `Git::Base` guards and `@base.lib` fallbacks | v5 cleanup | Explicitly drops direct `Git::Base` provider support in domain-object constructors; normal factory-created objects remain supported. |
 #### Phase 3 completion criteria
 
 Use this table to decide whether a checklist item can be marked complete. A step is
@@ -526,7 +552,6 @@ done only when its code, focused specs, and delegation/cleanup checks are all tr
 | C1c-2: public-API parity audit and remediation | End-of-Phase-3 sweep complete (Issue #1370): a public-method inventory compares `Git::Base` and `Git::Repository`; every surviving public method has a repository implementation and focused coverage; every intentional removal has an upgrade-note/deprecation decision; no unclassified compatibility gap remains. |
 | C1d: entry-point flip | `Git.open`, `Git.clone`, `Git.init`, and `Git.bare` return `Git::Repository`; common existing workflows still pass through those entry points; YARD return docs are updated; no top-level factory method calls `Git::Base.*`; full suite passes. |
 | D1: domain-object fallback removal | No `is_a?(Git::Base)` guards remain; no `@base.lib` fallback remains in domain objects; direct `Git::Base` provider support is documented as a v5-only removal; full suite passes. |
-| D2 / Phase 4: `base_object` bridge removal | `Git::ExecutionContext::Repository` no longer accepts or exposes `base_object`; `from_base` is removed or converted to a non-`Git::Base` path; this lands only with the PR that deletes or retires `Git::Base`, so no releasable state contains a broken `Git::Base#facade_repository`. |
 | E: instance helper methods | `Git::Repository` implements or explicitly deprecates `chdir`, `with_index`, `with_temp_index`, `with_working`, `with_temp_working`, `set_index`, and `set_working`; context rebuilding after index/worktree changes is covered by specs; helpers yield the same values and restore state after block exit/errors. |
 | F: `Git` module utilities off `Git::Lib` | `Git.default_branch`, `Git.global_config`, `Git.ls_remote`, module instance `#config`, and module instance `#global_config` no longer call `Git::Lib.new`; `Git::Base.repository_default_branch` migrated to use `Git::Commands::LsRemote` directly; existing `LsRemote` and `ConfigOptionSyntax` commands provide the behavior; parser/helper code needed from `Git::Lib` has moved; `grep -n 'Lib.new' lib/git.rb` returns no matches. |
 
@@ -542,15 +567,14 @@ done only when its code, focused specs, and delegation/cleanup checks are all tr
 | A4: new `Inspecting` — `show`, `fsck` | ✅ |
 | B (C0): `Git::Base` factory delegation wiring | ✅ |
 | C1a-1: `Git::Repository.open`/`.bare`, path state (`dir`, `repo`, `index`, `repo_size`) | ✅ |
-| C1a-2: `Git::Repository.clone`/`.init` (no `Git::Lib` dependency) | ⬜ |
-| C1b: Global config ownership (`Base.config` → `Git::Config`) | ⬜ |
-| C1c-1: Guidance/process updates for signature compatibility (#1369) | ⬜ |
-| C1c-2: End-of-Phase-3 public-API parity audit and remediation (#1370) | ⬜ |
-| C1d: Entry-point flip (`Git.open` etc. → `Git::Repository`) | ⬜ |
-| D1 (C3): Remove `is_a?(Git::Base)` guards + `@base.lib` fallbacks | ⬜ (v5 cleanup) |
-| D2 (C2 / Phase 4): Remove `base_object` bridge with `Git::Base` deletion | ⬜ (v5 cleanup) |
-| E: Instance helpers (`#chdir`, `#with_index`, `#with_temp_index`, `#with_working`, `#with_temp_working`) | ⬜ |
-| F: `Git` module utilities (`default_branch`, `global_config`, `ls_remote`) off `Git::Lib` | ⬜ (Phase 4 prereq) |
+| C1a-2: `Git::Repository.clone`/`.init` (no `Git::Lib` dependency) | ✅ |
+| C1b: Global config ownership (`Base.config` → `Git::Config`) | ✅ |
+| C1c-1: Guidance/process updates for signature compatibility (#1369) | ✅ |
+| C1c-2: End-of-Phase-3 public-API parity audit and remediation (#1370) | ✅ |
+| C1d: Entry-point flip (`Git.open` etc. → `Git::Repository`) | ✅ |
+| D1 (C3): Remove `is_a?(Git::Base)` guards + `@base.lib` fallbacks | ✅ |
+| E: Instance helpers (`#chdir`, `#with_index`, `#with_temp_index`, `#with_working`, `#with_temp_working`) | ✅ |
+| F: `Git` module utilities (`default_branch`, `global_config`, `ls_remote`) off `Git::Lib` | ✅ |
 
 #### Quality gates (per step)
 
@@ -580,7 +604,7 @@ logic. The gem will be fully functional after this phase.*
 1. **Create New Directory Structure**
 
    - `lib/git/commands/` ✅
-   - `lib/git/repository/` ✅ — populated with 12 facade modules in Phase 3 (see [Facade Modules Completed](#facade-modules-completed))
+   - `lib/git/repository/` ✅ — populated with 15 included modules in Phase 3 (see [Facade Modules Completed](#facade-modules-completed))
 
 2. **Eliminate Custom Path Classes**
 
@@ -602,14 +626,14 @@ logic. The gem will be fully functional after this phase.*
      - `Git::ExecutionContext::Global` subclass in `lib/git/execution_context/global.rb` ✅
 
    - `Git::Repository` in `lib/git/repository.rb` ✅
-     - Now includes 12 facade modules (see [Facade Modules Completed](#facade-modules-completed))
+     - Now includes 15 modules via `include` (see [Facade Modules Completed](#facade-modules-completed))
 
    - `Git::Commands::Arguments` DSL in `lib/git/commands/arguments.rb` ✅
      - Provides declarative argument definition for command classes
 
 4. **Set Up RSpec Environment**
 
-    RSpec configured and working alongside TestUnit. Specs live in `spec/` and can be
+    RSpec configured and working alongside Test::Unit. Specs live in `spec/` and can be
     run with `bundle exec rspec`. ✅
 
 ## Phase 2: The Strangler Fig Pattern - Migrating Commands
@@ -1254,7 +1278,7 @@ future work:
     instantiate and call the new `Git::Commands::Add` object, passing `self` as the
     context.
 
-  - **Verify**: Run the full test suite (both TestUnit and RSpec). The existing tests
+  - **Verify**: Run the full test suite (both Test::Unit and RSpec). The existing tests
     for `g.add` should still pass, but they will now be executing the new, refactored
     code.
 
@@ -1483,7 +1507,9 @@ order: Basic Snapshotting → Branching & Merging → etc.
 ***Goal**: Switch the public-facing classes to use the new architecture directly,
 breaking the final ties to the old implementation.*
 
-> **Status**: Task 1 below is complete; Task 2 is in progress — see the [Next Task](#next-task) section above for the current plan.
+> **Status**: Phase 3 is ✅ complete. Tasks 1 and 2 are both complete; the remaining
+> redesign work is the Phase 4 cleanup described in the [Next Task](#next-task)
+> section above.
 
 1. **Add `binary_path:` to `Git::ExecutionContext`** ✅
 
@@ -1493,43 +1519,54 @@ breaking the final ties to the old implementation.*
    stopgap in `Git.run_git_version` was replaced with
    `Git::Commands::Version.new(Git::ExecutionContext::Global.new(...)).call`.
 
-2. **Implement the Facade** ⏳
+2. **Implement the Facade** ✅
 
-   `Git::Repository` now includes 12 facade modules (see
-   [Facade Modules Completed](#facade-modules-completed)). `Git::Base` wraps the
-   corresponding methods via `facade_repository`. The domain-object migration
-   iterations (iters 1–9) add further facade methods, but full `Git::Base`
-   coverage requires additional facade PRs for methods not touched by those
-   iterations (e.g. `clean`, `rm`, `tags`/`add_tag`, `fsck`, `show`, `remotes`,
-   remote URL/branch helpers) before the cleanup PR can run.
+   `Git::Repository` now includes 15 modules via `include` in
+   `lib/git/repository.rb` (see [Facade Modules Completed](#facade-modules-completed)).
+   `Git::Base` wraps the corresponding methods via `facade_repository`, and the
+   end-of-Phase-3 parity sweep landed the remaining low-level facade coverage
+   needed before the entry-point flip — including `describe`, `show`, `fsck`,
+   `apply`, `apply_mail`, `read_tree`, `cat_file_*`, `repack`, `gc`, helper/path
+   context methods, and the remaining remote/tag convenience APIs.
 
 ## Phase 4: Final Cleanup and Release Preparation
 
 ***Goal**: Remove all old code, finalize the test suite, and prepare for the v5.0.0
 release.*
 
-1. **Remove Old Code**:
+### Phase 4 step graph
 
-   - Delete the `Git::Lib` class entirely.
+```mermaid
+graph LR
+    A --> B
+    B --> C
+```
 
-   - Delete the `Git::Base` class file.
+#### Step A — Remove old code
 
-   - Remove any other dead code that was part of the old implementation.
+- Delete `attr_reader :base_object`, remove `base_object:` from `#initialize`, and remove or convert `from_base`.
+- Delete the `Git::Lib` class entirely.
+- Delete the `Git::Base` class file.
+- Remove any other dead code that was part of the old implementation.
 
-2. **Finalize Test Suite**:
+**Done when**: `lib/git/lib.rb` and `lib/git/base.rb` are deleted; `Git::ExecutionContext::Repository` no longer accepts or exposes `base_object`; no references to `Git::Lib` or `Git::Base` remain in `lib/`.
 
-   - Convert any remaining, relevant TestUnit tests to RSpec.
+**Planning tip**: Before generating a deletion plan, audit all remaining callers of `Git::Lib`, `Git::Base`, and `from_base` across `lib/` and `spec/`. The bridge removal and `Git::Base` deletion must land atomically in the same PR — plan for a single large deletion commit rather than incremental removals.
 
-   - Remove the `test-unit` dependency from the `Gemfile`.
+#### Step B — Finalize test suite
 
-   - Ensure the RSpec suite has comprehensive coverage for the new architecture.
+- Convert any remaining, relevant Test::Unit tests to RSpec.
+- Remove the `test-unit` dependency from the `Gemfile`.
+- Ensure the RSpec suite has comprehensive coverage for the new architecture.
 
-3. **Update Documentation**:
+**Done when**: The `tests/` directory is empty or removed; `test-unit` is no longer
+in `Gemfile`; RSpec is the sole test framework.
 
-   - Thoroughly document the new public API (`Git`, `Git::Repository`, etc.).
+#### Step C — Update documentation
 
-   - Mark all internal classes (`ExecutionContext`, `Commands`, `*Path`) with `@api
-     private` in the YARD documentation.
+- Thoroughly document the new public API (`Git`, `Git::Repository`, etc.).
+- Mark all internal classes (`ExecutionContext`, `Commands`, `*Path`) with `@api private` in the YARD documentation.
+- Update the `README.md` and create a `UPGRADING.md` guide explaining the breaking changes for v5.0.0.
 
-   - Update the `README.md` and create a `UPGRADING.md` guide explaining the breaking
-     changes for v5.0.0.
+**Done when**: `yard stats` reports no missing docs on public API; `UPGRADING.md`
+covers all breaking changes; `README.md` reflects the new entry points.