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

``bash


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

`bash


Initialize configuration

givr init

Run all zones

givr run

Run with enforcement (exit code 1 on failures)

givr run --enforce
`

Commands

$3

Initialize givr configuration for your project. Auto-detects:
- TypeScript projects
- Test frameworks (Vitest, Jest)
- Linting tools (ESLint)
- Formatters (Prettier)

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

$3

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.

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

Output: .givr-zone1-report.json

$3

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.

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

Output: .givr-zone2-report.json

$3

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 |

`bash
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

$3

Run all three zones sequentially and generate a combined report.

`bash
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

$3

Show current governance status including:
- Configuration state
- Last run timestamp
- Per-zone status

`bash
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.

$3

Authenticate with the dashboard to enable sync and upload features.

`bash
givr login # Interactive login
givr login --endpoint # Use custom dashboard URL
`

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

$3

Clear stored credentials.

`bash
givr logout
`

$3

Show current authentication status and tenant info.

`bash
givr whoami
`

$3

Fetch governance rules from your team's dashboard configuration.

`bash
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.

$3

Include team-wide metrics from the dashboard.

`bash
givr status --remote
`

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

$3

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

`yaml


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

`yaml
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

$3

`yaml
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
`

$3

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

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

Programmatic API

givr exports all functionality for programmatic use:

`typescript
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