Emit guard verdicts as JUnit evidence to a caller-named file #386

Activity

1. HackingGate

   changed the title [-]Record every bypass: a local sink first, a remote store later[/-] [+]Emit guard verdicts to a caller-named file[/+] on Oct 17, 2026
2. HackingGate

   added a commit that references this issue on Oct 17, 2026

   Emit guard verdicts to a caller-named file (#387)

   ...

   ca05631
3. HackingGate commented on Oct 18, 2026

   

   HackingGate

   on Oct 18, 2026

   OwnerAuthor

   More actions

   Design, continued: what the code decides for us

   Read against src/guard/mod.rs (run, evaluate, bypassed), src/main.rs (guard_command), src/check.rs (Report) and docs/REFERENCE.md (uphold check --json).

   1. Where the sink lives

   guard_command reads UPHOLD_VERDICTS once, opens the file, and hands guard::run a writer through RunRequest. run writes one line per rule; nothing else in the binary reads the variable in this issue. The environment is read at the same boundary as --stage and --message, and run stays testable against an in-memory writer.

   2. Open before the first guard runs

   The file is opened for create+append before the loop, and before the no rule declares a git hook early return. Two consequences:

   • A path that cannot be written is exit 2 with no guard evaluated. The caller asked for a record and cannot have one, so nothing is judged that would go unrecorded.
   • A stage with nothing declared leaves an existing empty file. "Ran, nothing to evaluate" is then distinguishable from "never ran", which a verifier reading absence needs.

   3. The path must be absolute

   Git runs a hook with the working directory at the top of the working tree. A relative path the recorder set from a subdirectory would land beside the repository root, not where the recorder reads. Relative is exit 2, naming the value.

   Empty (UPHOLD_VERDICTS=) is also exit 2. This is deliberately the opposite reading from UPHOLD_ALLOW=, where blank is treated as unset: there, blank-means-set switched every guard off silently; here, blank-means-set only refuses one run, loudly. A caller that exported and blanked the variable learns at once.

   4. One line per rule, and what unknown covers

   run stops at the first Fatal from evaluate (the ?). The rule whose evaluation failed gets an unknown line, then the error propagates. Rules the loop never reached get no line. Absence is not a claim, and exit 2 tells the recorder the run was cut short. The complete list of rules a stage would evaluate is the policy's to answer, not the record's.

   A Fatal reached before the loop (runner::push told nothing, policy that will not load) produces an open file with no lines, or no file at all, and exit 2. Same reading.

   The unknown line carries no diagnostic text. A Fatal message can quote a path or a message line, and the record holds nothing about the subject.

   5. Fields

   {"schema_version":1,"uphold":"1.32.0","stage":"pre-push","rule":"prevent-public-push","builtin":"prevent-public-push","set":"unowned-push","outcome":"pass"}
   {"schema_version":1,"uphold":"1.32.0","stage":"pre-push","rule":"no-local-merge","builtin":"no-local-merge","set":"unreviewed-history","outcome":"bypass","by":"UPHOLD_ALLOW","allowed":"id"}

   • builtin is added. evaluate dispatches on the built-in name, not the id; a repository may call a rule anything. A verifier asking "did prevent-public-push run" means the built-in, and the id alone is a name the repository chose.
   • uphold is the binary's version. A bundled set's contents are a property of the binary, so "no-local-merge from unreviewed-history passed" is only a complete statement beside the version that defined the set. One short field per line keeps each line self-contained, which is what lets the recorder fold lines in verbatim.
   • set is omitted, not null, for a rule declared locally, matching how policy.set_of answers and how the human report names a refusal (refused_by).
   • by is present only on bypass. allowed says whether the id was named or all matched, because bypassed() conflates the two and a recorder may well treat "this gate was switched off whole" differently from "this one rule was waived". Cheap: bypassed returns an enum instead of a bool.
   • refuse carries no report text. The report goes to stderr as today.

   Evolution follows uphold check --json: fields may be added within version 1 and a consumer ignores keys it does not know. A new outcome value or a changed meaning bumps the version, because a consumer matching exhaustively on outcome breaks either way.

   6. stdout and stderr are unchanged

   The N guard(s) passed line, the bypassed by UPHOLD_ALLOW line and the refusal report keep their wording. The file is additive. Nothing is known to parse the prose, and this issue is what makes parsing it unnecessary.

   7. One act, several stages, one file

   git commit runs pre-commit then commit-msg; a recorder that keeps the variable set across the act gets both in one file, which is why every line names its stage. Each line is written with one write_all under append, so two writers interleave at line granularity. No two guard stages run concurrently today, and in this repository's lefthook pre-commit the guards job is the only emitter among its parallel siblings.

   The variable reaches the hook because git hands its environment to hooks, and lefthook, prek and pre-commit hand theirs to the commands they run. Setting it on the git push is the whole integration, as the issue says. A test should go through a real hook rather than calling uphold guard directly, so that claim is checked and not assumed.

   8. --text and --stage manual

   --stage manual emits like any stage. uphold guard --text with the variable set is exit 2 until the shim follow-up gives that seam lines. It evaluates rules through text::judged, which returns refusals only, so it cannot honestly write a pass, and a caller that asked for verdicts and got silence is the case the issue refuses to create. The shim does not read the variable at all in this issue, so a variable exported around a whole act does not trip the shim.

   9. Where the words go

   • docs/REFERENCE.md, under uphold guard, a subsection beside "Overriding one": the variable, the line shape, the three exit-2 cases, and the evolution rule.
   • docs/DESIGN.md, after "One override spelling": "uphold decides; it does not record", with the --no-verify paragraph from this issue.
   • USAGE in src/main.rs: one line under UPHOLD_ALLOW.

   10. Tests (tests/guard_cli.rs, plus one structural)

   1. pass, refuse and bypass each produce the documented line; every line parses; schema_version is 1.
   2. an unwritable path is exit 2 and the refusing guard never printed, so the open happened first.
   3. relative and empty values are exit 2, naming the value.
   4. a stage with no rules leaves an empty file.
   5. a Fatal inside evaluate writes unknown for that rule and nothing for the rest.
   6. --text with the variable set is exit 2.
   7. through a real hook (the structural_test_git harness): set on git push, the file holds the pre-push lines.
   8. structural: the example lines in REFERENCE.md carry exactly the keys the serializer emits.

   Estimate

   One PR, about a day: roughly 80 lines in guard/mod.rs and main.rs, eight tests, three doc edits. Follow-up issue for the shim and hook.rs seams once this lands.
4. HackingGate

   changed the title [-]Emit guard verdicts to a caller-named file[/-] [+]Emit guard verdicts as JUnit evidence to a caller-named file[/+] on Oct 18, 2026
5. HackingGate commented on Oct 18, 2026

   

   HackingGate

   on Oct 18, 2026

   OwnerAuthor

   More actions

   Revised the body: JUnit XML to a caller-named file (UPHOLD_JUNIT), not JSON Lines of uphold's own shape.

   What changed against the comment above:

   • The format is JUnit, the evidence format the fleet's .test-evidence/ directories, their publisher and Allure already use. pass/refuse/unknown/bypass map to testcase/failure/error/skipped.
   • The claim that the gate recorder reads "a file of the same shape" was wrong. Its outcomes file is a tier map and its predicate holds tiers; attesting the JUnit file is a design issue of its own there.
   • One document per invocation, replaced not appended, so the variable names a file per stage.
   • Library named: quick-junit. Two unknowns recorded (hostname attribute, testcase properties in Allure).

   Everything else from the comment stands: open before the first guard, absolute and non-empty path, error for the rule whose evaluation failed, --text exit 2, no subject text, tests and doc locations.
6. HackingGate commented on Oct 18, 2026

   

   HackingGate

   on Oct 18, 2026

   OwnerAuthor

   More actions

   Both unknowns are resolved; #388 implements the result and removes the JSON Lines record of #387.

   • quick-junit 0.8 writes no hostname unless one is placed in a suite's extra map, so it is the library. junit-report writes hostname="localhost" on every suite with no way out, and is not used.
   • Allure 3's JUnit reader (packages/reader/src/junitxml/index.ts in allure-framework/allure3) reads no <properties> on a testcase or a suite. It files a testcase by classname (the testClass label, and fullName = classname.name), the suite name as the suite label and the suite package as the package label. So classname stays the set or local, the suite carries package="uphold", and the properties serve a machine reader rather than the report.
7. HackingGate

   closed this as completedin #388on Oct 18, 2026