fix(python): commit proto stubs so sdist-based builds produce working wheels

.github/workflows/branch-checks.yml

@@ -200,12 +200,18 @@ jobs:
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
+      - name: Mark workspace as safe for git
+        run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
+
       - name: Install tools
         run: mise install --locked
 
       - name: Install dependencies
         run: uv sync --frozen
 
+      - name: Proto stubs freshness
+        run: mise run python:proto:check
+
       - name: Format
         run: mise run python:format:check
 

.gitignore

@@ -96,9 +96,6 @@ dmypy.json
 # Cython debug symbols
 cython_debug/
 
-# Generated Python protobuf stubs (keep package marker)
-python/openshell/_proto/*
-!python/openshell/_proto/__init__.py
 
 # =============================================================================
 # IDE / Editor

CONTRIBUTING.md

@@ -408,6 +408,21 @@ These are the primary `mise` tasks for day-to-day development:
 | `mise run helm:docs` | Regenerate the Helm chart README                        |
 | `mise run clean`     | Clean build artifacts                                   |
 
+### Protobuf Stubs
+
+The Python SDK depends on generated protobuf/gRPC stubs committed under
+`python/openshell/_proto/`. After changing any `.proto` file in `proto/`,
+regenerate the stubs and commit the result:
+
+```shell
+mise run python:proto
+git add python/openshell/_proto/
+```
+
+The generation output is deterministic across Python versions because
+`grpcio-tools` is pinned via `uv.lock`. CI runs `mise run python:proto:check`
+to reject PRs with stale stubs. The local `mise run pre-commit` also catches
+this.
 ### Bazel targets (experimental)
 
 > [!IMPORTANT]

architecture/build.md

@@ -172,15 +172,16 @@ for explicit publication.
 
 ## Python Wheel Packaging
 
-The generated protobuf/gRPC stubs under `python/openshell/_proto/` are gitignored
-build outputs of `mise run python:proto`. The task uses `uv run --frozen` to
-synchronize the current worktree's `.venv` from `uv.lock` before generation.
-maturin honors `.gitignore` when collecting `python-source` files, so native
-builds (Linux CI, local `pip install .`) would drop them and ship an unimportable
-wheel. `pyproject.toml`
-pins them back in with `[tool.maturin].include` globs. The release workflows
-install each Linux wheel in a clean image and import `openshell.sandbox` as a
-smoke check.
+The generated protobuf/gRPC stubs under `python/openshell/_proto/` are committed
+to the repository so that standard PEP 517 build frontends (pip, build, fromager)
+can produce working wheels from the source tarball without replicating the mise
+task graph. After modifying any `.proto` file under `proto/`, regenerate the stubs
+with `mise run python:proto` and commit the result. The task uses
+`uv run --frozen` to pin `grpcio-tools` via `uv.lock`, so the output is
+deterministic regardless of the contributor's Python version. CI enforces
+freshness: `mise run python:proto:check` regenerates the stubs and fails if the
+working tree differs. The release workflows install each Linux wheel in a clean
+image and import `openshell.sandbox` as a smoke check.
 
 ## CI and E2E
 

pyproject.toml

@@ -71,13 +71,6 @@ bindings = "bin"
 manifest-path = "crates/openshell-cli/Cargo.toml"
 python-source = "python"
 module-name = "openshell"
-# _proto/ stubs are gitignored; force them into the wheel so git-aware
-# maturin builds don't drop them (package-relative paths).
-include = [
-    "openshell/_proto/*_pb2.py",
-    "openshell/_proto/*_pb2_grpc.py",
-    "openshell/_proto/*.pyi",
-]
 
 [tool.ruff]
 target-version = "py311"