chore(governance): reduce required merge load and add pre-push lint/test gate (#357)

Author: Cataldir

.githooks/pre-push

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(git rev-parse --show-toplevel)"
+cd "$repo_root"
+
+python scripts/ops/pre_push_gate.py

.github/workflows/codeql.yml

@@ -14,8 +14,6 @@ name: "CodeQL Advanced"
 on:
   push:
     branches: [ "main" ]
-  pull_request:
-    branches: [ "main" ]
   schedule:
     - cron: '37 7 * * 1'
 

CONTRIBUTING.md

@@ -27,6 +27,8 @@ Get-ChildItem apps | ForEach-Object {
 - Format/lint: `python -m isort --check lib apps` then `python -m black --check lib apps` and `python -m pylint lib/src apps/*/src`
 - Tests: `pytest lib/tests apps/**/tests --maxfail=1 --cov=. --cov-report=term-missing --cov-fail-under=75`
 - Coverage floor is 75% to match CI.
+- Optional (recommended) push gate setup: `git config core.hooksPath .githooks`
+- With push gate enabled, every push runs `scripts/ops/pre_push_gate.py`, which mirrors CI lint/test gate commands used by `.github/workflows/lint.yml` and `.github/workflows/test.yml`.
 - Run a service locally (example): `uvicorn main:app --reload --app-dir apps/ecommerce-catalog-search/src --port 8000`
 - Keep README and docs in sync when adding adapters, agents, or services.
 

docs/governance/README.md

@@ -74,6 +74,11 @@ Detailed policy is defined in [Infrastructure Governance](infrastructure-governa
 - Minimize bypass actors to explicit break-glass identities only
 - Revalidate protections after any GitHub ruleset/permission change
 
+### Required checks baseline for `main`
+
+- Required checks should be limited to `lint` and `test` in strict mode to reduce merge queue pressure while preserving core quality gates.
+- Additional workflows (for example CodeQL and non-blocking governance audits) remain recommended but should not be configured as required merge checks unless explicitly approved.
+
 ## Verification Procedure (PR-only governance)
 
 Use both checks below for governance hardening and drift detection:
@@ -95,6 +100,14 @@ Use both checks below for governance hardening and drift detection:
 	  - branch deletion blocked
 	  - bypass actors minimized to explicit allowlist
 
+#### Admin enforcement command (GitHub API)
+
+For repositories using branch protection (instead of organization-level rulesets), an admin can enforce the baseline with:
+
+`gh api -X PUT repos/<owner>/<repo>/branches/main/protection -H "Accept: application/vnd.github+json" --input <payload.json>`
+
+Where `<payload.json>` sets strict required checks to `lint` and `test` and keeps PR-only protections enabled.
+
 ### Current External Governance Gap
 
 - Ruleset/protection enforcement itself is controlled by repository admin permissions and cannot be remediated by branch code changes alone.

scripts/ops/pre_push_gate.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""Run repository push gate checks aligned with CI lint/test workflows."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def run_step(command: list[str], *, title: str) -> None:
+    print(f"\n==> {title}")
+    print("$", " ".join(command))
+    subprocess.run(command, check=True, cwd=ROOT)
+
+
+def run_lint_gate() -> None:
+    run_step(
+        ["python", "-m", "isort", "--check-only", "lib", "apps"],
+        title="Lint gate: isort",
+    )
+    run_step(
+        ["python", "-m", "black", "--check", "lib", "apps"],
+        title="Lint gate: black",
+    )
+
+    pylint_targets = [str(ROOT / "lib" / "src")]
+    pylint_targets.extend(
+        str(path)
+        for path in sorted((ROOT / "apps").glob("*/src"))
+        if (path / "pyproject.toml").exists()
+    )
+    run_step(
+        ["python", "-m", "pylint", *pylint_targets],
+        title="Lint gate: pylint",
+    )
+
+    run_step(
+        [
+            "python",
+            "scripts/ops/check_markdown_links.py",
+            "--roots",
+            "docs/governance",
+            "docs/architecture/README.md",
+        ],
+        title="Lint gate: governance/architecture links",
+    )
+
+    stale_tokens = (
+        "OPERATIONAL-WORKFLOWS.md",
+        "REPOSITORY-SURFACES.md",
+        "governance-map.md",
+    )
+    agents_root = ROOT / ".github" / "agents"
+    stale_refs: list[str] = []
+    if agents_root.exists():
+        for file_path in sorted(agents_root.rglob("*.md")):
+            content = file_path.read_text(encoding="utf-8", errors="ignore")
+            if any(token in content for token in stale_tokens):
+                stale_refs.append(str(file_path.relative_to(ROOT)))
+
+    if stale_refs:
+        print("\nFound stale canonical governance references:")
+        for item in stale_refs:
+            print(f"- {item}")
+        raise RuntimeError("Stale canonical governance references found in .github/agents")
+
+
+def run_test_gate() -> None:
+    run_step(
+        ["pytest", "lib/tests", "--maxfail=1"],
+        title="Test gate: lib tests",
+    )
+
+    app_test_dirs = [
+        str(path)
+        for path in sorted((ROOT / "apps").glob("*/tests"))
+        if path.is_dir() and path.name == "tests"
+    ]
+    run_step(
+        ["pytest", *app_test_dirs, "--ignore=apps/ui/tests"],
+        title="Test gate: app tests (excluding UI tests)",
+    )
+
+
+def main() -> int:
+    try:
+        run_lint_gate()
+        run_test_gate()
+    except subprocess.CalledProcessError as exc:
+        print(f"\nPush gate failed at exit code {exc.returncode}")
+        return exc.returncode
+    except Exception as exc:  # pylint: disable=broad-exception-caught
+        print(f"\nPush gate failed: {exc}")
+        return 1
+
+    print("\nPush gate passed: lint + test checks match CI workflow expectations.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())