Github Pre Push Gates

Pre-Push Quality Gates

Before pushing a branch to a shared remote, run through these gates. They prevent pushing credentials, PII, private history, or a broken tree. The skill covers the pre-PR quality phase — use github-pr-workflow for the PR lifecycle itself.

Dependency audit interpretation

• The standard production gate is npm audit --omit=dev --audit-level=high, but a zero result there does not clear a vulnerable developer toolchain. Run the full audit too when the repository ships or executes from source.
• Separate lockfile evidence from installed-tree evidence. npm audit --package-lock-only can pass while stale node_modules still reports old versions; use a clean npm ci in CI and then run ordinary npm audit before declaring the dependency fix verified.
• If a patched transitive version requires an override, verify every resolved package path and exercise tests/build/validation. Do not use npm audit fix --force without reviewing proposed major downgrades and behavior changes.

Workflow overview

[code complete] → [immutable verification] → [privacy scan] → [reviewer] → [push + SHA verify] → [PR]

Each gate is optional by severity — skip when the scope doesn't warrant it, but never skip the privacy scan when pushing to a shared/public remote.

Multi-agent candidate freeze

Before any final gate or read-only review, verify that no write-capable agent still owns the checkout or can advance the branch from an orchestrator/sibling worktree. A clean status alone is insufficient: interrupted parent agents can leave delegated workers alive, continuation controllers can auto-start the next task, and command | tee log can mask an agent failure unless the shell uses set -o pipefail. Freeze the exact SHA across gates and recheck HEAD/status/writers after every long command. For process checks, shared-ref/worktree freezes, dirty-tree fingerprints, safe interrupted-writer recovery, and synthetic secret-fixture classification,

If later work keeps advancing the live development branch, publish the approved ancestor from a detached non-cloud worktree instead of resetting or force-pushing the moving checkout. Re-run immutable gates, privacy scanning, and exact-SHA review there, then push the immutable SHA with an explicit refspec (see §4 for the full frozen-worktree procedure).

If the checkout is under iCloud Drive, OneDrive, Dropbox, or another placeholder-backed sync root, move recovery to a non-cloud development directory before resuming. Resource deadlock avoided, unreadable Git refs/objects, zero-block placeholders, and conflict copies such as file 2.ts invalidate normal Git evidence. Hydrate placeholders before reading, preserve dirty-tree state, and verify the destination before resuming.

---

1. Immutable Verification Gate

Run the full test suite, then verify the working tree and commit SHA did not change. This catches regenerated lockfiles, build artifacts, or side-effect file writes that could invalidate your pass:

set -e
sha=$(git rev-parse HEAD)
test -z "$(git status --porcelain)"
npm test
npx tsc --noEmit
npm run build
npm run validate
git diff --check
# ... any other project-specific gates ...
npm audit --audit-level=high --omit=dev
test -z "$(git status --porcelain)"
test "$sha" = "$(git rev-parse HEAD)"
printf 'IMMUTABLE_GATE=PASS sha=%s\n' "$sha"

Pitfalls:

• Run this AFTER you've finalized what you want to push, not before.
• If git status shows a change after the test suite, investigate — the tree is not reproducible.
• A SHA mismatch means something (npm regenerate, schema generation, etc.) wrote to the tree during testing. Fix the root cause: either commit the generated file, or add it to .gitignore.
• Treat command transport and command output as two independent signals. If a wrapper reports a nonzero exit while stdout contains a final PASS marker—or reports zero while an inner gate failed—do not choose the convenient result. Run a minimal standalone reconciliation that verifies the exact SHA, empty porcelain, committed-range diff --check, and lock/writer state, with an explicit final exit code. Record the first run as contradictory transport evidence, not a pass or product failure.

Static-site theme and contrast gate

When a release changes a website's palette, theme, gradients, or component backgrounds, responsive geometry is not sufficient accessibility evidence.

1. Probe focus-only UI explicitly—especially skip links, menus, dialogs, and controls hidden until keyboard focus. A palette token that passes against white may fail when used as the focused element's background.
2. Calculate contrast from the actual computed foreground/background pair in the rendered state, not from variable names or the page background. Tab to the element in a browser and read getComputedStyle() after focus.
3. Check gradient controls at their weakest endpoint. For normal-size text require at least 4.5:1; for qualifying large text require at least 3:1.
4. Re-run the exact-candidate independent review after any contrast repair because amending the commit invalidates the previous verdict.
5. Keep a deterministic browser assertion in the immutable gate when practical; report the measured ratio and colors so a future palette change cannot silently regress it.

A useful Playwright pattern is: load the page, press Tab, assert the active element is the expected skip link, parse its computed color and backgroundColor, calculate WCAG relative luminance, and require ratio >= 4.5.

