@ryuenn3123/agentic-senior-core 1.8.0

package/.agent-context/review-checklists/architecture-review.md

@@ -0,0 +1,70 @@
+# Architecture Review Checklist
+
+> Run this when reviewing module structure, new feature design, or refactoring.
+> Bad architecture is invisible until it becomes unmaintainable.
+
+## Instructions for Agent
+
+Evaluate every item against the current project structure. For each violation, explain:
+1. What layer or boundary is broken
+2. Why it leads to maintenance or scalability problems
+3. The correct architectural pattern to apply
+
+---
+
+## Layer Separation
+
+- [ ] **Controllers/Handlers contain NO business logic** — Only parsing input, calling service, formatting response
+- [ ] **Services contain NO HTTP concepts** — No `Request`, `Response`, `HttpStatus` imports
+- [ ] **Services contain NO raw SQL or direct DB access** — Use repository/DAO layer
+- [ ] **Repositories contain NO business rules** — Only CRUD and query operations
+- [ ] **Domain entities have NO framework dependencies** — Pure language types only
+- [ ] **Dependencies flow inward** — Transport → Service → Repository → Domain (never reverse)
+
+## Module Boundaries
+
+- [ ] **Modules don't import from each other's internal files** — Only public exports
+- [ ] **No circular dependencies between modules** — A → B → A is forbidden
+- [ ] **Each module has a clear single responsibility** — Not a "kitchen sink" module
+- [ ] **Shared code is genuinely shared** — Not domain-specific code disguised as "common"
+- [ ] **Module size is reasonable** — If a module has 20+ files, consider splitting
+
+## Dependency Management
+
+- [ ] **No God classes** — No class/file with 500+ lines or 10+ dependencies
+- [ ] **Constructor injection only** — No service locator, no field injection, no global state
+- [ ] **Interfaces defined where consumed** — Not in the implementation module
+- [ ] **External services abstracted behind interfaces** — Swappable, testable
+- [ ] **Configuration injected, not hardcoded** — No magic strings for URLs, ports, keys
+
+## Data Flow
+
+- [ ] **DTOs at boundaries** — Internal models don't leak to external interfaces
+- [ ] **Validation at entry points** — Zod / Pydantic / Bean Validation at transport layer
+- [ ] **No raw request objects passed deep** — Transform to domain types ASAP
+- [ ] **Response transformation explicit** — Dedicated serializers / resources / mappers
+- [ ] **Sensitive data excluded from responses** — Passwords, tokens, internal IDs
+
+## Database Design
+
+- [ ] **Migrations are incremental** — No destructive changes without migration plan
+- [ ] **Foreign keys for data integrity** — Relations enforced at DB level
+- [ ] **Indexes for query patterns** — Not just primary keys
+- [ ] **No business logic in DB** — Triggers and stored procs used sparingly
+- [ ] **Soft delete considered** — For audit-sensitive entities
+
+## Error Architecture
+
+- [ ] **Error hierarchy defined** — Base error class with domain-specific subtypes
+- [ ] **Global error handler exists** — Catches unhandled errors, returns safe responses
+- [ ] **Error codes are typed** — Enum or const, not arbitrary strings
+- [ ] **Client errors vs server errors distinguished** — 4xx vs 5xx with different handling
+- [ ] **Errors don't leak internals** — No stack traces, SQL errors, or file paths to client
+
+## Scalability Readiness
+
+- [ ] **Stateless services** — No in-memory session or request state across requests
+- [ ] **Background jobs for heavy work** — Long operations don't block HTTP responses
+- [ ] **Idempotent endpoints where needed** — POST with idempotency keys for payment/creation
+- [ ] **Feature flags for gradual rollout** — New features can be toggled without deploy
+- [ ] **Health check endpoint exists** — `/health` returning service status

package/.agent-context/review-checklists/frontend-usability.md

