690603:2041 ADR-034-134 #01

2026-06-03 20:41:42 +07:00
parent 754d609399
commit 3274dede7a
197 changed files with 1575 additions and 42 deletions
@@ -0,0 +1,141 @@
+---
+trigger: always_on
+---
+
+# LCBP3 Agent Rules
+
+Critical rules and guidelines for AI agents working on LCBP3-DMS.
+
+## Version
+
+- **Current:** v1.9.6
+- **Last Updated:** 2026-05-22
+- **Synced with:** `AGENTS.md` (v1.9.6)
+
+## Purpose
+
+This directory contains rule files that define:
+
+- Project context and role expectations
+- Critical Tier 1 rules (CI blockers)
+- Coding standards and patterns
+- Domain terminology and glossary
+- Development workflows
+- Security requirements
+- AI integration architecture (ADR-023/023A)
+
+## Rule Enforcement Tiers
+
+### 🔴 Tier 1 — CRITICAL (CI BLOCKER)
+
+Build fails immediately if violated:
+
+- Security (Auth, RBAC, Validation)
+- UUID Strategy (ADR-019) — no `parseInt` / `Number` / `+` on UUID
+- Database correctness — verify schema before writing queries
+- File upload security (ClamAV + whitelist)
+- AI validation boundary (ADR-023)
+- Error handling strategy (ADR-007)
+- Forbidden patterns: `any`, `console.log`, UUID misuse, `id ?? ''` fallback
+
+### 🟡 Tier 2 — IMPORTANT (CODE REVIEW)
+
+Must fix before merge:
+
+- Architecture patterns (thin controller, business logic in service)
+- Test coverage (80%+ business logic, 70%+ backend overall)
+- Cache invalidation
+- Naming conventions
+- TypeScript Standards: Missing JSDoc, explicit types, or file headers
+
+### 🟢 Tier 3 — SPECIALIZED WORK
+
+Requires domain-specific knowledge:
+
+- **ADR-021 Integration:** Workflow Engine & Context implementation
+- **AI Infrastructure:** ADR-023/023A boundary enforcement and pipeline usage
+- **AI Runtime Layer:** ADR-024 Intent Classification, ADR-025 Tool Layer, ADR-026 Chat UI, ADR-027 Admin Console
+- **Migration Pipeline:** ADR-028 Staging Queue & post-migration cleanup
+- **Complex Business Logic:** Multi-step workflows with state management
+- **Performance Optimization:** Database queries, caching strategies, bulk operations
+
+### 🔵 Tier 4 — GUIDELINES
+
+Best practice — follow when possible:
+
+- Code style / formatting (Prettier handles)
+- Comment completeness
+- Minor optimizations
+
+## Rule Files
+
+### Core Rules (Tier 1 - CRITICAL)
+
+| File                    | Purpose                                                                         |
+| ----------------------- | ------------------------------------------------------------------------------- |
+| `00-project-context.md` | Project context, role & persona, tier classification, specs folder organization |
+| `01-adr-019-uuid.md`    | UUID handling strategy — no parseInt, use publicId only                         |
+| `02-security.md`        | Security requirements, checklist, ADR-023/023A AI boundaries                    |
+
+### Coding Standards
+
+| File                      | Purpose                                                 |
+| ------------------------- | ------------------------------------------------------- |
+| `03-typescript.md`        | TypeScript rules, file headers, i18n guidelines         |
+| `06-backend-patterns.md`  | NestJS patterns, UUID resolution, API response patterns |
+| `07-frontend-patterns.md` | Next.js patterns, RHF+Zod+TanStack Query, UUID handling |
+
+### Domain & Workflow
+
+| File                       | Purpose                                                       |
+| -------------------------- | ------------------------------------------------------------- |
+| `04-domain-terminology.md` | DMS glossary, key spec files priority table                   |
+| `08-development-flow.md`   | Development workflow by work type (Critical/Normal/Quick Fix) |
+
+### Compliance & Architecture
+
+| File                      | Purpose                                                        |
+| ------------------------- | -------------------------------------------------------------- |
+| `05-forbidden-actions.md` | Actions that must never be done, schema changes, UUID handling |
+| `09-commit-checklist.md`  | Pre-commit verification, commit message format                 |
+| `10-error-handling.md`    | ADR-007 error handling strategy, layered classification        |
+| `11-ai-integration.md`    | ADR-023/023A AI architecture, 2-model stack, BullMQ 2-queue    |
+
+## Key Spec Files Priority
+
+Spec priority: **`06-Decision-Records`** > **`05-Engineering-Guidelines`** > others
+
+| Document                       | Path                                                                        | Use When                          |
+| ------------------------------ | --------------------------------------------------------------------------- | --------------------------------- |
+| **Glossary**                   | `specs/00-overview/00-02-glossary.md`                                       | Verify domain terminology         |
+| **Schema Tables**              | `specs/03-Data-and-Storage/lcbp3-v1.9.0-schema-02-tables.sql`               | Before writing any query          |
+| **Data Dictionary**            | `specs/03-Data-and-Storage/03-01-data-dictionary.md`                        | Field meanings + business rules   |
+| **Edge Cases**                 | `specs/01-Requirements/01-06-edge-cases-and-rules.md`                       | Prevent bugs in flows             |
+| **ADR-019 UUID**               | `specs/06-Decision-Records/ADR-019-hybrid-identifier-strategy.md`           | UUID-related work                 |
+| **ADR-023 AI**                 | `specs/06-Decision-Records/ADR-023-unified-ai-architecture.md`              | AI integration work               |
+| **ADR-023A AI Model**          | `specs/06-Decision-Records/ADR-023A-unified-ai-architecture.md`             | 2-model stack, BullMQ 2-queue     |
+| **ADR-024 Intent Class.**      | `specs/06-Decision-Records/ADR-024-intent-classification-strategy.md`       | Pattern→LLM Fallback; Redis cache |
+| **ADR-025 AI Tool Layer**      | `specs/06-Decision-Records/ADR-025-ai-tool-layer-architecture.md`           | Tool Registry; CASL-guarded       |
+| **ADR-026 Chat UI**            | `specs/06-Decision-Records/ADR-026-document-chat-ui-pattern.md`             | Side-panel; streaming SSE         |
+| **ADR-027 AI Admin Console**   | `specs/06-Decision-Records/ADR-027-ai-admin-console-and-dynamic-control.md` | Dynamic control; admin-only       |
+| **ADR-028 Migration Refactor** | `specs/06-Decision-Records/ADR-028-migration-architecture-refactor.md`      | Staging Queue; cleanup            |
+| **Backend Guidelines**         | `specs/05-Engineering-Guidelines/05-02-backend-guidelines.md`               | NestJS patterns                   |
+| **Frontend Guidelines**        | `specs/05-Engineering-Guidelines/05-03-frontend-guidelines.md`              | Next.js patterns                  |
+| **Testing Strategy**           | `specs/05-Engineering-Guidelines/05-04-testing-strategy.md`                 | Coverage goals                    |
+
+## Maintenance
+
+When updating rules:
+
+1. **Check AGENTS.md version** — Ensure rule files are synced
+2. **Update version numbers** — Bump version in `00-project-context.md` only (03-typescript.md no longer has version)
+3. **Review ADR references** — Ensure all ADR references are current (ADR-023, ADR-023A, ADR-024~028)
+4. **Add new forbidden actions** — When new patterns are identified as violations
+5. **Update key spec files table** — When new ADRs or guidelines are added
+6. **Update Tier 3 SPECIALIZED WORK** — When new domain-specific workflows are added
+
+## Related Documents
+
+- `AGENTS.md` — Master agent configuration and context
+- `specs/06-Decision-Records/` — All Architecture Decision Records
+- `specs/05-Engineering-Guidelines/` — Backend, frontend, and testing guidelines