feat(conformance): the one screen, and self-healing where a PR is honest (backend#1608 items 3+4)

[LukasWodka]

The gap

Item 3 of the harness is "one screen". The matrix has existed since #223 — but nothing published it when the fleet was green.

The drift comment fires only on findings, and that is deliberate: an all-clear per run trains people to ignore the issue (backend#1344, five silent failures nobody read). The unintended consequence is that a conformant fleet produced a step summary on a run nobody opens. "Where does the fleet stand?" was still answered by running the script by hand — the exact thing the ticket set out to remove.

The fix: split the two roles

	role	cadence
issue body	the current state	rewritten every scheduled/manual run
issue comments	the history	drift-only, unchanged

The body is rewritten regardless of outcome, and that is what makes staleness mean anything. The audit is weekly, so a timestamp older than ~8 days means the audit itself stopped and conformance is UNKNOWN — the backend#1530 cron-watchdog contract. That only holds if a red run rewrites the body too; otherwise a fleet that broke in January still shows January's green and merely looks stale-ish. Hence always(), not gated on exit_code.

Two bugs found while building it

1. The drift comment was posting to a closed issue. backend#1415 is CLOSED. Comments on a closed issue still post, so this looked like it worked — but a closed issue cannot be pinned, drops out of every default issue view, and notifies nobody not already subscribed. Drift has been reporting into a drawer. Now backend#1781, open and pinnable.

2. WATCHDOG_ISSUE was defined in one step's env: and used in another, where it is undefined — under set -u that step dies. Loud rather than silent, but the drift comment would never post. Hoisted to job level, which is also this repo's stated rule for inputs reaching the shell.

The verdict is derived, not asserted

A clean exit code alongside a non-zero unreadable/findings count now renders "Inconsistent result — treat as UNKNOWN". The script does not produce that pair today, which is exactly why it is worth pinning: ✅ every repo read printed directly above 3 unreadable is the most confidently wrong thing this screen could say, and the headline should stay true if the exit-code contract ever changes.

Also: report heading Repo conformance drift → Repo conformance. It now renders under a verdict line that is often "Conformant", and a heading asserting drift above a green matrix contradicts itself on the one screen people are meant to trust.

Evidence

• selftest 123 pass / 0 fail; actionlint and shellcheck clean
• body rendered against a live fleet audit: evaluated=20, unreadable=0, findings=0
• all five verdict paths exercised — clean / drift / unevaluable / empty exit code / inconsistent
• truncation guard verified: a >60k report is cut to ~59k with a TRUNCATED marker, keeping the body under GitHub's 65536 limit. A rejected edit would leave the previous body in place — a stale green presented as current, the one outcome this step exists to prevent.

After merge

backend#1781 still reads "Awaiting first sweep". Trigger Actions → Caller inventory drift → Run workflow once to populate it immediately rather than waiting for Monday — that also proves the issues: write path works with the real token, which local rendering cannot.

Parent: backend#1608 (item 3). Remaining after this: item 4, the create-prs self-healing dispatch.

---

Note

Medium Risk
Manual dispatch can push workflow files across the org (needs Contents/PR/workflow token scopes), but scope is limited to required copies and failures fail closed; issue-body rewrites affect the fleet visibility surface on every weekly run.

Overview
Adds the org conformance “one screen” and optional self-healing for canonical workflow copies, extending caller-drift beyond report-only drift detection.

On every scheduled or manual audit (not PR/push), a new step rewrites backend#1781’s issue body with timestamp, counts, a derived verdict (conformant / drift / unevaluable / inconsistent / remediation failed), and the full matrix. Drift still lands as comments only on failure. Drift reporting moves from closed #1415 to open #1781; WATCHDOG_ISSUE is job-level so both reporting steps see it under set -u. Bodies truncate before GitHub’s size limit so a failed edit cannot leave a stale green matrix.

Manual dispatch gains a create-prs input (explicit workflow_dispatch only—never cron/PR). When enabled, caller-drift.py --create-prs opens/refreshes PRs that realign inventory required copies only; divergent / exempt are never rewritten. Remediation uses branch reuse, content PUTs with correct SHAs, retries for fresh-branch 404s, and exit 2 + remediation_failures output when writes fail (separate from unreadable repos). Report heading becomes “Repo conformance” so green runs don’t say “drift” above a clean matrix.

Selftests add AST checks that only required copies enter remediation plus stubbed remediate_copies paths; .gitignore ignores workflow scratch wd-body.md / body.md.

^{Reviewed by Cursor Bugbot for commit ba8ea38. Bugbot is set up for automated code reviews on this repo. Configure here.}

[LukasWodka]

Item 4 added to this PR (7208ce6)

Why here and not a separate PR: item 4 touches the same two files as item 3, so a separate PR would either conflict or be stacked on this one — and the standard forbids stacking. Retitled to cover both.

What item 4 will NOT do — most of the design

The ask was "open the missing-piece PR per repo", but a PR is the right instrument for exactly one of the five families:

family	remediable?	why
copies	✅ yes	byte-identical by definition; the guard already holds the canonical bytes, so the fix is exact rather than generated
callers	❌ no	content is repo-specific — measured: all 8 sampled repos have a different code-quality-caller.yml, each passing its own toolchain inputs. A generated caller would be a plausible file that is wrong, which is worse than an absent one that at least reports as a finding
protection, required_checks, rulesets	❌ no	API settings, not files in the tree. No commit can change them, so a PR claiming to fix them would be theatre

And within copies, only required entries. divergent records a written reason why a repo differs — cli pins actions/stale@v11 where canon pins v9, and the newer pin may well be the better one. A script that silently overwrote a recorded decision would destroy the judgement the inventory exists to hold.

Safety

Dispatch-only, gated on github.event_name == 'workflow_dispatch' && inputs.create-prs == true — the same expression standards-sync.yml uses, whose remediation path this mirrors throughout (422-means-reuse, sha-refresh, PR reuse, actor assignment).

Remediation failures go in their own list, not unreadable: the exit path derives "caller/copy state UNKNOWN" by subtracting the protection and ruleset lists from unreadable, so a failed write pushed in there gets reported as a failed read — the wrong diagnosis on the one line an operator acts from.

Evidence

• selftest 132 pass / 0 fail (up from 123)
• five mutations, each caught by its intended case and only that case: enqueue a divergent copy (the safety property — asserted structurally via AST, since a grep for "divergent" near "remediable" would pass whatever the code did); return None on a failed write; treat any branch-create failure as "already exists"; always send sha=; skip the existing-PR check
• live fleet, no-op path:--create-prs reports "nothing to remediate" and writes nothing
• live fleet, drift path: with cli's genuinely-drifted stale-backlog.yml flipped to required, it selects exactly that one file (blob 4e4246398130 vs canonical 14d689eab3df) — run with the writer replaced by a recorder, so nothing was written
• shellcheck + actionlint clean

The workflow header said REPORT-ONLY and no longer is — updated in the same commit, along with the token scopes that implies.

[LukasWodka]

bugbot run

[LukasWodka]

bugbot run

[LukasWodka]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 8ec0d8b. Configure here.}

[shujaatTracebloc]

Approving the code. The red is not this PR's — and it will not clear by re-running, so the note that checks were "settling post-#231" needs correcting.

Where the red comes from

audit exits 1 with 16 findings. All sixteen are the same file with the same pair of blobs:

add-to-kanban.yml has DRIFTED (blob 603751a070de vs 3b6d693535ef)

Sixteen repos all sitting on the identical blob is not sixteen repos drifting — it is the hub moving and the fleet standing still. And it did:

#231 merged, bumping canonical add-to-kanban.yml to add-to-project v2.0.0	14:45:33Z
#227's audit ran and found 16 drifted copies	14:46:41Z

68 seconds. #231 changed the canonical copy and repo-inventory.yml and did not propagate the file to the 16 repos that hold copies of it. #227's four files (caller-drift.yml, .gitignore, caller-drift.py, caller-drift-selftest.py) don't touch add-to-kanban.yml at all — it inherited the drift and, because it edits contract files, the gate correctly refuses to let a contract change ride over an unclean audit.

So the gate is working. It is reporting real fleet state that arrived a minute before it looked.

Worth flagging separately: #231 merged through this same gate, red

gh pr checks 231 shows audit fail and gate fail, no override label, merged to develop. So the conformance gate is not enforced as a required check — which means the guard this PR extends can be walked past, and the PR that introduced the drift is what walked past it. That is a bigger finding than anything in this diff and probably wants its own issue.

Ordering, because there's a bootstrap knot

The one-dispatch fix for those 16 copies is the --create-prs path in this PR, and workflow_dispatch inputs are read from the default branch — so create-prs: true isn't dispatchable until this merges. Sequencing that works:

1. merge this (the same route #231 took)
2. dispatch caller-drift.yml with create-prs: true → one PR per drifted repo, divergent/exempt untouched
3. those merge → audit greens → the gate becomes load-bearing again

Doing it the other way means 16 hand-written PRs to unblock the tool that would have written them.

On the diff itself

The remediation boundary is the right call, and the reasoning for it is the part I'd have pushed back on if it were missing: callers measured as eight different files across eight repos means a generated caller is a plausible file that is wrong, which is worse than the absent one that at least reports. And protection/rulesets being API state means a PR claiming to fix them is theatre.

Two things I checked rather than took on trust:

• the divergent/exempt guard is asserted structurally, by parsing main() and requiring every remediable mutation to sit inside the state == "required" branch — plus a second assertion that the branch does enqueue, so the first can't pass vacuously. A grep for "divergent" near "remediable" would have passed whatever the code did. This is the assertion that matters most, since the failure it prevents is silently overwriting a recorded human decision.
• the fresh-vs-reused branch distinction in _read_copy_on_head.expect_file=on_base and branch_is_fresh is the load-bearing half: on a fresh branch a 404 for a drifted copy is provably a lie, so retry-then-fail-closed is right; on a reused branch that 404 is honest and permanent, and failing closed there is what stranded standards-sync (#197). Conflating them would break either the commonest dispatch or every re-dispatch. Both directions are pinned.

Exit 2 for remediation_failures with its own output rather than folding into unreadable is also correct — "could not write" reported as "could not read" sends the operator to the wrong problem.

Two nits, neither blocking

1. scripts/caller-drift.py — remediable: "dict[tuple[str, str], list[str]]" is wrong; the code appends (copy_name, bool) and remediate_copies declares list[tuple[str, bool]]. Should be dict[tuple[str, str], list[tuple[str, bool]]].
2. .gitignore — wd-body.md and body.md are unanchored, so they match at any depth. Both are written at the workspace root; /wd-body.md and /body.md avoid silently swallowing a legitimately committed body.md later. body.md is a generic enough name to be worth anchoring.