sfh-ci-monitoringlisted

# Monitor an exact CI execution, not “whatever is latest” CI is remote and time-varying. Stabilize the flow with identity, bounded waiting, durable snapshots, and deterministic conclusion mapping. Read [references/ci-design.md](references/ci-design.md) and [references/ci-failure-taxonomy.md](references/ci-failure-taxonomy.md). ## Identity contract Capture and verify: - repository - workflow name/id - exact CI run ID - exact head SHA - attempt number when relevant - trigger time or correlation ID Never use `gh run watch` without an explicit run ID in automation. Never assume the newest run belongs to this flow. If discovery returns zero or multiple candidates, fail or route to `stuck` rather than guessing. ## Observation contract Separate: ```text trigger/discover exact run → poll exact run → verify head SHA → save raw status JSON → map status/conclusion to stable exit code → route ``` The bundled `scripts/gh_ci_gate.py` performs the polling/mapping portion without rerunning or cancelling CI. ## Status handling - queued/in_progress/waiting: keep polling under a deadline - completed + success: pass - completed + logical failure: route to diagnosis/fix - cancelled because superseded/concurrency: classify separately from product failure - API/auth/network failure: bounded transient retry - unknown status/conclusion or SHA mismatch: fail closed - timeout: handoff/stuck, not infinite polling ## Repair loop A stable CI repair flow is: ```text exact failed run snapshot