feat(auto-derive): open reconciliation PR on diff (write + PR mode)

[bradymiller]

What

Promotes the derive-ip-map workflow from dry-run-only (PR #135) to active reconciliation:

• Daily 07:00 UTC schedule runs derive.sh --write and, on any diff in ip_map_branch.txt or docker/scripts/demoLibrary.source vs master, force-pushes the stable branch auto-derive/reconciliation and opens (or updates) a PR titled [auto-derive] reconcile demo_farm against upstream openemr master.
• On no-diff with an open reconciliation PR from a prior run: the PR is closed (with explanatory comment) and the remote branch deleted -- upstream drift reverted.
• workflow_dispatch now takes a mode input (reconcile default, dry-run optional). dry-run mode keeps the artifact-upload preview behavior from PR feat(auto-derive): scaffold ip_map + demoLibrary derivation bot (dry-run) #135 with no branch/PR side effects.
• Fixture test suite job is unchanged from PR feat(auto-derive): scaffold ip_map + demoLibrary derivation bot (dry-run) #135.

Why

PR #135 set up the algorithm + dry-run scaffolding. PR #2 (this) is the "live" rung -- the bot now actually reconciles. PR #3 will retire the legacy bump-tag.yml + tools/release/ PHP toolchain.

Behavior details

• Stable branch + force-push: the bot updates the same PR across days rather than spamming new ones. --force-with-lease is safe even if the branch was just deleted (lease against missing ref).
• Scoped diff: detection is git diff --quiet -- ip_map_branch.txt docker/scripts/demoLibrary.source. An unrelated edit to tools/auto-derive/ (or anywhere else) on master won't trip the bot into PR-ing changes it didn't make.
• Scoped staging: git add only the two output files. No accidental sweep of other working-tree noise.
• Idempotent across midstream merges: if a maintainer manually merges the bot PR while the next day's run is in flight, the next force-push to the (now-merged-and-typically-deleted) branch still works.
• Repo guard: the reconcile job's if: pins to openemr/demo_farm_openemr so forks don't accidentally try to open PRs against themselves.

Caveats

• PRs created via GITHUB_TOKEN do NOT trigger downstream workflows (rabbit, CI). The in-workflow fixture suite job is the authoritative algorithm validator. To manually run CI on a bot PR, push an empty commit (git commit --allow-empty -m 'trigger ci' && git push).
• Repo settings prereq: Settings -> Actions -> General -> Workflow permissions must have "Allow GitHub Actions to create and approve pull requests" enabled. Without this, the gh pr create step will fail.

Out of scope

• tools/auto-derive/derive.sh (algorithm is stable from PR feat(auto-derive): scaffold ip_map + demoLibrary derivation bot (dry-run) #135)
• tools/auto-derive/fixtures-and-tests/** (fixtures are stable from PR feat(auto-derive): scaffold ip_map + demoLibrary derivation bot (dry-run) #135)
• tools/release/**, demo_build.sh, ip_map_branch.txt, docker/scripts/demoLibrary.source (untouched here; the daily bot run will pick up any drift)

Test plan

• Confirm repo setting "Allow GitHub Actions to create and approve pull requests" is enabled on openemr/demo_farm_openemr
• Trigger workflow_dispatch with mode=dry-run -- verify artifact uploads, no branch created, no PR opened
• Trigger workflow_dispatch with mode=reconcile -- verify either (a) no-diff path logs cleanly with no PR, or (b) diff path creates branch auto-derive/reconciliation + opens PR with expected title/body/stat/full-diff
• Re-trigger reconcile with no underlying drift change -- verify existing PR is updated (gh pr edit) rather than duplicated
• If a bot PR is open, manually merge it, then re-trigger reconcile with no further drift -- verify clean no-diff exit with no zombie PR
• Fixture test job still passes

Summary by CodeRabbit

• New Features
  • Added a unified “derive ip_map” workflow that can run on a daily schedule or via manual dispatch.
  • Supports selectable execution modes: reconcile (updates) and dry-run (no changes).
  • Automatically manages a reconciliation pull request—creating/updating it when changes are detected and closing it when none are found.
• Documentation
  • Updated the auto-derive usage guide for write-mode behavior.
  • Expanded workflow notes covering daily reconcile, diff detection scope, and how to run dry-run and CI manually.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: faf337a1-b3fd-4c52-8675-e56637688b86

📥 Commits

Reviewing files that changed from the base of the PR and between 994c4b5 and ced31ee.

📒 Files selected for processing (1)

• .github/workflows/derive-ip-map.yml

🚧 Files skipped from review as they are similar to previous changes (1)

• .github/workflows/derive-ip-map.yml

---

📝 Walkthrough

Walkthrough

The derive-ip-map workflow now supports a reconcile mode that writes derived outputs, checks for diffs, and manages a stable PR branch. The dry-run path is restricted to manual dispatch. The README documents the new daily reconcile flow and PR behavior.

Reconcile Workflow and Documentation

Layer / File(s)	Summary
Reconcile job and workflow restructure .github/workflows/derive-ip-map.yml	Adds workflow_dispatch mode selection, a reconcile job for write-mode runs and PR management, and updates the dry-run and fixture test job gating and shell flags.
README reconcile documentation tools/auto-derive/README.md	Updates the write-mode note and documents the daily reconcile schedule, diff scope, stable branch behavior, PR lifecycle, and manual CI caveat.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐇 The bunny taps a gentle key,
A reconcile dance in YAML sea.
Two files diff, the branch hops free,
PRs bloom on schedule, happily.
Readme carrots line the trail,
For dry-run and write-mode tale.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	#135 scoped this work to dry-run scaffolding only, but the PR adds active reconciliation and auto-PR creation.	Split the reconciliation/PR-creation behavior into a separate follow-up and keep this PR limited to dry-run scaffolding, tests, and docs.
Out of Scope Changes check	⚠️ Warning	The write-mode daily reconcile workflow, branch force-pushes, and auto-created PRs go beyond the linked dry-run-only scope.	Move the active reconciliation and PR automation into a separate PR so this change stays within the dry-run scaffold scope.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: opening reconciliation PRs on diff with write and PR modes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/derive-ip-map.yml:
- Around line 35-43: Gate the reconcile job’s side effects behind the fixture
suite by making `reconcile` depend on the `test` job in this workflow, rather
than running as an անկախ parallel sibling. Update the `jobs.reconcile`
definition in `derive-ip-map.yml` so it only executes when `test` succeeds,
preventing force-push/PR actions from `reconcile` when
`./tools/auto-derive/fixtures-and-tests/test.sh` fails.
- Around line 39-55: The Checkout step in the derive-ip-map workflow is using
the workflow-triggering HEAD, which can pull in unrelated commits when run
manually. Update the actions/checkout configuration in the Checkout step to
explicitly check out master by setting the ref on that step, so the
auto-derive/reconciliation branch and PR diff are always based on the correct
baseline.
- Around line 151-167: The `git diff` summary in the reconciliation workflow is
being built incorrectly because `--stat` is placed after the pathspec separator,
so the `stat` variable captures a full patch instead of the summary. Update the
diff command in the reconciliation script to use `git diff` with `--stat` before
`--` while keeping the same paths, so `stat` and `full_diff` remain distinct in
the PR body.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: aefdd18d-b7ca-47ab-8fb7-3455c5ecc99c

📥 Commits

Reviewing files that changed from the base of the PR and between ffe3646 and 994c4b5.

📒 Files selected for processing (2)

• .github/workflows/derive-ip-map.yml
• tools/auto-derive/README.md