@@ -0,0 +1,33 @@
+# Frontend Usability Checklist — V1.7 Gate
+
+Run this checklist before claiming frontend work is production-ready.
+
+## 1. Visual System
+- [ ] Typography scale is consistent and tokenized.
+- [ ] Color usage follows design tokens and avoids ad-hoc values.
+- [ ] Spacing and layout rhythm is coherent across pages.
+
+## 2. Responsiveness
+- [ ] Core pages are usable at mobile, tablet, and desktop breakpoints.
+- [ ] Navigation remains accessible and understandable on small screens.
+- [ ] No content overlap, clipped text, or horizontal scroll regressions.
+
+## 3. Accessibility
+- [ ] Keyboard-only navigation covers all critical user paths.
+- [ ] Primary text and actionable controls meet WCAG AA contrast.
+- [ ] Reduced-motion mode is respected for non-essential animations.
+
+## 4. Interaction Quality
+- [ ] Motion is meaningful, not decorative noise.
+- [ ] Loading, empty, and error states are explicitly designed.
+- [ ] CTA hierarchy is clear and supports user intent.
+
+## 5. Performance and Stability
+- [ ] Lighthouse mobile performance target is met on core pages.
+- [ ] No severe layout shift during load and transition.
+- [ ] Visual regression checks cover protected pages.
+
+## 6. Documentation and Release Evidence
+- [ ] Frontend architecture decision is documented.
+- [ ] Visual baseline update process is documented.
+- [ ] Release note includes usability and responsiveness evidence.

package/.agent-context/review-checklists/performance-audit.md

@@ -0,0 +1,65 @@
+# Performance Audit Checklist
+
+> Run this on any code path that handles data, queries, or network requests.
+> Performance problems are architectural — they don't fix themselves.
+
+## Instructions for Agent
+
+Evaluate every item below. For each finding, rate impact:
+- **CRITICAL** — Will cause outage or severe degradation under normal load
+- **HIGH** — Will degrade at scale, fix before production traffic
+- **MEDIUM** — Wasted resources, fix in this sprint
+- **LOW** — Optimization opportunity, track for later
+
+---
+
+## Database & Queries
+
+- [ ] **No N+1 queries** — No database queries inside loops. Use eager loading or joins.
+- [ ] **No unbounded queries** — Every list query has LIMIT / pagination
+- [ ] **No `SELECT *`** — Only select columns that are actually needed
+- [ ] **Indexes exist for frequently queried columns** — WHERE, JOIN, ORDER BY columns
+- [ ] **Composite indexes match query patterns** — Column order matters
+- [ ] **No unnecessary COUNT(*)** — Use EXISTS for existence checks
+- [ ] **Bulk operations used** — insertAll/updateAll instead of loops for batch work
+- [ ] **Connection pool configured** — Not creating new connections per request
+- [ ] **Query execution time logged** — Slow query detection enabled (> 200ms threshold)
+
+## I/O & Network
+
+- [ ] **No synchronous I/O in async context** — No blocking calls in event-loop code
+- [ ] **HTTP requests have timeouts** — Connect (5s) and read (30s) timeouts configured
+- [ ] **Parallel requests when independent** — Use Promise.all / asyncio.gather
+- [ ] **Retry with backoff** — Network calls retry with exponential backoff + jitter
+- [ ] **Response streaming for large data** — Don't buffer entire response in memory
+- [ ] **File uploads size-limited** — Max upload size configured at server level
+
+## Caching
+
+- [ ] **Cache has invalidation strategy** — If cache exists, invalidation is documented
+- [ ] **TTL is reasonable** — Not too long (stale data), not too short (no benefit)
+- [ ] **Cache stampede prevented** — Locking or staggered TTL for popular keys
+- [ ] **Cache key includes relevant context** — User ID, locale, version where needed
+- [ ] **No caching of user-specific data in shared cache** — Privacy and correctness
+
+## Memory
+
+- [ ] **No unbounded in-memory collections** — Arrays/lists don't grow without limit
+- [ ] **Streaming for large datasets** — Cursor/stream instead of loading all into memory
+- [ ] **No memory leaks** — Event listeners cleaned up, intervals cleared, no circular refs
+- [ ] **Resource cleanup** — File handles, DB connections, HTTP clients properly closed
+
+## Frontend Performance (If Applicable)
+
+- [ ] **No unnecessary re-renders** — Memoization where component receives same props
+- [ ] **Images optimized** — Proper format (WebP), lazy loading, responsive sizes
+- [ ] **Bundle size checked** — No 500KB library for a 5-function use case
+- [ ] **API calls deduplicated** — Same data not fetched multiple times in same render
+- [ ] **Pagination/virtualization for long lists** — Not rendering 10,000 DOM nodes
+
+## General
+
+- [ ] **No premature optimization** — Changes based on evidence, not assumptions
+- [ ] **Hot paths identified** — Critical user-facing paths are optimized first
+- [ ] **Compression enabled** — gzip/brotli for HTTP responses
+- [ ] **Rate limiting configured** — API endpoints have request limits