For background-clip: text / -webkit-background-clip: text headings, add a visual glyph-paint gate: DOM containment and scrollWidth can pass while the bottom of a gradient line is visibly shaved off. Prefer a small bottom paint allowance on the gradient span (for example padding-bottom: 0.08em) over globally loosening every heading’s line-height. Verify computed padding, overflow: visible, and screenshot appearance at the exact reported width plus mobile/desktop Chromium and WebKit widths; confirm the allowance does not introduce an uneven gap below the headline.

Agent-produced commit acceptance

A background process exit code is not an engineering verdict. An agent can exit 0 after returning HOLD, exhausting turns, leaving a dirty candidate, or failing to commit. Before accepting an agent-produced commit:

1. Read the complete final report and distinguish PASS, HOLD, and native/runtime gaps.
2. Inspect live Git state independently: HEAD, porcelain status, staged/unstaged/untracked paths, locks, and every worktree.
3. Verify the raw commit object with git cat-file commit plus explicit %H/%P/%T/%an/%ae/%cn/%ce formatting. Do not rely only on a wrapper-rendered identity line.
4. Compare the exact changed-path set against the authorized scope and confirm the parent is the frozen baseline.
5. Run committed-range whitespace with two separate revision arguments, for example git diff --check "$parent" "$sha". Do not build a revision expression with control characters or a visually ambiguous separator.
6. Re-run meaningful focused/full tests and the build from the committed tree, then assert the SHA and porcelain are unchanged.
7. Check remote containment separately; a local commit can be accepted without being pushed, but never imply publication from local evidence.
8. If a report says a writer is still active, inspect current process command lines/CWDs and Git locks. A stale summary is not proof of a live writer; conversely, a clean tree is not proof that an orchestrator cannot advance the branch.

For producer/consumer changes across repositories, acceptance also requires field-by-field reconciliation using the producer's minimal exact payload. See specification-compliance-review and ; green convenience fixtures do not prove interoperability.

---

2. Pre-Push Privacy and Secrets Scan

Scan the committed tree for credentials, local paths, private artifacts, and whitespace issues. Run after the immutable gate so the tree is final.

2a. Committed credential scan

Check for API keys, tokens, private keys in the tracked tree:

PAT='AKIA[0-9A-Z]{16}|gh[pousr]_[A-Za-z0-9_]{30,}|sk-[A-Za-z0-9_-]{20,}|-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY-----|xox[baprs]-[A-Za-z0-9-]{20,}'
test -z "$(git grep -IlE "$PAT" HEAD -- . || true)"

2b. Local and internal identifier scan

Check for machine-specific paths, private IP addresses, employer email addresses, and internal assistant/agent/profile persona names:

test -z "$(git grep -IlE '/Users/[^/]|10\.0\.0\.[0-9]|@[a-zA-Z]+\.com' HEAD -- . || true)"
test -z "$(git grep -IlEi '||' HEAD -- . || true)"

Build the profile/persona inventory from the user's actual private environment; generic terms such as router-test, test-profile, alpha, and beta are safe fixture names. Scan the whole candidate tree, current public default branch, every active PR head, and PR metadata—not only added lines. Profile names can be inherited from main or remain exposed on sibling draft branches even when the current diff is clean.

Keep legitimate public author attribution separate from profile-name privacy. A copyright holder or package author is not automatically an internal profile identifier. Also distinguish current-tree cleanup from history purge: removing a name in a new commit does not erase it from reachable Git history, and history rewriting requires separate explicit authorization.

Adjust patterns for the user's environment.

2c. Artifact directory scan

Check for tracked internal artifact directories:

test -z "$(git ls-tree -r --name-only HEAD .hermes .vscode __pycache__ .DS_Store 2>/dev/null || true)"

2d. Commit-range diff scan

Only lines added by this branch (not inherited from main). This avoids false positives from pre-existing public values:

git diff --check origin/main..HEAD

python3 -c '
import subprocess, re, sys
raw = subprocess.check_output(["git","diff","--unified=0","origin/main..HEAD"])
patterns = {
 "credential": re.compile(rb"AKIA[0-9A-Z]{16}|gh[pousr]_[A-Za-z0-9_]{30,}|sk-[A-Za-z0-9_-]{20,}|-----BEGIN.*PRIVATE KEY-----"),
 "local_path": re.compile(rb"/Users/[^/]|10\.0\.0\.[0-9]"),
}
hits = []
for line in raw.splitlines():
 if line.startswith(b"+") and not line.startswith(b"+++"):
 for kind, pat in patterns.items():
 if pat.search(line):
 hits.append((kind, line[:120].decode(errors="replace")))
if hits:
 for kind, text in hits:
 print(kind, text)
 sys.exit(9)
