From 63c5d2056fddc02005538630d996dd1f739d64c5 Mon Sep 17 00:00:00 2001 From: installer-7 Date: Fri, 31 Jul 2026 00:03:38 +0000 Subject: [PATCH] feat(git): add push-guard.README.md Mechanical closure of 'a verification that passes when the thing it verifies never happened.' --- .../framework/tools/git/push-guard.README.md | 107 ++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 packages/mosaic/framework/tools/git/push-guard.README.md diff --git a/packages/mosaic/framework/tools/git/push-guard.README.md b/packages/mosaic/framework/tools/git/push-guard.README.md new file mode 100644 index 00000000..e4cb83c0 --- /dev/null +++ b/packages/mosaic/framework/tools/git/push-guard.README.md @@ -0,0 +1,107 @@ +# push-guard + +Mechanical closure of one defect: **a verification that passes when the thing it verifies never happened.** + +Three incidents in one evening, three agents, no coordination, same shape: + +| # | Incident | Why the check passed | +|---|---|---| +| 1 | `PUSH VERIFIED` reported after nothing was pushed | Commit had aborted, so local HEAD trivially equalled the remote ref | +| 2 | An **empty commit** carrying another commit's message was pushed | A push was chained after a *failed* commit and ran on stale state | +| 3 | Conflict markers + invalid JSON committed into 70 generated files | Nothing asserted the generated output still parsed | + +Each is an assertion satisfied by the null case. `push-guard.sh` asserts the **positive** fact instead: a new object exists, the remote *moved*, the content *parses*. + +## Checks + +| Sub-command | Asserts | Exit on failure | +|---|---|---| +| `check-staged` | index has no unmerged paths | `2` | +| | no conflict markers in staged content | `2` | +| | the conflict scan actually *completed* | `2` | +| | staged JSON under `--json-path` parses | `3` | +| | **something is actually staged** | `5` | +| `push` | HEAD advanced past `--since-head` | `5` | +| | HEAD is a non-empty commit | `5` | +| | remote **moved**, and now equals local HEAD | `4` | + +## Usage + +```bash +push-guard.sh check-staged --json-path 'data/**/*.json' + +BEFORE=$(git rev-parse HEAD) +git commit -m "..." +push-guard.sh push --remote origin --branch main --since-head "$BEFORE" +``` + +`--since-head` is what distinguishes "committed nothing" from "committed something", and capturing the remote ref *before* pushing is what makes `remote == local` mean anything. Both were missing from the guard that produced incident 1. + +## Design decisions that measurement forced + +These are the interesting part; each one was wrong in the first draft. + +**A bare `=======` is deliberately NOT treated as a conflict marker.** It collides with reStructuredText underlines and ASCII rules. Every genuine conflict git writes also contains `<<<<<<<` and `>>>>>>>`, so requiring those loses no real detection. Measured against a real repository: **zero** false positives across the entire tracked tree. + +**The JSON check is opt-in by path, not on-by-default.** The first draft checked every staged `*.json`, on the reasoning that broader is strictly stronger. Measured against the same repository: **17 of 119** tracked `.json` files fail a strict parse, *all legitimately* — every `tsconfig*.json` is JSONC (comments are legal there) and the CA templates are Go templates that merely carry a `.json` suffix. An on-by-default check fires on ~14% of the repo's JSON, and a guard that cries wolf gets routed around until the bypass is habitual — at which point the bypass covers the true positives too. Broader was **weaker**. + +**`--json-path` values are normalized to `:(glob)` magic.** Git's default pathspec matching makes `data/**/*.json` require at least one intermediate directory: it matches `data/sub/b.json` and *silently skips* `data/a.json`. The obvious spelling would have delivered partial coverage with no warning. + +## Found by independent review, after the needles were already green + +An adversarial review (author ≠ reviewer) found two genuine fail-opens that 17 self-written needles, five mutation runs and a repo-wide false-positive measurement had all missed. Both were reproduced before being fixed, and both now have needles. + +**Renamed files were invisible to every content check.** Git detects renames by default (`diff.renames=true` since 2.9), so `git mv` plus a small edit is reported as a single `R` entry — which `--diff-filter=ACM` does not match. Reproduced at 97% similarity: the guard printed `staged content OK` and exited 0 with conflict markers in the staged blob. Fixed with `--no-renames`. + +There is a trap inside this one worth recording. With *only* the renamed file staged, the guard exits 5 — the nothing-staged check fires because the file list came back empty. That looks like a catch and is pure accident; co-stage one ordinary file and the fail-open is total. The needle deliberately co-stages a clean file so it cannot pass for the wrong reason. + +**`-I` skipped files marked binary in `.gitattributes`,** while the summary still counted them as scanned — a clean pass *and* a false count. Fixed with `-a`. + +The review also correctly identified one **vacuous control**: the positive `--since-head` case asserted only exit 0, which the push produces anyway, so deleting the entire `--since-head` block left it passing. It now asserts on output. + +Two reported findings did **not** reproduce and were not acted on: `:(glob)` does still match a bare directory pathspec, and my first rename repro failed only because the edit dropped similarity below the detection threshold — a badly built test, not an absent bug. Re-testing properly is what confirmed it. + +## Known limitations — stated, not hidden + +- **The JSON check is unprotected until a repo wires up `--json-path`.** This is a real fail-open. The mitigation is that the guard prints `JSON check NOT REQUESTED` on *every* run, so the unprotected state is visible in every log rather than silent. That printed line is the only thing standing between "not configured" and "not noticed". +- `check-staged` inspects the index. Content added to the working tree *after* it runs is not covered — it belongs in a `pre-commit` hook, where the window is smallest. + +## Test harness + +`test-push-guard.sh` — 19 cases, each check in **both polarities**: + +- **NEEDLE** — a deliberately broken fixture that must trip the guard. +- **CONTROL** — a clean fixture that must pass. + +Controls are not decoration. A guard that failed unconditionally would satisfy every needle and look fully covered. Several controls additionally assert on the guard's *output* (`--out`), because exit 0 cannot distinguish "checked the files and they were fine" from "matched no files and had nothing to check" — two controls in an earlier revision were passing vacuously for exactly that reason. + +### Mutation results — the harness was itself tested by breaking the guard + +| Mutant | Result | +|---|---| +| fail-open (every failure downgraded to exit 0) | 9/16 fail — exactly the needles | +| always-fail | 16/16 fail — controls catch it | +| revert `:(glob)` normalization | 3/16 fail — caught **only** by the `--out` assertions | +| drop the remote-did-not-move assertion | 1/16 fail — the incident-1 needle | +| restore blanket `\|\| true` on the scan | 1/17 fail — the fault-injection needle | +| revert `--no-renames` | 1/19 fail — the rename needle | +| revert `-a` to `-I` | 1/19 fail — the binary-attribute needle | +| delete the `--since-head` block | 2/19 fail — incl. the control that *was* vacuous | +| unmodified | 19/19 pass | + +A guard nobody has watched fail is not a guard. The same applies to the harness: mutant C would have passed silently without the output assertions, so the assertions are load-bearing rather than ornamental. + +**A blanket `|| true` on the scan was a fail-open in the guard's own error handling.** `git grep` exits `1` for "no match" but `>=2` for a real failure. `|| true` collapsed the two, so a malformed pathspec or unreadable index would have been reported as "ok, no conflict markers" — a clean pass from a scan that never ran. The status is now discriminated, and a PATH-shim fault-injection needle proves the refusal. + +**The `-E` flag on `git grep` is load-bearing and was caught by a needle, not by review.** `git grep` defaults to *basic* regex, in which `(`, `|` and `{7}` are literal characters. Without `-E` the patterns match nothing and the check reports a clean pass over a file full of conflict markers — the exact defect this tool exists to prevent, shipped inside the tool itself. + +## Proposed framework path + +``` +framework/tools/git/push-guard.sh +framework/tools/git/test-push-guard.sh +``` + +Matches the existing `tools/git/test-*.sh` convention. Dependencies: bash 4.4+, git, python3 — `python3` is already an accepted dependency of `ci-queue-wait.sh`. + +Operator-agnostic: no hostnames, credentials, remotes, or operator-specific paths. Clean under the framework-PR firewall.