The Cognitive Control Plane for Human-First Software Engineering. Gating pull requests behind interactive architectural quizzes to combat passive "rubber-stamping," preserve developer agency, and prevent systemic deskilling in the age of AI.

📺 View the v1.0.0-alpha Demo (PDF)

Modern software development is experiencing a subtle but profound socio-technical shift. The rise of AI code generation tools has dramatically accelerated output velocity, but it has also introduced a critical vulnerability: cognitive bypass.

When developers delegate code generation to AI assistants, they frequently review the output with passive, low-effort cognitive engagement. This leads to "rubber-stamping"—approving complex, multi-layered code changes without a deep conceptual model of the architecture. Over time, this behaviors generates:

• Systemic Deskilling: The gradual erosion of human engineering intuition, problem-solving capacity, and system understanding.
• Architecture Drift: Silent accumulation of structural complexity and mismatched patterns that humans fail to critique in real time.
• Accountability Debt: Gaps in system ownership where developers are unable to maintain, debug, or justify code they "wrote" but do not comprehend.

ArchiCheck applies Design Thinking to the pull request lifecycle, transforming code verification from a passive checklist into an active, human-first learning gate.

Instead of treating developer verification as a purely administrative task, ArchiCheck introduces friction back into the workflow at strategic moments of complexity. This encourages developers to step out of "System 1" automatic processing and engage their "System 2" deliberate reasoning before code enters the main branch.

• Active Cognitive Gating: Dynamically assesses incoming Git diffs for complexity and AI-reliance cues. If complexity exceeds system thresholds, it locks the PR commit status and generates interactive, language-agnostic architectural comprehension quizzes directly in the PR thread.
• Automatic Secret & Privacy Sanitizer: Utilizes ECMAScript regex lookbehinds and protective execution limits to redact sensitive items (such as AWS credentials, Google API keys, or Slack bot tokens) from code diffs before transmitting data to external LLMs, protecting repository secrets from context window exposure.
• Free-Tier Developer Sandbox (Local AI Playground): Offers a stateful, offline playground featuring a custom-built, React-based "Pipeline Thread" UI. Developers can locally seed mock scenarios, test answers, view separate prompt/generation token telemetry, and debug evaluate rubrics locally without live GitHub webhook connections. See the Local AI Playground Guide.
• Edge-Ready Asynchronous Lifecycles: Features an intelligent background execution manager that leverages serverless waitUntil hooks on Edge runtimes, or falls back to an in-memory queue with graceful termination hooks on standalone container runtimes to prevent thread loss during container restarts.
• Pre-LLM Deterministic Guardrails: Uses high-efficiency, pre-LLM check filters to reject obvious keyboard mashing, spam answers, or duplicate letter strings instantly, saving API token quotas and giving developers immediate local warning badge feedback.

flowchart TD
    Developer[GitHub Developer] -->|1. Opens PR / Pushes Code| GitHub[GitHub REST API / Webhooks]
    GitHub -->|2. Webhook Event Triggered| HMAC[HMAC Verifier Gate]
    HMAC -->|3. Signature TimingSafe Verified| App[ArchiCheck Webhook App]
    App -->|4. Lock Commit Status to Pending| GitHub
    App -->|5. Fetch PR Diff & Match Custom Rules| GitHub
    App -->|6. Run Sanitizer & Heuristics Check| Heuristics{Heuristics Decides?}
    
    Heuristics -->|Bypass: Low Complexity| AutoApprove[Set Commit Status to Success]
    Heuristics -->|Gate: High Complexity| QuizGen[Generate Quiz & Post PR Comment]
    
    Developer -->|7. Replies to PR Quiz Comment| GitHub
    GitHub -->|8. Webhook Comment Triggered| App
    App -->|9. Run Pre-LLM Spam Filters| Filter{Gibberish Checked?}
    
    Filter -->|Failed| RejectComment[Post Warning Comment & Keep Gate Locked]
    Filter -->|Passed| Evaluator[Validate Answer via LLM Provider]
    
    Evaluator -->|Passed Heuristics Rubric| ApprovePR[Set Commit Status to Success & Post Pass Comment]
    Evaluator -->|Failed Heuristics Rubric| KeepLocked[Keep Commit Status Locked & Post Alert]

ArchiCheck is designed in accordance with the Human-First-AI Framework (as detailed at humanfirstengineering.dev). Rather than aiming to automate the developer out of the system, ArchiCheck utilizes AI to enhance human agency, cognitive responsibility, and knowledge retention.

We enforce a strict, documentation-driven Scoping Process before any code is generated. Every proposed epic, feature, or tool begins with a rigorous system scoping report mapping out target outcomes, boundaries, user friction points, and failure domains. This keeps technical debt quarantined and guarantees that development remains aligned with human accessibility needs.

