# 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