'

2e. Reachable-history and metadata scan

For a new public repository or a branch whose existing history will become reachable, scanning HEAD is insufficient. Inspect every reachable commit and ref—not only the current tree:

• enumerate git rev-list --all and scan the blobs reachable from each revision;
• inspect author/committer names and emails with git log --all --format=...;
• inspect branch/tag refs and run git fsck --full;
• flag unexpected binary blobs, logs, databases, screenshots, exports, or deleted secrets still present in history;
• verify the intended public/noreply commit identity.

A clean current tree does not erase private data from prior commits. If reachable history is unsafe, publish from a new clean history rather than merely deleting the file in a later commit.

---

3. Independent Closeout Review

For significant branches (new feature, cross-repo work, security hardening), run a separate read-only agent as a second opinion:

hermes --profile  --yolo chat --provider  --model  --max-turns  \
 -q 'READ-ONLY final binary check of exact clean commit  in . ...'

Rules:

• The reviewer must inspect without editing, staging, committing, or pushing anything.
• A dispatched or still-running background review is not a PASS. Do not push until the reviewer returns a verdict on the final candidate diff; if the diff changes after review, review the replacement diff again.
• Supply the exact SHA and verify both tree cleanliness and commit identity.
• When the reviewer runs under another Hermes profile, remember that configs, plugins, memory providers, skills, and credentials are profile-isolated. The reviewer's local status is not evidence about the target profile. Either run the live check with hermes --profile ... or provide verified target-profile output as authoritative context.
• If the target is a staging directory rather than a Git repository, say so explicitly and do not let the reviewer turn expected missing Git metadata into a product defect.
• Require a full sentence and file:line for every HOLD. A bare line number or unexplained verdict is not actionable; retrieve the review transcript or rerun with a tighter prompt.
• A HOLD return means either concrete defects or procedural issues (tool budget exhaustion is not a hold — re-run with more turns).
• Write the verdict report to a timestamped file on the user's Desktop when a durable external review artifact is required.
• For large cross-boundary branches, use specification, security/privacy, and code-quality reviewers as distinct axes. Let all finish before one consolidated repair pass; any evidence-backed BLOCKER/HIGH is HOLD even if another reviewer says PASS. Re-review the replacement SHA on each axis that previously held.

Electron and large-diff closeout

For Electron/filesystem features, a passing bridge test does not prove product completeness: trace the production UI route through preload, privileged IPC, and the service, and treat an unreachable user-facing feature as blocking. Review canonical-path, symlink, and TOCTOU behavior across write, rollback, extraction, reveal, and deletion—not only the nominal import call.

For packaged Electron release manifests and scanners, follow the release checklist. It covers built-vs-packaged proof, macOS framework symlinks without dereferencing, regular-entry type checks before hashing, canonical manifest paths, global caps, binary allowlists, literal-backslash spoofing, and idempotent manifest regeneration.

For large branches, partition evidence by risk surface rather than asking one bounded reviewer to ingest the entire diff. Context exhaustion is an incomplete review, never approval. An evidence-backed BLOCKER/HIGH from specification or security review overrides a generic quality PASS until repaired, and every replacement SHA must be re-reviewed.

For multi-skill/tool collection repositories, see for layout, raw-install URL, companion-asset, CI-path, and first-release checks.

---

4. Publishing from Divergent Local History

When local history diverged significantly from origin/main (dozens of commits of internal/campaign/prototype work), do not push the raw history. Expose a clean single commit.

4a. Preserve private history

git branch local/archive/-$(date +%Y%m%d)

4b. Create a clean squash commit

git reset --hard origin/main
git merge --squash local/archive/-$(date +%Y%m%d)

4c. Clean up artifacts from the staged squash

Remove private artifacts, campaign docs, and generated files from staging:

git rm --cached -r .hermes docs/autoresearch-*.md .vscode 2>/dev/null || true
rm -f docs/autoresearch-*.md

4d. Resolve conflicts properly

Real three-way conflicts mean remote main accumulated changes during your local work. Resolve with care:

• For code files (agent.ts, tools.ts): prefer the archive's proven implementation when it is the superset
• For configuration files (plugin schemas, YAML): prefer the archive's companion-aware version
• For lockfiles (package-lock.json): regenerate via npm install and stage the result
• For test files testing a superseded implementation: git rm --cached them rather than forcing incompatible tests into the publication commit

4e. Run verification on the squash

npm test
npx tsc --noEmit
npm run build
npm run validate
git diff --chec

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [AtlasOmnia](https://github.com/AtlasOmnia)
- **Source:** [AtlasOmnia/donna-starter](https://github.com/AtlasOmnia/donna-starter)
- **License:** MIT

Install and usage instructions live in the source repository linked above.