feat: AI Code Governance CLI v1.0.0

- 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
2026-06-14 11:08:11 +00:00
commit f8c82902a5
21 changed files with 3024 additions and 0 deletions
@@ -0,0 +1,95 @@
+# 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