# Common Standards Catalog - Cross-Language Patterns

**Version:** 1.0.0
**Last Updated:** 2026-03-03
**Purpose:** Universal coding standards shared across all languages. Language-specific files reference this document for philosophical and cross-cutting patterns, keeping language-specific implementation details in their own catalogs.

---

## Table of Contents

1. [Error Handling Philosophy](#error-handling-philosophy)
2. [Testing Best Practices](#testing-best-practices)
3. [Security Principles](#security-principles)
4. [Documentation Standards](#documentation-standards)
5. [Code Organization Principles](#code-organization-principles)
6. [Canonical Language Owners](#canonical-language-owners)

---

## Error Handling Philosophy

Errors are first-class citizens. Every language has different mechanisms (Result types, exceptions, error returns), but the underlying principles are universal.

### Core Rules

| Rule | ALWAYS | NEVER |
|------|--------|-------|
| Visibility | Log or propagate every error | Suppress errors silently |
| Specificity | Use specific error types/exceptions | Catch-all without re-raising |
| Context | Add context when propagating | Lose the original error chain |
| Recovery | Distinguish recoverable vs fatal | Treat all errors the same |
| Documentation | Document error behavior in public APIs | Assume callers know failure modes |
| Libraries | Log before raising in library boundaries | Swallow errors inside libraries |

### Error Chain Preservation

Every language provides a mechanism for preserving error chains. Use it.

| Language | Mechanism | Example |
|----------|-----------|---------|
| Go | `fmt.Errorf("context: %w", err)` | Preserves `errors.Is()` / `errors.As()` |
| Python | `raise NewError("context") from exc` | Preserves `__cause__` chain |
| Rust | `?` with `.context()` / `#[source]` | Preserves `Error::source()` chain |
| TypeScript | `new AppError("context", { cause: err })` | Preserves `Error.cause` chain |
| Shell | `err "context: $cmd failed"; return $exit_code` | Preserves exit code semantics |

### Intentional Error Ignores

When errors are intentionally ignored (e.g., best-effort cleanup), document the reason:

| Language | Pattern |
|----------|---------|
| Go | `_ = conn.Close() // nolint:errcheck - best effort cleanup` |
| Python | `except SpecificError: pass  # best effort cleanup` with comment |
| Rust | `let _ = conn.close(); // Intentional ignore: best effort cleanup` |
| TypeScript | `void promise.catch(() => {}); // fire-and-forget, logged elsewhere` |
| Shell | `rm -rf "$TMPDIR" 2>/dev/null \|\| true` |

### Error Aggregation

When multiple operations can fail independently (parallel execution, multi-step cleanup), use the language's error aggregation mechanism rather than discarding all but the first error.

| Language | Mechanism |
|----------|-----------|
| Go | `errors.Join(err1, err2)` (1.20+) |
| Python | `ExceptionGroup` (3.11+) |
| Rust | Custom `Vec<Error>` or `anyhow` context chain |
| TypeScript | `AggregateError` |

### Custom Error Hierarchies

Define a base error type per project/crate/package. Subtypes encode categories.

**Principles:**
- Base type enables catch-all at API boundaries
- Subtypes enable programmatic handling by callers
- Machine-readable codes (where applicable) enable telemetry
- Human-readable messages enable debugging

### Severity Classification

| Level | Definition | Action |
|-------|-----------|--------|
| Fatal | Process cannot continue | Log, clean up, exit non-zero |
| Recoverable | Operation failed, process continues | Log, retry or degrade gracefully |
| Warning | Non-ideal but not broken | Log at warning level, continue |
| Informational | Expected alternative path | Log at debug level |

### Anti-Patterns (Universal)

| Anti-Pattern | Why It's Bad | Instead |
|--------------|-------------|---------|
| Silent suppression (`catch {}`, `except: pass`, `_ =` without comment) | Hides bugs, makes debugging impossible | Log, propagate, or document the ignore |
| String-only errors | Not matchable, no programmatic handling | Use typed/structured errors |
| Catching too broadly | Masks unrelated failures | Catch the most specific type possible |
| Logging AND re-raising the same error | Duplicate log entries at every layer | Log at the boundary, propagate elsewhere |
| Panic/throw in library code for expected failures | Crashes callers unexpectedly | Return error types; reserve panic for invariant violations |

---

## Testing Best Practices

### Test Organization

| Layer | Scope | Speed | When to Run |
|-------|-------|-------|-------------|
| Unit | Single function/method | < 100ms | Every commit |
| Integration | Multiple components, real I/O | < 30s | Every PR |
| End-to-end | Full system with real deps | < 5min | Pre-release |
| Property-based | Invariant fuzzing | Varies | CI nightly or on critical paths |

### Table-Driven / Parameterized Tests

The table-driven pattern is universal. Define inputs and expected outputs in a data structure, then iterate.

| Language | Mechanism |
|----------|-----------|
| Go | `[]struct{ name, input, want }` + `t.Run()` |
| Python | `@pytest.mark.parametrize("input,expected", [...])` |
| Rust | `#[test]` with loop or `proptest!` macro |
| TypeScript | `test.each([...])` or `describe.each([...])` |
| Shell | BATS `@test` with parameterized fixtures |

**Benefits:**
- Easy to add new cases (one line per case)
- Clear test naming
- DRY -- assertion logic written once

### Fixtures and Mocking Philosophy

| Principle | ALWAYS | NEVER |
|-----------|--------|-------|
| External boundaries | Mock external services, APIs, databases | Let tests hit real external services in unit tests |
| Internal code | Test real internal implementations | Mock internal functions (couples tests to implementation) |
| Test isolation | Each test sets up its own state | Share mutable state between tests |
| Cleanup | Clean up resources (files, containers, connections) | Leave test artifacts behind |

### Test Double Types

| Type | Purpose | When to Use |
|------|---------|-------------|
| Stub | Returns canned data | Simple happy/sad path |
| Mock | Verifies interactions were called | Behavior verification |
| Fake | Working lightweight implementation | Integration-like tests without real infra |
| Spy | Records calls for later assertion | Interaction counting/ordering |

### Coverage Targets

| Metric | Minimum | Target | Critical Paths |
|--------|---------|--------|----------------|
| Line coverage | 60% | 80% | 90%+ |
| Branch coverage | 50% | 70% | 85%+ |

**Coverage philosophy:**
- Coverage is a floor, not a ceiling -- low coverage signals under-testing, high coverage does not guarantee quality
- Prioritize critical paths (error handling, security, data integrity) over boilerplate
- Measure branch coverage, not just line coverage -- untested branches hide bugs

### Property-Based Testing

Test invariants that must hold for ALL inputs, not just hand-picked examples.

**When to use:**
- Serialization roundtrips (encode then decode = original)
- Mathematical properties (commutativity, associativity)
- Parser contracts (valid input always parses, invalid always fails)
- Boundary conditions (output never exceeds input, no negative values)

### Doc Tests / Example Tests

Code examples in documentation should be executable tests. Guarantees documentation accuracy.

| Language | Mechanism |
|----------|-----------|
| Go | `func Example*` in `_test.go` files |
| Python | Doctest in docstrings, or `>>> ` examples |
| Rust | Code blocks in `///` doc comments |
| TypeScript | JSDoc `@example` blocks (manual verification) |

---

## Security Principles

### No Hardcoded Secrets

| ALWAYS | NEVER |
|--------|-------|
| Load secrets from environment variables or secret stores | Hardcode API keys, tokens, passwords in source |
| Use `.env` files locally (gitignored) | Commit `.env` or credential files |
| Rotate secrets on exposure | Assume secrets are safe in private repos |
| Audit git history for leaked secrets | Rely on `.gitignore` alone for protection |

**Detection:** Prescan pattern P2 flags hardcoded secrets in all languages.

### Input Validation

Validate at system boundaries (user input, external APIs, file reads). Trust internal code within the same trust boundary.

| Rule | Description |
|------|-------------|
| Validate early | Check inputs at the entry point, not deep in business logic |
| Fail fast | Reject invalid input immediately with clear error messages |
| Allowlist over denylist | Define what IS valid, not what ISN'T |
| Type-safe parsing | Parse into typed structures, not raw strings |

### Injection Prevention

| Attack Vector | Prevention |
|---------------|-----------|
| SQL injection | Parameterized queries / prepared statements. NEVER string interpolation. |
| Command injection | Use array-based exec (no shell). Avoid `eval()`, `exec()`, `system()`. |
| Template injection | Use auto-escaping template engines. Escape user input in templates. |
| Path traversal | Resolve to absolute path, verify within allowed directory. Block `..` sequences. |
| JSON/YAML injection | Use proper serialization libraries (e.g., `jq` in shell). NEVER string interpolation for structured formats. |

### Cryptographic Best Practices

| ALWAYS | NEVER |
|--------|-------|
| Use timing-safe comparison for secrets | Use `==` for secret/token comparison |
| Use established crypto libraries | Roll your own cryptography |
| Use strong hash functions (SHA-256+, bcrypt, argon2) | Use MD5 or SHA-1 for security |
| Enforce TLS 1.2+ (prefer 1.3) | Disable certificate verification in production |
| Generate random values with crypto-grade RNG | Use math/random for security-sensitive values |

### Dependency Auditing

| Practice | Frequency |
|----------|-----------|
| Run `audit` command (`npm audit`, `cargo audit`, `pip-audit`, `govulncheck`) | Every CI build |
| Pin dependency versions with lock files | Always committed for applications |
| Review new dependencies before adding | Before merge |
| Monitor for CVEs in transitive dependencies | Automated via Dependabot/Renovate |

### eval/exec/system Avoidance

| Rule | Description |
|------|-------------|
| Avoid `eval()` in all languages | Executes arbitrary code; use structured dispatch instead |
| Avoid shell execution from application code | Use library APIs instead of shelling out |
| If shell execution is unavoidable | Use array-based exec with no interpolation |
| Shell scripts | Avoid `eval` for user-provided data; use functions for dispatch |

### OWASP Top 10 Mapping

| # | OWASP Category | Prevention Pattern | Detection |
|---|----------------|-------------------|-----------|
| A01 | Broken Access Control | Deny by default; enforce server-side auth on every endpoint | Prescan P3: missing auth middleware |
| A02 | Cryptographic Failures | TLS 1.2+, strong hashing (bcrypt/argon2), no plaintext secrets | Prescan P2: hardcoded secrets |
| A03 | Injection | Parameterized queries, array-based exec, template auto-escaping | Prescan P1: string interpolation in queries/commands |
| A04 | Insecure Design | Threat modeling, abuse case testing, rate limiting | Architecture review |
| A05 | Security Misconfiguration | Minimal permissions, disable defaults, harden headers | Config audit |
| A06 | Vulnerable Components | `govulncheck`, `npm audit`, `pip-audit`, `cargo audit` | CI dependency scan |
| A07 | Auth Failures | MFA, strong passwords, session timeout, credential rotation | Auth integration tests |
| A08 | Data Integrity Failures | Signed updates, verified CI/CD pipeline, SBOM | Supply chain review |
| A09 | Logging Failures | Log auth events, access control failures, input validation | Log coverage audit |
| A10 | SSRF | Allowlist outbound hosts, block internal IPs, validate URLs | Prescan P4: unvalidated URL construction |

### HTTP Handler Security Patterns

| Pattern | ALWAYS | NEVER |
|---------|--------|-------|
| Request validation | Validate Content-Type, Content-Length, and body schema before processing | Process requests without type checking |
| Response escaping | Use framework auto-escaping; set explicit Content-Type headers | Return user data in responses without escaping |
| Content-Type | Set `Content-Type` and `X-Content-Type-Options: nosniff` on every response | Rely on browser MIME-sniffing |
| CORS | Restrict `Access-Control-Allow-Origin` to known domains | Use wildcard (`*`) origin with credentials |
| CSRF | Use anti-CSRF tokens for state-changing operations | Rely solely on cookies for authentication |
| Rate limiting | Apply rate limits to authentication, API, and upload endpoints | Allow unlimited requests to sensitive endpoints |
| Headers | Set `Strict-Transport-Security`, `X-Frame-Options`, `Content-Security-Policy` | Omit security headers from responses |

### Path Traversal Prevention

Resolve user-supplied paths to absolute form, then verify the result stays within the allowed directory.

| Language | Pattern |
|----------|---------|
| Go | `cleaned := filepath.Clean(userPath); if !strings.HasPrefix(filepath.Join(baseDir, cleaned), baseDir) { reject }` |
| Python | `resolved = (base_dir / user_path).resolve(); if not str(resolved).startswith(str(base_dir.resolve())): raise` |
| Node | `const resolved = path.resolve(baseDir, userPath); if (!resolved.startsWith(baseDir)) throw` |
| Shell | `realpath "$user_path" | grep -q "^$base_dir" || exit 1` |

**Key rules:**
- Always resolve BEFORE checking — `../` sequences bypass naive prefix checks
- Block null bytes (`\0`) in file paths — some runtimes truncate at null
- Reject absolute paths in user input when relative paths are expected

### Logging Security

| Rule | Description |
|------|-------------|
| Never log passwords | Hash or mask credentials before any log statement |
| Never log tokens | API keys, JWTs, session tokens — redact to first/last 4 chars max |
| Never log PII | Email, SSN, phone numbers — mask or omit in logs |
| Structured logging | Use structured fields (JSON) to prevent log injection via newlines |
| Log levels for security events | Auth failures = WARN, access control violations = ERROR, suspected attacks = CRITICAL |
| Retention | Define log retention policy; purge logs containing sensitive data on schedule |

### Rate Limiting Guidance

| Endpoint Type | Recommended Limit | Strategy |
|---------------|-------------------|----------|
| Authentication (login, register) | 5-10 req/min per IP | Token bucket with exponential backoff |
| API (authenticated) | 100-1000 req/min per user | Sliding window counter |
| File upload | 5-10 req/hour per user | Fixed window with size limits |
| Password reset | 3-5 req/hour per email | Fixed window, no enumeration leak |
| Public (unauthenticated) | 30-60 req/min per IP | Sliding window with CAPTCHA fallback |

**Implementation notes:**
- Apply rate limits at the reverse proxy / API gateway level when possible
- Return `429 Too Many Requests` with `Retry-After` header
- Log rate limit hits for abuse detection
- Consider separate limits for read vs write operations

---

## Documentation Standards

### What to Document

| Document | Why |
|----------|-----|
| Public API signatures | Callers need to know parameters, return types, error behavior |
| Non-obvious logic | Future readers (including yourself) need to understand WHY, not WHAT |
| Error behavior | Callers must know what can fail and how |
| Security-sensitive decisions | Reviewers need to verify threat model compliance |
| Configuration options | Users need to know defaults, valid ranges, and effects |
| Architecture decisions | Teams need to understand trade-offs and constraints |

### What NOT to Document

| Skip | Why |
|------|-----|
| Obvious code (`i++`, `return nil`) | Comments add noise, not signal |
| Implementation details of private functions | Changes frequently; comments go stale |
| Type information already in signatures | Redundant with the type system |
| "What" the code does (when code is clear) | The code itself is the documentation |

### Examples in Documentation

- Include usage examples for public APIs
- Examples should be runnable (doc tests where supported)
- Show the common case first, edge cases second
- Include error handling in examples

### Keeping Documentation in Sync

| Practice | Description |
|----------|-------------|
| Doc tests | Executable examples catch staleness automatically |
| Review docs with code changes | PR reviews should include doc updates |
| Delete docs for deleted features | Stale docs are worse than no docs |
| Version documentation | Match docs to release versions |

### Cross-Reference Patterns

- Link to related concepts rather than duplicating content
- Use relative paths within a project
- Reference external standards by URL (e.g., RFC numbers, OWASP guides)

---

## Code Organization Principles

### Module/Package Naming

| Convention | Description |
|------------|-------------|
| Short, descriptive names | `config`, `handlers`, `models` -- not `configurationManager` |
| Lowercase with language-appropriate separators | `snake_case` (Python/Rust/Go), `kebab-case` (npm/crate names), `camelCase` (TS) |
| No stuttering | `config.Config` is fine; `config.ConfigConfig` is not |
| Domain-driven grouping | Group by feature/domain, not by technical layer |

### Public vs Private Visibility

| Rule | Description |
|------|-------------|
| Minimize public API surface | Export only what callers need |
| Default to private | Make things public only when required |
| Use explicit re-exports | Control the public API from a single entry point |
| Hide implementation details | Internal helpers, data structures, and algorithms stay private |

### Circular Dependency Avoidance

| Strategy | Description |
|----------|-------------|
| Dependency inversion | Depend on abstractions (interfaces/traits), not implementations |
| Extract shared types | Move shared types to a separate, leaf-level module |
| Event-based decoupling | Use events/callbacks instead of direct cross-module calls |
| Layer discipline | Higher layers depend on lower layers, never the reverse |

### File Size Heuristics

| Size | Status | Action |
|------|--------|--------|
| < 300 lines | Excellent | Maintain |
| 300-500 lines | Acceptable | Monitor |
| 500-800 lines | Warning | Consider splitting |
| 800+ lines | Critical | Split into submodules |

### Version-Aware Development

Language-specific standards SHOULD declare the target language/runtime version and organize modern features by version availability. This prevents using features unavailable in the target version and ensures developers adopt modern alternatives when available.

| Language | Version Source | Example Modern Features |
|----------|---------------|------------------------|
| Go | `go.mod` `go` directive | `slices` (1.21+), `range n` (1.22+), `t.Context()` (1.24+) |
| Python | `pyproject.toml` `requires-python` | `match` (3.10+), `tomllib` (3.11+), exception groups (3.11+) |
| Rust | `Cargo.toml` `edition` | `let-else` (2021+), `async fn in trait` (2024+) |
| TypeScript | `tsconfig.json` `target` | `satisfies` (4.9+), `using` (5.2+) |

### Import Ordering

All languages follow the same conceptual grouping:

1. **Standard library** imports
2. **External/third-party** imports
3. **Internal/project** imports

Separated by blank lines. Alphabetical within each group.

---

## Canonical Language Owners

Language-specific guidance lives beside this document in one concise canonical
file per language:

| Language | Canonical file |
|----------|----------------|
| Go | `go.md` |
| Python | `python.md` |
| Rust | `rust.md` |
| TypeScript | `typescript.md` |
| JavaScript | `javascript.md` |
| Shell | `shell.md` |
| JSON/JSONL | `json.md` |
| YAML | `yaml.md` |
| Markdown | `markdown.md` |

Validate consumes these standards as criteria; it does not own duplicate
language catalogs. Universal error-handling, testing, security, documentation,
and organization rules remain here, while language files carry only the
syntax, tooling, and runtime details needed to apply them.

---

**Related:** Language-specific standards in `go.md`, `python.md`, `rust.md`, `typescript.md`, `shell.md`

# Go Standards (Tier 1)

## Target Version

Detect from `go.mod`. Use all features up to and including that version. Never use features from newer versions. Current project target: **Go 1.26**.

## Required

- `gofmt` (automatic)
- `golangci-lint run` passes
- All exported symbols documented

## Error Handling

- Always check errors: `if err != nil`
- Wrap errors with context: `fmt.Errorf("doing X: %w", err)`
- Never `_ = err` without `// nolint:errcheck` comment
- Use `errors.Is(err, target)` instead of `err == target` -- works with wrapped errors (1.13+)
- Use `errors.Join(err1, err2)` to aggregate errors from parallel operations or multi-step cleanup (1.20+)
- Use `context.WithCancelCause` / `context.Cause` to attach error reasons to cancellations (1.20+)

## Common Issues

| Pattern | Problem | Fix |
|---------|---------|-----|
| `%v` for errors | Breaks error chain | Use `%w` |
| `panic()` in library | Crashes caller | Return error |
| Naked goroutine | No error handling | errgroup or channels |
| `interface{}` | Type safety loss | Use `any` (1.18+), generics, or specific types |
| `err == target` | Misses wrapped errors | `errors.Is(err, target)` (1.13+) |
| `atomic.StoreInt32` | Type-unsafe | `atomic.Bool` / `atomic.Int64` / `atomic.Pointer[T]` (1.19+) |
| `for i := 0; i < n; i++` | Verbose | `for i := range n` (1.22+) |
| Manual loop for contains/sort | Error-prone, verbose | `slices.Contains`, `slices.SortFunc` (1.21+) |
| `sync.Once` + closure wrapper | Verbose, easy to misuse | `sync.OnceFunc` / `sync.OnceValue` (1.21+) |

## Interfaces

- Accept interfaces, return structs
- Keep interfaces small (1-3 methods)
- Define interfaces where used, not implemented

## Documentation

- All exported symbols must have godoc comments starting with the symbol name
- Package-level doc in `doc.go` for non-trivial packages
- Include runnable `Example_*` functions in `_test.go` files
- Run `go doc ./...` to verify documentation

## Concurrency

- Always pass `context.Context` as first param
- Use `sync.Mutex` for shared state; use type-safe atomics (`atomic.Bool`, `atomic.Int64`, `atomic.Pointer[T]`) for simple flags/counters (1.19+)
- Prefer channels for communication
- Use `sync.OnceFunc(fn)` instead of `sync.Once` + wrapper; `sync.OnceValue(fn)` when returning a value (1.21+)
- Use `context.AfterFunc(ctx, cleanup)` to register cleanup on cancellation (1.21+)
- Loop variables are safe to capture in goroutines since 1.22 (each iteration gets its own copy)

## Modern Standard Library

### slices package (1.21+)

Prefer `slices` over hand-written loops:

| Function | Replaces |
|----------|----------|
| `slices.Contains(items, x)` | Manual search loop |
| `slices.Index(items, x)` | Manual search loop returning index |
| `slices.IndexFunc(items, fn)` | Manual search loop with predicate |
| `slices.Sort(items)` | `sort.Slice` / `sort.Strings` |
| `slices.SortFunc(items, cmp)` | `sort.Slice` with less function |
| `slices.Max(items)` / `slices.Min(items)` | Manual loop tracking max/min |
| `slices.Reverse(items)` | Manual swap loop |
| `slices.Compact(items)` | Manual dedup of consecutive elements |
| `slices.Clip(s)` | `s[:len(s):len(s)]` to remove excess capacity |
| `slices.Clone(s)` | `append([]T(nil), s...)` |

Iterator consumption (1.23+):

| Function | Usage |
|----------|-------|
| `slices.Collect(iter)` | Build slice from iterator |
| `slices.Sorted(iter)` | Collect and sort in one step |

### maps package (1.21+; Keys/Values return iterators as of 1.23)

| Function | Replaces |
|----------|----------|
| `maps.Clone(m)` | Manual map copy loop |
| `maps.Copy(dst, src)` | Manual map merge loop |
| `maps.DeleteFunc(m, fn)` | Manual delete loop with predicate |
| `maps.Keys(m)` | Manual key collection loop (returns iterator, 1.23+) |
| `maps.Values(m)` | Manual value collection loop (returns iterator, 1.23+) |

### cmp package (1.22+)

- `cmp.Or(a, b, c)` -- returns first non-zero value. Replaces `if x == "" { x = default }` chains:
  ```go
  name := cmp.Or(os.Getenv("NAME"), config.Name, "default")
  ```

### strings / bytes improvements

| Function | Version | Replaces |
|----------|---------|----------|
| `strings.Cut(s, sep)` / `bytes.Cut(b, sep)` | 1.18+ | `Index` + slice arithmetic |
| `strings.CutPrefix(s, prefix)` / `strings.CutSuffix(s, suffix)` | 1.20+ | `HasPrefix` + `TrimPrefix` |
| `strings.Clone(s)` / `bytes.Clone(b)` | 1.20+ | Manual copy (prevents memory leaks from substring references) |

### net/http improvements (1.22+)

Enhanced `ServeMux` with method and path parameters:

```go
mux.HandleFunc("GET /api/users/{id}", func(w http.ResponseWriter, r *http.Request) {
    id := r.PathValue("id")
    // ...
})
```

May eliminate the need for third-party routers for simple APIs.

### Other stdlib

| Function | Version | Replaces |
|----------|---------|----------|
| `fmt.Appendf(buf, fmt, args...)` | 1.19+ | `[]byte(fmt.Sprintf(...))` -- avoids allocation |
| `time.Since(start)` | 1.0+ | `time.Now().Sub(start)` |
| `time.Until(deadline)` | 1.8+ | `deadline.Sub(time.Now())` |
| `errors.Join(err1, err2)` | 1.20+ | Discarding all but the first error (see Error Handling) |
| `reflect.TypeFor[T]()` | 1.22+ | `reflect.TypeOf((*T)(nil)).Elem()` |
| `min(a, b)` / `max(a, b)` | 1.21+ | `if a > b` patterns or custom helpers |
| `clear(m)` / `clear(s)` | 1.21+ | Manual map deletion loop / manual slice zeroing |

## Struct Contract Completeness

When adding fields to a struct, every code path that creates an instance **must** populate them. Partial population creates an inconsistent contract for consumers.

| Anti-Pattern | Problem | Fix |
|--------------|---------|-----|
| New field on struct, some constructors don't set it | Consumers see zero-value for some paths, real value for others | Grep all `StructName{` literals; verify each sets the new field |
| Synthesized instances (e.g., end-of-batch summaries) skip fields | Downstream code assumes all instances have the same shape | Store provenance metadata alongside state so synthesized instances can populate fields from last-seen values |
| Index fields after sort | `EventIndex` points to sorted position, not caller's original position | Wrap items with original index before sorting; emit original index in output |

**Checklist for adding struct fields:**
1. Grep `StructName{` across the package — every literal must set the new field
2. Check factory functions and builder patterns
3. Check synthesized/summary instances created outside the main loop
4. Add a structural assertion test: iterate all output instances, assert new field is non-zero (or document why zero is valid)

## Wire Input Validation

When parsing external JSON/YAML into structs with enum-like fields, **validate against an allowlist** before trusting the value.

```go
// BAD: trust whatever the wire sends
if ev.ErrorClass != "" {
    // use it as-is — "bogus" passes through
}

// GOOD: validate against known values
var validClasses = map[ErrorClass]bool{ ... }
if ev.ErrorClass != "" && !validClasses[ev.ErrorClass] {
    ev.ErrorClass = classify(ev) // reclassify from content
}
```

Also normalize impossible states: if `IsError=false` but `ErrorClass="timeout"`, clear it.

## Testing

### Exact Assertion Rule

**Always assert the exact expected value, never just "not the wrong one."**

```go
// BAD: passes even if classification drifts to a different wrong class
if got == StreamErrorClassRateLimit {
    t.Errorf("should not be rate_limit")
}

// GOOD: pins the exact expected behavior
if got != StreamErrorClassExecutionError {
    t.Errorf("got %q, want execution_error", got)
}
```

This applies to all classifier/enum tests. `!= X` assertions silently pass when the result drifts to a third, equally wrong value.

### Structural Invariant Tests

For structs with required fields, add a sweep test that asserts ALL output instances populate them:

```go
func TestAllViolationsHaveStructuredFields(t *testing.T) {
    // Run through multiple scenarios, collect all violations
    for _, v := range allViolations {
        if v.TeamName == "" && v.Rule != RuleSomeException {
            t.Errorf("violation %+v missing TeamName", v)
        }
        if v.Timestamp.IsZero() {
            t.Errorf("violation %+v missing Timestamp", v)
        }
    }
}
```

### CI-Safe Test Pattern

When testing functions that shell out to an external CLI, inject a command
runner and test both the adapter and the pure result mapping. This keeps tests
deterministic when the CLI is not installed.

```go
func TestInspectToolMapsOutput(t *testing.T) {
    runner := fakeRunner{stdout: []byte(`{"status":"ok"}`)}
    got, err := inspectTool(context.Background(), runner)
    require.NoError(t, err)
    assert.Equal(t, "ok", got.Status)
}
```

Also add one adapter-level test that proves the expected executable name and
arguments were supplied to the runner.

### Table-Driven Tests

Prefer table-driven tests for functions with multiple input/output cases:

```go
func TestClassifyServeArg(t *testing.T) {
    tests := []struct {
        name      string
        flagRunID string
        args      []string
        wantGoal  string
        wantRunID string
    }{
        {"empty", "", nil, "", ""},
        {"flag run-id", "rpi-abc12345", nil, "", "rpi-abc12345"},
        {"arg goal", "", []string{"fix the bug"}, "fix the bug", ""},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            goal, runID := classifyServeArg(tt.flagRunID, tt.args)
            assert.Equal(t, tt.wantGoal, goal)
            assert.Equal(t, tt.wantRunID, runID)
        })
    }
}
```

### Test Conventions

- **File naming:** Test files MUST be named `<source>_test.go`. NEVER `cov*_test.go`, `*_extra_test.go`, or other non-standard prefixes. Keep all tests for a source file in one test file.
- **Function naming:** `Test<Uppercase>` (e.g., `TestFoo_Bar`). Go requires uppercase letter after `Test`.
- **No coverage-padding:** Tests that use trivial `!= ""` or `!= nil` assertions solely to inflate coverage are banned. Every test must assert behavioral correctness.
- **No zero-assertion smoke tests:** Every test must have assertions. For print/output functions, use `captureStdout` and assert output contains expected strings.
- **Assert exact expected values:** Use `== expected`, never `!= wrong`. (See Exact Assertion Rule above.)
- **Table-driven tests** preferred for multi-case functions. (See example above.)
- **Test low-level functions directly;** don't depend on external CLIs (`bd`, `ao`) in tests. (See CI-Safe Test Pattern above.)
- **Guard-test fixtures must use the real persisted shape.** Skip/dedup/consumed/idempotency/regression guard tests must round-trip a real persisted sample (production writer → production reader) or assert against a checked-in real example — never a hand-built in-memory constructor that sets a marker at a granularity the on-disk format never emits (e.g. `consumed` at item-level when `next-work.jsonl` marks it at batch-level). A fixture of a shape production can't produce gives a false green (ag-mjlg / PR #652). Related fixture guidance: `test-pyramid.md` → "Regression design".
- **Test isolation — restore shared global/process state via `t.Cleanup`.** `cli/cmd/ao` tests share one `rootCmd` + package-global cobra flag vars and run inside the repo tree, so a test that mutates shared state without restoring it leaks into whatever test the `-shuffle=on` order runs next. This is a recurring flake class: goals `goalsMeasureScenariosOnly` cobra-global (`a9dab21c4`), `core.bare` git-env (ek8v), cwd floor (hvb).
  - Set a package-global cobra flag only through a self-cleaning helper, so every set-site auto-restores and no order can leak it:

    ```go
    func setGoalsMeasureScenariosOnly(t *testing.T, v bool) {
        t.Helper()
        old := goalsMeasureScenariosOnly
        goalsMeasureScenariosOnly = v
        t.Cleanup(func() { goalsMeasureScenariosOnly = old })
    }
    ```

  - Scope process state: `t.Chdir(t.TempDir())`, `t.Setenv`, and `git -C <tempRepo>` with `cmd.Dir` set. Never run a state-mutating `git` op against the real repo via an unset `cmd.Dir` / leaked `GIT_DIR`.
  - Any package whose tests shell out to `git` MUST call `testsupport.ScrubGitDiscoveryEnv()` from its `TestMain` (`cli/internal/testsupport`). Git injects `GIT_DIR`/`GIT_WORK_TREE`/... into hook-launched processes; with `GIT_DIR` pointing at a linked worktree's gitdir, a fixture `git init` rewrites the SHARED `.git/config` to `core.bare=true`, bricking every worktree (ek8v; recurred 2026-07-18).
  - Find leakers by analysis (grep set-sites for a missing reset), not by chasing reproducing seeds: order-dependent flakes are population+seed-specific, so "couldn't reproduce" ≠ fixed — close on the root (the missing cleanup).
  - The push==CI full race suite runs `-shuffle=on` as the *late* backstop; it is not the primary guard.

### Benchmark Tests (BF7)

Use Go's built-in benchmark support for hot-path functions:

```go
func BenchmarkParseConfig(b *testing.B) {
    input := generateLargeConfig(1000)
    b.ResetTimer()
    for b.Loop() {  // Go 1.24+; use `for i := 0; i < b.N; i++` for older versions
        parseConfig(input)
    }
}
```

Run with: `go test -bench=. -benchmem ./...`

Compare across changes with `benchstat`:
```bash
go test -bench=. -count=10 ./... > old.txt
# ... make changes ...
go test -bench=. -count=10 ./... > new.txt
benchstat old.txt new.txt
```

### Backward Compatibility Tests (BF8)

Maintain golden fixtures in `testdata/compat/`:

```go
func TestBackwardCompat(t *testing.T) {
    fixtures, err := filepath.Glob("testdata/compat/*.json")
    require.NoError(t, err)
    require.NotEmpty(t, fixtures, "compat fixtures must exist")
    for _, f := range fixtures {
        t.Run(filepath.Base(f), func(t *testing.T) {
            data, _ := os.ReadFile(f)
            result, err := ParseConfig(data)
            require.NoError(t, err, "legacy format must still parse")
            assert.NotEmpty(t, result.Name)
        })
    }
}
```

### Regression Tests (BF6)

Name after the bug ID. Reproduce the exact failure:

```go
func TestBug_AG_XYZ_NilMapPanic(t *testing.T) {
    // Regression: processGoals panicked on nil options map (ag-xyz)
    result, err := processGoals(nil)
    require.NoError(t, err)
    assert.Empty(t, result)
}
```

### Security Tests (BF9)

Test path traversal rejection and secrets redaction:

```go
func TestRejectsPathTraversal(t *testing.T) {
    payloads := []string{"../../../etc/passwd", "..\\windows", "foo/../bar"}
    for _, p := range payloads {
        t.Run(p, func(t *testing.T) {
            _, err := LoadConfig(p)
            assert.Error(t, err, "must reject path traversal")
        })
    }
}
```

### Complexity Budget

- **Warn** at cyclomatic complexity 15, **fail** at 25.
- Use the repository's actual complexity/CI check; lint alone does not establish
  this budget. In AgentOps, run from the repository root:
  `bash scripts/check-go-complexity.sh --base <accepted-base>`.
  It discovers changed paths from committed `<accepted-base>...HEAD`; a
  no-files/skip result does not validate uncommitted changes.

### Before Committing Go Changes

```bash
cd cli && go build ./... && go vet ./... && go test ./...
```

Or equivalently: `cd cli && make build && make test`

## HTTP Handler Security

Go HTTP handlers in this codebase are localhost-only but should still follow defense-in-depth:

| Pattern | Risk | Fix |
|---------|------|-----|
| `innerHTML = userInput` in embedded HTML | XSS | Use DOM construction (`createElement` + `textContent`) |
| `r.URL.Query().Get("param")` used in file paths | Path traversal | Reject `..`, `/`, `\` before use |
| `fmt.Fprintf(w, userInput)` in HTML handler | XSS | Use `html/template` or `text/template` with escaping |
| `filepath.Join(root, userInput)` | Path traversal | Validate input against allowlist pattern (e.g., `regexp`) |
| `Access-Control-Allow-Origin: *` | CORS bypass | Acceptable for localhost-only; restrict for public APIs |

**Query parameter validation pattern:**

```go
param := strings.TrimSpace(r.URL.Query().Get("id"))
if param != "" && (strings.Contains(param, "..") || strings.Contains(param, "/") || strings.Contains(param, "\\")) {
    http.Error(w, "invalid parameter", http.StatusBadRequest)
    return
}
```

**DOM construction instead of innerHTML:**

```javascript
// BAD: innerHTML with user-controlled data
el.innerHTML = '<span>' + userInput + '</span>';

// GOOD: DOM construction
const span = document.createElement('span');
span.textContent = userInput;
el.appendChild(span);
```

## Security-Lint Suppressions (gosec + semgrep)

When a security-lint finding is a false positive on intentional crypto (e.g. SHA-1 used for git object IDs, not as a security primitive), the suppression needs TWO independent annotations on the SAME line. gosec and semgrep run as separate scanners and each ignores the other's directives.

| Scanner | What it ignores | What suppresses it |
|---------|-----------------|--------------------|
| gosec (standalone) | `//nolint:gosec` (golangci-lint-only) | `// #nosec G<NN>` directive, e.g. `// #nosec G401 G505` |
| semgrep | qualified `nosemgrep: <rule-id>` (does NOT suppress) | a **bare** `// nosemgrep` |

Combine both into one comment and place it on **both** the import line and the usage/call site — each is flagged independently:

```go
import (
    "crypto/sha1" // #nosec G505 nosemgrep -- git object IDs are SHA-1 by definition; not a security primitive here.
)

func gitBlobID(content []byte) string {
    h := sha1.New() // #nosec G401 nosemgrep -- git blob IDs are SHA-1; matching git.
    // ...
}
```

The `G<NN>` codes differ by site: G505 flags the `crypto/sha1` import (blocklisted import), G401 flags the `sha1.New()` call (weak crypto primitive). Pass every code that fires on a given line.

Canonical example in this repo: `cli/internal/drrebuild/drrebuild.go`.

## Future Features (Go 1.24+)

This section tracks features by first-supported Go version and can be used to plan future target upgrades.

| Feature | Version | What It Replaces |
|---------|---------|------------------|
| `t.Context()` | 1.24+ | `context.WithCancel(context.Background())` in tests |
| `b.Loop()` | 1.24+ | `for i := 0; i < b.N; i++` in benchmarks |
| `omitzero` JSON tag | 1.24+ | `omitempty` (which fails for `time.Duration`, structs, slices, maps) |
| `strings.SplitSeq` / `FieldsSeq` | 1.24+ | `strings.Split` when iterating (avoids intermediate slice) |
| `wg.Go(fn)` | 1.25+ | `wg.Add(1)` + `go func() { defer wg.Done(); ... }()` |
| `new(val)` | 1.26+ | `x := val; &x` for pointer creation |
| `errors.AsType[T](err)` | 1.26+ | `var target T; errors.As(err, &target)` |

# JavaScript Standards (Tier 1)

## Required
- ES2020 or newer (Node 18+ runtime).
- `prettier` for formatting; `eslint` with the recommended ruleset.
- `package.json` declares `"type": "module"` for new packages.

## Style
- `const` by default; `let` only when reassignment is required; never `var`.
- Arrow functions for callbacks; named `function` for top-level declarations.
- Strict equality (`===` / `!==`) — no loose equality.
- One module per file; default export only when the module is the unit.

## Async
- `async`/`await` over raw `.then()` chains.
- Always `await` or explicitly handle returned Promises.
- Reject errors with `Error` instances, never raw strings.

## Error Handling
- No empty `catch {}` blocks; either re-throw or log with context.
- Use `try`/`catch` only at boundaries (HTTP, IO, IPC); let errors bubble inside pure logic.
- Validate external input before use; trust internal callers.

## Common Issues
| Pattern | Problem | Fix |
|---------|---------|-----|
| `==`, `!=` | Coerces types silently | Use `===`, `!==` |
| `parseInt(x)` | Defaults to base 10 only since ES5 but easy to miss | Pass radix: `parseInt(x, 10)` |
| `for...in` on arrays | Iterates inherited enumerable props | Use `for...of` or `.forEach` |
| Mutating shared state | Hard-to-trace bugs | Spread/`Object.assign` for copies; Array methods that return new arrays |
| Float arithmetic | `0.1 + 0.2 !== 0.3` | Round to integer cents before compare |

## Testing
- Vitest or Jest; `node --test` is acceptable for small libraries.
- Use `describe` / `it` blocks; one logical assertion per `it`.
- Mock external services; don't mock the unit under test.
- Snapshot tests only for stable serialized output, never for UI-rich strings.

## Security
- Never use `eval()`, `Function()`, or `new Function()` with untrusted input.
- Sanitize HTML before injecting into the DOM; prefer `textContent` over `innerHTML`.
- Use `crypto.randomUUID()` / `crypto.getRandomValues()`, not `Math.random()`, for tokens.
- Pin dependency versions in `package-lock.json` or `pnpm-lock.yaml`; audit with `npm audit` before release.

# JSON Standards (Tier 1)

## Validation
- Valid JSON (use `jq .` to verify)
- Consistent formatting (2-space indent)
- No trailing commas

## Common Issues
| Pattern | Problem | Fix |
|---------|---------|-----|
| Trailing comma | Parse error | Remove |
| Single quotes | Invalid JSON | Double quotes only |
| Comments | Invalid JSON | Remove or use JSONC |
| Unquoted keys | Invalid JSON | Quote all keys |

## JSONL (newline-delimited)
- One JSON object per line
- No trailing newline on last line
- Each line must be valid JSON

## Schema Validation
- Use JSON Schema for validation
- Reference: `"$schema": "https://..."`
- Required fields should be explicit

## Security
- Never use `eval()` or `Function()` to parse JSON — use `JSON.parse()`
- Validate against JSON Schema before processing untrusted input
- Watch for prototype pollution in JavaScript/TypeScript JSON handling
- Sanitize keys and values when constructing JSON from user input

## Large Files
- Consider JSONL for append-only logs
- Use streaming parsers for large files
- Compress with gzip for storage

# LLM Trust Boundary Checklist

Domain-specific checklist for code that calls LLM APIs or processes LLM outputs.

## Mandatory Checks

### Input Validation
- [ ] User-supplied prompts are sanitized (no prompt injection vectors)
- [ ] System prompts are not exposed to end users
- [ ] Prompt templates use parameterized injection points, not string concatenation
- [ ] Input length limits enforced before API call (prevent token budget exhaustion)

### Output Validation
- [ ] LLM output is validated against expected schema before use
- [ ] JSON responses are parsed with strict schema validation (not just `json.loads()`)
- [ ] Hallucinated field names/values are detected and rejected
- [ ] Output is never used as code input without sandboxing (`eval()`, `exec()`, shell commands)
- [ ] Empty responses handled explicitly (not silently passed through)

### Error Handling
- [ ] API timeout has explicit handling (retry with backoff)
- [ ] Rate limit (429) has backoff strategy
- [ ] Model refusal detected and handled (not treated as valid output)
- [ ] Malformed response has retry-with-stricter-prompt fallback
- [ ] Cost/token budget tracked per request (prevent runaway spending)

### Trust Boundaries
- [ ] LLM output treated as untrusted input at every boundary
- [ ] No direct database writes from LLM output without validation
- [ ] No file system operations from LLM output without path validation
- [ ] No network requests to LLM-generated URLs without allowlist check
- [ ] User-visible LLM output has content safety filtering

### Observability
- [ ] Request/response pairs logged (with PII redaction)
- [ ] Token usage tracked per call and per session
- [ ] Latency metrics captured (p50, p95, p99)
- [ ] Retry counts and failure modes tracked
- [ ] Model version pinned and logged (not just "latest")

### Testing
- [ ] Tests cover malformed response handling
- [ ] Tests cover empty response handling
- [ ] Tests cover refusal handling
- [ ] Tests use deterministic fixtures, not live API calls
- [ ] Evaluation suite exists for output quality regression

## When to Apply

Load this checklist when:
- Changed files import `anthropic`, `openai`, `google.generativeai`, or similar
- Code constructs prompts or processes LLM responses
- Plan includes LLM integration or AI-powered features
- Files match patterns: `*llm*`, `*ai*`, `*prompt*`, `*completion*`, `*chat*`

# Markdown Standards (Tier 1)

## Structure
- Single H1 (`#`) at top
- Hierarchical headings (don't skip levels)
- Blank line before/after headings

## Common Issues
| Pattern | Problem | Fix |
|---------|---------|-----|
| Multiple H1s | Confusing structure | Single H1 |
| Skipped heading | H1 → H3 | H1 → H2 → H3 |
| No blank lines | Rendering issues | Blank before/after blocks |
| Hard line breaks | Formatting | Let text wrap naturally |

## Tables
```markdown
| Header | Header |
|--------|--------|
| Cell   | Cell   |
```
- Align `|` for readability
- Use `-` for header separator

## Code Blocks
- Always specify language: ` ```python `
- Use inline `` `code` `` for short refs
- 4-space indent also works (but fenced preferred)

## Links
- Use descriptive link text, not generic "click here"
- Use relative paths for local references
- Check links aren't broken

# Python Standards (Tier 1)

## Required
- `ruff check` passes (or `flake8`)
- `ruff format` (or `black`) for formatting
- Type hints on public functions
- Docstrings on public classes/functions

## Error Handling
- Never bare `except:` - always specify exception type
- Use `raise ... from e` to preserve stack traces
- Log before raising in library code

## Common Issues
| Pattern | Problem | Fix |
|---------|---------|-----|
| `except Exception:` | Too broad | Catch specific exceptions |
| `# type: ignore` | Hiding problems | Fix the type error |
| `eval()` / `exec()` | Security risk | Use safer alternatives |
| Mutable default args | Shared state bugs | Use `None` + conditional |

## Security
- Never use `eval()`, `exec()`, or `__import__()` with untrusted input
- Use `secrets` module for tokens, not `random`
- Validate and sanitize all external input (user data, file paths, URLs)
- Use parameterized queries for SQL — never string formatting

## Dataclass & Model Contract Completeness

When adding fields to a dataclass, Pydantic model, or TypedDict, every code path that creates an instance **must** populate them.

| Anti-Pattern | Problem | Fix |
|--------------|---------|-----|
| New field with `default=None`, some constructors never set it | Consumers see `None` for some paths, real value for others | Grep all `ClassName(` calls; verify each sets the new field |
| Synthesized instances (e.g., summary dicts, fallback objects) skip fields | Downstream code assumes all instances have the same shape | Store provenance metadata alongside state; populate synthesized instances from it |
| Index fields after sort | `event_index` points to sorted position, not caller's original position | Zip with `enumerate()` before sorting; emit original index |
| `__init__` sets fields conditionally | Some branches leave fields unset | Use `field(default_factory=...)` or set in all branches |

**Checklist for adding fields:**
1. Grep `ClassName(` across the package — every constructor call must set the new field
2. Check factory functions (`from_dict`, `from_json`, `create_*`)
3. Check synthesized/summary instances created outside the main loop
4. Add a structural assertion test (see below)

## Wire Input Validation

When parsing external JSON/YAML into models with enum-like fields, **validate against known values** before trusting.

```python
# BAD: trust whatever the wire sends
if event.error_class:
    # use as-is — "bogus" passes through

# GOOD: validate against known values
VALID_ERROR_CLASSES = {"timeout", "rate_limit", "auth_failure", ...}
if event.error_class and event.error_class not in VALID_ERROR_CLASSES:
    event.error_class = classify_error(event)  # reclassify from content
```

For Pydantic models, use `Literal` types or `@field_validator` to reject invalid values at parse time:

```python
from typing import Literal

class StreamEvent(BaseModel):
    error_class: Literal["timeout", "rate_limit", "auth_failure", ""] = ""
```

Also normalize impossible states: if `is_error=False` but `error_class="timeout"`, use a `@model_validator` to clear it.

## Classification & Pattern Matching

When classifying inputs by string patterns (error types, log levels, status codes):

| Anti-Pattern | Problem | Fix |
|--------------|---------|-----|
| `"429" in msg` | Matches port numbers, line numbers | Use regex with context: `r'\b(status|http|error|code)\s*:?\s*429\b'` |
| Bare keyword match (`"sandbox" in msg`) | "sandbox startup failed" misclassifies as sandbox violation | Require compound match: keyword + policy phrase (`denied`, `violation`) |
| Meaningless default case | `return "unknown"` for both truly-unknown and simply-unrecognized | Make default semantic: `"execution_error"` for non-empty, `"unknown"` for empty |
| No false-positive test coverage | Tests only check happy paths | Generate 5+ realistic false-positive inputs per pattern |

## Testing

### Exact Assertion Rule

**Always assert the exact expected value, never just "not the wrong one."**

```python
# BAD: passes even if classification drifts to a different wrong class
assert classify(msg) != "rate_limit"

# GOOD: pins the exact expected behavior
assert classify(msg) == "execution_error"
```

This applies to all classifier/enum tests. `!= X` assertions silently pass when the result drifts to a third, equally wrong value.

### Structural Invariant Tests

For dataclasses/models with required fields, add a sweep test that asserts ALL output instances populate them:

```python
def test_all_violations_have_structured_fields(violations):
    """Every violation must populate team_name, timestamp, and event_index."""
    for v in violations:
        assert v.team_name, f"violation {v} missing team_name"
        assert v.timestamp is not None, f"violation {v} missing timestamp"
```

### Property-Based Tests (BF1)

Use Hypothesis to randomize inputs to data transformations:

```python
from hypothesis import given
import hypothesis.strategies as st

@given(st.dictionaries(
    keys=st.from_regex(r'[A-Z_]+', fullmatch=True),
    values=st.text(min_size=0, max_size=200),
    min_size=1,
))
def test_parse_reader_never_crashes(env_vars):
    """Any valid config must parse without crashing."""
    stream = io.StringIO("\n".join(f"{k}={v}" for k, v in env_vars.items()))
    ctx = parse_reader(stream)
    assert isinstance(ctx, SiteContext)
```

Target: every parser, serializer, and data transformer. If it accepts external input, fuzz it.

### Backward Compatibility Tests (BF8)

Maintain a corpus of real inputs from prior versions as fixtures:

```python
from glob import glob

@pytest.mark.parametrize("fixture", sorted(glob("tests/fixtures/compat/*.env")))
def test_legacy_config_parses(fixture):
    """Every historical config format must still parse."""
    ctx = parse_config_env(fixture)
    assert ctx.site_name  # at least one required field populated
```

**Rule:** When changing input formats, add the OLD format as a fixture BEFORE making the change.

### Performance/Benchmark Tests (BF7)

Use `pytest-benchmark` for hot-path functions:

```python
def test_parse_config_performance(benchmark):
    """Parser must handle large configs without regression."""
    large_config = "\n".join(f"KEY_{i}=value_{i}" for i in range(1000))
    result = benchmark(parse_reader, io.StringIO(large_config))
    assert isinstance(result, SiteContext)
```

Install: `pip install pytest-benchmark`. Run: `pytest --benchmark-only`.

### Regression Tests (BF6)

Every bug fix gets a reproducing test named after the bug ID:

```python
def test_bug_ag_m0r_empty_value_crashes():
    """Regression: parse_reader crashed on config lines with empty values (ag-m0r)."""
    stream = io.StringIO("SITE_NAME=\nDB_HOST=prod-db")
    ctx = parse_reader(stream)
    assert ctx.site_name == ""
    assert ctx.db_host == "prod-db"
```

### Security Tests (BF9)

Test secrets redaction and input sanitization:

```python
def test_render_export_redacts_secrets():
    """render_export must never emit raw secret values."""
    ctx = SiteContext(site_name="test", db_password="s3cr3t!", api_key="ak-12345")
    output = render_export(ctx)
    assert "s3cr3t!" not in output, "raw password leaked"
    assert "ak-12345" not in output, "raw API key leaked"

def test_rejects_path_traversal():
    """Config paths must reject traversal attempts."""
    for payload in ["../../../etc/passwd", "..\\windows", "foo/../bar"]:
        with pytest.raises(ValueError):
            load_config(payload)
```

### Test Conventions

- **pytest** preferred; `conftest.py` for shared fixtures.
- **Mock external services, not internal code.**
- **ruff** linter: `ruff check` must pass.
- **mypy** for type checking.
- **Black** formatter with 100-character line length. Config in `pyproject.toml`.
- **Type hints** on all public functions.
- **Docstrings** on all public classes and functions.

Security and error-handling rules are not repeated here; see `## Security` and
`## Error Handling` above.

# Race Condition Checklist

Domain-specific checklist for concurrent, parallel, or multi-process code.

## Mandatory Checks

### Shared State
- [ ] All shared mutable state protected by mutex/lock/atomic
- [ ] No global mutable variables accessed from multiple goroutines/threads
- [ ] Map/dict access synchronized (Go maps are NOT goroutine-safe)
- [ ] Slice/list append operations synchronized when shared
- [ ] Read-write locks used where reads dominate (not exclusive mutex everywhere)

### File System Races
- [ ] Check-then-act on files uses atomic operations (temp file + rename)
- [ ] File locks used for multi-process coordination
- [ ] PID files checked with `flock` or equivalent, not just `[ -f ]`
- [ ] Directory creation uses `mkdir -p` (idempotent), not check-then-create
- [ ] Log file rotation handles concurrent writers

### Database Races
- [ ] Upsert uses `INSERT ... ON CONFLICT` (not check-then-insert)
- [ ] Counter increments use `UPDATE ... SET x = x + 1` (not read-modify-write)
- [ ] Unique constraint violations handled with retry (not just error)
- [ ] Optimistic locking uses version column for concurrent updates
- [ ] Queue consumers use `SELECT ... FOR UPDATE SKIP LOCKED`

### API / Network Races
- [ ] Idempotency keys used for non-idempotent API calls
- [ ] Retry logic uses exponential backoff (not fixed delay)
- [ ] Circuit breaker pattern for failing external services
- [ ] Request deduplication for concurrent identical requests
- [ ] Webhook handlers are idempotent (same event delivered twice = same result)

### Go-Specific
- [ ] Channel sends/receives have timeout or context cancellation
- [ ] `sync.WaitGroup` counter matches goroutine count exactly
- [ ] `defer mu.Unlock()` immediately after `mu.Lock()` (no early return gap)
- [ ] Race detector run: `go test -race ./...`
- [ ] Context propagation through goroutine chains (no orphaned goroutines)

### Python-Specific
- [ ] `threading.Lock` used for shared state (GIL doesn't protect everything)
- [ ] `asyncio` tasks properly awaited (no fire-and-forget without tracking)
- [ ] `multiprocessing` shared state uses `Manager` or `Value`/`Array`
- [ ] File I/O in async code uses `aiofiles` (not blocking `open()`)

### Testing
- [ ] Concurrent tests exist (multiple goroutines/threads hitting same code)
- [ ] Race detector enabled in CI (`go test -race`, `PYTHONFAULTHANDLER=1`)
- [ ] Stress tests for hot paths (100+ concurrent operations)
- [ ] Deterministic ordering tests (verify no output depends on scheduling)

## When to Apply

Load this checklist when:
- Code uses goroutines, threads, `asyncio`, `multiprocessing`, or `concurrent.futures`
- Multiple processes read/write the same files
- Database operations involve concurrent access patterns
- Plan mentions "parallel", "concurrent", "async", "worker pool", or "queue"
- Code uses `sync.Mutex`, `threading.Lock`, `asyncio.Lock`, or similar primitives

# Rust Standards (Tier 1)

## Required
- `cargo fmt` (automatic)
- `cargo clippy` passes (no warnings)
- All public items documented (rustdoc)

## Error Handling
- Use `Result<T, E>` for fallible operations
- Implement custom errors with `thiserror` or `anyhow`
- Never `unwrap()` in library code (OK in tests/bins)
- Use `?` operator for error propagation

## Adapter Recursion Guard
- Subprocess adapters that can invoke their own kernel must set a guard env var
  on every child command: `<TOOL>_IN_PROGRESS=1`.
- Kernel entry must reject re-entry when that env var is already present.
- This is a two-end check: set-on-spawn plus check-at-entry. One end alone is
  not enough.
- Source pattern: commit `97e16fe`, bead `mo-l1tyqp.23`, and
  `MTO_SKILL_AUDIT_IN_PROGRESS` from the Mt Olympus skill-audit adapter fix.

```rust
pub const GUARD_ENV: &str = "MY_TOOL_IN_PROGRESS";

fn command() -> std::process::Command {
    let mut cmd = std::process::Command::new("sh");
    cmd.env(GUARD_ENV, "1");
    cmd
}

fn entry() -> Result<(), MyError> {
    if std::env::var_os(GUARD_ENV).is_some() {
        return Err(MyError::Recursion);
    }
    Ok(())
}
```

## Ownership & Borrowing
- Prefer references over cloning
- Use `&str` in function params over `String`
- Add explicit lifetime annotations when needed
- Clone sparingly and document why

## Common Issues
| Pattern | Problem | Fix |
|---------|---------|-----|
| `unwrap()` | Panic on None/Err | Use `?` or pattern match |
| Mutable statics | Data races | Use `once_cell` or `Mutex` |
| String allocation | Performance | Use `&str` in function params |
| Lifetime errors | Borrow checker reject | Add explicit lifetimes |
| Unsafe block | Memory unsafety | Add `// SAFETY:` comment |
| Excessive `.clone()` | Performance waste | Use references or `Cow<T>` |

## Unsafe Code
- Always add `// SAFETY:` comment explaining invariants
- Minimize unsafe scope
- Prefer safe abstractions

## Security
- Minimize `unsafe` blocks — each needs `// SAFETY:` justification
- Use `secrecy::Secret<T>` for sensitive values (prevents accidental logging)
- Validate all external input before deserialization (`serde` validators)
- Prefer `ring` or `rustls` over OpenSSL bindings

## Documentation
- All public items must have rustdoc comments (`///`)
- Include `# Examples` section in doc comments for complex APIs
- Use `#![deny(missing_docs)]` in library crates
- Run `cargo doc --no-deps` to verify doc builds

## Testing
- `cargo test` (built-in)
- `cargo test --doc` (doc tests)
- Use `#[cfg(test)]` modules
- `cargo bench` for benchmarks

# Shell Standards (Tier 1)

## Required Header
```bash
#!/usr/bin/env bash
set -euo pipefail
```

## Validation
- `shellcheck` must pass
- Quote all variables: `"$var"` not `$var`

## Common Issues
| Pattern | Problem | Fix |
|---------|---------|-----|
| Unquoted `$var` | Word splitting | `"$var"` |
| `cd` without check | Silent failure | `cd dir \|\| exit 1` |
| `[ ]` vs `[[ ]]` | Portability | Use `[[ ]]` in bash |
| Backticks | Nesting issues | Use `$(command)` |

## Best Practices
- Use `local` for function variables
- Trap errors: `trap 'cleanup' ERR EXIT`
- Check command existence: `command -v foo >/dev/null`
- Use `readonly` for constants

## Cluster Scripts
- Always verify connectivity first:
  ```bash
  oc whoami &>/dev/null || { echo "Not logged in"; exit 1; }
  ```

# AgentOps Skill Structure

`skills/<slug>/SKILL.md` is the source of truth for one AgentOps skill. Generated
catalogs, graphs, routers, counts, and Codex projections derive from its
metadata. Do not maintain a second inventory by hand.

## Package shape

```text
skills/<slug>/
├── SKILL.md           required source contract
├── references/        optional detailed material linked from SKILL.md
├── scripts/           optional repeatable mechanics
├── schemas/           optional machine-readable outputs
├── assets/            optional reusable payloads
└── SELF-TEST.md       optional trigger or behavior examples
```

Rules:

- Use a kebab-case directory and the exact filename `SKILL.md`.
- Match the frontmatter `name` to the directory.
- Keep the kernel at or below 250 lines.
- Add references, scripts, schemas, assets, or self-tests only when the skill
  needs them; their absence is not a quality defect.
- Link every reference from `SKILL.md`. Do not leave unreferenced package files.
- Put repeated deterministic mechanics in a script; keep judgment in prose.

## Frontmatter

The repository validators own the complete schema. A typical skill declares:

```yaml
---
name: example
description: 'What it does. Triggers: "phrase a caller would use".'
practices: [design-by-contract]
hexagonal_role: supporting
consumes: [explicit-input]
produces: [factual-output]
context_rel: []
skill_api_version: 1
metadata:
  capabilities: [example]
  effects: []  # NOT a default — list every side effect; keep [] only if the skill is genuinely read-only
  canonical_status: canonical
  disposition: keep_specialist
  tier: execution
  dependencies: []
output_contract: concise description or schema path
---
```

`effects` is load-bearing, not boilerplate. Declare every side effect the skill
performs — a file it writes, a process it starts, host or credential state it
mutates, a network call it makes — as a short snake_case phrase
(`write_advisory_report`, `modify_declared_subject`, `operate_gas_city`). Leave
`effects: []` only when the skill is genuinely read-only and returns to stdout;
copying `[]` onto a skill that writes is a false contract, not a safe default.

The description states both what the skill does and when it should load. Add
an inline `Triggers:` or `Use when:` marker with phrases a caller might
actually use. Also state an important false-positive boundary in the body when
the skill could be confused with a broader workflow.

Use `dependencies` only for behavior that cannot execute without the named
skill. Advisory context belongs in prose links or `context_rel`; it is not a
hard dependency. The core hard-dependency graph is only:

```text
rpi -> plan
rpi -> implement
rpi -> validate
```

These are available core operations, not mandatory worksheets or dispatches for
every edit. RPI uses Plan on demand and requires fresh final Validate.
Anti-ceremony and Memory are optional, with no hard edge.

## Body contract

A good kernel makes five things obvious:

1. Trigger and purpose.
2. Inputs and boundaries.
3. The smallest ordered procedure.
4. Output and evidence.
5. Stop condition or unchecked scope.

Use natural language for cross-skill handoffs: “supply the result to Plan,” not
runtime-specific slash commands. A skill may describe optional adapters, but
must not silently start a runtime or assume one exists.

## Product boundary

AgentOps skills may shape intent, implement and repair authorized work, establish exact
subject identity, make one fresh independent judgment, and preserve evidence.
They do not own:

- aggregate retry controllers or attempt budgets;
- queues, claims, leases, priorities, or work selection;
- Git state, commits, pushes, merging, release, or delivery;
- lifecycle closure, next actions, or operator notification policy.

If a specialist encounters failure, it reports the factual result and stops.
The caller decides what happens next.

## Outputs

The frontmatter `output_contract` is the binding concise declaration. Add a
body `## Output` section when readers need field meanings, a path convention,
or a validator command. Small inline skills do not need a ceremonial artifact
path, schema, filename, validator, and downstream handoff.

Structured outputs should name their schema and identity rules. Factual inline
outputs should name the fields or sentence shape. Never imply PASS, readiness,
or continuation unless the skill is Validate returning a fresh semantic result.
`verdict.v2` is an optional representation for declared consumers, not the
source of Validate's authority.

The reference example of a structured-output validator is
`skills/research/scripts/pattern-mining/validate-output.sh` — a small `jq` predicate that
checks a supplied output artifact against its declared contract. Copy that shape
when a skill emits a machine-readable artifact; do not reinvent it.

## Validation

Run the canonical checks after editing a skill:

```bash
bash skills/skill-builder/scripts/heal.sh --check --strict skills/<slug>
bash skills/skill-builder/scripts/audit.sh --strict skills/<slug>
bash scripts/validate-skill-frontmatter.sh --strict
python3 scripts/generate-skill-mesh.py --check
```

When metadata or behavior changes, regenerate the declared projections and
then validate them:

```bash
bash scripts/refresh-codex-artifacts.sh --scope worktree
bash scripts/validate-codex-generated-artifacts.sh --scope worktree
```

Add a focused test when the skill contains a parser, script, schema, or other
executable behavior. For a concise judgment prompt, example fixtures may be
enough. Validation should prove the behavior that exists, not reward package
size or ceremony.

## Review checklist

- The trigger and false-positive boundary are clear.
- The procedure has one owner and a bounded stop.
- The output contract matches actual behavior.
- Links resolve and optional resources are justified.
- No deleted skill, command, schema, or control-plane concept is live.
- Metadata and all generated projections agree.

# SQL Safety Checklist

Domain-specific checklist for code that interacts with databases.

## Mandatory Checks

### Injection Prevention
- [ ] All user input is parameterized (no string interpolation in queries)
- [ ] ORM queries use parameter binding, not f-strings or `.format()`
- [ ] Raw SQL uses `?` or `$N` placeholders, never concatenation
- [ ] Dynamic table/column names are validated against an allowlist

### Migration Safety
- [ ] Migrations are reversible (both `up` and `down` defined)
- [ ] No `DROP TABLE` or `DROP COLUMN` without explicit data migration plan
- [ ] Large table migrations use batched operations (not full-table locks)
- [ ] Index creation uses `CONCURRENTLY` where supported (PostgreSQL)
- [ ] Migration tested on production-size dataset (not just empty dev DB)

### Query Performance
- [ ] Queries touching >1000 rows have appropriate indexes
- [ ] No `SELECT *` in production code (explicit column lists)
- [ ] N+1 queries identified and resolved (use `includes`/`preload`/`JOIN`)
- [ ] Pagination used for unbounded result sets
- [ ] `EXPLAIN ANALYZE` run on new queries touching large tables

### Transaction Safety
- [ ] Long-running transactions avoided (< 30s)
- [ ] Deadlock-prone operations use consistent lock ordering
- [ ] Retry logic for serialization failures / deadlocks
- [ ] Connection pool sized for peak concurrent transactions

### Data Integrity
- [ ] Foreign keys enforced at database level (not just application)
- [ ] NOT NULL constraints on required fields
- [ ] Unique constraints on business-key columns
- [ ] Check constraints on bounded values (enums, ranges)
- [ ] Soft deletes use `deleted_at` timestamp, not boolean

## When to Apply

Load this checklist when:
- Changed files contain SQL queries or ORM calls
- Migration files are in the changeset
- Database schema changes are proposed in the plan
- Code interacts with `database/sql`, `sqlx`, `gorm`, `sqlalchemy`, `activerecord`, `prisma`, `knex`, or similar

# Risk-Based Test Portfolio

Choose the smallest test surface that can disprove the behavior claim. Test
levels are tools, not mandatory ceremony: the right mix follows risk,
boundaries, and failure modes.

## Levels

| Level | Scope | Best for |
|---|---|---|
| L0 contract | schemas, registrations, imports, generated parity | structural promises and compatibility |
| L1 unit | one function or module | dense logic, edge cases, fast regression guards |
| L2 integration | collaborating modules or an I/O boundary | interface mismatches and adapter behavior |
| L3 component/E2E | a user-visible path through a subsystem | workflows and high-blast-radius behavior |
| smoke/production | a deployed critical path | environment, packaging, and rollout facts |

Higher is not automatically better. A pure parser fix may need one table-driven
unit test. A CLI command crossing config, filesystem, and formatting boundaries
may need an integration test. A deployment claim cannot be proven by a local
unit test.

## Selection questions

Start from the acceptance behavior and ask:

1. What is the narrowest observable that fails when the behavior is wrong?
2. Which boundary is most likely to hide a defect?
3. Which regression would be expensive or dangerous?
4. Can the check run quickly and deterministically during implementation?
5. What remains impossible to check in this environment?

Add test levels only when each one covers a distinct risk. Do not require L2 by
default, duplicate the same assertion at every level, or treat test count as
evidence quality.

## RPI traversal use

- **Plan** names the active behavior, edge scenario, required evidence, and
  first acceptance check.
- **Implement** records the first check failing for the right reason, makes the
  smallest change that turns it green, and refactors without changing the
  behavior.
- **Validate** examines the exact candidate, judges whether the evidence is
  sufficient for each acceptance criterion, and records checked and unchecked
  scope.

Premortem, Council, Postmortem, and test specialists are optional strategies.
They do not add lifecycle phases or authorize continuation.

## Regression design

When fixing a bug, preserve a test that:

- reproduces the observed failure before the fix;
- asserts the externally relevant result, not incidental implementation;
- includes the edge that made the defect reachable;
- fails if the old behavior returns.

Prefer realistic fixtures at the boundary under test. Mocks are useful for
specific failure injection, but a mock that reimplements the expected behavior
can make the test prove itself instead of the system.

Use property, fuzz, mutation, golden, chaos, performance, or compatibility
tests when the risk calls for them:

- property or fuzz tests for parsers and broad input spaces;
- mutation testing for critical logic whose coverage may be shallow;
- golden tests for stable generated or formatted output;
- fault injection for timeout, permission, corruption, and dependency errors;
- performance tests for a named latency or throughput contract;
- compatibility fixtures for public data or command formats.

These are targeted tools, not a required checklist for every change.

## Throughput

Keep feedback proportional to the current surface:

1. Run the first acceptance check while shaping the change.
2. Run focused package or adapter checks after the bounded implementation.
3. Run the full deterministic repository suite once on the frozen complete
   candidate.

Use one machine-readable invocation when it provides both timing and failure
details. Before repairing a newly observed failure, establish whether it is
introduced by the candidate; pre-existing failures belong in unchecked or
residual evidence unless the caller expands scope.

Parallelize read-only tests only when they do not contend for shared state.
Isolate tests that touch tmux, ports, environment variables, global config, or
the filesystem so they cannot damage a parent session.

## Evidence quality

Good test evidence records:

- exact command or artifact path;
- subject identity or changed surface;
- exit status and relevant result;
- environment assumptions that affect reproducibility;
- what the check did not cover.

Green tests are factual evidence, not a semantic verdict. Validate supplies the
independent judgment against the exact candidate.

# TypeScript Standards (Tier 1)

## Required
- `strict: true` in tsconfig.json
- `prettier` for formatting
- `eslint` with recommended rules

## Type Safety
- No `any` - use `unknown` + type guards
- No `@ts-ignore` without explanation
- Prefer `interface` for objects, `type` for unions

## Common Issues
| Pattern | Problem | Fix |
|---------|---------|-----|
| `as Type` | Unsafe cast | Type guards or `satisfies` |
| `!` (non-null) | Runtime errors | Proper null checks |
| `== null` | Loose equality | `=== null \|\| === undefined` |
| Implicit `any` | Type safety loss | Enable `noImplicitAny` |

## React (if applicable)
- Functional components only
- `useState` / `useReducer` for state
- `useEffect` with proper deps array
- No inline object/function props (memo issues)

## Testing
- Jest or Vitest
- React Testing Library for components
- MSW for API mocking

# YAML Standards (Tier 1)

## Validation
- `yamllint` must pass
- 2-space indentation
- No trailing whitespace

## Common Issues
| Pattern | Problem | Fix |
|---------|---------|-----|
| Tabs | Invalid YAML | 2 spaces |
| `yes`/`no` unquoted | Becomes boolean | Quote: `"yes"` |
| `:` in value | Parse error | Quote the value |
| Long lines | Readability | Use `>` or `\|` |

## Kubernetes/Helm
- Use `---` between documents
- Labels: `app.kubernetes.io/*`
- Always specify `resources.limits`
- Use ConfigMaps for config, Secrets for secrets

## Security
- Never use `yaml.load()` (Python) — always `yaml.safe_load()`
- Quote values that look like booleans (`"yes"`, `"no"`, `"true"`)
- Validate against schema before processing untrusted YAML
- Avoid anchors/aliases (`*`/`&`) in user-facing configs — confusing and exploitable

## Multiline Strings
```yaml
# Literal (preserves newlines)
description: |
  Line 1
  Line 2

# Folded (joins lines)
description: >
  This becomes
  one line
```