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

#	Validator	What It Catches	Standards
01	Testing Coverage	Missing tests, weak assertions, no edge cases	Score 0-100
02	Security Scanning	Injection, XSS, hardcoded secrets, weak crypto	OWASP A01-A07, 12 CWEs
03	Performance	High complexity, memory leaks, sync bottlenecks	Cyclomatic & cognitive
04	Maintainability	God functions, duplication, poor documentation	Halstead V/D/E, MI index
05	Dependencies	Unused packages, wildcard versions, missing lock	Package health
06	Documentation	Missing JSDoc, README gaps, no CHANGELOG	Coverage %
07	Code Style	Inconsistent formatting, console.log, trailing WS	Consistency score
08	Architecture	Circular deps, god classes, layer violations	Score 0-100
09	API Contracts	REST violations, missing auth, no rate limiting	REST & OpenAPI
10	Accessibility	Missing alt, ARIA, semantic HTML, heading order	WCAG 2.1 AA
11	Internationalization	Hardcoded strings, locale-naive date/currency	i18n readiness
12	Error Handling	Empty catches, swallowed errors, unhandled promises	Resilience score
13	Type Safety	any abuse, ts-ignore, non-null assertions	Type strictness
14	Dead Code	Unused imports, unreachable branches, phantom exports	Dead code score

---

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

Code	Meaning
0	Quality gate passed
1	Quality gate failed
2	Runtime error

---

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:

Detection	CWE	OWASP Category
eval() / Function()	CWE-94, CWE-95	A03 Injection
SQL template injection	CWE-89	A03 Injection
Command injection	CWE-78	A03 Injection
innerHTML / document.write	CWE-79	A07 XSS
Hardcoded passwords/tokens	CWE-798	A02 Crypto Failures
Hardcoded API keys	CWE-321	A02 Crypto Failures
MD5/SHA-1 usage	CWE-327	A02 Crypto Failures
Path traversal	CWE-22	A01 Access Control
Unsafe deserialization	CWE-502	A04 Insecure Design

---

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

Class	Purpose
Sentinel	Main orchestrator — runs all validators, aggregates results
BaseValidator	Abstract base — file traversal, issue creation, result building
FileCollector	Cached I/O — collect, filter, read files with caching
SentinelIgnore	.gitignore-style pattern matching
PluginLoader	Load and register custom validator plugins
ResultCache	File-hash-based validation result caching
HookManager	Git hook installation and management
DiffAnalyzer	Git diff analysis for incremental validation
ConsensusEngine	Dual-agent verification with consensus scoring
BusinessGates	Business rule enforcement layer
RiskBudget	Risk allocation and tracking across validators
FitnessFunctions	Architectural fitness function evaluation

All 14 Validator Classes

Class	Standards
TestingValidator	Test coverage, assertions, edge cases
SecurityValidator	OWASP Top 10, CWE-22/78/79/89/94/95/321/327/502/798
PerformanceValidator	Cyclomatic complexity, async patterns
MaintainabilityValidator	Halstead metrics, Maintainability Index
DependencyValidator	Package health, semver compliance
DocumentationValidator	JSDoc coverage, README/CHANGELOG
CodeStyleValidator	Formatting consistency
ArchitectureValidator	Circular deps, SOLID violations
ApiContractValidator	REST patterns, Express/NestJS/Next.js
AccessibilityValidator	WCAG 2.1 AA — HTML, Vue, Svelte, JSX
I18nValidator	Hardcoded strings, locale formatting
ErrorHandlingValidator	Error resilience patterns
TypeSafetyValidator	TypeScript strictness enforcement
DeadCodeValidator	Unused code elimination

---

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.}