ryderfreeman4logos/quality-gate

Quality Gate: Repository Gate Infrastructure Builder

Create, audit, and optimize multi-layer quality gates for any repository. Gates enforce code quality deterministically — through tooling, not instructions.

Principles

1. Deterministic over instructional — enforce via exit codes, not README prose
2. Fail-closed — unknown state = blocked; only explicit pass allows through
3. Layer defense — pre-commit catches early, pre-push catches drift, pre-merge catches bypass
4. Sandbox-aware — skip gates that can't run in CI/sandbox (check writable paths)

Gate Architecture (4 Layers)

Layer 1: PRE-COMMIT (developer machine, every commit)
  ├── Branch protection (block commits to protected branches)
  ├── Monolith guard (block oversized files by token/line count)
  ├── Artifact guard (block generated/scratch files from staging)
  ├── Version guard (version must differ from base branch)
  ├── Charset guard (enforce codebase language consistency)
  ├── Format (auto-format + auto-stage formatted files)
  ├── Lint (language-specific strict linting)
  ├── Dependency audit (license + vulnerability scanning)
  └── Test (unit + integration + e2e)

Layer 2: PRE-PUSH (before code reaches remote)
  ├── Version bump verification (redundant check, different timing)
  ├── Review verification (require recorded review session for HEAD)
  └── Advisory warnings (e.g., missing PR-bot marker for open PRs)

Layer 3: PRE-MERGE (before merging to protected branch)
  ├── Review completion marker verification
  ├── CI status check (all checks green)
  └── Merge command interception (PATH-injected wrapper)

Layer 4: POST-MERGE (after code lands on protected branch)
  ├── Auto-rebuild (recompile and install updated binaries)
  ├── Notification (audit log, team alerts)
  └── Cleanup (stale branch pruning, marker cleanup)

Execution Protocol

Phase 1 — DETECT (Audit Current State)

Analyze the repository to determine:

1. Tech stack detection:

   # Check for language indicators
   ls Cargo.toml package.json go.mod pyproject.toml Makefile justfile \
      CMakeLists.txt build.gradle pom.xml 2>/dev/null
   

2. Hook manager detection:

   # Lefthook (preferred)
   ls lefthook.yml lefthook.yaml .lefthook.yml 2>/dev/null
   # Husky (Node.js)
   ls .husky/_/husky.sh 2>/dev/null
   # pre-commit (Python)
   ls .pre-commit-config.yaml 2>/dev/null
   # Raw git hooks
   ls .git/hooks/pre-commit .git/hooks/pre-push 2>/dev/null
   

3. Task runner detection:

   ls justfile Justfile Makefile makefile package.json 2>/dev/null
   

4. Existing gate inventory — enumerate all active checks:

   • Parse lefthook.yml / .husky / .pre-commit-config.yaml
   • Parse justfile / Makefile / package.json scripts
   • List scripts/hooks/ directory
   • Check CI config (.github/workflows/, .gitlab-ci.yml, etc.)

5. Coverage gap analysis — compare against the 4-layer model above, report which gates exist and which are missing.

Output a structured audit report with coverage matrix:

GATE AUDIT REPORT
=================
Tech Stack: Rust (Cargo workspace)
Hook Manager: lefthook (v2.x)
Task Runner: just

Layer 1 (Pre-Commit):
  [x] Branch protection
  [x] Format (cargo fmt)
  [x] Lint (clippy)
  [x] Test
  [ ] Monolith guard        <- MISSING
  [ ] Artifact guard         <- MISSING
  [ ] Dependency audit       <- MISSING

Layer 2 (Pre-Push):
  [ ] Version check          <- MISSING
  ...

Phase 2 — DESIGN (Plan Gates)

Based on the audit, design gates for each missing layer. Follow tech-stack-specific best practices:

Tech Stack Reference

| Stack | Format | Lint | Type Check | Test | Dep Audit | Monolith | |-------|--------|------|------------|------|-----------|----------| | Rust | cargo fmt | cargo clippy -- -D warnings | (compiler) | cargo nextest run | cargo deny check | tokuin/wc -l | | Go | gofmt -l . | golangci-lint run | (compiler) | go test ./... | govulncheck ./... | tokuin/wc -l | | Python | ruff format | ruff check | mypy --strict | pytest | pip-audit | tokuin/wc -l | | TypeScript | biome format | biome check | tsc --noEmit | vitest run | npm audit | tokuin/wc -l | | Mixed | Per-language | Per-language | Per-language | Per-language | Per-language | tokuin/wc -l |

