sentinel-method

sentinel-method

The AI Code Quality Gate That Thinks Before It Ships

14 validators. Sub-agent verification. Consensus engine.
One command between chaos and production.

The Problem

AI generates code fast. But fast != safe. Every unchecked commit is a potential security breach, a performance regression, an accessibility violation, or a maintenance nightmare waiting to happen.

The Solution

Sentinel Method is a production-grade quality gate that intercepts AI-generated code and subjects it to 14 independent validators, dual sub-agent verification, and a consensus engine — all before a single line reaches your codebase.

npx sentinel validate ./src

That's it. One command. Zero tolerance for bad code.

Quick Start

# Install
npm install sentinel-method

# Validate your project
npx sentinel validate ./src

# Initialize config files
npx sentinel init

# Install git hooks (pre-commit + pre-push)
npx sentinel hooks --install

The 14 Validators

Architecture

                         ╔══════════════════════════════════════╗
                         ║        SENTINEL METHOD v3.0          ║
                         ║    "Trust, but verify. Twice."       ║
                         ╚══════════════╦═══════════════════════╝
                                        ║
                    ┌───────────────────╨───────────────────┐
                    │          14 VALIDATOR MATRIX           │
                    │                                       │
                    │  Testing ─── Security ─── Performance │
                    │  Maintain ── Dependency ── Docs       │
                    │  Style ──── Architect ─── API         │
                    │  A11y ───── i18n ──────── Errors      │
                    │  Types ──── Dead Code                 │
                    └───────────────────┬───────────────────┘
                                        │
              ┌─────────────────────────┼─────────────────────────┐
              │                         │                         │
   ╔══════════╧═══════════╗  ╔═════════╧══════════╗  ╔══════════╧═══════════╗
   ║   SUB-AGENT VERIFY   ║  ║  INTELLIGENCE LAYER ║  ║   SENTINEL ENGINE    ║
   ║                       ║  ║                     ║  ║                      ║
   ║  SecurityVerifier     ║  ║  BusinessGates      ║  ║  Promise.all()       ║
   ║  ConsensusEngine      ║  ║  RiskBudget         ║  ║  PluginLoader        ║
   ║  Taint Flow Analysis  ║  ║  FitnessFunctions   ║  ║  ResultCache         ║
   ╚══════════╤═══════════╝  ╚═════════╤══════════╝  ╚══════════╤═══════════╝
              └─────────────────────────┼─────────────────────────┘
                                        │
                         ╔══════════════╧═══════════════╗
                         ║    REPORTER + CLI OUTPUT      ║
                         ║  Console │ JSON │ MD │ HTML   ║
                         ╚══════════════════════════════╝

How Sub-Agent Verification Works

Sentinel doesn't just run validators — it verifies its own findings. The ConsensusEngine runs dual independent analysis paths and only reports issues where both agents agree. This eliminates false positives and gives you confidence that every flagged issue is real.

Validator Result ──→ Agent A (SecurityVerifier) ──→ ┐
                                                     ├──→ ConsensusEngine ──→ Final Verdict
Validator Result ──→ Agent B (Independent Check) ──→ ┘

CLI Reference

# Core validation
sentinel validate [directory] [options]

# Project setup
sentinel init [--force]

# Git hooks
sentinel hooks --install | --remove | --status

# List validators
sentinel list

Options

-f, --format <format>              Output: console | json | markdown | html
-t, --testing-threshold <n>        Min testing score (default: 80)
-s, --security-level <level>       strict | moderate | permissive
-p, --performance-target <target>  optimal | good | acceptable
-m, --maintainability-score <n>    Min maintainability (default: 75)
-o, --output <file>                Save report (auto-detects format)
-w, --watch                        Re-run on file changes
--fail-on-warnings                 Treat warnings as failures
--json                             Shorthand for -f json
--min-severity <level>             Filter: error | warning | info

Exit Codes

Programmatic API

