givr

Governance Inversion Verifier - A three-zone code governance CLI that helps teams maintain quality without blocking velocity.

The Governance Inversion Philosophy

Traditional governance models block developers: strict pre-commit hooks, mandatory code reviews, and rigid CI gates create friction that slows teams down. Governance Inversion flips this model by using graduated, observable enforcement:

1. Zone 1 (Observer) - Detect and log without blocking
2. Zone 2 (Classifier) - AI-powered analysis and test generation
3. Zone 3 (Gate) - Enforce only what truly matters

The result: developers move fast, while teams maintain full visibility into code quality and security posture.

Installation

# Global installation (recommended)
npm install -g givr

# Or as a dev dependency
npm install --save-dev givr

Requires Node.js 20.0.0 or higher.

Quick Start

# Initialize configuration
givr init

# Run all zones
givr run

# Run with enforcement (exit code 1 on failures)
givr run --enforce

Commands

givr init

Initialize givr configuration for your project. Auto-detects:

• TypeScript projects
• Test frameworks (Vitest, Jest)
• Linting tools (ESLint)
• Formatters (Prettier)

givr init           # Create .givr.yml with detected settings
givr init --force   # Overwrite existing configuration

givr zone1

Zone 1: Observer - Scans your codebase for:

• Localhost references (localhost:*, 127.0.0.1, 0.0.0.0)
• API endpoint definitions (Express, NestJS decorators)

Zone 1 never blocks. It logs findings for visibility.

givr zone1          # Run with detailed output
givr zone1 --quiet  # Suppress output (for CI)

Output: .givr-zone1-report.json

givr zone2

Zone 2: Classifier - AI-powered code analysis that:

• Classifies changes (new endpoint, bugfix, refactor, etc.)
• Identifies functions and expected behaviors
• Generates test stubs for untested code

Requires ANTHROPIC_API_KEY environment variable. Skipped gracefully if not set.

export ANTHROPIC_API_KEY=sk-ant-...
givr zone2

Output: .givr-zone2-report.json

givr zone3

Zone 3: Gate - Security and quality enforcement with three gates:

| Gate | Checks | Blocking | |------|--------|----------| | Coverage | Code coverage meets threshold (default 80%) | Configurable | | Localhost | No hardcoded localhost in production code | With --enforce | | Security | No hardcoded secrets, eval(), innerHTML | With --enforce |

givr zone3              # Report mode (warns but doesn't block)
givr zone3 --enforce    # Enforcement mode (exit 1 on failures)

Security Patterns Detected:

• eval() usage
• innerHTML assignments
• dangerouslySetInnerHTML
• Hardcoded passwords, API keys, secrets
• Anthropic (sk-ant-*) and OpenAI (sk-*) API keys

Output: .givr-zone3-report.json

givr run

Run all three zones sequentially and generate a combined report.

givr run              # Report mode
givr run --enforce    # Enforcement mode for Zone 3
givr run --quiet      # CI-friendly (no output, exit codes only)

Output: .givr-all-report.json

givr status

Show current governance status including:

• Configuration state
• Last run timestamp
• Per-zone status

givr status

Example output:

╭─────────────────────────────────────╮
│       Governance Status             │
╰─────────────────────────────────────╯
✓ Configuration: .givr.yml found

Last run: 2h ago (PASS)

Zone                  Status
Zone 1 (Observer)     ✓ PASS (52m ago)
Zone 2 (Classifier)   ✓ PASS (52m ago)
Zone 3 (Gate)         ✓ PASS (52m ago)

Dashboard Integration

Connect givr to the Governance Inversion SaaS dashboard for team-wide visibility, centralized rules, and compliance reporting.

givr login

Authenticate with the dashboard to enable sync and upload features.

givr login                    # Interactive login
givr login --endpoint <url>   # Use custom dashboard URL

Credentials are stored securely in ~/.givr/credentials.json with restricted permissions.

givr logout

Clear stored credentials.

givr logout

givr whoami

Show current authentication status and tenant info.

givr whoami

givr sync

Fetch governance rules from your team's dashboard configuration.

givr sync          # Fetch rules (uses 1-hour cache)
givr sync --force  # Ignore cache, always fetch fresh