Gate Design Decisions

For each missing gate, decide:

1. Hard vs soft fail: Pre-commit checks are hard (exit 1). Advisories are soft (echo warning).
2. Auto-fix capability: Formatters can auto-fix + auto-stage. Linters generally cannot.
3. Skip conditions: When should the gate be skipped? (CI env, sandbox)
4. Performance budget: Pre-commit should complete in < 60s for good DX. Move slow checks to pre-push.

Phase 3 — IMPLEMENT (Create Infrastructure)

Generate the following files based on design decisions:

3a. Hook Manager Config

Preferred: lefthook (language-agnostic, fast, single binary).

# lefthook.yml
pre-commit:
  commands:
    branch-protection:
      run: scripts/hooks/branch-protection.sh
    quality-gates:
      run: just pre-commit

pre-push:
  commands:
    version-check:
      run: scripts/hooks/version-check.sh
    # Add review-check if using csa:
    # review-check:
    #   run: scripts/hooks/review-check.sh

post-merge:
  commands:
    rebuild:
      run: scripts/hooks/post-merge-rebuild.sh

If the project already uses husky or pre-commit, adapt to that tool instead.

3b. Task Runner (justfile or Makefile)

Organize recipes in this order:

1. default: pre-commit          (run all checks)
2. Individual gates:
   a. find-monolith-files       (token/line count guard)
   b. check-generated-artifacts (block generated files from staging)
   c. check-version-bumped      (version differs from base branch)
   d. check-charset             (enforce codebase language if needed)
   e. fmt                       (format + auto-stage)
   f. deny / audit              (dependency audit)
   g. lint / clippy             (strict linting)
   h. test                      (unit tests)
   i. test-e2e                  (end-to-end tests)
3. pre-commit: a b c d e f g h i (orchestration recipe)

Critical patterns to include:

Monolith Guard — block oversized files that degrade LLM/reviewer performance:

# Token-count check (requires tokuin, falls back to line count)
# Thresholds: MONOLITH_TOKEN_THRESHOLD (default 8000), MONOLITH_LINE_THRESHOLD (default 800)
# Process: git ls-files | parallel check_file {}
# Exclusions: *.lock, generated docs, workflow definitions
# Output: actionable error with stash-then-split instructions

Artifact Guard — block generated/scratch files from being committed:

# Check git diff --cached --name-only --diff-filter=ACMR against patterns:
# .test-target/, .tmp/, target/, dist/, node_modules/, __pycache__/
# Allow DELETIONS (cleanup commits should work)

Version Guard — enforce version bump on feature branches:

# Compare current version vs base branch version
# Skip on main/dev, skip if CSA_SKIP_VERSION_CHECK=1
# Error message includes the bump command (just bump-patch / npm version patch / etc.)

Format + Auto-Stage — format and re-add only modified tracked files:

# Run formatter
# git diff --name-only | grep '<ext>' | xargs -r git add
# This allows fmt to be part of pre-commit without manual re-staging

3c. Hook Scripts (scripts/hooks/)

Each hook script MUST follow this template:

#!/usr/bin/env bash
# <Purpose>: <one-line description>
set -euo pipefail

# ── Skip conditions ─────────────────────────────────────────────
# Skip inside sandbox/CI environments
if [ -n "${CSA_SESSION_ID:-}" ]; then
    echo "[<hook>] Inside sandbox -- skipping."
    exit 0
fi

# ── Main logic ──────────────────────────────────────────────────
# ...

# ── Error output ────────────────────────────────────────────────
# MUST include:
# 1. What failed (exact condition)
# 2. How to fix it (exact command)
# 3. Why it matters (one line)

Branch Protection (scripts/hooks/branch-protection.sh):

#!/usr/bin/env bash
set -euo pipefail
branch=$(git symbolic-ref --short HEAD 2>/dev/null) || exit 0
[ -z "$branch" ] && exit 0
PROTECTED="main dev master"
for pb in $PROTECTED; do
  if [ "$branch" = "$pb" ]; then
    echo "BLOCKED: Cannot commit directly to '$branch'."
    echo "Create a feature branch: git checkout -b feat/<description>"
    exit 1
  fi
