# Authoring Requirements

This guide is for teams writing non-functional requirements in this repo. Your requirements will be read by AI agents and validated by deterministic CI checks. Both the requirement AND its test are your responsibility.

## Requirement Format

Every requirement must include:

```markdown
## [DOMAIN]-[NNN]: [Title]

[One-sentence rule statement using MUST / MUST NOT.]

**Rationale:** Why this policy exists. This is what the AI agent reads to understand intent.

**Test type:** stack-agnostic | stack-specific

**Test:** How compliance is verified. Be specific — name the file patterns, config keys, or import paths.
```

## Test Types

### Stack-Agnostic Tests

These work regardless of service language. You own them entirely.

Examples:
- File presence/absence: "No `.tf` files in service repos"
- YAML structure: "No `kind: Ingress` in Helm templates"
- Config patterns: "No pinned infrastructure image tags"

Implement these directly in `.tests/check.sh` using `find`, `grep`, and standard shell tools.

### Stack-Specific Tests

These depend on the service language. You define WHAT to check. Stack teams contribute HOW.

Your job:
1. Write the requirement
2. Add a generic check in `check.sh` that reads from adapter files
3. Write the adapter pattern for at least one major stack (Java or Python)

Stack team's job:
- Add their language's patterns to `.tests/adapters/<language>.patterns`

### Adapter File Format

One pattern per line. Key=value. Keys match the check IDs in `check.sh`.

```
# .tests/adapters/java.patterns
cloud_sdk_imports=com\.amazonaws\.|com\.google\.cloud\.|com\.azure\.
jwt_libraries=io\.jsonwebtoken|com\.auth0\.jwt
auth_endpoints=@PostMapping.*"/login"|@RequestMapping.*"/authenticate"
```

When adding a new stack-specific requirement, add the corresponding key to all existing adapter files (use empty value if not applicable to that stack).

## Quality Checklist

Before submitting a requirement:

- [ ] Rule uses MUST or MUST NOT (not SHOULD)
- [ ] Test is deterministic (no LLM, no flaky assertions)
- [ ] Test runs in <5 seconds
- [ ] Rationale explains WHY, not just WHAT
- [ ] At least one adapter pattern exists for a major stack
- [ ] Demo violation added to `.demo/` folder
- [ ] Requirement doesn't duplicate existing static analysis (Checkstyle, SonarQube, ESLint)

## What Doesn't Belong Here

- Coding style rules (use your linter)
- Language best practices (use static analysis)
- Team-specific conventions (put those in your repo's agent config)
- Aspirational guidelines without testable criteria