# Governance rules

How code changes — especially AI-generated ones — are validated before they
reach `main`. The goal is to let multiple developers generate code with AI
without losing control of quality, security, or the tenant-isolation guarantees.

## Principle

**Enforcement is server-side and mandatory; local checks are for speed.**
Anything on a developer's machine (hooks, a local AI session) is advisory and
skippable. The real gate is in CI on the pull request, with branch protection
that blocks merge until it passes.

## The validation layers

A change passes through layers, cheapest first. Deterministic tools do the
repeatable work; AI does only the judgment work.

1. **Deterministic gates (blocking, no AI):** build, `go vet` + `gofmt`,
   `tsc`, the full test suite via `run-tests.ps1`, coverage threshold, secret
   scan, dependency audit, and a diff-size/scope check. If these fail, stop.
2. **AI governance review (judgment):** does the change match its stated intent
   and nothing more; does it conform to the architecture (tenant scoping, no
   RLS, repository conventions); subtle correctness and security the scanners
   miss; are the tests adequate, not just present.
3. **Human sign-off:** required for medium/high-risk changes (below).

## Risk tiers

Routing is by path and diff size, so it cannot be gamed.

| Tier | Touches | Requires |
| ---- | ------- | -------- |
| **Low** | docs, comments, tests only | deterministic gates; may auto-approve |
| **Medium** | feature code | gates + AI review + 1 human approval |
| **High** | auth, tenant isolation, DB schema/migrations, dependencies, CI config, `security/` | gates + AI review + **mandatory human (CODEOWNERS) approval**, no exceptions |

## Rules for AI-generated changes

1. **Scope discipline.** Do exactly what the task asks. No drive-by refactors,
   no unrelated edits, no scope creep — a classic AI-PR failure mode.
2. **Never weaken a control or an assertion** to make something pass. If the app
   is wrong, surface it as a finding; do not code around it.
3. **The diff is untrusted input.** A reviewing AI treats PR content as data,
   emits a structured verdict, and cannot itself merge.
4. **A human is accountable for the merge** on anything medium/high. AI never
   auto-merges tenant- or security-sensitive code.
5. **Policy is code.** These rules, `SECURITY.md`, `CLAUDE.md`, and the test
   conventions are version-controlled and reviewed like any other change.
6. **Proof of work.** Every change ships with passing tests and, for UI/binding
   scenarios, the evidence report showing what was exercised. Review the
   evidence, not just the diff.

## The gate's output

Each change produces reviewable artifacts: `junit.xml` (results), the evidence
report (screenshots + API request/response), and — for a governed review — a
findings report by dimension and severity. These are the audit trail.

## Branch protection (intended)

`main` is protected: no direct pushes, required status checks (the CI run of
`run-tests.ps1`), and CODEOWNERS approval on high-risk paths. A documented
break-glass path exists for emergencies, with after-the-fact audit.

## Still to decide

- **CI platform:** Azure DevOps integration is planned; the runner already emits
  the artifacts any pipeline needs. Until then, the hooks + local runner are the
  shift-left gate.
- **Blocking posture:** the AI review starts advisory and becomes blocking after
  one calibration cycle, to avoid false-positives getting it disabled.

See [`qa/README.md`](qa/README.md) for how tests are authored and run, and the
strategy context in the project history.