feat(phase3-A): PostToolUse relevance detector + session-state protocol

[CameronCrow]

Summary

Phase 3, deliverable A — the cheap, deterministic relevance test half of the
autonomous trigger. Implements exactly the A decomposition in
planning/PHASE_3.md (Implementation design → FROZEN INTERFACE), building to the
frozen state-file schema issue #32's Stop hook is built against in parallel.

• hooks/flag_ui_change.py — a PostToolUse-invoked Python script (portable;
  Windows-primary repo, so no bash). Core logic lives in an importable flag(payload, project_dir) function; the __main__ block is a thin stdin/stdout adapter.
  • Reads tool_input.file_path from the hook stdin JSON.
  • Matches it against a default UI-glob set (ui/**, **/*.tsx, **/*.jsx,
    **/*.xaml, **/*.css, frontend/**), overridable per-repo via
    .cyclaudes/ui-globs.txt (one glob per line, # comments/blank lines ignored;
    presence replaces the defaults entirely — documented in the module docstring).
  • On a match, appends the de-duplicated repo-relative path to
    <project>/.cyclaudes/pending-ui/<session_id>.json:

    { "session_id": "...", "ui_touched": ["relpath/one.tsx", "relpath/two.xaml"] }

    Creates the dir/file on first write; read-modify-write preserves existing
    entries; idempotent on repeat edits of the same file.
  • No-op (exit 0) on a non-UI path or an incomplete payload — never raises, never
    disrupts the tool call (PostToolUse can't block anyway; this only flags).
• hooks/hooks.json (new) — registers the hook with matcher Edit|Write. Kept
  minimal/localized per the issue's instruction, since the Stop hook (issue feat(phase3-B): Stop-gate enforcement, three-outcome routing, bounded retry + instrumentation #32)
  will add its own entry to the same file in parallel.
• .gitignore — adds .cyclaudes/ (the session-state directory).
• planning/TODO.md — checks off the Phase 3 "Trigger + cheap relevance test"
  line with a pointer to what landed.
• tests/test_flag_ui_change.py — loads the hook script by file path (it lives
  outside the cyclaudes package on purpose, so the bare python ${CLAUDE_PLUGIN_ROOT}/hooks/flag_ui_change.py invocation needs no install step)
  and exercises flag() directly against tmp_path project dirs:
  • UI path → state file contains the repo-relative path.
  • Non-UI path → no-op, no state file.
  • Dedup (same file twice → one entry) and accumulation (distinct UI files).
  • Two session_ids → separate files, no cross-contamination.
  • Glob override → changes what matches.
  • Missing session_id/file_path → no-op.

Does not touch the Stop hook, verify-result/*.json, or anything outside
hooks/, hooks.json, .gitignore, planning/TODO.md, and tests/ — scoped
strictly to the "A" decomposition so the hooks.json collision with issue #32 stays
a trivial rebase.

Closes #31

Test plan

• python -m pytest tests/test_flag_ui_change.py -p no:cacheprovider -v — 7
  passed
• python -m pytest tests/ -p no:cacheprovider — full suite, 155 passed, 6
  deselected (live, unaffected by this change)
• No pip install -e . run, per instructions (shared site-packages)