Operational repos audit against main, matching AUDIT.md section 1 (#340)

[ptr727]

Fixes #340 - and it turns out to be a reconciliation, not a policy change.

What I found

AUDIT.md section 1 already says, with no model exception:

Read the target's main branch as ground truth: main is the released, authoritative state.

But three operational entries in registry/repos.json named develop - Vantage-Config, ESPHome-Config, HomeAutomation-Config. So the registry was contradicting the hub's own documented rule; #340's proposal is what the docs already required. (HomeAssistant-Config was correctly on main.)

Changes

• registry/repos.json: the three operational entries flip to groundTruthBranch: main.
• AUDIT.md section 1: states the both-models rule explicitly, since that is precisely where the ambiguity arose - an operational repo commits directly to develop, but its ground truth is still main, the promoted snapshot; develop is mid-flight by design, so conformance work landed there but not yet promoted is un-promoted work, not a defect. A groundTruthBranch naming develop contradicts the section, for either model.

Verification (the risk was manufacturing false findings)

Before flipping, I confirmed all four conformance files (repo-config/main.json, repo-config/operational/develop.json, AUDIT.md, spec/secrets.json) are already present on main in all three repos - so measuring main surfaces nothing new.

BEFORE (develop ground truth):  Vantage/ESPHome/HomeAutomation -> all clean
AFTER  (main ground truth):     all four operational repos      -> all clean, 0 findings

spec/validate.py, markdownlint, editorconfig-checker: clean.

Out of scope here: four release repos also name develop

Checking the fleet surfaced that KiCadLibrary, EspDinIoT, PhotoCleaner, and HolidayLights (all release model, all with a main branch) also carry groundTruthBranch: develop - the same contradiction. They are deliberately not flipped in this PR, because unlike the operational three their main is stale, so the flip is not mechanical:

repo	baseline files present on main
KiCadLibrary	4/4
PhotoCleaner	2/4
HolidayLights	1/4
EspDinIoT	0/4

Flipping them would surface real-but-voluminous findings (their released state genuinely is non-conformant - which is arguably the correct signal, but it is a scope and noise decision for the owner, not a mechanical reconciliation). Raised for a separate call.

Note on the counter-view

#340 raises deploy-from-develop as the one case for a develop ground truth, and suggests a separate deployBranch field rather than overloading groundTruthBranch. No fleet repo deploys from develop today, so I have not added the field - cheap to add later if one genuinely needs it.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Aligns the audit "ground truth" branch selection for operational repos with the documented intent that main is the promoted, authoritative snapshot, and reconciles the registry accordingly.

Changes:

• Updates three operational repos in registry/repos.json to use groundTruthBranch: main.
• Clarifies AUDIT.md section 1 to explain why operational repos still audit main even though they commit directly to develop.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
registry/repos.json	Flips operational repo entries from groundTruthBranch: develop to main for consistent audit targeting.
AUDIT.md	Expands section 1 to explicitly state operational-model ground truth expectations.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

AUDIT.md:19

• Section 1 says to always audit main and states that any registry groundTruthBranch: develop "contradicts this section", but the mechanized audit runner actually reads groundTruthBranch from registry/repos.json (spec/audit.py:72) and the registry still contains several groundTruthBranch: develop entries. Please update this section to describe the implemented behavior (audit groundTruthBranch, default main) while keeping the normative guidance that operational repos should use main.

Audit one repository at a time. Read the target's **`main` branch** as ground truth: `main` is the released, authoritative state. Read `develop` only to detect divergence - a stale or diverged `develop` (behind `main`, or diverged) is reported as a **drift finding**, never audited as the truth. Do not treat a `develop`-only file as present if it is absent on `main`.

This holds for **both workflow models**. An `operational` repo commits directly to `develop`, but its ground truth is still `main` - the promoted, gated snapshot the promotion PR blesses. `develop` there is mid-flight by design (ungated direct pushes), so auditing it would measure work in progress: conformance scaffolding that has landed on `develop` but is not yet promoted is *un-promoted work*, not a conformance defect, and it counts when it reaches `main`. A registry `groundTruthBranch` naming `develop` therefore contradicts this section - for either model.