nilesh.pandClaude Opus 4.8
035711f08c
- CLAUDE.md + AGENTS.md: canonical guiding principles for AI agents and developers (tenant isolation, no RLS, stack, security, conventions, environment gotchas) - SECURITY.md: required security controls (isolation, secrets, auth, input handling, least privilege) with VAPT status - GOVERNANCE.md: how changes are validated before merge — deterministic gates + AI review, risk tiers, human accountability - CONTRIBUTING.md: code hygiene, definition of done, file hygiene - docs/wiki/: product reference (overview, domain model, features, roles & access, API reference, glossary) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
76 lines
3.6 KiB
Markdown
76 lines
3.6 KiB
Markdown
# 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.
|