ArchiCheck executes within a bounded, declarative AI-Agent Governance framework. Autonomous agents are prohibited from making unverified mutations or side-effects. All security boundaries, mock stubs, and pipeline caching structures are locked under strict execution schemas, ensuring that AI agents act as auxiliary partners while humans maintain architectural authority.

ArchiCheck represents a live experiment in "AI-Scrum"—running autonomous, stateful AI agent teams within the operational cadence of high-performing human engineering teams.

• Cadence & Sprints: Agents operate within structured sprint windows. Sprints feature flexible timelines, adjusting dynamically to accommodate complex scoping needs, manual code audits, or system validation cycles.
• Rigorous Continuous Improvement: Each iteration concludes with a brutal, honest retrospective mapping out what went wrong, identifying AI hallucination modes, and recording technical blockers.
• Human-in-the-Loop Reviews: Agent-generated plans, schema changes, and pull requests must undergo human review gates. This pairing of agentic execution with human oversight ensures quality and system safety at scale.

For deep-dives into the architecture, security models, policies, testing gates, and development procedures of ArchiCheck, refer to the ArchiCheck Documentation Index.

The index maps the entire documentation layout:

• Onboarding: Step-by-step guides for registering your GitHub App and utilizing the Local AI Playground Guide sandbox.
• Architecture & Design: Architectural Decision Records (ADRs), API Contracts, and environment diagrams.
• Security & Threat Models: STRIDE threat modeling, vulnerability registers, and sandbox reviews.
• Applied AI Policies: Model safety settings, prompt engineering guidelines, and gibberish mitigations.
• Project Management: Sprint reports, Scrum backlogs, risk registers, and state tracking.
• Testing & Release Gates: Vitest rules, Playwright integrations, and manual UAT test checklists.

• Node.js (v20+ recommended)

If you want to run tests or explore the Local AI Playground immediately without registering GitHub Apps, Redis, or LLM API keys:

1. Clone the Repository:

   git clone https://github.com/tinhct/archi-check.git
   cd archi-check

2. Install Dependencies: This automatically initializes a local .env.local file preconfigured to use the offline Mock LLM provider and mock database:

   npm install

3. Start the Dev Server:

   npm run dev

4. Explore & Test:

   • Open your browser to http://localhost:3000/playground to test diffs, secret scrubbing, and justification evaluation.
   • Run the test suite: npm run test:run (unit & integration tests) or npm run test:e2e (local Playwright E2E simulation).

If you are ready to connect ArchiCheck to your actual repositories to enforce PR gating checks:

1. Register Your GitHub App: Follow the step-by-step GitHub App Installation Guide to register your App, configure permissions, and collect your keys (GITHUB_APP_ID, GITHUB_PRIVATE_KEY, and GITHUB_WEBHOOK_SECRET).

2. Run the Setup Wizard: Configure your free-tier Gemini API key for live-fire LLM questions:

   npm run setup:keys

3. Configure Your Gated Target Repositories: Add a .archicheck.yml configuration file to the root of the repository you want to protect (committed directly to the feature branch you are opening the PR from) to activate the gating rules.

To customize complexity thresholds, exclude paths, or configure AI-reliance ratios, add a .archicheck.yml configuration file to the root of your gated repositories (the external repositories you want to protect and gate, e.g. your-org/your-app-repo).

Here is the supported configuration schema with standard default values:

# .archicheck.yml (Add to the root of your gated repository)
algorithmic_complexity_score: 5      # Gate PRs scoring 5 or higher (1 to 10)
ai_reliance_ratio: 0.7              # Gate if AI reliance is >= 70% (0.0 to 1.0)
lines_added_threshold: 300          # Min code additions to trigger Velocity Gate (default: 300)
excluded_paths:                     # Paths ignored during analysis
  - "**/node_modules/**"
  - "package-lock.json"
  - "yarn.lock"
  - "pnpm-lock.yaml"

We maintain a comprehensive, plain-English Frequently Asked Questions Guide covering:

• Algorithmic Gating & Metrics: How complexity scoring and the "Spray & Pray" velocity filters are calculated.
• Security & Data Privacy: Outbound secrets redaction, HMAC timing-safe webhook verification, and Vercel Edge middleware access rules.
• Integrations & AI: How the fail-open resiliency policies, timeout gates, and administrative slash bypass commands operate under outage conditions.
• Local Playground Sandbox: How the offline two-stage evaluation pipeline and per-question textboxes work.

Refer to the FAQ Guide for complete details on onboarding, limitations, and customization options.

ArchiCheck is open-source software released under the MIT License.