# Flaky Test Governance

This toolkit discovers recovered test failures in the repository's unit and
integration GitHub Actions JUnit artifacts, then idempotently reconciles one
GitHub issue per target branch and exact nextest testcase identity.

## Setup

1. Copy `.env.example` to `.env` and configure the repository and existing
   labels.
2. Set `.env` to mode `0600` if it contains a token. The token needs Actions
   read and Issues read/write access. If no token is configured, authenticate
   `gh` for `github.com` first.
3. Run `./run.sh --dry-run` before enabling daily execution.

## Usage

```bash
./run.sh
./run.sh --dry-run
./run.sh --run-id 123456789 --dry-run
./run.sh --since 2026-08-01T00:00:00Z --dry-run
```

`--run-id` and `--since` are mutually exclusive. Selector runs and dry runs do
not advance the daily cursor. Every invocation ends with a one-line JSON
summary. Exit code `0` means success, `1` means an operational failure, and `2`
means valid inputs were processed but at least one permanent input was rejected.

The default state directory is `.state`. It must be on a filesystem with
reliable `flock` semantics and must not be shared by active reconcilers on
different hosts.