feat: add AI agent governance configs

.amazonq/rules/governance.md

@@ -0,0 +1,54 @@
+<!-- crag:auto-start -->
+# Amazon Q Rules — fastapi
+
+> Generated from governance.md by crag. Regenerate: `crag compile --target amazonq`
+
+## About
+
+(No description)
+
+**Stack:** python
+
+**Runtimes detected:** python
+
+## How Amazon Q Should Behave on This Project
+
+### Code Generation
+
+1. **Run governance gates before suggesting commits.** The gates below define the quality bar.
+2. **Respect classifications:** MANDATORY (default) blocks on failure; OPTIONAL warns; ADVISORY is informational only.
+3. **Respect scopes:** Path-scoped gates run from that directory. Conditional gates skip when their file does not exist.
+4. **No secrets.** - No hardcoded secrets — grep for sk_live, AKIA, password= before commit
+5. **Minimal diffs.** Prefer editing existing code over creating new files. Do not refactor unrelated areas.
+
+### Quality Gates
+
+- `uv run mypy .`
+- `uv run pytest`
+- `python -m build`
+- `python -m build --sdist`
+- `uv run --no-sync bash scripts/test-cov.sh`
+- `uv run --no-sync pytest tests/benchmarks --codspeed`
+- `uv run coverage combine coverage`
+- `uv run coverage html --title "Coverage for ${{ github.sha }}"`
+- `uv run coverage report --fail-under=100`
+
+### Commit Style
+
+Follow project commit conventions.
+
+### Boundaries
+
+- All file operations must stay within this repository.
+- No destructive shell commands (rm -rf above repo root, DROP TABLE without confirmation, force-push to main).
+- No new dependencies without an explicit reason.
+
+## Authoritative Source
+
+When these instructions seem to conflict with something in the repo, **`.claude/governance.md` is the source of truth**. This file is a compiled view.
+
+---
+
+**Tool:** crag — https://www.npmjs.com/package/@whitehatd/crag
+
+<!-- crag:auto-end -->

.claude/governance.md

@@ -0,0 +1,63 @@
+# Governance — fastapi
+# Inferred by crag analyze — review and adjust as needed
+
+## Identity
+- Project: fastapi
+- Stack: python
+
+## Gates (run in order, stop on failure)
+### Lint
+- uv run mypy .
+
+### Test
+- uv run pytest
+
+### Build
+- python -m build
+
+### CI (inferred from workflow)
+- python -m build --sdist
+- uv run --no-sync bash scripts/test-cov.sh
+- uv run --no-sync pytest tests/benchmarks --codspeed
+- uv run coverage combine coverage
+- uv run coverage html --title "Coverage for ${{ github.sha }}"
+- uv run coverage report --fail-under=100
+
+## Advisories (informational, not enforced)
+- actionlint  # [ADVISORY]
+
+## Branch Strategy
+- Trunk-based development
+- Free-form commits
+- Commit trailer: Co-Authored-By: Claude <noreply@anthropic.com>
+
+## Security
+- No hardcoded secrets — grep for sk_live, AKIA, password= before commit
+
+## Autonomy
+- Auto-commit after gates pass
+
+## Architecture
+- Type: monolith
+
+## Key Directories
+- `.github/` — CI/CD
+- `docs/` — documentation
+- `scripts/` — tooling
+- `tests/` — tests
+
+## Testing
+- Framework: pytest
+- Layout: flat
+- Naming: test_*.py
+
+## Dependencies
+- Package manager: uv (uv.lock)
+
+## Anti-Patterns
+
+Do not:
+- Do not catch bare `Exception` — catch specific exceptions
+- Do not use mutable default arguments (e.g., `def f(x=[])`)
+- Do not use `import *` — use explicit imports
+

.clinerules

@@ -0,0 +1,53 @@
+<!-- crag:auto-start -->
+# Cline Rules — fastapi
+
+Generated from governance.md by crag. Regenerate with: `crag compile --target cline`
+
+## About this project
+
+(No description)
+
+Stack: python
+Runtimes: python
+
+## Mandatory behavior
+
+1. Read this file at the start of every session. Read `governance.md` for full context.
+2. Run all mandatory quality gates before proposing a commit.
+3. If a gate fails, attempt an automatic fix (lint/format) with bounded retry (max 2 attempts). If it still fails, escalate to the user.
+4. Never modify files outside this repository.
+5. Never run destructive system commands (rm -rf /, DROP TABLE, force-push to main, curl|bash).
+6. Use conventional commits.
+
+## Quality gates
+
+Run these in order, stop on first MANDATORY failure:
+
+- uv run mypy .
+- uv run pytest
+- python -m build
+- python -m build --sdist
+- uv run --no-sync bash scripts/test-cov.sh
+- uv run --no-sync pytest tests/benchmarks --codspeed
+- uv run coverage combine coverage
+- uv run coverage html --title "Coverage for ${{ github.sha }}"
+- uv run coverage report --fail-under=100
+
+## Security
+
+- No hardcoded secrets — grep for sk_live, AKIA, password= before commit
+
+## Workflow
+
+For every task:
+1. Read the governance.md file first
+2. Understand which files need to change
+3. Make minimal, focused changes
+4. Run all mandatory gates
+5. Commit with a conventional commit message
+
+## Tool context
+
+This project uses **crag** — the governance engine for AI coding agents. https://www.npmjs.com/package/@whitehatd/crag
+
+<!-- crag:auto-end -->

