[bassilkhilo-ag2]

Summary

• Adds scripts/check-py39-union-annotations.py: AST-based CI gate that scans src/ and skills/ for PEP-604 X | Y union annotations used in annotation positions (variable annotations, function return types, argument annotations) without from __future__ import annotations — the root cause of the fix(telegram-bridge): from __future__ import annotations — fixes py3.9 crash #960 telegram-bridge outage on Python 3.9
• Wires the check into .github/workflows/ci.yml alongside the existing UTC timestamp gate (runs before Node deps install — no deps needed)
• Fixes the 5 violations found in skills/deal-finder/scripts/scan.py by adding the __future__ import
• 14/14 structural tests in tests/check-py39-union-annotations.test.py covering AST detection, file-level guard, CLI exit codes

What the gate catches

def foo(x: str | None) -> int | None:   # ← FLAGGED (no __future__)
    pass

from __future__ import annotations
def foo(x: str | None) -> int | None:   # ← OK (runtime-safe on 3.9)
    pass

x = flags | NEW_FLAG                    # ← OK (non-annotation BitOr)

Test plan

• python3 scripts/check-py39-union-annotations.py → Results: 52 Python files checked, 0 violations.
• python3 tests/check-py39-union-annotations.test.py -v → 14/14 pass
• CI step added after UTC timestamp check, before Node setup

Closes #961

🤖 Generated with Claude Code

[VasiliyRad]

Clean. Script is stdlib-only AST-based, correctly distinguishes annotation BitOr from expression BitOr, file-level future guard works as expected. CI wiring is a pure additive step in the right slot (pre-Node, no deps), no conflict with #1181's cwd-lint step. Fixing the deal-finder violation in the same PR is the right call. 14/14 tests cover the meaningful edge cases. Good to go.

[VasiliyRad]

Solid CI gate. AST walk correctly scopes BitOr detection to annotation positions (AnnAssign, function returns, all arg kinds), early-exits on from __future__ import annotations, and surfaces file:line violations with a fix hint. Bundled deal-finder/scripts/scan.py patch presumably adds the __future__ line to clear the gate — appropriate companion change.

Nit (non-blocking): hits.append(node.col_offset and node.lineno or node.lineno) in annotation_union_lines for the AnnAssign case is equivalent to plain hits.append(node.lineno) — col_offset and … only filters when col_offset is 0, which can't happen for a real statement. Won't affect output, just dead idiom. Otherwise clean.

Scope: only src/ + skills/ scanned. Defensible since the original outage was in src/, but worth widening to scripts/ + tests/ later if a similar regression slips through.

LGTM 👍