feat: add system-aware tiered parallel pytest + cgroup v1/v2 support and on-behalf review standards

[LahkLeKey]

Summary

Adds an opt-in, system-aware parallel pytest mode with tiered profiles, cgroup v1/v2 quota awareness, and documentation/template updates for on-behalf review disclosure standards.

Highlights

• Keeps default flow unchanged: uv sync && uv run pytest

• Adds optional parallel execution: uv run pytest --parallel

• Adds tiered aggressiveness: --parallel-tier low|medium|high

• Computes worker settings from effective CPU + available memory + OS caps

• Supports both cgroup v2 and cgroup v1 CPU quota signals

• Prints resolved parallel settings in pytest header

• Adds standards-aligned docs/template guidance for "posted on behalf" review comments

Why

The suite can be slow in serial mode, while naive parallelism can overload machines or behave inconsistently across environments. This change provides bounded, explainable parallelism that remains optional and transparent.

A tag-along standards update was included to make AI-on-behalf review communication explicit and consistent.

Requirements Checklist

Functional

• Keep existing default test workflow intact (uv run pytest unchanged)

• Add optional parallel flag (--parallel)

• Calculate settings from system information

• Add 3-tier profile system (low, medium, high)

• Allow hard cap override (--parallel-max-workers)

• Avoid changing CI workflows for this feature

System-awareness

• Use effective CPU count (including affinity/quota signals where available)

• Use available memory with total-memory fallback

• Support cgroup v2 and cgroup v1 CPU quota parsing

• Consider cgroup memory constraints where available

• Apply OS-specific caps to prevent over-allocation

UX / observability

• Emit resolved parallel settings in pytest header

• Include selected tier in reported settings

• Keep command ergonomics simple for contributors

Documentation / standards

• Update contributor guidance for optional parallel testing

• Add tier recommendation matrix for laptop/workstation/CI usage

• Update PR template testing section with optional tiered command

• Add explicit on-behalf AI-comment attribution guidance in contributor docs

• Add PR-template checklist item for on-behalf attribution compliance

Validation

• Add/expand worker-sizing tests

• Validate medium/default tier behavior

• Validate low/high tier behavior

• Validate max-worker cap behavior

• Validate cgroup v2 and cgroup v1 quota parsing

Scope of Changes

Core logic

• tests/_parallel.py

  • Added system detection helpers:

    • effective CPU count

    • available memory

    • cgroup-aware CPU/memory constraints

  • Added tier model/config for low|medium|high

  • Added cgroup v2 + v1 CPU quota handling

  • Added ParallelSettings model for transparent resolved output

• tests/conftest.py

  • Added pytest options:

    • --parallel

    • --parallel-tier low|medium|high

    • --parallel-max-workers N

  • Wired computed settings into xdist numprocesses

  • Added report-header output for resolved settings

Tests

• tests/test_parallel_workers.py

  • CPU-bound and memory-bound decisions

  • OS cap behavior

  • max-worker cap behavior

  • low vs high tier conservatism

  • memory-per-worker tier scaling

  • cgroup v2 and cgroup v1 quota parsing tests

Docs / templates

• CONTRIBUTING.md

  • Optional parallel execution section

  • Tier guidance and recommendation matrix

  • Explicit on-behalf AI PR-comment attribution standard

• .github/PULL_REQUEST_TEMPLATE.md

  • Optional tiered parallel invocation in testing checklist

  • AI on-behalf attribution checklist item

Test Evidence

Executed locally:

• uv run specify --help

• uv run pytest tests/test_parallel_workers.py -q

• uv run pytest tests/test_parallel_workers.py --parallel --parallel-tier low --parallel-max-workers 2

• uv run pytest tests/test_parallel_workers.py --parallel --parallel-tier high --parallel-max-workers 2

Output excerpts:

$ uv run pytest tests/test_parallel_workers.py -q


============================= test session starts =============================


platform win32 -- Python 3.13.13, pytest-9.0.3, pluggy-1.6.0


collected 12 items





tests\test_parallel_workers.py ............                              [100%]





============================= 12 passed in 0.29s ==============================

$ uv run pytest tests/test_parallel_workers.py --parallel --parallel-tier low --parallel-max-workers 2


[spec-kit] --parallel settings: tier=low, workers=2 (cpu_cap=10, mem_cap=4, os_cap=2), effective_cpus=12, avail_mem=10.9GiB, total_mem=47.8GiB, mem_per_worker=2.5GiB


...


============================= 12 passed in 0.21s ==============================

$ uv run pytest tests/test_parallel_workers.py --parallel --parallel-tier high --parallel-max-workers 2


[spec-kit] --parallel settings: tier=high, workers=2 (cpu_cap=12, mem_cap=10, os_cap=6), effective_cpus=12, avail_mem=10.9GiB, total_mem=47.8GiB, mem_per_worker=1.0GiB


...


============================= 12 passed in 0.21s ==============================

Incoming Copilot Reviews Checklist

• Addressed inline feedback: add cgroup v1 CPU quota support for worker sizing

• Added regression tests for cgroup v2 and cgroup v1 quota parsing

