For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: A diff→(boards, tests) selector (test/hil/hil_select.py) that scopes CI's HIL build+test jobs on pull requests and is reusable locally, per docs/superpowers/specs/2026-07-29-hil-pr-scoped-selection-design.md.
Architecture: Pure-stdlib classification engine (changed files → per-board test selection, fail-open to full) + thin CLI emitting JSON with per-rig hil_test.py arg strings; consumed by hil_ci_set_matrix.py --select (prunes hil-build) and shell steps in the three HIL jobs (prunes rig runs). Test lists shared via new hil_examples.py.
Tech Stack: Python 3.11 stdlib only (re, json, glob, subprocess for git), unittest for tests, GitHub Actions YAML.
.claude/worktrees/hil-select (branch claude/hil-select); never touch the primary checkout.hil_select.py, hil_examples.py, test_hil_select.py import NOTHING outside the stdlib and each other — in particular never hil_test/hil_flash/hil_lock (GitHub's bare runner has no pyserial/pymtp).full: true. Scoping applies to pull_request events only; push/scheduled runs stay full.hil_test.py runtime behavior unchanged (only its test-list constants move to hil_examples.py); hil_ci_set_matrix.py without --select emits byte-identical output to today.config['boards']); boards-skip is invisible to it.python3 -m py_compile clean on touched python files, python3 test/hil/test_hil_select.py green (once it exists), pre-commit run --files <touched> clean.Files:
test/hil/hil_examples.pytest/hil/hil_select.py (engine only; CLI comes in Task 2)test/hil/test_hil_select.pytest/hil/hil_test.py (import test lists from hil_examples)test/hil/hil_ci.sh (scp list gains hil_examples.py)Interfaces:
Produces hil_examples.py: device_tests: list[str], dual_tests: list[str], host_test: list[str] — the three lists moved VERBATIM (incl. comments) from hil_test.py.
Produces hil_select.py engine API used by Task 2:
classify(changed_files: list[str], repo_root: str, rosters: list[tuple[str, list[dict]]]) -> dict returning {'full': bool, 'boards': {board_name: 'all' | sorted list[str]}, 'reasons': list[str]} where rosters = [(config_path, config['boards']), ...].board_roles(board: dict) -> set[str] — subset of {'device', 'host'} from the roster entry‘s tests flags (device/host/dual booleans; an only list contributes the roles of its entries’ path prefixes; dual implies both roles).board_family(board_name: str, repo_root: str) -> str | None — the <family> for which hw/bsp/<family>/boards/<board_name> exists.port_families(port_dir: str, repo_root: str) -> set[str] — directories of hw/bsp/*/family.cmake and hw/bsp/*/family.mk whose text contains port_dir (e.g. raspberrypi/rp2040).class_examples(class_dir: str, role: str, repo_root: str) -> set[str] — tests from hil_examples lists whose example tusb_config.h enables the class for that role (regex #define\s+CFG_TUD_<C>\s+\(?\s*0*[1-9] / CFG_TUH_<C>; exceptions per spec: dfu_rt_device.*→CFG_TUD_DFU_RUNTIME, dfu_device.*→CFG_TUD_DFU, class dir net → CFG_TUD_ECM_RNDIS|CFG_TUD_NCM). Test path device/x ⇒ config at examples/device/x/src/tusb_config.h; same pattern for host/ and dual/.[ ] Step 1: Move the test lists into hil_examples.py
Create test/hil/hil_examples.py:
#!/usr/bin/env python3 # SPDX-License-Identifier: MIT # HIL example test lists, shared by hil_test.py (runner) and hil_select.py # (PR-diff selector). Stdlib-only: hil_select runs on bare CI runners.
then MOVE the device_tests, dual_tests, host_test list definitions (and their preceding comment block “The per-board run order is shuffled...”) VERBATIM from hil_test.py into it. In hil_test.py, add from hil_examples import device_tests, dual_tests, host_test where the lists were (a from-import of data constants is fine here — they are read-only lists used by name throughout test_board). Add "$ROOT_DIR/test/hil/hil_examples.py" \ to the hil_ci.sh scp list after the hil_lock.py line.
Run: cd /home/hathach/code/tinyusb/.claude/worktrees/hil-select && python3 -m py_compile test/hil/hil_examples.py test/hil/hil_test.py && python3 test/hil/hil_test.py --help >/dev/null && echo ok Expected: ok
Create test/hil/test_hil_select.py. ROSTER is a trimmed but real-shaped fixture; tests call the engine API directly (no git, no CLI):
#!/usr/bin/env python3 # SPDX-License-Identifier: MIT # Unit tests for hil_select.py — pure logic, no hardware, no git. Run directly: # python3 test/hil/test_hil_select.py import os import sys import unittest sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) import hil_select from hil_examples import device_tests, dual_tests, host_test REPO = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) ROSTER = [ # device-only, rp2040 family {'name': 'raspberry_pi_pico', 'uid': 'u1', 'tests': {'device': True, 'host': True, 'dual': True}}, # device-only, stm32f4 family {'name': 'stm32f407disco', 'uid': 'u2', 'tests': {'device': True, 'host': False, 'dual': False}}, # host-only board {'name': 'raspberry_pi_pico2', 'uid': 'u3', 'tests': {'device': False, 'host': True, 'dual': False}}, # only-list board (espressif-style) {'name': 'espressif_s3_devkitm', 'uid': 'u4', 'tests': {'only': ['device/cdc_msc_freertos', 'host/device_info']}}, ] ROSTERS = [('test/hil/tinyusb.json', ROSTER)] def sel(files): return hil_select.classify(files, REPO, ROSTERS) class TestPortRule(unittest.TestCase): def test_dcd_rp2040_selects_pico_family_only(self): s = sel(['src/portable/raspberrypi/rp2040/dcd_rp2040.c']) self.assertFalse(s['full']) self.assertIn('raspberry_pi_pico', s['boards']) self.assertNotIn('stm32f407disco', s['boards']) self.assertNotIn('espressif_s3_devkitm', s['boards']) # device role: no host tests in pico's list self.assertTrue(all(not t.startswith('host/') for t in s['boards']['raspberry_pi_pico'])) # host-only boards drop out entirely on a device-role change self.assertNotIn('raspberry_pi_pico2', s['boards']) def test_shared_port_file_is_both_roles(self): s = sel(['src/portable/synopsys/dwc2/dwc2_common.c']) self.assertFalse(s['full']) self.assertNotIn('raspberry_pi_pico', s['boards']) # rp2040 is not a dwc2 family self.assertIn('stm32f407disco', s['boards']) # stm32f4 is class TestCoreRoleRule(unittest.TestCase): def test_usbd_selects_all_device_tests_everywhere(self): s = sel(['src/device/usbd.c']) self.assertFalse(s['full']) self.assertNotIn('raspberry_pi_pico2', s['boards']) # host-only board dropped pico = s['boards']['raspberry_pi_pico'] self.assertTrue(set(device_tests).issubset(set(pico))) self.assertTrue(set(dual_tests).issubset(set(pico))) # dual survives device role self.assertTrue(all(not t.startswith('host/') for t in pico)) # only-list board: selection intersects its only-list esp = s['boards']['espressif_s3_devkitm'] self.assertEqual(esp, ['device/cdc_msc_freertos']) def test_host_change_drops_device(self): s = sel(['src/host/usbh.c']) self.assertFalse(s['full']) self.assertIn('raspberry_pi_pico2', s['boards']) self.assertNotIn('stm32f407disco', s['boards']) # device-only board dropped class TestClassRule(unittest.TestCase): def test_cdc_device_selects_cdc_examples_only(self): s = sel(['src/class/cdc/cdc_device.c']) self.assertFalse(s['full']) pico = s['boards']['raspberry_pi_pico'] self.assertIn('device/cdc_msc', pico) self.assertIn('device/cdc_dual_ports', pico) self.assertNotIn('device/msc_dual_lun', pico) # CFG_TUD_CDC 0 there self.assertNotIn('device/usbtest', pico) # CFG_TUD_CDC 0 there self.assertTrue(all(not t.startswith('host/') for t in pico)) def test_msc_host_selects_host_side(self): s = sel(['src/class/msc/msc_host.c']) self.assertFalse(s['full']) self.assertNotIn('stm32f407disco', s['boards']) # device-only board pico2 = s['boards']['raspberry_pi_pico2'] self.assertIn('host/msc_file_explorer', pico2) self.assertTrue(all(not t.startswith('device/') for t in pico2)) class TestFallbackRules(unittest.TestCase): def test_unknown_tool_is_full(self): s = sel(['tools/random_new_script.py']) self.assertTrue(s['full']) def test_docs_only_is_empty_not_full(self): s = sel(['docs/info/contributing.rst', 'README.rst']) self.assertFalse(s['full']) self.assertEqual(s['boards'], {}) def test_bsp_family_selects_family_boards(self): s = sel(['hw/bsp/rp2040/family.cmake']) self.assertFalse(s['full']) self.assertIn('raspberry_pi_pico', s['boards']) self.assertEqual(s['boards']['raspberry_pi_pico'], 'all') self.assertNotIn('stm32f407disco', s['boards']) def test_bsp_board_narrows_to_board(self): s = sel(['hw/bsp/rp2040/boards/raspberry_pi_pico/board.h']) self.assertFalse(s['full']) self.assertEqual(list(s['boards'].keys()), ['raspberry_pi_pico']) def test_example_change_selects_that_example(self): s = sel(['examples/device/cdc_msc/src/main.c']) self.assertFalse(s['full']) self.assertEqual(s['boards']['raspberry_pi_pico'], ['device/cdc_msc']) def test_core_common_is_full(self): for f in ['src/tusb.c', 'src/common/tusb_fifo.c', 'src/osal/osal_freertos.h']: self.assertTrue(sel([f])['full'], f) def test_harness_is_full(self): for f in ['test/hil/hil_test.py', '.github/workflows/build.yml', 'hw/mcu/nxp/x.c', 'lib/foo/x.c']: self.assertTrue(sel([f])['full'], f) def test_mixed_roles_no_pruning(self): s = sel(['src/device/usbd.c', 'src/host/usbh.c']) self.assertFalse(s['full']) self.assertIn('raspberry_pi_pico2', s['boards']) self.assertIn('stm32f407disco', s['boards']) if __name__ == '__main__': unittest.main(verbosity=1)
Run: python3 test/hil/test_hil_select.py 2>&1 | tail -2 Expected: ModuleNotFoundError: No module named 'hil_select' (or import error).
Create test/hil/hil_select.py:
#!/usr/bin/env python3 # SPDX-License-Identifier: MIT """PR-diff -> HIL selection: which rig boards and which tests a change can affect. Stdlib-only (runs on bare CI runners; never imports hil_test/hil_flash/hil_lock). Fail-open: any file no rule classifies forces the full matrix. See docs/superpowers/specs/2026-07-29-hil-pr-scoped-selection-design.md. """ import argparse import glob import json import os import re import subprocess import sys from hil_examples import device_tests, dual_tests, host_test ALL_TESTS = {'device': device_tests, 'dual': dual_tests, 'host': host_test} # class dir -> config macro suffix exceptions (rule 3); dfu is per-file, handled inline NET_MACROS = ('ECM_RNDIS', 'NCM') _NONCODE_RE = re.compile( r'^(docs/|\.claude/|.*\.(md|rst|txt)$|LICENSE)') _FULL_RE = re.compile( r'^(src/common/|src/osal/|src/tusb\.c$|src/tusb\.h$|src/tusb_option\.h$|' r'test/hil/|\.github/workflows/build.*\.yml$|\.github/actions/|' r'tools/build\.py$|tools/get_deps\.py$|tools/cmake/|hw/mcu/|lib/|' r'hw/bsp/(family_support\.cmake|board_api\.h|board\.c|ansi_escape\.h)$|' r'examples/build_system/|examples/CMakeLists\.txt$)') def test_role(test: str) -> str: return test.split('/', 1)[0] # 'device' | 'dual' | 'host' def board_roles(board: dict) -> set: t = board.get('tests', {}) roles = set() if t.get('device'): roles.add('device') if t.get('host'): roles.add('host') if t.get('dual'): roles.update(('device', 'host')) for only in t.get('only', []): r = test_role(only) roles.update(('device', 'host') if r == 'dual' else (r,)) return roles def board_tests(board: dict) -> list: """Every test this board would run today (mirrors hil_test.test_board's default).""" t = board.get('tests', {}) if 'only' in t: run = list(t['only']) else: run = [] if t.get('device'): run += device_tests if t.get('dual'): run += dual_tests if t.get('host'): run += host_test return [x for x in run if x not in t.get('skip', [])] def board_family(board_name: str, repo_root: str): hits = glob.glob(os.path.join(repo_root, 'hw/bsp/*/boards', board_name)) return os.path.basename(os.path.dirname(os.path.dirname(hits[0]))) if hits else None def port_families(port_dir: str, repo_root: str) -> set: fams = set() for f in glob.glob(os.path.join(repo_root, 'hw/bsp/*/family.cmake')) + \ glob.glob(os.path.join(repo_root, 'hw/bsp/*/family.mk')): try: if port_dir in open(f).read(): fams.add(os.path.basename(os.path.dirname(f))) except OSError: pass return fams def _config_enables(cfg_path: str, macros) -> bool: try: text = open(cfg_path).read() except OSError: return False return any(re.search(rf'#define\s+{m}\s+\(?\s*0*[1-9]', text) for m in macros) def class_examples(macros, role: str, repo_root: str) -> set: """Tests (from role's + dual lists) whose example config enables any macro.""" pools = {'device': device_tests + dual_tests, 'host': host_test + dual_tests} out = set() for test in pools[role]: cfg = os.path.join(repo_root, 'examples', test, 'src', 'tusb_config.h') if _config_enables(cfg, macros): out.add(test) return out class _Sel: """Accumulates contributions. board->set(tests) plus 'all-board' markers.""" def __init__(self): self.full = False self.by_board = {} # name -> set of tests, or 'all' self.roles = set() # roles touched by any contribution self.reasons = [] def add(self, boards, tests, reason): """tests: 'all' or iterable of test paths.""" self.reasons.append(reason) for b in boards: cur = self.by_board.get(b) if tests == 'all' or cur == 'all': self.by_board[b] = 'all' else: self.by_board[b] = (cur or set()) | set(tests) def force_full(self, reason): self.full = True self.reasons.append(reason) def _classify_one(path, repo_root, roster_boards, s: _Sel): base = os.path.basename(path) if _NONCODE_RE.match(path): s.reasons.append(f'{path}: non-code, no contribution') return if _FULL_RE.match(path): s.force_full(f'{path}: core/infra -> full matrix') return m = re.match(r'src/portable/((?:[^/]+/)?[^/]+)/', path) if m: port = m.group(1) if re.match(r'(dcd_|.*_device)', base): roles = {'device'} elif re.match(r'(hcd_|.*_host)', base): roles = {'host'} else: roles = {'device', 'host'} fams = port_families(port, repo_root) boards = [b['name'] for b in roster_boards if board_family(b['name'], repo_root) in fams and (board_roles(b) & roles)] tests = [t for r in roles for t in ALL_TESTS[r]] + dual_tests s.roles.update(roles) s.add(boards, tests, f'{path}: port {port} -> families {sorted(fams)} -> boards {boards} ({"/".join(sorted(roles))})') return m = re.match(r'src/class/([^/]+)/', path) if m: cls = m.group(1) if re.search(r'_device\.[ch]$', base): roles = {'device'} elif re.search(r'_host\.[ch]$', base): roles = {'host'} else: roles = {'device', 'host'} # macro names per role def macros(prefix): if cls == 'net': return [f'CFG_{prefix}_{m2}' for m2 in NET_MACROS] if cls == 'dfu': if base.startswith('dfu_rt'): return [f'CFG_{prefix}_DFU_RUNTIME'] if base.startswith('dfu_device') or base.startswith('dfu_host'): return [f'CFG_{prefix}_DFU'] return [f'CFG_{prefix}_DFU', f'CFG_{prefix}_DFU_RUNTIME'] return [f'CFG_{prefix}_{cls.upper()}'] tests = set() if 'device' in roles: tests |= class_examples(macros('TUD'), 'device', repo_root) if 'host' in roles: tests |= class_examples(macros('TUH'), 'host', repo_root) boards = [b['name'] for b in roster_boards if board_roles(b) & roles] s.roles.update(roles) s.add(boards, tests, f'{path}: class {cls} -> {sorted(tests)} ({"/".join(sorted(roles))})') return m = re.match(r'src/(device|host)/', path) if m: role = m.group(1) boards = [b['name'] for b in roster_boards if role in board_roles(b)] s.roles.add(role) s.add(boards, ALL_TESTS[role] + dual_tests, f'{path}: core {role} stack -> all {role} tests') return m = re.match(r'hw/bsp/([^/]+)/(?:boards/([^/]+)/)?', path) if m: fam, brd = m.group(1), m.group(2) if brd: boards = [b['name'] for b in roster_boards if b['name'] == brd] why = f'{path}: bsp board {brd}' else: boards = [b['name'] for b in roster_boards if board_family(b['name'], repo_root) == fam] why = f'{path}: bsp family {fam}' s.roles.update(('device', 'host')) s.add(boards, 'all', f'{why} -> boards {boards}') return m = re.match(r'examples/(device|host|dual)/([^/]+)/', path) if m: test = f'{m.group(1)}/{m.group(2)}' known = any(test in pool for pool in ALL_TESTS.values()) if known: boards = [b['name'] for b in roster_boards] role = test_role(test) s.roles.update(('device', 'host') if role == 'dual' else (role,)) s.add(boards, [test], f'{path}: example -> {test} on all boards') else: s.reasons.append(f'{path}: example not in HIL lists, no contribution') return s.force_full(f'{path}: unclassified -> full matrix') def classify(changed_files, repo_root, rosters): all_boards = [] seen = set() for _, boards in rosters: for b in boards: if b['name'] not in seen: seen.add(b['name']) all_boards.append(b) s = _Sel() for path in changed_files: _classify_one(path, repo_root, all_boards, s) if s.full: break if s.full: return {'full': True, 'boards': {b['name']: 'all' for b in all_boards}, 'reasons': s.reasons} # role pruning: single-role selections drop the other role's tests and boards by_name = {b['name']: b for b in all_boards} out = {} for name, tests in s.by_board.items(): allowed = board_tests(by_name[name]) if tests == 'all': kept = list(allowed) else: kept = [t for t in allowed if t in tests] if s.roles and s.roles != {'device', 'host'}: role = next(iter(s.roles)) kept = [t for t in kept if test_role(t) in (role, 'dual')] if kept: out[name] = 'all' if set(kept) == set(allowed) else sorted(kept) return {'full': False, 'boards': out, 'reasons': s.reasons}
Run: python3 test/hil/test_hil_select.py Expected: all tests PASS (OK line). Iterate on the engine (not the tests) until green; if a test premise contradicts the repo (e.g. a family name), verify against the tree and fix the test only with evidence noted in your report.
git add test/hil/hil_examples.py test/hil/hil_select.py test/hil/test_hil_select.py test/hil/hil_test.py test/hil/hil_ci.sh git commit -m "hil: add PR-diff selection engine (hil_select) with shared example lists"
Files:
test/hil/hil_select.py (add selection_args, main)test/hil/test_hil_select.py (add CLI/args tests)Interfaces:
Consumes: Task 1's classify and roster shapes.
Produces:
selection_args(sel: dict, rosters) -> dict mapping each config path‘s basename to the hil_test.py argument string for that rig: for each selected board ON that roster, -b <name>, plus -bt <name>:<t1>,<t2> when the board’s entry is a list (not ‘all’). Empty string when no selected board is on that roster. When sel['full'], every roster board gets bare -b? NO — full means “today's behavior”: selection_args returns '' for every config (no filtering args at all).python3 test/hil/hil_select.py [--base REF | --diff-file PATH] CONFIG... printing the JSON {'full', 'boards', 'args', 'reasons'} to stdout, reasons also to stderr (one line each, prefixed hil_select: ). Non-zero exit only on operational errors (bad ref, unreadable config) — never on an empty selection.[ ] Step 1: Add failing CLI/args tests to test_hil_select.py
class TestArgsEmission(unittest.TestCase): def test_args_for_scoped_selection(self): s = sel(['src/portable/raspberrypi/rp2040/dcd_rp2040.c']) args = hil_select.selection_args(s, ROSTERS) a = args['tinyusb.json'] self.assertIn('-b raspberry_pi_pico', a) self.assertNotIn('stm32f407disco', a) self.assertIn('-bt raspberry_pi_pico:', a) # device-only subset of a device+host board def test_args_full_is_empty(self): s = sel(['tools/random_new_script.py']) self.assertEqual(hil_select.selection_args(s, ROSTERS), {'tinyusb.json': ''}) def test_args_all_board_gets_bare_b(self): s = sel(['hw/bsp/rp2040/boards/raspberry_pi_pico/board.h']) a = hil_select.selection_args(s, ROSTERS)['tinyusb.json'] self.assertIn('-b raspberry_pi_pico', a) self.assertNotIn('-bt', a) def test_cli_diff_file(self): import subprocess, tempfile, json as j with tempfile.NamedTemporaryFile('w', suffix='.txt', delete=False) as f: f.write('src/class/cdc/cdc_device.c\n') path = f.name r = subprocess.run([sys.executable, os.path.join(REPO, 'test/hil/hil_select.py'), '--diff-file', path, os.path.join(REPO, 'test/hil/tinyusb.json')], capture_output=True, text=True) self.assertEqual(r.returncode, 0, r.stderr) out = j.loads(r.stdout) self.assertFalse(out['full']) self.assertIn('tinyusb.json', out['args']) self.assertTrue(any('cdc_device' in line for line in out['reasons'])) os.unlink(path)
Run: python3 test/hil/test_hil_select.py 2>&1 | tail -3 Expected: failures/errors mentioning selection_args.
selection_args and mainAppend to hil_select.py:
def selection_args(sel, rosters): args = {} for cfg_path, boards in rosters: key = os.path.basename(cfg_path) if sel['full']: args[key] = '' continue parts = [] for b in boards: chosen = sel['boards'].get(b['name']) if chosen is None: continue parts.append(f'-b {b["name"]}') if chosen != 'all': parts.append(f'-bt {b["name"]}:{",".join(chosen)}') args[key] = ' '.join(parts) return args def changed_files_from_git(base, repo_root): mb = subprocess.run(['git', 'merge-base', 'HEAD', base], cwd=repo_root, capture_output=True, text=True, check=True).stdout.strip() diff = subprocess.run(['git', 'diff', '--name-only', f'{mb}..HEAD'], cwd=repo_root, capture_output=True, text=True, check=True).stdout return [l for l in diff.splitlines() if l.strip()] def main(): ap = argparse.ArgumentParser(description=__doc__) g = ap.add_mutually_exclusive_group(required=True) g.add_argument('--base', help='git ref to diff against (merge-base..HEAD)') g.add_argument('--diff-file', help='newline-separated changed-file list') ap.add_argument('configs', nargs='+', help='rig roster JSON file(s)') a = ap.parse_args() repo_root = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) rosters = [] for c in a.configs: with open(c) as f: rosters.append((c, json.load(f)['boards'])) files = (open(a.diff_file).read().splitlines() if a.diff_file else changed_files_from_git(a.base, repo_root)) files = [f for f in files if f.strip()] s = classify(files, repo_root, rosters) s['args'] = selection_args(s, rosters) for r in s['reasons']: print(f'hil_select: {r}', file=sys.stderr) print(json.dumps(s)) if __name__ == '__main__': main()
(The parts.append f'...' line above is pseudo-highlighted; write valid Python: parts.append(f'-bt {b["name"]}:{",".join(chosen)}').)
Run: python3 test/hil/test_hil_select.py && chmod +x test/hil/hil_select.py Expected: OK.
Run: python3 test/hil/hil_select.py --base HEAD test/hil/tinyusb.json test/hil/hfp.json Expected: empty diff ⇒ {"full": false, "boards": {}, "args": {"tinyusb.json": "", "hfp.json": ""}, ...} exit 0. Then: printf 'src/portable/wch/dcd_ch32_usbfs.c\n' > /tmp/d.txt && python3 test/hil/hil_select.py --diff-file /tmp/d.txt test/hil/tinyusb.json | python3 -m json.tool | head -20 Expected: only WCH-family boards (nanoch32v203, ch32v103r_r1_1v0, ch32v307v_r1_1v0 — whichever reference that port) with device tests.
git add test/hil/hil_select.py test/hil/test_hil_select.py git commit -m "hil: hil_select CLI with per-rig hil_test argument emission"
Files:
test/hil/hil_ci_set_matrix.py.github/workflows/build.yml (set-matrix job; hil-build consumers unchanged; hil-tinyusb + hil-tinyusb-esp steps)Interfaces:
Consumes: Task 2's CLI JSON (full, boards, args).
Produces:
hil_ci_set_matrix.py [--select JSON_STRING] CONFIG...: with --select and full == false, boards not in select['boards'] are skipped when building the toolchain buckets; otherwise identical behavior. Buckets stay present (possibly []) so fromJSON(...)[toolchain] keeps resolving.hil_select_json (compact selection), hil_args_tinyusb, hil_args_hfp, hil_run_tinyusb, hil_run_hfp (string ‘true’/‘false’).[ ] Step 1: Add --select to hil_ci_set_matrix.py
In main() add:
parser.add_argument('--select', help='hil_select.py JSON; scopes boards when full=false')
and after parsing:
selected = None sel = json.loads(args.select) if args.select else None if sel and not sel.get('full'): selected = set(sel.get('boards', {}))
then inside the per-board loop, first line:
if selected is not None and board['name'] not in selected: continue
Run: python3 test/hil/hil_ci_set_matrix.py test/hil/tinyusb.json test/hil/hfp.json > /tmp/m1.json && git stash -q && python3 test/hil/hil_ci_set_matrix.py test/hil/tinyusb.json test/hil/hfp.json > /tmp/m0.json && git stash pop -q && diff /tmp/m0.json /tmp/m1.json && echo identical Expected: identical. Then: python3 test/hil/hil_ci_set_matrix.py --select '{"full": false, "boards": {"raspberry_pi_pico": "all"}}' test/hil/tinyusb.json test/hil/hfp.json Expected: JSON whose arm-gcc list contains only the raspberry_pi_pico entry, riscv-gcc/esp-idf = [].
.github/workflows/build.ymlIn the set-matrix job: give the checkout full history and add the selection step between checkout and matrix generation; make the HIL matrix use it:
- name: Checkout TinyUSB uses: actions/checkout@v6 with: fetch-depth: 0 - name: HIL selection (PR only) id: hil-select if: github.event_name == 'pull_request' run: | python3 test/hil/test_hil_select.py SELECT_JSON=$(python3 test/hil/hil_select.py --base "origin/${{ github.base_ref }}" test/hil/tinyusb.json test/hil/hfp.json) echo "select=$SELECT_JSON" >> $GITHUB_OUTPUT python3 - "$SELECT_JSON" >> $GITHUB_OUTPUT <<'EOF' import json, sys s = json.loads(sys.argv[1]) args = s.get('args', {}) for cfg, key in (('tinyusb.json', 'tinyusb'), ('hfp.json', 'hfp')): a = args.get(cfg, '') run = 'true' if (s['full'] or a) else 'false' print(f'args_{key}={a}') print(f'run_{key}={run}') EOF
and in the existing “Generate matrix json” step, change the HIL line to:
# HIL matrix (merged from tinyusb + hifiphile configs), scoped on PRs SELECT='${{ steps.hil-select.outputs.select }}' HIL_MATRIX_JSON=$(python test/hil/hil_ci_set_matrix.py ${SELECT:+--select "$SELECT"} test/hil/tinyusb.json test/hil/hfp.json)
Add to the job's outputs: block:
hil_args_tinyusb: ${{ steps.hil-select.outputs.args_tinyusb }} hil_args_hfp: ${{ steps.hil-select.outputs.args_hfp }} hil_run_tinyusb: ${{ steps.hil-select.outputs.run_tinyusb }} hil_run_hfp: ${{ steps.hil-select.outputs.run_hfp }}
(On non-PR events the step is skipped: outputs are empty strings — the consumers below treat empty run_* as ‘true’ and empty args as no filtering, i.e. today's behavior.)
In the hil-tinyusb job (the matrixed one covering both rigs), find the step that runs hil_test.py --retry 1 ${{ matrix.test_args }} ${{ env.HIL_JSON }} $RERUN_ARGS (~line 360) and change the step's run: to select per-rig args and honor the skip flag:
run: | case "$HIL_JSON" in *tinyusb.json) SEL_ARGS='${{ needs.set-matrix.outputs.hil_args_tinyusb }}'; SEL_RUN='${{ needs.set-matrix.outputs.hil_run_tinyusb }}' ;; *hfp.json) SEL_ARGS='${{ needs.set-matrix.outputs.hil_args_hfp }}'; SEL_RUN='${{ needs.set-matrix.outputs.hil_run_hfp }}' ;; esac if [ "$SEL_RUN" = "false" ]; then echo "HIL skipped by PR selection (no affected boards on this rig)"; exit 0; fi python3 test/hil/hil_test.py --retry 1 ${{ matrix.test_args }} $SEL_ARGS ${{ env.HIL_JSON }} $RERUN_ARGS
Apply the same pattern to the second hil_test.py invocation at ~line 423 (hil-tinyusb-esp, which is tinyusb-rig only: use the hil_args_tinyusb/hil_run_tinyusb outputs directly, no case needed) and to the hfp job‘s direct python3 test/hil/hil_test.py hfp.json call at ~line 487 (use hil_args_hfp/hil_run_hfp). Preserve each step’s existing surrounding lines (report-dir env, RERUN_ARGS logic) — only inject the SEL_ARGS/SEL_RUN mechanics.
Run: pre-commit run check-yaml --files .github/workflows/build.yml && python3 -c "import yaml; yaml.safe_load(open('.github/workflows/build.yml')); print('yaml ok')" Expected: yaml ok (pyyaml is available; if not, pip install --user pyyaml first). Also simulate the selection step's python inline script: SELECT_JSON=$(python3 test/hil/hil_select.py --diff-file /tmp/d.txt test/hil/tinyusb.json test/hil/hfp.json) && python3 -c "import json,sys; s=json.loads(sys.argv[1]); print(s['args'])" "$SELECT_JSON" Expected: the args dict prints.
git add test/hil/hil_ci_set_matrix.py .github/workflows/build.yml git commit -m "ci: scope HIL build+test matrix by PR diff via hil_select"
Files:
.claude/skills/pre-pr/SKILL.md (mapping section delegates to the selector).claude/skills/hil/SKILL.md (document the selector for manual runs)Interfaces:
Consumes: Task 2's CLI.
[ ] Step 1: Rewrite pre-pr's “2. Map changes to boards” section
Replace the section's grep heuristics (keep its numbered-section structure and the roster/cap policy) with:
## 2. Map changes to boards - `python3 test/hil/hil_select.py --base $BASE test/hil/tinyusb.json` → JSON with the affected rig boards (`boards`) and per-file `reasons`. `full: true` means a broad/infra change. - Build-board sampling: from the selection's boards (or, when `full`, the representative set `stm32f407disco` + `raspberry_pi_pico`), pick ONE board per family, preferring rig-roster boards; cap at 4 and tell the user which families the cap dropped. The boards list must NEVER end up empty — final fallback is `[stm32f407disco]`. - A `full: true` selection or an empty one (docs-only) keeps today's behavior: minimal software-only gate for docs-only, representative set otherwise.
Append to .claude/skills/hil/SKILL.md after the pool-check section:
## PR-scoped selection `test/hil/hil_select.py` maps a diff to affected boards/tests (used by CI on PRs; fail-open to the full matrix). Manual use: ```bash ARGS=$(python3 test/hil/hil_select.py --base master test/hil/tinyusb.json | python3 -c "import json,sys; print(json.load(sys.stdin)['args']['tinyusb.json'])") python3 test/hil/hil_test.py -B examples $ARGS test/hil/tinyusb.json
Unit suite: python3 test/hil/test_hil_select.py (no hardware).
- [ ] **Step 3: Full validation sweep** Run: `python3 test/hil/test_hil_select.py && python3 -m py_compile test/hil/hil_select.py test/hil/hil_examples.py test/hil/hil_ci_set_matrix.py test/hil/hil_test.py && python3 test/hil/hil_test.py --help >/dev/null && pre-commit run --files $(git diff --name-only claude/hil-pool-check..HEAD) && echo ALL-GREEN` Expected: `ALL-GREEN`. - [ ] **Step 4: Real-diff spot checks (acceptance)** Run each and eyeball the JSON (record outputs in your report): ```bash for f in 'src/portable/raspberrypi/rp2040/dcd_rp2040.c' 'src/device/usbd.c' 'src/class/cdc/cdc_device.c' 'src/host/usbh.c'; do printf '%s\n' "$f" > /tmp/d.txt echo "=== $f"; python3 test/hil/hil_select.py --diff-file /tmp/d.txt test/hil/tinyusb.json test/hil/hfp.json 2>/dev/null | python3 -m json.tool | sed -n '1,25p' done
Expected: matches the spec's acceptance examples (pico-family only / all-device / CDC examples only / host side only, with hfp.json args populated only where hfp boards qualify).
git add .claude/skills/pre-pr/SKILL.md .claude/skills/hil/SKILL.md git commit -m "docs: pre-pr and hil skill use hil_select for PR-scoped boards"