Compare the Ruleset Fields the Fleet Actually Manages

[ptr727]

Problem

AUDIT.md section 6's ruleset comparison projected bypass_actors on both sides and sorted it with sort_by(.actor_id). No committed payload declares that key, so the committed side did not mis-compare, it failed outright:

jq: error (at repo-config/main.json:58): Cannot iterate over null (null)

Process substitution then hands diff an empty left side, so the whole live payload reads as an addition and the || echo DRIFT branch fires. Every ruleset on every repo reported drift, from the snippet rather than from the repo. Reported by the agent resyncing ESPHome-Config.

Pre-fix, against Blog, which is in sync:

0a1,68
> {
> "bypass_actors": [ { "actor_id": 5, "actor_type": "RepositoryRole", "bypass_mode": "always" } ],
...
develop: DRIFT
main: DRIFT

Why this field

spec/audit.py's RULESET_SUBSET already excludes it, and the comment above it records that including it once made every repo report a ruleset DEFECT. repo-config/configure.sh is the authority both must agree with: apply reads the live list and writes it back unchanged, check reports it and asserts nothing, because who may bypass a ruleset is a human decision taken in the UI. The mechanized path was corrected and the prose snippet beside it was not.

Change

Three surfaces stated the old policy, so the class is swept rather than the instance:

• AUDIT.md section 6 compares name, target, enforcement, conditions, rules, matching RULESET_SUBSET, and states why the field is outside it.
• docs/repo-config-carry.md payload regeneration no longer captures bypass_actors. Capturing it baked one repo's bypass list into the canonical every other repo diffs against.
• repo-config/README.md no longer lists the field as part of the compared subset.

Verification

The snippet is extracted from the shipped AUDIT.md bytes rather than retyped, placeholders substituted, and run against three repos including two operational ones (exercising the operational/develop.json selection):

=== Blog === develop: in sync main: in sync
=== ESPHome-Config === develop: in sync main: in sync
=== HomeAutomation-Config === develop: in sync main: in sync

Gates: prose_lint.py --diff HEAD clean, repo_gate.py --check eol and --check eol-coverage clean, markdownlint-cli2 0 issues on all three files.

Note the committed downstream copies of these payloads are separately stale against the hub canonical (reports/divergences.md), which is a re-vendor drift. This PR does not touch that: the live rulesets match the hub's payloads, so enforcement was never affected.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Updates the fleet documentation and payload regeneration guidance so ruleset comparisons only include the ruleset fields the fleet actually manages, avoiding false drift/defect reports caused by projecting bypass_actors.

Changes:

• Remove bypass_actors from the documented ruleset diff/regeneration projections and add rationale for leaving it unmanaged.
• Update AUDIT.md ruleset-diff snippet to reflect the managed subset (name, target, enforcement, conditions, rules) and explain why bypass_actors is excluded.
• Clarify in repo-config/README.md that bypass_actors is writable but deliberately not asserted/diffed.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
repo-config/README.md	Documents bypass_actors as writable but intentionally unmanaged, and narrows the managed subset list.
docs/repo-config-carry.md	Removes bypass_actors from the payload regeneration projection to avoid baking repo-specific bypass lists into canonical payloads.
AUDIT.md	Updates the ruleset diff snippet to exclude bypass_actors and explains the policy rationale for doing so.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

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

Suppressed comments (1)

AUDIT.md:82

• The inline comment says audit.py sorts rules by .type, but spec/audit.py actually normalizes rules by sorting on each rule's full JSON content (see normalize_ruleset: sorted(..., key=lambda r: json.dumps(r, sort_keys=True))). This comment is now misleading and contradicts the preceding prose claiming parity with spec/audit.py.

 # bypass_actors stays outside the projection, since no payload declares one and jq cannot sort the null that leaves.
# Rules sort on their whole content rather than on .type, which is the key audit.py sorts by.
# Sorting on .type alone leaves two rules of one type in input order, so a reordered pair would read as drift.

[ptr727]

Addressed the suppressed finding from the second review round in 30e40d4.

You read it correctly, and the fault was mine rather than a false positive. The comment said "on their whole content rather than on .type, which is the key audit.py sorts by", where the relative clause attaches to the nearest noun, .type. So the sentence asserted that .type is audit.py's key, which is the opposite of the line above it and of what the change does. It now names the function, leaving no antecedent to pick wrongly:

# Rules sort on each rule's whole content, matching the key normalize_ruleset in audit.py sorts by.

Worth recording that this arrived as a suppressed comment rather than a thread, so it would have shipped had the review body gone unread.

[Copilot]

Pull request overview

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

Suppressed comments (1)

AUDIT.md:84

• The norm key uses sort_by(tojson), but spec/audit.py sorts rules by json.dumps(..., sort_keys=True). Because payloads are generated with sorted object keys (jq -S) while the live API response can have a different field order, tojson can produce different strings for semantically identical rules, reintroducing false drift. Consider normalizing object key order before tojson so the snippet matches normalize_ruleset's intent (order-insensitive by full content).

 # bypass_actors stays outside the projection, since no payload declares one and jq cannot sort the null that leaves.
# Rules sort on each rule's whole content, matching the key normalize_ruleset in audit.py sorts by.
# Sorting on .type alone leaves two rules of one type in input order, so a reordered pair would read as drift.
norm='{name,target,enforcement,conditions,rules} | .rules|=sort_by(tojson)'

[ptr727]

Addressed the second suppressed finding in a96b2b8. You were right, and measuring it turned up something worth recording.

The hazard is real. The live main ruleset returns type before parameters where the committed payload has parameters before type, so tojson gives the same rule two different sort keys, and pull_request and required_status_checks sort into different positions:

committed: {"parameters":{...},"type":"pull_request"}
live: {"type":"pull_request","parameters":{...}}

But the snippet still reported in sync, and that is the interesting part. The live side reaches jq through gh api --jq, which is gojq, and gojq emits object keys sorted. The projection was silently canonicalizing the input, so the filter was correct only by depending on which jq implementation produced it. Rewriting the same pipeline as raw gh api piped to real jq reports drift on a ruleset that matches, which is how I confirmed your reasoning rather than my own earlier four-repo pass.

The fix sorts keys at every depth before serializing, so the sort key no longer depends on that:

canon='def canon: walk(if type == "object" then to_entries | sort_by(.key) | from_entries else . end);'
norm="$canon"'{name,target,enforcement,conditions,rules} | .rules|=sort_by(canon|tojson)'

Verified three ways: the shipped snippet against four repos across both workflow models, the raw-jq path that exposed the defect, and a rules array reversed to confirm order-insensitivity.

[Copilot]

Pull request overview

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

Suppressed comments (1)

AUDIT.md:84

• The audit snippet now relies on jq's walk/1 (via canon), which is not available on jq 1.5; on hosts that still have jq 1.5 this snippet will fail to compile even though repo-config/configure.sh explicitly avoids that by using a portable recursive normalizer. Consider defining canon without walk so the snippet is runnable on the same floor as the script it references.

 canon='def canon: walk(if type == "object" then to_entries | sort_by(.key) | from_entries else . end);'

[ptr727]

Addressed the third suppressed finding in ff62314. Confirmed both halves of it against the tree.

spec/host-tools.json declares floors for docker, gh, git, git-restore-mtime, python3 and uv, and no jq entry at all, so nothing puts a host above 1.6. And repo-config/configure.sh:242 already says exactly this:

# The walk/1 builtin arrived in jq 1.6, so it is defined here rather than called.
# A host on jq 1.5 would otherwise not degrade, it would fail to compile the filter.
# The check_ruleset function would then report drift on every parameterized rule it never actually compared.

So calling walk reintroduced the two-tools-under-opposite-policies defect the rest of this branch exists to remove, in the same file. canon now recurses, inserting keys in sorted order so tojson emits them sorted at every depth:

canon='def canon: . as $in | if type == "object" then reduce (keys_unsorted|sort)[] as $k ({}; . + { ($k): ($in[$k]|canon) }) elif type == "array" then map(canon) else . end;'

Verified byte-identical to the walk version's output on a live ruleset payload, then re-run as the shipped snippet against Blog, ESPHome-Config, HomeAutomation-Config and PlexCleaner: all in sync on both branches. The only remaining mentions of walk in the file are the two comments explaining why it is not called.

Noting a gap this surfaced rather than fixing it here: there is no jq floor in the host contract even though two hub tools depend on jq behavior. Worth its own issue.

[Copilot]

Pull request overview

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