GITHOOKS KNOWLEDGE BASE

Generated: 2026-11-04 Commit: eb2097b0 Branch: sprint/2026-11-03-02 Version: 0.37.0.0

OVERVIEW

Git quality gates: pre-commit runs 12 numbered gates (Gate 0–11) plus Gate 12 (File Hygiene, warning-only) via 13 language adapters; pre-push runs 8 gates: Gate 10 (Build Integrity), Gate M (TS mutation), Gate M-Python, M-Go, M-Java, M-Kotlin (multi-lang mutation), Gate M2 (Mock Density, WARNING-only), Gate ML (Mock Layering), Gate UI (UI Sprint Gates), Gate MW (Code Walkthrough), and Gate S (Sprint Flow). Zero-tolerance policy per QUALITY-GATES-CODE-OF-CONDUCT.md — --no-verify strictly prohibited.

STRUCTURE

githooks/
├── pre-commit                    # ~2084 lines: Gate 0 (Version) + Gates 1–9
├── pre-push                      # ~607 lines: Gate M / M2 / M3 + Delphi walkthrough validator
├── adapter-common.sh             # detect_project_lang(), route_to_adapter(), 3-tier resolution
├── adapters/                     # 13 language adapters + plugins/
│   ├── typescript.sh, python.sh, go.sh, java.sh, kotlin.sh
│   ├── cpp.sh, swift.sh, objectivec.sh, shell.sh, powershell.sh
│   ├── dart.sh, flutter.sh, iac.sh
│   │                             # NOTE: no standalone c.sh (cpp.sh handles both C and C++)
│   └── plugins/                  # 5 third-party extensions
│       ├── p3c-java/             # Alibaba P3C Java guidelines
│       ├── whalecloud-java/      # Whalecloud Java rules
│       ├── book299-20132-python/ # Python style rules
│       ├── book299-4081-c/       # C style rules
│       └── book299-4083-javascriptes5/  # ES5 JavaScript rules
├── QUALITY-GATES-CODE-OF-CONDUCT.md  # --no-verify strictly prohibited
├── TOOL-INSTALLATION-GUIDE.md
├── install.sh, verify.sh         # Project-local install + verification
└── __tests__/                    # BATS tests

WHERE TO LOOK

GATES

Pre-commit (12 numbered gates)

The README/docs/CAPABILITIES.md "6 Gates" framing is a conceptual grouping (CodeQ, Complexity, Principles, Tests, Architecture, Security) over these 10 script-level gates. See root AGENTS.md → "Known Drift" #1.

Pre-push (8 gates)

Code-walkthrough has no hard file-count or LOC threshold. Large diffs must be reviewed completely or split by user choice; size-based bypass is not permitted. Code-walkthrough is skipped on main/master pushes by design. All pre-push runs write a JSON journal under .xp-gate/reports/pre-push/<UTC-timestamp>.json.

CONVENTIONS

