# SPEC — AI Code Quality Governance CLI

## Core User Value
Stop cowboy-shipping of AI-generated code to production. A lightweight, friction-minimal pre-commit / CI gate that enforces your team's chosen guardrails **before** merge.

## v1 Feature Set (REAL — honestly implemented)

### Gates (configurable, all real, no ML)
1. **disclosure-required** — Every changed file must contain an `AI-GENERATED:` or `AI-ASSISTED:` label comment (or a `.codegov.yml` override marker). Fails if any changed file lacks it. Supports per-file overrides via config.
2. **rfc-required** — Commit message or PR description must reference an RFC, issue, or ticket (regex for `#\d+`, `RFC-\d+`, or a custom pattern). Fails if absent.
3. **requirements-checklist** — A checklist file (default `REQUIREMENTS.md`) must exist and all checkboxes (`- [x]`) must be ticked. Fails if missing or any unchecked.
4. **quality-gates** — Runs a configurable array of shell commands (e.g., `npm run lint`, `npm run test`, `npm run typecheck`). Fails on any non-zero exit.

### Config (`.codegov.yml`)
- Top-level: `enabled: boolean`, `gates: { [name]: GateConfig }`
- Per-gate: `required: boolean`, command strings, regex patterns, file paths.
- Sane defaults when config is missing (all gates enabled with defaults, plus a warning).

### CLI
- `codegov check [--config path] [--from-ref ref] [--to-ref ref]`
- Parses git diff, evaluates each enabled gate, prints a readable report, exits non-zero on any failure.
- Handles edge cases: no config → defaults + warning; no changed files → pass (nothing to gate); missing RFC → fail with clear message.

## Tech Choice
- TypeScript / Node 20+
- No external runtime deps (uses child_process, fs, path — zero `dependencies` in package.json)
- Dev deps: `typescript`, `@types/node`, `vitest`
- Build target: CommonJS, single entry `dist/cli.js`, shebang `#!/usr/bin/env node`

## Non-Goals (DEFERRED — gated)
- Hosted dashboard / web UI (needs backend + auth)
- AI-vs-human code detection ML (use disclosure/label instead; be honest in README)
- npm publish (needs registry auth)
- GitHub Action marketplace listing (needs action.yml polish + marketplace publish)
- Paid tier / Stripe (needs backend + payments infra)
- Per-team SaaS backend (needs DB + auth)