• Replied inline with fix + validation evidence

Risk / review focus

Please review with extra focus on:

• Cross-platform behavior of system detection logic

• cgroup detection correctness on Linux/containerized runners

• Tier defaults and cap conservatism

• Interaction between custom --parallel options and xdist behavior

• Clarity and enforceability of on-behalf review disclosure wording

AI disclosure

This PR was prepared with GitHub Copilot assistance, with human-directed implementation, validation, and review.

Update 2026-06-05: Windows/Bash path fixes + verified parallel execution

What changed after prior report

• Fixed the previously reported Windows/Git Bash path assertion failures in:

  • tests/test_setup_plan_no_overwrite.py

  • tests/test_setup_tasks.py

  • tests/test_timestamp_branches.py

• Ensured --parallel now actually activates xdist workers (not just settings reporting).

New validation evidence

Repro subset (previously failing files) in serial mode:

$ uv run pytest tests/test_setup_tasks.py tests/test_setup_plan_no_overwrite.py tests/test_timestamp_branches.py -q


117 passed in 103.28s (0:01:43)

Same subset with optional parallel high tier:

$ uv run pytest tests/test_setup_tasks.py tests/test_setup_plan_no_overwrite.py tests/test_timestamp_branches.py -q --parallel --parallel-tier high


6 workers [117 items]


117 passed in 32.48s

Full suite with optional parallel high tier:

$ uv run pytest -q --parallel --parallel-tier high


6 workers [3660 items]


3653 passed, 7 skipped in 137.81s (0:02:17)

Optimization outcome

• Subset runtime improved from ~103s to ~32s with --parallel --parallel-tier high.

• Full suite now completes green under optional parallel mode with active workers.

Commit references for this update

• 5ec7f40 test: make --parallel activate xdist workers

• c1cf15f test: harden bash path assertions on Windows

Review Fix Ledger (On Behalf Of @LahkLeKey)

This section tracks review-driven follow-up fixes to avoid repetitive feedback loops across rounds.

Commit	Summary
3936c1c	fix: honor cgroup v1 cpu quota for parallel worker sizing
31537cf	fix: support cpuacct,cpu cgroup v1 quota mount layout
6935ad8	test: handle zero available memory in parallel sizing
7c966ae	test: address open review findings for path and xdist checks
1b757be	test: honor explicit -n auto and clean InvalidMetadata fallback
03e30e9	test: floor cgroup quota workers and remove dead helper
1927cb6	test: tighten path checks and report effective workers
003f870	test: skip parallel xdist hooks when plugin is disabled
a83ad7b	test: simplify bash path normalization helper
173207b	test: harden parallel args and cwd-safe upgrade tests

[Copilot]

Pull request overview

Adds an opt-in --parallel mode for running the repo’s pytest suite with pytest-xdist, computing a bounded worker count from detected CPU/memory constraints plus tiered OS caps, and surfacing the resolved settings in the pytest header for transparency.

Changes:

• Introduces system-aware worker sizing logic with low/medium/high tiers (tests/_parallel.py).
• Adds pytest CLI options and wiring to enable xdist only when --parallel is provided, plus a report header line (tests/conftest.py).
• Adds unit tests for sizing behavior and documents the optional parallel workflow; adds pytest-xdist to test extras.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/test_parallel_workers.py	Adds tests covering CPU/memory/OS caps, tier effects, and max-worker override behavior.
tests/conftest.py	Adds --parallel/tier/max-workers options, computes worker settings, and prints resolved settings in the pytest header.
tests/_parallel.py	Implements CPU/memory detection helpers (incl. cgroup-aware memory) and tiered worker sizing model.
pyproject.toml	Adds pytest-xdist to the test optional dependency set.
CONTRIBUTING.md	Documents optional parallel test execution and tier recommendations.
.github/PULL_REQUEST_TEMPLATE.md	Updates testing checklist to mention optional parallel tiered invocation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[LahkLeKey]

Posted on behalf of @LahkLeKey by GitHub Copilot (model: GPT-5.3-Codex).

Review round update

Commit: 3936c1c

Addressed feedback

• Added cgroup v1 CPU quota handling in parallel worker sizing.
• Preserved existing cgroup v2 handling.
• Added regression tests for both cgroup v2 and cgroup v1 quota parsing.

Validation

• uv run pytest tests/test_parallel_workers.py -q (11 passed)

No conversation was resolved in this update.

[LahkLeKey]

Posted on behalf of @LahkLeKey by GitHub Copilot (model: GPT-5.3-Codex).

Review round update

Commit: 573ead4

Standards tag-along implementation

• Added explicit on-behalf attribution guidance to CONTRIBUTING.md.
• Added PR-template checklist item requiring explicit on-behalf attribution when applicable.
• Refined PR body formatting and added a dedicated checklist section for this standards item.

No conversation was resolved in this update.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

[LahkLeKey]

Posted on behalf of @LahkLeKey by GitHub Copilot (model: GPT-5.3-Codex).

Review round update

Commit: 31537cf

Addressed Copilot feedback

