BUGGERS/SYSTEM ARCHITECTURE & TECHNICAL SPECIFICATIONS

Engineering Documentation

Deterministic release intelligence, mathematical risk models, automated OWASP AST vulnerability scanners, and production deployment specifications grounded in verified pull request diffs.

10 SPECIFICATION MODULES

Core Architecture

Purpose-built for release confidence.

Engineered from first principles with deterministic AST scanners, orthogonal Shannon entropy tensors, and sub-second diff verification.

FIG 0.1 · AST DECONSTRUCTION

Deterministic-first triage

Zero-overhead regex scanners and AST verification execute in-process before invoking LLMs, ensuring zero hallucination on critical file coordinates.

Zero-runtime AST

FIG 0.2 · SIGNAL TENSOR

Mathematical risk synthesis

Combines 8 orthogonal signals—churn volume, Shannon diffusion entropy, test ratios, and author unfamiliarity—into a calibrated score between 0 and 100.

8 orthogonal tensors

FIG 0.3 · VELOCITY PIPELINE

Designed for high velocity

Engineered with Nitro SSR, Vinxi, and Supabase RLS for sub-second page transitions, instant diff caching, and zero developer review fatigue.

140ms p95 latency

SPECIFICATION 01 / DIFF TRIAGE & BOT ACTIONS

Build, review, and ship

Streamline code reviews with clear diffs, whole-repo defect churn context, and fewer noisy back-and-forth comments. Keep PRs moving without sacrificing quality.

Explore triage architecture

In Review (3 active PRs)AST Triage Active

src/auth/session.ts

Scroll to trigger

05import { createHmac, timingSafeEqual } from 'node:crypto';

06export function verifySessionToken(token: string, session: Session) {

07 const sig = req.headers.get('x-signature') ?? '';

08 if (token === session.signature) {

09 return { verified: true, session };

10 }

11 throw new UnauthorizedError('HMAC signature mismatch');

12}

Buggers Review BotReady

CWE-208

Direct equality operator === leaks execution time through early byte mismatch termination. Constant-time comparison via timingSafeEqual prevents side-channel token recovery.

Awaiting AST completion

Features

SPECIFICATION 02 / MULTI-PROVIDER AI ORCHESTRATION

AI and automations

Build and deploy multi-provider fallback chains that triage diffs alongside deterministic scanners. Inspect AST changes together or delegate routine syntax fixes end-to-end.

View pipeline specifications

Buggers TriageActive (0ms)

In-process regex scanner & AST structural verification

Evaluates diff patches in 140ms with zero token cost before any LLM API is invoked.

Stage 1-5 In-Process$0.00 / PR

Claude 3.5Primary AI

Deep architectural refactoring & defect reasoning

Generates verified replacement diff hunks with exact line mappings and rationale.

~2,410 tokens$0.007 / PR

GPT-4oFallback 1

Standby secondary verification & JSON schema parsing

Automatically triggered if primary AI rate-limits or times out after 4 seconds.

Automatic Failover<200ms switch

Gemini FlashFallback 2

High-throughput emergency queue processing

Zero-downtime queue worker fallback handling large mono-repo diff bursts.

1M Context WindowFast Stream

Features

SPECIFICATION 03 / MATHEMATICAL RISK MODEL 1.1.0

Deterministic risk scoring

Calculate multi-dimensional risk scores (0–100) before merging. Align your team with saturating churn curves, historical fault lines, and regression probability.

Explore quality gate integration

Risk Engine 1.1.0 Live Simulator

MEDIUM (46/100)

Lines Churned:340 lines

Saturating curve: saturate(340, 400) = 46% contribution (weight: 0.18)

Historical 90-Day Churn:18 avg commits

Saturating curve: saturate(18, 15) = 55% contribution (weight: 0.20)

Past Defect Commits on Files:6 commits

Defect multiplier: 0.30 × 2.0x (weight: 0.20)

Touches Critical Manifests:

Pull Request Risk Distribution(30 Pull Requests)

Policy Threshold: 50

100Critical Tier (>75)

Release v1.8.0Release v1.9.0 (Active)Release v2.0.0 (Staged)

Additive Normalized Formulation

Computed deterministically without hallucinated priors:

Score = round( Σ(s.value × s.weight) / Σ(s.weight) × 100 )

