feat(directives): scavenge sweep 4/5 (tracks + commands + styleguides + todos): 18 batch-4 directives + concurrent worker batches

2026-07-04 02:00:42 -04:00
parent e8d3578f2e
commit 79124774ec
82 changed files with 2430 additions and 0 deletions
@@ -0,0 +1,10 @@
+# use_batched_test_runner
+
+## v1
+
+**Why this iteration:** Lifted from `conductor/tier2/agents/tier2-autonomous.md:119-121` + `conductor/tier2/commands/tier-2-auto-execute.md:39-40` + `conductor/tier2/commands/tier-2-auto-execute.md:53-55` — the Tier 2 sandbox explicitly forbids `uv run pytest` directly because the batched runner provides tier filtering, xdist parallelization, and a summary table that `live_gui` tests depend on.
+**Source:** `conductor/tier2/agents/tier2-autonomous.md:119-121,127` + `conductor/tier2/commands/tier-2-auto-execute.md:39-40,53-55`
+
+---
+
+**Lifted:** 2026-07-03 scavenge sweep batch 4/5: tracks + commands + styleguides + todos
@@ -0,0 +1,36 @@
+# Always invoke tests via `uv run python scripts/run_tests_batched.py` — never `uv run pytest` directly
+
+## What it says
+
+Tier 2 autonomous execution (and any other automation that wants parallel runs, tier filtering, and a summary table) MUST invoke the project's batched test runner: `uv run python scripts/run_tests_batched.py`. Direct `uv run pytest` calls are forbidden for the same reasons raw `git checkout` is forbidden — they bypass the layer that the project's `live_gui` tests depend on.
+
+## Why
+
+The batched runner provides:
+
+- **Tier-based filtering** (`--tier tier3`, `--tier tier4`). Tests are organized into tiers so a per-task verification only runs the tier relevant to the change.
+- **Parallelization via xdist** — the runner wires `pytest-xdist` so independent test files execute concurrently.
+- **A summary table** at the end (per-tier pass/fail/skip counts) that direct `pytest` does not produce.
+
+Direct `pytest` is slow and bypasses the tiering that the `live_gui` tests (session-scoped subprocess tests) depend on for batch-isolation correctness.
+
+## Targeted vs full tier
+
+Prefer targeted tier runs:
+
+```bash
+uv run python scripts/run_tests_batched.py --tier tier3
+uv run python scripts/run_tests_batched.py --filter test_<specific_file>
+```
+
+The full 11-tier batch is for the USER to run after merge review, not for per-task verification. Running the full batch every time wastes 20+ minutes and the output is too large to be useful in context.
+
+## Output redirection (HARD RULE)
+
+NEVER filter test output. Do NOT pipe through `Select-Object`, `| Select -First N`, `| Select -Last N`, `head`, `tail`, or any truncation filter. ALWAYS redirect to a log file:
+
+```bash
+uv run python scripts/run_tests_batched.py > tests/artifacts/tier2_state/<track>/test_run_<phase>_<task>.log 2>&1
+```
+
+Then read the log file with `manual-slop_read_file` or `grep` to find the relevant sections. The log file is your full record; you can search it without re-running.