• Added support for additional cgroup v1 combined-controller mount layout:
  • /sys/fs/cgroup/cpuacct,cpu/cpu.cfs_quota_us
  • /sys/fs/cgroup/cpuacct,cpu/cpu.cfs_period_us
• Kept existing support for:
  • /sys/fs/cgroup/cpu/
  • /sys/fs/cgroup/cpu,cpuacct/
• Added regression test:
  • test_detect_cgroup_cpu_quota_count_v1_parses_cpuacct_cpu_mount

Validation

• uv run pytest tests/test_parallel_workers.py -q (12 passed)

No conversation was resolved in this update; inline replies were posted for reviewer/bot closure.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

[LahkLeKey]

Posted on behalf of @LahkLeKey by GitHub Copilot (model: GPT-5.3-Codex).

Review-round update summary:

• Reduced skip count by converting the symlink test in integration subcommand tests from an unconditional Windows skip to a capability-based check.
• Test now runs on Windows environments where directory symlink creation is available.

Included commit:

• 731af61

Validation:

• Full suite (parallel high tier): 3656 passed, 6 skipped

[LahkLeKey]

Posted on behalf of @LahkLeKey by GitHub Copilot (model: GPT-5.3-Codex).

Review-round update summary:

• Removed the remaining platform-gated skips by converting tests to capability-aware/cross-platform assertions.
• Replaced relative installer-path tests to avoid Windows path/teardown edge cases while preserving intent.
• Kept strict permission/mode intent checks on POSIX and used equivalent intent checks on Windows.

Included commit:

• 2dc74cd

Validation:

• Full suite (parallel high tier): 3662 passed, 0 skipped

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 5 comments.

[LahkLeKey]

Posted on behalf of @LahkLeKey by GitHub Copilot (model: GPT-5.3-Codex).

Review-round update summary:

• Addressed all currently open Copilot findings for xdist gating, Windows bash path normalization, auth permission warning determinism, and setup-tasks assertion strictness.
• Kept Windows-specific fallback behavior only where platform behavior is known to diverge, while restoring stricter checks on non-Windows platforms.

Included commit:

• 7c966ae

Validation:

• Focused regression set for all five findings: 4 passed

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

tests/test_self_upgrade_execution.py:90

• test_relative_installer_path_does_not_require_path_lookup now runs on Windows but creates a relative installer file named uv-installer without an executable extension. In _run_installer() (src/specify_cli/_version.py) the relative-path branch checks os.access(path, os.X_OK), which commonly returns False on Windows for non-.exe/.bat files, so this test can fail with an “invalid installer” exit instead of the expected success.

Patch specify_cli._version.os.access to return True in this test (it’s not trying to validate Windows executability semantics, just that PATH lookup isn’t required for relative paths).

        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
            "specify_cli._version.shutil.which", side_effect=lambda name: None
        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
            "specify_cli._version._get_installed_version", return_value="0.7.5"
        ), patch(

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.

[LahkLeKey]

Posted on behalf of @LahkLeKey by GitHub Copilot (model: GPT-5.3-Codex). Review round update for 1927cb6: addressed all currently open review comments and posted inline Resolved by replies on each thread. Changes include stricter non-Windows shell path matching, tighter Windows override-path assertion, and report-header display of effective workers (with regression test coverage). Validation: uv run pytest tests/test_parallel_workers.py tests/test_setup_tasks.py tests/test_timestamp_branches.py -q (128 passed).

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

[LahkLeKey]

Posted on behalf of @LahkLeKey by GitHub Copilot (model: GPT-5.3-Codex). Review round update for 003f870: addressed all currently open review comments by guarding both parallel xdist hook paths when users pass -p no:xdist. Added regression tests for split and compact disable forms. Validation: uv run pytest tests/test_parallel_workers.py -q (19 passed).

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 1 comment.

[LahkLeKey]

Posted on behalf of @LahkLeKey by GitHub Copilot (model: GPT-5.3-Codex). Review round update for a83ad7b: addressed the remaining open review comment by simplifying _path_from_bash_output() in tests/test_setup_plan_no_overwrite.py and posting an inline Resolved by reply. Validation: uv run pytest tests/test_setup_plan_no_overwrite.py -q (6 passed).

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 6 comments.

[LahkLeKey]

Posted on behalf of @LahkLeKey by GitHub Copilot (model: GPT-5.3-Codex). Resolved by 173207b. _assert_shell_path_matches() now applies pytest-tempdir trimming only on Windows; POSIX no longer uses that relaxation and stays strict.

[LahkLeKey]

Posted on behalf of @LahkLeKey by GitHub Copilot (model: GPT-5.3-Codex). Review round update for 173207b: addressed all currently open review comments and posted inline 'Resolved by 173207b' replies on each open thread. Also backfilled a persistent Review Fix Ledger in the PR description (including both 'Addressed in' and 'Resolved by' history) to track add-on fixes and prevent feedback loops across rounds. Validation: uv run pytest tests/test_parallel_workers.py tests/test_timestamp_branches.py tests/test_self_upgrade_execution.py -q (130 passed).

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.