done

Post-Merge Rebuild (scripts/hooks/post-merge-rebuild.sh):

#!/usr/bin/env bash
# Skip sandbox, check writable target, rebuild
set -euo pipefail
if [ -n "${CSA_SESSION_ID:-}" ]; then exit 0; fi
if [ ! -w /usr/local/bin ]; then
    echo "[post-merge] Install target not writable -- skipping."
    exit 0
fi
echo "[post-merge] Rebuilding..."
if just install; then
    echo "[post-merge] Installed successfully."
else
    echo "[post-merge] WARNING: build failed (exit $?)." >&2
fi

3d. Review Checklist (.csa/review-checklist.md)

Project-specific review items that encode hard-won lessons:

# Project Review Checklist

Common pitfalls and patterns to verify during code review:

- [ ] <Domain-specific check 1>
- [ ] <Domain-specific check 2>
...

Derive items from:

• Recurring review findings (if review history exists)
• Language-specific pitfalls (e.g., Rust: RAII guards + process::exit, Go: goroutine leaks)
• Project architecture constraints (e.g., sandbox writable paths, FFI boundaries)
• Security patterns (e.g., config structs with serde(default) need is_default())

3e. Installation Recipe

Add to justfile:

install-hooks:
    @git config --unset core.hooksPath 2>/dev/null || true
    lefthook install
    @echo "Hooks installed."

Phase 4 — VERIFY

1. Dry-run each gate: Run just pre-commit on the current codebase
2. Test failure modes: Verify each gate produces clear, actionable error messages
3. Performance check: Time just pre-commit — should be < 60s for good DX
4. Sandbox test: Verify hooks skip gracefully when CSA_SESSION_ID is set

Gate Catalog (Complete Reference)

Layer 1: Pre-Commit Gates

1.1 Branch Protection

• Purpose: Prevent direct commits to protected branches
• Fail mode: Hard (exit 1)
• Skip: Detached HEAD
• Action: Suggest feature branch naming convention
• Applies to: All projects

1.2 Monolith File Guard

• Purpose: Block oversized files that degrade LLM and reviewer performance
• Fail mode: Hard (exit 1)
• Thresholds: 8000 tokens / 800 lines (configurable via env)
• Tool: tokuin estimate (fallback: wc -l)
• Exclusions: Lock files, generated docs, workflow definitions, test fixtures
• Action: Stash, split file, retry commit
• Applies to: All projects with LLM-assisted workflows

1.3 Generated Artifact Guard

• Purpose: Block staging of generated/scratch files
• Fail mode: Hard (exit 1)
• Patterns: .test-target/, .tmp/, target/, dist/, node_modules/, __pycache__/, *.pyc
• Exception: Deletions allowed (cleanup commits)
• Applies to: All projects

1.4 Version Bump Guard

• Purpose: Ensure version changes on feature branches
• Fail mode: Hard (exit 1)
• Skip: Main/dev branches, CSA_SKIP_VERSION_CHECK=1
• Action: Show bump command for the project's version tool
• Applies to: Projects with release versioning (libraries, CLIs, services)

1.5 Charset/Encoding Guard

• Purpose: Enforce codebase language consistency
• Fail mode: Hard (exit 1)
• Tool: rg "\p{Script=Han}" (or equivalent Unicode script check)
• Exclusions: i18n files, test fixtures, rule/doc files
• Applies to: Projects with explicit language policy

1.6 Formatting

• Purpose: Consistent code style
• Fail mode: Hard (exit 1 if unformatted files remain)
• Auto-fix: YES — format then git add modified tracked files
• Tools: cargo fmt, gofmt, ruff format, biome format, prettier
• Applies to: All projects

1.7 Dependency Audit

• Purpose: License compliance and vulnerability scanning
• Fail mode: Hard (exit 1)
• Tools: cargo deny check, npm audit, pip-audit, govulncheck
• Applies to: All projects with external dependencies

1.8 Linting

• Purpose: Catch bugs, enforce idioms, prevent anti-patterns
• Fail mode: Hard (exit 1 with -D warnings)
• Tools: cargo clippy, golangci-lint run, ruff check, biome check, eslint
• Applies to: All projects

