timmy-config/docs/QUALITY_GATES.md

Quality Gates — PR Review Standards

Overview

All pull requests across the Timmy Foundation organization must be reviewed by Perplexity before merge. This standing quality gate leverages Perplexity's demonstrated A+ quality and reliability rating (audit #477).

Policy

• Required reviewer: perplexity (Gitea user ID 7)
• Minimum approvals: 1
• Scope: All repositories under Timmy_Foundation/
• Enforcement: Branch protection on default branch (main)

What This Means

Every PR must receive at least one approving review from Perplexity. No PR may be merged without this approval.

Implementation

1. Branch Protection Rules

Run the setup script once per repo (or across all core repos):

cd timmy-config
./bin/perplexity-quality-gate.sh

The script:

• Determines each repo's default branch
• Sets Gitea branch protection with:
  • required_approving_review_count = 1
  • required_reviewers = [{type: "User", id: 7}] (Perplexity)
  • enforce_admins = true
• Creates or updates the protection rule

Prerequisite: ~/.config/gitea/token must have admin rights on target repos.

2. Default Reviewer Assignment

Perplexity is set as a required reviewer at the branch-protection level. This standing assignment applies automatically to every PR on protected branches.

3. Review Coverage Tracking

Track compliance with the coverage script:

./bin/perplexity-coverage.sh 30   # last 30 days

Outputs:

• Per-repo merged PR count with/without Perplexity approval
• Org-wide coverage percentage
• Logs daily snapshot to logs/perplexity-coverage-YYYY-MM-DD.jsonl

Target: 100%

4. Review Standard

Perplexity follows the PR review template in .gitea/PULL_REQUEST_TEMPLATE.md and issue #387 (PERPLEXITY-02).

Key checklist:

• Correctness — does the change do what the issue asks?
• Security — no secrets, unsafe execution paths, permission drift
• Tests & verification — does the author prove the change?
• Scope — PR matches issue, no scope creep
• Governance — boundary changes require Timmy approval
• Workflow fit — reduces drift, duplication, hidden operational risk

Low-risk, clear-verification, green-CI PRs → APPROVED quickly. Uncertain, missing proof, or risky changes → REQUEST_CHANGES with actionable feedback.

Running the Setup

# 1. Configure Gitea token (once)
export GITEA_URL=https://forge.alexanderwhitestone.com
# token stored at ~/.config/gitea/token

# 2. Apply protections to all core repos
./bin/perplexity-quality-gate.sh

# 3. Verify
# Visit each repo → Settings → Branch Protection → review the rule.
# Or use the Gitea API:
curl -H "Authorization: token $(cat ~/.config/gitea/token)"   "$GITEA_URL/api/v1/repos/Timmy_Foundation/<repo>/branch-protection/main"

Monitoring & Ops

• Daily run: ops-perplexity-coverage (add to ops panel)
• Alert when coverage drops below 100%
• Periodic audit: ensure Perplexity user (ID 7) remains active

Related

• Issue: #477 — Establish Perplexity as standing quality gate
• Reference: #387 — Code review standard
• Audit: #174 — Quality enforcement
• Agent lane: playbooks/agent-lanes.json → perplexity
• Scripts:
  • bin/perplexity-quality-gate.sh — apply protections
  • bin/perplexity-coverage.sh — track coverage
• Workflow: .gitea/workflows/pr-checklist.yml