.continuerules

@@ -0,0 +1,51 @@
+<!-- crag:auto-start -->
+# Continue Rules — fastapi
+
+> Generated from governance.md by crag. Regenerate: `crag compile --target continue`
+
+
+
+## Project Context
+
+- **Stack:** python
+- **Runtimes:** python
+- **Governance source:** `.claude/governance.md` (single source of truth)
+
+## Coding Rules
+
+Always follow these when generating or modifying code:
+
+1. **Run gates before committing.** Every change must pass the mandatory gates below.
+2. **Classifications matter:**
+   - `MANDATORY` — must pass (default)
+   - `OPTIONAL` — should pass, warn on failure
+   - `ADVISORY` — informational only
+3. **Path-scoped gates** run from their declared directory.
+4. **Conditional gates** only run when their referenced file exists.
+5. **No secrets.** - No hardcoded secrets — grep for sk_live, AKIA, password= before commit
+6. Follow project commit conventions.
+
+## Quality Gates
+
+  - uv run mypy .
+  - uv run pytest
+  - python -m build
+  - python -m build --sdist
+  - uv run --no-sync bash scripts/test-cov.sh
+  - uv run --no-sync pytest tests/benchmarks --codspeed
+  - uv run coverage combine coverage
+  - uv run coverage html --title "Coverage for ${{ github.sha }}"
+  - uv run coverage report --fail-under=100
+
+## Boundaries
+
+- All file operations stay within this repository
+- No destructive shell commands
+- No new dependencies without justification
+- Prefer editing existing files over creating new ones
+
+## Powered by crag
+
+This rule file is auto-generated from a single `governance.md` via **crag** (https://www.npmjs.com/package/@whitehatd/crag). To update, edit governance.md and re-run `crag compile --target continue`.
+
+<!-- crag:auto-end -->

.cursor/rules/governance.mdc

@@ -0,0 +1,40 @@
+---
+description: Governance rules for fastapi — quality gates, security, conventions
+globs:
+  - "**/*.py"
+alwaysApply: true
+---
+
+# Governance — fastapi
+
+> Generated from governance.md by crag. Regenerate: `crag compile --target cursor`
+
+**Stack:** python
+
+## Quality Gates
+
+Run these checks in order before committing:
+### Lint
+- `uv run mypy .`
+
+### Test
+- `uv run pytest`
+
+### Build
+- `python -m build`
+
+### Ci (inferred from workflow)
+- `python -m build --sdist`
+- `uv run --no-sync bash scripts/test-cov.sh`
+- `uv run --no-sync pytest tests/benchmarks --codspeed`
+- `uv run coverage combine coverage`
+- `uv run coverage html --title "Coverage for ${{ github.sha }}"`
+- `uv run coverage report --fail-under=100`
+## Security
+
+- No hardcoded secrets — grep for sk_live, AKIA, password= before commit
+
+## Conventions
+
+- Follow project commit conventions
+- Runtimes: python

.github/copilot-instructions.md

@@ -0,0 +1,41 @@
+<!-- crag:auto-start -->
+# Copilot Instructions — fastapi
+
+> Generated from governance.md by crag. Regenerate: `crag compile --target copilot`
+
+
+
+**Stack:** python
+
+## Runtimes
+
+python
+
+## Quality Gates
+
+When you propose changes, the following checks must pass before commit:
+
+- **lint**: `uv run mypy .`
+- **test**: `uv run pytest`
+- **build**: `python -m build`
+- **ci (inferred from workflow)**: `python -m build --sdist`
+- **ci (inferred from workflow)**: `uv run --no-sync bash scripts/test-cov.sh`
+- **ci (inferred from workflow)**: `uv run --no-sync pytest tests/benchmarks --codspeed`
+- **ci (inferred from workflow)**: `uv run coverage combine coverage`
+- **ci (inferred from workflow)**: `uv run coverage html --title "Coverage for ${{ github.sha }}"`
+- **ci (inferred from workflow)**: `uv run coverage report --fail-under=100`
+
+## Expectations for AI-Assisted Code
+
+1. **Run gates before suggesting a commit.** If you cannot run them (no shell access), explicitly remind the human to run them.
+2. **Respect classifications.** `MANDATORY` gates must pass. `OPTIONAL` gates should pass but may be overridden with a note. `ADVISORY` gates are informational only.
+3. **Respect workspace paths.** When a gate is scoped to a subdirectory, run it from that directory.
+4. **No hardcoded secrets.** - No hardcoded secrets — grep for sk_live, AKIA, password= before commit
+5. Follow project commit conventions.
+6. **Conservative changes.** Do not rewrite unrelated files. Do not add new dependencies without explaining why.
+
+## Tool Context
+
+This project uses **crag** (https://www.npmjs.com/package/@whitehatd/crag) as its AI-agent governance layer. The `governance.md` file is the authoritative source. If you have shell access, run `crag check` to verify the infrastructure and `crag diff` to detect drift.
+
+<!-- crag:auto-end -->

.rules

@@ -0,0 +1,60 @@
+<!-- crag:auto-start -->
+# Zed Assistant Rules — fastapi
+
+> Generated from governance.md by crag. Regenerate: `crag compile --target zed`
+
+## Project Summary
+
+(No description)
+
+**Stack:** python
+
+**Runtimes:** python
+
+## Rules for Zed AI Assistant
+
+When suggesting edits or running the inline assistant:
+
+### 1. Quality Gates
+
+These must pass before any commit. Run them via Zed's terminal integration:
+
+- `uv run mypy .`
+- `uv run pytest`
+- `python -m build`
+- `python -m build --sdist`
+- `uv run --no-sync bash scripts/test-cov.sh`
+- `uv run --no-sync pytest tests/benchmarks --codspeed`
+- `uv run coverage combine coverage`
+- `uv run coverage html --title "Coverage for ${{ github.sha }}"`
+- `uv run coverage report --fail-under=100`
+
+### 2. Classification Semantics
+
+- **MANDATORY** — stop if this fails
+- **OPTIONAL** — warn and continue
+- **ADVISORY** — log and continue (informational)
+
+### 3. Scope Rules
+
+- `path:dir/` — run the gate from that directory
+- `if:file` — skip the gate's section when the file does not exist
+
+### 4. Behavior Boundaries
+
+- All file operations must stay within this repository.
+- Never run destructive system commands (`rm -rf /`, `DROP TABLE`, `curl|bash`, force-push to main).
+- - No hardcoded secrets — grep for sk_live, AKIA, password= before commit
+- Follow project commit conventions.
+
+### 5. Authoritative Source
+
+When these rules conflict with ad-hoc instructions, **governance.md wins**. It is the single source of truth for this project's policies.
+
+---
+
+**Generated by crag** — https://www.npmjs.com/package/@whitehatd/crag
+
+To update these rules, edit `.claude/governance.md` and re-run `crag compile --target zed`.
+
+<!-- crag:auto-end -->

.windsurf/rules/governance.md

@@ -0,0 +1,54 @@
+---
+trigger: always_on
+description: Governance rules for fastapi — compiled from governance.md by crag
+---
+
+# Windsurf Rules — fastapi
+
+Generated from governance.md by crag. Regenerate: `crag compile --target windsurf`
+
+## Project
+
+(No description)
+
+**Stack:** python
+
+## Runtimes
+
+python
+
+## Cascade Behavior
+
+When Windsurf's Cascade agent operates on this project:
+
+- **Always read governance.md first.** It is the single source of truth for quality gates and policies.
+- **Run all mandatory gates before proposing changes.** Stop on first failure.
+- **Respect classifications.** OPTIONAL gates warn but don't block. ADVISORY gates are informational.
+- **Respect path scopes.** Gates with a `path:` annotation must run from that directory.
+- **No destructive commands.** Never run rm -rf, dd, DROP TABLE, force-push to main, curl|bash, docker system prune.
+- - No hardcoded secrets — grep for sk_live, AKIA, password= before commit
+- Follow the project commit conventions.
+
+## Quality Gates (run in order)
+
+1. `uv run mypy .`
+2. `uv run pytest`
+3. `python -m build`
+4. `python -m build --sdist`
+5. `uv run --no-sync bash scripts/test-cov.sh`
+6. `uv run --no-sync pytest tests/benchmarks --codspeed`
+7. `uv run coverage combine coverage`
+8. `uv run coverage html --title "Coverage for ${{ github.sha }}"`
+9. `uv run coverage report --fail-under=100`
+
+## Rules of Engagement
+
+1. **Minimal changes.** Don't rewrite files that weren't asked to change.
+2. **No new dependencies** without explicit approval.
+3. **Prefer editing** existing files over creating new ones.
+4. **Always explain** non-obvious changes in commit messages.
+5. **Ask before** destructive operations (delete, rename, migrate schema).
+
+---
+
+**Tool:** crag — https://www.npmjs.com/package/@whitehatd/crag

AGENTS.md

@@ -0,0 +1,70 @@
+<!-- crag:auto-start -->
+# AGENTS.md
+
+> Generated from governance.md by crag. Regenerate: `crag compile --target agents-md`
+
+## Project: fastapi
+
+
+## Quality Gates
+
+All changes must pass these checks before commit:
+
+### Lint
+1. `uv run mypy .`
+
+### Test
+1. `uv run pytest`
+
+### Build
+1. `python -m build`
+
+### Ci (inferred from workflow)
+1. `python -m build --sdist`
+2. `uv run --no-sync bash scripts/test-cov.sh`
+3. `uv run --no-sync pytest tests/benchmarks --codspeed`
+4. `uv run coverage combine coverage`
+5. `uv run coverage html --title "Coverage for ${{ github.sha }}"`
+6. `uv run coverage report --fail-under=100`
+
+## Coding Standards
+
+- Stack: python
+- Follow project commit conventions
+
+## Architecture
+
+- Type: monolith
+
+## Key Directories
+
+- `.github/` — CI/CD
+- `docs/` — documentation
+- `scripts/` — tooling
+- `tests/` — tests
+
+## Testing
+
+- Framework: pytest
+- Layout: flat
+- Naming: test_*.py
+
+## Anti-Patterns
+
+Do not:
+- Do not catch bare `Exception` — catch specific exceptions
+- Do not use mutable default arguments (e.g., `def f(x=[])`)
+- Do not use `import *` — use explicit imports
+
+## Security
+
+- No hardcoded secrets — grep for sk_live, AKIA, password= before commit
+
+## Workflow
+
+1. Read `governance.md` at the start of every session — it is the single source of truth.
+2. Run all mandatory quality gates before committing.
+3. If a gate fails, fix the issue and re-run only the failed gate.
+4. Use the project commit conventions for all changes.
+
+<!-- crag:auto-end -->

CLAUDE.md

@@ -0,0 +1,42 @@
+<!-- crag:auto-start -->
+# CLAUDE.md — fastapi
+
+> Generated from governance.md by crag. Regenerate: `crag compile --target claude`
+
+
+
+**Stack:** python
+**Runtimes:** python
+
+## Quality Gates
+
+Run these in order before committing. Stop on first MANDATORY failure:
+
+- `uv run mypy .`
+- `uv run pytest`
+- `python -m build`
+- `python -m build --sdist`
+- `uv run --no-sync bash scripts/test-cov.sh`
+- `uv run --no-sync pytest tests/benchmarks --codspeed`
+- `uv run coverage combine coverage`
+- `uv run coverage html --title "Coverage for ${{ github.sha }}"`
+- `uv run coverage report --fail-under=100`
+
+## Rules
+
+1. Read `governance.md` at the start of every session — it is the single source of truth.
+2. Run all mandatory quality gates before committing.
+3. If a gate fails, attempt an automatic fix (lint/format) with bounded retry (max 2 attempts). If it still fails, escalate to the user.
+4. Never modify files outside this repository.
+5. Never run destructive system commands (`rm -rf /`, `DROP TABLE`, force-push to main).
+- Follow project commit conventions
+
+## Security
+
+- No hardcoded secrets — grep for sk_live, AKIA, password= before commit
+
+## Tool Context
+
+This project uses **crag** (https://www.npmjs.com/package/@whitehatd/crag) as its governance engine. The `governance.md` file is the authoritative source. Run `crag audit` to detect drift and `crag compile --target all` to recompile all targets.
+
+<!-- crag:auto-end -->

GEMINI.md

@@ -0,0 +1,38 @@
+<!-- crag:auto-start -->
+# GEMINI.md
+
+> Generated from governance.md by crag. Regenerate: `crag compile --target gemini`
+
+## Project Context
+
+- **Name:** fastapi
+- **Stack:** python
+- **Runtimes:** python
+
+## Rules
+
+### Quality Gates
+
+Run these checks in order before committing any changes:
+
+1. [lint] `uv run mypy .`
+2. [test] `uv run pytest`
+3. [build] `python -m build`
+4. [ci (inferred from workflow)] `python -m build --sdist`
+5. [ci (inferred from workflow)] `uv run --no-sync bash scripts/test-cov.sh`
+6. [ci (inferred from workflow)] `uv run --no-sync pytest tests/benchmarks --codspeed`
+7. [ci (inferred from workflow)] `uv run coverage combine coverage`
+8. [ci (inferred from workflow)] `uv run coverage html --title "Coverage for ${{ github.sha }}"`
+9. [ci (inferred from workflow)] `uv run coverage report --fail-under=100`
+
+### Security
+
+- No hardcoded secrets — grep for sk_live, AKIA, password= before commit
+
+### Workflow
+
+- Follow project commit conventions
+- Run quality gates before committing
+- Review security implications of all changes
+
+<!-- crag:auto-end -->