fix(session-handoff): restore Python 3.9 compatibility in scripts

[viktorkostetskyy-max]

Summary

skills/session-handoff/scripts/list_handoffs.py and check_staleness.py use PEP 604 union syntax (X | None) in function annotations, which requires Python 3.10+. On macOS, the system /usr/bin/python3 is Python 3.9.6 (Apple-shipped), so both scripts fail at import time before reaching main():

$ python3 .claude/skills/session-handoff/scripts/list_handoffs.py
Traceback (most recent call last):
  File ".../list_handoffs.py", line 54, in <module>
    def parse_date_from_filename(filename: str) -> datetime | None:
TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'

The skill's SKILL.md instructs users to invoke python / python3, so they hit this on a stock macOS install with no extra toolchain.

Fix

Add from __future__ import annotations to defer annotation evaluation. Minimal, non-invasive — no signatures change, no behavioral change on 3.10+.

The scripts don't use runtime annotation introspection (no typing.get_type_hints, no inspect.signature(...).return_annotation evaluation), so deferred annotations are safe here.

create_handoff.py and validate_handoff.py were already 3.9-compatible because they only use PEP 585 lower-case generics (list[str], tuple[bool, str]), which 3.9 supports.

Files changed

• skills/session-handoff/scripts/list_handoffs.py (source)
• skills/session-handoff/scripts/check_staleness.py (source)
• dist/plugins/session-handoff/skills/session-handoff/scripts/list_handoffs.py (regenerated via python3 scripts/build_plugins.py)
• dist/plugins/session-handoff/skills/session-handoff/scripts/check_staleness.py (same)

8 insertions, 0 deletions.

Test plan

• python3 --version → Python 3.9.6 (macOS stock)
• python3 list_handoffs.py → runs (no TypeError); prints handoff list
• python3 check_staleness.py <handoff-file> → runs; prints staleness report with FRESH/SLIGHTLY_STALE/STALE/VERY_STALE verdict
• python3 create_handoff.py test → still works (regression check)
• python3 validate_handoff.py <file> → still works (regression check)
• All four scripts also tested on Python 3.11 (Homebrew) — unchanged behavior
• dist/ regenerated from skills/ via scripts/build_plugins.py — tree clean, no extra changes

🤖 Generated with Claude Code