• saturate(n, mid) = n / (n + mid): Smooth non-linear asymptote
• insufficient_data: Automatically dropped from denominator
• confidence: Proportion of observed weights × file coverage

Observable Signal Weights Matrix

Signal ID	Weight	Midpoint / Parameter
change_size	0.18	400 lines
file_churn	0.2	15 commits (90-day window)
defect_history	0.2	2.0x multiplier on fix/revert commits
change_spread	0.08	12 files
test_changes	0.09	0.33 code-to-test ratio
dependency_changes	0.05	0.60 manifest modification penalty

Features

SPECIFICATION 04 / DECLARATIVE MERGE GATES (.buggers.yml)

Policy enforcement & merge gates

Enforce declarative repository security policies via instant GitHub commit status checks, custom branch protection rules, and real-time team alerts.

Inspect pre-execution scanners

Repository Policy Controller.buggers.yml

Max Allowable Risk Threshold:50 / 100

Block on Plaintext Secrets:

Block on Critical OWASP SAST:

Simulated GitHub Commit Check Evaluation

buggers/quality-gate

Passed

1. Composite Risk Score:46 ≤ 50 (Passed)

2. Plaintext Credentials:0 Detected (Passed)

3. Critical SAST Vulnerabilities:0 Detected (Passed)

Context: buggers/quality-gateEvaluated in 140ms

Declarative Configuration File (.buggers.yml)

.buggers.yml

# .buggers.yml - Declarative Repository Quality Gate Policy
version: "1.0"

rules:
  # Maximum allowable composite risk score (0-100)
  max_risk_score: 50

  # Block pull requests if any plaintext credentials are discovered
  block_on_secrets: true

  # Block on critical static analysis findings (Command/SQL injection)
  block_on_critical_sast: true

  # Minimum required test-to-code change ratio
  required_test_ratio: 0.20

  # Files requiring strict review when modified
  critical_files:
    - "src/auth/**"
    - "src/server/**"
    - "supabase/migrations/**"

status_checks:
  context: "buggers/quality-gate"
  post_summary_comment: true
  auto_apply_safe_fixes: false

Features

SPECIFICATION 05 / IN-PROCESS SCANNER TESTBED

Pre-execution security & SAST

Zero-overhead, in-process scanners inspect every diff hunk before any LLM inference occurs. Plaintext credentials and OWASP Top 10 vulnerabilities are caught deterministically.

Inspect worker execution pipeline

Interactive In-Process Scanner Testbed

diff --git a/test.ts b/test.ts

Live Regex Evaluation

Scanner Output1 FINDINGS DETECTED

AWS Access Key IDLine 6

Matched: AKIAIOSFODNN7EXAMPLE

Store AWS credentials in AWS Secrets Manager or environment variables (AWS_ACCESS_KEY_ID).

Plaintext Secret Patterns (8 Rules)

In-Process Regex

AWS Access Key ID

\b(AKIA[0-9A-Z]{16})\b

AWS Access Key ID exposed directly in source code.

GitHub Personal Access Token

\b(gh[pousr]_[A-Za-z0-9_]{36,255})\b

GitHub Access Token exposed in source code.

OpenAI API Key

\b(sk-[a-zA-Z0-9_\-]{20,64})\b

OpenAI Secret API Key exposed in source code.

Slack Webhook or Token

(https:\/\/hooks\.slack\.com\/services\/T[0-9A-Z]{4,12}\/B[0-9A-Z]{4,12}\/[0-9a-zA-Z]{18,32}|xox[baprs]-[0-9a-zA-Z-]{10,48})

Slack API Token or Incoming Webhook URL exposed in plaintext.

Stripe Live Secret Key

\b(sk_live_[0-9a-zA-Z]{24,34})\b

Stripe Production Secret Key detected in repository.

Google Cloud / Firebase API Key

\b(AIza[0-9A-Za-z\-_]{35})\b

Google Cloud / Maps API Key detected in code.

Unencrypted Private Key Block

-----BEGIN (?:RSA|EC|DSA|OPENSSH|PGP|PRIVATE) KEY-----

Cryptographic Private Key header discovered in commit diff.

Database Connection String with Password

Database connection string containing plaintext password credentials.

