From d3a99d01fa1a66b7a2c96be431ec05f14f202d0a Mon Sep 17 00:00:00 2001
From: Max Mayfield <max@openclaw.ai>
Date: Sat, 7 Mar 2026 07:47:22 +0000
Subject: [PATCH] Add authoring guide, stack adapters, and CI layer distinction

- AUTHORING.md: instructions for teams writing requirements + tests
- Stack adapters: java.patterns, python.patterns, go.patterns
- Quality checklist for new requirements
- Open question on adapter threshold for minor stacks
---
 .tests/adapters/go.patterns     |  4 ++
 .tests/adapters/java.patterns   |  4 ++
 .tests/adapters/python.patterns |  4 ++
 AUTHORING.md                    | 76 +++++++++++++++++++++++++++++++++
 4 files changed, 88 insertions(+)
 create mode 100644 .tests/adapters/go.patterns
 create mode 100644 .tests/adapters/java.patterns
 create mode 100644 .tests/adapters/python.patterns
 create mode 100644 AUTHORING.md

diff --git a/.tests/adapters/go.patterns b/.tests/adapters/go.patterns
new file mode 100644
index 0000000..50e5a59
--- /dev/null
+++ b/.tests/adapters/go.patterns
@@ -0,0 +1,4 @@
+cloud_sdk_imports=cloud\.google\.com/go|aws-sdk-go|azure-sdk-for-go
+jwt_libraries=golang-jwt|dgrijalva/jwt
+auth_endpoints=HandleFunc.*"/login"|Handle.*"/authenticate"
+external_url=https?://(?!localhost|127\.0\.0\.1|10\.|192\.168\.)(?!.*reltio\.(com|net|io))
diff --git a/.tests/adapters/java.patterns b/.tests/adapters/java.patterns
new file mode 100644
index 0000000..c158d88
--- /dev/null
+++ b/.tests/adapters/java.patterns
@@ -0,0 +1,4 @@
+cloud_sdk_imports=com\.amazonaws\.|com\.google\.cloud\.|com\.azure\.
+jwt_libraries=io\.jsonwebtoken|com\.auth0\.jwt
+auth_endpoints=@PostMapping.*"/login"|@RequestMapping.*"/authenticate"
+external_url=https?://(?!localhost|127\.0\.0\.1|10\.|192\.168\.)(?!.*reltio\.(com|net|io))
diff --git a/.tests/adapters/python.patterns b/.tests/adapters/python.patterns
new file mode 100644
index 0000000..f9313e7
--- /dev/null
+++ b/.tests/adapters/python.patterns
@@ -0,0 +1,4 @@
+cloud_sdk_imports=import boto3|from google\.cloud|from azure\.
+jwt_libraries=import jwt|from jose|from authlib
+auth_endpoints=@app\.route.*/login|@app\.post.*/authenticate|def login\(
+external_url=https?://(?!localhost|127\.0\.0\.1|10\.|192\.168\.)(?!.*reltio\.(com|net|io))
diff --git a/AUTHORING.md b/AUTHORING.md
new file mode 100644
index 0000000..34752e3
--- /dev/null
+++ b/AUTHORING.md
@@ -0,0 +1,76 @@
+# 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