1.9 Testing

• Purpose: Verify correctness
• Fail mode: Hard (exit 1)
• Tools: cargo nextest run, go test, pytest, vitest run
• Split: Unit tests in pre-commit, slow E2E in pre-push (if > 60s total)
• Applies to: All projects

Layer 2: Pre-Push Gates

2.1 Version Re-verification

• Purpose: Redundant check (catches amend/rebase that reverted version)
• Fail mode: Hard (exit 1)
• Applies to: Same as 1.4

2.2 Review Session Verification

• Purpose: Ensure code has been reviewed before reaching remote
• Fail mode: Hard (exit 1)
• Check: Query csa session list --format json for review session matching branch + HEAD
• VCS support: Git commit_id + jj change_id
• Applies to: Projects using CSA review workflow

2.3 PR-Bot Marker Advisory

• Purpose: Warn about open PRs missing pr-bot verification
• Fail mode: Soft (echo warning, exit 0)
• Check: Look for .done marker file for the PR + current HEAD SHA
• Applies to: Projects using pr-bot workflow

Layer 3: Pre-Merge Gates

3.1 Review Completion Marker

• Purpose: Verify automated review completed for this PR
• Fail mode: Hard (exit 1)
• Check: Marker file exists at ~/.local/state/cli-sub-agent/pr-bot-markers/{REPO}/{PR}-{SHA}.done
• Applies to: Projects using pr-bot

3.2 Merge Command Interception

• Purpose: Intercept gh pr merge to enforce review gate
• Mechanism: PATH-injected shell wrapper that validates marker before forwarding to real gh
• Fail mode: Hard (wrapper exits 1 if marker missing)
• Features: --auto blocking, cross-repo rejection, --help passthrough
• Applies to: Projects using CSA merge guard (csa hooks install-merge-guard)

Layer 4: Post-Merge Hooks

4.1 Auto-Rebuild

• Purpose: Keep local binaries in sync with merged code
• Skip: Sandbox (CSA_SESSION_ID), read-only install target
• Action: Run build + install, warn on failure
• Applies to: Projects that install local binaries

4.2 Audit Logging

• Purpose: Record merge events for compliance trail
• Format: JSONL append to ~/.local/state/cli-sub-agent/audit/merge-events.jsonl
• Fields: timestamp, repo, branch, PR number, HEAD SHA, merger identity
• Applies to: Projects with audit requirements

Anti-Patterns (NEVER Do These)

| Anti-Pattern | Why It's Wrong | Correct Approach | |--------------|----------------|------------------| | --no-verify / -n | Bypasses ALL hooks | Fix the failing check | | LEFTHOOK=0 env var | Disables hook manager | Fix the failing check | | git config core.hooksPath /dev/null | Redirects hooks to void | Use lefthook install | | Catch-all \|\| true in gates | Swallows real failures | Only on skip conditions | | Hard-coding paths in hooks | Breaks portability | Use git rev-parse --show-toplevel | | Running slow tests in pre-commit | Ruins DX (> 60s) | Move to pre-push or CI | | Advisory-only for critical gates | Gets ignored | Hard fail with clear error | | Checking tool version in gate | Fragile, over-specified | Check behavior, not version |

Example Usage

| Command | Effect | |---------|--------| | /quality-gate | Full audit of current repository's gate infrastructure | | /quality-gate audit | Audit-only (no changes) | | /quality-gate create | Create gate infrastructure from scratch | | /quality-gate optimize | Analyze and improve existing gates | | /quality-gate add monolith-guard | Add specific gate to existing setup |

Done Criteria

1. Audit report generated with coverage matrix for all 4 layers.
2. Hook manager config created or updated (lefthook.yml preferred).
3. Task runner recipes cover all applicable gates for the tech stack.
4. Hook scripts follow the standard template (skip conditions, clear errors).
5. Each gate tested: runs successfully on clean codebase.
6. just pre-commit (or equivalent) exits 0 on current codebase.
7. Performance: pre-commit completes in < 60s.
8. Sandbox safety: hooks skip gracefully when CSA_SESSION_ID is set.
9. Review checklist created with project-specific items (if applicable).
10. lefthook install (or equivalent) documented in setup recipe.