OWASP Top 10 SAST Scanners (7 Rules)

Zero Token Inference

Command Injection via Child Processcritical

\b(?:exec|execSync)\s*\(\s*(?:`[^`]*\$\{[^`]+\}[^`]*`|[a-zA-Z0-9_\.]+\s*\+\s*["'`a-zA-Z0-9_\.])

User input or variable concatenation detected inside a shell execution command.

SQL Injection via String Concatenationcritical

(?:(?:SELECT|INSERT|UPDATE|DELETE|FROM|WHERE)\s+[^\n]*\$\{|\b(?:query|\$queryRawUnsafe|literal)\s*\(\s*`[^`]*(?:SELECT|INSERT|UPDATE|DELETE|FROM|WHERE)[^`]*\$\{)

Direct string interpolation detected in a SQL statement.

Potential Path Traversal in File System Accesshigh

File system access constructed directly from HTTP request parameters without sanitization.

Server-Side Request Forgery (SSRF)high

HTTP client requests a URL supplied directly by user input without domain validation.

Overly Permissive Insecure CORS Configurationmedium

cors\(\s*\{[^\}]*origin\s*:\s*["'`]\*["'`][^\}]*credentials\s*:\s*true

CORS configuration pairs wildcard origin ('*') with credentials: true.

Weak Hash Algorithm (MD5 / SHA-1)medium

crypto\.createHash$\s*["'](?:md5|sha1)["']\s*$

Legacy hash algorithm (MD5 or SHA-1) used for cryptographic operations.

Insecure Randomness for Security Tokensmedium

(?:token|session|csrf|secret|apiKey)\s*=\s*[^;\n]*Math\.random

Math.random() used to generate security-sensitive tokens.

SPECIFICATION 06 / WORKER RUNTIME & HEARTBEAT LEASES

Worker runtime & 9-stage pipeline

Background analysis runs in isolated 9-stage passes governed by 5-minute heartbeat leases and exponential backoff reapers.

Explore dual-auth architecture

EXECUTION RUNTIME SPECIFICATION

9-Stage Deterministic Analysis Pipeline

Select any stage in the sequence to inspect its internal logic, latency profile, and persisted outputs.

Typical End-to-End: ~3.5–6.0s

5. Historical 90-Day ChurnRepository Intelligence

Execution Latency: 400–900ms

Inspects the last 90 days of commit history for modified files on the base branch to evaluate past defect density.

Persisted Outputs & Telemetry

Historical commit count

Defect-associated commit ratio

File inception age

SPECIFICATION 07 / DUAL-AUTH ISOLATION & NITRO ROUTES

Architecture & API reference

Strict separation of authentication boundaries: User authentication via Supabase JWT with Row-Level Security, and GitHub repository tokens encrypted via AES-256-GCM.

View production deployment runbook

Dual-Auth Boundary IsolationZero Secret Leakage

1. Browser Client

Maintains Supabase JWT session in local storage. Never touches GitHub OAuth tokens or database service role keys directly.

Headers: Bearer <SUPABASE_JWT>

2. Nitro SSR & RPC

Verifies caller JWT on every RPC function. Decrypts AES-256-GCM tokens on demand in memory, never logging or leaking them.

Key: APP_USER_CONNECTION_KEY_SECRET (AES-256)

3. PostgreSQL & RLS

Strict Row-Level Security ensures users can only read their own repositories, pull requests, analyses, and findings.

Policy: auth.uid() = user_id

Nitro REST Webhooks & Internal Endpoints

HTTP / JSON

Endpoint	Method	Authentication
/api/webhooks/github	POST	HMAC SHA-256 (X-Hub-Signature-256)
/api/cron/worker	GET	Bearer Token (CRON_SECRET)
/api/health	GET	Public

SPECIFICATION 08 / VERIFIED DEPLOYMENT RUNBOOK

Production deployment & runbook

Step-by-step verified guide for provisioning Supabase PostgreSQL schemas, GitHub OAuth credentials, cryptographic secrets, and Vercel edge deployment.

Open your Supabase SQL editor and execute the complete schema definition located in supabase-setup.sql at the root of the repository. This provisions the 8 core tables:

profilesuser_connectionsrepositoriespull_requestspr_analysesfindingsfinding_commentsdiff_caches