package/.agent-context/review-checklists/pr-checklist.md

@@ -0,0 +1,97 @@
+# PR Checklist — The Quality Gate
+
+> Run this before declaring any task "done."
+> If ANY item fails, the task is NOT complete.
+
+## Instructions for Agent
+
+When asked to review code using this checklist, evaluate EVERY item below.
+For each failed item, provide a Reasoning Chain (see `.cursorrules` → Reasoning Clause).
+Output format:
+
+```
+## PR REVIEW RESULTS
+━━━━━━━━━━━━━━━━━━━
+
+✅ [Item] — Passes
+❌ [Item] — FAILS
+   📌 Rule: [rule file + section]
+   ❌ Problem: [specific issue found]
+   ✅ Fix: [what to change]
+
+VERDICT: PASS ✅ / FAIL ❌ (X/Y items passed)
+```
+
+---
+
+## The Checklist
+
+### 1. Naming (→ rules/naming-conv.md)
+- [ ] All variables are descriptive nouns (no `data`, `temp`, `val`, `x`)
+- [ ] All functions start with a verb (no `userData()`, `orderLogic()`)
+- [ ] All booleans use `is/has/can/should` prefix
+- [ ] Constants use SCREAMING_SNAKE_CASE with unit suffix
+- [ ] No single-letter variables (except `i` in classic for-loops)
+- [ ] File names follow the project's chosen convention consistently
+
+### 2. Architecture (→ rules/architecture.md)
+- [ ] No layer leaks (controllers don't query DB, services don't return HTTP responses)
+- [ ] Feature-based file organization (not technical grouping)
+- [ ] Dependencies flow inward (transport → service → repository)
+- [ ] Module boundaries respected (no reaching into another module's internals)
+- [ ] Domain layer has zero external dependencies
+
+### 3. Type Safety (→ stacks/typescript.md)
+- [ ] No `any` type anywhere (use `unknown` + narrowing)
+- [ ] No `// @ts-ignore` (use `@ts-expect-error` with justification comment)
+- [ ] All function return types are explicit
+- [ ] Zod schemas validate ALL external input at boundaries
+- [ ] Types derived from Zod schemas (single source of truth)
+
+### 4. Error Handling (→ rules/error-handling.md)
+- [ ] No empty catch blocks
+- [ ] No `catch(e) { console.log(e) }` without re-throw or recovery
+- [ ] Typed error classes used (not generic `new Error('...')`)
+- [ ] Error responses don't leak internal details to clients
+- [ ] Structured logging with context (traceId, userId, action)
+
+### 5. Security (→ rules/security.md)
+- [ ] All user input validated at boundaries (Zod/schema)
+- [ ] No SQL/command string concatenation with user input
+- [ ] No secrets hardcoded in source code
+- [ ] Auth checked server-side (not client-side only)
+- [ ] Error messages don't reveal internal system details
+- [ ] CORS configured (not `*` in production)
+
+### 6. Performance (→ rules/performance.md)
+- [ ] No N+1 queries (no queries inside loops)
+- [ ] All list queries have LIMIT/pagination
+- [ ] No `SELECT *` (only needed columns)
+- [ ] No synchronous I/O in async context
+- [ ] Cache has documented invalidation strategy (if caching used)
+
+### 7. Testing (→ rules/testing.md)
+- [ ] Business logic has unit tests
+- [ ] Test names follow `should [behavior] when [condition]`
+- [ ] Tests follow AAA pattern (Arrange → Act → Assert)
+- [ ] No implementation detail testing (test behavior, not structure)
+- [ ] Test data uses factories (no copy-pasted objects)
+
+### 8. Dependencies (→ rules/efficiency-vs-hype.md)
+- [ ] No new dependencies added without justification
+- [ ] No dependency that replaces < 20 lines of code
+- [ ] New packages checked for maintenance health
+- [ ] Bundle impact considered (frontend)
+
+### 9. Git (→ rules/git-workflow.md)
+- [ ] Commit messages follow Conventional Commits
+- [ ] No `console.log` debugging statements
+- [ ] No `// TODO` without a linked issue
+- [ ] No commented-out code blocks
+- [ ] `.env` not committed
+
+### 10. Documentation
+- [ ] API endpoints have OpenAPI/Swagger documentation
+- [ ] Complex business logic has comments explaining WHY
+- [ ] Public functions/methods have JSDoc/docstrings
+- [ ] README updated if new setup steps required

package/.agent-context/review-checklists/release-operations.md

@@ -0,0 +1,29 @@
+# Release Operations Checklist (V1.8)
+
+Use this checklist before promoting any release tag or package publish operation.
+
+## 1) Versioning and Changelog Integrity
+- `package.json` version is valid semantic version (`x.y.z`).
+- `CHANGELOG.md` has a matching release header for the package version.
+- `docs/roadmap.md` reflects release status and scope for the current milestone.
+
+## 2) Quality Gates and Test Evidence
+- `npm run validate` passes with zero failures.
+- `npm run test` passes on the full suite.
+- Frontend governance gate (`npm run audit:frontend-usability`) passes.
+- Release governance gate (`npm run gate:release`) passes.
+
+## 3) Supply Chain and Compliance Evidence
+- SBOM is generated with `npm run sbom:generate`.
+- CI uploads SBOM artifact for retention and audit traceability.
+- CI uploads release-gate report artifact for each run.
+
+## 4) Security and Override Governance
+- `.agent-override.md` entries have valid `Owner` and `Expiry` metadata.
+- No expired overrides remain active.
+- Any temporary exception has explicit rollback owner and date.
+
+## 5) Publish Readiness
+- Release notes summarize scope, risks, and rollback steps.
+- Required GitHub workflows are green on target commit.
+- Tag and publish command are executed only after all checks pass.

package/.agent-context/review-checklists/security-audit.md

@@ -0,0 +1,113 @@
+# Security Audit Checklist — OWASP-Aligned
+
+> Run this on any code that handles authentication, authorization,
+> user input, or external data. When in doubt, run it anyway.
+
+## Instructions for Agent
+
+Evaluate every item below against the current code. For each finding, rate severity:
+- 🔴 **CRITICAL** — Exploitable now, must fix before deploy
+- 🟠 **HIGH** — Likely exploitable, fix in this PR
+- 🟡 **MEDIUM** — Potential risk, fix before production
+- 🟢 **LOW** — Minor, fix when convenient
+
+Output format:
+```
+## SECURITY AUDIT RESULTS
+━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🔴 CRITICAL: [finding title]
+   Location: [file:line]
+   Risk: [what an attacker could do]
+   Fix: [specific remediation]
+
+VERDICT: X findings (🔴 N critical, 🟠 N high, 🟡 N medium, 🟢 N low)
+```
+
+---
+
+## A1: Injection (SQL, NoSQL, OS, LDAP)
+
+- [ ] No string concatenation in SQL queries → use parameterized queries
+- [ ] No string interpolation in OS commands → use argument arrays
+- [ ] No raw user input in regex → escape or use validated patterns
+- [ ] ORM/query builder used correctly (no raw queries with user input)
+- [ ] No `eval()`, `new Function()`, or `exec()` with user-controlled input
+
+## A2: Broken Authentication
+
+- [ ] Passwords hashed with bcrypt (cost ≥ 12) or argon2
+- [ ] No MD5, SHA1, or SHA256 for password hashing
+- [ ] Rate limiting on login endpoints (max 5 per minute per IP)
+- [ ] Session tokens are cryptographically random (≥ 256 bits)
+- [ ] JWT tokens have reasonable expiration (≤ 15 min for access, ≤ 7 days refresh)
+- [ ] Refresh token rotation implemented (invalidate old token on use)
+- [ ] Password reset tokens are single-use and time-limited (≤ 1 hour)
+
+## A3: Sensitive Data Exposure
+
+- [ ] No secrets in source code (API keys, passwords, tokens)
+- [ ] No secrets in git history (check with `git log -p | grep -i secret`)
+- [ ] Sensitive fields excluded from API responses (password, tokens, internal IDs)
+- [ ] Sensitive fields excluded from logs (passwords, tokens, PII)
+- [ ] HTTPS enforced (HSTS header present)
+- [ ] Sensitive cookies have `Secure`, `HttpOnly`, `SameSite` flags
+
+## A4: Broken Access Control
+
+- [ ] Authorization enforced server-side (not just client-side UI hiding)
+- [ ] Resource ownership verified (user can only access their own data)
+- [ ] Default deny — if no rule grants access, deny
+- [ ] Admin endpoints require admin role verification
+- [ ] No direct object reference without access check (IDOR prevention)
+- [ ] CORS configured with specific origins (not `*`)
+- [ ] File upload paths don't allow directory traversal
+
+## A5: Security Misconfiguration
+
+- [ ] Debug mode disabled in production (no stack traces to client)
+- [ ] Default credentials changed
+- [ ] Unnecessary features/endpoints disabled
+- [ ] Security headers present:
+  - `Strict-Transport-Security`
+  - `Content-Security-Policy`
+  - `X-Content-Type-Options: nosniff`
+  - `X-Frame-Options: DENY`
+  - `Referrer-Policy`
+- [ ] Error responses don't reveal framework/version info
+
+## A6: XSS (Cross-Site Scripting)
+
+- [ ] No `innerHTML`, `dangerouslySetInnerHTML`, or `v-html` with user data
+- [ ] Output encoding applied when rendering user input
+- [ ] Content-Security-Policy header restricts inline scripts
+- [ ] URL parameters validated before rendering
+
+## A7: Insecure Dependencies
+
+- [ ] No known vulnerabilities in dependencies (`npm audit` clean)
+- [ ] Dependencies are actively maintained (check pulse)
+- [ ] Lock files committed and up-to-date
+- [ ] No unnecessary dependencies (check efficiency-vs-hype.md)
+
+## A8: Logging & Monitoring
+
+- [ ] Authentication failures logged with IP and timestamp
+- [ ] Authorization failures logged with userId and resource
+- [ ] Critical operations logged (data deletion, role changes, exports)
+- [ ] Logs do NOT contain passwords, tokens, or full credit card numbers
+- [ ] Log injection prevented (sanitize user input before logging)
+
+## A9: Rate Limiting
+
+- [ ] Auth endpoints rate-limited
+- [ ] API endpoints have reasonable rate limits
+- [ ] File upload size limits configured
+- [ ] Pagination limits enforced (prevent requesting 1M records)
+
+## A10: Mass Assignment
+
+- [ ] Input DTOs explicitly whitelist allowed fields
+- [ ] No `Object.assign(entity, req.body)` without field filtering
+- [ ] Admin-only fields (role, permissions) can't be set by regular users
+- [ ] Database updates use explicit field sets, not spread operators on raw input

package/.agent-context/rules/api-docs.md

@@ -0,0 +1,186 @@
+# API Documentation — The "Invisible API" Rule
+
+> An undocumented API is an unusable API.
+> If it's not in the spec, it doesn't exist.
+
+## The Zero-Doc Death Penalty
+
+Every API endpoint MUST have machine-readable documentation that covers:
+1. HTTP method + path
+2. Request body schema with field descriptions and examples
+3. All response codes with typed schemas
+4. Authentication requirements
+5. Rate limiting (if applicable)
+
+```
+BANNED: An endpoint without a defined Request/Response schema.
+BANNED: Using generic `object` or `any` in documentation types.
+BANNED: "See code for details" as documentation.
+BANNED: Swagger UI with auto-generated summaries only (no descriptions, no examples).
+
+REQUIRED: Every field MUST have a `description` and an `example` value.
+REQUIRED: Every error response MUST be documented (400, 401, 403, 404, 409, 500).
+REQUIRED: Documentation MUST be updated in the SAME commit as the endpoint change.
+```
+
+---
+
+## Documentation Format: OpenAPI 3.1 (Non-Negotiable)
+
+All APIs produce an OpenAPI 3.1 specification. Not 3.0, not proprietary formats, not "we'll add Swagger later."
+
+### Why OpenAPI
+- Machine-readable: clients, tests, and mocks can be generated from the spec
+- Full JSON Schema Draft 2020-12 compatibility (3.1+ only)
+- Vendor-neutral: works with Scalar, Swagger UI, Redoc, Postman, Stoplight
+- Version-controllable: the spec is a file you can diff and review
+
+---
+
+## Tooling by Framework
+
+### NestJS
+Use `@nestjs/swagger` with Scalar UI (not default Swagger UI — Scalar is faster and more readable).
+
+```typescript
+// main.ts — Setup
+import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
+import { apiReference } from '@scalar/nestjs-api-reference';
+
+const config = new DocumentBuilder()
+  .setTitle('Service Name')
+  .setDescription('Brief service purpose')
+  .setVersion('1.0')
+  .addBearerAuth()
+  .build();
+
+const document = SwaggerModule.createDocument(app, config);
+
+// Scalar UI at /docs
+app.use('/docs', apiReference({ spec: { content: document } }));
+
+// Raw spec at /api-json
+SwaggerModule.setup('api', app, document);
+```
+
+Every controller method requires these decorators at minimum:
+```typescript
+@ApiOperation({ summary: 'Create a user account' })
+@ApiBody({ type: CreateUserDto, description: 'User registration data' })
+@ApiResponse({ status: 201, type: UserResponseDto, description: 'User created successfully' })
+@ApiResponse({ status: 400, description: 'Validation error — invalid input fields' })
+@ApiResponse({ status: 409, description: 'Conflict — email already registered' })
+@Post()
+```
+
+Every DTO property requires `@ApiProperty`:
+```typescript
+export class CreateUserDto {
+  @ApiProperty({
+    description: 'User email address, must be unique across the system',
+    example: 'jane.doe@example.com',
+  })
+  email: string;
+
+  @ApiProperty({
+    description: 'Display name shown in the UI',
+    example: 'Jane Doe',
+    minLength: 1,
+    maxLength: 100,
+  })
+  name: string;
+}
+```
+
+### Next.js (App Router)
+Use `zod-to-openapi` or `next-swagger-doc` to generate OpenAPI from Zod schemas.
+
+```typescript
+import { extendZodWithOpenApi } from '@asteasolutions/zod-to-openapi';
+import { z } from 'zod';
+
+extendZodWithOpenApi(z);
+
+export const CreateUserSchema = z.object({
+  email: z.string().email().openapi({
+    description: 'User email address, must be unique',
+    example: 'jane.doe@example.com',
+  }),
+  name: z.string().min(1).max(100).openapi({
+    description: 'Display name shown in the UI',
+    example: 'Jane Doe',
+  }),
+}).openapi('CreateUserRequest');
+```
+
+Expose the spec at `/api/docs` or `/api/openapi.json`.
+
+### Other Frameworks (Express, Fastify, Hono)
+Use `swagger-jsdoc` + TSDoc comments, or `@asteasolutions/zod-to-openapi`.
+The output MUST be a valid OpenAPI 3.1 JSON/YAML file served at a known endpoint.
+
+---
+
+## Response Documentation Standard
+
+Every endpoint MUST document these response scenarios:
+
+| Status | When | Schema Required |
+|--------|------|----------------|
+| `200` | Successful retrieval or update | Yes — typed response body |
+| `201` | Successful creation | Yes — the created resource |
+| `204` | Successful deletion | No body |
+| `400` | Validation error | Yes — field-level error details |
+| `401` | Missing or invalid authentication | Fixed message, no details |
+| `403` | Authenticated but insufficient permissions | Fixed message |
+| `404` | Resource not found | Fixed message |
+| `409` | Conflict (duplicate resource) | Description of conflict |
+| `429` | Rate limit exceeded | Retry-After header |
+| `500` | Internal error | `{ traceId }` only — NO stack traces |
+
+### Error Response Schema (Standardized)
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "One or more fields are invalid",
+    "details": [
+      { "field": "email", "message": "Invalid email format" }
+    ],
+    "traceId": "req-abc-123"
+  }
+}
+```
+
+This schema MUST be documented in OpenAPI as a reusable component (`#/components/schemas/ErrorResponse`).
+
+---
+
+## Documentation Sync Rule
+
+```
+Endpoint changed + docs NOT updated = PR REJECTED.
+
+The spec is a contract. If the contract is wrong, consumers will break.
+"I'll update the docs later" means "the docs will never be updated."
+```
+
+### Enforcement
+1. API docs live next to the code (same module, same directory)
+2. Docs update in the SAME commit as the endpoint change
+3. CI can validate the spec: `openapi-generator validate -i openapi.json`
+4. Generated clients (if any) must be regenerated after spec changes
+
+---
+
+## The Documentation Quality Test
+
+Open your API docs URL (`/docs`). For a randomly chosen endpoint, verify:
+
+1. Can a developer who has never seen the codebase call this endpoint correctly? (Must be YES)
+2. Are all required fields clearly marked? (Must be YES)
+3. Does every field have a realistic example value? (Must be YES)
+4. Are all error responses documented with their conditions? (Must be YES)
+5. Can you copy the example request and it works? (Must be YES)
+
+If any answer is "no", the documentation is incomplete.