[kandrosov]

Summary

FLAF side of multi-era change set C (cms-flaf/StatInference#32). The StatInference tasks now take several eras, as a workflow without era branches: the card workflows have one branch per card, and each card may read several eras. This PR documents that second model next to the first, and gives such a workflow its own error for an era-numbered --branches selection; the old error advised --era <era> --branches <local>, which does not apply to a card that needs several eras.

Merge after cms-flaf/StatInference#32 and the HH_bbWW PR that advances its StatInference gitlink, so that the docs describe what the analyses run.

Changes

• run_tools/law_customizations.py _check_branch_selection: over several eras, a workflow without era branches given a number of 1 000 000 or more raises BranchSelectionError stating that its branches keep their own numbers. test/test_era_branches.py asserts the message; the test fails on the old message.
• Docs:
  • concepts/eras.md: the StatInference tasks under "Which tasks take several eras". This covers the card rule, paths and job state per configuration rather than per --era, jobs carrying the whole --era, the workflow's own branch numbers, one configuration per --version, and the settings that must agree. The one-era statements are now limited to stages with era branches.
  • troubleshooting.md: the new message the cards of <configuration> need … with its exit paths (60 at construction for the entry tasks; 50 or 60 for a card workflow started directly), and the new selection message. StatInference is no longer listed as taking one era.
  • reference/tasks.md, workflow/walkthrough.md (the example now passes the four eras), workflow/arguments.md, concepts/tasks-and-law.md.
  • contributing.md: how to write a workflow over several eras without era branches.
• .github/copilot-instructions.md: the second model and what to flag in it.

Testing

• FLAF's unit list (the 27 files of unit-tests.yaml): 972 passed on 4e01825, with Python 3.13 and only pyyaml, luigi 3.8.1, law 0.1.21 and pytest (env -i).
• mkdocs build --strict: OK.
• flaf-tester, run_ci_test.sh <ana> Run3_2022 htcondor, in isolated trees with FLAF 4e01825. The analyses were at their main, with their pinned Corrections 47958b7 and StatInference 31b4c6a. In H_mumu's bundled code, law_customizations.py was checked byte-identical to 4e01825.
  • TESTER VERDICT: PASS — HH_bbtautau (FLAF 4e01825, version ci_htcondor_20261019_095925)
  • TESTER VERDICT: PASS — HH_bbWW (FLAF 4e01825, version ci_htcondor_20261019_095925)
  • TESTER VERDICT: PASS — H_mumu (FLAF 4e01825, version ci_htcondor_20261019_095925)
  • The chains exercise _check_branch_selection only on the path that must not break; the new error itself is covered by the unit test.
• flaf-reviewer:
  • round 1: 2 blocking issues. The docs claimed a keep_alive wait that does not occur (the real runs exit with 50 or 60), and several pages, the walkthrough among them, still showed one-era StatInference examples. Both were fixed.
  • round 2: REVIEWER OK for 4e01825 + 021ddb5.
  • 7c2b187 differs from 021ddb5 only in the qualifiers the review suggested ("stages with era branches" in four places).
• Every documented exit path was run for real by the StatInference#32 gate on HH_bbWW's law.cfg: RC 60 at construction, RC 50 for local scheduling, RC 60 over htcondor.