[Golden Test] Document the daily golden-verify triage agent (operator guide + design rationale)

[PeterJhongLinksys]

Goal

Document the golden-verify daily triage agent so that someone other than its author can understand, operate, and debug it — and so that the reasoning behind its non-obvious rules survives.

Right now the knowledge lives in three places that are all invisible to the team: a Hermes skill on one laptop (privacygui-golden-ci, with four reference documents), a playbook prompt under ~/.hermes/automation/prompts/, and the comment threads on #1185–#1189. None of that is discoverable from either repository, and none of it survives that laptop.

Why this matters more than usual

Several of this agent's rules look arbitrary until you know the incident that produced them. Undocumented, they are one "cleanup" away from being reverted:

• Failure authority. The report — not the Actions run conclusion — is the sole authority on image-comparison failures and overflow. A red run only means the round hit an obstacle; a bad clone or broken environment also turns it red. Run status is used only to decide whether a usable report exists.
• verified_branch never defaults. It used to fall back to the workflow default usp, which was indistinguishable from a genuine usp and would have driven judging and baseline triggering against the wrong branch, silently.
• The systemic breaker needs spread, not just volume. One shared-string edit across 26 locales is a large count yet perfectly attributable; a partial baseline shrinks the denominator. Genuine SDK/font drift is wide because it changes rendering itself.
• The strict intended bar makes automatic baseline refresh rare on purpose. Anyone measuring the agent by "how often it opens a baseline PR" will draw the wrong conclusion and loosen the wrong knob.
• Dedup anchors on the failing-screen set, not the suspect PR, because a suspect PR evaporates as the attribution window moves.

Proposed deliverables

1. Operator guide, in PrivacyGUI-golden-ci/docs/ (this is the repo the agent watches, so it is the discoverable home):
   • What the agent does each morning, in sequence, and what it will and will not touch.
   • How to read its Telegram message and what each verdict means.
   • Runbook: what to do when it reports an anomaly; how to re-judge a past day; how to pause it; what happens if the lock is left behind by a crashed run.
   • Explicit list of what the agent never does: close issues, merge PRs, push to any branch, edit production code or CI workflows.
2. A "why it is built this way" section capturing the load-bearing decisions above, each with the failure mode it prevents. Keep it short — a reason per rule, not an essay.
3. Architecture sketch: CI (verify → report on gh-pages) → collector (read-only extraction) → playbook (judgment) → actions (issue / baseline PR / Telegram). Make the boundary explicit: the agent consumes the published report and never inspects or reasons about the report generator's internals.
4. Cross-links so each entry point leads to the docs: a pointer in this repo's README, and one in PrivacyGUI-golden-ci.

Out of scope

Turning the agent into a reusable module — tracked separately.

Acceptance

Someone with no prior context can read the operator guide and correctly answer: what triggers an issue, why a red run alone is not a failure, why baseline updates are rare, and what to do when the morning message says the judging was inconclusive.