Write guard verdicts as JUnit evidence to a caller-named file

Cargo.toml

@@ -117,6 +117,21 @@ shell-words = "1"
 ureq = { version = "3.4.2", default-features = false, features = ["rustls"] }
 # Parse PEP 508 requirements before accepting the closed optional-extra form.
 pyreq = "0.2.0"
+# JUnit XML, for `UPHOLD_JUNIT`: the evidence format the gate tier already
+# writes, publishes and links, so a guard run is read by the same publisher with
+# nothing of uphold's own to parse. A library rather than a hand-rolled writer
+# because the format's escaping and its counts on every suite are what a reader
+# trusts first and a writer gets wrong last. This one is nextest's own, and it
+# writes a `hostname` only when one is put in `extra`, which this crate never
+# does -- `no-running-os-identity-metadata` refuses a machine name in a file a
+# gate publishes. `junit-report` was the alternative and is not used: it writes
+# `hostname="localhost"` on every suite, with no way to leave it out.
+quick-junit = "0.8"
+# Already in the tree under quick-junit. Named here only to turn the clock into
+# the suite's `timestamp`, the one piece of run metadata the file keeps;
+# `std` is the feature that converts a `SystemTime`, and the default features,
+# the local time zone among them, stay off.
+chrono = { version = "0.4", default-features = false, features = ["std"] }
 
 [target.'cfg(unix)'.dependencies]
 # Git discovers hooks with access(X_OK), which checks the caller's permission

docs/DESIGN.md

@@ -257,6 +257,39 @@ in the environment and is deliberately not a rule field: a bypass belongs to one
 invocation by whoever is running it, and written into the policy file it would
 be committed, reviewed once, and permanent, which is not a bypass.
 
+### uphold decides; it does not record
+
+`--junit FILE`, or `UPHOLD_JUNIT` for a run whose command line the caller does
+not own, names a file and uphold writes one JUnit document to it. The
+format is not one of uphold's own because the fleet already has one evidence
+format: a gate writes JUnit XML under `.test-evidence/` and a publisher turns
+the directory into a report. The four testcase states are the four answers a
+guard already gives, so publishers and report tools read the file with no glue
+and nothing downstream learns a second schema.
+
+The caller names the file, rather than uphold printing to stdout or keeping a
+file in a state directory. Stdout is already the prose a person reads and a
+hook runner may swallow. A default path in a state directory would be shared by
+every repository and every act on the machine, and would put a write somewhere
+the caller did not choose. A named file lets the caller put it where its
+publisher already looks, outside the tree or inside an ignored directory.
+
+The flag is the conventional spelling and the one a gate task types. The
+variable exists because a hook's command line is the hook definition's, pinned
+by the repository, so a caller running `git push` has no argv to add a flag
+to; the environment is the one channel that reaches through git and the runner
+to the guard, which is also why `UPHOLD_ALLOW` is a variable.
+
+`git commit --no-verify` and `git push --no-verify` run no hook, so no file is
+written. That needs no code here: a verifier that expects evidence on every
+pushed commit sees the absence, held on the remote and out of reach of the
+machine that skipped the hooks.
+
+"Evidence" here means what it means in `.test-evidence/`. Inside uphold the word
+also names a provider's facts to a policy, described in the section "Evidence:
+what a provider reports and what a policy may read", and the two meanings do
+not meet.
+
 ## What an external provider must establish
 
 A trustworthy provider claim has a verifiable rule name, a demonstrated