ci(tools): parse the run steps of composite actions in the run-syntax gate

[gHashTag]

Closes #854. Stacked on #893 — merge #893 first; until then this diff also shows #893's commit (54020cd).

What was wrong

tools/check_run_syntax.py globbed .github/workflows/*.yml|yaml and nothing else. #852 adds the repo's first composite action (.github/actions/openxc7-chipdb/action.yml), called by 53 jobs, and a run step in it that does not parse would have passed the gate.

What changes

• Composite actions under .github/actions/** (action.yml or action.yaml, any depth) are read like workflows: bash -n per shell, plus the single-quoted bash -c '...' scripts inside each step, through one check_run() shared with workflow steps.
• A composite run: step must name shell: (GitHub requires it there; there are no job or workflow defaults in an action). One that does not is cannot tell, rc 2.
• The runner is the caller's: every job that uses: the action directly or through other local actions; a cycle of actions ends. A macOS-possible caller under a gate whose bash is not 3.x is cannot tell, the same rule as for workflow steps.
• An action no workflow calls is still parsed. Node and Docker actions have no run: steps and are skipped.
• Output line: workflows read: X of Y; actions read: A of B (U with no caller here); ....

Measured

	result
self-test, laptop (bash 3.2)	98 of 98 (23 new: 19 one-tree action cases, 4 direct)
mutants of the new code	17 of 18 killed; survivor has_actions = True is equivalent (rglob of a missing directory is empty)
this branch's tree	122 of 122 workflows, 0 of 0 actions, rc 0
#852's tree (30b2919), as is	120 of 120 workflows, 1 of 1 actions, 20 inner scripts, 0 bad, rc 0
#852's tree with an unclosed " planted in the action's last step	new gate rc 1, gate at 54020cd rc 0
callers of openxc7-chipdb on #852's tree	53 jobs, ubuntu-22.04 / ubuntu-latest, 0 macOS-possible

Mutants killed: no action glob · one-level glob · action.yml only · no macOS caller check · macOS callers never found · no transitive callers · no cycle guard (RecursionError) · no shell requirement · uncalled actions skipped · trailing / kept in uses: · every action treated as composite · four cannot-tell returns turned into skips · action findings dropped · action cannot-tells dropped.

The laptop's bash is 3.2, so the macOS-caller cases in the one-tree list expect rc 1 there and rc 2 on CI (bash 5); four direct cases pin the bash 5 answer on any machine.

Not changed here

• .github/actions/** is not added to this gate's paths:: no tracked file matches it on main yet, and the workflow-path gate rejects that entry (measured: audit_workflow_paths.py rc 1 with it, rc 0 without). It is added in fix(ci): key the chipdb cache on the openXC7 image so it can hit #852 (0c5f415), which creates the directory. The same commit makes ax7203-led-onehot.yml run when the action changes: none of the action's 46 calling workflows watched .github/actions/, so an action-only change ran nothing.
• Checks red here and on ci(tools): parse the scripts inside single-quoted bash -c arguments #893 alike, inherited from main at 57de4a1: doc-refs, orphan-artefacts, and gates-can-fail (which cannot test those two while they already fail on a clean tree). fix(gates): green doc-refs and orphan-artefacts on main after #510 #872 fixes the first two.

Not measured

• The tee-pipefail gate (tools/check_tee_pipefail.py) still reads workflows only. In a composite action shell: bash already carries -o pipefail, so the gap is shell: sh or a custom bash {0} with | tee; no action in any tree here has one. Not fixed in this PR.
• A Windows caller's Git Bash is not modelled; an action step is checked with the gate's own bash.

🤖 Generated with Claude Code

[github-actions]

X Brain Health Check

Score: 100.0/100
Status: 🟢 HEALTHY
Threshold: 80/100

X Brain is above merge threshold

[github-actions]

🧪 Brain Stress Test Results

Score: not measured (no stress test prints a Score: line)
Status: 🟢 PASS
Threshold: 270/300

X Stress test passed

[tri-claw]

Summary by t27-bees

The PR extends the run-syntax gate to also parse run: steps in composite actions under .github/actions/**. It extracts and checks single-quoted bash -c '...'/sh -c '...' scripts inside those steps (and workflow steps), resolves transitive callers to determine the runner (macOS vs Linux), and requires composite run: steps to declare shell:.

Worth a look

• tools/check_run_syntax.py:85-130 (inner_scripts) — The SPLICE regex only matches "...", ${...}, and $VAR. It does not match $(cmd), `cmd`, $((arith)), or parameter expansions like ${var:-default}. A script like bash -c 'echo '$(date)'' will be reported as “glued to $” → cannot tell (rc 2), even though it is valid bash.

• tools/check_run_syntax.py:195-210 (action_callers) — jobs_of recurses with frozenset for cycle detection, but direct.get(rel, []) returns the same list object for every caller. If a job calls multiple actions, that job dict appears in multiple action’s caller lists. Not a bug now, but mutating those dicts later would cross-contaminate.

• tools/check_run_syntax.py:212-245 (check_action) — Calls _shell_named(step, {}, {}) with empty job/workflow dicts. _shell_named currently ignores them, but shell_of (used for workflows) does read job/workflow defaults. If _shell_named is ever updated to support defaults, composite actions will silently lose that behavior.

• tools/check_run_syntax.py:260-270 (main) — actions_root.rglob("action.yml") + rglob("action.yaml") will process both files if they coexist in the same directory. GitHub Actions permits only one; the tool would check both and report duplicate errors.

• tools/test_check_run_syntax.py:326 — run_case mutates module globals crs.ROOT and crs.WORKFLOWS. Tests run sequentially so it works today, but any future parallel test runner or reordering would cause cross-test pollution.

---

_{Read: 3 files, +326 -12, the whole diff. Head b335f27. Model: openai-compatible/nvidia/nemotron-3-ultra-550b-a55b. Commands: @t27-bees review | summary | help | pause | resume. Free for every repository.}