@ryuenn3123/agentic-senior-core 3.0.17 → 3.0.20

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

@@ -1,76 +1,45 @@
 # Architecture Review Checklist
 
-> Run this when reviewing module structure, new feature design, or refactoring.
-> Bad architecture is invisible until it becomes unmaintainable.
+Use this when module structure, feature shape, public contracts, topology, or refactoring are in scope.
 
-## Instructions for Agent
+## Boundary Review
 
-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
+- [ ] The changed code has clear transport, application, domain, and infrastructure boundaries where those layers exist.
+- [ ] Business policy is not hidden in transport handlers, UI adapters, database queries, framework glue, or generated code.
+- [ ] Internal models do not leak across public API, event, CLI, library, or UI contracts without a deliberate mapping.
+- [ ] Modules import through public entrypoints instead of deep internal paths.
+- [ ] Circular dependencies are absent or explicitly removed.
 
----
-
-## 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
+## Structure Review
 
 ## Backend Universal Principles
 
-- [ ] **No clever hacks in backend and shared core modules** — Prefer explicit flow over language tricks that hide intent
-- [ ] **No premature abstraction** — Introduce shared abstractions only after repeated, stable patterns emerge
-- [ ] **Readability over brevity** — Prefer clear multi-line logic over compressed one-liners
-
-## 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
+- [ ] No clever hacks in backend and shared core modules
+- [ ] No premature abstraction (base classes/util layers created only after repeated stable patterns)
+- [ ] Readability over brevity for maintainability
+- [ ] The project structure follows existing repo conventions unless a change was approved.
+- [ ] New structure is feature/domain-oriented when that improves discoverability.
+- [ ] Large files or modules are split around real responsibilities, not arbitrary layers.
+- [ ] Shared code is genuinely shared and not domain-specific behavior disguised as utility.
+- [ ] Names describe product meaning, not generic plumbing.
 
-## Database Design
+## Topology Review
 
-- [ ] **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
+- [ ] Monolith remains acceptable when boundaries, team size, consistency needs, and operations favor one deployable.
+- [ ] Service extraction is backed by current evidence: ownership, scaling, compliance, fault isolation, or deploy cadence.
+- [ ] Service boundaries define ownership, contract, data boundary, observability, timeouts, retry, and recovery behavior.
+- [ ] Event or realtime architecture is justified by product need, not trend pressure.
 
-## Error Architecture
+## Contract Review
 
-- [ ] **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
+- [ ] API, event, CLI, library, data, and UI contracts are documented before or alongside implementation.
+- [ ] Schema and validation strategy matches the project’s chosen runtime and official docs.
+- [ ] Error contracts are safe, stable, and do not leak internals.
+- [ ] Migration and rollback plans exist for risky data or public contract changes.
 
-## Scalability Readiness
+## Operational Review
 
-- [ ] **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
+- [ ] Critical flows have tests at the right level.
+- [ ] Observability, logging, and health checks match the project’s runtime and risk level.
+- [ ] Security assumptions are documented and enforced at trust boundaries.
+- [ ] Performance-sensitive paths avoid avoidable repeated work, unbounded lists, and hidden blocking operations.

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

@@ -1,138 +1,104 @@
-# PR Checklist — The Quality Gate
+# PR Checklist - Quality Gate
 
-> Run this before declaring any task "done."
-> If ANY item fails, the task is NOT complete.
+Run this before declaring a task done. Apply only the sections relevant to the changed scope, but do not skip correctness, security, testing, or docs checks when the change touches them.
 
-## Instructions for Agent
+## 1. Repo Context
 
-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:
+- [ ] The agent read `AGENTS.md` and the smallest relevant rule set.
+- [ ] Existing project context came from real files, docs, package metadata, and changed code, not folder name alone.
+- [ ] Runtime, framework, library, topology, and design choices are explicit user constraints or agent recommendations from current evidence.
+- [ ] No offline default stack, blueprint, vendor, or visual style was treated as authoritative.
 
-```
-## PR REVIEW RESULTS
-━━━━━━━━━━━━━━━━━━━
+## 2. Correctness
 
-PASS [Item]
-FAIL [Item]
-   Rule: [rule file + section]
-   Problem: [specific issue found]
-   Fix: [what to change]
+- [ ] The changed behavior matches the user request.
+- [ ] Existing behavior is preserved unless the user approved a behavior change.
+- [ ] Edge cases, empty states, error paths, and rollback/recovery paths are handled.
+- [ ] Public contracts remain stable or are versioned and documented.
 
-VERDICT: PASS / FAIL (X/Y items passed)
-```
+## 3. Architecture
 
----
+### 2. Architecture (→ rules/architecture.md)
 
-## The Checklist
+- [ ] Layer and module boundaries are clear for the project’s chosen structure.
+- [ ] No clever hacks in backend and shared core modules
+- [ ] No premature abstraction (base classes/util layers created only after repeated stable patterns)
+- [ ] Readability over brevity for maintainability
+- [ ] Code is grouped by feature/domain where that improves maintainability.
+- [ ] Cross-module access uses public contracts instead of internal file reach-through.
+- [ ] Files above roughly 1000 lines were split or explicitly justified.
+- [ ] Monolith/service split decisions are evidence-backed, not fashion-driven.
 
