Finalize PR

Step 6 — Editor-Lens Pass Over the Diff

Comment debt accumulates while a PR is in flight: review-process scaffolding (chunk numbers, finding IDs like H1 / M5 / L2, plan back-references, sketch IDs, "Round-2 adv#6"), wordy paraphrases of the code, dated status notes, and "previously / now" archaeology. None of this serves a future reader. Scrub it as part of finalize.

This step is run via the review-loop skill against the PR diff (not the whole repo) using the editor-lens agent.

1. Identify the changed in-scope source files:

   mkdir -p .copilot/finalize
   git diff --name-only main -- \
       'src/bocpy/**/*.c' 'src/bocpy/**/*.h' \
       'src/bocpy/**/*.py' 'src/bocpy/**/*.pyi' \
       'examples/**/*.py' \
       'test/**/*.py' \
       'templates/c_abi_consumer/src/**/*.c' \
       'templates/c_abi_consumer/src/**/*.h' \
       'templates/c_abi_consumer/src/**/*.py' \
       'scripts/**/*.py' \
     | tee .copilot/finalize/editor-lens-targets.txt

   git diff (no ..HEAD) covers both committed and uncommitted changes — important during finalize, when you may still be editing.

2. Invoke review-loop with editor-lens as the reviewer and the file list as the target. The lens follows the keep / rewrite / cut policy in .github/agents/editor-lens.agent.md. Iterate until the loop comes back clean.

3. Apply approved cuts and rewrites. Anything the lens flags under "Questions for the user" must be resolved before proceeding — do not silently delete.

The editor-lens scope explicitly excludes sphinx/source/, README.md, CHANGELOG.md, the top-level policy docs, and everything under .github/ and .copilot/. Those have different rules and are managed by other steps in this skill (or are off-limits entirely).

Why this lives in finalize, not pre-commit: during PR work the review tags and scaffold comments are useful — they let the author and reviewer cross-reference findings. They become noise only after the review documents are deleted. Finalize is the right place to scrub.

Step 7 — Lint and Test

Activate the chosen venv (default .env314 — confirm with the user) and run the full local mirror of the PR gate. Pipe long-running output to .copilot/finalize/<name>.log so the chat stays readable.

source .env314/bin/activate

7.1 Lint

Mirrors the .github/workflows/pr_gate.yml linting job. The --filename flag opts the walker into .pyi stubs (it would otherwise skip them silently):

flake8 --filename='*.py,*.pyi' src/bocpy test examples scripts \
  2>&1 | tee .copilot/finalize/flake8.log

Must exit zero.

7.2 Clang-format

Mirrors the cpp-format job. Run for both C trees touched by the branch:

clang-format-18 --dry-run -Werror \
    src/bocpy/*.c src/bocpy/*.h src/bocpy/include/bocpy/*.h \
  2>&1 | tee .copilot/finalize/clang-format-src.log

clang-format-18 --dry-run -Werror \
    templates/c_abi_consumer/src/**/*.{c,h} \
  2>&1 | tee .copilot/finalize/clang-format-template.log

Both must exit zero. If clang-format-18 is not installed, install it (apt install clang-format-18) or skip with explicit user approval; the CI version is pinned to 18.

7.3 Reinstall bocpy in the venv

A version bump touches pyproject.toml and (often) C sources. Force a fresh editable install so the test suite sees the new build. Use the BOCPY_BUILD_INTERNAL_TESTS=1 opt-in so the _internal_test_* extensions are built and the test_internal_* / test_compat_atomics.py modules run instead of skipping:

BOCPY_BUILD_INTERNAL_TESTS=1 pip install -e .[test] --no-build-isolation \
  2>&1 | tee .copilot/finalize/install.log

7.4 Full test suite

pytest -vv 2>&1 | tee .copilot/finalize/pytest.log | tail -40

Must exit zero. If pre-existing skips are present (e.g. version-gated tests), confirm they match the baseline recorded in the session plan; new skips warrant investigation.

7.5 Downstream consumer (if touched)

If the branch changed anything under src/bocpy/include/bocpy/, src/bocpy/boc_*.{c,h}, templates/c_abi_consumer/, or the bocpy.get_include() / bocpy.get_sources() helpers, also run:

pip install --no-build-isolation ./templates/c_abi_consumer \
  2>&1 | tee .copilot/finalize/consumer-install.log

pytest -vv templates/c_abi_consumer/test \
  2>&1 | tee .copilot/finalize/consumer-pytest.log | tail -20

Both must exit zero.

7.6 Cross-version spot check (optional)

If the branch touched anything version-gated (xidata.h, PY_VERSION_HEX ladders, free-threaded code paths, #if Py_GIL_DISABLED branches), re-run 7.3 + 7.4 in at least one additional venv covering the affected versions (e.g. .env312, .env313t, .env315t). Confirm with the user which extra venvs to exercise.

Step 8 — Summarize

Present a single summary to the user with:

• Version: old → new
• Files changed by this skill: pyproject.toml, sphinx/source/conf.py, CITATION.cff, templates/c_abi_consumer/pyproject.toml, CHANGELOG.md, any Sphinx pages updated, any README sections updated, and the list of source files edited by the editor-lens pass.
• Verification: flake8, clang-format, pytest, downstream consumer (if run), cross-version (if run) — all pass / fail with log paths under .copilot/finalize/.
• Open questions: anything editor-lens flagged as ambiguous and any pre-existing test skips that warrant attention.

Do not commit. All git operations belong to the user.

Guardrails

• Never commit, push, tag, or create a release. The user owns every git operation.
• Never skip a file listed in Step 3. All five (pyproject.toml, conf.py, CITATION.cff, the template pyproject.toml, and CHANGELOG.md) must move in lock-step.
• Never silently widen scope. If the editor-lens pass surfaces a bug, stop and raise it as a finding; do not fix it in the finalize pass.
• Never edit prose under sphinx/source/ to mask a missing public symbol. If the docs reference a symbol that does not exist, the bug is in the code or in __init__.pyi, not the docs.
• Always confirm the venv at Step 7 before running pip install. Installing into the wrong venv silently rebuilds the wrong interpreter's wheel.