Repository navigation
Description
Context
Filed from the HomeAssistant-Config #16 operational onboarding. This is a deliberate disagreement with the current groundTruthBranch convention for operational repos, raised for a fleet-wide decision.
Observation
groundTruthBranch is inconsistent across operational (workflowModel: operational) repos:
| Repo | workflowModel | groundTruthBranch |
|---|---|---|
| Vantage-Config | operational | develop |
| ESPHome-Config | operational | develop |
| HomeAutomation-Config | operational | develop |
| HomeAssistant-Config | operational | main (deliberate, this onboarding) |
Three operational repos audit against develop; HomeAssistant-Config was deliberately kept on main. The registry default is main.
Position: operational repos should audit against main, not develop
The audit's ground truth is the "known-good reference state" a repo is measured against. For an operational repo that should be main, for the same reasons the release repos already audit main:
mainis the promoted, gated, known-good snapshot.repo-config/README.mddescribes the operational model as "editdevelopdirectly and promote a known-good snapshot tomainvia an occasional PR." The promotion gate (PR + required status check + Copilot review + resolved threads + signed merge commit) exists precisely so thatmainis the trustworthy state. Conformance should measure that trustworthy state.developis mid-flight by design. It takes direct, ungated signed commits with no PR gate. Auditing it measures work-in-progress: a half-finished live-config edit, or a conformance file that has landed ondevelopbut not yet been promoted, reads as "drift" or aLETTERfinding that is not a real defect - only an un-promoted change. (Concretely in#16: carrying the baseline todevelopwould leave therepo-config/... absentLETTERstanding against adevelopground truth until promotion, even though the work is done.)- Consistency. Release repos already default to
main; there is no model-specific reason an operational repo's reference branch should differ. The operational model changes howdevelopis written (direct vs PR), not which branch is the stable reference.
Proposal
- Default operational repos to
groundTruthBranch: main(drop the operational-specificdevelopchoice), and revisit Vantage-Config, ESPHome-Config, and HomeAutomation-Config. - Keep HomeAssistant-Config on
main(already done in#16).
Counter-view (acknowledged)
If an operational repo is deployed directly from develop (develop = live production), one could argue develop is the state worth auditing. Even then, the fleet-conformance scaffolding (repo-config/, AUDIT.md, spec/secrets.json, workflows) is stable infrastructure that belongs on the gated branch, and a develop ground truth turns "not yet promoted" into a standing finding. If deploy-from-develop is the real driver, that argues for a separate deployBranch field rather than overloading groundTruthBranch.
Raised per the HomeAssistant-Config owner's decision in #16.
Activity
Registry: HomeAssistant-Config operational conformance completed (#342)
Operational repos audit against main, matching AUDIT.md section 1 (#340…
ptr727 commentedon Jul 18, 2026
Fixed in #351 (develop bd48caf) - as a reconciliation, not a policy change.
AUDIT.md section 1 already mandated
mainas ground truth with no model exception ("Read the target's main branch as ground truth"). Three operational registry entries nameddevelop- Vantage-Config, ESPHome-Config, HomeAutomation-Config - so the registry was contradicting the hub's own documented rule. Your proposal was what the docs already required.groundTruthBranch: main.Verified before flipping: all four conformance files were already present on
mainin all three repos, so measuring main surfaces nothing new. Audit before and after: all four operational repos clean, 0 findings.On the counter-view: no fleet repo deploys from develop today, so I did not add a
deployBranchfield - cheap to add later if one genuinely needs it.Surfaced while doing this (not fixed here): four release repos carry the same contradiction - KiCadLibrary, EspDinIoT, PhotoCleaner, HolidayLights all name
developand all have a main branch. Unlike the operational three, their main is stale (baseline files present on main: 4/4, 2/4, 1/4, 0/4 respectively), so flipping them surfaces real-but-voluminous findings. That is a scope call rather than a mechanical fix - raising it separately rather than bundling it here.Promote the AGENTS.md router split and the scripts/ gate harness to m…