-### 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
+## 4. Security And Privacy
 
-### 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
-- [ ] No clever hacks in backend and shared core modules (prefer explicit control flow)
-- [ ] No premature abstraction (base classes/util layers created only after repeated stable patterns)
-- [ ] Readability over brevity for maintainability (no compressed one-liners that hide intent)
-
-### 3. Type Safety (→ dynamic TypeScript stack guidance)
-- [ ] 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
+- [ ] External input is validated at trust boundaries using the project’s chosen validation approach.
+- [ ] Secrets, tokens, credentials, and private data are not committed or logged.
+- [ ] Authorization is enforced at a trusted boundary.
+- [ ] Error responses and logs do not leak internals.
+- [ ] Dependency or platform security claims are based on current official docs or repo evidence.
+
+## 5. Testing
+
+- [ ] Changed behavior has appropriate tests at the smallest useful level.
+- [ ] Tests assert behavior and contracts, not implementation trivia.
+- [ ] Critical flows include failure-path coverage.
+- [ ] Test fixtures are readable and do not hide the behavior under test.
+
+## 6. Docs And Contracts
 
 ### 10. Documentation
+
 - [ ] Scope applied: This applies to documentation, release notes, onboarding text, review summaries, and agent-facing explanations
 - [ ] Style scope review is advisory and does not block merge when API docs are synced in the same commit and contract details are correct
+- [ ] Required docs exist before implementation: project brief, architecture decision, flow overview, API/public contract when relevant, data model when relevant, and UI design contract when relevant.
+- [ ] Docs cover feature plan, architecture rationale, public contracts, data model, UI/design, security assumptions, testing strategy, delivery flow, and next validation actions where relevant.
+- [ ] API, event, CLI, library, data, and UI contract changes update docs in the same scope.
 - [ ] Public surface changes fail review if documentation updates are missing or stale in the same scope
-- [ ] API endpoint/contract changes include synchronized API/OpenAPI documentation updates
-- [ ] Database structure changes include synchronized schema or migration documentation updates
 - [ ] Documentation checks stay boundary-aware and only enforce touched scopes
-- [ ] 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
+- [ ] Facts, assumptions, and next actions are separated when context is incomplete.
 - [ ] No emoji in formal documentation or review summaries
 - [ ] Documentation uses plain English and avoids AI cliches
-- [ ] Performance/quality claims include source and timestamp
-- [ ] Acronyms are expanded on first use
-- [ ] Facts and assumptions are explicitly separated
+
+## 7. UI And Accessibility
+
+- [ ] UI work follows `docs/DESIGN.md` and `docs/design-intent.json`.
+- [ ] Visual direction is project-specific and not a template/default component-kit habit.
+- [ ] Responsive behavior recomposes content and priority, not only shrinking desktop layout.
+- [ ] Accessibility hard requirements are preserved: keyboard access, focus visibility, contrast, target size, status feedback, and no color-only meaning.
+- [ ] Motion is purposeful, reduced-motion-safe, and justified by product value.
+
+## 8. Dependencies And Runtime
+
+- [ ] New dependencies are justified by capability, maintenance health, bundle/runtime cost, and current official docs.
+- [ ] Official setup flows are preferred when they produce better-supported current defaults.
+- [ ] Docker, framework, package, and ecosystem claims were checked live when they could be stale.
+- [ ] Token optimization and memory continuity defaults remain enabled unless the user explicitly opts out.
+
+## 9. State And Governance
 
 ### 11. Context-Triggered Audit Mode
+
 - [ ] Strict audit mode activates automatically on review and PR-intent workflows
 - [ ] Small edits avoid heavy checks by default unless strict mode is explicitly requested
 - [ ] User can always force strict audit mode manually
-
-### 12. Rules as Guardian (Cross-Session Consistency)
-- [ ] Session handoff includes active architecture contract summary
-- [ ] Drift detection warns before direction changes
-- [ ] Direction changes require explicit user confirmation
-
-### 13. Invisible State Management (Explain-on-Demand)
-- [ ] Default responses avoid unnecessary state-file internals
-- [ ] State internals are exposed only on explicit request
-- [ ] Diagnostic mode can explain relevant state decisions when needed
-
-### 14. Single Source and Lazy Rule Loading
+- [ ] Session handoff includes active architecture contract summary.
+- [ ] Drift detection warns before direction changes.
+- [ ] Direction changes require explicit user confirmation.
+- [ ] Default responses avoid unnecessary state-file internals.
+- [ ] State internals are exposed only on explicit request.
+- [ ] Diagnostic mode can explain relevant state decisions when needed.
 - [ ] Canonical rule source is explicitly defined and enforced
 - [ ] Language-specific guidance is loaded lazily based on detected scope
 - [ ] No conflicting duplicate rule instructions during normal flow
