@@ -64,7 +64,8 @@ jobs:
       - name: Check parity and publish comparison
         run: |
           .bench-gix/bin/python -m test.performance.compare_backends \
-            benchmark-results/cli.json benchmark-results/gix.json > benchmark-results/comparison.md
+            benchmark-results/cli.json benchmark-results/gix.json \
+            --cli-budget test/performance/cli-budget.json > benchmark-results/comparison.md
           cat benchmark-results/comparison.md >> "$GITHUB_STEP_SUMMARY"
           .bench-gix/bin/python -m pyperf compare_to \
             benchmark-results/cli.json benchmark-results/gix.json --table --table-format md \
 
@@ -4,6 +4,46 @@ Before starting work, read and follow [CONTRIBUTING.md](CONTRIBUTING.md),
 including the [Prevent agent impersonation](CONTRIBUTING.md#prevent-agent-impersonation)
 section governing identification when communicating through a person's account.
 
+# Gix backend implementations
+
+Gix backend operations must use Gix through the supported GixPython (`gix`)
+APIs. Python/stdlib implementations, direct filesystem inference, and custom
+native implementations outside Gix are not substitutes for a missing Gix
+operation. Do not implement Git behavior independently to avoid CLI calls.
+
+"Native" in code, documentation, reports and benchmarks means execution by
+Gitoxide through GixPython's `gix` API. It never means Python-implemented Git
+behavior. Every eliminated CLI call must be backed by identified Gix calls.
+
+Python glue may validate inputs, adapt Gix results to GitPython's return types
+and formatting, manage the retained `gix.Repository`, and select a CLI fallback.
+It must not invent a successful result or repair missing Git semantics with a
+separate implementation. Retaining and explicitly recreating a Gix repository
+through the shared accessor is allowed.
+
+Adapting native locations may append the fixed metadata leaf names `modules`
+and `COMMIT_EDITMSG` to `Repository.git_dir()`, whose location Gix resolves.
+Input paths may be canonicalized before reopening through Gix; return metadata
+from that native handle. These adaptations must match Git in regression tests
+and do not authorize a Python implementation of the general `--git-path` rules.
+
+If Gix lacks a capability, differs from the required behavior, or its use is
+unclear, keep the existing Git CLI path and document the gap in
+`doc/gix-backend.md`. State the expected behavior, available evidence, and what
+GixPython or Gitoxide needs to expose or fix upstream. Tests, coverage reports
+and benchmark ceilings must reflect that fallback; a lower CLI count alone
+does not demonstrate a Gix implementation.
+
+Track every observed difference from the equivalent Git operation as a Git
+compatibility bug, even if the Gix behavior is intentional. Gix must provide
+matching behavior, at least through a mode as strict as Git. Record Git's
+expected behavior, Gix's actual behavior, versions, reproduction or regression,
+and the affected adapter/fallback in the ledger. Keep these bugs open when a
+Gix-based adapter workaround restores parity; close them only after verifying
+the upstream fix or compatible mode. Distinguish demonstrated mismatches from
+missing APIs and unverified behavior. Do not repair a compatibility bug by
+implementing Git semantics in Python.
+
 # Commit messages
 
 Follow Conventional Commits for every commit. Every commit must have a
 
@@ -77,6 +77,53 @@ The `git.backend` DEBUG logger reports these decisions outside pytest.
 `git._backend.statistics()` returns a snapshot of the process-local counters.
 Zero observed calls means untested in that run, not unsupported.
 
+Successful `Git.execute` launches also appear as `CLI process` records. This
+includes raw `repo.git` calls and failed Git commands that started a process,
+but excludes failed process creation, direct subprocesses in test helpers,
+other Python processes and Git's own child processes. A persistent `cat-file`
+launch counts once; subsequent requests through it do not. These counts apply
+to both installations and are separate from native/fallback decisions.
+
+Pytest prints session launch totals split into setup, call, teardown and
+collection/session work. `--backend-report` keeps its existing record-list
+format and adds `pytest.*` phase records. The `Git.execute` record is
+process-lifetime cumulative (including import-time probes); `pytest.session_total`
+is the current session's total. Optional ceilings fail the test session on an
+increase while allowing reductions:
+
+```sh
+.tox/gix/bin/python test/run-local.py --no-cov -q \
+    --backend-report=.cache/gix-processes.json \
+    --max-cli-processes=TOTAL --max-cli-test-processes=CALLS
+```
+
+Replace `TOTAL`/`CALLS` with baselines for the same selected tests and platform.
+Setup is deliberately counted separately because fixture improvements and
+test additions can change it independently of native backend capability.
+These are pytest phases: `unittest.TestCase.setUp()`/`tearDown()` run inside
+the call phase, so that column can still include their fixture work. Counts
+cover the current Python process; they are not aggregated across xdist workers.
+For a stable CI assertion, the pinned repository benchmark uses per-measurement
+ceilings in `test/performance/cli-budget.json`: the warm Gix journey launches
+one CLI process, opening launches five, and nested discovery launches seven.
+Reduce these ceilings as conversions land. The other operation rows have zero
+ceilings except the one-process patch diff.
+
+Before the Gix-only audit, this instrumentation on CPython 3.12.14/macOS arm64 and official
+GixPython 0.1.0 recorded a full suite without coverage passing 1,674 tests and 38
+subtests (79 skipped, one xfailed) in 408.81 seconds. It recorded **30,898
+`Git.execute` launches**: 6,523 in pytest setup and 24,375 in call phases,
+with zero in teardown or collection/session phases. The process-lifetime
+counter is 30,899 because the import-time Git probe precedes pytest session
+accounting. The same run recorded 21,409 fallback decisions. These totals
+include explicit CLI tests and fixture commands, including non-Git commands
+passed directly to `Git.execute`; they are a local baseline, not a count of
+only fallback calls. The fixed warm benchmark instead isolates a user journey:
+23 CLI launches versus one Gix launch, opening 11 versus five, and nested
+discovery 13 versus seven after restoring the reference-format fallback.
+The historical full-suite counts above predate this correction. A constant
+`files` answer was not a Gix query; `GIX-1` records the missing binding.
+
 | GitPython entry point / managed command | Native implementation | Remaining CLI cases |
 | --- | --- | --- |
 | `Git.get_object_header`, ODB `info` | Object resolution and native header lookup | Custom storage, unsupported revision grammar |
 
@@ -1604,6 +1604,7 @@ def execute(
         except cmd_not_found_exception as err:
             raise GitCommandNotFound(redacted_command, err) from err
         else:
+            _backend.record("Git.execute", "CLI process")
             # Replace with a typeguard for Popen[bytes]?
             proc.stdout = cast(BinaryIO, proc.stdout)
             proc.stderr = cast(BinaryIO, proc.stderr)
 
@@ -1,5 +1,6 @@
 """Report native coverage when the optional backend is installed."""
 
+from collections import Counter
 import json
 from pathlib import Path
 
@@ -11,22 +12,85 @@
 
 def pytest_addoption(parser):
     parser.addoption("--backend-report", help="Write native/CLI operation counts as JSON")
+    parser.addoption("--max-cli-processes", type=int, help="Maximum Git.execute launches in the pytest session")
+    parser.addoption("--max-cli-test-processes", type=int, help="Maximum Git.execute launches in test call phases")
+
+
+def cli_processes():
+    return _backend.statistics().get(("Git.execute", "CLI process"), 0)
+
+
+def pytest_configure(config):
+    for option in ("--max-cli-processes", "--max-cli-test-processes"):
+        limit = config.getoption(option)
+        if limit is not None and limit < 0:
+            raise pytest.UsageError(option + " must be nonnegative")
+    config._cli_process_start = cli_processes()
+    config._cli_process_phases = Counter()
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_runtest_setup(item):
+    before = cli_processes()
+    yield
+    item.config._cli_process_phases["setup"] += cli_processes() - before
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_runtest_call(item):
+    before = cli_processes()
+    yield
+    item.config._cli_process_phases["call"] += cli_processes() - before
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_runtest_teardown(item):
+    before = cli_processes()
+    yield
+    item.config._cli_process_phases["teardown"] += cli_processes() - before
+
+
+def pytest_sessionfinish(session, exitstatus):
+    config = session.config
+    actual = {
+        "--max-cli-processes": cli_processes() - config._cli_process_start,
+        "--max-cli-test-processes": config._cli_process_phases["call"],
+    }
+    config._cli_process_failures = [
+        f"{option}: {count} launches exceed ceiling {config.getoption(option)}"
+        for option, count in actual.items()
+        if config.getoption(option) is not None and count > config.getoption(option)
+    ]
+    if config._cli_process_failures:
+        session.exitstatus = pytest.ExitCode.TESTS_FAILED
 
 
 def pytest_report_header(config):
     return "GitPython backend: " + _backend.name
 
 
 def pytest_terminal_summary(terminalreporter, exitstatus, config):
-    if _backend.name != "gix":
-        return
+    total = cli_processes() - config._cli_process_start
+    phases = config._cli_process_phases
+    terminalreporter.section("Git CLI process launches")
+    terminalreporter.write_line(
+        f"{total} total: {phases['setup']} setup, {phases['call']} call, "
+        f"{phases['teardown']} teardown, {total - sum(phases.values())} collection/session"
+    )
+    for failure in config._cli_process_failures:
+        terminalreporter.write_line(failure, red=True)
     records = [
         {"method": method, "outcome": outcome, "count": count}
         for (method, outcome), count in sorted(_backend.statistics().items())
     ]
-    terminalreporter.section("GixPython operation coverage")
-    for item in records:
-        terminalreporter.write_line("{method}: {outcome} ({count})".format(**item))
+    if _backend.name == "gix":
+        terminalreporter.section("GixPython operation coverage")
+        for item in records:
+            terminalreporter.write_line("{method}: {outcome} ({count})".format(**item))
+    records.extend(
+        {"method": "pytest." + phase, "outcome": "CLI process", "count": count}
+        for phase, count in sorted({**phases, "session_total": total}.items())
+    )
     path = config.getoption("--backend-report")
     if path:
         Path(path).parent.mkdir(parents=True, exist_ok=True)
 
@@ -49,7 +49,8 @@ Run from the source root, sequentially to avoid competing for CPU and disk:
     --repo "$BENCH_REPO" --expect-backend gix -o /tmp/gix.json
 .venv/bin/python -m test.performance.bench_repository \
     --repo "$BENCH_REPO" --expect-backend cli -o /tmp/cli.json
-.tox/gix/bin/python -m test.performance.compare_backends /tmp/cli.json /tmp/gix.json
+.tox/gix/bin/python -m test.performance.compare_backends /tmp/cli.json /tmp/gix.json \
+    --cli-budget test/performance/cli-budget.json
 .tox/gix/bin/python -m pyperf compare_to /tmp/cli.json /tmp/gix.json --table --table-format md
 ```
 
@@ -76,6 +77,24 @@ of the journey and parity checks. Include supported and fallback operations;
 the current patch measurement intentionally exercises fallback. Backend
 decisions are adapter events, not complete subprocess counts.
 
+`cli_processes` counts successful launches through `Git.execute` during one
+warm invocation, including raw calls and the launch of persistent `cat-file`
+processes. Sending another request to an existing process does not increment
+it. Native/fallback decisions remain separate: the current warm Gix journey has
+two fallback decisions but launches only one process (the patch diff).
+Direct subprocesses in the harness and Git's own child processes are excluded.
+
+The checked-in `cli-budget.json` sets maximum Gix launch counts for this pinned
+fixture. CI enforces the ceilings: reductions pass, increases fail with the
+measurement and counts. Lower ceilings when an optimization lands to retain
+the gain. The initial warm ceilings are journey/patch 1, opening 5, discovery 7,
+and zero for the other operations. New measurements need an explicit ceiling;
+do not automatically raise an existing ceiling to accept a regression.
+
+The opening/discovery ceilings include a real CLI reference-format query
+(`GIX-1`). GixPython must expose the format before that call can disappear;
+Python inference does not count as a native implementation.
+
 Timing is observational: shared CI runners and local activity introduce noise.
 The CI job publishes all means, standard deviations and ratios, retains raw
 artifacts, and uses `pyperf compare_to` for significance reporting. It fails on
 
@@ -149,6 +149,7 @@ def git(*arguments, cwd=args.repo):
             ]
         )
         for name, operation, target in measurements:
+            operation(target)  # Warm persistent CLI processes before counting.
             # Untimed preflight validates parity and records native/fallback
             # decisions for ONE invocation, rather than calibrated loop counts.
             before = _backend.statistics()
@@ -161,6 +162,11 @@ def git(*arguments, cwd=args.repo):
             metadata = {
                 "result_digest": sha256(json.dumps(result, sort_keys=True).encode()).hexdigest(),
                 "backend_decisions": json.dumps(decisions, sort_keys=True),
+                "cli_processes": sum(
+                    item["count"]
+                    for item in decisions
+                    if (item["method"], item["outcome"]) == ("Git.execute", "CLI process")
+                ),
             }
             runner.bench_func(name, operation, target, metadata=metadata)
 
 
@@ -0,0 +1,16 @@
+{
+  "fixture_revision": "6ba2c0a2f9ee7feffd7e079621c4845820180c9a",
+  "max_gix_cli_processes": {
+    "journey": 1,
+    "inventory": 0,
+    "history_25": 0,
+    "browse_tree_and_blob": 0,
+    "read_index": 0,
+    "revision_graph": 0,
+    "diff_and_stats": 0,
+    "patch_diff": 1,
+    "worktree_status": 0,
+    "open_repository": 5,
+    "discover_repository": 7
+  }
+}
@@ -1,13 +1,15 @@
 """Validate benchmark parity and print every measurement, including slowdowns."""
 
+import argparse
 import json
-import sys
+from pathlib import Path
 
 import pyperf
 
 
-def compare(cli_path, gix_path):
+def compare(cli_path, gix_path, cli_budget=None):
     cli, gix = pyperf.BenchmarkSuite.load(str(cli_path)), pyperf.BenchmarkSuite.load(str(gix_path))
+    budget = json.loads(Path(cli_budget).read_text()) if cli_budget else None
     if cli.get_benchmark_names() != gix.get_benchmark_names():
         raise ValueError("The backends measured different journeys")
     rows = []
@@ -30,20 +32,34 @@ def compare(cli_path, gix_path):
             if lm[key] != rm[key]:
                 raise ValueError(f"{name}: backends differ in {key}: {lm[key]!r} != {rm[key]!r}")
         decisions = json.loads(rm["backend_decisions"])
+        if budget is not None:
+            if rm["fixture_revision"] != budget["fixture_revision"]:
+                raise ValueError("CLI process budget belongs to a different fixture")
+            limit = budget["max_gix_cli_processes"][name]
+            if rm["cli_processes"] > limit:
+                raise ValueError(f"{name}: {rm['cli_processes']} CLI launches exceed ceiling {limit}")
         native = sum(item["count"] for item in decisions if item["outcome"] == "native")
         fallback = sum(item["count"] for item in decisions if item["outcome"].startswith("CLI:"))
         rows.append(
             f"| {name} | {left.mean() * 1000:.2f} ± {left.stdev() * 1000:.2f} "
             f"| {right.mean() * 1000:.2f} ± {right.stdev() * 1000:.2f} "
-            f"| {left.mean() / right.mean():.2f}× | {native} / {fallback} |"
+            f"| {left.mean() / right.mean():.2f}× | {native} / {fallback} "
+            f"| {lm['cli_processes']} / {rm['cli_processes']} |"
         )
-    print("| Measurement | CLI mean ± stdev (ms) | GixPython mean ± stdev (ms) | CLI / Gix | Native / fallback |")
-    print("| --- | ---: | ---: | ---: | ---: |")
+    print(
+        "| Measurement | CLI mean ± stdev (ms) | GixPython mean ± stdev (ms) "
+        "| CLI / Gix | Native / fallback | CLI launches: CLI / Gix |"
+    )
+    print("| --- | ---: | ---: | ---: | ---: | ---: |")
     print("\n".join(rows))
-    print("\nRatios above 1 favor GixPython. Decisions are per invocation, not subprocess counts.")
+    print("\nRatios above 1 favor GixPython. Decisions are per invocation; CLI launches count Git.execute processes.")
     print("\nWarm-cache, read-only measurements; checkout, imports and preflight are outside timing.")
     print("The journey reuses one open Repo; opening and nested discovery are measured separately.")
 
 
 if __name__ == "__main__":
-    compare(*sys.argv[1:])
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("cli_path")
+    parser.add_argument("gix_path")
+    parser.add_argument("--cli-budget", help="JSON ceilings for GixPython's launches on the fixed fixture")
+    compare(**vars(parser.parse_args()))
@@ -1,11 +1,13 @@
 """The benchmark comparison must reject incompatible workloads and results."""
 
+import json
+
 import pytest
 
 pyperf = pytest.importorskip("pyperf")
 
 
-@pytest.mark.parametrize("changed", [None, "result_digest", "fixture_revision", "backend"])
+@pytest.mark.parametrize("changed", [None, "result_digest", "fixture_revision", "backend", "cli_processes"])
 def test_comparison_requires_parity(tmp_path, capsys, changed):
     from test.performance.compare_backends import compare
 
@@ -20,18 +22,23 @@ def test_comparison_requires_parity(tmp_path, capsys, changed):
         "python_version": "3.12.14",
         "result_digest": "equal",
         "backend_decisions": "[]",
+        "cli_processes": 0,
         "name": "journey",
     }
     paths = [tmp_path / "cli.json", tmp_path / "gix.json"]
     for backend, path in zip(("cli", "gix"), paths):
         values = {**metadata, "backend": backend}
         if backend == "gix" and changed:
-            values[changed] = "different"
+            values[changed] = 1 if changed == "cli_processes" else "different"
         run = pyperf.Run([0.1, 0.2], metadata=values, collect_metadata=False)
         pyperf.BenchmarkSuite([pyperf.Benchmark([run])]).dump(str(path))
+    budget = tmp_path / "budget.json"
+    budget.write_text(json.dumps({"fixture_revision": "fixture", "max_gix_cli_processes": {"journey": 0}}))
     if changed:
-        with pytest.raises(ValueError, match="differ|Expected"):
-            compare(*paths)
+        with pytest.raises(ValueError, match="differ|Expected|exceed"):
+            compare(*paths, cli_budget=budget)
     else:
-        compare(*paths)
+        compare(*paths, cli_budget=budget)
         assert "journey | 150.00" in capsys.readouterr().out
+        budget.write_text(json.dumps({"fixture_revision": "fixture", "max_gix_cli_processes": {"journey": 1}}))
+        compare(*paths, cli_budget=budget)  # A reduction stays within the ceiling.
Original file line number	Diff line number	Diff line change
`@@ -149,6 +149,7 @@ def git(*arguments, cwd=args.repo):`
`149`	`149`	`]`
`150`	`150`	`)`
`151`	`151`	`for name, operation, target in measurements:`
	`152`	`+ operation(target) # Warm persistent CLI processes before counting.`
`152`	`153`	`# Untimed preflight validates parity and records native/fallback`
`153`	`154`	`# decisions for ONE invocation, rather than calibrated loop counts.`
`154`	`155`	`before = _backend.statistics()`
`@@ -161,6 +162,11 @@ def git(*arguments, cwd=args.repo):`
`161`	`162`	`metadata = {`
`162`	`163`	`"result_digest": sha256(json.dumps(result, sort_keys=True).encode()).hexdigest(),`
`163`	`164`	`"backend_decisions": json.dumps(decisions, sort_keys=True),`
	`165`	`+ "cli_processes": sum(`
	`166`	`+ item["count"]`
	`167`	`+ for item in decisions`
	`168`	`+ if (item["method"], item["outcome"]) == ("Git.execute", "CLI process")`
	`169`	`+ ),`
`164`	`170`	`}`
`165`	`171`	`runner.bench_func(name, operation, target, metadata=metadata)`
`166`	`172`