• 3-tier adapter resolution: ~/.config/xp-gate/adapters/<lang>.sh (global) → <project>/githooks/adapters/<lang>.sh (project) → script dir (fallback).
• Tool unavailable → SKIP, not BLOCK — except Gate 8: since #499 secret scanning is fail-closed — gitleaks missing or exiting non-0/1 BLOCKs the commit (a security gate that cannot run must not report success). CI installs gitleaks for the first-commit job accordingly. Adapter degrades other gates to SKIP when the underlying tool isn't installed; block fires only when the tool exists and the check fails.
• Code-walkthrough scope: no hard file-count or LOC threshold; large diffs require complete review or user-directed splitting, never a size-based bypass.
• Code-walkthrough skipped on main/master. Gate M, M2, M3 still run.
• Boy Scout Rule (Gate 6): new files zero-tolerance; modified files cannot increase warnings; untouched files unchecked.
• Adapter plugins under adapters/plugins/ extend the base language adapters (P3C/whalecloud for Java, book299 for Python/C/ES5 JS). Opt-in per project.
• Project-level coverage exclusions: a project may ship .xp-gate-powershell-coverage-ignore (one glob per line, # comments allowed) to exclude scripts that cannot be exercised by Pester (e.g. bootstrap scripts whose Main ends in exit); the PowerShell adapter drops matching files from coverage accounting instead of counting them as 0%. Python coverage thresholds come from pyproject.toml [tool.coverage.report] fail_under — the adapter never hardcodes a threshold.
• Gate 10 SAST verdict comes from semgrep's JSON, not its exit code (#518): without --error, semgrep exits 0 even with ERROR-severity findings, and its own severity scale (ERROR/WARNING/INFO) never intersects the old CRITICAL/HIGH red-flag vocabulary — the gate used to print PASS on a textbook command-injection finding. The verdict is now parsed from results[].extra.severity with a union vocabulary: blocking = everything OUTSIDE the warnings-only list (WARNING|INFO|MEDIUM|LOW) — i.e. ERROR/CRITICAL/HIGH and any unknown or missing tier fail closed to BLOCK; warnings-only = WARNING|INFO|MEDIUM|LOW. stdout/stderr are captured separately (the old 2>&1 merge poisoned the JSON). --error must NOT be added: its exit-code mapping has drifted across semgrep versions/platforms and the JSON verdict needs nothing from it — keeping it off also leaves failure exit codes unambiguous for the #475 diagnostics path. node is a hard dependency of the verdict and is checked BEFORE the semgrep run (missing node = SKIP with an install hint, not a silent net-loss). Unparseable output, missing verdict fields, or a zero-results run with scan errors/nonzero exit all fail closed to SKIP (never PASS). The same semantics are implemented in the TS CLI gate (src/gates/gate-9.ts, dispatched as xp-gate gate sast); the legacy gate-9*.sh fallback copies are tracked in a follow-up issue. Pinned by __tests__/gate-10-verdict.test.bats and src/gates/__tests__/gate-9.test.ts.
• Python mypy scope is repo-declared (#513, generalizing #501): adapters/python.sh uses .xp-gate-mypy-scope at the repo root when present (one directory per line, # comments allowed — full-line or inline); otherwise existence-guarded src/ + scripts/. Every target (declared or default) must exist AND contain at least one .py file — targets failing the guard are WARNed and skipped, so a typo'd or .py-less declaration degrades to SKIP instead of false-BLOCKing. An empty or fully-unusable declaration also SKIPs (with a distinct WARNING), never a silent pass-through. A repo declaring no type surface SKIPs with a notice pointing to the declaration file instead of false-BLOCKing every .py commit. mypy is invoked per target (matching the CI type job's per-directory runs — a merged mypy src scripts call reports "Duplicate module" for same-named modules and false-BLOCKs). Never a bare mypy .. Pinned by __tests__/adapter-mypy-pester-scope.test.bats.
• PROJECT_SUBDIR derivation is root-aware (#515, R2 delphi-walkthrough): nested project markers only locate a subdir when the repo ROOT itself declares no project. The root short-circuit marker set is the FULL _detect_subdir set (10 markers: tsconfig.json / package.json / pyproject.toml / setup.py / go.mod / pubspec.yaml / pom.xml / build.gradle / build.gradle.kts / CMakeLists.txt) — the two lists must not drift. One exception, checked FIRST (a root tsconfig.json often coexists with it): a root package.json carrying a "workspaces": key is a JS monorepo, not a single project, so derivation keeps running there. Known limitation (#527, pinned in tests): Gradle multi-module, CMake subdirectory layouts and pnpm (pnpm-workspace.yaml) / Lerna (lerna.json) workspaces are not disambiguated from single projects — the root marker wins. With a root marker present, a nested marker that is merely a module file must not hijack the cwd — Gates 1-9 would run in the wrong directory and false-BLOCK on root-relative paths. Pinned by __tests__/subdir-root-shortcircuit.test.bats.
• No CLI invocation in pre-push hook for Delphi. The hook is a validator only — it reads .code-walkthrough-result.json; the actual review must run via the skill before push.
• Adapters are duplicated into src/npm-package/adapters/. Source of truth = here; resync via build scripts.

ANTI-PATTERNS (THIS PROJECT)

• Do NOT use --no-verify to bypass any gate. Process violation per QUALITY-GATES-CODE-OF-CONDUCT.md.
• Do NOT use change size as authorization to bypass code-walkthrough; review large diffs completely or split them before review.
• Do NOT hardcode tool paths in an adapter — use the routing in adapter-common.sh.
• Do NOT delete or rename .code-walkthrough-result.json before push; the validator will block.
• Do NOT add a new gate without adding both a script-level Gate N row AND updating root AGENTS.md + README.md.
• Do NOT edit adapters here without resyncing src/npm-package/adapters/. Source-of-truth is this directory.

UNIQUE STYLES

• Monolithic pre-commit (~2084 lines) intentionally — single bash file keeps the trust boundary auditable.
• Pre-push is a thin validator — heavy lifting (mutation, mock policy, Delphi) lives in src/ modules invoked via npx tsx.
• Graceful adapter degradation: SKIP semantics keep the hook useful in mixed-language repos.
• JSON journal: every pre-push writes .xp-gate/reports/pre-push/*.json for audit / xp-gate audit --tail.

COMMANDS

# Install per-project hooks + adapter infrastructure
bash githooks/install.sh

# Verify installation integrity
bash githooks/verify.sh

# Run BATS tests
cd githooks/__tests__ && bats *.bats

# Check / repair drift between this directory and the INSTALLED hooks
xp-gate doctor                # reports hook drift + which copy is in charge
xp-gate doctor --sync-hooks   # copy githooks/* over the installed copy

EFFECTIVE HOOKS — READ THIS BEFORE EDITING A HOOK

This directory is the source of truth in version control, but it is not necessarily what executes. When core.hooksPath is set (global install), git runs the copy under ~/.config/xp-gate/hooks/ instead:

$ git config --get core.hooksPath
C:/Users/think/.config/xp-gate/hooks

Editing a hook here therefore has no local effect until you sync. This was the whole of issue #451, and it is easy to misread as "my edit does nothing".

xp-gate doctor                # shows "Effective hooks:", the drift, and its direction
xp-gate doctor --sync-hooks   # make this directory effective, then commit as normal

xp-gate doctor reports drift only when the current project actually carries hook files here (i.e. this repo, or a fork). Consumer projects get only githooks/adapters/ from xp-gate init, which is not a hook source of truth.

NOTES

• See repo root AGENTS.md → "Known Drift" for the canonical list of doc-vs-reality gaps (gate count, C-adapter claim, etc).
• Pre-push reads .code-walkthrough-result.json and compares commit_hash to git rev-parse HEAD.
• Main-branch push: Gate M / M2 / M3 still execute; only the walkthrough validator is skipped.
• Mutation testing CI: .github/workflows/mutation-test.yml narrows --mutate to the files changed in the PR (full-suite runs exceed the 45-min budget).