+- [ ] Canonical rule source is explicit and duplicate/conflicting instructions are avoided.
 
 ### 15. Universal SOP Consolidation
-- [ ] `.agent-context/rules/` remains the default guidance source for implementation and review
-- [ ] Backend and frontend mindset checks are both applied when scope spans API and UI boundaries
-- [ ] Security and testing requirements remain mandatory after static template purge
+
+- [ ] `.agent-context/rules/` remains the default guidance source for implementation and review.
+- [ ] Security and testing requirements remain mandatory after static template purge.
 - [ ] Coding flow is blocked if `docs/architecture-decision-record.md` (or `docs/Architecture-Decision-Record.md`) is missing
 - [ ] UI implementation flow is blocked if `docs/DESIGN.md` or `docs/design-intent.json` is missing
+
+## Verdict
+
+Report findings first, ordered by severity, with file/line references and concrete fixes. If no findings exist, say that explicitly and name any residual risk.

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

@@ -1,29 +1,19 @@
-# API Documentation — The "Invisible API" Rule
+# API and Public Contract Boundary
 
-> 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)
+## Documentation as Hard Rule (Boundary-Aware)
 
-```
-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).
+If a change affects an API, CLI command, exported library behavior, schema, event, or integration contract, update the matching docs in the same change.
 
-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.
-```
+## Contract Rules
 
----
+- Document the public surface before or alongside implementation.
+- Machine-readable API contracts should use the current project standard. If unresolved, the LLM must recommend a current maintained option from official docs.
+- HTTP APIs should prefer OpenAPI 3.1 when no stronger project standard exists.
+- Event APIs should define producer, consumer, payload, versioning, retry, and failure behavior.
+- CLI/library public behavior must update README, help text, changelog, or docs as appropriate.
+- Do not write "see code" as the contract.
+- Do not expose generic `object` or `any` contract shapes when the boundary can be typed.
+- Public error shapes must be safe, stable, and documented.
 
 ## Human Writing Standard (Mandatory)
 
@@ -31,6 +21,7 @@ This applies to documentation, release notes, onboarding text, review summaries,
 API docs and README updates are included in this scope.
 
 ### Style Baseline
+
 1. Write for native English speakers.
 2. Target an 8th-grade reading level.
 3. Use clear, direct, plain language.
@@ -39,6 +30,7 @@ API docs and README updates are included in this scope.
 6. State the main point first, then supporting detail.
 
 ### Required Behavior
+
 1. Explain decisions the way a competent coworker would explain them out loud.
 2. Cut unnecessary words and remove filler.
 3. Use concrete verbs and everyday phrasing.
@@ -46,206 +38,26 @@ API docs and README updates are included in this scope.
 5. Keep explanations short by default; expand only when complexity requires it.
 
 ### Scope Severity and Merge Behavior
+
 1. Scope style guidance controls readability and consistency.
 2. Style baseline findings are advisory by default and must not block endpoint-change commits that already include accurate docs/spec updates.
 3. Hard blockers remain contract failures: missing same-commit docs sync, incorrect schema, missing required responses, or factual inaccuracies.
 4. If style polish is still needed, open a follow-up task instead of delaying the contract update.
 
 ### Non-Negotiables
+
 1. No emoji in formal artifacts.
 2. Avoid AI cliches and buzzwords: delve, leverage, robust, utilize, seamless.
 3. Avoid inflated, academic, or performative language.
 4. Avoid padding, hedging, and redundant phrasing.
 
 ### Critical Controls
+
 1. Any claim about quality, performance, or reliability must include a measurable source and timestamp.
 2. Expand acronyms on first use, then use terms consistently.
 3. Separate facts from assumptions explicitly.
 4. End major explanations with a clear next action.
 
 ### Final Check
-Read the text out loud before shipping. If it sounds robotic, rewrite it.
 
----
-
-## 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.
-
-This sync rule has higher priority than style polish timing.
-Do not delay same-commit documentation sync only to iterate writing tone.
-
-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."
-```
-
-## Documentation as Hard Rule (Boundary-Aware)
-
-Documentation checks are hard-blocking for contract accuracy, but scope-aware to avoid unnecessary overhead.
-
-### Boundary Triggers
-1. Public surface boundary: exported/public behavior changes in CLI, library, or runtime scripts.
-2. API contract boundary: endpoint, route, controller, or OpenAPI contract changes.
-3. Database structure boundary: schema, migration, repository contract, or persistence model changes.
-
-### Boundary-Aware Enforcement
-1. Only triggered boundaries require synchronized documentation updates.
-2. Untouched boundaries are ignored during the same review run.
-3. Missing docs for a triggered boundary is a blocking failure.
-
-### Required Same-Scope Sync
-1. Public surface changes must update user-facing docs (`README.md`, `CHANGELOG.md`, or `docs/*`).
-2. API contract changes must update API/OpenAPI docs in the same scope.
-3. Database structure changes must update schema/migration documentation in the same scope.
-
-### 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.
+Read the text out loud before shipping. If it sounds robotic, rewrite it.