[timlichtenberg]

What this does

Adds a small Python package and a scheduled workflow that keep shared fields equal across the Interra Management board, the Interra Collaboration board, the PROTEUS Development Roadmap and the org issue fields of each issue. When a value changes in one place, the next run writes it to the others.

Why

The same dates, priorities and statuses are kept by hand on three boards and on the issues themselves, and they drift apart. The roadmap views are only useful when start and target dates agree everywhere.

Changes

• board_sync/core.py: the sync rules. Newest change wins; a value that every place already shows wins without a conflict; a missing field, a field created again or an emptied field never clears the other places; an issue that leaves a board and comes back starts from its old record.
• board_sync/github.py: GraphQL reads of the three boards and of the org issue fields, with change times from the issue timeline, and the four write mutations. Retries on server errors, network errors and rate limits; a list longer than one page stops the read.
• board_sync/__main__.py: dry run by default; with --apply a run stops above 20 new writes until a person approves the plan, puts writes that failed before last, parks writes that keep failing, saves its state even when it is cut short, and prints only counts, field names and error types to the log.
• scripts/store_state.sh: stores the state, snapshot and report of a run in the private board-sync-state repository; the files of the run replace the stored ones whole.
• .github/workflows/sync.yml: runs every 30 minutes on main as a GitHub App and pins every action by commit.
• .github/workflows/tests.yml: lint and tests on every pull request, with a coverage floor of 95%.
• README.md: the rules, the setup and the exit codes. .gitignore keeps local run files with private board data out of commits.

Testing

• 134 tests, 99% line and branch coverage; each of the safety rules was checked by breaking it on purpose and seeing a test fail.
• The store script is tested against real local git repositories: a first run without a state file, a conflicting remote change, no change, a push that is rejected once, a failed commit, and a folder that is not a repository.
• A read-only run against the live boards: 293 issues, 1688 planned writes, 36 conflicts, no issue data in the log output.
• The four mutations were sent with ids that do not exist and reached the id lookup, so their shape matches the live schema. A missing board was checked against the live API, which answers with a NOT_FOUND error that the read turns into a named error.
• Not tested yet: a real write through the App, and the workflow on GitHub. Before the first run, the App, the environment and the deploy key need to be set up as in the README.