Promote an upstream-dependency-version-tracker pattern into the template

[ptr727]

Problem

The template has no scaffold for the common case of a derived repo that wraps an upstream release and must react when that upstream publishes a new version. Two downstreams have independently converged on the same pattern:

• homeassistant-purpleair check-ha-version.yml - resolves the upstream Home Assistant version, writes it into a committed state file (.github/ha-test-versions.json), and opens a rolling, App-authored, signed PR that merge-bot auto-merges.
• ptr727/NxWitness - does the equivalent via daily codegen that updates Make/Version.json/Make/Matrix.json.
• ptr727/ESPHome-NonRoot now mirrors the purpleair pattern (check-esphome-version.yml + .github/esphome-version.json) for the upstream ESPHome PyPI release.

Each repo reinvents the same shape (resolve upstream -> write committed state file -> rolling bump PR -> merge-bot -> next publish ships it). Nothing in the template documents or scaffolds it, so the next wrapper repo starts from scratch and may regress to a less-good approach (e.g. a direct gh workflow run build trigger, which ESPHome used before this migration).

Suggestion

Document the pattern in AGENTS.md (probably near "Branching Model"/"Release Model") and/or ship a parameterized check-upstream-version-task.yml skeleton: inputs for the resolver command + state-file path + bump-branch prefix, dual-target matrix when the version is shipped content (vs develop-only when it only drives CI), and the peter-evans/create-pull-request rolling-PR + merge-bot wiring. Also worth a note on the two-phase latency tradeoff (a merged bump ships on the next weekly publish, not immediately).

---

Surfaced while adopting the template in ptr727/ESPHome-NonRoot (see ptr727/ESPHome-NonRoot#61).

[ptr727]

Sub-point: standardize the state-file location

If the template promotes this tracker pattern, it should also fix a consistent location for the committed version-state file, because the downstreams currently disagree:

• homeassistant-purpleair: .github/ha-test-versions.json
• NxWitness: Make/Version.json + Make/Matrix.json
• ESPHome-NonRoot: started at .github/esphome-version.json, moved to repo root esphome-version.json (beside version.json).

Rationale for root: the file is a build-input version source the pipeline reads (like NBGV's version.json), not GitHub-platform config. .github/ conventionally holds workflows / Dependabot / issue templates / copilot-instructions, so a build-state file there is a semantic misfit and easy to overlook next to the platform config.

Suggestion: when scaffolding the pattern, default the state file to the repo root alongside version.json (or document a single deliberate convention), so every wrapper repo agrees and the location is discoverable next to the existing version pin.

---

Context: ptr727/ESPHome-NonRoot (see ptr727/ESPHome-NonRoot#61).

[ptr727]

Shipped a parameterized check-upstream-version-task.yml skeleton + merge-upstream-version wiring in the merge-bot, standardized the state file at the repo root beside version.json, and documented the pattern (incl. the two-phase latency tradeoff) in AGENTS.md.

Addressed in #167 (merged to develop; not yet promoted to main, pending any further feedback as these changes are applied downstream).