import { Sentinel } from 'sentinel-method';

const sentinel = new Sentinel({
  testingThreshold: 80,
  securityLevel: 'strict',
  performanceTarget: 'optimal',
  maintainabilityScore: 75,
});

const result = await sentinel.validate('./src');

if (result.success) {
  console.log('Quality gate passed!');
} else {
  console.log(`Failed: ${result.summary.failedChecks} validators failed`);
  process.exit(1);
}

Custom Validators (Plugin System)

import { BaseValidator, PluginLoader } from 'sentinel-method';
import type { ValidatorResult, SentinelConfig } from 'sentinel-method';

class LicenseValidator extends BaseValidator {
  readonly name = 'License Check';

  validate(sourceDir: string): ValidatorResult {
    const files = this.getAllFiles(sourceDir);
    const hasLicense = files.some(f => f.includes('LICENSE'));

    return this.buildResult(
      hasLicense,
      hasLicense ? [] : [this.createIssue('error', 'NO_LICENSE', 'Missing LICENSE file')],
      { licenseFound: hasLicense },
    );
  }
}

// Register directly
const sentinel = new Sentinel();
sentinel.registerValidator(new LicenseValidator(config));

// Or load from directory
const loader = new PluginLoader();
loader.loadFromDirectory('./plugins');

Configuration

.sentinelrc.json

{
  "testingThreshold": 80,
  "securityLevel": "strict",
  "performanceTarget": "optimal",
  "maintainabilityScore": 75,
  "excludePatterns": ["node_modules", "dist", "coverage"],
  "reporters": ["json", "markdown"],
  "failOnWarnings": false
}

.sentinelignore

Uses .gitignore syntax. Default exclusions are always active: node_modules/, .git/, dist/, coverage/, .*.

# Generated
generated/
*.auto.ts

# Vendor
vendor/

# Legacy
legacy-module.js

CI/CD Integration

GitHub Actions

name: Sentinel Quality Gate
on: [push, pull_request]

jobs:
  sentinel:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18, 20]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci
      - run: npx sentinel validate ./src --json > sentinel-report.json
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: sentinel-report-node${{ matrix.node-version }}
          path: sentinel-report.json

GitLab CI

sentinel:
  stage: validate
  image: node:20
  script:
    - npm ci
    - npx sentinel validate ./src -f markdown > sentinel-report.md
  artifacts:
    paths:
      - sentinel-report.md

Security Coverage

Full OWASP Top 10 (2021) and CWE mapping:

Halstead Complexity Metrics

The Maintainability validator integrates Halstead software science metrics with a 20% weight in the final Maintainability Index:

• Volume (V): N * log2(n) — information content of the code
• Difficulty (D): (n1/2) * (N2/n2) — cognitive complexity to understand
• Effort (E): D * V — mental effort to comprehend
• Estimated Time: E / 18 — predicted development time (seconds)
• Estimated Bugs: V / 3000 — predicted defect count

Incremental Validation

import { DiffAnalyzer } from 'sentinel-method';

const diff = new DiffAnalyzer('.');

// Only files changed in current PR
const prFiles = diff.getDiffAgainst('main');

// Only staged files (pre-commit)
const staged = diff.getStagedFiles();

// Filter to code files
const codeFiles = diff.filterCodeFiles(staged);

Result caching is automatic via .sentinel-cache/. Unchanged files are skipped on subsequent runs.

Testing

npm test                # Run all 765 tests
npm run test:coverage   # With coverage report
npm run test:watch      # Watch mode

765 tests across 32 suites. 95% statement coverage, 99% function coverage.

API Reference

Core Classes

All 14 Validator Classes

License

MIT License 2026 — Camilo Girardelli / Girardelli Tecnologia

Built by Camilo Girardelli
IEEE Senior Member | Senior Software Architect | CTO at Girardelli Tecnologia

_{If AI writes the code, Sentinel decides if it ships.}