commit

AGENTS.md

@@ -34,6 +34,127 @@ Current migration status:
 
 ---
 
+## Governance Layer
+
+This repository now treats governance documentation as implementation input, not optional background reading.
+
+Before any task that changes behavior, architecture, permissions, reporting, exports, PDFs, approvals, or CRM workflow, agents must review the relevant standards and foundations first.
+
+Primary governance documents:
+
+- `AGENTS.md`
+- `docs/standards/task-contract-template.md`
+- `docs/standards/task-catalog.md`
+- `docs/standards/project-foundations.md`
+- `docs/standards/architecture-rules.md`
+- `docs/standards/ui-ux-rules.md`
+- `docs/standards/task-review-checklist.md`
+- `docs/adr/**`
+- `docs/business/**`
+- `docs/security/**`
+- `docs/implementation/**` for the related feature lineage
+
+### Task Execution Rules
+
+All tasks follow these rules:
+
+- review first; implementation without review is prohibited
+- reuse existing foundations before creating new modules, helpers, or flows
+- extend existing services before creating duplicate services
+- extend existing route groups before creating duplicate APIs
+- extend existing permission models before creating duplicate permission systems
+- extend existing export/report foundations before creating duplicate export flows
+- keep business logic in feature service layers, not in route handlers or client components
+- document any exception when an existing foundation cannot be reused
+
+Required review order for non-trivial work:
+
+1. `AGENTS.md`
+2. `docs/standards/**`
+3. relevant `docs/adr/**`
+4. relevant `docs/business/**`
+5. related completed tasks from `docs/standards/task-catalog.md` and `docs/implementation/**`
+6. existing foundations under `src/features/foundation/**`
+7. existing feature implementations under `src/features/**`
+8. existing APIs under `src/app/api/**`
+9. permission and access enforcement under `src/lib/auth/**`, `src/features/crm/security/**`, and `docs/security/**`
+10. existing audit patterns under `src/features/foundation/audit-log/**`
+
+### Historical Knowledge Rule
+
+Before implementing any feature:
+
+1. review related foundations
+2. review related ADRs
+3. review related completed tasks from `docs/standards/task-catalog.md`
+4. reuse before creating
+
+Implementation without historical review is prohibited.
+
+### Required Foundations
+
+The following reusable foundations are mandatory whenever the task touches their area:
+
+- Audit Foundation: `src/features/foundation/audit-log/**`
+- Approval Foundation: `src/features/foundation/approval/**`
+- Storage Foundation: `src/features/foundation/storage/**` and `src/features/foundation/document-artifact/**`
+- PDF Foundation: `src/features/foundation/pdf-generator/**` and `src/features/crm/quotations/document/**`
+- Report Foundation: `src/features/crm/reports/**`, `docs/adr/0017-report-foundation.md`
+- CRM Authorization Foundation: `src/lib/auth/crm-access.ts`, `src/features/crm/security/**`, `docs/security/**`
+- Customer Ownership Foundation: `docs/adr/0015-customer-ownership-contact-sharing.md`, `src/features/crm/customers/**`
+- Contact Sharing Foundation: `docs/adr/0015-customer-ownership-contact-sharing.md`, `src/app/api/crm/customers/[id]/contacts/[contactId]/shares/**`
+
+If a task touches CRM leads, enquiries, quotations, approvals, reports, exports, storage, or PDFs, agents must explicitly check whether one of these foundations already solves part of the problem.
+
+### Architecture Constraints
+
+Frontend constraints:
+
+- Next.js App Router only
+- server components first
+- `PageContainer` for dashboard page headers
+- shadcn/ui primitives and existing app UI wrappers
+- TanStack React Query with server prefetch + `HydrationBoundary` + client `useSuspenseQuery()` for data-heavy app pages
+- TanStack Form + Zod for forms
+- `nuqs` for URL state
+- existing CRM terminology helpers and Thai labels for business-facing CRM UI
+
+Backend constraints:
+
+- Route Handlers are the main HTTP boundary
+- feature service layer owns business logic
+- Drizzle ORM owns database access
+- auth and organization access go through `@/auth` and `src/lib/auth/session.ts`
+- CRM scope resolution goes through resolved-access helpers, not direct role-string branching
+- audit logging goes through `src/features/foundation/audit-log/service.ts`
+
+Forbidden patterns:
+
+- Redux for new application state
+- SWR for new server-state fetching
+- React Hook Form for new forms in this repo
+- direct database access from client components
+- business logic inside route handlers
+- new Clerk usage
+- direct role-string authorization such as `if (role === 'sales')`
+- report-specific export systems that bypass `src/features/crm/reports/server/exports/service.ts`
+
+### Mandatory Task Review
+
+Before implementation, every non-trivial task must review:
+
+- reusable foundations
+- relevant ADRs
+- related completed tasks from `docs/standards/task-catalog.md`
+- related existing APIs
+- permission and scope enforcement
+- audit events and existing entity/action naming
+- duplication risk across services, routes, exports, datasets, and UI shells
+
+Implementation without this review is prohibited.
+
+---
+
 ## Technology Stack Details
 
 ### Core Runtime
@@ -516,3 +637,17 @@ Ensure these are set:
 17. When deleting entities, remove stale detail queries with `removeQueries` in addition to invalidating lists.
 18. If a component overrides `useMutation` callbacks on top of a shared mutation config, preserve or explicitly call the shared invalidation behavior before closing UI.
 19. After successful create/update/delete, sheets, dialogs, and destructive modals must close only after cache invalidation has been triggered and the UI can refresh from fresh data.
+20. Review `docs/standards/**`, relevant `docs/adr/**`, `docs/business/**`, and `docs/security/**` before implementing non-trivial changes.
+21. Review related completed task notes in `docs/standards/task-catalog.md` and `docs/implementation/**` before implementing non-trivial changes.
+22. Reuse foundations under `src/features/foundation/**` and `src/features/crm/**` before introducing new services, routes, permissions, exports, or datasets.
+23. Do not create duplicate report/export/PDF/approval/security plumbing when a project foundation already exists.
+24. CRM authorization must flow through resolved access helpers such as `resolveCrmMembershipAccess()`, `buildCrmSecurityContext()`, or report-context builders; do not authorize with raw role strings alone.
+
+Before implementing any task, review:
+- AGENTS.md
+- docs/standards/*
+- docs/standards/task-catalog.md
+- related ADRs
+- related completed task documents
+
+Implementation without review is prohibited.