Synced rules are cached locally at ~/.givr/rules-cache.json.

givr status --remote

Include team-wide metrics from the dashboard.

givr status --remote

Shows:

• Team pass rate for last 7 days
• Top contributors with event counts
• Recent governance events across the team

Auto-Upload

When configured, reports automatically upload to the dashboard after each run:

# .givr.yml
upload:
  enabled: true
  autoUpload: true  # Upload after every 'givr run'

Upload is non-blocking—if the dashboard is unreachable, the local report is still saved.

Configuration

Configuration is stored in .givr.yml at your project root:

zones:
  zone1:
    enabled: true
    lintCommand: npm run lint       # Optional: auto-detected
    formatCommand: npm run format   # Optional: auto-detected
    typeCheckCommand: npm run typecheck

  zone2:
    enabled: true
    model: claude-sonnet-4-20250514  # AI model for classification
    maxFiles: 5                       # Max files to analyze per run

  zone3:
    enabled: true
    coverageThreshold: 80            # Minimum coverage percentage
    testCommand: npm run test:coverage
    enforce: false                   # Set to true for CI blocking

upload:
  enabled: true                      # Enable dashboard integration
  autoUpload: true                   # Auto-upload after 'givr run'

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | ANTHROPIC_API_KEY | For Zone 2 | Anthropic API key for AI classification |

Exit Codes

| Code | Meaning | |------|---------| | 0 | All checks passed (or warnings in report mode) | | 1 | Failures detected in enforcement mode |

Report Files

Each zone generates a JSON report:

| File | Contents | |------|----------| | .givr-zone1-report.json | Localhost references, detected endpoints | | .givr-zone2-report.json | AI classifications, test stubs generated | | .givr-zone3-report.json | Gate results, security findings, coverage | | .givr-all-report.json | Combined report with summary |

Add these to .gitignore if you don't want to commit reports.

CI/CD Integration

GitHub Actions

name: Governance
on: [push, pull_request]

jobs:
  governance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci
      - run: npm test -- --coverage

      - name: Run governance checks
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          npm install -g givr
          givr run --enforce

Pre-commit Hook

Add to .husky/pre-commit or your pre-commit tool:

#!/bin/sh
givr zone1 --quiet && givr zone3 --quiet

Programmatic API

givr exports all functionality for programmatic use:

import {
  runZone1,
  runZone2,
  runZone3,
  runAllZones,
  initConfig,
  getStatus,
  loadConfig,
  type Zone1Report,
  type Zone2Report,
  type Zone3Report,
  type AllZonesReport,
} from 'givr';

// Run Zone 1 on a specific project
const report = await runZone1({ projectPath: '/path/to/project' });
console.log(`Found ${report.findings.localhost.length} localhost references`);

// Classify code with AI
import { classifyCode, generateTestStub } from 'givr';

const classification = await classifyCode(sourceCode, 'myModule.ts');
console.log(`Type: ${classification.type}, Confidence: ${classification.confidence}`);

const testStub = generateTestStub(classification, 'myModule.ts');
// Returns a Vitest test skeleton with Arrange-Act-Assert pattern

// Check security independently
import { checkSecurity } from 'givr';

const findings = checkSecurity('/path/to/project');
for (const finding of findings) {
  console.log(`${finding.severity}: ${finding.pattern} at ${finding.file}:${finding.line}`);
}

Why Governance Inversion?

Traditional pre-commit hooks and CI gates create an adversarial relationship between developers and governance. Developers find workarounds, skip checks, or accumulate technical debt in areas that aren't covered.

Governance Inversion recognizes that:

1. Observability beats enforcement - You can't fix what you can't see
2. AI can reduce toil - Automated classification and test generation
3. Graduated response works - Zone 1 observes, Zone 2 assists, Zone 3 enforces
4. Developer experience matters - Fast local checks, smart CI integration

The goal isn't to block developers—it's to give teams the visibility and tools they need to ship quality code faster.

License

MIT License - see LICENSE for details.

Contributing

Contributions welcome! Please read our contributing guidelines before submitting PRs.

Built by Governance Inversion LLC | Published by iWuntu