BunBun Labs
f8c82902a5
- Config-driven gates via .codegov.yml/.codegov.json - disclosure gate: requires AI-GENERATED/AI-ASSISTED markers on changed files - rfc gate: requires issue/RFC reference in commit message or PR description - checklist gate: requires all items checked in REQUIREMENTS.md - quality gate: runs configurable lint/test/typecheck commands - CLI with readable reports and non-zero exit on violations - 41 tests covering all gates, config loading, and integration - Zero skeletons, no fake features, deferred items honestly documented
96 lines
2.4 KiB
Markdown
96 lines
2.4 KiB
Markdown
# AI Code Governance
|
|
|
|
Lightweight, friction-minimal guardrails on AI-generated code before production.
|
|
|
|
## Problem
|
|
|
|
Coworkers ship one-shot AI-generated apps straight to production with no RFC process, no requirements, no review — creating garbage. Teams need lightweight guardrails that run **before** merge.
|
|
|
|
## Solution
|
|
|
|
`codegov` is a config-driven CLI that runs as a pre-commit hook or CI gate. It enforces your team's chosen rules on every change, failing with clear, actionable output when guardrails are violated.
|
|
|
|
## Gates (v1)
|
|
|
|
| Gate | What it checks |
|
|
|------|---------------|
|
|
| **disclosure** | Every changed file must contain an `AI-GENERATED:` or `AI-ASSISTED:` marker comment |
|
|
| **rfc** | Commit message or PR description must reference an issue/RFC (`#123`, `RFC-456`, etc.) |
|
|
| **checklist** | `REQUIREMENTS.md` must exist and all checkboxes (`- [x]`) must be ticked |
|
|
| **quality** | Runs configurable commands (e.g., `npm run lint`, `npm run test`) — off by default |
|
|
|
|
## Install
|
|
|
|
```bash
|
|
npm install ai-code-governance
|
|
# or clone and use directly:
|
|
node dist/cli.js check
|
|
```
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
# Check current staged changes
|
|
codegov check
|
|
|
|
# Check a PR range
|
|
codegov check --from-ref origin/main --to-ref HEAD
|
|
|
|
# Use a custom config
|
|
codegov check --config ./ci/.codegov.yml
|
|
```
|
|
|
|
## Config (`.codegov.yml`)
|
|
|
|
```yaml
|
|
enabled: true
|
|
gates:
|
|
disclosure:
|
|
required: true
|
|
markers:
|
|
- "AI-GENERATED:"
|
|
- "AI-ASSISTED:"
|
|
excludePaths:
|
|
- "node_modules/"
|
|
- "dist/"
|
|
- "package-lock.json"
|
|
rfc:
|
|
required: true
|
|
pattern: "(#|issue/|RFC-|ticket/|TICKET-)[0-9]+"
|
|
source: commit-message # or pr-description, env, file
|
|
checklist:
|
|
required: true
|
|
filePath: REQUIREMENTS.md
|
|
quality:
|
|
required: false
|
|
commands:
|
|
- npm run lint
|
|
- npm run test
|
|
- npm run typecheck
|
|
```
|
|
|
|
If no config is found, sane defaults are used (all gates enabled with defaults, plus a warning).
|
|
|
|
## Pre-commit hook
|
|
|
|
```bash
|
|
# .git/hooks/pre-commit
|
|
codegov check
|
|
```
|
|
|
|
## CI (GitHub Actions)
|
|
|
|
```yaml
|
|
- name: AI Code Governance
|
|
run: npx codegov check --from-ref origin/main --to-ref HEAD
|
|
```
|
|
|
|
## What's real vs deferred
|
|
|
|
- **Real**: All four gates, config loading, git diff parsing, CLI, report generation, tests.
|
|
- **Deferred**: npm publish (needs registry auth), GitHub Action marketplace listing, hosted dashboard, SaaS backend, AI-vs-human detection ML (we use the disclosure/label approach instead).
|
|
|
|
## License
|
|
|
|
MIT
|