ai-sdlc-standards/AUTHORING.md

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:

## [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